1. 为什么要在 Docker Compose 里跑 Hermes AgentHermes Agent 是 Nous Research 出的开源自托管 AI Agent社区里叫它「爱马仕龙虾」。它和普通聊天机器人的区别在于有一套闭环学习机制用 MEMORY.md 和 USER.md 跨会话记住你的偏好任务做完会自动把流程封装成可复用 Skill历史对话存在 SQLite 里配合摘要索引做跨会话检索。换句话说它是个越用越懂你的长驻 Agent而不是用完即走的一次性工具。它内置 29 个工具集覆盖浏览器自动化、终端执行、文件操作、网页抓取、图像生成、语音合成、定时任务还能通过一个 Gateway 连通 Telegram、Discord、Slack 等 15 消息平台。模型层面完全中立OpenAI 兼容接口、OpenRouter、Anthropic、MiniMax 都能接切换模型不用改代码。问题来了Hermes 的依赖链很长Python 3、Node.js、Playwright 加 Chromium手动装一遍很容易把宿主机环境搞乱。Docker Compose 的价值就在这里——官方镜像基于 Debian 打包好全部依赖数据目录挂载到宿主机升级时直接 pull 新镜像记忆和技能一点不丢。再配一行restart: unless-stopped宿主机重启后容器自动拉起配合 Telegram Bot 就是一个 7×24 小时在线的私人助手。这篇面向想在 VPS 或本地长期跑 Hermes 的人从 compose 文件、config 骨架、Telegram 环境变量一路写到容器启动后的连通性验证和报错排查。如果你之前卡在「容器起来了但 Bot 不回消息」第五节的排查清单可以直接对照。2. 前置准备TaoToken 统一 Key 与目录规划在写 compose 文件之前先把两件事定下来模型通道和数据目录。模型通道这块Hermes 支持任何 OpenAI 兼容接口。我实测下来用 TaoToken 的统一 Key 接进去比较省事——一个 Key 覆盖多个模型不用在 config 里来回换 base_url 和密钥。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions协议填进 Hermes 的 Custom OpenAI-compatible endpoint 就能用。你需要先去控制台拿一个 Key获取 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite拿到形如sk-xxxx的 Key 后先放一边后面配置向导会用到。想先确认模型列表和对话效果可以打开模型对话页试一条模型对话体验https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite目录规划建议统一放在~/service/hermes/数据目录用./data/data与 compose 文件同级备份时整个目录打包即可。硬件方面不开浏览器自动化 1GB 内存够用要跑 Playwright/Chromium 至少 2GB推荐 4GB。软件只需要 Docker 和 docker compose v2。3. 可复制的 docker-compose.yml 与 config 骨架3.1 创建目录并对齐权限cd ~/service mkdir -p hermes/data/data cd hermes sudo chown -R 10000:10000 datachown这一步别省。容器内进程以 UID 10000 运行宿主机挂载目录权限不对启动时会报Permission denied写不进 config。3.2 docker-compose.yml在~/service/hermes/下创建docker-compose.ymlservices: hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped command: gateway run ports: - 8642:8642 volumes: - ./data/data:/opt/data environment: - TELEGRAM_BOT_TOKEN${TELEGRAM_BOT_TOKEN} - TELEGRAM_ALLOWED_USERS${TELEGRAM_ALLOWED_USERS} deploy: resources: limits: memory: 4G cpus: 2.0 networks: - hermes-net dashboard: image: nousresearch/hermes-agent:latest container_name: hermes-dashboard restart: unless-stopped command: dashboard --host 0.0.0.0 --port 9119 --insecure --no-open ports: - 9119:9119 volumes: - ./data/data:/opt/data environment: - GATEWAY_HEALTH_URLhttp://hermes:8642 networks: - hermes-net depends_on: - hermes deploy: resources: limits: memory: 512M cpus: 0.5 networks: hermes-net: driver: bridge两个容器挂同一个./data/data卷共享配置、记忆和技能。hermes是核心 Gateway处理对话和工具调用dashboard是 Web 面板通过GATEWAY_HEALTH_URL探活 Gateway。--insecure --no-open表示面板无鉴权启动且不在服务器端尝试开浏览器所以 9119 端口别直接暴露公网用 SSH 隧道访问更稳妥。3.3 .env 环境变量模板同目录创建.env把 Telegram 相关变量抽出来避免写死在 compose 里# Telegram Bot Token从 BotFather 获取 TELEGRAM_BOT_TOKEN7xxxxxxxxx:AAxxxxxxxxxxxxxxxx # 允许使用 Bot 的 Telegram 数字 ID多个用逗号分隔 TELEGRAM_ALLOWED_USERS8610xxxxxx.env里不要留空格KEYvalue直接写。这个文件包含敏感信息记得chmod 600 .env。3.4 config.toml 骨架Hermes 的配置文件在数据目录下路径是./data/data/config.yaml部分版本用config.toml以容器内实际生成为准。如果向导没生成可以手动放一份骨架[inference] provider custom base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken密钥 model gpt-4o-mini [gateway] host 0.0.0.0 port 8642 [messaging.telegram] enabled true bot_token ${TELEGRAM_BOT_TOKEN} allowed_users [8610xxxxxx] home_channel 8610xxxxxxbase_url结尾的/v1别漏Hermes 会拼/chat/completions。home_channel是 Cron 任务结果和跨平台通知的投递目标Telegram 私聊场景填你自己的数字 ID 即可。4. 启动容器并跑通配置向导4.1 拉起服务cd ~/service/hermes docker compose up -d正常输出会看到 network、hermes、hermes-dashboard 三个对象创建成功。用docker compose ps确认两个容器都是Up状态。4.2 进入容器运行 setupdocker exec -ti hermes-dashboard bash /opt/hermes/.venv/bin/python3 /opt/hermes/.venv/bin/hermes setup向导会依次问配置位置、推理提供商、消息平台。推理提供商选Custom OpenAI-compatible endpoint然后填API base URL: https://taotoken.net/api/v1 API key: sk-你的TaoToken密钥验证通过后会列出可用模型选一个即可。消息平台那一步勾选 Telegram粘贴 Bot Token 和你的数字 ID向导会写入 allowlist 并设置 home channel。4.3 重启让 Telegram 生效配置写完后 Gateway 不会自动重载 Telegram 连接必须重启容器exit docker compose restart hermes docker compose logs -f hermes看到下面两行日志就说明 Bot 上线了[gateway] Telegram bot connected: 你的BotName [gateway] Ready. Listening for messages...5. 验证请求与成功结果5.1 验证 TaoToken Key 是否生效最直接的方式是在容器里发一条测试请求确认 Key 和 base_url 都对docker exec -ti hermes-dashboard bash curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}返回 JSON 里带choices[0].message.content就说明 Key 有效。如果返回 401检查 Key 有没有多余空格返回 404检查 base_url 是不是漏了/v1。5.2 验证 Telegram Bot 连通性打开 Telegram 找到你的 Bot发一条hello。正常情况几秒内会回复。如果没反应先在容器里看日志docker compose logs --tail50 hermes | grep -i telegram日志里出现Unauthorized user说明你的数字 ID 没进 allowlist出现getUpdates conflict说明同一个 Token 在别处还有实例在跑把另一个停掉。5.3 验证 Gateway 健康状态Dashboard 容器通过GATEWAY_HEALTH_URL探活可以直接 curldocker exec -ti hermes-dashboard bash curl -s http://hermes:8642/health返回{status:ok}表示 Gateway 正常。浏览器访问http://你的服务器IP:9119能看到面板但记得用 SSH 隧道别裸奔公网。6. 本篇常见报错排查容器起来就退出日志报Permission denied: /opt/data/config.yaml宿主机数据目录权限不对。执行sudo chown -R 10000:10000 ~/service/hermes/data后docker compose restart。Telegram Bot 不回消息日志无 telegram 相关行向导配置完没重启容器。docker compose restart hermes即可。这是最常见的坑配置写入后 Gateway 不会热加载消息平台。curl 测试返回 401 UnauthorizedTaoToken Key 错误或过期。去控制台重新生成一个重新获取 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite返回 404 Not Foundbase_url 写成了https://taotoken.net/api少了/v1。Hermes 会自己拼/chat/completions所以 base_url 必须到/v1这一层。日志报getUpdates conflict同一个 Bot Token 在多个地方跑。检查是不是本地还开着一个 Hermes 实例或者之前用docker run起过一个没停。docker ps -a找出来停掉。Dashboard 打不开浏览器超时9119 端口没放行或者容器没起来。先docker compose ps确认 dashboard 是 Up再检查防火墙。安全起见建议用ssh -L 9119:localhost:9119 userserver隧道访问。内存被吃满容器被 OOM kill开了浏览器自动化但内存给少了。compose 里 hermes 的 memory limit 调到 4G 以上或者关掉 Playwright 相关工具集。想切换模型但不想重跑向导进容器执行hermes setup model或者直接改config.yaml里的model字段后重启容器。长期跑编码和 Agent 任务的话用 Coding Plan 通道更划算Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档在哪看参数细节和最新字段以官方文档为准接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后补一句实操经验.env和config.yaml里的 Key 别提交到 Git数据目录定期打包备份升级镜像前先docker compose down再pull避免容器运行中文件句柄冲突。Telegram 的 allowlist 一定要设Bot Token 泄露等于把整个 Agent 的执行权限交出去出事第一时间去 BotFather 发/revoke。
