Настройка DingTalk

VibeOS интегрируется с DingTalk (钉钉) в качестве чат-бота, позволяя вам общаться с вашим AI-ассистентом через личные сообщения или групповые чаты. Бот подключается через Stream Mode от DingTalk — долгоживущее WebSocket-соединение, не требующее публичного URL или вебхук-сервера — и отвечает с помощью сообщений в формате Markdown через API сессионных вебхуков DingTalk.

Перед настройкой вот что большинство людей хотят знать: как VibeOS ведёт себя, оказавшись в вашем рабочем пространстве DingTalk.

Поведение VibeOS

Контекст	Поведение
Личные сообщения (чат 1:1)	VibeOS отвечает на каждое сообщение. `@упоминание` не требуется. Каждый личный чат имеет свой собственный сеанс.
Групповые чаты	VibeOS отвечает, когда вы `@упоминаете` его. Без упоминания VibeOS игнорирует сообщение.
Общие группы с несколькими пользователями	По умолчанию VibeOS изолирует историю сеанса для каждого пользователя внутри группы. Два человека, общающиеся в одной группе, не используют одну стенограмму, если вы явно не отключите это.

Модель сеанса в DingTalk

По умолчанию:

каждый личный чат получает свой собственный сеанс
каждый пользователь в общем групповом чате получает свой собственный сеанс внутри этой группы

Это контролируется в config.yaml:

group_sessions_per_user: true

Установите значение false, только если вы явно хотите один общий разговор для всей группы:

group_sessions_per_user: false

Это руководство проведёт вас через весь процесс настройки — от создания вашего бота DingTalk до отправки первого сообщения.

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

Установите необходимые пакеты Python:

cd ~/.vibeos/vibeos-agent && uv pip install -e ".[dingtalk]"

Или по отдельности:

pip install dingtalk-stream httpx alibabacloud-dingtalk

dingtalk-stream — официальный SDK DingTalk для Stream Mode (обмен сообщениями в реальном времени на основе WebSocket)
httpx — асинхронный HTTP-клиент, используемый для отправки ответов через сессионные вебхуки
alibabacloud-dingtalk — SDK OpenAPI DingTalk для AI-карточек, реакций-эмодзи и загрузки медиа

Шаг 1: Создайте приложение DingTalk

Перейдите в DingTalk Developer Console.
Войдите в систему, используя учётную запись администратора DingTalk.
Нажмите Application Development → Custom Apps → Create App via H5 Micro-App (или Robot в зависимости от версии консоли).
Заполните:
- App Name: например, VibeOS
- Description: необязательно
После создания перейдите в Credentials & Basic Info, чтобы найти ваш Client ID (AppKey) и Client Secret (AppSecret). Скопируйте оба.

Учётные данные отображаются только один раз

Client Secret отображается только один раз при создании приложения. Если вы его потеряете, вам нужно будет сгенерировать его заново. Никогда не делитесь этими учётными данными публично и не сохраняйте их в Git.

Шаг 2: Включите возможность робота

На странице настроек вашего приложения перейдите в Add Capability → Robot.
Включите возможность робота.
В разделе Message Reception Mode выберите Stream Mode (рекомендуется — не требуется публичный URL).

подсказка

Stream Mode — это рекомендуемая настройка. Он использует долгоживущее WebSocket-соединение, инициированное с вашей машины, поэтому вам не нужен публичный IP, доменное имя или конечная точка вебхука. Это работает за NAT, брандмауэрами и на локальных машинах.

Шаг 3: Найдите свой DingTalk User ID

VibeOS использует ваш DingTalk User ID для контроля того, кто может взаимодействовать с ботом. DingTalk User ID — это буквенно-цифровые строки, установленные администратором вашей организации.

Чтобы найти свой:

Спросите у администратора вашей организации DingTalk — User ID настраиваются в консоли администратора DingTalk в разделе Contacts → Members.
Альтернативно, бот записывает sender_id для каждого входящего сообщения. Запустите шлюз, отправьте боту сообщение, затем проверьте логи на наличие вашего ID.

Шаг 4: Настройте VibeOS

Вариант A: Интерактивная настройка (рекомендуется)

Запустите команду настройки с помощью мастера:

vibeos gateway setup

Выберите DingTalk при появлении запроса. Мастер настройки может авторизоваться одним из двух способов:

