weclaw: putting a coding agent behind a WeChat conversation

QR code login, agent detection, config file

The install is one line and the first run is one command:

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

weclaw start

On that first start, the README describes four things happening in sequence. You get a QR code to scan with WeChat, installed agents are detected automatically (Claude, Codex, Gemini and others), configuration lands in `~/.weclaw/config.json`, and the program begins receiving and replying to WeChat messages. `weclaw login` adds further WeChat accounts afterwards. That QR login is the part worth pausing on: the bridge authenticates as a real WeChat client, which is also why the project says it is inspired by `@tencent-weixin/openclaw-weixin` and is for personal learning rather than commercial use.

Two other install routes are documented. Go users can install the module directly:

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

And there is a container image, with the config directory mounted so state survives the container:

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

The `Dockerfile` is a two stage Alpine build: Go 1.25 compiles a static binary with `CGO_ENABLED=0`, and the runtime stage copies in `ca-certificates` and `tzdata` before declaring a volume at `/root/.weclaw` and an entrypoint of `weclaw` with a `start` command. It is a small, conventional image, which is a good sign about how the binary behaves outside a developer's laptop.

Three agent modes and how auto-detection picks between them

The interesting design decision is that weclaw does not require one specific agent runtime. It supports three modes, and the README is explicit about the trade-off in each.

ACP keeps a long running subprocess and talks JSON-RPC over stdio. The README calls this the fastest mode because it reuses the process and its sessions, and it lists Claude, Codex, Kimi, Gemini, Cursor, OpenCode and OpenClaw as agents that work this way. CLI mode spawns a new process per message and supports session resume via `--resume`, with Claude (`claude -p`) and Codex (`codex exec`) as the named examples. HTTP mode is an OpenAI compatible chat completions endpoint, documented as the OpenClaw fallback.

Auto-detection picks ACP over CLI when both are available, which is the right default given that ACP keeps a warm process and a session rather than paying startup cost per message.

The repository layout matches that story. Directories named `agent/`, `api/`, `cmd/`, `config/`, `ilink/`, `messaging/` and `service/` sit next to `main.go`, a `go.mod` requiring Go 1.25, a `Makefile` whose only target is `dev: air -c .air.toml start`, and an `.air.toml` for live reload. The `ilink/` directory is the part you would read first if you wanted to know how the WeChat side actually works, since that is where the messaging protocol lives.

Chat commands and per agent aliases

Routing is done with slash commands typed as ordinary WeChat messages. A plain `hello` goes to the default agent, `/codex write a function` targets a named agent, `/claude` switches the default, `/cwd /path/to/project` changes the workspace directory, `/new` clears the session, and `/info` and `/help` report state and usage.

Aliases are the part that saves typing, and the built-in table is short: `/cc` for claude, `/cx` for codex, `/cs` for cursor, `/km` for kimi, `/gm` for gemini, `/ocd` for opencode and `/oc` for openclaw. You can add your own per agent in the config file:

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

After that, `/ai hello` and `/c hello` both route to claude. Switching the default agent is persisted to config, so it survives a restart. The `cwd` command is the one with real consequences, since it changes which directory the agent works in; the README notes that if `cwd` is omitted, the workspace defaults to `~/.weclaw/workspace`.

Release v0.7.1 is a good illustration of how this layer actually gets used. It added the missing ACP agents from the acpx registry, fixed a Claude CLI misconfiguration where the `claude` binary was configured as `type: acp` (a hint now tells you it needs `type: cli` or `claude-agent-acp` installed), and added a fix for empty responses from newer Claude CLI versions.

Permission prompts that do not survive a chat window

Here is the real constraint of the whole project, and the README states it plainly: some agents require interactive permission approval, and interactive approval does not work in WeChat. There is nobody at the terminal to press a key.

The documented escape hatch is an `args` array on the agent config:

{
  "claude": {
    "type": "cli",
    "command": "/usr/local/bin/claude",
    "cwd": "/home/user/my-project",
    "args": ["--dangerously-skip-permissions"]
  }
}

