Hermes Agent 配置

配置、扩展或贡献 Hermes Agent 智能体

Hermes Agent

Hermes Agent 是 Nous Research 开发的开源 AI 智能体框架，可在终端、消息平台和 IDE 中运行。它与 Claude Code（Anthropic）、Codex（OpenAI）和 OpenClaw 属于同一类别——使用工具调用与系统交互的自主编码和任务执行智能体。Hermes 兼容任何 LLM 提供商（OpenRouter、Anthropic、OpenAI、DeepSeek、本地模型等 15+ 家），支持 Linux、macOS 和 WSL。

Hermes 的与众不同之处：

通过技能自我改进——Hermes 通过将可复用的流程保存为技能来从经验中学习。当它解决复杂问题、发现工作流或被纠正时，可以将这些知识持久化为技能文档，加载到后续会话中。技能随时间积累，使智能体在你的特定任务和环境中表现更好。

跨会话持久记忆——记住你是谁、你的偏好、环境细节和经验教训。可插拔的记忆后端（内置、Honcho、Mem0 等）让你自由选择记忆的工作方式。

多平台网关——同一个智能体可在 Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Email 等 10+ 个平台上运行，拥有完整的工具访问权限，而非仅限聊天。

提供商无关——可在工作流中途切换模型和提供商，无需更改其他配置。凭据池自动在多个 API 密钥间轮换。

Profile（配置文件）——运行多个独立的 Hermes 实例，各自拥有隔离的配置、会话、技能和记忆。

可扩展——支持插件、MCP 服务器、自定义工具、Webhook 触发器、Cron 定时任务以及完整的 Python 生态系统。

人们使用 Hermes 进行软件开发、研究、系统管理、数据分析、内容创作、家庭自动化，以及任何能从具有持久上下文和完整系统访问权限的 AI 智能体中受益的工作。

此技能帮助你高效使用 Hermes Agent——包括安装配置、功能设置、启动额外的智能体实例、排查问题、查找合适的命令和设置，以及在你需要扩展或贡献代码时理解系统的工作原理。

文档： https://hermes-agent.nousresearch.com/docs/

快速入门

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

# Interactive chat (default)
hermes

# Single query
hermes chat -q "What is the capital of France?"

# Setup wizard
hermes setup

# Change model/provider
hermes model

# Check health
hermes doctor

---

CLI 参考

全局标志

hermes [flags] [command]

  --version, -V             Show version
  --resume, -r SESSION      Resume session by ID or title
  --continue, -c [NAME]     Resume by name, or most recent session
  --worktree, -w            Isolated git worktree mode (parallel agents)
  --skills, -s SKILL        Preload skills (comma-separate or repeat)
  --profile, -p NAME        Use a named profile
  --yolo                    Skip dangerous command approval
  --pass-session-id         Include session ID in system prompt

不带子命令时默认执行 chat。

聊天

hermes chat [flags]
  -q, --query TEXT          Single query, non-interactive
  -m, --model MODEL         Model (e.g. anthropic/claude-sonnet-4)
  -t, --toolsets LIST       Comma-separated toolsets
  --provider PROVIDER       Force provider (openrouter, anthropic, nous, etc.)
  -v, --verbose             Verbose output
  -Q, --quiet               Suppress banner, spinner, tool previews
  --checkpoints             Enable filesystem checkpoints (/rollback)
  --source TAG              Session source tag (default: cli)

配置

hermes setup [section]      Interactive wizard (model|terminal|gateway|tools|agent)
hermes model                Interactive model/provider picker
hermes config               View current config
hermes config edit          Open config.yaml in $EDITOR
hermes config set KEY VAL   Set a config value
hermes config path          Print config.yaml path
hermes config env-path      Print .env path
hermes config check         Check for missing/outdated config
hermes config migrate       Update config with new options
hermes login [--provider P] OAuth login (nous, openai-codex)
hermes logout               Clear stored auth
hermes doctor [--fix]       Check dependencies and config
hermes status [--all]       Show component status

工具与技能

