DingTalk 설정

Hermes 에이전트는 DingTalk(钉钉)과 챗봇으로 통합되어, 직접 메시지나 그룹 채팅을 통해 AI 어시스턴트와 대화할 수 있습니다. 이 봇은 DingTalk의 스트림 모드 — 공용 URL이나 웹훅 서버가 필요 없는 장기 WebSocket 연결 — 를 통해 연결되며, DingTalk 세션 웹훅 API를 이용해 마크다운 형식 메시지로 응답합니다.

설정 전에, 대부분의 사람들이 가장 알고 싶어하는 부분은 Hermes가 당신의 DingTalk 작업 공간에 들어간 후 어떤 방식으로 동작하는지입니다.

Hermes의 동작 방식

컨텍스트	동작
DMs (1:1 채팅)	Hermes는 모든 메시지에 응답합니다. @mention가 필요 없습니다. 각 DM은 자체 세션을 가집니다.
그룹 채팅	Hermes는 당신이 @mention 할 때 반응합니다. 언급이 없으면 Hermes는 메시지를 무시합니다.
다중 사용자가 있는 공유 그룹	기본적으로 Hermes는 그룹 안에서 사용자별로 세션 기록을 분리합니다. 같은 그룹에서 대화하는 두 사람은 명시적으로 이를 비활성화하지 않는 한 하나의 기록을 공유하지 않습니다.

DingTalk의 세션 모델

기본적으로:

• 각 DM마다 자체 세션을 갖습니다
• 공유 그룹 채팅의 각 사용자는 해당 그룹 안에서 자신의 세션을 가집니다

이것은 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

• dingtalk-stream — DingTalk의 스트림 모드(WebSocket 기반 실시간 메시징)를 위한 공식 SDK
• httpx — 세션 웹후크를 통해 응답을 보내는 데 사용되는 비동기 HTTP 클라이언트
• alibabacloud-dingtalk — AI 카드, 이모지 반응 및 미디어 다운로드를 위한 DingTalk OpenAPI SDK

1단계: DingTalk 앱 만들기

1. DingTalk 개발자 콘솔로 이동하세요.
2. DingTalk 관리자 계정으로 로그인하세요.
3. 애플리케이션 개발→맞춤 앱→H5 마이크로 앱을 통해 앱 생성(또는 콘솔 버전에 따라 로봇)을 클릭합니다.
4. 작성:
   • 앱 이름: 예: Hermes Agent
   • 설명: 선택 사항
5. 생성한 후, 자격 증명 및 기본 정보로 이동하여 클라이언트 ID(AppKey)와 클라이언트 시크릿(AppSecret)를 찾으세요. 둘 다 복사하세요.

Credentials shown only once

클라이언트 시크릿은 앱을 생성할 때 한 번만 표시됩니다. 분실하면 재생성해야 합니다. 이러한 자격 증명을 공개적으로 공유하거나 Git에 커밋하지 마세요.

2단계: 로봇 기능 활성화

1. 앱의 설정 페이지에서 기능 추가→로봇으로 이동하세요.
2. 로봇 기능을 활성화하세요.
3. 메시지 수신 모드에서 스트림 모드를 선택하세요 (권장 — 공개 URL 필요 없음).

팁

스트림 모드는 권장 설정입니다. 이 모드는 사용자의 컴퓨터에서 시작되는 장기 WebSocket 연결을 사용하므로, 공용 IP, 도메인 이름 또는 웹훅 엔드포인트가 필요하지 않습니다. 이는 NAT, 방화벽 뒤 및 로컬 컴퓨터에서도 작동합니다.

단계 3: 당신의 DingTalk 사용자 ID 찾기

Hermes Agent는 DingTalk 사용자 ID를 사용하여 누가 봇과 상호작용할 수 있는지 제어합니다. DingTalk 사용자 ID는 조직의 관리자가 설정한 영숫자 문자열입니다.

당신의 것을 찾으려면:

