H繁中版
文件user-guidemulti profile gateways
<!-- Source: https://hermesbible.com/docs/user-guide/multi-profile-gateways -->

章節：使用 Hermes · 網址：https://hermesbible.com/docs/user-guide/multi-profile-gateways

同時執行多個 Gateway

在一台機器上以託管服務的形式，同時運作多個 Profile —— 每個 Profile 各自擁有獨立的 bot token、Session 和記憶體。本頁面介紹相關的運維要點：同時啟動所有 Profile、跨 Profile 查看日誌、防止主機進入休眠，以及處理常見的 launchd/systemd 異常狀況。

如果你只運行一個 Hermes Agent，不需要參閱本頁面——請先參閱 Profile 了解基本概念。

何時需要使用

當你有兩個以上需要同時保持上線的 Hermes Agent 時，就需要這個設定。常見情境包括：

  • 個人助理跑在一個 Telegram bot 上，程式碼助手跑在另一個 bot 上
  • 每位家庭成員各有一個 Agent，或每個 Slack 工作區各有一個
  • 同一份設定分別有沙箱版和正式版實例
  • 研究 Agent + 寫作 Agent + 定時排程 Bot —— 各自擁有獨立的記憶體和技能

每個 Profile 都已經自動建立了屬於自己的平台級別 LaunchAgent（ai.hermes.gateway-<name>.plist）或 systemd user service（hermes-gateway-<name>.service）。本指南補充的是如何集體管理這些服務的模式。

快速開始

# 建立 Profile（僅需執行一次）
hermes profile create coder
hermes profile create personal-bot
hermes profile create research

# 設定每個 Profile
coder setup
personal-bot setup
research setup

# 將每個 Gateway 安裝為託管服務
coder gateway install
personal-bot gateway install
research gateway install

# 全部啟動
coder gateway start
personal-bot gateway start
research gateway start

就這樣——三個獨立的 Agent，各自運行在自己的程序上，崩潰後會自動重啟，使用者登入時也會自動啟動。

一次性啟動、停止或重啟所有 Gateway

CLI 提供了單一 Profile 的生命週期管理命令。若要對所有 Profile 執行相同操作，可以用 shell 迴圈包裝。將以下腳本片段放入 ~/.local/bin/hermes-gateways 並執行 chmod +x：

#!/bin/sh
set -eu

# 根據實際情況新增或移除 Profile 名稱。
profiles="default coder personal-bot research"

usage() {
  echo "Usage: hermes-gateways {start|stop|restart|status|list}"
}

run_for_profile() {
  profile="$1"
  action="$2"
  if [ "$profile" = "default" ]; then
    hermes gateway "$action"
  else
    hermes -p "$profile" gateway "$action"
  fi
}

action="${1:-}"
case "$action" in
  start|stop|restart|status)
    for profile in $profiles; do
      echo "==> $action $profile"
      run_for_profile "$profile" "$action"
    done
    ;;
  list)
    hermes gateway list
    ;;
  *)
    usage
    exit 2
    ;;
esac

然後：

hermes-gateways start      # 啟動所有已設定的 Profile
hermes-gateways stop       # 停止所有已設定的 Profile
hermes-gateways restart    # 重啟所有 Profile
hermes-gateways status     # 查看所有 Profile 的狀態
hermes-gateways list       # 委託執行 `hermes gateway list`

提示

default Profile 的操作指令是 hermes gateway <action>（不需要 -p）， 而不是 hermes -p default gateway <action>。上述腳本已同時處理這兩種形式。

管理單一 Profile

每個 Profile 安裝後提供的快捷指令：

coder gateway run        # 前台執行（Ctrl-C 停止）
coder gateway start      # 啟動託管服務
coder gateway stop       # 停止託管服務
coder gateway restart    # 重啟
coder gateway status     # 查看狀態
coder gateway install    # 建立 LaunchAgent / systemd 單元
coder gateway uninstall  # 移除服務檔案

這些指令等同於 hermes -p coder gateway <action>——在 Profile 別名不在 PATH 中，或需要在腳本中動態指定 Profile 時相當實用。

服務檔案

每個 Profile 會安裝各自獨立的服務檔案，名稱各不相同，因此安裝不會互相衝突：

平台路徑
macOS~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist
Linux~/.config/systemd/user/hermes-gateway-<profile>.service

Default Profile 沿用歷史命名：ai.hermes.gateway.plist / hermes-gateway.service。

查看日誌

每個 Profile 的日誌寫入各自獨立的檔案：

# Default Profile
tail -f ~/.hermes/logs/gateway.log
tail -f ~/.hermes/logs/gateway.error.log

# 命名 Profile
tail -f ~/.hermes/profiles/<name>/logs/gateway.log
tail -f ~/.hermes/profiles/<name>/logs/gateway.error.log

同時串流查看所有 Profile 的日誌：

