📄 reference/faq.md

sidebar_position: 3 title: "FAQ & Troubleshooting" description: "Frequently asked questions and solutions to common issues with Hermes Agent"

FAQ & Troubleshooting

คำตอบและวิธีแก้ไขปัญหาสำหรับคำถามและปัญหาที่พบบ่อยที่สุด

Frequently Asked Questions

What LLM providers work with Hermes?

Hermes Agent สามารถทำงานร่วมกับ API ที่เข้ากันได้กับ OpenAI ทุกตัว ผู้ให้บริการที่รองรับ ได้แก่:

• OpenRouter - เข้าถึงโมเดลหลายร้อยตัวผ่าน API key เดียว (แนะนำสำหรับความยืดหยุ่น)
• Nous Portal - endpoint inference ของ Nous Research เอง
• OpenAI - GPT-4o, o1, o3, และอื่น ๆ
• Anthropic - โมเดล Claude (ผ่าน OpenRouter หรือ proxy ที่เข้ากันได้)
• Google - โมเดล Gemini (ผ่าน OpenRouter หรือ proxy ที่เข้ากันได้)
• z.ai / ZhipuAI - โมเดล GLM
• Kimi / Moonshot AI - โมเดล Kimi
• MiniMax - endpoints ทั่วโลกและในจีน
• Local models - ผ่าน Ollama, vLLM, llama.cpp, SGLang, หรือเซิร์ฟเวอร์ที่เข้ากันได้กับ OpenAI ทุกตัว

ตั้งค่า provider ของคุณด้วยคำสั่ง hermes model หรือโดยการแก้ไขไฟล์ ~/.hermes/.env ดูเอกสารอ้างอิง Environment Variables สำหรับคีย์ provider ทั้งหมด

Does it work on Windows?

ไม่รองรับโดยตรง (Not natively). Hermes Agent ต้องการสภาพแวดล้อมแบบ Unix-like บน Windows ให้ติดตั้ง WSL2 และรัน Hermes จากภายใน WSL2 คำสั่งติดตั้งมาตรฐานทำงานได้อย่างสมบูรณ์ใน WSL2:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Does it work on Android / Termux?

ได้ - Hermes มีวิธีการติดตั้ง Termux ที่ผ่านการทดสอบสำหรับโทรศัพท์ Android แล้ว

ติดตั้งอย่างรวดเร็ว:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

สำหรับขั้นตอนการติดตั้งด้วยตนเองที่ละเอียดทั้งหมด, extras ที่รองรับ, และข้อจำกัดปัจจุบัน ดูที่ Termux guide

ข้อควรระวังที่สำคัญ: extra .[all] ทั้งหมดยังไม่พร้อมใช้งานบน Android เนื่องจาก extra voice ขึ้นอยู่กับ faster-whisper -> ctranslate2 และ ctranslate2 ไม่ได้เผยแพร่ Android wheels ให้ใช้ extra .[termux] ที่ผ่านการทดสอบแทน

Is my data sent anywhere?

การเรียก API จะส่งข้อมูลไปยัง LLM provider ที่คุณกำหนดค่าเท่านั้น (เช่น OpenRouter, อินสแตนซ์ Ollama ท้องถิ่นของคุณ) Hermes Agent ไม่มีการเก็บ telemetry, usage data, หรือ analytics การสนทนา, memory, และ skills ของคุณจะถูกจัดเก็บไว้ในเครื่องที่ ~/.hermes/

Can I use it offline / with local models?

ได้ รัน hermes model, เลือก Custom endpoint, และป้อน URL ของเซิร์ฟเวอร์ของคุณ:

hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 32768   ← set this to match your server's actual context window

หรือกำหนดค่าโดยตรงใน config.yaml:

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

Hermes จะเก็บ endpoint, provider, และ base URL ไว้ใน config.yaml เพื่อให้คงอยู่แม้จะรีสตาร์ท หากเซิร์ฟเวอร์ท้องถิ่นของคุณมีโมเดลโหลดอยู่เพียงตัวเดียว /model custom จะตรวจจับอัตโนมัติ คุณยังสามารถตั้งค่า provider: custom ใน config.yaml ได้ - ซึ่งเป็น provider ระดับแรก ไม่ใช่ชื่อแทนของอย่างอื่น

สิ่งนี้ใช้ได้กับ Ollama, vLLM, llama.cpp server, SGLang, LocalAI, และอื่น ๆ ดู Configuration guide สำหรับรายละเอียด

:::tip Ollama users หากคุณตั้งค่า num_ctx แบบกำหนดเองใน Ollama (เช่น ollama run --num_ctx 16384), โปรดตรวจสอบให้แน่ใจว่าคุณได้ตั้งค่า context length ที่ตรงกันใน Hermes - /api/show ของ Ollama จะรายงาน ค่าสูงสุด ของ context ของโมเดล ไม่ใช่ num_ctx ที่คุณกำหนดค่าไว้ :::

:::tip Timeouts with local models Hermes จะตรวจจับ local endpoints อัตโนมัติและผ่อนคลาย timeouts สำหรับ streaming (read timeout ถูกเพิ่มจาก 120s เป็น 1800s, ปิดการตรวจจับ stale stream) หากคุณยังคงพบ timeouts ในบริบทขนาดใหญ่มาก ให้ตั้งค่า HERMES_STREAM_READ_TIMEOUT=1800 ในไฟล์ .env ของคุณ ดู Local LLM guide สำหรับรายละเอียด :::

How much does it cost?

ตัว Hermes Agent เอง ฟรีและเป็น open-source (MIT license) คุณจ่ายเฉพาะค่า usage ของ LLM API จาก provider ที่คุณเลือก โมเดลท้องถิ่นฟรีสำหรับการรันโดยสมบูรณ์

Can multiple people use one instance?

ได้ messaging gateway อนุญาตให้ผู้ใช้หลายคนโต้ตอบกับอินสแตนซ์ Hermes Agent เดียวกันผ่าน Telegram, Discord, Slack, WhatsApp, หรือ Home Assistant การเข้าถึงถูกควบคุมผ่าน allowlists (user IDs เฉพาะ) และ DM pairing (ผู้ใช้คนแรกที่ส่งข้อความจะอ้างสิทธิ์การเข้าถึง)

What's the difference between memory and skills?

• Memory จัดเก็บ ข้อเท็จจริง (facts) - สิ่งที่ agent รู้เกี่ยวกับคุณ, โปรเจกต์ของคุณ, และความชอบ ความทรงจำจะถูกดึงมาโดยอัตโนมัติตามความเกี่ยวข้อง
• Skills จัดเก็บ ขั้นตอน (procedures) - คำแนะนำแบบทีละขั้นตอนเกี่ยวกับวิธีการทำสิ่งต่าง ๆ Skills จะถูกเรียกใช้เมื่อ agent พบงานที่คล้ายกัน

