Hermes Ollama 模型未显示：目录与提供商检查

如果你的 Ollama 模型从 Hermes 选择器中消失，请先检查版本，再修改配置：恰好会产生这一症状的原生目录缓存 bug 已于 2026 年 9 月 17 日关闭为已完成，修复包含在标签 v2026.9.21（hermes-agent 0.21.4）中，但不在 v2026.9.14 中。不过，该已关闭报告并不是全部情况。截至 2026 年 9 月 21 日，仍有另外两份关于 Ollama 模型从选择器中消失的报告处于开放状态；还有第三个开放问题描述了 Hermes Desktop 的一种机制：任何曾自定义过可见模型列表的提供商都会出现相同症状，而我在同一标签的已发布源码中仍读到了该行为。第四个常见原因根本不是缺陷。每种情况都会留下不同的特征，而本页面的用途就是解释这些特征。

先澄清两个概念，因为它们都会在搜索结果中混在一起。Hermes Agent 是 Nous Research 的 Python 智能体（MIT 许可，未归档；根据 GitHub API，最近一次推送为 2026 年 9 月 21 日）。Hermes 3 和 Hermes 4 是同一实验室的开放权重 LLM 系列，是完全不同的产品；此外还有一个无关的 JavaScript 引擎也叫 Hermes——它们的版本号都不适用于这里。还有，本地 Ollama 不等于 Ollama Cloud：Hermes 通过 Custom Endpoint 流程访问 11434 端口上的免费本地运行时，而 Ollama Cloud 是独立的付费产品，使用自身的提供商 slug 和缓存文件。一个产品中缺失的模型不能说明另一个产品的情况。

三层必须彼此一致，而其中只有一层属于 Ollama

“模型不在选择器中”描述的是三层中的最后一层，诊断的关键是找出第一层出现不一致的位置。

# 1. Does Ollama itself list the model? This is the native catalog
#    Hermes reads when the endpoint qualifies for the /api/tags branch.
curl -s http://127.0.0.1:11434/api/tags | jq '.models[].name'

# 2. Does the OpenAI-compatible surface list it too? This is what a
#    generic custom endpoint is probed on.
curl -s http://127.0.0.1:11434/v1/models | jq '.data[].id'

第一层需要排除的一点是：ollama list 包含嵌入模型，而嵌入模型不是编码智能体可以选择的聊天模型。Kunavo 同样不提供嵌入、文本转语音或语音转文本模型，因此托管路由无法在这里弥补这一缺口。

先检查版本，并仔细阅读版本信息

Issue #112898——“本地 Ollama 模型列表在选择器中闪烁”——已关闭为已完成，于 2026 年 9 月 16 日创建，并于 2026 年 9 月 17 日关闭。Pull request #113129 将修复合并为提交 d6d6565，GitHub compare 显示该提交位于标签 v2026.9.21 内而不在 v2026.9.14 内：比较 v2026.9.21…d6d6565 返回状态 behind，领先提交数为零，因此该提交是该标签的祖先；而比较 v2026.9.14…d6d6565 返回状态 ahead，落后提交数为零，因此该标签是该提交的祖先，而不是反过来。贡献者自己的 #112900 仍处于开放状态，但这并不表示修复缺失于 main：其内容已在保留作者署名的情况下被 cherry-pick 到已合并的 pull request 中。所有状态均读取自 2026 年 9 月 21 日的 GitHub API。

现在说说陷阱。同一个标签中包含两个不同的版本号：在 v2026.9.21 中，pyproject.toml 读取的是 version = "0.21.4"，而 apps/desktop/package.json 读取的是 "version": "0.17.6"。因此，标题为 "Hermes Desktop 0.17.6" 的错误报告描述的是一个当前构建，而不是旧构建——将此类报告视为过时报告，会导致你自己的证据日期判断错误。还要注意版本检查的局限性：这里验证的是标签中的 git 包含关系。你实际安装的 pip 发行版、Homebrew formula、容器镜像或桌面自动更新渠道是否包含该提交，此处并未验证。

五种原因，以及区分它们的迹象

其中两个原因值得单独说明。桌面端冻结最容易被误认为是缓存问题：在标签 v2026.9.21 中读取 apps/desktop/src/store/model-visibility.ts 时，只要某个提供商存有任何密钥，渲染器就会完全跳过提供商默认值的合并，因此之后发现的模型永远不会进入菜单。问题 #114369 在一个自定义提供商上准确复现了这一点，该提供商使用 discover_models: true；该问题随后作为重复问题关闭，而不是作为已修复问题关闭。其复现使用的是 vLLM 端点，因此应将此机制视为与提供商无关，而不是 Ollama 专属复现。另外还有两个问题仍处于开放且未解决状态：#89874（自定义 Ollama 提供商的模型数量为零，带有 needs-repro 标签，因此是未经确认的报告，而不是已确立的缺陷）以及 #71169（模型存在于 Ollama API 中，却不在桌面下拉菜单中）。两者是否与 #112898 具有共同根因，尚未确定。

