Hermes Agent Docker 安装

清夏晚风 Lv7
  2026-06-23 16:29:45 2026-06-23 16:29:45 Created   2026-07-19 01:57:11 2026-07-19 01:57:11 Updated      

简介

Hermes Agent 是一个开源的 AI 智能体框架，能够自主感知环境、做出决策、调用工具执行操作，并与数字世界进行多轮交互。

使用 Docker 部署 Hermes Agent 可以实现一键部署，避免环境差异带来的”在我电脑上能跑”问题。

官方文档

网址：https://hermes-doc.aigc.green/

Hermes 与 Docker 的两种交互方式

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

  1. 在 Docker 中运行 Hermes — Agent 本身运行在容器内（本文的主要内容）
  2. 将 Docker 作为终端后端 — Agent 在主机上运行，但命令在 Docker 沙箱中执行

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

快速入门

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

1
2
3
4
5
mkdir -p ~/.hermes

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

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

以网关模式运行

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

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

交互式运行（CLI 聊天）

要针对已运行的数据目录打开一个交互式聊天会话：

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

持久化卷详解

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

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

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

环境变量传递

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

1
2
3
4
5
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 非常方便：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
version: "3.8"

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data
    # 取消注释以转发特定的环境变量，而不是使用 `.env` 文件：
    # 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 中设置限制：

1
2
3
4
5
6
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

升级方法

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

1
2
3
4
5
6
7
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：

1
2
docker compose pull
docker compose up -d

技能与凭证文件

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

SSH 和 Modal 后端也执行相同的同步操作 —— 在每次命令执行前，通过 rsync 或 Modal 挂载 API 上传技能和凭证文件。

安装额外依赖

容器内使用虚拟环境（venv）和 uv pip管理/安装依赖

故障排除

容器立即退出

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

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

“权限被拒绝”错误

容器默认以 root 用户运行。如果您的主机 ~/.hermes/ 目录是由非 root 用户创建的，则权限应能正常工作。如果遇到错误，请确保数据目录可写：

1
chmod -R 755 ~/.hermes

浏览器工具无法使用

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

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

网络问题后网关无法重新连接

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

1
docker restart hermes

检查容器健康状态

1
2
3
docker logs --tail 50 hermes  # 最近的日志
docker exec hermes hermes version  # 验证版本
docker stats hermes  # 资源使用情况

总结

使用 Docker 部署 Hermes Agent 是一种高效、可靠的方式，它提供了：

  • 环境一致性：避免”在我电脑上能跑”的问题
  • 快速部署：一键启动，无需复杂配置
  • 数据持久化：通过卷挂载保证数据安全
  • 易于升级：镜像升级不影响用户数据
  • 资源可控：可精确限制内存和CPU使用

无论是个人开发还是生产部署，Docker 都是一个理想的选择。希望这篇指南能帮助你顺利部署和使用 Hermes Agent！

  • Title: Hermes Agent Docker 安装
  • Author: 清夏晚风
  • Created at : 2026-06-23 16:29:45
  • Updated at : 2026-07-19 01:57:11
  • Link: https://blog.yuil.cn/2026/06/23/AI相关工具/AI Agent/Hermes Agent/01.Hermes Agent Docker 安装/
  • License: This work is licensed under CC BY-NC-SA 4.0.
Comments
On this page
Hermes Agent Docker 安装
  1. 简介
  2. 官方文档
  3. Hermes 与 Docker 的两种交互方式
  4. 快速入门
  5. 以网关模式运行
  6. 交互式运行（CLI 聊天）
  7. 持久化卷详解
  8. 环境变量传递
  9. Docker Compose 示例
  10. 资源限制建议
  11. Dockerfile 的作用
  12. 升级方法
  13. 技能与凭证文件
  14. 安装额外依赖
  15. 故障排除
    1. 容器立即退出
    2. “权限被拒绝”错误
    3. 浏览器工具无法使用
    4. 网络问题后网关无法重新连接
    5. 检查容器健康状态
  16. 总结