跳到主要內容

桌面應用

Hermes 桌面應用是一款原生應用，圍繞著你從 CLI 和網關獲得的同一個 Agent 構建——相同的配置、相同的 API 密鑰、相同的會話、相同的技能、相同的記憶。它不是一個獨立的產品或輕量級克隆；它使用相同的 Hermes Agent 核心和設置，並通過現代且經過深思熟慮設計的 UI 來驅動它。如果你在終端中使用過 hermes，那麼你在那裡設置的一切都已在此處可用，而你在此處執行的操作也會反映在那裡。

它支持 macOS、Windows 和 Linux。

哪個界面對應什麼？

Hermes 擁有多個前端，它們都與同一個 Agent 通信：

  • 桌面應用（本頁）—— 一款原生應用程序，擁有專為聊天、配置和管理打造的 UI。
  • CLI (hermes) 和 TUI (hermes --tui) —— 終端界面。
  • Web 儀表板 (hermes dashboard) —— 瀏覽器管理面板；其可選的 Chat 標籤頁通過偽終端嵌入 TUI。

選擇適合當下情境的那一個即可。它們共享狀態，因此你可以在一個界面中開始會話，然後在另一個界面中繼續。

安裝​

請遵循 Hermes Desktop 安裝說明。

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

hermes desktop

這將使用你當前的配置、密鑰、會話和技能。

應用內容​

桌面應用組織為一個以聊天為主的窗口，左側帶有用於導航的側邊欄。它旨在允許管理多個併發的 Agent 對話、配置消息提供商、創建工件、瀏覽項目的文件夾結構以及同時處理多個項目。

聊天​

應用的中心區域。你可以獲得：

  • 流式響應，在 Agent 工作時顯示實時的工具活動和結構化的工具調用摘要。
  • 與其他 Hermes 界面相同的對話歷史 —— 在此處開始的會話可以在 CLI/TUI 中恢復，反之亦然。
  • 拖放文件 到聊天區域的任何位置，將其附加到你的下一條消息中。
  • 右側預覽欄 —— 在繼續聊天的同時，並排渲染網頁、文件和工具輸出。
  • Composer 歷史和隊列編輯 —— 在空的 composer 中按上下箭頭鍵，可以回憶並複用之前的提示，並在發送前編輯已排隊等待發送的消息。

狀態欄​

聊天窗口底部的狀態欄顯示實時會話狀態，並提供快速控制選項，無需打開設置：

  • 內聯模型選擇器 —— 直接從狀態欄切換活動會話的模型。
  • 每會話 YOLO 開關 —— 僅為此會話開啟或關閉 YOLO（與 TUI 匹配）。YOLO 會繞過危險命令的批准提示，因此請清楚你關閉的是什麼 —— 參見 安全 → YOLO 模式。

是與另一臺機器上的 Hermes 實例聊天，而不是使用捆綁的本地後端？請參閱下方的 連接到遠程後端 —— 有關遠程託管儀表板連接工作原理的完整細節（認證關卡、/api/ws 聊天 socket 以及 WebSocket 關閉代碼分類），請參閱 Web 儀表板 → 將 Hermes Desktop 連接到遠程後端。

文件瀏覽器​

在不離開應用的情況下探索和預覽工作目錄 —— 這對於跟蹤 Agent 讀取、寫入和編輯文件的過程非常有用。使用 hermes desktop --cwd <path>（或 HERMES_DESKTOP_CWD 環境變量）設置初始項目目錄。

語音​

與 Hermes 交談並聽取其回覆，使用與其他地方相同的 語音模式。在 macOS 上，操作系統會提示一次麥克風訪問權限。

設置與入門引導​

