Skip to main content
Glama
Yero-413

wechat-clawbot-push

by Yero-413
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

wechat-clawbot-push

让自动化任务的结果不再困在电脑里 —— 直接推到你手机微信。

一个符合 MCP(stdio) 协议的服务器。注册为 WorkBuddy 连接器后，自动化 / 定时任务的结果 可以主动推送到用户自己的个人微信。无需企业微信，无需抓包。

✅ 它不占你的微信名额：默认复用 WorkBuddy 那只 bot

微信侧的「ClawBot」名额只有一个，重复扫码授权会顶掉上一次授权 —— 所以本包默认 不新建 bot。它直接复用 WorkBuddy 已绑定的那只，用同一套凭证推送 （2.0.4 起，2026-09-30 实测确认）。

于是两者可以并存：

能力

状态

在微信里跟 AI 对话（WorkBuddy 自带连接）

不受影响

自动化结果主动推送到微信（本包）

可用

微信里的 ClawBot 联系人

仍然只有一个

前提：你已在 WorkBuddy 里绑定过微信连接。如果还没绑，先去 WorkBuddy 设置里绑定 —— 那也是唯一一次扫码，本包不需要再扫。

⚠️ 不要轻易跑 --login：它会为桥单独申请一只 bot，占掉唯一名额，把 WorkBuddy 的微信 连接顶掉（原生双向随即失效）。只有确实需要桥用独立身份时才这么做，且要清楚代价。 检测到你已有绑定时，--login 会先打印警告再继续。

想关掉复用、强制用桥自己的 bot：在 config.json 里设 "reuse_wb_bot": false。

Related MCP server: wx4py-mcp

它不是什么

  • 单向通道：只能「WorkBuddy → 你的微信」，不能接收你的消息，也无法实现微信内对话

  • 不是聊天机器人：你给它发消息，它不会回

  • 不替代 WorkBuddy 自带的微信连接 —— 它搭在同一次绑定上，是那个连接的「出口」

安装

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple wechat-clawbot-push==2.0.5
# 或本地源码安装
pip install .

加 -i 是因为国内部分镜像（如阿里云）同步可能滞后数小时以上。不加的话， 指定版本会报 No matching distribution found，不指定版本则会静默装上旧版 （旧版缺少网络容错，表现为推送时 TLS 握手卡死）。

快速交接：给使用者的三步

前提：你已在 WorkBuddy 里绑定过微信连接（设置 → 微信）。这是唯一的扫码， 本包不再需要扫码 —— 它直接复用那只 bot，不占名额。

1️⃣ 装

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple wechat-clawbot-push==2.0.5

2️⃣ 注册成连接器

编辑 ~/.workbuddy/mcp.json：

{
  "mcpServers": {
    "wechat-clawbot-push": {
      "command": "wechat-clawbot-push",
      "args": ["--mcp"]
    }
  }
}

重启 WorkBuddy → 连接器管理页点「信任」→ 新任务的工具列表里出现 push_wechat_message。

3️⃣ 自检

wechat-clawbot-push --diag

看到 模式：复用 WorkBuddy 的 bot（不占名额） 就成了。再试推一条：

wechat-clawbot-push --test "hello"

然后怎么用：在对话里说「把结果推到我微信」，或建自动化任务并在 prompt 里写明 「结果用微信推送工具发给我」。触发端在 WorkBuddy，不是在微信里给 bot 发消息。

⚠️ 两条最容易踩的：

  • 别跑 --login —— 它会为桥单独申请一只 bot，把 WorkBuddy 的微信连接顶掉

  • 别把 config.json 发出去 —— 里面的 bot_token 等于你的微信推送权限

怎么用：触发端在 WorkBuddy，不在微信

本包只负责「送出去」，触发它的是 WorkBuddy：

  • 在对话里直接说「把结果推到我微信」

  • 或建自动化任务，在 prompt 里写明「结果用微信推送工具发给我」

直接给微信里的 bot 发「帮我建个自动化任务」是没有用的 —— bot 不是 WorkBuddy 的输入口。

作为 WorkBuddy 连接器使用

在 ~/.workbuddy/mcp.json 注册（command 指向你的 python，args 用 -m）：

{
  "mcpServers": {
    "wechat-clawbot-push": {
      "command": "python",
      "args": ["-m", "wechat_clawbot_push", "--mcp"]
    }
  }
}

或安装后直接用 console script：

{
  "mcpServers": {
    "wechat-clawbot-push": {
      "command": "wechat-clawbot-push",
      "args": ["--mcp"]
    }
  }
}

复用模式是怎么取到凭证的

WorkBuddy 绑定微信后，会把当前 bot 的凭证写进运行时状态目录：

~/.workbuddy/claw-state/weixin/<bot_id>_im.bot.cursor.json

