hermes-agent-optimization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hermes Agent Optimization

Hermes Agent优化

Skill by ara.so — Hermes Skills collection.

Hermes Agent is an autonomous AI agent framework that orchestrates LLM calls across 20+ platforms (Telegram, Discord, Slack, CLI, webhooks), integrates with MCP servers for tool access, supports multiple LLM providers (Anthropic, OpenAI, Google, local models), and includes durable execution features like Kanban boards and persistent goals.

This skill covers production deployment, multi-platform configuration, cost optimization, security hardening, skill creation, and troubleshooting based on the OnlyTerp/hermes-optimization-guide repository.

由ara.so提供的Skill — Hermes Skills合集。

Hermes Agent是一款自主AI Agent框架，可协调20+平台（Telegram、Discord、Slack、CLI、webhooks）的LLM调用，集成MCP服务器以实现工具访问，支持多个LLM提供商（Anthropic、OpenAI、Google、本地模型），并包含看板、持久化目标等持久执行功能。

本Skill基于OnlyTerp/hermes-optimization-guide仓库，涵盖生产环境部署、多平台配置、成本优化、安全加固、Skill创建及故障排查等内容。

Installation

安装

Quick Local Setup (5 minutes)

快速本地部署（5分钟）

bash

undefined

bash

undefined

Install Hermes (requires Node.js 18+)

安装Hermes（需要Node.js 18+）

npm install -g @nousresearch/hermes-agent

Initialize config directory

初始化配置目录

hermes init

Start interactive setup

启动交互式配置

hermes configure

undefined

hermes configure

undefined

Production VPS Setup (One Command)

生产环境VPS一键部署

For Debian 12 / Ubuntu 24.04:

bash

curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/main/scripts/vps-bootstrap.sh | sudo bash

This installs Hermes, Node.js, Caddy reverse proxy, UFW firewall, fail2ban, creates a

hermes

user, sets up systemd services, and symlinks all guide skills.

适用于Debian 12 / Ubuntu 24.04：

bash

curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/main/scripts/vps-bootstrap.sh | sudo bash

该脚本会安装Hermes、Node.js、Caddy反向代理、UFW防火墙、fail2ban，创建

hermes

用户，配置systemd服务，并关联指南中的所有Skill。

Manual Installation

手动安装

bash

undefined

bash

undefined

Install dependencies

安装依赖

sudo apt update && sudo apt install -y nodejs npm git curl

Install Hermes globally

全局安装Hermes

npm install -g @nousresearch/hermes-agent

Create hermes user (production)

创建hermes用户（生产环境）

sudo useradd -r -m -d /home/hermes -s /bin/bash hermes

Initialize config

初始化配置

sudo -u hermes hermes init

undefined

sudo -u hermes hermes init

undefined

Configuration Structure

配置结构

Hermes config lives at

~/.hermes/config.yaml

yaml

undefined

Hermes配置文件位于

~/.hermes/config.yaml

：

yaml

undefined

Minimal working config

最简可用配置

providers: anthropic: api_key: ${ANTHROPIC_API_KEY} default_model: claude-3-5-sonnet-20241022

gateways: telegram: token: ${TELEGRAM_BOT_TOKEN} enabled: true

memory: provider: lightrag storage_path: ~/.hermes/memory

skills: directory: ~/.hermes/skills auto_load: true

security: redact_secrets: true approval_mode: auto

undefined

providers: anthropic: api_key: ${ANTHROPIC_API_KEY} default_model: claude-3-5-sonnet-20241022

gateways: telegram: token: ${TELEGRAM_BOT_TOKEN} enabled: true

memory: provider: lightrag storage_path: ~/.hermes/memory

skills: directory: ~/.hermes/skills auto_load: true

security: redact_secrets: true approval_mode: auto

undefined

Environment Variables

环境变量

Create

~/.hermes/.env

bash

undefined

创建

~/.hermes/.env

文件：

bash

undefined

LLM Providers

LLM提供商

