Hermes 工程化实战专栏：安装部署实战——从装好到跑通第一个任务

装好一个 agent，不是装好一个软件。是给它安家：它住哪儿、用什么脑子、开口第一句话说什么。这三件事不定下来，它只是个没通电的程序。

系列第 1 篇《Hermes 是什么》讲了 Hermes 是会自我进化的 agent：执行任务、评估结果、把经验沉淀成技能，下次更聪明。那篇停在「它值得装」，这篇走到「把它装好」。这是 A 上手篇的第一篇，本篇三件事：怎么装、装在哪、怎么开口说话。

动手前先亮两样东西。

第一样，这篇的成色。全篇是我在 Windows 本机一步步跑出来的逐字实录，命令和输出来自取证日志，你照着敲就能复刻；没跑过的我明说没跑过，不替编输出。

第二样，这趟会踩的三处 Windows 差异。官方文档假定你活在类 Unix 世界，这三条它没写：

• Hermes home 不在 ~/.hermes，在 %LOCALAPPDATA%\hermes；
• uv 不指定 Python 版本，会给你建一个没有 pip 的 Python 3.14；
• PowerShell 给 curl 传 JSON，双引号会被吞掉。

版本口径先立住：截至 2026-08-28，本机实测 v0.19.0（2026-07-20 构建）。网络资料滞后，搜到的最新还停在 v0.14，照它写命令会踩空。后面所有命令都在这版上跑。

全程就三步，先给你全景图，后面每一节都是给图里的一格装细节。

环境准备：uv 显式指定 Python 3.12

先交代基线，方便你对号入座（2026-08-26 记录）：

Hermes 是 Python 包，装它我先建一个干净的虚拟环境。Windows 原生走通就一条路：uv 建环境 + pip 装包，不用碰 WSL。uv 的好处是快，而且自己能下载 Python，省得去官网折腾解释器。

先建虚拟环境：

cd /d/CF-AICoding/hermes-lab
uv venv .venv --python 3.12

输出：

Creating virtual environment at: .venv
Activate with: source .venv/Scripts/activate

注意 --python 3.12 这个参数，我第一遍就栽在这。uv 默认不指定版本时，会去装一个最新的 Python------我那次拿到的是 3.14.0，里面没有 pip 模块，装包直接抓瞎。弃掉重建，显式钉死 3.12 才正常。这就是开头预告的第二处差异。这不是 uv 的 bug，是「默认追新」撞上 Hermes 的兼容口径，uv 不会替你猜版本。

两个细节先记住，后面都用得上：虚拟环境在 .venv，Windows 下的可执行文件在 .venv/Scripts/，不是 Unix 的 .venv/bin/；装 Hermes 钉 Python 3.12，别拿系统 Python 裸装。

安装与验证：v0.19.0 与三个命令入口

装包：

uv pip install --python .venv/Scripts/python.exe hermes-agent

输出（节选，安装成功）：

 + six==1.17.0
 + starlette==1.6.0
 + tenacity==9.1.4
 + uvicorn==0.52.4
 + websockets==15.0.1
...

依赖栈一眼可见：uvicorn + starlette 是服务端，websockets 是实时通道，后面还有 OpenAI SDK 2.24.0 管模型接入。装完验证版本：

.venv/Scripts/hermes.exe --version

输出（逐字）：

Hermes Agent v0.19.0 (2026.7.20)
Install directory: D:\CF-AICoding\hermes-lab\.venv\Lib\site-packages
Install method: pip
Python: 3.12.7
OpenAI SDK: 2.24.0

v0.19.0，构建日期 2026-07-20。装完后你会发现包里冒出三个命令入口：

ls .venv/Scripts/ | grep -i hermes
# hermes-acp.exe
# hermes-agent.exe
# hermes.exe

hermes 是主命令，平时都用它；hermes-agent 是同名服务；hermes-acp 走 ACP 协议（Agent Client Protocol），给外部 harness 挂 Hermes 当后端用。一条 pip 装出三个入口，是「一个包、多张脸」：核心逻辑一份，对外接口分三套。包本体确认一下：

