aradotso/weclaw-wechat-ai-bridge

WeClaw — WeChat AI Agent Bridge

Skill by ara.so — Daily 2026 Skills collection.

WeClaw connects WeChat to AI agents (Claude, Codex, Gemini, Kimi, OpenClaw, etc.) via a Go-based bridge. It handles QR-code login, message routing, media conversion, and agent lifecycle. Supports three agent modes: ACP (JSON-RPC subprocess, fastest), CLI (new process per message), and HTTP (OpenAI-compatible REST).

---

Installation

# One-line installer
curl -sSL https://raw.githubusercontent.com/fastclaw-ai/weclaw/main/install.sh | sh

# Via Go toolchain
go install github.com/fastclaw-ai/weclaw@latest

# Via Docker
docker run -it -v ~/.weclaw:/root/.weclaw ghcr.io/fastclaw-ai/weclaw start

---

First-Run Flow

weclaw start        # Shows QR code → scan with WeChat → auto-detects agents → saves config
weclaw login        # Add/re-authenticate a WeChat account
weclaw status       # Show running state and active agent
weclaw stop         # Stop the background daemon
weclaw start -f     # Foreground mode (debug/verbose)

Logs: ~/.weclaw/weclaw.log
Config: ~/.weclaw/config.json

---

Configuration

{
  "default_agent": "claude",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "/usr/local/bin/claude-agent-acp",
      "model": "sonnet"
    },
    "codex": {
      "type": "acp",
      "command": "/usr/local/bin/codex-acp"
    },
    "claude-cli": {
      "type": "cli",
      "command": "/usr/local/bin/claude",
      "args": ["--dangerously-skip-permissions"]
    },
    "codex-cli": {
      "type": "cli",
      "command": "/usr/local/bin/codex",
      "args": ["--skip-git-repo-check"]
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "$OPENCLAW_GATEWAY_TOKEN",
      "model": "openclaw:main"
    }
  }
}

Environment Variables

| Variable | Purpose | |----------|---------| | WECLAW_DEFAULT_AGENT | Override default agent at runtime | | WECLAW_API_ADDR | Change local HTTP API address (default 127.0.0.1:18011) | | OPENCLAW_GATEWAY_URL | HTTP agent endpoint | | OPENCLAW_GATEWAY_TOKEN | HTTP agent API token |

---

Agent Modes

| Mode | Process model | Best for | |------|--------------|----------| | acp | Long-running subprocess, JSON-RPC over stdio | Claude, Codex, Kimi, Gemini — fastest, session reuse | | cli | New process per message, --resume for sessions | claude -p, codex exec | | http | OpenAI-compatible /v1/chat/completions | Any REST-accessible model |

Auto-detection prefers acp over cli when both binaries exist.

---

Chat Commands (send as WeChat messages)

| Command | Action | |---------|--------| | hello | Send to default agent | | /codex write a sort function | Route to named agent | | /cc explain this code | Use alias (/cc → claude) | | /claude | Switch default agent to Claude (persisted) | | /status | Show active agent info | | /help | List available commands |

Built-in Aliases

| Alias | Agent | |-------|-------| | /cc | claude | | /cx | codex | | /cs | cursor | | /km | kimi | | /gm | gemini | | /ocd | opencode | | /oc | openclaw |

---

Proactive Messaging — CLI

# Send plain text
weclaw send --to "[email protected]" --text "Hello from WeClaw"

# Send an image
weclaw send --to "[email protected]" --media "https://example.com/photo.png"

# Send text + media together
weclaw send --to "[email protected]" \
  --text "Check this out" \
  --media "https://example.com/photo.png"

# Send a file
weclaw send --to "[email protected]" --media "https://example.com/report.pdf"

---

Proactive Messaging — HTTP API

The local API listens on 127.0.0.1:18011 while weclaw start is running.

# Send text
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "text": "Hello from WeClaw"}'

# Send image
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "media_url": "https://example.com/photo.png"}'

# Send text + media
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "text": "See this", "media_url": "https://example.com/photo.png"}'

Supported media types: png, jpg, gif, webp, mp4, mov, pdf, doc, zip.

Change listen address:

WECLAW_API_ADDR=0.0.0.0:18011 weclaw start

---

Go Integration Example

Call the WeClaw HTTP API from a Go service to send notifications:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type SendRequest struct {
	To       string `json:"to"`
	Text     string `json:"text,omitempty"`
	MediaURL string `json:"media_url,omitempty"`
}

