hermes - 💡(How to fix) Fix [i18n] Thai Translation: Guides Part d - use-soul-with-hermes, use-voice-mode-with-hermes, webhook-github-pr-review, work-with-skills [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#15043Fetched 2026-04-25 06:24:46
View on GitHub
Comments
0
Participants
1
Timeline
2
Reactions
0
Author
Participants
Timeline (top)
labeled ×2

Error Message

I keep getting a docker permission error. Help me debug it.

  • "Read the last error again"

Root Cause

จากนั้นดำเนินการแบบ hands-free ต่อไป:

  • "Read the last error again"
  • "Explain the root cause in simpler terms"
  • "Now give me the exact fix"

Code Example

~/.hermes/SOUL.md

---

$HERMES_HOME/SOUL.md

---

You are direct, calm, and technically precise.
Prefer substance over politeness theater.
Push back clearly when an idea is weak.
Keep answers compact unless deeper detail is useful.

---

You are a pragmatic senior engineer.
You care more about correctness and operational reality than sounding impressive.

## Style
- Be direct
- Be concise unless complexity requires depth
- Say when something is a bad idea
- Prefer practical tradeoffs over idealized abstractions

## Avoid
- Sycophancy
- Hype language
- Overexplaining obvious things

---

You are a thoughtful research collaborator.
You are curious, honest about uncertainty, and excited by unusual ideas.

## Style
- Explore possibilities without pretending certainty
- Distinguish speculation from evidence
- Ask clarifying questions when the idea space is underspecified
- Prefer conceptual depth over shallow completeness

---

You are a patient technical teacher.
You care about understanding, not performance.

## Style
- Explain clearly
- Use examples when they help
- Do not assume prior knowledge unless the user signals it
- Build from intuition to details

---

You are a rigorous reviewer.
You are fair, but you do not soften important criticism.

## Style
- Point out weak assumptions directly
- Prioritize correctness over harmony
- Be explicit about risks and tradeoffs
- Prefer blunt clarity to vague diplomacy

---

# Identity
ใครคือ Hermes

# Style
Hermes ควรมีน้ำเสียงอย่างไร

# Avoid
Hermes ไม่ควรทำอะไร

# Defaults
Hermes ควรมีพฤติกรรมอย่างไรเมื่อเกิดความคลุมเครือ

---

nano ~/.hermes/SOUL.md

---

vim ~/.hermes/SOUL.md

---

hermes

---

What tools do you have available?

---

pip install "hermes-agent[voice]"

---

pip install "hermes-agent[messaging]"

---

pip install "hermes-agent[tts-premium]"

---

python -m pip install -U neutts[all]

---

pip install "hermes-agent[all]"

---

brew install portaudio ffmpeg opus
brew install espeak-ng

---

sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng

---

# Cloud STT options (local needs no key)
GROQ_API_KEY=***
VOICE_TOOLS_OPENAI_KEY=***

# Premium TTS (optional)
ELEVENLABS_API_KEY=***

---

python -m pip install -U neutts[all]

---

voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120
  auto_tts: false
  beep_enabled: true
  silence_threshold: 200
  silence_duration: 3.0

stt:
  provider: "local"
  local:
    model: "base"

tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

---

tts:
  provider: "neutts"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

---

hermes

---

/voice on

---

/voice
/voice on
/voice off
/voice tts
/voice status

---

I keep getting a docker permission error. Help me debug it.

---

voice:
  silence_threshold: 250

---

voice:
  silence_duration: 4.0

---

voice:
  record_key: "ctrl+space"

---

hermes gateway

---

/voice on

---

/voice tts

---

/voice join
/voice leave
/voice status

---

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644          # default; change if another service occupies this port
      rate_limit: 30      # max requests per minute per route (not a global cap)

      routes:
        github-pr-review:
          secret: "your-webhook-secret-here"   # must match the GitHub webhook secret exactly
          events:
            - pull_request

          # The agent is instructed to fetch the actual diff before reviewing.
          # {number} and {repository.full_name} are resolved from the GitHub payload.
          prompt: |
            A pull request event was received (action: {action}).

            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            Branch: {pull_request.head.ref}{pull_request.base.ref}
            Description: {pull_request.body}
            URL: {pull_request.html_url}

            If the action is "closed" or "labeled", stop here and do not post a comment.

            Otherwise:
            1. Run: gh pr diff {number} --repo {repository.full_name}
            2. Review the code changes for correctness, security issues, and clarity.
            3. Write a concise, actionable review comment and post it.

          deliver: github_comment
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

---

hermes gateway

---

[webhook] Listening on 0.0.0.0:8644 - routes: github-pr-review

---

curl http://localhost:8644/health
# {"status": "ok", "platform": "webhook"}

---

tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"

---

ngrok http 8644

---

SECRET="your-webhook-secret-here"
BODY='{"action":"opened","number":99,"pull_request":{"title":"Test PR","body":"Adds a feature.","user":{"login":"testuser"},"head":{"ref":"feat/x"},"base":{"ref":"main"},"html_url":"https://github.com/org/repo/pull/99"},"repository":{"full_name":"org/repo"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print "sha256="$2}')

curl -s -X POST http://localhost:8644/webhooks/github-pr-review \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: pull_request" \
  -H "X-Hub-Signature-256: $SIG" \
  -d "$BODY"
# Expected: {"status":"accepted","route":"github-pr-review","event":"pull_request","delivery_id":"..."}

---

tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"

---

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        github-pr-review:
          secret: "your-webhook-secret-here"
          events: [pull_request]
          prompt: |
            A pull request event was received (action: {action}).
            PR #{number}: {pull_request.title} by {pull_request.user.login}
            URL: {pull_request.html_url}

            If the action is "closed" or "labeled", stop here and do not post a comment.

            Otherwise:
            1. Run: gh pr diff {number} --repo {repository.full_name}
            2. Review the diff using your review guidelines.
            3. Write a concise, actionable review comment and post it.
          skills:
            - review
          deliver: github_comment
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

---

# Inside platforms.webhook.extra.routes.<route-name>:

# Slack
deliver: slack
deliver_extra:
  chat_id: "C0123456789"   # Slack channel ID (omit to use the configured home channel)

# Discord
deliver: discord
deliver_extra:
  chat_id: "987654321012345678"  # Discord channel ID (omit to use home channel)

---

events:
  - Merge Request Hook

---

platforms:
  webhook:
    enabled: true
    extra:
      host: "0.0.0.0"         # bind address (default: 0.0.0.0)
      port: 8644               # listen port (default: 8644)
      secret: ""               # optional global fallback secret
      rate_limit: 30           # requests per minute per route
      max_body_bytes: 1048576  # payload size limit in bytes (default: 1 MB)

      routes:
        <route-name>:
          secret: "required-per-route"
          events: []            # [] = accept all; otherwise list X-GitHub-Event values
          prompt: ""            # {field} / {nested.field} resolved from payload
          skills: []            # first matching skill is loaded (only one)
          deliver: "log"        # log | github_comment | telegram | discord | slack | signal | sms
          deliver_extra: {}     # repo + pr_number for github_comment; chat_id for others

---

# In any chat session:
/skills

# Or from the CLI:
hermes skills list

---

ascii-art         Generate ASCII art using pyfiglet, cowsay, boxes...
arxiv             Search and retrieve academic papers from arXiv...
github-pr-workflow Full PR lifecycle - create branches, commit...
plan              Plan mode - inspect context, write a markdown...
excalidraw        Create hand-drawn style diagrams using Excalidraw...

---

# Search by keyword
/skills search docker
/skills search music

---

# Browse official optional skills
/skills browse

# Search the hub
/skills search blockchain

---

# Load a skill and give it a task
/ascii-art Make a banner that says "HELLO WORLD"
/plan Design a REST API for a todo app
/github-pr-workflow Create a PR for the auth refactor

# Just the skill name (no task) loads it and lets you describe what you need
/excalidraw

---

