Docker 安裝

Hermes Agent 與 Docker 的交互有兩種不同的方式：

1. 在 Docker 中運行 Hermes — Agent 本身運行在容器內（本頁的主要內容）
2. 將 Docker 作為終端後端 — Agent 在主機上運行，但命令在 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	Agent 人格/身份
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
    # 取消註釋以轉發特定的環境變量，而不是使用 `.env` 文件：
    # 環境：
    #   - 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 作為執行環境時（非上述方法，而是 Agent 在 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          # 最近的日誌
docker exec hermes hermes version     # 驗證版本
docker stats hermes                    # 資源使用情況