uv pip list --python .venv/Scripts/python.exe | grep -i hermes
# hermes-agent           0.19.0

到这里，安装段收工。官方还给了两条更省事的路（都在官方文档里）：Linux/macOS/WSL2 用一键脚本 curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash，Windows 用 PowerShell 的 iex (irm https://hermes-agent.nousresearch.com/install.ps1)。我没跑这两条，原因很简单：一键脚本背后做的事不可见，而这套系列后面要拆它、改它，我选透明可控的 uv + pip 路。两条路殊途同归，你按口味挑。

一个提醒：pip 装的是纯 Python 部分，node/browser/ripgrep/ffmpeg 这些非 Python 依赖不在这里面，官方用 hermes postinstall 引导补齐。这条我本机没实跑，标「待核实」------本篇只跑了对话链路，没碰浏览器和终端执行后端。

Hermes home

它把家安在了 %LOCALAPPDATA%\hermes

软件装完，Agent 才算刚落地。Hermes 有个核心概念叫 Hermes home，所有状态都堆在这里：配置、身份、记忆、会话日志、技能、定时任务。它是整个 agent 的「家目录」。

官方文档写默认 home 是 ~/.hermes。这是类 Unix 的写法。Windows 上不是------Hermes 源码里 get_hermes_home() 会先判系统：Windows 解析到 %LOCALAPPDATA%\hermes，类 Unix 才落到 ~/.hermes。这就是开头预告的第一处差异。

%LOCALAPPDATA% 展开后就是 C:\Users\你的用户名\AppData\Local\hermes。第一次跑 Hermes 时，这个目录自动长齐了一套结构，不用你手动 mkdir：

• config.yaml------运行配置（模型、provider、工具集）；
• SOUL.md------身份文件，agent 的「人格」；
• state.db------状态数据库（SQLite）；
• sessions/------会话记录；
• memories/------持久记忆；
• skills/------技能；
• cron/------定时任务；
• sandboxes/------沙箱目录。

一句话：它首跑自己把家搭好。这就是「给它安家」的实义------你只要知道家在哪，然后往里面放东西。

Provider 配置：直连 DeepSeek

家安好了，下一步给它装脑子------接一个能用的模型。我接的是 DeepSeek 官方 API 直连。

先说背景。我本来想走阿里百炼 token plan 的 Anthropic 协议端点，key 都配好了，结果鉴权通过（不是 401/403），模型调用却全部 500 Invoke backend failed，换了几种 header、几个路径都一样，暂时没法用。于是掉头直连 DeepSeek 官方 API，这条跑通了。

先卖个关子：接之前，我差点照网上教程直接填 deepseek-chat。幸好先拿 /v1/models 实查了一眼------真名完全是另一套。

查模型列表我用了一个 PowerShell 脚本：

powershell -NoProfile -ExecutionPolicy Bypass -File D:\CF-AICoding\hermes-lab\test-deepseek.ps1

输出（节选，key 不打码）：

KEY_PRESENT len=35 (value not printed)
== 1) GET /v1/models ==
{"object":"list","data":[{"id":"deepseek-v4-flash","object":"model","owned_by":"deepseek"},{"id":"deepseek-v4-pro","object":"model","owned_by":"deepseek"},{"id":"deepseek-v4-flash-vision-exp","object":"model","owned_by":"deepseek"}]}|HTTP:200

现在兑现关子：DeepSeek 当前的真名是 deepseek-v4-flash / deepseek-v4-pro / deepseek-v4-flash-vision-exp，不是文档时代留下的 deepseek-chat。旧名是兼容别名，官方计划 2026-07-24 起弃用。模型名以实查为准，别照抄旧教程。

再测一次对话调用，确认协议层通不通：

