如何在 Docker 中运行 Hermes Agent（自托管版）

为什么 Docker 是运行 Hermes Agent 的首选方式

Hermes Agent 将 Docker 容器作为首选部署目标。镜像内置了网关、控制台、运行时依赖以及合理的默认配置，让你无需在宿主机上折腾 Python 版本、系统库或 PATH 问题。你只需要一台安装了 Docker 的主机、一个用于存储状态的小型持久化卷，以及你的服务商 API 密钥，容器会处理好其余一切。

典型的自托管配置如下：

• 一个网关容器，对外暴露 8642 端口，提供兼容 OpenAI 的 API 接口和健康检查端点。
• 一个持久化命名卷，用于存储会话、记忆、已学技能和配置。
• 一个 .env 文件，存放服务商密钥和 Telegram 凭证。
• 可选项：一个以只读模式读取同一数据目录的控制台边车容器。

其余工作——升级、重启、日志轮转——均由 Docker 本身负责。本文将从头到尾演示完整的配置流程，并展示生产级的 docker-compose 布局，以及在将智能体部署到公网主机之前值得注意的坑点。

如果你还没决定是自托管还是使用托管服务，请先阅读自托管与 Hermify 托管服务对比。本指南其余部分默认你已决定自行运行容器。

前置条件

你需要准备：

• 一台安装了 Docker 24+ 的主机（Linux VPS、通过 Docker Desktop 的 macOS，或通过 WSL2 的 Windows）。
• 至少 1 个 vCPU 和 2 GB 内存。官方建议配置为 2 vCPU 和 8 GB 内存，以保证并发使用的流畅体验。
• 一个服务商 API 密钥（OpenAI、Anthropic、OpenRouter，或任何兼容 OpenAI 的端点）。
• 约 2 GB 的可用磁盘空间用于存储镜像，以及数据卷的增长空间。

任何主流服务商提供的 $5 VPS 均可满足最低配置要求。智能体在不进行推理时，I/O 和 CPU 占用都很低——大部分时间处于空闲状态，等待 Telegram 消息或定时任务。

第一步——创建数据目录

容器将所有内容持久化到镜像内部的 /data 目录。在宿主机上，你需要决定该目录的位置。约定俗成的路径是 ~/.hermes/data：

mkdir -p ~/.hermes/data

这个单一目录存放着会话历史、向量记忆、已学技能、加密密钥和用户配置。备份这个目录，就等于备份了整个智能体。一旦丢失，你将从零开始——容器本身是无状态的。

第二步——首次运行安装向导

第一次运行时，以交互模式启动容器，让它引导你输入密钥并将其写入 ~/.hermes/.env：

docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest setup

向导会询问：

• 默认的 LLM 服务商（OpenAI、Anthropic、OpenRouter，或自定义）。
• 服务商 API 密钥。
• 可选的 Telegram 机器人 Token 和允许访问的用户列表。
• 可选的语音服务商密钥（仅在计划启用语音模式时需要）。

配置值将写入宿主机上的 ~/.hermes/.env。请将该文件视为机密——执行 chmod 600 ~/.hermes/.env，切勿将其提交到版本控制。

第三步——启动持久化网关

向导完成后，以长期运行模式启动同一容器，开启网关服务：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -p 8642:8642 \
  --env-file ~/.hermes/.env \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest gateway

各参数说明：

• -d 以后台模式运行容器。
• --restart unless-stopped 在主机重启或容器崩溃后自动重新启动。
• -p 8642:8642 暴露兼容 OpenAI 的 API 接口和 /health 端点。
• --env-file ~/.hermes/.env 注入服务商密钥，无需将其写入镜像。
• -v ~/.hermes/data:/data 是持久化的关键——删掉这一行，智能体每次重启都会失去所有记忆。

验证服务是否正常运行：

curl http://localhost:8642/health
# {"status":"ok","gateway":"running"}

如果你在 VPS 上运行并希望从本地笔记本访问，请不要直接将端口绑定到 0.0.0.0。应在前面放置反向代理（Caddy、Nginx 或 Traefik）并启用 HTTPS，或仅通过 Tailscale 或 WireGuard 暴露端口。兼容 OpenAI 的 API 默认没有认证机制——它信任所在的网络环境。

第四步——使用 docker-compose 用于生产环境

对于任何超出快速测试的场景，请切换到 docker-compose.yaml。这让配置更易于审查，可以作为一个整体重启，并且便于添加可选的控制台边车容器：

services:
  gateway:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    command: gateway
    ports:
      - "127.0.0.1:8642:8642"
    env_file:
      - ./.env
    volumes:
      - hermes_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G

  dashboard:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard
    ports:
      - "127.0.0.1:8643:8643"
    volumes:
      - hermes_data:/data:ro
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  hermes_data:

几点值得注意的细节：

• 控制台容器以只读方式（:ro）挂载数据卷。它只读取会话和记忆来渲染界面，从不写入。这正是两个容器可以安全共存的原因。
• 网关端口绑定到宿主机的 127.0.0.1。公网暴露是反向代理的职责，而非 Docker 的。
• healthcheck 让 depends_on 在控制台启动前等待网关就绪。
• 1 GB 内存限制对大多数个人级工作负载来说已绰绰有余。高流量场景可适当调高。

使用 docker compose up -d 启动整个服务栈，用 docker compose logs -f 实时查看日志。

第五步——升级

容器是升级的基本单元。要迁移到新版本：

docker compose pull
docker compose up -d

Compose 会用新镜像重建网关容器，同时保持命名卷完整。记忆、技能和 Telegram 连接将完全恢复如初。生产环境建议固定到具体版本标签而非 latest——例如使用 ghcr.io/nousresearch/hermes-agent:0.42 而非 :latest——以确保升级是显式可控的。

升级前，先对卷做快照备份：

docker run --rm \
  -v hermes_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /data .

恢复操作是相同命令的逆向执行。这比单独回滚镜像更快捷、更安全。

常见坑点

两个网关容器共用同一个卷。 Hermes 的会话和记忆存储假设只有单一写入者。若两个网关容器同时指向同一个 /data，数据文件会在数分钟内损坏。控制台边车容器没有问题，因为它是只读的。

缺少 --env-file。 没有它，容器能启动，但第一次 LLM 调用就会以 401 失败。如果请求始终没有响应，请检查 docker logs hermes。

在公网 VPS 上绑定到 0.0.0.0:8642。 API 没有内置认证机制。务必在前面放置要求 HTTPS 的反向代理，并配合基本认证或网络层限制（Tailscale、防火墙规则）。

匿名卷。 如果忘记添加 -v ~/.hermes/data:/data 这一行，Docker 会创建一个匿名卷。它在重启后依然存在，但难以定位，且容易被意外清理。始终使用命名卷或宿主机绑定挂载。

Telegram 机器人重连。 升级后，机器人会自动重新连接。若未成功重连，请检查 .env 中是否仍有 TELEGRAM_BOT_TOKEN，并确认容器有外网出口。

关于 Telegram 相关问题，Hermes Agent Telegram 故障排查对消息侧有更深入的讨论。

跳过容器运维的繁琐

在 Docker 中运行 Hermes 并不复杂，但你仍需自行负责宿主机的一切：备份、TLS 证书、日志轮转、系统补丁，以及升级节奏。对于个人使用来说这完全可以接受——周末下午配置一次，此后每月大概花十分钟维护。

如果你宁愿省去这一切，Hermify 会在隔离的托管容器中运行你的 Hermes Agent，提供静态加密密钥、自动升级、每日卷快照，以及通过控制台两步完成 Telegram 接入。你只需提供服务商密钥，平台负责处理底层的所有事宜。

参考资料

• Hermes Agent Docker 用户指南
• Hermes Agent 快速上手
• Hermes Agent docker-compose 部署指南
• 在 $5 VPS 上自托管 Hermes Agent
• Docker 卷与持久化存储最佳实践 2026
• 使用 Docker Compose 构建 AI 智能体