WeClaw

中文文档

WeChat AI Agent Bridge — connect WeChat to AI agents (Claude, Codex, Gemini, Kimi, etc.).

This project is inspired by @tencent-weixin/openclaw-weixin. For personal learning only, not for commercial use.

Quick Start

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

# Start (first run will prompt QR code login)
weclaw start

That's it. On first start, WeClaw will:

1. Show a QR code — scan with WeChat to login
2. Auto-detect installed AI agents (Claude, Codex, Gemini, etc.)
3. Save config to ~/.weclaw/config.json
4. Start receiving and replying to WeChat messages

Use weclaw login to add additional WeChat accounts.

Other install methods

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

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

How It Works

Agent modes:

Mode	How it works	Examples
ACP	Long-running subprocess, JSON-RPC over stdio. Fastest — reuses process and sessions.	Claude, Codex, Kimi, Gemini, Cursor, OpenCode, OpenClaw
CLI	Spawns a new process per message. Supports session resume via --resume.	Claude (claude -p), Codex (codex exec)
HTTP	OpenAI-compatible chat completions API.	OpenClaw (HTTP fallback)

Auto-detection picks ACP over CLI when both are available.

Chat Commands

Send these as WeChat messages:

Command	Description
hello	Send to default agent
/codex write a function	Send to a specific agent
/cc explain this code	Send to agent by alias
/claude	Switch default agent to Claude
/status	Show current agent info
/help	Show help message

Aliases

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

Switching default agent is persisted to config — survives restarts.

Media Messages

WeClaw supports sending images, videos, and files to WeChat.

From agent replies: When an AI agent returns markdown with images (![](url)), WeClaw automatically extracts the image URLs, downloads them, uploads to WeChat CDN (AES-128-ECB encrypted), and sends them as image messages.

Markdown handling: Agent responses are automatically converted from markdown to plain text for WeChat display — code fences are stripped, links show display text only, bold/italic markers are removed, etc.

Proactive Messaging

Send messages to WeChat users without waiting for them to message first.

CLI:

# Send text
weclaw send --to "user_id@im.wechat" --text "Hello from weclaw"

# Send image
weclaw send --to "user_id@im.wechat" --media "https://example.com/photo.png"

# Send text + image
weclaw send --to "user_id@im.wechat" --text "Check this out" --media "https://example.com/photo.png"

# Send file
weclaw send --to "user_id@im.wechat" --media "https://example.com/report.pdf"

HTTP API (runs on 127.0.0.1:18011 when weclaw start is running):

# Send text
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "user_id@im.wechat", "text": "Hello from weclaw"}'

# Send image
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "user_id@im.wechat", "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": "user_id@im.wechat", "text": "See this", "media_url": "https://example.com/photo.png"}'

Supported media types: images (png, jpg, gif, webp), videos (mp4, mov), files (pdf, doc, zip, etc.).

Set WECLAW_API_ADDR to change the listen address (e.g. 0.0.0.0:18011).

Configuration

Config file: ~/.weclaw/config.json

{
  "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"
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "sk-xxx",
      "model": "openclaw:main"
    }
  }
}

Environment variables:

• WECLAW_DEFAULT_AGENT — override default agent
• OPENCLAW_GATEWAY_URL — OpenClaw HTTP fallback endpoint
• OPENCLAW_GATEWAY_TOKEN — OpenClaw API token

Permission bypass

By default, some agents require interactive permission approval which doesn't work in WeChat. Add args to your agent config to bypass:

Agent	Flag	What it does
Claude (CLI)	--dangerously-skip-permissions	Skip all tool permission prompts
Codex (CLI)	--skip-git-repo-check	Allow running outside git repos

Example:

{
  "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"]
  }
}

Warning: These flags disable safety checks. Only enable them if you understand the risks. ACP agents handle permissions automatically and don't need these flags.

Background Mode

# Start (runs in background by default)
weclaw start

# Check if running
weclaw status

# Stop
weclaw stop

# Run in foreground (for debugging)
weclaw start -f

Logs are written to ~/.weclaw/weclaw.log.

System service (auto-start on boot)

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

Docker

# Build
docker build -t weclaw .

# Login (interactive — scan QR code)
docker run -it -v ~/.weclaw:/root/.weclaw weclaw login

# Start with HTTP agent
docker run -d --name weclaw \
  -v ~/.weclaw:/root/.weclaw \
  -e OPENCLAW_GATEWAY_URL=https://api.example.com \
  -e OPENCLAW_GATEWAY_TOKEN=sk-xxx \
  weclaw

# View logs
docker logs -f weclaw

Note: ACP and CLI agents require the agent binary inside the container. The Docker image ships only WeClaw itself. For ACP/CLI agents, mount the binary or build a custom image. HTTP agents work out of the box.

Release

# Tag a new version to trigger GitHub Actions build & release
git tag v0.1.0
git push origin v0.1.0

The workflow builds binaries for darwin/linux x amd64/arm64, creates a GitHub Release, and uploads all artifacts with checksums.

Development

# Hot reload
make dev

# Build
go build -o weclaw .

# Run
./weclaw start

License

MIT