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。デフォルト: 最初に利用可能なもの |
--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(能動的プッシュの鍵)
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 |
dns | DNS解決失敗 | true |
connection | 接続リセット / socket hang up | true |
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_TOKEN | bot tokenを上書き ([email protected]:your-token) |
WXCLAW_BASE_URL | APIエンドポイントを上書き (デフォルト: https://ilinkai.weixin.qq.com) |
プログラミングAPIの詳細は references/programmatic-api.md を参照してください。