ANTHROPIC_API_KEY=your_key_here OPENAI_API_KEY=your_key_here GOOGLE_API_KEY=your_key_here

Platforms

平台配置

TELEGRAM_BOT_TOKEN=your_bot_token DISCORD_BOT_TOKEN=your_discord_token SLACK_BOT_TOKEN=xoxb-your-slack-token

Observability

可观测性配置

LANGFUSE_SECRET_KEY=your_langfuse_key LANGFUSE_PUBLIC_KEY=your_public_key LANGFUSE_HOST=https://cloud.langfuse.com

Optional: Cost optimization

可选：成本优化配置

DEEPSEEK_API_KEY=your_deepseek_key CEREBRAS_API_KEY=your_cerebras_key

undefined

DEEPSEEK_API_KEY=your_deepseek_key CEREBRAS_API_KEY=your_cerebras_key

undefined

Key Commands

核心命令

Starting Hermes

启动Hermes

bash

undefined

bash

undefined

Interactive TUI mode

交互式TUI模式

hermes

Headless daemon (production)

无头守护进程（生产环境）

hermes daemon

Web dashboard (runs on http://localhost:3000)

Web仪表盘（运行在http://localhost:3000）

hermes dashboard

Specific gateway only

仅启动指定网关

hermes --gateway telegram

Debug mode with verbose logging

调试模式（详细日志）

DEBUG=hermes:* hermes daemon

undefined

DEBUG=hermes:* hermes daemon

undefined

Management Commands

管理命令

bash

undefined

bash

undefined

Update to latest version

更新至最新版本

hermes update

Run skill curator (grade and clean skills)

运行Skill管理器（评分并清理Skill）

hermes curator

Backup configuration and data

备份配置与数据

hermes backup --output ~/hermes-backup-$(date +%F).tar.gz

Test configuration without starting

验证配置（无需启动服务）

hermes validate

List active sessions

列出活跃会话

hermes sessions list

Clear all memory (DESTRUCTIVE)

清空所有内存（操作不可逆）

hermes memory clear

undefined

hermes memory clear

undefined

Systemd Service (Production)

Systemd服务配置（生产环境）

bash

undefined

bash

undefined

Install service

安装服务

sudo cp /path/to/templates/systemd/hermes.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable hermes sudo systemctl start hermes

View logs

查看日志

sudo journalctl -u hermes -f

Restart after config changes

修改配置后重启服务

sudo systemctl restart hermes

undefined

sudo systemctl restart hermes

undefined

Setting Up Platforms

平台配置

Telegram Bot

Telegram机器人

Create bot with @BotFather
Get token and add to
```
.env
```
Configure in
```
config.yaml
```
:

yaml

gateways:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users:
      - 123456789  # Your Telegram user ID
    features:
      voice_enabled: true
      document_upload: true
      inline_mode: true

通过@BotFather创建机器人
获取token并添加至
```
.env
```
在
```
config.yaml
```
中配置：

yaml

gateways:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users:
      - 123456789  # 你的Telegram用户ID
    features:
      voice_enabled: true
      document_upload: true
      inline_mode: true

Discord Bot

Discord机器人

Create application at Discord Developer Portal
Enable Message Content Intent
Configure:

yaml

gateways:
  discord:
    enabled: true
    token: ${DISCORD_BOT_TOKEN}
    command_prefix: "!"
    allowed_roles:
      - "AI Assistant Users"
    allowed_guilds:
      - "1234567890123456789"

在Discord开发者平台创建应用
启用消息内容权限
配置：

yaml

gateways:
  discord:
    enabled: true
    token: ${DISCORD_BOT_TOKEN}
    command_prefix: "!"
    allowed_roles:
      - "AI Assistant Users"
    allowed_guilds:
      - "1234567890123456789"

Slack App

Slack应用

yaml

gateways:
  slack:
    enabled: true
    bot_token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}
    signing_secret: ${SLACK_SIGNING_SECRET}
    socket_mode: true

