📄 user-guide/messaging/discord.md

sidebar_position: 3 title: "Discord" description: "Set up Hermes Agent as a Discord bot"

การตั้งค่า Discord

Hermes Agent ผสานรวมกับ Discord ในรูปแบบบอท ทำให้คุณสามารถแชทกับ AI assistant ของคุณผ่าน direct messages หรือช่องทางในเซิร์ฟเวอร์ได้ บอทจะรับข้อความของคุณ ประมวลผลผ่าน pipeline ของ Hermes Agent (รวมถึง tool use, memory, และ reasoning) และตอบกลับแบบ real time รองรับข้อความประเภท text, voice messages, file attachments, และ slash commands

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

วิธีการทำงานของ Hermes

:::tip หากคุณต้องการช่องสำหรับให้คนคุยกับ Hermes โดยไม่ต้อง tag มันทุกครั้ง ให้เพิ่มช่องนั้นใน DISCORD_FREE_RESPONSE_CHANNELS :::

Discord Gateway Model

Hermes บน Discord ไม่ใช่ webhook ที่ตอบกลับแบบ statelessly แต่ทำงานผ่าน full messaging gateway ซึ่งหมายความว่าทุกข้อความที่เข้ามาจะผ่าน:

1. authorization (DISCORD_ALLOWED_USERS)
2. mention / free-response checks
3. session lookup
4. session transcript loading
5. normal Hermes agent execution, including tools, memory, and slash commands
6. response delivery back to Discord

สิ่งนี้มีความสำคัญเพราะพฤติกรรมในเซิร์ฟเวอร์ที่ยุ่งเหยิงขึ้นอยู่กับการกำหนดเส้นทางของ Discord และนโยบาย session ของ Hermes

Session Model in Discord

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

• แต่ละ DM จะได้ session ของตัวเอง
• แต่ละ server thread จะได้ session namespace ของตัวเอง
• ผู้ใช้แต่ละคนใน shared channel จะได้ session ของตัวเองภายในช่องนั้น

ดังนั้น หาก Alice และ Bob คุยกับ Hermes ใน #research ทั้งคู่ Hermes จะถือว่านั่นเป็นการสนทนาที่แยกจากกันโดยค่าเริ่มต้น แม้ว่าพวกเขาจะใช้ Discord channel ที่มองเห็นร่วมกันก็ตาม

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

group_sessions_per_user: true

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

group_sessions_per_user: false

Shared sessions อาจมีประโยชน์สำหรับห้องทำงานร่วมกัน แต่ก็หมายความว่า:

• ผู้ใช้แชร์ context growth และ token costs
• งานที่ใช้ tool หนักของคนหนึ่งสามารถทำให้ context ของคนอื่นบวมได้
• การรันแบบ in-flight ของคนหนึ่งสามารถขัดจังหวะการติดตามผลของอีกคนในห้องเดียวกันได้

Interrupts and Concurrency

Hermes ติดตาม agents ที่กำลังทำงานอยู่ด้วย session key

ด้วยค่าเริ่มต้น group_sessions_per_user: true:

• การที่ Alice ขัดจังหวะคำขอ in-flight ของตัวเองจะส่งผลกระทบเฉพาะ session ของ Alice ในช่องนั้น
• Bob สามารถพูดคุยต่อไปในช่องเดียวกันได้โดยไม่ได้รับประวัติของ Alice หรือขัดจังหวะการทำงานของ Alice

ด้วย group_sessions_per_user: false:

• ทั้งห้องจะแชร์ slot ของ running-agent เดียวกันสำหรับช่อง/thread นั้น
• ข้อความติดตามผลจากคนต่างกันสามารถขัดจังหวะหรือเข้าคิวต่อกันได้

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

Step 1: Create a Discord Application

1. ไปที่ Discord Developer Portal และลงชื่อเข้าใช้ด้วยบัญชี Discord ของคุณ
2. คลิก New Application ที่มุมขวาบน
3. ป้อนชื่อสำหรับแอปพลิเคชันของคุณ (เช่น "Hermes Agent") และยอมรับ Developer Terms of Service
4. คลิก Create

คุณจะเข้าสู่หน้า General Information ให้จด Application ID ไว้ - คุณจะต้องใช้สิ่งนี้ในภายหลังเพื่อสร้าง invite URL

Step 2: Create the Bot

1. ในแถบด้านซ้าย คลิก Bot
2. Discord จะสร้างผู้ใช้บอทสำหรับแอปพลิเคชันของคุณโดยอัตโนมัติ คุณจะเห็นชื่อผู้ใช้บอท ซึ่งคุณสามารถปรับแต่งได้
3. ใต้ Authorization Flow:
   • ตั้งค่า Public Bot เป็น ON - จำเป็นสำหรับการใช้ Discord-provided invite link (แนะนำ) สิ่งนี้ช่วยให้แท็บ Installation สามารถสร้าง default authorization URL ได้
   • ปล่อย Require OAuth2 Code Grant เป็น OFF

:::tip คุณสามารถตั้งค่า avatar และ banner แบบกำหนดเองสำหรับบอทของคุณในหน้านี้ นี่คือสิ่งที่ผู้ใช้จะเห็นใน Discord :::

:::info[Private Bot Alternative] หากคุณต้องการให้บอทของคุณเป็นส่วนตัว (Public Bot = OFF) คุณ ต้อง ใช้ method Manual URL ใน Step 5 แทนแท็บ Installation ลิงก์ที่ Discord ให้มาต้องเปิดใช้งาน Public Bot :::

Step 3: Enable Privileged Gateway Intents

นี่คือขั้นตอนที่สำคัญที่สุดในการตั้งค่าทั้งหมด หากไม่มีการเปิดใช้งาน intents ที่ถูกต้อง บอทของคุณจะเชื่อมต่อกับ Discord ได้ แต่ จะไม่สามารถอ่านเนื้อหาข้อความได้

ในหน้า Bot ให้เลื่อนลงไปที่ Privileged Gateway Intents คุณจะเห็นสวิตช์สามตัว:

เปิดใช้งานทั้ง Server Members Intent และ Message Content Intent โดยการสลับเป็น ON

• หากไม่มี Message Content Intent บอทของคุณจะได้รับ message events แต่ข้อความจะว่างเปล่า - บอทไม่สามารถเห็นสิ่งที่คุณพิมพ์ได้จริง ๆ
• หากไม่มี Server Members Intent บอทจะไม่สามารถ resolve usernames สำหรับรายชื่อผู้ใช้ที่อนุญาต และอาจล้มเหลวในการระบุว่าใครกำลังส่งข้อความถึงมัน

:::warning[นี่คือเหตุผลอันดับ 1 ที่บอท Discord ไม่ทำงาน] หากบอทของคุณออนไลน์อยู่แต่ไม่ตอบกลับข้อความเลย Message Content Intent เกือบจะถูกปิดใช้งานแล้ว ให้กลับไปที่ Developer Portal, เลือกแอปพลิเคชันของคุณ → Bot → Privileged Gateway Intents และตรวจสอบให้แน่ใจว่า Message Content Intent ถูกสลับเป็น ON คลิก Save Changes :::

เกี่ยวกับจำนวนเซิร์ฟเวอร์:

• หากบอทของคุณอยู่ใน น้อยกว่า 100 เซิร์ฟเวอร์ คุณสามารถสลับ intents เปิด-ปิดได้อย่างอิสระ
• หากบอทของคุณอยู่ใน 100 เซิร์ฟเวอร์หรือมากกว่า Discord กำหนดให้คุณต้องส่งใบสมัครตรวจสอบเพื่อใช้ privileged intents สำหรับการใช้งานส่วนตัว สิ่งนี้ไม่ใช่ข้อกังวล

คลิก Save Changes ที่ด้านล่างของหน้า

Step 4: Get the Bot Token

bot token คือ credential ที่ Hermes Agent ใช้ในการเข้าสู่ระบบในฐานะบอทของคุณ ยังคงอยู่ในหน้า Bot:

1. ใต้ส่วน Token คลิก Reset Token
2. หากคุณเปิดใช้งาน two-factor authentication บนบัญชี Discord ของคุณ ให้ป้อนรหัส 2FA ของคุณ
3. Discord จะแสดง token ใหม่ของคุณ คัดลอกทันที

