<!-- Source: https://hermesbible.com/docs/user-guide/desktop -->

章節：使用 Hermes · URL: https://hermesbible.com/docs/user-guide/desktop

Hermes 桌面應用程式是一個原生應用程式，圍繞著與 CLI 和 gateway 相同的同一個 agent 打造——相同的設定、相同的 API 金鑰、相同的 session、相同的 skill、相同的記憶。它不是一個獨立的產品或精簡版的複製品；它使用與 Hermes Agent 核心相同的設定，並透過一個精心設計的現代化 UI 來操控它。如果你在終端機中使用過 hermes，你在那裡設定的一切在這裡都已經就緒，而你在這裡做的任何事也會出現在那裡。

它可在 macOS、Windows 和 Linux 上運行。

提示——哪個介面是什麼？

Hermes 有多個前端，它們都與同一個 agent 通訊：

• 桌面應用程式（本頁）——一個帶有專用 UI 的原生應用程式，用於聊天、設定和管理。
• CLI (hermes) 和 TUI (hermes --tui)——終端機介面。
• Web Dashboard (hermes dashboard)——瀏覽器管理面板；其可選的 Chat 分頁透過偽終端機嵌入了 TUI。

選擇適合當下的介面即可。它們共享狀態，所以你可以在一個介面開始一個 session，然後在另一個介面中繼續。

安裝

按照 Hermes Desktop 安裝說明 進行。

如果你已經安裝了 Hermes，只需執行

hermes desktop

這會使用你目前的設定、金鑰、session 和 skill。

應用程式中有哪些功能

桌面應用程式以聊天為中心的視窗組織，左側有一個導航側邊欄。它旨在允許管理多個同時進行的 agent 對話、設定訊息提供者、建立 artifact、瀏覽專案的資料夾結構，以及同時處理多個專案。

聊天

應用程式的核心。你會獲得：

• 串流回應，帶有即時的工具活動和結構化的工具呼叫摘要，當 agent 工作時會即時顯示。
• 與所有其他 Hermes 介面相同的對話歷史——在這裡開始的 session 可以在 CLI/TUI 中繼續，反之亦然。
• 拖放檔案到聊天區域的任何位置，將它們附加到你的下一則訊息中。
• 右側預覽面板——在你繼續聊天的同時，並排呈現網頁、檔案和工具輸出。
• 撰寫器歷史和佇列編輯——在空白的撰寫器中按上/下方向鍵來召回和重複使用先前的提示，並在訊息被傳送之前編輯你已排入佇列的訊息。

狀態列

聊天底部的狀態列顯示即時的 session 狀態，並在不需要開啟設定的情況下提供快速控制項：

• 逐 session 的 YOLO 切換——僅為此 session 開啟或關閉 YOLO（與 TUI 相符）。YOLO 會繞過危險命令的確認提示，所以要清楚你在關閉什麼——參見 安全 → YOLO 模式。

你是在與另一台機器上的 Hermes 實例聊天，而不是使用內建的本地後端？請參閱下面的連接到遠端後端，並了解遠端託管的 dashboard 連線運作的完整情況（驗證閘道、/api/ws 聊天 socket，以及 WebSocket 關閉代碼的處理），請參閱 Web Dashboard → 將 Hermes Desktop 連接到遠端後端。

選擇模型

模型選擇器位於撰寫器中，就在麥克風的左邊。點擊它即可從一個下拉式選單切換模型、推理 effort 和快速模式。

• 撰寫器選擇器是固定的 UI 狀態，永遠不會觸及你的預設值。它會在本地記憶（每個裝置），並且在新的聊天和重啟後跟隨你，而不是切回預設值——選擇一個模型一次，下一次 Cmd/Ctrl+N 就會使用它開啟。在進行中的聊天中切換模型會將變更限定在該當前聊天中；無論哪種方式，選擇會隨著 session 的建立/切換而一起傳遞，並且永遠不會寫入 profile 預設值。（切換 profile 會重新套用該 profile 自己的預設值。）
• 在 Settings → Model 中設定預設值。那個「主要」模型是你的逐 profile 全域預設值——它是新聊天、cron、subagent 和輔助任務的起點，也是唯一寫入它的地方。每個 profile 都有自己的預設值。
• **逐模型的 effort/快速預設。**每個模型在桌面應用程式中都會記住自己的推理 effort 和快速模式選擇，當你選擇該模型時會重新套用到 session。這些預設是桌面端的便利功能，不會影響 cron 或 subagent。