== 1) POST /v1/chat/completions (deepseek-v4-flash) ==
{"id":"...","object":"chat.completion","model":"deepseek-v4-flash","choices":[{"index":0,"message":{"role":"assistant","content":"","reasoning_content":"We need answer to user...","finish_reason":"length"}}],...}|HTTP:200

这里有个反直觉点：content 是空的，但 HTTP 200。因为 deepseek-v4-flash 是推理模型，响应带 reasoning_content 字段；我探测时把 max_tokens 压到 16，token 全耗在思考上，正文还没轮到就 finish_reason: "length" 截断了。联通性已经证实------它「想」了，只是没「说」完。这个字段后面是整篇的伏笔。

探测过程还踩了第三处 Windows 坑：PowerShell 把 $body 直接传给 curl.exe 时，会吞掉 JSON 里的双引号，服务端解析直接 400。解决方式是不走内联 body，改用 -d @临时文件 把 JSON 从文件读进去。Windows 的 PowerShell + curl.exe 组合，双引号是一堵你迟早要撞的墙。

现在把它写进 Hermes。Hermes home 下的 config.yaml，providers 字典里加一个 deepseek 条目：

model: deepseek-v4-flash
providers:
  deepseek:
    base_url: https://api.deepseek.com/v1
    key_env: DS-KEY
    api_mode: chat_completions
    model: deepseek-v4-flash
    models:
      deepseek-v4-flash: {}
      deepseek-v4-pro: {}
      deepseek-v4-flash-vision-exp: {}

四个字段各自的意思：

• base_url：API 端点，https://api.deepseek.com/v1；
• key_env：key 从环境变量 DS-KEY 读，不写进 config，不落盘；
• api_mode: chat_completions：走 OpenAI 兼容的 /chat/completions 协议（对应 transport openai_chat）；
• models：这个 provider 下可用的模型清单。

key_env 是重点：密钥只存在于你的机器级环境变量，config 里只留一个指针。丢了 config 不丢 key，提交到仓库也不会泄密。

一点版本说明：网上大部分教程写的是 custom_providers: 列表 + - name: 的旧格式，本机 v0.19.0 用 providers: 字典实测可用。两种格式在不同版本间并存过，我以实测为准。Hermes 的 provider 解析（_normalize_custom_provider_entry）还兼容 baseUrl / apiMode / keyEnv 这些 camelCase 别名，写小写蛇形是惯例。

配置写完了。跑第一个任务之前，先预告一件事：等它开口，你会先看到一段英文思考，然后才轮到你问的答案。为什么，下一节跑给你看。

第一个任务：它第一次开口

验证整个链路，用一条一次性命令。hermes chat 是非交互对话，-q 给问题，--provider deepseek 指定刚才配的 provider，-m 指定模型，-Q 安静模式------不带交互提示符，适合程序化调用。

.venv/Scripts/hermes.exe chat -q "用一句话介绍你自己，20字以内" --provider deepseek -m deepseek-v4-flash -Q

输出（逐字）：

┌─ Reasoning ──────────────────────┐
The user asks in Chinese: "Introduce yourself in one sentence, within 20 characters." I should respond in Chinese, keeping it under 20 characters...
session_id: 20260828_190847_8801d7
我是Hermes，你的AI助手。

现在兑现上一节的预告。这个输出三块，各说一件事：

• 第一块 Reasoning 框：模型先想再答。这段英文思考就是 reasoning_content 的可视化，上一节埋的伏笔在这兑现------它是推理模型，开口前先过一遍脑子；
• 第二行 session_id: 20260828_190847_8801d7：这次会话的编号。Hermes 每次对话都记一条会话，这个 id 对应 sessions/ 里的一条记录；
• 第三行 我是Hermes，你的AI助手。：模型的正式回答。约束「20字以内」它遵守了。

这一条命令，把前面所有环节串起来了：uv 建的环境 → 装好的 v0.19.0 → %LOCALAPPDATA%\hermes 下的 config → DS-KEY 环境变量 → DeepSeek /v1/chat/completions → 回答回到终端。链路通了，第一次开口完成。

