Hermes 0→1
0%

真机安装实录 · 每一步都有证据 · 可复现

Hermes Agent
从 0 到 1

这不是一份“把官方文档翻译一遍”的教程。它是一次真机安装的完整记录： 我在这台 Windows 电脑上从零装到能用，中间撞了 8 个坑， 每一条成功的命令、每一段报错、每一次绕路都原样保留下来。 你可以照着做，也可以照着验收。

写给检查者 · 一页看懂这份作业
教什么

Hermes Agent 的安装 → 配置 → 对话 → 工具调用全流程， 按官方学习路径 Step 1–6 组织，每步一个明确验收标准。

怎么教

先讲为什么再给命令，命令都能一键复制； 每个概念配图、对比表和真实输出，不要求你背命令。

怎么验收

6 步全部真机跑通并有证据（版本号、配置回读、 工具调用日志、自动生成的报告文件）。 见 验收看板。

可复现性

环境、版本、Provider 全部写死在页面上； README.md 里有完整命令序列， 换台机器按顺序执行即可得到同样结果。

6个学习步骤 · 全部通过
17个已加载工具
8个真机踩坑记录
33处命令可一键复制
看验收看板 → 直接从第 1 步开始 去终端沙盒练手
先看结论：Hermes Agent 是一个跑在终端里的 AI Agent。它和普通聊天机器人的 本质区别是 —— 它能真的读写你的文件、执行终端命令、调用工具完成任务， 而不仅仅是“告诉你该怎么做”。

✔学习路径验收看板

按官方 Step 1–6 学习路径逐项核验。点开任意一行看这一步的 验收标准、我实际执行的命令、以及真实输出的证据。

6 / 6步骤验收通过
v0.19.0Hermes 实测版本
3.13.7Python 实测版本
0遗留未解决报错

$ hermes --version Hermes Agent v0.19.0 (2026.7.20) Install directory: P:\student_task\24llm\test1\hermes-agent\venv\Lib\site-packages Install method: pip Python: 3.13.7 OpenAI SDK: 2.24.0

验收标准：hermes 能正常启动并输出版本信息。✅

说明：官方一键脚本在本机因 TLS 被拦截而失败， 因此改为手动复刻安装器（准备 Python 3.13 → 建 venv → pip 安装 → 写启动器）。 详见 Step 1 与 踩坑 #1 / #2。

$ hermes -z "Reply with exactly: HERMES_OK and then state which model you are." HERMES_OK I am DeepSeek-V4-Pro, running on the Hermes Agent framework by Nous Research.

验收标准：能正常与 Hermes 对话。✅

同时验证：交互式 hermes 横幅正常显示 （模型、工作目录、会话 ID、17 tools）， 并且 hermes -c 会话续接可用。详见 Step 2。

$ hermes config get model provider: deepseek default: deepseek-v4-pro $ hermes doctor ✓ .env file exists ✓ API key or custom endpoint configured ✓ config.yaml exists ✓ Config version up to date (v33)

验收标准：能成功配置教师提供的模型 API。✅

要点：机密（API Key）自动落到 .env， 普通配置（provider / model）落到 config.yaml； 模型的 Base URL 由 Provider deepseek 自动推导为 https://api.deepseek.com/v1。详见 Step 3。

$ hermes tools list Built-in toolsets (cli): ✓ enabled web 🔍 Web Search & Scraping ✓ enabled terminal 💻 Terminal & Processes ✓ enabled file 📁 File Operations ✓ enabled code_execution ⚡ Code Execution ... (共 23 个工具集，其中 17 个启用) 交互式 CLI 横幅： deepseek-v4-pro · Nous Research P:\student_task\24llm\test1\demo Session: 20260922_163415_647dda 17 tools · 0 skills · /help for commands

验收标准：能说出当前模型、可用工具和 Context 情况。✅

对应关系：/model → 当前模型 deepseek-v4-pro；/tools → 17 个工具； /status / /context → 会话状态与上下文占用明细。 页面上有命令浏览器可逐个点开看真实输出。

$ hermes doctor ✓ P:\student_task\24llm\test1\.hermes/.env file exists ✓ P:\student_task\24llm\test1\.hermes/config.yaml exists ✓ P:\student_task\24llm\test1\.hermes/SOUL.md exists (persona configured) ✓ P:\student_task\24llm\test1\.hermes/state.db exists (1 sessions)

验收标准：能解释普通配置和 Secret 配置的区别。✅

一句话区别：config.yaml 放不怕被看到的设置 （可以分享/提交 Git）；.env 放泄露就出事的凭据 （只留在本机）。Hermes 用命名规则自动分流：全大写下划线 → .env， 小写点号路径 → config.yaml。详见 Step 5。

$ hermes chat -q "读取 data/scores.csv，统计每科平均分与总分， 找出总分最高的学生和需要重点关注（总分低于210）的学生， 并把结果写成 result/report.md，同时在终端打印这个文件的完整内容。" （详细日志） 🛠️ Loaded 17 tools: … read_file, search_files, terminal, write_file … tools.terminal_tool - local environment ready for task default agent.tool_executor - tool terminal completed (1.63s, 193 chars) agent.tool_executor - tool terminal completed (0.31s, 58 chars) Turn ended: reason=text_response model=deepseek-v4-pro api_calls=2/90 tool_turns=1 → 产出文件 demo/result/report.md

验收标准：完成一次读取文件、处理数据并生成结果文件的 Tool Calling。✅

结果复核：语文平均 78.0、数学 76.6、英语 78.5； 总分最高王五 287 分；总分低于 210 的 3 人（周九 166、赵六 189、王二 196） —— 人工重算完全一致。 页面上有工具调用回放可逐步观看。详见 Step 6。

选读项，未作为验收标准。本教程的六步结构即按该学习路径的顺序组织； 官方针对不同经验水平给出的分支建议（新手走 Quickstart、进阶直接看 Tools / Skills） 已吸收进本页导航与 FAQ。

