指南

如何在 Mac 上用 Docker 安裝 Hermes Agent

2026年5月18日

這篇指南說明如何在 Mac 上透過 Docker Desktop 執行 Hermes Agent。Docker 負責提供執行環境，而你的設定、認證、session 與 logs 會保存在 Mac 的固定資料夾中。

Hermes Agent 可以使用 API key provider，不過本文以 ChatGPT OAuth 連接 OpenAI Codex provider 為主。建議順序是安裝 Docker Desktop、執行 setup、設定 provider、啟動 Hermes Agent，最後確認 localhost:9119 的 dashboard。

快速摘要

先在 Mac 安裝並啟動 Docker Desktop。
使用官方 image：nousresearch/hermes-agent。
將 ~/.hermes mount 到 /opt/data，保留設定、OAuth、sessions、skills 與 logs。
先執行 setup，再用 hermes model 選擇 OpenAI Codex。
啟用 dashboard 後，瀏覽器應能開啟 http://localhost:9119。

準備項目

項目	說明
Mac	Apple Silicon 與 Intel Mac 都可使用，但 Docker Desktop 安裝檔需符合晶片類型。
Docker Desktop	用來執行 Hermes Agent container。
Terminal	用來執行 Docker、setup、OAuth 與 log 檢查。
ChatGPT 帳號	透過 ChatGPT OAuth 連接 OpenAI Codex 時需要。
網路連線	下載 image 與完成 OAuth 登入時需要。

顯示 Mac、Docker Desktop、Hermes Agent container 與持久化資料 volume 的示意圖 — Docker 執行 Hermes Agent，而 `~/.hermes` 在 Mac 上保留資料。

Docker 方式的意義

Hermes Agent 是 NousResearch 的 AI agent runtime。官方文件說明了多種使用方式，包括 local installation、Docker execution，以及 Docker terminal backend。本文聚焦於把 Hermes Agent 本身放在 Docker container 內執行。

這樣做的好處是 runtime 較容易隔離。你不必把 Python、Node.js、browser automation dependencies 與相關工具直接安裝到 macOS。相對地，Docker Desktop 必須先啟動，而且檔案存取要透過明確 mount 的資料夾來理解。

Hermes Agent 在 container 內使用 /opt/data 作為使用者資料位置。因此本文把 Mac 的 ~/.hermes 對應到 /opt/data。

安裝 Docker Desktop

從 Docker 官方 Mac 安裝文件下載 Docker Desktop。M 系列 Mac 選 Apple Silicon 版本，舊款 Intel Mac 選 Intel 版本。

基本安裝流程如下：

從 Docker 官方 Mac 安裝頁下載 Docker Desktop。
開啟 Docker.dmg，把 Docker 移到 Applications 資料夾。
從 Applications 啟動 Docker Desktop。
檢查初始權限提示與條款畫面。
等到選單列中的 Docker 圖示穩定顯示為可用狀態。

接著在 Terminal 檢查：

docker --version

如果找不到指令，可能是 Docker Desktop 尚未啟動，或 CLI 整合尚未完成。

顯示安裝 Docker Desktop 並在 Terminal 執行 docker version 的流程 — 啟動 Hermes Agent image 前，先確認 Docker Desktop 能正常使用。

為什麼要 mount `~/.hermes`

Volume mount 是 Docker 安裝中最重要的細節。若沒有 mount，container 被刪除後，設定與登入狀態可能會消失。

所有 Hermes command 都應使用同一個 mount：

-v ~/.hermes:/opt/data

顯示 Mac 的 ~/.hermes 資料夾連接到 Docker container 內 /opt/data 的圖 — `~/.hermes:/opt/data` 會保留設定、sessions、OAuth 資料、skills 與 logs。

第一次執行：啟動 setup wizard

建立資料夾並執行官方 setup：

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

因為使用 --rm，暫時 container 會在結束後刪除，但 /opt/data 中建立的檔案會保留在 ~/.hermes。

setup wizard 可能建立或更新以下內容：

位置	用途
`~/.hermes/.env`	使用 API key provider 時存放 secrets。
`~/.hermes/config.yaml`	存放 model、backend、gateway 與 tools 設定。
`~/.hermes/SOUL.md`	存放 agent 的基本行為方向。
`~/.hermes/sessions/`	保存 session 歷史。
`~/.hermes/memories/`	啟用時保存長期記憶資料。
`~/.hermes/skills/`	保存已安裝 skills。
`~/.hermes/logs/`	保存執行 logs。

實際 prompts 會因 Hermes Agent 版本而不同，但初學者可以用這個判斷方式：

