hermes-agent

Hermes Agent

Hermes Agent 是 Nous Research 推出的开源 AI Agent 框架，可在你的终端、原生桌面应用、消息平台和 IDE 中运行。它与 Claude Code（Anthropic）、Codex（OpenAI）和 OpenClaw 属于同一类别——这些都是通过工具调用与你的系统交互的自主编码和任务执行 Agent。Hermes 可与任何大模型提供商（OpenRouter、Anthropic、OpenAI、Google、DeepSeek、xAI、本地模型以及其他 20 多家提供商）配合使用，并可在 Linux、macOS、Windows 和 WSL 上运行。

Hermes 的独特之处：

• 通过技能自我改进——Hermes 会从经验中学习，将可复用的流程保存为技能，供未来的会话加载。
• 跨会话持久记忆——记住你的身份、偏好、环境详情和经验教训。支持可插拔的记忆后端。
• 多平台网关——同一个 Agent 可在 Telegram、Discord、Slack、WhatsApp、iMessage、Signal、Matrix、Teams、Email 以及另外十余个平台上运行，并拥有完整的工具访问权限，而不只是用于聊天。
• 多种界面——同一个 Agent 核心可驱动 CLI、Ink TUI、原生 Electron 桌面应用、Web 仪表板，以及面向 IDE（VS Code / Zed / JetBrains）的 ACP 服务。
• 提供商无关——可在工作流中途切换模型和提供商；凭据池会在多个 API 密钥之间自动轮换。
• 配置档案——使用相互隔离的配置、会话、技能和记忆，运行多个独立的 Hermes 实例。
• 可扩展且可定制主题——支持插件、MCP 服务、自定义工具、Webhook 触发器、cron 调度、可为所有界面设置主题的皮肤、桌面 UI 插件、TUI 组件和宠物吉祥物。

此技能是一个枢纽。 主体内容涵盖身份、快速入门、Agent 派生和编排以及硬性不变量。其余所有内容均位于参考文件中——回答前请加载匹配的参考资料（见下文）；不要仅凭主体内容回答细节问题。

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

范围与验证

此技能是一份简洁的操作指南，并非所有 Hermes 功能的完整权威依据。如果此处或参考资料中未提及某个 Hermes 功能、命令或设置，不要将这种缺失视为它不存在的证据。在给出否定回答前，请检查当前代码仓库和官方文档。

验证时优先选择成本最低的目标：

• 每个已发布功能各占一行：https://hermes-agent.nousresearch.com/docs/llms.txt。 回答任何“Hermes 能执行 X 吗？”或“我该如何执行 X？”问题时，都应从这里开始；其中索引了整个文档集，并链接到相应的解答页面。它会在每次构建时根据文档树生成，因此永远不会落后于产品。可使用 web_extract 获取；网页工具未启用时，则使用 curl -s https://hermes-agent.nousresearch.com/docs/llms.txt。完整文档集均包含在一个文件中，路径为 /docs/llms-full.txt。
• CLI 命令：hermes --help、hermes <command> --help 和 hermes_cli/main.py
• 源代码树：https://github.com/NousResearch/hermes-agent

绝不要凭记忆回答“Hermes 无法做到这一点”。Hermes 随附的功能远不止此技能主体所描述的内容，而有了这份索引，任何否定回答都可以核实。

快速开始

# Install (shell installer — bootstraps PM, Python, dependencies, and the launcher)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)
hermes

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

# Setup wizard  /  pick model+provider  /  health check
hermes setup
hermes model
hermes doctor

# Other surfaces
hermes desktop                 # launch the native desktop app (alias: hermes gui)
hermes dashboard               # web admin panel + embedded chat
hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider

关键路径

~/.hermes/config.yaml       Main configuration (settings — never secrets)
~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)
$HERMES_HOME/skills/        Installed skills
~/.hermes/skins/            Custom themes (see references/themes.md)
~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
~/.hermes/pets/             Installed pet mascots (see references/petdex.md)
~/.hermes/state.db          Canonical session store (SQLite + FTS5)
~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
~/.hermes/logs/             Gateway and error logs
~/.hermes/auth.json         OAuth tokens and credential pools
~/.hermes/hermes-agent/     Source code (if git-installed)

配置档案使用 ~/.hermes/profiles/<name>/，目录布局与上述路径相同。配置档案激活后，请从 $HERMES_HOME 解析实际主目录——切勿硬编码 ~/.hermes。

路由表——为任务加载参考文档

