Files
Obsidian/githubLibs/fastclaw-aiweclaw Connect to any agents with WeChat ClawBot.md
T
2026-07-21 14:53:24 +08:00

350 lines
9.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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/raw/main/previews/preview1.png)](https://github.com/fastclaw-ai/weclaw/blob/main/previews/preview1.png) | [![](https://github.com/fastclaw-ai/weclaw/raw/main/previews/preview2.png)](https://github.com/fastclaw-ai/weclaw/blob/main/previews/preview2.png) | [![](https://github.com/fastclaw-ai/weclaw/raw/main/previews/preview3.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/raw/main/previews/architecture.png)](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(`![](url)` )时,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://camo.githubusercontent.com/8a793edee2e5dcf5f6c8b2910535faa5f0a4c0b985bdea73e09fdf779e154f44/68747470733a2f2f636f6e747269622e726f636b732f696d6167653f7265706f3d66617374636c61772d61692f7765636c6177)](https://github.com/fastclaw-ai/weclaw/graphs/contributors)
## Star 趋势
[![Star History Chart](https://camo.githubusercontent.com/d64d51a85c98515e9d7d098a9b23876263fe239887665f15ede4c56df095224e/68747470733a2f2f6170692e737461722d686973746f72792e636f6d2f7376673f7265706f733d66617374636c61772d61692f7765636c617726747970653d54696d656c696e65)](https://star-history.com/#fastclaw-ai/weclaw&Timeline)
## 许可证
[MIT](https://github.com/fastclaw-ai/weclaw/blob/main/LICENSE)