tail -f ~/.hermes/logs/gateway.log ~/.hermes/profiles/*/logs/gateway.log

CLI 也提供結構化日誌檢視器：

hermes logs -f                  # 追蹤 default profile
hermes -p coder logs -f         # 追蹤單一 profile
hermes logs --help              # 篩選條件、日誌等級、JSON 輸出

確認實際運行狀態

hermes profile list             # Profile 清單、模型、Gateway 狀態
hermes-gateways status          # 所有 Profile 的完整狀態
launchctl list | grep hermes    # macOS — PID 與標籤
systemctl --user list-units 'hermes-gateway-*'   # Linux — 服務單元

編輯設定檔

每個 Profile 的設定檔存放在自己的目錄中：

~/.hermes/profiles/<name>/
├── .env              # API 金鑰、bot token（chmod 600）
├── config.yaml       # 模型、供應商、工具組、Gateway 設定
└── SOUL.md           # 人格 / 系統提示詞

Default Profile 直接使用 ~/.hermes/ 目錄，包含相同的三個檔案。

可以使用任何編輯器或透過 CLI 進行修改：

hermes config set model.model anthropic/claude-sonnet-4    # default profile
coder config set model.model openai/gpt-5                  # named profile

編輯 .env 或 config.yaml 後，請重啟對應的 Gateway：

coder gateway restart
# 或者，重啟所有：
hermes-gateways restart

防止主機進入休眠

Gateway 程式可以全天候運行，但作業系統仍會在閒置時嘗試進入休眠。以下提供兩種方案：

macOS — caffeinate

caffeinate 是 macOS 內建的工具，可在運行期間阻止系統休眠，無需額外安裝。

caffeinate -dis                    # 阻止螢幕、閒置、系統休眠
caffeinate -dis -t 28800           # 同上，8 小時後自動退出
caffeinate -i -w $(cat ~/.hermes/gateway.pid) &   # 在 default gateway 運行期間保持喚醒

# 持久執行：背景運行後退出終端
nohup caffeinate -dis >/dev/null 2>&1 &
disown

# 檢查 / 停止
pmset -g assertions | grep -iE 'caffeinate|prevent|user is active'
pkill caffeinate
參數效果
-d阻止螢幕休眠
-i阻止閒置休眠（預設）
-m阻止磁碟休眠
-s阻止系統休眠（僅限接電的 Mac）
-u模擬使用者活動（防止螢幕鎖定）
-t NN 秒後自動退出
-w P當 PID P 結束時退出

警告 — 合上 MacBook 螢幕仍會進入休眠

caffeinate 無法覆蓋 MacBook 硬體層級的合蓋休眠機制。 若要在合蓋狀態下持續運作，請修改「節能」/「電池」偏好設定， 或使用第三方工具。

Linux — systemd-inhibit 或 loginctl

# 在指令執行期間抑制系統休眠
systemd-inhibit --what=idle:sleep --who=hermes --why="gateways running" \
  sleep infinity &

# 允許使用者服務在登出後持續運行（建議啟用）
sudo loginctl enable-linger "$USER"

啟用 lingering 後，你的 systemd 使用者服務單元（包括 hermes-gateway-<profile>.service）會在 SSH 斷線和重啟後持續運行。

Token 衝突防護

每個 Profile 在各平台上必須使用不同的 bot token。若兩個 Profile 共用了同一個 Telegram、Discord、Slack、WhatsApp 或 Signal 的 token，第二個 Gateway 會拒絕啟動，並顯示與衝突 Profile 相關的錯誤訊息。

若要檢查：

grep -H 'TELEGRAM_BOT_TOKEN\|DISCORD_BOT_TOKEN' \
     ~/.hermes/.env ~/.hermes/profiles/*/.env

更新程式碼

hermes update 會拉取最新程式碼，並將新的內建技能同步到所有 Profile：

hermes update
hermes-gateways restart

使用者自行修改的技能不會被覆蓋。

疑難排解

"Could not find service in domain for user gui: 501"

這是在執行 hermes gateway stop 之後又執行 hermes gateway start 時出現的錯誤。CLI 的 stop 指令會執行完整的 launchctl unload，將服務從 launchd 註冊表中移除。CLI 在執行 start 時會自動捕獲這個特定錯誤，並重新載入 plist（↻ launchd job was unloaded; reloading service definition）。服務會正常啟動，無需額外處理。

崩潰後殘留的 PID

若某個 Profile 的 Gateway 顯示 not running，但程序仍在運行：

ps -ef | grep "hermes_cli.*-p <profile>"
cat ~/.hermes/profiles/<profile>/gateway.pid
kill -TERM <pid>          # 優雅終止
kill -KILL <pid>          # 若幾秒後仍未結束，強制終止
<profile> gateway start

強制重置單一服務

# macOS
launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist
launchctl load   ~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist

# Linux
systemctl --user restart hermes-gateway-<profile>.service

健康檢查

hermes doctor                  # default profile
hermes -p <profile> doctor     # 單一 profile

Profile Distribution：分享整個 Agent

yuanbaoprofile distributions