📄 user-guide/messaging/homeassistant.md

title: Home Assistant description: Control your smart home with Hermes Agent via Home Assistant integration. sidebar_label: Home Assistant sidebar_position: 5

การผสานรวมกับ Home Assistant

Hermes Agent ผสานรวมกับ Home Assistant ได้ 2 วิธี:

1. Gateway platform - สมัครรับการเปลี่ยนแปลงสถานะแบบเรียลไทม์ผ่าน WebSocket และตอบสนองต่อเหตุการณ์ต่างๆ
2. Smart home tools - เครื่องมือ 4 ตัวที่สามารถเรียกใช้ผ่าน LLM สำหรับการสอบถามและควบคุมอุปกรณ์ผ่าน REST API

การตั้งค่า

1. สร้าง Long-Lived Access Token

1. เปิด Home Assistant instance ของคุณ
2. ไปที่ Profile ของคุณ (คลิกที่ชื่อของคุณในแถบด้านข้าง)
3. เลื่อนลงไปที่ Long-Lived Access Tokens
4. คลิก Create Token ตั้งชื่อ เช่น "Hermes Agent"
5. คัดลอก token

2. กำหนดค่า Environment Variables

# Add to ~/.hermes/.env

# Required: your Long-Lived Access Token
HASS_TOKEN=your-long-lived-access-token

# Optional: HA URL (default: http://homeassistant.local:8123)
HASS_URL=http://192.168.1.100:8123

:::info เครื่องมือ homeassistant จะถูกเปิดใช้งานโดยอัตโนมัติเมื่อมีการตั้งค่า HASS_TOKEN ทั้ง gateway platform และ device control tools จะเปิดใช้งานจาก token เดียวนี้ :::

3. เริ่มต้น Gateway

hermes gateway

Home Assistant จะปรากฏเป็น platform ที่เชื่อมต่ออยู่เคียงข้างกับแพลตฟอร์มการส่งข้อความอื่นๆ (เช่น Telegram, Discord เป็นต้น)

เครื่องมือที่ใช้งานได้

Hermes Agent ลงทะเบียนเครื่องมือ 4 ตัวสำหรับการควบคุม smart home:

ha_list_entities

แสดงรายการ entity ของ Home Assistant โดยสามารถกรองตาม domain หรือ area ได้ตามต้องการ

Parameters:

• domain (optional) - กรองตาม entity domain: light, switch, climate, sensor, binary_sensor, cover, fan, media_player, etc.
• area (optional) - กรองตามชื่อ area/ห้อง (เทียบกับ friendly names): living room, kitchen, bedroom, etc.

Example:

List all lights in the living room

จะส่งคืน entity IDs, states, และ friendly names

ha_get_state

รับสถานะโดยละเอียดของ entity เดียว รวมถึง attributes ทั้งหมด (เช่น brightness, color, temperature setpoint, sensor readings, etc.)

Parameters:

• entity_id (required) - entity ที่ต้องการสอบถาม เช่น light.living_room, climate.thermostat, sensor.temperature

Example:

What's the current state of climate.thermostat?

จะส่งคืน: state, all attributes, last changed/updated timestamps

ha_list_services

แสดงรายการบริการ (actions) ที่พร้อมใช้งานสำหรับการควบคุมอุปกรณ์ แสดงให้เห็นว่าสามารถดำเนินการใดได้บ้างกับอุปกรณ์แต่ละประเภท และรับ parameters อะไรบ้าง

Parameters:

• domain (optional) - กรองตาม domain เช่น light, climate, switch

Example:

What services are available for climate devices?

ha_call_service

เรียกใช้บริการของ Home Assistant เพื่อควบคุมอุปกรณ์

Parameters:

• domain (required) - Service domain: light, switch, climate, cover, media_player, fan, scene, script
• service (required) - Service name: turn_on, turn_off, toggle, set_temperature, set_hvac_mode, open_cover, close_cover, set_volume_level
• entity_id (optional) - Target entity เช่น light.living_room
• data (optional) - Additional parameters ในรูปแบบ JSON object

Examples:

Turn on the living room lights
→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")

Set the thermostat to 22 degrees in heat mode
→ ha_call_service(domain="climate", service="set_temperature",
    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})

Set living room lights to blue at 50% brightness
→ ha_call_service(domain="light", service="turn_on",
    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})

Gateway Platform: เหตุการณ์แบบเรียลไทม์

Home Assistant gateway adapter เชื่อมต่อผ่าน WebSocket และสมัครรับเหตุการณ์ state_changed เมื่อสถานะของอุปกรณ์มีการเปลี่ยนแปลงและตรงกับ filters ที่กำหนดไว้ จะถูกส่งต่อไปยัง agent เป็นข้อความ

Event Filtering

:::warning Required Configuration โดยค่าเริ่มต้น จะไม่มีการส่งต่อเหตุการณ์ใดๆ คุณต้องกำหนดค่าอย่างน้อยหนึ่งใน watch_domains, watch_entities, หรือ watch_all เพื่อรับเหตุการณ์ หากไม่มี filters จะมีการบันทึก warning เมื่อเริ่มต้นใช้งาน และการเปลี่ยนแปลงสถานะทั้งหมดจะถูกละเลยอย่างเงียบๆ :::

กำหนดค่าว่า agent จะเห็นเหตุการณ์ใดได้บ้างในไฟล์ ~/.hermes/config.yaml ภายใต้ส่วน extra ของ Home Assistant platform:

platforms:
  homeassistant:
    enabled: true
    extra:
      watch_domains:
        - climate
        - binary_sensor
        - alarm_control_panel
        - light
      watch_entities:
        - sensor.front_door_battery
      ignore_entities:
        - sensor.uptime
        - sensor.cpu_usage
        - sensor.memory_usage
      cooldown_seconds: 30

:::tip เริ่มต้นด้วยชุด domains ที่เน้นเฉพาะเจาะจง - climate, binary_sensor, และ alarm_control_panel ครอบคลุม automation ที่มีประโยชน์ที่สุด เพิ่มเติมตามความจำเป็น ใช้ ignore_entities เพื่อระงับ sensor ที่มีสัญญาณรบกวน เช่น อุณหภูมิ CPU หรือตัวนับ uptime :::

Event Formatting

การเปลี่ยนแปลงสถานะจะถูกจัดรูปแบบเป็นข้อความที่มนุษย์อ่านได้ตาม domain:

Agent Responses

ข้อความขาออกจาก agent จะถูกส่งในรูปแบบ Home Assistant persistent notifications (ผ่าน persistent_notification.create) สิ่งเหล่านี้จะปรากฏในแผงแจ้งเตือนของ HA โดยมีชื่อเรื่องว่า "Hermes Agent"

Connection Management

• WebSocket พร้อม heartbeat 30 วินาที สำหรับเหตุการณ์แบบเรียลไทม์
• Automatic reconnection พร้อม backoff: 5s → 10s → 30s → 60s
• REST API สำหรับการแจ้งเตือนขาออก (แยก session เพื่อหลีกเลี่ยงความขัดแย้งกับ WebSocket)
• Authorization - เหตุการณ์ HA จะได้รับการอนุญาตเสมอ (ไม่จำเป็นต้องมี user allowlist เนื่องจาก HASS_TOKEN ทำหน้าที่ยืนยันการเชื่อมต่อ)

ความปลอดภัย

เครื่องมือของ Home Assistant บังคับใช้ข้อจำกัดด้านความปลอดภัย:

:::warning Blocked Domains service domains ต่อไปนี้ถูก บล็อก เพื่อป้องกันการรันโค้ดแบบสุ่มบน host ของ HA:

• shell_command - คำสั่ง shell แบบสุ่ม
• command_line - sensors/switches ที่รันคำสั่ง
• python_script - การรัน Python แบบ scripted
• pyscript - การผสานรวม scripting ที่กว้างขึ้น
• hassio - การควบคุม addon, host shutdown/reboot
• rest_command - คำขอ HTTP จาก HA server (SSRF vector)

การพยายามเรียกใช้บริการใน domains เหล่านี้จะส่งคืนข้อผิดพลาด :::

Entity IDs จะถูกตรวจสอบความถูกต้องตามรูปแบบ ^[a-z_][a-z0-9_]*\.[a-z0-9_]+$ เพื่อป้องกันการโจมตีแบบ injection

ตัวอย่างระบบอัตโนมัติ

Morning Routine

User: Start my morning routine