通過真正的 UI 管理提供商、模型、工具和憑證，而無需編輯 YAML。首次運行的入門引導可讓你在幾秒鐘內發出第一條消息。設置面板涵蓋提供商/密鑰、模型選擇、工具集配置、MCP 服務器、網關和會話管理。

  • 提供商設置面板 —— 一個專門用於管理推理提供商的地方，具有用於登錄和存儲每個提供商憑證的賬戶/API 密鑰 UX。
  • 菜單中包含所有提供商和模型 —— GUI 展示了完整的提供商列表以及 hermes model 所知的所有模型，因此你可以從 CLI 看到的相同目錄中進行選擇，而不是一個精選的子集。
  • xAI Grok OAuth —— Grok 是啟動器中的一流 OAuth 提供商；像其他 OAuth 提供商一樣，通過瀏覽器流程登錄。
  • 從 GUI 安裝工具後端 —— 直接從應用中運行工具後端的安裝後設置步驟，而無需切換到終端。
  • 輔助模型警告 —— 如果在輔助任務（標題生成、摘要及類似助手）仍固定在其他提供商時，你將主模型切換到新提供商，應用會發出警告，以免你在不知情的情況下將工作分散到兩個提供商。

首次運行的入門引導已基於統一的覆蓋層設計系統重新設計，你可以選擇 稍後選擇提供商 以跳過提供商設置並優先進入應用。

管理面板​

該應用還展示了更廣泛的 Hermes 管理界面，因此你無需切換到終端：

  • Skills（技能） — 瀏覽、安裝和管理 skills。
  • Cron（定時任務） — 查看和管理 scheduled jobs。
  • Profiles（配置文件） — 在 Hermes profiles（隔離的配置/技能/會話）之間切換。
  • Messaging（消息） — 設置網關通道。
  • Agents（代理） 和 Command Center（指揮中心） — 用於多代理工作的編排界面。

鍵盤與導航​

  • 命令面板 — 按下 Cmd+K（Windows/Linux 上為 Ctrl+K）以跳轉到操作並通過鍵盤導航應用。
  • 可重新綁定的快捷鍵 — 設置中的快捷鍵面板允許你將應用的鍵盤快捷鍵重新映射到你自己的按鍵。
  • 自定義縮放快捷鍵 — 以半步增量縮放界面，從而更精細地控制文本大小。
  • UI 語言切換器 — 在應用內更改界面語言，包括簡體中文（zh-Hans）。

會話與配置文件​

  • 會話列表重構 — 經過重新設計的會話列表，支持歸檔和常規會話清理，以便在列表增長時保持其易於管理。
  • 按 ID 搜索會話 — 直接通過 ID 查找特定會話。
  • 併發多配置文件會話 — 同時在多個 profiles 中運行會話，並通過跨配置文件 @session 鏈接引用另一個配置文件中的會話。

更新​

應用在後臺檢查更新，並在準備好時提供一鍵更新。

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

卸載​

打開 Settings → About → Danger zone 並選擇要移除的內容：

  • 僅卸載 Chat GUI — 移除桌面應用及其數據；Hermes 代理、你的配置和你的聊天記錄保留。（等同於 hermes uninstall --gui。）
  • 卸載 GUI + 代理，保留我的數據 — 移除應用和代理，但保留配置、聊天記錄和密鑰以供將來重新安裝。（等同於 hermes uninstall。）
  • 卸載所有內容 — 移除應用、代理和所有用戶數據。（等同於 hermes uninstall --full。）

應用會關閉以完成操作（清理工作在退出後運行，以便它可以移除正在運行的應用包及其自身的 venv）。當未安裝本地代理時（例如，連接到遠程後端的僅 GUI “lite” 客戶端），移除代理的選項會自動隱藏。

你也可以從終端執行相同的操作 — 僅使用 hermes uninstall --gui 卸載 GUI，或使用 hermes uninstall / hermes uninstall --full 同時卸載代理。

備註

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

CLI 參考：hermes desktop​

要通過 CLI 啟動，只需運行 hermes desktop。默認情況下，它會安裝工作區 Node 依賴項，構建當前操作系統的未打包 Electron 應用，然後啟動該打包後的構件。