1. DingTalk 조직 관리자에게 문의하세요 — 사용자 ID는 DingTalk 관리 콘솔의 연락처→회원에서 설정됩니다.
2. 또는, 봇은 들어오는 각 메시지에 대해 sender_id을 기록합니다. 게이트웨이를 시작하고, 봇에게 메시지를 보내고, 그런 다음 로그에서 당신의 ID를 확인하세요.

단계 4: Hermes 에이전트 구성

옵션 A: 인터랙티브 설정 (권장)

안내 설정 명령을 실행하세요:

hermes gateway setup

프롬프트가 나타나면 DingTalk을 선택하세요. 설치 마법사는 두 가지 경로 중 하나를 통해 인증할 수 있습니다:

• QR코드 장치 흐름(권장). 터미널에 출력된 QR 코드를 DingTalk 모바일 앱으로 스캔하면 클라이언트 ID와 클라이언트 시크릿이 자동으로 반환되어 ~/.hermes/.env에 기록됩니다. 개발자 콘솔에 접속할 필요가 없습니다.
• 수동 붙여넣기. 이미 자격 증명이 있거나(또는 QR 스캔이 불편한 경우) 요청 시 클라이언트 ID, 클라이언트 시크릿 및 허용된 사용자 ID를 붙여넣으세요.

openClaw branding disclosure

DingTalk의 verification_uri_complete가 API 레이어에서 openClaw 아이덴티티로 하드코딩되어 있기 때문에, 현재 QR은 Alibaba / DingTalk-Real-AI가 Hermes 전용 템플릿을 서버 측에 등록할 때까지 openClaw 소스 문자열로 인증됩니다. 이는 순전히 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`의 선택적 동작 설정:

```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

• group_sessions_per_user: true는 각 참가자의 컨텍스트를 공유 그룹 채팅 내에서 격리 상태로 유지합니다
• require_mention: true는 봇이 모든 그룹 메시지에 응답하는 것을 방지합니다 — 누군가가 @-멘션했을 때만 답변합니다
• allowed_users은 dingtalk.extra에서 DINGTALK_ALLOWED_USERS의 대안입니다; 두 개가 모두 설정되면, 그것들은 병합됩니다

게이트웨이를 시작하세요

설정이 완료되면 DingTalk 게이트웨이를 시작하십시오:

hermes gateway

봇은 몇 초 내에 DingTalk의 스트림 모드에 연결되어야 합니다. 테스트를 위해 DM이든 추가된 그룹이든 메시지를 보내세요.

팁

지속적인 운영을 위해 hermes gateway를 백그라운드나 systemd 서비스로 실행할 수 있습니다. 자세한 내용은 배포 문서를 참조하세요.

특징

AI 카드

Hermes는 일반 마크다운 메시지 대신 DingTalk AI 카드를 사용하여 응답할 수 있습니다. 카드는 더욱 풍부하고 구조화된 표시를 제공하며, 에이전트가 응답을 생성하는 동안 스트리밍 업데이트를 지원합니다.

AI 카드를 활성화하려면 config.yaml에 카드 템플릿 ID를 구성하십시오:

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

카드 템플릿 ID는 DingTalk 개발자 콘솔에서 앱의 AI 카드 설정 아래에서 찾을 수 있습니다. AI 카드가 활성화되면 모든 응답은 스트리밍 텍스트 업데이트와 함께 카드로 전송됩니다.

이모지 반응

Hermes는 처리 상태를 보여주기 위해 메시지에 자동으로 이모지 반응을 추가합니다:

• 🤔생각 중 — 봇이 메시지를 처리하기 시작할 때 추가됨
• 🥳완료 — 응답이 완료되면 추가됨 (생각 중 반응을 대체함)

이 반응들은 DM과 그룹 채팅 모두에서 작동합니다.

디스플레이 설정

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에 사용자 ID가 포함되어 있지 않습니다.

수정: 앱 설정에서 로봇 기능이 활성화되어 있고 스트림 모드가 선택되어 있는지 확인하세요. 사용자 ID가 DINGTALK_ALLOWED_USERS에 있는지 확인하세요. 게이트웨이를 다시 시작하세요.