:::warning[Token แสดงเพียงครั้งเดียว] token จะแสดงเพียงครั้งเดียว หากคุณทำหาย คุณจะต้องรีเซ็ตและสร้างใหม่ ห้ามแชร์ token ของคุณสู่สาธารณะหรือ commit มันไปยัง Git - ใครก็ตามที่มี token นี้จะควบคุมบอทของคุณได้อย่างเต็มที่ :::

เก็บ token ไว้ในที่ปลอดภัย (เช่น password manager) คุณจะต้องใช้มันใน Step 8

Step 5: Generate the Invite URL

คุณต้องการ OAuth2 URL เพื่อเชิญบอทไปยังเซิร์ฟเวอร์ของคุณ มีสองวิธีในการทำสิ่งนี้:

Option A: Using the Installation Tab (Recommended)

:::note[Requires Public Bot] วิธีนี้ต้องตั้งค่า Public Bot เป็น ON ใน Step 2 หากคุณตั้ง Public Bot เป็น OFF ให้ใช้วิธี Manual URL ด้านล่างแทน :::

1. ในแถบด้านซ้าย คลิก Installation
2. ใต้ Installation Contexts เปิดใช้งาน Guild Install
3. สำหรับ Install Link ให้เลือก Discord Provided Link
4. ใต้ Default Install Settings สำหรับ Guild Install:
   • Scopes: เลือก bot และ applications.commands
   • Permissions: เลือก permissions ที่ระบุไว้ด้านล่าง

Option B: Manual URL

คุณสามารถสร้าง invite URL ได้โดยตรงโดยใช้รูปแบบนี้:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

แทนที่ YOUR_APP_ID ด้วย Application ID จาก Step 1

Required Permissions

เหล่านี้คือ permissions ขั้นต่ำที่บอทของคุณต้องการ:

• View Channels - ดูช่องที่เข้าถึงได้
• Send Messages - ตอบกลับข้อความของคุณ
• Embed Links - จัดรูปแบบการตอบกลับที่สวยงาม
• Attach Files - ส่งรูปภาพ, เสียง, และไฟล์ output
• Read Message History - รักษา context การสนทนา

Recommended Additional Permissions

• Send Messages in Threads - ตอบกลับในบทสนทนาแบบ thread
• Add Reactions - แสดง reaction กับข้อความเพื่อการรับทราบ

Permission Integers

Step 6: Invite to Your Server

1. เปิด invite URL ในเบราว์เซอร์ของคุณ (จากแท็บ Installation หรือ manual URL ที่คุณสร้างขึ้น)
2. ในเมนูแบบเลื่อนลง Add to Server ให้เลือกเซิร์ฟเวอร์ของคุณ
3. คลิก Continue, จากนั้น Authorize
4. ทำ CAPTCHA ให้เสร็จสิ้นหากมีการแจ้งเตือน

:::info คุณต้องมี permission Manage Server ใน Discord server เพื่อเชิญบอท หากคุณไม่เห็นเซิร์ฟเวอร์ของคุณในเมนูแบบเลื่อนลง ให้ขอให้แอดมินเซิร์ฟเวอร์ใช้ invite link แทน :::

หลังจาก authorize แล้ว บอทจะปรากฏในรายชื่อสมาชิกของเซิร์ฟเวอร์ของคุณ (จะแสดงเป็น offline จนกว่าคุณจะเริ่ม Hermes gateway)

Step 7: Find Your Discord User ID

Hermes Agent ใช้ Discord User ID ของคุณเพื่อควบคุมว่าใครสามารถโต้ตอบกับบอทได้ คุณสามารถค้นหาได้โดย:

1. เปิด Discord (desktop หรือ web app)
2. ไปที่ Settings → Advanced → สลับ Developer Mode เป็น ON
3. ปิด settings
4. คลิกขวาที่ชื่อผู้ใช้ของคุณเอง (ในข้อความ, member list, หรือ profile) → Copy User ID

User ID ของคุณคือตัวเลขยาว ๆ เช่น 284102345871466496

:::tip Developer Mode ยังช่วยให้คุณคัดลอก Channel IDs และ Server IDs ในลักษณะเดียวกัน - คลิกขวาที่ชื่อช่องหรือเซิร์ฟเวอร์และเลือก Copy ID คุณจะต้องใช้ Channel ID หากคุณต้องการตั้งค่า home channel ด้วยตนเอง :::

Step 8: Configure Hermes Agent

Option A: Interactive Setup (Recommended)

รันคำสั่ง setup แบบ guided:

hermes gateway setup

เลือก Discord เมื่อถูกแจ้งเตือน จากนั้นวาง bot token และ user ID ของคุณเมื่อถูกถาม

Option B: Manual Configuration

เพิ่มสิ่งต่อไปนี้ในไฟล์ ~/.hermes/.env ของคุณ:

# Required
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# Multiple allowed users (comma-separated)
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

จากนั้นเริ่ม gateway:

hermes gateway

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

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

Configuration Reference

พฤติกรรมของ Discord ถูกควบคุมผ่านสองไฟล์: ~/.hermes/.env สำหรับ credentials และ env-level toggles และ ~/.hermes/config.yaml สำหรับการตั้งค่าที่มีโครงสร้าง Environment variables จะมีลำดับความสำคัญเหนือกว่าค่าใน config.yaml เสมอเมื่อทั้งสองถูกตั้งค่า

Environment Variables (.env)

Config File (config.yaml)

ส่วน discord ใน ~/.hermes/config.yaml สะท้อนถึง env vars ข้างต้น การตั้งค่า config.yaml จะถูกใช้เป็นค่าเริ่มต้น - หาก env var ที่เทียบเท่าถูกตั้งค่าไว้แล้ว env var จะมีลำดับความสำคัญกว่า

# Discord-specific settings
discord:
  require_mention: true           # Require @mention in server channels
  free_response_channels: ""      # Comma-separated channel IDs (or YAML list)
  auto_thread: true               # Auto-create threads on @mention
  reactions: true                 # Add emoji reactions during processing
  ignored_channels: []            # Channel IDs where bot never responds
  no_thread_channels: []          # Channel IDs where bot responds without threading
  channel_prompts: {}             # Per-channel ephemeral system prompts
  allow_mentions:                 # What the bot is allowed to ping (safe defaults)
    everyone: false               # @everyone / @here pings (default: false)
    roles: false                  # @role pings (default: false)
    users: true                   # @user pings (default: true)
    replied_user: true            # reply-reference pings the author (default: true)

# Session isolation (applies to all gateway platforms, not just Discord)
group_sessions_per_user: true     # Isolate sessions per user in shared channels

discord.require_mention

Type: boolean — Default: true

เมื่อเปิดใช้งาน บอทจะตอบกลับใน server channels เมื่อมีการ @mention โดยตรงเท่านั้น DMs จะได้รับคำตอบเสมอไม่ว่าการตั้งค่าจะเป็นอย่างไร

discord.free_response_channels

Type: string or list — Default: ""

Channel IDs ที่บอทตอบกลับทุกข้อความโดยไม่จำเป็นต้อง @mention ยอมรับได้ทั้ง string ที่คั่นด้วยจุลภาค หรือ YAML list:

# String format
discord:
  free_response_channels: "1234567890,9876543210"

# List format
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

หาก parent channel ของ thread อยู่ในรายการนี้ thread นั้นก็จะกลายเป็น mention-free ด้วย

Free-response channels ยัง ข้าม auto-threading - บอทจะตอบกลับแบบ inline แทนการสร้าง thread ใหม่ต่อข้อความ สิ่งนี้ทำให้ช่องยังคงใช้งานได้เป็น chat ที่เบาและใช้งานง่าย หากคุณต้องการพฤติกรรมการสร้าง thread อย่าระบุช่องนั้นเป็น free-response (ให้ใช้ flow @mention ปกติแทน)

discord.auto_thread

Type: boolean — Default: true

