1. Hermes Agent 全栈安装前必须搞懂的目录分离设计Hermes Agent 是一个可自建的 Agent 服务框架能让你在本地跑起一套带 Web 聊天界面、后端网关和文档站点的完整链路。它适合想自己掌控模型调用通道、又不想从零写调度层的开发者。我试过把它装在三台不同配置的机器上踩过的坑基本都集中在“配置到底存哪”这件事上所以先把这个讲透后面安装会顺很多。Hermes Agent 最核心的设计是程序与数据完全分离。很多人第一次装完改了半天仓库里的配置文件结果重启后配置全没了就是因为没分清这两个目录。Git 克隆下来的仓库目录比如D:\hermes-agent或者~/hermes-agent它是源码工程目录。里面装的是后端 Python 代码、前端 Vue 工程web 文件夹、文档站点website 文件夹、插件和脚本。这个目录的角色是开发环境载体你升级版本、改源码、跑测试都在这里。它不存储你的个人配置所以删掉重新 clone 也不会丢东西。另一个是本地.hermes配置目录路径在 Windows 上是C:\Users\你的用户名\.hermesLinux/Mac 上是~/.hermes。这是全局持久化目录是真正的数据核心。里面有几个关键文件.env存 API 密钥state.db存会话状态和聊天记录还有日志和模型缓存。你运行任何hermes命令时它优先读取的都是这个目录而不是仓库里的配置。理解这一点之后后面所有配置动作你都会知道该改哪个文件。简单说仓库管代码.hermes管数据。备份.hermes文件夹就等于备份了你所有的设置和聊天记录换机器时把它拷过去配置直接迁移。环境要求方面官方推荐 Python 3.11、uv 包管理器和 Git。uv 是官方指定的高速包管理器比普通 pip 快很多而且能精确锁定 Python 版本。如果你机器上已经有 Python 3.10 或 3.12建议还是按官方要求装 3.11因为部分依赖对版本比较敏感用错版本可能在安装阶段就报编译错误。还有一个容易被忽略的点.hermes目录是全局的意味着你在任何路径下执行hermes命令读到的都是同一份配置。这既是优点也是坑——如果你同时想跑两套不同 Key 的环境就得靠环境变量或者切换.hermes目录来隔离不能指望在仓库里改配置生效。把这两个目录的角色记牢接下来进入官方标准安装流程你会发现每一步都清晰很多。2. TaoToken 前置准备统一 Key 与 API 通道配置在正式跑 Hermes Agent 之前先把模型调用通道准备好这样安装完就能直接验证连通性不用中途停下来折腾 Key。TaoToken 在这里的角色是提供一个统一的 API 通道你拿到一个 Key 之后就能通过它调用多种模型省去在多个平台分别申请、分别配置的麻烦。你需要先拿到两样东西API Key和Base URL。Key 在控制台的 API Keys 页面创建Base URL 统一用https://taotoken.net/api。注意这个地址后面不要加 UTM 参数直接作为接口根地址使用。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys进去之后点创建复制生成的 Key形如sk-开头的一串字符。这个 Key 只显示一次建议先粘到临时文本里等会儿要写进.hermes/.env。如果你还不确定该用哪个模型可以先在模型对话页面测一下确认通道通不通、模型响应正不正常模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chat这一步的意义在于先验证通道再接入 Agent。很多人反过来做装完 Hermes 发现调不通分不清是安装问题还是 Key 问题排查成本翻倍。先在对话页面发一条消息能正常返回说明 Key 和 Base URL 都没问题后面接入就只是填配置的事。关于模型 IDTaoToken 的接口遵循 OpenAI 兼容格式所以你在配置里填的模型名要跟平台支持的名称一致。常见的比如claude-sonnet-4-5、gpt-4o这类具体以文档里的模型列表为准。填错模型名会直接报 404 或 model not found这个后面排障章节会细说。接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc文档里有完整的接口说明和模型清单配置前扫一眼能省不少试错时间。如果你打算长期跑编码类 Agent 任务可以关注 Coding Plan它更适合高频调用场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan前置准备就这些一个 Key、一个 Base URL、一个确认可用的模型 ID。三样齐了下面开始装。3. 官方命令全栈安装与可复制配置片段这一节是全文技术含量最高的部分我会把官方命令逐行拆开配上每一步会遇到什么现象以及最终要写进配置文件的可复制片段。你照着做基本能一次跑通。先确认环境。Python 3.11 是硬要求用python --version检查。如果没有去官网装一个 3.11.x。Git 一般都有git --version能出版本号即可。第一步克隆官方仓库git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent克隆完会生成hermes-agent文件夹进入后就是项目根目录。这一步会遇到的是网络问题如果 clone 卡住多半是网络波动重试即可。第二步安装 uv 包管理器。官方指定用 uv不要用普通 pip 装依赖否则后面可能因为依赖解析不一致报错curl -LsSf https://astral.sh/uv/install.sh | shWindows 用户如果用的是 PowerShell可以用对应的安装脚本或者直接下载 uv 的可执行文件放进 PATH。装完执行uv --version确认。第三步创建 Python 3.11 虚拟环境uv venv venv --python 3.11这一步会生成venv文件夹。如果提示找不到 Python 3.11说明系统里没装uv 不会自动帮你下需要你先装好。第四步激活虚拟环境。Linux/Macsource venv/bin/activateWindowsvenv\Scripts\activate激活成功的标志是命令行前缀出现(venv)。后面所有 hermes 命令都必须在激活状态下执行这是新手最容易忘的一步忘了就会报 command not found。第五步安装完整版依赖uv pip install -e .[all,dev]-e是可编辑安装[all,dev]表示装全部功能和开发依赖。这一步耗时最长最后出现Successfully installed就成功了。如果中途报编译错误多半是 Python 版本不对或者缺少系统级编译工具。第六步跑测试验证安装python -m pytest tests/ -q出现X passed说明安装完全成功。有 failed 的话先看是不是环境问题一般干净环境下不会失败。安装完成后进入初始化配置。这一步是解决 401 错误的关键hermes setup它会交互式引导你填 API Key。但如果你想直接写配置文件可以手动编辑~/.hermes/.env。下面是我实测可用的配置片段把 Key 和 Base URL 换成你自己的# ~/.hermes/.env OPENAI_API_KEYsk-你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODELclaude-sonnet-4-5 GATEWAY_ALLOW_ALL_USERStrue这里三个字段对应三件套Base URL Key Model ID。Base URL 固定用https://taotoken.net/apiKey 是你刚创建的Model ID 填平台支持的模型名。GATEWAY_ALLOW_ALL_USERStrue是本地开发时放开网关用户限制避免前端连不上后端。如果你用的是 JSON 格式的配置部分版本支持settings.json结构类似{ api: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-5 }, gateway: { allow_all_users: true } }路径同样放在~/.hermes/下。注意不要改仓库里的配置模板那些是给开发用的默认值改了不生效。配置写完先别急着启动 Web 端用一条命令验证通道hermes chat 你好测试一下连通性能正常返回内容说明 Key、Base URL、模型 ID 三件套都对。返回 401 就是 Key 问题返回 model not found 就是模型名问题返回连接超时就是 Base URL 或网络问题。这一步过了再启动 Web 服务。4. 三大 Web 服务启动与连通性验证Hermes Agent 的 Web 端由三个部分组成理解它们的关系能帮你快速定位“前端一直转圈”这类问题。这三个服务有严格的启动顺序Dashboard 必须第一个启动因为它是后端网关前端要靠它转发请求。第一个是 Dashboard核心后端网关端口固定 9119。它是整个系统的大脑负责 API 网关、会话管理和调试界面。启动命令hermes dashboard成功现象是终端显示Dashboard running on http://localhost:9119。这个端口不要被其他程序占用否则启动会失败。如果 9119 被占先找到占用进程杀掉再重启。第二个是 web 文件夹专业聊天 UI也就是你日常使用的主界面。它依赖 Dashboard所以必须等 Dashboard 起来之后再启动cd web npm install npm run devnpm install第一次会装前端依赖耗时看网络。npm run dev启动开发服务器默认访问地址是http://localhost:5173。打开浏览器能看到聊天界面说明前后端都通了。第三个是 website 文件夹项目文档站点。它只用于查看和编辑文档不影响 Agent 功能不需要启动。你可以把它理解成一个静态文档站跟运行链路无关。验证连通性的完整动作是这样的先确认 Dashboard 在 9119 跑着再打开 5173 的聊天界面发一条消息。如果消息能正常返回说明整条链路——前端 → Dashboard 网关 → TaoToken API → 模型——全部打通。如果前端一直加载八成是 Dashboard 没启动或者启动失败。这时候回到终端看 Dashboard 的日志常见的是端口占用或者.env配置没读到。如果消息发出去报错看浏览器控制台和 Dashboard 日志401 是 Key 问题超时是网络或 Base URL 问题。Windows 用户可以用一个极简的一键启动脚本新建start.batecho off cd /d D:\study\hermes-agent call venv\Scripts\activate set GATEWAY_ALLOW_ALL_USERStrue hermes dashboard pause双击就能启动后端。注意cd /d后面的路径换成你自己的仓库路径。这个脚本只启动 Dashboard前端还是要单独npm run dev因为前端需要热更新放脚本里反而不方便调试。启动顺序总结成一句话先 Dashboard9119再 web5173website 不用管。所有 hermes 命令都要在(venv)激活状态下执行这是反复强调的重点。5. 高频报错排查401、端口占用与前端加载失败这一节把实战中最常遇到的几个报错列出来对照现象找原因基本能覆盖 90% 的安装问题。报错一401 User not found这是最典型的配置问题说明请求发出去了但 Key 没被识别。原因通常是.env没写对或者hermes setup没跑完。解决方法是重新执行hermes setup或者手动检查~/.hermes/.env里的OPENAI_API_KEY是不是完整的sk-开头字符串。注意不要有多余空格或换行。如果 Key 确认没问题还是 401检查 Base URL 是不是写成了带路径的形式正确写法就是https://taotoken.net/api不要在后面加/v1之类。报错二9119 端口占用Dashboard 启动时报Address already in use。先用netstat -ano | findstr 9119Windows或lsof -i:9119Linux/Mac找到占用进程杀掉后重启。如果 9119 被系统服务长期占用可以考虑改 Dashboard 端口但前端默认连的是 9119改端口要同步改前端配置比较麻烦建议还是腾出 9119。报错三前端一直加载 / 转圈打开 5173 后界面出不来或者消息发不出去。第一反应是检查 Dashboard 有没有在跑。前端只是 UI所有请求都要经过 Dashboard 网关。Dashboard 没起来前端就是个空壳。确认 Dashboard 日志里有running on http://localhost:9119之后再刷新前端。报错四local proxy failed这个报错通常出现在网关转发阶段说明 Dashboard 尝试把请求转发到上游 API 时失败了。原因可能是 Base URL 写错、网络不通或者模型 ID 不存在。先确认https://taotoken.net/api能通再确认模型名在平台支持列表里。如果用的是本地代理类工具检查代理配置有没有冲突。报错五reading choices 相关错误这类报错说明请求发出去了但返回结构不符合预期通常是模型名不对或者接口返回了错误信息。检查OPENAI_MODEL字段确保填的是平台支持的模型 ID。有些模型名带版本号比如claude-sonnet-4-5少写一段就会报这个。报错六依赖安装失败uv pip install报编译错误或依赖冲突。首先确认 Python 版本是 3.11其次确认用的是 uv 而不是普通 pip。如果之前用 pip 装过依赖建议删掉venv重新创建避免残留冲突。报错七OAuth 相关错误如果配置里涉及 OAuth 流程报错多半是回调地址或凭证不匹配。本地开发时建议先用 API Key 方式绕开 OAuth等链路通了再考虑接 OAuth。排查的通用思路是先看终端日志再看浏览器控制台最后对照配置三件套。Base URL、Key、Model ID 这三个只要有一个不对就会在某个环节报错。把这三个确认死大部分问题都能定位。6. 长期编码与 Agent 场景的接入建议装完跑通只是第一步真正用起来还会遇到一些工程化问题。这一节聊几个实际使用中的建议帮你把 Hermes Agent 用得更顺。首先是配置备份。前面反复强调.hermes目录是数据核心所以定期备份这个文件夹就等于备份了所有设置和聊天记录。换机器时把它拷过去Key 和会话直接迁移不用重新配。仓库目录反而不用备份随时可以重新 clone。其次是模型选择。TaoToken 的统一通道支持多种模型不同任务适合不同模型。日常对话用响应快的复杂编码任务用推理能力强的。你可以在.env里改OPENAI_MODEL来切换改完重启 Dashboard 生效。如果频繁切换可以准备几份.env备份用的时候替换。第三是 Coding Plan 的适用场景。如果你打算把 Hermes Agent 当作长期编码助手高频调用模型Coding Plan 在成本和配额上更适合Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan它面向的就是持续编码和 Agent 任务场景比按次调用更划算。第四是开发调试的 Checklist。按顺序来先启动 Dashboard再启动前端所有 hermes 命令在(venv)下执行配置只改~/.hermes/.env不动仓库内配置9119 端口留给 Dashboard备份.hermes文件夹。这五条记住日常使用基本不会出问题。最后说一个实际经验Hermes Agent 的 Web 端架构是前后端分离的前端只是展示层真正的逻辑都在 Dashboard 网关里。所以调试时优先看 Dashboard 日志前端报错往往只是表象。理解了这一点排查效率会高很多。如果你还没创建 Key从这里开始API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys配置细节查文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc整套流程走下来从 clone 到前端能聊天顺利的话半小时内能搞定。卡住的地方基本都在配置三件套和启动顺序上对照第 5 节的报错表逐个排除就行。