hermes tools                Interactive tool enable/disable (curses UI)
hermes tools list           Show all tools and status
hermes tools enable NAME    Enable a toolset
hermes tools disable NAME   Disable a toolset

hermes skills list          List installed skills
hermes skills search QUERY  Search the skills hub
hermes skills install ID    Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name)
hermes skills inspect ID    Preview without installing
hermes skills config        Enable/disable skills per platform
hermes skills check         Check for updates
hermes skills update        Update outdated skills
hermes skills uninstall N   Remove a hub skill
hermes skills publish PATH  Publish to registry
hermes skills browse        Browse all available skills
hermes skills tap add REPO  Add a GitHub repo as skill source

MCP 服务器

hermes mcp serve            Run Hermes as an MCP server
hermes mcp add NAME         Add an MCP server (--url or --command)
hermes mcp remove NAME      Remove an MCP server
hermes mcp list             List configured servers
hermes mcp test NAME        Test connection
hermes mcp configure NAME   Toggle tool selection

网关（消息平台）

hermes gateway run          Start gateway foreground
hermes gateway install      Install as background service
hermes gateway start/stop   Control the service
hermes gateway restart      Restart the service
hermes gateway status       Check status
hermes gateway setup        Configure platforms

支持的平台：Telegram、Discord、Slack、WhatsApp、Signal、Email、SMS、Matrix、Mattermost、Home Assistant、DingTalk、Feishu、WeCom、BlueBubbles（iMessage）、Weixin（WeChat）、API Server、Webhooks。Open WebUI 通过 API Server 适配器连接。

平台文档：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/

会话

hermes sessions list        List recent sessions
hermes sessions browse      Interactive picker
hermes sessions export OUT  Export to JSONL
hermes sessions rename ID T Rename a session
hermes sessions delete ID   Delete a session
hermes sessions prune       Clean up old sessions (--older-than N days)
hermes sessions stats       Session store statistics

Cron 任务

hermes cron list            List jobs (--all for disabled)
hermes cron create SCHED    Create: '30m', 'every 2h', '0 9 * * *'
hermes cron edit ID         Edit schedule, prompt, delivery
hermes cron pause/resume ID Control job state
hermes cron run ID          Trigger on next tick
hermes cron remove ID       Delete a job
hermes cron status          Scheduler status

Webhook

hermes webhook subscribe N  Create route at /webhooks/
hermes webhook list         List subscriptions
hermes webhook remove NAME  Remove a subscription
hermes webhook test NAME    Send a test POST

Profile

hermes profile list         List all profiles
hermes profile create NAME  Create (--clone, --clone-all, --clone-from)
hermes profile use NAME     Set sticky default
hermes profile delete NAME  Delete a profile
hermes profile show NAME    Show details
hermes profile alias NAME   Manage wrapper scripts
hermes profile rename A B   Rename a profile
hermes profile export NAME  Export to tar.gz
hermes profile import FILE  Import from archive

凭据池

hermes auth add             Interactive credential wizard
hermes auth list [PROVIDER] List pooled credentials
hermes auth remove P INDEX  Remove by provider + index
hermes auth reset PROVIDER  Clear exhaustion status

其他

hermes insights [--days N]  Usage analytics
hermes update               Update to latest version
hermes pairing list/approve/revoke  DM authorization
hermes plugins list/install/remove  Plugin management
hermes honcho setup/status  Honcho memory integration (requires honcho plugin)
hermes memory setup/status/off  Memory provider config
hermes completion bash|zsh  Shell completions
hermes acp                  ACP server (IDE integration)
hermes claw migrate         Migrate from OpenClaw
hermes uninstall            Uninstall Hermes

---

斜杠命令（会话内）

在交互式聊天会话中输入这些命令。新命令会经常

更新；如果下面的内容看起来过时了，请在会话中运行 /help 获取

权威列表，或查看 实时斜杠命令参考。

注册表源文件为 hermes_cli/commands.py — 每个消费方

（自动补全、Telegram 菜单、Slack 映射、/help）都从中派生。

会话控制

