Hermes Agent

Hermes Agent（NousResearch 出品）是一个 Python 写的开源 AI agent CLI，自带 40+ 工具（文件、终端、网页搜索、代码分析）+ Skill 自学习 + 长期记忆 + IM 网关（Telegram / Discord / Slack / WhatsApp）。适合做「比 Claude Code 更通用的智能体」，跑长任务、自动化、cron。

1. 安装

系统要求

  • macOS / Linux ✅ 完整支持；Windows 用 WSL2（原生支持是 beta）
  • Python 3.11+（安装脚本会用 uv 自动配）
  • Git（如果没装，安装脚本会下个 ~45MB 的便携 MinGit）
  • 节点依赖（脚本自动装 Node.js + Playwright Chromium for 网页工具）

一键安装

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)"

装好后所有东西都在 ~/.hermes/：

  • ~/.hermes/hermes-agent/ — 主代码 + venv
  • ~/.hermes/config.yaml — 主配置
  • ~/.hermes/.env — 仅 API key 类敏感字段
  • ~/.hermes/logs/ — 日志（agent.log / errors.log / gateway.log）
  • ~/.hermes/skills/ — 自学习的技能
  • ~/.hermes/sessions/ — 会话历史（FTS5 全文搜索）

2. 接入 Miloapi

Hermes Agent 用 provider: custom 模式走 OpenAI 兼容协议，跟 Miloapi 完美匹配。

2.1 编辑配置

hermes config edit

会用 $EDITOR（默认 nano）打开 ~/.hermes/config.yaml。改 model: 段：

model:
  default: gpt-5.5                       # 或 claude-opus-4-7 等
  provider: custom
  base_url: https://www.miloapi.com/v1   # ⚠️ 末尾带 /v1
  api_key: sk-你的key                     # 见下方 §2.2 注意事项

2.2 选对 key（重要，避免 403）

Miloapi 不同分组的 key 只能调对应平台的模型，用错会 403：

你想跑的模型必须用哪个分组的 key
gpt-5.x、gpt-image-2、codex-auto-reviewGPT 或 gpt（无生图） 组的 key
claude-opus-4-7、claude-sonnet-4-6、claude-haiku-4-5Claude-MAX 池的 key
gemini-3.1-pro-preview、gemini-2.5-flashgemini 组的 key

去 API 密钥 页面看每把 key 的分组标签，复制对应那把的完整 key 填进去。

2.3 推荐配置示例

跑代码 / 通用 agent（GPT 池，便宜）：

model:
  default: gpt-5.5
  provider: custom
  base_url: https://www.miloapi.com/v1
  api_key: sk-1fa...
agent:
  max_turns: 90
  gateway_timeout: 1800
  reasoning_effort: medium

长上下文 / 复杂推理（Claude opus）：

model:
  default: claude-opus-4-7
  provider: custom
  base_url: https://www.miloapi.com/v1
  api_key: sk-ad2...           # Claude-MAX 池
agent:
  max_turns: 90
  gateway_timeout: 1800
  service_tier: ''

💡 base_url 末尾必须是 /v1。Hermes 自己会拼上 /chat/completions。

2.4 也可以用 CLI 直接设

不想手动编辑，可以：

hermes config set model.default gpt-5.5
hermes config set model.provider custom
hermes config set model.base_url https://www.miloapi.com/v1
hermes config set model.api_key sk-你的key

值会自动按字段类型路由到 config.yaml 或 .env。

3. 启动

hermes          # 经典 CLI
hermes --tui    # 推荐的现代 TUI（弹窗 + 鼠标选择 + 非阻塞输入）

启动后会看到欢迎横幅，显示：

  • 当前 model
  • 可用工具列表
  • 已学习的 skills

直接输入问题就开始用：

> 帮我读一下当前目录所有的 .py 文件，找出可能的性能瓶颈
[Hermes 调 list_dir → read_file × N → 分析 → 输出报告]

