🏠 Главная › User Guide › dingtalk

sidebar_position: 10 title: "DingTalk" description: "Set up Hermes Agent as a DingTalk chatbot" lang: ru

Настройка DingTalk

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

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

Как ведет себя Гермес

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

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

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

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

pip install "hermes-agent[dingtalk]"

Или индивидуально:

pip install dingtalk-stream httpx alibabacloud-dingtalk

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

  1. Перейдите в Консоль разработчика DingTalk.
  2. Войдите в свою учетную запись администратора DingTalk.
  3. Нажмите Разработка приложений → Пользовательские приложения → Создать приложение с помощью микроприложения H5 (или Робот в зависимости от версии вашей консоли).
  4. Заполните:
  5. Имя приложения: например, Hermes Agent.
  6. Описание: необязательно.
  7. После создания перейдите в раздел Учетные данные и основная информация, чтобы найти свой Идентификатор клиента (AppKey) и Секрет клиента (AppSecret). Скопируйте оба.

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

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

  1. На странице настроек вашего приложения выберите Добавить возможность → Робот.
  2. Включите возможности робота.
  3. В разделе Режим приема сообщений выберите Потоковый режим (рекомендуется — общедоступный URL-адрес не требуется).

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

Шаг 3. Найдите свой идентификатор пользователя DingTalk

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

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

  1. Обратитесь к администратору вашей организации DingTalk. Идентификаторы пользователей настраиваются в консоли администратора DingTalk в разделе Контакты → Участники.
  2. Альтернативно, бот регистрирует sender_id для каждого входящего сообщения. Запустите шлюз, отправьте боту сообщение, затем проверьте журналы на предмет вашего идентификатора.

Шаг 4. Настройка агента Hermes

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

Запустите команду управляемой настройки:

hermes gateway setup

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

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

Вариант Б: настройка вручную

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

# Required
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# Security: restrict who can interact with the bot
DINGTALK_ALLOWED_USERS=user-id-1

# Multiple allowed users (comma-separated)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

# Optional: group-chat gating (mirrors 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

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

group_sessions_per_user: true

gateway:
  platforms:
    dingtalk:
      extra:
        # Require @mention in groups before the bot replies (parity with Slack/Telegram/Discord).
        # DMs ignore this — the bot always replies in 1:1 chats.
        require_mention: true

        # Per-platform allowlist. When set, only these DingTalk user IDs can interact with the bot
        # (same semantics as DINGTALK_ALLOWED_USERS, but scoped here instead of in .env).
        allowed_users:
          - user-id-1
          - user-id-2

Запуск шлюза

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

hermes gateway

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

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

Особенности

Карты ИИ

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

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

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

Вы можете найти идентификатор шаблона своей карты в консоли разработчика DingTalk в настройках AI Card вашего приложения. Если карты AI включены, все ответы отправляются в виде карточек с потоковыми текстовыми обновлениями.

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

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

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

Настройки дисплея

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

display:
  platforms:
    dingtalk:
      show_reasoning: false   # Show model reasoning/thinking in replies
      streaming: true         # Enable streaming responses (works with AI Cards)
      tool_progress: all      # Show tool execution progress (all/new/off)
      interim_assistant_messages: true  # Show intermediate commentary messages

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

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

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

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

Причина: возможности робота не включены или DINGTALK_ALLOWED_USERS не включает ваш идентификатор пользователя.

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

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

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

Исправление. Установите:

pip install dingtalk-stream httpx

«Требуются DINGTALK_CLIENT_ID и DINGTALK_CLIENT_SECRET»

Причина: учетные данные не заданы в вашей среде или файле .env.

Исправление: убедитесь, что DINGTALK_CLIENT_ID и DINGTALK_CLIENT_SECRET установлены правильно в ~/.hermes/.env. Идентификатор клиента — это ваш ключ приложения, а секрет клиента — это ваш AppSecret из консоли разработчика DingTalk.

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

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

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

Бот не в сети

Причина: шлюз Hermes не работает или не удалось подключиться.

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

"Нет доступного session_webhook"

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

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

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

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

Примечания