Hermes Agent Docker：2026 年完整部署指南

两种 Docker 模式说明 - 开始之前选择

大多数指南完全跳过此决定并跳转到 docker run。不。这两种模式具有明显不同的安全性和操作配置文件。

模式 1 — Hermes 在容器内运行

Hermes 及其所有依赖项都位于图像内。您可以通过命名卷来管理状态。容器重新启动策略使其在重新启动后保持活动状态。这是最常见的生产模式。

• 与主机完全分离——不会意外写入您的机器
• 完全的便携性；使用相同的撰写文件在任何地方重新部署
• 开销比本地运行稍高

模式 2 — Docker 作为终端后端沙箱

在这里，Hermes 直接在主机（或容器中）运行，并调用 Docker 守护进程来启动临时容器以执行 shell。您可以通过设置 DOCKER_HOST 来配置它，以便 Hermes 可以访问守护进程：

export DOCKER_HOST=unix:///var/run/docker.sock   # Linux
export DOCKER_HOST=tcp://host.docker.internal:2375  # Windows/Mac (Docker Desktop)

先决条件和环境设置

在拉取任何镜像之前，请确认：

• Docker 引擎 24+ 或者 Docker 桌面版 4.26+
• 准备好 LLM API 密钥：OpenAI (OPENAI_API_KEY)、Anthropic (Anthropic_API_KEY) 或本地 Ollama 端点
• 端口 443 上的出站互联网访问（用于 LLM API 调用）
• 至少 2 GB 内存 分配给容器（对于 Ollama 支持的设置，建议使用 4 GB）

Windows 特定设置（Docker 桌面 + WSL2）

Windows 是大多数 Docker 部署悄然崩溃的地方。注意这些：

# Correct — Docker Desktop translates this automatically
volumes:
  - hermes_data:/root/.hermes

DOCKER_HOST=npipe:////./pipe/docker_engine

[wsl2]
memory=4GB
processors=2

快速入门——5分钟用Docker运行Hermes Agent

拉取官方镜像并运行安装向导：

# Pull the latest image
docker pull nousresearch/hermes-agent:latest

# Run with a persistent volume for state
docker run -it \
  -v hermes_home:/root/.hermes \
  -e OPENAI_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

这 设置向导 首次运行时启动。它会提示您：

1. 选择您的 LLM 提供商（OpenAI、Anthropic、Ollama 或自定义端点）
2. 输入您的 API 密钥或端点 URL
3. 配置终端后端（本机或 Docker 沙箱）

完成后，验证会话是否正常工作：

> hello

使用 Docker Compose 进行生产部署

裸 docker run 命令适用于测试。对于任何持久性的事情，请使用 Compose。

version: "3.9"

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    stdin_open: true
    tty: true

    environment:
      # Use environment secrets — never hardcode keys in compose files
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      Anthropic_API_KEY: ${Anthropic_API_KEY}
      HERMES_LOG_LEVEL: info

    volumes:
      - hermes_home:/root/.hermes         # Config + conversation history
      - hermes_skills:/root/.hermes/skills # Skill store — see next section

    deploy:
      resources:
        limits:
          memory: 2G
          cpus: "1.5"

    healthcheck:
      test: ["CMD", "hermes", "--health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  hermes_home:
  hermes_skills:

将您的 API 密钥存储在 .env 文件中（从不提交版本控制）：

OPENAI_API_KEY=sk-...
Anthropic_API_KEY=sk-ant-...

在容器重建过程中保留 Hermes 技能

这是最容易被忽视的生产问题。爱马仕商店将技能与一般配置分开学习。显式挂载这些路径：

更新图像时：

docker compose pull
docker compose up -d   # Named volumes persist automatically

高级拓扑 - 主机-Docker（同级容器）设置

当您希望 Hermes 编排同级容器以实现隔离的代码执行时，可以使用此架构 - 例如，安全地运行用户提交的代码。

┌─────────────────────────────────┐
│         Docker Host             │
│                                 │
│  ┌──────────────┐               │
│  │ hermes-agent │◄──socket──────┤── /var/run/docker.sock
│  │  container   │               │
│  └──────┬───────┘               │
│         │ docker run (sibling)  │
│  ┌──────▼───────┐               │
│  │  sandbox-1   │  (ephemeral)  │
│  └──────────────┘               │
└─────────────────────────────────┘

为该拓扑编写配置：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    restart: unless-stopped
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DOCKER_HOST: unix:///var/run/docker.sock
      HERMES_TERMINAL_BACKEND: docker
    volumes:
      - hermes_home:/root/.hermes
      - /var/run/docker.sock:/var/run/docker.sock  # Socket mount
    group_add:
      - "999"   # docker group GID — adjust to match your host

通过 Telegram Bot 将 Hermes 连接到 Claude

目前没有书面指南涵盖这一点 - 它仅以视频形式显示。这是完整的设置。

/newbot
→ Name: Hermes Agent
→ Username: your_hermes_bot
→ Save the token: 123456:ABC-DEF...

environment:
  Anthropic_API_KEY: ${Anthropic_API_KEY}
  HERMES_LLM_PROVIDER: Anthropic
  HERMES_TELEGRAM_TOKEN: ${TELEGRAM_BOT_TOKEN}
  HERMES_TELEGRAM_ALLOWED_USERS: "your_telegram_user_id"

docker compose up -d

多架构部署（ARM64 / Oracle 免费套餐 / Raspberry Pi）

nousresearch/hermes-agent 映像作为多架构清单提供。支持 ARM64 — 在 ARM 主机上显式拉取它：

# Oracle Free Tier (Ampere A1) or Raspberry Pi 4/5
docker pull --platform linux/arm64 nousresearch/hermes-agent:latest

# Verify the architecture
docker inspect nousresearch/hermes-agent:latest | grep Architecture

已知的 ARM 特定问题：

• 一些 Ollama 模型量化 (Q8) 在 ARM 上运行速度较慢；更喜欢 Q4_K_M 进行本地推理
• 如果您点击 exec format error，请确认您正在使用 --platform linux/arm64 标志
• Apple Silicon 上的 Docker Desktop 原生处理 ARM — 无需平台标志

排除常见的 Hermes Agent Docker 故障

您最有可能遇到的故障的参考表：

常见问题解答

最后的想法：清单和后续步骤

学习循环是 Hermes 与您在 Docker 中运行的所有其他代理的区别所在。上面的设置确保循环实际上 积累 - 不会重置 - 每次发布更新时。

在调用部署生产就绪之前，请确认：

• ☐ 为 hermes_home 和 hermes_skills 创建的命名卷
• ☐ API 密钥存储在 .env 中，未在 compose 中硬编码
• ☐ restart: unless-stopped 策略处于活动状态
• ☐ 健康检查通过：docker inspect hermes-agent --format='{{.State.Health.Status}}'
• ☐ 配置日志轮换（max-size、max-file）
• ☐ 设置资源限制以防止内存耗尽
• ☐ 设置向导已完成并验证了第一个聊天会话
• ☐ （如果模式 2）确认 Docker 套接字安装并考虑套接字代理

立即获得价值的后续步骤：

1. 运行一些实际任务 - 文件摘要、代码审查、网络研究 - 为技能库播种
2. 完成 10-15 个任务后，运行 hermes skills list 查看学到了什么
3. 查看 Nous Research GitHub 以获取涵盖自定义技能模板和内存调整的代理配置文档
4. 如果您使用 Oracle 免费套餐，请设置基于 cron 的 docker compose pull && docker compose up -d 来实现零停机图像更新，同时保留学习状态