用户想要……	加载
下方未列出的任何内容——“Hermes 能做 X 吗？”“如何设置 X？”	https://hermes-agent.nousresearch.com/docs/llms.txt
可聊天、运行例程或互相发消息的机器人；机器人选项卡	文档：/user-guide/bot-mode
CLI 命令、子命令、选项，“如何运行 X”	references/cli-reference.md
会话内斜杠命令	references/slash-commands.md
提供商设置、API 密钥、OAuth	references/providers-and-models.md
config.yaml 各节、工具集、语音／STT／TTS	references/configuration.md
AGENTS.md / .hermes.md / CLAUDE.md 项目规则	references/project-context-files.md
机密信息脱敏、PII、审批模式、“重置权限”	references/security-privacy.md
委派、cron、策展器、看板	references/background-systems.md
MCP 服务（添加、目录、hermes mcp）	references/native-mcp.md
Webhook 路由和事件驱动运行	references/webhooks.md
自定义主题／皮肤（“合成波主题”“更改金色 ●”）	references/themes.md + templates/skin.yaml
桌面应用 UI 元素（窗格、小组件、⌘K 命令、页面）	references/desktop-plugins.md + templates/plugin.js
实时 TUI 面板或模态小组件（信息滚动显示、时钟、仪表板）	references/tui-widgets.md + templates/clock.mjs
宠物吉祥物——安装、选择、调整大小、诊断	references/petdex.md
Windows 特定问题（按键绑定、WinError 10106、BOM）	references/windows-quirks.md
调试：语音、工具缺失、网关、辅助模型	references/troubleshooting.md
贡献代码：添加工具、斜杠命令、测试	references/contributor-guide.md
delegate_task“上限为 N”的报告	references/delegate-task-concurrency-diagnosis.md
“应用 X 能使用我的 Nous Portal 订阅／OAuth 吗？”	references/portal-auth-for-third-party-apps.md
连接消息平台（Telegram、Discord、Slack、WhatsApp、……）	文档：/user-guide/messaging

上述参考列表不是功能列表——它列出的只是那些 仅凭其文档页面无法获得完整信息的主题。对于 Hermes 提供的其他所有内容，请获取 llms.txt，它会将问题映射到能够解答问题的页面。

即使无需加载参考资料，以下两条主题规则也始终适用：你自行应用皮肤（hermes config set display.skin <name>——所有界面都会在约 1 秒内实时重绘；不要让用户运行 /skin），以及要微调一种颜色，请编辑当前生效的皮肤（hermes skin set <key> <hex>）——绝不要从 default 创建分支，否则会丢失调色板并重置背景。

启动额外的 Hermes 实例

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

何时使用此方式而非 delegate_task

	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 协调

# 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 — 比启动完整进程的开销更低
• 让 Agent 编辑代码时使用 -w（工作树模式） — 可防止 git 冲突
• 为一次性模式设置超时 — 复杂任务可能需要 5-10 分钟
• 使用 hermes chat -q 进行即发即弃操作 — 无需 PTY
• 交互式会话使用 tmux — 原始 PTY 模式配合 prompt_toolkit 时存在 \r 与 \n 的问题
• 定时任务使用 cronjob 工具，而非启动进程 — 可处理投递和重试
• 出现“delegate_task 的上限为 N”报告 — 参见 references/delegate-task-concurrency-diagnosis.md。Hermes 中有三条真正的上限触发路径；如果均未触发，则是模型在自我限制，并将此合理化为“运行时限制了上限”。
• “$external_app 可以使用我的 Nous Portal 订阅／OAuth 吗？” — 参见 references/portal-auth-for-third-party-apps.md。引导用户了解三个层面（插件与应用、Portal 实际开放的功能，以及本地代理选项）。

使用界面（快速导览）

• 桌面应用（hermes desktop / hermes gui）— 适用于 macOS/Linux/Windows 的原生 Electron 应用：流式聊天、会话列表、Cmd+K 命令面板、拖放文件、原生通知，以及按配置档远程网关登录。可使用 UI 插件扩展 — references/desktop-plugins.md。
• Web 仪表板（hermes dashboard）— 完整的管理面板：消息通道、MCP 目录、Webhook、内存、配置档构建器，以及内嵌的 hermes --tui 聊天。通过 OAuth／令牌门控保护。
• Ink TUI（hermes --tui 或 display.interface: tui）— 带有停靠小组件应用的终端 UI — references/tui-widgets.md。
• 兼容 OpenAI 的代理（hermes proxy）— 由当前登录的 OAuth 提供商支持的本地 OpenAI API。可将 Codex CLI、Aider、Cline 或任意脚本指向它，无需 API 密钥。

硬性不变量（无论加载了什么，都不得违反）

• 绝不破坏提示词缓存 — 不要在对话中途更改过去的上下文、工具集或系统提示词。唯一的例外是上下文压缩。
• 消息角色交替 — 不得连续出现两条助手消息或两条用户消息；只有 tool 结果可以重复。
• 机密信息放在 .env 中，设置放在 config.yaml 中 — 绝不能让用户将非凭据设置放入 .env。
• 安全的配置档路径 — 代码中使用 get_hermes_home()，在会话中解析路径时使用 $HERMES_HOME。
• 绝不要为用户手动编辑 config.yaml — 使用 hermes config set KEY VAL；多余缩进可能会损坏文件并导致实时网关中断。