WeChat ClawBot(WechatClaw)アダプター - プラットフォーム機能ドキュメント
基本情報
- モジュール名:
ErisPulse-WechatClaw - プラットフォーム識別子:
wechatclaw - モジュールバージョン: 0.1.0
- メンテナー: wsu2059q
- 最終更新: 2026-11-17
- 依存関係:
qrcode、pycryptodome
プラットフォームの位置づけ
テンセント公式 iLink Bot API(WeChat ClawBot ボットチャネル)に基づく WeChat 個人アカウント接続アダプター:QRコードスキャンによるバインド、トークンの自動書き戻し、ロングポーリングによる受信。公式のコンプライアントなチャネルであり、リバースエンジニアリングによるプロトコルではありません。機能範囲は WeChat 公式の開放内容に準じます。
接続とバインディング
token設定を空のままにした場合、アダプターの起動時にログイン用QRコードが出力されます(ターミナル上のASCIIアート + リンクによるフォールバック)。スマートフォンのWeChatでQRコードをスキャンして確認すると、バインディングが完了します- ダッシュボードパネルでのQRスキャン(推奨):アダプターは「アカウント追加ウィザード」に「WeChat QRスキャンログイン」拡張エリアを登録し、パネル内で直接QRコードをスキャンしてバインドできます(bilibiliアダプターのパネルQRスキャン規約に準拠)
- バインド成功後、
token/bot_user_id/base_urlはフレームワークのロスレスTOMLエンジンにより自動的にconfig.tomlに書き戻されます(ユーザーのコメントは保持されます)。再起動時の再スキャンは不要です - トークンが無効になった場合(ロングポーリングが401/403を返したとき)、ログには「token をクリアして再スキャン」と明示されます
QRスキャンログインエンドポイント(サードパーティフロントエンドとの連携可能)
アダプターは起動時に POST /wechatclaw/qr/start と POST /wechatclaw/qr/poll を登録します:
qr/start:QRコードを取得し、{success, task_id, poll_token, qr_img}を返します(qr_imgはSVG data URI)qr/poll:リクエストにはtask_id+poll_tokenを含める必要があります(未認可のポーリング防止、欠落時は403を返します)。{success, status}を返し、status ∈pending/scan/done/timeoutdoneの時点で認証情報は自動的に設定へ書き込まれており、レスポンスにはaccountが付属します
標準化の整合
イベントとレスポンスは イベント変換標準 と API レスポンス規範 に従います。
- メッセージイベントのトップレベルには標準の
message_idが含まれます(公式の message_id を使用し、欠落時は client_id/seq にフォールバック) - イベントの
idにはアカウント次元が含まれ({bot_id}:{message_id})、冪等な重複排除とアカウント間の分離はフレームワークが処理します - 送信は標準レスポンスを返します:
status/retcode/data/message_id/message+ トップレベルのwechatclaw_raw
メッセージイベント
- イベントタイプ:
message/private(公式チャネルは個人アカウントのダイレクトメッセージであり、グループチャット機能はありません) - 受信メッセージセグメント:
text、image、voice、file、video - メディアセグメントはファイルをディスクに書き出しません:
wechatclaw_cdn(CDN 記述 + キー)を保持し、call_api("download_media")により必要に応じてダウンロード・復号します
コンテキストトークンと返信
プロトコルは返信に context_token の付与を要求します(受信したメッセージと共に配布されます)。アダプターはユーザーごとに最新のコンテキストをキャッシュします:
- イベントチェーン内の返信(
event.reply()/Send.To("user", ...))は自動的にそのユーザーのコンテキストを付与します - 能動的なダイレクトメッセージはプロトコルの制限を受けます:会話コンテキストのないユーザーはプラットフォームに拒否される可能性があります(レスポンスの errcode でフィードバックされます)
サポートされるメッセージ送信タイプ
| メソッド | 説明 | 公式 API |
|---|---|---|
Text(text) |
テキストを送信(Markdown は自動的にプレーンテキストへフォールバック) | sendmessage |
Image(file) |
画像を送信(URL/パス/base64:///bytes、自動暗号化アップロード) | getuploadurl + CDN |
Video(file) |
動画を送信 | 同上 |
File(file) |
ファイルを送信 | 同上 |
Voice(file) |
音声を送信(SILK エンコードのみ。その他の音声はファイルメッセージとしてフォールバック) | 同上 |
Reply(message_id) |
引用返信(引用対象はこの会話で最後に受信したメッセージ) | sendmessage + ref_msg |
mention/atセグメントは個人アカウントのダイレクトメッセージでは意味を持たないため、送信時にサイレントに無視されます。
拡張 API(call_api)
| エンドポイント | パラメータ | 説明 |
|---|---|---|
download_media |
media(受信メディアセグメントの wechatclaw_cdn) |
ダウンロードして復号しディスクに保存、data.path でローカルパスを返す |
send_typing |
user_id、オプションで status(1=入力中 2=キャンセル) |
「入力中」ステータス(有効なセッションコンテキストが必要) |
プラットフォームの制限
- ダイレクトメッセージのみ(公式チャンネルではグループチャットに対応していない)
- 一部の動画メッセージには復号鍵が欠落している場合がある(公式チャンネルの既知の問題)。該当するメディアはダウンロード不可
- 音声には SILK エンコーディングが必要(encode_type=6、24kHz)
設定リファレンス
| 設定項目 | デフォルト値 | 説明 |
|---|---|---|
token |
"" | 空欄のままにするとQRコードスキャンでログイン、連携後に自動的に書き戻されます |
bot_user_id |
"" | 公式アカウントID、連携後に自動的に書き戻されます |
base_url |
公式デフォルト | APIベースURL、連携後に自動更新される場合があります |
login_timeout |
300 | QRコードスキャンの待機時間(秒) |
poll_interval |
1.0 | ロングポーリングのバッチ間隔(秒、サーバー側の1回のホールドは約35秒) |