/new (/reset)        Fresh session
/clear               Clear screen + new session (CLI)
/retry               Resend last message
/undo                Remove last exchange
/title [name]        Name the session
/compress            Manually compress context
/stop                Kill background processes
/rollback [N]        Restore filesystem checkpoint
/snapshot [sub]      Create or restore state snapshots of Hermes config/state (CLI)
/background  Run prompt in background
/queue       Queue for next turn
/steer       Inject a message after the next tool call without interrupting
/agents (/tasks)     Show active agents and running tasks
/resume [name]       Resume a named session
/goal [text|sub]     Set a standing goal Hermes works on across turns until achieved
                     (subcommands: status, pause, resume, clear)
/redraw              Force a full UI repaint (CLI)

配置

/config              Show config (CLI)
/model [name]        Show or change model
/personality [name]  Set personality
/reasoning [level]   Set reasoning (none|minimal|low|medium|high|xhigh|show|hide)
/verbose             Cycle: off → new → all → verbose
/voice [on|off|tts]  Voice mode
/yolo                Toggle approval bypass
/busy [sub]          Control what Enter does while Hermes is working (CLI)
                     (subcommands: queue, steer, interrupt, status)
/indicator [style]   Pick the TUI busy-indicator style (CLI)
                     (styles: kaomoji, emoji, unicode, ascii)
/footer [on|off]     Toggle gateway runtime-metadata footer on final replies
/skin [name]         Change theme (CLI)
/statusbar           Toggle status bar (CLI)

工具与技能

/tools               Manage tools (CLI)
/toolsets            List toolsets (CLI)
/skills              Search/install skills (CLI)
/skill         Load a skill into session
/reload-skills       Re-scan ~/.hermes/skills/ for added/removed skills
/reload              Reload .env variables into the running session (CLI)
/reload-mcp          Reload MCP servers
/cron                Manage cron jobs (CLI)
/curator [sub]       Background skill maintenance (status, run, pin, archive, …)
/kanban [sub]        Multi-profile collaboration board (tasks, links, comments)
/plugins             List plugins (CLI)

网关

/approve             Approve a pending command (gateway)
/deny                Deny a pending command (gateway)
/restart             Restart gateway (gateway)
/sethome             Set current chat as home channel (gateway)
/update              Update Hermes to latest (gateway)
/topic [sub]         Enable or inspect Telegram DM topic sessions (gateway)
/platforms (/gateway) Show platform connection status (gateway)

实用工具

/branch (/fork)      Branch the current session
/fast                Toggle priority/fast processing
/browser             Open CDP browser connection
/history             Show conversation history (CLI)
/save                Save conversation to file (CLI)
/copy [N]            Copy the last assistant response to clipboard (CLI)
/paste               Attach clipboard image (CLI)
/image               Attach local image file (CLI)

信息

/help                Show commands
/commands [page]     Browse all commands (gateway)
/usage               Token usage
/insights [days]     Usage analytics
/gquota              Show Google Gemini Code Assist quota usage (CLI)
/status              Session info (gateway)
/profile             Active profile info
/debug               Upload debug report (system info + logs) and get shareable links

退出

/quit (/exit, /q)    Exit CLI

---

关键路径与配置

~/.hermes/config.yaml       Main configuration
~/.hermes/.env              API keys and secrets
$HERMES_HOME/skills/        Installed skills
~/.hermes/sessions/         Session transcripts
~/.hermes/logs/             Gateway and error logs
~/.hermes/auth.json         OAuth tokens and credential pools
~/.hermes/hermes-agent/     Source code (if git-installed)

Profile 使用 ~/.hermes/profiles//，目录结构相同。

配置段

通过 hermes config edit 或 hermes config set section.key value 编辑。

配置段

键选项

`model`

`default`, `provider`, `base_url`, `api_key`, `context_length`

`agent`

`max_turns` (90), `tool_use_enforcement`

`terminal`

`backend` (local/docker/ssh/modal), `cwd`, `timeout` (180)

`compression`

`enabled`, `threshold` (0.50), `target_ratio` (0.20)

`display`

`skin`, `tool_progress`, `show_reasoning`, `show_cost`

`stt`

