WorkBuddy 部署 Hermes Agent v0.9.0 踩坑记录：auxiliary_client 401 问题排查全流程

用 WorkBuddy 的 Auto 模式在 Mac 上部署 Hermes Agent，遇到 auxiliary_client 反复报 401 错误，折腾了一整晚。把排查过程和经验教训分享出来，希望能帮到遇到同样问题的朋友。

一、背景

目标：在 iMac (2014, macOS 11.6 Big Sur) 上部署 Hermes Agent v0.9.0，配置 DeepSeek 作为辅助模型，通过 iLink Bot 接入微信网关。

环境信息：

• macOS 11.6 (Big Sur)
• Python 3.11 + venv
• Hermes Agent v0.9.0
• DeepSeek API (通义千问 Plus 模型)
• launchd 守护进程管理

部署方式：全程使用 WorkBuddy 的 Auto 模式进行，AI 自主执行安装、配置、调试。

二、部署流程回顾

第一阶段：基础安装 ✅

这一步很顺利：

bash

复制

# 克隆仓库并安装
git clone https://github.com/xxx/hermes.git ~/hermes_full
cd ~/hermes_full
python3 -m venv venv
source venv/bin/activate
pip install -e .

# 配置 DeepSeek API Key
hermes config set providers.deepseek.api_key sk-xxx

安装完成，hermes CLI 正常可用。

第二阶段：网关配置 ⚠️

配置 iLink Bot 微信网关：

bash

复制

hermes gateway configure \
  --ilink-bot-token "your_token" \
  --ilink-bot-endpoint "wss://ilink-bot.example.com/ws"

第三阶段：启动网关并注册 ✅

bash

复制

hermes gateway start
hermes auth register --email your@email.com --password yourpass
hermes auth login

CLI 和网关都正常启动，主模型（用于对话的模型）工作正常。

第四阶段：auxiliary_client 报错 ❌

网关启动后，后台辅助模型客户端 auxiliary_client 初始化失败，日志中反复出现：

ERROR auxiliary_client | HTTP 401: Authentication failed for model provider 'deepseek/custom/main'

这个错误导致：

• 后台任务（如自动摘要、意图分类）无法执行
• 网关虽然能接收消息，但辅助功能全部失效

三、排查过程（血泪史）

尝试 1：环境变量配置

bash

复制

# 在 ~/.hermes/.env 中设置
DEEPSEEK_API_KEY=sk-xxx

# 在 launchd plist 中设置环境变量
<key>EnvironmentVariables</key>
<dict>
  <key>DEEPSEEK_API_KEY</key>
  <string>sk-xxx</string>
</dict>

结果：❌ 无效，仍然 401。

尝试 2：修改 config.yaml

在 ~/.hermes/config.yaml 中显式配置：

yaml

复制

providers:
  deepseek:
    api_key: sk-xxx
    base_url: https://api.deepseek.com/v1
    default_model: deepseek-chat

结果：❌ 无效。

尝试 3：直接修改源码注入 API Key

修改 agent/auxiliary_client.py，在初始化时直接传入 api_key：

python

复制

client = AsyncOpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com/v1"
)

结果：❌ 仍然 401。说明问题不在 key 的传递上，而是 provider 注册逻辑本身。

尝试 4：阅读源码分析

深入阅读 auxiliary_client.py 和 provider 注册相关代码，发现：

• auxiliary_client 通过 provider 名称 deepseek/custom/main 查找已注册的 provider
• provider 注册发生在网关启动时，但注册逻辑中似乎没有正确读取 api_key 配置
• 即使环境变量和配置文件都有 key，provider 实例化时可能使用了空的 key

尝试 5：使用 CLI 模式验证

bash

复制

hermes gateway stop
hermes chat "你好"

CLI 模式下 DeepSeek 模型调用正常，说明 API Key 本身没问题。

结论：问题出在网关模式下 auxiliary_client 的 provider 注册逻辑，与 API Key 的正确性无关。

四、最终结论

经过一整晚的排查，判断这是一个 Hermes Agent 代码层面的 bug：

1. CLI 模式正常，网关模式异常 → 说明 key 配置没问题
2. 所有传参方式都试过 → 环境变量、config.yaml、launchd plist、硬编码全无效
3. 主模型正常，辅助模型异常 → 说明 auxiliary_client 的 provider 初始化逻辑有缺陷
4. 错误信息 custom/main → provider 路径拼接可能有问题，导致找不到正确的 provider 实例

五、经验教训

1. 先验证 API Key，再排查代码

wasted 很多时间在「key 没传对」这个方向上。应该先在 CLI 模式下确认 key 可用，再去看网关代码。

2. 用 WorkBuddy 调试要注意积分消耗

AI 反复试错会快速消耗积分。建议：

• 简单调试手动操作
• 复杂代码分析再交给 AI
• 遇到代码 bug 及时止损，先去提 issue

3. launchd 和 Hermes CLI 不能同时运行

Hermes 的网关进程不能通过 CLI 和 launchd 同时管理，否则会抢占 WebSocket 连接。

4. 8GB 内存跑多 AI 应用确实紧张

iMac 2014 的 8GB 内存同时跑 Hermes 网关 + WorkBuddy 比较吃力，建议升级内存。

六、后续建议（给遇到同样问题的朋友）

1. 去 GitHub 提 Issue：描述清楚 CLI 正常但网关 auxiliary_client 报 401 的现象
2. 换 OpenRouter 中转：用 OpenRouter 的 key 替代直连 DeepSeek，可能绕过 provider 注册的 bug
3. 先用 CLI 模式：不急的话先用 hermes chat 等命令行模式，等 bug 修复再开网关
4. 降级版本：如果 v0.9.0 有问题，尝试 v0.8.x 看看是否正常

七、WorkBuddy 使用体验

虽然最终没解决 Hermes 的 bug，但 WorkBuddy 的 Auto 模式在整个过程中表现还是不错的：

• ✅ 自动克隆仓库、创建 venv、安装依赖
• ✅ 自动配置 launchd 守护进程
• ✅ 自动分析日志、定位错误
• ✅ 自动阅读源码、分析 provider 注册逻辑
• ⚠️ 唯一的不足：AI 在确认「这是代码 bug」之前，花了太多轮试错

省积分建议：遇到这种需要深入排查代码的问题，可以让 AI 做一次全面分析后给出结论，而不是反复试错。

部署环境：macOS 11.6 / Python 3.11 / Hermes Agent v0.9.0 / WorkBuddy Auto 模式 发布日期：2026-04-15