เมื่อเปิดใช้งาน ทุก @mention ใน text channel ปกติจะสร้าง thread ใหม่โดยอัตโนมัติสำหรับการสนทนานั้น สิ่งนี้ทำให้ main channel สะอาด และให้แต่ละบทสนทนามี session history ที่แยกจากกัน เมื่อสร้าง thread แล้ว ข้อความถัดไปใน thread นั้นไม่จำเป็นต้อง @mention - บอทรู้ว่ากำลังเข้าร่วมอยู่แล้ว

ข้อความที่ส่งใน thread หรือ DMs ที่มีอยู่แล้วไม่ได้รับผลกระทบจากการตั้งค่านี้ ช่องที่ระบุใน discord.free_response_channels หรือ discord.no_thread_channels ก็จะข้าม auto-threading และได้รับคำตอบแบบ inline แทน

discord.reactions

Type: boolean — Default: true

ควบคุมว่าบอทจะเพิ่ม emoji reactions ให้กับข้อความหรือไม่เพื่อเป็น visual feedback:

• 👀 เพิ่มเมื่อบอทเริ่มประมวลผลข้อความของคุณ
• ✅ เพิ่มเมื่อส่งการตอบกลับสำเร็จ
• ❌ เพิ่มหากเกิดข้อผิดพลาดระหว่างการประมวลผล

ปิดการใช้งานสิ่งนี้หากคุณพบว่า reactions รบกวน หรือหาก role ของบอทไม่มี permission Add Reactions

discord.ignored_channels

Type: string or list — Default: []

Channel IDs ที่บอท จะไม่ ตอบกลับเลย แม้ว่าจะถูก @mention โดยตรง สิ่งนี้มีลำดับความสำคัญสูงสุด - หากช่องอยู่ในรายการนี้ บอทจะเพิกเฉยต่อข้อความทั้งหมดโดยเงียบ ๆ ไม่ว่าจะเป็น require_mention, free_response_channels, หรือการตั้งค่าอื่น ๆ

# String format
discord:
  ignored_channels: "1234567890,9876543210"

# List format
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

หาก parent channel ของ thread อยู่ในรายการนี้ ข้อความใน thread นั้นก็จะถูกเพิกเฉยด้วย

discord.no_thread_channels

Type: string or list — Default: []

Channel IDs ที่บอทตอบกลับโดยตรงในช่องแทนการสร้าง thread สิ่งนี้มีผลเฉพาะเมื่อ auto_thread เป็น true เท่านั้น ในช่องเหล่านี้ บอทจะตอบกลับแบบ inline เหมือนข้อความปกติแทนการสร้าง thread ใหม่

discord:
  no_thread_channels:
    - 1234567890  # Bot responds inline here

มีประโยชน์สำหรับช่องที่ทุ่มเทให้กับการโต้ตอบกับบอท ซึ่ง thread จะเพิ่ม noise ที่ไม่จำเป็น

discord.channel_prompts

Type: mapping — Default: {}

Per-channel ephemeral system prompts ที่ถูกฉีดในทุก turn ใน Discord channel หรือ thread ที่ตรงกันโดยไม่ถูกบันทึกใน transcript history

discord:
  channel_prompts:
    "1234567890": |
      This channel is for research tasks. Prefer deep comparisons,
      citations, and concise synthesis.
    "9876543210": |
      This forum is for therapy-style support. Be warm, grounded,
      and non-judgmental.

พฤติกรรม:

• การจับคู่ ID ของ thread/channel ที่ตรงกันจะชนะ
• หากข้อความมาถึงภายใน thread หรือ forum post และ thread นั้นไม่มี entry ที่ชัดเจน Hermes จะย้อนกลับไปใช้ parent channel/forum ID
• Prompts ถูกนำไปใช้แบบ ephemerally ที่ runtime ดังนั้นการเปลี่ยนแปลงจะส่งผลต่อ future turns ทันทีโดยไม่ต้องเขียนทับ history ของ session ที่ผ่านมา

group_sessions_per_user

Type: boolean — Default: true

นี่คือการตั้งค่า gateway ทั่วโลก (ไม่เฉพาะ Discord) ที่ควบคุมว่าผู้ใช้ในช่องเดียวกันจะได้ session histories ที่แยกจากกันหรือไม่

เมื่อเป็น true: Alice และ Bob ที่คุยกันใน #research แต่ละคนจะมีบทสนทนากับ Hermes แยกกัน เมื่อเป็น false: ทั้งช่องจะแชร์ transcript การสนทนาและ slot ของ running-agent เดียวกัน

group_sessions_per_user: true

ดูที่ส่วน Session Model ด้านบนสำหรับนัยยะทั้งหมดของแต่ละโหมด

display.tool_progress

Type: string — Default: "all" — Values: off, new, all, verbose

ควบคุมว่าบอทจะส่ง progress messages ใน chat ขณะประมวลผลหรือไม่ (เช่น "Reading file...", "Running terminal command...") นี่คือการตั้งค่า gateway ทั่วโลกที่ใช้ได้กับทุกแพลตฟอร์ม

display:
  tool_progress: "all"    # off | new | all | verbose

• off — ไม่มี progress messages
• new — แสดงเฉพาะ tool call แรกต่อ turn
• all — แสดง tool calls ทั้งหมด (ถูกตัดให้เหลือ 40 ตัวอักษรใน gateway messages)
• verbose — แสดงรายละเอียด tool call ทั้งหมด (อาจสร้างข้อความยาว)

display.tool_progress_command

Type: boolean — Default: false

เมื่อเปิดใช้งาน จะทำให้ slash command /verbose พร้อมใช้งานใน gateway ทำให้คุณสามารถวนรอบโหมด tool progress ได้ (off → new → all → verbose → off) โดยไม่ต้องแก้ไข config.yaml

display:
  tool_progress_command: true

ตัวเลือก Model แบบโต้ตอบ (Interactive Model Picker)

ส่ง /model โดยไม่มี argument ในช่อง Discord เพื่อเปิดตัวเลือก Model แบบ Dropdown:

1. Provider selection - Dropdown ที่แสดง Provider ที่พร้อมใช้งาน (สูงสุด 25 รายการ)
2. Model selection - Dropdown ตัวที่สองที่แสดง Model สำหรับ Provider ที่เลือก (สูงสุด 25 รายการ)

ตัวเลือกนี้จะหมดเวลา (time out) หลังจาก 120 วินาที อนุญาตให้เฉพาะผู้ใช้ที่ได้รับอนุญาต (ผู้ที่อยู่ใน DISCORD_ALLOWED_USERS) เท่านั้นที่สามารถโต้ตอบกับตัวเลือกนี้ได้ หากคุณทราบชื่อ Model ให้พิมพ์ /model <name> ได้โดยตรง

คำสั่ง Slash แบบ Native สำหรับ Skills

Hermes จะลงทะเบียน Skills ที่ติดตั้งโดยอัตโนมัติเป็น Discord Application Commands แบบ Native ซึ่งหมายความว่า Skills เหล่านี้จะปรากฏในเมนู autocomplete / ของ Discord ควบคู่ไปกับคำสั่ง built-in

• แต่ละ Skill จะกลายเป็น Discord slash command (เช่น /code-review, /ascii-art)
• Skills สามารถรับพารามิเตอร์ string ชื่อ args แบบทางเลือก
• Discord มีข้อจำกัดที่ 100 application commands ต่อ bot - หากคุณมี Skills มากกว่าจำนวนช่องว่างที่มีอยู่ Skills ส่วนเกินจะถูกข้ามไปพร้อมกับการแจ้งเตือนใน logs
• Skills จะถูกลงทะเบียนในระหว่างการเริ่มต้น bot ควบคู่ไปกับคำสั่ง built-in เช่น /model, /reset, และ /background

ไม่จำเป็นต้องมีการตั้งค่าเพิ่มเติม - Skills ใดๆ ที่ติดตั้งผ่าน hermes skills install จะถูกลงทะเบียนเป็น Discord slash command โดยอัตโนมัติเมื่อมีการรีสตาร์ท gateway ครั้งถัดไป

ช่องหลัก (Home Channel)

คุณสามารถกำหนด "ช่องหลัก" ที่ bot จะส่งข้อความเชิงรุก (เช่น ผลลัพธ์ของ cron job, การแจ้งเตือน, และการแจ้งเตือนต่างๆ) มีสองวิธีในการตั้งค่า:

การใช้ Slash Command

