Telegram 私人機器人方便連到 VPS 上的代理，但閘道已連線不代表指定的人能收到回覆。本指南從全新 Hermes Agent 資料目錄開始，允許一個 Telegram 數字 ID，檢查實際回答，並留下經確認的停止控制。它依據 NousResearch 的 v0.22.2 Docker 說明與Telegram 說明，於 2026 年 10 月 19 日核查。BIG CHANGE 未為本指南執行 VPS、拉取映像、建立機器人或呼叫模型。

關鍵改變

  • 改變了什麼： 以摘要固定且核查版本的 Docker 映像，搭配專用的 /opt/data 掛載，可辨識這一個閘道的軟體及狀態。
  • 為何重要： Telegram 數字 ID 允許清單與實際私訊回覆，可確認指定帳戶能否使用閘道。
  • 需要留意： 配對或全域授權可能擴大存取，無害提示不限制代理工具。請檢查授權、日誌、重啟及停止狀態。

你須有權以 SSH 管理一台 Linux VPS，有可用的 Docker Engine 與主機復原存取、可透過 BotFather 建立機器人的 Telegram 帳戶，以及符合 Hermes 模型提供者條件的帳戶。核對主機架構、資源與官方 amd64 或 arm64 映像，使用精靈前查看提供者目前存取及計費條件。本指南假設 Docker 已可運作；安裝與防火牆變更依系統及服務商而定。主機須能對外連到 Telegram 及模型提供者。保留私人目錄儲存 Hermes 狀態並限制誰能讀取：/opt/data 將存放憑證、工作階段及日誌。Docker 手冊把此掛載稱為持續保存的權威資料來源。

1. 設定前固定映像

透過 SSH 連線，以下命令留在同一個 shell 執行。stable 標籤可能移動。拉取映像、記錄儲存庫摘要，並確認映像本身回報版本為 0.22.2。版本不同、摘要缺少、目錄已有狀態，或名為 hermes 的容器已存在就停止。繼續前依實際版本更新說明，或取得有文件依據的對應映像。摘要固定要執行的映像，不能單獨證明發行版本。

Terminal
set -eu
docker info >/dev/null
docker container inspect hermes >/dev/null 2>&1 && { echo 'Container hermes already exists; stop here.'; exit 1; }
HERMES_DATA="$HOME/.hermes"
if [ -e "$HERMES_DATA" ]; then echo 'Hermes data path already exists; stop here.'; exit 1; fi
mkdir -m 700 "$HERMES_DATA"
docker pull nousresearch/hermes-agent:stable
docker image inspect nousresearch/hermes-agent:stable --format '{{json .RepoDigests}}'
IMAGE_REF="$(docker image inspect nousresearch/hermes-agent:stable --format '{{index .RepoDigests 0}}')"
if ! printf '%s\n' "$IMAGE_REF" | grep -Eq '^nousresearch/hermes-agent@sha256:[0-9a-f]{64}$'; then
  echo 'No valid repository digest; stop here.'; exit 1
fi
printf 'Pinned image: %s\n' "$IMAGE_REF"
VERSION_OUTPUT="$(docker run --rm "$IMAGE_REF" --version)"
printf 'Image version: %s\n' "$VERSION_OUTPUT"
if ! printf '%s\n' "$VERSION_OUTPUT" | grep -Eq '(^|[^0-9])v?0[.]22[.]2([^0-9]|$)'; then
  echo 'Image version is not 0.22.2; stop here.'; exit 1
fi

set -eu 會在 Docker 不可用、拉取或檢查失敗、版本命令失敗時停止這串 shell 操作。明確的摘要及版本檢查也會攔下空摘要或其他版本。遇到這些結果不要繼續設定。保留記錄的 nousresearch/hermes-agent@sha256:… 值。以下設定與閘道都用 IMAGE_REF，之後標籤改變就不會悄悄換掉容器。讀者須在實際 VPS 檢查；本文無已驗證映像摘要。使用主機原生檔案系統的新專用目錄，絕不可讓兩個閘道容器同用一個資料目錄。

2. 設定提供者與一名私訊傳送者

使用已掛載目錄執行Docker 設定精靈。選帳戶允許的模型路徑，完成驗證並查看產生的提供者與模型設定。存取和費用依帳戶而異；已存設定不證明模型請求成功。

Terminal
docker run -it --rm -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" setup

在 Telegram 向 @BotFather 透過 /newbot 申請機器人，將權杖保密。取得指定傳送者的Telegram 數字使用者 ID，例如使用Telegram 手冊連結的 ID 查核方法；使用者名稱不是 ID。精靈或 hermes gateway setup 可寫入機器人權杖及允許清單。手動設定時將 TELEGRAM_BOT_TOKEN=<private token>與TELEGRAM_ALLOWED_USERS=<your numeric ID> 放進 $HERMES_DATA/.env，容器內顯示為 /opt/data/.env。不要把權杖放進命令、shell 歷史、共用筆記或本文。

