Communitygithub.com

lroolle/wxclawbot-cli

Weixin ClawBot CLI - 為 OpenClaw Agent 提供主動推送訊息的能力

wxclawbot-cli 是什麼?

這個技能為 AI Agent(如 Claude Code、Coder 或任何使用 OpenClaw 架構的 Agent)提供了一個 CLI 工具,使其能夠主動向微信使用者推送訊息,而不僅僅是被動回應。它支援文字、圖片、影片和檔案等多種格式的訊息發送。更重要的是,它實現了真正的「推送」——透過自動管理微信要求的 `context_token`,確保訊息能夠主動通知使用者,而不需要使用者先打開聊天視窗。它還支援 cron 整合,可用於定時提醒、監控告警報和自動報告分發等場景。此 CLI 工具會自動從 `~/.openclaw/openclaw-weixin/accounts/` 目錄發現並管理微信帳號,也支援透過環境變數覆蓋設定。對於程式化整合,必須使用 `--json` 參數來獲取可解析的輸出,並依據 `ok` 欄位判斷訊息是否成功送達,而不僅僅是 CLI 的 exit code。它還提供了詳細的錯誤處理指南,包括頻率限制(`ret=-2`)、會話過期(`ret=-14`)和結構化傳輸錯誤訊息,幫助開發者建構穩健的推送邏輯。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add lroolle/wxclawbot-cli

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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>指定帳號。預設: 第一個可用的
--jsonJSON 格式輸出。程式呼叫必須帶上
--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
dnsDNS 解析失敗true
connection連線重置 / socket hang uptrue
network連線被拒 / 主機不可達 / fetch failedtrue
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。

相關技能