พิมพ์ /sethome ในช่อง Discord ใดก็ได้ที่ bot อยู่ ช่องนั้นจะกลายเป็นช่องหลัก

การตั้งค่าด้วยตนเอง (Manual Configuration)

เพิ่มสิ่งเหล่านี้ลงใน ~/.hermes/.env ของคุณ:

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

แทนที่ ID ด้วย Channel ID จริง (คลิกขวา -> Copy Channel ID with Developer Mode)

ข้อความเสียง (Voice Messages)

Hermes Agent รองรับข้อความเสียงของ Discord:

• ข้อความเสียงขาเข้า (Incoming voice messages) จะถูกถอดเสียง (transcribed) โดยอัตโนมัติโดยใช้ STT provider ที่กำหนดค่าไว้: local faster-whisper (ไม่มี key), Groq Whisper (GROQ_API_KEY), หรือ OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
• Text-to-speech: ใช้ /voice tts เพื่อให้ bot ส่งการตอบกลับแบบเสียง (spoken audio) ควบคู่ไปกับข้อความตัวอักษร
• ช่องเสียง Discord: Hermes ยังสามารถเข้าร่วมช่องเสียง ฟังผู้ใช้พูด และตอบกลับในช่องนั้นได้

สำหรับคู่มือการตั้งค่าและการใช้งานฉบับเต็ม โปรดดูที่:

• Voice Mode
• Use Voice Mode with Hermes

ช่อง Forum (Forum Channels)

Discord forum channels (ประเภท 15) ไม่รับข้อความส่วนตัว (direct messages) - ทุกโพสต์ในฟอรัมจะต้องเป็น thread เท่านั้น Hermes จะตรวจจับ forum channels โดยอัตโนมัติ และสร้างโพสต์ thread ใหม่ทุกครั้งที่จำเป็นต้องส่งข้อความไปที่นั่น ดังนั้น send_message, TTS, รูปภาพ, ข้อความเสียง, และไฟล์แนบจึงทำงานได้ทั้งหมดโดยไม่ต้องมีการจัดการพิเศษจาก agent

• Thread name จะถูกดึงมาจากบรรทัดแรกของข้อความ (ลบ prefix ของ markdown heading และจำกัดสูงสุด 100 ตัวอักษร) เมื่อข้อความมีเฉพาะไฟล์แนบ ชื่อไฟล์จะถูกใช้เป็น thread name สำรอง
• Attachments จะถูกส่งไปพร้อมกับข้อความเริ่มต้นของ thread ใหม่ - ไม่ต้องมีการอัปโหลดแยกขั้นตอน และไม่มีการส่งแบบบางส่วน
• หนึ่งคำสั่ง, หนึ่ง thread: การส่งไปยัง forum แต่ละครั้งจะสร้าง thread ใหม่ ดังนั้นการส่งต่อเนื่องไปยัง forum เดียวกันจะสร้าง thread แยกกัน
• การตรวจจับมีสามระดับ: คือ cache ของ directory ช่องก่อน, cache ของ process-local ถัดมา, และการ probe แบบ live GET /channels/{id} เป็นทางเลือกสุดท้าย (ซึ่งผลลัพธ์จะถูก memoize ตลอดอายุของ process)

การรีเฟรช directory (/channels refresh บนแพลตฟอร์มที่เปิดเผย หรือการรีสตาร์ท gateway) จะเติม cache ด้วย forum channels ใดๆ ที่ถูกสร้างขึ้นหลังจากที่ bot เริ่มทำงาน

การแก้ไขปัญหา (Troubleshooting)

Bot ออนไลน์แต่ไม่ตอบสนองต่อข้อความ

สาเหตุ: Message Content Intent ถูกปิดใช้งาน

วิธีแก้ไข: ไปที่ Developer Portal -> app ของคุณ -> Bot -> Privileged Gateway Intents -> เปิดใช้งาน Message Content Intent -> Save Changes และรีสตาร์ท gateway

ข้อผิดพลาด "Disallowed Intents" เมื่อเริ่มต้น

สาเหตุ: โค้ดของคุณร้องขอ intents ที่ไม่ได้เปิดใช้งานใน Developer Portal

วิธีแก้ไข: เปิดใช้งาน Privileged Gateway Intents ทั้งสาม (Presence, Server Members, Message Content) ใน Bot settings จากนั้นรีสตาร์ท

Bot ไม่เห็นข้อความในช่องใดช่องหนึ่ง

สาเหตุ: Role ของ bot ไม่มีสิทธิ์ในการดูช่องนั้น

วิธีแก้ไข: ใน Discord ให้ไปที่การตั้งค่าของช่อง -> Permissions -> เพิ่ม role ของ bot พร้อมเปิดใช้งาน View Channel และ Read Message History

ข้อผิดพลาด 403 Forbidden

สาเหตุ: bot ขาดสิทธิ์ที่จำเป็น

วิธีแก้ไข: เชิญ bot ใหม่ด้วยสิทธิ์ที่ถูกต้องโดยใช้ URL จากขั้นตอนที่ 5 หรือปรับสิทธิ์ role ของ bot ด้วยตนเองใน Server Settings -> Roles

Bot ออฟไลน์

สาเหตุ: Hermes gateway ไม่ได้ทำงาน หรือ token ไม่ถูกต้อง

วิธีแก้ไข: ตรวจสอบว่า hermes gateway กำลังทำงานอยู่ ตรวจสอบ DISCORD_BOT_TOKEN ในไฟล์ .env ของคุณ หากคุณเพิ่งรีเซ็ต token ให้ทำการอัปเดต

"User not allowed" / Bot ไม่สนใจคุณ

สาเหตุ: User ID ของคุณไม่ได้อยู่ใน DISCORD_ALLOWED_USERS

วิธีแก้ไข: เพิ่ม User ID ของคุณใน DISCORD_ALLOWED_USERS ใน ~/.hermes/.env และรีสตาร์ท gateway

ผู้คนในช่องเดียวกันแชร์ context กันโดยไม่คาดคิด

สาเหตุ: group_sessions_per_user ถูกปิดใช้งาน หรือแพลตฟอร์มไม่สามารถให้ user ID สำหรับข้อความในบริบทนั้นได้

วิธีแก้ไข: ตั้งค่าสิ่งนี้ใน ~/.hermes/config.yaml และรีสตาร์ท gateway:

group_sessions_per_user: true

หากคุณต้องการการสนทนาห้องแชร์โดยเจตนา ให้ปล่อยค่านี้ไว้ — เพียงแค่คาดหวังประวัติการถอดเสียงที่แชร์และพฤติกรรม interrupt ที่แชร์

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

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

การควบคุมการเข้าถึงตาม Role (Role-Based Access Control)

สำหรับเซิร์ฟเวอร์ที่การเข้าถึงถูกจัดการด้วย role แทนที่จะเป็นรายการผู้ใช้รายบุคคล (เช่น ทีม moderator, เจ้าหน้าที่สนับสนุน, เครื่องมือภายใน) ให้ใช้ DISCORD_ALLOWED_ROLES - ซึ่งเป็นรายการ role ID ที่คั่นด้วยเครื่องหมายคอมมา สมาชิกคนใดที่มี role เหล่านั้นจะได้รับอนุญาต

# ~/.hermes/.env — ทำงานร่วมกับหรือแทนที่ DISCORD_ALLOWED_USERS
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

ความหมาย:

• OR กับ user allowlist. ผู้ใช้จะได้รับอนุญาตหาก ID ของพวกเขาอยู่ใน DISCORD_ALLOWED_USERS หรือ พวกเขามี role ใดๆ ใน DISCORD_ALLOWED_ROLES
• Server Members Intent auto-enabled. เมื่อตั้งค่า DISCORD_ALLOWED_ROLES bot จะเปิดใช้งาน Members intent เมื่อเชื่อมต่อ - ซึ่งจำเป็นสำหรับ Discord ในการส่งข้อมูล role พร้อมกับ record ของสมาชิก
• Role IDs ไม่ใช่ชื่อ. ดึงจาก Discord: User Settings → Advanced → Developer Mode ON, จากนั้นคลิกขวาที่ role ใดๆ -> Copy Role ID
• DM fallback. ใน DMs การตรวจสอบ role จะสแกน guild ร่วมกัน ผู้ใช้ที่มี role ที่ได้รับอนุญาตในเซิร์ฟเวอร์ที่แชร์ใดๆ จะได้รับอนุญาตใน DMs ด้วย