yaml

gateways:
  slack:
    enabled: true
    bot_token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}
    signing_secret: ${SLACK_SIGNING_SECRET}
    socket_mode: true

CLI (Always Available)

CLI（默认可用）

bash

undefined

bash

undefined

Direct CLI conversation

直接通过CLI对话

hermes chat "explain quantum computing"

Pipe input

管道输入

echo "summarize this" | hermes chat

File processing

文件处理

hermes chat "analyze this code" < script.py

undefined

hermes chat "analyze this code" < script.py

undefined

Model Routing & Cost Optimization

模型路由与成本优化

Smart Router Configuration

智能路由配置

yaml

models:
  router:
    enabled: true
    strategy: cost_optimized  # or: balanced, performance, local_first
    
  profiles:
    cheap:
      provider: cerebras
      model: llama-3.3-70b
      max_context: 8192
      cost_per_1m_tokens: 0.60
      
    balanced:
      provider: anthropic
      model: claude-3-5-haiku-20241022
      max_context: 200000
      cost_per_1m_tokens: 1.00
      
    premium:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      max_context: 200000
      cost_per_1m_tokens: 3.00
      
    local:
      provider: lm_studio
      model: qwen-2.5-coder-32b
      endpoint: http://localhost:1234/v1
      max_context: 32768
      
  routing_rules:
    - if: "token_count < 2000"
      use: cheap
    - if: "requires_code_execution"
      use: premium
    - if: "user_priority == high"
      use: premium
    - default: balanced

yaml

models:
  router:
    enabled: true
    strategy: cost_optimized  # 可选：balanced, performance, local_first
    
  profiles:
    cheap:
      provider: cerebras
      model: llama-3.3-70b
      max_context: 8192
      cost_per_1m_tokens: 0.60
      
    balanced:
      provider: anthropic
      model: claude-3-5-haiku-20241022
      max_context: 200000
      cost_per_1m_tokens: 1.00
      
    premium:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      max_context: 200000
      cost_per_1m_tokens: 3.00
      
    local:
      provider: lm_studio
      model: qwen-2.5-coder-32b
      endpoint: http://localhost:1234/v1
      max_context: 32768
      
  routing_rules:
    - if: "token_count < 2000"
      use: cheap
    - if: "requires_code_execution"
      use: premium
    - if: "user_priority == high"
      use: premium
    - default: balanced

Provider Setup Examples

提供商配置示例

Anthropic (Claude):

yaml

providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-sonnet-20241022
    max_tokens: 4096
    temperature: 0.7

OpenAI:

yaml

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    default_model: gpt-4o-2024-11-20
    organization: ${OPENAI_ORG_ID}

Google (Gemini):

yaml

providers:
  google:
    api_key: ${GOOGLE_API_KEY}
    default_model: gemini-2.0-flash-exp
    safety_settings:
      harassment: BLOCK_NONE
      hate_speech: BLOCK_NONE

Local LM Studio:

yaml

providers:
  lm_studio:
    endpoint: http://localhost:1234/v1
    default_model: qwen-2.5-coder-32b-instruct
    timeout: 300000

Anthropic (Claude):

yaml

providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-sonnet-20241022
    max_tokens: 4096
    temperature: 0.7

OpenAI:

yaml

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    default_model: gpt-4o-2024-11-20
    organization: ${OPENAI_ORG_ID}

Google (Gemini):

yaml

providers:
  google:
    api_key: ${GOOGLE_API_KEY}
    default_model: gemini-2.0-flash-exp
    safety_settings:
      harassment: BLOCK_NONE
      hate_speech: BLOCK_NONE

本地LM Studio:

yaml

providers:
  lm_studio:
    endpoint: http://localhost:1234/v1
    default_model: qwen-2.5-coder-32b-instruct
    timeout: 300000

MCP Server Integration

MCP Server集成

MCP (Model Context Protocol) servers provide tools/resources to Hermes.