# Install an official optional skill
hermes skills install official/research/arxiv

# Install from the hub in a chat session
/skills install official/creative/songwriting-and-ai-music

---

# Check it's there
hermes skills list | grep arxiv

# Or in chat
/skills search arxiv

---

# Load a plugin skill by its qualified name
skill_view("superpowers:writing-plans")

# Built-in skill with the same base name is unaffected
skill_view("writing-plans")

---

metadata:
  hermes:
    config:
      - key: tenor.api_key
        description: "Tenor API key for GIF search"
        prompt: "Enter your Tenor API key"
        url: "https://developers.google.com/tenor/guides/quickstart"

---

# Interactive config for a specific skill
hermes skills config gif-search

# View all skill config
hermes config get skills.config

---

mkdir -p ~/.hermes/skills/my-category/my-skill

---

### 3. Add Reference Files (Optional)

Skills สามารถรวมไฟล์สนับสนุนที่ agent โหลดเมื่อจำเป็นได้:

---

อ้างอิงสิ่งเหล่านี้ใน SKILL.md ของคุณ:

---

### 4. Test It

เริ่ม session ใหม่และลองใช้ skill ของคุณ:

---

skill จะปรากฏโดยอัตโนมัติ - ไม่ต้องลงทะเบียน แค่ใส่ไว้ใน `~/.hermes/skills/` ก็ใช้งานได้แล้ว

:::info
agent ยังสามารถสร้างและอัปเดต skills ได้ด้วยตัวเองโดยใช้ `skill_manage` หลังจากแก้ปัญหาที่ซับซ้อนเสร็จแล้ว Hermes อาจเสนอให้บันทึกแนวทางนั้นเป็น skill สำหรับครั้งต่อไป ตอบตกลง - skills ที่สร้างโดย agent เหล่านี้จะบันทึก workflow ที่แม่นยำ รวมถึง pitfalls ที่ค้นพบระหว่างทาง
:::

---

## Per-Platform Skill Management

ควบคุมว่า skills ใดบ้างที่พร้อมใช้งานบนแพลตฟอร์มใด:
RAW_BUFFERClick to expand / collapse

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


sidebar_position: 7 title: "Use SOUL.md with Hermes" description: "How to use SOUL.md to shape Hermes Agent's default voice, what belongs there, and how it differs from AGENTS.md and /personality"

การใช้ SOUL.md กับ Hermes

SOUL.md คือ อัตลักษณ์หลัก (primary identity) สำหรับ instance ของ Hermes ของคุณ มันเป็นสิ่งแรกใน system prompt - มันกำหนดว่า agent คือใคร พูดอย่างไร และควรหลีกเลี่ยงอะไร

หากคุณต้องการให้ Hermes รู้สึกเหมือนผู้ช่วยคนเดิมทุกครั้งที่คุยด้วย - หรือหากคุณต้องการแทนที่บุคลิกภาพของ Hermes ทั้งหมดด้วยของคุณเอง - นี่คือไฟล์ที่คุณต้องใช้

SOUL.md ใช้สำหรับอะไร

ใช้ SOUL.md สำหรับ:

  • น้ำเสียง (tone)
  • บุคลิกภาพ (personality)
  • รูปแบบการสื่อสาร (communication style)
  • ระดับความตรงไปตรงมาหรือความอบอุ่นที่ Hermes ควรมี
  • สิ่งที่ Hermes ควรหลีกเลี่ยงในเชิงรูปแบบ (stylistically)
  • วิธีที่ Hermes ควรรับมือกับความไม่แน่นอน (uncertainty), ความขัดแย้ง (disagreement), และความคลุมเครือ (ambiguity)

กล่าวโดยสรุป:

  • SOUL.md เกี่ยวกับว่า Hermes คือใคร และ Hermes พูดอย่างไร

SOUL.md ไม่ได้ใช้สำหรับอะไร

ห้ามใช้สำหรับ:

  • ข้อกำหนดการเขียนโค้ดเฉพาะ repo (repo-specific coding conventions)
  • file paths
  • commands
  • service ports
  • architecture notes
  • คำแนะนำขั้นตอนการทำงานของโปรเจกต์ (project workflow instructions)

สิ่งเหล่านี้ควรอยู่ใน AGENTS.md

กฎง่ายๆ:

  • ถ้ามันควรใช้ได้ทุกที่ ให้ใส่ใน SOUL.md
  • ถ้ามันเป็นของโปรเจกต์เดียว ให้ใส่ใน AGENTS.md

ตำแหน่งที่อยู่

ปัจจุบัน Hermes ใช้เฉพาะไฟล์ SOUL ทั่วโลก (global SOUL file) สำหรับ instance ปัจจุบัน:

~/.hermes/SOUL.md

หากคุณรัน Hermes ด้วย home directory ที่กำหนดเอง มันจะเป็น:

$HERMES_HOME/SOUL.md

พฤติกรรมเมื่อรันครั้งแรก

Hermes จะสร้างไฟล์ SOUL.md เริ่มต้นให้คุณโดยอัตโนมัติ หากยังไม่มีไฟล์นี้

นั่นหมายความว่าผู้ใช้ส่วนใหญ่จะเริ่มต้นด้วยไฟล์จริงที่สามารถอ่านและแก้ไขได้ทันที

สิ่งสำคัญ:

  • หากคุณมี SOUL.md อยู่แล้ว Hermes จะไม่เขียนทับไฟล์นั้น
  • หากไฟล์มีอยู่แต่ว่างเปล่า Hermes จะไม่เพิ่มข้อมูลใดๆ จากไฟล์นั้นลงใน prompt

Hermes ใช้มันอย่างไร

เมื่อ Hermes เริ่ม session มันจะอ่าน SOUL.md จาก HERMES_HOME สแกนหา pattern ของ prompt-injection, ตัดเนื้อหาหากจำเป็น, และใช้มันเป็น อัตลักษณ์ของ agent (agent identity) - ตำแหน่งที่ #1 ใน system prompt นั่นหมายความว่า SOUL.md จะแทนที่ข้อความอัตลักษณ์เริ่มต้นที่มาพร้อมกับระบบโดยสมบูรณ์

หาก SOUL.md หายไป ว่างเปล่า หรือไม่สามารถโหลดได้ Hermes จะกลับไปใช้อัตลักษณ์เริ่มต้นที่ระบบกำหนดไว้

จะไม่มีการเพิ่ม wrapper language รอบไฟล์ เนื้อหาของไฟล์เองที่สำคัญ - ให้เขียนในแบบที่คุณต้องการให้ agent ของคุณคิดและพูด

การแก้ไขครั้งแรกที่ดี

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

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

You are direct, calm, and technically precise.
Prefer substance over politeness theater.
Push back clearly when an idea is weak.
Keep answers compact unless deeper detail is useful.

เพียงเท่านี้ก็สามารถเปลี่ยนความรู้สึกของ Hermes ได้อย่างเห็นได้ชัด

รูปแบบตัวอย่าง

1. วิศวกรเชิงปฏิบัติ (Pragmatic engineer)

You are a pragmatic senior engineer.
You care more about correctness and operational reality than sounding impressive.

## Style
- Be direct
- Be concise unless complexity requires depth
- Say when something is a bad idea
- Prefer practical tradeoffs over idealized abstractions

## Avoid
- Sycophancy
- Hype language
- Overexplaining obvious things

2. คู่ค้างานวิจัย (Research partner)

You are a thoughtful research collaborator.
You are curious, honest about uncertainty, and excited by unusual ideas.

## Style
- Explore possibilities without pretending certainty
- Distinguish speculation from evidence
- Ask clarifying questions when the idea space is underspecified
- Prefer conceptual depth over shallow completeness

3. ครู/ผู้ให้คำอธิบาย (Teacher / explainer)

You are a patient technical teacher.
You care about understanding, not performance.

## Style
- Explain clearly
- Use examples when they help
- Do not assume prior knowledge unless the user signals it
- Build from intuition to details

