HermesClaw: Run Hermes Agent, OpenClaw, and OpenCode on One WeChat Account

curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh | HERMESCLAW_YES=1 bash
# or, when running the script directly:
bash install.sh -y

Run: curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh | bash

Then read README.md and install.sh from the installed HermesClaw directory.
Detect whether Hermes Agent, OpenClaw, their WeChat gateways, python3, pip3,
and systemd are present. At least one gateway must be configured. Extract
the iLink token from the first available gateway account file. Patch
openclaw-weixin baseUrl to http://127.0.0.1:19999 and Hermes WEIXIN_BASE_URL
to http://127.0.0.1:19998. Install dependencies and systemd service.

Also detect OpenCode CLI: run `command -v opencode` or check
~/.npm-global/bin/opencode. If not found, suggest installing with:
  npm install -g opencode-ai
Set OPENCODE_CMD in .env to the detected path (or empty if not found).
OPENCODE_MODEL defaults to opencode/minimax-m2.5-free (free, no API key needed).

If Hermes Agent WeChat gateway is detected, the installer will offer to patch
weixin.py to disable newline-based message splitting (recommended). Accept
this patch so long replies are sent as single messages instead of being split
by paragraphs. The fix script is at fix_hermes_splitting.sh.

Restart gateways. Verify /whoami works in WeChat.

npm install -g opencode-ai

Stop and disable the hermesclaw systemd service. Restore openclaw-weixin
account .bak files. Remove WEIXIN_BASE_URL override from ~/.hermes/.env
(or restore .bak). Optionally remove ~/hermesclaw directory.

sudo systemctl stop hermesclaw
sudo systemctl disable hermesclaw
sudo rm -f /etc/systemd/system/hermesclaw.service
sudo systemctl daemon-reload

# Restore openclaw-weixin configs:
find "$HOME" -maxdepth 5 -name "*.json.bak" -path "*/openclaw-weixin/accounts/*" \
  -exec sh -c 'for f; do cp "$f" "${f%.bak}"; done' sh {} +

# Restore Hermes .env:
[ -f "$HOME/.hermes/.env.bak" ] && cp "$HOME/.hermes/.env.bak" "$HOME/.hermes/.env"

rm -rf "$HOME/hermesclaw"

How It Works

Architecture

HermesClaw acts as the sole iLink poller and token owner. It runs two local proxy servers (for Hermes and OpenClaw) plus a direct ACP bridge (for OpenCode). Each gateway believes it is talking to the real iLink API.

The architecture diagram from the sources shows:

                    ┌────────── iLink API ──────────┐
                    │  ilinkai.weixin.qq.com        │
                    └──────────┬────────────────────┘
                               │
                      (sole poller / token owner)
                               │
                    ┌──────────▼────────────────────┐
                    │     HermesClaw v3              │
                    │  routes by /hermes /openclaw   │
                    │          /opencode /three      │
                    │  queues raw iLink messages     │
                    ├────────┬──────────┬────────────┤
                    │        │          │
              Proxy A      Proxy B    ACP Bridge
              (:19999)     (:19998)   (subprocess)
              openclaw     hermes     opencode acp
                    │        │          │
                    ▼        ▼          ▼
              ┌──────────┐ ┌──────────┐ ┌──────────┐
              │ openclaw │ │ hermes   │ │ opencode │
              │ gateway  │ │ gateway  │ │ process  │
              └────┬─────┘ └────┬─────┘ └────┬─────┘
                   │            │             │
              sendmessage  sendmessage   send_text_ilink
                   └─────┬──────┘            │
                         │ (proxy forwards)  │
                         └──────────────────►┘
                                to iLink

Data Flow

1. HermesClaw polls iLink API at ilinkai.weixin.qq.com as the sole poller
2. Incoming messages are queued and routed based on the active command mode
3. For Hermes and OpenClaw, messages are forwarded to their respective local proxy servers (ports 19998 and 19999)
4. For OpenCode, messages go through the ACP bridge which implements JSON-RPC 2.0 over NDJSON for the opencode acp subprocess
5. Each gateway processes the raw iLink message natively (media decryption, AI interaction, markdown formatting)
6. Outgoing messages are sent back through the proxy to iLink

Media Handling

HermesClaw forwards raw iLink protocol messages to each gateway:

• Text: forwarded as-is
• Voice: iLink includes a transcription; HermesClaw forwards the transcription text
• Images, video, files: the raw iLink message (with CDN URLs and AES keys) is forwarded; each gateway downloads and decrypts natively

