チャンネル

チャンネルを使用すると、ターミナルではなく、Telegram、WeChat、QQ、DingTalk、Feishu などのメッセージングプラットフォームから Qwen Code エージェントと対話できます。スマートフォンやデスクトップのチャットアプリからメッセージを送信すると、エージェントは CLI の場合と同じように応答します。

仕組み

qwen channel start を実行すると、Qwen Code は次のように動作します。

settings.json からチャンネル設定を読み取ります
Agent Client Protocol (ACP) を使用して単一のエージェントプロセスを生成します
各メッセージングプラットフォームに接続し、メッセージの受信を開始します
受信したメッセージをエージェントにルーティングし、応答を正しいチャットに送信します

すべてのチャンネルは、ユーザーごとに分離されたセッションを持つ単一のエージェントプロセスを共有します。各チャンネルは、独自の作業ディレクトリ、モデル、および指示を持つことができます。

クイックスタート

メッセージングプラットフォームでボットをセットアップします（チャンネル固有のガイドを参照してください：Telegram、WeChat、QQ Bot、DingTalk、Feishu）
チャンネル設定を ~/.qwen/settings.json に追加します
qwen channel start を実行してすべてのチャンネルを開始するか、qwen channel start <name> で単一のチャンネルを開始します

組み込みでないプラットフォームを接続したいですか？Plugins を参照して、カスタムアダプタを拡張機能として追加してください。

設定

チャンネルは settings.json の channels キー配下で設定します。各チャンネルには名前と一連のオプションがあります。