里面的 get_updates_buf 是 base64，解码后含完整的 <bot_id>@im.bot:060000<hex>，与桥自己 config.json 里的 bot_token 同格式。桥只读这个文件（取 mtime 最新的那个 —— WorkBuddy 重新绑定后 bot_id 会变），不写入，也不碰 WorkBuddy 自己的轮询游标。

⚠️ 这依赖 WorkBuddy 的内部文件结构，不是公开 API：WorkBuddy 改了路径或格式，复用模式就会 失效。此时桥会自动回落到 config.json / settings.json 里的凭证，或提示你扫码。

想让桥用独立身份时才需要的扫码登录

默认不需要这一步。仅当你确实要让桥用一只单独的 bot （代价：占掉唯一名额，WorkBuddy 的微信连接会被顶掉）：

python -m wechat_clawbot_push --login

程序会打开二维码地址。使用微信扫码，若手机要求验证码，就把验证码输入回终端。登录成功后， 凭证会保存到 ~/.workbuddy/wechat-clawbot-push/config.json。 请不要把这个文件或 bot_token 发到群聊、日志或 issue 中。

暴露的工具

工具

作用

push_wechat_message(text[, auto_acquire])

主动推送一条文本到用户个人微信（默认复用 WorkBuddy 的 bot，context_token 可缺省）

acquire_token()

获取/刷新 context_token（长轮询，需手机给 bot 发一条消息）

bridge_status()

返回当前 token 状态，供自动化推送前自检

首次授权（多数情况下可跳过）

2.0.4 起不再强制：实测 iLink 在缺省 context_token 时会把消息投递到最近活跃会话， 所以装好就能直接推送。

若你希望推送落在指定会话上，再执行一次 acquire_token：手机给 bot 发一条普通文本消息， 脚本捕获并缓存 context_token。不需要退出 WorkBuddy。

这里有两个容易混淆的 token：bot_token 是账号鉴权凭证，context_token 是会话上下文凭证。 后者会过期或在重新连接后变化，不能当作永久 token。发送失败且服务端返回 ret=-2 或 errcode=-14 时，桥会自动尝试读取新入站消息刷新上下文，然后重试；新版 iLink 还会尝试 省略过期的 context_token，使用最近活跃会话发送。

如果 WorkBuddy 的 settings.json 版本变化导致自动读取不到账号凭证，可以在 ~/.workbuddy/wechat-clawbot-push/config.json 中显式配置（文件权限请保持仅当前用户可读）：

{
  "bot_token": "bot_id:secret"
}

也可以使用环境变量 WECHAT_BOT_TOKEN。桥不会解密或绕过 WorkBuddy 的加密凭证；如果文件中 保存的确实是不可逆的密文，应该从 WorkBuddy 的已连接配置或官方二维码登录流程重新取得 bot_token，而不是把 context_token 当作替代品。

协议契约（已核对腾讯官方 iLink / OpenClaw）

  • 收消息：POST https://ilinkai.weixin.qq.com/ilink/bot/getupdates

  • 发消息：POST https://ilinkai.weixin.qq.com/ilink/bot/sendmessage

  • 鉴权：Authorization: Bearer {bot_id:secret}（优先复用 WorkBuddy 运行时状态里的凭证，其次 config.json / settings.json）

  • 主动发优先带回最近一次入站消息的 context_token；会话失效时自动刷新或尝试省略该字段

  • --login 使用官方 get_bot_qrcode / get_qrcode_status 流程获取独立 bot_token

命令行

  • --mcp：stdio MCP 服务模式（主用）

  • --login：扫码登录，生成桥独立的 bot_token（默认不需要，会顶掉 WorkBuddy 的微信连接）

  • --refresh：acquire_token 一次，用于获取 context_token

  • --diag：自检，逐层打印凭证 / 会话 / 代理 / DNS / 链路状态

  • --test "文本"：手动推送一条

网络容错

DNS 轮询可能返回「TCP 能建连、TLS 握手却卡死」的地址，而 socket.create_connection 只在建连失败时才换下一个 IP，握手卡死不会触发轮换，于是上层只能干等超时。 因此 ilink_post 采用三程选路：

  1. 复用上次可用 IP（持久化在 ip_cache.json），传完整超时以保住长轮询等待窗口

  2. 常规通路（保留现有代理设置），首探短超时以便快速失败

  3. 解析全部 IPv4 逐个直连重试，SNI 与 Host 仍用原域名

遇到推送异常时先跑 --diag：它会把「连不上」和「没人发消息」这两种表现相同、 成因完全不同的情况区分开。

实现说明（stdio 铁律）

  • stdout 仅输出 newline-delimited JSON-RPC 消息；所有日志走 stderr

  • 二进制缓冲 + UTF-8 编解码，规避 Windows GBK 中文乱码

  • 运行态（token/缓存）写入用户级目录 ~/.workbuddy/wechat-clawbot-push/，与安装位置无关、多用户隔离

License

MIT

Available Tools

3 tools
acquire_tokenA

