Каналы

Каналы позволяют взаимодействовать с агентом Qwen Code через мессенджеры, такие как Telegram, WeChat или DingTalk, вместо терминала. Вы отправляете сообщения с телефона или десктопного чата, а агент отвечает так же, как в CLI.

Как это работает

При запуске qwen channel start Qwen Code:

1. Считывает конфигурации каналов из вашего settings.json
2. Запускает единый процесс агента, используя Agent Client Protocol (ACP)
3. Подключается к каждой платформе обмена сообщениями и начинает прослушивать входящие сообщения
4. Маршрутизирует входящие сообщения агенту и отправляет ответы обратно в правильный чат

Все каналы используют один процесс агента с изолированными сессиями для каждого пользователя. Каждый канал может иметь собственную рабочую директорию, модель и инструкции.

Быстрый старт

1. Настройте бота на вашей платформе обмена сообщениями (см. руководства для конкретных каналов: Telegram, WeChat, DingTalk)
2. Добавьте конфигурацию канала в ~/.qwen/settings.json
3. Запустите qwen channel start для запуска всех каналов или qwen channel start <name> для одного канала

Хотите подключить платформу, которая не поддерживается из коробки? См. Плагины, чтобы добавить кастомный адаптер в виде расширения.

Конфигурация

Каналы настраиваются в разделе channels файла settings.json. Каждый канал имеет имя и набор опций:

{
  "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 }
      }
    }
  }
}

Опции

Политика отправителей (Sender Policy)

Определяет, кто может взаимодействовать с ботом:

• allowlist (по умолчанию) — Сообщения могут отправлять только пользователи из allowedUsers. Остальные игнорируются без уведомлений.
• pairing — Неизвестные отправители получают код сопряжения. Оператор бота одобряет их через CLI, и они добавляются в постоянный allowlist. Пользователи из allowedUsers пропускают этап сопряжения. См. Сопряжение в ЛС ниже.
• open — Сообщения может отправлять кто угодно. Используйте с осторожностью.

Область сессии (Session Scope)

Определяет, как управляются сессии разговора:

• user (по умолчанию) — Одна сессия на пользователя. Все сообщения от одного пользователя относятся к одному разговору.
• thread — Одна сессия на ветку/тему. Полезно для групповых чатов с ветками.
• single — Одна общая сессия для всех пользователей. Все участники ведут один разговор.

Безопасность токенов

Токены ботов не следует хранить напрямую в settings.json. Вместо этого используйте ссылки на переменные окружения:

{
  "token": "$TELEGRAM_BOT_TOKEN"
}

Установите реальный токен в окружении вашего shell или в файле .env, который загружается перед запуском канала.

Сопряжение в ЛС (DM Pairing)

Если для senderPolicy установлено значение "pairing", неизвестные отправители проходят процесс одобрения:

1. Неизвестный пользователь отправляет сообщение боту
2. Бот отвечает 8-символьным кодом сопряжения (например, VEQDDWXJ)
3. Пользователь передает код вам (оператору бота)
4. Вы одобряете его через CLI:

qwen channel pairing approve my-channel VEQDDWXJ

После одобрения ID пользователя сохраняется в ~/.qwen/channels/<name>-allowlist.json, и все последующие сообщения обрабатываются в обычном режиме.

CLI-команды для сопряжения

# Список ожидающих запросов на сопряжение
qwen channel pairing list my-channel
 
# Одобрить запрос по коду
qwen channel pairing approve my-channel <CODE>

Правила сопряжения

• Коды состоят из 8 символов в верхнем регистре, используется однозначный алфавит (без 0/O/1/I)
• Коды истекают через 1 час
• Максимум 3 ожидающих запроса на канал одновременно — дополнительные запросы игнорируются, пока один не истечет или не будет одобрен
• Пользователи, указанные в allowedUsers в settings.json, всегда пропускают этап сопряжения
• Одобренные пользователи хранятся в ~/.qwen/channels/<name>-allowlist.json — относитесь к этому файлу как к конфиденциальному

Групповые чаты

По умолчанию бот работает только в личных сообщениях. Чтобы включить поддержку групповых чатов, установите groupPolicy в "allowlist" или "open".

Политика групп (Group Policy)

Определяет, участвует ли бот в групповых чатах вообще:

• disabled (по умолчанию) — Бот игнорирует все сообщения в группах. Самый безопасный вариант.
• allowlist — Бот отвечает только в группах, явно указанных в groups по ID чата. Ключ "*" задает настройки по умолчанию, но не работает как wildcard для разрешения.
• open — Бот отвечает во всех группах, куда его добавили. Используйте с осторожностью.

Фильтр по упоминаниям (Mention Gating)

В группах бот по умолчанию требует @mention или ответ на одно из его сообщений. Это предотвращает реакцию бота на каждое сообщение в групповом чате.

Настройте для каждой группы через параметр groups:

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

• "*" — Настройки по умолчанию для всех групп. Задает только конфигурационные значения по умолчанию, не является записью в allowlist.
• ID группового чата — Переопределяет настройки для конкретной группы. Имеет приоритет над значениями "*" по умолчанию.
• requireMention (по умолчанию: true) — Если true, бот отвечает только на сообщения, где его @упоминают или отвечают на его сообщение. Если false, бот отвечает на все сообщения (полезно для выделенных групп задач).

Как оцениваются сообщения в группах

1. groupPolicy — разрешена ли эта группа?           (нет → игнорировать)
2. requireMention — упомянули бота/ответили ему?    (нет → игнорировать)
3. senderPolicy — одобрен ли отправитель?           (нет → процесс сопряжения)
4. Маршрутизация в сессию

