wxclawbot-send
這個技能解決什麼問題
微信機器人(iLink Bot)只能被動回覆使用者訊息,不能主動發起對話。 這意味著 agent 沒法做定時提醒、告警推送、報告發送等主動觸達場景。
這個技能透過 wxclawbot CLI 讓 agent 能主動給微信使用者推送訊息,
包括文字、圖片、影片、檔案。配合 cron 可實現定時任務。
前置條件
- Node.js >= 20
npm install -g @claw-lab/wxclawbot-cli- openclaw-weixin 已登入(憑證在
~/.openclaw/openclaw-weixin/accounts/)
驗證: wxclawbot accounts --json
快速上手
wxclawbot send --text "訊息內容" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "請查收" --json
什麼時候用什麼
主動發文字訊息 → wxclawbot send --text "msg" --json
主動發檔案/圖片 → wxclawbot send --file ./path --json
檢查帳號狀態 → wxclawbot accounts --json
程式呼叫 → see references/programmatic-api.md
命令參考
send
wxclawbot send --text "message" --json
wxclawbot send --to "[email protected]" --text "你好" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "請查收" --json
wxclawbot send --file "https://example.com/img.png" --json
echo "日報已產生" | wxclawbot send --json
wxclawbot send --text "test" --dry-run
| 參數 | 說明 |
|---|---|
--text <msg> | 訊息文字。"-" 明確讀取 stdin |
--file <path> | 本地檔案或 URL(圖片 / 影片 / 檔案) |
--to <userId> | 目標使用者 ID。預設: 帳號綁定使用者 |
--account <id> | 指定帳號。預設: 第一個可用的 |
--json | JSON 格式輸出。程式呼叫必須帶上 |
--dry-run | 預覽,不發送 |
媒體類型按副檔名自動識別:
- 圖片: .png .jpg .jpeg .gif .webp .bmp
- 影片: .mp4 .mov .webm .mkv .avi
- 檔案: 其他所有
accounts
wxclawbot accounts --json
回傳: [{"id":"<botId>-im-bot","configured":true,"baseUrl":"..."}]
帳號發現機制
CLI 自動從 ~/.openclaw/openclaw-weixin/accounts/*.json 發現帳號。
每個檔案包含 token, baseUrl, userId(預設 --to 目標)。
- Bot ID 從 token 執行時提取(不是寫死的)
- 帳號 ID 會在 openclaw-weixin 升級或重新註冊後變化
--to預設是帳號檔案裡的userId(綁定使用者)- 設了
WXCLAW_TOKEN環境變數會覆蓋檔案發現
Context Token(主動推送關鍵)
微信要求 context_token 才能主動推送訊息。沒有它,訊息會留在伺服器上,
直到使用者主動開啟聊天視窗才能看到——這就不叫「主動推送」了。
CLI 自動讀取 {accountId}.context-tokens.json(和帳號檔案同目錄)。
這個檔案由 openclaw-weixin 維護,格式是 userId → contextToken 的對應。
不需要手動配置——使用者給機器人發過訊息後 openclaw-weixin 會自動儲存。
如果 context_token 缺失(新使用者、token 過期),訊息仍然會發送成功
(ok:true),但不會主動推送通知。
升級 openclaw-weixin 後,務必用 wxclawbot accounts --json 驗證。
Agent 整合
程式呼叫必須用 --json。解析 JSON 判斷是否成功。
result=$(wxclawbot send --text "任務完成" --json)
result=$(wxclawbot send --file ./chart.png --text "每日指標" --json)
- 成功:
{"ok":true,"to":"[email protected]","clientId":"..."} - 失敗:
{"ok":false,"error":"..."} - 退出碼: 0 = CLI 執行成功, 1 = 失敗
注意: exit 0 只代表 CLI 跑完了,不代表訊息送達。看 ok 欄位。
錯誤處理
| 錯誤 | 含義 | 處理 |
|---|---|---|
ret=-2 | 頻率限制(每個 bot 約 7 條 / 5 分鐘,所有用戶端共享) | 等 60-120 秒重試,別做緊湊迴圈 |
ret=-14 | 會話過期 | 透過 openclaw 重新登入 |
| No account found | 憑證缺失 | 執行 wxclawbot accounts 排查 |
| CDN upload error | 檔案上傳失敗 | 檢查檔案大小 / 格式,重試 |
| Request timeout | 網路問題(15 秒超時) | 重試 |
頻率限制是伺服器端的,同一個 bot token 下所有用戶端共享配額。
結構化傳輸錯誤 (v0.5.1+)
--json 模式下,傳輸層失敗會包含額外欄位:
{"ok":false,"error":"send failed: ...","errorKind":"timeout","retryable":true}
errorKind | 含義 | retryable |
|---|---|---|
timeout | 請求超過 15 秒 | true |
dns | DNS 解析失敗 | true |
connection | 連線重置 / socket hang up | true |
network | 連線被拒 / 主機不可達 / fetch failed | true |
tls | 憑證或 TLS 錯誤 | false |
unknown | 未分類錯誤 | false |
用 retryable 欄位判斷應該重試還是直接失敗。
常見陷阱
- 必須用
--json—— 不帶的話輸出的格式是人類可讀的,沒法解析 - 看
ok欄位 —— exit 0 只代表 CLI 跑了,不代表訊息到了 - 別緊湊迴圈重試
ret=-2—— 至少等 5-10 秒 - 大段文字用 stdin ——
echo "..." | wxclawbot send --json,避免 shell 引號問題 - 檔案會加密上傳到微信 CDN —— 大檔案可能要等一會
環境變數
| 變數 | 用途 |
|---|---|
WXCLAW_TOKEN | 覆蓋 bot token ([email protected]:your-token) |
WXCLAW_BASE_URL | 覆蓋 API 端點 (預設: https://ilinkai.weixin.qq.com) |
程式化介面詳見 references/programmatic-api.md。