企业官网建设流程全解析

1. Hermes Agent 全栈安装前必须搞懂的目录分离设计

Hermes Agent 是一个可自建的 Agent 服务框架，能让你在本地跑起一套带 Web 聊天界面、后端网关和文档站点的完整链路。它适合想自己掌控模型调用通道、又不想从零写调度层的开发者。我试过把它装在三台不同配置的机器上，踩过的坑基本都集中在“配置到底存哪”这件事上，所以先把这个讲透，后面安装会顺很多。

Hermes Agent 最核心的设计是程序与数据完全分离。很多人第一次装完，改了半天仓库里的配置文件，结果重启后配置全没了，就是因为没分清这两个目录。

Git 克隆下来的仓库目录，比如D:\hermes-agent或者~/hermes-agent，它是源码工程目录。里面装的是后端 Python 代码、前端 Vue 工程（web 文件夹）、文档站点（website 文件夹）、插件和脚本。这个目录的角色是开发环境载体，你升级版本、改源码、跑测试都在这里。它不存储你的个人配置，所以删掉重新 clone 也不会丢东西。

另一个是本地.hermes配置目录，路径在 Windows 上是C:\Users\你的用户名\.hermes，Linux/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 Keys：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys

进去之后点创建，复制生成的 Key，形如sk-开头的一串字符。这个 Key 只显示一次，建议先粘到临时文本里，等会儿要写进.hermes/.env。

如果你还不确定该用哪个模型，可以先在模型对话页面测一下，确认通道通不通、模型响应正不正常：

模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model-chat

这一步的意义在于：先验证通道，再接入 Agent。很多人反过来做，装完 Hermes 发现调不通，分不清是安装问题还是 Key 问题，排查成本翻倍。先在对话页面发一条消息，能正常返回，说明 Key 和 Base URL 都没问题，后面接入就只是填配置的事。

关于模型 ID，TaoToken 的接口遵循 OpenAI 兼容格式，所以你在配置里填的模型名要跟平台支持的名称一致。常见的比如claude-sonnet-4-5、gpt-4o这类，具体以文档里的模型列表为准。填错模型名会直接报 404 或 model not found，这个后面排障章节会细说。

接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

文档里有完整的接口说明和模型清单，配置前扫一眼能省不少试错时间。如果你打算长期跑编码类 Agent 任务，可以关注 Coding Plan，它更适合高频调用场景：

Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-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 | sh

Windows 用户如果用的是 PowerShell，可以用对应的安装脚本，或者直接下载 uv 的可执行文件放进 PATH。装完执行uv --version确认。

第三步，创建 Python 3.11 虚拟环境：

uv venv venv --python 3.11

这一步会生成venv文件夹。如果提示找不到 Python 3.11，说明系统里没装，uv 不会自动帮你下，需要你先装好。

第四步，激活虚拟环境。Linux/Mac：

source venv/bin/activate

Windows：

venv\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_KEY=sk-你的TaoToken密钥 OPENAI_BASE_URL=https://taotoken.net/api OPENAI_MODEL=claude-sonnet-4-5 GATEWAY_ALLOW_ALL_USERS=true

这里三个字段对应三件套：Base URL + Key + Model ID。Base URL 固定用https://taotoken.net/api，Key 是你刚创建的，Model ID 填平台支持的模型名。GATEWAY_ALLOW_ALL_USERS=true是本地开发时放开网关用户限制，避免前端连不上后端。

如果你用的是 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 dev

npm 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.bat：

@echo off cd /d D:\study\hermes-agent call venv\Scripts\activate set GATEWAY_ALLOW_ALL_USERS=true hermes dashboard pause

双击就能启动后端。注意cd /d后面的路径换成你自己的仓库路径。这个脚本只启动 Dashboard，前端还是要单独npm run dev，因为前端需要热更新，放脚本里反而不方便调试。

启动顺序总结成一句话：先 Dashboard（9119），再 web（5173），website 不用管。所有 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 9119（Windows）或lsof -i:9119（Linux/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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan

它面向的就是持续编码和 Agent 任务场景，比按次调用更划算。

第四是开发调试的 Checklist。按顺序来：先启动 Dashboard，再启动前端；所有 hermes 命令在(venv)下执行；配置只改~/.hermes/.env，不动仓库内配置；9119 端口留给 Dashboard；备份.hermes文件夹。这五条记住，日常使用基本不会出问题。

最后说一个实际经验：Hermes Agent 的 Web 端架构是前后端分离的，前端只是展示层，真正的逻辑都在 Dashboard 网关里。所以调试时优先看 Dashboard 日志，前端报错往往只是表象。理解了这一点，排查效率会高很多。

如果你还没创建 Key，从这里开始：

API Keys：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys

配置细节查文档：

接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

整套流程走下来，从 clone 到前端能聊天，顺利的话半小时内能搞定。卡住的地方基本都在配置三件套和启动顺序上，对照第 5 节的报错表，逐个排除就行。