New from the same author: MuseInst — open-source personal agent infra on Cloudflare. Agent Mail, WeChat, Telegram, a cloud browser and long-term memory, without a cloud computer per user. HermesClaw keeps working as before. If MuseInst looks useful to you, a star there would mean a lot.
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
</p>
<p align="center">
<img src="docs/HermesClaw.jpeg" alt="HermesClaw — One WeChat bot. Two AI brains. /hermes, /openclaw, /both." style="max-width: 100%;" />
</p>
<p align="center">
<em>One iLink account. Three AI brains. Switch with <code>/hermes</code>, <code>/openclaw</code>, <code>/opencode</code>, <code>/both</code>, <code>/three</code>.</em><br/>
<em>一个 iLink 账号，三个 AI 大脑。<code>/hermes</code>、<code>/openclaw</code>、<code>/opencode</code>、<code>/both</code>、<code>/three</code> 一句话切换。</em>
</p>
Why HermesClaw
Both Hermes Agent and OpenClaw now support WeChat natively — but you can't run both on the same account. Each gateway exclusively locks the iLink connection. If you start both, one gets 403 errors and drops messages. OpenCode adds a third AI brain via its ACP subprocess protocol.
HermesClaw solves this by becoming the sole iLink poller, then running two local proxy servers (for Hermes and OpenClaw) plus a direct ACP bridge (for OpenCode). Each gateway believes it's talking to the real iLink API.
The new OpenCode support also lets you Vibe Code via WeChat voice messages — just speak and OpenCode handles it, backed by four free models including MiniMax M2.5 Free. You can also use it alongside the other two agents to complement each other — fixing their issues, tracing bugs, or inspecting the local environment.
Special thanks to the Hermes Agent team at Nous Research for recognizing and recommending HermesClaw in the Community section of their official GitHub README.
特别感谢 Nous Research 的 Hermes Agent 团队，在其 GitHub 官方 README 的 Community 区收录并推荐 HermesClaw。
HermesClaw is a thin Python proxy (~500 lines). It does not process media, call agent APIs, or touch agent memory. It just queues and forwards raw iLink protocol messages. Each gateway handles its own media decryption, markdown formatting, and AI interaction natively.
HermesClaw 只是一个轻量转发代理（~500 行），不处理媒体、不调 Agent API、不动记忆。每个 Gateway 原生处理自己的媒体解密和 AI 交互。
Prerequisites
Before installing HermesClaw, you need at least one of:
OpenClaw + clawbot (openclaw-weixin) — installed and logged into WeChat
For non-interactive / automated installs (skips all confirmation prompts):
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
The installer will:
Detect which gateways are installed and configured
Extract the iLink token from gateway account files
Patch openclaw-weixin baseUrl → http://127.0.0.1:19999 (proxy A)
Patch Hermes WEIXIN_BASE_URL → http://127.0.0.1:19998 (proxy B)
Detect OpenCode CLI (optional — enables /opencode and /three)
Install Python deps (requests, python-dotenv)
Create OpenClaw media symlink (workaround for media path mismatch)
Set up the hermesclaw systemd service
After install, restart your gateways and send /whoami in WeChat.
AI-assisted install
Drop this into any AI agent on the target machine:
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.
Commands
| Command | Action |
|---------|--------|
| /hermes | Route to Hermes only |
| /openclaw | Route to OpenClaw only |
| /opencode | Route to OpenCode only (via ACP bridge) |
| /both | Route to Hermes + OpenClaw (reply from both) |
| /three | Route to all three (reply from all) |
| /whoami | Show current route and status |
| anything else | Forward to the active agent(s) |
Default route is Hermes. In /both and /three modes, proxy replies are prefixed with [Hermes Agent] / [OpenClaw] / [OpenCode] for attribution.
OpenCode setup
OpenCode connects via its native ACP subprocess protocol — no proxy port needed. Install it first:
npm install -g opencode-ai
Then set OPENCODE_CMD in .env (the installer auto-detects it). Use /opencode or /three once OpenCode is installed.
Feature: Native macOS support — The install.sh script now supports macOS (Darwin) out-of-the-box by leveraging launchd instead of failing on the missing systemctl. It automatically creates, loads, and manages the background service via ~/Library/LaunchAgents/com.hermesclaw.plist (Thanks @unliftedq for the feature request).
v0.3.6
Fix: macOS install failure — mapfile: command not found — macOS ships with bash 3.2 which lacks the mapfile builtin (added in bash 4). All 3 occurrences replaced with portable while IFS= read -r loops, making the installer work on macOS out of the box.
Fix: curl | bash silent abort — 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. 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.
5 new regression tests — tests/test_install_sh.py covers mapfile absence, bash syntax, read guards, tty detection, and non-interactive stdin.
OpenCode ACP bridge — New OpenCodeBridge + ACPSession classes implement JSON-RPC 2.0 over NDJSON for opencode acp subprocess. Per-user sessions with automatic reconnect.
/opencode command — Route messages to OpenCode only.
/three command — Route messages to all three agents simultaneously (Hermes + OpenClaw + OpenCode).
"Not installed" detection — If opencode binary is not found, /opencode and /three show a helpful install hint instead of crashing.
Tagging in THREE mode — Proxy tags Hermes/OpenClaw replies; OpenCode worker tags its own replies with [OpenCode].
Dead subprocess recovery — If OpenCode exits mid-session, pending prompts unblock immediately with an error instead of hanging for the full 120 s timeout.
Headless ACP permissions — OpenCode permission prompts are handled automatically with OPENCODE_PERMISSION_STRATEGY=allow_always, preventing WeChat replies from hanging on non-interactive tool approvals. 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.
OpenCode typing indicator — OpenCode mode now sends and keeps alive the WeChat typing indicator while the ACP agent is working.
Non-interactive installer — bash install.sh -y (or HERMESCLAW_YES=1 bash install.sh) skips all confirmation prompts; OpenCode appears in the discovery summary.
Installer git pull — Re-running install.sh on an existing install now pulls the latest code before continuing.
117 tests — Expanded route matrix covers every command route across text, voice, image, video, and file payloads, plus ACP permissions, OpenCode media prompts, dead-subprocess recovery, and THREE mode.
v0.2.1 (2026-04-12)
Fix: Hermes message splitting — The installer now offers to patch Hermes Agent's weixin.py to disable newline-based message splitting during installation (recommended, default Yes). This ensures long replies are sent as single messages instead of being split by paragraphs. Existing users can run bash fix_hermes_splitting.sh manually.