Hermes Agent 踩坑实录：从安装到多端消息、服务器与 Cloudflare 全记录

1. 安装体积到底多大？#

~/.hermes 实测 8.5G，看着吓人但大头都有出处：

• hermes-agent/ 5.6G：本体源码，其中 .git 2.5G（升级历史）、node_modules 1.0G（桌面端/TUI）、venv 927M（Python 运行时）
• tools/ 972M：自动下载的 chromium、独立 node、cua-driver 等
• state.db 304M：会话数据库，删了整个聊天记录就没了，别当缓存清

真正能安全回收的只有 cache/scratch 和各种日志，软件本体约 7.5G 属正常水平。

2. npm 全局装包 EACCES#

macOS 下往 /usr/local 写全局包会权限报错。统一改用独立 prefix：

1
npm i -g <pkg> --prefix ~/.npm-global
2
# PATH 里加 ~/.npm-global/bin（写在 ~/.zprofile）

另一个坑：有些 CLI 自带的 xxx update 不认你的 prefix（比如 chatlab-cli），升级仍要回到 npm i -g --prefix ~/.npm-global <pkg>@latest。

3. Node 版本大一统#

机器上同时躺着 brew node、nvm node、pkg 安装的 node 时，脚本会以谁先入 PATH 说了算，构建行为玄学。收敛方案：nvm 设 default 版本 + 全局 CLI 全部搬进 ~/.npm-global，然后卸掉 brew 版 node。系统残留的 /usr/local/bin/node（pkg 装的）最后要么删掉要么确保 PATH 顺序。

1. “No usable credentials” 的假警报（经典陷阱）#

症状：Could not resolve credentials for provider X: No usable credentials found，提示你去设环境变量。

真相：key 可能完全有效。凭证池 ~/.hermes/auth.json 的 credential_pool.<provider> 每项带 last_status / failure_reason 状态字段，一次 402（billing）会把它标成 exhausted，之后即使账户恢复，Hermes 仍按标记判定”无可用凭证”。

处理流程：

1
# 1. 先证伪：直接拿 key 调一次 provider API，200 就说明 key 是好的
2
# 2. 备份后重置
3
cp ~/.hermes/auth.json ~/.hermes/auth.json.bak
4
hermes auth reset <provider>   # 实测可能不彻底，必须回读文件确认
5
# 3. 不彻底就手改 JSON：把 last_status / failure_reason / last_error_* 全部置 null，request_count 归零
6
# 4. 验证：hermes auth status + 实跑一次，输出里没有 "Switched to fallback" 才算过

2. CLI 通了、gateway 还在报错#

gateway 是常驻进程，凭证状态在内存里；CLI 每次新进程读磁盘。清完磁盘状态后如果 gateway 仍报错，需要 hermes gateway restart。

重启多 profile 时别用裸 --replace——它会误杀默认网关（web-ui 托管会自动拉起的那个），要按 pid 文件精确 kill 再启动对应 profile。

3. 自定义 provider 的模型在 /model 里看不到#

hermes model 选择器只管官方 portal，自定义模型用别名暴露：

1
hermes config set model_aliases.<name>.model '<model-id>'
2
hermes config set model_aliases.<name>.provider '<provider>'
3
# 之后 /model <name> 任意平台可切

坑：一次性命令 hermes chat -m <alias> 在已有默认 provider 时不会解析用户别名，会静默归一化到默认模型。走 /model 或环境变量 HERMES_INFERENCE_PROVIDER 才可靠。

4. 图像生成：Web UI 端点没起来怎么办#

走 apikey-image-gen 那条路时如果本机 8648 端口压根没监听（Web UI 没跑），不要死等——直接用 provider 的 chat completions 多模态路由生成图像。注意百炼这类中转端的响应是非标准结构：图片 URL 藏在 output.choices[0].message.content[0].image，不是 OpenAI 标准的 choices 顶层。

1. “通道显示已连接，但消息永远不回”——先查 home_channel#

最高优先级的静默故障：profile 的 home_channel 缺 platform 键 → load_gateway_config() 抛 KeyError: 'platform' → 该 profile 所有适配器直接不启动，但界面上看着一切正常。

1
hermes --profile <name> config set platforms.wecom.home_channel.platform wecom
2
# 然后重启 gateway；修完一个 profile 记得扫一遍所有 profile，同病往往成串

2. 第二高频：发送者没配对#

日志里出现 Unauthorized user ... on wecom 且对方收到 “pairing code: XXXX”，批准即可：

1
hermes -p <profile> pairing approve wecom <CODE>

3. 群消息永远不回 ≠ DM 配对问题#

group_policy: pairing（默认）会丢弃全部群流量。逐群放行：

1
hermes config set platforms.wecom.group_policy allowlist
2
hermes config set platforms.wecom.group_allow_from '["<chatid>"]'
3
# 改完要 gateway restart（这项在适配器构造期读取）