ทั้งสองอย่างจะคงอยู่ข้าม session ดู Memory และ Skills สำหรับรายละเอียด

Can I use it in my own Python project?

ได้ นำเข้าคลาส AIAgent และใช้ Hermes ในรูปแบบ programmatic:

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")

ดู Python Library guide สำหรับการใช้งาน API เต็มรูปแบบ

Troubleshooting

Installation Issues

hermes: command not found after installation

สาเหตุ: shell ของคุณไม่ได้โหลด PATH ที่อัปเดตแล้ว

วิธีแก้ไข:

# โหลดโปรไฟล์ shell ของคุณใหม่
source ~/.bashrc    # สำหรับ bash
source ~/.zshrc     # สำหรับ zsh

# หรือเริ่มเซสชัน terminal ใหม่

หากยังไม่ทำงาน ให้ตรวจสอบตำแหน่งการติดตั้ง:

which hermes
ls ~/.local/bin/hermes

:::tip ตัวติดตั้งจะเพิ่ม ~/.local/bin เข้าไปใน PATH ของคุณ หากคุณใช้การตั้งค่า shell ที่ไม่เป็นมาตรฐาน ให้เพิ่ม export PATH="$HOME/.local/bin:$PATH" ด้วยตนเอง :::

Python version too old

สาเหตุ: Hermes ต้องการ Python 3.11 หรือใหม่กว่า

วิธีแก้ไข:

python3 --version   # ตรวจสอบเวอร์ชันปัจจุบัน

# ติดตั้ง Python เวอร์ชันใหม่กว่า
sudo apt install python3.12   # สำหรับ Ubuntu/Debian
brew install [email protected]      # สำหรับ macOS

ตัวติดตั้งจะจัดการเรื่องนี้โดยอัตโนมัติ - หากคุณเห็นข้อผิดพลาดนี้ระหว่างการติดตั้งด้วยตนเอง ให้ทำการอัปเกรด Python ก่อน

Terminal commands say node: command not found (or nvm, pyenv, asdf, …)

สาเหตุ: Hermes สร้าง snapshot ของสภาพแวดล้อมต่อเซสชันโดยการรัน bash -l เพียงครั้งเดียวเมื่อเริ่มต้นใช้งาน bash login shell จะอ่าน /etc/profile, ~/.bash_profile, และ ~/.profile แต่ จะไม่ source ~/.bashrc - ดังนั้นเครื่องมือที่ติดตั้งตัวเองที่นั่น (nvm, asdf, pyenv, cargo, การ export PATH แบบกำหนดเอง) จะมองไม่เห็นใน snapshot นี้ สิ่งนี้มักเกิดขึ้นเมื่อ Hermes ทำงานภายใต้ systemd หรือใน shell ที่เรียบง่ายที่ไม่มีการโหลดโปรไฟล์ shell แบบ interactive ล่วงหน้า

วิธีแก้ไข: โดยค่าเริ่มต้น Hermes จะ auto-source ~/.bashrc หากยังไม่เพียงพอ - เช่น คุณเป็นผู้ใช้ zsh ที่ PATH อยู่ใน ~/.zshrc หรือคุณ init nvm จากไฟล์เดี่ยว - ให้ระบุไฟล์เพิ่มเติมที่ต้อง source ใน ~/.hermes/config.yaml:

terminal:
  shell_init_files:
    - ~/.zshrc                     # สำหรับผู้ใช้ zsh: ดึง PATH ที่จัดการโดย zsh เข้าไปใน bash snapshot
    - ~/.nvm/nvm.sh                # nvm init โดยตรง (ใช้ได้ไม่ว่า shell จะเป็นอะไร)
    - /etc/profile.d/cargo.sh      # ไฟล์ rc ระดับระบบ
  # เมื่อตั้งค่ารายการนี้ การ auto-source ~/.bashrc เริ่มต้นจะไม่ถูกเพิ่ม -
  # ให้รวมมันอย่างชัดเจนหากคุณต้องการทั้งสอง:
  #   - ~/.bashrc
  #   - ~/.zshrc

ไฟล์ที่ขาดหายไปจะถูกข้ามไปอย่างเงียบ ๆ การ source เกิดขึ้นใน bash ดังนั้นไฟล์ที่ต้องพึ่งพาสังเกตการณ์เฉพาะ zsh อาจเกิดข้อผิดพลาด - หากเป็นข้อกังวล ให้ source เฉพาะส่วนที่ตั้งค่า PATH (เช่น nvm.sh ของ nvm โดยตรง) แทนที่จะเป็นไฟล์ rc ทั้งหมด

ในการปิดการทำงานของ auto-source behaviour (strict login-shell semantics เท่านั้น):

terminal:
  auto_source_bashrc: false

uv: command not found

สาเหตุ: ตัวจัดการแพ็คเกจ uv ไม่ได้ติดตั้งหรือไม่ได้อยู่ใน PATH

วิธีแก้ไข:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Permission denied errors during install

สาเหตุ: สิทธิ์ไม่เพียงพอในการเขียนไปยังไดเรกทอรีติดตั้ง

วิธีแก้ไข:

# ห้ามใช้ sudo กับตัวติดตั้ง - เพราะมันติดตั้งที่ ~/.local/bin
# หากคุณเคยติดตั้งด้วย sudo มาก่อน ให้ล้างข้อมูล:
sudo rm /usr/local/bin/hermes
# จากนั้นรันตัวติดตั้งมาตรฐานอีกครั้ง
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Provider & Model Issues

/model only shows one provider / can't switch providers

สาเหตุ: /model (ภายในเซสชันแชท) สามารถสลับระหว่าง provider ที่คุณ กำหนดค่าไว้แล้ว เท่านั้น หากคุณตั้งค่า OpenRouter ไว้เท่านั้น /model ก็จะแสดงแค่นั้น

วิธีแก้ไข: ออกจากเซสชันของคุณและใช้ hermes model จาก terminal เพื่อเพิ่ม provider ใหม่:

# ออกจากเซสชันแชท Hermes ก่อน (Ctrl+C หรือ /quit)

# รันตัวช่วยตั้งค่า provider เต็มรูปแบบ
hermes model

# สิ่งนี้ช่วยให้คุณ: เพิ่ม provider, รัน OAuth, ป้อน API keys, กำหนดค่า endpoints

หลังจากเพิ่ม provider ใหม่ผ่าน hermes model ให้เริ่มเซสชันแชทใหม่ - /model จะแสดง provider ที่คุณกำหนดค่าไว้ทั้งหมด

:::tip Quick reference

API key not working

