Hermes Agent 安装配置教程（Windows 小白版）

这是一份从零开始的教程，教你在 Windows 电脑上安装 Hermes Agent（一个超强的 AI 助手工具），并对接飞书机器人。

Hermes 是什么？简单说就是一个可以记住你、会自己学习进步的 AI 助手，类似 OpenClaw，但更强大。它能通过终端、网页、飞书、Telegram 等多种方式跟你聊天。

目录

1. 安装 WSL2（Windows 里跑 Linux）
2. 安装 Hermes Agent
3. 安装 Hermes WebUI（网页界面）
4. 配置 AI 模型（让 Hermes 能思考）
5. 对接飞书机器人
6. 在飞书中操作项目（进阶用法）
7. 性能优化与多 Agent 协作（进阶）
8. 常用命令速查表
9. 常见问题

第一步：安装 WSL2

什么是 WSL2？

WSL2 就是让你在 Windows 里跑一个 Linux 系统。Hermes 只能在 Linux 上运行，所以我们需要先装这个。

操作步骤

1. 以管理员身份打开 PowerShell

   • 右键点击「开始」按钮 → 选择「Windows PowerShell (管理员)」

2. 输入安装命令

   wsl --install
   

3. 重启电脑（安装完会提示你重启）

4. 重启后会自动弹出 Ubuntu 窗口，让你设置用户名和密码

   • 用户名：随便取，比如 p
   • 密码：随便设，但要记住（输入密码时屏幕不会显示，正常的）

5. 验证安装成功

   • 打开 PowerShell，输入：

   wsl -l -v
   

   • 看到 Ubuntu 且 VERSION 是 2 就对了

以后怎么进入 Linux？

在 PowerShell 或 CMD 里输入 wsl 回车就行了。

第二步：安装 Hermes Agent

操作步骤

1. 进入 WSL

   • 打开 PowerShell，输入 wsl 回车

2. 运行一键安装脚本

   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
   

   这个脚本会自动帮你装好所有东西：Python、Node.js、Hermes 本体等。

   安装过程中如果提示要 sudo 密码，输入你刚才设置的密码。

   如果 ripgrep 和 ffmpeg 安装失败也没关系，它们是可选的，不影响使用。

3. 安装完成后，重新加载环境

   source ~/.bashrc
   

4. 验证安装成功

   hermes --version
   

   能看到版本号就说明装好了。

5. 首次设置

   hermes setup
   

   按提示选择你要用的 AI 模型和 provider。

第三步：安装 Hermes WebUI（网页界面）

WebUI 让你可以在浏览器里用 Hermes，比终端好看好用。

操作步骤

1. 在 WSL 中运行

   git clone https://github.com/nesquena/hermes-webui.git ~/hermes-webui
   cd ~/hermes-webui
   python3 bootstrap.py --no-browser
   

2. 看到这行就成功了

   [bootstrap] Web UI is ready: http://localhost:8787
   

3. 打开浏览器，访问 http://localhost:8787

以后每次启动 WebUI

WSL 重启后 WebUI 会停掉，需要手动重新启动：

cd ~/hermes-webui && python3 bootstrap.py --no-browser

小技巧：可以把这行命令加到 ~/.bashrc 末尾，这样每次打开 WSL 就自动启动 WebUI。

第四步：配置 AI 模型

Hermes 需要连接一个 AI 模型才能工作。你可以配置多个 Profile（配置方案），每个用不同的模型。

概念解释

• Provider：模型提供商（比如 Anthropic、小米、OpenAI）
• API Key：你的密钥，用来验证身份
• Base URL：API 地址（如果走代理或用非默认地址，就需要改这个）
• Profile：一套完整的配置方案，可以随时切换
• Token Plan（套餐计划）：预付费套餐，有额度限制但单价更低
• 按量计费：用多少算多少，没有预付，但单价稍贵

三种常见模型接入方式

4.1 配置全局环境变量（.env 文件）

这是所有配置的基础，不管用哪种方式都要先配这个：