Настройка Telegram для групп

1. Добавьте бота в группу
2. Отключите режим конфиденциальности в BotFather (/mybots → Bot Settings → Group Privacy → Turn Off) — иначе бот не будет видеть сообщения без команд
3. Удалите и снова добавьте бота в группу после изменения режима конфиденциальности (Telegram кэширует эту настройку)

Поиск ID группового чата

Чтобы найти ID чата группы для allowlist в groups:

1. Остановите бота, если он запущен
2. Отправьте в группе сообщение с упоминанием бота
3. Используйте Telegram Bot API для проверки ожидающих обновлений:

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

Ищите message.chat.id в ответе — ID групп отрицательные (например, -5170296765).

Поддержка медиа

Каналы поддерживают отправку изображений и файлов агенту, а не только текста.

Изображения

Отправьте фото боту, и агент его увидит — удобно для скриншотов, сообщений об ошибках или диаграмм. Изображение передается модели напрямую как vision-вход.

Чтобы использовать поддержку изображений, настройте мультимодальную модель для канала:

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

Файлы

Отправьте документ (PDF, файл с кодом, текстовый файл и т.д.) боту. Файл скачивается и сохраняется во временную директорию, а агенту передается путь к файлу, чтобы он мог прочитать содержимое с помощью своих инструментов.

Файлы работают с любой моделью — поддержка мультимодальности не требуется.

Отличия платформ

Режимы диспетчеризации (Dispatch Modes)

Определяет, что происходит при отправке нового сообщения, пока бот все еще обрабатывает предыдущее.

• steer (по умолчанию) — Бот отменяет текущий запрос и начинает работать над новым сообщением. Лучше всего подходит для обычного чата, где follow-up обычно означает, что вы хотите исправить или перенаправить бота.
• collect — Ваши новые сообщения буферизуются. Когда текущий запрос завершается, все буферизованные сообщения объединяются в один follow-up промпт. Хорошо для асинхронных рабочих процессов, где нужно накапливать мысли.
• followup — Каждое сообщение ставится в очередь и обрабатывается как отдельный ход по порядку. Полезно для пакетных рабочих процессов, где каждое сообщение независимо.

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

Вы также можете задать режим диспетчеризации для каждой группы, переопределяя значение по умолчанию для канала:

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

Потоковая передача блоками (Block Streaming)

По умолчанию агент работает некоторое время, а затем отправляет один большой ответ. При включенной потоковой передаче блоками ответ приходит несколькими короткими сообщениями, пока агент еще работает — аналогично тому, как ChatGPT или Claude показывают прогрессивный вывод.

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

Как это работает

• Ответ агента разбивается на блоки по границам абзацев и отправляется отдельными сообщениями
• minChars (по умолчанию 400) — не отправлять блок, пока он не достигнет этой длины, чтобы избежать спама крошечными сообщениями
• maxChars (по умолчанию 1000) — если блок достигает этой длины без естественного разрыва, отправить его в любом случае
• idleMs (по умолчанию 1500) — если агент делает паузу (например, запускает инструмент), отправить все, что накопилось в буфере
• Когда агент завершает работу, любой оставшийся текст отправляется немедленно

Требуется только blockStreaming. Настройки чанков и объединения опциональны и имеют разумные значения по умолчанию.

Слэш-команды

Каналы поддерживают слэш-команды. Они обрабатываются локально (без round-trip к агенту):

• /help — Список доступных команд
• /clear — Очистить вашу сессию и начать заново (алиасы: /reset, /new)
• /status — Показать информацию о сессии и политику доступа

Все остальные слэш-команды (например, /compress, /summary) пересылаются агенту.

Эти команды работают на всех типах каналов (Telegram, WeChat, DingTalk).

Запуск

# Запуск всех настроенных каналов (общий процесс агента)
qwen channel start
 
# Запуск одного канала
qwen channel start my-channel
 
# Проверка статуса сервиса
qwen channel status
 
# Остановка работающего сервиса
qwen channel stop

Бот работает в foreground. Нажмите Ctrl+C для остановки или используйте qwen channel stop из другого терминала.

Режим нескольких каналов

При запуске qwen channel start без имени все каналы, определенные в settings.json, запускаются вместе, используя один процесс агента. Каждый канал поддерживает собственные сессии — пользователь Telegram и пользователь WeChat ведут отдельные разговоры, даже если используют одного агента.

Каждый канал использует свою cwd из конфигурации, поэтому разные каналы могут одновременно работать над разными проектами.

Управление сервисом

Сервис каналов использует PID-файл (~/.qwen/channels/service.pid) для отслеживания запущенного экземпляра:

• Предотвращение дубликатов: Запуск qwen channel start при уже работающем сервисе покажет ошибку вместо запуска второго экземпляра
• qwen channel stop: Корректно останавливает работающий сервис из другого терминала
• qwen channel status: Показывает, запущен ли сервис, время его работы и количество сессий на канал

Восстановление после сбоев

Если процесс агента неожиданно завершается с ошибкой, сервис каналов автоматически перезапускает его и пытается восстановить все активные сессии. Пользователи могут продолжить разговор без необходимости начинать заново.

• Сессии сохраняются в ~/.qwen/channels/sessions.json во время работы сервиса
• При сбое: агент перезапускается в течение 3 секунд и перезагружает сохраненные сессии
• После 3 последовательных сбоев сервис завершает работу с ошибкой
• При корректном завершении (Ctrl+C или qwen channel stop): данные сессий очищаются — следующий запуск всегда начинается с чистого листа