weclaw

WeClaw

中文文档

WeChat AI Agent Bridge — connect WeChat to AI agents (Claude, Codex, Hermes, 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, Hermes, 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, Hermes, 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), MiniMax

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

Chat Commands

Send these as WeChat messages:

Command	Description
hello	Send to default agent
/hermes	Switch default agent to Hermes
/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)
/cron list|add|delete|enable|disable	Manage scheduled tasks
/info	Show current agent info
/help	Show help message

Aliases

Alias	Agent
/cc	claude
/cx	codex
/hm	hermes
/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 "[email protected]" --text "Hello from weclaw"

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

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

# Send file
weclaw send --to "[email protected]" --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": "[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: 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).

Cron (Scheduled Tasks)

Schedule recurring or one-shot tasks that send messages to AI agents on a timer:

/cron add "standup" every:24h "summarize yesterday's work"
/cron add "check" */30 * * * * "check for new PRs"
/cron add "reminder" at:2026-04-01T09:00:00 "sprint review today"
/cron list
/cron enable <id>
/cron disable <id>
/cron delete <id>

Schedule formats:

Format	Example	Description
every:<duration>	every:5m, every:24h	Fixed interval
Cron expression	*/30 * * * *, 0 9 * * 1-5	Standard 5-field cron
at:<time>	at:2026-04-01T09:00:00	One-shot (auto-disables after run)

Jobs are persisted to ~/.weclaw/cron/jobs.json and survive restarts. Each job can optionally target a specific agent.

Heartbeat

Periodic agent check-in driven by a user-authored checklist. Create ~/.weclaw/HEARTBEAT.md:

# Heartbeat checklist
- Check if any urgent emails arrived
- Scan for open PRs needing review
- Check CI pipeline status

WeClaw reads this file on each heartbeat interval, sends it to the default agent, and:

• Agent replies HEARTBEAT_OK → suppressed (nothing to report)
• Agent replies with content → delivered to the target user with [Heartbeat] prefix
• Duplicate replies within 24h are suppressed to avoid noise

Config:

{
  "heartbeat": {
    "enabled": true,
    "interval": "30m",
    "active_hours": "09:00-18:00",
    "timezone": "Asia/Shanghai",
    "target_user": "your_wechat_user_id"
  }
}

Option	Default	Description
enabled	false	Enable heartbeat runner
interval	30m	Time between heartbeat checks
active_hours	—	Only run during these hours (e.g. 09:00-18:00)
timezone	local	IANA timezone for active hours
target_user	—	WeChat user ID to send heartbeat results to

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"
      }
    },
    "hermes": {
      "type": "acp",
      "command": "hermes",
      "args": ["acp"]
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "sk-xxx",
      "model": "openclaw:main"
    },
    "minimax": {
      "type": "http",
      "endpoint": "https://api.minimax.io/v1/chat/completions",
      "api_key": "sk-xxx",
      "model": "MiniMax-M3.1-Flash"
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": "30m",
    "active_hours": "09:00-18:00",
    "timezone": "Asia/Shanghai",
    "target_user": "your_wechat_user_id"
  }
}

Environment variables:

• WECLAW_DEFAULT_AGENT — override default agent
• OPENCLAW_GATEWAY_URL — OpenClaw HTTP fallback endpoint
• OPENCLAW_GATEWAY_TOKEN — OpenClaw API token
• MINIMAX_API_KEY — enable the MiniMax OpenAI-compatible HTTP provider
• MINIMAX_REGION — MiniMax region: global_en (default) or cn_zh
• MINIMAX_BASE_URL — override the MiniMax chat completions endpoint
• MINIMAX_MODEL — MiniMax model: MiniMax-M3.1-Flash (default) or MiniMax-M3; explicit custom and legacy model IDs remain supported

These environment variables configure a new MiniMax agent. Existing saved agent settings, including the model and endpoint, are preserved.

Custom agent CLI environment variables:

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

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