Skip to Content
ユーザーガイド機能チャンネルWeCom 自作アプリケーションコールバック

WeCom 自作アプリケーションコールバック

wecom-callback を使用して、WeCom 自作アプリケーション（企业微信自建应用）を通じて Qwen Code とチャットします。暗号化された HTTP コールバックを受信し、アプリケーション API を通じてテキスト返信を送信します。Bot ID と Secret を持つインテリジェントロボットの場合は、別の WeCom WebSocket チャネル を使用してください。

前提条件

  • WeCom 管理者、およびメッセージの受信とアプリケーションメッセージの送信権限を持つ自作アプリケーション。
  • 企業 Corp ID、アプリケーション Agent ID と Secret、およびアプリケーションのメッセージ受信設定で設定されたコールバック Token と EncodingAESKey。
  • ローカルリスナーに転送されるパブリック HTTPS コールバック URL。テナントの要件に従って、アプリケーションの信頼できる送信元 IP と表示メンバー範囲を設定します。Qwen ホストの時計を同期し続けてください。

プラットフォームの要件については、公式の コールバック暗号化  および アプリケーションメッセージ API  のドキュメントを参照してください。

設定

~/.qwen/settings.json に名前付きチャネルを追加します:

{
  "channels": {
    "my-wecom-app": {
      "type": "wecom-callback",
      "corpId": "$WECOM_CORP_ID",
      "agentId": "$WECOM_AGENT_ID",
      "corpSecret": "$WECOM_APP_SECRET",
      "token": "$WECOM_CALLBACK_TOKEN",
      "encodingAESKey": "$WECOM_ENCODING_AES_KEY",
      "webhookHost": "127.0.0.1",
      "webhookPort": 8645,
      "privatePolicy": "allowlist",
      "allowedUsers": ["zhangsan"],
      "sessionScope": "user",
      "groupPolicy": "disabled",
      "cwd": "/path/to/your/project"
    }
  }
}

Qwen Code を起動するプロセスで 5 つの環境変数を設定します。Agent ID は正の整数の文字列です（例: "1000002"）。EncodingAESKey は WeCom コンソールの 43 文字のキーです。コールバック Token はアプリケーション Secret および API アクセストークンとは異なります。Qwen は API アクセストークンを自動的に取得します。3 つのシークレットフィールドはチャネル管理でマスクされます。

リスナーのデフォルトは 127.0.0.1:8645 で、固定パスは /wecom/callback です。パブリック URL をそのパスに転送し、クエリ文字列と本文を保持します。コンテナデプロイメントの場合は、到達可能なインターフェースに明示的にバインドします。複数のアプリケーションには別のチャネル名とポートを使用します。

実行とプラットフォームの検証

  1. qwen channel start my-wecom-app を実行します。
  2. 自作アプリケーションのメッセージ受信設定で、/wecom/callback で終わるパブリック HTTPS URL、Token、および EncodingAESKey を入力します。設定を保存すると、Qwen が復号化して検証チャレンジを返します。
  3. テストメンバーをアプリケーションの表示範囲に追加し、その WeCom User ID を allowedUsers に入れます。アプリケーションにテキストメッセージを送信します。そのアプリケーションからテキスト返信が返ってくることを確認します。
  4. allowedUsers の外にある表示メンバーから送信します。エージェントタスクや返信は返ってこないことを確認します。Qwen はプラットフォームの再試行を回避するためにコールバックに確認応答します。
  5. 中国語テキストと絵文字を含む長い返信を要求します。プラットフォームの 2048 バイト制限内の順序付けされたテキストメッセージが返ってくることを確認します。
  6. チャネルを停止し、ローカルリスナーが閉じることを確認します。

URL 検証が失敗した場合は、リバースプロキシ、コールバックパス、時計、Corp ID、Token、および EncodingAESKey を確認します。コールバックは届くが返信が失敗する場合は、Agent ID、アプリケーション Secret、アプリケーションの可視性、および信頼できる送信元 IP を確認します。アプリケーションシークレットとコールバックキーは、ログや issue に絶対に投稿しないでください。

サポートされる動作と制限

  • テキストのプライベートメッセージとテキスト返信。共有アクセスポリシー、ペアリング、コマンド、権限、およびセッションが適用されます。アクセスルールにはメンバー User ID を使用します。
  • プロアクティブメッセージは個々のユーザーをターゲットにできます。グループ、スレッド、メディア、アプリケーションイベント、およびストリーミング返信はサポートされていません。
  • コールバックはエージェントの実行が完了する前に認証、復号化、および確認応答されます。返信はコールバックの同期応答ではなく、アプリケーションメッセージ API を使用します。受け入れられたメッセージ ID は、少なくとも 5 分間、および署名付きタイムスタンプウィンドウが期限切れになるまで、メモリで抑制されます。5 分の署名タイムスタンプウィンドウ外の要求は失敗します。拒否された送信者は再試行キャッシュ容量を消費しません。
  • 処理中の作業は永続的にキューイングされません。確認応答後にプロセスを再起動すると、そのタスクが失われる可能性があり、再起動すると再試行キャッシュがクリアされます。

企業テナントなしでのテスト

packages/channels/wecom から、以下を実行します:

npx vitest run src/wecom-callback-crypto.test.ts src/wecom-callback-adapter.test.ts src/callback-plugin.test.ts src/WeComAdapter.test.ts

テストは、独立した公開 SDK 暗号化フィクスチャ、実際のループバック HTTP リクエスト、共有インバウンドアクセスチェック、およびモックされたアプリケーション API 応答を使用します。ハンドシェイク検証、認証失敗、再試行、受信者分離、Unicode 分割、およびシャットダウンをカバーします。実際の認証情報や WeCom へのメッセージ送信は必要ありません。実際のテナントのパブリック URL、権限、およびネットワーク設定を検証するには、上記のプラットフォーム検証手順が依然として必要です。

Last updated on
メールフック