檔案瀏覽器

無需離開應用程式即可探索和預覽工作目錄——當 agent 讀取、寫入和編輯檔案時，這非常有用。使用 hermes desktop --cwd <path>（或 HERMES_DESKTOP_CWD 環境變數）設定初始專案目錄。

語音

與 Hermes 對話並聽到它的回覆，與其他地方可用的相同語音模式。在 macOS 上，作業系統會提示一次麥克風存取權限。

設定與引導

從真正的 UI 管理提供者、模型、工具和憑證，而不是編輯 YAML。首次執行引導讓你在幾秒內就能發送第一則訊息。設定面板涵蓋提供者/金鑰、模型選擇、工具集設定、MCP 伺服器、gateway 和 session 管理。

• 提供者設定面板——一個專門管理推理提供者的地方，具有帳戶/ API 金鑰的使用者體驗，用於登入和儲存每個提供者的憑證。
• 選單中的每個提供者和模型——GUI 呈現完整的提供者清單和 hermes model 所知的每個模型，讓你從 CLI 看到的相同目錄中選擇，而不是策劃過的子集。
• xAI Grok OAuth——Grok 在啟動器中是一等的 OAuth 提供者；透過瀏覽器流程登入，就像其他 OAuth 提供者一樣。
• 從 GUI 安裝工具後端——直接從應用程式執行工具後端的設定後安裝步驟，而不需要切換到終端機。
• 輔助模型警告——如果你在輔助任務（標題、摘要和類似的輔助工具）仍固定在另一個提供者時切換主要模型到新的提供者，應用程式會警告你，以免你不自覺地將工作分散在兩個提供者之間。

首次執行引導已經在統一的 overlay 設計系統上重新設計，你可以選擇稍後選擇提供者來跳過提供者設定，先進入應用程式。

管理面板

應用程式也呈現更廣泛的 Hermes 管理介面，讓你不需要切換到終端機：

• Skills——瀏覽、安裝和管理 skill。
• Cron——查看和管理排程任務。
• Profiles——在 Hermes profile 之間切換（獨立的設定/skill/session）。
• Messaging——設定 gateway 頻道。
• Agents 和 Command Center——多 agent 工作的協調介面。

鍵盤與導航

• 命令面板——按 Cmd+K（Windows/Linux 上為 Ctrl+K）跳轉到操作並使用鍵盤導航應用程式。
• 可重新綁定的快捷鍵——設定中的快捷鍵面板讓你可以將應用程式的鍵盤快捷鍵重新對應到你自己的按鍵。
• 自訂縮放快捷鍵——以半步增量縮放介面，更精細地控制文字大小。
• UI 語言切換器——在應用程式內切換應用程式的介面語言，包括簡體中文（zh-Hans）。

Sessions 與 Profiles

• Session 清單大改版——重新設計的 session 清單，支援歸檔和一般的 session 整理，讓清單在增長時保持可管理。
• 按 ID 搜尋 session——直接透過 ID 找到特定的 session。
• 並行多 profile session——同時在多個 profile 中執行 session，並使用跨 profile 的 @session 連結引用另一個 profile 中的 session。

更新

應用程式會在背景檢查更新，並在有更新時提供一鍵更新。

手動更新流程也適用於 GUI。

解除安裝

開啟 Settings → About → Danger zone 並選擇要移除多少：

• 僅解除安裝 Chat GUI——移除桌面應用程式及其資料；Hermes agent、你的設定和你的聊天記錄會保留。（與 hermes uninstall --gui 相同。）
• 解除安裝 GUI + agent，保留我的資料——移除應用程式和 agent，但保留設定、聊天記錄和 secret，以便未來重新安裝。（與 hermes uninstall 相同。）
• 解除安裝所有內容——移除應用程式、agent 和所有使用者資料。（與 hermes uninstall --full 相同。）