QR-код (рекомендуется). Отсканируйте QR-код, который появится в вашем терминале, с помощью мобильного приложения DingTalk — ваш Client ID и Client Secret будут возвращены автоматически и записаны в ~/.vibeos/.env. Посещение консоли разработчика не требуется.
Ручная вставка. Если у вас уже есть учётные данные (или сканирование QR-кода неудобно), вставьте ваш Client ID, Client Secret и разрешённые User ID при появлении запроса.

Раскрытие информации о бренде openClaw

Поскольку verification_uri_complete от DingTalk жёстко закодирован на идентификатор openClaw на уровне API, QR-код в настоящее время авторизуется под исходной строкой openClaw, пока Alibaba / DingTalk-Real-AI не зарегистрирует шаблон, специфичный для VibeOS, на стороне сервера. Это чисто вопрос того, как DingTalk отображает экран согласия — созданный вами бот полностью ваш и приватный для вашего тенанта.

Вариант B: Ручная настройка

Добавьте следующее в ваш файл ~/.vibeos/.env:

# Обязательно
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# Безопасность: ограничьте, кто может взаимодействовать с ботом
DINGTALK_ALLOWED_USERS=user-id-1

# Несколько разрешённых пользователей (через запятую)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

# Опционально: ограничение группового чата (аналогично Slack/Telegram/Discord/WhatsApp)
# DINGTALK_REQUIRE_MENTION=true
# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DINGTALK_MENTION_PATTERNS=^小马
# DINGTALK_HOME_CHANNEL=cidXXXX==
# DINGTALK_ALLOW_ALL_USERS=true

Опциональные настройки поведения в ~/.vibeos/config.yaml:

group_sessions_per_user: true

gateway:
  platforms:
    dingtalk:
      extra:
        # Требовать @упоминание в группах, прежде чем бот ответит (паритет со Slack/Telegram/Discord).
        # Личные сообщения игнорируют это — бот всегда отвечает в чатах 1:1.
        require_mention: true

        # Разрешённый список для конкретной платформы. Если установлен, только эти DingTalk User ID могут взаимодействовать с ботом
        # (та же семантика, что и DINGTALK_ALLOWED_USERS, но с областью действия здесь, а не в .env).
        allowed_users:
          - user-id-1
          - user-id-2

group_sessions_per_user: true сохраняет контекст каждого участника изолированным внутри общих групповых чатов
require_mention: true предотвращает ответ бота на каждое групповое сообщение — он отвечает только тогда, когда кто-то @упоминает его
allowed_users в dingtalk.extra является альтернативой DINGTALK_ALLOWED_USERS; если установлены оба, они объединяются

Запустите шлюз

После настройки запустите шлюз DingTalk:

vibeos gateway

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

подсказка

Вы можете запустить vibeos gateway в фоновом режиме или как службу systemd для постоянной работы. Смотрите документацию по развёртыванию для подробностей.

Возможности

AI-карточки

VibeOS может отвечать с помощью AI-карточек DingTalk вместо обычных сообщений в формате Markdown. Карточки обеспечивают более богатое и структурированное отображение и поддерживают потоковые обновления по мере генерации ответа агентом.

Чтобы включить AI-карточки, настройте ID шаблона карточки в config.yaml:

platforms:
  dingtalk:
    enabled: true
    extra:
      card_template_id: "your-card-template-id"

Вы можете найти ID шаблона карточки в DingTalk Developer Console в настройках AI-карточек вашего приложения. Когда AI-карточки включены, все ответы отправляются в виде карточек с потоковыми текстовыми обновлениями.

Реакции-эмодзи

VibeOS автоматически добавляет реакции-эмодзи к вашим сообщениям, чтобы показать статус обработки:

🤔Думаю — добавляется, когда бот начинает обрабатывать ваше сообщение
🥳Готово — добавляется, когда ответ завершён (заменяет реакцию «Думаю»)

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

Настройки отображения

Вы можете настроить поведение отображения DingTalk независимо от других платформ:

display:
  platforms:
    dingtalk:
      show_reasoning: false   # Показывать рассуждения/мышление модели в ответах
      streaming: true         # Включить потоковые ответы (работает с AI-карточками)
      tool_progress: all      # Показывать прогресс выполнения инструментов (all/new/off)
      interim_assistant_messages: true  # Показывать промежуточные комментарии ассистента

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

display:
  platforms:
    dingtalk:
      tool_progress: off
      interim_assistant_messages: false

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

Бот не отвечает на сообщения