Agent:
1. ha_call_service(domain="light", service="turn_on",
     entity_id="light.bedroom", data={"brightness": 128})
2. ha_call_service(domain="climate", service="set_temperature",
     entity_id="climate.thermostat", data={"temperature": 22})
3. ha_call_service(domain="media_player", service="turn_on",
     entity_id="media_player.kitchen_speaker")

Security Check

User: Is the house secure?

Agent:
1. ha_list_entities(domain="binary_sensor")
     → checks door/window sensors
2. ha_get_state(entity_id="alarm_control_panel.home")
     → checks alarm status
3. ha_list_entities(domain="lock")
     → checks lock states
4. Reports: "All doors closed, alarm is armed_away, all locks engaged."

Reactive Automation (via Gateway Events)

เมื่อเชื่อมต่อในรูปแบบ gateway platform agent สามารถตอบสนองต่อเหตุการณ์ได้:

[Home Assistant] Front Door: triggered (was cleared)

Agent automatically:
1. ha_get_state(entity_id="binary_sensor.front_door")
2. ha_call_service(domain="light", service="turn_on",
     entity_id="light.hallway")
3. Sends notification: "Front door opened. Hallway lights turned on."

📄 user-guide/messaging/matrix.md

sidebar_position: 9 title: "Matrix" description: "Set up Hermes Agent as a Matrix bot"

การตั้งค่า Matrix

Hermes Agent ทำงานร่วมกับ Matrix ซึ่งเป็นโปรโตคอลการส่งข้อความแบบ federated ที่เปิดกว้าง Matrix ช่วยให้คุณสามารถรัน homeserver ของตัวเอง หรือใช้ homeserver สาธารณะอย่าง matrix.org ได้ ไม่ว่าจะด้วยวิธีใด คุณก็ยังคงควบคุมการสื่อสารของคุณได้ บอทจะเชื่อมต่อผ่าน Python SDK mautrix ประมวลผลข้อความผ่าน pipeline ของ Hermes Agent (รวมถึงการใช้ tool, memory, และ reasoning) และตอบกลับแบบ real time โดยรองรับข้อความ, file attachments, รูปภาพ, เสียง, วิดีโอ, และการเข้ารหัสแบบ end-to-end (E2EE) แบบทางเลือก

Hermes ทำงานได้กับ homeserver Matrix ใดๆ - Synapse, Conduit, Dendrite, หรือ matrix.org

ก่อนการตั้งค่า นี่คือส่วนที่คนส่วนใหญ่ต้องการทราบ: Hermes จะมีพฤติกรรมอย่างไรเมื่อเชื่อมต่อแล้ว

พฤติกรรมของ Hermes

:::tip บอทจะเข้าร่วมห้องโดยอัตโนมัติเมื่อถูกเชิญ เพียงแค่เชิญผู้ใช้ Matrix ของบอทเข้าห้องใดก็ได้ มันจะเข้าร่วมและเริ่มตอบกลับทันที :::

Session Model ใน Matrix

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

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

การตั้งค่า Mention และ Threading

คุณสามารถกำหนดค่าพฤติกรรม mention และ auto-threading ผ่าน environment variables หรือ config.yaml:

matrix:
  require_mention: true           # ต้องการ @mention ในห้อง (ค่าเริ่มต้น: true)
  free_response_rooms:            # ห้องที่ได้รับการยกเว้นจากการกำหนดให้ต้อง mention
    - "!abc123:matrix.org"
  auto_thread: true               # สร้าง thread อัตโนมัติสำหรับการตอบกลับ (ค่าเริ่มต้น: true)
  dm_mention_threads: false       # สร้าง thread เมื่อ @mentioned ใน DM (ค่าเริ่มต้น: false)

หรือผ่าน environment variables:

MATRIX_REQUIRE_MENTION=true
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true          # default: true — emoji reactions ระหว่างการประมวลผล

:::tip Disabling reactions MATRIX_REACTIONS=false จะปิด emoji reactions ในระหว่าง lifecycle การประมวลผลที่บอทโพสต์ในข้อความขาเข้า มีประโยชน์สำหรับห้องที่ event ของ reaction มีมากเกินไป หรือไม่ได้รองรับโดย client ที่เข้าร่วมทั้งหมด :::

:::note หากคุณกำลังอัปเกรดจากเวอร์ชันที่ไม่มี MATRIX_REQUIRE_MENTION บอทจะตอบกลับทุกข้อความในห้องก่อนหน้านี้ เพื่อรักษาพฤติกรรมนั้น ให้ตั้งค่า MATRIX_REQUIRE_MENTION=false :::

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

ขั้นตอนที่ 1: สร้างบัญชีบอท

คุณต้องมีบัญชีผู้ใช้ Matrix สำหรับบอท มีหลายวิธีในการทำเช่นนี้:

Option A: ลงทะเบียนบน Homeserver ของคุณ (แนะนำ)

หากคุณรัน homeserver ของตัวเอง (Synapse, Conduit, Dendrite):

1. ใช้ admin API หรือ registration tool เพื่อสร้างผู้ใช้ใหม่:

# Synapse example
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

1. เลือกชื่อผู้ใช้ เช่น hermes - user ID เต็มจะเป็น @hermes:your-server.org

Option B: ใช้ matrix.org หรือ Homeserver สาธารณะอื่น

1. ไปที่ Element Web และสร้างบัญชีใหม่
2. เลือกชื่อผู้ใช้สำหรับบอทของคุณ (เช่น hermes-bot)

Option C: ใช้บัญชีของคุณเอง

คุณยังสามารถรัน Hermes ในฐานะผู้ใช้ของคุณเองได้ ซึ่งหมายความว่าบอทจะโพสต์ในชื่อของคุณ - มีประโยชน์สำหรับผู้ช่วยส่วนตัว

ขั้นตอนที่ 2: รับ Access Token

Hermes ต้องการ access token เพื่อยืนยันตัวตนกับ homeserver คุณมีสองทางเลือก:

Option A: Access Token (แนะนำ)

วิธีที่เชื่อถือได้ที่สุดในการรับ token:

ผ่าน Element:

1. เข้าสู่ระบบ Element ด้วยบัญชีบอท
2. ไปที่ Settings → Help & About.
3. เลื่อนลงและขยาย Advanced - access token จะแสดงอยู่ที่นั่น
4. คัดลอกทันที

ผ่าน API:

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes:your-server.org",
    "password": "your-password"
  }'

การตอบกลับจะรวม field access_token - คัดลอกสิ่งนี้

:::warning[เก็บ access token ของคุณให้ปลอดภัย] access token ให้สิทธิ์เข้าถึงบัญชี Matrix ของบอทอย่างเต็มที่ ห้ามแชร์ต่อสาธารณะหรือ commit เข้า Git หากถูกบุกรุก ให้เพิกถอนสิทธิ์โดยการออกจากระบบทุก session สำหรับผู้ใช้นั้น :::

Option B: Password Login

แทนที่จะให้ access token คุณสามารถให้ user ID และ password ของบอทแก่ Hermes ได้ Hermes จะเข้าสู่ระบบโดยอัตโนมัติเมื่อเริ่มต้น นี่ง่ายกว่า แต่หมายความว่า password จะถูกเก็บไว้ในไฟล์ .env ของคุณ

MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-password

ขั้นตอนที่ 3: ค้นหา Matrix User ID ของคุณ

Hermes Agent ใช้ Matrix User ID ของคุณเพื่อควบคุมว่าใครสามารถโต้ตอบกับบอทได้ Matrix User IDs มีรูปแบบ @username:server

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

1. เปิด Element (หรือ Matrix client ที่คุณต้องการ)
2. คลิกที่ avatar ของคุณ → Settings.
3. User ID ของคุณจะแสดงที่ด้านบนของโปรไฟล์ (เช่น @alice:matrix.org)

:::tip Matrix User IDs จะขึ้นต้นด้วย @ เสมอ และมี : ตามด้วยชื่อ server ตัวอย่างเช่น: @alice:matrix.org, @bob:your-server.com :::

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

Option A: การตั้งค่าแบบ Interactive (แนะนำ)

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

hermes gateway setup

เลือก Matrix เมื่อถูกแจ้งเตือน จากนั้นให้ URL homeserver, access token (หรือ user ID + password), และ user IDs ที่อนุญาตเมื่อถูกถาม

Option B: การกำหนดค่าแบบ Manual

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

เมื่อใช้ access token:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Optional: user ID (auto-detected from token if omitted)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Security: restrict who can interact with the bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Multiple allowed users (comma-separated)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

