Installation Procedures

Quick Install

1. Ensure at least one of OpenClaw+clawbot or Hermes Agent+WeChat gateway is installed and logged into WeChat.
2. Run the following command:

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

3. For non-interactive install, use one of:

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

   Or:

   bash install.sh -y
   

4. The installer performs the following actions:
   • Detects installed gateways.
   • Extracts iLink token from gateway account files.
   • Patches openclaw-weixin baseUrl to http://127.0.0.1:19999.
   • Patches Hermes WEIXIN_BASE_URL to http://127.0.0.1:19998.
   • Detects OpenCode CLI (optional).
   • Installs Python dependencies (requests, python-dotenv).
   • Creates OpenClaw media symlink.
   • Sets up hermesclaw systemd service.
5. After install, restart your gateways and send /whoami in WeChat to verify.

AI-Assisted Install

1. On the target machine, run:

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

2. Read README.md and install.sh from the installed HermesClaw directory.
3. Detect whether Hermes Agent, OpenClaw, their WeChat gateways, python3, pip3, and systemd are present. At least one gateway must be configured.
4. Extract the iLink token from the first available gateway account file.
5. Patch openclaw-weixin baseUrl to http://127.0.0.1:19999 and Hermes WEIXIN_BASE_URL to http://127.0.0.1:19998.
6. Install dependencies and systemd service.
7. Detect OpenCode CLI: run command -v opencode or check ~/.npm-global/bin/opencode. If not found, suggest installing with:

   npm install -g opencode-ai
   

8. 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).
9. If Hermes Agent WeChat gateway is detected, offer to patch weixin.py to disable newline-based message splitting (recommended). Accept this patch so long replies are sent as single messages. The fix script is at fix_hermes_splitting.sh.
10. Restart gateways. Verify /whoami works in WeChat.

OpenCode Setup

1. Install OpenCode CLI:

   npm install -g opencode-ai
   

2. Set OPENCODE_CMD in .env (installer auto-detects it).
3. Use /opencode or /three commands once OpenCode is installed.

Uninstall (AI-Assisted)

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

Uninstall (Manual)

1. Stop and disable the service:

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

2. Restore OpenClaw configs:

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

3. Restore Hermes .env:

   [ -f "$HOME/.hermes/.env.bak" ] && cp "$HOME/.hermes/.env.bak" "$HOME/.hermes/.env"
   

4. Remove HermesClaw directory:

   rm -rf "$HOME/hermesclaw"
   

Configuration Parameters

The following parameters can be set in the .env file or as environment variables:

• HERMESCLAW_YES: Environment variable to skip all confirmation prompts during install. Optional, for non-interactive installs.
• -y flag: Command-line flag for install.sh to skip all confirmation prompts. Optional, for non-interactive installs.
• OPENCODE_CMD: Path to the opencode CLI binary, set in .env file. Optional, enables /opencode and /three commands.
• OPENCODE_MODEL: Model to use for OpenCode; defaults to opencode/minimax-m2.5-free. Optional, defaults to free model.
• OPENCODE_PERMISSION_STRATEGY: Strategy for handling OpenCode permission prompts; set to allow_always for headless operation. Optional, defaults to allow_always in installer.

Constraints and Caveats

• HermesClaw is a thin Python proxy (~500 lines); it does not process media, call agent APIs, or touch agent memory.
• Each gateway handles its own media decryption, markdown formatting, and AI interaction natively.
• At least one gateway (OpenClaw+clawbot or Hermes Agent+WeChat gateway) must be installed and logged into WeChat before installing HermesClaw.
• Default route is Hermes.
• In /both and /three modes, proxy replies are prefixed with [Hermes Agent], [OpenClaw], [OpenCode] for attribution.
• OpenCode connects via its native ACP subprocess protocol; no proxy port needed.
• HermesClaw forwards raw iLink protocol messages; it does not do AES decryption, CDN downloads, or media re-encoding.
• macOS support uses launchd instead of systemd; install.sh creates ~/Library/LaunchAgents/com.hermesclaw.plist.
• macOS ships with bash 3.2 which lacks mapfile; installer uses portable while IFS= read -r loops.
• With set -euo pipefail, bare read calls can return non-zero on EOF when stdin is a pipe; installer detects non-tty stdin and redirects prompts to /dev/tty, falling back to auto-yes if /dev/tty unavailable.
• Re-running install.sh on an existing install pulls the latest code before continuing.
• If opencode binary is not found, /opencode and /three show a helpful install hint instead of crashing.
• OpenCode permission prompts are handled automatically with OPENCODE_PERMISSION_STRATEGY=allow_always to prevent hanging.
• HermesClaw is not affiliated with NousResearch or OpenClaw; it is a community bridge.

Failure Modes

• iLink 403 errors if both gateways try to poll simultaneously without HermesClaw.
• Token conflict causing dropped messages if multiple gateways connect directly to iLink.
• OpenCode subprocess exiting mid-session causing pending prompts to hang; HermesClaw unblocks with error instead of waiting 120s timeout.
• Hermes Agent message splitting (long replies split by paragraphs) if weixin.py patch is not applied.
• OpenClaw ENOENT on media files if symlink is not created (installer creates it).
• macOS install failure due to missing mapfile builtin (fixed in v0.3.6).
• curl | bash silent abort due to bare read calls with set -euo pipefail (fixed in v0.3.6).
• BrokenPipeError caught and logged as DEBUG (improved error handling).

Examples

Switching Agents

Send the following commands in WeChat to change routing:

• /hermes - Route to Hermes only.
• /openclaw - Route to OpenClaw only.
• /opencode - Route to OpenCode only.
• /both - Route to Hermes and OpenClaw.
• /three - Route to all three agents.

Voice-Driven Vibe Coding

Speak a voice message in WeChat. HermesClaw forwards the transcription to OpenCode for processing, enabling voice-driven Vibe Coding.

Before and After

Without HermesClaw, Hermes and OpenClaw each work individually but cannot run on the same account due to token conflict and 403 errors. With HermesClaw, all three agents work simultaneously on one account, and OpenCode gains WeChat support via the ACP bridge.

Additional Notes

The year 2026 is referenced in the project's version history as a milestone for future development. The command -v opencode command is used by the installer to detect the OpenCode CLI binary during setup.