配置国内镜像加速

macOS

打开 Docker Desktop → Settings → Docker Engine，直接在界面中编辑 JSON 配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}

保存后点击 Apply & Restart，等待 Docker 重启完成。

Linux

手动编辑 daemon 配置文件：

1
sudo vi /etc/docker/daemon.json

写入以下内容（如果文件已存在，合并 registry-mirrors 字段即可）：

1
2
3
4
5
6
7
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}

保存后重启 Docker 服务：

1
sudo systemctl daemon-reload && sudo systemctl restart docker

拉取镜像

1
docker pull nousresearch/hermes-agent
  • 镜像基于 Debian，内置了 Python、Node.js、Playwright/Chromium、ffmpeg、git 等依赖
  • 镜像本身是无状态的，可通过拉取新版本进行升级而不会丢失任何配置。

准备数据目录

Hermes Agent 的所有用户数据（配置、API Key、会话记录、技能、记忆等）都存放在一个本地目录中，通过 Docker 挂载到容器内的 /opt/data。

如果本机已经安装了 Hermes，并且已有 ~/.hermes/ 配置目录，可以新建一个独立目录给 Docker 使用，避免互相干扰：

1
mkdir -p ~/.hermes-docker

如果想沿用已有的 API Key 和配置，可以直接复制：

1
2
cp ~/.hermes/.env ~/.hermes-docker/.env
cp ~/.hermes/config.yaml ~/.hermes-docker/config.yaml

复制完成后可以直接跳到启动 Hermes Gateway，无需再跑 setup。

首次配置：运行 Setup 向导

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

这会启动一个交互式向导，引导你填写 API Key 等信息，完成后自动写入 ~/.hermes-docker/.env。只需做一次，容器完成后会自动销毁（--rm）。

启动 Hermes Gateway

配置完成后，以后台守护进程模式启动 Hermes：

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

参数说明：

参数 说明
-d 后台运行
--name hermes-docker 容器名称
--restart unless-stopped 异常退出自动重启
-v ~/.hermes-docker:/opt/data 挂载本地数据目录
-p 8642:8642 暴露 API 端口

可选：开启 API Server

如果你希望通过 OpenAI 兼容的接口（如 Cherry Studio、Open WebUI 等客户端）调用 Hermes，需要额外开启 API Server：

1
2
3
4
5
6
7
8
9
10
docker run -d \
  --name hermes-docker \
  --restart unless-stopped \
  -v ~/.hermes-docker:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

⚠️ 将端口暴露到公网有安全风险，请确保了解风险后再操作。

可选：开启 Web Dashboard

Hermes 内置了一个网页管理界面。直接开启 Dashboard 时，若绑定到 0.0.0.0 会触发 OAuth 认证要求（需要登录 Nous Portal），导致启动失败。需要额外加上 HERMES_DASHBOARD_INSECURE=1 跳过认证：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 先停掉当前容器
docker rm -f hermes-docker
# 重新启动并开启 Dashboard
docker run -d \
  --name hermes-docker \
  --restart unless-stopped \
  -v ~/.hermes-docker:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  -e HERMES_DASHBOARD_HOST=0.0.0.0 \
  -e HERMES_DASHBOARD_INSECURE=1 \
  nousresearch/hermes-agent gateway run

⚠️ HERMES_DASHBOARD_INSECURE=1 会跳过认证，仅建议在本地或受信任的网络环境中使用。

启动后浏览器访问 http://localhost:9119 或 http://IP:9119 即可。

交互式运行（CLI 聊天）

不想用 Gateway，只想直接在终端里和 Hermes 对话，可以用交互模式启动：

1
2
3
4
5
6
# 先停掉当前容器
docker rm -f hermes-docker
# 重新启动并开启交互式CLI
docker run -it --rm \
  -v ~/.hermes-docker:/opt/data \
  nousresearch/hermes-agent

容器退出后自动销毁（--rm），数据仍保存在本地目录里，不会丢失。

如果已经有一个运行中的容器，也可以直接进去执行：

1
2
3
docker exec -it hermes-docker /opt/hermes/.venv/bin/hermes
# approve feishu pairing code可以：
docker exec -it hermes-docker /opt/hermes/.venv/bin/hermes pairing approve feishu X43YLYNB

解释：/opt/hermes/.venv/bin/hermes 是容器内部 hermes 程序的完整路径。Hermes 装在一个 Python 虚拟环境（.venv）里，所以不能直接写 hermes，要写完整路径。

持久化目录说明

/opt/data 是容器内所有状态的唯一来源，对应本机的 ~/.hermes-docker/。目录结构如下：

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

镜像本身是无状态的，所有数据都在这个目录里。升级镜像、重建容器，数据完全不受影响。

多 Profile 支持

如果需要运行多个相互独立的 Agent（比如工作号和私人号分开），官方推荐的做法是一个 profile 对应一个容器，每个容器挂载各自的数据目录，而非使用 Hermes 内置的多 profile 功能。

好处：每个 Agent 有独立的文件系统、进程空间和资源限制，互不干扰，也可以独立升级或重启。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 工作 profile
docker run -d \
  --name hermes-work \
  --restart unless-stopped \
  -v ~/.hermes-work:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

# 私人 profile
docker run -d \
  --name hermes-personal \
  --restart unless-stopped \
  -v ~/.hermes-personal:/opt/data \
  -p 8643:8642 \
  nousresearch/hermes-agent gateway run

注意两个容器的宿主机端口不能重复（这里分别用了 8642 和 8643），容器内部都监听 8642。

⚠️ 不要让两个容器共用同一个数据目录，会造成并发写入冲突。

环境变量转发

API Key 默认从 /opt/data/.env 读取。如果你在 CI/CD 流水线或使用密钥管理工具，不想把 Key 写到磁盘，可以通过 -e 直接传入：

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

-e 传入的值会覆盖 .env 文件中的同名变量，两种方式可以混用。

升级镜像

由于数据全部在本地目录里，升级只需拉新镜像、重建容器，数据完全不受影响：

1
2
3
4
5
6
7
8
docker pull nousresearch/hermes-agent:latest
docker rm -f hermes-docker
docker run -d \
  --name hermes-docker \
  --restart unless-stopped \
  -v ~/.hermes-docker:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

参考