สาเหตุ: Key ขาดหาย, หมดอายุ, ตั้งค่าไม่ถูกต้อง, หรือสำหรับ provider ผิด

วิธีแก้ไข:

# ตรวจสอบการกำหนดค่าของคุณ
hermes config show

# กำหนดค่า provider ของคุณใหม่
hermes model

# หรือตั้งค่าโดยตรง
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

:::warning โปรดตรวจสอบให้แน่ใจว่า key ตรงกับ provider Key ของ OpenAI จะใช้ไม่ได้กับ OpenRouter และในทางกลับกัน ตรวจสอบ ~/.hermes/.env สำหรับรายการที่ขัดแย้งกัน :::

Model not available / model not found

สาเหตุ: ตัวระบุโมเดลไม่ถูกต้อง หรือไม่มีให้ใช้ใน provider ของคุณ

วิธีแก้ไข:

# แสดงโมเดลที่พร้อมใช้งานสำหรับ provider ของคุณ
hermes model

# ตั้งค่าโมเดลที่ถูกต้อง
hermes config set HERMES_MODEL anthropic/claude-opus-4.7

# หรือระบุต่อเซสชัน
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

Rate limiting (429 errors)

สาเหตุ: คุณใช้เกินขีดจำกัด rate limit ของ provider

วิธีแก้ไข: รอสักครู่แล้วลองอีกครั้ง สำหรับการใช้งานอย่างต่อเนื่อง ให้พิจารณา:

• อัปเกรดแผน provider ของคุณ
• สลับไปใช้โมเดลหรือ provider อื่น
• ใช้ hermes chat --provider <alternative> เพื่อส่งไปยัง backend อื่น

Context length exceeded

สาเหตุ: การสนทนายาวเกินไปสำหรับ context window ของโมเดล หรือ Hermes ตรวจพบ context length ที่ไม่ถูกต้องสำหรับโมเดลของคุณ

วิธีแก้ไข:

# บีบอัดเซสชันปัจจุบัน
/compress

# หรือเริ่มเซสชันใหม่
hermes chat

# ใช้โมเดลที่มี context window ใหญ่กว่า
hermes chat --model openrouter/google/gemini-3-flash-preview

หากสิ่งนี้เกิดขึ้นในการสนทนาที่ยาวครั้งแรก Hermes อาจมี context length ที่ไม่ถูกต้องสำหรับโมเดลของคุณ ตรวจสอบสิ่งที่มันตรวจพบ:

ดูที่บรรทัดเริ่มต้นของ CLI - มันจะแสดง context length ที่ตรวจพบ (เช่น 📊 Context limit: 128000 tokens) คุณยังสามารถตรวจสอบด้วย /usage ระหว่างเซสชันได้

ในการแก้ไขการตรวจจับ context ให้ตั้งค่าอย่างชัดเจน:

# ใน ~/.hermes/config.yaml
model:
  default: your-model-name
  context_length: 131072  # context window จริงของโมเดลของคุณ

หรือสำหรับ custom endpoints ให้เพิ่มในแต่ละโมเดล:

custom_providers:
  - name: "My Server"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768

ดู Context Length Detection สำหรับวิธีการทำงานของการตรวจจับอัตโนมัติและตัวเลือกการเขียนทับทั้งหมด

Terminal Issues

Command blocked as dangerous

สาเหตุ: Hermes ตรวจพบคำสั่งที่อาจก่อให้เกิดการทำลายล้าง (เช่น rm -rf, DROP TABLE) นี่คือคุณสมบัติด้านความปลอดภัย

วิธีแก้ไข: เมื่อถูกแจ้งเตือน ให้ตรวจสอบคำสั่งและพิมพ์ y เพื่ออนุมัติ คุณยังสามารถ:

• ขอให้ agent ใช้ทางเลือกที่ปลอดภัยกว่า
• ดูรายการรูปแบบอันตรายทั้งหมดใน Security docs

:::tip นี่ทำงานตามที่ตั้งใจ - Hermes จะไม่รันคำสั่งที่ทำลายล้างอย่างเงียบ ๆ การแจ้งเตือนการอนุมัติแสดงให้คุณเห็นว่าอะไรจะถูกดำเนินการอย่างแน่นอน :::

sudo not working via messaging gateway

สาเหตุ: messaging gateway ทำงานโดยไม่มี terminal แบบ interactive ดังนั้น sudo จึงไม่สามารถแจ้งให้ใส่รหัสผ่านได้

วิธีแก้ไข:

• หลีกเลี่ยง sudo ใน messaging - ขอให้ agent หาทางเลือกอื่น
• หากคุณต้องใช้ sudo ให้กำหนดค่า passwordless sudo สำหรับคำสั่งเฉพาะใน /etc/sudoers
• หรือสลับไปใช้ terminal interface สำหรับงานบริหาร: hermes chat

Docker backend not connecting

สาเหตุ: Docker daemon ไม่ได้ทำงาน หรือผู้ใช้ไม่มีสิทธิ์

วิธีแก้ไข:

# ตรวจสอบว่า Docker กำลังทำงานหรือไม่
docker info

# เพิ่มผู้ใช้ของคุณในกลุ่ม docker
sudo usermod -aG docker $USER
newgrp docker

# ตรวจสอบ
docker run hello-world

Messaging Issues

Bot not responding to messages

สาเหตุ: bot ไม่ได้ทำงาน, ไม่ได้รับอนุญาต, หรือผู้ใช้ของคุณไม่ได้อยู่ใน allowlist

วิธีแก้ไข:

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

# เริ่ม gateway
hermes gateway start

# ตรวจสอบ log สำหรับข้อผิดพลาด
cat ~/.hermes/logs/gateway.log | tail -50

Messages not delivering

สาเหตุ: ปัญหาเครือข่าย, bot token หมดอายุ, หรือการกำหนดค่า webhook ของแพลตฟอร์มผิดพลาด

วิธีแก้ไข:

• ตรวจสอบว่า bot token ของคุณถูกต้องด้วย hermes gateway setup
• ตรวจสอบ log gateway: cat ~/.hermes/logs/gateway.log | tail -50
• สำหรับแพลตฟอร์มที่ใช้ webhook (Slack, WhatsApp), ตรวจสอบให้แน่ใจว่าเซิร์ฟเวอร์ของคุณเข้าถึงได้จากสาธารณะ

Allowlist confusion - who can talk to the bot?

สาเหตุ: โหมดการอนุญาตกำหนดว่าใครสามารถเข้าถึงได้

วิธีแก้ไข:

กำหนดค่าใน ~/.hermes/config.yaml ภายใต้การตั้งค่า gateway ของคุณ ดู Messaging docs

Gateway won't start

