Communitygithub.com

lroolle/wxclawbot-cli

Weixin ClawBot CLI - OpenClawエージェント向けプッシュ通知ツール

wxclawbot-cli とは?

このスキルは、WeChatボット(iLink Bot)が抱える「ユーザーの返信待ちしかできない」という制限を解消します。`wxclawbot` CLIを通じて、エージェントがテキスト、画像、動画、ファイルをWeChatユーザーに能動的にプッシュできるようになります。特に、cronと組み合わせることで、定期リマインダー、アラート通知、レポート配信といった能動的なシナリオを実現できます。Node.js 20以上が必要で、`npm install -g @claw-lab/wxclawbot-cli`でインストールします。認証情報は`~/.openclaw/openclaw-weixin/accounts/`から自動検出され、`--json`フラグを付けることでプログラミングによる連携が容易になります。内部では、WeChatの`context_token`を使用してメッセージを即座に配信し、レート制限(ボットあたり約7件/5分)やエラーハンドリングも充実しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add lroolle/wxclawbot-cli

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

wxclawbot-send

このスキルが解決する問題

WeChatボット(iLink Bot)は、ユーザーからのメッセージに受動的に返信するだけで、能動的に会話を開始することはできません。 つまり、エージェントは定期リマインダー、アラート通知、レポート送信などの能動的な処理を行えません。

このスキルは、wxclawbot CLIを使用して、エージェントがWeChatユーザーに能動的にメッセージをプッシュできるようにします。 テキスト、画像、動画、ファイルに対応しており、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>使用するアカウント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(能動的プッシュの鍵)

WeChatが能動的にメッセージをプッシュするには context_token が必要です。これがないと、メッセージはサーバーに留まり、 ユーザーがチャットウィンドウを開くまで見ることができません。これでは「能動的プッシュ」とは言えません。

CLIは自動的に {accountId}.context-tokens.json(アカウントファイルと同じディレクトリ)を読み取ります。 このファイルはopenclaw-weixinによって管理され、userId → contextToken のマッピング形式です。 手動での設定は不要です。ユーザーがボットにメッセージを送信すると、openclaw-weixinが自動的に保存します。

context_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レート制限(ボットあたり約7件/5分、全クライアント共有)60〜120秒待ってリトライ。紧密ループは避ける
ret=-14セッションの期限切れopenclawで再ログイン
No account found認証情報が不足wxclawbot accounts で確認
CDN upload errorファイルアップロード失敗ファイルサイズ/形式を確認し、リトライ
Request timeoutネットワーク問題(15秒タイムアウト)リトライ

レート制限はサーバー側で行われ、同じボットトークンを持つすべてのクライアントで共有されます。

構造化トランスポートエラー (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失敗true
tls証明書またはTLSエラーfalse
unknown分類不能なエラーfalse

retryable フィールドを使用して、リトライすべきか直接失敗させるかを判断します。

よくある落とし穴

  • 必ず --json を使う —— 付けないと人間が読める形式で出力され、パースできません
  • ok フィールドを確認する —— exit 0 はCLIが実行されただけで、メッセージが届いたわけではありません
  • ret=-2 で緊密ループリトライしない —— 最低5〜10秒待つ
  • 大きなテキストはstdinを使う —— echo "..." | wxclawbot send --json。シェルの引用符問題を回避
  • ファイルは暗号化されてWeChat CDNにアップロードされる —— 大きなファイルは時間がかかる場合があります

環境変数

変数用途
WXCLAW_TOKENbot tokenを上書き ([email protected]:your-token)
WXCLAW_BASE_URLAPIエンドポイントを上書き (デフォルト: https://ilinkai.weixin.qq.com)

プログラミングAPIの詳細は references/programmatic-api.md を参照してください。

関連スキル