【零基础部署】Docker 部署 Hermes Agent 保姆级教程：TaoToken 统一 Key 配置与容器验证

1. 为什么要在 Docker 里跑 Hermes Agent

Hermes Agent 是 Nous Research 推出的 AI 智能助手平台，支持对话、任务规划、工具调用等能力，你可以把它理解成一个能自己拆解任务、调用外部工具的智能体框架。它适合想快速体验 Agent 工作流、又不想把本机 Python 环境搞乱的人。而 Docker 部署最大的好处就是环境隔离：镜像里依赖都装好了，升级时拉个新镜像重启容器就行，玩坏了直接删容器重来，数据挂在宿主机目录里不会丢。

不过零基础用户真正卡住的地方，往往不是docker run那几行命令，而是容器启动之后——Agent 要调用大模型，Key 和 API 通道怎么配？容器里读的是哪个配置文件？配完了怎么确认它真的连通了？这篇就围绕 Docker 部署 Hermes Agent 的完整流程，重点把「统一 Key / API 通道」这件事讲透，给你可复制的 docker-compose 骨架、settings.json 配置片段，以及容器启动后验证连通性的具体命令和排查步骤。全程假设你只会敲命令，不需要懂 Python。

2. 前置准备：Docker 环境与 TaoToken 统一 Key

先确认 Docker 装好了，终端里执行：

docker --version # 输出类似：Docker version 24.x.x, build xxxxxx docker compose version # 输出类似：Docker Compose version v2.x.x

两条都有版本号输出就说明环境 OK。如果docker compose报错，说明你的 Compose 还是老的独立版本，把后面命令里的docker compose换成docker-compose即可。

接下来是 Key。Hermes Agent 本身不带模型，它需要连一个兼容 OpenAI 接口的 API 通道。我这边统一用 TaoToken 来管理 Key，好处是一个 Key 能对接多种模型，容器里只配一个 base_url 和 api_key 就行，不用为每个模型单独改配置。你需要先去控制台创建一个 API Key：

创建 Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite

创建完把 Key 复制下来，形如sk-xxxxxxxx，先存到本地一个临时文件里，别直接写进会提交到 Git 的配置。TaoToken 的 API 入口地址是：

https://taotoken.net/api

注意这个地址后面不带斜杠，也不带/v1，具体路径拼接规则在下一节的配置里说明。如果你对可用模型和接入方式还不熟，可以先在模型对话页面试一条请求，确认 Key 本身是通的：

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

3. 可复制配置：docker-compose 骨架与 settings.json

3.1 目录结构先规划好

零基础最容易乱的就是挂载目录。建议在宿主机建一个统一的工作目录，配置和数据都放里面：

mkdir -p ~/hermes/{data,workspace} cd ~/hermes

data用来持久化 Hermes 的配置和会话数据，workspace用来放你想让 Agent 访问的项目代码。这样容器删了重建，这两个目录还在。

3.2 docker-compose.yml 骨架

在~/hermes下新建docker-compose.yml，内容如下，可以直接复制：

services: hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped networks: - hermes-net ports: - "8642:8642" volumes: - ./data:/opt/data - ./workspace:/workspace environment: - HERMES_API_BASE=https://taotoken.net/api - HERMES_API_KEY=${HERMES_API_KEY} - HERMES_MODEL=gpt-4o-mini command: gateway run hermes-dashboard: image: nousresearch/hermes-agent:latest container_name: hermes-dashboard restart: unless-stopped networks: - hermes-net ports: - "127.0.0.1:9119:9119" volumes: - ./data:/opt/data environment: - GATEWAY_HEALTH_URL=http://hermes:8642 command: dashboard --host 0.0.0.0 --insecure networks: hermes-net: driver: bridge

几个关键点解释一下。HERMES_API_BASE填 TaoToken 的 API 入口，容器内所有模型请求都会走这个地址；HERMES_API_KEY用${HERMES_API_KEY}引用环境变量，不把明文写进 compose 文件；HERMES_MODEL先填一个便宜的小模型做连通性测试，跑通再换。Dashboard 的端口映射写成127.0.0.1:9119:9119，只允许本机访问，别暴露到公网。

3.3 用 .env 管理 Key

在同目录新建.env文件：

echo "HERMES_API_KEY=sk-你的真实Key" > .env chmod 600 .env

chmod 600保证只有当前用户能读。记得把.env加进.gitignore，避免误提交。

3.4 settings.json 配置片段

Hermes 的模型配置最终会落到data目录下的settings.json。如果你不想用环境变量，也可以直接写这个文件。初始化后它大概长这样，重点是providers这一段：