`enabled`, `provider` (local/groq/openai/mistral)

`tts`

`provider` (edge/elevenlabs/openai/minimax/mistral/neutts)

`memory`

`memory_enabled`, `user_profile_enabled`, `provider`

`security`

`tirith_enabled`, `website_blocklist`

`delegation`

`model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort`

完整配置参考：https://hermes-agent.nousresearch.com/docs/user-guide/configuration

提供商

支持 20+ 家提供商。通过 hermes model 或 hermes setup 设置。

`checkpoints`

`enabled`, `max_snapshots` (50)

提供商

认证方式

密钥环境变量

OpenRouter

API 密钥

`OPENROUTER_API_KEY`

Anthropic

API 密钥

`ANTHROPIC_API_KEY`

Nous Portal

OAuth

`hermes auth`

OpenAI Codex

OAuth

`hermes auth`

GitHub Copilot

令牌

`COPILOT_GITHUB_TOKEN`

Google Gemini

API 密钥

`GOOGLE_API_KEY` or `GEMINI_API_KEY`

DeepSeek

API 密钥

`DEEPSEEK_API_KEY`

xAI / Grok

API 密钥

`XAI_API_KEY`

Hugging Face

令牌

`HF_TOKEN`

Z.AI / GLM

API 密钥

`GLM_API_KEY`

MiniMax

API 密钥

`MINIMAX_API_KEY`

MiniMax CN

API 密钥

`MINIMAX_CN_API_KEY`

Kimi / Moonshot

API 密钥

`KIMI_API_KEY`

Alibaba / DashScope

API 密钥

`DASHSCOPE_API_KEY`

Xiaomi MiMo

API 密钥

`XIAOMI_API_KEY`

Kilo Code

API 密钥

`KILOCODE_API_KEY`

AI Gateway (Vercel)

API 密钥

`AI_GATEWAY_API_KEY`

OpenCode Zen

API 密钥

`OPENCODE_ZEN_API_KEY`

OpenCode Go

API 密钥

`OPENCODE_GO_API_KEY`

Qwen OAuth

OAuth

`hermes login --provider qwen-oauth`

自定义端点

配置

`model.base_url` + `model.api_key` in config.yaml

完整提供商文档：https://hermes-agent.nousresearch.com/docs/integrations/providers

工具集

通过 hermes tools（交互式）或 hermes tools enable/disable NAME 启用/禁用。

GitHub Copilot ACP

外部

`COPILOT_CLI_PATH` or Copilot CLI

工具集

提供的功能

`web`

Web 搜索与内容提取

`search`

仅 Web 搜索（`web` 的子集）

`browser`

浏览器自动化（Browserbase、Camofox 或本地 Chromium）

`terminal`

Shell 命令与进程管理

`file`

文件读/写/搜索/补丁

`code_execution`

沙箱化 Python 执行

`vision`

图像分析

`image_gen`

AI 图像生成

`video`

视频分析与生成

`tts`

文本转语音

`skills`

技能浏览与管理

`memory`

跨会话持久记忆

`session_search`

搜索历史对话

`delegation`

子智能体任务委派

`cronjob`

定时任务管理

`clarify`

向用户提出澄清问题

`messaging`

跨平台消息发送

`todo`

会话内任务规划与跟踪

`kanban`

多智能体工作队列工具（仅限 worker 可用）

`debugging`

额外内省/调试工具（默认关闭）

`safe`

最小化低风险工具集，适用于锁定会话

`spotify`

Spotify 播放与播放列表控制

`homeassistant`

智能家居控制（默认关闭）

`discord`

Discord 集成工具

`discord_admin`

Discord 管理/审核工具

`feishu_doc`

Feishu（Lark）文档工具

`feishu_drive`

Feishu（Lark）云盘工具

`yuanbao`

Yuanbao 集成工具

`rl`	强化学习工具（默认关闭）

完整枚举位于 toolsets.py 的 TOOLSETS 字典中；_HERMES_CORE_TOOLS 是大多数平台继承的默认工具包。

工具更改在 /reset（新会话）时生效。不会在会话中途应用，以保持 prompt caching。