應用程式會關閉以完成工作（清理工作在退出後執行，以便它可以移除執行中的應用程式套件及其自己的 venv）。當沒有安裝本地 agent 時（例如，連接到遠端後端的僅 GUI「精簡」客戶端），移除 agent 的選項會自動隱藏。

你可以從終端機做同樣的事——hermes uninstall --gui 僅移除 GUI，或 hermes uninstall / hermes uninstall --full 也移除 agent。

注意

從原始碼簽出（hermes desktop 開發建置）執行 hermes uninstall --gui 也會移除工作區的 node_modules 和 apps/desktop/{dist,release} 建置輸出，因為這些是 GUI 建置的產物。它們可以透過 hermes desktop（或 npm install + 重新建置）恢復——但如果你正在積極開發桌面應用程式，預期之後需要重新安裝依賴項。

CLI 參考：hermes desktop

要透過 CLI 啟動，只需執行 hermes desktop。預設情況下，它會安裝工作區的 Node 依賴項，建置當前作業系統的未打包 Electron 應用程式，然後啟動該打包的產物。

運作方式

打包的應用程式只包含 Electron 外殼。首次啟動時，它會將 Hermes Agent 執行時安裝到 HERMES_HOME（~/.hermes，或 Windows 上的 %LOCALAPPDATA%\hermes）——與 CLI 安裝使用的佈局相同，這就是為什麼兩者可以互換。React 渲染器透過標準的 gateway API 與 hermes dashboard 後端通訊，並重用 agent 而不是重新實作它。安裝、後端解析和自動更新邏輯位於主要的 Electron 進程中。

連接到遠端後端

預設情況下，應用程式會啟動並管理自己的本地後端。你也可以將其指向運行在另一台機器上的 Hermes 後端——VPS、家庭伺服器，或在 Tailscale 後面的 Mini。

資訊——遠端後端是一個運行中的 hermes dashboard 進程

「遠端後端」是指在遠端機器上運行的 hermes dashboard 伺服器——這就是桌面應用程式連接到的進程。除非該 dashboard 實際啟動且可達，否則本節中的任何內容都不會運作。桌面應用程式不會為你啟動它；你（或 systemd 服務）在遠端主機上保持 hermes dashboard 運行，然後應用程式連接到它。如果你也使用訊息頻道（Telegram、Discord 等），gateway 是一個你獨立啟動的獨立長運行進程——請參閱設定步驟後的說明。

連接有兩部分：在後端，你使用驗證提供者保護 dashboard；在應用程式中，你輸入後端的 URL 並登入。將 dashboard 綁定到非迴地址會自動啟動其驗證閘道，你設定的提供者就是讓桌面應用程式通過的關鍵。

根據後端所在位置選擇提供者：

• OAuth（Nous Portal）——適用於任何超出你自己機器的可達位置。 登入會透過你的 Nous 帳戶進行驗證，所以這適用於 VPS、公開主機或任何遠端後端。使用 hermes dashboard register（或 Portal /local-dashboards 頁面）註冊 dashboard 以設定其 OAuth 客戶端，然後使用 Sign in with Nous Research 從應用程式登入。如果你運行自己的身分提供者，自託管的 OIDC 提供者運作方式相同。
• 使用者名稱/密碼——僅適用於本地/受信任網路。 當後端在同一個受信任的區域網上或僅透過 VPN 可達時（例如 Tailscale），這是最簡單的選項。它保護一個共享憑證，不需要外部身分提供者，所以不要用於暴露在公開網際網路上的 dashboard——在那種情況下請使用 OAuth。

本節其餘部分展示使用者名稱/密碼路徑，因為它是在受信任網路上最快啟動的方式；有關 OAuth 路徑，請參閱 Web Dashboard → 預設提供者：Nous Research。

