📄 user-guide/messaging/index.md

sidebar_position: 1 title: "Messaging Gateway" description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Webhooks, or any OpenAI-compatible frontend via the API server - architecture and setup overview"

Messaging Gateway

แชทกับ Hermes ได้จาก Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, หรือจากเบราว์เซอร์ของคุณ Gateway เป็นกระบวนการพื้นหลัง (background process) ตัวเดียวที่เชื่อมต่อกับแพลตฟอร์มที่คุณกำหนดค่าทั้งหมด จัดการเซสชัน (sessions) รัน cron jobs และส่งข้อความเสียง

สำหรับชุดฟีเจอร์เสียงแบบเต็ม - รวมถึงโหมดไมโครโฟน CLI, การตอบกลับด้วยเสียงในข้อความ, และการสนทนาในช่องเสียง Discord - โปรดดูที่ Voice Mode และ Use Voice Mode with Hermes

การเปรียบเทียบแพลตฟอร์ม

Voice = การตอบกลับด้วยเสียง TTS และ/หรือการถอดเสียงข้อความเสียง Images = การส่ง/รับรูปภาพ Files = การส่ง/รับไฟล์แนบ Threads = การสนทนาแบบมีเธรด (threaded conversations) Reactions = ปฏิกิริยาอีโมจิบนข้อความ Typing = ตัวบ่งชี้การพิมพ์ขณะประมวลผล Streaming = การอัปเดตข้อความแบบต่อเนื่องผ่านการแก้ไข

สถาปัตยกรรม (Architecture)

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
            api["API Server<br/>(OpenAI-compatible)"]
            wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

Platform adapter แต่ละตัวจะรับข้อความ ส่งต่อผ่าน session store สำหรับแต่ละแชท และส่งไปยัง AIAgent เพื่อประมวลผล นอกจากนี้ Gateway ยังรัน cron scheduler ซึ่งจะทำงานทุก 60 วินาทีเพื่อดำเนินการงานที่ถึงกำหนดเวลา

การตั้งค่าเบื้องต้น (Quick Setup)

วิธีที่ง่ายที่สุดในการกำหนดค่าแพลตฟอร์มข้อความคือ interactive wizard:

hermes gateway setup        # Interactive setup for all messaging platforms

คำสั่งนี้จะนำคุณผ่านการกำหนดค่าแต่ละแพลตฟอร์มด้วยการเลือกด้วยปุ่มลูกศร แสดงแพลตฟอร์มที่กำหนดค่าไว้แล้ว และเสนอให้เริ่ม/รีสตาร์ท gateway เมื่อเสร็จสิ้น

คำสั่ง Gateway (Gateway Commands)

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

คำสั่งแชท (Chat Commands) (ภายใน Messaging)

การจัดการเซสชัน (Session Management)

Session Persistence

เซสชันจะคงอยู่ข้ามข้อความจนกว่าจะมีการรีเซ็ต Agent จะจดจำบริบทการสนทนาของคุณ

Reset Policies

เซสชันจะรีเซ็ตตามนโยบายที่กำหนดค่าได้:

กำหนดค่าการเขียนทับสำหรับแต่ละแพลตฟอร์มใน ~/.hermes/gateway.json:

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

ความปลอดภัย (Security)

โดยค่าเริ่มต้น Gateway จะปฏิเสธผู้ใช้ทุกคนที่ไม่ได้อยู่ใน allowlist หรือไม่ได้จับคู่ผ่าน DM นี่คือค่าเริ่มต้นที่ปลอดภัยสำหรับบอทที่มีสิทธิ์เข้าถึง terminal

# จำกัดเฉพาะผู้ใช้ที่ระบุ (แนะนำ):
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=[email protected],[email protected]
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2

# หรืออนุญาต
GATEWAY_ALLOWED_USERS=123456789,987654321

# หรืออนุญาตผู้ใช้ทุกคนอย่างชัดเจน (ไม่แนะนำสำหรับบอทที่มีสิทธิ์เข้าถึง terminal):
GATEWAY_ALLOW_ALL_USERS=true

DM Pairing (ทางเลือกแทน Allowlists)

แทนที่จะกำหนดค่า user ID ด้วยตนเอง ผู้ใช้ที่ไม่รู้จักจะได้รับรหัสจับคู่ (pairing code) แบบครั้งเดียวเมื่อพวกเขา DM หาบอท:

# ผู้ใช้จะเห็น: "Pairing code: XKGH5N7P"
# คุณอนุมัติพวกเขาด้วย:
hermes pairing approve telegram XKGH5N7P

# คำสั่ง pairing อื่นๆ:
hermes pairing list          # ดูผู้ใช้ที่รอดำเนินการ + ที่อนุมัติแล้ว
hermes pairing revoke telegram 123456789  # ลบการเข้าถึง

รหัสจับคู่จะหมดอายุภายใน 1 ชั่วโมง มีการจำกัดอัตรา (rate-limited) และใช้ cryptographic randomness

การขัดจังหวะ Agent (Interrupting the Agent)

ส่งข้อความใดๆ ขณะที่ agent กำลังทำงานเพื่อขัดจังหวงมัน พฤติกรรมหลักๆ:

• คำสั่ง terminal ที่กำลังดำเนินการอยู่จะถูกยกเลิกทันที (SIGTERM, จากนั้น SIGKILL หลังจาก 1 วินาที)
• Tool calls จะถูกยกเลิก - มีเพียงการเรียกใช้ที่กำลังดำเนินการอยู่เท่านั้นที่จะทำงาน ส่วนที่เหลือจะถูกข้ามไป
• ข้อความหลายรายการจะถูกรวมเข้าด้วยกัน - ข้อความที่ส่งระหว่างการขัดจังหวะจะถูกรวมเป็น prompt เดียว
• คำสั่ง /stop - ขัดจังหวะโดยไม่มีการจัดคิวข้อความติดตามผล

การแจ้งเตือนความคืบหน้าของ Tool (Tool Progress Notifications)

ควบคุมว่ากิจกรรมของ tool ส่วนใดจะแสดงใน ~/.hermes/config.yaml:

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # set to true to enable /verbose in messaging

เมื่อเปิดใช้งาน บอทจะส่งข้อความสถานะขณะทำงาน:

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

เซสชันพื้นหลัง (Background Sessions)

รัน prompt ในเซสชันพื้นหลังแยกต่างหาก เพื่อให้ agent ทำงานอย่างอิสระในขณะที่แชทหลักของคุณยังคงตอบสนองได้:

/background Check all servers in the cluster and report any that are down

Hermes จะยืนยันทันที:

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

วิธีการทำงาน (How It Works)

แต่ละ prompt /background จะสร้าง agent instance แยกต่างหาก ที่ทำงานแบบ asynchronous:

• Isolated session - background agent มีเซสชันของตัวเองพร้อมประวัติการสนทนาของตัวเอง มันไม่มีความรู้เกี่ยวกับบริบทแชทปัจจุบันของคุณ และรับเฉพาะ prompt ที่คุณให้เท่านั้น
• Same configuration - สืบทอด model, provider, toolsets, reasoning settings, และ provider routing จากการตั้งค่า gateway ปัจจุบัน
• Non-blocking - แชทหลักของคุณยังคงโต้ตอบได้อย่างเต็มที่ คุณสามารถส่งข้อความ รันคำสั่งอื่น หรือเริ่มงานพื้นหลังเพิ่มเติมได้ในขณะที่มันทำงาน
• Result delivery - เมื่องานเสร็จสิ้น ผลลัพธ์จะถูกส่งกลับไปยัง แชทหรือช่องเดียวกัน ที่คุณออกคำสั่ง โดยมีคำนำหน้าว่า "✅ Background task complete" หากล้มเหลว คุณจะเห็น "❌ Background task failed" พร้อมข้อผิดพลาด

การแจ้งเตือนกระบวนการพื้นหลัง (Background Process Notifications)

เมื่อ agent ที่รันเซสชันพื้นหลังใช้ terminal(background=true) เพื่อเริ่มกระบวนการที่ทำงานเป็นเวลานาน (เช่น servers, builds, ฯลฯ) gateway สามารถส่งการอัปเดตสถานะไปยังแชทของคุณได้ ควบคุมสิ่งนี้ด้วย display.background_process_notifications ใน ~/.hermes/config.yaml:

display:
  background_process_notifications: all    # all | result | error | off

คุณยังสามารถตั้งค่าสิ่งนี้ผ่าน environment variable:

HERMES_BACKGROUND_NOTIFICATIONS=result

Use Cases