Причина: Возможность робота не включена, или DINGTALK_ALLOWED_USERS не включает ваш User ID.

Решение: Убедитесь, что возможность робота включена в настройках вашего приложения и выбран Stream Mode. Проверьте, что ваш User ID находится в DINGTALK_ALLOWED_USERS. Перезапустите шлюз.

Ошибка «dingtalk-stream not installed»

Причина: Пакет Python dingtalk-stream не установлен.

Решение: Установите его:

pip install dingtalk-stream httpx

Ошибка «DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required»

Причина: Учётные данные не установлены в вашем окружении или файле .env.

Решение: Убедитесь, что DINGTALK_CLIENT_ID и DINGTALK_CLIENT_SECRET правильно установлены в ~/.vibeos/.env. Client ID — это ваш AppKey, а Client Secret — это ваш AppSecret из DingTalk Developer Console.

Разрывы потока / циклы переподключения

Причина: Нестабильность сети, техническое обслуживание платформы DingTalk или проблемы с учётными данными.

Решение: Адаптер автоматически переподключается с экспоненциальной задержкой (2с → 5с → 10с → 30с → 60с). Проверьте, что ваши учётные данные действительны и ваше приложение не деактивировано. Убедитесь, что ваша сеть разрешает исходящие WebSocket-соединения.

Бот не в сети

Причина: Шлюз VibeOS не запущен, или ему не удалось подключиться.

Решение: Проверьте, что vibeos gateway запущен. Посмотрите на вывод терминала на наличие сообщений об ошибках. Распространённые проблемы: неверные учётные данные, деактивированное приложение, не установлены dingtalk-stream или httpx.

Ошибка «No session_webhook available»

Причина: Бот попытался ответить, но у него нет URL сессионного вебхука. Обычно это происходит, если срок действия вебхука истёк или бот был перезапущен между получением сообщения и отправкой ответа.

Решение: Отправьте новое сообщение боту — каждое входящее сообщение предоставляет новый сессионный вебхук для ответов. Это нормальное ограничение DingTalk; бот может отвечать только на сообщения, полученные недавно.

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

предупреждение

Всегда устанавливайте DINGTALK_ALLOWED_USERS, чтобы ограничить круг лиц, которые могут взаимодействовать с ботом. Без этого шлюз по умолчанию отклоняет всех пользователей в качестве меры безопасности. Добавляйте только User ID людей, которым вы доверяете — авторизованные пользователи имеют полный доступ к возможностям агента, включая использование инструментов и доступ к системе.

Для получения дополнительной информации о защите вашего развёртывания VibeOS смотрите Руководство по безопасности.

Примечания

Stream Mode: Не требуется публичный URL, доменное имя или сервер вебхуков. Соединение инициируется с вашей машины через WebSocket, поэтому оно работает за NAT и брандмауэрами.
AI-карточки: Опционально отвечайте с помощью богатых AI-карточек вместо обычного Markdown. Настройте через card_template_id.
Реакции-эмодзи: Автоматические реакции 🤔Думаю/🥳Готово для статуса обработки.
Ответы в Markdown: Ответы форматируются в формате Markdown DingTalk для отображения форматированного текста.
Поддержка медиа: Изображения и файлы во входящих сообщениях автоматически разрешаются и могут быть обработаны инструментами зрения.
Дедупликация сообщений: Адаптер дедуплицирует сообщения с окном в 5 минут, чтобы предотвратить обработку одного и того же сообщения дважды.
Автоматическое переподключение: Если потоковое соединение разрывается, адаптер автоматически переподключается с экспоненциальной задержкой.
Ограничение длины сообщения: Ответы ограничены 20 000 символов на сообщение. Более длинные ответы обрезаются.

Поведение VibeOS​

Модель сеанса в DingTalk​

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

Шаг 1: Создайте приложение DingTalk​

Шаг 2: Включите возможность робота​

Шаг 3: Найдите свой DingTalk User ID​

Шаг 4: Настройте VibeOS​

Вариант A: Интерактивная настройка (рекомендуется)​

Вариант B: Ручная настройка​

Запустите шлюз​

Возможности​

AI-карточки​

Реакции-эмодзи​

Настройки отображения​

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

Бот не отвечает на сообщения​

Ошибка «dingtalk-stream not installed»​

Ошибка «DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required»​

Разрывы потока / циклы переподключения​

Бот не в сети​

Ошибка «No session_webhook available»​

Безопасность​

Примечания​