体检与正规路线：最小可跑，不等于完整可体检

第一个任务跑通了。但先别高兴太早------跑通对话，不等于配置健康。我接下来做了个体检，命令是 hermes doctor，官方体检命令，逐项检查安装与配置。

先声明：体检的逐字输出我没存进取证日志，下面是本机实测看到的结论清单，不是伪造的终端回显。手写这份最小 config 跑出来的结果，缺口一块块列在这：

• .env 缺失 ：Hermes 完整形态期望密钥写在 home 下的 .env，我直接用了环境变量，它没看到；
• config 版本过旧：手写的是旧格式（版本 v0），当前 Hermes 期望的 config 版本已经迭代到 v33，格式演进没跟上；
• model/provider 校验失败 ：字段校验对不上，报错是 Python 风格的一句 'str' object has no attribute 'get'------手写的精简结构让校验器在预期是字典的地方收到了字符串。

记住：最小可跑，不等于完整可体检。

手写最小 config 的价值在于读懂结构------你亲手填过一遍 base_url、key_env、models，就知道 provider 是怎么接进去的。但它只覆盖了「能跑」的最小切面，hermes doctor 一把体检尺子量下去，缺的角全露出来。这是本篇的诚实边界：上面所有「跑通」都成立，但「跑通」和「体检合格」是两回事。

正规路线是什么？是 hermes setup 向导。它交互式地带着你把每一步走完：选 provider、填 key、写 .env、生成最新版本的 config。

两条路放一起看：

我的建议：第一次装，两条路都走一遍。先手写一遍最小 config 跑通对话，理解结构；再跑向导看它生成什么、对比自己缺了哪些。装好不是终点，看懂才是。

SOUL.md：改一行，它就换个人

家安好了、脑子接上了、第一次开口了，最后看一个文件：SOUL.md。

它是 Hermes 的身份文件，和 config.yaml 同目录，住在 Hermes home。config.yaml 管它怎么跑（模型、工具、后端），SOUL.md 管它是谁（语气、口癖、行为边界）------一个管运行，一个管人格。

首次跑 Hermes 时，它会自动种下一份默认 SOUL.md（本机这份 513 字节，正文就一行）。上一节它答「我是Hermes，你的AI助手。」，底气就来自这份默认人格。

两个关键机制：

• 每次消息都重新加载 ：Hermes 每轮对话都会重新读 SOUL.md，你改完存盘，下一句话它就换了个人，不用重启、不用清缓存；
• 从不覆盖已有文件：首跑自动种种子，但只要你改过，它绝不动你的版本。

所以「换人格 = 编辑一个文件」。想让它是周报助手，把 SOUL.md 改成周报助手的口吻；想让它是日报编辑，改成编辑的口吻。这跟 prompt 里的临时指令是两回事------SOUL.md 是常驻的、每次都注入系统提示词第一格的身份槽，优先级比普通指令高。

动手改一句，再跑一次 hermes chat -q "你是谁"，你会立刻看到它换了一张脸。这就是「会自我进化」的第一步地基：先有个稳定的「我」，后面才能谈「我学到了什么」。

结论：装好只是拿到钥匙

回到开头那句话：装好一个 agent，是给它安家。现在家在哪、脑子在哪、怎么开口，三件事都落地了。你手里的，是一把能开门的钥匙------但门还没打开。

这把钥匙能干什么，下一篇就会为你呈现。下一篇 会用这个装好的 Hermes 跑第一个真实任务：载体项目「各家 AI 动态日报」------每天 6:00 自动收集国内外 AI 动态，汇总去重，生成一个网页。收集、汇总、出网页，每一步都要调工具、跨天记忆去重、把策略沉淀成技能，这才是 Hermes 真正值钱的地方，也是它「会自我进化」第一次被实战检验。

装 Hermes 这个动作本身，你卡在哪一步？是 home 路径找不到，还是 uv 建出个没 pip 的 Python，还是 provider 配了半天不通？欢迎评论区分享，让大家少踩坑。