MCP（Model Context Protocol）服务器为Hermes提供工具/资源支持。

Configuration

配置

yaml

mcp:
  servers:
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/home/user/projects"
      transport: stdio
      
    github:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
      transport: stdio
      
    brave_search:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: ${BRAVE_API_KEY}
      transport: stdio
      
    postgres:
      command: docker
      args:
        - "run"
        - "-i"
        - "--rm"
        - "mcp/postgres"
      env:
        DATABASE_URL: ${DATABASE_URL}
      transport: stdio

yaml

mcp:
  servers:
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/home/user/projects"
      transport: stdio
      
    github:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
      transport: stdio
      
    brave_search:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: ${BRAVE_API_KEY}
      transport: stdio
      
    postgres:
      command: docker
      args:
        - "run"
        - "-i"
        - "--rm"
        - "mcp/postgres"
      env:
        DATABASE_URL: ${DATABASE_URL}
      transport: stdio

Testing MCP Servers

测试MCP服务器

bash

undefined

bash

undefined

List available MCP tools

列出可用MCP工具

hermes mcp list

Test specific server

测试指定服务器

hermes mcp test filesystem

Interactive MCP inspector

交互式MCP检查器

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

undefined

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

undefined

Creating Custom Skills

创建自定义Skill

Skills live in

~/.hermes/skills/

as markdown files.

Skill以markdown文件形式存储在

~/.hermes/skills/

目录下。

Skill Template

Skill模板

markdown

---
name: example-skill
description: Does something useful
triggers:
  - "how do I use example"
  - "explain example tool"
dependencies:
  - "example-npm-package"
---

markdown

---
name: example-skill
description: Does something useful
triggers:
  - "how do I use example"
  - "explain example tool"
dependencies:
  - "example-npm-package"
---

Example Skill

What it does

Brief explanation.

Usage

bash

npm install example-npm-package

javascript

const example = require('example-npm-package');
example.doThing();

bash

npm install example-npm-package

javascript

const example = require('example-npm-package');
example.doThing();

Common patterns

Pattern 1
Pattern 2

undefined

Pattern 1
Pattern 2

undefined

Installing Skills from Guide

从指南安装Skill

bash

undefined

bash

undefined

Clone the optimization guide

克隆优化指南仓库

git clone https://github.com/OnlyTerp/hermes-optimization-guide.git

Symlink all guide skills

关联指南中的所有Skill