นี่คือรูปแบบที่แนะนำเมื่อทีม moderation มีการเปลี่ยนแปลง - moderator ใหม่จะได้รับสิทธิ์ทันทีที่ role ได้รับการมอบให้ โดยไม่ต้องแก้ไข .env หรือรีสตาร์ท gateway

การควบคุมการกล่าวถึง (Mention Control)

โดยค่าเริ่มต้น Hermes จะบล็อกไม่ให้ bot ping @everyone, @here, และการกล่าวถึง role แม้ว่าการตอบกลับของมันจะมี token เหล่านั้นก็ตาม สิ่งนี้ป้องกันไม่ให้ prompt ที่เขียนไม่ดีหรือเนื้อหาผู้ใช้ที่สะท้อนกลับไปสแปมทั้งเซิร์ฟเวอร์ การ ping @user รายบุคคล และการ ping อ้างอิงการตอบกลับ (ชิป "replying to...") ยังคงเปิดใช้งานเพื่อให้การสนทนาปกติยังคงทำงานได้

คุณสามารถผ่อนคลายค่าเริ่มต้นเหล่านี้ได้ผ่าน env vars หรือ config.yaml:

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # อนุญาตให้ bot ping @everyone / @here
    roles: false         # อนุญาตให้ bot ping @role mentions
    users: true          # อนุญาตให้ bot ping @users รายบุคคล
    replied_user: true   # ping ผู้เขียนเมื่อตอบกลับข้อความของพวกเขา

# ~/.hermes/.env — env vars ชนะ config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

:::tip ปล่อย everyone และ roles ไว้ที่ false เว้นแต่คุณจะทราบแน่ชัดว่าทำไมคุณถึงต้องการมัน มันง่ายมากที่ LLM จะสร้าง string @everyone ในการตอบกลับที่ดูเป็นปกติ; หากไม่มีการป้องกันนี้ นั่นจะแจ้งเตือนสมาชิกทุกคนในเซิร์ฟเวอร์ของคุณ :::

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

📄 user-guide/messaging/email.md

sidebar_position: 7 title: "อีเมล" description: "ตั้งค่า Hermes Agent ให้เป็นผู้ช่วยอีเมลผ่าน IMAP/SMTP"

การตั้งค่าอีเมล

Hermes สามารถรับและตอบกลับอีเมลโดยใช้โปรโตคอล IMAP และ SMTP มาตรฐาน ส่งอีเมลไปยังที่อยู่ของ agent และมันจะตอบกลับในเธรด (in-thread) โดยไม่จำเป็นต้องมี client หรือ bot API พิเศษ รองรับ Gmail, Outlook, Yahoo, Fastmail หรือผู้ให้บริการใดๆ ที่รองรับ IMAP/SMTP

:::info ไม่ต้องพึ่งพาภายนอก Email adapter ใช้โมดูล imaplib, smtplib, และ email ที่มาพร้อมกับ Python ไม่จำเป็นต้องใช้แพ็กเกจเพิ่มเติมหรือบริการภายนอก :::

ข้อกำหนดเบื้องต้น

• บัญชีอีเมลเฉพาะ สำหรับ Hermes agent ของคุณ (ห้ามใช้บัญชีส่วนตัว)
• เปิดใช้งาน IMAP บนบัญชีอีเมล
• รหัสผ่านแอป (App password) หากใช้ Gmail หรือผู้ให้บริการอื่นที่มี 2FA

การตั้งค่า Gmail

1. เปิดใช้งาน 2-Factor Authentication บน Google Account ของคุณ
2. ไปที่ App Passwords
3. สร้าง App Password ใหม่ (เลือก "Mail" หรือ "Other")
4. คัดลอกรหัสผ่าน 16 ตัวอักษร - คุณจะใช้รหัสนี้แทนรหัสผ่านปกติของคุณ

Outlook / Microsoft 365

1. ไปที่ Security Settings
2. เปิดใช้งาน 2FA หากยังไม่ได้เปิดใช้งาน
3. สร้าง App Password ภายใต้ "Additional security options"
4. IMAP host: outlook.office365.com, SMTP host: smtp.office365.com

ผู้ให้บริการอื่น ๆ

ผู้ให้บริการอีเมลส่วนใหญ่รองรับ IMAP/SMTP โปรดตรวจสอบเอกสารของผู้ให้บริการของคุณสำหรับ:

• IMAP host และ port (โดยปกติคือ port 993 พร้อม SSL)
• SMTP host และ port (โดยปกติคือ port 587 พร้อม STARTTLS)
• การใช้ app passwords

ขั้นตอนที่ 1: กำหนดค่า Hermes

วิธีที่ง่ายที่สุด:

hermes gateway setup

เลือก Email จากเมนูแพลตฟอร์ม ตัวช่วย (wizard) จะแจ้งให้คุณระบุอีเมลแอดเดรส รหัสผ่าน host ของ IMAP/SMTP และผู้ส่งที่อนุญาต

การกำหนดค่าด้วยตนเอง

เพิ่มใน ~/.hermes/.env:

# Required
EMAIL_ADDRESS=[email protected]
EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password (not your regular password)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# Security (recommended)
EMAIL_ALLOWED_USERS=[email protected],[email protected]

# Optional
EMAIL_IMAP_PORT=993                    # Default: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587                    # Default: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15                 # Seconds between inbox checks (default: 15)
EMAIL_HOME_ADDRESS=[email protected]      # Default delivery target for cron jobs

ขั้นตอนที่ 2: เริ่มต้น Gateway

hermes gateway              # Run in foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

เมื่อเริ่มต้นใช้งาน adapter จะ:

1. ทดสอบการเชื่อมต่อ IMAP และ SMTP
2. ทำเครื่องหมายข้อความใน inbox ที่มีอยู่ทั้งหมดเป็น "seen" (ประมวลผลเฉพาะอีเมลใหม่)
3. เริ่มการตรวจสอบข้อความใหม่ (polling)

การทำงาน

การรับข้อความ

adapter จะตรวจสอบ inbox ของ IMAP เพื่อหาข้อความที่ยังไม่ได้อ่าน (UNSEEN) ในช่วงเวลาที่กำหนดได้ (ค่าเริ่มต้น: 15 วินาที) สำหรับอีเมลใหม่แต่ละฉบับ:

• Subject line จะถูกรวมเป็นบริบท (เช่น [Subject: Deploy to production])
• Reply emails (subject ขึ้นต้นด้วย Re:) จะข้ามการใส่ prefix subject - บริบทของเธรดได้ถูกกำหนดไว้แล้ว
• Attachments จะถูกแคชในเครื่อง:
  • รูปภาพ (JPEG, PNG, GIF, WebP) → พร้อมใช้งานสำหรับ vision tool
  • เอกสาร (PDF, ZIP, etc.) → พร้อมใช้งานสำหรับการเข้าถึงไฟล์
• HTML-only emails จะมีการลบแท็กออกเพื่อดึงข้อความที่เป็น plain text
• Self-messages จะถูกกรองออกเพื่อป้องกันวงจรการตอบกลับ (reply loops)
• Automated/noreply senders จะถูกเพิกเฉยอย่างเงียบๆ - เช่น noreply@, mailer-daemon@, bounce@, no-reply@, และอีเมลที่มี header Auto-Submitted, Precedence: bulk, หรือ List-Unsubscribe

การส่งการตอบกลับ

การตอบกลับจะถูกส่งผ่าน SMTP พร้อมการจัดการเธรดอีเมลที่เหมาะสม:

• In-Reply-To และ References headers จะรักษาเธรด
• Subject line จะถูกเก็บรักษาพร้อม prefix Re: (ไม่ให้มี Re: Re:)
• Message-ID จะถูกสร้างด้วย domain ของ agent
• การตอบกลับจะถูกส่งเป็น plain text (UTF-8)

File Attachments

agent สามารถส่งไฟล์แนบได้ในการตอบกลับ ให้รวม MEDIA:/path/to/file ใน response และไฟล์นั้นจะถูกแนบไปกับอีเมลที่ส่งออก