{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "token": "$MY_BOT_TOKEN",
      "senderPolicy": "allowlist",
      "allowedUsers": ["123456789"],
      "sessionScope": "user",
      "cwd": "/path/to/working/directory",
      "instructions": "Optional system instructions for the agent.",
      "groupPolicy": "disabled",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

オプション

オプション	必須	説明
`type`	はい	チャンネルタイプ：`telegram`、`weixin`、`qq`、`dingtalk`、`feishu`、または拡張機能のカスタムタイプ（Plugins を参照）
`token`	Telegram	ボットトークン。環境変数から読み取るための `$ENV_VAR` 構文をサポートします。WeChat、DingTalk、Feishu では不要です
`clientId`	DingTalk, Feishu	DingTalk AppKey または Feishu App ID。`$ENV_VAR` 構文をサポートします
`clientSecret`	DingTalk, Feishu	DingTalk AppSecret または Feishu App Secret。`$ENV_VAR` 構文をサポートします
`model`	いいえ	このチャンネルで使用するモデル（例：`qwen3.5-plus`）。デフォルトモデルを上書きします。画像入力をサポートするマルチモーダルモデルに便利です
`senderPolicy`	いいえ	ボットと対話できるユーザー：`allowlist`（デフォルト）、`open`、または `pairing`
`allowedUsers`	いいえ	ボットの使用を許可するユーザー ID のリスト（`allowlist` および `pairing` ポリシーで使用）
`sessionScope`	いいえ	セッションのスコープ方法：`user`（デフォルト）、`thread`、または `single`
`cwd`	いいえ	エージェントの作業ディレクトリ。デフォルトは現在のディレクトリです
`instructions`	いいえ	各セッションの最初のメッセージの前に追加されるカスタム指示
`groupPolicy`	いいえ	グループチャットへのアクセス：`disabled`（デフォルト）、`allowlist`、または `open`。Group Chats を参照
`groupHistoryLimit`	いいえ	グループ履歴のバックフィルをオプトインします。`0` または省略すると無効になります。正の数を指定すると、次のボットのメンションや返信に対して、許可されたメンションなしのグループメッセージがその数だけ永続化されます。
`groups`	いいえ	グループごとの設定。キーはグループチャット ID またはデフォルト値の `"*"` です。Group Chats を参照
`dispatchMode`	いいえ	ボットがビジーのときにメッセージを送信したときの動作：`steer`（デフォルト）、`collect`、または `followup`。Dispatch Modes を参照
`blockStreaming`	いいえ	プログレッシブなレスポンス配信：`on` または `off`（デフォルト）。Block Streaming を参照
`blockStreamingChunk`	いいえ	チャンクサイズの境界：`{ "minChars": 400, "maxChars": 1000 }`。Block Streaming を参照
`blockStreamingCoalesce`	いいえ	アイドル時のフラッシュ：`{ "idleMs": 1500 }`。Block Streaming を参照

送信者ポリシー

ボットと対話できるユーザーを制御します。

allowlist（デフォルト）— allowedUsers にリストされているユーザーのみがメッセージを送信できます。その他のユーザーは暗黙に無視されます。
pairing — 不明な送信者にはペアリングコードが送信されます。ボットオペレーターが CLI 経由で承認し、永続的な許可リストに追加されます。allowedUsers にいるユーザーはペアリングを完全にスキップします。以下の DM Pairing を参照してください。
open — 誰でもメッセージを送信できます。使用には注意が必要です。

セッションスコープ

会話セッションの管理方法を制御します。

user（デフォルト）— ユーザーごとに 1 つのセッション。同じユーザーからのすべてのメッセージは 1 つの会話を共有します。
thread — スレッドまたはトピックごとに 1 つのセッション。スレッド付きのグループチャットに便利です。
single — すべてのユーザーで共有される 1 つのセッション。全員が同じ会話を共有します。

チャンネルメモリ

チャンネルメモリを使用すると、許可されたチャンネルメンバーが 1 つのチャットまたはスレッドの安定したコンテキストを保存できます。Qwen Code は、/clear の後など、新しいチャンネルセッションが開始されるときにそのメモリを注入します。

自然言語の例：

记住：默认使用 staging 环境 は現在のチャットまたはスレッドのメモリを保存します。
你记一下以后回复前要说 1122 は抽出された永続メモリを保存します。
你现在都记住了什么 は現在のチャットまたはスレッドの保存済みメモリを表示します。
把这个聊天的记忆清空 はクリアフローを開始し、确认清空记忆 で確定します。

グループチャットでは保存済みメモリを表示できますが、共有メモリが他の参加者へのプロンプトインジェクションの経路になるのを防ぐため、書き込みとクリアはブロックされます。

allowedUsers にリストされているユーザーのみがチャンネルメモリの読み取り、書き込み、クリアを行えます。allowedUsers が空の場合、チャンネルメモリコマンドは全員に対して無効になります。

トークンのセキュリティ

ボットトークンは settings.json に直接保存すべきではありません。代わりに、環境変数参照を使用してください。


{
  "token": "$TELEGRAM_BOT_TOKEN"
}

実際のトークンは、シェル環境またはチャンネルの実行前に読み込まれる .env ファイルに設定してください。

DM ペアリング

senderPolicy が "pairing" に設定されている場合、不明な送信者は承認フローを経由します。

不明なユーザーがボットにメッセージを送信します
ボットが 8 文字のペアリングコード（例：VEQDDWXJ）で応答します
ユーザーがコードをあなた（ボットオペレーター）に共有します
CLI 経由で承認します。


qwen channel pairing approve my-channel VEQDDWXJ

承認されると、ユーザーの ID が ~/.qwen/channels/<name>-allowlist.json に保存され、以降のすべてのメッセージは通常通り処理されます。

ペアリング CLI コマンド


# List pending pairing requests
qwen channel pairing list my-channel
 
# Approve a request by code
qwen channel pairing approve my-channel <CODE>

ペアリングルール

コードは 8 文字の大文字で、曖昧さのないアルファベットを使用します（0/O/1/I は除く）。
コードは 1 時間後に期限切れになります。
チャンネルごとに同時に保留中のリクエストは最大 3 つまでです。追加のリクエストは、いずれかが期限切れになるか承認されるまで無視されます。
settings.json の allowedUsers にリストされているユーザーは、常にペアリングをスキップします。
承認されたユーザーは ~/.qwen/channels/<name>-allowlist.json に保存されます。このファイルは機密として扱ってください。

グループチャット

デフォルトでは、ボットはダイレクトメッセージでのみ動作します。グループチャットのサポートを有効にするには、groupPolicy を "allowlist" または "open" に設定します。

グループポリシー

ボットがグループチャットに参加するかどうかを制御します。

disabled（デフォルト）— ボットはすべてのグループメッセージを無視します。最も安全なオプションです。
allowlist — ボットは groups にチャット ID で明示的にリストされているグループでのみ応答します。"*" キーはデフォルト設定を提供しますが、ワイルドカード許可としては機能しません。
open — ボットは追加されたすべてのグループで応答します。使用には注意が必要です。

メンションゲーティング

グループ内では、デフォルトでボットは @mention または自身のメッセージへの返信を要求します。これにより、ボットがグループチャットのすべてのメッセージに応答するのを防ぎます。

groups 設定を使用してグループごとに設定します。


{
  "groups": {
    "*": { "requireMention": true },
    "-100123456": { "requireMention": false }
  }
}

"*" — すべてのグループのデフォルト設定。設定のデフォルト値を設定するだけで、許可リストのエントリではありません。
グループチャット ID — 特定のグループの設定を上書きします。"*" のデフォルト値を上書きします。
requireMention（デフォルト：true）— true の場合、ボットは自身を @mention するメッセージまたは自身のメッセージへの返信にのみ応答します。false の場合、ボットはすべてのメッセージに応答します（専用タスクグループに便利です）。

グループ履歴のバックフィル

デフォルトでは、Qwen はメンションのないグループメッセージを無視し、セッションのターンとして保存しません。次の @mention に最近のグループコンテキストを含めるには、groupHistoryLimit を正の数に設定します。


{
  "channels": {
    "my-dingtalk": {
      "type": "dingtalk",
      "clientId": "$DINGTALK_CLIENT_ID",
      "clientSecret": "$DINGTALK_CLIENT_SECRET",
      "groupPolicy": "open",
      "groupHistoryLimit": 50,
      "groups": {
        "*": { "requireMention": true },
        "sensitive-group-id": {
          "requireMention": true,
          "groupHistoryLimit": 0
        }
      }
    }
  }
}

省略または 0 はバックフィルを無効にします。
グループレベルの groupHistoryLimit はチャンネルレベルの値を上書きします。
許可された送信者からのメッセージのみが永続化されます。
groupPolicy またはグループ許可リストによって拒否されたメッセージは永続化されません。
保留中のグループ履歴は、~/.qwen/channels/<channel-name>-group-history.jsonl または $QWEN_HOME/channels/<channel-name>-group-history.jsonl 配下のローカル JSONL として保存されます。
キャッシュされたメッセージは、次の実際のトリガーで信頼できないコンテキストとして注入され、独立したセッションのターンとして書き込まれません。

グループメッセージの評価方法


1. groupPolicy — is this group allowed?           (no → ignore)
2. requireMention — was the bot mentioned/replied to? (no → ignore)
3. senderPolicy — is this sender approved?         (no → pairing flow)
4. Route to session

グループ向け Telegram のセットアップ

ボットをグループに追加します
BotFather で プライバシーモードを無効にします（/mybots → Bot Settings → Group Privacy → Turn Off）。無効にしないと、ボットはコマンド以外のメッセージを見ることができません。
プライバシーモードを変更した後、グループからボットを削除して再度追加します（Telegram はこの設定をキャッシュするため）。

グループチャット ID の確認

groups 許可リスト用のグループチャット ID を確認するには:

ボットが実行中の場合は停止する
グループ内でボットにメンション付きのメッセージを送信する
Telegram Bot API を使用してキューに入れられた更新を確認する:


curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | python3 -m json.tool

レスポンス内の message.chat.id を確認します。グループ ID は負の数値です（例: -5170296765）。

メディアサポート

チャネルでは、テキストだけでなく、エージェントへの画像やファイルの送信もサポートされています。

画像

ボットに写真を送信すると、エージェントがそれを認識します。スクリーンショット、エラーメッセージ、図の共有に便利です。画像は vision input としてモデルに直接送信されます。

画像サポートを使用するには、チャネルにマルチモーダルモデルを設定します:


{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "model": "qwen3.5-plus",
      ...
    }
  }
}

