Hermes Agent 文本消息接入

本文Hermes Agent 接入方案。目标是让继续负责微信多账号、审批、消息收发和审计，Hermes Agent 只作为后端智能体运行时处理文本消息。

接入原则

Hub 不把微信账号交给 Hermes 直接管理。
Hub 保留微信登录、session、审批、暂停、清理和消息入库能力。
Hermes 通过 OpenAI 兼容 HTTP API 接收文本输入并返回文本结果。
Hub 根据账号策略决定是否直接回微信，或者只生成待人工复核的草稿。

当前实现范围

第一版只处理微信用户文本消息：

仅处理 MessageType.USER 的消息。
仅处理能提取出文本内容的消息。
仅已批准账号可以触发 Hermes。
Hermes 调用记录写入 MongoDB agent_runs 集合。
requiresHumanReview=false 的策略会自动把 Hermes 文本结果发回微信。
requiresHumanReview=true 的策略只保存 Hermes 输出，不自动发送。

暂不处理：

图片、语音、文件、视频
多轮上下文串联
后台人工批准发送
Agent Runs 管理页
Hermes 工具调用过程的前端展示

Hermes 侧配置

Hermes 需要启用 API Server。编辑 Hermes 环境文件：

~/.hermes/.env

最小配置：

API_SERVER_ENABLED=true
API_SERVER_KEY=YOUR_API_KEY

可选配置：

API_SERVER_PORT=8642
API_SERVER_HOST=127.0.0.1
API_SERVER_MODEL_NAME=hermes-agent

启动 Hermes gateway：

hermes gateway

正常情况下会看到类似输出：

[API Server] API server listening on http://<HERMES_HOST>:<PORT>

Docker 版 Hermes 链接方式

如果 Hermes 是 Docker 版，推荐先确认 Hermes 容器以 gateway 模式运行，并把 8642 端口映射到宿主机。

如果使用 Hermes 官方仓库里的 docker-compose.yml，它默认使用：

network_mode: host
command: ["gateway", "run"]

在 Ubuntu/Linux 上，这表示 Hermes 容器直接使用宿主机网络。Hub API 容器不能用 127.0.0.1 访问它，因为 127.0.0.1 在 hub 容器内指向 hub 容器自己。推荐让 hub 通过 host.docker.internal 访问宿主机，并在 hub 的 docker-compose.yml 中为 API 服务加入：

extra_hosts:
  - "host.docker.internal:host-gateway"

本项目已经在 api 服务中加入这段配置。

使用 Hermes 官方 Compose 时的推荐配置

在 Hermes 项目目录创建或修改 .env：

HERMES_UID=1000
HERMES_GID=1000
API_SERVER_KEY=YOUR_API_KEY

HERMES_UID 和 HERMES_GID 建议填当前宿主机用户 ID：

id -u
id -g

然后修改 Hermes 官方 docker-compose.yml 中 gateway.environment，把 API Server 打开：

environment:
  - HERMES_UID=${HERMES_UID:-10000}
  - HERMES_GID=${HERMES_GID:-10000}
  - API_SERVER_ENABLED=true
  - API_SERVER_HOST=0.0.0.0
  - API_SERVER_KEY=${API_SERVER_KEY}

说明：

API_SERVER_ENABLED=true：启用 OpenAI 兼容 API Server。
API_SERVER_HOST=0.0.0.0：让 API 不只监听容器/宿主机自己的 127.0.0.1，否则 hub 容器访问不到。
API_SERVER_KEY：Bearer token，必须和 hub 的 HERMES_API_KEY 一致。

启动 Hermes：

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d

查看日志：

docker logs -f hermes

正常会看到 API Server 监听 8642 的日志。

首次初始化 Hermes 数据目录：

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

启动 Hermes gateway：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

如果使用 Docker Compose，可以参考：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes:/opt/data

Hub 和 Hermes 分别在两个容器中运行时，最简单的链接方式是：

HERMES_AGENT_ENABLED=true
HERMES_API_BASE_URL=http://host.docker.internal:8642/v1
HERMES_API_KEY=YOUR_API_KEY
HERMES_MODEL=hermes-agent
HERMES_TIMEOUT_MS=120000
WECHAT_AUTO_REPLY_ENABLED=false

这里的 host.docker.internal 表示“从 hub API 容器访问宿主机”。因为 Hermes 已经通过 -p 8642:8642 暴露到了宿主机，所以 hub 可以通过宿主机地址访问 Hermes。