---

安全说明与隐私开关

常见的"为什么 Hermes 会对我的输出/工具调用/命令做 X？"开关——以及更改它们的确切命令。其中大多数需要新会话（聊天中执行 /reset，或启动新的 hermes 调用），因为它们仅在启动时读取一次。

工具输出中的密钥脱敏

密钥脱敏默认关闭——工具输出（终端 stdout、read_file、网页内容、子智能体摘要等）原样传递。如果用户希望 Hermes 在 API 密钥、令牌和敏感信息进入会话上下文和日志之前自动遮蔽：

hermes config set security.redact_secrets true       # enable globally

需要重启。security.redact_secrets 在导入时快照——在会话中途切换（例如通过工具调用执行 export HERMES_REDACT_SECRETS=true）不会对正在运行的进程生效。请告诉用户在终端中运行 hermes config set security.redact_secrets true，然后启动新会话。这是有意为之——防止 LLM 在任务执行中途自行切换开关。

再次关闭：

hermes config set security.redact_secrets false

网关消息中的 PII 脱敏

与密钥脱敏独立。启用后，网关会在用户 ID 和电话号码进入模型之前，从会话上下文中对其进行哈希处理和脱敏：

hermes config set privacy.redact_pii true    # enable
hermes config set privacy.redact_pii false   # disable (default)

命令审批提示

默认情况下（approvals.mode: manual），Hermes 在运行被标记为破坏性的 Shell 命令（rm -rf、git reset --hard 等）之前会提示用户。模式有：

manual — 始终提示（默认）

smart — 使用辅助 LLM 自动批准低风险命令，高风险命令仍提示

off — 跳过所有审批提示（等同于 --yolo）

hermes config set approvals.mode smart       # recommended middle ground
hermes config set approvals.mode off         # bypass everything (not recommended)

不改配置的单次绕过方式：

hermes --yolo …

export HERMES_YOLO_MODE=1

注意：YOLO / approvals.mode: off 不会关闭密钥脱敏。两者相互独立。

Shell hooks 白名单

某些 shell-hook 集成需要在触发前显式加入白名单。通过 ~/.hermes/shell-hooks-allowlist.json 管理——首次触发 hook 时会交互式提示。

禁用 Web/浏览器/图像生成工具

要让模型完全不使用网络或媒体工具，打开 hermes tools 并按平台切换。下次会话生效（/reset）。参见上方的工具与技能部分。

---

语音与转录

STT（语音转文本）

来自消息平台的语音消息会自动转录。

提供商优先级（自动检测）：

本地 faster-whisper — 免费，无需 API 密钥：pip install faster-whisper

Groq Whisper — 免费额度：设置 GROQ_API_KEY

OpenAI Whisper — 付费：设置 VOICE_TOOLS_OPENAI_KEY

Mistral Voxtral — 设置 MISTRAL_API_KEY

配置：

stt:
  enabled: true
  provider: local        # local, groq, openai, mistral
  local:
    model: base          # tiny, base, small, medium, large-v3

TTS（文本转语音）

`moa`

Mixture of Agents（默认关闭）

提供商

环境变量

免费？

Edge TTS

无

是（默认）

ElevenLabs

`ELEVENLABS_API_KEY`

免费额度

OpenAI

`VOICE_TOOLS_OPENAI_KEY`

付费

MiniMax

`MINIMAX_API_KEY`

付费

Mistral (Voxtral)

`MISTRAL_API_KEY`

付费

语音命令：/voice on（语音转语音）、/voice tts（始终语音）、/voice off。

---

启动额外的 Hermes 实例

将额外的 Hermes 进程作为完全独立的子进程运行——独立的会话、工具和环境。

使用场景 本方式 vs delegate_task

NeuTTS（本地）

无（`pip install neutts[all]` + `espeak-ng`）

免费

`delegate_task`

启动 `hermes` 进程

隔离性

独立会话，共享进程

完全独立的进程

持续时间

分钟级（受父循环限制）

小时/天

工具访问

父级工具的子集

完整工具访问

交互性

否

是（PTY 模式）

