Hermes Agent 接入 ClaudeAPI.com 完整教程（2026最新）

Hermes Agent 支持自定义 API 接入点，配合 ClaudeAPI.com 国内直连，无需代理即可在国内稳定使用 Claude 全系模型。

什么是 Hermes Agent？

Hermes Agent 是 NousResearch 推出的开源 AI 智能体框架，定位类似 Claude Code，但支持更广泛的 LLM 提供商和更多消息平台接入（Telegram、Discord 等）。它内置 47+ 工具，支持持久化记忆、多模型路由和自定义接入点，适合对 Agent 工作流有深度定制需求的开发者。

对国内用户而言，Hermes 的优势之一是：支持将任意 OpenAI / Anthropic 兼容的接入点配置为推理后端，只需填写 base_url 和 API Key，即可对接 ClaudeAPI.com 国内直连节点。

前置条件

Hermes 暂不支持原生 Windows 环境，Windows 用户请参阅 WSL2 安装指南。

步骤 1：查看已安装的 WSL

wsl --list --verbose

wsl --list --verbose

步骤 2：进入 WSL（Linux 环境）

wsl

wsl

步骤 3：在 WSL 内执行安装命令（此时才是真正的 Linux bash 环境）

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

🔧 如果 WSL 进不去或有问题

重新设置默认用户并启动：

wsl --set-default Ubuntu
wsl

wsl --set-default Ubuntu
wsl

如果想重装 WSL（清除原有数据）：

wsl --unregister Ubuntu
wsl --install -d Ubuntu

wsl --unregister Ubuntu
wsl --install -d Ubuntu

⚠️ 注意事项

1. 不要在 PowerShell 中直接运行 .sh 脚本，.sh 是 Linux shell 脚本，必须在 WSL / Linux 环境运行。
2. 进入 WSL 后，提示符会变成类似 用户名@主机:~$ 的样式，此时才能用真正的 curl 和 bash。
3. 运行安装脚本前，建议先看看脚本内容：

   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | less
   

   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | less
   

Step 1：安装 Hermes Agent

一条命令完成安装，脚本自动处理 Python、Node.js、ripgrep 等所有依赖：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后重载 Shell：

source ~/.bashrc   # zsh 用户改为 source ~/.zshrc

source ~/.bashrc   # zsh 用户改为 source ~/.zshrc

验证安装成功：

hermes --version

hermes --version

Step 2：配置 ClaudeAPI.com 接入点

方式一：hermes model 交互式配置（推荐新手）

hermes setup

hermes setup

在菜单中选择 「Custom endpoint (self-hosted / VLLM / etc.)」，按提示依次填写：

填写完成后 Hermes 自动保存到 ~/.hermes/config.yaml，立即生效。

还没有 ClaudeAPI.com API Key？访问 claudeapi.com 注册，支持支付宝 / 微信充值，无需境外信用卡。

方式二：直接编辑 config.yaml（推荐有经验的用户）

打开配置文件：

nano ~/.hermes/config.yaml

nano ~/.hermes/config.yaml

找到 model: 部分，修改为：

model:
  provider: custom
  default: claude-sonnet-4-6
  base_url: https://gk.claudeapi.com
  api_key: sk-你的ClaudeAPI密钥
  api_mode: anthropic_messages

model:
  provider: custom
  default: claude-sonnet-4-6
  base_url: https://gk.claudeapi.com
  api_key: sk-你的ClaudeAPI密钥
  api_mode: anthropic_messages

保存后无需重启，下次运行 hermes 自动读取新配置。

Step 3：验证配置

hermes doctor

hermes doctor

输出中看到 LLM provider: OK 即表示连接正常。

也可以直接发一条消息验证：

hermes
# 输入任意问题，看到模型正常回复即配置成功

hermes
# 输入任意问题，看到模型正常回复即配置成功

可用模型列表

ClaudeAPI.com 当前支持以下模型，在 config.yaml 的 default 字段填写对应 Model ID：

切换模型：直接修改 config.yaml 中的 default 字段，或重新运行 hermes model。

进阶：配置 Fallback 模型

当主模型出现错误或限流时，Hermes 可自动切换到备用模型。在 config.yaml 中添加：

model:
  provider: custom
  default: claude-opus-4-6
  base_url: https://gk.claudeapi.com
  api_key: sk-你的ClaudeAPI密钥
  api_mode: anthropic_messages

fallback_model:
  provider: custom
  model: claude-sonnet-4-6
  base_url: https://gk.claudeapi.com
  api_key: sk-你的ClaudeAPI密钥
  api_mode: anthropic_messages

model:
  provider: custom
  default: claude-opus-4-6
  base_url: https://gk.claudeapi.com
  api_key: sk-你的ClaudeAPI密钥
  api_mode: anthropic_messages

fallback_model:
  provider: custom
  model: claude-sonnet-4-6
  base_url: https://gk.claudeapi.com
  api_key: sk-你的ClaudeAPI密钥
  api_mode: anthropic_messages

这样当 Opus 4.6 出现问题时，自动降级到 Sonnet 4.6，不中断工作流。

常用命令速查

常见问题

Q：运行 hermes 后提示 connection error，怎么排查？

先运行 hermes doctor 查看详细错误。最常见原因是 base_url 填写有误，确认填写的是 https://gk.claudeapi.com（不带结尾斜杠）。

Q：api_mode: anthropic_messages 是必填的吗？

是。ClaudeAPI.com 使用 Anthropic Messages API 格式，必须指定 api_mode: anthropic_messages，否则 Hermes 会默认用 OpenAI Chat Completions 格式请求，导致报错。

Q：Windows 用户怎么安装？

Hermes 不支持原生 Windows，需要先安装 WSL2。安装完成后在 WSL2 终端内执行本文所有命令，操作与 Linux 完全一致。

Q：如何更换 API Key？

直接编辑 ~/.hermes/config.yaml，修改 api_key 字段保存即可，无需重新运行 hermes setup。

相关文章

• Claude Code cc-switch 国内接入教程（2026最新）→
• Claude Code 国内最优解：ClaudeAPI.com + MiMo-V2.5-Pro →
• Claude API 价格详解：2026最新定价 →
• Cherry Studio 接入 Claude API 完整教程 →