桌面端症状也比人们预期的更加明显。在该标签中的 model-catalog-menu.tsx 里，折叠后的模型系列列表为空的提供商会被直接跳过——这就是为什么人们通常抱怨的是“我的提供商消失了”，而不是“我的提供商显示了一个空列表”。

为什么普通打开选择器时会显示过时列表

这是整个故障类别背后的机制，值得一次弄清楚。普通打开选择器时，只有当前自定义端点会进行实时探测；其他每个已配置端点都从磁盘缓存 $HERMES_HOME/provider_models_cache.json 中读取结果。HERMES_HOME 默认值为 ~/.hermes，但可以覆盖，因此不要假定路径固定不变。标签 v2026.9.21 中的 hermes_cli 有三个时间窗口控制重新探测：

这些是内部源代码常量，而不是有文档说明的设置；此次检查没有发现面向用户的选项可以调整这三个值。该代码中有一个值得了解的有意例外：空的原生目录只有在较短 TTL 内才被视为权威数据，并且永远不会按过时数据提供，正是为了避免 Ollama 在首次打开时没有模型，导致新拉取的模型在整整七天内都无法显示。缓存行的键由规范化 URL 加上凭据、API 模式和额外请求头的指纹组成，因为多个提供商行可以合理地共享一个代理 URL，同时使用不同的密钥。实际影响是：轮换密钥、更改传输方式或编辑 extra_headers 都会使该缓存条目失效；下一次不进行探测的打开操作会将其显示为空，直到某个操作刷新它。

检查顺序

1. 确认 Ollama 中存在该模型。 运行上面的两条 curl 命令。如果 /api/tags 没有列出该模型，后续任何环节都不可能列出它。
2. 确认版本。 如果你的构建早于标签 v2026.9.21，且症状是列表在正确和空之间闪烁，那么你遇到的是一个已经修复的错误——先升级，再进行调试。
3. 强制刷新。 --refresh 中的 hermes model 标志在其帮助文本中明确说明，它会清除选择器磁盘缓存，并重新获取每个提供商的实时列表；注意，它会清除所有提供商的缓存，而不是某一个提供商的缓存。在会话中，斜杠命令参考文档说明 /model --refresh 会重新获取提供商的模型列表；桌面端也有明确的“刷新模型”控件，会请求新的目录，而普通打开操作仍使用一小时缓存。
4. 检查你的端点使用哪条探测路径。 当提供商名称为 ollama、名称为 custom:ollama 或以 -ollama 结尾、URL 与配置的 Ollama 基础 URL 匹配，或无法明确判定的自定义 URL 使用端口 11434 且确实响应 /api/tags 时，会进入原生 /api/tags 分支。在其他端口上运行且名称仅为 custom 的 Ollama 则会转而使用通用的 /v1/models 探测——从代码路径来看，逻辑就是如此；这里并未实际运行以确认这一回退机制能否正常工作。
5. 如果问题出在发现本身，就停止发现。 discover_models 默认值为 true；将其设为 false 后，选择器会显示你配置的列表，而不是进行实时探测。
6. 如果只有桌面菜单不正确，你很可能遇到的是 #107391 类问题，刷新无法解决它——后端会返回该模型，但渲染器的筛选层会将其丢弃。

providers:
  # The published reference documents `api` for a providers entry.
  local-ollama:
    api: http://127.0.0.1:11434/v1
    # No key for local Ollama. Discovery is on by default; turn it off and
    # hand-write the list when the probe is the thing that is failing.
    discover_models: false
    models:
      - qwen3-coder:30b

model:
  default: qwen3-coder:30b
  provider: custom:local-ollama

有一个配置细节反复让人困惑，值得在这里明确说明。参考文档将 api 记录为 providers: 条目的基础 URL 键，并在该条目的字段列表中将 base_url 和 url 列为它的可接受别名；base_url 则是顶层 model: 映射下单独使用的键。文档还记录，旧配置使用顶层 custom_providers: 列表，其中使用 的 base_url 而不是 api；该写法仍然有效，并会在配置版本 v12 上通过 hermes update 自动迁移。跟踪器中的错误报告两种写法都有，这正符合两个字段都会被读取的情况。因此，一个没有生效的 providers: 条目不太可能是因为键名错误——应检查端点和该条目的其他字段。

