README に戻る

WeCom

PicoClaw は WeCom を公式 WeCom AI Bot WebSocket API に基づく単一の channels.wecom チャンネルとして公開します。従来の wecom、wecom_app、wecom_aibot の分割を統一された設定モデルに置き換えました。

パブリックな Webhook コールバック URL は不要です。PicoClaw は WeCom へのアウトバウンド WebSocket 接続を確立します。

サポートされる機能

ダイレクトチャットとグループチャット
WeCom AI Bot プロトコルによるチャンネル側ストリーミング返信
テキスト、音声、画像、ファイル、動画、ミックスメッセージの受信
テキストおよびメディア返信の送信（image、file、voice、video）
Web UI または CLI による QR コードオンボーディング
共有許可リストと reasoning_channel_id ルーティング

クイックスタート

オプション 1：Web UI QR バインディング（推奨）

Web UI を開き、Channels → WeCom に移動して、QR バインディングボタンをクリックします。WeCom で QR コードをスキャンし、アプリ内で確認すると、認証情報が自動的に保存されます。

オプション 2：CLI QR ログイン

実行：

bash

picoclaw auth wecom

コマンドの動作：

WeCom に QR コードをリクエストし、ターミナルに表示します
ターミナルの QR コードがスキャンしにくい場合に備え、ブラウザで開ける QR コードリンク も表示します
確認をポーリングします — スキャン後、WeCom アプリ内でログインを確認 する必要があります
成功すると、bot_id と secret を channels.wecom に書き込み、設定を保存します

デフォルトのタイムアウトは 5 分 です。--timeout で延長できます：

bash

picoclaw auth wecom --timeout 10m

⚠️ QR コードのスキャンだけでは不十分です — WeCom アプリ内で確認をタップする必要があります。そうしないとコマンドがタイムアウトします。

オプション 3：手動設定

WeCom AI Bot プラットフォームから bot_id と secret を既にお持ちの場合、直接設定できます：

json

{
  "channel_list": {
    "wecom": {
      "enabled": true,
      "type": "wecom",
      "bot_id": "YOUR_BOT_ID",
      "secret": "YOUR_SECRET",
      "websocket_url": "wss://openws.work.weixin.qq.com",
      "send_thinking_message": true,
      "allow_from": [],
      "reasoning_channel_id": ""
    }
  }
}

設定

フィールド	型	デフォルト	説明
`enabled`	bool	`false`	WeCom チャンネルを有効にする。
`bot_id`	string	—	WeCom AI Bot 識別子。有効時に必須。
`secret`	string	—	WeCom AI Bot シークレット。`.security.yml` に暗号化して保存。有効時に必須。
`websocket_url`	string	`wss://openws.work.weixin.qq.com`	WeCom WebSocket エンドポイント。
`send_thinking_message`	bool	`true`	ストリーミング返信の開始前に `Processing...` メッセージを送信する。
`allow_from`	array	`[]`	送信者許可リスト。空の場合はすべての送信者を許可。
`reasoning_channel_id`	string	`""`	推論・思考出力を別の会話にルーティングするためのオプションのチャット ID。

環境変数

すべてのフィールドは PICOCLAW_CHANNELS_WECOM_ プレフィックスの環境変数で上書きできます：

環境変数	対応フィールド
`PICOCLAW_CHANNELS_WECOM_ENABLED`	`enabled`
`PICOCLAW_CHANNELS_WECOM_BOT_ID`	`bot_id`
`PICOCLAW_CHANNELS_WECOM_SECRET`	`secret`
`PICOCLAW_CHANNELS_WECOM_WEBSOCKET_URL`	`websocket_url`
`PICOCLAW_CHANNELS_WECOM_SEND_THINKING_MESSAGE`	`send_thinking_message`
`PICOCLAW_CHANNELS_WECOM_ALLOW_FROM`	`allow_from`
`PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_ID`	`reasoning_channel_id`

ランタイム動作

PicoClaw はアクティブな WeCom ターンを維持し、可能な限り同じストリームでストリーミング返信を継続します。
ストリーミング返信の最大持続時間は 5.5 分、最小送信間隔は 500ms です。
ストリーミングが利用できなくなった場合、返信はアクティブプッシュ配信にフォールバックします。
チャットルートの関連付けは 30 分 の非アクティブ後に期限切れになります。
受信メディアはエージェントに渡される前にローカルメディアストアにダウンロードされます。
送信メディアは WeCom に一時ファイルとしてアップロードされ、メディアメッセージとして送信されます。
重複メッセージは検出され抑制されます（最新 1000 件のメッセージ ID のリングバッファ）。

レガシー WeCom 設定からの移行

以前の設定	移行方法
`channels.wecom`（Webhook ボット）	`bot_id` + `secret` を使用する `channels.wecom` に置き換える。
`channels.wecom_app`	削除して `channels.wecom` を使用する。
`channels.wecom_aibot`	`bot_id` と `secret` を `channels.wecom` に移動する。
`token`、`encoding_aes_key`、`webhook_url`、`webhook_path`	使用されなくなりました。設定から削除してください。
`corp_id`、`corp_secret`、`agent_id`	使用されなくなりました。設定から削除してください。
`welcome_message`、`processing_message`、`max_steps`	WeCom チャンネル設定の一部ではなくなりました。

トラブルシューティング

QR バインディングがタイムアウトする

QR コードをスキャンした後、WeCom アプリ内でログインを確認 する必要があります。スキャンだけでは不十分です。
より長い --timeout で再実行してください：picoclaw auth wecom --timeout 10m
ターミナルの QR コードがスキャンしにくい場合は、その下に表示される QR コードリンク を使用してブラウザで開いてください。

QR コードの有効期限切れ

QR コードには有効期限があります。picoclaw auth wecom を再実行して新しいものを取得してください。

WebSocket 接続の失敗

bot_id と secret が正しいことを確認してください。
ホストが wss://openws.work.weixin.qq.com に到達できることを確認してください（アウトバウンド WebSocket、インバウンドポートは不要）。

返信が届かない

allow_from が送信者をブロックしていないか確認してください。
channels.wecom.bot_id と channels.wecom.secret が設定されており、空でないことを確認してください。