获取/刷新 context_token（长轮询，约 35 秒内需用手机给 bot 发一条消息以完成绑定）。推送前若 bridge_status 显示未获取 token，应先调用本工具。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and discloses important behavior: it uses long polling, requires the user to send a message to the bot within ~35 seconds to complete binding, and must precede push operations. It does not mention failure behavior or what happens on timeout, but the key interactive traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is one dense, front-loaded sentence. It places the core action first, then provides the essential operational constraint and the ordering rule, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description covers the main operational context: binding requirement, timeout window, and relationship to bridge_status and push. It could add what is returned or what happens on timeout, but this is not critical for selecting and invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the default baseline of 4 applies. The schema already fully represents the empty input; no additional parameter explanation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action: obtaining or refreshing context_token, and adds the distinctive long-polling/binding behavior. This differentiates it from sibling tools like bridge_status and push_wechat_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly gives a usage condition: call this tool before pushing when bridge_status shows no token has been acquired. This effectively tells the agent when to invoke it and implies it is unnecessary once a valid token exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bridge_statusA

返回推送桥当前状态：是否已缓存 context_token、目标用户微信id。供自动化推送前自检。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a status (cached or not), implying a read-only operation. However, it does not explicitly state non-destructiveness, whether any side effects occur, or the exact return format. Given the simplicity, it adds some value but lacks explicit behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the key information (what is returned) and then states its purpose. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema status check tool, the description covers the essential purpose and when to use it. It does not detail the exact format of the status (e.g., boolean vs. object), but the phrasing '是否已缓存' (whether cached) implies a boolean-like response. Given the tool's simplicity, it is sufficiently complete for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is trivially 100%. The description does not need to explain parameters. Per rubric, baseline for 0 params is 4, and the description appropriately omits parameter details since there are none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (返回/returns), resource (推送桥当前状态/current status of the push bridge), and specifically what it returns (whether context_token and target user WeChat ID are cached). It also mentions its purpose (pre-push self-check), which distinguishes it from siblings push_wechat_message and acquire_token.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear usage context: '供自动化推送前自检' (for self-check before automated push). This tells an agent when to use it, but it does not explicitly state exclusions or alternatives to siblings. However, the purpose is unambiguous enough to guide selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

push_wechat_messageA

向用户【个人微信】(ClawBot)主动推送一条文本消息。发送前自动验证 context_token：已获取则直接推送；未获取或已失效则返回明确指引，提示先调用 acquire_token 并在手机给 bot 发消息。供 WB 自动化在定时/触发任务完成后调用，把结果推送到用户微信。

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes要推送到微信的文本内容
auto_acquireNo可选。token 缺失时是否自动尝试获取(会阻塞等待手机消息，默认 false)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool automatically validates context_token before sending, and details the two branches (valid → push directly; invalid → return guidance to call acquire_token and send a message to the bot). This goes beyond the bare 'push' action and covers the prerequisite flow, which is valuable behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, information-dense paragraph. It front-loads the core action and then explains the token validation logic and usage context. No fluff, but it could be slightly more compact; still well-structured and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main flow (token validation, usage context) but does not describe the return value on successful push, nor does it mention the auto_acquire parameter (even though the schema covers it). For a simple 2-parameter tool with no output schema, the missing success-return specification is a minor gap, so it's adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% as both 'text' and 'auto_acquire' have descriptions in the schema. The description does not add additional meaning beyond what the schema already provides; it mentions token validation but does not elaborate on parameter specifics. Baseline of 3 is appropriate when schema fully documents parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('push') and resource ('text message to user's personal WeChat/ClawBot'), and specifies the scope ('WB automation after scheduled/triggered tasks'). It differentiates from siblings by explicitly referencing acquire_token as a prerequisite and describing the token validation flow, making it unmistakable which tool this is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context: 'for WB automation after scheduled/triggered tasks' and explicitly states that if the token is missing/expired, one should call acquire_token first. While it doesn't mention bridge_status, the usage scenario and interaction with acquire_token are clearly outlined, providing sufficient guidance for when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv2.0.1
    • First observedacquire_token
    • First observedbridge_status
    • First observedpush_wechat_message
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool maps to a distinct step in the push workflow: checking bridge/token state, acquiring/refreshing the token, and sending the message. There is no overlap or ambiguity between them.

Naming Consistency4/5

Two tools use a clear verb_noun pattern (push_wechat_message, acquire_token), while bridge_status is a noun phrase that would be more consistent as get_bridge_status. Minor deviation, but the naming is still predictable and readable.

Tool Count5/5

Three tools is exactly right for this narrow purpose: preflight status, token acquisition, and sending. Every tool serves a necessary role in the workflow with no redundancy.

Completeness5/5

The lifecycle is complete: check status, acquire token if needed, then push; push_wechat_message also self-verifies the token, avoiding dead ends. There are no obvious missing operations for the stated text-push use case.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers