Skip to Content
Руководство для пользователейВозможностиКаналыDingTalk

DingTalk (Dingtalk)

В этом руководстве описана настройка канала Qwen Code в DingTalk (钉钉).

Предварительные требования

  • Учётная запись организации DingTalk
  • Приложение-бот DingTalk с AppKey и AppSecret (см. ниже)

Создание бота

  1. Перейдите на Портал разработчика DingTalk 
  2. Создайте новое приложение (или используйте существующее)
  3. В приложении включите возможность Robot (робот)
  4. В настройках робота включите Stream Mode (机器人协议 → Stream 模式)
  5. Запишите AppKey (Client ID) и AppSecret (Client Secret) со страницы учётных данных приложения

Stream Mode

Режим Stream в DingTalk использует исходящее WebSocket-соединение — не требуется публичный URL или сервер. Бот подключается к серверам DingTalk, которые отправляют сообщения через WebSocket. Это самая простая модель развёртывания.

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

Добавьте канал в ~/.qwen/settings.json:

{
  "channels": {
    "my-dingtalk": {
      "type": "dingtalk",
      "clientId": "$DINGTALK_CLIENT_ID",
      "clientSecret": "$DINGTALK_CLIENT_SECRET",
      "useConnectionManager": true,
      "senderPolicy": "open",
      "sessionScope": "user",
      "cwd": "/path/to/your/project",
      "instructions": "Вы — лаконичный ассистент по программированию, отвечающий через DingTalk.",
      "groupPolicy": "open",
      "atSender": true,
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Установите учётные данные как переменные окружения:

export DINGTALK_CLIENT_ID=<your-app-key>
export DINGTALK_CLIENT_SECRET=<your-app-secret>

Или определите их в секции env файла settings.json:

{
  "env": {
    "DINGTALK_CLIENT_ID": "your-app-key",
    "DINGTALK_CLIENT_SECRET": "your-app-secret"
  }
}

Интерактивные карточки

Добавьте объект interactiveCards, чтобы включить статусные карточки и карточки-вопросы DingTalk. Отсутствие объекта отключает интерактивные карточки. Когда объект присутствует, общий переключатель и оба типа карточек по умолчанию включены, а время ожидания карточек-вопросов составляет 270 000 миллисекунд (270 секунд).

{
  "channels": {
    "my-dingtalk": {
      "type": "dingtalk",
      "clientId": "$DINGTALK_CLIENT_ID",
      "clientSecret": "$DINGTALK_CLIENT_SECRET",
      "interactiveCards": {
        "enabled": true,
        "statusCard": { "enabled": true },
        "questionCard": {
          "enabled": true,
          "timeoutMs": 270000
        }
      }
    }
  }
}

Установите interactiveCards.enabled в false, чтобы отключить все интерактивные карточки. Используйте statusCard.enabled или questionCard.enabled, чтобы отключить один тип карточек, а questionCard.timeoutMs установите в конечное положительное число, чтобы изменить время ожидания ответа на карточку-вопрос. Значения выше 2 147 483 647 миллисекунд (около 24,8 дня) ограничиваются этим максимумом. Интерактивные карточки настраиваются через settings.json или API управления; редактор канала Web Shell не отображает их, но сохраняет сохранённый объект при редактировании других полей.

Восстановление соединения

useConnectionManager по умолчанию равен true. Менеджер подключений отслеживает Stream WebSocket и заменяет клиент DingTalk SDK, когда соединение перестаёт отвечать. Обычно его следует оставлять включённым.

Установите "useConnectionManager": false, чтобы отключить менеджер подключений Qwen Code и вернуться к поведению keepalive и автоматического переподключения SDK.

Запуск

# Запустить только канал DingTalk
qwen channel start my-dingtalk
 
# Или запустить все настроенные каналы вместе
qwen channel start

Откройте DingTalk и отправьте сообщение боту. Вы увидите реакцию в виде эмодзи 👀, пока агент обрабатывает запрос, после чего придёт ответ.

Доставка вебхуков демона

Когда канал работает под управлением qwen serve, аутентифицированные внешние вебхук-события могут запускать автономные задачи агента и доставлять финальный ответ в Markdown пользователю или группе DingTalk. Используйте существующие поля цели вебхука; отдельный тип канала не требуется:

{
  "webhooks": {
    "sources": {
      "manual-test": {
        "secretEnv": "QWEN_CHANNEL_DINGTALK_TEST_SECRET",
        "targets": {
          "operator": {
            "chatId": "DINGTALK_USER_ID",
            "senderId": "webhook:manual-test",
            "isGroup": false
          },
          "team": {
            "chatId": "OPEN_CONVERSATION_ID",
            "senderId": "webhook:manual-test",
            "isGroup": true
          }
        }
      }
    }
  }
}

Каждая цель должна явно устанавливать isGroup. Для личного сообщения chatId — это ID пользователя DingTalk получателя. Для группового сообщения chatId — это openConversationId группы. Цели тредов и URL входящих вебхуков робота не поддерживаются для проактивной доставки. См. Задачи, запускаемые вебхуками, для полной конфигурации канала и формата запроса.

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

Боты DingTalk работают как в личных сообщениях, так и в групповых чатах. Чтобы включить поддержку групп:

  1. Установите groupPolicy в "allowlist", "pairing" или "open" в конфигурации канала
  2. Добавьте бота в группу DingTalk
  3. Упомяните бота с помощью @ в группе, чтобы вызвать ответ
  4. Если используется groupPolicy: "pairing", однократно одобрите запрос на сопряжение группы перед началом ответов

По умолчанию бот требует упоминания @ в групповых чатах (requireMention: true). Установите "requireMention": false для конкретной группы, чтобы бот отвечал на все сообщения. Подробнее см. в разделе Групповые чаты.

Установите "atSender": true, чтобы бот @упоминал участника, чьё групповое сообщение вызвало его ответ. По умолчанию эта опция выключена и применяется только к ответам агента с ID сотрудника DingTalk. Ответы отправляются в формате DingTalk markdown независимо от наличия упоминания; префикс упоминания включается в первый чанк сообщения.

Поиск ID беседы группы

DingTalk использует conversationId для идентификации групп. Вы можете найти его в логах службы канала, когда кто-то отправляет сообщение в группу — ищите поле conversationId в выводе логов.

Изображения и файлы

Вы можете отправлять боту фотографии и документы, а не только текст.

Фотографии: Отправьте изображение (снимок экрана, диаграмму и т.д.), и агент проанализирует его с помощью возможностей зрения. Для этого требуется мультимодальная модель — добавьте "model": "qwen3.5-plus" (или другую модель с поддержкой зрения) в конфигурацию канала. DingTalk поддерживает отправку изображений напрямую или как часть форматированного текста (текст + изображения).

Файлы: Отправьте PDF, файл с кодом или любой документ. Бот загружает его с серверов DingTalk и сохраняет локально, чтобы агент мог прочитать его с помощью своих файловых инструментов. Аудио- и видеофайлы также поддерживаются. Это работает с любой моделью.

Ключевые отличия от Telegram

  • Аутентификация: AppKey + AppSecret вместо статического токена бота. SDK автоматически обновляет токен доступа.
  • Подключение: WebSocket-поток вместо опроса — не требуется публичный IP или URL вебхука.
  • Форматирование: Ответы используют диалект Markdown от DingTalk. Таблицы Markdown передаются клиенту DingTalk как есть; длинные сообщения разбиваются на части примерно по 3800 символов.
  • Индикатор работы: К сообщению пользователя добавляется реакция в виде эмодзи 👀 во время обработки, затем она удаляется при отправке ответа.
  • Загрузка медиа: Двухэтапный процесс — downloadCode из сообщения обменивается на временный URL для загрузки через API DingTalk.
  • Группы: DingTalk использует isInAtList для обнаружения упоминаний @ вместо анализа сущностей сообщения.

Советы

  • Используйте инструкции, учитывающие Markdown DingTalk — DingTalk поддерживает заголовки, жирный текст, ссылки, блоки кода и таблицы. Делайте таблицы компактными, так как на узких экранах может появиться горизонтальная прокрутка.
  • Ограничьте доступ — В контексте организации senderPolicy: "open" может быть приемлемо. Для более строгого контроля используйте "allowlist" или "pairing". Подробнее см. в разделе Личное сопряжение (DM Pairing).
  • Цитируемые сообщения — Цитирование (ответ на) сообщения пользователя включает цитируемый текст как контекст для агента. Цитирование ответов бота пока не поддерживается.

Устранение неполадок

Бот не подключается

  • Проверьте правильность AppKey и AppSecret
  • Убедитесь, что переменные окружения установлены перед запуском qwen channel start
  • Убедитесь, что Stream Mode включён в настройках бота на портале разработчика DingTalk
  • Проверьте вывод терминала на наличие ошибок подключения

Бот не отвечает в группах

  • Проверьте, что groupPolicy установлен в "allowlist", "pairing" или "open" (по умолчанию "disabled")
  • Если используется "pairing", убедитесь, что запрос на сопряжение группы был одобрен
  • Убедитесь, что вы упомянули бота с помощью @ в групповом сообщении
  • Проверьте, что бот добавлен в группу

”No sessionWebhook in message”

Это означает, что DingTalk не включил конечную точку ответа в callback сообщения. Такое может произойти, если разрешения бота настроены неправильно. Проверьте настройки бота на портале разработчика.

”Sorry, something went wrong processing your message”

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

Last updated on
WeChatПлагины