weclaw

README

WeClaw

中文文档

WeChat + OpenClaw = WeClaw.

Control OpenClaw, Claude Code, Codex, OpenCode, Cursor, Kimi, Trae, and custom agents from WeChat.

WeClaw turns your WeChat into a remote control for AI coding agents. Message from your phone, your agents respond from your machine. Supports ACP (persistent sessions), CLI (per-message), and HTTP (cloud APIs).

OpenClaw users: A recent OpenClaw update broke older WeChat plugin installs. If you also use the official OpenClaw WeChat plugin, reinstall the latest version:

npx -y @tencent-weixin/openclaw-weixin-cli@latest install

WeClaw itself talks to iLink Bot API directly, so this does not block WeClaw, but it does matter if you are testing both side-by-side.

Spaces At A Glance

Spaces are named working lanes inside WeClaw.

• /space work codex means: create or switch to the work lane and make Codex the default agent there
• /space fun cursor means: jump into a different lane with a different default agent
• plain messages after that stay in that lane, so you do not need to repeat /codex or /cursor every turn

This is the core UX improvement over a single shared chat thread: each space gets its own default agent, its own long-lived conversation, and its own log path.

Quick Start

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

# Login (scan QR code with WeChat)
weclaw login

# Start
weclaw start

That's it. The installer fetches the weclaw binary and, when npm is available, also installs the bundled Claude/Codex ACP adapters (claude-agent-acp, codex-acp). WeClaw then auto-detects installed agents and starts routing messages.

To skip the bundled adapters:

curl -fsSL https://raw.githubusercontent.com/shp-ai/weclaw/main/install.sh | WECLAW_SKIP_ADAPTERS=1 sh

Other install methods

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

# Build from source
git clone https://github.com/shp-ai/weclaw.git
cd weclaw && make install

How It Works

flowchart LR
    U["WeChat user"] --> I["iLink Bot API"]
    I --> M["Monitor<br/>long-poll per account"]
    M --> R["Router<br/>commands, aliases, per-user default"]
    R --> P["Agent Pool<br/>lazy start + reuse"]
    P --> ACP["ACP backends<br/>Claude, Codex, OpenCode, Cursor"]
    P --> CLI["CLI backends<br/>OpenClaw, CLI fallbacks"]
    P --> HTTP["HTTP backends<br/>OpenAI-compatible APIs"]
    ACP --> A["Local coding agents"]
    CLI --> A
    HTTP --> C["Cloud models / gateways"]
    R --> S["Sender<br/>markdown -> text, media extraction"]
    S --> I
    R --> L["Session logs<br/>~/.weclaw/logs/*.jsonl"]
    R --> H["HTTP API<br/>:18012 /api/send, /health"]

Message Lifecycle

sequenceDiagram
    participant U as WeChat user
    participant M as Monitor
    participant R as Router
    participant P as Agent Pool
    participant A as Agent backend
    participant S as Sender
    participant L as Session log

    U->>M: Send message in WeChat
    M->>R: Parsed WeixinMessage
    R->>R: Built-in command or agent routing
    R->>P: Get or create target agent
    P->>A: ACP / CLI / HTTP request
    A-->>R: Text or markdown reply
    R->>S: Plaintext + extracted media URLs
    S-->>U: WeChat reply
    R-->>L: Append JSONL session log

WeClaw is intentionally thin: it does not try to be a full workflow orchestrator. It sits between WeChat and your existing agents, keeps routing deterministic, and preserves enough state to make chat from the phone useful instead of gimmicky.

Agent Modes

Mode	How it works	Best for
ACP	Persistent subprocess, JSON-RPC over stdio. Fastest — no cold-start, full context across turns.	Claude, Codex, OpenCode, Cursor, Kimi
CLI	New process per message. Supports --resume for session continuity when the CLI supports it.	Any agent with a usable non-interactive CLI entrypoint
HTTP	OpenAI-compatible chat completions API. 20-message history window. Streaming with non-streaming fallback.	Cloud APIs (OpenAI, Anthropic, GLM, DeepSeek, etc.)

