Hermes 部署教程
Hermes Agent Docker 部署：配置、数据持久化与托管选择
把 Hermes 放进容器只是第一步。真正影响长期运行的是：模型配置是否生效、记忆是否保存在容器外，以及升级后能否恢复。
搜索 hermes agent docker，通常是想让 Hermes 在自己的服务器上持续运行。下面从版本选择、配置初始化到备份逐步说明，默认你已经安装 Docker Engine 和 Compose v2。Docker 承担环境隔离，模型调用仍需要单独配置服务商与凭证。
版本说明：站内两篇英文指南的配置文件、挂载路径与端口示例存在差异，不能混合使用。本页沿用其部署与运维思路；具体启动文件以所选版本的上游 Compose及 Dockerfile为准。下文命令适用于包含 gateway 服务、支持 Hermes 子命令透传的上游模板。
先选部署方式：自建 Docker 还是托管？
| 要处理的事情 | Docker 自建 | OpenClaw Launch 托管 Hermes |
|---|---|---|
| 服务器与容器 | 自己购买、安装和维护 | 由平台提供运行环境，通过仪表盘管理实例 |
| 配置与扩展 | 自己选择版本、挂载目录和系统依赖 | 使用平台支持的模型、渠道与扩展入口 |
| 远程访问 | 自己设置访问控制、反向代理与 HTTPS | 使用平台提供的访问入口 |
| 升级与故障 | 自己验证兼容性、查看日志并准备回退 | 平台管理基础设施与版本流程，用户仍需检查自己的配置 |
| 成本 | 服务器、存储、模型 API 与维护时间 | 托管套餐及所用模型的费用，按当前套餐和用量确认 |
需要自定义镜像、私有网络或特殊系统依赖，可以选择自建。希望尽快使用 Hermes，且功能需求在平台支持范围内，可以选择托管 Hermes。产品叫 OpenClaw Launch，但这里部署的框架是 Hermes；两种框架的配置不能互换。
第一步：固定版本，准备完整部署文件
- 从Hermes 官方发布页选择一个明确版本，记录标签或提交编号。
- 获取该版本的完整源码与部署文件。源码构建需要 Dockerfile 引用的脚本和依赖文件，不能只下载一个 Compose 文件。
- 检查模板采用源码构建还是预构建镜像。源码构建固定源码版本；预构建镜像固定经过验证的标签或 digest，避免使用浮动标签。
- 准备专用数据目录与模型服务商凭证。若主机已有 Hermes 数据，先备份，不要让两个实例同时写同一个目录。
在部署文件所在目录确认工具与 Compose 语法：
docker --version
docker compose version
docker compose config --quietconfig --quiet 只检查 Compose 配置，不会证明 Hermes 的模型或渠道已经可用。也不要把展开后的完整配置贴到公开帖子中，其中可能含有密钥。
第二步：挂载 Hermes 数据，再初始化配置
持久化要覆盖 Hermes 实际读取和写入的整个数据目录。核对时查看挂载的宿主机来源、容器内目标，以及启动进程使用的目录；不要仅凭目录名称里有 hermes 就判断正确。当前上游 Compose 使用宿主机 ~/.hermes，挂载到容器 /opt/data；所选旧版本应按同版本文件处理。
Hermes 的常规设置放在 config.yaml，密钥放在数据目录的 .env。英文指南提到的 OPENROUTER_API_KEY 和 OPENAI_API_KEY 分别用于对应服务商，选择实际使用的一项即可。完整规则见上游配置说明。这里使用初始化向导生成配置，不另写一套模型或渠道字段。
以下流程针对当前上游源码构建模板，在源码目录执行。UID/GID 用于让容器写入的数据与宿主机用户匹配：
mkdir -p ~/.hermes
export HERMES_UID="$(id -u)"
export HERMES_GID="$(id -g)"
docker compose build
docker compose run --rm gateway --help
docker compose run --rm gateway setup在向导里完成模型服务商与凭证配置。上游的容器入口脚本负责转发 Hermes 子命令；保留模板的入口，不要为绕过启动报错随意覆盖它。如果使用预构建镜像，按该版本说明拉取固定镜像，替代上面的构建步骤。
Compose 文件旁边用于变量替换的 .env，与 Hermes 数据目录内保存密钥的 .env 是不同用途。只在宿主机写下密钥，并不代表容器里的 Hermes 会读取它。让初始化向导写入正确目录，并限制凭证文件访问权限。
第三步：启动网关，分层确认运行状态
docker compose up -d gateway
docker compose ps
docker compose logs --tail=100 gateway- 先看进程：容器应保持运行；反复退出时先查日志，不要靠连续重启掩盖错误。
- 再看配置：确认模型服务商、凭证和所需渠道已配置到当前实例。
- 最后验证任务：在自己的测试实例发送不含隐私的简短请求，确认模型能返回结果；这一步可能产生 API 费用。
网关运行、网页能打开、模型能回答是三个检查点。不要把旧教程中的某个端口或 /health 路径当作所有 Hermes 镜像都具备的接口。需要网页管理时，按同版本模板启用对应服务；远程访问使用 SSH 隧道，或带认证的 HTTPS 反向代理。
第四步：备份后升级，并保留恢复路径
镜像保存运行环境，挂载目录保存实例状态。备份应覆盖配置、密钥、记忆、Skills、会话及其他实际写入的数据；复制 Compose 文件不能代替备份。先停止所有写入同一目录的 Hermes 进程，再创建备份，避免复制到一半的数据。
如果使用上述默认宿主机目录，可在停止相关进程后执行：
docker compose stop
umask 077
mkdir -p ~/hermes-backups
tar -czf ~/hermes-backups/hermes-$(date +%Y%m%d-%H%M%S).tar.gz \
-C "$HOME" .hermes备份包含密钥，存到受保护的位置。升级时选择新固定版本，按原方式构建或拉取镜像，然后运行 docker compose up -d。核对模型调用、渠道连接与已有记忆后再结束维护。需要回退时，除了旧镜像，还要确认旧版本能读取升级后的数据；必要时恢复升级前备份。
不要把删除持久卷当作常规升级步骤。修改挂载路径之前先记录原路径，否则容器可能正常启动，却表现得像一个没有记忆的新实例。
常见问题：从出错的那一层排查
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 镜像拉取或构建失败 | 固定标签是否存在、网络是否能访问镜像仓库与依赖源 | 区分下载失败和容器启动失败；保留完整错误信息 |
| 写入配置时 Permission denied | 宿主机目录属主、模板的 UID/GID 设置、只读挂载 | 按所选镜像的用户映射规则修复目标目录权限 |
| 容器运行，但模型返回认证错误 | 实际服务商、密钥读取位置与账户状态 | 检查对应凭证，不要通过改端口解决 API 认证问题 |
| 重建后记忆或 Skills 消失 | 新旧容器是否挂载同一数据目录 | 找到原数据并恢复正确挂载，再检查备份 |
| 只有聊天渠道不响应 | 渠道配置、机器人凭证、访问许可与相关日志 | 按该渠道的 Hermes 接入文档检查，不套用 OpenClaw 字段 |
| 容器频繁退出或内存不足 | 退出原因、宿主机剩余资源和任务负载 | 检查资源使用；浏览器任务和本地模型需单独估算 |
国内网络环境下，源码下载、镜像下载与模型 API 连通性需要分别检查。在宿主机能打开网页，不代表容器可以访问模型接口。托管可以减少自行维护服务器网络的工作，但所选模型的凭证、额度与使用条件仍需要确认。
常见问题
Hermes Agent 必须用 Docker 部署吗？
不必须。Docker 适合想隔离运行环境、自己管理服务器的用户；也可以使用原生安装或 OpenClaw Launch 托管。使用托管 Hermes 实例不需要在自己的电脑上安装 Docker。
重启 Hermes 容器会丢失记忆吗？
普通容器重启通常保留可写层，但删除并重建容器时不能依赖它。把实际使用的 Hermes 数据目录挂载到宿主机目录或持久卷，并备份配置、凭证、记忆、Skills 和会话。挂载到错误路径也无法保护真实数据。
可以直接复制 OpenClaw 的 Docker 配置吗？
不能直接复制。Hermes 的配置文件、容器入口和数据路径需要按所选 Hermes 版本确认；OpenClaw 的配置字段与端口不能当作 Hermes 的默认值。本页只介绍 Hermes 部署。
Docker 部署 Hermes 需要 GPU 吗？
调用云端模型 API 时，不需要为了运行 Hermes 配备 GPU。如果同时自建 Ollama 或其他本地推理服务，GPU 和显存要求由模型及推理服务决定，需要单独规划。
OpenClaw Launch 托管能直接套用自建 Compose 文件吗？
托管实例由平台管理容器、网络和版本，用户通过仪表盘配置可用功能。自建 Compose 文件不是托管实例的导入格式；自定义镜像、宿主机挂载和额外系统依赖应先确认平台是否支持。