Hermes Agent — Docker

Hermes Agent 与 Docker 的交互有两种截然不同的方式：

1. 在 Docker 中运行 Hermes —— 代理本身运行在容器内（本页重点）
2. Docker 作为终端后端 —— 代理在主机上运行，但命令在 Docker 沙箱中执行（参见 配置 → terminal.backend）

本页介绍第一种方式。容器将所有用户数据（配置、API 密钥、会话、技能、记忆等）存储在一个从主机挂载的目录中，路径为 /opt/data。镜像本身是无状态的，可通过拉取新版本进行升级，而不会丢失任何配置。

快速入门

如果你是首次运行 Hermes Agent，请在主机上创建一个数据目录，并以交互模式启动容器以运行设置向导：

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

这将进入设置向导，提示你输入 API 密钥，并将其写入 ~/.hermes/.env。只需执行一次即可。强烈建议在此阶段设置一个聊天系统，以便网关正常工作。

以网关模式运行

配置完成后，可将容器以后台模式运行，作为持久化的网关（支持 Telegram、Discord、Slack、WhatsApp 等）：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

交互式运行（CLI 聊天）

要对已运行的数据目录开启交互式聊天会话：

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

持久化卷

/opt/data 卷是 Hermes 所有状态的唯一来源。它映射到主机上的 ~/.hermes/ 目录，包含以下内容：

路径	内容
.env	API 密钥和敏感信息
config.yaml	所有 Hermes 配置
SOUL.md	代理人格/身份信息
sessions/	对话历史记录
memories/	持久化记忆存储
skills/	已安装的技能
cron/	定时任务定义
hooks/	事件钩子
logs/	运行时日志
skins/	自定义 CLI 外观

warning

请勿同时运行两个 Hermes 容器访问同一数据目录——会话文件和内存存储不支持并发访问。

环境变量传递

API 密钥从容器内的 /opt/data/.env 读取。你也可以直接传入环境变量：

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent

直接通过 -e 标志指定的值会覆盖 .env 中的值。这对于 CI/CD 或密钥管理器集成非常有用，避免将密钥写入磁盘。

Docker Compose 示例

对于持久化网关部署，使用 docker-compose.yaml 非常方便：

version: "3.8"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data
    # Uncomment to forward specific env vars instead of using .env file:
    # environment:
    #   - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    #   - OPENAI_API_KEY=${OPENAI_API_KEY}
    #   - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

使用 docker compose up -d 启动服务，并通过 docker compose logs -f hermes 查看日志。

资源限制

Hermes 容器需要中等资源。推荐最低配置如下：

资源	最低要求	推荐配置
内存	1 GB	2–4 GB
CPU	1 核	2 核
磁盘（数据卷）	500 MB	2+ GB（随会话/技能增长）

浏览器自动化（Playwright/Chromium）是最耗内存的功能。若不需要浏览器工具，1 GB 已足够；若启用浏览器功能，建议至少分配 2 GB。

在 Docker 中设置资源限制：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  --memory=4g --cpus=2 \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Dockerfile 的作用

官方镜像基于 debian:13.4 构建，包含以下内容：

• Python 3 及所有 Hermes 依赖项（pip install -e ".[all]"）
• Node.js + npm（用于浏览器自动化和 WhatsApp 桥接）
• Playwright 与 Chromium（npx playwright install --with-deps chromium）
• ripgrep 和 ffmpeg 作为系统工具
• WhatsApp 桥接组件（scripts/whatsapp-bridge/）

入口脚本（docker/entrypoint.sh）会在首次运行时引导数据卷：

• 创建目录结构（sessions/、memories/、skills/ 等）
• 若不存在 .env.example，则复制 .env → .env
• 若缺少默认 config.yaml，则复制一份
• 若缺少默认 SOUL.md，则复制一份
• 使用基于清单的同步方式同步内置技能（保留用户修改）
• 然后以你传入的参数运行 hermes

升级方法

拉取最新镜像并重建容器。你的数据目录将保持不变。

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

或使用 Docker Compose：

docker compose pull
docker compose up -d

技能与凭证文件

当使用 Docker 作为执行环境（非上述方式，而是指代理在 Docker 沙箱中运行命令时），Hermes 会自动将技能目录（~/.hermes/skills/）以及技能声明的任何凭证文件以只读卷的形式挂载进容器。这意味着技能脚本、模板和引用可在沙箱中直接使用，无需手动配置。

SSH 和 Modal 后端也采用相同机制：每次执行命令前，通过 rsync 或 Modal 挂载 API 上传技能和凭证文件。

故障排查

容器立即退出

检查日志：docker logs hermes。常见原因包括：

• 缺失或无效的 .env 文件 —— 建议先以交互模式运行完成设置
• 若暴露端口，可能存在端口冲突

“权限拒绝”错误

容器默认以 root 用户运行。如果主机上的 ~/.hermes/ 是由非 root 用户创建的，权限通常可以正常工作。若仍出现错误，请确保数据目录可写：

chmod -R 755 ~/.hermes

浏览器工具无法使用

Playwright 需要共享内存。请在 Docker 运行命令中添加 --shm-size=1g：

docker run -d \
  --name hermes \
  --shm-size=1g \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

网关在网络中断后无法重新连接

--restart unless-stopped 标志可处理大多数临时故障。若网关卡住，请重启容器：

docker restart hermes

检查容器健康状态

docker logs --tail 50 hermes          # Recent logs
docker exec hermes hermes version     # Verify version
docker stats hermes                    # Resource usage