还有一个需要单独说明的细节：Ollama 自己的 Hermes 页面将设置提示写作“Context length in tokens [leave blank for auto-detect]”，而Hermes 的提供商文档要求代理使用至少 64,000 tokens，并说明提供更小窗口的本地端点会在启动时被拒绝。两处内容均于 2026 年 9 月 21 日检查。将字段留空本身没有问题，但这无法解决服务器只提供较小窗口的问题——因此应在服务器上增大窗口（或在 Hermes 配置中固定该值）至 Hermes 要求的数值，并记住，这种失败会在启动时拒绝并指出所提供的窗口大小，而不是导致选择器中的条目缺失。

验证后，再决定本地运行是否值得

更改后按顺序执行三件事：在不使用 --refresh 的情况下重新打开选择器，并确认模型在一次冷打开中列出；选择该模型；发送一个有界请求并返回一次完成结果。中间这一步很重要，因为只有在探测后立即正确的列表，正是缓存错误的特征，而不是修复的证明。这些是供你执行的说明——编写本页时并未实际运行 Hermes、Ollama 实例或选择器。

如果结论是本地运行对这项任务来说不值得折腾，那么费用问题可以清楚地分成两部分：软件费用，以及模型使用费用。

Ollama Cloud 的 Pro 层还列出了每年支付 $200 的年度计费方案，其套餐包含每月使用额度——Pro 为 $60，Max 为 $300，Team 共享 $1,000。这些属于云产品，而不是你正在修复的本地端点。

对于按量计费的路径，下面是说明性 token 算术，不是实测任务成本，也不是账单上限。假设一个会话发送 200,000 个未缓存输入 token，接收 12,000 个输出 token，没有缓存读取，也没有外部工具费用。费率采用实时的Kunavo 目录价格，按每百万 token 计。

在将其视为预算之前，请根据你每天实际运行的会话数进行缩放，并注意，列出的最低费率与完成任务的最低成本是不同的说法——一个需要尝试三次的低价模型，成本可能高于只需一次尝试的模型。Kunavo 目录金额是计费底价，而不是上限：上游报告费用后，账单金额取目录成本与上游成本乘以适用加价两者中的较高值。请参阅计费详情。

选择哪条路径取决于工作内容。本地 Ollama适合小型、私密或离线任务，不收取按请求计费；真正的限制是硬件和 64,000-token 最低要求。直接供应商 API适合你长期使用某个供应商的旗舰模型，并希望使用其专属缓存和批处理条款。需要按任务切换模型，并希望使用一个密钥和一个余额时，网关更合适。如果固定费率的高强度日常使用比按 token 计费更适合你，订阅则更合适。

将 Hermes 指向其他位置

如果你决定在本地端点旁边添加一个托管端点，机制与相同的自定义提供商流程一致——但在尝试之前，有一个边界值得了解：添加提供商需要在 hermes model 中执行，且发生在会话之外，因为会话中的 /model 只能在已配置的提供商之间切换，不能添加提供商或接受密钥。Hermes Agent 自定义 API详细介绍了条目格式、传输方式和回滚；Hermes Agent 定价介绍了四项独立费用。Kunavo 发布的是配置参考，而不是兼容性测试：本次工作从未对 Hermes 与 Kunavo 端点进行运行时测试，因此此处任何内容都不能证明 Hermes 能够成功对其执行发现。尝试时请保留当前可用的路径。Ollama 的 OpenAI 兼容 API解释了为什么相同的客户端代码可以访问两者；如果你希望为密钥充值，请创建 Kunavo 账户。

还在选择客户端，而不是调试现有客户端？Hermes Agent 替代方案和OpenAI 兼容 API介绍了更广泛的选择。

常见问题

2026 年 9 月 21 日检查的内容及方式如下：问题和拉取请求状态、两个修复的标签包含关系、最新发布标签，以及仓库的许可证和归档状态，均来自 GitHub API；缓存常量、发现条件、桌面端可见性存储、--refresh 帮助字符串和文档引文，均从标签 v2026.9.21 的源代码中读取；Ollama 定价页面、Ollama 自己的 Hermes 集成页面和 Nous Portal 套餐列表也在同一天获取。未检查的内容：你安装的 pip、Homebrew、容器或桌面自动更新产物是否包含任一修复。此处没有任何内容经过运行时测试——没有运行任何已安装的 Hermes 实例、没有启动 Ollama，也没有打开选择器。Kunavo token 费率来自实时目录，美元示例是说明性的 token 用量计算，而不是实测任务成本。