单次模式

terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)

# Background for long tasks:
terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)

交互式 PTY 模式（通过 tmux）

Hermes 使用 prompt_toolkit，需要真实终端。使用 tmux 进行交互式启动：

# Start
terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)

# Wait for startup, then send a message
terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)

# Read output
terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)

# Send follow-up
terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)

# Exit
terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)

多智能体协作

# Agent A: backend
terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)

# Agent B: frontend
terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)

# Check progress, relay context between them
terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)

会话恢复

# Resume most recent session
terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)

# Resume specific session
terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)

使用技巧

快速子任务优先使用 delegate_task——比启动完整进程开销更小

使用 -w（worktree 模式）启动编辑代码的智能体——防止 git 冲突

为单次模式设置超时——复杂任务可能需要 5-10 分钟

使用 hermes chat -q 实现即发即忘——无需 PTY

交互式会话使用 tmux——原生 PTY 模式与 prompt_toolkit 存在 r vs n 问题

定时任务使用 cronjob 工具而非启动进程——可处理投递和重试

---

持久化与后台系统

四个系统与主会话循环并行运行。此处为快速参考；

完整开发者文档见 AGENTS.md，面向用户的文档位于

website/docs/user-guide/features/。

委托（`delegate_task`）

同步子智能体生成——父级等待子级的摘要

后再继续自身的循环。隔离的上下文 + 终端会话。

单个：delegate_task(goal, context, toolsets)。

批量：delegate_task(tasks=[{goal, ...}, ...]) 并行运行子任务，

上限为 delegation.max_concurrent_children（默认 3）。

角色：leaf（默认；不可再委派） vs orchestrator

（可生成自身的 worker，受 delegation.max_spawn_depth 限制）。

非持久化。如果父级被中断，子级会被

取消。对于必须超越当前轮次的工作，请使用 cronjob 或

terminal(background=True, notify_on_complete=True)。

配置：config.yaml 中的 delegation.*。

Cron（定时任务）

持久化调度器——cron/jobs.py + cron/scheduler.py。通过

cronjob 工具、hermes cron CLI（list、add、edit、

pause、resume、run、remove）或 /cron 斜杠命令来驱动。

调度格式：时长（"30m"、"2h"），"every" 短语

（"every monday 9am"），5 字段 cron（"0 9 * * *"），或 ISO 时间戳。

单任务配置项：skills、model/provider 覆盖、script

（运行前数据采集；no_agent=True 使脚本成为整个

任务）、context_from（将任务 A 的输出链接到任务 B）、workdir

（在指定目录中运行，加载其 AGENTS.md / CLAUDE.md），

多平台投递。

不变量：每次运行 3 分钟硬中断，.tick.lock 文件

防止跨进程重复触发，cron 会话默认传递

skip_memory=True，cron 投递使用 header/footer 包裹

而非镜像到目标网关

会话（保持角色交替完整）。

用户文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/cron

Curator（技能生命周期）

智能体创建技能的后台维护。跟踪使用情况，标记

闲置技能为过期，归档过期技能，保留运行前 tar.gz 备份

确保不会丢失任何内容。

CLI：hermes curator — status、run、pause、resume、

pin、unpin、archive、restore、prune、backup、rollback。

斜杠命令：/curator 与 CLI 对应。

范围：仅触及 created_by: "agent" 来源的技能。

内置和 hub 安装的技能不在范围内。从不删除——

最大的破坏性操作是归档。已置顶的技能免受

所有自动状态转换和所有 LLM 审查。

遥测：sidecar 文件 ~/.hermes/skills/.usage.json 存储

每个技能的 use_count、view_count、patch_count、

last_activity_at、state、pinned。

配置：curator.*（enabled、interval_hours、min_idle_hours、

stale_after_days、archive_after_days、backup.*）。

用户文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/curator

Kanban（多智能体工作队列）

用于多 Profile / 多 worker 协作的持久化 SQLite 看板。

用户通过 hermes kanban 驱动；调度器生成的 worker

看到的是精简的 kanban_* 工具集，受 HERMES_KANBAN_TASK 控制，因此

