English
中文English日本語

Hermes Agent Text Message Access

By /

This article provides Hermes Agent access scheme. The goal is to continue to be responsible for WeChat multi-accounts, approvals, messaging and auditing, and Hermes Agent will only process text messages as a backend agent at runtime.

Access principles

  • Hub does not hand over WeChat accounts to Hermes for direct management.
  • Hub retains the capabilities of WeChat login, session, approval, suspension, cleanup and message warehousing.
  • Hermes receives text input and returns text results through the OpenAI-compatible HTTP API.
  • Hub determines whether to directly reply to WeChat based on account policies or only generate drafts for manual review.

Current implementation scope

The first version only handles text messages from WeChat users:

  • process only MessageType.USER the news.
  • Only process messages from which text content can be extracted.
  • Only approved accounts can trigger Hermes.
  • Hermes call record written to MongoDB agent_runs Gather.
  • requiresHumanReview=false The strategy will automatically send Hermes text results back to WeChat.
  • requiresHumanReview=true The policy of only saves Hermes output and does not automatically send it.

Not processed temporarily:

  • Pictures, voices, files, videos
  • Multiple rounds of context concatenation
  • Backstage manual approval and sending
  • Agent Runs Management Page
  • Front-end display of the Hermes tool invocation process

Hermes side configuration

Hermes requires API Server enabled. Edit the Hermes environment file:

~/.hermes/.env

Minimum configuration:

API_SERVER_ENABLED=true
API_SERVER_KEY=YOUR_API_KEY

Optional configuration:

API_SERVER_PORT=8642
API_SERVER_HOST=127.0.0.1
API_SERVER_MODEL_NAME=hermes-agent

Launch the Hermes Gateway:

hermes gateway

Under normal circumstances, you will see similar output:

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

Docker version of Hermes link method

If Hermes is a Docker version, it is recommended to first verify that the Hermes container is running in gateway mode and set the 8642 Ports are mapped to host machines.

If you use the information from Hermes official warehouse docker-compose.yml, it uses by default:

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

On Ubuntu/Linux, this means that the Hermes container uses the host network directly. Hub API container is not available 127.0.0.1 Visit it because 127.0.0.1 Point to the hub container itself within the hub container. Recommend to let hub pass host.docker.internal Access the host machine and check in the hub's docker-compose.yml Add API services in:

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

This project is already in api Add this configuration to the service.

Recommended configurations when using Hermes official Compose

Create or modify in the Hermes Project Catalog .env：

HERMES_UID=1000
HERMES_GID=1000
API_SERVER_KEY=YOUR_API_KEY

HERMES_UID and HERMES_GID It is recommended to fill in the current host user ID:

id -u
id -g

Then revise the Hermes official docker-compose.yml in gateway.environment, open the 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}

Description:

  • API_SERVER_ENABLED=true: Enable OpenAI-compatible API Server.
  • API_SERVER_HOST=0.0.0.0: Let the API listen not only on the container/host's own 127.0.0.1, otherwise the hub container cannot be accessed.
  • API_SERVER_KEY: Bearer token, must be used with hub HERMES_API_KEY Agreed.

Launch Hermes:

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

View the log:

docker logs -f hermes

Normally, you will see API Server listening 8642 The journal.

Initialize the Hermes Data Catalog for the first time:

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

Launch the Hermes Gateway:

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

If you use Docker Compose, you can refer to:

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

When Hub and Hermes are running in two containers, the easiest way to link is:

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

here host.docker.internal Represents "accessing the host machine from the hub API container". Because Hermes has passed -p 8642:8642 Exposed to the host, so the hub can access Hermes through the host address.

If you merge Hermes services directly into wechat-clawbot-hub/docker-compose.yml, you can allow two services to access each other on the same Compose network. at this time HERMES_API_BASE_URL Can be changed to:

HERMES_API_BASE_URL=http://hermes:8642/v1

The corresponding service name must be called 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

Choose one of two methods:

  • Hermes runs Docker alone: using hub http://host.docker.internal:8642/v1。
  • Hermes merged into hub's Compose network: hub usage http://hermes:8642/v1。

Hub side configuration

If the Hub API runs in a Docker container,.env Use:

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

If the Hub API runs directly on the host machine, use:

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

Key points:

  • HERMES_API_KEY Must be consistent with Hermes ' API_SERVER_KEY Agreed.
  • Used when Docker container accesses host services host.docker.internal。
  • Used when running API directly on the machine 127.0.0.1。
  • It is recommended to turn off automatic development replies after enabling Hermes:WECHAT_AUTO_REPLY_ENABLED=false。

Verify the Hermes API

PowerShell testing:

$body = @{
  model = "hermes-agent"
  messages = @(
    @{
      role = "user"
      content = "Hello, please give a brief reply. "
    }
  )
} | 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

The ability to return assistant content means that the Hermes API itself is available.

Verify Hub to Hermes

  1. Launch the Hermes Gateway.
  2. start or restart wechat-clawbot-hub。
  3. Create or select a Bot in the management backend.
  4. Perform scanning code login.
  5. implementation Approve。
  6. implementation Start Polling。
  7. Send a text message to the WeChat Bot.
  8. Check whether WeChat receives a reply from Hermes.
  9. at MongoDB agent_runs Collects to view call records.

data state

agent_runs Current record fields include:

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

Common status:

  • running: Record has been created and Hermes is being called.
  • retry_pending: Hermes is temporarily unavailable. A temporary reminder has been sent to WeChat users, waiting for the next round of retries.
  • retrying: The background retry loop is recalling Hermes.
  • sent: Hermes has returned, and the results have been sent back to WeChat.
  • awaiting_review: Hermes has returned, but the policy requires manual review and has not been sent yet.
  • error: Account unavailable, delivery failed or unrecoverable error.

When Hermes does not start or the API link fails, Hub will reply first:

Message received. Currently, the Agent cannot connect temporarily. I will queue this message first, and continue processing and reply after the connection is restored.

Then the API container presses HERMES_RETRY_INTERVAL_MS periodic scan retry_pending Record. After Hermes recovers, the Hub will continue to call the Agent; the normal policy will automatically send the final result back to WeChat,manual-review Strategy still enters awaiting_review。

troubleshooting

If WeChat does not receive a reply from Hermes, check first:

  1. Whether the Hermes gateway is running.
  2. HERMES_AGENT_ENABLED whether it is true。
  3. HERMES_API_BASE_URL Whether it can be accessed from the API container.
  4. HERMES_API_KEY whether API_SERVER_KEY Agreed.
  5. Does the Bot account have Approve and has been Start Polling。
  6. Whether the current policy is manual-review。If so, the result will only enter agent_runs, will not be sent automatically.
  7. agent_runs.status whether it is retry_pending、retrying or error, and error Field content.

Follow-up maintenance recommendations

  1. increase Agent Runs Management page.
  2. for awaiting_review Add approval sending interface.
  3. Save Hermes response.id, for multiple rounds of context access previous_response_id or conversation。
  4. Add the conversion of picture messages to Hermes picture input.
  5. Add audit logs and time-consuming statistics for Hermes calls.
Scroll to Top