Hermes CLI 升级、切换模型与配置文件修改指南

Hermes CLI 用一段时间后，升级版本、切换模型、改配置文件是三件最常做的事。这篇把三件事的操作步骤和配置示例集中放到一起，方便随时查。

升级 Hermes CLI

升级走 hermes update 这一条主命令，先看版本，再决定要不要升。

# 看当前版本
hermes version

# 只检查有没有更新，不动文件
hermes update --check

# 正式升级，建议带备份
hermes update --backup

# 升级后检查环境
hermes doctor

hermes update 会拉取最新代码、重装依赖，并处理新增的配置项。--check 只检查是否落后，不执行安装；--backup 会在升级前给 HERMES_HOME 做一份快照。

如果升级后提示配置缺失，用这两个命令补齐：

hermes config check
hermes config migrate

升级时如果跳过了新的配置项，config migrate 会帮你把它们加回来。

安装方式自动识别

Hermes 会自动识别 pip、git installer、Homebrew、NixOS 等安装方式，hermes update 按对应方式处理，hermes doctor 也会显示检测到的安装方式。

如果本机提示 hermes: command not found，先查路径：

which hermes
echo $PATH
source ~/.zshrc

别和 IBC Relayer 的 Hermes 搞混

如果你说的是 IBC Relayer 那个 Hermes，不是 AI Agent 这个，升级命令是另一套：

cargo install ibc-relayer-cli --bin hermes --locked
hermes version

这个 Hermes 是 Rust crate ibc-relayer-cli 里的 hermes 二进制，和本文讲的 NousResearch Hermes Agent 不是同一个东西。

切换模型和 Provider

切换分两种：临时切当前会话，和写进全局配置。

用向导切换

在终端里运行：

hermes model

这是完整的模型和 Provider 配置向导，可以添加新的 provider、走 OAuth、填 API Key、选择模型。需要在 Hermes 会话外运行。

会话内临时切换

先进会话：

hermes

然后在对话里输入：

这只切换当前 session，退出就恢复。

切换并保存为默认

加 --global 会把选择写入 config.yaml，之后默认就用这个模型，同时原地切换当前会话。

直接编辑配置文件

Hermes 的配置目录是 ~/.hermes/，其中 config.yaml 放模型、终端、压缩等设置，.env 放 API Key。密钥和普通配置分开存放：API Key 写 .env，模型和 provider 写 config.yaml。

打开配置：

hermes config edit
# 或直接编辑
code ~/.hermes/config.yaml

OpenRouter

~/.hermes/.env：

~/.hermes/config.yaml：

model:
  provider: openrouter
  default: anthropic/claude-sonnet-latest
  base_url: ''
  api_mode: chat_completions

OpenRouter 模型 ID 通常是 <author>/<slug>，也支持 anthropic/claude-sonnet-latest 这种写法。

也可以用命令行直接设：

hermes config set OPENROUTER_API_KEY sk-or-xxxx
hermes chat --provider openrouter --model anthropic/claude-sonnet-latest

DeepSeek

~/.hermes/.env：

~/.hermes/config.yaml：

model:
  provider: deepseek
  default: deepseek-chat
  base_url: ''
  api_mode: chat_completions

Kimi / Moonshot

~/.hermes/.env：

~/.hermes/config.yaml：

model:
  provider: kimi-coding
  default: 你的模型ID
  base_url: ''
  api_mode: chat_completions

Hermes 的 provider 列表里，Kimi/Moonshot 对应 kimi-coding，DeepSeek 对应 deepseek，OpenRouter 对应 openrouter。

自定义 OpenAI 兼容接口

接第三方中转、LiteLLM、vLLM 或本地服务时，用 custom_providers 定义自己的 endpoint。

~/.hermes/.env：

~/.hermes/config.yaml：

custom_providers:
  - name: myapi
    base_url: https://你的接口地址/v1
    key_env: MY_API_KEY
    api_mode: chat_completions

model:
  provider: custom:myapi
  default: 你的模型ID

本地无密钥服务可以不写 key_env：

custom_providers:
  - name: local
    base_url: http://localhost:11434/v1
    api_mode: chat_completions

model:
  provider: custom:local
  default: qwen3.5:27b

定义好 custom_providers 里的 name、base_url、key_env、api_mode 后，主模型用 provider: custom:<name> 指向它。

两个容易踩的坑

如果 config.yaml 里还是这样：

model: ""

要改成上面的对象格式。新安装时可能是 model: ""，配置过模型后会升级成 provider/default/base_url/api_mode 这种结构。

另外，在 model: 段里，default: 和 model: 两个键都能表示模型 ID，建议统一用 default:，少踩坑。

改完后检查

hermes config check
hermes doctor

小结

日常用得最多的是这几条：升级走 hermes update --backup，切模型用 hermes model 向导或在会话里 /model ... --global，接自定义接口就编辑 config.yaml 加 custom_providers。改完别忘了 hermes doctor 跑一遍。