เมื่อใช้ password login:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Security
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

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

group_sessions_per_user: true

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

เริ่มต้น Gateway

เมื่อกำหนดค่าแล้ว ให้เริ่ม Matrix gateway:

hermes gateway

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

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

End-to-End Encryption (E2EE)

Hermes รองรับ end-to-end encryption ของ Matrix ดังนั้นคุณจึงสามารถแชทกับบอทของคุณในห้องที่เข้ารหัสได้

Requirements

E2EE ต้องการไลบรารี mautrix พร้อม encryption extras และไลบรารี C libolm:

# ติดตั้ง mautrix พร้อมการรองรับ E2EE
pip install 'mautrix[encryption]'

# หรือติดตั้งด้วย hermes extras
pip install 'hermes-agent[matrix]'

คุณยังต้องติดตั้ง libolm บนระบบของคุณ:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

เปิดใช้งาน E2EE

เพิ่มใน ~/.hermes/.env ของคุณ:

MATRIX_ENCRYPTION=true

เมื่อเปิดใช้งาน E2EE, Hermes จะ:

• เก็บ encryption keys ใน ~/.hermes/platforms/matrix/store/ (สำหรับติดตั้งแบบ legacy: ~/.hermes/matrix/store/)
• อัปโหลด device keys เมื่อเชื่อมต่อครั้งแรก
• ถอดรหัสข้อความขาเข้าและเข้ารหัสข้อความขาออกโดยอัตโนมัติ
• เข้าร่วมห้องที่เข้ารหัสโดยอัตโนมัติเมื่อถูกเชิญ

Cross-Signing Verification (แนะนำ)

หากบัญชี Matrix ของคุณเปิดใช้งาน cross-signing (ค่าเริ่มต้นใน Element) ให้ตั้งค่า recovery key เพื่อให้บอทสามารถ self-sign device ของตัวเองเมื่อเริ่มต้นทำงาน หากไม่มีสิ่งนี้ Client Matrix อื่นๆ อาจปฏิเสธที่จะแชร์ encryption sessions กับบอทหลังจากมีการหมุนเวียน device key

MATRIX_RECOVERY_KEY=EsT... your recovery key here

หาได้ที่ไหน: ใน Element ไปที่ Settings → Security & Privacy → Encryption → recovery key ของคุณ (หรือที่เรียกว่า "Security Key") นี่คือคีย์ที่คุณถูกขอให้บันทึกเมื่อคุณตั้งค่า cross-signing ครั้งแรก

ในการเริ่มต้นแต่ละครั้ง หาก MATRIX_RECOVERY_KEY ถูกตั้งค่า, Hermes จะนำเข้า cross-signing keys จาก secure secret storage ของ homeserver และ sign device ปัจจุบัน สิ่งนี้เป็นกระบวนการที่ idempotent และปลอดภัยที่จะเปิดใช้งานอย่างถาวร

:::warning[การลบ crypto store] หากคุณลบ ~/.hermes/platforms/matrix/store/crypto.db, บอทจะสูญเสีย identity การเข้ารหัสของมัน การรีสตาร์ทด้วย device ID เดิมจะไม่สามารถกู้คืนได้อย่างสมบูรณ์ - homeserver ยังคงเก็บ one-time keys ที่ sign ด้วย old identity key และ peers ไม่สามารถสร้าง Olm sessions ใหม่ได้

Hermes ตรวจพบสภาวะนี้เมื่อเริ่มต้นและปฏิเสธที่จะเปิดใช้งาน E2EE โดยบันทึก: device XXXX has stale one-time keys on the server signed with a previous identity key

วิธีที่ง่ายที่สุดในการกู้คืน: สร้าง access token ใหม่ (ซึ่งจะได้ device ID ใหม่ที่ไม่มีประวัติ key เก่า) ดูส่วน "Upgrading from a previous version with E2EE" ด้านล่าง นี่เป็นเส้นทางที่เชื่อถือได้ที่สุดและหลีกเลี่ยงการแตะต้อง homeserver database

การกู้คืนแบบ Manual (ขั้นสูง - เก็บ device ID เดิม):

1. หยุด Synapse และลบ device เก่าจาก database:

   sudo systemctl stop matrix-synapse
   sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "
     DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
     DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
     DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
     DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
   "
   sudo systemctl start matrix-synapse

   หรือผ่าน Synapse admin API (สังเกต user ID ที่ URL-encoded):

   curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
     'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID'

   หมายเหตุ: การลบ device ผ่าน admin API อาจทำให้ access token ที่เกี่ยวข้องเป็นโมฆะ คุณอาจต้องสร้าง token ใหม่หลังจากนั้น

2. ลบ local crypto store และรีสตาร์ท Hermes:

   rm -f ~/.hermes/platforms/matrix/store/crypto.db*
   # restart hermes

Client Matrix อื่นๆ (Element, matrix-commander) อาจ cache device keys เก่า หลังจากกู้คืนแล้ว ให้พิมพ์ /discardsession ใน Element เพื่อบังคับสร้าง encryption session ใหม่กับบอท :::

:::info หากไม่ได้ติดตั้ง mautrix[encryption] หรือ libolm หายไป บอทจะ fallback ไปใช้ client แบบ plain (ไม่เข้ารหัส) โดยอัตโนมัติ คุณจะเห็นคำเตือนใน logs :::

Home Room

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

การใช้ Slash Command

พิมพ์ /sethome ในห้อง Matrix ใดๆ ที่บอทอยู่ ห้องนั้นจะกลายเป็น home room

การกำหนดค่าแบบ Manual

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

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

:::tip ในการค้นหา Room ID: ใน Element ไปที่ห้อง → Settings → Advanced → Internal room ID จะแสดงอยู่ที่นั่น (ขึ้นต้นด้วย !) :::

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

บอทไม่ตอบสนองต่อข้อความ

สาเหตุ: บอทไม่ได้เข้าร่วมห้อง หรือ MATRIX_ALLOWED_USERS ไม่รวม User ID ของคุณ

วิธีแก้ไข: เชิญบอทเข้าห้อง - มันจะเข้าร่วมโดยอัตโนมัติเมื่อถูกเชิญ ตรวจสอบว่า User ID ของคุณอยู่ใน MATRIX_ALLOWED_USERS (ใช้รูปแบบ @user:server เต็ม) รีสตาร์ท gateway

"Failed to authenticate" / "whoami failed" เมื่อเริ่มต้น

สาเหตุ: access token หรือ homeserver URL ไม่ถูกต้อง

วิธีแก้ไข: ตรวจสอบว่า MATRIX_HOMESERVER ชี้ไปยัง homeserver ของคุณ (รวม https://, ไม่มี trailing slash) ตรวจสอบว่า MATRIX_ACCESS_TOKEN ถูกต้อง - ลองใช้กับ curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/_matrix/client/v3/account/whoami

หากสิ่งนี้ส่งข้อมูลผู้ใช้ของคุณกลับมา แสดงว่า token ถูกต้อง หากส่งข้อผิดพลาดกลับมา ให้สร้าง token ใหม่

ข้อผิดพลาด "mautrix not installed"

สาเหตุ: ไม่ได้ติดตั้ง package Python mautrix

วิธีแก้ไข: ติดตั้ง:

pip install 'mautrix[encryption]'

หรือด้วย Hermes extras:

pip install 'hermes-agent[matrix]'

ข้อผิดพลาดการเข้ารหัส / "could not decrypt event"

สาเหตุ: ขาด encryption keys, libolm ไม่ได้ติดตั้ง, หรือ device ของบอทไม่น่าเชื่อถือ

วิธีแก้ไข:

1. ตรวจสอบว่า libolm ติดตั้งบนระบบของคุณแล้ว (ดูส่วน E2EE ด้านบน)
2. ตรวจสอบให้แน่ใจว่า MATRIX_ENCRYPTION=true ถูกตั้งค่าใน .env ของคุณ
3. ใน Matrix client ของคุณ (Element), ไปที่โปรไฟล์ของบอท -> Sessions -> verify/trust device ของบอท
4. หากบอทเพิ่งเข้าร่วมห้องที่เข้ารหัส มันจะถอดรหัสข้อความที่ส่ง หลังจาก มันเข้าร่วมได้เท่านั้น ข้อความเก่าจะไม่สามารถเข้าถึงได้

การอัปเกรดจากเวอร์ชันก่อนหน้าที่มี E2EE

:::tip หากคุณลบ crypto.db ด้วยตัวเองด้วย ให้ดูคำเตือน "Deleting the crypto store" ในส่วน E2EE ด้านบน - มีขั้นตอนเพิ่มเติมในการล้าง one-time keys ที่ล้าสมัยออกจาก homeserver :::

หากคุณเคยใช้ Hermes ด้วย MATRIX_ENCRYPTION=true และกำลังอัปเกรดเป็นเวอร์ชันที่ใช้ crypto store แบบ SQLite ใหม่ identity การเข้ารหัสของบอทได้เปลี่ยนไป Client Matrix ของคุณ (Element) อาจ cache device keys เก่า และปฏิเสธที่จะแชร์ encryption sessions กับบอท

อาการ: บอทเชื่อมต่อและแสดง "E2EE enabled" ใน logs แต่ข้อความทั้งหมดแสดง "could not decrypt event" และบอทไม่ตอบกลับเลย

เกิดอะไรขึ้น: สถานะการเข้ารหัสเก่า (จาก backend matrix-nio หรือ mautrix ที่อิงจากการ serialize) ไม่เข้ากันกับ crypto store แบบ SQLite ใหม่ บอทสร้าง identity การเข้ารหัสใหม่ แต่ Client Matrix ของคุณยังคง cache keys เก่า และจะไม่แชร์ encryption session ของห้องกับ device ที่ keys เปลี่ยนไป นี่คือคุณสมบัติความปลอดภัยของ Matrix - client จะถือว่า identity keys ที่เปลี่ยนไปสำหรับ device เดียวกันเป็นสิ่งที่น่าสงสัย

วิธีแก้ไข (การย้ายข้อมูลครั้งเดียว):

1. สร้าง access token ใหม่ เพื่อรับ device ID ใหม่ วิธีที่ง่ายที่สุด:

   curl -X POST https://your-server/_matrix/client/v3/login \
     -H "Content-Type: application/json" \
     -d '{
       "type": "m.login.password",
       "identifier": {"type": "m.id.user", "user": "@hermes:your-server.org"},
       "password": "***",
       "initial_device_display_name": "Hermes Agent"
     }'

   คัดลอก access_token ใหม่ และอัปเดต MATRIX_ACCESS_TOKEN ใน ~/.hermes/.env

2. ลบ encryption state เก่า:

   rm -f ~/.hermes/platforms/matrix/store/crypto.db
   rm -f ~/.hermes/platforms/matrix/store/crypto_store.*

3. ตั้งค่า recovery key ของคุณ (หากคุณใช้ cross-signing - ผู้ใช้ Element ส่วนใหญ่ทำ) เพิ่มใน ~/.hermes/.env:

   MATRIX_RECOVERY_KEY=EsT... your recovery key here

   สิ่งนี้ช่วยให้บอท self-sign ด้วย cross-signing keys เมื่อเริ่มต้น ทำให้ Element เชื่อถือ device ใหม่ทันที หากไม่มีสิ่งนี้ Element อาจเห็น device ใหม่ว่าไม่ได้รับการตรวจสอบและปฏิเสธที่จะแชร์ encryption sessions

4. บังคับให้ Matrix client ของคุณหมุนเวียน encryption session ใน Element เปิด DM room กับบอทและพิมพ์ /discardsession สิ่งนี้บังคับให้ Element สร้าง encryption session ใหม่และแชร์กับ device ใหม่ของบอท

5. รีสตาร์ท gateway:

   hermes gateway run

   หาก MATRIX_RECOVERY_KEY ถูกตั้งค่า คุณควรเห็น Matrix: cross-signing verified via recovery key ใน logs

6. ส่งข้อความใหม่ บอทควรถอดรหัสและตอบกลับตามปกติ

:::note หลังการย้ายข้อมูล ข้อความที่ส่ง ก่อน การอัปเกรดจะไม่สามารถถอดรหัสได้ - encryption keys เก่าหายไป สิ่งนี้ส่งผลกระทบเฉพาะช่วงการเปลี่ยนผ่านเท่านั้น ข้อความใหม่ทำงานได้ตามปกติ :::

:::tip การติดตั้งใหม่ไม่ได้รับผลกระทบ การย้ายข้อมูลนี้จำเป็นเฉพาะเมื่อคุณเคยมีการตั้งค่า E2EE ที่ทำงานได้ด้วย Hermes เวอร์ชันก่อนหน้าและกำลังอัปเกรด

ทำไมต้องใช้ access token ใหม่? Matrix access token แต่ละตัวผูกติดกับ device ID เฉพาะ การใช้ device ID เดิมกับ encryption keys ใหม่ทำให้ Client Matrix อื่นๆ ไม่เชื่อถือ device (พวกเขามองว่า identity keys ที่เปลี่ยนไปเป็น potential security breach) access token ใหม่จะได้รับ device ID ใหม่ที่ไม่มีประวัติ key เก่า ดังนั้น client อื่นๆ จึงเชื่อถือมันทันที :::

Proxy Mode (E2EE on macOS)

Matrix E2EE ต้องการ libolm ซึ่งไม่สามารถ compile บน macOS ARM64 (Apple Silicon) ได้ extra hermes-agent[matrix] จึงถูกจำกัดให้ใช้กับ Linux เท่านั้น หากคุณใช้ macOS, proxy mode จะช่วยให้คุณรัน E2EE ใน Docker container บน Linux VM ในขณะที่ agent จริงทำงานแบบ native บน macOS โดยเข้าถึง local files, memory, และ skills ของคุณได้อย่างเต็มที่

How It Works

macOS (Host):
  └─ hermes gateway
       ├─ api_server adapter ← listens on 0.0.0.0:8642
       ├─ AIAgent ← single source of truth
       ├─ Sessions, memory, skills
       └─ Local file access (Obsidian, projects, etc.)

Linux VM (Docker):
  └─ hermes gateway (proxy mode)
       ├─ Matrix adapter ← E2EE decryption/encryption
       └─ HTTP forward → macOS:8642/v1/chat/completions
           (no LLM API keys, no agent, no inference)

Docker container จัดการเฉพาะ Matrix protocol + E2EE เมื่อมีข้อความมาถึง มันจะถอดรหัสและส่งข้อความไปยัง host ผ่าน HTTP request มาตรฐาน Host จะรัน agent, เรียกใช้ tools, สร้าง response, และ stream กลับ Container จะเข้ารหัสและส่ง response ไปยัง Matrix ทุก session ถูกรวมเป็นหนึ่งเดียว - CLI, Matrix, Telegram, และแพลตฟอร์มอื่น ๆ แชร์ memory และ conversation history เดียวกัน

Step 1: Configure the Host (macOS)

เปิดใช้งาน API server เพื่อให้ host ยอมรับ incoming requests จาก Docker container

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

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

• API_SERVER_HOST=0.0.0.0 ผูกกับทุก interface เพื่อให้ Docker container เข้าถึงได้
• API_SERVER_KEY จำเป็นสำหรับ non-loopback binding เลือก string สุ่มที่แข็งแกร่ง
• API server รันที่ port 8642 โดยค่าเริ่มต้น (เปลี่ยนด้วย API_SERVER_PORT หากจำเป็น)

เริ่ม gateway:

hermes gateway

คุณควรเห็น API server เริ่มทำงานพร้อมกับแพลตฟอร์มอื่น ๆ ที่คุณกำหนดค่าไว้ ตรวจสอบว่าสามารถเข้าถึงได้จาก VM:

# จาก Linux VM
curl http://<mac-ip>:8642/health

Step 2: Configure the Docker Container (Linux VM)

Container ต้องการ Matrix credentials และ proxy URL มันไม่ต้องการ LLM API keys

docker-compose.yml:

services:
  hermes-matrix:
    build: .
    environment:
      # Matrix credentials
      MATRIX_HOMESERVER: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@you:matrix.example.org"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_BOT"

      # Proxy mode — forward to host agent
      GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
      GATEWAY_PROXY_KEY: "your-secret-key-here"
    volumes:
      - ./matrix-store:/root/.hermes/platforms/matrix/store

Dockerfile:

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN pip install 'hermes-agent[matrix]'

CMD ["hermes", "gateway"]

นั่นคือ container ทั้งหมด ไม่มี API keys สำหรับ OpenRouter, Anthropic, หรือ inference provider ใดๆ

Step 3: Start Both

1. เริ่ม host gateway ก่อน:

   hermes gateway

2. เริ่ม Docker container:

   docker compose up -d

3. ส่งข้อความในห้อง Matrix ที่เข้ารหัส Container จะถอดรหัสและส่งต่อไปยัง host และ stream response กลับมา

Configuration Reference

Proxy mode ถูกกำหนดค่าที่ ฝั่ง container (gateway ที่บางเบา):

ฝั่ง host ต้องการ:

Works for Any Platform

Proxy mode ไม่ได้จำกัดแค่ Matrix เท่านั้น Adapter แพลตฟอร์มใดๆ สามารถใช้ได้ - ตั้งค่า GATEWAY_PROXY_URL บน gateway instance ใดๆ และมันจะส่งต่อไปยัง agent ระยะไกลแทนที่จะรันในเครื่องนี้ มีประโยชน์สำหรับการ deployment ใดๆ ที่ platform adapter ต้องการรันในสภาพแวดล้อมที่แตกต่างจาก agent (network isolation, E2EE requirements, resource constraints)

:::tip Session continuity ถูกรักษาไว้ผ่าน header X-Hermes-Session-Id API server ของ host ติดตาม session ด้วย ID นี้ ดังนั้นการสนทนาจึงคงอยู่ข้ามข้อความเหมือนกับที่ทำกับ local agent :::

:::note ข้อจำกัด (v1): ข้อความความคืบหน้าของ tool จาก agent ระยะไกลจะไม่ถูกส่งกลับ - ผู้ใช้จะเห็นเฉพาะ final response ที่ stream เท่านั้น ไม่ใช่การเรียกใช้ tool ทีละครั้ง การแจ้งเตือนการอนุมัติคำสั่งอันตรายจะจัดการที่ฝั่ง host ไม่ได้ส่งต่อไปยังผู้ใช้ Matrix สิ่งเหล่านี้สามารถแก้ไขได้ในการอัปเดตในอนาคต :::

Sync issues / bot falls behind

สาเหตุ: การรัน tool ที่ใช้เวลานานสามารถทำให้ sync loop ล่าช้า หรือ homeserver ช้า

วิธีแก้ไข: sync loop จะพยายามใหม่โดยอัตโนมัติทุก 5 วินาทีเมื่อเกิดข้อผิดพลาด ตรวจสอบ Hermes logs สำหรับคำเตือนที่เกี่ยวข้องกับการ sync หากบอทตามหลังอย่างต่อเนื่อง ให้แน่ใจว่า homeserver ของคุณมีทรัพยากรเพียงพอ

Bot is offline

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

วิธีแก้ไข: ตรวจสอบว่า hermes gateway กำลังทำงานอยู่ ดูที่ terminal output สำหรับข้อความข้อผิดพลาด ปัญหาทั่วไป: URL homeserver ผิด, access token หมดอายุ, homeserver เข้าถึงไม่ได้

"User not allowed" / Bot ignores you

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

วิธีแก้ไข: เพิ่ม User ID ของคุณใน MATRIX_ALLOWED_USERS ใน ~/.hermes/.env และรีสตาร์ท gateway ใช้รูปแบบ @user:server เต็ม

Security

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

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

Notes

• Any homeserver: ทำงานกับ Synapse, Conduit, Dendrite, matrix.org, หรือ homeserver Matrix ที่ compliant กับ spec ใดๆ ไม่จำเป็นต้องมีซอฟต์แวร์ homeserver เฉพาะ
• Federation: หากคุณอยู่บน homeserver แบบ federated, บอทสามารถสื่อสารกับผู้ใช้จากเซิร์ฟเวอร์อื่นได้ - เพียงแค่เพิ่ม full @user:server IDs ของพวกเขาใน MATRIX_ALLOWED_USERS
• Auto-join: บอทจะยอมรับคำเชิญเข้าห้องและเข้าร่วมโดยอัตโนมัติ มันจะเริ่มตอบกลับทันทีหลังจากเข้าร่วม
• Media support: Hermes สามารถส่งและรับรูปภาพ, เสียง, วิดีโอ, และ file attachments ได้ Media จะถูกอัปโหลดไปยัง homeserver ของคุณโดยใช้ Matrix content repository API
• Native voice messages (MSC3245): Matrix adapter จะติด flag org.matrix.msc3245.voice ให้กับข้อความเสียงขาออกโดยอัตโนมัติ ซึ่งหมายความว่า TTS responses และ voice audio จะแสดงเป็น native voice bubbles ใน Element และ client อื่นๆ ที่รองรับ MSC3245 แทนที่จะเป็น file attachments เสียงทั่วไป ข้อความเสียงขาเข้าที่มี flag MSC3245 ก็จะถูกระบุและส่งต่อไปยัง speech-to-text transcription อย่างถูกต้อง ไม่จำเป็นต้องตั้งค่า - สิ่งนี้ทำงานโดยอัตโนมัติ

📄 user-guide/messaging/mattermost.md

sidebar_position: 8 title: "Mattermost" description: "Set up Hermes Agent as a Mattermost bot"

การตั้งค่า Mattermost

Hermes Agent ทำงานร่วมกับ Mattermost ในรูปแบบบอท ทำให้คุณสามารถแชทกับผู้ช่วย AI ของคุณได้ผ่านข้อความส่วนตัว (direct messages) หรือช่องทีม (team channels) Mattermost เป็นทางเลือกแบบ open-source ที่โฮสต์เองได้ (self-hosted) สำหรับ Slack - คุณสามารถรันมันบนโครงสร้างพื้นฐานของคุณเอง ทำให้คุณควบคุมข้อมูลได้อย่างเต็มที่ บอทจะเชื่อมต่อผ่าน Mattermost's REST API (v4) และ WebSocket สำหรับเหตุการณ์แบบ real-time โดยจะประมวลผลข้อความผ่าน pipeline ของ Hermes Agent (รวมถึง tool use, memory, และ reasoning) และตอบกลับแบบ real-time รองรับข้อความ (text), ไฟล์แนบ (file attachments), รูปภาพ (images), และ slash commands

ไม่จำเป็นต้องใช้ library ภายนอกของ Mattermost - adapter นี้ใช้ aiohttp ซึ่งเป็น dependency ที่ Hermes มีอยู่แล้ว

ก่อนการตั้งค่า นี่คือส่วนที่คนส่วนใหญ่ต้องการทราบ: Hermes จะทำงานอย่างไรเมื่ออยู่ใน instance Mattermost ของคุณ

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

:::tip หากคุณต้องการให้ Hermes ตอบกลับในรูปแบบการสนทนาแบบ thread (ซ้อนอยู่ใต้ข้อความต้นฉบับของคุณ) ให้ตั้งค่า MATTERMOST_REPLY_MODE=thread ค่าเริ่มต้นคือ off ซึ่งจะส่งข้อความแบบ flat ในช่อง :::

Session Model ใน Mattermost

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

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

• ผู้ใช้แชร์การเติบโตของ context และค่าใช้จ่าย token
• งานที่ใช้ tool หนักๆ ของคนหนึ่งอาจทำให้ context ของทุกคนบวมได้
• การรันงานที่กำลังดำเนินอยู่ของคนหนึ่งอาจขัดจังหวะการติดตามผลของอีกคนในช่องเดียวกัน

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

ขั้นตอนที่ 1: เปิดใช้งานบัญชีบอท (Bot Accounts)

คุณต้องเปิดใช้งานบัญชีบอทบนเซิร์ฟเวอร์ Mattermost ของคุณก่อนจึงจะสามารถสร้างบอทได้

1. เข้าสู่ระบบ Mattermost ในฐานะ System Admin
2. ไปที่ System Console → Integrations → Bot Accounts
3. ตั้งค่า Enable Bot Account Creation เป็น true
4. คลิก Save

:::info หากคุณไม่มีสิทธิ์ System Admin ให้ขอให้ผู้ดูแลระบบ Mattermost ของคุณเปิดใช้งานบัญชีบอทและสร้างบัญชีให้คุณ :::

ขั้นตอนที่ 2: สร้างบัญชีบอท

1. ใน Mattermost คลิกเมนู ☰ (มุมซ้ายบน) → Integrations → Bot Accounts
2. คลิก Add Bot Account
3. กรอกรายละเอียด:
   • Username: เช่น hermes
   • Display Name: เช่น Hermes Agent
   • Description: (ไม่บังคับ)
   • Role: Member ก็เพียงพอ
4. คลิก Create Bot Account
5. Mattermost จะแสดง bot token คัดลอกทันที

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

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

:::tip คุณยังสามารถใช้ personal access token แทนบัญชีบอทได้ ไปที่ Profile → Security → Personal Access Tokens → Create Token วิธีนี้มีประโยชน์หากคุณต้องการให้ Hermes โพสต์ในฐานะผู้ใช้ของคุณเองแทนผู้ใช้บอทแยกต่างหาก :::

ขั้นตอนที่ 3: เพิ่มบอทเข้าสู่ช่อง (Channels)

บอทจะต้องเป็นสมาชิกของทุกช่องที่คุณต้องการให้มันตอบกลับ:

1. เปิดช่องที่คุณต้องการให้บอททำงาน
2. คลิกชื่อช่อง → Add Members
3. ค้นหาชื่อผู้ใช้บอทของคุณ (เช่น hermes) และเพิ่มมัน

สำหรับ DMs เพียงแค่เปิดข้อความส่วนตัวกับบอท - มันจะสามารถตอบกลับได้ทันที

ขั้นตอนที่ 4: ค้นหา User ID ของ Mattermost

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

1. คลิก avatar ของคุณ (มุมซ้ายบน) → Profile
2. User ID ของคุณจะแสดงในหน้าต่าง profile - คลิกเพื่อคัดลอก

User ID ของคุณคือสตริงตัวอักษรตัวเลข (alphanumeric) 26 ตัว เช่น 3uo8dkh1p7g1mfk49ear5fzs5c

:::warning User ID ของคุณ ไม่ใช่ username username คือสิ่งที่ปรากฏหลังเครื่องหมาย @ (เช่น @alice) User ID คือตัวระบุตัวอักษรตัวเลขยาวๆ ที่ Mattermost ใช้ภายใน :::

ทางเลือก: คุณยังสามารถรับ User ID ของคุณผ่าน API ได้:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

:::tip ในการรับ Channel ID: คลิกชื่อช่อง → View Info Channel ID จะแสดงในแผงข้อมูล คุณจะต้องใช้สิ่งนี้หากคุณต้องการตั้งค่า home channel ด้วยตนเอง :::

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

Option A: การตั้งค่าแบบโต้ตอบ (Interactive Setup) (แนะนำ)

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

hermes gateway setup

