📄 guides/migrate-from-openclaw.md

sidebar_position: 10 title: "Migrate from OpenClaw" description: "Complete guide to migrating your OpenClaw / Clawdbot setup to Hermes Agent - what gets migrated, how config maps, and what to check after."

Migrate from OpenClaw

hermes claw migrate ใช้สำหรับนำการตั้งค่า OpenClaw (หรือ Clawdbot/Moldbot รุ่นเก่า) ของคุณเข้าสู่ Hermes คู่มือนี้ครอบคลุมว่าอะไรบ้างที่จะถูกย้าย, การแมปคีย์ config, และสิ่งที่ต้องตรวจสอบหลังการย้ายข้อมูล

Quick start

# Preview then migrate (always shows a preview first, then asks to confirm)
hermes claw migrate

# Preview only, no changes
hermes claw migrate --dry-run

# Full migration including API keys, skip confirmation
hermes claw migrate --preset full --yes

การย้ายข้อมูลจะแสดงตัวอย่างเต็มรูปแบบเสมอว่าอะไรจะถูกนำเข้าก่อนที่จะทำการเปลี่ยนแปลงใดๆ โปรดตรวจสอบรายการ จากนั้นยืนยันเพื่อดำเนินการต่อ

โดยค่าเริ่มต้นจะอ่านจาก ~/.openclaw/ ไดเรกทอรี ~/.clawdbot/ หรือ ~/.moltbot/ รุ่นเก่าจะถูกตรวจจับโดยอัตโนมัติ เช่นเดียวกับชื่อไฟล์ config รุ่นเก่า (clawdbot.json, moltbot.json)

Options

What gets migrated

Persona, memory, and instructions

ไฟล์ workspace ยังถูกตรวจสอบที่ workspace.default/ และ workspace-main/ เป็น path สำรอง (OpenClaw เปลี่ยนชื่อ workspace/ เป็น workspace-main/ ในเวอร์ชันล่าสุด และใช้ workspace-{agentId} สำหรับการตั้งค่าหลาย agent)

Skills (4 sources)

ความขัดแย้งของ skill ถูกจัดการโดย --skill-conflict: skip จะคง skill ของ Hermes ที่มีอยู่, overwrite จะแทนที่, และ rename จะสร้างสำเนา -imported

Model and provider configuration

Agent behavior

Session reset policies

หมายเหตุ: OpenClaw ยังมี session.resetTriggers (เป็น simple string array เช่น ["daily", "idle"]) หากไม่มี session.reset ที่มีโครงสร้าง การย้ายข้อมูลจะย้อนกลับไปอนุมานจาก resetTriggers

MCP servers

TTS (text-to-speech)

การตั้งค่า TTS จะอ่านจากตำแหน่ง config ของ OpenClaw สอง แห่ง โดยมีลำดับความสำคัญดังนี้:

1. messages.tts.providers.{provider}.* (ตำแหน่งหลัก)
2. talk.providers.{provider}.* (ตำแหน่งสำรอง)
3. คีย์แบบ flat รุ่นเก่า messages.tts.{provider}.* (รูปแบบเก่าที่สุด)

Messaging platforms

Other config

Archived (no direct Hermes equivalent)

รายการเหล่านี้จะถูกบันทึกไว้ที่ ~/.hermes/migration/openclaw/<timestamp>/archive/ เพื่อตรวจสอบด้วยตนเอง:

API key resolution

เมื่อเปิดใช้งาน --migrate-secrets, API keys จะถูกรวบรวมจาก สี่แหล่ง โดยมีลำดับความสำคัญดังนี้:

1. Config values — models.providers.*.apiKey และคีย์ provider TTS ใน openclaw.json
2. Environment file — ~/.openclaw/.env (คีย์เช่น OPENROUTER_API_KEY, ANTHROPIC_API_KEY, ฯลฯ)
3. Config env sub-object — openclaw.json → "env" หรือ "env"."vars" (การตั้งค่าบางอย่างเก็บคีย์ไว้ที่นี่แทนไฟล์ .env แยก)
4. Auth profiles — ~/.openclaw/agents/main/agent/auth-profiles.json (credentials ต่อ agent)

ค่า config มีลำดับความสำคัญสูงสุด แหล่งที่มาถัดไปจะเติมช่องว่างที่เหลือทั้งหมด

Supported key targets

OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZAI_API_KEY, MINIMAX_API_KEY, ELEVENLABS_API_KEY, TELEGRAM_BOT_TOKEN, VOICE_TOOLS_OPENAI_KEY

คีย์ที่ไม่อยู่ใน allowlist นี้จะไม่ถูกคัดลอก

SecretRef handling

ค่า config ของ OpenClaw สำหรับ token และ API keys สามารถอยู่ในสามรูปแบบ:

// Plain string
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// Environment template
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// SecretRef object
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }

การย้ายข้อมูลจะแก้ไขทั้งสามรูปแบบ สำหรับ env templates และ SecretRef objects ที่มี source: "env", ระบบจะค้นหาค่าใน ~/.openclaw/.env และ sub-object env ของ openclaw.json SecretRef objects ที่มี source: "file" หรือ source: "exec" ไม่สามารถแก้ไขได้โดยอัตโนมัติ - การย้ายข้อมูลจะแจ้งเตือนเกี่ยวกับสิ่งเหล่านี้ และค่าเหล่านั้นจะต้องถูกเพิ่มเข้าสู่ Hermes ด้วยตนเองผ่าน hermes config set

After migration

1. Check the migration report - รายงานที่พิมพ์เมื่อเสร็จสิ้น พร้อมจำนวนรายการที่ถูกย้าย, ข้าม, และขัดแย้ง

2. Review archived files - สิ่งใดๆ ใน ~/.hermes/migration/openclaw/<timestamp>/archive/ ต้องได้รับการดูแลด้วยตนเอง

3. Start a new session - skills และ memory entries ที่นำเข้าจะมีผลใน session ใหม่ ไม่ใช่ session ปัจจุบัน

4. Verify API keys - รัน hermes status เพื่อตรวจสอบการยืนยันตัวตนของ provider

5. Test messaging - หากคุณย้าย token ของ platform ให้รีสตาร์ท gateway: systemctl --user restart hermes-gateway

6. Check session policies - ตรวจสอบว่า hermes config get session_reset ตรงตามความคาดหวังของคุณ

7. Re-pair WhatsApp - WhatsApp ใช้การจับคู่ด้วย QR code (Baileys) ไม่ใช่การย้าย token รัน hermes whatsapp เพื่อจับคู่

8. Archive cleanup - หลังจากยืนยันว่าทุกอย่างทำงานได้แล้ว ให้รัน hermes claw cleanup เพื่อเปลี่ยนชื่อไดเรกทอรี OpenClaw ที่เหลือให้เป็น .pre-migration/ (ป้องกันความสับสนของสถานะ)

Troubleshooting

"OpenClaw directory not found"

การย้ายข้อมูลจะตรวจสอบ ~/.openclaw/, จากนั้น ~/.clawdbot/, จากนั้น ~/.moltbot/ หากการติดตั้งของคุณอยู่ที่อื่น ให้ใช้ --source /path/to/your/openclaw

"No provider API keys found"

คีย์อาจถูกเก็บไว้ในหลายที่ขึ้นอยู่กับเวอร์ชัน OpenClaw ของคุณ: ใน openclaw.json ภายใต้ models.providers.*.apiKey, ใน ~/.openclaw/.env, ใน sub-object "env" ของ openclaw.json, หรือใน agents/main/agent/auth-profiles.json การย้ายข้อมูลจะตรวจสอบทั้งสี่ที่ หากคีย์ใช้ SecretRefs ที่มี source: "file" หรือ source: "exec" พวกมันจะไม่สามารถแก้ไขได้โดยอัตโนมัติ - ให้เพิ่มพวกมันผ่าน hermes config set

Skills not appearing after migration

skills ที่นำเข้าจะอยู่ใน ~/.hermes/skills/openclaw-imports/ ให้เริ่ม session ใหม่เพื่อให้มีผล หรือรัน /skills เพื่อตรวจสอบว่าโหลดแล้ว

TTS voice not migrated

OpenClaw เก็บการตั้งค่า TTS ไว้ในสองที่: messages.tts.providers.* และ talk config ระดับบนสุด การย้ายข้อมูลจะตรวจสอบทั้งสองที่ หาก voice ID ของคุณถูกตั้งค่าผ่าน OpenClaw UI (ซึ่งเก็บไว้ใน path ที่แตกต่างกัน) คุณอาจต้องตั้งค่าด้วยตนเอง: hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID

📄 guides/python-library.md

sidebar_position: 5 title: "การใช้ Hermes ในฐานะ Python Library" description: "ฝัง AIAgent ใน Python scripts, web apps, หรือ automation pipelines ของคุณเอง โดยไม่จำเป็นต้องใช้ CLI"

การใช้ Hermes ในฐานะ Python Library

Hermes ไม่ได้เป็นแค่ CLI tool เท่านั้น คุณสามารถ import AIAgent ได้โดยตรงและนำไปใช้แบบ programmatic ใน Python scripts, web applications, หรือ automation pipelines ของคุณได้ คู่มือนี้จะแสดงให้คุณเห็นถึงวิธีการทำ

การติดตั้ง (Installation)

ติดตั้ง Hermes โดยตรงจาก repository:

pip install git+https://github.com/NousResearch/hermes-agent.git

หรือด้วย uv:

uv pip install git+https://github.com/NousResearch/hermes-agent.git

คุณยังสามารถระบุเวอร์ชันใน requirements.txt ของคุณได้:

hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git

:::tip เมื่อใช้ Hermes ในฐานะ library คุณจำเป็นต้องใช้ environment variables เดียวกันกับที่ CLI ใช้ อย่างน้อยที่สุด ให้ตั้งค่า OPENROUTER_API_KEY (หรือ OPENAI_API_KEY / ANTHROPIC_API_KEY หากใช้การเข้าถึง provider โดยตรง). :::

การใช้งานพื้นฐาน (Basic Usage)

วิธีที่ง่ายที่สุดในการใช้ Hermes คือเมธอด chat() - เพียงแค่ส่งข้อความเข้าไป แล้วรับ string กลับมา:

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)
response = agent.chat("What is the capital of France?")
print(response)

chat() จะจัดการวงจรการสนทนาทั้งหมดภายในเอง - ไม่ว่าจะเป็น tool calls, retries, หรือทุกอย่าง - และจะส่งคืนเฉพาะข้อความสุดท้ายเท่านั้น

:::warning ควรตั้งค่า quiet_mode=True เสมอเมื่อฝัง Hermes ในโค้ดของคุณเอง หากไม่ทำเช่นนั้น agent จะพิมพ์ CLI spinners, progress indicators, และ output terminal อื่นๆ ซึ่งจะทำให้ output ของแอปพลิเคชันของคุณดูรกตา :::

การควบคุมการสนทนาแบบเต็มรูปแบบ (Full Conversation Control)

หากต้องการควบคุมการสนทนาให้มากขึ้น ให้ใช้ run_conversation() โดยตรง เมธอดนี้จะส่งคืน dictionary ที่มีข้อมูลการตอบกลับทั้งหมด, ประวัติข้อความ, และ metadata:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

result = agent.run_conversation(
    user_message="Search for recent Python 3.13 features",
    task_id="my-task-1",
)

print(result["final_response"])
print(f"Messages exchanged: {len(result['messages'])}")

dictionary ที่ส่งคืนมาประกอบด้วย:

• final_response - ข้อความตอบกลับสุดท้ายของ agent
• messages - ประวัติข้อความที่สมบูรณ์ (system, user, assistant, tool calls)
• task_id - ตัวระบุ task ที่ใช้สำหรับการแยก VM

คุณยังสามารถส่ง system message แบบกำหนดเองเพื่อแทนที่ system prompt ชั่วคราวสำหรับ call นั้นๆ ได้:

result = agent.run_conversation(
    user_message="Explain quicksort",
    system_message="You are a computer science tutor. Use simple analogies.",
)

การกำหนดค่า Tools (Configuring Tools)

ควบคุมชุดเครื่องมือที่ agent สามารถเข้าถึงได้โดยใช้ enabled_toolsets หรือ disabled_toolsets:

# เปิดใช้งานเฉพาะ web tools (browsing, search)
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# เปิดใช้งานทุกอย่าง ยกเว้นการเข้าถึง terminal
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)

:::tip ใช้ enabled_toolsets เมื่อคุณต้องการ agent ที่จำกัดและปลอดภัยที่สุด (เช่น ใช้เฉพาะ web search สำหรับ research bot) ใช้ disabled_toolsets เมื่อคุณต้องการความสามารถส่วนใหญ่ แต่จำเป็นต้องจำกัดบางอย่าง (เช่น ไม่อนุญาตให้เข้าถึง terminal ในสภาพแวดล้อมที่ใช้ร่วมกัน) :::

การสนทนาแบบหลายรอบ (Multi-turn Conversations)

รักษาสถานะการสนทนาข้ามหลายรอบได้โดยการส่ง message history กลับเข้าไป:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

# รอบที่หนึ่ง
result1 = agent.run_conversation("My name is Alice")
history = result1["messages"]

# รอบที่สอง - agent จะจำบริบทได้
result2 = agent.run_conversation(
    "What's my name?",
    conversation_history=history,
)
print(result2["final_response"])  # "Your name is Alice."

พารามิเตอร์ conversation_history จะรับรายการ messages จากผลลัพธ์ก่อนหน้า agent จะคัดลอกรายการนี้ภายใน ทำให้รายการต้นฉบับของคุณไม่ถูกเปลี่ยนแปลง

การบันทึก Trajectories (Saving Trajectories)

เปิดใช้งาน trajectory saving เพื่อบันทึกการสนทนาในรูปแบบ ShareGPT - มีประโยชน์สำหรับการสร้าง training data หรือการ debug:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    save_trajectories=True,
    quiet_mode=True,
)

agent.chat("Write a Python function to sort a list")
# บันทึกใน trajectory_samples.jsonl ในรูปแบบ ShareGPT

การสนทนาแต่ละครั้งจะถูกเพิ่มเป็นบรรทัด JSONL เดียว ทำให้ง่ายต่อการรวบรวม dataset จากการรันแบบอัตโนมัติ

Custom System Prompts

ใช้ ephemeral_system_prompt เพื่อตั้งค่า system prompt แบบกำหนดเองที่แนะนำพฤติกรรมของ agent แต่ จะไม่ ถูกบันทึกในไฟล์ trajectory (ทำให้ training data ของคุณสะอาด):

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    ephemeral_system_prompt="You are a SQL expert. Only answer database questions.",
    quiet_mode=True,
)

response = agent.chat("How do I write a JOIN query?")
print(response)

สิ่งนี้เหมาะอย่างยิ่งสำหรับการสร้าง specialized agents - เช่น code reviewer, documentation writer, หรือ SQL assistant - โดยทั้งหมดใช้ underlying tooling เดียวกัน

การประมวลผลแบบ Batch (Batch Processing)

สำหรับการรัน prompt จำนวนมากแบบขนาน Hermes มี batch_runner.py ซึ่งจัดการ instance ของ AIAgent แบบ concurrent พร้อมการแยก resource ที่เหมาะสม:

python batch_runner.py --input prompts.jsonl --output results.jsonl

แต่ละ prompt จะได้รับ task_id และ environment ที่แยกจากกัน หากคุณต้องการ logic batch แบบกำหนดเอง คุณสามารถสร้างเองได้โดยใช้ AIAgent โดยตรง:

import concurrent.futures
from run_agent import AIAgent

prompts = [
    "Explain recursion",
    "What is a hash table?",
    "How does garbage collection work?",
]

def process_prompt(prompt):
    # สร้าง agent ใหม่สำหรับแต่ละ task เพื่อความปลอดภัยของ thread
    agent = AIAgent(
        model="anthropic/claude-sonnet-4",
        quiet_mode=True,
        skip_memory=True,
    )
    return agent.chat(prompt)

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    results = list(executor.map(process_prompt, prompts))

for prompt, result in zip(prompts, results):
    print(f"Q: {prompt}\nA: {result}\n")

:::warning ควรสร้าง instance ของ AIAgent ใหม่สำหรับแต่ละ thread หรือ task เสมอ agent จะรักษาสถานะภายใน (conversation history, tool sessions, iteration counters) ซึ่งไม่ปลอดภัยที่จะแชร์กันใน concurrent call :::

ตัวอย่างการรวมระบบ (Integration Examples)

FastAPI Endpoint