สาเหตุ: Dependencies ขาดหาย, port conflicts, หรือ token กำหนดค่าผิดพลาด

วิธีแก้ไข:

# ติดตั้ง dependencies ของ messaging
pip install "hermes-agent[telegram]"   # หรือ [discord], [slack], [whatsapp]

# ตรวจสอบ port conflicts
lsof -i :8080

# ตรวจสอบการกำหนดค่า
hermes config show

WSL: Gateway keeps disconnecting or hermes gateway start fails

สาเหตุ: การรองรับ systemd ของ WSL ไม่น่าเชื่อถือ การติดตั้ง WSL2 หลายครั้งไม่มีการเปิดใช้งาน systemd และแม้ว่าจะเปิดใช้งานแล้ว บริการก็อาจไม่รอดจากการรีสตาร์ท WSL หรือการปิดเครื่อง Windows

วิธีแก้ไข: ใช้โหมด foreground แทน systemd service:

# ตัวเลือก 1: Direct foreground (ง่ายที่สุด)
hermes gateway run

# ตัวเลือก 2: Persistent via tmux (รอดจากการปิด terminal)
tmux new -s hermes 'hermes gateway run'
# Reattach later: tmux attach -t hermes

# ตัวเลือก 3: Background via nohup
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

หากคุณต้องการลองใช้ systemd อย่างไรก็ตาม ให้แน่ใจว่ามันถูกเปิดใช้งาน:

1. เปิด /etc/wsl.conf (สร้างถ้ายังไม่มี)
2. เพิ่ม:

   [boot]
   systemd=true

3. จาก PowerShell: wsl --shutdown
4. เปิด terminal WSL ของคุณใหม่
5. ตรวจสอบ: systemctl is-system-running ควรแสดง "running" หรือ "degraded"

:::tip Auto-start on Windows boot สำหรับการเริ่มทำงานอัตโนมัติที่เชื่อถือได้ ให้ใช้ Windows Task Scheduler เพื่อเปิด WSL + gateway เมื่อเข้าสู่ระบบ:

1. สร้าง task ที่รัน wsl -d Ubuntu -- bash -lc 'hermes gateway run'
2. ตั้งค่าให้ทริกเกอร์เมื่อผู้ใช้เข้าสู่ระบบ :::

macOS: Node.js / ffmpeg / other tools not found by gateway

สาเหตุ: บริการ launchd สืบทอด PATH ที่เรียบง่าย ( /usr/bin:/bin:/usr/sbin:/sbin) ซึ่งไม่รวม Homebrew, nvm, cargo, หรือไดเรกทอรีเครื่องมือที่ติดตั้งโดยผู้ใช้ สิ่งนี้มักทำให้ WhatsApp bridge (node not found) หรือ voice transcription (ffmpeg not found) ล้มเหลว

วิธีแก้ไข: gateway จะจับภาพ PATH ของ shell ของคุณเมื่อคุณรัน hermes gateway install หากคุณติดตั้งเครื่องมือหลังจากตั้งค่า gateway ให้รัน install ใหม่เพื่อจับภาพ PATH ที่อัปเดต:

hermes gateway install    # Re-snapshots your current PATH
hermes gateway start      # ตรวจจับ plist ที่อัปเดตและโหลดใหม่

คุณสามารถตรวจสอบได้ว่า plist มี PATH ที่ถูกต้องหรือไม่:

/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.hermes.gateway.plist

Performance Issues

Slow responses

สาเหตุ: โมเดลขนาดใหญ่, server API ที่อยู่ไกล, หรือ system prompt ที่มีเครื่องมือจำนวนมาก

วิธีแก้ไข:

• ลองใช้โมเดลที่เร็วกว่า/เล็กกว่า: hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
• ลดชุดเครื่องมือที่ใช้งาน: hermes chat -t "terminal"
• ตรวจสอบ latency ของเครือข่ายของคุณไปยัง provider
• สำหรับโมเดลท้องถิ่น ให้แน่ใจว่าคุณมี VRAM ของ GPU เพียงพอ

High token usage

สาเหตุ: การสนทนายาว, system prompt ที่เยิ่นเย้อ, หรือการเรียกใช้เครื่องมือจำนวนมากที่สะสม context

วิธีแก้ไข:

# บีบอัดการสนทนาเพื่อลด token
/compress

# ตรวจสอบการใช้ token ของเซสชัน
/usage

:::tip ใช้ /compress เป็นประจำระหว่างเซสชันที่ยาวนาน มันจะสรุปประวัติการสนทนาและลดการใช้ token อย่างมาก ในขณะที่ยังคงรักษา context ไว้ :::

Session getting too long

สาเหตุ: การสนทนาที่ขยายออกไปสะสมข้อความและผลลัพธ์เครื่องมือ เข้าใกล้ขีดจำกัด context

วิธีแก้ไข:

# บีบอัดเซสชันปัจจุบัน (คง context หลักไว้)
/compress

# เริ่มเซสชันใหม่พร้อมการอ้างอิงถึงเซสชันเก่า
hermes chat

# กลับมาใช้เซสชันเฉพาะในภายหลังหากจำเป็น
hermes chat --continue

MCP Issues

MCP server not connecting

สาเหตุ: ไม่พบ binary ของเซิร์ฟเวอร์, path คำสั่งผิด, หรือ runtime ขาดหาย

วิธีแก้ไข:

# ตรวจสอบให้แน่ใจว่าติดตั้ง dependencies ของ MCP แล้ว (รวมอยู่ใน standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

# สำหรับเซิร์ฟเวอร์ที่ใช้ npm, ตรวจสอบว่า Node.js พร้อมใช้งาน
node --version
npx --version

# ทดสอบเซิร์ฟเวอร์ด้วยตนเอง
npx -y @modelcontextprotocol/server-filesystem /tmp

ตรวจสอบการกำหนดค่า MCP ของ ~/.hermes/config.yaml:

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

Tools not showing up from MCP server

สาเหตุ: เซิร์ฟเวอร์เริ่มทำงานแล้วแต่การค้นพบเครื่องมือล้มเหลว, เครื่องมือถูกกรองโดย config, หรือเซิร์ฟเวอร์ไม่รองรับความสามารถ MCP ที่คุณคาดหวัง

วิธีแก้ไข:

• ตรวจสอบ log gateway/agent สำหรับข้อผิดพลาดการเชื่อมต่อ MCP
• ตรวจสอบให้แน่ใจว่าเซิร์ฟเวอร์ตอบสนองต่อ RPC method tools/list
• ตรวจสอบการตั้งค่า tools.include, tools.exclude, tools.resources, tools.prompts, หรือ enabled ใด ๆ ภายใต้เซิร์ฟเวอร์นั้น
• จำไว้ว่าเครื่องมือ utility resource/prompt จะลงทะเบียนก็ต่อเมื่อเซสชันนั้นรองรับความสามารถเหล่านั้นจริง ๆ
• ใช้ /reload-mcp หลังจากเปลี่ยน config