เลือก Mattermost เมื่อระบบแจ้งเตือน จากนั้นวาง URL เซิร์ฟเวอร์, bot token, และ user ID ของคุณเมื่อถูกถาม

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

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

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply mode (thread หรือ off, default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without @mention (default: true = require mention)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where bot responds without @mention (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

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

group_sessions_per_user: true

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

เริ่มต้น Gateway

เมื่อกำหนดค่าเสร็จแล้ว ให้เริ่ม Mattermost gateway:

hermes gateway

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

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

Home Channel

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

การใช้ Slash Command

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

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

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

แทนที่ ID ด้วย channel ID จริง (คลิกชื่อช่อง → View Info → คัดลอก ID)

Reply Mode

การตั้งค่า MATTERMOST_REPLY_MODE ควบคุมวิธีการโพสต์การตอบกลับของ Hermes:

ตั้งค่าใน ~/.hermes/.env ของคุณ:

MATTERMOST_REPLY_MODE=thread

Mention Behavior

โดยค่าเริ่มต้น บอทจะตอบกลับในช่องก็ต่อเมื่อมีการ @mention เท่านั้น คุณสามารถเปลี่ยนสิ่งนี้ได้:

ในการค้นหา Channel ID ใน Mattermost: เปิดช่อง คลิกที่ส่วนหัวชื่อช่อง และมองหา ID ใน URL หรือรายละเอียดช่อง

เมื่อบอทถูก @mention การ mention จะถูกลบออกจากข้อความโดยอัตโนมัติก่อนการประมวลผล

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

บอทไม่ตอบกลับข้อความ

สาเหตุ: บอทไม่ได้เป็นสมาชิกของช่อง หรือ MATTERMOST_ALLOWED_USERS ไม่ได้รวม User ID ของคุณ

วิธีแก้ไข: เพิ่มบอทเข้าสู่ช่อง (ชื่อช่อง → Add Members → ค้นหาบอท) ตรวจสอบว่า User ID ของคุณอยู่ใน MATTERMOST_ALLOWED_USERS แล้ว และรีสตาร์ท gateway

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

สาเหตุ: bot token ไม่ถูกต้อง หรือบอทไม่มีสิทธิ์ในการโพสต์ในช่อง

วิธีแก้ไข: ตรวจสอบว่า MATTERMOST_TOKEN ในไฟล์ .env ของคุณถูกต้องหรือไม่ ตรวจสอบให้แน่ใจว่าบัญชีบอทไม่ได้ถูกปิดใช้งาน ตรวจสอบว่าบอทได้ถูกเพิ่มเข้าสู่ช่องแล้ว หากใช้ personal access token ให้แน่ใจว่าบัญชีของคุณมีสิทธิ์ที่จำเป็น

WebSocket disconnects / reconnection loops

สาเหตุ: ความไม่เสถียรของเครือข่าย, การรีสตาร์ทเซิร์ฟเวอร์ Mattermost, หรือปัญหา firewall/proxy กับการเชื่อมต่อ WebSocket

วิธีแก้ไข: adapter จะเชื่อมต่อใหม่โดยอัตโนมัติด้วย exponential backoff (2s → 60s) ตรวจสอบการตั้งค่า WebSocket ของเซิร์ฟเวอร์ของคุณ - reverse proxies (nginx, Apache) จำเป็นต้องตั้งค่า WebSocket upgrade headers ให้ถูกต้อง ตรวจสอบว่าไม่มี firewall บล็อกการเชื่อมต่อ WebSocket บนเซิร์ฟเวอร์ Mattermost ของคุณ

สำหรับ nginx ให้แน่ใจว่า config ของคุณรวม:

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

"Failed to authenticate" เมื่อเริ่มต้น

สาเหตุ: token หรือ URL เซิร์ฟเวอร์ไม่ถูกต้อง

วิธีแก้ไข: ตรวจสอบว่า MATTERMOST_URL ชี้ไปยังเซิร์ฟเวอร์ Mattermost ของคุณ (รวม https:// และไม่มี trailing slash) ตรวจสอบว่า MATTERMOST_TOKEN ถูกต้อง - ลองใช้กับ curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

หากสิ่งนี้ส่งคืนข้อมูลผู้ใช้บอทของคุณ แสดงว่า token ถูกต้อง หากส่งคืนข้อผิดพลาด ให้สร้าง token ใหม่

บอทออฟไลน์

สาเหตุ: Hermes gateway ไม่ได้ทำงาน หรือล้มเหลวในการเชื่อมต่อ

วิธีแก้ไข: ตรวจสอบว่า hermes gateway กำลังทำงานอยู่ ดูที่ output ของ terminal เพื่อหาข้อความแสดงข้อผิดพลาด ปัญหาทั่วไป: URL ผิด, token หมดอายุ, Mattermost server เข้าถึงไม่ได้

"User not allowed" / บอทเพิกเฉยต่อคุณ

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

วิธีแก้ไข: เพิ่ม User ID ของคุณใน MATTERMOST_ALLOWED_USERS ใน ~/.hermes/.env และรีสตาร์ท gateway จำไว้ว่า: User ID คือสตริงตัวอักษรตัวเลข 26 ตัว ไม่ใช่ @username ของคุณ

Per-Channel Prompts

กำหนด system prompts ชั่วคราว (ephemeral) ให้กับช่อง Mattermost เฉพาะเจาะจง Prompt จะถูกแทรกใน runtime ในทุกรอบการสนทนา - ไม่เคยถูกบันทึกในประวัติ transcript - ดังนั้นการเปลี่ยนแปลงจะมีผลทันที

mattermost:
  channel_prompts:
    "channel_id_abc123": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "channel_id_def456": |
      Code review mode. Be precise about edge cases and
      performance implications.

Keys คือ Mattermost channel IDs (ค้นหาได้ใน URL ของช่องหรือผ่าน API) ข้อความทั้งหมดในช่องที่ตรงกันจะได้รับ prompt ที่ถูกแทรกเป็นคำสั่ง system ชั่วคราว

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

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

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

หมายเหตุ (Notes)

• เหมาะสำหรับ self-hosted: ทำงานได้กับ Mattermost instance ที่โฮสต์เองทุกประเภท ไม่จำเป็นต้องมีบัญชีหรือการสมัครสมาชิก Mattermost Cloud
• ไม่ต้องการ dependencies เพิ่มเติม: adapter ใช้ aiohttp สำหรับ HTTP และ WebSocket ซึ่งรวมอยู่ใน Hermes Agent อยู่แล้ว
• รองรับ Team Edition: ทำงานได้ทั้ง Mattermost Team Edition (ฟรี) และ Enterprise Edition

📄 user-guide/messaging/open-webui.md

sidebar_position: 8 title: "Open WebUI" description: "Connect Open WebUI to Hermes Agent via the OpenAI-compatible API server"

การรวม Open WebUI

Open WebUI (126k★) เป็น chat interface สำหรับ AI แบบ self-hosted ที่ได้รับความนิยมที่สุด ด้วย API server ที่มาพร้อมกับ Hermes Agent คุณสามารถใช้ Open WebUI เป็น web frontend ที่สวยงามสำหรับ agent ของคุณ ซึ่งมาพร้อมกับการจัดการบทสนทนา บัญชีผู้ใช้ และ chat interface ที่ทันสมัย

สถาปัตยกรรม

flowchart LR
    A["Open WebUI<br/>browser UI<br/>port 3000"]
    B["hermes-agent<br/>gateway API server<br/>port 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|SSE streaming response| A

Open WebUI เชื่อมต่อกับ API server ของ Hermes Agent เหมือนกับการเชื่อมต่อกับ OpenAI โดย agent ของคุณจะจัดการ requests ด้วย toolset ทั้งหมดของมัน - terminal, file operations, web search, memory, skills - และส่งคืน response สุดท้าย

Open WebUI สื่อสารกับ Hermes แบบ server-to-server ดังนั้นคุณจึงไม่จำเป็นต้องใช้ API_SERVER_CORS_ORIGINS สำหรับการรวมระบบนี้

การตั้งค่าเบื้องต้น

1. เปิดใช้งาน API server

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

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

2. เริ่มต้น Hermes Agent gateway

hermes gateway

คุณควรเห็น:

[API Server] API server listening on http://127.0.0.1:8642

3. เริ่มต้น Open WebUI

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

4. เปิด UI

ไปที่ http://localhost:3000 สร้างบัญชี admin ของคุณ (ผู้ใช้คนแรกจะเป็น admin) คุณควรเห็น agent ของคุณในรายการ model dropdown (ชื่อตามโปรไฟล์ของคุณ หรือ hermes-agent สำหรับโปรไฟล์เริ่มต้น) เริ่มแชทได้เลย!

การตั้งค่าด้วย Docker Compose

สำหรับการตั้งค่าที่ถาวรยิ่งขึ้น ให้สร้างไฟล์ docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

จากนั้น:

docker compose up -d

การกำหนดค่าผ่าน Admin UI

หากคุณต้องการกำหนดค่าการเชื่อมต่อผ่าน UI แทนการใช้ environment variables:

1. เข้าสู่ระบบ Open WebUI ที่ http://localhost:3000
2. คลิก profile avatar ของคุณ → Admin Settings
3. ไปที่ Connections
4. ใต้ OpenAI API, คลิก wrench icon (Manage)
5. คลิก + Add New Connection
6. ป้อน:
   • URL: http://host.docker.internal:8642/v1
   • API Key: key ของคุณ หรือค่าที่ไม่ว่างเปล่าใดๆ (เช่น not-needed)
7. คลิก checkmark เพื่อตรวจสอบการเชื่อมต่อ
8. Save

ตอนนี้ agent model ของคุณควรปรากฏใน model dropdown (ชื่อตามโปรไฟล์ของคุณ หรือ hermes-agent สำหรับโปรไฟล์เริ่มต้น)

:::warning Environment variables จะมีผลเฉพาะในการ เปิดใช้งานครั้งแรก ของ Open WebUI เท่านั้น หลังจากนั้น การตั้งค่าการเชื่อมต่อจะถูกจัดเก็บไว้ใน internal database ของมัน หากต้องการเปลี่ยนในภายหลัง ให้ใช้ Admin UI หรือลบ Docker volume และเริ่มใหม่ :::

ประเภท API: Chat Completions เทียบกับ Responses

Open WebUI รองรับสองโหมด API เมื่อเชื่อมต่อกับ backend:

การใช้ Chat Completions (แนะนำ)

นี่คือค่าเริ่มต้นและไม่จำเป็นต้องมีการตั้งค่าเพิ่มเติม Open WebUI จะส่ง requests รูปแบบ OpenAI มาตรฐาน และ Hermes Agent จะตอบกลับตามนั้น แต่ละ requests จะรวมประวัติบทสนทนาทั้งหมด

การใช้ Responses API

ในการใช้โหมด Responses API:

1. ไปที่ Admin Settings → Connections → OpenAI → Manage
2. แก้ไขการเชื่อมต่อ hermes-agent ของคุณ
3. เปลี่ยน API Type จาก "Chat Completions" เป็น "Responses (Experimental)"
4. Save

ด้วย Responses API, Open WebUI จะส่ง requests ในรูปแบบ Responses (input array + instructions), และ Hermes Agent สามารถรักษาประวัติ tool call ทั้งหมดข้ามรอบการสนทนาผ่าน previous_response_id เมื่อ stream: true, Hermes ยังจะ stream รายการ function_call และ function_call_output แบบ spec-native ซึ่งช่วยให้สามารถสร้าง UI สำหรับ tool-call แบบ structured ได้ใน client ที่แสดง Responses events

:::note ปัจจุบัน Open WebUI จัดการประวัติบทสนทนาแบบ client-side แม้ในโหมด Responses - โดยมันจะส่งประวัติข้อความทั้งหมดในแต่ละ request แทนการใช้ previous_response_id ข้อได้เปรียบหลักของ Responses mode ในวันนี้คือ structured event stream: text deltas, function_call, และ function_call_output items จะมาถึงในรูปแบบ OpenAI Responses SSE events แทน Chat Completions chunks :::

วิธีการทำงาน

เมื่อคุณส่งข้อความใน Open WebUI:

1. Open WebUI ส่ง request POST /v1/chat/completions พร้อมข้อความของคุณและประวัติบทสนทนา
2. Hermes Agent สร้าง instance ของ AIAgent ด้วย toolset ทั้งหมดของมัน
3. agent จะประมวลผล request ของคุณ - มันอาจเรียกใช้ tools (terminal, file operations, web search, ฯลฯ)
4. ขณะที่ tools ทำงาน, inline progress messages จะ stream ไปยัง UI เพื่อให้คุณเห็นว่า agent กำลังทำอะไรอยู่ (เช่น `💻 ls -la`, `🔍 Python 3.12 release`)
5. ข้อความตอบกลับที่เป็น text สุดท้ายของ agent จะ stream กลับไปยัง Open WebUI
6. Open WebUI แสดง response ใน chat interface ของมัน

agent ของคุณเข้าถึงเครื่องมือและความสามารถทั้งหมดแบบเดียวกับการใช้ CLI หรือ Telegram - ความแตกต่างเพียงอย่างเดียวคือ frontend

:::tip Tool Progress เมื่อเปิดใช้งาน streaming (ค่าเริ่มต้น) คุณจะเห็นตัวบ่งชี้แบบ inline สั้นๆ ขณะที่ tools กำลังทำงาน - คือ emoji ของ tool และ argument หลักของมัน สิ่งเหล่านี้จะปรากฏใน response stream ก่อนคำตอบสุดท้ายของ agent ทำให้คุณเห็นภาพว่าเกิดอะไรขึ้นเบื้องหลัง :::

ข้อมูลอ้างอิงการตั้งค่า

Hermes Agent (API server)

Open WebUI

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

ไม่มี model ปรากฏใน dropdown

• ตรวจสอบว่า URL มี suffix /v1: http://host.docker.internal:8642/v1 (ไม่ใช่แค่ :8642)
• ตรวจสอบว่า gateway กำลังทำงาน: curl http://localhost:8642/health ควรคืนค่า {"status": "ok"}
• ตรวจสอบการแสดงรายการ model: curl http://localhost:8642/v1/models ควรคืนค่ารายการที่มี hermes-agent
• Docker networking: จากภายใน Docker, localhost หมายถึง container ไม่ใช่ host ของคุณ ให้ใช้ host.docker.internal หรือ --network=host

Connection test ผ่าน แต่ไม่มี model โหลด

นี่เกือบจะเป็นปัญหาที่ขาด suffix /v1 เสมอ การทดสอบการเชื่อมต่อของ Open WebUI เป็นเพียงการตรวจสอบการเชื่อมต่อพื้นฐาน - มันไม่ได้ตรวจสอบว่าการแสดงรายการ model ทำงานหรือไม่

Response ใช้เวลานานมาก

Hermes Agent อาจกำลังเรียกใช้ tool call หลายครั้ง (อ่านไฟล์, รันคำสั่ง, ค้นหาเว็บ) ก่อนที่จะสร้าง response สุดท้าย นี่เป็นเรื่องปกติสำหรับ queries ที่ซับซ้อน Response จะปรากฏทั้งหมดเมื่อ agent ทำงานเสร็จ

ข้อผิดพลาด "Invalid API key"

ตรวจสอบให้แน่ใจว่า OPENAI_API_KEY ใน Open WebUI ตรงกับ API_SERVER_KEY ใน Hermes Agent

การตั้งค่าหลายผู้ใช้ด้วย Profiles

หากต้องการรัน Hermes instances แยกกันสำหรับผู้ใช้แต่ละคน - โดยแต่ละคนมี config, memory, และ skills ของตัวเอง - ให้ใช้ profiles แต่ละ profile จะรัน API server ของตัวเองบนพอร์ตที่แตกต่างกัน และจะประกาศชื่อ profile เป็น model ใน Open WebUI โดยอัตโนมัติ

1. สร้าง profiles และกำหนดค่า API servers

hermes profile create alice
hermes -p alice config set API_SERVER_ENABLED true
hermes -p alice config set API_SERVER_PORT 8643
hermes -p alice config set API_SERVER_KEY alice-secret

hermes profile create bob
hermes -p bob config set API_SERVER_ENABLED true
hermes -p bob config set API_SERVER_PORT 8644
hermes -p bob config set API_SERVER_KEY bob-secret

2. เริ่มต้นแต่ละ gateway

hermes -p alice gateway &
hermes -p bob gateway &

3. เพิ่มการเชื่อมต่อใน Open WebUI

ใน Admin Settings → Connections → OpenAI API → Manage, เพิ่มการเชื่อมต่อหนึ่งรายการต่อ profile:

model dropdown จะแสดง alice และ bob เป็น model ที่แตกต่างกัน คุณสามารถกำหนด model ให้ผู้ใช้ Open WebUI ผ่าน admin panel เพื่อให้ผู้ใช้แต่ละคนมี agent ของ Hermes ที่แยกออกจากกัน

:::tip Custom Model Names ชื่อ model จะเป็นค่าเริ่มต้นเป็นชื่อ profile หากต้องการเปลี่ยน ให้ตั้งค่า API_SERVER_MODEL_NAME ใน .env ของ profile:

hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"

:::

Linux Docker (ไม่มี Docker Desktop)

บน Linux ที่ไม่มี Docker Desktop, host.docker.internal จะไม่สามารถ resolve ได้โดยค่าเริ่มต้น มีตัวเลือกดังนี้:

# Option 1: เพิ่ม host mapping
docker run --add-host=host.docker.internal:host-gateway ...

# Option 2: ใช้ host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: ใช้ Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...

📄 user-guide/messaging/qqbot.md

QQ Bot

เชื่อมต่อ Hermes เข้ากับ QQ ผ่าน Official QQ Bot API (v2) - รองรับข้อความส่วนตัว (C2C), การกล่าวถึงในกลุ่ม (@-mentions), Guild, และข้อความส่วนตัวพร้อมการถอดเสียงด้วยเสียง

Overview

QQ Bot adapter ใช้ Official QQ Bot API เพื่อ:

• รับข้อความผ่านการเชื่อมต่อ WebSocket แบบถาวรไปยัง QQ Gateway
• ส่งข้อความและข้อความตอบกลับแบบ markdown ผ่าน REST API
• ดาวน์โหลดและประมวลผลรูปภาพ, ข้อความเสียง, และไฟล์แนบ
• ถอดเสียงข้อความเสียงโดยใช้ ASR ที่มีอยู่ในตัวของ Tencent หรือผู้ให้บริการ STT ที่สามารถกำหนดค่าได้

Prerequisites

1. QQ Bot Application - ลงทะเบียนที่ q.qq.com:

   • สร้างแอปพลิเคชันใหม่และจดบันทึก App ID และ App Secret
   • เปิดใช้งาน intents ที่จำเป็น: C2C messages, Group @-messages, Guild messages
   • กำหนดค่าบอทของคุณในโหมด sandbox สำหรับการทดสอบ หรือเผยแพร่สำหรับ Production

2. Dependencies - adapter นี้ต้องการ aiohttp และ httpx:

   pip install aiohttp httpx

Configuration

Interactive setup

hermes gateway setup

เลือก QQ Bot จากรายการแพลตฟอร์มและทำตามคำแนะนำ

Manual configuration

ตั้งค่า environment variables ที่จำเป็นใน ~/.hermes/.env:

QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

Environment Variables

Advanced Configuration

สำหรับการควบคุมที่ละเอียดอ่อน ให้เพิ่ม platform settings ใน ~/.hermes/config.yaml:

platforms:
  qq:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true       # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
      dm_policy: "open"          # open | allowlist | disabled
      allow_from:
        - "user_openid_1"
      group_policy: "open"       # open | allowlist | disabled
      group_allow_from:
        - "group_openid_1"
      stt:
        provider: "zai"          # zai (GLM-ASR), openai (Whisper), etc.
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"

Voice Messages (STT)

การถอดเสียงด้วยเสียงทำงานในสองขั้นตอน:

1. QQ built-in ASR (ฟรี, จะถูกลองก่อนเสมอ) - QQ จะให้ asr_refer_text ในไฟล์แนบข้อความเสียง ซึ่งใช้ระบบรู้จำคำพูดของ Tencent เอง

2. Configured STT provider (fallback) - หาก ASR ของ QQ ไม่ส่งคืนข้อความ adapter จะเรียกใช้ STT API ที่เข้ากันได้กับ OpenAI:

   • Zhipu/GLM (zai): ผู้ให้บริการเริ่มต้น ใช้โมเดล glm-asr
   • OpenAI Whisper: ตั้งค่า QQ_STT_BASE_URL และ QQ_STT_MODEL
   • Endpoint STT ที่เข้ากันได้กับ OpenAI อื่นๆ

Troubleshooting

Bot disconnects immediately (quick disconnect)

โดยทั่วไปหมายความว่า:

• Invalid App ID / Secret - ตรวจสอบ credentials ของคุณอีกครั้งที่ q.qq.com
• Missing permissions - ตรวจสอบให้แน่ใจว่าบอทมีการเปิดใช้งาน intents ที่จำเป็น
• Sandbox-only bot - หากบอทอยู่ในโหมด sandbox มันจะรับข้อความได้เฉพาะจากช่องทดสอบ sandbox ของ QQ เท่านั้น

Voice messages not transcribed

1. ตรวจสอบว่า asr_refer_text ที่มีอยู่ในตัวของ QQ มีอยู่ในข้อมูลไฟล์แนบหรือไม่
2. หากใช้ผู้ให้บริการ STT แบบกำหนดเอง ให้ตรวจสอบว่า QQ_STT_API_KEY ถูกตั้งค่าอย่างถูกต้อง
3. ตรวจสอบ log ของ gateway สำหรับข้อความแสดงข้อผิดพลาดของ STT

Messages not delivered

• ตรวจสอบว่า intents ของบอทถูกเปิดใช้งานที่ q.qq.com
• ตรวจสอบ QQ_ALLOWED_USERS หากการเข้าถึง DM ถูกจำกัด
• สำหรับข้อความกลุ่ม ให้แน่ใจว่าบอทถูก @mentioned (นโยบายกลุ่มอาจต้องมีการ allowlisting)
• ตรวจสอบ QQBOT_HOME_CHANNEL สำหรับการส่ง cron/notification

Connection errors

• ตรวจสอบให้แน่ใจว่าติดตั้ง aiohttp และ httpx แล้ว: pip install aiohttp httpx
• ตรวจสอบการเชื่อมต่อเครือข่ายไปยัง api.sgroup.qq.com และ WebSocket gateway
• ตรวจสอบ log ของ gateway สำหรับข้อความแสดงข้อผิดพลาดโดยละเอียดและพฤติกรรมการเชื่อมต่อใหม่