4. 常用配置项

写在 ~/.hermes/config.yaml 里：

字段说明推荐值
agent.max_turns一次任务最多多少轮 tool call90（默认）
agent.gateway_timeout网关超时（秒）1800（30 分钟，够长任务）
agent.api_max_retriesAPI 重试次数3
agent.tool_use_enforcement强制走 tool（auto / required / disabled）auto
agent.reasoning_effort思考深度（low / medium / high / xhigh）medium，复杂任务用 high
agent.image_input_mode图片输入处理auto
agent.verbose调试模式打印更多日志false
disabled_toolsets禁用某些工具（如 ["browser"]）空
toolsets启用的工具组["hermes-cli"]（核心组）

4.1 fallback provider（容灾）

Hermes 支持配多个 provider，主 provider 挂了自动切换。在 config.yaml 加：

fallback_providers:
  - provider: custom
    base_url: https://www.miloapi.com/v1
    api_key: sk-备用key
    model: gpt-5.4         # 主 provider 挂了的时候用便宜的兜底

4.2 MCP server 配置

跟 Claude Code 类似，Hermes 也支持 MCP：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

5. 常用 CLI 命令

命令作用
hermes启动经典 CLI
hermes --tui启动现代 TUI
hermes config edit编辑配置
hermes config set X Y单字段设置
hermes config list看当前所有配置
hermes model切换模型（无需重启）
hermes gateway start起 IM 网关（Telegram / Discord 等）
hermes sessions list列出所有历史会话
hermes sessions resume <id>恢复某次会话
hermes skills list看自学习产出的技能

进入会话内常用斜杠命令：/quit 退出、/clear 清屏、/save <name> 保存会话、/model 切换模型。

6. 故障排查

现象处理
403 Forbidden99% 是 §2.2 的 key 分组不匹配；换对的分组 key
401 UnauthorizedAPI key 粘错了 / 多了空格 / key 已被禁用，去 dashboard 确认
429 Too Many Requests余额不足或者分组 RPM 限制；充值或换分组
model context exceedsprompt 超过模型上下文（Claude 200k / GPT 1M）；调小 max_turns 或换 long-context 模型
Hermes 启动失败说 "context < 64000"Hermes 要求模型上下文 ≥ 64k；不要用 nano 类小模型
工具调用一直转圈Playwright 没装好，跑 cd ~/.hermes/hermes-agent && uv run playwright install chromium
Windows 装不上用 WSL2，原生 Windows 支持还是 beta
余额一直不动在 Miloapi dashboard 的「使用记录」查实际扣费，确认是否走通

7. 跟 Claude Code 的差异

维度Hermes AgentClaude Code
主要用途通用智能体、长任务、cron终端编程助手（IDE-like）
模型支持OpenAI / Claude / Gemini / Kimi / GLM 等几十家主要 Claude
Skill 自学习✅ 有，5+ tool call 后自动生成 skill markdown❌ 无
长期记忆✅ FTS5 跨会话搜索 + LLM 摘要❌ 单会话
IM 网关✅ Telegram / Discord / Slack / WhatsApp❌ 无
上手难度中（要懂配置 yaml）低
适合场景自动化、研究型 agent、远程 IM 控制日常写代码

8. 计费说明

走 Miloapi 标准计费：

  • 跑 gpt-5.5 × GPT 组 0.3× 倍率 → 实际成本 = 上游价 × 0.3
  • 跑 claude-opus-4-7 × Claude-MAX 1.8× 倍率 → 实际成本 = 上游价 × 1.8

Hermes 默认每轮可能产生多次 tool call + LLM 调用，所以 agent 任务单次成本比单次对话高，是正常的。建议：

  • 长任务用 gpt-5.5 或 gpt-5.4 跑（性价比好）
  • 关键决策点 / 推理深度高的任务才上 claude-opus-4-7

详细价格 + 倍率：余额与计费

最近更新：: