Hermes Agent 完整使用指南

Hermes Agent 完整使用指南目录项目概览安装部署初始配置CLI 基本使用核心功能详解5.1 工具与工具集5.2 技能系统5.3 持久化记忆5.4 上下文文件5.5 子代理委派5.6 代码执行5.7 定时任务 Cron5.8 检查点与回滚终端后端消息平台集成语音模式浏览器自动化MCP 集成个性化定制安全机制高级配置参考实战应用案例常见问题 FAQ1. 项目概览Hermes Agent 不是绑定在 IDE 上的编码助手也不是单纯包装 API 的聊天机器人。它是一个自主代理Autonomous Agent运行时间越长就越强大。核心特性学习闭环代理策管的记忆 自主技能创建 使用中技能自我改进 FTS5 跨会话召回 Honcho 辩证用户建模可部署任何环境6 种终端后端——本地、Docker、SSH、Daytona、Singularity、ModalDaytona 和 Modal 提供无服务器持久化空闲时几乎零成本多平台即时通讯CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、飞书、企业微信、BlueBubbles、Home Assistant 等 15 平台47 个内置工具覆盖网页搜索、终端执行、文件编辑、记忆管理、浏览器自动化、图像生成、TTS 等技能标准开放兼容 agentskills.io 开放标准技能可移植、共享支持并行子代理最多同时运行 3 个隔离子代理MCP 协议支持连接任意 MCP 服务器扩展工具能力RL 训练就绪批处理、轨迹导出、Atropos 强化学习训练2. 安装部署2.1 一键安装推荐Linux / macOS / WSL2curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bash安装脚本会自动处理所有依赖Python 3.11、Node.js v22、ripgrep、ffmpeg、仓库克隆、虚拟环境创建、全局hermes命令设置以及 LLM 提供商配置。Android / Termux同样使用上述命令安装脚本会自动检测 Termux 环境并切换到专用 Android 安装流程。⚠️Windows不支持原生 Windows请安装 WSL2 后在 WSL2 内运行。2.2 安装完成后source~/.bashrc# 或 source ~/.zshrchermes# 开始聊天2.3 手动安装如果需要完全控制安装过程# 1. 安装 uvcurl-LsSfhttps://astral.sh/uv/install.sh|sh# 2. 克隆仓库gitclone --recurse-submodules https://github.com/NousResearch/hermes-agent.gitcdhermes-agent# 3. 创建虚拟环境uv venv venv--python3.11exportVIRTUAL_ENV$(pwd)/venv# 4. 安装依赖全量安装uv pipinstall-e.[all]# 5. 可选Node.js 依赖浏览器自动化和 WhatsAppnpminstall# 6. 创建配置目录mkdir-p~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}cpcli-config.yaml.example ~/.hermes/config.yamltouch~/.hermes/.env# 7. 添加 API 密钥echoOPENROUTER_API_KEYsk-or-v1-your-key~/.hermes/.env# 8. 全局可用mkdir-p~/.local/binln-sf$(pwd)/venv/bin/hermes~/.local/bin/hermes# 9. 验证hermes doctor hermes2.4 可选依赖包一览额外包功能安装命令all安装全部uv pip install -e .[all]messagingTelegram 和 Discord 网关uv pip install -e .[messaging]cron定时任务表达式解析uv pip install -e .[cron]modalModal 云执行后端uv pip install -e .[modal]tts-premiumElevenLabs 高级语音uv pip install -e .[tts-premium]voiceCLI 麦克风输入 音频播放uv pip install -e .[voice]honchoAI 原生记忆Honcho 集成uv pip install -e .[honcho]mcpModel Context Protocol 支持uv pip install -e .[mcp]slackSlack 消息uv pip install -e .[slack]termuxAndroid/Termux 专用包python -m pip install -e .[termux]可组合使用uv pip install -e .[messaging,cron,mcp]3. 初始配置3.1 目录结构~/.hermes/ ├── config.yaml # 主配置文件模型、终端、TTS、压缩等 ├── .env # API 密钥和秘密 ├── auth.json # OAuth 提供商凭证 ├── SOUL.md # 代理主要身份系统提示词第一位 ├── memories/ # 持久化记忆MEMORY.md、USER.md ├── skills/ # 代理创建的技能 ├── cron/ # 定时任务 ├── sessions/ # 网关会话 └── logs/ # 日志自动脱敏3.2 配置管理命令hermes config# 查看当前配置hermes config edit# 编辑器打开 config.yamlhermes configsetKEY VAL# 设置特定值hermes config check# 检查缺失选项hermes config migrate# 交互式添加缺失选项hermes model# 选择 LLM 提供商和模型hermes tools# 配置启用的工具hermes gateway setup# 设置消息平台hermes setup# 完整设置向导3.3 配置优先级优先级从高到低CLI 参数— 如hermes chat --model anthropic/claude-sonnet-4~/.hermes/config.yaml— 主配置文件~/.hermes/.env— 环境变量API 密钥必须存放于此内置默认值经验法则秘密信息API 密钥、令牌、密码放.env。其他所有内容放config.yaml。3.4 支持的 LLM 提供商Hermes 兼容多种提供商OpenRouter— 路由到数百个模型推荐入门Nous Portal— Nous Research 官方门户Anthropic— Claude 系列OpenAI— GPT 系列Codex— ChatGPT OAuth 方式自定义端点— 任何 OpenAI 兼容 API本地模型、Ollama、vLLM 等4. CLI 基本使用hermes# 启动交互式聊天hermes chat-q你好# 单次查询hermes chat--modelopenai/gpt-4o-q解释量子计算# 指定模型# 常用斜杠命令/help# 帮助信息/tools# 查看可用工具/skills# 查看已安装技能/memory# 查看记忆内容/voice on# 启用语音模式/verbose# 切换工具输出详细度/reasoning high# 设置推理强度/rollback# 回滚到上一个检查点/clear# 清除当前会话/exit# 退出上下文引用 语法在消息中输入后跟引用即可注入外部内容file.py # 注入文件内容 src/ # 注入目录结构 git:diff # 注入 git 差异 https://url.com # 注入网页内容5. 核心功能详解5.1 工具与工具集Tools ToolsetsHermes 内置47 个工具按逻辑分组为工具集工具集包含工具示例terminal终端命令执行file文件读写、编辑、搜索web网页搜索、网页提取、网页爬取browser浏览器导航、截图、表单填写memory记忆管理、会话搜索skills技能列表、查看、创建、管理delegation子代理任务委派code_executionPython 沙盒代码执行media图像生成、TTS、视觉分析cron定时任务管理通过hermes tools配置启用/禁用各工具集。5.2 技能系统Skills技能是代理按需加载的知识文档遵循渐进式披露模式以最小化 token 消耗。使用方式# 作为斜杠命令使用/gif-search funny cats /axolotlhelpme fine-tune Llama3/plan design a rolloutforauth migration# 通过对话自然触发你有什么技能渐进式加载层次层级调用内容Level 0skills_list()名称、描述、分类概览~3k tokensLevel 1skill_view(name)完整内容 元数据Level 2skill_view(name, path)特定参考文件技能目录~/.hermes/skills/代理可以自主创建和改进技能——当它发现某个流程值得记录时会自动将其保存为可复用的技能。SKILL.md 格式示例---name:my-skilldescription:简要描述技能功能version:1.0.0platforms:[macos,linux]metadata:hermes:tags:[python,automation]category:devops---# 技能标题## When to Use触发条件## Procedure1. 步骤一 2. 步骤二## Pitfalls-已知故障模式和修复## Verification确认生效的方法5.3 持久化记忆MemoryHermes 的记忆由两个文件组成持久化于~/.hermes/memories/文件用途字符限制MEMORY.md代理个人笔记——环境事实、约定、经验教训2,200 字符~800 tokensUSER.md用户画像——偏好、沟通风格、期望1,375 字符~500 tokens记忆工作方式两个文件在会话启动时作为冻结快照注入系统提示词代理通过memory工具管理记忆add、replace、remove代理会主动保存学到的信息无需用户要求记忆写入即时持久化到磁盘但在当前会话的系统提示词中不变下次会话生效包含安全扫描防止注入攻击代理自动保存的内容示例用户偏好“我偏好 TypeScript”环境事实“该服务器运行 Debian 12 PostgreSQL 16”纠正“Docker 命令不需要 sudo”编码约定“项目使用 tabs、120 字符行宽”会话搜索session_search除了 MEMORY.md 和 USER.md代理还能通过 FTS5 全文搜索回顾所有历史会话。5.4 上下文文件Context FilesHermes 自动发现并加载多种项目上下文文件文件用途SOUL.md代理主要身份占系统提示词第一位.hermes.md/HERMES.md项目特定指令最高优先级AGENTS.md项目特定指令、编码约定支持子目录层级合并CLAUDE.mdClaude Code 上下文文件.cursorrulesCursor IDE 规则优先级.hermes.md→AGENTS.md→CLAUDE.md→.cursorrules仅加载第一个匹配。SOUL.md始终独立加载。5.5 子代理委派Delegationdelegate_task工具可以派生子代理实例具有隔离的上下文、受限的工具集和独立的终端会话。最多同时运行3 个并行子代理子代理可以使用不同的模型如用便宜模型处理子任务配置示例delegation:model:google/gemini-3-flash-previewprovider:openrouter5.6 代码执行Code Executionexecute_code工具让代理编写 Python 脚本通过沙盒 RPC 调用 Hermes 工具将多步骤工作流合并为单次 LLM 推理。code_execution:timeout:300max_tool_calls:505.7 定时任务 Cron支持自然语言或 cron 表达式调度任务。任务可以附加技能将结果推送到任意消息平台。# 在对话中每天早上 8 点给我发送天气预报到 Telegram每周一生成项目进度报告5.8 检查点与回滚CheckpointsHermes 在执行破坏性文件操作前自动创建文件系统快照。checkpoints:enabled:truemax_snapshots:50使用/rollback命令回滚到之前的状态。6. 终端后端Hermes 支持 6 种终端后端决定代理的 Shell 命令在哪里执行后端执行位置隔离级别适用场景local本地机器无开发、个人使用dockerDocker 容器完全隔离安全沙盒、CI/CDssh远程服务器网络边界远程开发、强力硬件modalModal 云沙盒完全隔离云 VM临时云计算、评估daytonaDaytona 工作空间完全隔离云容器托管云开发环境singularitySingularity 容器命名空间隔离HPC 集群、共享机器配置示例terminal:backend:dockerdocker_image:nikolaik/python-nodejs:python3.11-nodejs20container_cpu:1container_memory:5120container_persistent:truetimeout:180Docker 后端安全加固--cap-drop ALL仅恢复DAC_OVERRIDE、CHOWN、FOWNER--security-opt no-new-privileges--pids-limit 256大小受限的 tmpfs7. 消息平台集成Hermes 支持 15 消息平台通过统一消息网关接入平台特性Telegram完整支持含语音消息、文件、流式编辑Discord服务器频道、DM、语音频道、线程Slack频道、线程、应用集成WhatsApp通过 WhatsApp Web 桥接Signal安全消息Matrix去中心化协议EmailIMAP/SMTPSMS短信DingTalk / 飞书 / 企业微信国内企业通讯平台Home Assistant智能家居集成设置命令hermes gateway setup# 交互式设置hermes gateway start# 启动网关群聊会话隔离group_sessions_per_user:true# 每个用户独立会话默认推荐8. 语音模式Hermes 支持完整的语音交互覆盖 CLI 和消息平台。CLI 语音/voice on# 启用麦克风模式/voice tts# 开启语音回复TTS 提供商提供商说明Edge TTS免费322 种声音74 种语言ElevenLabs高质量高级语音OpenAI TTSGPT-4o-mini-ttsNeuTTS本地运行STT 提供商localfaster-whisper、groq、openai配置tts:provider:edgeedge:voice:zh-CN-XiaoxiaoNeural# 中文语音示例voice:record_key:ctrlbmax_recording_seconds:120stt:provider:locallocal:model:base9. 浏览器自动化支持多后端浏览器自动化Browserbase 云、Browser Use 云、本地 Chrome CDP、本地 Chromium。能力包括网页导航和截图表单填写信息提取视觉分析配合多模态模型browser:inactivity_timeout:120command_timeout:30record_sessions:false10. MCP 集成Hermes 可以连接任意 MCPModel Context Protocol服务器通过 stdio 或 HTTP 传输协议访问外部工具。功能包括连接 GitHub、数据库、文件系统、内部 API 等无需编写原生 Hermes 工具支持每服务器工具过滤和采样11. 个性化定制SOUL.md — 代理身份~/.hermes/SOUL.md定义代理的核心身份是系统提示词的第一部分。完全可自定义。人格预设使用/personality命令切换预设人格或在 SOUL.md 中完全自定义。皮肤与主题display:skin:default# 内置或自定义 CLI 皮肤compact:false插件将自定义工具、钩子、集成放入~/.hermes/plugins/目录包含plugin.yaml和 Python 代码。12. 安全机制命令审批approvals:mode:manual# manual | smart | offmanual执行任何危险命令前提示用户smart使用辅助 LLM 评估命令风险低风险自动批准off跳过所有审批仅用于可信沙盒环境秘密信息脱敏security:redact_secrets:true自动检测并脱敏工具输出和日志中的 API 密钥、令牌、密码。Tirith 安全扫描终端命令执行前通过 Tirith 扫描检测潜在危险操作。网站黑名单security:website_blocklist:enabled:truedomains:-*.internal.company.com-admin.example.com记忆安全扫描记忆条目在接受前会扫描注入和数据泄露模式。13. 高级配置参考上下文压缩长对话自动压缩以保持在模型上下文窗口内compression:enabled:truethreshold:0.50target_ratio:0.20protect_last_n:20summary_model:google/gemini-3-flash-previewsummary_provider:auto辅助模型图像分析、网页摘要、浏览器截图分析等旁路任务使用轻量级辅助模型auxiliary:vision:provider:automodel:web_extract:provider:autotimeout:360凭证池多个 API 密钥轮换策略credential_pool_strategies:openrouter:round_robin# fill_first | round_robin | least_used | random推理强度agent:reasoning_effort:# none | minimal | low | medium | high | xhighmax_turns:90流式输出display:streaming:trueshow_reasoning:truestreaming:enabled:truetransport:editedit_interval:0.3网页搜索后端web:backend:firecrawl# firecrawl | parallel | tavily | exa隐私保护privacy:redact_pii:false# 从 LLM 上下文中脱敏 PII网关专用快速命令定义零 token 消耗的自定义命令quick_commands:status:type:execcommand:systemctl status hermes-agentdisk:type:execcommand:df-h /gpu:type:execcommand:nvidia-smi--query-gpuname,utilization.gpu,memory.used--formatcsv,noheader14. 实战应用案例案例 1个人编程助手# 在项目目录中启动cd~/projects/my-app hermes# 对话分析 src/ 目录的代码结构并给出改进建议重构 auth 模块使用 JWT 替换 session-based auth为所有 API 端点编写单元测试案例 2远程服务器管理# config.yamlterminal:backend:ssh# 通过 Telegram 远程管理检查服务器磁盘使用情况重启 nginx 服务查看最近的错误日志案例 3自动化工作流# 设置定时任务每天早上 9 点搜索 Hacker News 上关于 AI 的最新文章生成摘要发送到 Telegram# 并行处理同时搜索三个竞品的定价页面整理成对比表格案例 4知识管理# 技能创建基于我们刚才的部署流程创建一个可复用的技能# 跨会话记忆上周我们讨论过的数据库迁移方案是什么案例 5Docker 安全沙盒开发terminal:backend:dockerdocker_image:nikolaik/python-nodejs:python3.11-nodejs20container_persistent:truedocker_volumes:-/home/user/projects:/workspace/projects安装 TensorFlow 并运行 benchmark 测试# 完全隔离不影响宿主机环境15. 常见问题 FAQQhermes: command not foundA重新加载 Shellsource ~/.bashrc或检查~/.local/bin是否在 PATH 中。QAPI key not setA运行hermes model配置提供商或hermes config set OPENROUTER_API_KEY your_key。Q更新后配置缺失A运行hermes config check然后hermes config migrate。Q如何更新 HermesAcd~/.hermes/hermes-agent# 或你克隆仓库的位置gitpull uv pipinstall-e.[all]Q如何完全诊断问题A运行hermes doctor它会告诉你缺少什么以及如何修复。Q支持哪些模型A通过 OpenRouter 支持数百个模型也可以使用任何 OpenAI 兼容 API包括本地部署的 Ollama、vLLM 等。Q如何降低成本A使用便宜的模型如 Gemini Flash作为辅助任务模型使用delegation让子代理使用更便宜的模型启用上下文压缩减少 token 消耗。相关资源 官方文档https://hermes-agent.nousresearch.com/docs GitHub 仓库https://github.com/NousResearch/hermes-agent 技能中心https://agentskills.io Discord 社区https://discord.gg/NousResearch Nous Researchhttps://nousresearch.com