ln -s $(pwd)/hermes-optimization-guide/skills/* ~/.hermes/skills/

Or individual skill

或仅关联单个Skill

ln -s $(pwd)/hermes-optimization-guide/skills/mcp-filesystem.md ~/.hermes/skills/

undefined

ln -s $(pwd)/hermes-optimization-guide/skills/mcp-filesystem.md ~/.hermes/skills/

undefined

Skill Curator

Skill管理器

bash

undefined

bash

undefined

Run curator to grade and clean skills

运行管理器对Skill进行评分和清理

hermes curator

Curator runs automatically every 7 days by default

管理器默认每7天自动运行一次

Configure in config.yaml:

在config.yaml中配置：

curator: enabled: true schedule: "0 3 * * 0" # Weekly Sunday 3am grade_threshold: 6 # Archive skills below this score review_provider: anthropic review_model: claude-3-5-haiku-20241022

undefined

curator: enabled: true schedule: "0 3 * * 0" # 每周日凌晨3点 grade_threshold: 6 # 归档评分低于此值的Skill review_provider: anthropic review_model: claude-3-5-haiku-20241022

undefined

Durable Execution Features

持久执行功能

Kanban Boards (v0.13+)

看板（v0.13+）

yaml

tenacity:
  kanban:
    enabled: true
    boards:
      - name: development
        lanes:
          - todo
          - in_progress
          - review
          - done
        heartbeat_interval: 60
        retry_budget: 3
        
  checkpoints:
    enabled: true
    directory: ~/.hermes/checkpoints
    max_size_mb: 500
    pruning:
      enabled: true
      keep_last_n: 10

Usage:

User: "Add feature X to project Y and deploy"
Agent creates Kanban card → moves through lanes → reports status

yaml

tenacity:
  kanban:
    enabled: true
    boards:
      - name: development
        lanes:
          - todo
          - in_progress
          - review
          - done
        heartbeat_interval: 60
        retry_budget: 3
        
  checkpoints:
    enabled: true
    directory: ~/.hermes/checkpoints
    max_size_mb: 500
    pruning:
      enabled: true
      keep_last_n: 10

使用示例：

用户："为项目Y添加功能X并部署"
Agent创建看板卡片 → 按阶段移动 → 汇报状态

Persistent Goals

持久化目标

/goal set "Deploy the new API endpoint to production"
/goal list
/goal pause goal_abc123
/goal resume goal_abc123
/goal clear goal_abc123

Goals persist across sessions and keep the agent focused until completion.

/goal set "Deploy the new API endpoint to production"
/goal list
/goal pause goal_abc123
/goal resume goal_abc123
/goal clear goal_abc123

目标会跨会话保存，确保Agent专注完成任务。

Cron Jobs (No-Agent Watchdogs)

Cron任务（无Agent监控）

yaml

cron:
  jobs:
    - name: disk_space_check
      schedule: "*/30 * * * *"  # Every 30 min
      command: "df -h | grep -E '9[0-9]%|100%'"
      no_agent: true  # Just run command, don't involve LLM
      alert_on: stderr
      
    - name: backup
      schedule: "0 2 * * *"  # Daily 2am
      command: "hermes backup --output /backups/hermes-$(date +%F).tar.gz"
      no_agent: true

yaml

cron:
  jobs:
    - name: disk_space_check
      schedule: "*/30 * * * *"  # 每30分钟
      command: "df -h | grep -E '9[0-9]%|100%'"
      no_agent: true  # 仅执行命令，不调用LLM
      alert_on: stderr
      
    - name: backup
      schedule: "0 2 * * *"  # 每日凌晨2点
      command: "hermes backup --output /backups/hermes-$(date +%F).tar.gz"
      no_agent: true

Security Configuration

安全配置

Production Security Settings

生产环境安全设置

yaml

security:
  # Redact secrets in logs (default: true in v0.13+)
  redact_secrets: true
  
  # Approval modes: auto, manual, quarantine
  approval_mode: manual
  
  # Tool restrictions
  tool_allowlist:
    - read_file
    - write_file
    - execute_command
    - mcp_*
    
  tool_denylist:
    - dangerous_tool
    
  # Command execution sandbox
  sandbox:
    enabled: true
    allowed_directories:
      - /home/hermes/workspace
      - /tmp/hermes
    forbidden_commands:
      - rm -rf /
      - dd if=
      - mkfs
      
  # Rate limiting
  rate_limits:
    requests_per_minute: 60
    tokens_per_hour: 500000
    
  # Webhook signature verification
  webhooks:
    require_signatures: true
    allowed_ips:
      - 192.168.1.0/24

yaml

security:
  # 日志中自动脱敏敏感信息（v0.13+默认开启）
  redact_secrets: true
  
  # 审批模式：auto, manual, quarantine
  approval_mode: manual
  
  # 工具权限白名单
  tool_allowlist:
    - read_file
    - write_file
    - execute_command
    - mcp_*
    
  tool_denylist:
    - dangerous_tool
    
  # 命令执行沙箱
  sandbox:
    enabled: true
    allowed_directories:
      - /home/hermes/workspace
      - /tmp/hermes
    forbidden_commands:
      - rm -rf /
      - dd if=
      - mkfs
      
  # 速率限制
  rate_limits:
    requests_per_minute: 60
    tokens_per_hour: 500000
    
  # Webhook签名验证
  webhooks:
    require_signatures: true
    allowed_ips:
      - 192.168.1.0/24

Platform-Specific Security

平台专属安全配置

Telegram:

yaml

gateways:
  telegram:
    allowed_users:
      - 123456789
    block_groups: true  # Only allow DMs
    require_authorization: true

Discord:

yaml

gateways:
  discord:
    allowed_roles:
      - "Admin"
      - "Developer"
    allowed_guilds:
      - "1234567890"  # Specific server ID
    reject_dms: true

Webhooks:

yaml

gateways:
  webhook:
    port: 3001
    path: /webhook
    secret: ${WEBHOOK_SECRET}
    verify_signatures: true
    require_api_key: true
    api_keys:
      - ${WEBHOOK_API_KEY_1}

Telegram:

yaml

gateways:
  telegram:
    allowed_users:
      - 123456789
    block_groups: true  # 仅允许私聊
    require_authorization: true

Discord:

yaml

gateways:
  discord:
    allowed_roles:
      - "Admin"
      - "Developer"
    allowed_guilds:
      - "1234567890"  # 指定服务器ID
    reject_dms: true

Webhooks:

yaml

gateways:
  webhook:
    port: 3001
    path: /webhook
    secret: ${WEBHOOK_SECRET}
    verify_signatures: true
    require_api_key: true
    api_keys:
      - ${WEBHOOK_API_KEY_1}

Observability & Monitoring

可观测性与监控

Langfuse Integration

Langfuse集成

yaml

observability:
  langfuse:
    enabled: true
    public_key: ${LANGFUSE_PUBLIC_KEY}
    secret_key: ${LANGFUSE_SECRET_KEY}
    host: https://cloud.langfuse.com
    trace_all: true
    capture_io: true
    
  logging:
    level: info  # debug, info, warn, error
    file: ~/.hermes/logs/hermes.log
    max_size_mb: 100
    max_files: 10

yaml

observability:
  langfuse:
    enabled: true
    public_key: ${LANGFUSE_PUBLIC_KEY}
    secret_key: ${LANGFUSE_SECRET_KEY}
    host: https://cloud.langfuse.com
    trace_all: true
    capture_io: true
    
  logging:
    level: info  # 可选：debug, info, warn, error
    file: ~/.hermes/logs/hermes.log
    max_size_mb: 100
    max_files: 10

Prometheus Metrics

Prometheus指标

yaml

observability:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

Key metrics:

```
hermes_requests_total
```
- Total requests by platform/status
```
hermes_tokens_used
```
- Token consumption by model
```
hermes_cost_usd
```
- Estimated cost
```
hermes_latency_seconds
```
- Response times

yaml

observability:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

核心指标：

```
hermes_requests_total
```
- 按平台/状态统计的总请求数
```
hermes_tokens_used
```
- 各模型的Token消耗
```
hermes_cost_usd
```
- 估算成本
```
hermes_latency_seconds
```
- 响应时间

Dashboard Analytics

仪表盘分析

Access at

http://localhost:3000

after running

hermes dashboard

Real-time session view
Token/cost tracking
Model performance comparison
Platform activity charts
Skill usage statistics
Error rate monitoring

运行

hermes dashboard

后，访问

http://localhost:3000

：

实时会话视图
Token/成本追踪
模型性能对比
平台活动图表
Skill使用统计
错误率监控

Troubleshooting

故障排查

Common Issues

常见问题

1. "Cannot find module '@nousresearch/hermes-agent'"

bash

undefined

1. "Cannot find module '@nousresearch/hermes-agent'"

bash

undefined

Reinstall globally

重新全局安装

npm uninstall -g @nousresearch/hermes-agent npm install -g @nousresearch/hermes-agent

Or use npx

或使用npx

npx @nousresearch/hermes-agent


**2. Telegram bot not responding**
```bash

npx @nousresearch/hermes-agent


**2. Telegram机器人无响应**
```bash

Check token validity

验证token有效性

curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe

Verify webhook isn't set (conflicts with polling)

确认未设置webhook（与轮询冲突）

curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook

Check logs

查看日志