from fastapi import FastAPI
from pydantic import BaseModel
from run_agent import AIAgent

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    model: str = "anthropic/claude-sonnet-4"

@app.post("/chat")
async def chat(request: ChatRequest):
    agent = AIAgent(
        model=request.model,
        quiet_mode=True,
        skip_context_files=True,
        skip_memory=True,
    )
    response = agent.chat(request.message)
    return {"response": response}

Discord Bot

import discord
from run_agent import AIAgent

client = discord.Client(intents=discord.Intents.default())

@client.event
async def on_message(message):
    if message.author == client.user:
        return
    if message.content.startswith("!hermes "):
        query = message.content[8:]
        agent = AIAgent(
            model="anthropic/claude-sonnet-4",
            quiet_mode=True,
            skip_context_files=True,
            skip_memory=True,
            platform="discord",
        )
        response = agent.chat(query)
        await message.channel.send(response[:2000])

client.run("YOUR_DISCORD_TOKEN")

CI/CD Pipeline Step

#!/usr/bin/env python3
"""CI step: auto-review a PR diff."""
import subprocess
from run_agent import AIAgent

diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    skip_context_files=True,
    skip_memory=True,
    disabled_toolsets=["terminal", "browser"],
)

review = agent.chat(
    f"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}"
)
print(review)

Key Constructor Parameters

ข้อควรทราบที่สำคัญ (Important Notes)

:::tip

• ตั้งค่า skip_context_files=True หากคุณไม่ต้องการให้ไฟล์ AGENTS.md จาก working directory ถูกโหลดเข้าสู่ system prompt
• ตั้งค่า skip_memory=True เพื่อป้องกันไม่ให้ agent อ่านหรือเขียน persistent memory - แนะนำสำหรับ stateless API endpoints
• พารามิเตอร์ platform (เช่น "discord", "telegram") จะใส่ hints สำหรับการจัดรูปแบบเฉพาะแพลตฟอร์ม เพื่อให้ agent ปรับรูปแบบ output ของตัวเองได้ :::

:::warning

• Thread safety: สร้าง AIAgent เพียงตัวเดียวต่อ thread หรือ task ห้ามแชร์ instance ข้าม concurrent calls
• Resource cleanup: agent จะทำความสะอาด resources โดยอัตโนมัติ (terminal sessions, browser instances) เมื่อการสนทนาสิ้นสุดลง หากคุณกำลังรันใน process ที่มีอายุยาวนาน ให้แน่ใจว่าทุกการสนทนาเสร็จสมบูรณ์ตามปกติ
• Iteration limits: ค่า default max_iterations=90 นั้นค่อนข้างสูง สำหรับกรณีใช้งาน Q&A แบบง่าย ควรพิจารณาลดค่าลง (เช่น max_iterations=10) เพื่อป้องกัน tool-calling loops ที่ไม่สิ้นสุดและควบคุมค่าใช้จ่าย :::

📄 guides/team-telegram-assistant.md

sidebar_position: 4 title: "Tutorial: Team Telegram Assistant" description: "Step-by-step guide to setting up a Telegram bot that your whole team can use for code help, research, system admin, and more"

การตั้งค่า Team Telegram Assistant

บทช่วยสอนนี้จะแนะนำวิธีการตั้งค่า Telegram bot ที่ขับเคลื่อนโดย Hermes Agent ซึ่งสมาชิกหลายคนในทีมสามารถใช้งานได้ เมื่อทำตามขั้นตอนเสร็จสิ้น ทีมของคุณจะมี AI assistant ส่วนกลางที่สามารถส่งข้อความเพื่อขอความช่วยเหลือด้านโค้ด การวิจัย การบริหารระบบ และอื่น ๆ อีกมากมาย โดยมีการรักษาความปลอดภัยด้วยการอนุญาตเฉพาะผู้ใช้แต่ละคน

สิ่งที่เรากำลังสร้าง

Telegram bot ที่:

• สมาชิกในทีมที่ได้รับอนุญาตทุกคน สามารถส่ง DM เพื่อขอความช่วยเหลือได้ - เช่น การรีวิวโค้ด การวิจัย คำสั่ง shell การดีบัก
• ทำงานบนเซิร์ฟเวอร์ของคุณ พร้อมการเข้าถึงเครื่องมือเต็มรูปแบบ - เช่น terminal, การแก้ไขไฟล์, การค้นหาเว็บ, การรันโค้ด
• เซสชันต่อผู้ใช้ - แต่ละคนจะได้รับบริบทการสนทนาของตัวเอง
• ปลอดภัยโดยค่าเริ่มต้น - มีเพียงผู้ใช้ที่ได้รับอนุมัติเท่านั้นที่สามารถโต้ตอบได้ โดยมีวิธีการอนุญาตสองวิธี
• งานตามกำหนดเวลา (Scheduled tasks) - เช่น การรายงานสถานะประจำวัน (daily standups) การตรวจสอบสุขภาพ (health checks) และการแจ้งเตือนที่ส่งไปยังช่องของทีม

สิ่งที่ต้องมี (Prerequisites)

ก่อนเริ่มต้น ให้แน่ใจว่าคุณมีสิ่งเหล่านี้:

• Hermes Agent ติดตั้งแล้ว บนเซิร์ฟเวอร์หรือ VPS (ไม่ใช่แล็ปท็อปของคุณ - เพราะบอทต้องทำงานอยู่ตลอดเวลา) หากยังไม่ได้ติดตั้ง ให้ทำตาม installation guide
• บัญชี Telegram สำหรับตัวคุณเอง (เจ้าของบอท)
• ผู้ให้บริการ LLM ที่กำหนดค่าแล้ว - อย่างน้อยต้องมี API key สำหรับ OpenAI, Anthropic, หรือผู้ให้บริการที่รองรับอื่น ๆ ใน ~/.hermes/.env

:::tip VPS ราคา $5/เดือน ก็เพียงพอสำหรับการรัน gateway แล้ว ตัว Hermes เองมีน้ำหนักเบา - ส่วนที่เสียเงินคือการเรียกใช้ LLM API ซึ่งจะเกิดขึ้นจากระยะไกล :::

ขั้นตอนที่ 1: สร้าง Telegram Bot

Telegram bot ทุกตัวเริ่มต้นด้วย @BotFather - บอทอย่างเป็นทางการของ Telegram สำหรับการสร้างบอท

1. เปิด Telegram และค้นหา @BotFather หรือไปที่ t.me/BotFather

2. ส่ง /newbot - BotFather จะถามคุณสองสิ่ง:

   • Display name - ชื่อที่ผู้ใช้เห็น (เช่น Team Hermes Assistant)
   • Username - ต้องลงท้ายด้วย bot (เช่น myteam_hermes_bot)

3. คัดลอก bot token - BotFather จะตอบกลับด้วยข้อความประมาณนี้:

   Use this token to access the HTTP API:
   7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

   บันทึก token นี้ไว้ - คุณจะต้องใช้มันในขั้นตอนถัดไป

4. ตั้งค่าคำอธิบาย (Description) (ไม่บังคับแต่แนะนำ):

   /setdescription

   เลือกบอทของคุณ จากนั้นป้อนข้อความประมาณนี้:

   Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.

5. ตั้งค่าคำสั่งบอท (Bot commands) (ไม่บังคับ - ช่วยให้ผู้ใช้มีเมนูคำสั่ง):

   /setcommands

   เลือกบอทของคุณ จากนั้นวาง:

   new - Start a fresh conversation
   model - Show or change the AI model
   status - Show session info
   help - Show available commands
   stop - Stop the current task

:::warning เก็บ bot token ของคุณเป็นความลับ ใครก็ตามที่มี token สามารถควบคุมบอทได้ หากรั่วไหล ให้ใช้ /revoke ใน BotFather เพื่อสร้าง token ใหม่ :::

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

คุณมีสองทางเลือก: setup wizard แบบโต้ตอบ (แนะนำ) หรือการกำหนดค่าด้วยตนเอง

ตัวเลือก A: Setup แบบโต้ตอบ (แนะนำ)

hermes gateway setup

สิ่งนี้จะแนะนำคุณทุกอย่างด้วยการเลือกด้วยปุ่มลูกศร เลือก Telegram วาง bot token ของคุณ และป้อน user ID ของคุณเมื่อถูกแจ้ง

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

เพิ่มบรรทัดเหล่านี้ลงใน ~/.hermes/.env:

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

