🏠 Главная › user guide › dingtalk

Настройка DingTalk

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

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

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

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

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

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

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

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

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

pip install dingtalk-stream httpx alibabacloud-dingtalk

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

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

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

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

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

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

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

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

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

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

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

hermes gateway setup

При получении запроса выберите 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, либо в совет группы, куда оно было добавлено — для проверки. Вы можете запустить «гермес-шлюз» в фоновом режиме или в качестве systemd службы мониторинга для постоянной работы. Подробности см. в документации по развертыванию.

Особенности

Карты ИИ

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

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

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

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

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

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

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

Настройки видеокарт

Вы можете настроить отображение 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 запущен. Посмотрите на вывод терминала об ошибках. Распространенные проблемы: неверные учетные данные, приложение деактивировано, не установлен dingtalk-stream или httpx.

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

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

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

Безопасность:::предупреждение

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

Примечания