The corresponding Codex flag is `--skip-git-repo-check`, which allows running outside a git repository. The README's own warning is that these flags disable safety checks, and it adds the detail that matters: ACP agents handle permissions automatically and do not need these flags at all. So the permission question and the mode question are the same question. If you are on ACP, you keep approvals. If you are on CLI, you are choosing between a bridge that cannot prompt and an agent that runs unattended.

A person messaging from their phone is also not in the same position as someone watching a terminal. There is no diff review in the message thread, no visible working directory unless they ask for it, and the agent has whatever filesystem access the machine running it already had. The README does not add role based limits, an allowlist of commands, or a read only mode. Those are not documented features rather than known gaps, but nothing suggests they exist.

Sending messages back out over a local HTTP API

The bridge is bidirectional, which is the feature that turns it from a remote terminal into a notification path. Messages can be pushed to a WeChat user without waiting for them to write first, either from the CLI:

weclaw send --to "[email protected]" --text "Hello from weclaw"

or over HTTP, on `127.0.0.1:18011` while `weclaw start` is running:

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

The `send` command also takes `--media`, alone or alongside `--text`, for an image or a file. Supported types are listed as images (png, jpg, gif, webp), videos (mp4, mov) and files (pdf, doc, zip and similar). `WECLAW_API_ADDR` changes the listen address, and the README's own example for that is `0.0.0.0:18011`, which is worth noting as a security decision rather than a default.

Media handling in the inbound direction is more interesting than it sounds. Voice messages use WeChat's own speech to text transcription, and the transcribed text goes to the agent. In the outbound direction, when an agent replies with markdown containing images, weclaw extracts the URLs, downloads them, uploads them to the WeChat CDN with AES-128-ECB encryption, and sends them as image messages. That means agent output can cause weclaw to fetch arbitrary URLs on your machine and push the bytes to a chat service. Markdown is also flattened for display, with code fences stripped and links reduced to their display text.

Configuration, environment variables and process control

Everything lives in `~/.weclaw/config.json`, and the shape is one object per agent with a type, a command, optional environment and optional arguments:

{
  "default_agent": "claude",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "/usr/local/bin/claude-agent-acp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxx"
      },
      "model": "sonnet"
    }
  }
}

API keys sit in that file, which is the obvious thing to notice about the layout. The Dockerfile's `VOLUME /root/.weclaw` and the documented mount of `~/.weclaw` mean the file holding every credential for every agent is the one directory you have to protect, back up carefully, and keep out of any synced folder. Three environment variables are documented alongside it: `WECLAW_DEFAULT_AGENT` to override the default, plus `OPENCLAW_GATEWAY_URL` and `OPENCLAW_GATEWAY_TOKEN` for the OpenClaw HTTP fallback.

Process control is four commands. `weclaw start` runs in the background by default, `weclaw status` reports whether it is up, `weclaw stop` stops it, and `weclaw start -f` runs in the foreground, which the README recommends for debugging. Release v0.7.1 extended HTTP agent timeouts from 60 to 120 seconds for long running requests and added a `headers` field on HTTP agent configs, which it also needed to fix a 403 from the OpenClaw gateway by sending `x-openclaw-scopes: operator.write`.

The releases are few and recent: v0.7.0 on 2026-03-28, v0.7.1 on 2026-03-29, and a rolling `beta-latest` pre-release built from `main`. The last push was on 2026-04-01. Version numbers below 1.0 with a three week gap between the last tagged release and the last commit is the state of the project right now, which is young enough that you should read the release notes before trusting a configuration detail.

Editorial conclusion

weclaw makes sense if your relationship with a coding agent is a message rather than a terminal, and if you are willing to give up per tool permission approval on the CLI path. ACP mode is the safer of the three because it keeps the permission model intact, and it is the mode auto-detection prefers when both are available. The last push was on 2026-04-01, so check that release notes page before wiring it into anything you depend on. Start with `weclaw start` on your own account, add a second account later with `weclaw login`, and read the config file at `~/.weclaw/config.json` before you enable any permission bypass flag.

Frequently asked questions

Official sources

1. fastclaw-ai/weclaw on GitHub
2. License: MIT
3. Project website
4. README
5. Releases