产出物在哪

下面这些文件是这份作业的可检查实体，不是页面上的文字：

test1/hermes.cmd 一键启动器。设置 HERMES_HOME、UTF-8 控制台、Git Bash 路径后调用 Hermes，等价于官方安装器写入的 hermes.cmd。 任意目录可用
test1/.hermes/config.yaml 普通配置：模型、Provider、终端后端、显示选项。_config_version: 33。 已 migrate 到 v33
test1/.hermes/.env 机密配置：DEEPSEEK_API_KEY。由 hermes config set 自动分流写入。 ⚠ 不要外传
test1/demo/data/scores.csv Step 6 的输入数据：10 名学生 4 个字段，含出勤率与低分样本。 335 B
test1/demo/result/report.md Step 6 的产出：由 Hermes 通过 write_file 工具真实落盘的成绩统计报告。 540 B · 已人工复核
test1/README.md 完整文字版记录：学习路径对照表、目录结构、安装命令序列、8 个踩坑与解决办法。 可复现步骤

§先搞懂 4 个词

后面所有步骤都建立在这 4 个概念上，30 秒看完。

🏷️

Provider

“模型服务商”。谁给你提供大模型算力。例如 deepseek、openrouter、anthropic。

🧠

Model

“具体哪个模型”。同一个 Provider 下可以有多个模型，例如 deepseek-v4-pro。

🔑

API Key

“通行证”。证明请求是你发的。属于机密，只能放进 .env。

🌐

Base URL

“服务器地址”。请求发到哪个域名，例如 https://api.deepseek.com/v1。

一句话关系： 你拿着 API Key，向 Base URL 这个地址，指定要用的 Model，请求由 Provider 提供服务。

六步路线图

这就是接下来的主线。每一步都有明确的验收标准， 做完一步再走下一步 —— 不要跳步，这是新手最容易翻车的地方。

Step 1 装好它 让 hermes 能启动 Step 2 跑通第一次对话 初始化 + 说上话 Step 3 配一个模型 Provider / Key / Base URL Step 4 学会看状态 /model /tools /status /context Step 5 看懂配置文件 config.yaml vs .env Step 6 让它干一件真事 读文件 → 处理 → 写结果

💡 侧边栏底部的「资料与自测」里还有： 终端沙盒（亲手敲命令看输出）、 踩坑与排错、 FAQ、 自测题 和 学习心得与边界。

Step 1

安装 Hermes Agent

目标：让 hermes 这条命令能正常启动。

验收标准 终端里敲 hermes，能看到欢迎界面和版本号

1.1 官方给的安装方式

官方文档提供了两种方式，优先用第一种：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

不需要管理员权限。安装器会把东西放进 %LOCALAPPDATA%\hermes\，并把 hermes 加进用户 PATH —— 装完必须新开一个终端窗口才生效。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

装完执行 source ~/.bashrc 或 source ~/.zshrc 重新加载环境。

适合不想碰命令行的同学：从官网下载 Hermes Desktop 安装包，双击安装。 它内部同样会调用 install.ps1 去准备 Python、Node、Git 等依赖。

1.2 安装器到底做了什么

理解这 5 件事，后面出问题你才知道去哪儿找：

  1. 装 uv一个很快的 Python 包管理器，装在 %USERPROFILE%\.local\bin
  2. 装 Python 3.11用 uv 装，不需要你本机预先有 Python
  3. 装 Node.js 26给浏览器工具和 WhatsApp 桥接用
  4. 准备 Git / PortableGit给终端工具用的 bash.exe（Hermes 跑命令靠它）
  5. 克隆仓库 + 建虚拟环境代码放在 %LOCALAPPDATA%\hermes\hermes-agent
关键限制：Python 版本必须在 3.11 ~ 3.13 之间。

这是我在真机上撞的第一个墙。Hermes 的包元数据里写着 Requires-Python: >=3.11,<3.14。 如果你本机是 Python 3.14，直接装会失败 —— 但安装器会自动帮你装 3.11，所以官方脚本是安全的。 只有手动安装（像本文档下面这种）才需要注意。

1.3 我这台机器上的实际安装过程

因为这台电脑的沙箱禁止写入 %LOCALAPPDATA%，官方的一键脚本没法用。 于是我在 test1 文件夹里做了一次 “手动复刻官方安装器” 的操作。 这个过程反而更适合教学，因为它把黑盒拆开了。

① 准备一个合规的 Python 3.13（工作区内，免管理员）

直接从 npmmirror 拉官方 Python 3.13 的 zip 包并解压，这样不需要管理员权限、也不污染系统。