ファイル

ボットにドキュメント（PDF、コードファイル、テキストファイルなど）を送信します。ファイルはダウンロードされて一時ディレクトリに保存され、エージェントにファイルパスが通知されるため、ファイル読み取りツールを使用して内容を読み取ることができます。

ファイルはどのモデルでも機能します。マルチモーダルサポートは不要です。

プラットフォームによる違い

機能	Telegram	WeChat	DingTalk	Feishu
画像	Bot API 経由で直接ダウンロード	AES 復号化付き CDN ダウンロード	downloadCode API（2ステップ）	Open API リソースエンドポイント（認証付き GET、50MB 制限）
ファイル	Bot API 経由で直接ダウンロード（20MB 制限）	AES 復号化付き CDN ダウンロード	downloadCode API（2ステップ）	Open API リソースエンドポイント（50MB 制限）
キャプション	写真/ファイルのキャプションがメッセージテキストとして含まれる	対象外	リッチテキスト: 1つのメッセージにテキストと画像が混在	リッチテキスト（`post`）: テキストが抽出され、埋め込み画像は無視される

QQ Bot は受信メディアを処理しません。画像やスタンプのメッセージは無視されるため、上記のメディア処理に関する行はありません。

ディスパッチモード

ボットが前のメッセージを処理している間に新しいメッセージを送信した際の動作を制御します。

