Hermes Agent 国内使用完整教程：稳定调用（2026）

Hermes Agent 支持自定义 API 接入点，只需把 base_url 换成国内中转地址，就能在国内直连 Claude 全系模型。本文完整记录我的配置过程，避你少踩坑。

---

一、Hermes Agent 是什么？

Hermes Agent 是 NousResearch 推出的开源 AI 智能体框架，定位和 Claude Code 类似，但有几个关键差异：

对比项	Claude Code	Hermes Agent
底层模型	仅 Claude	任意 OpenAI / Anthropic 兼容接入点
消息平台	终端	终端 + Telegram + Discord
内置工具数	~20	47+
持久化记忆	有限	原生支持
开源	否	是

对国内开发者来说，Hermes 最大的优势是：支持填写任意 base_url，这意味着只要找到一个兼容 Anthropic 协议的中转服务，就能在国内无代理跑 Claude。

---

二、前置准备

2.1 系统要求

• macOS / Linux：直接用，安装脚本自动处理依赖
• Windows：需先安装 WSL2，所有命令在 WSL2 内执行

Windows 用户先确认 WSL2 状态：

wsl --list --verbose

如果没有 Ubuntu 发行版，执行：

wsl --install -d Ubuntu

2.2 获取 Claude API Key

注册地址：https://claudeapi.com

注意：记住你的 API Key，下面配置时会用到。

---

三、安装 Hermes Agent

一条命令搞定，脚本自动安装 Python、Node.js、ripgrep 等所有依赖：

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

安装完成后重载 Shell：

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

验证安装：

hermes --version

看到版本号输出就表示安装成功了。

---

四、配置接入点

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

hermes setup

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

提示项	填写内容
API base URL	https://gw.claudeapi.com
API Key	你的 ClaudeAPI.com API Key（sk- 开头）
Model name	claude-sonnet-4-6

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

方式二：直接编辑配置文件（老手推荐）

nano ~/.hermes/config.yaml

找到 model: 部分，替换为：

model:
  provider: custom
  default: claude-sonnet-4-6
  base_url: https://gw.claudeapi.com
  api_key: sk-你的ClaudeAPIKey
  api_mode: anthropic_messages

保存退出（Ctrl+O → Enter → Ctrl+X），无需重启。

---

五、验证配置是否成功

hermes doctor

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

也可以直接发条消息测试：

hermes
# 随便问一个问题，看模型是否正常回复

---

六、可用模型列表

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

模型	Model ID	适用场景
Claude Opus 4.6	claude-opus-4-6	复杂推理、长上下文
Claude Sonnet 4.6	claude-sonnet-4-6	通用开发、Agent 工作流（推荐）
Claude Haiku 4.5	claude-haiku-4-5-20251001	轻量请求、快速响应

切换模型只需改 default 字段，或重跑 hermes model。

---

七、进阶：配置 Fallback 模型

主模型限流或报错时，Hermes 可自动切换备用模型：

model:
  provider: custom
  default: claude-opus-4-6
  base_url: https://gw.claudeapi.com
  api_key: sk-你的ClaudeAPIKey
  api_mode: anthropic_messages

fallback_model:
  provider: custom
  model: claude-sonnet-4-6
  base_url: https://gw.claudeapi.com
  api_key: sk-你的ClaudeAPIKey
  api_mode: anthropic_messages

这样即使 Opus 偶发限流，也能无缝切到 Sonnet 继续工作。

---

八、常见报错及解决方法

报错：401 Unauthorized
→ API Key 填写有误，检查是否带了多余空格，或 Key 已过期。

报错：Connection refused / 连接超时
→ base_url 填写错误，确认使用 https://gw.claudeapi.com（不带尾部斜杠）。

报错：Model not found
→ Model ID 填写错误，对照第六节的表格检查拼写。

Windows 下 .sh 脚本无法运行
→ 必须进入 WSL 环境再执行，PowerShell 不支持 .sh 脚本。

---

九、总结

Hermes Agent 对国内开发者最友好的一点就是支持自定义接入点，配合 ClaudeAPI.com 这类国内可用的中转服务，整个配置流程 10 分钟内就能跑通。

如果你之前因为网络问题一直没法用上 Claude 做 Agent 开发，现在可以试试这个方案。

相关资源：

• ClaudeAPI.com 注册：https://claudeapi.com
• Hermes Agent 官方文档：https://hermes-agent.nousresearch.com
• Hermes GitHub：https://github.com/NousResearch/hermes-agent

有问题欢迎评论区留言，我看到都会回。