การค้นหา User ID ของคุณ

Telegram user ID ของคุณคือค่าตัวเลข (ไม่ใช่ username ของคุณ) หากต้องการค้นหา:

1. ส่งข้อความถึง @userinfobot บน Telegram
2. มันจะตอบกลับด้วย user ID ตัวเลขของคุณทันที
3. คัดลอกตัวเลขนั้นไปใส่ใน TELEGRAM_ALLOWED_USERS

:::info Telegram user IDs เป็นตัวเลขถาวร เช่น 123456789 ซึ่งแตกต่างจาก @username ของคุณที่สามารถเปลี่ยนแปลงได้ ควรใช้ numeric ID เสมอสำหรับ allowlists :::

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

การทดสอบอย่างรวดเร็ว (Quick Test)

รัน gateway ใน foreground ก่อน เพื่อให้แน่ใจว่าทุกอย่างทำงานได้:

hermes gateway

คุณควรเห็น output เช่น:

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

เปิด Telegram ค้นหาบอทของคุณ และส่งข้อความให้มัน หากมันตอบกลับมา แสดงว่าคุณพร้อมใช้งานแล้ว กด Ctrl+C เพื่อหยุด

สำหรับ Production: ติดตั้งเป็น Service

สำหรับการใช้งานที่คงอยู่และรอดจากการรีบูต:

hermes gateway install
sudo hermes gateway install --system   # สำหรับ Linux เท่านั้น: system service ที่ทำงานเมื่อบูต

สิ่งนี้จะสร้าง background service: service ระดับผู้ใช้ systemd บน Linux โดยค่าเริ่มต้น, service launchd บน macOS, หรือ system service ของ Linux ที่ทำงานเมื่อบูตหากคุณส่ง --system

# Linux - จัดการ service ผู้ใช้เริ่มต้น
hermes gateway start
hermes gateway stop
hermes gateway status

# ดู live logs
journalctl --user -u hermes-gateway -f

# ให้ทำงานต่อไปแม้จะ logout ผ่าน SSH
sudo loginctl enable-linger $USER

# เซิร์ฟเวอร์ Linux - คำสั่ง system-service โดยชัดเจน
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS - จัดการ service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

:::tip macOS PATH launchd plist จะบันทึก shell PATH ของคุณ ณ เวลาติดตั้ง เพื่อให้ subprocesses ของ gateway สามารถค้นหาเครื่องมือต่างๆ เช่น Node.js และ ffmpeg ได้ หากคุณติดตั้งเครื่องมือใหม่ในภายหลัง ให้รัน hermes gateway install อีกครั้งเพื่ออัปเดต plist :::

ตรวจสอบว่ากำลังทำงานอยู่

hermes gateway status

จากนั้นส่งข้อความทดสอบไปยังบอทของคุณบน Telegram คุณควรได้รับการตอบกลับภายในไม่กี่วินาที

ขั้นตอนที่ 4: ตั้งค่าการเข้าถึงของทีม

ตอนนี้เรามาให้สิทธิ์เพื่อนร่วมทีมของคุณกัน มีสองแนวทาง

แนวทาง A: Static Allowlist

รวบรวม user ID ของ Telegram ของสมาชิกในทีมแต่ละคน (ให้พวกเขาส่งข้อความถึง @userinfobot) และเพิ่มพวกเขาเป็นรายการที่คั่นด้วยเครื่องหมายคอมมา:

# ใน ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

รีสตาร์ท gateway หลังจากการเปลี่ยนแปลง:

hermes gateway stop && hermes gateway start

แนวทาง B: DM Pairing (แนะนำสำหรับทีม)

DM pairing มีความยืดหยุ่นกว่า - คุณไม่จำเป็นต้องรวบรวม user ID ล่วงหน้า นี่คือวิธีการทำงาน:

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

   🔐 Pairing code: XKGH5N7P
   Send this code to the bot owner for approval.

2. เพื่อนร่วมทีมส่งโค้ดให้คุณ (ผ่านช่องทางใดก็ได้ - Slack, email, ตัวจริง)

3. คุณอนุมัติมัน บนเซิร์ฟเวอร์:

   hermes pairing approve telegram XKGH5N7P

4. พวกเขาเข้าใช้งานได้แล้ว - บอทจะเริ่มตอบกลับข้อความของพวกเขาในทันที

การจัดการผู้ใช้ที่จับคู่แล้ว:

# ดูผู้ใช้ที่รอการอนุมัติและผู้ที่อนุมัติแล้วทั้งหมด
hermes pairing list

# เพิกถอนการเข้าถึงของใครบางคน
hermes pairing revoke telegram 987654321

# ล้างรหัสที่รอการอนุมัติที่หมดอายุ
hermes pairing clear-pending

:::tip DM pairing เหมาะสำหรับทีม เพราะคุณไม่จำเป็นต้องรีสตาร์ท gateway เมื่อเพิ่มผู้ใช้ใหม่ การอนุมัติจะมีผลทันที :::

ข้อควรพิจารณาด้านความปลอดภัย

• ห้ามตั้งค่า GATEWAY_ALLOW_ALL_USERS=true บนบอทที่มีการเข้าถึง terminal - ใครก็ตามที่พบบอทของคุณสามารถรันคำสั่งบนเซิร์ฟเวอร์ของคุณได้
• รหัสจับคู่จะหมดอายุภายใน 1 ชั่วโมง และใช้ cryptographic randomness
• Rate limiting ป้องกันการโจมตีแบบ brute-force: 1 request ต่อผู้ใช้ ต่อ 10 นาที, สูงสุด 3 pending codes ต่อแพลตฟอร์ม
• หลังจากพยายามอนุมัติล้มเหลว 5 ครั้ง แพลตฟอร์มจะเข้าสู่โหมดล็อกเอาต์ 1 ชั่วโมง
• ข้อมูล pairing ทั้งหมดจะถูกจัดเก็บด้วยสิทธิ์ chmod 0600

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

ตั้งค่า Home Channel

Home channel คือที่ที่บอทส่งผลลัพธ์ของ cron job และข้อความเชิงรุก หากไม่มี Home channel งานตามกำหนดเวลาจะไม่มีที่ส่ง output

ตัวเลือก 1: ใช้คำสั่ง /sethome ในกลุ่มหรือแชท Telegram ใดก็ได้ที่บอทเป็นสมาชิก

ตัวเลือก 2: ตั้งค่าด้วยตนเองใน ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

ในการค้นหา channel ID ให้เพิ่ม @userinfobot เข้าไปในกลุ่ม - มันจะรายงาน chat ID ของกลุ่ม

กำหนดค่าการแสดงความคืบหน้าของเครื่องมือ (Tool Progress Display)

ควบคุมว่าบอทจะแสดงรายละเอียดมากแค่ไหนเมื่อใช้เครื่องมือ ใน ~/.hermes/config.yaml:

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

ผู้ใช้ยังสามารถเปลี่ยนสิ่งนี้ได้ต่อเซสชันด้วยคำสั่ง /verbose ในแชท

ตั้งค่าบุคลิกภาพด้วย SOUL.md

ปรับแต่งวิธีการสื่อสารของบอทโดยการแก้ไข ~/.hermes/SOUL.md:

สำหรับคู่มือฉบับเต็ม ดูที่ Use SOUL.md with Hermes

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries - the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

เพิ่มบริบทของโปรเจกต์ (Project Context)

หากทีมของคุณทำงานในโปรเจกต์เฉพาะ ให้สร้างไฟล์ context เพื่อให้บอททราบ stack ของคุณ:

<!-- ~/.hermes/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

:::info Context files จะถูกฉีดเข้าไปใน system prompt ของทุกเซสชัน เก็บให้กระชับ - ทุกตัวอักษรมีผลต่องบประมาณ token ของคุณ :::

ขั้นตอนที่ 6: ตั้งค่างานตามกำหนดเวลา (Scheduled Tasks)

เมื่อ gateway ทำงานแล้ว คุณสามารถตั้งเวลางานที่เกิดขึ้นซ้ำๆ ซึ่งจะส่งผลลัพธ์ไปยังช่องของทีมคุณ

สรุป Daily Standup

ส่งข้อความถึงบอทบน Telegram:

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

agent จะสร้าง cron job โดยอัตโนมัติและส่งผลลัพธ์ไปยังแชทที่คุณถาม (หรือ home channel)