steer（デフォルト） — ボットは現在のリクエストをキャンセルし、新しいメッセージの処理を開始します。フォローアップが通常ボットの修正や方向転換を意味する通常のチャットに最適です。
collect — 新しいメッセージはバッファリングされます。現在のリクエストが完了すると、バッファリングされたすべてのメッセージが1つのフォローアッププロンプトに結合されます。考えをキューに入れたい非同期ワークフローに適しています。
followup — 各メッセージはキューに入れられ、順番に独立したターンとして処理されます。各メッセージが独立しているバッチワークフローに便利です。


{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "dispatchMode": "steer",
      ...
    }
  }
}

チャネルのデフォルト設定を上書きして、グループごとにディスパッチモードを設定することもできます:


{
  "groups": {
    "*": { "requireMention": true, "dispatchMode": "steer" },
    "-100123456": { "dispatchMode": "collect" }
  }
}

ブロックストリーミング

デフォルトでは、エージェントはしばらく処理を行った後、1つの大きなレスポンスを送信します。ブロックストリーミングを有効にすると、エージェントが処理を続けている間、レスポンスが複数の短いメッセージとして届きます。これは、ChatGPT や Claude が進行中の出力を表示する仕組みと似ています。


{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "blockStreaming": "on",
      "blockStreamingChunk": { "minChars": 400, "maxChars": 1000 },
      "blockStreamingCoalesce": { "idleMs": 1500 },
      ...
    }
  }
}

仕組み

エージェントのレスポンスは段落の境界でブロックに分割され、個別のメッセージとして送信されます
minChars（デフォルト 400） — 小さなメッセージのスパムを避けるため、少なくともこの文字数に達するまでブロックを送信しません
maxChars（デフォルト 1000） — 自然な区切りがないままブロックがこの文字数に達した場合、とにかく送信します
idleMs（デフォルト 1500） — エージェントが一時停止した場合（例: ツールの実行中）、それまでにバッファリングされた内容を送信します
エージェントが完了すると、残りのテキストはすぐに送信されます