• Server monitoring - "/background Check the health of all services and alert me if anything is down"
• Long builds - "/background Build and deploy the staging environment" ในขณะที่คุณยังคงแชทต่อไป
• Research tasks - "/background Research competitor pricing and summarize in a table"
• File operations - "/background Organize the photos in ~/Downloads by date into folders"

:::tip งานพื้นหลังบนแพลตฟอร์มข้อความเป็นแบบ fire-and-forget - คุณไม่จำเป็นต้องรอหรือตรวจสอบมัน ผลลัพธ์จะมาถึงในแชทเดียวกันโดยอัตโนมัติเมื่องานเสร็จสิ้น :::

การจัดการบริการ (Service Management)

Linux (systemd)

hermes gateway install               # Install as user service
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
journalctl --user -u hermes-gateway -f  # View logs

# Enable lingering (keeps running after logout)
sudo loginctl enable-linger $USER

# หรือติดตั้งระบบบริการที่ทำงานตั้งแต่บูต (boot-time system service) ที่ยังคงทำงานในฐานะผู้ใช้ของคุณ
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

ใช้ user service บนแล็ปท็อปและ dev boxes ใช้ system service บน VPS หรือ headless hosts ที่ควรกลับมาทำงานเมื่อบูตโดยไม่ต้องพึ่งพา systemd linger

หลีกเลี่ยงการติดตั้งทั้ง user และ system gateway units พร้อมกัน เว้นแต่คุณจะตั้งใจจริงๆ Hermes จะแจ้งเตือนหากตรวจพบทั้งสองอย่าง เนื่องจากพฤติกรรม start/stop/status จะคลุมเครือ

:::info Multiple installations หากคุณรันการติดตั้ง Hermes หลายครั้งบนเครื่องเดียวกัน (ด้วยไดเรกทอรี HERMES_HOME ที่แตกต่างกัน) แต่ละรายการจะได้รับชื่อบริการ systemd ของตัวเอง ค่าเริ่มต้น ~/.hermes ใช้ hermes-gateway; การติดตั้งอื่นใช้ hermes-gateway-<hash> คำสั่ง hermes gateway จะกำหนดเป้าหมายไปยังบริการที่ถูกต้องสำหรับ HERMES_HOME ปัจจุบันของคุณโดยอัตโนมัติ :::

macOS (launchd)

hermes gateway install               # Install as launchd agent
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
tail -f ~/.hermes/logs/gateway.log   # View logs

plist ที่สร้างขึ้นจะอยู่ที่ ~/Library/LaunchAgents/ai.hermes.gateway.plist ซึ่งรวม environment variables สามตัว:

• PATH - PATH ของ shell ทั้งหมดของคุณ ณ เวลาติดตั้ง โดยมีการเพิ่ม bin/ ของ venv และ node_modules/.bin เข้าไปด้านหน้า สิ่งนี้ทำให้มั่นใจได้ว่าเครื่องมือที่ติดตั้งโดยผู้ใช้ (Node.js, ffmpeg, ฯลฯ) สามารถใช้งานได้กับ subprocesses ของ gateway เช่น WhatsApp bridge
• VIRTUAL_ENV - ชี้ไปยัง Python virtualenv เพื่อให้เครื่องมือสามารถแก้ไขแพ็คเกจได้อย่างถูกต้อง
• HERMES_HOME - กำหนดขอบเขตของ gateway ให้กับการติดตั้ง Hermes ของคุณ

:::tip PATH เปลี่ยนแปลงหลังการติดตั้ง launchd plists เป็นแบบ static - หากคุณติดตั้งเครื่องมือใหม่ (เช่น Node.js เวอร์ชันใหม่ผ่าน nvm, หรือ ffmpeg ผ่าน Homebrew) หลังจากตั้งค่า gateway ให้รัน hermes gateway install อีกครั้งเพื่อจับ PATH ที่อัปเดตแล้ว Gateway จะตรวจพบ plist ที่ล้าสมัยและโหลดใหม่โดยอัตโนมัติ :::

:::info Multiple installations เช่นเดียวกับบริการ systemd ของ Linux แต่ละไดเรกทอรี HERMES_HOME จะได้รับ launchd label ของตัวเอง ค่าเริ่มต้น ~/.hermes ใช้ ai.hermes.gateway; การติดตั้งอื่นใช้ ai.hermes.gateway-<suffix> :::

Toolsets เฉพาะแพลตฟอร์ม (Platform-Specific Toolsets)