nano ~/.hermes/.env

根据你要用的 provider 添加环境变量：

# ============ Claude 走代理 ============
ANTHROPIC_API_KEY=你的代理key
ANTHROPIC_BASE_URL=https://你的代理地址

# ============ 小米 MiMo - Token Plan（套餐计划）============
# 注意！Token Plan 的 base_url 和按量计费的不同！
XIAOMI_API_KEY=tp-开头的key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/anthropic

# ============ 小米 MiMo - 按量计费 ============
# XIAOMI_API_KEY=sk-开头的key
# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1

# ============ OpenRouter（一个key用200+模型）============
# OPENROUTER_API_KEY=你的key

保存退出：按 Ctrl+X，然后按 Y，再按 Enter。

重要提示：XIAOMI_BASE_URL 必须设置！ Hermes 的小米 provider 通过这个环境变量读取地址。如果不设，会用默认地址，导致 Token Plan 的 key 报 401 错误。

4.2 配置方式一：Claude 走代理

适用场景：你有 Claude 的代理服务（比如 maas.marketingforce.com 等第三方转发）。

第一步：设置 .env

nano ~/.hermes/.env

添加：

ANTHROPIC_API_KEY=sk-xxxxxx你的代理key
ANTHROPIC_BASE_URL=https://maas.marketingforce.com

第二步：创建 Profile

mkdir -p ~/.hermes/profiles/marketing
nano ~/.hermes/profiles/marketing/config.yaml

写入：

model:
  provider: anthropic
  default: claude-opus-4-6
  api_key: sk-xxxxxx你的代理key
  base_url: https://maas.marketingforce.com

第三步：如果要作为全局默认模型

编辑全局配置：

nano ~/.hermes/config.yaml

确保 model: 部分是：

model:
  max_tokens: 16384
  default: claude-opus-4-6
  provider: anthropic
  base_url: https://maas.marketingforce.com
  api_key: sk-xxxxxx你的代理key

4.3 配置方式二：小米 MiMo Token Plan（套餐计划）

适用场景：你在 https://platform.xiaomimimo.com 购买了月度/年度套餐。

Token Plan 和按量计费的区别：

第一步：设置 .env（关键！）

nano ~/.hermes/.env

添加：

XIAOMI_API_KEY=tp-xxxxxx你的tokenplan的key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/anthropic

坑点提醒： XIAOMI_BASE_URL 这个环境变量必须写！Hermes 通过它来确定小米的 API 地址。如果只在 config.yaml 里写 base_url 而不设这个环境变量，Hermes 还是会用默认地址，导致你的 Token Plan key 认证失败（401 Invalid API Key）。

第二步：创建 Profile

mkdir -p ~/.hermes/profiles/xiaomimimo
nano ~/.hermes/profiles/xiaomimimo/config.yaml

写入：

model:
  provider: xiaomi
  default: mimo-v2.5-pro
  api_key: tp-xxxxxx你的tokenplan的key
  base_url: https://token-plan-cn.xiaomimimo.com/anthropic

第三步：修复域名识别（重要！）

Hermes 默认只识别 api.xiaomimimo.com 和 xiaomimimo.com，不认识 token-plan-cn.xiaomimimo.com。需要手动添加：

nano ~/.hermes/hermes-agent/agent/model_metadata.py

搜索 "xiaomimimo.com": "xiaomi",（按 Ctrl+W 搜索），在它下面加一行：

    "token-plan-cn.xiaomimimo.com": "xiaomi",

改完后这几行应该是：

    "api.xiaomimimo.com": "xiaomi",
    "xiaomimimo.com": "xiaomi",
    "token-plan-cn.xiaomimimo.com": "xiaomi",

第四步：如果要作为全局默认模型

nano ~/.hermes/config.yaml

确保 model: 部分是：

model:
  max_tokens: 16384
  default: mimo-v2.5-pro
  provider: xiaomi
  base_url: https://token-plan-cn.xiaomimimo.com/anthropic
  api_key: tp-xxxxxx你的tokenplan的key