DEBUG=hermes:telegram hermes daemon


**3. MCP server connection fails**
```bash

DEBUG=hermes:telegram hermes daemon


**3. MCP服务器连接失败**
```bash

Test server directly

直接测试服务器

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Check permissions

检查权限

ls -la ~/.hermes/mcp-servers/

Verify environment variables

验证环境变量

env | grep -E 'GITHUB|BRAVE|DATABASE'


**4. Out of memory errors**
```yaml

env | grep -E 'GITHUB|BRAVE|DATABASE'


**4. 内存不足错误**
```yaml

Reduce context window

缩小上下文窗口

providers: anthropic: max_tokens: 2048 # Down from 4096

providers: anthropic: max_tokens: 2048 # 从4096下调

Enable context compression

启用上下文压缩

memory: compression: enabled: true target_tokens: 4000


**5. High costs**
```bash

memory: compression: enabled: true target_tokens: 4000


**5. 成本过高**
```bash

Check token usage

查看Token使用情况

hermes stats

Enable cost-optimized routing

启用成本优化路由

models: router: strategy: cost_optimized

Use local models for simple tasks

简单任务使用本地模型

providers: lm_studio: default_model: qwen-2.5-coder-32b-instruct


**6. Skills not loading**
```bash

providers: lm_studio: default_model: qwen-2.5-coder-32b-instruct


**6. Skill无法加载**
```bash

Verify directory

验证目录

ls -la ~/.hermes/skills/

Check skill syntax

检查Skill语法

hermes validate ~/.hermes/skills/my-skill.md

Force reload

强制重新加载

hermes --reload-skills

undefined

hermes --reload-skills

undefined

Debug Mode

调试模式

bash

undefined

bash

undefined

Full debug output

完整调试输出

DEBUG=hermes:* hermes daemon

Specific subsystems

指定子系统调试

DEBUG=hermes:telegram,hermes:mcp hermes daemon

Save debug logs

保存调试日志

DEBUG=hermes:* hermes daemon 2>&1 | tee debug.log

undefined

DEBUG=hermes:* hermes daemon 2>&1 | tee debug.log

undefined

Validation Commands

验证命令

bash

undefined

bash

undefined

Validate config

验证配置

hermes validate

Test provider connectivity

测试提供商连接

hermes test-providers

Check MCP servers

检查MCP服务器

hermes mcp list

Verify skills

验证所有Skill

hermes skills validate-all

undefined

hermes skills validate-all

undefined

Real-World Patterns

实战模式

Pattern 1: Multi-Model Routing

模式1：多模型路由

yaml

undefined

yaml

undefined

Use cheap models for simple tasks, premium for complex

简单任务使用低成本模型，复杂任务使用高级模型

models: router: enabled: true rules: - if: "token_count < 1000 and !contains(user_input, 'code')" use: cerebras # $0.60/1M tokens - if: "contains(user_input, 'write code')" use: claude_sonnet - if: "contains(user_input, 'analyze image')" use: gemini_flash - default: claude_haiku

undefined

undefined

Pattern 2: Secure Webhook Handler

模式2：安全Webhook处理器

yaml

gateways:
  webhook:
    enabled: true
    port: 3001
    path: /webhook
    secret: ${WEBHOOK_SECRET}
    handlers:
      github:
        events:
          - push
          - pull_request
        action: "trigger_skill:github-pr-reviewer"
      stripe:
        verify_signature: true
        action: "trigger_skill:payment-processor"

yaml

gateways:
  webhook:
    enabled: true
    port: 3001
    path: /webhook
    secret: ${WEBHOOK_SECRET}
    handlers:
      github:
        events:
          - push
          - pull_request
        action: "trigger_skill:github-pr-reviewer"
      stripe:
        verify_signature: true
        action: "trigger_skill:payment-processor"

Pattern 3: Automated Code Review

模式3：自动化代码评审

yaml

