上周你在飞机上用一个本地跑的 Qwen 写完整个模块，全程没联网，体验很好。这周一你打开 Webapp 想接着干，屏幕上却是那句熟悉的欢迎词：“Let’s get you setup…”，下面两个按钮：Nous Portal、I have an API key。

你第一反应是“账号掉登录了”，于是重新登录、重新贴 key，弄了十分钟。真相是：你的账号一点问题都没有，只是那个本地模型服务器没在跑（桌面端退出时把它停掉了，或者它还在加载模型）。旧版的界面把“模型解析失败”和“什么都没配置”当成了同一件事，于是把你送去登录。

这个问题现在修好了，而且修的方式值得一看——它不是改了句文案，而是把“哪种失败”这件事变成了一个结构化的字段。

一个错误被当成了另一个错误

先看旧版是怎么走进死胡同的。

当主模型是 Hermes 托管的本地运行时（llama.cpp），而那个服务器没在跑时，网关的 setup.runtime_check 会返回 ok: false；同时 setup.status 明明说“已经配置了 provider”。两句都对，但渲染层的引导门禁（refreshOnboarding）只看了前一句：它把所有 ok: false 都理解为“没配置任何东西”，于是弹出 provider 登录层。

更糟的是第二步。如果你不管三七二十一直接发一条消息，网关会把这次“解析不到运行时”标成 auth_permanent（认证永久失败），前端于是给你一张“Update API key”的卡片。于是一个纯粹的“服务器没起”问题，被包装成了“你的密钥有问题”。

这里要澄清一个常见误解：Webapp 的登录态全程是好的，browser-transport.ts 的重新认证逻辑根本没被触发。你看到的那一层，是 provider 引导浮层，只不过它里面写着“本地模型不可用”这句话，看着像登录界面而已。

新的错误码：local_runtime_unavailable

修复的核心是把两种失败分开：

• 本地运行时不可用时，抛的是一个新的具名异常 LocalRuntimeUnavailableError（ValueError 的子类，所以老调用方的 except 仍然能接住），它带一个结构化的错误码 local_runtime_unavailable。
• 其中“服务器开着但还没开始服务”这一种，被标成 可重试（retryable）。这个区分很关键：模型在加载时要等一会儿，这时候让你去换个模型是错的建议。
• setup.runtime_check 通过一个统一的辅助函数把 error_code 放进返回值。注意是结构化字段，不是让前端去匹配错误字符串——文案会变，字段不会。

两个状态对应的原话也不一样了：

• 还在启动：“The local model server isn’t running. It may still be starting — try again in a moment, or switch to another model with /model.”
• 明确关掉了：“The local model server is turned off. Start it from the Hermes desktop app or hermes model → Local models, or switch to another model with /model.”

桌面端和 Webapp：两种不同的下一步

这里有个细节特别值得夸：修复没有偷懒地给两边同一句提示。

你用的界面	看到什么	能做什么
桌面端	应用正常打开（configured: true），显示“Local model unavailable”提示	Open Local models，直接跳到设置里那个面板
Webapp	应用正常打开，提示里说明本地模型不可用	Choose another model（Webapp 没有 Local models 面板——那个面板是 Electron 独有的）

为什么 Webapp 不给“打开本地模型面板”？因为那个面板在浏览器里根本不存在，给你一个点不动的按钮比不给更糟。所以 Webapp 的文案里特意不提那个面板，只提“换个模型”。

对话里那张错误卡片也改了

一次因此失败的回合，现在会带着 failure_reason=local_runtime_unavailable 传到界面上，卡片标题从“你的 API key 被拒绝”变成 “Can’t reach your model server”，下面给两个动作：

• Retry：如果服务器还在启动，先重试是对的；
• Switch provider：如果它就是没开，换一个模型更快。

同时删掉了一句只有工程师看得懂的后缀——旧版会在错误下面补一句“setup.status 说有凭据，但运行时解析仍然失败”，这是明显的内部术语，新版在没有错误码时才保留类似说明。

还是要去登录的情况

修复没有把所有失败都归到“本地模型”上，这一点很重要，否则会掩盖真正的凭据问题。以下情况仍然会走登录引导：

• 根本没有可用凭据（比如 Nous 没登录、key 没配）；
• 配的是云 provider，而它的 key 真的失效了。

换句话说：只有当失败能被明确归因到“本地运行时”时，才不把你送去登录。

你自己怎么排查

如果你的本地模型突然用不了，按这个顺序走：

1. 看服务器在不在。 桌面端：设置 → Providers → Local Models，看那个模型是不是显示为运行中；如果是“已安装但停止”，点启动。命令行：hermes model → Local models，会列出目录、启动服务器并把它设为默认。
2. 区分“没启动”和“还在加载”。 刚点完启动的前十几秒，模型在往显存里装，这时候重试是对的动作；等一分钟还没好，就看日志。
3. 临时换一个模型继续干活。 会话里 /model 可以直接切到已配置的其他 provider；注意切模型会让这一轮的 prompt 缓存失效，长会话里代价不小。
4. 确认不是“面板不存在”的错觉。 如果你在 Webapp 里找不到 Local models 设置，那是对的——它只在桌面端有。Webapp 侧的正确动作是换模型，或者回到桌面端把服务器起来。

现在能用吗

这个修复在 2026-10-30 合入 main（PR #146883，标签 type/bug、P2），并已随 v0.22.6（2026-11-02 发布） 进入正式发行版——升上去之后，本地服务器没起来会报成不可用，而不是把你当成没配置、送去登录界面。

在那个版本上，遇到“突然要你登录”的时候，先别急着重新登录：去看一眼本地模型服务器在不在跑。这个判断能省你十分钟，也能避免你在一台离线机器上反复尝试登录一个根本连不上的账号。

本地模型这条线上我们之前写过两篇，可以配合看：本地模型是怎么被托管起来的（llama.cpp 三步入坑指南），以及怎么判断你的显卡到底能跑多大的模型。这一篇补的是第三块：出问题的时候，界面到底在跟你说什么。