在 $HERMES_DATA/config.yaml (/opt/data/config.yaml，容器內路徑）設定全域未授權私訊行為：

YAML
unauthorized_dm_behavior: ignore

設定容器結束後，官方映像可能將 $HERMES_DATA 的擁有者改為執行 UID 10000。啟動程序將 .env 限為模式 600，並把已有的 config.yaml 收緊為 640；該次啟動首次建立的設定也可能需要相同收緊。一般 SSH 登入者可能因此無法開檔。精靈未設必要鍵時，獲授權的主機管理員 可用 sudo 查看並編輯這兩個指定檔案，再恢復執行擁有權與私人權限。以 UID 10000 執行主機編輯器可能無法穿過登入使用者擁有的 $HOME，因此此命令使用主機管理權限。在具備 sudo與vi 的主機上，先確認不含秘密的擁有者及模式讀回，再使用命令。UID 不同或檔案缺少不要繼續，先解決主機特定存取問題。

Terminal
sudo stat -c '%u:%g %a %n' "$HERMES_DATA" "$HERMES_DATA/.env" "$HERMES_DATA/config.yaml"
# Expected: directory owner 10000 and mode 700; .env owner 10000 and mode 600.
# config.yaml should have owner 10000; its first-boot mode can vary.
sudo vi "$HERMES_DATA/.env"
sudo vi "$HERMES_DATA/config.yaml"
sudo chown 10000:10000 "$HERMES_DATA/.env" "$HERMES_DATA/config.yaml"
sudo chmod 700 "$HERMES_DATA"
sudo chmod 600 "$HERMES_DATA/.env"
sudo chmod 640 "$HERMES_DATA/config.yaml"
sudo stat -c '%u:%g %a %n' "$HERMES_DATA" "$HERMES_DATA/.env" "$HERMES_DATA/config.yaml"

最後的 stat 輸出應顯示兩檔 UID/GID 都是 10000，目錄模式 700, .env 模式 600與config.yaml 模式 640；只顯示中繼資料，不顯示憑證。chown 僅針對兩個檔案，含編輯器建立的替換檔。若沒有 sudo或vi，使用主機獲准的管理程序，進行同樣的擁有者及模式讀回。勿將狀態目錄改為所有人可讀，也勿為此流程重新映射容器使用者。

編輯時保留精靈的提供者設定。確保 Telegram 專屬的 unauthorized_dm_behavior 覆寫未設為 pair，全域的 GATEWAY_ALLOWED_USERS或GATEWAY_ALLOW_ALL_USERS 亦未授予更廣存取。在 config.yaml 裡，也確認 gateway.allow_all_users 和頂層的 allow_all_users 都不為 true，且全域或 Telegram 允許清單沒有額外傳送者。不要在清單用 *、新增群組清單或批准配對碼。全新目錄避免沿用授權；已有資料就停下檢查，別覆寫。保持 BotFather 群組隱私啟用，不將機器人加入群組或設為管理員。閘道存取手冊把允許清單與持續配對授權列為不同存取路徑。安全手冊說明 ignore 會靜默丟棄未授權私訊。

允許清單控制誰能開啟對話，不限制獲授權代理能做什麼。Hermes Telegram 工作階段預設有終端工具；允許傳送者前查看工具權限、Docker 掛載、提供者存取與主機政策。無害測試提示僅是測試，不是權限界線。

3. 啟動閘道並檢查首次回覆

由已記錄摘要啟動一個具名容器。公布的 Docker 命令含可選的 -p 8642:8642 供 API 存取；此處省略，因為 Telegram 私訊不需公開 API 或儀表板連接埠。映像監督閘道程序，Docker 的 unless-stopped 策略則控制 Docker 啟動時重啟容器。掛載目錄會在重啟後保留設定與工作階段。

Terminal
docker run -d --name hermes --restart unless-stopped \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" gateway run
if ! {
  docker inspect hermes --format '{{.Image}} {{.State.Status}}' &&
  [ "$(docker inspect hermes --format '{{.State.Status}}')" = running ] &&
  docker logs --tail 50 hermes &&
  docker exec -u hermes hermes hermes pairing list
}; then
  echo 'State, logs or pairing check failed; stopping before any message.'
  docker stop hermes || true
  docker inspect hermes --format '{{.State.Status}}' || true
  exit 1
fi

確認容器為 running，查看日誌的 Telegram 連線及提供者錯誤，發提示前先查配對清單。任何初始讀取失敗時，程式碼會停止閘道並列出狀態；CLI 或授權結果不明不等於允許。進一步查核前確認 exited，不確定時不要傳訊或重啟。不應有其他核准傳送者；若有，停止閘道並確認停止狀態。docker exec 不能對停止的容器執行，一般映像進入點可能恢復先前執行的閘道。全新且使用預設 UID 的安裝中，下方離線檢查只以 UID 10000 執行固定的 Hermes CLI，停用網路並略過閘道啟動。這是依文件配對命令與進入點改編，BIG CHANGE 未實測。只有確認執行中閘道 UID 和掛載資料擁有者都為 10000 才使用。擁有權、UID、CLI 輸出或授權不明時保持停止，釐清後才能重啟。

Terminal
if [ "$(docker exec -u hermes hermes id -u)" != 10000 ] || [ "$(stat -c %u "$HERMES_DATA")" != 10000 ]; then
  echo 'Runtime UID or data owner differs; stop for a host-specific repair.'; docker stop hermes; exit 1
fi
docker stop hermes
if [ "$(docker inspect hermes --format '{{.State.Status}}')" != exited ]; then
  echo 'Container is not exited; do not mount state in another container.'; exit 1
fi
docker run --rm --network none --user 10000:10000 \
  --entrypoint /opt/hermes/.venv/bin/hermes \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" pairing list
# For a listed unwanted Telegram user, read the exact numeric ID first:
printf 'Unwanted numeric Telegram user ID: '; IFS= read -r UNWANTED_ID
if ! printf '%s\n' "$UNWANTED_ID" | grep -Eq '^[0-9]+$'; then echo 'Invalid ID; leave gateway stopped.'; exit 1; fi
docker run --rm --network none --user 10000:10000 \
  --entrypoint /opt/hermes/.venv/bin/hermes \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" pairing revoke telegram "$UNWANTED_ID"
docker run --rm --network none --user 10000:10000 \
  --entrypoint /opt/hermes/.venv/bin/hermes \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" pairing list

確認最後清單不含不要的 ID。私下檢查 $HERMES_DATA/.env與config.yaml 中其他平台及全域允許清單、* 或全部允許設定，透過文件設定流程撤除多餘授權。所有路徑檢查前保持閘道停止。移除清單一項不會撤銷獨立配對或全域授權。讀回完成後，docker start hermes 會有意恢復原容器；傳訊前再查日誌及配對。

由獲准帳戶開啟與機器人的私人對話，發一個無害要求，例如「用簡短問候回覆」。確認對話中實際回答，查看相應日誌或工作階段記錄。已傳送、輸入中、狀態畫面或設定完成都不是回答。Telegram 的 /whoami 可顯示目前訊息範圍，不代表主機授權。僅保存非敏感檢查證據。

沒有回答時，先讀取容器狀態與 docker logs --tail 50 hermes。檢查權杖、正確數字 TELEGRAM_ALLOWED_USERS 值、模型提供者驗證及用量資格、對外連線。該輪結果不明時先看私訊與日誌，再決定傳下一則。文件所述冷啟動可能丟棄待處理更新，去重僅在有限記憶體內生效；此路徑不保證恰好一次送達。

4. 檢查重啟、停止與復原

首輪結束後重啟同一容器，檢查新日誌及保留的 /opt/data 狀態，再發一個新的無害私人提示並確認回答。停止容器，讀 Docker 狀態。exited 才是停止訊號，對話安靜不等於停止。docker start hermes 是稍後刻意恢復的方法。

Terminal
docker restart hermes
docker logs --tail 50 hermes
docker inspect hermes --format '{{.State.Status}}'
# After the restarted gateway is ready, send a new private test message.
docker stop hermes
docker inspect hermes --format '{{.State.Status}}'
# Expected after stop: exited
# When intentionally resuming later: docker start hermes

重啟失敗時看 Docker 狀態、日誌，再查 $HERMES_DATA/logs/gateways/default/current與$HERMES_DATA/logs/container-boot.log、目錄掛載、擁有權、固定映像與版本。v0.22.2 版本說明描述閘道啟動存活修復，無法證明你主機上發生什麼。勿刪資料目錄作修復。權杖外洩時停止閘道、在 BotFather 撤銷，私下替換掛載的 .env 內權杖，重啟前再查存取。也撤銷不需要的配對授權並查看有效清單。

VPS 主機與模型可能分別收費。確認實際方案、限制與費用；未承諾執行時間、免費模型額度或可用性目標。Telegram 及模型提供者會處理訊息，主機掛載目錄保留本機秘密與對話狀態。這只是一台主機、一個機器人的首次回覆檢查。其他 BIG CHANGE 指南涵蓋Hermes 備份與復原與Hermes 定期工作.

來源與延伸閱讀

以下Docker 設定, Telegram 設定, 閘道存取指南, 安全指南與v0.22.2 版本皆為 NousResearch 第一方來源。快速入門說明模型提供者設定。連結記載程序，不是 BIG CHANGE 執行 VPS 或 Telegram 機器人的紀錄。