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

1. 为什么要在 Docker 里跑 Hermes AgentHermes 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创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完把 Key 复制下来形如sk-xxxxxxxx先存到本地一个临时文件里别直接写进会提交到 Git 的配置。TaoToken 的 API 入口地址是https://taotoken.net/api注意这个地址后面不带斜杠也不带/v1具体路径拼接规则在下一节的配置里说明。如果你对可用模型和接入方式还不熟可以先在模型对话页面试一条请求确认 Key 本身是通的模型对话体验https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite3. 可复制配置docker-compose 骨架与 settings.json3.1 目录结构先规划好零基础最容易乱的就是挂载目录。建议在宿主机建一个统一的工作目录配置和数据都放里面mkdir -p ~/hermes/{data,workspace} cd ~/hermesdata用来持久化 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_BASEhttps://taotoken.net/api - HERMES_API_KEY${HERMES_API_KEY} - HERMES_MODELgpt-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_URLhttp://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_KEYsk-你的真实Key .env chmod 600 .envchmod 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 hermes4.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 UnauthorizedKey 错了或没生效。检查.env里有没有多余空格和引号改完必须docker compose up -d重建容器光restart不会重新读.env。返回 404 Not Foundbase_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 -dKey 这块如果你后面要跑长期编码任务或者接 Agent 工作流单次对话的按量方式可能不够划算可以看看 Coding Plan适合高频调用场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite需要新建或轮换 Key 的时候回到控制台的 API Keys 页面操作换完记得同步更新.env并重建容器API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入细节和参数说明以官方文档为准遇到路径拼接、模型名这类问题先查文档再动手接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你用的是 Claude Code 这类编码工具想让它也走同一个通道可以参考这份接入说明Claude Code 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后提醒一句.env和settings.json里的 Key 都是明文别把~/hermes整个目录传到公开仓库。真要备份只备份docker-compose.ymlKey 单独存密码管理器里。