Auto-detection picks ACP over CLI when both are available. The bundled installer makes that true for Claude and Codex by default.

Supported Agents

Agent	Alias	Mode	Binary
Claude Code	/cc	ACP/CLI	claude-agent-acp, claude
Codex	/cx	ACP/CLI	codex-acp, codex
OpenCode	/oc /ocd	ACP	opencode
Cursor	/cs	ACP	agent
OpenClaw	—	CLI	openclaw
Kimi	/km	ACP	kimi
Trae	/tr	CLI	trae
Any cloud LLM	—	HTTP	(config)

Verified Runtime Surface

Agent	Current preferred mode	Notes
Claude	ACP	Bundled installer now installs claude-agent-acp by default
Codex	ACP	Bundled installer now installs codex-acp by default
OpenCode	ACP	Verified locally with message and tool-call streaming
Cursor	ACP	Verified locally; may stream more conversational preamble
OpenClaw	CLI	Current installed ACP bridge completes prompts without returning reply text chunks reliably
HTTP agents	HTTP	Generic OpenAI-compatible path

Known Limitations

• OpenClaw currently defaults to CLI mode because the installed ACP bridge does not reliably emit reply text chunks.
• Persistent routing state and spaces are implemented, but the new WeChat-side /space ... flow still needs more real-world dogfooding.
• Docker/service packaging is not shipped in this repo yet.

Chat Commands

Send these as WeChat messages:

Command	Effect
hello	Send to default agent
/codex write tests	Send to specific agent
/cc explain this	Send via alias
/claude	Switch default agent to Claude
/status	Bridge status (uptime, agents, accounts)
/agents	List available agents with type and model
/accounts	Show connected WeChat accounts
/spaces	List spaces for the current account
/space	Show the current space
/space work	Switch to a named space, creating it if needed
/space work codex	Switch/create a space and set its default agent
/help	Command reference

Default agent and current space are now persisted per user in ~/.weclaw/state.json.

Spaces and Persistent Routing

WeClaw now keeps lightweight routing state outside the process so users do not lose their setup on restart.

• A space is a lightweight profile bound to one WeChat account.
• Each space has a bound account, a default agent, and its own log directory.
• Each user binding is keyed by account + user, so the same person can have different defaults in different spaces.
• Agent session isolation now uses account + space + user, so switching spaces creates genuinely separate long-lived agent conversations.

Why this exists:

• You may want codex for a coding-heavy project but claude for planning.
• You may want separate long-lived threads for work, ops, and frontend.
• You should not need to type /codex on every single turn just to stay in the right context.

In practice, a space gives you a named lane with its own default agent and conversation history.

State file:

~/.weclaw/state.json

Per-space logs:

~/.weclaw/logs/spaces/<space>/YYYY-MM-DD.jsonl

CLI management:

weclaw space list
weclaw space add work --account "user@im.wechat" --default-agent codex
weclaw space remove work

If the same space name exists on multiple accounts, remove it with:

weclaw space remove work --account "user@im.wechat"

WeChat-side usage:

/spaces
/space
/space work
/space work codex
/claude

/claude, /codex, etc. now persist as per-user default-agent overrides for the current space.

Example flow:

/space work codex
fix the auth bug
add tests

/space planning claude
write the rollout plan

/space work
now refactor the handler

In that example:

• work and planning are separate spaces
• each space can keep a different default agent
• switching back to work restores that lane instead of mixing with planning

Configuration

Config file: ~/.weclaw/config.json

{
  "default_agent": "claude",
  "api_addr": "127.0.0.1:18012",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "claude-agent-acp"
    },
    "codex": {
      "type": "acp",
      "command": "codex-acp"
    },
    "glm": {
      "type": "http",
      "endpoint": "https://api.z.ai/api/coding/paas/v4/chat/completions",
      "api_key": "your-key",
      "model": "glm-4.5",
      "system_prompt": "You are a helpful coding assistant."
    }
  }
}

If you prefer CLI mode for either local agent, point command back to claude or codex and set "type": "cli".

Agent config fields