在 worker 进程之外模式占用为零。

CLI 命令（常用）：init、create、list（别名 ls）、

show、assign、link、unlink、comment、complete、block、

unblock、archive、tail。不常用：watch、stats、runs、

log、dispatch、daemon、gc。

Worker 工具集：kanban_show、kanban_complete、kanban_block、

kanban_heartbeat、kanban_comment、kanban_create、kanban_link。

调度器默认在网关内运行

（kanban.dispatch_in_gateway: true）——回收过期认领、

提升就绪任务、原子性认领、生成已分配的 Profile。

连续生成失败约 5 次后自动阻塞任务。

隔离：看板是硬边界（worker 环境中

HERMES_KANBAN_BOARD 被固定）；租户是看板内的

软命名空间，用于工作区路径 + 记忆键隔离。

用户文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban

---

常见问题

语音不工作

检查 config.yaml 中 stt.enabled: true

验证提供商：pip install faster-whisper 或设置 API 密钥

网关中：/restart。CLI 中：退出并重新启动。

工具不可用

hermes tools — 检查工具集是否为你的平台启用

某些工具需要环境变量（检查 .env）

启用工具后执行 /reset

模型/提供商问题

hermes doctor — 检查配置和依赖

hermes login — 重新认证 OAuth 提供商

检查 .env 是否有正确的 API 密钥

Copilot 403：gh auth login 令牌不适用于 Copilot API。必须通过 hermes model → GitHub Copilot 使用 Copilot 专用的 OAuth 设备码流程。

更改未生效

工具/技能：/reset 启动带有更新工具集的新会话

配置更改：网关中：/restart。CLI 中：退出并重新启动。

代码更改：重启 CLI 或网关进程

技能未显示

hermes skills list — 验证已安装

hermes skills config — 检查平台启用状态

显式加载：/skill name 或 hermes -s name

网关问题

首先检查日志：

grep -i "failed to send|error" ~/.hermes/logs/gateway.log | tail -20

常见网关问题：

SSH 注销后网关终止：启用 linger：sudo loginctl enable-linger $USER

WSL2 关闭后网关终止：WSL2 需要在 /etc/wsl.conf 中设置 systemd=true 才能使 systemd 服务正常工作。否则，网关回退到 nohup（会话关闭时终止）。

网关崩溃循环：重置失败状态：systemctl --user reset-failed hermes-gateway

平台特定问题

Discord 机器人无响应：必须在 Bot → Privileged Gateway Intents 中启用 Message Content Intent。

Slack 机器人仅在 DM 中工作：必须订阅 message.channels 事件。否则，机器人会忽略公共频道。

Windows HTTP 400 "No models provided"：配置文件编码问题（BOM）。确保 config.yaml 以 UTF-8 无 BOM 编码保存。

辅助模型不工作

如果 auxiliary 任务（vision、compression、session_search）静默失败，说明 auto 提供商找不到后端。设置 OPENROUTER_API_KEY 或 GOOGLE_API_KEY，或显式配置每个辅助任务的提供商：

hermes config set auxiliary.vision.provider 
hermes config set auxiliary.vision.model 

---

查找信息指南

使用场景

快速并行子任务

长时间自主任务

查找内容

位置

配置选项	`hermes config edit` 或 [配置文档](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)