# ตรวจสอบว่า MCP servers ถูกกำหนดค่าไว้หรือไม่
hermes config show | grep -A 12 mcp_servers

# รีสตาร์ท Hermes หรือ reload MCP หลังจากเปลี่ยน config
hermes chat

ดูเพิ่มเติม:

• MCP (Model Context Protocol)
• Use MCP with Hermes
• MCP Config Reference

MCP timeout errors

สาเหตุ: MCP server ใช้เวลานานเกินไปในการตอบสนอง หรือล่มระหว่างการดำเนินการ

วิธีแก้ไข:

• เพิ่ม timeout ใน config ของ MCP server หากรองรับ
• ตรวจสอบว่า process ของ MCP server ยังคงทำงานอยู่หรือไม่
• สำหรับเซิร์ฟเวอร์ MCP แบบ HTTP ระยะไกล ให้ตรวจสอบการเชื่อมต่อเครือข่าย

:::warning หาก MCP server ล่มระหว่างคำขอ Hermes จะรายงาน timeout ให้ตรวจสอบ log ของเซิร์ฟเวอร์เอง (ไม่ใช่แค่ log ของ Hermes) เพื่อวินิจฉัยสาเหตุที่แท้จริง :::

Profiles

Profiles แตกต่างจากการตั้งค่า HERMES_HOME อย่างไร?

Profiles เป็นชั้นการจัดการที่ทำงานอยู่เหนือ HERMES_HOME คุณสามารถตั้งค่า HERMES_HOME=/some/path ด้วยตนเองก่อนทุกคำสั่งได้ แต่ Profiles จะจัดการส่วนประกอบเบื้องหลังทั้งหมดให้คุณ: ทั้งการสร้างโครงสร้างไดเรกทอรี การสร้าง shell aliases (hermes-work) การติดตาม active profile ใน ~/.hermes/active_profile และการซิงค์การอัปเดต skill ข้ามทุก Profile โดยอัตโนมัติ นอกจากนี้ยังรวมการทำงานกับ tab completion ทำให้คุณไม่จำเป็นต้องจำ path ต่างๆ

Profiles สองตัวสามารถใช้ bot token เดียวกันได้หรือไม่?

ไม่ได้ แต่ละแพลตฟอร์มการส่งข้อความ (Telegram, Discord, ฯลฯ) ต้องการสิทธิ์เข้าถึง bot token แบบเฉพาะเจาะจง หาก Profiles สองตัวพยายามใช้ token เดียวกันพร้อมกัน gateway ตัวที่สองจะล้มเหลวในการเชื่อมต่อ ให้สร้าง bot แยกกันสำหรับแต่ละ Profile - สำหรับ Telegram ให้คุยกับ @BotFather เพื่อสร้าง bot เพิ่มเติม

Profiles แชร์หน่วยความจำหรือเซสชันกันหรือไม่?

ไม่ แต่ละ Profile มีที่เก็บหน่วยความจำ (memory store) ฐานข้อมูลเซสชัน และไดเรกทอรี skill เป็นของตัวเอง พวกมันแยกออกจากกันโดยสมบูรณ์ หากคุณต้องการเริ่มต้น Profile ใหม่โดยใช้หน่วยความจำและเซสชันที่มีอยู่ ให้ใช้ hermes profile create newname --clone-all เพื่อคัดลอกทุกอย่างจาก Profile ปัจจุบัน

เกิดอะไรขึ้นเมื่อฉันรัน hermes update?

hermes update จะดึงโค้ดล่าสุดและติดตั้ง dependencies ใหม่ เพียงครั้งเดียว (ไม่ใช่ต่อ Profile) จากนั้นมันจะซิงค์ skill ที่อัปเดตไปยังทุก Profile โดยอัตโนมัติ คุณจำเป็นต้องรัน hermes update เพียงครั้งเดียว - เพราะมันครอบคลุมทุก Profile บนเครื่อง

ฉันสามารถย้าย Profile ไปยังเครื่องอื่นได้หรือไม่?

ได้ ให้ export Profile เป็น archive แบบพกพา แล้ว import บนเครื่องอื่น:

# บนเครื่องต้นทาง
hermes profile export work ./work-backup.tar.gz

# คัดลอกไฟล์ไปยังเครื่องปลายทาง แล้ว:
hermes profile import ./work-backup.tar.gz work

Profile ที่ import เข้ามาจะมี config, memories, sessions, และ skills ทั้งหมดจาก export คุณอาจจำเป็นต้องอัปเดต paths หรือ re-authenticate กับ providers หากเครื่องใหม่มีการตั้งค่าที่แตกต่างกัน

ฉันสามารถรัน Profiles ได้กี่ตัว?

ไม่มีขีดจำกัดที่ตายตัว แต่ละ Profile เป็นเพียงไดเรกทอรีภายใต้ ~/.hermes/profiles/ ขีดจำกัดในทางปฏิบัติขึ้นอยู่กับพื้นที่ดิสก์ของคุณ และจำนวน gateway พร้อมกันที่ระบบของคุณสามารถรองรับได้ (แต่ละ gateway คือ process Python น้ำหนักเบา) การรันหลายสิบ Profiles นั้นไม่มีปัญหา เพราะ Profile ที่ไม่ได้ใช้งานจะใช้ทรัพยากรเป็นศูนย์

Workflows & Patterns

การใช้โมเดลที่แตกต่างกันสำหรับงานที่แตกต่างกัน (multi-model workflows)

สถานการณ์: คุณใช้ GPT-5.4 เป็นโมเดลหลักในชีวิตประจำวัน แต่ Gemini หรือ Grok เขียนเนื้อหาโซเชียลมีเดียได้ดีกว่า การสลับโมเดลด้วยตนเองทุกครั้งนั้นน่าเบื่อ

วิธีแก้ปัญหา: Delegation config Hermes สามารถกำหนดเส้นทาง subagents ไปยังโมเดลที่แตกต่างกันโดยอัตโนมัติ ตั้งค่าสิ่งนี้ใน ~/.hermes/config.yaml:

delegation:
  model: "google/gemini-3-flash-preview"   # subagents ใช้โมเดลนี้
  provider: "openrouter"                    # provider สำหรับ subagents

ตอนนี้เมื่อคุณบอก Hermes ว่า "เขียน Twitter thread เกี่ยวกับ X ให้หน่อย" และมันสร้าง subagent ชื่อ delegate_task subagent นั้นจะทำงานบน Gemini แทนโมเดลหลักของคุณ การสนทนาหลักของคุณจะยังคงอยู่บน GPT-5.4