แต่ละแพลตฟอร์มมี toolset ของตัวเอง:

ขั้นตอนถัดไป (Next Steps)

• Telegram Setup
• Discord Setup
• Slack Setup
• WhatsApp Setup
• Signal Setup
• SMS Setup (Twilio)
• Email Setup
• Home Assistant Integration
• Mattermost Setup
• Matrix Setup
• DingTalk Setup
• Feishu/Lark Setup
• WeCom Setup
• WeCom Callback Setup
• Weixin Setup (WeChat)
• BlueBubbles Setup (iMessage)
• QQBot Setup
• Open WebUI + API Server
• Webhooks

📄 user-guide/messaging/bluebubbles.md

BlueBubbles (iMessage)

เชื่อมต่อ Hermes เข้ากับ Apple iMessage ผ่าน BlueBubbles - ซึ่งเป็น macOS server แบบ open-source ฟรี ที่ทำหน้าที่เชื่อมต่อ iMessage ไปยังอุปกรณ์ใดๆ ก็ได้

Prerequisites

• Mac (ต้องเปิดอยู่ตลอดเวลา) ที่รัน BlueBubbles Server
• Apple ID ที่ลงชื่อเข้าใช้ใน Messages.app บน Mac เครื่องนั้น
• BlueBubbles Server v1.0.0+ (webhooks ต้องใช้เวอร์ชันนี้)
• การเชื่อมต่อเครือข่ายระหว่าง Hermes และ BlueBubbles server

Setup

1. Install BlueBubbles Server

ดาวน์โหลดและติดตั้งจาก bluebubbles.app. ดำเนินการตาม setup wizard ให้เสร็จสมบูรณ์ - ลงชื่อเข้าใช้ด้วย Apple ID ของคุณและกำหนดค่าวิธีการเชื่อมต่อ (local network, Ngrok, Cloudflare, หรือ Dynamic DNS)

2. Get your Server URL and Password

ใน BlueBubbles Server → Settings → API, โปรดทราบ:

• Server URL (เช่น http://192.168.1.10:1234)
• Server Password

3. Configure Hermes

รัน setup wizard:

hermes gateway setup

เลือก BlueBubbles (iMessage) และป้อน server URL กับ password ของคุณ

หรือตั้งค่า environment variables โดยตรงใน ~/.hermes/.env:

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

4. Authorize Users

เลือกแนวทางใดแนวทางหนึ่ง:

DM Pairing (แนะนำ): เมื่อมีคนส่งข้อความถึง iMessage ของคุณ, Hermes จะส่งรหัส pairing ให้โดยอัตโนมัติ คุณสามารถอนุมัติรหัสนี้ได้ด้วยคำสั่ง:

hermes pairing approve bluebubbles <CODE>

ใช้ hermes pairing list เพื่อดูรหัสที่รอดำเนินการและผู้ใช้ที่อนุมัติแล้ว

Pre-authorize specific users (ใน ~/.hermes/.env):

BLUEBUBBLES_ALLOWED_USERS=[email protected],+15551234567

Open access (ใน ~/.hermes/.env):

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. Start the Gateway

hermes gateway run

Hermes จะเชื่อมต่อกับ BlueBubbles server ของคุณ, ลงทะเบียน webhook, และเริ่มรอรับข้อความ iMessage

How It Works

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage

• Inbound: BlueBubbles จะส่ง webhook events ไปยัง local listener เมื่อมีข้อความใหม่เข้ามา ไม่มีการ polling - ส่งมอบทันที
• Outbound: Hermes ส่งข้อความผ่าน BlueBubbles REST API
• Media: รองรับรูปภาพ, voice messages, วิดีโอ, และเอกสาร ทั้งสองทิศทาง ไฟล์แนบขาเข้าจะถูกดาวน์โหลดและแคชในเครื่องเพื่อที่ agent จะได้ประมวลผล

Environment Variables

Features

Text Messaging

ส่งและรับ iMessages Markdown จะถูกลบออกโดยอัตโนมัติเพื่อให้ส่งข้อความ plain-text ที่สะอาด

Rich Media

• Images: รูปภาพจะปรากฏใน iMessage conversation อย่างเป็นธรรมชาติ
• Voice messages: ไฟล์เสียงที่ส่งเป็น iMessage voice messages
• Videos: ไฟล์แนบวิดีโอ
• Documents: ไฟล์ที่ส่งเป็น iMessage attachments

Tapback Reactions

ปฏิกิริยา Love, like, dislike, laugh, emphasize, และ question ต้องการ Private API helper ของ BlueBubbles

Typing Indicators

แสดง "typing..." ใน iMessage conversation ขณะที่ agent กำลังประมวลผล ต้องการ Private API

Read Receipts

ทำเครื่องหมายข้อความว่าอ่านโดยอัตโนมัติหลังการประมวลผล ต้องการ Private API

Chat Addressing

คุณสามารถระบุแชทด้วยอีเมลหรือหมายเลขโทรศัพท์ - Hermes จะแก้ไขให้เป็น BlueBubbles chat GUIDs โดยอัตโนมัติ ไม่จำเป็นต้องใช้รูปแบบ GUID ดิบ

Private API

ฟีเจอร์บางอย่างต้องการ Private API helper ของ BlueBubbles:

• Tapback reactions
• Typing indicators
• Read receipts
• การสร้างแชทใหม่ด้วยที่อยู่

หากไม่มี Private API, การส่งข้อความและสื่อพื้นฐานยังคงใช้งานได้

Troubleshooting

"Cannot reach server"

• ตรวจสอบว่า server URL ถูกต้องและ Mac เปิดอยู่
• ตรวจสอบว่า BlueBubbles Server กำลังทำงาน
• ตรวจสอบการเชื่อมต่อเครือข่าย (firewall, port forwarding)

Messages not arriving

• ตรวจสอบว่า webhook ได้รับการลงทะเบียนใน BlueBubbles Server → Settings → API → Webhooks
• ตรวจสอบว่า webhook URL สามารถเข้าถึงได้จาก Mac
• ตรวจสอบ hermes logs gateway สำหรับข้อผิดพลาดของ webhook (หรือ hermes logs -f เพื่อติดตามแบบ real-time)

"Private API helper not connected"

• ติดตั้ง Private API helper: docs.bluebubbles.app
• การส่งข้อความพื้นฐานยังคงใช้งานได้โดยไม่ต้องใช้ - มีเพียงปฏิกิริยา, typing, และ read receipts เท่านั้นที่ต้องการมัน

📄 user-guide/messaging/dingtalk.md

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

การตั้งค่า DingTalk

Hermes Agent ทำงานร่วมกับ DingTalk (钉钉) ในรูปแบบแชทบอท ทำให้คุณสามารถแชทกับผู้ช่วย AI ของคุณได้ผ่านข้อความส่วนตัว (direct messages) หรือกลุ่มแชท บอทนี้เชื่อมต่อผ่าน Stream Mode ของ DingTalk ซึ่งเป็น WebSocket connection ที่มีอายุยาวนานและไม่จำเป็นต้องใช้ public URL หรือ webhook server และตอบกลับโดยใช้ข้อความที่จัดรูปแบบด้วย markdown ผ่าน DingTalk's session webhook API

ก่อนการตั้งค่า นี่คือส่วนที่คนส่วนใหญ่ต้องการทราบ: Hermes มีพฤติกรรมอย่างไรเมื่ออยู่ในพื้นที่ทำงาน DingTalk ของคุณ

Hermes ทำงานอย่างไร

Session Model ใน DingTalk

โดยค่าเริ่มต้น:

• แต่ละ DM จะได้รับ session ของตัวเอง
• ผู้ใช้แต่ละคนในกลุ่มแชทที่แชร์กันจะได้รับ session ของตัวเองภายในกลุ่มนั้น

สิ่งนี้ถูกควบคุมโดย config.yaml:

group_sessions_per_user: true

ให้ตั้งค่าเป็น false เฉพาะเมื่อคุณต้องการให้กลุ่มแชททั้งหมดใช้ conversation ร่วมกันเท่านั้น:

group_sessions_per_user: false

คู่มือนี้จะพาคุณไปดูขั้นตอนการตั้งค่าทั้งหมด - ตั้งแต่การสร้างบอท DingTalk ของคุณไปจนถึงการส่งข้อความแรก

Prerequisites

ติดตั้ง Python packages ที่จำเป็น:

pip install "hermes-agent[dingtalk]"

หรือติดตั้งทีละตัว:

pip install dingtalk-stream httpx alibabacloud-dingtalk

• dingtalk-stream - SDK อย่างเป็นทางการของ DingTalk สำหรับ Stream Mode (การส่งข้อความแบบ real-time ที่ใช้ WebSocket)
• httpx - async HTTP client ที่ใช้สำหรับส่งคำตอบผ่าน session webhooks
• alibabacloud-dingtalk - DingTalk OpenAPI SDK สำหรับ AI Cards, emoji reactions, และการดาวน์โหลดสื่อ

Step 1: Create a DingTalk App

1. ไปที่ DingTalk Developer Console.
2. เข้าสู่ระบบด้วยบัญชีผู้ดูแลระบบ DingTalk ของคุณ
3. คลิก Application Development → Custom Apps → Create App via H5 Micro-App (หรือ Robot ขึ้นอยู่กับเวอร์ชัน console ของคุณ)
4. กรอกข้อมูล:
   • App Name: เช่น Hermes Agent
   • Description: (ไม่บังคับ)
5. หลังจากสร้างแล้ว ให้ไปที่ Credentials & Basic Info เพื่อค้นหา Client ID (AppKey) และ Client Secret (AppSecret) คัดลอกทั้งสองค่า

:::warning[Credentials shown only once] Client Secret จะแสดงเพียงครั้งเดียวเมื่อคุณสร้างแอป หากคุณทำสูญหาย คุณจะต้องสร้างใหม่ ห้ามแชร์ credentials เหล่านี้สู่สาธารณะหรือ commit เข้า Git :::

Step 2: Enable the Robot Capability

1. ในหน้าการตั้งค่าแอปของคุณ ให้ไปที่ Add Capability → Robot.
2. เปิดใช้งาน robot capability
3. ภายใต้ Message Reception Mode, เลือก Stream Mode (แนะนำ - ไม่จำเป็นต้องใช้ public URL)

:::tip Stream Mode คือการตั้งค่าที่แนะนำ มันใช้การเชื่อมต่อ WebSocket ที่มีอายุยาวนานซึ่งเริ่มต้นจากเครื่องของคุณ ดังนั้นคุณจึงไม่จำเป็นต้องมี public IP, domain name, หรือ webhook endpoint วิธีนี้ทำงานได้แม้จะอยู่หลัง NAT, firewalls, และบนเครื่อง local :::

Step 3: Find Your DingTalk User ID

Hermes Agent ใช้ DingTalk User ID ของคุณเพื่อควบคุมว่าใครสามารถโต้ตอบกับบอทได้ User ID ของ DingTalk เป็นสตริง alphanumeric ที่กำหนดโดยผู้ดูแลระบบองค์กรของคุณ

ในการค้นหาของคุณ:

1. สอบถามผู้ดูแลระบบองค์กร DingTalk ของคุณ - User IDs จะถูกกำหนดค่าใน DingTalk admin console ภายใต้ Contacts → Members.
2. หรืออีกวิธีหนึ่ง บอทจะบันทึก sender_id สำหรับข้อความที่เข้ามาแต่ละข้อความ เริ่มต้น gateway, ส่งข้อความให้บอท จากนั้นตรวจสอบ logs เพื่อหา ID ของคุณ

Step 4: Configure Hermes Agent

Option A: Interactive Setup (Recommended)

รันคำสั่ง setup แบบมีคำแนะนำ:

hermes gateway setup

เมื่อระบบแจ้ง ให้เลือก DingTalk ตัวช่วยตั้งค่าจะสามารถอนุญาตผ่านช่องทางใดช่องทางหนึ่ง:

• QR-code device flow (แนะนำ). สแกน QR ที่พิมพ์ใน terminal ของคุณด้วยแอปมือถือ DingTalk - Client ID และ Client Secret ของคุณจะถูกส่งกลับมาโดยอัตโนมัติและเขียนลงใน ~/.hermes/.env ไม่จำเป็นต้องผ่าน developer-console
• Manual paste. หากคุณมี credentials อยู่แล้ว (หรือการสแกน QR ไม่สะดวก) ให้วาง Client ID, Client Secret, และ user ID ที่อนุญาตเมื่อระบบแจ้ง

:::note openClaw branding disclosure เนื่องจาก verification_uri_complete ของ DingTalk ถูก hardcode ให้เป็น openClaw identity ที่ชั้น API, QR จึงอนุญาตภายใต้ openClaw source string จนกว่า Alibaba / DingTalk-Real-AI จะลงทะเบียน template server-side สำหรับ Hermes โดยเฉพาะ นี่เป็นเพียงวิธีที่ DingTalk แสดงหน้า consent เท่านั้น - บอทที่คุณสร้างเป็นของคุณโดยสมบูรณ์และเป็นส่วนตัวสำหรับ tenant ของคุณ :::

Option B: Manual Configuration

เพิ่มข้อมูลต่อไปนี้ในไฟล์ ~/.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

การตั้งค่าพฤติกรรมทางเลือกใน ~/.hermes/config.yaml:

group_sessions_per_user: true

• group_sessions_per_user: true จะรักษา context ของผู้เข้าร่วมแต่ละคนให้แยกออกจากกันภายในกลุ่มแชทที่แชร์

Start the Gateway

เมื่อตั้งค่าเสร็จแล้ว ให้เริ่ม DingTalk gateway:

hermes gateway

บอทควรเชื่อมต่อกับ Stream Mode ของ DingTalk ภายในไม่กี่วินาที ส่งข้อความให้มัน - ไม่ว่าจะเป็น DM หรือในกลุ่มที่เพิ่มมันเข้าไป - เพื่อทดสอบ

:::tip คุณสามารถรัน hermes gateway ใน background หรือเป็น systemd service เพื่อให้ทำงานอย่างต่อเนื่อง ดูเอกสาร deployment สำหรับรายละเอียด :::

Features

AI Cards

Hermes สามารถตอบกลับโดยใช้ DingTalk AI Cards แทนข้อความ markdown ธรรมดา Cards ให้การแสดงผลที่สมบูรณ์และมีโครงสร้างมากขึ้น และรองรับการอัปเดตแบบ streaming ขณะที่ agent สร้างคำตอบ

ในการเปิดใช้งาน AI Cards ให้กำหนด card template ID ใน config.yaml:

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

คุณสามารถค้นหา card template ID ของคุณได้ใน DingTalk Developer Console ภายใต้การตั้งค่า AI Card ของแอปของคุณ เมื่อเปิดใช้งาน AI Cards การตอบกลับทั้งหมดจะถูกส่งเป็น cards พร้อมการอัปเดตข้อความแบบ streaming

Emoji Reactions

Hermes จะเพิ่ม emoji reactions ให้กับข้อความของคุณโดยอัตโนมัติเพื่อแสดงสถานะการประมวลผล:

• 🤔Thinking - เพิ่มเมื่อบอทเริ่มประมวลผลข้อความของคุณ
• 🥳Done - เพิ่มเมื่อการตอบกลับเสร็จสมบูรณ์ (แทนที่ Thinking reaction)

reactions เหล่านี้ใช้ได้ทั้งใน DMs และกลุ่มแชท

Display Settings

คุณสามารถปรับแต่งพฤติกรรมการแสดงผลของ DingTalk ได้อย่างอิสระจากแพลตฟอร์มอื่น ๆ:

display:
  platforms:
    dingtalk:
      show_reasoning: false   # แสดง reasoning/thinking ของ model ในการตอบกลับ
      streaming: true         # เปิดใช้งานการตอบกลับแบบ streaming (ใช้ได้กับ AI Cards)
      tool_progress: all      # แสดงความคืบหน้าของการทำงานของ tool (all/new/off)
      interim_assistant_messages: true  # แสดงข้อความ commentary ระหว่างกลาง

ในการปิด tool progress และ intermediate messages เพื่อประสบการณ์ที่สะอาดตาขึ้น:

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

Troubleshooting

Bot is not responding to messages

Cause: ไม่ได้เปิดใช้งาน robot capability หรือ DINGTALK_ALLOWED_USERS ไม่ได้รวม User ID ของคุณ

Fix: ตรวจสอบว่า robot capability ถูกเปิดใช้งานในการตั้งค่าแอปของคุณ และ Stream Mode ถูกเลือก ตรวจสอบว่า User ID ของคุณอยู่ใน DINGTALK_ALLOWED_USERS และเริ่ม gateway ใหม่

"dingtalk-stream not installed" error

Cause: ไม่ได้ติดตั้ง Python package dingtalk-stream

Fix: ติดตั้ง:

pip install dingtalk-stream httpx

"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"

Cause: credentials ไม่ได้ตั้งค่าใน environment หรือไฟล์ .env ของคุณ

Fix: ตรวจสอบว่า DINGTALK_CLIENT_ID และ DINGTALK_CLIENT_SECRET ถูกตั้งค่าอย่างถูกต้องใน ~/.hermes/.env Client ID คือ AppKey ของคุณ และ Client Secret คือ AppSecret จาก DingTalk Developer Console

Stream disconnects / reconnection loops

Cause: ความไม่เสถียรของเครือข่าย, การบำรุงรักษาแพลตฟอร์ม DingTalk, หรือปัญหา credentials

Fix: adapter จะเชื่อมต่อใหม่โดยอัตโนมัติด้วย exponential backoff (2s -> 5s -> 10s -> 30s -> 60s) ตรวจสอบว่า credentials ของคุณถูกต้องและแอปของคุณไม่ได้ถูกปิดใช้งาน ตรวจสอบว่าเครือข่ายของคุณอนุญาตการเชื่อมต่อ WebSocket แบบ outbound

Bot is offline

Cause: Hermes gateway ไม่ได้รัน หรือล้มเหลวในการเชื่อมต่อ

Fix: ตรวจสอบว่า hermes gateway กำลังทำงานอยู่ ดูที่ output ของ terminal เพื่อหาข้อความ error ปัญหาทั่วไป: credentials ผิด, app ถูกปิดใช้งาน, dingtalk-stream หรือ httpx ไม่ได้ติดตั้ง

"No session_webhook available"

Cause: บอทพยายามตอบกลับแต่ไม่มี session webhook URL ซึ่งโดยทั่วไปจะเกิดขึ้นหาก webhook หมดอายุหรือบอทถูกรีสตาร์ทระหว่างการรับข้อความและการส่งคำตอบ

Fix: ส่งข้อความใหม่ให้บอท - ข้อความที่เข้ามาแต่ละข้อความจะให้ session webhook ใหม่สำหรับการตอบกลับ นี่เป็นข้อจำกัดปกติของ DingTalk; บอทสามารถตอบกลับได้เฉพาะข้อความที่ได้รับเมื่อเร็วๆ นี้เท่านั้น

Security

:::warning ควรตั้งค่า DINGTALK_ALLOWED_USERS เสมอเพื่อจำกัดว่าใครสามารถโต้ตอบกับบอทได้ หากไม่มีการตั้งค่านี้ gateway จะปฏิเสธผู้ใช้ทั้งหมดโดยค่าเริ่มต้นเพื่อความปลอดภัย ควรเพิ่ม User ID ของผู้ที่คุณไว้ใจเท่านั้น - ผู้ใช้ที่ได้รับอนุญาตมีการเข้าถึงเต็มรูปแบบถึงความสามารถของ agent รวมถึงการใช้ tool และการเข้าถึงระบบ :::

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการรักษาความปลอดภัยในการ deploy Hermes Agent ของคุณ โปรดดู Security Guide.

Notes

• Stream Mode: ไม่จำเป็นต้องใช้ public URL, domain name, หรือ webhook server การเชื่อมต่อเริ่มต้นจากเครื่องของคุณผ่าน WebSocket ดังนั้นจึงทำงานได้หลัง NAT และ firewalls
• AI Cards: สามารถตอบกลับด้วย AI Cards ที่มีเนื้อหาที่สมบูรณ์แทน markdown ธรรมดา กำหนดค่าผ่าน card_template_id
• Emoji Reactions: การตอบกลับ 🤔Thinking/🥳Done อัตโนมัติสำหรับสถานะการประมวลผล
• Markdown responses: การตอบกลับจะถูกจัดรูปแบบด้วย markdown format ของ DingTalk สำหรับการแสดงผลข้อความที่สมบูรณ์
• Media support: รูปภาพและไฟล์ในข้อความที่เข้ามาจะถูก resolve โดยอัตโนมัติและสามารถประมวลผลได้โดย vision tools
• Message deduplication: adapter จะลบข้อความที่ซ้ำกันภายในช่วง 5 นาทีเพื่อป้องกันการประมวลผลข้อความเดียวกันซ้ำสองครั้ง
• Auto-reconnection: หากการเชื่อมต่อ stream หลุด adapter จะเชื่อมต่อใหม่โดยอัตโนมัติด้วย exponential backoff
• Message length limit: การตอบกลับถูกจำกัดที่ 20,000 characters ต่อข้อความ การตอบกลับที่ยาวกว่าจะถูกตัดทอน