weclaw-wechat-ai-bridge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WeClaw — WeChat AI Agent Bridge

Skill by ara.so — Daily 2026 Skills collection.

WeClaw connects WeChat to AI agents (Claude, Codex, Gemini, Kimi, OpenClaw, etc.) via a Go-based bridge. It handles QR-code login, message routing, media conversion, and agent lifecycle. Supports three agent modes: ACP (JSON-RPC subprocess, fastest), CLI (new process per message), and HTTP (OpenAI-compatible REST).

由ara.so开发的Skill — 属于Daily 2026 Skills合集。

WeClaw通过基于Go语言的桥接工具，将微信与AI Agent（Claude、Codex、Gemini、Kimi、OpenClaw等）相连。它支持二维码登录、消息路由、媒体格式转换以及Agent生命周期管理。同时提供三种Agent模式：ACP（基于JSON-RPC的长驻子进程，速度最快）、CLI（每条消息启动新进程）和HTTP（兼容OpenAI的REST接口）。

Installation

安装方法

bash

undefined

bash

undefined

One-line installer

一键安装脚本

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

Via Go toolchain

通过Go工具链安装

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

Via Docker

通过Docker安装

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

---

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

---

First-Run Flow

首次运行流程

bash

weclaw start        # Shows QR code → scan with WeChat → auto-detects agents → saves config
weclaw login        # Add/re-authenticate a WeChat account
weclaw status       # Show running state and active agent
weclaw stop         # Stop the background daemon
weclaw start -f     # Foreground mode (debug/verbose)

Logs:

~/.weclaw/weclaw.log

Config:

~/.weclaw/config.json

bash

weclaw start        # 显示二维码 → 用微信扫码 → 自动检测Agent → 保存配置
weclaw login        # 添加或重新认证微信账号
weclaw status       # 查看运行状态及当前激活的Agent
weclaw stop         # 停止后台守护进程
weclaw start -f     # 前台模式运行（用于调试/查看详细日志）

日志路径:

~/.weclaw/weclaw.log

配置文件路径:

~/.weclaw/config.json

Configuration

配置说明

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"
    },
    "claude-cli": {
      "type": "cli",
      "command": "/usr/local/bin/claude",
      "args": ["--dangerously-skip-permissions"]
    },
    "codex-cli": {
      "type": "cli",
      "command": "/usr/local/bin/codex",
      "args": ["--skip-git-repo-check"]
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "$OPENCLAW_GATEWAY_TOKEN",
      "model": "openclaw:main"
    }
  }
}

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"
    },
    "claude-cli": {
      "type": "cli",
      "command": "/usr/local/bin/claude",
      "args": ["--dangerously-skip-permissions"]
    },
    "codex-cli": {
      "type": "cli",
      "command": "/usr/local/bin/codex",
      "args": ["--skip-git-repo-check"]
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "$OPENCLAW_GATEWAY_TOKEN",
      "model": "openclaw:main"
    }
  }
}

Environment Variables

环境变量

Variable	Purpose
`WECLAW_DEFAULT_AGENT`	Override default agent at runtime
`WECLAW_API_ADDR`	Change local HTTP API address (default `127.0.0.1:18011` )
`OPENCLAW_GATEWAY_URL`	HTTP agent endpoint
`OPENCLAW_GATEWAY_TOKEN`	HTTP agent API token

变量名	用途
`WECLAW_DEFAULT_AGENT`	运行时覆盖默认Agent
`WECLAW_API_ADDR`	修改本地HTTP API监听地址（默认值 `127.0.0.1:18011` ）
`OPENCLAW_GATEWAY_URL`	HTTP Agent的接口地址
`OPENCLAW_GATEWAY_TOKEN`	HTTP Agent的API令牌

Agent Modes

Agent模式

Mode	Process model	Best for
`acp`	Long-running subprocess, JSON-RPC over stdio	Claude, Codex, Kimi, Gemini — fastest, session reuse
`cli`	New process per message, `--resume` for sessions	`claude -p` , `codex exec`
`http`	OpenAI-compatible `/v1/chat/completions`	Any REST-accessible model

Auto-detection prefers

acp

over

cli

when both binaries exist.

模式	进程模型	最佳适用场景
`acp`	长驻子进程，通过标准I/O进行JSON-RPC通信	Claude、Codex、Kimi、Gemini — 速度最快，支持会话复用
`cli`	每条消息启动新进程，通过 `--resume` 参数维持会话	`claude -p` 、 `codex exec` 等命令行工具
`http`	兼容OpenAI的 `/v1/chat/completions` 接口	任何可通过REST访问的模型

当同时存在ACP和CLI版本的二进制文件时，系统会自动优先选择ACP模式。

Chat Commands (send as WeChat messages)

聊天指令（通过微信消息发送）

Command	Action
`hello`	Send to default agent
`/codex write a sort function`	Route to named agent
`/cc explain this code`	Use alias ( `/cc` → claude)
`/claude`	Switch default agent to Claude (persisted)
`/status`	Show active agent info
`/help`	List available commands

