---
title: "安裝 Hermes Agent"
description: "用官方安裝路徑在 Linux、macOS、WSL2、原生 Windows（早期測試）或 Termux 上安裝 Hermes Agent，並完成 PATH、目錄、依賴和排障驗收。"
verifiedAt: "2026-05-09"
---

Hermes Agent 的安裝本身不復雜。真正容易出錯的是：指令碼跑完後 shell 找不到 `hermes` 命令、provider（推理服務商）沒配置、`~/.hermes/` 這個配置目錄看不懂、Termux 或 WSL2 環境誤用、或者一上來就接 Gateway（訊息閘道器）和 cron（定時任務）導致問題疊在一起沒法定位。

官方資料：[Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)、[Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)、[GitHub README](https://github.com/NousResearch/hermes-agent)。

> [!NOTE]
> **先給結論**：先用官方一行安裝指令碼；POSIX 系（Linux / macOS / WSL2 / Termux）跑 `install.sh`，原生 Windows 跑 PowerShell `install.ps1`（早期測試，比 WSL2 路徑粗糙）。安裝後先確認 `hermes --help`、`hermes model` 和 `~/.hermes/`，不要馬上接訊息平臺和 cron。

## 支援環境

官方安裝指令碼現在覆蓋五類環境：

| 環境 | 指令碼 | 狀態 |
| --- | --- | --- |
| Linux | `install.sh`（一行 curl） | 主路徑，最穩定 |
| macOS | `install.sh` | 主路徑 |
| Windows via WSL2 | 在 WSL2 裡跑 `install.sh` | **Windows 推薦路徑**——比原生 Windows 經過更多驗證 |
| 原生 Windows（PowerShell） | `install.ps1`（一行 PowerShell） | **Early Beta** ⚠️ —— 裝得上、跑得通主流程，但還沒經過 POSIX 那麼廣的實戰，遇到坑請回報 |
| Android via Termux | `install.sh`（自動檢測 Termux） | 主路徑，安裝器自動切換到 Android 流程 |

> [!TIP]
> **Windows 怎麼選**：日常工作或團隊部署用 **WSL2 + `install.sh`**——穩定且能複用所有 Linux 資料；只想在原生 Windows 上快速試一下、不在意細節問題，可以試 `install.ps1`。兩者資料互不衝突（原生資料在 `%LOCALAPPDATA%\hermes`，WSL 資料在 `~/.hermes`）。

Termux（Android 終端模擬器）走同一個 `install.sh`，但安裝器會自動檢測並切換到 Android 專用流程：用 Termux `pkg` 裝系統依賴（`git`、`python`、`nodejs`、`ripgrep`、`ffmpeg`），用 `python -m venv` 建立虛擬環境，自動設 `ANDROID_API_LEVEL` 讓 Python wheel（預編譯包）能正確構建，並裝精簡的 `.[termux]` extra。瀏覽器和 WhatsApp bootstrap（啟動）這類不穩定能力預設不啟用。

## 一行安裝

POSIX 系（Linux、macOS、WSL2、Termux）執行：

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

原生 Windows 開啟 PowerShell（早期測試，遇坑可切 WSL2）：

```powershell
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
```

安裝前只需要先確認 `git` 可用：

```bash
git --version
```

官方安裝器會自動處理常見依賴：`uv`（Python 包管理器）、Python、Node.js、`ripgrep`（高速正則搜尋）、`ffmpeg`（音影片處理）等（具體版本號按官方 [Installation 頁](https://hermes-agent.nousresearch.com/docs/getting-started/installation) 當前要求為準，避免在教程裡寫死）。**不要**在安裝前手動混裝一堆 Python / Node 環境——先讓安裝器走完，再按報錯補缺口；提前裝的版本反而容易和安裝器期望版本衝突。

## 安裝器會做什麼

安裝器主要完成五件事：

1. 檢查系統和依賴。
2. 複製 Hermes Agent 儲存庫。
3. 建立 Python virtualenv（虛擬環境，把 Hermes 的依賴和系統 Python 隔離）。
4. 註冊全域性 `hermes` 命令（在 `~/.local/bin/` 下放一個 symlink 指向真正的入口指令碼）。
5. 引導你進入 LLM provider（推理服務商）配置——填 OpenAI / Anthropic / Nous Portal 等家的 API key 或 OAuth 憑據。

安裝成功的標準不是「指令碼沒有紅字」，而是 `hermes` 命令能被當前 shell 找到，並能進入幫助或模型配置。指令碼跑通了 ≠ 裝好了——下一節驗收命令入口才是真的標準。

## 安裝目錄

POSIX 系普通使用者安裝後，先記住這三個位置：

```text
~/.hermes/hermes-agent/    Hermes Agent 源码（仓库本体 + virtualenv）
~/.local/bin/hermes        全局命令入口，通常是指向源码内启动脚本的 symlink
~/.hermes/                 配置、auth、skills、sessions、memory、logs（用户数据，可备份）
```

如果用 root-mode（`sudo curl ... | sudo bash`）做系統級安裝，官方路徑會變成類似：

```text
/usr/local/lib/hermes-agent/    系统级源码位置（FHS 标准）
/usr/local/bin/hermes           系统级命令入口
/root/.hermes/ 或 HERMES_HOME   root 用户数据目录
```

原生 Windows 安裝路徑不同：原始碼放在 `%LOCALAPPDATA%\hermes\hermes-agent`，自帶的 portable Git 放在 `%LOCALAPPDATA%\hermes\git`，`hermes` 加進**使用者級 PATH**（不是系統級，不要 admin），資料在 `%LOCALAPPDATA%\hermes`。**裝完一定要重啟終端**或開新 PowerShell 視窗，PATH 才會生效。

個人學習和單使用者機器優先用普通使用者安裝。共享伺服器或統一運維場景才考慮 root-mode，並且要單獨規劃每個使用者的 `HERMES_HOME` 環境變數和金鑰邊界——不要讓所有使用者共享一份 `~/.hermes/` 資料。

## 安裝後第一步

POSIX 系安裝完成後先**過載 shell**，讓新加進 PATH 的 `hermes` 命令在當前終端生效。bash 使用者：

```bash
source ~/.bashrc
```

zsh 使用者：

```bash
source ~/.zshrc
```

> [!TIP]
> 不確定自己用的是哪個 shell？執行 `echo $SHELL`。看到 `/bin/zsh` 就用 `.zshrc`，看到 `/bin/bash` 就用 `.bashrc`——**改錯檔案是 `command not found` 最常見的原因**：明明是 zsh 使用者，卻只過載了 `.bashrc`。

原生 Windows 使用者**關掉當前 PowerShell 視窗、開個新視窗**，或在當前視窗執行 `$env:Path` 看 `%LOCALAPPDATA%\hermes` 是否在裡面。

然後驗收命令入口：

```bash
hermes --help
hermes model
```

`hermes --help` 能輸出幫助，說明 PATH 基本沒問題。`hermes model` 能進入互動配置，說明下一步可以配置 provider。

## 不要一開始全開功能

第一次安裝後的順序應該是：

```text
install -> PATH check -> hermes model -> first chat -> session resume
（安装 → PATH 验证 → 配 provider → 第一次对话 → 会话恢复）
```

**不要**反過來先接 Telegram、Discord、Slack、WhatsApp、cron、MCP（模型上下文協議）、skills 或 browser automation（瀏覽器自動化）。基礎對話還沒跑通時，功能開得越多，排障越慢——同一個問題既可能在模型層、也可能在 toolset、也可能在 backend，最後變成「哪都可能錯」。

## 常見問題

**`hermes: command not found`**

先過載 shell（`source ~/.zshrc` 或 `~/.bashrc`），再檢查 `~/.local/bin` 是否真的在 `PATH` 裡：

```bash
echo $PATH | tr ':' '\n' | grep '\.local/bin'
```

如果你用的是 zsh 卻只改了 `.bashrc`，當前 shell 不會自動讀到——這是最常見誤區。原生 Windows 上則是沒重啟 PowerShell。

**`API key not set` 或 provider 拒絕呼叫**

執行 `hermes model` 重新配置 provider。金鑰應該寫入 Hermes 的配置路徑（`~/.hermes/auth.json` 或 `.env`），**不要**貼進公開儲存庫、普通 Markdown、shell 歷史命令或團隊聊天群——一旦提交進 git 歷史就很難真正撤回。

**Termux 編譯失敗**

先確認你在 Termux 原生環境裡直接執行官方指令碼，**不是**在 Android 上套了不受支援的 Linux 容器（如某些"Linux on Android" 應用）。再看 [官方 Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。

**原生 Windows：裝完了但找不到命令**

99% 是 PATH 沒重新整理。**關掉當前 PowerShell 視窗、開新視窗**，再 `hermes --help`。還不行就檢查 `$env:Path` 裡有沒有 `%LOCALAPPDATA%\hermes`。

**更新後配置異常**

先跑診斷命令，讓 Hermes 自己告訴你哪裡壞了：

```bash
hermes doctor
hermes config check
```

必要時再做配置遷移，**不要**直接 `rm -rf ~/.hermes/`——那會一併刪掉你所有的 session、memory 和已配的 skill。

## 安裝驗收清單

安裝完成後至少確認下面 6 條。任何一條不過，**先停下排查**，不要繼續往下接 provider、Gateway 或 cron：

- [ ] `git --version` 正常輸出。
- [ ] `hermes --help` 能列印幫助。
- [ ] `hermes model` 能開啟 provider 配置互動介面。
- [ ] `~/.hermes/` 目錄已建立（POSIX）或 `%LOCALAPPDATA%\hermes` 已建立（Windows native）。
- [ ] 你能用一句話解釋 `config.yaml`、`.env`、`skills`、`sessions`、`memory` 和 `logs` 大致放在哪裡、各管什麼。
- [ ] **沒有把任何 API key 寫進公開檔案、git 儲存庫或 shell history**。

## 下一步

<Cards>
  <Card title="快速上手 Hermes Agent" description="安裝完成後，下一步配置 provider、完成第一次對話並驗證 session 恢復——5 分鐘跑通最小閉環。" href="/zh-Hant/docs/hermes/official/00-getting-started/quickstart" />
  <Card title="配置 Hermes Agent" description="如果安裝成功但 provider、金鑰或 backend 混亂，先查配置頁弄清 ~/.hermes 下各檔案的分工。" href="/zh-Hant/docs/hermes/official/01-user-guide/configuration" />
</Cards>

## 官方資料

- [Installation 完整頁](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
- [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
- [Termux 專項 guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux)
- [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating)
- [GitHub README](https://github.com/NousResearch/hermes-agent)