# 下载并解压出完整版 Python 3.13.7
Expand-Archive -Path "_tools\python-3.13.7-amd64.zip" `
               -DestinationPath "_tools\python313full" -Force

# 验证
& "_tools\python313full\python.exe" -c "import sys,venv;print(sys.version)"
3.13.7 (tags/v3.13.7:bcee1c3, Aug 14 2025, 14:15:11) [MSC v.1944 64 bit (AMD64)]
② 建虚拟环境（venv）

虚拟环境 = 给 Hermes 一个**独立的 Python 世界**，它装的包不会和系统 Python 打架。

& "_tools\python313full\python.exe" -m venv "hermes-agent\venv"
③ 安装 Hermes Agent 本体 
& "hermes-agent\venv\Scripts\python.exe" -m pip install "hermes-agent[messaging,dashboard]"
Successfully installed … hermes-agent-0.19.0
④ 把它变成一条能直接敲的 hermes 命令

官方安装器会写一个 hermes.cmd 到 %LOCALAPPDATA%\hermes\bin。 我们自己写一个等价物，放在项目根目录：

@echo off
set "HERMES_ROOT=%~dp0"
REM 数据目录：配置、密钥、会话、技能都存在这里
if "%HERMES_HOME%"=="" set "HERMES_HOME=%HERMES_ROOT%.hermes"
REM UTF-8，避免中文/emoji 让 Python 崩掉
set "PYTHONUTF8=1"
set "PYTHONIOENCODING=utf-8"
REM Hermes 的终端工具靠 Git Bash 执行命令
set "HERMES_GIT_BASH_PATH=P:\Tool\Git\Git\bin\bash.exe"
"%HERMES_ROOT%hermes-agent\venv\Scripts\hermes.exe" %*

1.4 验收：确认装好了

hermes --version

你应该看到类似输出（这是本机的真实输出）：

Hermes Agent v0.19.0 (2026.7.20) Install directory: …\hermes-agent\venv\Lib\site-packages Install method: pip Python: 3.13.7 OpenAI SDK: 2.24.0
下一步：初始化与第一次对话 →
Step 2

初始化与第一次对话

目标：完成初始化、配置模型，然后真的和 Hermes 聊上话。

验收标准 输入一句话，Hermes 能正常回复，并且能连续对话多轮

2.1 两种初始化方式

🪄 hermes setup

完整向导，一次性配好模型、工具、平台。新装推荐。

hermes setup

还会问你三种模式：Quick Setup（Nous Portal，免密钥）、 Full Setup（自己填密钥）、Blank Slate（最小化，只开文件+终端）。

🎯 hermes model

只配模型和 Provider，最快。已经知道用哪家模型就选这个。

hermes model

交互式选择 Provider → Model，选完自动写进配置文件。

2.2 非交互式配置（脚本 / 自动化场景）

本文这套环境用的就是这种：不进交互界面，直接写配置。

# 1) 存 API Key —— 注意：它会自动写进 .env，不会写进 config.yaml
hermes config set DEEPSEEK_API_KEY sk-xxxxxxxxxxxxxxxx

# 2) 指定 Provider 和默认模型 —— 这两个是普通配置，写进 config.yaml
hermes config set model.provider deepseek
hermes config set model.default  deepseek-v4-pro

# 3) 回读确认
hermes config get model
✓ Set DEEPSEEK_API_KEY in …\.hermes\.env ✓ Set model.provider = deepseek in …\.hermes\config.yaml ✓ Set model.default = deepseek-v4-pro in …\.hermes\config.yaml provider: deepseek default: deepseek-v4-pro
这里藏着 Step 5 的考点： 同一句 hermes config set，全大写下划线的名字（DEEPSEEK_API_KEY） 自动进 .env；带点的小写路径（model.provider）自动进 config.yaml。 你不用自己判断，Hermes 帮你分流。

2.3 跑通第一次对话

先试单次问答模式，最容易验证：

hermes -z "你好，请用一句话介绍你自己"

本机真实返回：

你好！我是 Hermes Agent，一个由 Nous Research 打造的终端原生 AI 助手， 可以直接读写你的文件、执行命令，帮你把任务真正做完。

然后是交互式对话（这才是日常用法）：

hermes           # 经典 CLI
hermes --tui     # 新版 TUI（鼠标友好，推荐）

启动后你会看到什么

下面是本机 hermes 启动时的真实横幅（节选）：

2.4 验证会话可以续接

会话（session）是 Hermes 的记忆载体。一定要确认它能恢复：

hermes --continue    # 恢复最近一次会话
hermes -c            # 简写
真机踩坑 #1：不要用管道喂输入给交互式 CLI。

我尝试过 "/help`n/exit`n" | hermes --cli 想自动化截取输出， 结果 prompt_toolkit 直接抛异常崩溃：

File "…\prompt_toolkit\application\current.py", line 67, in output self._output = create_output()

结论：交互式 CLI 需要真正的终端（TTY）。要自动化测试，请用 hermes -z "…" 或 hermes chat -q "…" 这种单次问答模式。

下一步：搞懂模型配置 →
Step 3

Provider / 模型配置

目标：理解 Provider、Model、Base URL、API Key 的关系，并成功配上老师给的模型。

验收标准 能成功调用配置好的模型 API，并说清这 4 个概念的对应关系

3.1 数据是怎么流动的

把下面这张图记住，配置模型永远不会迷路：

🧑你输入问题
→
⚙️Hermes组装上下文 + 工具
→
🌐Base URLapi.deepseek.com/v1
→
🔑API Key身份验证
→
🧠Modeldeepseek-v4-pro

在你自己的配置文件里，它们长这样

config.yaml  普通配置

model:
  provider: deepseek        # Provider
  default: deepseek-v4-pro  # Model

.env  机密

DEEPSEEK_API_KEY=sk-…     # API Key

Base URL 通常不用手写 —— Hermes 认得 deepseek 这个 Provider， 会自己用官方地址 https://api.deepseek.com/v1。只有用自建/代理端点时才需要显式设置 model.base_url。

3.2 主流 Provider 速查

Hermes 支持非常多 Provider。点开看每个需要哪个环境变量：

Provider是什么需要设置的环境变量
Nous Portal官方订阅制，免密钥管理hermes setup --portal（OAuth 登录）
DeepSeekDeepSeek 官方直连 本文使用DEEPSEEK_API_KEY
OpenRouter聚合路由，一个 Key 用几百个模型OPENROUTER_API_KEY
AnthropicClaude 系列ANTHROPIC_API_KEY
OpenAIGPT 系列OPENAI_API_KEY
Google AI StudioGemini 系列GOOGLE_API_KEY / GEMINI_API_KEY
Kimi / Moonshot月之暗面KIMI_API_KEY
Z.AI / GLM智谱 GLMGLM_API_KEY / ZAI_API_KEY
Alibaba Cloud通义千问DASHSCOPE_API_KEY
Hugging Face开源模型路由器HF_TOKEN
xAIGrokXAI_API_KEY
LM Studio / Ollama本地跑模型LM_API_KEY + LM_BASE_URL
Custom Endpoint任何 OpenAI 兼容接口base_url + api_key

3.3 手动配置自定义端点（学校/公司常见）

如果老师给的是私有地址，比如 https://ai.school.edu/v1，就这样写：

model:
  provider: custom
  default: 老师的模型名
  base_url: https://ai.school.edu/v1
# 自定义端点的密钥变量名要和 Provider 定义对应
CUSTOM_API_KEY=老师给的密钥
硬性要求：模型上下文至少 64,000 tokens。

Hermes 启动时会检查。上下文窗口太小的模型撑不住多步工具调用，会被直接拒绝。 大多数云端模型（Claude / GPT / Gemini / DeepSeek / Qwen）都轻松满足； 本地模型记得把上下文设到 64K 以上，例如 llama.cpp --ctx-size 65536。

3.4 验证配置是否真的生效

hermes status     # 看 Provider / Model / API Key 状态
hermes doctor     # 完整体检，包括连通性测试

本机 hermes doctor 的真实体检结果（节选）：

✓ Python 3.13.7 ✓ Virtual environment active ✓ .env file exists ✓ API key or custom endpoint configured ✓ config.yaml exists ✓ Config version up to date (v33) ✓ git ✓ ripgrep (rg) (faster file search) ✓ Node.js
真机踩坑 #2：把模型写成了字符串，doctor 会警告。

一开始我用 hermes config set model deepseek-v4-pro， 结果 config.yaml 里变成了一行 model: deepseek-v4-pro， doctor 报 Could not validate model/provider config ('str' object has no attribute 'get')。

原因：新版配置里 model 是一个映射（mapping），不是一个字符串。 修法：先 hermes config unset model，再分别设置 model.provider 和 model.default。

下一步：CLI 常用指令 →
Step 4

CLI 常用指令

目标：熟练使用 /help、/model、/tools、/status、/context。

验收标准 能说出：当前用的是哪个模型、有哪些工具可用、Context 占用多少

4.1 两种“命令”，别搞混

🖥️ 终端命令 在 shell 里敲

启动前 / 启动外使用，不进入对话。

hermes status
hermes doctor
hermes config get model

💬 斜杠命令 在对话里敲

已经进入 hermes 对话界面后使用，输入 / 会弹出自动补全。

/help
/status
/context

4.2 五个必会斜杠命令

点击卡片展开详细说明 👇

4.3 hermes tools：查看工具清单

想在不进入对话的情况下看工具，用这个（本机真实输出）：

hermes tools list
✓ enabled web 🔍 Web Search & Scraping ✓ enabled browser 🌐 Browser Automation ✓ enabled terminal 💻 Terminal & Processes ✓ enabled file 📁 File Operations ✓ enabled code_execution ⚡ Code Execution ✓ enabled vision 👁️ Vision / Image Analysis ✓ enabled memory 💾 Memory ✓ enabled delegation 👥 Task Delegation ✗ disabled video 🎬 Video Analysis ✗ disabled homeassistant 🏠 Home Assistant
小技巧：! 前缀直接执行 shell。

在对话里输入 !git status，Hermes 会直接执行这条命令： 不消耗 token、不进对话历史、不产生费用。 它是“查看信息”的最快方式。

4.4 两个省时间的命令

命令作用什么时候用
/title 我的实验给当前会话起名以后 /resume 我的实验 就能找回
/compress手动压缩上下文对话太长、快撞上下文上限时
/btw 问题问一个旁支问题不想打断当前任务，又想知道点别的
/undo撤销上一轮问答说错话、想重来
/exit退出收工

4.5 上下文是什么，为什么重要

Context（上下文）= 模型这一次能“看到”的全部内容，包括： 系统提示词、工具定义、技能索引、记忆、以及你们的对话历史。

它是有上限的（由模型决定）。占满了，Hermes 就得压缩历史 —— 会有信息损失。 所以 /context 是你经常要看的仪表盘。

上下文占用示意 0 / 128,000 tokens

💡 鼠标悬停 / 点击色块查看各分类占用。数据为示意，实际请以 /context 输出为准。

下一步：配置文件与密钥 →
Step 5

配置文件与密钥

目标：找到并看懂 config.yaml 和 .env，说清普通配置与 Secret 配置的区别。

验收标准 能解释：什么该放 config.yaml，什么必须放 .env，为什么

5.1 Hermes 的数据目录长什么样

所有属于“你”的东西都在这一个目录里（Linux/macOS 是 ~/.hermes/， Windows 原生是 %LOCALAPPDATA%\hermes\）：

📁 .hermes/
📄config.yaml 普通配置：模型、终端后端、压缩策略…
🔒.env 机密：API Key、Bot Token、密码
🎫auth.json OAuth 凭证（Nous Portal 等登录态）
🪞SOUL.md Agent 的人格设定（系统提示词第一段）
📁memories/ 长期记忆：MEMORY.md、USER.md
📁skills/ 技能库：每个技能一个 SKILL.md
📁sessions/ 会话记录
📁logs/ 日志（会自动打码密钥）
🗄️state.db SQLite 状态库

👆 点击任意一项，看它的作用与示例内容。

5.2 核心区别：普通配置 vs Secret 配置

这是 Step 5 最重要的知识点。一句话记住：

📄
config.yaml普通配置
  • 放 不怕被人看到的设置
  • 模型、Provider、Base URL
  • 工具开关、终端后端
  • 上下文压缩阈值、超时
  • 可以提交到 Git、可以分享
  • 用小写点号路径设置：model.provider
model:
  provider: deepseek
  default: deepseek-v4-pro
terminal:
  backend: local
vs
🔒
.envSecret 配置
  • 放 泄露就会出事的东西
  • API Key、访问令牌
  • Bot Token、数据库密码
  • 绝对不能提交到 Git
  • 不能随便截图、不能贴群里
  • 用全大写下划线设置：DEEPSEEK_API_KEY
DEEPSEEK_API_KEY=sk-…
TELEGRAM_BOT_TOKEN=…
为什么必须分开？

因为两者的生命周期完全不同：config.yaml 你想备份、想分享、 想同步到另一台电脑；.env 你希望它永远只留在本机。 混在一起，你备份配置的时候就顺手把密钥泄露出去了。

5.3 配置优先级（谁说了算）

同一个设置被写在多个地方时，Hermes 按这个顺序取（从高到低）：

1命令行参数hermes chat --model xxx最高
2config.yaml所有非机密设置主要
3.env环境变量回退 + 机密必需次之
4内置默认值什么都没设时的安全默认兜底

注意：对于非机密设置，如果两处都写了，config.yaml 赢。 但机密的值只能从 .env（或系统环境变量）来。

5.4 管理命令速查

hermes config              # 查看当前完整配置
hermes config get KEY      # 读取某个值
hermes config set KEY VAL  # 设置某个值（自动分流到正确文件）
hermes config unset KEY    # 删除用户设置的值
hermes config check        # 检查是否有缺失项（升级后常做）
hermes config migrate      # 交互式补齐新增配置项
hermes config edit         # 用编辑器直接打开 config.yaml
真机踩坑 #3：升级后记得跑 config migrate。

刚装好时 doctor 报 Config version outdated (v0 → v33)。 执行 hermes config migrate 后变成 ✓ Config version up to date (v33)。 不迁移也能跑，但会缺少新版本才有的一些默认设置。

5.5 安全加分项：密钥自动打码

Hermes 默认开启 secret redaction： 看起来像 API Key / Token / 密码的字符串，会在工具输出、日志、聊天回复里被自动打码， 模型和你自己都看不到原文。这是默认行为，不用配置。

下一步：Tool Calling 实战 →
Step 6

Tool Calling 实战

目标：让 Hermes 真的读文件、处理数据、生成结果文件 —— 而不是“嘴上说说”。

验收标准 完成一次完整的「读文件 → 处理数据 → 生成结果文件」工具调用

6.1 什么是 Tool Calling

普通聊天机器人只能输出文字。Hermes 能做的是：

1 你提需求 “统计这个 CSV 并写成报告”
↓
2 模型决定调工具 它输出一个结构化的工具调用请求：read_file("scores.csv")
↓
3 Hermes 真的执行它 读磁盘、跑命令 —— 这一步发生在你的电脑上
↓
4 结果回传给模型 模型看到真实数据，继续下一步（可能再调工具）
↓
5 产出结果 写成文件 + 给你总结
所以：“工具”是模型的手和脚。模型负责决策，Hermes 负责执行。

6.2 Hermes 有哪些工具

按 Toolset（工具集）分组，常用的这几组：

📁file文件
  • read_file — 读文件内容
  • write_file — 创建 / 覆盖文件
  • patch — 精准修改文件片段
  • search_files — 按内容搜索文件
💻terminal终端
  • terminal — 执行 shell 命令
  • process — 管理后台进程
  • read_terminal — 读终端输出
  • Windows 上通过 Git Bash 执行
⚡code_execution代码
  • execute_code — 直接跑 Python 片段
  • 适合数据处理、计算、格式转换
🔍web网络
  • 网页搜索
  • 抓取网页内容
  • 需要额外的搜索服务密钥
💾memory记忆
  • 跨会话记住你的偏好
  • 写进 memories/
  • 下次会话自动注入
📋todo规划
  • 把复杂任务拆成清单
  • 自己跟踪进度
  • 长任务必备

6.3 实战：一次完整的工具调用

我在 demo/ 目录下准备了一个有 10 名学生的成绩 CSV， 然后让 Hermes 去处理它。这是真实执行过的过程。

📥 第一步：准备数据文件 demo/data/scores.csv 
姓名,学号,语文,数学,英语,出勤率
张三,2024001,88,92,79,0.96
李四,2024002,72,65,81,0.88
王五,2024003,95,98,94,0.99
赵六,2024004,61,58,70,0.72
钱七,2024005,83,77,85,0.91
孙八,2024006,90,85,88,0.94
周九,2024007,55,49,62,0.65
吴十,2024008,78,82,76,0.89
郑一,2024009,92,89,91,0.97
王二,2024010,66,71,59,0.80
🗣️ 第二步：下达指令 
cd demo

hermes chat -q "读取 data/scores.csv，统计每科平均分与总分，
找出总分最高的学生和需要重点关注（总分低于210）的学生，
并把结果写成 result/report.md，同时在终端打印这个文件的完整内容。"

这是一个好指令的范例：说清了 输入（哪个文件）、要算什么（平均分/总分/筛选条件）、 输出到哪（result/report.md）、怎么验证（打印出来）。

🔧 第三步：Hermes 真的调用了工具

开启 -v 详细日志后，能看到工具真实被调用了：

✅ Enabled toolset 'terminal': close_terminal, process, read_terminal, terminal 🛠️ Loaded 17 tools: clarify, cronjob, delegate_task, execute_code, memory, patch, process, read_file, search_files, session_search, skill_manage, skill_view, skills_list, terminal, text_to_speech, todo, write_file tools.terminal_tool - Creating new local environment for task default… tools.terminal_tool - local environment ready for task default agent.tool_executor - tool terminal completed (1.63s, 193 chars) agent.tool_executor - tool terminal completed (0.31s, 58 chars) Turn ended: reason=text_response model=deepseek-v4-pro api_calls=2/90 tool_turns=1

读法：加载了 17 个工具 → 创建本地执行环境 → terminal 工具执行了两次（1.63s 和 0.31s）→ 模型拿到结果后给出最终答案。 整轮只用了 2 次 API 调用。

📤 第四步：产出结果文件 demo/result/report.md

这个文件不是模型凭空写的，是 Hermes 用 write_file 工具真实落盘的：

# 成绩统计报告

## 各科平均分

| 科目 | 平均分 |
|------|--------|
| 语文 | 78.0 |
| 数学 | 76.6 |
| 英语 | 78.5 |
| **总分** | **233.1** |

## 总分最高的学生

- 王五（学号 2024003）：总分 287 分

## 需要重点关注的学生（总分低于 210）

| 姓名 | 学号 | 语文 | 数学 | 英语 | 总分 |
|------|------|------|------|------|------|
| 周九 | 2024007 | 55 | 49 | 62 | 166 |
| 赵六 | 2024004 | 61 | 58 | 70 | 189 |
| 王二 | 2024010 | 66 | 71 | 59 | 196 |

✅ 人工核对：语文 (88+72+95+61+83+90+55+78+92+66)/10 = 78.0 ✔️ 王五 95+98+94 = 287 ✔️ 低于 210 的 3 人正确 ✔️

6.4 工具调用回放（逐步播放）

把上面那次的真实执行过程拆成 7 步。点「开始回放」， 像看调试器一样看 Hermes 每一步在做什么 —— 这是理解 Agent 最快的方式。

Tool-call trace deepseek-v4-pro · 2 API calls · 1 tool turn
点「开始回放」看 Hermes 如何把一句话变成一份报告。

6.5 自己也来试一次（可复制的练习）

# 1) 建一个测试目录
mkdir my-first-task && cd my-first-task
echo "hello hermes" > note.txt

# 2) 让 Hermes 干活
hermes -z "读一下 note.txt，然后用中文写一个 summary.md，
包含文件里的内容和它的字符数。"

跑完后 ls 一下，你会看到 summary.md —— 这就是 Agent 和聊天机器人的分界线。

6.6 写出好指令的 4 个要素

① 输入哪个文件 / 哪个目录
② 动作要做什么处理
③ 输出结果写到哪、什么格式
④ 验证怎么让你确认它做对了

❌ 模糊：“帮我看看这个数据”

✅ 明确：“读取 data/scores.csv，算出每科平均分， 把结果写成 result/report.md（Markdown 表格），并在终端打印出来。”

安全提醒：工具是有真实权限的。

terminal 能执行命令、write_file 能改文件。 所以 Hermes 对危险命令默认会弹审批确认 （rm -rf、改配置文件等）。 在陌生目录跑之前，先想清楚；想隔离，可以切到 Docker 后端： hermes config set terminal.backend docker。

下一步：去终端沙盒亲手敲一遍 →

▶终端沙盒：亲手敲一遍

前面看了很多命令，但看懂 ≠ 会用。这里是一个安全的模拟终端 —— 输出全部来自我本机的真实记录。点下面的按钮，或者直接在输入框里敲。

hermes-lab — PowerShell（模拟，非真实执行）

⌨️ 也可以直接输入：help 看可用命令， clear 清屏。支持 hermes、hermes doctor、 hermes status、hermes tools list、 hermes config get model、/context、/status 等。

为什么这是模拟的？

网页不能真的执行你电脑上的命令 —— 那太危险也太慢。 所有输出都是我在这台机器上跑出来的真实结果， 这样你既能安全地反复练手，看到的又不是编造的内容。 想看真机输出，请按 Step 1 自己装一遍。

下一步：看我踩过的坑 →
实录

我踩过的坑 & 排错手册

这些不是网上抄的，是我在这台机器上真实撞到的。

7.1 坑 #1：TLS 握手失败，什么都下不下来

现象 irm https://… / curl 全部失败
基础连接已经关闭: 接收时发生错误。 curl: (35) schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS

诊断：SEC_E_NO_CREDENTIALS 是 Windows 的 TLS 后端（schannel） 拿不到凭据。TCP 能连通（端口测试是通的），但加密握手建不起来。

绕过办法：换一个用自己的 TLS 实现的下载器。 Node.js 自带 OpenSSL，不依赖 schannel，所以能用：

// 用 Node 的 fetch 下载文件（绕过 schannel 问题）
const r = await fetch(url, { redirect: 'follow' });
const buf = Buffer.from(await r.arrayBuffer());
fs.writeFileSync(dest, buf);

结论：遇到 TLS/证书类报错，先试 Node / Python / 浏览器下载。 不同工具用的 TLS 栈不同，这是最实用的排查直觉。

7.2 坑 #2：Python 3.14 装不上 Hermes

现象 pip 解析依赖失败

根因：查 PyPI 元数据发现 ——

requires_python: <3.14,>=3.11

本机是 Python 3.14.6，超出了支持范围。

解决：另外准备一个 Python 3.13，用它建 venv。

# 检查你的 Python 版本
python --version          # 必须是 3.11 / 3.12 / 3.13

# 如果是 3.14+，用官方安装器（它会自带一个 3.11）
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

7.3 坑 #3：没有 bash.exe，终端工具不能用

现象 终端工具报找不到 bash

原因：Windows 上没有 bash。Hermes 的 terminal 工具是通过 Git Bash 执行命令的（和 Claude Code 一个策略）。

坑中坑：我下载了 MinGit，结果里面只有 sh.exe 和 dash.exe，没有 bash.exe。原因是 MinGit 有多个变体：

包名里面有什么能用吗
MinGit-*-busybox-64-bit.zip只有 ash，缺 coreutils✗ 不行
MinGit-*-64-bit.zip有 sh、dash…△ 不稳
PortableGit-*.7z.exe完整 MSYS2：bash+365 个 coreutils✓ 推荐
系统安装的 Git for Windows自带 bash✓ 最省事

解决：找到 bash 后，用环境变量明确告诉 Hermes：

# 方式一：系统已装 Git for Windows
$env:HERMES_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"

# 方式二：便携版 Git
$env:HERMES_GIT_BASH_PATH = "P:\path\to\portablegit\bin\bash.exe"

# 验证
& $env:HERMES_GIT_BASH_PATH -c "echo BASH_OK"

Hermes 的查找顺序： HERMES_GIT_BASH_PATH → %LOCALAPPDATA%\hermes\git\usr\bin\bash.exe → …\git\bin\bash.exe → 系统 Git → PATH 上任意 bash。

7.4 坑 #4：ripgrep 下载被墙 / 缺 DLL

现象 winget install ripgrep 失败；解压出的 rg.exe 无法运行
InternetOpenUrl() failed. 0x80072efd rg.exe 退出码 -1073741515 （0xC0000135 = DLL not found）

两步解决：

① 从国内镜像（清华 MSYS2 源）拿包，而不是 GitHub Releases：

https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/mingw64/
  mingw-w64-x86_64-ripgrep-15.1.0-1-any.pkg.tar.zst

② 解压后 rg.exe 还缺依赖 DLL。用 PE 头分析出它需要 libpcre2-8-0.dll， 一起装上就好了：

# 用 Windows 自带的 bsdtar 解 zst 包（支持 zstd）
tar.exe -xf ripgrep.tar.zst -C .\rg

# 再补上 PCRE2 运行库
tar.exe -xf pcre2.tar.zst -C .\pcre2
Copy-Item .\pcre2\mingw64\bin\libpcre2-8-0.dll .\bin\

# 验证
.\bin\rg.exe --version
ripgrep 15.1.0

💡 通用技巧：Windows 报 0xC0000135 / “无法启动此程序”， 99% 是缺 DLL。用 PE 头的导入表（imports）能精确找出缺哪个。

7.5 通用排错顺序

出问题时，按这个顺序走，不要乱试：

1
hermes doctor

体检。它会直接告诉你哪一项不合格、怎么修。

2
hermes status

看 Provider / Model / API Key 是否都被识别到。

3
hermes config check

升级后配置项缺失？跑 hermes config migrate。

4
hermes model

重新选一遍 Provider 和模型，排除配置写错。

5
hermes sessions list

-c 找不到会话？确认在同一个 profile 下。

黄金法则：基础聊天没通，就不要加新功能。

先让一次干净的对话跑起来，再去加 gateway、cron、skills、语音。 跳过这一步是绝大多数“装好了但什么都不会干”的根源。

✓

自测与速查表

检验一下：这 6 步你真的学会了吗？

8.1 六道自测题

选完立刻出结果，没有提交按钮。

0/6

开始答题吧 👆

8.2 命令速查表

命令作用类型
hermes启动交互式对话启动
hermes --tui启动新版 TUI 界面启动
hermes -z "问题"单次问答，不进入交互启动
hermes chat -q "问题"同上（chat 子命令形式）启动
hermes -c恢复最近一次会话启动
hermes setup完整初始化向导配置
hermes model交互式选择 Provider / 模型配置
hermes tools配置启用哪些工具配置
hermes tools list列出所有工具及启用状态配置
hermes config get KEY读取配置值配置
hermes config set K V设置配置值（自动分流）配置
hermes config migrate升级后补齐新增配置配置
hermes doctor完整体检 + 修复建议诊断
hermes status查看各组件状态诊断
hermes sessions list列出历史会话诊断
hermes logs查看日志诊断
hermes gateway setup配置消息平台（TG/Discord…）扩展
hermes cron管理定时任务扩展
hermes skills browse浏览技能库扩展
hermes update升级到最新版本维护
hermes uninstall卸载维护

8.3 五个必会斜杠命令

/help列出所有命令
/model看 / 换当前模型
/tools列出可用工具
/status会话状态 + 回顾
/context上下文占用明细

8.4 下一步可以学什么

🧩

Skills 技能系统

把重复的工作流固化成 SKILL.md，之后一句话就能复用。

hermes skills browse

💬

Gateway 消息网关

把 Hermes 接到 Telegram / Discord / Slack，手机上也能用。

hermes gateway setup

⏰

Cron 定时任务

让它每天自动跑报表、自动巡检，不用你开口。

hermes cron

🎉

你走完了 0 → 1

现在你已经能：安装 Hermes、配好模型、用 CLI 管理它、看懂配置文件、 并让它真的帮你处理文件。剩下的就是用它做真实的事。

❓常见问题 FAQ

这些是我在装的过程中真的想问、以及同学最常问的问题。点问题展开答案。

能。有三条零成本路线：

  • 本地模型：用 Ollama 或 LM Studio 在本机跑开源模型，完全免费、数据不出电脑。 hermes model → 选本地/自定义端点。注意上下文必须设到 64K 以上。
  • 免费额度：部分 Provider 新用户有赠额；OpenRouter 上也有 :free 后缀的免费模型。
  • 同学/老师提供的 Key：本教程用的就是这种 —— 老师给一个 DeepSeek Key， 写进 .env 即可。

关键点：Hermes 本身不要钱，花钱的只是模型调用。前期学习阶段用量很小， 一天几毛钱量级。

99% 是 PATH 没刷新。官方安装器把 %LOCALAPPDATA%\hermes\bin 加进了用户 PATH，但已经打开的终端不会自动生效。

做法：完全关掉终端窗口，重新开一个（不是新标签页）。 临时救急可以直接用全路径：

& "$env:LOCALAPPDATA\hermes\bin\hermes.exe" --version

本教程因为装在工作区，用的是 test1\hermes.cmd，它在任意目录都能跑。

按这个顺序查，基本三步内定位：

  • hermes doctor —— 看有没有 ⚠。它会直接说哪一项不合格。
  • hermes status —— 确认 Provider / Model / API Key 三个都被识别到。
  • 自定义端点「能通但输出垃圾」—— 十有八九是 base_url 或模型名写错， 或者那个端点其实不是 OpenAI 兼容的。先用 curl 单独验证一次端点。

最常见的两个错：模型名拼错；把 API Key 写进了 config.yaml 而不是 .env。

这个担心是对的 —— 工具确实有真实权限。但 Hermes 有几层保护：

  • 危险命令审批：rm -rf、改配置这类操作默认会弹确认， 必须你同意才执行。
  • 检查点与回滚：支持文件系统快照，/rollback 可以回到之前的状态。
  • 容器隔离：hermes config set terminal.backend docker， 让它在容器里干活，碰不到你的真实系统。
  • 密钥打码：形似密钥的字符串在输出和日志里自动被打码。

实用建议：先在一个专门的测试目录里玩（就像本教程的 demo/）， 不要一上来就指向你的论文目录。

因为 prompt cache（提示词缓存）。系统提示词、工具定义、你的历史对话 在第二次请求时大部分没变，Provider 会把它们缓存起来，命中缓存的部分 计费大幅打折（常见是 1/10 左右）。

本机日志里就能看到：

API call #2: model=deepseek-v4-pro in=13596 out=93 total=13689 latency=2.7s cache=13440/13596 (99%)

实用推论：频繁中途换模型会清空缓存， 下一轮要按全价重读整个对话。所以「能一次选好模型就别换来换去」。

差在能不能动手。网页版只能给你文字，你自己去复制、去执行。 Hermes 是「有手有脚」的：

  • 能读你指定的文件（read_file）
  • 能执行终端命令（terminal，通过 Git Bash）
  • 能写文件（write_file）—— 本教程的 demo/result/report.md 就是它自己写出来的
  • 能跨会话记住你的偏好（memory → MEMORY.md / USER.md）
  • 能把重复流程固化成技能（Skills），下次一句话复用

一句话：网页版是「顾问」，Hermes 是「实习生」—— 你要为它的操作负责， 所以审批和隔离机制才这么重要。

不必须。Hermes 原生支持 Windows 10/11，本教程整篇都是原生 Windows 跑出来的，没有用 WSL。

唯一的差距是：网页控制台（dashboard）里那个内嵌终端面板需要 POSIX PTY， 原生 Windows 上用不了，其余功能都正常。

如果想让终端工具的行为更像 Linux（比如脚本里用了 fork、 文件监听等 POSIX 语义），那就上 WSL2。两者数据目录是分开的： 原生在 %LOCALAPPDATA%\hermes，WSL 在 ~/.hermes， 可以共存。

✎学习心得与这份教程的边界

一份诚实的自我评估：我学会了什么、卡在哪、以及这份教程没有覆盖什么。

9.1 三个板块的自我评估

✓ 确实学会并验证了

  • 安装与依赖管理 —— 不只是跑一键脚本，而是搞清了它背后装了什么 （uv / Python 3.11 / Node / PortableGit / venv），以及每一步为什么需要。
  • 配置分层 —— 真正理解了 config.yaml 与 .env 为什么要分开，以及 hermes config set 的自动分流规则。
  • Tool Calling 机制 —— 能说清模型负责决策、Hermes 负责执行、 结果回传后再推理这个循环。
  • 排错方法论 —— 从 hermes doctor 开始、 先让基础聊天跑通再加功能。

◆ 过程中真正想明白的事

  • 报错信息是第一手资料。SEC_E_NO_CREDENTIALS 让我意识到 「能 ping 通端口」和「能建 TLS 连接」是两件事，不同工具用的 TLS 栈不同。
  • 版本约束要早查。<3.14,>=3.11 这个条件如果一开始就查， 能省掉一轮失败安装。
  • 缺 DLL 是可以精确诊断的。读 PE 导入表比盲目试错快得多。
  • 配置 schema 会演进。升级后跑 config migrate 应该成为习惯。

⚠ 这份教程的边界（还没做的）

  • 没有接消息平台（Telegram / Discord / Slack）， 所以 gateway 的配置与安全策略没验证。
  • 没有深入 Skills 自增长与 Curator，只到「知道它存在、知道怎么浏览」。
  • 没有验证 MCP 服务器接入，属于下一阶段内容。
  • 没用过 Docker / SSH 终端后端，隔离方案只停留在「知道命令」层面。
  • 没有多 Profile 与团队协作场景（Kanban、profile 分发）。
  • 模拟终端是回放，不是真实执行 —— 想看真机行为必须自己装。

9.2 给同样要入门的同学三条建议

  • 先求通，再求好别一上来就配 gateway、cron、语音。 官方文档自己都说：基础聊天没通，就不要加功能。本教程把这条放在了显眼位置，因为它真的省时间。
  • 把报错原文留下来我保留了 8 个坑的原始报错文本，这正是这份记录比「成功截图」 更有价值的地方 —— 别人搜报错时能搜到这里。
  • 每个结论都留一条证据说「装好了」不如给出 hermes --version 输出； 说「工具调用成功」不如给出日志行和产出文件路径。这也是这份作业的验收方式。

    • 9.3 怎么复现这一切

    本页所有内容都可在另一台机器上复现。最短路径：

    # 1) 官方一键安装（Linux / macOS / WSL2 / Windows）
iex (irm https://hermes-agent.nousresearch.com/install.ps1)   # Windows
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash   # Linux/macOS

# 2) 配置模型（换成你自己的 Provider 与密钥）
hermes config set DEEPSEEK_API_KEY sk-your-key
hermes config set model.provider deepseek
hermes config set model.default  deepseek-v4-pro
hermes config migrate

# 3) 体检 + 第一次对话
hermes doctor
hermes -z "你好，介绍一下你自己"

# 4) 复现 Step 6 的工具调用
mkdir demo/data demo/result
# 把 scores.csv 放进去，然后：
hermes chat -q "读取 data/scores.csv，统计每科平均分与总分，写出 result/report.md"

    完整命令序列、目录说明和 8 个踩坑的详细解法见项目根目录的 README.md。

    已复制 ✓