Перейти к содержанию

Dingtalk

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

Как ведёт себя Hermes​

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

Модель сессий в DingTalk​

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

Это управляется через config.yaml: [code] group_sessions_per_user: true

[/code] Установите false только если вы явно хотите один общий диалог для всей группы: [code] group_sessions_per_user: false

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

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

Установите необходимые пакеты Python: [code] pip install \"hermes-agent[dingtalk]\"

[/code] Или по отдельности: [code] pip install dingtalk-stream httpx alibabacloud-dingtalk

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

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

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

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

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

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

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

Шаг 3: Поиск вашего DingTalk User ID​

Hermes Agent использует ваш DingTalk User ID для контроля того, кто может взаимодействовать с ботом. DingTalk User ID — это буквенно-цифровые строки, задаваемые администратором вашей организации. Чтобы найти свой: 1. Спросите администратора вашей организации DingTalk — User ID настраиваются в консоли администратора DingTalk в разделе Contacts → Members. 2. Кроме того, бот записывает sender_id для каждого входящего сообщения. Запустите шлюз, отправьте боту сообщение, затем проверьте логи на наличие вашего ID.

Шаг 4: Настройка Hermes Agent​

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

Запустите команду интерактивной настройки: [code] hermes gateway setup

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

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

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

Добавьте следующее в ваш файл ~/.hermes/.env: [code] # Обязательно
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

[/code] Опциональные настройки поведения в ~/.hermes/config.yaml: [code] 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

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

Запуск шлюза​

После настройки запустите шлюз DingTalk: [code] hermes gateway

[/code] Бот должен подключиться к Stream Mode DingTalk в течение нескольких секунд. Отправьте ему сообщение — либо в ЛС, либо в группе, куда он был добавлен — для проверки. tip Вы можете запустить hermes gateway в фоне или как службу systemd для постоянной работы. Подробнее см. в документации по развёртыванию.

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

AI-карточки​

Hermes может отвечать с помощью DingTalk AI Cards вместо обычных markdown-сообщений. Карточки обеспечивают более насыщенное и структурированное отображение и поддерживают потоковые обновления по мере генерации ответа агентом. Чтобы включить AI-карточки, укажите ID шаблона карточки в config.yaml: [code] platforms:
dingtalk:
enabled: true
extra:
card_template_id: "your-card-template-id"

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

Emoji-реакции​

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

Эти реакции работают как в ЛС, так и в групповых чатах.

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

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

[/code] Чтобы отключить прогресс инструментов и промежуточные сообщения для более чистого отображения: [code] display:
platforms:
dingtalk:
tool_progress: off
interim_assistant_messages: false

[/code]

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

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

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

Ошибка «dingtalk-stream не установлен»​

Причина: Пакет Python dingtalk-stream не установлен. Исправление: Установите его: [code] pip install dingtalk-stream httpx

[/code]

«DINGTALK_CLIENT_ID и DINGTALK_CLIENT_SECRET обязательны»​

Причина: Учётные данные не заданы в вашем окружении или файле .env. Исправление: Проверьте, что DINGTALK_CLIENT_ID и DINGTALK_CLIENT_SECRET корректно заданы в ~/.hermes/.env. Client ID — это ваш AppKey, а Client Secret — ваш AppSecret из DingTalk Developer Console.

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

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

Бот офлайн​

Причина: Шлюз Hermes не запущен или не смог подключиться. Исправление: Проверьте, что hermes gateway запущен. Посмотрите вывод терминала на наличие сообщений об ошибках. Частые проблемы: неверные учётные данные, приложение деактивировано, не установлены dingtalk-stream или httpx.

«Нет доступного session_webhook»​

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

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

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

Примечания​