Field	Type	Description
type	string	"acp", "cli", or "http"
command	string	Binary path (ACP/CLI)
args	[]string	Extra args passed to binary (ACP/CLI)
model	string	Model identifier
endpoint	string	API base URL (HTTP)
api_key	string	API key (HTTP)
system_prompt	string	System message prepended to every request (HTTP)

Environment overrides

WECLAW_DEFAULT_AGENT=claude
WECLAW_API_ADDR=127.0.0.1:18012

Permission bypass

Some agents require interactive approval which doesn't work via WeChat:

Agent	Flag	Effect
Claude (CLI)	--dangerously-skip-permissions	Skip tool permission prompts
Codex (CLI)	--skip-git-repo-check	Run outside git repos

Warning: These flags disable safety checks. ACP agents handle permissions automatically.

HTTP Agent (Cloud APIs)

Connect any OpenAI-compatible API as a WeChat agent:

{
  "openai": {
    "type": "http",
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "api_key": "sk-...",
    "model": "gpt-4o"
  },
  "deepseek": {
    "type": "http",
    "endpoint": "https://api.deepseek.com/v1/chat/completions",
    "api_key": "sk-...",
    "model": "deepseek-chat"
  }
}

Then: /openai what is the meaning of life or /deepseek write a haiku

Supports streaming (SSE) with automatic non-streaming fallback. Conversation history is maintained per-user (20 message window).

Proactive Messaging

Send messages TO WeChat from external systems — CI notifications, build alerts, agent updates.

CLI:

weclaw send --to "user_id" --text "Build failed on main"
weclaw send --to "user_id" --media "https://example.com/screenshot.png"

HTTP API (runs on :18012 when bridge is active):

# Text
curl -X POST http://127.0.0.1:18012/api/send \
  -H 'Content-Type: application/json' \
  -d '{"to": "user_id", "text": "Deploy complete"}'

# Media
curl -X POST http://127.0.0.1:18012/api/send \
  -H 'Content-Type: application/json' \
  -d '{"to": "user_id", "media_url": "https://example.com/image.png"}'

# Health check
curl http://127.0.0.1:18012/health

Session Logging

Every conversation is logged to ~/.weclaw/logs/YYYY-MM-DD.jsonl:

{"ts":"2026-03-24T12:00:00Z","direction":"inbound","wechat_user":"user123","agent":"claude","message":"fix the bug","response":"Done. The issue was...","latency_ms":3200}

Use this for cost attribution, debugging, analytics, or building dashboards. Buffered writes (5s flush) — zero impact on message latency.

Background Mode

weclaw start          # daemonize (default)
weclaw start -f       # foreground (for debugging)
weclaw status         # check if running
weclaw stop           # graceful shutdown
weclaw restart        # stop + start

Logs: ~/.weclaw/weclaw.log

Updating

weclaw update         # check for new version and install

Development

git clone https://github.com/shp-ai/weclaw.git
cd weclaw

make build            # build ./weclaw
make install          # install to $GOPATH/bin
make dev              # run in foreground

Requires Go 1.26+.

Release

make release
git tag v0.1.0
git push origin v0.1.0

make release writes cross-platform binaries plus dist/weclaw-sha256sums.txt.

Tag pushes (v*) are published by the GitHub release workflow in .github/workflows/release.yml. Use docs/oss-release-readiness.md as the first-stop checklist before cutting a public OSS release.

OSS Release

The repo is usable now, but should still be treated as a preview OSS release. Read docs/oss-release-readiness.md for:

• current release blockers
• packaging/distribution gaps versus benchmark competitors
• the exact pre-release checklist
• recommended next actions

Compatibility

WeClaw is a standalone bridge — it does not depend on OpenClaw's plugin SDK. It works with any version of OpenClaw (or without OpenClaw entirely).

Note: If you also use the official OpenClaw WeChat plugin, reinstall the latest version:

npx -y @tencent-weixin/openclaw-weixin-cli@latest install

WeClaw itself is unaffected — it connects to iLink Bot API directly.

Contributing

Issues and PRs welcome. Please open an issue first to discuss significant changes.

License

MIT — Copyright 2026 SHP AI Global Group Inc.