在後端（遠端機器）

設定使用者名稱和密碼，然後啟動綁定到可達地址的 dashboard。憑證存放在 ~/.hermes/.env（secret 檔案，權限為 0600）：

# 1. 設定 dashboard 登入憑證。
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# 建議：一個穩定的簽署 secret，這樣 session 在重啟後仍能保留。
# 沒有的話，每次啟動都會產生隨機金鑰，你每次重啟都會被登出。
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. 啟動綁定到可達地址的 dashboard。非迴地址綁定
#    會啟動驗證閘道；使用者名稱/密碼提供者處理登入。
hermes dashboard --no-open --host 0.0.0.0 --port 9119

只要你想讓桌面應用程式能夠連接，就保持該 hermes dashboard 進程運行——如果它停止了，應用程式就無法再連接到後端。將它放在 systemd、tmux 或你選擇的進程管理器下運行，使其能在登出和重啟後存活。

另外，如果你依賴訊息頻道，請確保 gateway 在遠端主機上運行——dashboard 後端是桌面應用程式通訊的對象，但你的 Telegram/Discord/Slack gateway session 是一個獨立的進程，你需要自行啟動並保持運行。請參閱 Messaging 了解 gateway 設定。

不想以明文密碼形式儲存？改為設定 HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH 為 scrypt 雜湊值——使用 python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))" 計算。完整的設定介面（config.yaml 金鑰、每個環境變數、速率限制器）：Web Dashboard → Username/password 提供者。

以 systemd 服務運行 dashboard？為該單元加上 EnvironmentFile=%h/.hermes/.env，讓憑證在啟動時進入環境。

警告

dashboard 可以讀寫你的 .env（API 金鑰、secret）並執行 agent 命令。上面所示的使用者名稱/密碼設定適用於受信任的網路——永遠不要將密碼保護的 dashboard 直接暴露在公開網際網路上；將它放在 VPN 後面。Tailscale 是一個乾淨的選項：綁定到機器的 tailscale IP（--host <tailscale-ip>）並使用 http://<tailscale-ip>:9119 作為遠端 URL，這樣只有你的 tailnet 才能連接到它。要透過公開網際網路連接到後端，請改用 OAuth（Nous Portal） 提供者。

在應用程式中

Settings → Gateway → Remote gateway：

1. Remote URL——http://<backend-host>:9119（如果你在前面加上反向代理，像 /hermes 這樣的路徑前置也能運作）
2. Sign in——應用程式會偵測後端宣告的是哪個提供者並相應調整按鈕。對於使用者名稱/密碼後端，它會顯示一個 Sign in 按鈕，開啟一個憑證表單（輸入步驟 1 中的憑證）。對於 OAuth 後端，它會顯示 Sign in with <provider>（例如 Sign in with Nous Research），執行提供者的瀏覽器登入流程。無論哪種方式，應用程式最終都會對後端建立一個已驗證的 session。
3. Save and reconnect——將桌面外殼切換到遠端後端。Session 會自動刷新；當設定 HERMES_DESKTOP_BASIC_AUTH_SECRET 時，你會在重啟後保持登入狀態。

你也可以在啟動應用程式之前，透過 HERMES_DESKTOP_REMOTE_URL 環境變數設定後端 URL（它會覆蓋應用程式內的設定）；你仍然需要從 Gateway 設定面板登入。

注意——逐 profile 的遠端主機

遠端 gateway 主機是按 profile 設定的，所以每個 profile 都可以指向自己的遠端後端（或保持在本地）。切換 profile 就會切換應用程式連接到的遠端主機。

疑難排解

