HS Knowledge Vault

Termux Hermes — 移动端 Hermes Agent 部署与排错

5分钟阅读

Termux Hermes — 移动端部署与排错

Hermes agent 在手机（Termux）上的部署、配置、典型故障。这是 Hermes1（主控）跑的环境。

环境概况

  • 平台：Android + Termux
  • Hermes 安装路径：/data/data/com.termux/files/home/.hermes/hermes-agent/
  • Hermes 版本（截至 2026-06-02）：v0.15.1 (2026.5.29)
  • Python：3.13.13
  • OpenAI SDK：2.32.0
  • MCP server 路径：~/.hermes/hermes-agent/mcp.json

MCP 配置 (mcp.json)

{
  "mcpServers": {
    "plur": {
      "command": "/data/data/com.termux/files/home/.hermes/bin/plur-mcp"
    },
    "mmx": {
      "command": "node",
      "args": [".bin/mmx-mcp-server.cjs"]
    }
  }
}

注意：

  • plur 用绝对路径（binary 可执行文件）
  • mmx 用裸 node 走系统 PATH + 相对 cwd 解析 .bin/mmx-mcp-server.cjs

🐛 Bug: hermes gateway 启动时 MCP server 连不上（2026-06-02）

现象

$ hermes gateway
⚙ Hermes Gateway Starting...
WARNING tools.mcp_tool: MCP server 'plur' initial connection failed (attempt 1/3), retrying in 1s: unhandled errors in a TaskGroup (1 sub-exception)
WARNING tools.mcp_tool: MCP server 'mmx' initial connection failed (attempt 1/3), retrying in 1s: unhandled errors in a TaskGroup (1 sub-exception)
...
WARNING tools.mcp_tool: Failed to connect to MCP server 'mmx' (command=node): Connection closed
WARNING tools.mcp_tool: Failed to connect to MCP server 'plur' (command=/data/data/com.termux/files/home/.hermes/bin/plur-mcp): Connection closed

关键观察：gateway 本身没崩，横幅照样出，Ctrl+C 才停。只是 2 个 MCP 工具不可用。

根因（按可能性排）

#根因证据概率
1mmx 失败 = Termux 上没装 Node.jsmcp.json 里 command: node 是裸命令，Termux 默认没 Node.js；mmx-mcp-server.cjs 第一行 #!/usr/bin/env node 必须 Node 跑~85%
2plur 失败 = plur-mcp 二进制缺失 / 缺 chmod +x / 架构不对命令是绝对路径说明 hermes 没在 PATH 找；Termux 是 arm64，binary 必须 arm64 版~80%（不互斥）
3anyio TaskGroup 包装导致 “unhandled errors in a TaskGroup (1 sub-exception)” 这种 misleading 信息mcp_tool.py 用 popen 启子进程，子进程立即退出 → “Connection closed”（真实子错误）因 1+2 的症状

修复步骤（在 Termux 上敲）

# 步骤 0: 备份
cp ~/.hermes/hermes-agent/mcp.json ~/.hermes/hermes-agent/mcp.json.bak.20260602
 
# 步骤 1: 装 Node.js (修 mmx)
pkg update && pkg upgrade -y
pkg install -y nodejs-lts
node --version   # 应输出 v20.x 或 v22.x
 
# 步骤 2: 检查 mmx-mcp-server.cjs 是否存在
ls -la ~/.hermes/hermes-agent/bin/mmx-mcp-server.cjs
# 不存在 → 从 PC 拷：
#   PC: C:\Users\IDA\.hermes\hermes-agent\bin\mmx-mcp-server.cjs
#   Termux: /data/data/com.termux/files/home/.hermes/hermes-agent/bin/
 
# 步骤 3: 检查 plur-mcp
ls -la ~/bin/plur-mcp
# 不存在 → 重新装 plur
# 存在但不可执行 → chmod +x ~/bin/plur-mcp
# 架构错 → 装 arm64 版（Termux 是 arm64）
 
# 步骤 4: 验证（Ctrl+C 停掉 gateway，再跑）
hermes gateway

成功标志

  • 没有 "Failed to connect to MCP server 'mmx'" 这行
  • 没有 "Failed to connect to MCP server 'plur'" 这行
  • 能跑 mcp__plur__xxx / mcp__mmx__xxx 工具

备份保护

  • mcp.json.bak.20260602 在 ~/.hermes/hermes-agent/ 里随时可恢复
  • 不改 PC 端的 mcp.json（PC 的 Node.js 在 PATH 里本来就 OK）

📚 调试经验沉淀

“Connection closed” 是什么？

  • mcp_tool.py 用 popen 启子进程 + anyio TaskGroup 包 stdin/stdout pipe
  • 子进程启动后立即退出（binary 找不到 / shebang 找不到解释器 / 权限不够）→ pipe 断了 → “Connection closed”
  • 不是 hermes-agent 的 bug，是真实子进程错误的二次包装

Termux 上的常见 binary 启动失败模式

  1. Node.js 缺失（默认没装）→ 装 nodejs-lts
  2. 架构不匹配（Termux 是 arm64，有些 binary 只有 x86_64）→ 装 arm64 版
  3. 缺可执行权限（cp/mv 过来常丢 +x）→ chmod +x ~/bin/<binary>
  4. PATH 不包含（hermes 用绝对路径启动 → 不需要管 PATH，但 binary 自己内部可能调别的命令）
  5. 依赖 .so 缺失（ldd ~/bin/plur-mcp 看 missing libraries）

验证 vs 自信地说”应该可以了”

  • 按 user profile “质量优先速度第二”
  • 不在没看到 “node: command not found” 这种字眼前就说”装个 node 就行”
  • 实际跑 which node / node --version / ls -la ~/bin/plur-mcp 拿证据
  • 调试完成用 hermes gateway 重跑，实际看到没有 WARNING 才行
  • hermes-agent — PC 端 Hermes（多 agent 协调中的副手/原型）
  • decision-log — 决策日志（含 2026-06-02 vault-keeper 砍掉 + vault 迁 H 盘）
  • workflow — Multi-Agent Coordination 部分（Hermes1 Termux = 主控）
  • 源码参考：C:\Users\IDA\.hermes\hermes-agent\mcp.json + C:\Users\IDA\.hermes\hermes-agent\bin\mmx-mcp-server.cjs

关系图谱