{ "providers": { "default": { "type": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "sk-你的真实Key", "model": "gpt-4o-mini" } }, "gateway": { "host": "0.0.0.0", "port": 8642 } }

type必须是openai-compatible，因为 TaoToken 走的是 OpenAI 兼容协议；base_url不要自己加/v1，客户端会自动拼；api_key和.env里的保持一致。两种方式选一种就行，同时配的话环境变量优先级更高，容易排查时混淆，建议只用.env。

4. 启动容器并验证 Agent 连通性

4.1 拉镜像并启动

cd ~/hermes docker compose pull docker compose up -d

镜像大概 1 到 2 GB，取决于网速，耐心等几分钟。启动后看状态：

docker compose ps

两个容器状态都是Up就对了。如果hermes反复重启，先别急，看日志：

docker compose logs -f hermes

4.2 验证 Gateway 是否活着

Gateway 是 Hermes 的核心服务，负责处理请求和管理会话。先确认端口通了：

curl -s http://localhost:8642/health # 期望输出类似：{"status":"ok"}

如果返回ok，说明 Gateway 进程正常。这一步不通，后面模型肯定也调不通，先解决进程问题。

4.3 验证模型通道是否连通

这是最关键的一步——确认容器里的 Agent 能通过 TaoToken 真正调到模型。进入容器执行一次对话测试：

docker exec -it hermes bash source /opt/hermes/.venv/bin/activate hermes chat --message "用一句话介绍你自己"

如果配置正确，你会看到模型返回的一段文字。如果报 401，说明 Key 不对；报 404，多半是base_url拼错了；报连接超时，检查容器能不能出网。

也可以不进容器，直接用 curl 从宿主机打 Gateway 的对话接口：

curl -s -X POST http://localhost:8642/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

返回里带choices字段就说明整条链路通了：请求 → Gateway → TaoToken → 模型 → 返回。

4.4 打开 Dashboard 看状态

浏览器访问http://localhost:9119，能看到面板就说明 Dashboard 也正常。面板里可以查看会话、模型调用记录，排查问题时比翻日志直观。

5. 本篇常见错误排查

容器启动即退出，日志报permission denied：多半是data目录权限问题。宿主机执行sudo chown -R 1000:1000 ~/hermes/data，再docker compose restart。Hermes 容器内默认用非 root 用户跑，挂载目录属主不对就写不进去。

curl http://localhost:8642/health连接被拒：先docker compose ps看容器是不是真在跑；再看端口有没有被占用，ss -tlnp | grep 8642，被占了就改 compose 里的宿主机端口，比如"8643:8642"。

对话返回 401 Unauthorized：Key 错了或没生效。检查.env里有没有多余空格和引号，改完必须docker compose up -d重建容器，光restart不会重新读.env。

返回 404 Not Found：base_url写错了。正确值是https://taotoken.net/api，不要加/v1，不要加结尾斜杠。如果你在 settings.json 里手写了/v1/chat/completions这种完整路径，删掉，只留 base。

容器内hermes命令找不到：忘了激活虚拟环境。先source /opt/hermes/.venv/bin/activate，再执行hermes相关命令。

Dashboard 打不开但 Gateway 正常：检查GATEWAY_HEALTH_URL是不是http://hermes:8642，两个容器必须在同一个hermes-net网络里，用容器名互访，不能用localhost。

改了 settings.json 不生效：Hermes 启动时读一次配置，改完要docker compose restart hermes。另外确认你改的是~/hermes/data/settings.json，不是容器里别的位置。

6. 后续升级与 Key 管理建议

升级很简单，拉新镜像重建就行，数据都在data目录里不会丢：

cd ~/hermes docker compose pull docker compose up -d

Key 这块，如果你后面要跑长期编码任务或者接 Agent 工作流，单次对话的按量方式可能不够划算，可以看看 Coding Plan，适合高频调用场景：

Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite

需要新建或轮换 Key 的时候，回到控制台的 API Keys 页面操作，换完记得同步更新.env并重建容器：

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

接入细节和参数说明以官方文档为准，遇到路径拼接、模型名这类问题先查文档再动手：

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

如果你用的是 Claude Code 这类编码工具，想让它也走同一个通道，可以参考这份接入说明：

Claude Code 接入：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite

最后提醒一句：.env和settings.json里的 Key 都是明文，别把~/hermes整个目录传到公开仓库。真要备份，只备份docker-compose.yml，Key 单独存密码管理器里。