• 登入失敗，出現 401 / "Invalid credentials"——使用者名稱或密碼與後端的 HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD 不符。後端對於未知使用者和錯誤密碼返回相同的通用錯誤（沒有列舉介面），所以請仔細檢查兩者。使用 curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' 確認閘道已開啟——它應該報告 true 並包含 "basic"。
• 沒有 "Sign in" 按鈕——它要求輸入 session token——後端的使用者名稱/密碼提供者未啟用。/api/status 不會在 auth_providers 中列出 "basic"。確保 ~/.hermes/.env 中設定了使用者名稱和密碼（或密碼雜湊值），且 dashboard 進程確實載入了它們。
• 每次重啟都被登出——將 HERMES_DASHBOARD_BASIC_AUTH_SECRET 設定為穩定的值。沒有它的話，token 簽署金鑰每次啟動都會重新產生，導致所有 session 失效。
• 連線被拒 / 超時——後端綁定到 127.0.0.1（預設值）或防火牆/VPN 封鎖了該連接埠。綁定到 0.0.0.0 或 tailscale IP，並對你的受信任網路開放該連接埠。

有關從 web-dashboard 角度的相同設定，請參閱 Web Dashboard → 將 Hermes Desktop 連接到遠端後端；環境變數列在 環境變數 → Web Dashboard & Hermes Desktop 下。

疑難排解

啟動日誌位於 HERMES_HOME/logs/desktop.log（它包含後端輸出和最近的 Python 追蹤訊息）——如果應用程式報告啟動失敗，請先檢查它。你也可以從 CLI 追蹤它：

hermes logs gui -f

常見的重設：

# 強制執行全新的首次啟動設定（macOS/Linux）
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"

# 重建損壞的 Python venv（macOS/Linux）
rm -rf "$HOME/.hermes/hermes-agent/venv"

# 重設卡住的 macOS 麥克風提示
tccutil reset Microphone com.nousresearch.hermes

"Build desktop app" 卡在 Electron 下載

建置過程從 github.com/electron/electron/releases 下載 Electron 執行時（約 114 MB）。如果安裝程式在 Build desktop app 步驟卡住，且即時輸出重複顯示 retrying attempt=…，表示你的網路上 GitHub 被封鎖或被限流（防火牆、代理或區域限制）。

安裝程式會自動修復：在建置失敗時，它（1）清除損壞的快取 Electron zip 並重試，然後（2）如果仍然失敗且你尚未設定 ELECTRON_MIRROR，會再透過 npmmirror.com（事實上的 Electron 社群鏡像）重試一次。@electron/get 會對下載進行 SHASUM 檢查，但雜湊值來自同一個鏡像——這可以捕獲損壞或不完整的下載，但無法發現被入侵的鏡像。如果你不想信任第三方主機，請自行固定 ELECTRON_MIRROR（如下）；建置永遠不會覆蓋你已設定的值。

要選擇你自己的鏡像（例如企業/受信任的鏡像），在安裝前或手動重建時設定 ELECTRON_MIRROR——建置會遵循它而不會覆蓋：

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
  bash -c 'cd "$HOME/.hermes/hermes-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack'

手動清除損壞的快取 zip：

rm -f "$HOME/Library/Caches/electron"/electron-*.zip   # macOS
rm -f "$HOME/.cache/electron"/electron-*.zip            # Linux

從原始碼建置

如果你想修改應用程式本身，先從 repo 根目錄安裝一次工作區依賴項，然後從 apps/desktop 執行開發伺服器：

npm install          # 從 repo 根目錄——連結 apps/desktop、web、apps/shared
cd apps/desktop
npm run dev          # Vite 渲染器 + Electron，它會啟動 Python 後端

將應用程式指向特定的簽出版本，或與你真實設定隔離：

HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot   # 使用確定性延遲測試啟動 overlay

建置安裝程式：

npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # release/ 下的未打包應用程式（無安裝程式）

當相關憑證存在於環境中時（macOS 為 CSC_LINK / CSC_KEY_PASSWORD / APPLE_*，Windows 為 WIN_CSC_*），macOS/Windows 的簽署和公證會自動執行。

另請參閱

• CLI 指南——終端機介面
• TUI——桌面後端重用的現代化終端機 UI
• Web Dashboard——帶有嵌入式聊天分頁的瀏覽器管理面板
• 設定——桌面應用程式讀取和寫入的設定
• Windows（原生）——原生 Windows 安裝路徑

---

---

同時運行多個 Gateway