標誌描述
--skip-build跳過 npm install/package 並從 apps/desktop/release 啟動現有的未打包應用
--force-build即使內容戳記匹配，也強制完全重新構建
--build-only構建桌面應用但不啟動它（由 hermes update 使用）
--source針對 apps/desktop/dist 通過 electron . 啟動，而不是使用打包後的應用
--cwd PATH桌面聊天會話的初始項目目錄（設置 HERMES_DESKTOP_CWD）
--hermes-root PATH覆蓋應用使用的 Hermes 源根目錄（設置 HERMES_DESKTOP_HERMES_ROOT）
--ignore-existing強制應用在解析後端期間忽略 PATH 上已存在的任何 hermes CLI
--fake-boot啟用確定性啟動延遲以驗證啟動 UI

工作原理​

打包後的應用僅包含 Electron 外殼。在首次啟動時，它將 Hermes Agent 運行時安裝到 HERMES_HOME（~/.hermes，或在 Windows 上為 %LOCALAPPDATA%\hermes）— 這與 CLI 安裝的佈局相同，這就是為什麼兩者可以互換的原因。React 渲染器通過標準網關 API 與 hermes dashboard 後端通信，並複用代理而不是重新實現它。安裝、後端解析和自我更新邏輯位於 Electron 主進程中。

連接到遠程後端​

默認情況下，應用啟動並管理其自己的 本地 後端。你可以將其指向另一臺機器上運行的 Hermes 後端 — VPS、家庭服務器或 Tailscale 背後的 Mini。

遠程後端是一個正在運行的 hermes dashboard 進程

“遠程後端”指的是在遠程機器上運行的 hermes dashboard 服務器——即桌面應用程序所連接的進程。除非該儀表板實際處於運行狀態且可訪問，否則本節中的任何操作都無法生效。桌面應用程序不會為你啟動它；你需要（或通過 systemd 服務）在遠程主機上保持 hermes dashboard 運行，然後應用程序會連接到它。如果你還使用消息通道（Telegram、Discord 等），網關是一個獨立的長期運行進程，你需要單獨啟動它——請參閱設置步驟後的說明。

連接分為兩部分：在後端，你通過身份驗證提供者保護儀表板；在應用程序中，你輸入後端的 URL 並登錄。將儀表板綁定到非環回地址會自動啟用其身份驗證網關，而你配置的提供者正是允許桌面應用程序通過的關鍵。

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

  • OAuth（Nous Portal）——適用於任何超出本機範圍的可訪問場景的首選方案。 登錄信息會根據你的 Nous 賬戶進行驗證，因此這是適用於 VPS、公共主機或任何遠程後端的選項。使用 hermes dashboard register（或 Portal /local-dashboards 頁面）註冊儀表板以配置其 OAuth 客戶端，然後在應用程序中使用 Sign in with Nous Research 登錄。如果你運行自己的身份提供者，自託管的 OIDC 提供者也以相同方式工作。
  • 用戶名/密碼——僅限本地/受信任網絡使用。 當後端位於同一受信任的 LAN 或僅可通過 VPN（例如 Tailscale）訪問時，這是最簡單的選項。它保護單個共享憑據，無需外部身份提供者，因此不要將其用於暴露於公共互聯網的儀表板——在這種情況下請使用 OAuth。

本節的其餘部分展示了用戶名/密碼路徑，因為它是在受信任網絡上快速搭建的最快方法；有關 OAuth 路徑，請參閱 Web Dashboard → Default provider: Nous Research。

在後端（遠程機器上）​

設置用戶名和密碼，然後啟動綁定到可訪問地址的儀表板。憑據存儲在 ~/.hermes/.env（秘密文件，權限模式為 0600）中：

# 1. Set the dashboard login credentials.
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
# Without it a random key is generated per boot and you'll be logged out
# on every restart.
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. Run the dashboard bound to a reachable address. The non-loopback bind
#    engages the auth gate; the username/password provider handles login.
hermes dashboard --no-open --host 0.0.0.0 --port 9119

只要希望桌面應用程序能夠連接，就請保持該 hermes dashboard 進程運行——如果它停止，應用程序將無法再訪問後端。在 systemd、tmux 或你選擇的進程管理器下運行它，以便在註銷和重啟後仍能存活。