คุณยังสามารถระบุอย่างชัดเจนใน prompt ของคุณได้: "มอบหมายงานเพื่อเขียนโพสต์โซเชียลมีเดียเกี่ยวกับการเปิดตัวผลิตภัณฑ์ของเรา ใช้ subagent ของคุณสำหรับการเขียนจริง" agent จะใช้ delegate_task ซึ่งจะเลือก delegation config โดยอัตโนมัติ

สำหรับการสลับโมเดลแบบครั้งเดียวโดยไม่มี delegation ให้ใช้ /model ใน CLI:

/model google/gemini-3-flash-preview    # สลับสำหรับเซสชันนี้
# ... เขียนเนื้อหาของคุณ ...
/model openai/gpt-5.4                   # สลับกลับ

ดู Subagent Delegation สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับวิธีการทำงานของ delegation

การรันหลาย agent บน WhatsApp number เดียว (per-chat binding)

สถานการณ์: ใน OpenClaw คุณมีหลาย agent อิสระที่ผูกกับแชท WhatsApp เฉพาะ - ตัวหนึ่งสำหรับกลุ่มรายการช้อปปิ้งของครอบครัว อีกตัวสำหรับแชทส่วนตัวของคุณ Hermes ทำสิ่งนี้ได้หรือไม่?

ข้อจำกัดปัจจุบัน: Profiles ของ Hermes แต่ละตัวต้องใช้ WhatsApp number/session ของตัวเอง คุณไม่สามารถผูกหลาย Profiles เข้ากับแชทที่แตกต่างกันบน WhatsApp number เดียวได้ - เพราะ WhatsApp bridge (Baileys) ใช้เซสชันที่ได้รับการยืนยันเพียงหนึ่งเดียวต่อหมายเลข

วิธีแก้ไข:

1. ใช้ Profile เดียวพร้อมการสลับบุคลิกภาพ (personality switching) สร้างไฟล์ context AGENTS.md ที่แตกต่างกัน หรือใช้คำสั่ง /personality เพื่อเปลี่ยนพฤติกรรมตามแชท Agent จะเห็นว่ามันอยู่ในแชทใดและสามารถปรับตัวได้

2. ใช้ cron jobs สำหรับงานเฉพาะทาง สำหรับตัวติดตามรายการช้อปปิ้ง ให้ตั้งค่า cron job ที่ตรวจสอบแชทเฉพาะและจัดการรายการ - ไม่จำเป็นต้องมี agent แยก

3. ใช้หมายเลขแยกกัน หากคุณต้องการ agent ที่เป็นอิสระอย่างแท้จริง ให้จับคู่แต่ละ Profile กับ WhatsApp number ของตัวเอง หมายเลขเสมือนจากบริการอย่าง Google Voice ใช้ได้สำหรับสิ่งนี้

4. ใช้ Telegram หรือ Discord แทน แพลตฟอร์มเหล่านี้รองรับ per-chat binding ได้เป็นธรรมชาติกว่า - แต่ละกลุ่ม Telegram หรือช่อง Discord จะได้เซสชันของตัวเอง และคุณสามารถรัน bot token หลายตัว (ตัวละ Profile) บนบัญชีเดียวกันได้

ดู Profiles และ WhatsApp setup สำหรับรายละเอียดเพิ่มเติม

การควบคุมสิ่งที่แสดงใน Telegram (การซ่อน logs และ reasoning)

สถานการณ์: คุณเห็น gateway exec logs, Hermes reasoning, และรายละเอียด tool call ใน Telegram แทนที่จะเห็นแค่ผลลัพธ์สุดท้าย

วิธีแก้ปัญหา: การตั้งค่า display.tool_progress ใน config.yaml ควบคุมว่ากิจกรรมของ tool จะแสดงมากน้อยแค่ไหน:

display:
  tool_progress: "off"   # ตัวเลือก: off, new, all, verbose

• off - แสดงเฉพาะคำตอบสุดท้าย ไม่มี tool calls, ไม่มี reasoning, ไม่มี logs
• new - แสดง tool calls ใหม่เมื่อเกิดขึ้น (แบบสั้นๆ)
• all - แสดงกิจกรรม tool ทั้งหมด รวมถึงผลลัพธ์
• verbose - รายละเอียดเต็ม รวมถึง tool arguments และ outputs

สำหรับแพลตฟอร์มการส่งข้อความ โดยทั่วไปแล้ว off หรือ new คือสิ่งที่คุณต้องการ หลังจากแก้ไข config.yaml ให้รีสตาร์ท gateway เพื่อให้การเปลี่ยนแปลงมีผล

คุณยังสามารถสลับสิ่งนี้ได้ต่อเซสชันด้วยคำสั่ง /verbose (หากเปิดใช้งาน):

display:
  tool_progress_command: true   # เปิดใช้งาน /verbose ใน gateway

การจัดการ skills บน Telegram (ข้อจำกัด slash command)

สถานการณ์: Telegram มีข้อจำกัด 100 slash command และ skills ของคุณกำลังเกินขีดจำกัดนั้น คุณต้องการปิดใช้งาน skills ที่คุณไม่ต้องการบน Telegram แต่การตั้งค่า hermes skills config ดูเหมือนจะไม่ทำงาน

วิธีแก้ปัญหา: ใช้ hermes skills config เพื่อปิดใช้งาน skills แยกตามแพลตฟอร์ม สิ่งนี้จะเขียนลงใน config.yaml:

skills:
  disabled: []                    # skills ที่ถูกปิดใช้งานทั่วโลก
  platform_disabled:
    telegram: [skill-a, skill-b]  # ปิดใช้งานเฉพาะบน telegram

หลังจากเปลี่ยนสิ่งนี้ ให้รีสตาร์ท gateway (hermes gateway restart หรือ kill และ relaunch) เมนูคำสั่ง bot ของ Telegram จะสร้างขึ้นใหม่เมื่อเริ่มต้น

:::tip Skills ที่มีคำอธิบายยาวมากจะถูกตัดเหลือ 40 ตัวอักษรในเมนู Telegram เพื่อให้อยู่ในขีดจำกัดขนาด payload หาก skills ไม่ปรากฏ อาจเป็นปัญหาขนาด payload โดยรวมมากกว่าข้อจำกัดจำนวน 100 คำสั่ง - การปิดใช้งาน skills ที่ไม่ได้ใช้จะช่วยได้ทั้งสองอย่าง :::

เซสชัน thread ที่แชร์กัน (ผู้ใช้หลายคน, การสนทนาเดียว)