การข้าม Attachments

หากต้องการเพิกเฉยต่อไฟล์แนบขาเข้าทั้งหมด (เพื่อป้องกันมัลแวร์หรือประหยัดแบนด์วิดท์) ให้เพิ่มใน config.yaml ของคุณ:

platforms:
  email:
    skip_attachments: true

เมื่อเปิดใช้งาน จะมีการข้าม attachment และ inline parts ก่อนการถอดรหัส payload ข้อความในเนื้อหาอีเมลยังคงถูกประมวลผลตามปกติ

การควบคุมการเข้าถึง

การเข้าถึงอีเมลเป็นไปตามรูปแบบเดียวกับแพลตฟอร์ม Hermes อื่น ๆ:

1. EMAIL_ALLOWED_USERS ถูกกำหนดค่า → จะประมวลผลเฉพาะอีเมลจากที่อยู่นเหล่านั้น
2. ไม่มีการกำหนด allowlist → ผู้ส่งที่ไม่ทราบจะได้รับรหัสจับคู่ (pairing code)
3. EMAIL_ALLOW_ALL_USERS=true → ยอมรับผู้ส่งทุกคน (ควรใช้ด้วยความระมัดระวัง)

:::warning ต้องกำหนดค่า EMAIL_ALLOWED_USERS เสมอ หากไม่มีการกำหนด ผู้ใดก็ตามที่รู้ที่อยู่อีเมลของ agent สามารถส่งคำสั่งได้ โดยค่าเริ่มต้น agent มีสิทธิ์เข้าถึง terminal :::

การแก้ไขปัญหา

ความปลอดภัย

:::warning ใช้บัญชีอีเมลเฉพาะ ห้ามใช้บัญชีส่วนตัว - agent จะจัดเก็บรหัสผ่านใน .env และมีสิทธิ์เข้าถึง inbox ทั้งหมดผ่าน IMAP :::

• ใช้ App Passwords แทนรหัสผ่านหลักของคุณ (จำเป็นสำหรับ Gmail ที่เปิด 2FA)
• กำหนด EMAIL_ALLOWED_USERS เพื่อจำกัดว่าใครสามารถโต้ตอบกับ agent ได้
• รหัสผ่านถูกจัดเก็บใน ~/.hermes/.env - โปรดป้องกันไฟล์นี้ (chmod 600)
• IMAP ใช้ SSL (port 993) และ SMTP ใช้ STARTTLS (port 587) โดยค่าเริ่มต้น - การเชื่อมต่อจะถูกเข้ารหัส

ข้อมูลอ้างอิงตัวแปร Environment

📄 user-guide/messaging/feishu.md

sidebar_position: 11 title: "Feishu / Lark" description: "Set up Hermes Agent as a Feishu or Lark bot"

การตั้งค่า Feishu / Lark

Hermes Agent ทำงานร่วมกับ Feishu และ Lark ในรูปแบบของ bot ที่มีคุณสมบัติครบถ้วน เมื่อเชื่อมต่อแล้ว คุณสามารถแชทกับ agent ได้ทั้งใน Direct messages หรือ group chats, รับผลลัพธ์ของ cron job ใน home chat, และส่งข้อความ รูปภาพ เสียง และไฟล์แนบผ่าน normal gateway flow

การเชื่อมต่อรองรับโหมดการเชื่อมต่อทั้งสองแบบ:

• websocket - แนะนำ; Hermes จะเปิด outbound connection และคุณไม่จำเป็นต้องมี public webhook endpoint
• webhook - มีประโยชน์เมื่อคุณต้องการให้ Feishu/Lark push events เข้ามาที่ gateway ของคุณผ่าน HTTP

วิธีการทำงานของ Hermes

พฤติกรรมของ shared-chat นี้ถูกควบคุมโดย config.yaml:

group_sessions_per_user: true

ให้ตั้งค่าเป็น false เฉพาะเมื่อคุณต้องการให้มีบทสนทนาที่แชร์กันเพียงครั้งเดียวต่อ chat เท่านั้น

ขั้นตอนที่ 1: สร้างแอป Feishu / Lark

แนะนำ: Scan-to-Create (คำสั่งเดียว)

hermes gateway setup

เลือก Feishu / Lark และสแกน QR code ด้วยแอปมือถือ Feishu หรือ Lark ของคุณ Hermes จะสร้างแอป bot โดยอัตโนมัติพร้อมสิทธิ์ที่ถูกต้องและบันทึก credentials

ทางเลือก: การตั้งค่าด้วยตนเอง (Manual Setup)

หากไม่สามารถใช้ scan-to-create ได้ wizard จะย้อนกลับไปใช้การป้อนข้อมูลด้วยตนเอง:

1. เปิด developer console ของ Feishu หรือ Lark:
   • Feishu: https://open.feishu.cn/
   • Lark: https://open.larksuite.com/
2. สร้างแอปใหม่
3. ในส่วน Credentials & Basic Info ให้คัดลอก App ID และ App Secret
4. เปิดใช้งานความสามารถ Bot สำหรับแอป
5. รัน hermes gateway setup, เลือก Feishu / Lark, และป้อน credentials เมื่อระบบแจ้ง

:::warning เก็บ App Secret เป็นความลับ ใครก็ตามที่มีสิ่งนี้สามารถปลอมตัวเป็นแอปของคุณได้ :::

ขั้นตอนที่ 2: เลือกโหมดการเชื่อมต่อ

แนะนำ: โหมด WebSocket

ใช้โหมด WebSocket เมื่อ Hermes ทำงานบน laptop, workstation หรือ private server ของคุณ ไม่จำเป็นต้องมี public URL Official Lark SDK จะเปิดและรักษาการเชื่อมต่อ WebSocket outbound แบบถาวรพร้อมการเชื่อมต่อใหม่โดยอัตโนมัติ

FEISHU_CONNECTION_MODE=websocket

ข้อกำหนด: ต้องติดตั้ง Python package websockets SDK จะจัดการ lifecycle การเชื่อมต่อ, heartbeats, และ auto-reconnection ภายใน

วิธีการทำงาน: adapter จะรัน WebSocket client ของ Lark SDK ใน background executor thread events ที่เข้ามา (ข้อความ, reactions, card actions) จะถูกส่งไปยัง main asyncio loop เมื่อการเชื่อมต่อหลุด SDK จะพยายามเชื่อมต่อใหม่โดยอัตโนมัติ

ทางเลือก: โหมด Webhook

ใช้โหมด webhook เมื่อคุณรัน Hermes อยู่เบื้องหลัง HTTP endpoint ที่เข้าถึงได้แล้วเท่านั้น

FEISHU_CONNECTION_MODE=webhook

ในโหมด webhook, Hermes จะเริ่ม HTTP server (ผ่าน aiohttp) และให้บริการ endpoint ของ Feishu ที่:

/feishu/webhook

ข้อกำหนด: ต้องติดตั้ง Python package aiohttp

คุณสามารถปรับแต่ง bind address และ path ของ webhook server ได้:

FEISHU_WEBHOOK_HOST=127.0.0.1   # default: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # default: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # default: /feishu/webhook

เมื่อ Feishu ส่ง URL verification challenge (type: url_verification), webhook จะตอบกลับโดยอัตโนมัติเพื่อให้คุณสามารถตั้งค่าการสมัครสมาชิกใน Feishu developer console ได้

ขั้นตอนที่ 3: กำหนดค่า Hermes

ตัวเลือก A: การตั้งค่าแบบโต้ตอบ (Interactive Setup)

hermes gateway setup

เลือก Feishu / Lark และกรอกข้อมูลตามที่ระบบแจ้ง

ตัวเลือก B: การกำหนดค่าด้วยตนเอง (Manual Configuration)

เพิ่มข้อมูลต่อไปนี้ใน ~/.hermes/.env:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# Optional but strongly recommended
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

FEISHU_DOMAIN รองรับ:

• feishu สำหรับ Feishu China
• lark สำหรับ Lark international

ขั้นตอนที่ 4: เริ่มต้น Gateway

hermes gateway

จากนั้นให้ส่งข้อความถึง bot จาก Feishu/Lark เพื่อยืนยันว่าการเชื่อมต่อทำงานแล้ว