如果你把 Hermes 服务直接合并进 wechat-clawbot-hub/docker-compose.yml，则可以让两个服务在同一个 Compose 网络里互相访问。这时 HERMES_API_BASE_URL 可以改成：

HERMES_API_BASE_URL=http://hermes:8642/v1

对应服务名必须叫 hermes：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "127.0.0.1:8642:8642"
    volumes:
      - ~/.hermes:/opt/data

两种方式选一种即可：

Hermes 单独 Docker 运行：hub 使用 http://host.docker.internal:8642/v1。
Hermes 合并进 hub 的 Compose 网络：hub 使用 http://hermes:8642/v1。

Hub 侧配置

如果 Hub API 运行在 Docker 容器中，.env 使用：

HERMES_AGENT_ENABLED=true
HERMES_API_BASE_URL=http://host.docker.internal:8642/v1
HERMES_API_KEY=change-me-local-dev
HERMES_MODEL=hermes-agent
HERMES_TIMEOUT_MS=120000
WECHAT_AUTO_REPLY_ENABLED=false

如果 Hub API 直接在宿主机运行，使用：

HERMES_AGENT_ENABLED=true
HERMES_API_BASE_URL=http://127.0.0.1:8642/v1
HERMES_API_KEY=change-me-local-dev
HERMES_MODEL=hermes-agent
HERMES_TIMEOUT_MS=120000
WECHAT_AUTO_REPLY_ENABLED=false

关键点：

HERMES_API_KEY 必须和 Hermes 的 API_SERVER_KEY 一致。
Docker 容器访问宿主机服务时使用 host.docker.internal。
本机直接运行 API 时使用 127.0.0.1。
建议启用 Hermes 后关闭开发自动回复：WECHAT_AUTO_REPLY_ENABLED=false。

验证 Hermes API

PowerShell 测试：

$body = @{
  model = "hermes-agent"
  messages = @(
    @{
      role = "user"
      content = "你好，简单回复一下。"
    }
  )
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "http://<HERMES_HOST>:<PORT>/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer change-me-local-dev" } `
  -ContentType "application/json" `
  -Body $body

能返回 assistant 内容，就说明 Hermes API 本身可用。

验证 Hub 到 Hermes

启动 Hermes gateway。
启动或重启 wechat-clawbot-hub。
在管理后台创建或选择一个 Bot。
执行扫码登录。
执行 Approve。
执行 Start Polling。
给该微信 Bot 发送文本消息。
查看微信是否收到 Hermes 回复。
在 MongoDB agent_runs 集合查看调用记录。

数据状态

agent_runs 当前记录字段包括：

id
accountId
userId
messageId
sessionId
contextToken
agent
policyId
policyMode
inputText
status
outputText
error
requiresHumanReview
outboundMessageId
queuedReplyMessageId
attemptCount
nextAttemptAt
createdAt
completedAt
rawResponse

常见状态：

running：已创建记录，正在调用 Hermes。
retry_pending：Hermes 暂时不可用，已向微信用户发送占位提示，等待下一轮重试。
retrying：后台重试循环正在重新调用 Hermes。
sent：Hermes 已返回，且结果已发回微信。
awaiting_review：Hermes 已返回，但策略要求人工复核，暂未发送。
error：账号不可用、发送失败或不可恢复错误。

Hermes 未启动或 API 链接失败时，Hub 会先回复：

信息收到了。目前 Agent 暂时连接不上，我会先把这条消息排队，等连接恢复后继续处理并回复。

随后 API 容器按 HERMES_RETRY_INTERVAL_MS 周期扫描 retry_pending 记录。Hermes 恢复后，Hub 会继续调用 Agent；普通策略会把最终结果自动回发微信，manual-review 策略仍进入 awaiting_review。

故障排查

如果微信没有收到 Hermes 回复，优先检查：

Hermes gateway 是否正在运行。
HERMES_AGENT_ENABLED 是否为 true。
HERMES_API_BASE_URL 是否能从 API 容器访问。
HERMES_API_KEY 是否与 API_SERVER_KEY 一致。
Bot 账号是否已 Approve 且已 Start Polling。
当前策略是否为 manual-review。如果是，结果只会进入 agent_runs，不会自动发送。
agent_runs.status 是否为 retry_pending、retrying 或 error，以及 error 字段内容。

后续维护建议

增加 Agent Runs 管理页。
为 awaiting_review 增加批准发送接口。
保存 Hermes response.id，为多轮上下文接入 previous_response_id 或 conversation。
增加图片消息到 Hermes 图片输入的转换。
为 Hermes 调用增加审计日志和耗时统计。