4. 白名单类环境变量必须放全局 .env#

WECOM_ALLOW_ALL_USERS=1 这类开关由 gateway 进程 os.getenv() 读取，而 profile 的 .env 永远不会合并进 os.environ。写在 profile .env 里静默无效，只有 ~/.hermes/.env 生效。

验证也别看 /proc/<pid>/environ——那是 exec 时快照，dotenv 启动后的改动看不见。以行为或 gateway.log 为准。

5. 企微/微信刷屏 ”💻 Running …”#

这些平台不能编辑已发送消息，工具进度每条都会变成新气泡。顶层 display.tool_progress: all 在桌面端很香，但会压过平台默认的静默档：

1
hermes config set display.platforms.wecom.tool_progress false
2
# display 配置每回合解析，不用重启

6. 微信 iLink 通道连发丢消息#

同账号 30 秒内连发多条消息/媒体会被冷却丢弃，批量交付时要间隔发送，不要一个回合甩十条。

1. 连主人自己的 Chrome：走 CDP，别拷 profile#

云浏览器拿不到登录态时，优先 browser.cdp_url = http://127.0.0.1:9222 直连本机开调试端口的 Chrome。use_real_profile（拷贝真实 profile）在 Chrome 运行中必然被写锁卡死。切标签的 Target.activateTarget 不可靠，用 new_tab() 开新标签自带登录态。

2. macOS 图片处理两连坑#

• sips -s format webp 在部分系统版本直接报 Can't write format → 改走 ffmpeg 或 PIL
• ffmpeg 想编码 avif 需要 libaom/encoder，常见发行版没带 → 目标 .avif 时先试，失败退回 PNG 交给构建工具优化

3. 二维码裁剪：OpenCV 有边界，视觉模型补位#

cv2.QRCodeDetector 能解标准方形 QR（裁完还能解码自证），但对微信赞赏码这种圆形太阳码完全无效——它根本不是 QR 格式。可行流程：

1. 标准 QR：detect() 拿四角坐标 → 裁方块 + 白边静区 → detectAndDecode 验证解出的链接和原图一致
2. 太阳码：vision_analyze 让多模态模型估圆心半径 → 按几何裁剪 → 再用视觉复检”无切边、无残留文字”

最后从线上 URL 拉回来做一次端到端解码/复检，防 CDN 给你旧图。

4. giscus 评论报 “app is not installed on this repository”#

仓库开了 Discussions 也会报——giscus 这个 GitHub App 必须单独安装授权：github.com/apps/giscus → 只选博客仓库 → Install and Authorize（会要求 passkey 二次验证）。装完不用改任何代码，刷新页面评论区就出来了。

1. 海外 VPS 的 SSH 玄学超时#

Vultr 东京机从国内连经常 Connection timed out during banner exchange，但 443 端口 curl 秒通。结论：线路抖动，不是机器死了，别上机排查——套一层 2~3 次重试循环即可。

2. 内联 ssh 命令是引号地狱，永远走脚本 + stdin#

1
ssh host 'bash -s' < /tmp/probe.sh

内联字符串里出现中文括号、%{...}、嵌套引号、python3 -c 时必炸。长命令还有 Argument list too long 风险。

3. 构建类长任务要完全脱离 ssh 会话#

直接 nohup ... & 挂在 ssh 里，ssh 断开仍可能带走子进程：

1
ssh host 'cd /opt/x && (setsid nohup bash -c "pnpm run build && ...; echo EXIT=\$?" >> build.log 2>&1 < /dev/null &); echo started'
2
# 之后另开连接 tail build.log 轮询

反面教材：pkill -f xxx 的匹配串也会命中你 ssh 命令自己，把会话杀死——用字符类打断如 pkill -f "kev[.]serve"。

4. nginx 的 403 不是 404#

静态站上「目录存在但没有 index.html」返回 403。写了 error_page 403 404 /404.html; 状态码仍然是 403（原始码透传），必须加等号强制改写：

1
error_page 403 404 =404 /404.html;

5. Cloudflare 橙云下的证书与缓存#

• HTTP-01 验证可以穿过 CF 代理正常签 Let’s Encrypt，源站选 Full 模式；但代理会把静态资源边缘缓存 4h，换图后 URL 加版本号（alipay.png?v=20260928）是最省事的破缓存手段，比登录后台刷缓存快
• 域名 NS 在 CF、解析走橙云时，dig 到的是 CF 边缘 IP 而不是你的 VPS——这是特性不是解析失败

6. 本机 DNS 会骗人#

家庭网络装了分流代理时，dig 本机可能返回 198.18.x.x 这类假 IP。验证公网解析一律走 DoH：

1
curl -s "https://dns.google/resolve?name=example.com&type=A"