🤖HermesBlog
Hermes 官方教程 · 第16篇2026/8/9· Easy Understand Hermes Agent

第十六篇：Docker 部署 Hermes——干净又省心

Hermes Agent 官方教程第十六篇：用 Docker 容器运行 Hermes，环境隔离、开箱即用。

Hermes tutorial

第十六篇：Docker 部署 Hermes——乾淨又省心

上一篇我們聊了各種安裝方式，今天來點更「乾淨」的——用 Docker 跑 Hermes。你可能會問：為啥要用 Docker？簡單說就倆字：省心。所有設定、API 金鑰、工作階段、技能、記憶，全都存在宿主機的一個目錄裡（預設 ~/.hermes），映像檔本身是無狀態的。想升級？直接拉新映像檔跑起來，設定一點不丟，跟換手機不丟通訊錄一個道理。

快速開始：先跑個安裝精靈

第一次用的話，先建個資料目錄，然後跑一次互動式安裝精靈：

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

它會問你 API 金鑰，然後寫進 ~/.hermes/.env，只需要跑這一次。強烈建議順手把聊天系統（Telegram、Discord 等）也配好，後面閘道才能幹活。

⚠️ 避坑提醒：別用 VPS 廠商網頁上的瀏覽器主控台來貼上這些指令！Hetzner 等好多家的網頁主控台會「吃」特殊字元——冒號變分號、@ 被吞、鍵盤配置還亂，你貼上的 -v ~/.hermes:/opt/data 可能悄悄就壞了。請用 SSH 連上去操作，實在不行就手敲指令，按 Enter 前仔細檢查每個 :、@、= 和 /。

💡 小撇步：容器裡跑一次 hermes setup --portal，重新整理權杖會持久化在掛載的 ~/.hermes 磁碟區裡，之後就不用重複登入了。

閘道模式：背景常駐跑起來

設定好之後，用背景模式把閘道跑起來（Telegram、Discord、Slack、WhatsApp 等都能接）：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

8642 連接埠是閘道內建的 OpenAI 相容 API 服務，只玩聊天平台的話可以不用開，但想要儀表板或外部工具連上來，就必須暴露它。

新版變化：s6 自動守護

這次文件有個重要更新：官方映像檔裡 gateway run 現在由 s6-overlay 自動守護——閘道程序崩了，幾秒內自動重啟，容器本身不會掛。想看日誌？docker logs 裡能看到守護程序的輸出，還有一行麵包屑提示確認升級成功。

想回到老行為（容器退出 = 閘道退出）？加 --no-supervise 參數或設 HERMES_GATEWAY_NO_SUPERVISE=1 就行。這個選項對 CI 冒煙測試有用——測試希望容器跟著閘道的狀態碼一起退出。生產環境建議就用預設的守護模式，更穩。

儀表板：一個容器全搞定

想要網頁儀表板？加個環境變數就行：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

儀表板也是 s6 守護的，崩了自動拉起，日誌同樣進 docker logs。

開放 API 服務？先想清楚

要把 API 服務暴露到外網，需要設 API_SERVER_ENABLED=true，再配 API_SERVER_HOST=0.0.0.0 和至少 8 位的 API_SERVER_KEY（用 openssl rand -hex 32 產生一個）：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/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

最後一句大實話：在公網機器上開任何連接埠都有安全風險，不懂就別亂開。

無人值守？記得開「熔斷」

新版文件還提醒了一件事：tool_loop_guardrails.hard_stop_enabled 預設是 false，這對互動式終端沒問題——人看著呢。但閘道無人值守時，agent 卡在死迴圈裡光靠警告可停不下來。想要「斷路器」效果，在 config.yaml 裡明確開啟：

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

總之，Docker 部署的好處就是乾淨、可升級、不丟資料。下一篇我們聊聊怎麼把 Hermes 接到更多平台，敬請期待！

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/docker

← 返回全部文章