4. ผู้ตรวจทานที่เข้มงวด (Tough reviewer)

You are a rigorous reviewer.
You are fair, but you do not soften important criticism.

## Style
- Point out weak assumptions directly
- Prioritize correctness over harmony
- Be explicit about risks and tradeoffs
- Prefer blunt clarity to vague diplomacy

อะไรที่ทำให้ SOUL.md แข็งแกร่ง?

SOUL.md ที่แข็งแกร่งคือ:

  • มีความเสถียร (stable)
  • สามารถนำไปใช้ได้กว้างขวาง (broadly applicable)
  • เฉพาะเจาะจงในด้านน้ำเสียง (specific in voice)
  • ไม่ถูกบรรจุด้วยคำสั่งชั่วคราวมากเกินไป

SOUL.md ที่อ่อนแอคือ:

  • เต็มไปด้วยรายละเอียดของโปรเจกต์
  • ขัดแย้งกันเอง
  • พยายามจัดการทุกรูปแบบการตอบกลับ (micro-manage every response shape)
  • ส่วนใหญ่เป็น filler ทั่วไป เช่น "be helpful" และ "be clear"

Hermes พยายามที่จะช่วยเหลือและชัดเจนอยู่แล้ว SOUL.md ควรเพิ่มบุคลิกภาพและสไตล์ที่แท้จริง ไม่ใช่การกล่าวซ้ำค่าเริ่มต้นที่ชัดเจน

โครงสร้างที่แนะนำ

คุณไม่จำเป็นต้องมีหัวข้อ (headings) แต่การมีจะช่วยได้

โครงสร้างง่ายๆ ที่ใช้งานได้ดี:

# Identity
ใครคือ Hermes

# Style
Hermes ควรมีน้ำเสียงอย่างไร

# Avoid
Hermes ไม่ควรทำอะไร

# Defaults
Hermes ควรมีพฤติกรรมอย่างไรเมื่อเกิดความคลุมเครือ

SOUL.md เทียบกับ /personality

ทั้งสองอย่างนี้เสริมกัน

ใช้ SOUL.md สำหรับ baseline ที่คงทนของคุณ ใช้ /personality สำหรับการสลับโหมดชั่วคราว

ตัวอย่าง:

  • SOUL เริ่มต้นของคุณคือเชิงปฏิบัติและตรงไปตรงมา
  • จากนั้นสำหรับการ session หนึ่ง คุณใช้ /personality teacher
  • ภายหลังคุณสลับกลับโดยไม่ต้องเปลี่ยนไฟล์ base voice ของคุณ

SOUL.md เทียบกับ AGENTS.md

นี่คือข้อผิดพลาดที่พบบ่อยที่สุด

ใส่สิ่งนี้ใน SOUL.md

  • “Be direct.”
  • “Avoid hype language.”
  • “Prefer short answers unless depth helps.”
  • “Push back when the user is wrong.”

ใส่สิ่งนี้ใน AGENTS.md

  • “Use pytest, not unittest.”
  • “Frontend lives in frontend/.”
  • “Never edit migrations directly.”
  • “The API runs on port 8000.”

วิธีแก้ไข

nano ~/.hermes/SOUL.md

หรือ

vim ~/.hermes/SOUL.md

จากนั้นให้รีสตาร์ท Hermes หรือเริ่ม session ใหม่

Workflow ในทางปฏิบัติ

  1. เริ่มต้นด้วยไฟล์ default ที่ถูก seed มา
  2. ตัดส่วนใดๆ ที่ไม่รู้สึกว่าเป็นน้ำเสียงที่คุณต้องการ
  3. เพิ่ม 4-8 บรรทัดที่กำหนด tone และ default อย่างชัดเจน
  4. คุยกับ Hermes สักพัก
  5. ปรับปรุงตามสิ่งที่ยังรู้สึกว่าไม่ถูกต้อง

แนวทางแบบทำซ้ำ (iterative approach) นี้ทำงานได้ดีกว่าการพยายามออกแบบบุคลิกภาพที่สมบูรณ์แบบในครั้งเดียว

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

ฉันแก้ไข SOUL.md แล้ว แต่ Hermes ยังคงมีน้ำเสียงเดิม

ตรวจสอบ:

  • คุณแก้ไข ~/.hermes/SOUL.md หรือ $HERMES_HOME/SOUL.md
  • ไม่ใช่ SOUL.md ที่อยู่ใน repo ท้องถิ่น
  • ไฟล์ไม่ได้ว่างเปล่า
  • คุณได้รีสตาร์ท session หลังการแก้ไขแล้ว
  • ไม่มี overlay ของ /personality เข้ามาครอบงำผลลัพธ์

Hermes เพิกเฉยต่อบางส่วนของ SOUL.md ของฉัน

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

  • คำสั่งที่มีลำดับความสำคัญสูงกว่ากำลังเขียนทับมัน
  • ไฟล์มีคำแนะนำที่ขัดแย้งกัน
  • ไฟล์ยาวเกินไปและถูกตัดทอน (truncated)
  • ข้อความบางส่วนคล้ายกับ prompt-injection content และอาจถูกบล็อกหรือเปลี่ยนแปลงโดย scanner

SOUL.md ของฉันกลายเป็นเฉพาะโปรเจกต์มากเกินไป

ย้ายคำแนะนำของโปรเจกต์ไปที่ AGENTS.md และให้ SOUL.md มุ่งเน้นไปที่อัตลักษณ์และสไตล์

เอกสารที่เกี่ยวข้อง


📄 guides/use-voice-mode-with-hermes.md


sidebar_position: 8 title: "Use Voice Mode with Hermes" description: "A practical guide to setting up and using Hermes voice mode across CLI, Telegram, Discord, and Discord voice channels"

Use Voice Mode with Hermes

คู่มือนี้เป็นคู่มือภาคปฏิบัติสำหรับ Voice Mode feature reference

หากหน้าฟีเจอร์อธิบายว่าโหมดเสียงทำอะไรได้ คู่มือนี้จะแสดงวิธีใช้งานให้ดีจริง ๆ

What voice mode is good for

โหมดเสียงจะมีประโยชน์เป็นพิเศษเมื่อ:

  • คุณต้องการ workflow แบบ hands-free ใน CLI
  • คุณต้องการการตอบกลับด้วยเสียงใน Telegram หรือ Discord
  • คุณต้องการให้ Hermes อยู่ใน Discord voice channel สำหรับการสนทนาแบบสด
  • คุณต้องการบันทึกไอเดียอย่างรวดเร็ว, debug, หรือการโต้ตอบไปมาขณะเดิน แทนการพิมพ์

Choose your voice mode setup

โดยพื้นฐานแล้ว Hermes มีประสบการณ์โหมดเสียงที่แตกต่างกันสามแบบ

ModeBest forPlatform
Interactive microphone loopPersonal hands-free use while coding or researchingCLI
Voice replies in chatSpoken responses alongside normal messagingTelegram, Discord
Live voice channel botGroup or personal live conversation in a VCDiscord voice channels

ลำดับที่ดีที่สุดคือ:

  1. ทำให้ text mode ใช้งานได้ก่อน
  2. เปิดใช้งาน voice replies เป็นอันดับสอง
  3. ย้ายไปใช้ Discord voice channels เป็นลำดับสุดท้าย หากคุณต้องการประสบการณ์แบบเต็มรูปแบบ

Step 1: make sure normal Hermes works first

ก่อนที่จะแตะต้องโหมดเสียง ให้ตรวจสอบว่า:

  • Hermes สามารถเริ่มต้นได้
  • provider ของคุณได้รับการตั้งค่าแล้ว
  • agent สามารถตอบ prompt แบบ text ได้ตามปกติ
hermes

ลองถามคำถามง่าย ๆ:

What tools do you have available?

หากส่วนนี้ยังไม่เสถียร ให้แก้ไข text mode ก่อน

Step 2: install the right extras

CLI microphone + playback

