Weixin（微信）

Hermes を、テンセントの個人向けメッセージングサービス WeChat（微信）につなぎます。このアダプターは個人の WeChat アカウント向けにテンセントの iLink Bot API を使います。WeCom（企業向け WeChat）とは別物です。メッセージはロングポーリングで届くので、公開エンドポイントや Webhook を用意する必要はありません。

事前に必要なもの

• 個人の WeChat アカウント
• Python パッケージ: aiohttp と cryptography
• Hermes を messaging エクストラ付きで入れると、ターミナルへの QR コード表示も一緒に入ります

必要な依存関係をインストールします。

pip install aiohttp cryptography
# Optional: for terminal QR code display
cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"

設定

1. セットアップウィザードを実行する

WeChat アカウントをつなぐいちばん簡単な方法は、対話式のセットアップです。

hermes gateway setup

選択肢が出たら Weixin を選びます。ウィザードは次の流れで進みます。

1. iLink Bot API に QR コードを要求する
2. ターミナルに QR コードを表示する（または URL を出す）
3. WeChat のスマホアプリで QR コードを読み取るのを待つ
4. スマホ側でログインを承認するよう促す
5. アカウントの認証情報を ~/.hermes/weixin/accounts/ へ自動保存する

承認が終わると、次のようなメッセージが出ます。

微信连接成功，account_id=your-account-id

ウィザードが account_id、token、base_url を保存するので、手作業で設定する必要はありません。

2. 環境変数を設定する

最初の QR ログインが済んだら、少なくともアカウント ID を ~/.hermes/.env に書きます。

WEIXIN_ACCOUNT_ID=your-account-id

# Optional: override the token (normally auto-saved from QR login)
# WEIXIN_TOKEN=your-bot-token

# Optional: restrict access
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# Optional: restore legacy multiline splitting behavior
# WEIXIN_SPLIT_MULTILINE_MESSAGES=true

# Optional: home channel for cron/notifications
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home

3. ゲートウェイを起動する

hermes gateway

アダプターが保存済みの認証情報を読み戻し、iLink API に接続して、メッセージのロングポーリングを始めます。

できること

• ロングポーリング通信 — 公開エンドポイント、Webhook、WebSocket のいずれも不要
• QR コードログイン — hermes gateway setup で読み取るだけの接続手順
• DM のやり取り — アクセス方針を設定可能。グループでのやり取りは、つないだ人格に対して iLink が実際にグループのイベントを届けるかどうか次第です（iLink ボットのアカウントでは届かないことが多い。上の警告を参照）
• メディア対応 — 画像、動画、ファイル、音声メッセージ
• AES-128-ECB 暗号化 CDN — すべてのメディア転送を自動で暗号化・復号
• コンテキストトークンの永続化 — ディスクに保存し、再起動をまたいで返信のつながりを保つ
• Markdown の書式 — 見出し、表、コードブロックを含めて Markdown をそのまま残すので、Markdown に対応した WeChat クライアントならそのまま表示できます
• 賢いメッセージ分割 — 上限内なら 1 つの吹き出しのまま。大きすぎるものだけを区切りのよい位置で分けます
• 入力中の表示 — エージェントが処理している間、WeChat クライアントに「入力中…」を表示します
• SSRF 対策 — 送信するメディアの URL をダウンロード前に検証します
• メッセージの重複排除 — 5 分間のスライディングウィンドウで二重処理を防ぎます
• バックオフ付きの自動再試行 — 一時的な API エラーから復帰します

設定できる項目

config.yaml の platforms.weixin.extra の下に書きます。

アクセス方針

DM の方針

だれがボットにダイレクトメッセージを送れるかを決めます。

WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

WEIXIN_ALLOWED_USERS は 受信側のフィルター であって、招待の仕組みではありません。QR ログインで Hermes につながるのは 1 つの iLink ボット人格です。ほかの人が自分のアカウントで Hermes の QR コードを読み取るわけではありません。つながっている iLink のボット／連絡先へ WeChat から話しかけてもらう形になり、Hermes が DM を処理するのは送信者の Weixin ユーザー ID が WEIXIN_ALLOWED_USERS にある場合だけです。

実際の手順は次のようになります。

1. hermes gateway setup で Hermes を一度ペアリングし、つながった iLink ボットの

アカウントを控えます。

1. 許可したい人それぞれに、そのボット／連絡先へダイレクトメッセージを送ってもらいます。
2. ゲートウェイのログか、受信したイベントの中身から送信者のユーザー ID を読み取ります。
3. その ID を WEIXIN_ALLOWED_USERS に追加し、ゲートウェイを再起動します。

QR コードを読み取ったアカウントとしか会話できない場合は、ほかの人が QR ログインに使った個人の WeChat アカウントではなく iLink のボット人格そのものへ話しかけているかを確認してください。iLink ボットは独立した人格で、普通の WeChat の連絡先やグループの経路はテンセントの iLink の挙動によって 制限されることがあります。

グループの方針

つないだ人格に対して iLink がグループのイベントを届ける場合に、ボットがどのグループで反応するかを決めます。QR ログインの iLink ボット人格（例: ...@im.bot）では、そもそもグループのイベントが届かないのが普通なので、この方針が効かないことがあります。ページ冒頭の iLink ボットの制約に関する警告を参照してください。