cron:
  jobs:
    - name: review_prs
      schedule: "0 */2 * * *"  # Every 2 hours
      command: "hermes chat 'Review open GitHub PRs in repo org/project'"
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      
skills:
  # Link github-pr-reviewer.md skill

yaml

cron:
  jobs:
    - name: review_prs
      schedule: "0 */2 * * *"  # 每2小时
      command: "hermes chat 'Review open GitHub PRs in repo org/project'"
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      
skills:
  # 关联github-pr-reviewer.md Skill

Pattern 4: Cost-Optimized Local First

模式4：本地优先成本优化

yaml

models:
  router:
    strategy: local_first
    fallback_on_error: true
    
providers:
  lm_studio:
    endpoint: http://localhost:1234/v1
    default_model: qwen-2.5-coder-32b-instruct
    timeout: 60000
    
  anthropic:  # Fallback for complex tasks
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-haiku-20241022

yaml

models:
  router:
    strategy: local_first
    fallback_on_error: true
    
providers:
  lm_studio:
    endpoint: http://localhost:1234/v1
    default_model: qwen-2.5-coder-32b-instruct
    timeout: 60000
    
  anthropic:  # 复杂任务 fallback
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-haiku-20241022

Pattern 5: Multi-Platform Broadcast

模式5：多平台广播

bash

undefined

bash

undefined

Send message to all platforms

向所有平台发送消息

hermes broadcast "System maintenance in 10 minutes"

Platform-specific routing in config.yaml

在config.yaml中配置平台路由

gateways: telegram: broadcast_channels: - "@myteamupdates" discord: broadcast_channels: - "1234567890" # Channel ID slack: broadcast_channels: - "#general"

undefined

gateways: telegram: broadcast_channels: - "@myteamupdates" discord: broadcast_channels: - "1234567890" # 频道ID slack: broadcast_channels: - "#general"

undefined

Reference Architecture

参考架构

Solo Developer Setup:

Hermes on local machine
Telegram bot for mobile access
LM Studio for local models
MCP filesystem + GitHub servers
Monthly cost: ~$10 (API only)

Small Team Setup:

Hermes on VPS (Hetzner CX22)
Telegram + Discord + Slack
Claude Haiku primary, Cerebras fallback
Langfuse for observability
Monthly cost: ~$50 (VPS + API)

Production Setup:

Hermes cluster behind load balancer
All platforms enabled
Multi-region model routing
Langfuse + Prometheus + Grafana
Redis session storage
Automated backups to S3
Monthly cost: $200-500 (infrastructure + API)

独立开发者配置：

本地机器部署Hermes
Telegram机器人实现移动端访问
LM Studio运行本地模型
MCP文件系统 + GitHub服务器
月度成本：约$10（仅API费用）

小型团队配置：

VPS（Hetzner CX22）部署Hermes
Telegram + Discord + Slack多平台
主用Claude Haiku，备用Cerebras
Langfuse实现可观测性
月度成本：约$50（VPS + API）

生产环境配置：

负载均衡后的Hermes集群
启用所有平台
多区域模型路由
Langfuse + Prometheus + Grafana
Redis会话存储
自动备份至S3
月度成本：$200-500（基础设施 + API）

Additional Resources

额外资源

Quick Reference

快速参考

bash

undefined

bash

undefined

Essential commands

核心命令

hermes # Start TUI hermes daemon # Start headless hermes dashboard # Start web UI hermes update # Update to latest hermes curator # Grade skills hermes backup # Backup data hermes validate # Check config

hermes # 启动TUI hermes daemon # 启动无头服务 hermes dashboard # 启动Web UI hermes update # 更新至最新版本 hermes curator # 评分Skill hermes backup # 备份数据 hermes validate # 检查配置

Debugging

调试命令

DEBUG=hermes:* hermes daemon hermes test-providers hermes mcp list hermes sessions list

Management

管理命令

systemctl restart hermes journalctl -u hermes -f hermes stats

undefined

systemctl restart hermes journalctl -u hermes -f hermes stats

undefined