Home Chat

ใช้ /set-home ใน chat ของ Feishu/Lark เพื่อกำหนดให้เป็น home channel สำหรับผลลัพธ์ของ cron job และการแจ้งเตือนข้ามแพลตฟอร์ม

คุณยังสามารถตั้งค่าล่วงหน้าได้:

FEISHU_HOME_CHANNEL=oc_xxx

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

User Allowlist

สำหรับการใช้งานใน production ให้ตั้งค่า allowlist ของ Feishu Open IDs:

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

หากคุณปล่อยให้ allowlist ว่างเปล่า ใครก็ตามที่เข้าถึง bot ได้อาจสามารถใช้งานได้ ใน group chats, allowlist จะถูกตรวจสอบกับ open_id ของผู้ส่งก่อนที่ข้อความจะถูกประมวลผล

Webhook Encryption Key

เมื่อทำงานในโหมด webhook, ให้ตั้งค่า encryption key เพื่อเปิดใช้งานการตรวจสอบ signature ของ webhook payload ที่เข้ามา:

FEISHU_ENCRYPT_KEY=your-encrypt-key

คีย์นี้สามารถหาได้ในส่วน Event Subscriptions ของการตั้งค่าแอป Feishu ของคุณ เมื่อตั้งค่าแล้ว adapter จะตรวจสอบทุก webhook request โดยใช้ signature algorithm:

SHA256(timestamp + nonce + encrypt_key + body)

ค่า hash ที่คำนวณได้จะถูกเปรียบเทียบกับ header x-lark-signature โดยใช้ timing-safe comparison Requests ที่มี signature ไม่ถูกต้องหรือขาดหายจะถูกปฏิเสธด้วย HTTP 401

:::tip ในโหมด WebSocket, การตรวจสอบ signature จะจัดการโดย SDK เอง ดังนั้น FEISHU_ENCRYPT_KEY จึงเป็นทางเลือก ในโหมด webhook, สิ่งนี้แนะนำอย่างยิ่งสำหรับการใช้งานใน production :::

Verification Token

ชั้นการตรวจสอบสิทธิ์เพิ่มเติมที่ตรวจสอบ field token ภายใน webhook payloads:

FEISHU_VERIFICATION_TOKEN=your-verification-token

โทเค็นนี้ก็สามารถหาได้ในส่วน Event Subscriptions ของแอป Feishu ของคุณ เมื่อตั้งค่าแล้ว ทุก webhook payload ที่เข้ามาจะต้องมี token ที่ตรงกันใน header object ของมัน Mismatched tokens จะถูกปฏิเสธด้วย HTTP 401

ทั้ง FEISHU_ENCRYPT_KEY และ FEISHU_VERIFICATION_TOKEN สามารถใช้ร่วมกันเพื่อเพิ่มความปลอดภัย (defense in depth)

นโยบายข้อความกลุ่ม (Group Message Policy)

ตัวแปร environment FEISHU_GROUP_POLICY ควบคุมว่า Hermes จะตอบกลับใน group chats หรือไม่และอย่างไร:

FEISHU_GROUP_POLICY=allowlist   # default

ในทุกโหมด, bot ต้องถูก @mention อย่างชัดเจน (หรือ @all) ในกลุ่มก่อนที่ข้อความจะถูกประมวลผล Direct messages จะข้าม gate นี้ไป

Bot Identity for @Mention Gating

สำหรับการตรวจจับ @mention ที่แม่นยำในกลุ่ม, adapter จำเป็นต้องรู้ identity ของ bot ซึ่งสามารถระบุได้อย่างชัดเจน:

FEISHU_BOT_OPEN_ID=ou_xxx
FEISHU_BOT_USER_ID=xxx
FEISHU_BOT_NAME=MyBot

หากไม่ได้ตั้งค่าสิ่งเหล่านี้, adapter จะพยายามค้นหาชื่อ bot โดยอัตโนมัติผ่าน Application Info API เมื่อเริ่มต้นทำงาน เพื่อให้สิ่งนี้ทำงานได้, ให้ grant permission scope admin:app.info:readonly หรือ application:application:self_manage

Interactive Card Actions

เมื่อผู้ใช้คลิกปุ่มหรือโต้ตอบกับ interactive cards ที่ส่งโดย bot, adapter จะส่งต่อสิ่งเหล่านี้เป็น synthetic /card command events:

• การคลิกปุ่มจะกลายเป็น: /card button {"key": "value", ...}
• payload value ของ action จาก card definition จะถูกรวมเป็น JSON
• Card actions จะถูก deduplicate ด้วยช่วงเวลา 15 นาทีเพื่อป้องกันการประมวลผลซ้ำ

Card action events จะถูกส่งด้วย MessageType.COMMAND, ดังนั้นจึงไหลผ่าน pipeline การประมวลผลคำสั่งปกติ

นี่คือวิธีที่ command approval ทำงานด้วย - เมื่อ agent ต้องการรันคำสั่งที่อันตราย, มันจะส่ง interactive card พร้อมปุ่ม Allow Once / Session / Always / Deny ผู้ใช้คลิกปุ่ม และ card action callback จะส่งผลการตัดสินใจอนุมัติกลับไปยัง agent

Required Feishu App Configuration

Interactive cards ต้องการการตั้งค่า สาม ขั้นตอนใน Feishu Developer Console การขาดขั้นตอนใดขั้นตอนหนึ่งจะทำให้เกิด error 200340 เมื่อผู้ใช้คลิกปุ่ม card

1. Subscribe to the card action event: ใน Event Subscriptions, เพิ่ม card.action.trigger เข้าไปใน events ที่คุณสมัครสมาชิก

2. Enable the Interactive Card capability: ใน App Features > Bot, ตรวจสอบให้แน่ใจว่า toggle Interactive Card ถูกเปิดใช้งาน สิ่งนี้บอก Feishu ว่าแอปของคุณสามารถรับ card action callbacks ได้