可用工具	`hermes tools list` 或 [工具参考](https://hermes-agent.nousresearch.com/docs/reference/tools-reference)

斜杠命令	会话中执行 `/help` 或 [斜杠命令参考](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)

技能目录	`hermes skills browse` 或 [技能目录](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog)

提供商设置

`hermes model` 或 [提供商指南](https://hermes-agent.nousresearch.com/docs/integrations/providers)

平台设置	`hermes gateway setup` 或 [消息平台文档](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)

MCP 服务器

`hermes mcp list` 或 [MCP 指南](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

Profile

`hermes profile list` 或 [Profile 文档](https://hermes-agent.nousresearch.com/docs/user-guide/profiles)

Cron 任务

`hermes cron list` 或 [Cron 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)

记忆	`hermes memory status` 或 [记忆文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)

环境变量	`hermes config env-path` 或 [环境变量参考](https://hermes-agent.nousresearch.com/docs/reference/environment-variables)

CLI 命令

`hermes --help` 或 [CLI 参考](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)

网关日志	`~/.hermes/logs/gateway.log`

会话文件	`~/.hermes/sessions/` 或 `hermes sessions browse`

---

贡献者快速参考

面向偶尔贡献者和 PR 作者。完整开发者文档：https://hermes-agent.nousresearch.com/docs/developer-guide/

项目结构

hermes-agent/
├── run_agent.py          # AIAgent — core conversation loop
├── model_tools.py        # Tool discovery and dispatch
├── toolsets.py           # Toolset definitions
├── cli.py                # Interactive CLI (HermesCLI)
├── hermes_state.py       # SQLite session store
├── agent/                # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
├── hermes_cli/           # CLI subcommands, config, setup, commands
│   ├── commands.py       # Slash command registry (CommandDef)
│   ├── config.py         # DEFAULT_CONFIG, env var definitions
│   └── main.py           # CLI entry point and argparse
├── tools/                # One file per tool
│   └── registry.py       # Central tool registry
├── gateway/              # Messaging gateway
│   └── platforms/        # Platform adapters (telegram, discord, etc.)
├── cron/                 # Job scheduler
├── tests/                # ~3000 pytest tests
└── website/              # Docusaurus docs site

配置：~/.hermes/config.yaml（设置），~/.hermes/.env（API 密钥）。

添加工具（3 个文件）

1. 创建 tools/your_tool.py：

import json, os
from tools.registry import registry

def check_requirements() -> bool:
    return bool(os.getenv("EXAMPLE_API_KEY"))

def example_tool(param: str, task_id: str = None) -> str:
    return json.dumps({"success": True, "data": "..."})

registry.register(
    name="example_tool",
    toolset="example",
    schema={"name": "example_tool", "description": "...", "parameters": {...}},
    handler=lambda args, **kw: example_tool(
        param=args.get("param", ""), task_id=kw.get("task_id")),
    check_fn=check_requirements,
    requires_env=["EXAMPLE_API_KEY"],
)

2. 添加到 toolsets.py → _HERMES_CORE_TOOLS 列表。

自动发现：任何包含顶层 registry.register() 调用的 tools/*.py 文件都会被自动导入——无需手动列表。

所有 handler 必须返回 JSON 字符串。路径请使用 get_hermes_home()，切勿硬编码 ~/.hermes。

添加斜杠命令

在 hermes_cli/commands.py 中将 CommandDef 添加到 COMMAND_REGISTRY

在 cli.py → process_command() 中添加 handler

（可选）在 gateway/run.py 中添加网关 handler

所有消费方（帮助文本、自动补全、Telegram 菜单、Slack 映射）都自动从中央注册表派生。

Agent 循环（概览）

run_conversation():
  1. Build system prompt
  2. Loop while iterations < max:
     a. Call LLM (OpenAI-format messages + tool schemas)
     b. If tool_calls → dispatch each via handle_function_call() → append results → continue
     c. If text response → return
  3. Context compression triggers automatically near token limit

测试

python -m pytest tests/ -o 'addopts=' -q   # Full suite
python -m pytest tests/tools/ -q            # Specific area

测试自动将 HERMES_HOME 重定向到临时目录——绝不触碰真实的 ~/.hermes/

推送任何更改前运行完整测试套件

使用 -o 'addopts=' 清除内置的 pytest 标志

提交规范

type: concise subject line

Optional body.

类型：fix:、feat:、refactor:、docs:、chore:

关键规则

切勿破坏 prompt caching——不要在会话中途更改上下文、工具或系统提示词

消息角色交替——绝不连续出现两条 assistant 或两条 user 消息

所有路径使用 hermes_constants 中的 get_hermes_home()（Profile 安全）

配置值放 config.yaml，密钥放 .env

新工具需要 check_fn，使其仅在满足条件时出现

源代码	`~/.hermes/hermes-agent/`