การตรวจสอบสุขภาพเซิร์ฟเวอร์ (Server Health Check)

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual -
partitions above 80%, containers that have restarted, or high memory usage.

การจัดการงานตามกำหนดเวลา

# จาก CLI
hermes cron list          # ดูงานที่กำหนดเวลาทั้งหมด
hermes cron status        # ตรวจสอบว่า scheduler กำลังทำงานอยู่หรือไม่

# จากแชท Telegram
/cron list                # ดูงาน
/cron remove <job_id>     # ลบงาน

:::warning คำสั่ง cron job จะทำงานในเซสชันที่สดใหม่โดยสมบูรณ์โดยไม่มีความทรงจำของการสนทนาก่อนหน้า ตรวจสอบให้แน่ใจว่าแต่ละ prompt มี บริบททั้งหมด ที่ agent ต้องการ - เช่น file paths, URLs, server addresses, และคำแนะนำที่ชัดเจน :::

เคล็ดลับสำหรับ Production (Production Tips)

ใช้ Docker เพื่อความปลอดภัย

บนบอททีมที่ใช้ร่วมกัน ให้ใช้ Docker เป็น backend terminal เพื่อให้คำสั่งของ agent ทำงานใน container แทนที่จะทำงานบน host ของคุณ:

# ใน ~/.hermes/.env
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

หรือใน ~/.hermes/config.yaml:

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

ด้วยวิธีนี้ แม้ว่าใครบางคนจะขอให้บอทรันสิ่งที่ทำลายล้าง ระบบ host ของคุณก็จะได้รับการป้องกัน

ตรวจสอบ Gateway

# ตรวจสอบว่า gateway กำลังทำงานอยู่หรือไม่
hermes gateway status

# ดู live logs (Linux)
journalctl --user -u hermes-gateway -f

# ดู live logs (macOS)
tail -f ~/.hermes/logs/gateway.log

อัปเดต Hermes

จาก Telegram ให้ส่ง /update ไปยังบอท - มันจะดึงเวอร์ชันล่าสุดและรีสตาร์ท หรือจากเซิร์ฟเวอร์:

hermes update
hermes gateway stop && hermes gateway start

ตำแหน่ง Log

ก้าวต่อไป (Going Further)

คุณมีทีม Telegram assistant ที่ใช้งานได้แล้ว นี่คือขั้นตอนต่อไปบางส่วน:

• Security Guide - เจาะลึกเรื่องการอนุญาต, container isolation, และการอนุมัติคำสั่ง
• Messaging Gateway - เอกสารอ้างอิงเต็มรูปแบบสำหรับสถาปัตยกรรม gateway, การจัดการเซสชัน, และคำสั่งแชท
• Telegram Setup - รายละเอียดเฉพาะแพลตฟอร์ม รวมถึง voice messages และ TTS
• Scheduled Tasks - การตั้งเวลา cron ขั้นสูงพร้อมตัวเลือกการส่งมอบและ cron expressions
• Context Files - AGENTS.md, SOUL.md, และ .cursorrules สำหรับความรู้โปรเจกต์
• Personality - preset บุคลิกภาพในตัวและคำจำกัดความ persona ที่กำหนดเอง
• เพิ่มแพลตฟอร์มอื่น ๆ - gateway เดียวกันสามารถรัน Discord, Slack, และ WhatsApp ได้พร้อมกัน

มีคำถามหรือปัญหาหรือไม่? เปิด issue บน GitHub - ยินดีรับการมีส่วนร่วม

📄 guides/tips.md

sidebar_position: 1 title: "Tips & Best Practices" description: "Practical advice to get the most out of Hermes Agent - prompt tips, CLI shortcuts, context files, memory, cost optimization, and security"

Tips & Best Practices

ชุดเคล็ดลับปฏิบัติที่ช่วยให้คุณทำงานกับ Hermes Agent ได้อย่างมีประสิทธิภาพมากขึ้นทันที แต่ละส่วนจะเน้นที่แง่มุมที่แตกต่างกัน - ให้สแกนหัวข้อและข้ามไปยังส่วนที่คุณสนใจได้เลย

Getting the Best Results

Be Specific About What You Want

Prompt ที่คลุมเครือจะให้ผลลัพธ์ที่คลุมเครือเช่นกัน แทนที่จะบอกว่า "fix the code" ให้ระบุว่า "fix the TypeError ใน api/handlers.py บรรทัดที่ 47 - ฟังก์ชัน process_request() ได้รับค่า None จาก parse_body()" ยิ่งคุณให้บริบทมากเท่าไหร่ คุณก็จะยิ่งต้องทำซ้ำน้อยลงเท่านั้น

Provide Context Up Front

ให้ข้อมูลที่เกี่ยวข้องตั้งแต่ต้น: file paths, error messages, expected behavior ข้อความที่คิดมาอย่างดีเพียงข้อความเดียวดีกว่าการถามคำถามเพื่อขอความชัดเจนถึงสามรอบ วาง error tracebacks ลงไปโดยตรง - agent สามารถวิเคราะห์ข้อมูลเหล่านี้ได้

Use Context Files for Recurring Instructions

หากคุณพบว่าตัวเองต้องทำซ้ำคำสั่งเดิมๆ ("ใช้ tabs ไม่ใช่ spaces," "เราใช้ pytest," "API อยู่ที่ /api/v2") ให้ใส่คำสั่งเหล่านั้นไว้ในไฟล์ AGENTS.md agent จะอ่านไฟล์นี้โดยอัตโนมัติในทุก session - ไม่ต้องออกแรงอะไรเลยหลังจากตั้งค่าครั้งแรก

Let the Agent Use Its Tools

อย่าพยายามควบคุมทุกขั้นตอน บอกว่า "find and fix the failing test" แทนที่จะบอกว่า "open tests/test_foo.py, ดูที่บรรทัด 42, แล้ว..." agent มีความสามารถในการค้นหาไฟล์, เข้าถึง terminal, และรันโค้ด - ปล่อยให้มันสำรวจและทำซ้ำได้เลย

Use Skills for Complex Workflows

ก่อนที่จะเขียน prompt ยาวๆ เพื่ออธิบายวิธีการทำอะไรบางอย่าง ให้ตรวจสอบก่อนว่ามี skill สำหรับงานนั้นอยู่แล้วหรือไม่ พิมพ์ /skills เพื่อดู skill ที่มีให้ใช้งาน หรือเรียกใช้โดยตรง เช่น /axolotl หรือ /github-pr-workflow

CLI Power User Tips

Multi-Line Input

กด Alt+Enter (หรือ Ctrl+J) เพื่อแทรกบรรทัดใหม่โดยที่ยังไม่ส่งข้อความ วิธีนี้ช่วยให้คุณสามารถเขียน prompt หลายบรรทัด, วาง code blocks, หรือจัดโครงสร้างคำขอที่ซับซ้อนก่อนที่จะกด Enter เพื่อส่ง

Paste Detection

CLI จะตรวจจับการวางข้อความหลายบรรทัดโดยอัตโนมัติ เพียงแค่วาง code block หรือ error traceback โดยตรง - มันจะไม่ส่งทีละบรรทัด แต่จะบัฟเฟอร์การวางทั้งหมดและส่งเป็นข้อความเดียว

Interrupt and Redirect

กด Ctrl+C หนึ่งครั้งเพื่อขัดจังหวะ agent ขณะที่กำลังตอบ คุณสามารถพิมพ์ข้อความใหม่เพื่อเปลี่ยนทิศทางของมันได้ หากต้องการบังคับออก ให้กด Ctrl+C สองครั้งภายใน 2 วินาที วิธีนี้มีค่ามากเมื่อ agent เริ่มออกนอกเส้นทางที่ถูกต้อง

Resume Sessions with -c

ลืมอะไรบางอย่างจาก session ที่แล้วไป? รัน hermes -c เพื่อกลับไปที่จุดที่คุณค้างไว้พอดี พร้อมกับประวัติการสนทนาทั้งหมดที่ถูกกู้คืน คุณยังสามารถกลับไปที่หัวข้อได้ด้วย: hermes -r "my research project"

Clipboard Image Paste

กด Ctrl+V เพื่อวางรูปภาพจาก clipboard ของคุณลงใน chat ได้โดยตรง agent ใช้ vision ในการวิเคราะห์ screenshots, diagrams, error popups, หรือ UI mockups - ไม่จำเป็นต้องบันทึกเป็นไฟล์ก่อน