pip install "hermes-agent[voice]"

Messaging platforms

pip install "hermes-agent[messaging]"

Premium ElevenLabs TTS

pip install "hermes-agent[tts-premium]"

Local NeuTTS (optional)

python -m pip install -U neutts[all]

Everything

pip install "hermes-agent[all]"

Step 3: install system dependencies

macOS

brew install portaudio ffmpeg opus
brew install espeak-ng

Ubuntu / Debian

sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng

เหตุผลที่ต้องติดตั้งสิ่งเหล่านี้:

  • portaudio → microphone input / playback สำหรับ CLI voice mode
  • ffmpeg → audio conversion สำหรับ TTS และการส่งข้อความ
  • opus → รองรับ Discord voice codec
  • espeak-ng → phonemizer backend สำหรับ NeuTTS

Step 4: choose STT and TTS providers

Hermes รองรับ speech stacks ทั้งแบบ local และ cloud

Easiest / cheapest setup

ใช้ local STT และ Edge TTS ฟรี:

  • STT provider: local
  • TTS provider: edge

โดยปกติแล้วนี่คือจุดเริ่มต้นที่ดีที่สุด

Environment file example

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

# Cloud STT options (local needs no key)
GROQ_API_KEY=***
VOICE_TOOLS_OPENAI_KEY=***

# Premium TTS (optional)
ELEVENLABS_API_KEY=***

Provider recommendations

Speech-to-text

  • local → ค่าเริ่มต้นที่ดีที่สุดสำหรับความเป็นส่วนตัวและค่าใช้จ่ายศูนย์
  • groq → cloud transcription ที่เร็วมาก
  • openai → ตัวเลือกสำรองแบบเสียเงินที่ดี

Text-to-speech

  • edge → ฟรีและเพียงพอสำหรับผู้ใช้ส่วนใหญ่
  • neutts → TTS แบบ local/on-device ฟรี
  • elevenlabs → คุณภาพดีที่สุด
  • openai → ตัวเลือกที่สมดุลที่ดี
  • mistral → รองรับหลายภาษา, Native Opus

If you use hermes setup

หากคุณเลือก NeuTTS ใน setup wizard, Hermes จะตรวจสอบว่า neutts ได้ถูกติดตั้งแล้วหรือไม่ หากขาดไป, wizard จะแจ้งว่า NeuTTS ต้องการ Python package neutts และ system package espeak-ng, เสนอให้ติดตั้งให้คุณ, ติดตั้ง espeak-ng ด้วย package manager ของ platform ของคุณ, และรัน:

python -m pip install -U neutts[all]

หากคุณข้ามการติดตั้งนั้นหรือมันล้มเหลว, wizard จะกลับไปใช้ Edge TTS

Step 5: recommended config

voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120
  auto_tts: false
  beep_enabled: true
  silence_threshold: 200
  silence_duration: 3.0

stt:
  provider: "local"
  local:
    model: "base"

tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

นี่คือค่า default ที่ปลอดภัยและดีสำหรับคนส่วนใหญ่

หากคุณต้องการ local TTS แทน, ให้เปลี่ยนบล็อก tts เป็น:

tts:
  provider: "neutts"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Use case 1: CLI voice mode

Turn it on

เริ่มต้น Hermes:

hermes

ภายใน CLI:

/voice on

Recording flow

Default key:

  • Ctrl+B

Workflow:

  1. กด Ctrl+B
  2. พูด
  3. รอให้ระบบตรวจจับความเงียบเพื่อหยุดบันทึกโดยอัตโนมัติ
  4. Hermes ถอดเสียงและตอบกลับ
  5. หาก TTS เปิดอยู่, มันจะพูดคำตอบ
  6. loop สามารถเริ่มใหม่โดยอัตโนมัติสำหรับการใช้งานต่อเนื่อง

Useful commands

/voice
/voice on
/voice off
/voice tts
/voice status

Good CLI workflows

Walk-up debugging

พูดว่า:

I keep getting a docker permission error. Help me debug it.

จากนั้นดำเนินการแบบ hands-free ต่อไป:

  • "Read the last error again"
  • "Explain the root cause in simpler terms"
  • "Now give me the exact fix"

Research / brainstorming

เหมาะสำหรับ:

  • การเดินไปรอบ ๆ ขณะคิด
  • การบอกไอเดียที่ยังไม่สมบูรณ์
  • การขอให้ Hermes จัดโครงสร้างความคิดของคุณแบบ real time

Accessibility / low-typing sessions

หากการพิมพ์ไม่สะดวก, voice mode เป็นวิธีที่เร็วที่สุดวิธีหนึ่งในการอยู่ใน loop ของ Hermes อย่างเต็มที่

Tuning CLI behavior

Silence threshold

หาก Hermes เริ่ม/หยุดทำงานเร็วเกินไป, ให้ปรับค่า:

voice:
  silence_threshold: 250

ค่า threshold สูง = ความไวต่ำลง

Silence duration

หากคุณหยุดพักนานระหว่างประโยค, ให้เพิ่มค่า:

voice:
  silence_duration: 4.0

Record key

หาก Ctrl+B ขัดแย้งกับนิสัยการใช้ terminal หรือ tmux ของคุณ:

voice:
  record_key: "ctrl+space"

Use case 2: voice replies in Telegram or Discord

โหมดนี้ง่ายกว่า voice channels แบบเต็มรูปแบบ

Hermes จะยังคงเป็น chat bot ทั่วไป แต่สามารถพูดคำตอบได้

Start the gateway

hermes gateway

Turn on voice replies

ภายใน Telegram หรือ Discord:

/voice on

หรือ

/voice tts

Modes

ModeMeaning
offtext only
voice_onlyspeak only when the user sent voice
allspeak every reply

When to use which mode

  • /voice on หากคุณต้องการคำตอบด้วยเสียงสำหรับข้อความที่มาจากเสียงเท่านั้น
  • /voice tts หากคุณต้องการผู้ช่วยที่พูดตลอดเวลา

Good messaging workflows

Telegram assistant on your phone

ใช้เมื่อ:

  • คุณไม่อยู่ที่เครื่องของคุณ
  • คุณต้องการส่ง voice notes และรับคำตอบด้วยเสียงอย่างรวดเร็ว
  • คุณต้องการให้ Hermes ทำหน้าที่เหมือนผู้ช่วยวิจัยหรือผู้ช่วยปฏิบัติการแบบพกพา

Discord DMs with spoken output

มีประโยชน์เมื่อคุณต้องการการโต้ตอบส่วนตัวโดยไม่มีพฤติกรรม mention ใน server-channel

Use case 3: Discord voice channels

นี่คือโหมดที่ล้ำหน้าที่สุด

Hermes จะเข้าร่วม Discord VC, ฟังคำพูดของผู้ใช้, ถอดเสียง, รัน agent pipeline ปกติ, และพูดคำตอบกลับเข้าไปใน channel

Required Discord permissions

นอกเหนือจากการตั้งค่า text-bot ปกติ, ให้แน่ใจว่า bot มี:

  • Connect
  • Speak
  • preferably Use Voice Activity

และเปิดใช้งาน privileged intents ใน Developer Portal:

  • Presence Intent
  • Server Members Intent
  • Message Content Intent

Join and leave

ใน Discord text channel ที่ bot อยู่:

/voice join
/voice leave
/voice status

What happens when joined

  • ผู้ใช้พูดใน VC
  • Hermes ตรวจจับขอบเขตของคำพูด
  • transcripts จะถูกโพสต์ใน text channel ที่เกี่ยวข้อง
  • Hermes ตอบกลับทั้งในรูปแบบ text และ audio
  • text channel คือช่องที่ออกคำสั่ง /voice join

Best practices for Discord VC use

  • keep DISCORD_ALLOWED_USERS tight
  • use a dedicated bot/testing channel at first
  • verify STT and TTS work in ordinary text-chat voice mode before trying VC mode

Voice quality recommendations