指令	操作
`hello`	发送消息给默认Agent
`/codex write a sort function`	将消息路由到指定Agent
`/cc explain this code`	使用别名（ `/cc` 对应 claude）
`/claude`	将默认Agent切换为Claude（设置会持久保存）
`/status`	查看当前激活的Agent信息
`/help`	列出所有可用指令

Built-in Aliases

内置别名

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

别名	对应Agent
`/cc`	claude
`/cx`	codex
`/cs`	cursor
`/km`	kimi
`/gm`	gemini
`/ocd`	opencode
`/oc`	openclaw

Proactive Messaging — CLI

主动消息发送 — CLI方式

bash

undefined

bash

undefined

Send plain text

发送纯文本消息

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

Send an image

发送图片

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

Send text + media together

同时发送文本和图片

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

Send a file

发送文件

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

---

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

---

Proactive Messaging — HTTP API

主动消息发送 — HTTP API方式

The local API listens on

127.0.0.1:18011

while

weclaw start

is running.

bash

undefined

当

weclaw start

运行时，本地API会监听

127.0.0.1:18011

地址。

bash

undefined

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:** `png`, `jpg`, `gif`, `webp`, `mp4`, `mov`, `pdf`, `doc`, `zip`.

Change listen address:
```bash
WECLAW_API_ADDR=0.0.0.0:18011 weclaw start

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"}'


**支持的媒体类型:** `png`, `jpg`, `gif`, `webp`, `mp4`, `mov`, `pdf`, `doc`, `zip`.

修改监听地址:
```bash
WECLAW_API_ADDR=0.0.0.0:18011 weclaw start

Go Integration Example

Go语言集成示例

Call the WeClaw HTTP API from a Go service to send notifications:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type SendRequest struct {
	To       string `json:"to"`
	Text     string `json:"text,omitempty"`
	MediaURL string `json:"media_url,omitempty"`
}

type SendResponse struct {
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

func sendToWeChat(to, text, mediaURL string) error {
	apiAddr := os.Getenv("WECLAW_API_ADDR")
	if apiAddr == "" {
		apiAddr = "127.0.0.1:18011"
	}

	req := SendRequest{To: to, Text: text, MediaURL: mediaURL}
	body, err := json.Marshal(req)
	if err != nil {
		return fmt.Errorf("marshal: %w", err)
	}

	resp, err := http.Post(
		fmt.Sprintf("http://%s/api/send", apiAddr),
		"application/json",
		bytes.NewReader(body),
	)
	if err != nil {
		return fmt.Errorf("post: %w", err)
	}
	defer resp.Body.Close()

	var result SendResponse
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return fmt.Errorf("decode: %w", err)
	}
	if !result.OK {
		return fmt.Errorf("weclaw error: %s", result.Message)
	}
	return nil
}

