Hermes Agent 配置

Hermes Agent 是 NousResearch 推出的 Agent CLI。接入 Modelink 时，将 Modelink 配置为 Custom endpoint（OpenAI 兼容），并设置 Base URL、API Key 和默认模型。

📖 官方文档参考：Configuration · AI Providers

方式一：自动配置（推荐）

Hermes Agent 已在 qiniu-coding-helper 的支持范围内，推荐使用自动配置：

npx qiniu-coding-helper enter hermes

或重新写入 Hermes Agent 配置：

npx qiniu-coding-helper auth reload hermes

配置完成后，完整重启 Hermes Agent。

方式二：交互式配置

Hermes Agent 提供交互式模型配置向导，可自动写入配置文件：

hermes model

在向导中选择 Custom endpoint (self-hosted / VLLM / etc.)，然后依次输入：

完成后 Hermes Agent 会自动将配置写入 ~/.hermes/config.yaml 和 ~/.hermes/.env。

方式三：手动配置

配置文件位置

Hermes Agent 的配置目录为 ~/.hermes/，核心文件：

⚠️ 配置优先级：CLI 参数 > config.yaml > .env > 内置默认值。API Key 等敏感信息应放入 .env，其余配置放入 config.yaml。

编辑 config.yaml

打开 ~/.hermes/config.yaml，添加或修改 model 段：

model:
  provider: custom
  base_url: https://api.qnaigc.com/v1
  default: deepseek-chat
  api_key: ${MODELINK_API_KEY}

然后在 ~/.hermes/.env 中写入 API Key：

MODELINK_API_KEY=sk-your-modelink-api-key

💡 config.yaml 支持 ${VAR_NAME} 环境变量替换语法。将 API Key 存放在 .env 中，通过 ${MODELINK_API_KEY} 引用，避免密钥明文写入 YAML。

使用 hermes config set

也可以通过 CLI 命令逐项设置（hermes config set 会自动将 API Key 路由到 .env，其余写入 config.yaml）：

hermes config set model.provider custom
hermes config set model.base_url https://api.qnaigc.com/v1
hermes config set model.default deepseek-chat
hermes config set model.api_key sk-your-modelink-api-key

配置多个接入点

如果需要同时配置中国大陆和海外两个接入点，可使用 命名自定义 provider。在 config.yaml 中添加 custom_providers 列表：

model:
  provider: custom
  base_url: https://api.qnaigc.com/v1
  default: deepseek-chat
  api_key: ${MODELINK_API_KEY}

custom_providers:
  - name: modelink-cn
    base_url: https://api.qnaigc.com/v1
    key_env: MODELINK_API_KEY
    api_mode: chat_completions
  - name: modelink-global
    base_url: https://api.modelink.ai/v1
    key_env: MODELINK_API_KEY
    api_mode: chat_completions

会话中可通过 /model 命令切换：

/model custom:deepseek-chat              # 使用默认 custom provider
/model custom:modelink-cn:deepseek-chat  # 使用中国大陆接入点
/model custom:modelink-global:deepseek-chat  # 使用海外接入点

接入点选择

验证配置

诊断检查

hermes doctor

hermes doctor 会检查配置文件完整性、API 连通性和模型可用性。

手动验证

1. 重启 Hermes Agent。
2. 查看当前 provider / model 状态，确认已切换到 Modelink。
3. 执行低风险任务，例如解释当前目录结构或生成一段测试代码。
4. 如果支持工具调用，再验证工具调用链路是否正常。

排障建议

参考

• Hermes Agent Configuration
• Hermes Agent AI Providers