必須なのは blockStreaming だけです。chunk と coalesce の設定はオプションであり、適切なデフォルト値が設定されています。

スラッシュコマンド

チャネルはスラッシュコマンドをサポートしています。これらはローカルで処理されます（エージェントとの往復は発生しません）:

/help — 利用可能なコマンドの一覧を表示
/clear — セッションをクリアして新規開始（エイリアス: /reset, /new）
/status — セッション情報とアクセスポリシーを表示

その他のすべてのスラッシュコマンド（例: /compress, /summary）はエージェントに転送されます。

これらのコマンドは、すべてのチャネルタイプ（Telegram, WeChat, QQ, DingTalk, Feishu）で機能します。

実行


# 設定されたすべてのチャネルを起動（エージェントプロセスを共有）
qwen channel start
 
# 単一のチャネルを起動
qwen channel start my-channel
 
# サービスが実行中かどうかを確認
qwen channel status
 
# 実行中のサービスを停止
qwen channel stop

ボットはフォアグラウンドで実行されます。停止するには Ctrl+C を押すか、別のターミナルから qwen channel stop を使用します。

実験的デーモン管理モード

設定したチャネルを qwen serve 配下で実行することもできます:


# デーモンのライフサイクル配下で1つのチャネルを起動
qwen serve --channel my-channel
 
# 設定されたすべてのチャネルを起動
qwen serve --channel all

このモードでは、qwen serve が所有する1つのチャネルワーカープロセスが起動します。ワーカーは SDK を介してデーモンに接続し、同じチャネルアダプタを使用します。デーモンプロセスとは分離されているため、チャネルアダプタがクラッシュしてもデーモンはクラッシュしません。

qwen serve --channel は qwen channel start とは異なるサービスです。単独の qwen channel start は引き続き ACP ベースのチャネルサービスを使用し、異なる cwd 値を持つチャネル設定を実行できます。デーモン管理チャネルでは、選択した各チャネルの cwd がデーモンワークスペースに解決される必要があります。

チャネルが serve 管理されている場合、qwen channel status はオーナーを qwen serve として表示し、qwen channel stop はワーカーに直接シグナルを送る代わりにデーモンを停止するように指示します。準備ができたワーカーが予期せず終了した場合、デーモンは実行を継続し、/daemon/status にチャネルワーカーの警告を報告します。

マルチチャネルモード

名前を指定せずに qwen channel start を実行すると、settings.json で定義されたすべてのチャネルが、単一のエージェントプロセスを共有して同時に起動します。各チャネルは独自のセッションを維持します。同じエージェントを共有していても、Telegram ユーザーと WeChat ユーザーは別々の会話を取得します。

各チャネルは設定から独自の cwd を使用するため、異なるチャネルが同時に異なるプロジェクトで作業できます。

サービス管理

チャネルサービスは PID ファイル（~/.qwen/channels/service.pid）を使用して、実行中のインスタンスを追跡します:

重複防止: サービスがすでに実行中に qwen channel start を実行すると、2つ目のインスタンスを起動する代わりにエラーが表示されます
qwen channel stop: 別のターミナルから実行中のサービスを正常に停止します
qwen channel status: サービスが実行中かどうか、稼働時間、およびチャネルごとのセッション数を表示します

クラッシュからの復旧

エージェントプロセスが予期せずクラッシュした場合、チャネルサービスは自動的にそれを再起動し、すべてのアクティブなセッションの復元を試みます。ユーザーはやり直すことなく会話を継続できます。

セッションは、サービスの実行中に ~/.qwen/channels/sessions.json に永続化されます
クラッシュ時: エージェントは3秒以内に再起動し、保存されたセッションをリロードします
3回連続でクラッシュした後、サービスはエラーで終了します
正常なシャットダウン時（Ctrl+C または qwen channel stop）: セッションデータはクリアされ、次回の起動は常に新規状態になります