Hermes Agent 完整使用教程目录Hermes 是什么 安装与初始化 第一次进入 CLI 配置、模型与 profile 工具、toolset 与执行边界 skill、memory 与上下文文件 MCP 接入外部系统 Gateway 与多平台使用 cron、后台任务与自动化 开发扩展 调试、测试与排障 最佳实践1. Hermes 是什么Hermes Agent 不是单纯的聊天界面也不是只能在 IDE 里工作的代码补全器。它更像一个统一的 agent 运行时在 CLI 里它可以读写文件、执行命令、管理会话、切换模型、调用工具 在 Gateway 里它可以通过 Telegram、Discord、Slack、WhatsApp、Signal 等平台长期在线 通过 skill、memory 和 context file它能把流程知识、事实信息和项目约束长期保留下来 通过 MCP 和 plugins它能对接外部系统 通过 cron 和背景任务它能定时、异步、持续地工作你可以把 Hermes 的核心结构概括成下面几层入口层CLI、Gateway、ACP、batch runner agent 层AIAgent和 prompt / provider / tool 调度 执行层tools、toolsets、terminal backend、browser backend、MCP 持久层sessions、memory、skills、profiles这意味着 Hermes 的效果不仅取决于模型还取决于工具可用性、上下文质量和你的使用方式。2. 安装与初始化普通安装最快的方式是官方安装脚本curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bashsource~/.bashrc# 或 source ~/.zshrchermes官方支持 Linux、macOS 和 WSL2。原生 Windows 不在推荐路径里。仓库开发安装如果你打算直接修改仓库gitclone https://github.com/NousResearch/hermes-agent.gitcdhermes-agent uv venv venv--python3.11sourcevenv/bin/activate uv pipinstall-e.[all,dev]对于这个仓库本身AGENTS.md明确要求运行 Python 相关命令前要先source venv/bin/activate。初始化配置首次安装后建议运行hermes setup它会帮你处理模型与 provider terminal backend gateway 平台 tools agent 行为默认配置目录是~/.hermes/你最需要知道的文件通常是~/.hermes/config.yaml~/.hermes/.env~/.hermes/SOUL.md.env里通常先配一个可用 provider例如OPENROUTER_API_KEY... 智谱 glm 配置 base-url 写这个 https://open.bigmodel.cn/api/coding/paas/v4安装验证建议用hermes version hermes doctor hermes status hermes3. 第一次进入 CLICLI 是最完整的主入口。推荐你第一次就用它而不是先上消息平台。启动hermes进入后先跑这几条/help /model /usage /toolsets然后给一个带动作的任务而不是“你好”例如阅读当前目录结构并总结这个仓库的核心组成。这样你能马上看到 Hermes 是否会用 file 或 terminal 工具。你很快会常用到的命令/new//reset新会话/title命名会话/resume恢复命名会话/model切换模型/usage看 token、成本、上下文/compress压缩上下文/verbose观察工具输出/background prompt后台启动独立任务/skills搜索和安装 skill/tools list看当前工具CLI 外也别忘了hermes-chermes-rsession-title复杂任务建议尽早/title否则后续恢复会话会很痛苦。4. 配置、模型与 profileHermes 的配置分两类config.yaml结构化行为配置.envAPI key、base URL、平台 token、终端环境变量等最常见的 provider 相关变量有OPENROUTER_API_KEYOPENAI_API_KEYOPENAI_BASE_URLANTHROPIC_API_KEYGLM_API_KEY选择模型最直接的方式是hermes model会话中可以/model /model openrouter:anthropic/claude-sonnet-4 /model zai:glm-5 /model custom:qwen-2.5profile 为什么重要如果你有多个用途强烈建议用 profile 隔离而不是把所有配置堆在一个默认实例里。常见命令hermes profile list hermes profile create work--clonehermes profile use work hermes profile show work hermes profile use defaultprofile 隔离的是整套 Hermes home包括配置、技能、会话、memory、gateway 状态等。关于 prompt cacheHermes 很依赖稳定的系统提示前缀来命中缓存。频繁改模型、系统提示、上下文文件、技能加载方式会提高成本并降低会话稳定性。不要把“中途乱改配置”当作常态。5. 工具、toolset 与执行边界Hermes 的执行力来自工具。每个工具属于一个 toolset你平时更常控制的是 toolset。常见 toolsetfileterminalwebbrowserskillsmemorycode_executiondelegationcronjob查看当前会话可用能力/toolsets /tools list从命令行按会话选择hermes chat--toolsetsweb,file,terminal hermes chat--toolsetsdebugging hermes chat--toolsetsall怎样选对工具层级读写搜索文件file 真正执行命令terminal 快速搜索网页或抽取正文web 点击按钮、填表单、真实页面交互browser 多步机械流程execute_code 并行子任务或新上下文分析delegate_task高频误区是“什么都开、什么都用”这会增加风险、成本和不可预测性。更好的方式是为任务提供最小且足够的能力集合。6. skill、memory 与上下文文件Hermes 的长期稳定性主要来自三类东西skill如何做 memory是什么 context file默认背景和规则使用 skill查看和安装/skills /skills searchdocker/skills browse或hermes skills list hermes skillsinstallofficial/research/arxivskill 安装后通常会直接变成 slash command例如/plan 设计一个 REST API /ascii-art Make a banner使用 memory适合保存长期事实例如记住我们的 CI 用 GitHub Actions部署工作流是 deploy.yml。使用AGENTS.md和SOUL.mdAGENTS.md项目规则、架构约束、测试要求SOUL.mdHermes 的长期风格和行为倾向如果你总在重复同一批规则就应该把它们写进AGENTS.md而不是继续每次重说。一个重要限制不要把AGENTS.md写成百科全书。它会进入系统上下文太长会增加成本并稀释重点。7. MCP 接入外部系统MCP 适合把外部系统接成 Hermes 的工具。例如 GitHub、文件系统、内部 API、远程知识库。当前仓库和代码使用的配置键是mcp_servers:...不是mcp.servers。最小 stdio 示例mcp_servers:filesystem:command:npxargs:[-y,modelcontextprotocol/server-filesystem,/home/user/projects]最小 HTTP 示例mcp_servers:company_api:url:https://mcp.internal.example.comheaders:Authorization:Bearer ***改完配置后记得/reload-mcp先过滤再暴露非常推荐一开始就做白名单或黑名单控制mcp_servers:github:command:npxargs:[-y,modelcontextprotocol/server-github]env:GITHUB_PERSONAL_ACCESS_TOKEN:***tools:include:[list_issues,create_issue,search_code]prompts:falseresources:false判断标准可以记为内置工具已经够用优先内置工具 只是流程复杂优先 skill 需要接外部系统优先 MCP8. Gateway 与多平台使用Hermes 可以通过 gateway 暴露到 Telegram、Discord、Slack、WhatsApp、Signal 等平台。核心命令hermes gateway setup hermes gateway run hermes gateway start hermes gateway stop hermes gateway status常见平台变量包括TELEGRAM_BOT_TOKENDISCORD_BOT_TOKENSLACK_BOT_TOKENSLACK_APP_TOKEN授权控制必须认真做不要轻易开放所有用户。优先配置TELEGRAM_ALLOWED_USERSDISCORD_ALLOWED_USERSGATEWAY_ALLOWED_USERShome channel 很重要进入对应聊天后执行/sethomecron 和后台结果才知道发去哪里。消息平台常见命令包括/new/status/model/personality/retry/undo/sethome/compress/title/resume/usage/reload-mcp/background而/tools、/toolsets、/browser之类通常更偏 CLI。9. cron、后台任务与自动化Hermes 的 cron 是“在新 session 中运行一个 agent 任务”而不是单纯执行系统计划任务。所以最关键的规则是你的 prompt 必须完全自包含。创建 job/cronadd0 9 * * 1生成每周 AI 摘要并发送到 home channel。或hermescroncreate0 9 * * 1生成每周 AI 摘要并发送到 home channel。--nameweekly-ai常见管理/cron list /cron runjob_id/cron pausejob_id/cron resumejob_id背景任务如果只是想把当前任务异步化而不是按时间重复执行/background 总结这个仓库的工具系统并写一份建议。自动化设计的一个好模式脚本负责抓数据、做机械步骤、保存状态 agent 负责解释、筛选、总结很多监控类任务还应该显式约定如果没有变化回复[SILENT]。这样不会把通知刷屏。10. 开发扩展如果你要修改这个仓库先记住关键结构run_agent.pyAIAgent 核心循环cli.pyCLIgateway/run.pyGatewaymodel_tools.py工具发现和 dispatchtools/registry.py工具注册toolsets.py工具分组新增 tool 的最小路径一般要动 3 个地方tools/your_tool.pytoolsets.pymodel_tools.py其中 handler 应返回 JSON 字符串错误也应包装成 JSON。新增 slash command一般要动hermes_cli/commands.pycli.pygateway/run.py如果 Gateway 也支持profile-safe 规则不要硬编码~/.hermes。代码里应使用get_hermes_home()用户可见提示中应使用display_hermes_home()本仓库开发测试sourcevenv/bin/activate python-mpytest tests/-qpython-mpytest tests/test_model_tools.py-qpython-mpytest tests/gateway/-qpython-mpytest tests/tools/-q11. 调试、测试与排障遇到问题时先按层次判断安装层hermes能否启动 provider 层认证、API key、base URL tool 层toolset 是否启用依赖是否满足 MCP 层server 是否加载 Gateway 层token、allowlist、home channel 上下文层skills、memory、会话状态、prompt cache通用命令hermes doctor hermes status hermes version hermes profile shownameCLI 内常用辅助/model /usage /toolsets /tools list /verboseMCP 问题优先检查mcp_servers键名是否正确 本地依赖命令是否存在 是否执行了/reload-mcp消息平台问题优先检查token 是否正确 allowlist 是否允许当前用户 是否需要 mention home channel 是否配置不要一上来就删整个~/.hermes。大多数问题都可以局部定位。12. 最佳实践最后给你一套更稳的长期使用方式1. 第一条消息尽量把上下文给够不要只说“帮我修一下”。尽量直接给文件路径 错误信息 期望结果 约束条件2. 复杂任务先命名会话/title auth-refactor以后恢复就简单很多。3. 重要规则写进AGENTS.md不要依赖聊天记录记住所有项目约定。4. 长会话定期看/usage必要时/compress不要等上下文快爆了才处理。5. 选对执行方式单一动作直接工具 多步机械流程execute_code 并行分析delegate_task 可复用流程skill6. 用 profile 管隔离工作、个人、bot、实验环境最好分 profile而不是混在一个实例里。7. 对不可信代码使用隔离环境优先 Docker、Daytona 等而不是默认本地 terminal。8. 最小暴露原则toolset、MCP、Gateway 授权都遵循同一个原则只开必须的不要因为“以后可能用到”而默认暴露。