另外，如果你依賴消息通道，請確保網關在遠程主機上運行——桌面應用程序與儀表板後端通信，但你的 Telegram/Discord/Slack 網關會話是另一個你需要單獨啟動並保持運行的進程。有關網關設置，請參閱 Messaging。

不希望以明文形式存儲密碼？可以將 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 provider。

作為 systemd 服務運行儀表板？給單元添加 EnvironmentFile=%h/.hermes/.env，以便在啟動時將憑據加載到環境中。

注意

儀表板會讀取和寫入你的 .env（API 密鑰、秘密信息），並可以運行代理命令。上述用戶名/密碼設置適用於受信任的網絡——切勿將受密碼保護的儀表板直接暴露於開放互聯網；請將其置於 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），這將運行提供者的瀏覽器登錄流程。無論哪種方式，應用程序最終都會獲得針對後端的已認證會話。
  3. Save and reconnect — 將桌面 shell 切換到遠程後端。會話會自動刷新；當設置了 HERMES_DASHBOARD_BASIC_AUTH_SECRET 時，你在重啟後仍保持登錄狀態。

你也可以在啟動應用程序之前通過 HERMES_DESKTOP_REMOTE_URL 環境變量設置後端 URL，而無需使用 UI（它會覆蓋應用程序內的設置）；你仍然需要從 Gateway 設置面板登錄。

每個配置文件對應的遠程主機

遠程網關主機是按配置文件配置的，因此每個配置文件都可以指向其自己的遠程後端（或保留在本地後端上）。切換配置文件會切換應用程序連接的遠程主機。

故障排除​

  • 登錄失敗，返回 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"。
  • 沒有“登錄”按鈕 — 而是要求提供會話令牌 — 後端的用戶名/密碼提供者未激活。/api/status 不會在 auth_providers 中列出 "basic"。確保在 ~/.hermes/.env 中設置了用戶名和密碼（或密碼哈希），並且儀表板進程確實加載了它們。
  • 每次重啟都會退出登錄 — 將 HERMES_DASHBOARD_BASIC_AUTH_SECRET 設置為一個穩定的值。如果沒有該值，令牌簽名密鑰會在每次啟動時重新生成，從而使所有會話失效。
  • 連接被拒絕 / 超時 — 後端綁定到了 127.0.0.1（默認值），或者防火牆/VPN 阻止了端口。綁定到 0.0.0.0 或 Tailscale IP，並向受信任的網絡開放端口。

有關從 Web 儀表板角度進行的相同設置，請參閱 Web 儀表板 → 將 Hermes Desktop 連接到遠程後端；環境變量收錄在 環境變量 → Web 儀表板和 Hermes Desktop 下。

故障排除​

啟動日誌位於 HERMES_HOME/logs/desktop.log（包括後端輸出和最近的 Python 回溯信息）— 如果應用程序報告啟動失敗，請首先檢查此文件。你也可以從 CLI 實時跟蹤日誌：

hermes logs gui -f

常見重置操作：

# Force a clean first-launch setup (macOS/Linux)
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"

# Rebuild a broken Python venv (macOS/Linux)
rm -rf "$HOME/.hermes/hermes-agent/venv"

# Reset a stuck macOS microphone prompt
tccutil reset Microphone com.nousresearch.hermes

“構建桌面應用程序”卡在 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

從源代碼構建​

如果你想修改應用程序本身，請從倉庫根目錄一次性安裝工作區依賴項，然後從 apps/desktop 運行開發服務器：

npm install          # from repo root — links apps/desktop, web, apps/shared
cd apps/desktop
npm run dev          # Vite renderer + Electron, which boots the Python backend

將應用程序指向特定的檢出版本，或將其與你的真實配置隔離：

HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot   # exercise the startup overlay with deterministic delays

構建安裝程序：

npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # unpacked app under release/ (no installer)

當環境中存在相關憑據時（macOS 使用 CSC_LINK / CSC_KEY_PASSWORD / APPLE_*，Windows 使用 WIN_CSC_*），macOS/Windows 的簽名和公證會自動運行。

另見​