Slash Command Autocomplete

พิมพ์ / แล้วกด Tab เพื่อดูคำสั่งทั้งหมดที่มีอยู่ ซึ่งรวมถึงคำสั่ง built-in (/compress, /model, /title) และทุก skill ที่ติดตั้ง คุณไม่จำเป็นต้องจำอะไรเลย - Tab completion จัดการให้คุณแล้ว

:::tip ใช้ /verbose เพื่อสลับโหมดการแสดงผล tool output: off → new → all → verbose โหมด "all" เหมาะสำหรับการดูว่า agent ทำอะไรไปบ้าง; "off" สะอาดที่สุดสำหรับการถาม-ตอบแบบง่ายๆ :::

Context Files

AGENTS.md: Your Project's Brain

สร้างไฟล์ AGENTS.md ใน root directory ของโปรเจกต์ของคุณ โดยใส่การตัดสินใจด้านสถาปัตยกรรม, coding conventions, และคำสั่งเฉพาะโปรเจกต์ สิ่งนี้จะถูกฉีดเข้าไปในทุก session โดยอัตโนมัติ ทำให้ agent รู้กฎของโปรเจกต์คุณเสมอ

# Project Context
- This is a FastAPI backend with SQLAlchemy ORM
- Always use async/await for database operations
- Tests go in tests/ and use pytest-asyncio
- Never commit .env files

SOUL.md: Customize Personality

ต้องการให้ Hermes มีบุคลิกภาพเริ่มต้นที่เสถียรไหม? แก้ไข ~/.hermes/SOUL.md (หรือ $HERMES_HOME/SOUL.md หากคุณใช้ Hermes home แบบกำหนดเอง) ตอนนี้ Hermes จะ seed SOUL เริ่มต้นโดยอัตโนมัติและใช้ไฟล์ global นี้เป็นแหล่งที่มาของบุคลิกภาพทั่วทั้ง instance

สำหรับคำแนะนำแบบเต็ม ให้ดูที่ Use SOUL.md with Hermes

# Soul
You are a senior backend engineer. Be terse and direct.
Skip explanations unless asked. Prefer one-liners over verbose solutions.
Always consider error handling and edge cases.

ใช้ SOUL.md สำหรับบุคลิกภาพที่คงทน ใช้ AGENTS.md สำหรับคำสั่งเฉพาะโปรเจกต์

.cursorrules Compatibility

