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 皮肤

注意

请勿同时运行两个 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，则复制 .env.example → .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 run 命令中添加 --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