HermesClaw does not perform AES decryption, CDN downloads, or media re-encoding. Those tasks are handled by each gateway.

OpenCode ACP Bridge

In v0.3.0, new OpenCodeBridge and ACPSession classes were added. They implement JSON-RPC 2.0 over NDJSON for the opencode acp subprocess. Per-user sessions with automatic reconnect are supported. If OpenCode exits mid-session, pending prompts unblock immediately with an error instead of hanging for the full 120-second timeout. OpenCode mode also sends and keeps alive the WeChat typing indicator while the ACP agent is working.

Requirements and Limitations

Prerequisites

• At least one of: OpenClaw + clawbot (openclaw-weixin) installed and logged into WeChat, or Hermes Agent + WeChat gateway installed with hermes gateway configured
• Python 3 and pip3 (for Python dependencies)
• For OpenCode: Node.js and npm (to install opencode-ai)
• For systemd service: Linux with systemd (or macOS with launchd as of v0.4.0)

Supported Platforms

• Linux (with systemd)
• macOS (Darwin) as of v0.4.0, using launchd

Known Gaps and Limitations

• HermesClaw is a community bridge. It is not affiliated with NousResearch or OpenClaw.
• HermesClaw does not process media, call agent APIs, or touch agent memory. It only queues and forwards raw iLink protocol messages.
• If the opencode binary is not found, /opencode and /three commands show a helpful install hint instead of crashing (v0.3.0+).
• The installer patches Hermes Agent's weixin.py to disable newline-based message splitting. This is recommended but optional. Existing users can run bash fix_hermes_splitting.sh manually.
• OpenCode permission prompts are handled automatically with OPENCODE_PERMISSION_STRATEGY=allow_always to prevent WeChat replies from hanging on non-interactive tool approvals.

Troubleshooting

iLink 403 Errors

Problem: When running both Hermes Agent and OpenClaw without HermesClaw, one gateway gets 403 errors and drops messages.

Fix: Install HermesClaw. It becomes the sole iLink poller and routes messages to local proxies, preventing the token conflict.

Hermes "Response formatting failed"

Problem: Hermes returns a "Response formatting failed" error.

Fix (v0.2.0): The proxy servers now use ThreadingHTTPServer instead of single-threaded HTTPServer. This was fixed in the v0.2.0 rewrite.

OpenClaw ENOENT on Media Files

Problem: OpenClaw fails with ENOENT errors when trying to access media files.

Fix (v0.2.0): The installer now creates a symlink for the media path mismatch.

Hermes Message Splitting

Problem: Long replies from Hermes are split by paragraphs instead of being sent as single messages.

Fix (v0.2.1): The installer offers to patch Hermes Agent's weixin.py to disable newline-based message splitting. Accept this patch during installation (recommended, default Yes). Existing users can run bash fix_hermes_splitting.sh manually.

macOS Install Failure: mapfile: command not found

Problem: macOS ships with bash 3.2 which lacks the mapfile builtin (added in bash 4).

Fix (v0.3.6): All 3 occurrences of mapfile were replaced with portable while IFS= read -r loops, making the installer work on macOS out of the box.

curl | bash Silent Abort

Problem: With set -euo pipefail, bare read calls returned non-zero on EOF when stdin was a pipe, causing the installer to exit before any ${REPLY:-Y} default was evaluated.

Fix (v0.3.6): The installer now detects a non-tty stdin and redirects interactive prompts to /dev/tty so users can still answer them. If /dev/tty is also unavailable (CI/Docker), it falls back to auto-yes. All three prompt calls also have || VAR="" guards as defence-in-depth.

BrokenPipeError

Problem: BrokenPipeError occurs during proxy operation.

Fix (v0.2.0): BrokenPipeError is now caught and logged as DEBUG, preventing crashes.

OpenCode Dead Subprocess

Problem: OpenCode exits mid-session, causing prompts to hang for the full 120-second timeout.

Fix (v0.3.0): Dead subprocess recovery was implemented. If OpenCode exits mid-session, pending prompts unblock immediately with an error instead of hanging.

OpenCode Permission Prompts Hanging

Problem: OpenCode permission prompts cause WeChat replies to hang on non-interactive tool approvals.

Fix (v0.3.0): OpenCode permission prompts are handled automatically with OPENCODE_PERMISSION_STRATEGY=allow_always. The OpenCode global config (~/.config/opencode/opencode.json) is also set to "permission": "allow" by the installer so tool calls are approved at the OpenCode level without round-tripping through ACP.