installation — The Hermes Bible

在兩分鐘內讓 Hermes Agent 啟動並運行！

快速安裝

使用 Hermes Desktop 安裝器（macOS 或 Windows）（建議）

要輕鬆安裝命令列和桌面應用程式，請從我們的網站下載 Hermes Desktop 安裝器並執行它。

不使用 Hermes Desktop：

若要僅透過命令列安裝（不使用 Hermes Desktop），請執行：

Linux / macOS / WSL2 / Android (Termux)

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (原生)

在 powershell 中執行：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

如果你想在僅命令列安裝後再安裝並執行 Hermes Desktop，只需執行

hermes desktop

安裝器做了什麼

安裝器會自動處理所有事情——所有相依性（Python、Node.js、ripgrep、ffmpeg）、儲存庫複製、虛擬環境、全域 hermes 指令設定，以及 LLM 供應商設定。完成後，你就可以開始聊天了。

安裝佈局

安裝器將檔案放置的位置取決於你是以一般使用者還是 root 身分安裝：

安裝方式	程式碼位置	`hermes` 二進位檔	資料目錄
pip install	Python site-packages	`~/.local/bin/hermes` (console_scripts)	`~/.hermes/`
單一使用者（git 安裝器）	`~/.hermes/hermes-agent/`	`~/.local/bin/hermes` (符號連結)	`~/.hermes/`
Root 模式 (`sudo curl … \| sudo bash`)	`/usr/local/lib/hermes-agent/`	`/usr/local/bin/hermes`	`/root/.hermes/` (或 `$HERMES_HOME`)

Root 模式的 FHS 佈局（/usr/local/lib/…、/usr/local/bin/hermes）與 Linux 上其他全域開發工具的安裝位置一致。這適用於共享機器的部署場景，其中一次系統安裝可以服務所有使用者。個別使用者設定（驗證、技能、工作階段）仍然位於每個使用者的 ~/.hermes/ 或明確指定的 HERMES_HOME 下。

安裝完成後

重新載入你的 shell 開始聊天：

source ~/.bashrc   # 或：source ~/.zshrc
hermes             # 開始聊天！

要之後重新設定個別設定，請使用專用指令：

hermes model          # 選擇你的 LLM 供應商和模型
hermes tools          # 設定啟用哪些工具
hermes gateway setup  # 設定訊息平台
hermes config set     # 設定個別設定值
hermes setup          # 或執行完整的設定精靈一次設定所有項目

提示——最快路徑：Nous Portal

一個訂閱即可涵蓋 300 多個模型以及 Tool Gateway（網路搜尋、圖片生成、TTS、雲端瀏覽器）。無需逐個工具管理金鑰：
hermes setup --portal
這會在一個指令中完成登入、將 Nous 設為你的供應商，並啟用 Tool Gateway。

前置需求

安裝器： 在非 Windows 平台上，唯一的前置需求是 Git。安裝器會自動處理所有其他內容：

uv（快速 Python 套件管理器）
Python 3.11（透過 uv，無需 sudo）
Node.js v22（用於瀏覽器自動化和 WhatsApp 橋接）
ripgrep（快速檔案搜尋）
ffmpeg（用於 TTS 的音訊格式轉換）

資訊

你不需要手動安裝 Python、Node.js、ripgrep 或 ffmpeg。安裝器會偵測缺少的項目並為你安裝。只需確保 git 可用（git --version）。

提示——Nix 使用者

如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有一個專用的設定路徑，包含 Nix flake、宣告式 NixOS 模組和可選的容器模式。請參閱 Nix & NixOS 設定 指南。

手動 / 開發者安裝

如果你想複製儲存庫並從原始碼安裝——為了貢獻、從特定分支執行、或完全控制虛擬環境——請參閱貢獻指南中的開發環境設定章節。

無需 sudo / 系統服務使用者安裝

支援以專用的無權限使用者執行 Hermes（例如 hermes systemd 服務帳號，或任何沒有 sudo 存取權限的使用者）。安裝路徑中唯一真正需要 root 權限的是 Playwright 的 --with-deps 步驟，它透過 apt 安裝 Chromium 使用的共用函式庫（libnss3、libxkbcommon 等）。安裝器會偵測 sudo 是否可用，並在不可用時優雅降級——它會將 Chromium 二進位檔安裝到服務使用者自己的 Playwright 快取中，並印出管理員需要單獨執行的確切指令。

建議的分割方式（Debian/Ubuntu）：

一次，使用有 sudo 權限的管理員使用者，安裝 Chromium 需要的系統函式庫：
```
sudo npx playwright install-deps chromium
```
（你可以從任何地方執行這個指令——npx 會即時取得 Playwright。）
使用無權限的服務使用者，執行一般安裝器。它會偵測到缺少的 sudo、跳過 --with-deps，並將 Chromium 安裝到使用者的本地 Playwright 快取：
```
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
如果你想完全跳過 Playwright 步驟——例如因為你在無頭環境中執行且不需要瀏覽器自動化——請傳入 --skip-browser：
```
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
```
**讓 hermes 在服務使用者的 shell 中可用。**安裝器將啟動器寫入 ~/.local/bin/hermes。系統服務帳號通常有最小的 PATH，不包含 ~/.local/bin。你可以將其加入使用者的環境，或將啟動器符號連結到系統位置：
```
# 選項 A — 加入服務使用者的設定檔
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# 選項 B — 全域符號連結（以管理員身分執行）
sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes
```
驗證：hermes doctor 現在應該可以正常執行。如果你遇到 ModuleNotFoundError: No module named 'dotenv'，表示你正在使用系統 Python 執行儲存庫原始碼的 hermes 檔案（~/.hermes/hermes-agent/hermes）而非虛擬環境啟動器（~/.hermes/hermes-agent/venv/bin/hermes）——請修正步驟 3。

相同的模式在 Arch（安裝器使用 pacman 並有相同的 sudo 偵測邏輯）、Fedora/RHEL 和 openSUSE 上也能運作——這些發行版不支援 --with-deps，所以管理員需要單獨安裝系統函式庫。相關的 dnf/zypper 指令會由安裝器印出。

疑難排解

問題	解決方案
`hermes: command not found`	重新載入你的 shell（`source ~/.bashrc`）或檢查 PATH
`API key not set`	執行 `hermes model` 設定你的供應商，或 `hermes config set OPENROUTER_API_KEY your_key`
更新後設定遺失	執行 `hermes config check` 然後 `hermes config migrate`

如需更多診斷資訊，請執行 hermes doctor——它會告訴你確切缺少了什麼以及如何修復。

安裝方法自動偵測

Hermes 會自動偵測它是透過 pip、git 安裝器、Homebrew 還是 NixOS 安裝的，而 hermes update 會印出與該路徑對應的更新指令。不需要設定環境變數——偵測是基於安裝佈局（Python site-packages、~/.hermes/hermes-agent/、Homebrew 前綴或 Nix store 路徑）。hermes doctor 也會在環境摘要中顯示偵測到的方法。