type SendResponse struct {
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

func sendToWeChat(to, text, mediaURL string) error {
	apiAddr := os.Getenv("WECLAW_API_ADDR")
	if apiAddr == "" {
		apiAddr = "127.0.0.1:18011"
	}

	req := SendRequest{To: to, Text: text, MediaURL: mediaURL}
	body, err := json.Marshal(req)
	if err != nil {
		return fmt.Errorf("marshal: %w", err)
	}

	resp, err := http.Post(
		fmt.Sprintf("http://%s/api/send", apiAddr),
		"application/json",
		bytes.NewReader(body),
	)
	if err != nil {
		return fmt.Errorf("post: %w", err)
	}
	defer resp.Body.Close()

	var result SendResponse
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return fmt.Errorf("decode: %w", err)
	}
	if !result.OK {
		return fmt.Errorf("weclaw error: %s", result.Message)
	}
	return nil
}

func main() {
	recipient := os.Getenv("WECHAT_RECIPIENT_ID") // e.g. "[email protected]"
	if err := sendToWeChat(recipient, "Build succeeded ✅", ""); err != nil {
		fmt.Fprintf(os.Stderr, "failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Message sent.")
}

---

Docker Setup

# Build image
docker build -t weclaw .

# Step 1: Interactive login (scan QR code)
docker run -it -v ~/.weclaw:/root/.weclaw weclaw login

# Step 2: Run daemon with HTTP agent
docker run -d --name weclaw \
  -v ~/.weclaw:/root/.weclaw \
  -e OPENCLAW_GATEWAY_URL=https://api.example.com \
  -e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN" \
  weclaw

# Expose the local API externally (bind carefully — no auth by default)
docker run -d --name weclaw \
  -v ~/.weclaw:/root/.weclaw \
  -e WECLAW_API_ADDR=0.0.0.0:18011 \
  -p 18011:18011 \
  -e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN" \
  weclaw

docker logs -f weclaw

ACP/CLI agents require the agent binary inside the container. Mount the binary or build a custom image. HTTP agents work out of the box.

---

System Service (Auto-start)

macOS (launchd):

cp service/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist

Linux (systemd):

sudo cp service/weclaw.service /etc/systemd/system/
sudo systemctl enable --now weclaw
journalctl -u weclaw -f

---

Development

make dev                        # Hot reload
go build -o weclaw .            # Build binary
./weclaw start -f               # Run in foreground

Releasing:

git tag v0.1.0
git push origin v0.1.0
# GitHub Actions builds darwin/linux × amd64/arm64 and uploads release artifacts

---

Common Patterns

Pattern: Per-user agent routing

Send /claude or /codex as a WeChat message to switch the default agent. The choice persists in ~/.weclaw/config.json across restarts.

Pattern: CI/CD build notifications

After a build, call weclaw send or POST to the HTTP API to push results to a WeChat contact or group.

Pattern: Media from agent

If an agent reply contains ![alt](https://...), WeClaw auto-downloads, AES-128-ECB encrypts, uploads to WeChat CDN, and delivers as a native image message — no extra config needed.

Pattern: Disable permission prompts for headless use

{
  "claude": { "type": "cli", "command": "/usr/local/bin/claude",
               "args": ["--dangerously-skip-permissions"] },
  "codex":  { "type": "cli", "command": "/usr/local/bin/codex",
               "args": ["--skip-git-repo-check"] }
}

ACP agents handle permissions automatically and do not need these flags.

---

Troubleshooting

| Symptom | Fix | |---------|-----| | QR code not appearing | Run weclaw login explicitly; ensure terminal supports UTF-8 | | Agent not auto-detected | Check binary is on $PATH; run weclaw status | | connection refused on HTTP API | Confirm weclaw start is running; check WECLAW_API_ADDR | | Agent permission prompts block responses | Add --dangerously-skip-permissions (Claude) or --skip-git-repo-check (Codex) to args; or use ACP mode | | Docker — no agent binary | Mount binary: -v /usr/local/bin/claude:/usr/local/bin/claude; or use HTTP mode | | Markdown not rendering | WeClaw strips markdown automatically for WeChat plain-text display; this is expected | | Logs | tail -f ~/.weclaw/weclaw.log or docker logs -f weclaw |