weclaw

README

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)
Shell	Executes shell commands directly and returns output. No AI — just a remote terminal.	/sh ls -la, /term docker ps

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
/cwd /path/to/project	Switch workspace directory
/new	Start a new conversation (clear session)
/info	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

You can also define custom aliases per agent in config:

{
  "agents": {
    "claude": {
      "type": "acp",
      "aliases": ["ai", "c"]
    }
  }
}

Then /ai hello or /c hello will route to claude.

Switching default agent is persisted to config — survives restarts.

Media Messages

WeClaw supports sending images, videos, files, and voice messages to/from WeChat.

Voice messages: When you send a voice message in WeChat, WeClaw automatically uses WeChat's speech-to-text transcription and forwards the text to the AI agent. Duplicate voice message events are automatically deduplicated.

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",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxx"
      },
      "model": "sonnet"
    },
    "codex": {
      "type": "acp",
      "command": "/usr/local/bin/codex-acp",
      "env": {
        "OPENAI_API_KEY": "sk-xxx"
      }
    },
    "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

Custom agent CLI environment variables:

{
  "default_agent": "...",
  "agents": {
    "...": {
      ...
      "env": {
        "ENV_NAME": "ENV_VALUE"
      }
    },
  }
}

Shell agent

The shell agent type lets you execute commands on the host machine from WeChat and see the output — like a remote terminal.

{
  "agents": {
    "sh": {
      "type": "shell",
      "cwd": "/home/user",
      "aliases": ["term"]
    }
  }
}

Then send /sh ls -la or /term docker ps in WeChat. The command runs via /bin/sh -c and stdout+stderr are sent back as the reply.

To use a different shell (e.g. zsh), set command:

{
  "sh": {
    "type": "shell",
    "command": "/bin/zsh",
    "cwd": "/home/user/project"
  }
}

Warning: This executes arbitrary commands on the host. Only enable it if you control who can send you WeChat messages.

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",
    "cwd": "/home/user/my-project",
    "args": ["--dangerously-skip-permissions"]
  },
  "codex": {
    "type": "cli",
    "command": "/usr/local/bin/codex",
    "cwd": "/home/user/my-project",
    "args": ["--skip-git-repo-check"]
  }
}

Set cwd to specify the agent's working directory (workspace). If omitted, defaults to ~/.weclaw/workspace.

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/windows x amd64/arm64, creates a GitHub Release, and uploads all artifacts with checksums.

Update

# Update to the latest version (auto-restarts if running)
weclaw update

# Check current version
weclaw version

Development

# Hot reload
make dev

# Build
go build -o weclaw .

# Run
./weclaw start

Contributors

Star History

License

MIT