Skip to content

README_CN.md

Latest commit

 

History

History
345 lines (253 loc) · 9.32 KB

README_CN.md

File metadata and controls

345 lines (253 loc) · 9.32 KB

WeClaw

English

微信 AI Agent 桥接器 — 将微信消息接入 AI Agent（Claude、Codex、Gemini、Kimi 等）。

本项目参考 @tencent-weixin/openclaw-weixin 实现，仅限个人学习，勿做他用。

快速开始

# 一键安装
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

架构

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

贡献者

Star 趋势

Star History Chart

许可证

MIT