Best quality setup

  • STT: local large-v3 or Groq whisper-large-v3
  • TTS: ElevenLabs

Best speed / convenience setup

  • STT: local base or Groq
  • TTS: Edge

Best zero-cost setup

  • STT: local
  • TTS: Edge

Common failure modes

"No audio device found"

ติดตั้ง portaudio

"Bot joins but hears nothing"

ตรวจสอบ:

  • user ID ของ Discord ของคุณอยู่ใน DISCORD_ALLOWED_USERS
  • คุณไม่ได้ถูก mute
  • privileged intents ถูกเปิดใช้งานแล้ว
  • bot มีสิทธิ์ Connect/Speak

"It transcribes but does not speak"

ตรวจสอบ:

  • การตั้งค่า TTS provider
  • API key / quota สำหรับ ElevenLabs หรือ OpenAI
  • การติดตั้ง ffmpeg สำหรับ Edge conversion paths

"Whisper outputs garbage"

ลอง:

  • สภาพแวดล้อมที่เงียบกว่า
  • silence_threshold ที่สูงขึ้น
  • provider/model STT ที่แตกต่างกัน
  • คำพูดที่สั้นลงและชัดเจนขึ้น

"It works in DMs but not in server channels"

นั่นมักจะเป็นเรื่องของ mention policy

โดยค่าเริ่มต้น, bot ต้องการ @mention ใน Discord server text channels เว้นแต่จะมีการตั้งค่าเป็นอย่างอื่น

Suggested first-week setup

หากคุณต้องการเส้นทางที่สั้นที่สุดสู่ความสำเร็จ:

  1. get text Hermes working
  2. install hermes-agent[voice]
  3. use CLI voice mode with local STT + Edge TTS
  4. then enable /voice on in Telegram or Discord
  5. only after that, try Discord VC mode

ลำดับนี้จะทำให้พื้นที่ในการ debug มีขนาดเล็ก

Where to read next


📄 guides/webhook-github-pr-review.md


sidebar_position: 11 sidebar_label: "GitHub PR Reviews via Webhook" title: "Automated GitHub PR Comments with Webhooks" description: "Connect Hermes to GitHub so it automatically fetches PR diffs, reviews code changes, and posts comments - triggered by webhooks with no manual prompting"

Automated GitHub PR Comments with Webhooks

คู่มือนี้จะแนะนำวิธีการเชื่อมต่อ Hermes Agent เข้ากับ GitHub เพื่อให้สามารถดึง diff ของ pull request โดยอัตโนมัติ วิเคราะห์การเปลี่ยนแปลงโค้ด และโพสต์คอมเมนต์ โดยถูกกระตุ้นโดยเหตุการณ์ webhook โดยไม่จำเป็นต้องมีการแจ้งเตือนด้วยตนเอง

เมื่อมีการเปิดหรืออัปเดต PR, GitHub จะส่ง webhook POST ไปยัง instance ของ Hermes ของคุณ Hermes จะรัน agent ด้วย prompt ที่สั่งให้ดึง diff ผ่าน gh CLI และส่ง response กลับไปยัง thread ของ PR

:::tip Want a simpler setup without a public endpoint? หากคุณไม่มี public URL หรือต้องการเริ่มต้นใช้งานอย่างรวดเร็ว ลองดู Build a GitHub PR Review Agent - ซึ่งใช้ cron jobs เพื่อ poll PRs ตามตารางเวลา ทำงานได้แม้หลัง NAT และ firewalls :::

:::info Reference docs สำหรับเอกสารอ้างอิงแพลตฟอร์ม webhook ฉบับเต็ม (ตัวเลือก config ทั้งหมด, ประเภทการส่ง, dynamic subscriptions, security model) ดูที่ Webhooks :::

:::warning Prompt injection risk Webhook payloads มีข้อมูลที่ผู้โจมตีควบคุมได้ - ชื่อ PR, commit messages, และ descriptions อาจมีคำสั่งที่เป็นอันตราย เมื่อ webhook endpoint ของคุณเปิดสู่อินเทอร์เน็ต ให้รัน gateway ในสภาพแวดล้อมแบบ sandboxed (Docker, SSH backend) ดูที่ security section ด้านล่าง :::


Prerequisites

  • Hermes Agent ติดตั้งและกำลังทำงานอยู่ (hermes gateway)
  • gh CLI ติดตั้งและ authenticated บน gateway host (gh auth login)
  • URL ที่สามารถเข้าถึงได้จากสาธารณะสำหรับ Hermes instance ของคุณ (ดู Local testing with ngrok หากรันในเครื่อง)
  • สิทธิ์ผู้ดูแลระบบ (Admin access) สำหรับ GitHub repository (จำเป็นสำหรับการจัดการ webhooks)

Step 1 - Enable the webhook platform

เพิ่มสิ่งต่อไปนี้ใน ~/.hermes/config.yaml:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644          # default; change if another service occupies this port
      rate_limit: 30      # max requests per minute per route (not a global cap)

      routes:
        github-pr-review:
          secret: "your-webhook-secret-here"   # must match the GitHub webhook secret exactly
          events:
            - pull_request

          # The agent is instructed to fetch the actual diff before reviewing.
          # {number} and {repository.full_name} are resolved from the GitHub payload.
          prompt: |
            A pull request event was received (action: {action}).

            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            Branch: {pull_request.head.ref}{pull_request.base.ref}
            Description: {pull_request.body}
            URL: {pull_request.html_url}

            If the action is "closed" or "labeled", stop here and do not post a comment.

            Otherwise:
            1. Run: gh pr diff {number} --repo {repository.full_name}
            2. Review the code changes for correctness, security issues, and clarity.
            3. Write a concise, actionable review comment and post it.

          deliver: github_comment
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Key fields:

FieldDescription
secret (route-level)HMAC secret สำหรับ route นี้ หากละเว้น จะใช้ค่า extra.secret global เป็นค่า fallback
eventsรายการค่าของ header X-GitHub-Event ที่ยอมรับ รายการว่างเปล่า = ยอมรับทั้งหมด
promptTemplate; {field} และ {nested.field} จะถูก resolve จาก GitHub payload
delivergithub_comment โพสต์ผ่าน gh pr comment ส่วน log จะเขียนลงใน gateway log
deliver_extra.repoResolve เป็น e.g. org/repo จาก payload
deliver_extra.pr_numberResolve เป็น PR number จาก payload

:::note The payload does not contain code Webhook payload ของ GitHub ประกอบด้วย metadata ของ PR (title, description, branch names, URLs) แต่ ไม่รวม diff prompt ด้านบนสั่งให้ agent รัน gh pr diff เพื่อดึงการเปลี่ยนแปลงจริง terminal tool ถูกรวมอยู่ใน hermes-webhook toolset เริ่มต้น ดังนั้นจึงไม่จำเป็นต้องมีการตั้งค่าเพิ่มเติม :::


Step 2 - Start the gateway

hermes gateway

คุณควรเห็น:

[webhook] Listening on 0.0.0.0:8644 - routes: github-pr-review

ตรวจสอบว่าทำงานได้:

curl http://localhost:8644/health
# {"status": "ok", "platform": "webhook"}

Step 3 - Register the webhook on GitHub

  1. ไปที่ repository ของคุณ → SettingsWebhooksAdd webhook
  2. กรอกข้อมูล:
    • Payload URL: https://your-public-url.example.com/webhooks/github-pr-review
    • Content type: application/json
    • Secret: ค่าเดียวกับที่คุณตั้งไว้สำหรับ secret ใน route config
    • Which events? → Select individual events → check Pull requests
  3. คลิก Add webhook

GitHub จะส่งเหตุการณ์ ping ทันทีเพื่อยืนยันการเชื่อมต่อ ซึ่งจะถูกเพิกเฉยอย่างปลอดภัย - ping ไม่อยู่ในรายการ events ของคุณ - และจะคืนค่า {"status": "ignored", "event": "ping"} มันจะถูกบันทึกเพียงระดับ DEBUG เท่านั้น ดังนั้นจึงจะไม่ปรากฏใน console ที่ระดับ log default