สถานการณ์: คุณมี thread ใน Telegram หรือ Discord ที่หลายคนกล่าวถึง bot คุณต้องการให้การกล่าวถึงทั้งหมดใน thread นั้นเป็นส่วนหนึ่งของการสนทนาที่แชร์กัน ไม่ใช่เซสชันแยกตามผู้ใช้

พฤติกรรมปัจจุบัน: Hermes สร้างเซสชันโดยใช้ user ID เป็นคีย์ในหลายแพลตฟอร์ม ดังนั้นแต่ละคนจะได้รับบริบทการสนทนาของตัวเอง นี่คือการออกแบบเพื่อความเป็นส่วนตัวและการแยกบริบท

วิธีแก้ไข:

1. ใช้ Slack เซสชันของ Slack จะถูกกำหนดคีย์ตาม thread ไม่ใช่ตามผู้ใช้ ผู้ใช้หลายคนใน thread เดียวกันจะแชร์การสนทนาเดียวกัน - ซึ่งเป็นพฤติกรรมที่คุณกำลังอธิบาย นี่คือรูปแบบที่เหมาะสมที่สุด

2. ใช้ group chat กับผู้ใช้คนเดียว หากมีคนหนึ่งเป็น "operator" ที่รับหน้าที่ส่งต่อคำถาม เซสชันจะยังคงเป็นหนึ่งเดียว คนอื่นสามารถอ่านตามได้

3. ใช้ Discord channel เซสชันของ Discord จะถูกกำหนดคีย์ตาม channel ดังนั้นผู้ใช้ทุกคนในช่องเดียวกันจะแชร์บริบท ใช้ช่องเฉพาะสำหรับการสนทนาที่แชร์

การ Export Hermes ไปยังเครื่องอื่น

สถานการณ์: คุณได้สร้าง skills, cron jobs, และ memories บนเครื่องหนึ่ง และต้องการย้ายทุกอย่างไปยัง Linux box ใหม่ที่ทุ่มเทให้งานนี้

วิธีแก้ปัญหา:

1. ติดตั้ง Hermes Agent บนเครื่องใหม่:

   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

2. คัดลอกไดเรกทอรี ~/.hermes/ ทั้งหมดของคุณ ยกเว้น subdirectory hermes-agent (นั่นคือ code repo - การติดตั้งใหม่มีของตัวเอง):

   # บนเครื่องต้นทาง
   rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

   หรือใช้ profile export/import:

   # บนเครื่องต้นทาง
   hermes profile export default ./hermes-backup.tar.gz
   
   # บนเครื่องปลายทาง
   hermes profile import ./hermes-backup.tar.gz default

3. บนเครื่องใหม่ ให้รัน hermes setup เพื่อตรวจสอบว่า API keys และ provider config ทำงานได้หรือไม่ ให้ re-authenticate messaging platforms ใดๆ (โดยเฉพาะ WhatsApp ซึ่งใช้ QR pairing)

ไดเรกทอรี ~/.hermes/ บรรจุทุกอย่าง: config.yaml, .env, SOUL.md, memories/, skills/, state.db (sessions), cron/, และ custom plugins ใดๆ โค้ดเองอยู่ใน ~/.hermes/hermes-agent/ และถูกติดตั้งใหม่

Permission denied เมื่อ reload shell หลังติดตั้ง

สถานการณ์: หลังจากรัน Hermes installer, source ~/.zshrc ให้ข้อผิดพลาด permission denied

สาเหตุ: โดยปกติสิ่งนี้เกิดขึ้นเมื่อ ~/.zshrc (หรือ ~/.bashrc) มีสิทธิ์ไฟล์ที่ไม่ถูกต้อง หรือเมื่อ installer ไม่สามารถเขียนลงไปได้อย่างสะอาด มันไม่ใช่ปัญหาเฉพาะของ Hermes - แต่มันเป็นปัญหา permission ของ shell config

วิธีแก้ปัญหา:

# ตรวจสอบสิทธิ์
ls -la ~/.zshrc

# แก้ไขหากจำเป็น (ควรเป็น -rw-r--r-- หรือ 644)
chmod 644 ~/.zshrc

# จากนั้น reload
source ~/.zshrc

# หรือเปิดหน้าต่าง terminal ใหม่ - มันจะรับ PATH changes โดยอัตโนมัติ

หาก installer เพิ่มบรรทัด PATH แต่สิทธิ์ผิด คุณสามารถเพิ่มมันด้วยตนเอง:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Error 400 ในการรัน agent ครั้งแรก

สถานการณ์: การตั้งค่าเสร็จสมบูรณ์ดี แต่การลองแชทครั้งแรกล้มเหลวด้วย HTTP 400

สาเหตุ: โดยปกติคือ model name mismatch - model ที่กำหนดค่าไว้ไม่มีอยู่บน provider ของคุณ หรือ API key ไม่มีสิทธิ์เข้าถึงมัน

วิธีแก้ปัญหา:

# ตรวจสอบว่า model และ provider ใดถูกกำหนดค่าไว้
hermes config show | head -20

# รัน model selection ใหม่
hermes model

# หรือทดสอบด้วย model ที่ทราบว่าใช้งานได้
hermes chat -q "hello" --model anthropic/claude-opus-4.7

หากใช้ OpenRouter ให้แน่ใจว่า API key ของคุณมีเครดิต 400 จาก OpenRouter มักหมายความว่า model นั้นต้องใช้แผนแบบเสียเงิน หรือ model ID มีการพิมพ์ผิด

ยังติดปัญหาอยู่ใช่ไหม?

หากปัญหาของคุณไม่ได้ถูกกล่าวถึงที่นี่:

1. ค้นหา issue ที่มีอยู่: GitHub Issues
2. สอบถามชุมชน: Nous Research Discord
3. รายงาน bug: รวม OS, Python version (python3 --version), Hermes version (hermes --version), และข้อความ error ทั้งหมด

📄 reference/mcp-config-reference.md

sidebar_position: 8 title: "MCP Config Reference" description: "Reference for Hermes Agent MCP configuration keys, filtering semantics, and utility-tool policy"

MCP Config Reference

หน้านี้เป็นเอกสารอ้างอิงฉบับย่อที่ใช้คู่กับเอกสาร MCP หลัก

หากต้องการคำแนะนำเชิงแนวคิด โปรดดูที่:

• MCP (Model Context Protocol)
• Use MCP with Hermes

Root config shape

mcp_servers:
  <server_name>:
    command: "..."      # stdio servers
    args: []
    env: {}

    # OR
    url: "..."          # HTTP servers
    headers: {}

    enabled: true
    timeout: 120
    connect_timeout: 60
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

Server keys

tools policy keys

Filtering semantics

include

หากมีการตั้งค่า include จะลงทะเบียนเฉพาะ MCP tools แบบ native ของเซิร์ฟเวอร์เท่านั้น