setup prompt	實用選擇
Model provider	選擇 `OpenAI Codex` 或 `Codex` 選項。若沒有看到，先完成 setup，再執行 `hermes model`。
Authentication method	API key provider 會把值存在 `.env`。ChatGPT OAuth 會把 tokens 存在 `auth.json` 這類 auth store。
Chat system 或 gateway integration	Telegram、Discord、Slack 若不是馬上要用，可稍後再設定。若打算長期跑 gateway，這裡先設定也方便。
不確定的 defaults	先保留 defaults，等安裝確認可用後再調整 `config.yaml`。

也就是說，先讓 setup 建立基本檔案與資料夾；若 provider 選擇不清楚，再用 hermes model 重新開啟設定。

setup 後可檢查：

ls -la ~/.hermes

也確認 config.yaml 是否存在。不要公開整個檔案；在本機查看前幾行即可。

sed -n '1,80p' ~/.hermes/config.yaml

不要印出或分享 .env，因為其中可能包含 secrets。若只要確認檔案存在：

ls -la ~/.hermes/.env

如果 setup 結束後沒有 ~/.hermes/config.yaml，或資料夾是空的，請先檢查 volume mount。Command 必須包含 -v ~/.hermes:/opt/data。

設定 ChatGPT OAuth

如果 setup 尚未完成 provider 設定，開啟 model picker：

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

選擇 OpenAI Codex 或最接近的 Codex provider。若 Hermes Agent 顯示 URL 或 device code，請在 Mac 瀏覽器開啟並使用 ChatGPT 登入。

部分版本也可使用：

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

OAuth token 不應只存在於可丟棄的 container 裡。它會保存在已 mount 的 ~/.hermes 資料夾，例如 auth.json 這類 auth store 中。這樣重建 container 時，provider 設定仍可保留。

顯示瀏覽器 ChatGPT OAuth 登入與 Hermes Agent Docker container 連接的示意圖 — ChatGPT OAuth 可連接 OpenAI Codex，而不必把 OpenAI API key 貼進 command。

執行 Hermes Agent

完成 setup 與 provider 設定後，啟動互動模式：

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

若互動 session 正常開啟，基本安裝就已可用。之後每個 command 都請使用同一個 volume mount。

主要 options 的意思如下：

Option	意思
`docker run`	啟動新的 container。
`-it`	開啟互動式 terminal session。
`--rm`	結束後移除暫時 container。
`-v ~/.hermes:/opt/data`	將 Mac 的 `~/.hermes` 連到 container 內的 `/opt/data`。
`nousresearch/hermes-agent`	使用官方 Hermes Agent Docker image。

在 `localhost:9119` 檢查 dashboard

setup、provider 設定與互動執行都可用後，先檢查 image 與 version：

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

若要確認 OAuth provider 狀態，使用同一個資料夾：

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

若要在背景執行 gateway 與 dashboard，開放兩個 port：

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

接著在瀏覽器開啟 http://localhost:9119。http://127.0.0.1:9119 也應可使用。dashboard 是用來檢查設定、sessions、logs 與 skills 的本機管理介面。

若頁面無法開啟：

curl -I http://127.0.0.1:9119

runtime 詳細資訊可從 logs 查看：

docker logs --tail 50 hermes

dashboard 相關 logs 可能以 [dashboard] 開頭。

停止並移除背景 container：

docker stop hermes
docker rm hermes

常見問題

問題	檢查項目
`Cannot connect to the Docker daemon`	Docker Desktop 尚未啟動。
`docker: command not found`	Docker CLI 尚未在 Terminal 可用。
OAuth URL 無法開啟	將 URL 或 device code 複製到 Mac 瀏覽器。
OpenAI Codex provider 不顯示	拉取最新 Hermes Agent image，重新檢查 `hermes model` 選單。
設定消失	缺少或更改了 `-v ~/.hermes:/opt/data`。
Permission error	檢查目前 macOS user 是否能寫入 `~/.hermes`。
dashboard 無法開啟	檢查 `-p 9119:9119`、`-e HERMES_DASHBOARD=1` 與 `[dashboard]` logs。
port 衝突	其他程序可能正在使用 `8642` 或 `9119`。

在 Apple Silicon Mac 上，只要不是強制使用 Intel-only image，Docker Desktop 通常會處理 architecture 差異。建議先從官方 latest image 與最新 Docker Desktop 開始。

顯示 Docker 狀態、OAuth、volume mount、logs 與 dashboard 檢查流程 — 依序檢查 Docker、OAuth、volume mount、logs 與 dashboard port。

更新或移除

更新時拉取最新 image，並在保留 ~/.hermes 的情況下重建 container：

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
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

移除 container 與 image：

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

只有在你也想刪除設定、OAuth tokens、sessions、skills 與 logs 時，才刪除 ~/.hermes。

rm -rf ~/.hermes

重點整理

穩定流程是：Docker Desktop、setup、透過 ChatGPT OAuth 連接 OpenAI Codex、將 ~/.hermes mount 到 /opt/data，並在 gateway 模式下確認 http://localhost:9119。