Step 4 - Open a test PR

สร้าง branch, push การเปลี่ยนแปลง, และเปิด PR ภายใน 30-90 วินาที (ขึ้นอยู่กับขนาด PR และ model) Hermes ควรจะโพสต์คอมเมนต์รีวิว

หากต้องการติดตามความคืบหน้าของ agent แบบเรียลไทม์:

tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"

Local testing with ngrok

หาก Hermes กำลังทำงานบน laptop ของคุณ ให้ใช้ ngrok เพื่อเปิดเผยมัน:

ngrok http 8644

คัดลอก URL https://...ngrok-free.app และใช้เป็น GitHub Payload URL บน free ngrok tier URL จะเปลี่ยนทุกครั้งที่ ngrok restart - ให้อัปเดต GitHub webhook ของคุณในแต่ละ session บัญชี ngrok แบบเสียเงินจะได้ static domain

คุณสามารถ smoke-test static route ได้โดยตรงด้วย curl - ไม่ต้องมีบัญชี GitHub หรือ PR จริง

:::tip Use deliver: log when testing locally เปลี่ยน deliver: github_comment เป็น deliver: log ใน config ของคุณขณะทดสอบ มิฉะนั้น agent จะพยายามโพสต์คอมเมนต์ไปยัง repo org/repo#99 ปลอมใน test payload ซึ่งจะล้มเหลว ให้สลับกลับไปที่ deliver: github_comment เมื่อคุณพอใจกับ output ของ prompt แล้ว :::

SECRET="your-webhook-secret-here"
BODY='{"action":"opened","number":99,"pull_request":{"title":"Test PR","body":"Adds a feature.","user":{"login":"testuser"},"head":{"ref":"feat/x"},"base":{"ref":"main"},"html_url":"https://github.com/org/repo/pull/99"},"repository":{"full_name":"org/repo"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print "sha256="$2}')

curl -s -X POST http://localhost:8644/webhooks/github-pr-review \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: pull_request" \
  -H "X-Hub-Signature-256: $SIG" \
  -d "$BODY"
# Expected: {"status":"accepted","route":"github-pr-review","event":"pull_request","delivery_id":"..."}

จากนั้นดู agent ทำงาน:

tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"

:::note hermes webhook test <name> ใช้ได้เฉพาะกับ dynamic subscriptions ที่สร้างด้วย hermes webhook subscribe เท่านั้น ไม่ได้อ่าน routes จาก config.yaml :::


Filtering to specific actions

GitHub ส่งเหตุการณ์ pull_request สำหรับหลาย actions: opened, synchronize, reopened, closed, labeled, ฯลฯ รายการ events กรองเฉพาะตามค่า header X-GitHub-Event เท่านั้น - ไม่สามารถกรองตาม action sub-type ในระดับ routing ได้

prompt ใน Step 1 จัดการเรื่องนี้แล้วโดยการสั่งให้ agent หยุดทำงานตั้งแต่เนิ่นๆ สำหรับเหตุการณ์ closed และ labeled

:::warning The agent still runs and consumes tokens คำสั่ง "stop here" ป้องกันการรีวิวที่มีความหมาย แต่ agent ยังคงรันจนเสร็จสิ้นสำหรับทุกเหตุการณ์ pull_request ไม่ว่า action จะเป็นอะไรก็ตาม GitHub webhooks สามารถกรองได้เฉพาะตามประเภทเหตุการณ์ (pull_request, push, issues, ฯลฯ) - ไม่ใช่ตาม action sub-type (opened, closed, labeled) ไม่มี filter ระดับ routing สำหรับ sub-actions สำหรับ repo ที่มีปริมาณสูง ให้ยอมรับค่าใช้จ่ายนี้ หรือกรองที่ต้นทางด้วย GitHub Actions workflow ที่เรียก webhook URL ของคุณแบบมีเงื่อนไข :::

There is no Jinja2 or conditional template syntax. {field} and {nested.field} are the only substitutions supported. Anything else is passed verbatim to the agent.


Using a skill for consistent review style

โหลด Hermes skill เพื่อให้ agent มีบุคลิกภาพในการรีวิวที่สม่ำเสมอ เพิ่ม skills เข้าไปใน route ของคุณภายใน platforms.webhook.extra.routes ใน config.yaml:

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        github-pr-review:
          secret: "your-webhook-secret-here"
          events: [pull_request]
          prompt: |
            A pull request event was received (action: {action}).
            PR #{number}: {pull_request.title} by {pull_request.user.login}
            URL: {pull_request.html_url}

            If the action is "closed" or "labeled", stop here and do not post a comment.

            Otherwise:
            1. Run: gh pr diff {number} --repo {repository.full_name}
            2. Review the diff using your review guidelines.
            3. Write a concise, actionable review comment and post it.
          skills:
            - review
          deliver: github_comment
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Note: Only the first skill in the list that is found is loaded. Hermes does not stack multiple skills - subsequent entries are ignored.


Sending responses to Slack or Discord instead

แทนที่ฟิลด์ deliver และ deliver_extra ภายใน route ของคุณด้วย target platform:

# Inside platforms.webhook.extra.routes.<route-name>:

# Slack
deliver: slack
deliver_extra:
  chat_id: "C0123456789"   # Slack channel ID (omit to use the configured home channel)

# Discord
deliver: discord
deliver_extra:
  chat_id: "987654321012345678"  # Discord channel ID (omit to use home channel)

Target platform ต้องเปิดใช้งานและเชื่อมต่อใน gateway ด้วย หากละเว้น chat_id response จะถูกส่งไปยัง home channel ที่กำหนดค่าไว้ของ platform นั้นๆ

Valid deliver values: log · github_comment · telegram · discord · slack · signal · sms


GitLab support

Adapter เดียวกันนี้ใช้ได้กับ GitLab GitLab ใช้ X-Gitlab-Token สำหรับการตรวจสอบสิทธิ์ (plain string match, ไม่ใช่ HMAC) - Hermes จัดการให้โดยอัตโนมัติ

สำหรับการกรองเหตุการณ์, GitLab ตั้งค่า X-GitLab-Event เป็นค่าต่างๆ เช่น Merge Request Hook, Push Hook, Pipeline Hook ให้ใช้ค่า header ที่แน่นอนใน events:

events:
  - Merge Request Hook

Field ของ payload ของ GitLab แตกต่างจาก GitHub - เช่น {object_attributes.title} สำหรับชื่อ MR และ {object_attributes.iid} สำหรับหมายเลข MR วิธีที่ง่ายที่สุดในการค้นหาโครงสร้าง payload ทั้งหมดคือปุ่ม Test ของ GitLab ในการตั้งค่า webhook ของคุณ ร่วมกับ log Recent Deliveries หรืออีกทางคือ ละเว้น prompt จาก route config ของคุณ - Hermes จะส่ง full payload เป็น formatted JSON ไปยัง agent โดยตรง และ response ของ agent (ที่มองเห็นได้ใน gateway log ด้วย deliver: log) จะอธิบายโครงสร้างของมัน


Security notes

  • Never use INSECURE_NO_AUTH ใน production - เพราะมันปิดการตรวจสอบ signature ทั้งหมด มันมีไว้สำหรับการพัฒนาในเครื่องเท่านั้น
  • Rotate your webhook secret เป็นระยะและอัปเดตทั้งใน GitHub (webhook settings) และ config.yaml ของคุณ
  • Rate limiting คือ 30 req/min ต่อ route โดยค่าเริ่มต้น (สามารถกำหนดค่าได้ผ่าน extra.rate_limit) การเกินขีดจำกัดจะคืนค่า 429
  • Duplicate deliveries (webhook retries) จะถูก deduplicate ผ่าน 1-hour idempotency cache คีย์ cache คือ X-GitHub-Delivery หากมี, จากนั้น X-Request-ID, จากนั้น timestamp แบบ millisecond เมื่อไม่มี delivery ID header ใดๆ, retries จะ ไม่ ถูก deduplicate
  • Prompt injection: ชื่อ PR, description, และ commit messages เป็นข้อมูลที่ผู้โจมตีควบคุมได้ PR ที่เป็นอันตรายอาจพยายามบิดเบือนการกระทำของ agent ให้รัน gateway ในสภาพแวดล้อมแบบ sandboxed (Docker, VM) เมื่อเปิดสู่สาธารณะอินเทอร์เน็ต