tools:
  include: [create_issue, list_issues]

exclude

หากมีการตั้งค่า exclude และไม่มีการตั้งค่า include จะลงทะเบียน MCP tools แบบ native ทั้งหมด ยกเว้นชื่อที่ระบุ

tools:
  exclude: [delete_customer]

Precedence

หากมีการตั้งค่าทั้งสองอย่าง include จะมีลำดับความสำคัญสูงกว่า

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

ผลลัพธ์:

• create_issue ยังคงได้รับอนุญาต
• delete_issue ถูกละเลยเนื่องจาก include มีลำดับความสำคัญสูงกว่า

Utility-tool policy

Hermes อาจลงทะเบียน utility wrappers เหล่านี้ต่อ MCP server:

Resources:

• list_resources
• read_resource

Prompts:

• list_prompts
• get_prompt

Disable resources

tools:
  resources: false

Disable prompts

tools:
  prompts: false

Capability-aware registration

แม้ว่า resources: true หรือ prompts: true แต่ Hermes จะลงทะเบียน utility tools เหล่านั้นก็ต่อเมื่อ MCP session เปิดเผย capability ที่เกี่ยวข้องจริงเท่านั้น

ดังนั้นกรณีนี้จึงเป็นปกติ:

• คุณเปิดใช้งาน prompts
• แต่ไม่มี utility prompt ใดปรากฏ
• เนื่องจากเซิร์ฟเวอร์ไม่รองรับ prompts

enabled: false

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

พฤติกรรม:

• ไม่มีการพยายามเชื่อมต่อ
• ไม่มีการค้นพบ (discovery)
• ไม่มีการลงทะเบียน tool
• config ยังคงอยู่เพื่อนำกลับมาใช้ใหม่ในภายหลัง

Empty result behavior

หากการกรองลบ tools แบบ native ของเซิร์ฟเวอร์ออกทั้งหมด และไม่มี utility tools ใดถูกลงทะเบียน Hermes จะไม่สร้าง MCP runtime toolset ว่างเปล่าสำหรับเซิร์ฟเวอร์นั้น

Example configs

Safe GitHub allowlist

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]
      resources: false
      prompts: false

Stripe blacklist

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

Resource-only docs server

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      include: []
      resources: true
      prompts: false

Reloading config

หลังจากเปลี่ยน MCP config ให้โหลดเซิร์ฟเวอร์ใหม่ด้วยคำสั่ง:

/reload-mcp

Tool naming

MCP tools แบบ native ของเซิร์ฟเวอร์จะกลายเป็น:

mcp_<server>_<tool>

ตัวอย่าง:

• mcp_github_create_issue
• mcp_filesystem_read_file
• mcp_my_api_query_data

Utility tools จะตามรูปแบบ prefix เดียวกัน:

• mcp_<server>_list_resources
• mcp_<server>_read_resource
• mcp_<server>_list_prompts
• mcp_<server>_get_prompt

Name sanitization

เครื่องหมายยัติภังค์ (-) และจุด (.) ในทั้งชื่อเซิร์ฟเวอร์และชื่อ tool จะถูกแทนที่ด้วยขีดล่าง (_) ก่อนการลงทะเบียน สิ่งนี้ช่วยให้มั่นใจว่าชื่อ tool เป็น identifier ที่ถูกต้องสำหรับ LLM function-calling APIs

ตัวอย่างเช่น เซิร์ฟเวอร์ชื่อ my-api ที่เปิดเผย tool ชื่อ list-items.v2 จะกลายเป็น:

mcp_my_api_list_items_v2

โปรดจำไว้เมื่อเขียนตัวกรอง include / exclude - ให้ใช้ชื่อ MCP tool ดั้งเดิม (พร้อมเครื่องหมายยัติภังค์/จุด) ไม่ใช่เวอร์ชันที่ถูก sanitize

OAuth 2.1 authentication

สำหรับ HTTP servers ที่ต้องการ OAuth ให้ตั้งค่า auth: oauth ในรายการเซิร์ฟเวอร์:

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

พฤติกรรม:

• Hermes ใช้ flow OAuth 2.1 PKCE ของ MCP SDK (metadata discovery, dynamic client registration, token exchange, และ refresh)
• เมื่อเชื่อมต่อครั้งแรก หน้าต่างเบราว์เซอร์จะเปิดขึ้นเพื่อขอสิทธิ์ (authorization)
• Tokens จะถูกบันทึกไว้ที่ ~/.hermes/mcp-tokens/<server>.json และนำกลับมาใช้ใหม่ข้าม session
• การ refresh token เป็นไปโดยอัตโนมัติ; การขอสิทธิ์ใหม่จะเกิดขึ้นเมื่อการ refresh ล้มเหลวเท่านั้น
• ใช้ได้เฉพาะกับ transport HTTP/StreamableHTTP (เซิร์ฟเวอร์ที่อิงตาม url)

📄 reference/optional-skills-catalog.md

sidebar_position: 9 title: "Optional Skills Catalog" description: "ชุดทักษะเสริมอย่างเป็นทางการที่มาพร้อมกับ hermes-agent - ติดตั้งผ่าน hermes skills install official/<category>/<skill>"

Optional Skills Catalog

ชุดทักษะเสริมจะมาพร้อมกับ hermes-agent ภายใต้ optional-skills/ แต่ จะไม่ทำงานโดยค่าเริ่มต้น คุณต้องติดตั้งอย่างชัดเจน:

hermes skills install official/<category>/<skill>

ตัวอย่างเช่น:

hermes skills install official/blockchain/solana
hermes skills install official/mlops/flash-attention

ทักษะแต่ละตัวด้านล่างนี้จะเชื่อมโยงไปยังหน้าเฉพาะที่มีคำจำกัดความ การตั้งค่า และวิธีการใช้งานอย่างครบถ้วน

ในการถอนการติดตั้ง:

hermes skills uninstall <skill-name>

autonomous-ai-agents

blockchain

communication

creative

devops

dogfood

email

health

mcp

migration

mlops

productivity

research

security

web-development

Contributing Optional Skills

ในการเพิ่ม optional skill ใหม่ไปยัง repository:

1. สร้าง directory ภายใต้ optional-skills/<category>/<skill-name>/
2. เพิ่ม SKILL.md พร้อม frontmatter มาตรฐาน (ชื่อ, คำอธิบาย, เวอร์ชัน, ผู้เขียน)
3. รวมไฟล์สนับสนุนใดๆ ใน subdirectory references/, templates/, หรือ scripts/
4. ส่ง pull request - skill จะปรากฏใน catalog นี้และจะมีหน้าเอกสารของตัวเองเมื่อรวมโค้ดแล้ว