WEIXIN_GROUP_POLICY=allowlist
# NOTE: this is a comma-separated list of group chat IDs, NOT member user IDs,
# despite the variable name containing "USERS". Keep this in mind when configuring.
WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2

メディアへの対応

受信

アダプターはユーザーからのメディア添付を受け取り、WeChat の CDN からダウンロードして復号し、エージェントが扱えるようローカルにキャッシュします。

引用されたメッセージ: 引用（返信元）のメッセージに含まれるメディアも取り出すので、ユーザーが何に返信しているかをエージェントが把握できます。

AES-128-ECB で暗号化された CDN

WeChat のメディアファイルは暗号化された CDN を通ってやり取りされます。アダプターはこれを裏側で処理します。

• 受信: 暗号化されたメディアを encrypted_query_param の URL で CDN からダウンロードし、メッセージに入っているファイルごとの鍵で AES-128-ECB を使って復号します。
• 送信: ファイルをローカルでランダムな AES-128-ECB 鍵を使って暗号化し、CDN へアップロードして、暗号化された参照を送信メッセージに含めます。
• AES の鍵は 16 バイト（128 ビット）です。鍵は生の base64 で来ることも 16 進数で来ることもあり、アダプターはどちらの形式にも対応します。
• これには Python の cryptography パッケージが必要です。

設定は要りません。暗号化と復号は自動で行われます。

送信

送信するメディアはすべて、暗号化された CDN へのアップロードの流れを通ります。

1. ランダムな AES-128 の鍵を作る
2. AES-128-ECB と PKCS#7 パディングでファイルを暗号化する
3. iLink API（getuploadurl）にアップロード先の URL を要求する
4. 暗号文を CDN へアップロードする
5. 暗号化されたメディアの参照を付けてメッセージを送る

コンテキストトークンの永続化

iLink Bot API は、相手ごとに送信メッセージへ context_token を付け返すことを求めます。アダプターはコンテキストトークンをディスクに保存して管理します。

• トークンはアカウントと相手の組ごとに ~/.hermes/weixin/accounts/<account_id>.context-tokens.json へ保存されます
• 起動時に、保存済みのトークンを読み戻します
• メッセージを受け取るたびに、その送信者のトークンを更新します
• 送信メッセージには最新のコンテキストトークンが自動で付きます

これにより、ゲートウェイを再起動しても返信のつながりが保たれます。

Markdown の書式

iLink Bot API を通してつながる WeChat クライアントは Markdown をそのまま表示できるので、アダプターは Markdown を書き換えずに残します。

• 見出し は Markdown の見出し（#、##、…）のまま
• 表 は Markdown の表のまま
• コードフェンス はフェンス付きコードブロックのまま
• 余分な空行 は、フェンス付きコードブロックの外では 2 つの改行にまとめられます

メッセージの分割

プラットフォームの上限に収まるかぎり、メッセージは 1 通として届きます。大きすぎるものだけが分割されます。

• メッセージの最大長: 4000 文字
• 上限内なら、段落や改行が複数あっても 1 通のままです
• 大きすぎるメッセージは、区切りのよい位置（段落、空行、コードフェンス）で分かれます
• コードフェンスはできるかぎりそのまま保たれます（フェンス自体が上限を超えないかぎり、途中で分けません）
• 大きすぎる 1 ブロックは、基底アダプターの切り詰め処理に回ります
• 複数に分けて送るときは、WeChat のレート制限による取りこぼしを防ぐため、断片の間に 0.3 秒の間隔を置きます

入力中の表示

アダプターは WeChat クライアントに入力中の状態を出します。

1. メッセージが届くと、アダプターは getconfig API で typing_ticket を取得します
2. 入力中チケットはユーザーごとに 10 分間キャッシュされます
3. send_typing が入力開始の合図を、stop_typing が入力終了の合図を送ります
4. エージェントがメッセージを処理している間、ゲートウェイが自動で入力中の表示を出します

ロングポーリング接続

このアダプターは、メッセージの受信に WebSocket ではなく HTTP のロングポーリングを使います。

仕組み

1. 接続: 認証情報を検証してポーリングのループを始めます
2. ポーリング: タイムアウト 35 秒で getupdates を呼びます。サーバーはメッセージが届くかタイムアウトするまでリクエストを保持します
3. 振り分け: 受信したメッセージは asyncio.create_task で並行して処理されます
4. 同期バッファー: 同期位置（get_updates_buf）をディスクへ保存するので、再起動しても正しい位置から再開できます

再試行の動き

API エラーが起きたとき、アダプターは単純な再試行を行います。

重複排除

受信メッセージはメッセージ ID を使って 5 分間の窓で重複排除されます。これにより、ネットワークの乱れやポーリング応答の重なりによる二重処理を防ぎます。

トークンのロック

1 つのトークンを同時に使える Weixin ゲートウェイは 1 つだけです。アダプターは起動時にスコープ付きのロックを取り、終了時に解放します。同じトークンを別のゲートウェイがすでに使っている場合、起動は失敗し、その旨のエラーメッセージが出ます。

環境変数の一覧

困ったときは