Troubleshooting

SymptomCheck
401 Invalid signatureSecret ใน config.yaml ไม่ตรงกับ GitHub webhook secret
404 Unknown routeชื่อ route ใน URL ไม่ตรงกับ key ใน routes:
429 Rate limit exceededเกิน 30 req/min ต่อ route - พบบ่อยเมื่อ re-delivering test events จาก UI ของ GitHub; รอหนึ่งนาที หรือเพิ่ม extra.rate_limit
No comment postedgh ไม่ได้ติดตั้ง, ไม่อยู่ใน PATH, หรือไม่ได้ authenticated (gh auth login)
Agent runs but no commentตรวจสอบ gateway log - หาก output ของ agent ว่างเปล่าหรือแค่ "SKIP", การส่ง delivery ก็ยังถูกพยายาม
Port already in useเปลี่ยน extra.port ใน config.yaml
Agent runs but reviews only the PR descriptionprompt ไม่ได้รวมคำสั่ง gh pr diff - เพราะ diff ไม่อยู่ใน webhook payload
Can't see the ping eventเหตุการณ์ที่ถูกเพิกเฉยจะคืนค่า {"status":"ignored","event":"ping"} ที่ระดับ log DEBUG เท่านั้น - ตรวจสอบ delivery log ของ GitHub (repo → Settings → Webhooks → your webhook → Recent Deliveries)

GitHub's Recent Deliveries tab (repo → Settings → Webhooks → your webhook) แสดง header request, payload, HTTP status, และ response body ที่แน่นอนสำหรับการส่งทุกครั้ง มันเป็นวิธีที่เร็วที่สุดในการวินิจฉัยความล้มเหลวโดยไม่ต้องแตะ server logs ของคุณ


Full config reference

platforms:
  webhook:
    enabled: true
    extra:
      host: "0.0.0.0"         # bind address (default: 0.0.0.0)
      port: 8644               # listen port (default: 8644)
      secret: ""               # optional global fallback secret
      rate_limit: 30           # requests per minute per route
      max_body_bytes: 1048576  # payload size limit in bytes (default: 1 MB)

      routes:
        <route-name>:
          secret: "required-per-route"
          events: []            # [] = accept all; otherwise list X-GitHub-Event values
          prompt: ""            # {field} / {nested.field} resolved from payload
          skills: []            # first matching skill is loaded (only one)
          deliver: "log"        # log | github_comment | telegram | discord | slack | signal | sms
          deliver_extra: {}     # repo + pr_number for github_comment; chat_id for others

What's Next?


📄 guides/work-with-skills.md


sidebar_position: 12 title: "Working with Skills" description: "Find, install, use, and create skills - on-demand knowledge that teaches Hermes new workflows"

Working with Skills

Skills คือเอกสารความรู้แบบ on-demand ที่สอนให้ Hermes จัดการงานเฉพาะอย่างได้ ตั้งแต่การสร้าง ASCII art ไปจนถึงการจัดการ GitHub PRs คู่มือนี้จะแนะนำวิธีการใช้งานในชีวิตประจำวัน

สำหรับข้อมูลอ้างอิงทางเทคนิคฉบับเต็ม ดูได้ที่ Skills System


Finding Skills

การติดตั้ง Hermes ทุกครั้งจะมาพร้อมกับ skills ที่รวมไว้แล้ว ดูว่ามีอะไรบ้าง:

# In any chat session:
/skills

# Or from the CLI:
hermes skills list

สิ่งนี้จะแสดงรายการแบบย่อพร้อมชื่อและคำอธิบาย:

ascii-art         Generate ASCII art using pyfiglet, cowsay, boxes...
arxiv             Search and retrieve academic papers from arXiv...
github-pr-workflow Full PR lifecycle - create branches, commit...
plan              Plan mode - inspect context, write a markdown...
excalidraw        Create hand-drawn style diagrams using Excalidraw...

Searching for a Skill

# Search by keyword
/skills search docker
/skills search music

The Skills Hub

official optional skills (skills ที่มีขนาดใหญ่ขึ้นหรือเฉพาะทาง ซึ่งไม่ได้เปิดใช้งานโดยค่าเริ่มต้น) สามารถเข้าถึงได้ผ่าน Hub:

# Browse official optional skills
/skills browse

# Search the hub
/skills search blockchain

Using a Skill

skills ที่ติดตั้งทุกตัวจะเป็น slash command โดยอัตโนมัติ เพียงแค่พิมพ์ชื่อของมัน:

# Load a skill and give it a task
/ascii-art Make a banner that says "HELLO WORLD"
/plan Design a REST API for a todo app
/github-pr-workflow Create a PR for the auth refactor

# Just the skill name (no task) loads it and lets you describe what you need
/excalidraw

คุณยังสามารถเรียกใช้ skills ผ่านการสนทนาแบบธรรมชาติได้ด้วย - เพียงแค่ขอให้ Hermes ใช้ skills เฉพาะตัว มันก็จะโหลดผ่านเครื่องมือ skill_view

Progressive Disclosure

Skills ใช้รูปแบบการโหลดที่ประหยัด token ตัว agent จะไม่โหลดทุกอย่างพร้อมกัน:

  1. skills_list() - รายการย่อของ skills ทั้งหมด (~3k tokens) โหลดเมื่อเริ่ม session
  2. skill_view(name) - เนื้อหา SKILL.md ฉบับเต็มสำหรับ skills หนึ่งตัว โหลดเมื่อ agent ตัดสินใจว่าต้องการ skills นั้น
  3. skill_view(name, file_path) - ไฟล์อ้างอิงเฉพาะภายใน skills โหลดก็ต่อเมื่อจำเป็นเท่านั้น

นั่นหมายความว่า skills จะไม่เสีย token จนกว่าจะถูกใช้งานจริง


Installing from the Hub

official optional skills มาพร้อมกับ Hermes แต่ไม่ได้เปิดใช้งานโดยค่าเริ่มต้น คุณต้องติดตั้งอย่างชัดเจน:

# Install an official optional skill
hermes skills install official/research/arxiv

# Install from the hub in a chat session
/skills install official/creative/songwriting-and-ai-music

สิ่งที่เกิดขึ้น:

  1. ไดเรกทอรี skills จะถูกคัดลอกไปยัง ~/.hermes/skills/
  2. มันจะปรากฏใน output ของ skills_list ของคุณ
  3. มันจะพร้อมใช้งานเป็น slash command

:::tip installed skills จะมีผลใน session ใหม่ หากต้องการให้ใช้งานได้ใน session ปัจจุบัน ให้ใช้ /reset เพื่อเริ่มใหม่ หรือเพิ่ม --now เพื่อทำให้ prompt cache ไม่ถูกต้องทันที (จะเสีย token มากขึ้นใน turn ถัดไป) :::

Verifying Installation

# Check it's there
hermes skills list | grep arxiv

# Or in chat
/skills search arxiv

Plugin-Provided Skills

Plugins สามารถรวม skills ของตัวเองโดยใช้ namespaced names (plugin:skill) ซึ่งป้องกันการชนกันของชื่อกับ skills ที่ติดตั้งมาให้แล้ว

# Load a plugin skill by its qualified name
skill_view("superpowers:writing-plans")

# Built-in skill with the same base name is unaffected
skill_view("writing-plans")

