350 lines
9.6 KiB
Markdown
350 lines
9.6 KiB
Markdown
---
|
||
title: "fastclaw-ai/weclaw: Connect to any agents with WeChat ClawBot."
|
||
source: "https://github.com/fastclaw-ai/weclaw/blob/main/README_CN.md"
|
||
author:
|
||
- "[[GitHub]]"
|
||
published:
|
||
created: 2026-03-28
|
||
description: "Connect to any agents with WeChat ClawBot. Contribute to fastclaw-ai/weclaw development by creating an account on GitHub."
|
||
tags:
|
||
- "clippings"
|
||
---
|
||
## WeClaw
|
||
|
||
[English](https://github.com/fastclaw-ai/weclaw/blob/main/README.md)
|
||
|
||
微信 AI Agent 桥接器 — 将微信消息接入 AI Agent(Claude、Codex、Gemini、Kimi 等)。
|
||
|
||
> 本项目参考 [@tencent-weixin/openclaw-weixin](https://npmx.dev/package/@tencent-weixin/openclaw-weixin) 实现,仅限个人学习,勿做他用。
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| [](https://github.com/fastclaw-ai/weclaw/blob/main/previews/preview1.png) | [](https://github.com/fastclaw-ai/weclaw/blob/main/previews/preview2.png) | [](https://github.com/fastclaw-ai/weclaw/blob/main/previews/preview3.png) |
|
||
|
||
## 快速开始
|
||
|
||
```
|
||
# 一键安装
|
||
curl -sSL https://raw.githubusercontent.com/fastclaw-ai/weclaw/main/install.sh | sh
|
||
|
||
# 启动(首次运行会弹出微信扫码登录)
|
||
weclaw start
|
||
```
|
||
|
||
就这么简单。首次启动时,WeClaw 会:
|
||
|
||
1. 显示二维码 — 用微信扫码登录
|
||
2. 自动检测已安装的 AI Agent(Claude、Codex、Gemini 等)
|
||
3. 保存配置到 `~/.weclaw/config.json`
|
||
4. 开始接收和回复微信消息
|
||
|
||
使用 `weclaw login` 可以添加更多微信账号。
|
||
|
||
### 其他安装方式
|
||
|
||
```
|
||
# 通过 Go 安装
|
||
go install github.com/fastclaw-ai/weclaw@latest
|
||
|
||
# 通过 Docker
|
||
docker run -it -v ~/.weclaw:/root/.weclaw ghcr.io/fastclaw-ai/weclaw start
|
||
```
|
||
|
||
## 架构
|
||
|
||
[](https://github.com/fastclaw-ai/weclaw/blob/main/previews/architecture.png)
|
||
|
||
**Agent 接入模式:**
|
||
|
||
| 模式 | 工作方式 | 支持的 Agent |
|
||
| --- | --- | --- |
|
||
| ACP | 长驻子进程,通过 stdio JSON-RPC 通信。速度最快,复用进程和会话。 | Claude, Codex, Kimi, Gemini, Cursor, OpenCode, OpenClaw |
|
||
| CLI | 每条消息启动一个新进程,支持通过 `--resume` 恢复会话。 | Claude (`claude -p`)、Codex (`codex exec`) |
|
||
| HTTP | OpenAI 兼容的 Chat Completions API。 | OpenClaw(HTTP 回退) |
|
||
|
||
同时存在 ACP 和 CLI 时,自动优先选择 ACP。
|
||
|
||
## 聊天命令
|
||
|
||
在微信中发送以下命令:
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `你好` | 发送给默认 Agent |
|
||
| `/codex 写一个排序函数` | 发送给指定 Agent |
|
||
| `/cc 解释一下这段代码` | 通过别名发送 |
|
||
| `/claude` | 切换默认 Agent 为 Claude |
|
||
| `/cwd /path/to/project` | 切换工作目录 |
|
||
| `/new` | 开始新对话(清除会话) |
|
||
| `/info` | 查看当前 Agent 信息 |
|
||
| `/help` | 查看帮助信息 |
|
||
|
||
### 快捷别名
|
||
|
||
| 别名 | Agent |
|
||
| --- | --- |
|
||
| `/cc` | Claude |
|
||
| `/cx` | Codex |
|
||
| `/cs` | Cursor |
|
||
| `/km` | Kimi |
|
||
| `/gm` | Gemini |
|
||
| `/ocd` | OpenCode |
|
||
| `/oc` | OpenClaw |
|
||
|
||
也可以在配置文件中为每个 Agent 自定义触发命令:
|
||
|
||
```
|
||
{
|
||
"agents": {
|
||
"claude": {
|
||
"type": "acp",
|
||
"aliases": ["ai", "c"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
然后 `/ai 你好` 或 `/c 你好` 就会路由到 claude。
|
||
|
||
切换默认 Agent 会写入配置文件,重启后仍然生效。
|
||
|
||
## 富媒体消息
|
||
|
||
WeClaw 支持收发图片、视频、文件和语音消息。
|
||
|
||
**语音消息:** 在微信中发送语音消息时,WeClaw 会自动使用微信的语音转文字功能,将转写后的文本发送给 AI Agent。重复的语音消息事件会自动去重。
|
||
|
||
**Agent 回复自动处理:** 当 AI Agent 返回包含图片的 markdown(`` )时,WeClaw 会自动提取图片 URL,下载文件,上传到微信 CDN(AES-128-ECB 加密),然后作为图片消息发送。
|
||
|
||
**Markdown 转换:** Agent 的回复会自动从 markdown 转为纯文本再发送 — 代码块去掉围栏、链接只保留文字、加粗斜体标记去除等。
|
||
|
||
## 主动推送消息
|
||
|
||
无需等待用户发消息,主动向微信用户推送消息。
|
||
|
||
**命令行:**
|
||
|
||
```
|
||
# 发送文本
|
||
weclaw send --to "user_id@im.wechat" --text "你好,来自 weclaw"
|
||
|
||
# 发送图片
|
||
weclaw send --to "user_id@im.wechat" --media "https://example.com/photo.png"
|
||
|
||
# 发送文本 + 图片
|
||
weclaw send --to "user_id@im.wechat" --text "看看这个" --media "https://example.com/photo.png"
|
||
|
||
# 发送文件
|
||
weclaw send --to "user_id@im.wechat" --media "https://example.com/report.pdf"
|
||
```
|
||
|
||
**HTTP API** ( `weclaw start` 运行时,默认监听 `127.0.0.1:18011` ):
|
||
|
||
```
|
||
# 发送文本
|
||
curl -X POST http://127.0.0.1:18011/api/send \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"to": "user_id@im.wechat", "text": "你好,来自 weclaw"}'
|
||
|
||
# 发送图片
|
||
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"}'
|
||
|
||
# 发送文本 + 媒体
|
||
curl -X POST http://127.0.0.1:18011/api/send \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"to": "user_id@im.wechat", "text": "看看这个", "media_url": "https://example.com/photo.png"}'
|
||
```
|
||
|
||
支持的媒体类型:图片(png、jpg、gif、webp)、视频(mp4、mov)、文件(pdf、doc、zip 等)。
|
||
|
||
设置 `WECLAW_API_ADDR` 环境变量可更改监听地址(如 `0.0.0.0:18011` )。
|
||
|
||
## 配置
|
||
|
||
配置文件路径: `~/.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"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
环境变量:
|
||
|
||
- `WECLAW_DEFAULT_AGENT` — 覆盖默认 Agent
|
||
- `OPENCLAW_GATEWAY_URL` — OpenClaw HTTP 回退地址
|
||
- `OPENCLAW_GATEWAY_TOKEN` — OpenClaw API Token
|
||
|
||
自定义 agent cli 环境变量
|
||
|
||
```
|
||
{
|
||
"default_agent": "...",
|
||
"agents": {
|
||
"...": {
|
||
...
|
||
"env": {
|
||
"ENV_NAME": "ENV_VALUE"
|
||
}
|
||
},
|
||
}
|
||
}
|
||
```
|
||
|
||
### 权限配置
|
||
|
||
部分 Agent 默认需要交互式权限确认,在微信场景下无法操作会导致卡住。可通过 `args` 配置跳过:
|
||
|
||
| Agent | 参数 | 说明 |
|
||
| --- | --- | --- |
|
||
| Claude (CLI) | `--dangerously-skip-permissions` | 跳过所有工具权限确认 |
|
||
| Codex (CLI) | `--skip-git-repo-check` | 允许在非 git 仓库目录运行 |
|
||
|
||
配置示例:
|
||
|
||
```
|
||
{
|
||
"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"]
|
||
}
|
||
}
|
||
```
|
||
|
||
通过 `cwd` 指定 Agent 的工作目录(workspace)。不设置则默认为 `~/.weclaw/workspace` 。
|
||
|
||
> **注意:** 这些参数会跳过安全检查,请了解风险后再启用。ACP 模式的 Agent 会自动处理权限,无需配置。
|
||
|
||
## 后台运行
|
||
|
||
```
|
||
# 启动(默认后台运行)
|
||
weclaw start
|
||
|
||
# 查看状态
|
||
weclaw status
|
||
|
||
# 停止
|
||
weclaw stop
|
||
|
||
# 前台运行(调试用)
|
||
weclaw start -f
|
||
```
|
||
|
||
日志输出到 `~/.weclaw/weclaw.log` 。
|
||
|
||
### 系统服务(开机自启)
|
||
|
||
**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
|
||
|
||
```
|
||
# 构建
|
||
docker build -t weclaw .
|
||
|
||
# 登录(交互式,扫描二维码)
|
||
docker run -it -v ~/.weclaw:/root/.weclaw weclaw login
|
||
|
||
# 使用 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
|
||
|
||
# 查看日志
|
||
docker logs -f weclaw
|
||
```
|
||
|
||
> 注意:ACP 和 CLI 模式需要容器内有对应的 Agent 二进制文件。 默认镜像只包含 WeClaw 本体。如需使用 ACP/CLI Agent,请挂载二进制文件或构建自定义镜像。 HTTP 模式开箱即用。
|
||
|
||
## 发版
|
||
|
||
```
|
||
# 打 tag 触发 GitHub Actions 自动构建发版
|
||
git tag v0.1.0
|
||
git push origin v0.1.0
|
||
```
|
||
|
||
自动构建 `darwin/linux/windows` x `amd64/arm64` 的二进制,创建 GitHub Release 并上传所有产物和校验文件。
|
||
|
||
## 更新
|
||
|
||
```
|
||
# 更新到最新版本(运行中会自动重启)
|
||
weclaw update
|
||
|
||
# 查看当前版本
|
||
weclaw version
|
||
```
|
||
|
||
## 开发
|
||
|
||
```
|
||
# 热重载
|
||
make dev
|
||
|
||
# 编译
|
||
go build -o weclaw .
|
||
|
||
# 运行
|
||
./weclaw start
|
||
```
|
||
|
||
## 贡献者
|
||
|
||
[](https://github.com/fastclaw-ai/weclaw/graphs/contributors)
|
||
|
||
## Star 趋势
|
||
|
||
[](https://star-history.com/#fastclaw-ai/weclaw&Timeline)
|
||
|
||
## 许可证
|
||
|
||
[MIT](https://github.com/fastclaw-ai/weclaw/blob/main/LICENSE) |