4.4 配置方式三：小米 MiMo 按量计费

适用场景：你在小米平台注册后获得的默认 API key（sk- 开头）。

第一步：设置 .env

nano ~/.hermes/.env

添加：

XIAOMI_API_KEY=sk-xxxxxx你的按量计费key
XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1

第二步：创建 Profile

mkdir -p ~/.hermes/profiles/xiaomimimo
nano ~/.hermes/profiles/xiaomimimo/config.yaml

写入：

model:
  provider: xiaomi
  default: mimo-v2.5-pro
  api_key: sk-xxxxxx你的按量计费key
  base_url: https://api.xiaomimimo.com/v1

按量计费用的是 OpenAI 兼容协议（/v1 结尾），和 Token Plan 的 Anthropic 兼容协议（/anthropic 结尾）不一样，不要搞混！

4.5 使用不同的 Profile

hermes -p marketing      # 用 Claude 代理配置启动
hermes -p xiaomimimo     # 用小米 MiMo 配置启动
hermes                   # 用全局默认配置启动

在 WebUI 里可以直接在底部栏切换 profile，不需要命令行。

4.6 验证配置是否正确

配置完后，用 curl 测试一下能不能通：

测试 Claude 代理：

curl -s -o /dev/null -w '%{http_code}' -X POST 'https://你的代理地址/v1/messages' \
  -H 'x-api-key: 你的key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  -d '{"model":"claude-opus-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

测试小米 Token Plan：

curl -s -o /dev/null -w '%{http_code}' -X POST 'https://token-plan-cn.xiaomimimo.com/anthropic/v1/messages' \
  -H 'x-api-key: 你的tp-开头的key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  -d '{"model":"mimo-v2.5-pro","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

测试小米按量计费：

curl -s -o /dev/null -w '%{http_code}' -X POST 'https://api.xiaomimimo.com/v1/chat/completions' \
  -H 'Authorization: Bearer 你的sk-开头的key' \
  -H 'content-type: application/json' \
  -d '{"model":"mimo-v2.5-pro","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

返回 200 就说明配置正确。如果返回 401 说明 key 无效，402 说明余额不足。

4.7 已知问题及修复

问题一：小米模型名称 bug（503 错误）

如果你用小米的 mimo-v2.5-pro 模型遇到 503 错误（日志显示请求的是 mimo-v2-5-pro），那是因为 Hermes 代码中没有把小米加入"保留点号"白名单，把版本号里的点变成了横杠。

修复方法：

nano ~/.hermes/hermes-agent/run_agent.py

搜索 "alibaba", "minimax", "minimax-cn",（按 Ctrl+W 搜索），把这行改成：

"alibaba", "minimax", "minimax-cn", "xiaomi",

保存退出，重启 hermes 即可。

问题二：Token Plan 报 401 Invalid API Key

最常见原因：没有设置 XIAOMI_BASE_URL 环境变量。

Hermes 的小米 provider 通过 XIAOMI_BASE_URL 环境变量来确定 API 地址。即使你在 config.yaml 里写了 base_url，如果 .env 里没有这个变量，Hermes 还是会用默认地址。你的 Token Plan key 在默认地址上是无效的，所以报 401。

修复： 确保 .env 里有：

XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/anthropic

问题三：余额不足（402 错误）

• 按量计费：去小米平台充值
• Token Plan：检查套餐是否到期或额度用完（在 https://platform.xiaomimimo.com 查看）

第五步：对接飞书机器人

让 Hermes 变成你的飞书机器人，在飞书里直接跟 AI 聊天。

5.1 在飞书开放平台创建机器人

1. 打开 https://open.feishu.cn/app
2. 点击「创建企业自建应用」
3. 填写应用名称（比如「我的AI助手」）
4. 创建完成后，记下：
   • App ID（类似 cli_a9799aead7b89bd5）
   • App Secret（类似 3PAp4f3YVuJtmI6XpFevKcTranQU1Z7q）

5.2 配置机器人权限

在飞书开放平台的应用设置中：

1. 「添加应用能力」→ 添加「机器人」
2. 「权限管理」→ 开通以下权限：
   • im:message （接收消息）
   • im:message:send_as_bot （发送消息）
3. 「事件订阅」→ 选择 WebSocket 模式（推荐，不需要公网服务器）
4. 发布应用（版本管理 → 创建版本 → 申请发布）

5.3 在 Hermes 中配置飞书

编辑 .env 文件：

nano ~/.hermes/.env

添加以下内容：

# 飞书配置
FEISHU_APP_ID=你的App_ID
FEISHU_APP_SECRET=你的App_Secret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=false
FEISHU_ALLOWED_USERS=
FEISHU_GROUP_POLICY=open
FEISHU_HOME_CHANNEL=你的App_ID

保存退出。

5.4 启动 Gateway（消息网关）

hermes gateway run

看到类似这样的输出就成功了：

[Lark] connected to wss://msg-frontier.feishu.cn/ws/v2?...

5.5 配对你的飞书账号

第一次在飞书上给机器人发消息，机器人会回复一个配对码，类似：

Hi~ I don't recognize you yet!
Here's your pairing code: K4UUPYM4
Ask the bot owner to run:
    hermes pairing approve feishu K4UUPYM4

在 WSL 中另开一个终端（或按 Ctrl+C 停掉 gateway 再执行），运行：

hermes pairing approve feishu 你收到的配对码

看到 Approved! 就配对成功了。之后在飞书上给机器人发消息就能正常聊天了。

5.6 让 Gateway 后台运行

前台运行的话关掉终端就断了。用 nohup 让它后台跑：

nohup hermes gateway run > ~/.hermes/gateway.log 2>&1 &

查看运行状态：

hermes gateway status

停止运行：

kill $(ps aux | grep 'hermes gateway' | grep -v grep | awk '{print $2}')

常用命令速查表

启动类

配置类

管理类

聊天中的命令（在 hermes 对话中输入）

常见问题

Q: WSL 重启后 Hermes 和 WebUI 都没了？

A: 数据不会丢，但进程需要重新启动：

# 启动 WebUI
cd ~/hermes-webui && python3 bootstrap.py --no-browser

# 启动 Gateway（飞书等）
hermes gateway run

Q: 安装时 ripgrep 和 ffmpeg 失败？

A: 先更新 apt 源再装：

sudo apt-get update
sudo apt-get install -y ripgrep ffmpeg

这两个是可选的，不装也不影响核心功能。

Q: API 连不上（走代理的情况）？

A: 确认 .env 文件中的 BASE_URL 设置正确。不同代理的路径格式可能不同：

• https://你的代理地址
• https://你的代理地址/v1
• https://你的代理地址/anthropic

Q: 小米模型报 503？

A: 参考第四步的「已知问题：小米模型名称 bug」修复。

Q: sudo hermes 提示 command not found？

A: hermes 装在用户目录下，sudo 找不到。不要用 sudo，直接运行 hermes 就行。Gateway 也用 hermes gateway run 而不是 systemd 服务。

Q: 飞书机器人收不到消息？

A: 检查以下几点：

1. Gateway 是否在运行（hermes gateway run）
2. 飞书应用是否已发布上线
3. 是否已配对（hermes pairing approve feishu 配对码）
4. WebSocket 模式是否已开启

Q: 怎么让多个 profile 同时对接飞书？

A: Gateway 默认用全局配置。如果想指定 profile：

hermes -p xiaomimimo gateway run

第六步：在飞书中操作项目（进阶用法）

Hermes 不只是聊天，还可以通过飞书远程操作你的代码项目——读文件、写文件、跑命令，就像一个远程编程助手。

飞书中可用的命令

在飞书聊天框里直接输入这些斜杠命令：

设置工作目录（让 Hermes 能操作你的项目）

Gateway 启动时会用配置中的 terminal.cwd 作为工作目录。改成你的项目路径，Hermes 就能在飞书里直接操作你的代码了：

nano ~/.hermes/config.yaml

找到 terminal 部分，修改 cwd：

terminal:
  cwd: /home/p/你的项目路径

比如你的项目在 /home/p/myproject，就改成：

terminal:
  cwd: /home/p/myproject

保存后重启 gateway 生效。

你也可以直接在飞书对话中让 Hermes 用 cd 命令切换目录，不一定非要改配置。

WebUI vs 飞书 功能对比

用指定 Profile 启动飞书 Gateway

飞书中不能动态切换 profile，但可以在启动时指定：

# 用小米模型对接飞书
hermes -p xiaomimimo gateway run

# 用 Claude 对接飞书
hermes -p marketing gateway run

实际使用场景举例

在飞书中你可以这样跟 Hermes 说：

• "帮我看看 src/main.py 的代码"
• "把 config.json 里的 debug 改成 false"
• "跑一下测试 pytest tests/"
• "帮我写一个新的 API 接口"
• "看看 git log 最近提交了什么"

Hermes 会在你指定的工作目录下执行这些操作，就像你坐在电脑前一样。

重要文件位置

第七步：性能优化与多 Agent 协作（进阶）

7.1 解决"干着干着就停了"的问题

如果你发现 Hermes 在生成长内容时突然停掉（特别是用小米 MiMo 模型时），原因是默认输出 token 上限太低（4096），生成到一半就被截断了。

修复方法：增大 max_tokens

nano ~/.hermes/config.yaml

在 model: 部分添加 max_tokens：

model:
  max_tokens: 16384
  default: mimo-v2.5-pro
  provider: xiaomi

16384 对于大多数任务足够了。如果还是不够，可以改成 32768。

7.2 显示思考过程

默认配置下 Hermes 不展示 AI 的推理过程，看起来就是一直在 "thinking" 但你不知道它在干什么。

修复方法：开启 show_reasoning

在 ~/.hermes/config.yaml 中找到 display 部分，改成：

display:
  show_reasoning: true

这样就能在对话中看到模型的思考过程了。

7.3 多 Agent 协作（让多个 AI 一起干活）

Hermes 支持 orchestrator 编排模式：一个主 Agent 把复杂任务拆分成多个子任务，分配给多个子 Agent 并行执行。

相关配置（在 ~/.hermes/config.yaml 中）：

delegation:
  model: claude-opus-4-6          # 编排器用的模型（建议用聪明的）
  provider: anthropic             # 编排器的 provider
  orchestrator_enabled: true      # 开启编排器
  max_concurrent_children: 3      # 最多3个子agent同时工作
  max_spawn_depth: 1              # 子agent嵌套层级
  max_iterations: 50              # 每个子agent最多执行50轮
  child_timeout_seconds: 600      # 子agent超时时间（秒）

推荐配置策略：

这样性价比最高：编排器用 Claude 来规划，子任务用便宜/免费的模型来执行。

怎么触发多 Agent：

在对话中给 Hermes 一个复杂的多步骤任务，比如：

• "帮我做一个完整的项目，包括前端、后端和数据库设计"
• "请拆解这个任务，用多个子agent并行完成"
• "同时分析这三个文件的代码质量"

Hermes 的 orchestrator 会自动判断是否要拆分，并行执行子任务。

7.4 推理深度调整

如果觉得模型回答太浅，可以调整 reasoning_effort：

agent:
  reasoning_effort: high    # 可选值：low / medium / high

• low：快速回答，适合简单问题
• medium：默认值，平衡速度和质量
• high：深度思考，适合复杂推理任务

相关链接

• Hermes Agent GitHub: https://github.com/NousResearch/hermes-agent
• Hermes WebUI GitHub: https://github.com/nesquena/hermes-webui
• Hermes 官方文档: https://hermes-agent.nousresearch.com/docs/
• 飞书开放平台: https://open.feishu.cn/app
• 小米 MiMo 平台: https://platform.xiaomimimo.com