skills ของ Plugin จะ ไม่ ถูกระบุใน system prompt และไม่ปรากฏใน skills_list พวกมันเป็นแบบ opt-in - ให้โหลดอย่างชัดเจนเมื่อคุณรู้ว่า plugin ตัวใดตัวหนึ่งมีให้ เมื่อโหลดแล้ว agent จะเห็น banner ที่แสดงรายการ skills อื่นๆ จาก plugin เดียวกัน

สำหรับวิธีการรวม skills ใน plugin ของคุณ ดูได้ที่ Build a Hermes Plugin → Bundle skills


Configuring Skill Settings

skills บางตัวจะประกาศการตั้งค่าที่ต้องการใน frontmatter ของมัน:

metadata:
  hermes:
    config:
      - key: tenor.api_key
        description: "Tenor API key for GIF search"
        prompt: "Enter your Tenor API key"
        url: "https://developers.google.com/tenor/guides/quickstart"

เมื่อมีการโหลด skills ที่มี config เป็นครั้งแรก Hermes จะแจ้งให้คุณระบุค่าเหล่านั้น ค่าเหล่านี้จะถูกจัดเก็บใน config.yaml ภายใต้ skills.config.*

จัดการ config ของ skills จาก CLI:

# Interactive config for a specific skill
hermes skills config gif-search

# View all skill config
hermes config get skills.config

Creating Your Own Skill

Skills เป็นเพียงไฟล์ markdown ที่มี YAML frontmatter การสร้างนั้นใช้เวลาไม่ถึงห้านาที

1. Create the Directory

mkdir -p ~/.hermes/skills/my-category/my-skill

2. Write SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
metadata:
  hermes:
    tags: [my-tag, automation]
    category: my-category
---

# My Skill

## When to Use
Use this skill when the user asks about [specific topic] or needs to [specific task].

## Procedure
1. First, check if [prerequisite] is available
2. Run `command --with-flags`
3. Parse the output and present results

## Pitfalls
- Common failure: [description]. Fix: [solution]
- Watch out for [edge case]

## Verification
Run `check-command` to confirm the result is correct.

3. Add Reference Files (Optional)

Skills สามารถรวมไฟล์สนับสนุนที่ agent โหลดเมื่อจำเป็นได้:

my-skill/
├── SKILL.md                    # Main skill document
├── references/
│   ├── api-docs.md             # API reference the agent can consult
│   └── examples.md             # Example inputs/outputs
├── templates/
│   └── config.yaml             # Template files the agent can use
└── scripts/
    └── setup.sh                # Scripts the agent can execute

อ้างอิงสิ่งเหล่านี้ใน SKILL.md ของคุณ:

For API details, load the reference: `skill_view("my-skill", "references/api-docs.md")`

4. Test It

เริ่ม session ใหม่และลองใช้ skill ของคุณ:

hermes chat -q "/my-skill help me with the thing"

skill จะปรากฏโดยอัตโนมัติ - ไม่ต้องลงทะเบียน แค่ใส่ไว้ใน ~/.hermes/skills/ ก็ใช้งานได้แล้ว

:::info agent ยังสามารถสร้างและอัปเดต skills ได้ด้วยตัวเองโดยใช้ skill_manage หลังจากแก้ปัญหาที่ซับซ้อนเสร็จแล้ว Hermes อาจเสนอให้บันทึกแนวทางนั้นเป็น skill สำหรับครั้งต่อไป ตอบตกลง - skills ที่สร้างโดย agent เหล่านี้จะบันทึก workflow ที่แม่นยำ รวมถึง pitfalls ที่ค้นพบระหว่างทาง :::


Per-Platform Skill Management

ควบคุมว่า skills ใดบ้างที่พร้อมใช้งานบนแพลตฟอร์มใด:

hermes skills

สิ่งนี้จะเปิด TUI แบบโต้ตอบที่คุณสามารถเปิดหรือปิด skills ตามแพลตฟอร์ม (CLI, Telegram, Discord, ฯลฯ) มีประโยชน์เมื่อคุณต้องการให้ skills บางตัวใช้งานได้เฉพาะในบริบทที่กำหนดเท่านั้น - ตัวอย่างเช่น การเก็บ development skills ให้ห่างจาก Telegram


Skills vs Memory

ทั้งสองอย่างมีความคงอยู่ข้าม session แต่มีวัตถุประสงค์ที่แตกต่างกัน:

SkillsMemory
WhatProcedural knowledge - how to do thingsFactual knowledge - what things are
WhenLoaded on demand, only when relevantInjected into every session automatically
SizeCan be large (hundreds of lines)Should be compact (key facts only)
CostZero tokens until loadedSmall but constant token cost
Examples"How to deploy to Kubernetes""User prefers dark mode, lives in PST"
Who createsYou, the agent, or installed from HubThe agent, based on conversations

กฎง่ายๆ: ถ้าคุณจะใส่ไว้ในเอกสารอ้างอิง มันคือ skill ถ้าคุณจะแปะไว้บนโพสต์อิท มันคือ memory


Tips

ให้ skills มีความเฉพาะเจาะจง skills ที่พยายามครอบคลุม "DevOps ทั้งหมด" จะยาวเกินไปและคลุมเครือเกินไป skills ที่ครอบคลุม "การ deploy Python app ไปยัง Fly.io" นั้นเฉพาะเจาะจงพอที่จะมีประโยชน์จริง

ให้ agent สร้าง skills หลังจากทำงานหลายขั้นตอนที่ซับซ้อน Hermes มักจะเสนอให้บันทึกแนวทางนั้นเป็น skill ตอบตกลง - skills ที่สร้างโดย agent เหล่านี้จะบันทึก workflow ที่แม่นยำ รวมถึง pitfalls ที่ค้นพบระหว่างทาง

ใช้ categories จัดระเบียบ skills เป็น subdirectories (~/.hermes/skills/devops/, ~/.hermes/skills/research/, ฯลฯ) สิ่งนี้ช่วยให้รายการจัดการได้ง่ายและช่วยให้ agent ค้นหา skills ที่เกี่ยวข้องได้เร็วขึ้น

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


สำหรับข้อมูลอ้างอิง skills ฉบับสมบูรณ์ - fields ของ frontmatter, conditional activation, external directories, และอื่นๆ - ดูได้ที่ Skills System.


extent analysis

TL;DR

The issue seems to be related to the configuration and usage of Hermes Agent, a conversational AI tool, specifically with its skills system, GitHub PR review feature, and voice mode, but the exact problem is unclear due to the large amount of provided context.

Guidance

  1. Clarify the Issue: Identify the specific problem or error encountered with Hermes Agent, such as issues with skills, GitHub PR reviews, or voice mode.
  2. Check Configuration: Verify that the configuration files (e.g., config.yaml) are correctly set up for the desired features, including skills, GitHub integration, and voice mode.
  3. Review Documentation: Consult the official Hermes Agent documentation and guides for setting up and using skills, GitHub PR reviews, and voice mode to ensure all steps were followed correctly.
  4. Test Isolated Features: Test each feature (skills, GitHub PR reviews, voice mode) in isolation to identify if the issue is specific to one feature or a combination of them.

Example

Given the complexity and breadth of the provided information, a specific code example cannot be accurately provided without a clearer understanding of the issue. However, ensuring that the config.yaml file is correctly configured for the desired features is a good starting point.

Notes

  • The issue description lacks a clear problem statement, making it challenging to provide a precise solution.
  • Hermes Agent's features, such as skills and voice mode, require specific configurations and setups that must be correctly implemented to function as intended.
  • Consulting the official Hermes Agent documentation and seeking support from the community or developers may provide more targeted assistance.

Recommendation

Apply a systematic approach to troubleshooting by isolating and testing each feature individually to pinpoint the exact cause of the issue, and then refer to the official documentation or community support for tailored solutions.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - 💡(How to fix) Fix [i18n] Thai Translation: Guides Part d - use-soul-with-hermes, use-voice-mode-with-hermes, webhook-github-pr-review, work-with-skills [1 participants]