ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

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 / timeout
  • done の時点で認証情報は自動的に設定へ書き込まれており、レスポンスには 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秒)