3. Configure the Card Request URL (webhook mode only): ใน App Features > Bot > Message Card Request URL, ตั้งค่า URL ให้เป็น endpoint เดียวกันกับ webhook event ของคุณ (เช่น https://your-server:8765/feishu/webhook) ในโหมด WebSocket สิ่งนี้จะถูกจัดการโดย SDK โดยอัตโนมัติ

:::warning หากขาดทั้งสามขั้นตอน, Feishu จะสามารถ ส่ง interactive cards ได้สำเร็จ (การส่งเท่านั้นที่ต้องการ permission im:message:send), แต่การคลิกปุ่มใดๆ จะส่งคืน error 200340 card จะดูเหมือนทำงาน - error จะปรากฏก็ต่อเมื่อผู้ใช้โต้ตอบกับมันเท่านั้น :::

Document Comment Intelligent Reply

นอกเหนือจากการแชท, adapter ยังสามารถตอบ @-mentions ที่ถูกทิ้งไว้บน เอกสาร Feishu/Lark ได้ เมื่อผู้ใช้คอมเมนต์บนเอกสาร (การเลือกข้อความในเครื่องหรือคอมเมนต์ทั้งเอกสาร) และ @-mention bot, Hermes จะอ่านเอกสารบวกกับ thread คอมเมนต์โดยรอบ และโพสต์ LLM reply แบบ inline ใน thread

ขับเคลื่อนด้วย event drive.notice.comment_add_v1, handler จะ:

• ดึงเนื้อหาเอกสารและ timeline คอมเมนต์แบบขนาน (20 ข้อความสำหรับ whole-doc threads, 12 สำหรับ local-selection threads)
• รัน agent ด้วย toolsets feishu_doc + feishu_drive ที่จำกัดขอบเขตสำหรับ session คอมเมนต์นั้นๆ
• แบ่ง replies เป็น chunk ที่ 4000 chars และโพสต์กลับเป็น threaded replies
• แคช per-document sessions เป็นเวลา 1 ชั่วโมง พร้อมขีดจำกัด 50 ข้อความ เพื่อให้คอมเมนต์ติดตามผลบนเอกสารเดียวกันยังคงมี context

3-Tier Access Control

การตอบกลับคอมเมนต์เอกสารเป็นแบบ explicit-grant only - ไม่มีโหมด allow-all โดยปริยาย Permissions จะถูกแก้ไขตามลำดับนี้ (match แรกที่ชนะ, ต่อ field):

1. Exact doc - rule ที่จำกัดขอบเขตสำหรับ document token เฉพาะ
2. Wildcard - rule ที่ตรงกับรูปแบบของเอกสาร
3. Top-level - default rule สำหรับ workspace

มีสองนโยบายที่ใช้ได้ต่อ rule:

• allowlist - รายการคงที่ของผู้ใช้ / tenants
• pairing - static list ∪ runtime-approved store มีประโยชน์สำหรับการ rollout ที่ moderator สามารถให้สิทธิ์เข้าถึงได้แบบสดๆ

Rules ถูกเก็บไว้ใน ~/.hermes/feishu_comment_rules.json (pairing grants ใน ~/.hermes/feishu_comment_pairing.json) พร้อม hot-reload ที่แคชด้วย mtime - การแก้ไขจะมีผลใน event คอมเมนต์ถัดไปโดยไม่ต้องรีสตาร์ท gateway

CLI:

# ตรวจสอบ rules และสถานะ pairing ปัจจุบัน
python -m gateway.platforms.feishu_comment_rules status

# จำลองการตรวจสอบการเข้าถึงสำหรับ doc + user เฉพาะ
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# จัดการ pairing grants ใน runtime
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>

Required Feishu App Configuration

นอกเหนือจากสิทธิ์ chat/card ที่ได้รับแล้ว, ให้เพิ่ม drive comment event:

• Subscribe to drive.notice.comment_add_v1 ใน Event Subscriptions
• Grant scopes docs:doc:readonly และ drive:drive:readonly เพื่อให้ handler สามารถอ่านเนื้อหาเอกสารได้

Media Support

Inbound (รับ)

adapter รับและแคช media types ต่อไปนี้จากผู้ใช้:

Media จาก rich-text (post) messages, รวมถึง inline images และ file attachments, ก็จะถูกดึงออกมาและแคชด้วย

สำหรับเอกสารข้อความขนาดเล็ก (.txt, .md), เนื้อหาไฟล์จะถูกฉีดเข้าไปในข้อความโดยอัตโนมัติเพื่อให้ agent สามารถอ่านได้โดยตรงโดยไม่จำเป็นต้องใช้ tools

Outbound (ส่ง)

การส่งต่อการอัปโหลดไฟล์เป็นแบบอัตโนมัติโดยอิงตาม extension:

• .ogg, .opus → อัปโหลดเป็นเสียง opus
• .mp4, .mov, .avi, .m4v → อัปโหลดเป็น media mp4
• .pdf, .doc(x), .xls(x), .ppt(x) → อัปโหลดพร้อมประเภทเอกสารของมัน
• อื่นๆ ทั้งหมด → อัปโหลดเป็น generic stream file

Markdown Rendering and Post Fallback

เมื่อ outbound text มี markdown formatting (headings, bold, lists, code blocks, links, etc.), adapter จะส่งมันเป็น Feishu post message โดยอัตโนมัติพร้อมแท็ก md ฝังตัว แทนที่จะเป็น plain text สิ่งนี้ช่วยให้สามารถแสดงผลแบบ rich ใน Feishu client ได้

หาก Feishu API ปฏิเสธ post payload (เช่น เนื่องจาก unsupported markdown constructs), adapter จะ fallback โดยอัตโนมัติเพื่อส่งเป็น plain text โดยลบ markdown ออกไป การ fallback สองขั้นตอนนี้ช่วยให้มั่นใจได้ว่าข้อความจะถูกส่งมอบเสมอ

ข้อความ plain text (ไม่ตรวจพบ markdown) จะถูกส่งเป็นประเภทข้อความ text แบบง่าย

Processing Status Reactions

ในขณะที่ agent กำลังทำงาน, bot จะแสดง reaction Typing บนข้อความของคุณ มันจะถูกล้างเมื่อ reply มาถึง, หรือถูกแทนที่ด้วย CrossMark หากการประมวลผลล้มเหลว

ตั้งค่า FEISHU_REACTIONS=false เพื่อปิดฟังก์ชันนี้

Burst Protection and Batching

adapter มี debouncing สำหรับ message bursts ที่รวดเร็วเพื่อหลีกเลี่ยงการทำให้ agent ทำงานหนักเกินไป:

Text Batching

เมื่อผู้ใช้ส่งข้อความ text หลายข้อความติดต่อกัน, ข้อความเหล่านั้นจะถูกรวมเป็น event เดียวก่อนที่จะถูกส่ง:

Media Batching

media attachments หลายรายการที่ส่งติดต่อกัน (เช่น การลากรูปภาพหลายรูป) จะถูกรวมเป็น event เดียว:

Per-Chat Serialization

ข้อความภายใน chat เดียวกันจะถูกประมวลผลแบบ serial (ทีละข้อความ) เพื่อรักษาความต่อเนื่องของการสนทนา แต่ละ chat มี lock ของตัวเอง ดังนั้นข้อความใน chat ต่างกันจึงถูกประมวลผลพร้อมกัน (concurrently)

Rate Limiting (Webhook Mode)

ในโหมด webhook, adapter บังคับใช้ per-IP rate limiting เพื่อป้องกันการใช้งานในทางที่ผิด:

• Window: 60-second sliding window
• Limit: 120 requests per window per (app_id, path, IP) triple
• Tracking cap: สูงสุด 4096 unique keys ที่ถูกติดตาม (ป้องกันการเติบโตของหน่วยความจำแบบไม่มีขีดจำกัด)

Requests ที่เกิน limit จะได้รับ HTTP 429 (Too Many Requests)

Webhook Anomaly Tracking

adapter ติดตามการตอบกลับ error ติดต่อกันต่อ IP address หลังจากเกิดข้อผิดพลาดติดต่อกัน 25 ครั้งจาก IP เดียวกันภายในช่วง 6 ชั่วโมง, จะมีการบันทึก warning สิ่งนี้ช่วยตรวจจับ client ที่ตั้งค่าผิดพลาดหรือความพยายามในการ probing

การป้องกัน webhook เพิ่มเติม:

• Body size limit: สูงสุด 1 MB
• Body read timeout: 30 seconds
• Content-Type enforcement: ยอมรับเฉพาะ application/json เท่านั้น

WebSocket Tuning

เมื่อใช้โหมด websocket, คุณสามารถปรับแต่งพฤติกรรมการ reconnect และ ping ได้:

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # วินาทีระหว่างการพยายาม reconnect (default: 120)
      ws_ping_interval: 30         # วินาทีระหว่าง WebSocket pings (optional; SDK default if unset)

Per-Group Access Control

นอกเหนือจาก FEISHU_GROUP_POLICY ทั่วโลก, คุณสามารถตั้งค่า rules ที่ละเอียดสำหรับแต่ละ group chat โดยใช้ group_rules ใน config.yaml:

platforms:
  feishu:
    extra:
      default_group_policy: "open"     # Default สำหรับกลุ่มที่ไม่ได้อยู่ใน group_rules
      admins:                          # ผู้ใช้ที่สามารถจัดการ bot settings
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"

กลุ่มที่ไม่ได้ระบุใน group_rules จะ fallback ไปที่ default_group_policy (ค่าเริ่มต้นคือค่าของ FEISHU_GROUP_POLICY)

Deduplication

Inbound messages ถูก deduplicate โดยใช้ message IDs พร้อม TTL 24 ชั่วโมง สถานะ dedup จะถูกเก็บไว้ข้ามการ restart ไปยัง ~/.hermes/feishu_seen_message_ids.json

All Environment Variables

การตั้งค่า WebSocket และ per-group ACL ทำผ่าน config.yaml ภายใต้ platforms.feishu.extra (ดู WebSocket Tuning และ Per-Group Access Control ด้านบน)

Troubleshooting

Toolset

Feishu / Lark ใช้ hermes-feishu platform preset ซึ่งรวม core tools เดียวกันกับ Telegram และแพลตฟอร์ม messaging อื่นๆ ที่ใช้ gateway

(Self-Correction/Review: Ensure the markdown links and formatting are preserved exactly as requested.)