มีไฟล์ .cursorrules หรือ .cursor/rules/*.mdc อยู่แล้วหรือไม่? Hermes อ่านไฟล์เหล่านั้นด้วย ไม่จำเป็นต้องทำซ้ำ coding conventions ของคุณ - เพราะมันถูกโหลดโดยอัตโนมัติจาก working directory

Discovery

Hermes จะโหลด AGENTS.md ระดับบนสุดจาก current working directory เมื่อเริ่ม session ไฟล์ AGENTS.md ใน subdirectory จะถูกค้นพบแบบ lazy ในระหว่างการเรียกใช้ tool (ผ่าน subdirectory_hints.py) และถูกฉีดเข้าไปใน tool results - มันไม่ได้ถูกโหลดล่วงหน้าเข้าไปใน system prompt

:::tip ให้ context files มีความกระชับและมุ่งเน้นเฉพาะเรื่อง เพราะทุกตัวอักษรมีผลต่อ token budget ของคุณ เนื่องจากมันถูกฉีดเข้าไปในทุกข้อความ :::

Memory & Skills

Memory vs. Skills: What Goes Where

Memory ใช้สำหรับข้อเท็จจริง: environment ของคุณ, preferences, ตำแหน่งโปรเจกต์, และสิ่งที่ agent ได้เรียนรู้เกี่ยวกับคุณ Skills ใช้สำหรับขั้นตอนการทำงาน: multi-step workflows, คำสั่งเฉพาะ tool, และสูตรที่นำกลับมาใช้ใหม่ได้ ใช้ memory สำหรับ "อะไร" (what), ใช้ skills สำหรับ "อย่างไร" (how)

When to Create Skills

หากคุณพบงานที่ต้องใช้ 5+ steps และคุณจะต้องทำมันอีกครั้ง ให้ขอให้ agent สร้าง skill สำหรับงานนั้น บอกว่า "save what you just did as a skill called deploy-staging" ครั้งหน้า เพียงแค่พิมพ์ /deploy-staging และ agent จะโหลดขั้นตอนทั้งหมดให้

Managing Memory Capacity

Memory ถูกจำกัดไว้โดยเจตนา (~2,200 chars สำหรับ MEMORY.md, ~1,375 chars สำหรับ USER.md) เมื่อเต็มแล้ว agent จะทำการรวมข้อมูล (consolidates entries) คุณสามารถช่วยได้โดยการบอกว่า "clean up your memory" หรือ "replace the old Python 3.9 note - we're on 3.12 now"

Let the Agent Remember

หลังจาก session ที่มีประสิทธิภาพ ให้บอกว่า "remember this for next time" และ agent จะบันทึก key takeaways คุณยังสามารถระบุเจาะจงได้: "save to memory that our CI uses GitHub Actions with the deploy.yml workflow"

:::warning Memory เป็น snapshot ที่ถูกแช่แข็ง - การเปลี่ยนแปลงที่เกิดขึ้นระหว่าง session จะไม่ปรากฏใน system prompt จนกว่า session ถัดไปจะเริ่ม agent จะเขียนลง disk ทันที แต่ prompt cache จะไม่ถูก invalidates ระหว่าง session :::

Performance & Cost

Don't Break the Prompt Cache

ผู้ให้บริการ LLM ส่วนใหญ่จะ cache system prompt prefix หากคุณรักษา system prompt ให้คงที่ (context files เดียวกัน, memory เดียวกัน) ข้อความถัดไปใน session จะได้ cache hits ซึ่งมีค่าใช้จ่ายที่ถูกกว่าอย่างมาก หลีกเลี่ยงการเปลี่ยน model หรือ system prompt กลาง session

Use /compress Before Hitting Limits

Session ที่ยาวนานจะสะสม tokens เมื่อคุณสังเกตเห็นว่าการตอบสนองช้าลงหรือถูกตัดทอน ให้รัน /compress สิ่งนี้จะสรุปประวัติการสนทนา โดยยังคงรักษา context ที่สำคัญไว้ ขณะที่ลดจำนวน tokens ลงอย่างมาก ใช้ /usage เพื่อตรวจสอบสถานะของคุณ

Delegate for Parallel Work

ต้องการวิจัยสามหัวข้อพร้อมกันไหม? ให้ agent ใช้ delegate_task พร้อม subtasks แบบขนาน แต่ละ subagent จะทำงานอย่างอิสระพร้อม context ของตัวเอง และมีเพียงสรุปสุดท้ายเท่านั้นที่ส่งกลับมา - ซึ่งช่วยลดการใช้ tokens ของ main conversation ของคุณได้อย่างมาก

Use execute_code for Batch Operations

แทนที่จะรันคำสั่ง terminal ทีละคำสั่ง ให้ขอให้ agent เขียน script ที่ทำทุกอย่างพร้อมกัน "Write a Python script to rename all .jpeg files to .jpg and run it" มีค่าใช้จ่ายน้อยกว่าและเร็วกว่าการเปลี่ยนชื่อไฟล์ทีละไฟล์

Choose the Right Model

ใช้ /model เพื่อสลับ model กลาง session ใช้ frontier model (Claude Sonnet/Opus, GPT-4o) สำหรับการให้เหตุผลที่ซับซ้อนและการตัดสินใจด้านสถาปัตยกรรม สลับไปใช้ model ที่เร็วกว่าสำหรับงานง่ายๆ เช่น การจัดรูปแบบ, การเปลี่ยนชื่อ, หรือการสร้าง boilerplate

:::tip รัน /usage เป็นระยะเพื่อดูการใช้ tokens ของคุณ รัน /insights เพื่อดูภาพรวมของรูปแบบการใช้งานในช่วง 30 วันที่ผ่านมา :::

Messaging Tips

Set a Home Channel

ใช้ /sethome ใน chat Telegram หรือ Discord ที่คุณต้องการ เพื่อกำหนดให้เป็น home channel ผลลัพธ์ของ cron job และ output ของ scheduled task จะถูกส่งมาที่นี่ หากไม่มีสิ่งนี้ agent จะไม่มีที่ส่งข้อความเชิงรุก

Use /title to Organize Sessions

ตั้งชื่อ session ของคุณด้วย /title auth-refactor หรือ /title research-llm-quantization Session ที่มีชื่อจะหาได้ง่ายด้วย hermes sessions list และกลับไปที่ด้วย hermes -r "auth-refactor" Session ที่ไม่มีชื่อจะสะสมและยากต่อการแยกแยะ

DM Pairing for Team Access

แทนที่จะรวบรวม user IDs สำหรับ allowlists ด้วยตนเอง ให้เปิดใช้งาน DM pairing เมื่อเพื่อนร่วมทีม DM bot พวกเขาจะได้รับรหัส pairing แบบใช้ครั้งเดียว คุณอนุมัติด้วย hermes pairing approve telegram XKGH5N7P - ง่ายและปลอดภัย

Tool Progress Display Modes

ใช้ /verbose เพื่อควบคุมว่าคุณจะเห็นกิจกรรมของ tool มากน้อยแค่ไหน ใน messaging platforms โดยทั่วไปยิ่งน้อยยิ่งดี - ให้คงไว้ที่ "new" เพื่อดูเฉพาะการเรียกใช้ tool ใหม่ๆ ใน CLI, "all" จะให้มุมมองสดที่น่าพอใจว่า agent ทำอะไรไปบ้าง

:::tip ใน messaging platforms, session จะรีเซ็ตโดยอัตโนมัติหลังจากไม่มีการใช้งาน (ค่าเริ่มต้น: 24 ชั่วโมง) หรือรายวันเวลา 4 โมงเช้า ปรับเปลี่ยนต่อแพลตฟอร์มใน ~/.hermes/config.yaml หากคุณต้องการ session ที่ยาวนานขึ้น :::

Security

Use Docker for Untrusted Code

เมื่อทำงานกับ repository ที่ไม่น่าเชื่อถือ หรือรันโค้ดที่ไม่คุ้นเคย ให้ใช้ Docker หรือ Daytona เป็น terminal backend ของคุณ ตั้งค่า TERMINAL_BACKEND=docker ใน .env คำสั่งที่ทำลายล้างภายใน container ไม่สามารถทำอันตรายต่อ host system ของคุณได้

# In your .env:
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest

Avoid Windows Encoding Pitfalls

บน Windows, encoding เริ่มต้นบางตัว (เช่น cp125x) ไม่สามารถแทน Unicode characters ได้ทั้งหมด ซึ่งอาจทำให้เกิด UnicodeEncodeError เมื่อเขียนไฟล์ใน tests หรือ scripts

• ควรเปิดไฟล์ด้วย encoding แบบ UTF-8 อย่างชัดเจน:

with open("results.txt", "w", encoding="utf-8") as f:
    f.write("✓ All good\n")

• ใน PowerShell คุณยังสามารถสลับ current session เป็น UTF-8 สำหรับ console และ native command output:

$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)

สิ่งนี้จะทำให้ PowerShell และ child processes อยู่บน UTF-8 และช่วยหลีกเลี่ยงความล้มเหลวเฉพาะของ Windows

Review Before Choosing "Always"

เมื่อ agent ทริกเกอร์การอนุมัติคำสั่งอันตราย (rm -rf, DROP TABLE, ฯลฯ) คุณจะได้รับสี่ตัวเลือก: once, session, always, deny คิดให้รอบคอบก่อนเลือก "always" - เพราะมันจะอนุญาต pattern นั้นอย่างถาวร เริ่มต้นด้วย "session" จนกว่าคุณจะรู้สึกสบายใจ

Command Approval Is Your Safety Net

Hermes จะตรวจสอบทุกคำสั่งกับรายการ pattern อันตรายที่รวบรวมไว้ก่อนการดำเนินการ ซึ่งรวมถึงการลบแบบ recursive, SQL drops, การ pipe curl ไปยัง shell และอื่นๆ ห้ามปิดฟังก์ชันนี้ใน production - เพราะมันมีเหตุผลที่ดี

:::warning เมื่อรันใน container backend (Docker, Singularity, Modal, Daytona), การตรวจสอบคำสั่งอันตรายจะ ถูกข้าม เนื่องจาก container คือขอบเขตความปลอดภัย ตรวจสอบให้แน่ใจว่า container images ของคุณถูกล็อกดาวน์อย่างเหมาะสม :::

Use Allowlists for Messaging Bots

ห้ามตั้งค่า GATEWAY_ALLOW_ALL_USERS=true บน bot ที่มีการเข้าถึง terminal เด็ดขาด ให้ใช้ platform-specific allowlists (TELEGRAM_ALLOWED_USERS, DISCORD_ALLOWED_USERS) หรือ DM pairing เสมอ เพื่อควบคุมว่าใครสามารถโต้ตอบกับ agent ของคุณได้

# Recommended: explicit allowlists per platform
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678

# Or use cross-platform allowlist
GATEWAY_ALLOWED_USERS=123456789,987654321

มีเคล็ดลับที่คุณคิดว่าควรอยู่ในหน้านี้หรือไม่? เปิด issue หรือ PR - ยินดีรับการมีส่วนร่วมจากชุมชน

📄 guides/use-mcp-with-hermes.md

sidebar_position: 6 title: "Use MCP with Hermes" description: "A practical guide to connecting MCP servers to Hermes Agent, filtering their tools, and using them safely in real workflows"

การใช้ MCP กับ Hermes

คู่มือนี้แสดงให้เห็นว่าคุณจะใช้ MCP กับ Hermes Agent ในเวิร์กโฟลว์ประจำวันได้อย่างไร

หากหน้าฟีเจอร์ได้อธิบายว่า MCP คืออะไร คู่มือนี้จะเน้นไปที่วิธีการดึงคุณค่าจากมันอย่างรวดเร็วและปลอดภัย

ควรใช้ MCP เมื่อใด?

ให้ใช้ MCP เมื่อ:

• มี tool ที่มีอยู่ในรูปแบบ MCP อยู่แล้ว และคุณไม่ต้องการสร้าง native Hermes tool
• คุณต้องการให้ Hermes ทำงานกับระบบภายในหรือภายนอกผ่านชั้น RPC layer ที่สะอาด
• คุณต้องการการควบคุมการเปิดเผย (exposure control) ของแต่ละ server อย่างละเอียด
• คุณต้องการเชื่อมต่อ Hermes กับ internal API, ฐานข้อมูล, หรือระบบของบริษัทโดยไม่ต้องแก้ไข core ของ Hermes

ไม่ควรใช้ MCP เมื่อ:

• built-in Hermes tool สามารถแก้ปัญหาได้ดีอยู่แล้ว
• server เปิดเผย tool surface ที่ใหญ่และอันตรายมาก และคุณยังไม่พร้อมที่จะกรองมัน
• คุณต้องการการเชื่อมต่อที่แคบมากเพียงอย่างเดียว และ native tool จะง่ายและปลอดภัยกว่า

แนวคิดหลัก (Mental model)

ให้คิดว่า MCP เป็น adapter layer:

• Hermes ยังคงเป็น agent
• MCP servers ทำหน้าที่ contribute tools
• Hermes จะค้นพบ tools เหล่านั้นเมื่อเริ่มต้นหรือเมื่อมีการโหลดใหม่
• model สามารถใช้ tools เหล่านั้นได้เหมือน tools ทั่วไป
• คุณเป็นผู้ควบคุมว่าส่วนใดของแต่ละ server ที่จะมองเห็นได้

ส่วนสุดท้ายนี้สำคัญมาก การใช้ MCP ที่ดีไม่ได้หมายถึงแค่ "เชื่อมต่อทุกอย่าง" แต่มันคือ "เชื่อมต่อสิ่งที่ถูกต้อง ด้วย surface ที่มีประโยชน์น้อยที่สุด"

ขั้นตอนที่ 1: ติดตั้ง MCP support

หากคุณติดตั้ง Hermes ด้วย standard install script, MCP support จะถูกรวมมาให้แล้ว (ตัวติดตั้งจะรัน uv pip install -e ".[all]").

หากคุณติดตั้งโดยไม่มี extras และต้องการเพิ่ม MCP แยกต่างหาก:

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

สำหรับ server ที่ใช้ npm-based, ให้แน่ใจว่า Node.js และ npx พร้อมใช้งาน

สำหรับ Python MCP servers ส่วนใหญ่, uvx เป็นค่าเริ่มต้นที่ดี

ขั้นตอนที่ 2: เพิ่ม server เพียงตัวเดียวก่อน

เริ่มต้นด้วย server ที่ปลอดภัยเพียงตัวเดียว

ตัวอย่าง: การเข้าถึง filesystem สำหรับไดเรกทอรีโปรเจกต์เพียงโปรเจกต์เดียว

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

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

hermes chat

ตอนนี้ให้ถามคำถามที่เฉพาะเจาะจง:

Inspect this project and summarize the repo layout.

ขั้นตอนที่ 3: ตรวจสอบว่า MCP โหลดแล้ว

คุณสามารถตรวจสอบ MCP ได้หลายวิธี:

• แบนเนอร์/สถานะของ Hermes ควรแสดงการรวม MCP เมื่อมีการกำหนดค่า
• ถาม Hermes ว่ามี tools อะไรให้ใช้งานบ้าง
• ใช้ /reload-mcp หลังจากการเปลี่ยนแปลง config
• ตรวจสอบ logs หาก server ล้มเหลวในการเชื่อมต่อ

คำสั่งทดสอบที่ใช้งานได้จริง:

Tell me which MCP-backed tools are available right now.

ขั้นตอนที่ 4: เริ่มการกรองทันที

อย่ารอจนกว่าจะสาย หาก server เปิดเผย tools จำนวนมาก

ตัวอย่าง: whitelist เฉพาะสิ่งที่คุณต้องการ

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

นี่มักจะเป็นค่าเริ่มต้นที่ดีที่สุดสำหรับระบบที่ละเอียดอ่อน

ตัวอย่าง: blacklist การกระทำที่อันตราย

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

ตัวอย่าง: ปิด utility wrappers ด้วย

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

การกรองส่งผลกระทบอะไรบ้าง?

ใน Hermes มีฟังก์ชันการทำงานที่เปิดเผยผ่าน MCP อยู่สองประเภท:

1. Server-native MCP tools

• ถูกกรองด้วย:
  • tools.include
  • tools.exclude

1. Hermes-added utility wrappers

• ถูกกรองด้วย:
  • tools.resources
  • tools.prompts

Utility wrappers ที่คุณอาจเห็น

Resources:

• list_resources
• read_resource

Prompts:

• list_prompts
• get_prompt

wrappers เหล่านี้จะปรากฏก็ต่อเมื่อ:

• config ของคุณอนุญาต และ
• session ของ MCP server นั้นรองรับความสามารถเหล่านั้นจริง

ดังนั้น Hermes จะไม่แสร้งทำเป็นว่า server มี resources/prompts หากมันไม่มีจริง

รูปแบบการใช้งานทั่วไป (Common patterns)

Pattern 1: local project assistant

ใช้ MCP สำหรับ filesystem หรือ git server ในระดับ repo เมื่อคุณต้องการให้ Hermes ใช้เหตุผลกับ workspace ที่ถูกจำกัดขอบเขต

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

prompts ที่ดี:

Review the project structure and identify where configuration lives.

Check the local git state and summarize what changed recently.

Pattern 2: GitHub triage assistant

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

prompts ที่ดี:

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.

Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

Pattern 3: internal API assistant

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

prompts ที่ดี:

Look up customer ACME Corp and summarize recent invoice activity.

นี่คือประเภทที่การใช้ strict whitelist ดีกว่า exclude list มาก

Pattern 4: documentation / knowledge servers

MCP servers บางตัวเปิดเผย prompts หรือ resources ที่เป็นเหมือน asset ความรู้ที่ใช้ร่วมกันมากกว่าการกระทำโดยตรง

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: true
      resources: true

prompts ที่ดี:

List available MCP resources from the docs server, then read the onboarding guide and summarize it.

List prompts exposed by the docs server and tell me which ones would help with incident response.

Tutorial: end-to-end setup with filtering

นี่คือลำดับการใช้งานจริง

Phase 1: เพิ่ม GitHub MCP ด้วย whitelist ที่จำกัด

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]
      prompts: false
      resources: false

เริ่ม Hermes และถาม:

Search the codebase for references to MCP and summarize the main integration points.

Phase 2: ขยายเมื่อจำเป็นเท่านั้น

หากภายหลังคุณต้องการการอัปเดต issue ด้วย:

tools:
  include: [list_issues, create_issue, update_issue, search_code]

จากนั้นโหลดใหม่:

/reload-mcp

Phase 3: เพิ่ม server ตัวที่สองด้วยนโยบายที่แตกต่างกัน

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

ตอนนี้ Hermes สามารถรวมทั้งสองอย่างได้:

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

นั่นคือจุดที่ MCP มีพลัง: เวิร์กโฟลว์หลายระบบโดยไม่ต้องเปลี่ยนแปลง core ของ Hermes

คำแนะนำสำหรับการใช้งานที่ปลอดภัย

ควรใช้ allowlists สำหรับระบบที่อันตราย

สำหรับสิ่งใดก็ตามที่เกี่ยวข้องกับการเงิน, การติดต่อลูกค้า, หรือการทำลายข้อมูล:

• ใช้ tools.include
• เริ่มต้นด้วยชุดที่เล็กที่สุดเท่าที่จะเป็นไปได้

ปิด utility ที่ไม่ได้ใช้

หากคุณไม่ต้องการให้ model เข้าถึง resources/prompts ที่ server ให้มา, ให้ปิดมัน:

tools:
  resources: false
  prompts: false

จำกัดขอบเขตของ server

ตัวอย่าง:

• filesystem server ที่ root อยู่ที่ไดเรกทอรีโปรเจกต์เดียว ไม่ใช่ home directory ทั้งหมด
• git server ที่ชี้ไปที่ repo เดียว
• internal API server ที่เปิดเผย tool ในลักษณะอ่านข้อมูลเป็นหลัก (read-heavy) โดยค่าเริ่มต้น

โหลดใหม่หลังการเปลี่ยนแปลง config

/reload-mcp

ทำสิ่งนี้หลังจากเปลี่ยนแปลง:

• include/exclude lists
• enabled flags
• resources/prompts toggles
• auth headers / env

การแก้ไขปัญหาตามอาการ (Troubleshooting by symptom)

"server เชื่อมต่อได้ แต่ tools ที่คาดหวังหายไป"

สาเหตุที่เป็นไปได้:

• ถูกกรองด้วย tools.include
• ถูกยกเว้นด้วย tools.exclude
• utility wrappers ถูกปิดด้วย resources: false หรือ prompts: false
• server ไม่ได้รองรับ resources/prompts จริงๆ

"server ถูกตั้งค่าแล้ว แต่ไม่มีอะไรโหลดเลย"

ตรวจสอบ:

• enabled: false ไม่ได้ถูกทิ้งไว้ใน config
• command/runtime มีอยู่จริง (npx, uvx, ฯลฯ)
• HTTP endpoint สามารถเข้าถึงได้
• auth env หรือ headers ถูกต้อง

"ทำไมฉันถึงเห็น tools น้อยกว่าที่ MCP server ประกาศ?"

เนื่องจาก Hermes ให้ความเคารพต่อ nโยบายและการลงทะเบียนที่คำนึงถึงความสามารถ (capability-aware registration) ของคุณในแต่ละ server นั่นเป็นสิ่งที่คาดหวังได้ และโดยปกติแล้วเป็นสิ่งที่พึงประสงค์

"ฉันจะลบ MCP server โดยไม่ลบ config ได้อย่างไร?"

ใช้:

enabled: false

สิ่งนี้จะเก็บ config ไว้ แต่ป้องกันการเชื่อมต่อและการลงทะเบียน

การตั้งค่า MCP เริ่มต้นที่แนะนำ

server แรกที่ดีสำหรับผู้ใช้ส่วนใหญ่:

• filesystem
• git
• GitHub
• fetch / documentation MCP servers
• internal API ที่แคบและเฉพาะเจาะจง

server แรกที่ไม่แนะนำ:

• ระบบธุรกิจขนาดใหญ่ที่มีการกระทำที่ทำลายข้อมูลจำนวนมากและไม่มีการกรอง
• สิ่งใดๆ ที่คุณไม่เข้าใจดีพอที่จะจำกัดขอบเขตได้

เอกสารที่เกี่ยวข้อง (Related docs)

• MCP (Model Context Protocol)
• FAQ
• Slash Commands