🏠 Главная › Документация › Мессенджеры

Настройка DingTalk

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

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

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

Контекст Поведение
ЛС (1:1 чат) Hermes отвечает на каждое сообщение. @упоминание не требуется. Каждая ЛС имеет свою собственную сессию.
Групповые чаты Hermes отвечает, когда вы @упоминаете его. Без упоминания Hermes игнорирует сообщение.
Общие группы с несколькими пользователями По умолчанию 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 Developer Console.

  2. Войдите в систему с помощью учётной записи администратора DingTalk.

  3. Нажмите Application Development → Custom Apps → Create App via H5 Micro-App (или Robot, в зависимости от версии консоли).

  4. Заполните:

  5. App Name: например, Hermes Agent

  6. Description: необязательно

  7. После создания перейдите в Credentials & Basic Info, чтобы найти Client ID (AppKey) и Client Secret (AppSecret). Скопируйте оба.

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

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

  1. В настройках вашего приложения перейдите в Add Capability → Robot.

  2. Включите возможность Robot.

  3. В разделе Message Reception Mode выберите Stream Mode (рекомендуется — не требует публичного URL).

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

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

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

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

  1. Спросите администратора вашей организации DingTalk — User ID настраиваются в консоли администратора DingTalk в разделе Contacts → Members.

  2. Альтернативно, бот записывает sender_id для каждого входящего сообщения. Запустите gateway, отправьте боту сообщение, затем проверьте логи для получения своего ID.

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

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

hermes gateway setup

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

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

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

Добавьте следующее в файл ~/.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

Запуск Gateway

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

hermes gateway

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

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

Возможности

AI Cards

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

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

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

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

Emoji-реакции

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

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

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

Вы можете настроить поведение отображения 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

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

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

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

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

Ошибка «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 правильно указаны в ~/.hermes/.env. Client ID — это ваш AppKey, а Client Secret — ваш AppSecret из DingTalk Developer Console.

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

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

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

Бот не в сети

Причина: Gateway Hermes не запущен или не смог подключиться.

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

«No session_webhook available»

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

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

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

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

Для получения дополнительной информации о безопасности вашего развёртывания Hermes Agent см. Security Guide.

Примечания