"dingtalk-stream이 설치되어 있지 않음" 오류

원인: dingtalk-stream Python 패키지가 설치되어 있지 않습니다.

수정: 설치하세요:

pip install dingtalk-stream httpx

"DINGTALK_CLIENT_ID와 DINGTALK_CLIENT_SECRET이 필요합니다"

원인: 환경이나 .env 파일에 자격 증명이 설정되어 있지 않습니다.

수정: ~/.hermes/.env에서 DINGTALK_CLIENT_ID와 DINGTALK_CLIENT_SECRET가 올바르게 설정되었는지 확인하세요. 클라이언트 ID는 당신의 AppKey이고, 클라이언트 시크릿은 DingTalk 개발자 콘솔에서 가져온 AppSecret입니다.

스트림 연결 끊김 / 재연결 반복

원인: 네트워크 불안정, DingTalk 플랫폼 유지보수 또는 자격 증명 문제.

수정: 어댑터는 지수 백오프(2초 → 5초 → 10초 → 30초 → 60초)를 사용하여 자동으로 재연결됩니다. 자격 증명이 유효한지, 앱이 비활성화되지 않았는지 확인하세요. 네트워크가 아웃바운드 WebSocket 연결을 허용하는지 확인하세요.

봇이 오프라인입니다

원인: Hermes 게이트웨이가 실행되지 않거나 연결에 실패했습니다.

수정: hermes gateway가 실행 중인지 확인하세요. 오류 메시지는 터미널 출력을 확인하세요. 일반적인 문제: 잘못된 인증 정보, 앱 비활성화, dingtalk-stream 또는 httpx 미설치.

"사용 가능한 session_webhook이 없습니다"

원인: 봇이 답장을 시도했지만 세션 웹훅 URL이 없습니다. 이는 일반적으로 웹훅이 만료되었거나 메시지를 받은 후 답장을 보내기 전 봇이 재시작된 경우에 발생합니다.

수정: 봇에게 새 메시지를 보내세요 — 들어오는 각 메시지는 답장을 위한 새 세션 웹훅을 제공합니다. 이는 일반적인 DingTalk 제한 사항으로, 봇은 최근에 받은 메시지에만 답장할 수 있습니다.

보안

경고

항상 DINGTALK_ALLOWED_USERS를 설정하여 누가 봇과 상호작용할 수 있는지 제한하세요. 이를 설정하지 않으면, 안전 조치로 게이트웨이는 기본적으로 모든 사용자를 거부합니다. 신뢰하는 사람들의 사용자 ID만 추가하세요 — 인증된 사용자는 도구 사용 및 시스템 접근을 포함한 에이전트의 모든 기능에 완전히 접근할 수 있습니다.

Hermes 에이전트 배포 보안을 위한 자세한 정보는 보안 가이드를 참조하십시오.

노트

• 스트림 모드: 공개 URL, 도메인 이름 또는 웹훅 서버가 필요 없습니다. 연결은 WebSocket을 통해 사용자의 컴퓨터에서 시작되므로 NAT 및 방화벽 뒤에서도 작동합니다.
• AI 카드: 일반 마크다운 대신 선택적으로 풍부한 AI 카드를 사용해 응답할 수 있습니다. card_template_id을 통해 구성하세요.
• 이모지 반응: 처리 상태에 대한 자동 🤔생각 중/🥳완료 반응.
• 마크다운 응답: 답변은 풍부한 텍스트 표시를 위해 DingTalk의 마크다운 형식으로 포맷됩니다.
• 미디어 지원: 수신된 메시지의 이미지와 파일은 자동으로 처리되며 비전 도구로 처리할 수 있습니다.
• 메시지 중복 제거: 어댑터는 동일한 메시지를 두 번 처리하는 것을 방지하기 위해 5분 간격으로 메시지를 중복 제거합니다.
• 자동 재연결: 스트림 연결이 끊어지면 어댑터가 지수 백오프로 자동으로 재연결합니다.
• 메시지 길이 제한: 응답은 메시지당 20,000자로 제한됩니다. 더 긴 응답은 잘립니다.