Hermes CLI 常见故障排查指南

启动时终端UI崩溃问题（macOS）

报错信息： OSError: [Errno 22] Invalid argument 或 KeyError: '0 is not registered'

问题根源： 此问题源于初始化向导与后续聊天界面的交互冲突。初始化过程中使用的 curses 交互式菜单在退出后，会干扰 macOS 底层事件循环机制（kqueue selector）对标准输入（stdin，文件描述符 0）的状态管理。这导致后续 prompt_toolkit 库在启动文本用户界面时，无法正常重新注册和使用标准输入流。

解决方案： 此问题已在程序内部得到修复。具体措施是在主应用启动前（位于 cli.py 的 app.run() 部分），临时将 asyncio 的事件循环选择器策略切换为 SelectSelector（此操作仅对 macOS 系统生效）。应用运行结束后，策略会自动恢复为系统默认。用户无需进行任何手动配置或操作即可规避此崩溃。

API身份验证失败问题（HTTP 401）

报错信息： AuthenticationError [HTTP 401] — 无效的令牌

问题根源： 配置文件中 model.provider 被设置为 custom，这是一个通用的提供者名称。在此配置下，Hermes 默认会尝试读取 OPENAI_API_KEY 环境变量作为认证密钥。然而，实际配置的 base_url 却指向了第三方 API 端点（例如 Airsim），其所需的 API 密钥与 OPENAI_API_KEY 并不相同，从而引发了认证失败。

解决方案： 将 provider 字段的值修改为与 custom_providers 列表中对应的自定义名称（例如 airsim）。修改后，Hermes 会自动尝试读取与之匹配的环境变量（如 AIRSIM_API_KEY）进行认证。

model:
  provider: airsim  # 此处应使用自定义名称，而非 generic 的 ‘custom’
  base_url: https://api.airsim.eu.cc/v1

未知提供者（Unknown provider）报错

报错信息： Unknown provider ‘xxx‘. Check ’hermes model‘ for available providers

问题根源： 在使用 hermes model 命令进行交互式配置或直接在配置文件中，指定了一个不存在的提供者名称。该名称既非 Hermes 内置的提供者，也未在 custom_providers 配置块中进行声明。

提供者配置规则梳理：

所有自定义命名的提供者，都必须在 config.yaml 文件的 custom_providers 部分预先进行声明。

custom_providers:
  - name: airsim  # 此处声明的名称，即为上方应使用的 provider 值
    base_url: https://api.airsim.eu.cc/v1
    api_key: ''  # 若此处为空字符串，程序将自动读取 `AIRSIM_API_KEY` 环境变量
    api_mode: chat_completions

解决方案： 直接编辑 ~/.hermes/config.yaml 配置文件，确保 model 部分下的 provider 字段值，与 custom_providers 列表里某一项的 name 完全一致。

cc-switch 工具不支持 Hermes 的原因说明

请注意，第三方命令行工具 cc-switch 目前支持管理的应用列表包括：Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等，其中并不包含 Hermes。

Hermes 拥有独立的配置体系和管理方式。其所有 API 密钥均需在专属的配置文件 ~/.hermes/.env 中进行设置，因此无法通过 cc-switch 工具进行统一切换或管理。

核心配置文件路径说明

了解配置文件的存放位置对于手动排查问题至关重要。