func main() {
	recipient := os.Getenv("WECHAT_RECIPIENT_ID") // e.g. "user_id@im.wechat"
	if err := sendToWeChat(recipient, "Build succeeded ✅", ""); err != nil {
		fmt.Fprintf(os.Stderr, "failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Message sent.")
}

从Go服务中调用WeClaw的HTTP API发送通知:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type SendRequest struct {
	To       string `json:"to"`
	Text     string `json:"text,omitempty"`
	MediaURL string `json:"media_url,omitempty"`
}

type SendResponse struct {
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

func sendToWeChat(to, text, mediaURL string) error {
	apiAddr := os.Getenv("WECLAW_API_ADDR")
	if apiAddr == "" {
		apiAddr = "127.0.0.1:18011"
	}

	req := SendRequest{To: to, Text: text, MediaURL: mediaURL}
	body, err := json.Marshal(req)
	if err != nil {
		return fmt.Errorf("marshal: %w", err)
	}

	resp, err := http.Post(
		fmt.Sprintf("http://%s/api/send", apiAddr),
		"application/json",
		bytes.NewReader(body),
	)
	if err != nil {
		return fmt.Errorf("post: %w", err)
	}
	defer resp.Body.Close()

	var result SendResponse
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return fmt.Errorf("decode: %w", err)
	}
	if !result.OK {
		return fmt.Errorf("weclaw error: %s", result.Message)
	}
	return nil
}

func main() {
	recipient := os.Getenv("WECHAT_RECIPIENT_ID") // 例如: "user_id@im.wechat"
	if err := sendToWeChat(recipient, "Build succeeded ✅", ""); err != nil {
		fmt.Fprintf(os.Stderr, "failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Message sent.")
}

Docker Setup

Docker部署

bash

undefined

bash

undefined

Build image

构建镜像

docker build -t weclaw .

Step 1: Interactive login (scan QR code)

步骤1: 交互式登录（扫描二维码）

docker run -it -v ~/.weclaw:/root/.weclaw weclaw login

Step 2: Run daemon with HTTP agent

步骤2: 启动守护进程并使用HTTP Agent

docker run -d --name weclaw
-v ~/.weclaw:/root/.weclaw
-e OPENCLAW_GATEWAY_URL=https://api.example.com
-e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN"
weclaw

Expose the local API externally (bind carefully — no auth by default)

将本地API暴露到外部（谨慎操作 — 默认无身份验证）

docker run -d --name weclaw
-v ~/.weclaw:/root/.weclaw
-e WECLAW_API_ADDR=0.0.0.0:18011
-p 18011:18011
-e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN"
weclaw

docker logs -f weclaw


> ACP/CLI agents require the agent binary inside the container. Mount the binary or build a custom image. HTTP agents work out of the box.

---

docker run -d --name weclaw
-v ~/.weclaw:/root/.weclaw
-e WECLAW_API_ADDR=0.0.0.0:18011
-p 18011:18011
-e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN"
weclaw

docker logs -f weclaw


> ACP/CLI模式的Agent需要容器内部存在对应的二进制文件。可以通过挂载二进制文件或构建自定义镜像来实现。HTTP模式的Agent可直接使用。

---

System Service (Auto-start)

系统服务配置（开机自启）

macOS (launchd):

bash

cp service/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist

Linux (systemd):

bash

sudo cp service/weclaw.service /etc/systemd/system/
sudo systemctl enable --now weclaw
journalctl -u weclaw -f

macOS (launchd):

bash

cp service/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist

Linux (systemd):

bash

sudo cp service/weclaw.service /etc/systemd/system/
sudo systemctl enable --now weclaw
journalctl -u weclaw -f

Development

开发指南

bash

make dev                        # Hot reload
go build -o weclaw .            # Build binary
./weclaw start -f               # Run in foreground

Releasing:

bash

git tag v0.1.0
git push origin v0.1.0

bash

make dev                        # 热重载开发
go build -o weclaw .            # 构建二进制文件
./weclaw start -f               # 前台模式运行

发布版本:

bash

git tag v0.1.0
git push origin v0.1.0

GitHub Actions builds darwin/linux × amd64/arm64 and uploads release artifacts

GitHub Actions会自动构建darwin/linux × amd64/arm64版本的产物并上传到发布页面

---

---

Common Patterns

常见使用场景

Pattern: Per-user agent routing

场景：按用户需求路由到不同Agent

Send

/claude

/codex

as a WeChat message to switch the default agent. The choice persists in

~/.weclaw/config.json

across restarts.

发送

/claude

或

/codex

作为微信消息，即可切换默认Agent。该设置会保存在

~/.weclaw/config.json

中，重启后依然有效。

Pattern: CI/CD build notifications

场景：CI/CD构建通知

After a build, call

weclaw send

or POST to the HTTP API to push results to a WeChat contact or group.

构建完成后，调用

weclaw send

或通过HTTP API发送请求，将构建结果推送到微信联系人或群组。

Pattern: Media from agent

场景：Agent返回媒体内容

If an agent reply contains

![alt](https://...)

, WeClaw auto-downloads, AES-128-ECB encrypts, uploads to WeChat CDN, and delivers as a native image message — no extra config needed.

如果Agent的回复中包含

![alt](https://...)

格式的内容，WeClaw会自动下载该媒体、进行AES-128-ECB加密、上传到微信CDN，并以原生图片消息的形式发送给用户 — 无需额外配置。

Pattern: Disable permission prompts for headless use

场景：无界面环境下禁用权限提示

json

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

ACP agents handle permissions automatically and do not need these flags.

json

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

ACP模式的Agent会自动处理权限问题，无需添加这些参数。

Troubleshooting

故障排查

Symptom	Fix
QR code not appearing	Run `weclaw login` explicitly; ensure terminal supports UTF-8
Agent not auto-detected	Check binary is on `$PATH` ; run `weclaw status`
`connection refused` on HTTP API	Confirm `weclaw start` is running; check `WECLAW_API_ADDR`
Agent permission prompts block responses	Add `--dangerously-skip-permissions` (Claude) or `--skip-git-repo-check` (Codex) to `args` ; or use ACP mode
Docker — no agent binary	Mount binary: `-v /usr/local/bin/claude:/usr/local/bin/claude` ; or use HTTP mode
Markdown not rendering	WeClaw strips markdown automatically for WeChat plain-text display; this is expected
Logs	`tail -f ~/.weclaw/weclaw.log` or `docker logs -f weclaw`

症状	解决方法
二维码不显示	显式运行 `weclaw login` 命令；确保终端支持UTF-8编码
Agent未被自动检测到	检查二进制文件是否在 `$PATH` 路径下；运行 `weclaw status` 查看状态
HTTP API提示 `connection refused`	确认 `weclaw start` 已启动；检查 `WECLAW_API_ADDR` 配置
Agent的权限提示阻塞响应	在 `args` 中添加 `--dangerously-skip-permissions` （Claude）或 `--skip-git-repo-check` （Codex）；或切换到ACP模式
Docker环境下无Agent二进制文件	挂载本地二进制文件： `-v /usr/local/bin/claude:/usr/local/bin/claude` ；或使用HTTP模式
Markdown格式未渲染	WeClaw会自动去除Markdown格式以适配微信的纯文本显示；这是正常行为
查看日志	执行 `tail -f ~/.weclaw/weclaw.log` 或 `docker logs -f weclaw`