wxbot 微信消息机器人

wxbot 是一个使用微信 iLink（ClawBot）协议收发文本消息的 CLI 服务。

• 无界面，极其轻量，支持绑定多个微信
• 支持 CLI 或 Webhook 方式发送消息，支持消息回调脚本
• 轻松导出 curl 命令或 skill 安装脚本
• 支持 IP 来源白名单
• Windows/Linux 支持

如果你仅需要一个通知到微信的手段，这个项目正合适。
例如AI干完活可以微信通知，或定时执行某些任务把结果发送到微信。

编译 & 下载

go build -o wxbot ./cmd/wxbot

或前往release页面下载。

快速开始

使用 run 命令运行服务，扫描屏幕上的二维码绑定即可。

# 运行（初次运行会显示二维码，也可以手动add添加）
./wxbot run
# 需要在运行状态接收一次用户发送的消息，获取 context_token
# 之后24小时内，即使server不运行，也可以给用户发送消息
./wxbot send --user user1 --text '你好'

也可以使用 ./wxbot daemon install 安装为服务。

说明：微信协议限制，每24小时，用户需要主动发送一条消息，以获取 context_token。
wxbot 会在 token 失效前 1 小时通知用户发送新消息，此行为可以在配置文件中修改。

AI 发消息 Skill

在本地可以使用wxbot print-skill --user user1 --local | bash一键安装skill。
然后就可以告诉AI：发一条微信说你好。

远端安装等详细内容请参阅 wxbot skill。

发送消息

本地可以使用 CLI 发送消息，通过参数或标准输入提供文本。

./wxbot send --user user1 --text '你好'
echo 你好 | ./wxbot send --user user1

也可以通过 Webhook 发送消息。print-curl 可以打印发送命令：

./wxbot print-curl --user user1
# 输出如下：
curl 'http://127.0.0.1:9900/v1/message/send' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: text/plain; charset=utf-8' \
  --data-binary '你好'

提示：微信 bot 使用 Markdown 格式，换行需要使用 \n\n 。

接收消息（回调）

通过修改配置目录下的 profiles.yaml，可以指定收到消息时执行的回调。

profiles:
    xxx@im.wechat:
        alias: user1
        command:
            - ./handlers/echo-handler.py
        timeout: 120s
        reply_stdout: true

修改完成后需要重新启动程序 ./wxbot run, 或安装后使用 wxbot daemon restart。

回调处理程序会从标准输入收到如下 JSON 数据：

{
  "event": "message.created",
  "user": "goodman",
  "wx_id": "xxx@im.wechat",
  "message_id": "123456",
  "created_at": "2026-08-01T14:20:31+08:00",
  "type": "text",
  "text": "你好"
}

安装与配置目录

• 可以使用 --dir 指定配置目录。
• 便携运行时，使用 ./wxbot_data 配置目录。
• 用户安装后，使用 ~/.config/wxbot 配置目录。
• 系统安装后，使用 /etc/wxbot 配置目录。

便携运行指直接 ./wxbot 运行。
用户安装指执行 ./wxbot daemon install 安装到 ~/.local/bin 中。
系统安装指执行 ./wxbot daemon install --system 安装到 /usr/local/bin 中。

服务安装与更新

./wxbot daemon install
wxbot status

# 重启
wxbot daemon restart

# 更新
wxbot daemon stop
./wxbot daemon install
wxbot status

常见问题

• 闪退，可能是端口占用，可以改config配置内的端口，以及看logs日志。

• 收不到send的信息，需要微信先发一次消息刷新token。

• 改了配置没反应，改完需要重启应用，安装后可以使用 wxbot daemon restart 重启。

• handlers/codex-handler.py 运行没反应，一是慢，二是daemon安装与用户安装的环境不同，可以使用 wxbot logs -f 查看日志。

AI 说明

除非用户明确要求，AI 不应修改本文件。

用户要求修改后，AI 仅可以在本次回合中修改（仅能修改一次，下次仍需用户许可）。

AI 发现本文档的问题时，应当指出问题，而不是直接修改。

详细架构和协议说明见 DESIGN.md。

AI 发现DESIGN文档的问题、可改进建议时，应该中止任务向用户确认。

License

MIT