安裝

安裝遇到困難？

點擊加入中文社區微信群，提問並獲取群內專家幫助。
如果您已經安裝了龍蝦 OpenClaw，或者國內常見的龍蝦版本，例如 QClaw、WorkBuddy、ArkClaw、AutoClaw，可以讓它讀文檔協助您配置，您自己不用懂任何技術細節。有兩種方式：
- 方式一（最簡單）：把中文社區網址 https://hermesagent.org.cn 發給它，讓它自己訪問並閱讀文檔。
- 方式二（更精準，推薦）：直接把下面這段話複製發給您的 Agent，它會自己完成配置：
```
請把這個 MCP server 加到你的配置裡：https://mcp.hermesagent.org.cn/v1 （Streamable HTTP，無需 API Key、無需登錄）。加完後用它幫我查 Hermes Agent 中文文檔來指導我完成安裝。
```
- 方式二配好後，Agent 就能按關鍵詞直接檢索並讀取 113 篇中文文檔的全文。
安裝過程中遇到問題時，也可以先詢問豆包、DeepSeek 等 AI 助手。

Hermes Agent 現在已經有 類 Unix 安裝路徑 和 Windows 安裝路徑 兩套方案。

如果你是 Windows 用戶，可以先把 WSL2 理解成：

一個運行在 Windows 裡的 Linux 環境
安裝後你會在開始菜單裡看到一個 Ubuntu 之類的終端
你可以繼續日常使用 Windows，但在這個 Ubuntu 終端裡執行 Linux 命令

對 Hermes Agent 來說，WSL2 的意義是：更接近官方推薦的類 Unix 工作流，兼容性通常比原生 PowerShell 更好。

Linux / macOS / WSL2：使用中文社區維護的鏡像版 install.sh，優先走國內可直連鏈路，是最穩的日常使用路徑。
Windows 原生 PowerShell：可以直接使用鏡像版 install.ps1，適合想先在本機快速跑起來的用戶。
Android / Termux：使用專門的移動端安裝路徑。

如果你主要在 Windows 上使用，建議先閱讀 Windows 安裝指南，裡面把 WSL2、原生 PowerShell、飛書接入和常見坑都拆開說明了。

快速安裝

類 Linux / macOS / WSL2

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

適合：

Linux 桌面 / 服務器
macOS
Windows + WSL2（推薦給大多數 Windows 用戶）

Windows 原生 PowerShell

irm https://res1.hermesagent.org.cn/install.ps1 | iex

如果你完全不熟悉 Windows 命令行，先記住這三件事：

PowerShell 是什麼？
它是 Windows 自帶的命令行程序，可以理解成“Windows 裡的終端”。
怎麼打開？
按鍵盤左下角 Windows 鍵，輸入 PowerShell，點擊 Windows PowerShell 或 PowerShell 即可。
在哪裡粘貼命令？
就粘貼到 PowerShell 窗口裡。不要粘貼到瀏覽器地址欄、文件資源管理器地址欄，或“運行”對話框裡。

適合：

想先在 Windows 本機快速體驗 Hermes Agent
不想先折騰 WSL2 的用戶

PowerShell 直裝小白步驟

如果你想直接在 Windows 本機安裝，可以按下面這套最短步驟來：

按一下 Windows 鍵
輸入 PowerShell
點擊 Windows PowerShell 或 PowerShell
把下面這行命令完整複製進去：

irm https://res1.hermesagent.org.cn/install.ps1 | iex

在 PowerShell 窗口裡粘貼並按回車
等安裝器自己跑完
關閉當前 PowerShell 窗口
再重新打開一個新的 PowerShell
輸入：

hermes

如果這時能正常進入 Hermes，說明安裝已經成功。

什麼時候需要“管理員 PowerShell”？

安裝 WSL2 時，通常需要管理員 PowerShell。
直接安裝 Hermes 時，一般用普通 PowerShell 就可以，不需要管理員權限。

如果窗口一閃而過，通常是打開方式不對

最常見的原因是：

你把命令輸到了別的地方，不是在 PowerShell 裡執行
你雙擊了某個 .ps1 文件，導致窗口執行完立即關閉
你打開的是別的終端程序，但沒有進入 PowerShell 標籤頁

最穩的方式還是：開始菜單搜索 PowerShell → 打開 → 粘貼命令 → 回車。

Windows 用戶怎麼選？

想要最穩、最接近官方類 Unix 工作流：先裝 WSL2，再在 WSL2 裡運行 install.sh。
想先在 PowerShell 裡快速跑起來：直接運行上面的 install.ps1。
如果你計劃長期使用終端工具、瀏覽器自動化、消息網關、MCP 或各種 shell 工作流，優先推薦 WSL2。

中國大陸網絡環境提示

當前頁面提供的安裝命令已經由 Hermes Agent 中文社區 接入了 國內鏡像加速，會優先使用國內可直連的下載鏈路。

為了提高中國大陸用戶的安裝體驗，鏡像版安裝器默認精簡了部分國人不常用、或體積較大且經常受外網影響的可選功能，例如瀏覽器自動化、Chromium 下載、WhatsApp 橋接等。建議先完成核心安裝，確認 Hermes Agent 可以正常運行；之後可讓 Hermes Agent 自身補全這些能力。

如果你仍然需要處理 WSL 網絡、終端代理或手動鏡像配置，可參考這些鏈接：

WSL 安裝（中文）：Windows 10/11 安裝 WSL2 指南
WSL 網絡 / autoProxy（官方）：Microsoft Learn - Accessing network applications with WSL
Python / pip 鏡像說明：清華 TUNA - PyPI 鏡像幫助
Node.js / npm 鏡像說明：清華 TUNA - NodeJS Release 鏡像幫助 / npmmirror

Android / Termux

Hermes 也提供了針對 Termux 的安裝路徑：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

安裝程序會自動檢測 Termux 並切換到經過測試的 Android 流程：

優先複用系統已有的 Python；缺失時通過 pkg 安裝 Python
自動補齊 Android 構建所需的基礎工具鏈（clang、rust、make、pkg-config、libffi、openssl）
使用 python -m venv 創建虛擬環境
自動導出 ANDROID_API_LEVEL 用於 Android 輪子構建
通過 pip 安裝經過精選的 .[termux] 額外組件
默認跳過瀏覽器 / WhatsApp 等額外 Node 組件

如需完全顯式路徑，請參考專用的 Termux 指南。

安裝程序執行的操作

安裝器會自動處理以下工作：

優先使用站點鏡像 / R2 資源下載源碼包，失敗時再回退到上游倉庫
優先複用系統已有的 Python（>= 3.11）；沒有時再嘗試通過 uv 安裝 Python
創建虛擬環境並安裝 hermes 命令
引導你完成模型配置與首次啟動
默認跳過瀏覽器、Chromium、WhatsApp 橋接等額外 Node 組件

安裝後操作

類 Unix / WSL2

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

Windows PowerShell

# 關閉並重新打開 PowerShell 後再運行
hermes

如需後續重新配置個別設置，請使用這些命令：

hermes model          # 選擇大語言模型提供商和模型
hermes tools          # 配置啟用哪些工具
hermes gateway setup  # 設置消息平臺
hermes config set     # 單獨設置某個配置項
hermes setup          # 或再次運行完整設置嚮導

先決條件

推薦先決條件：

Python 3.11+（安裝器會優先複用系統已有 Python）
Git（只有當鏡像源碼包不可用時，安裝器才會回退到 git clone）
Node.js v22+（僅在你需要瀏覽器 / 其他額外 Node 組件時再裝）
ripgrep / ffmpeg（非硬性依賴，缺失時會提示手動安裝）

信息

對大多數中國大陸用戶來說，最穩的路徑是：先用鏡像版 install.sh 完成核心安裝，再按需單獨補瀏覽器 / WhatsApp 等額外組件。

Nix 用戶

如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有專門的設置路徑，包括 Nix flake、聲明式 NixOS 模塊以及可選容器模式。請參閱 Nix & NixOS 設置 指南。

手動安裝

如果你希望對安裝過程擁有完全控制，請遵循以下步驟。

Windows 用戶

下面這組手動命令是給 類 Unix shell / WSL2 準備的，不適合直接在 PowerShell 中照抄。如果你使用的是原生 Windows，請優先走上面的 install.ps1，或直接看 Windows 安裝指南。

步驟 1：克隆倉庫

使用 --recurse-submodules 克隆以拉取所需子模塊：

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

如果您已不帶 --recurse-submodules 克隆：

git submodule update --init --recursive

步驟 2：安裝 uv 並創建虛擬環境

# 安裝 uv（如果尚未安裝）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 Python 3.11 創建虛擬環境（若本機不存在，uv 會自動下載，無需 sudo）
uv venv venv --python 3.11

提示

您無需激活虛擬環境即可使用 hermes。入口點已硬編碼指向虛擬環境的 Python，因此一旦創建符號鏈接，即可全局使用。

步驟 3：安裝 Python 依賴項

# 告訴 uv 要安裝到哪個虛擬環境
export VIRTUAL_ENV="$(pwd)/venv"

# 安裝完整推薦依賴
uv pip install -e ".[all]"

如果您僅需要核心 Agent（無 Telegram/Discord/cron 支持）：

uv pip install -e "."

可選額外組件說明

額外組件	添加內容	安裝命令
`all`	以下所有內容	`uv pip install -e ".[all]"`
`messaging`	Telegram 與 Discord 網關	`uv pip install -e ".[messaging]"`
`cron`	用於定時任務的 cron 表達式解析	`uv pip install -e ".[cron]"`
`cli`	設置嚮導的終端菜單 UI	`uv pip install -e ".[cli]"`
`modal`	Modal 雲執行後端	`uv pip install -e ".[modal]"`
`tts-premium`	ElevenLabs 高級語音	`uv pip install -e ".[tts-premium]"`
`voice`	CLI 麥克風輸入 + 音頻播放	`uv pip install -e ".[voice]"`
`pty`	PTY 終端支持	`uv pip install -e ".[pty]"`
`termux`	經測試的 Android / Termux 套件（`cron`、`cli`、`pty`、`mcp`、`honcho`、`acp`）	`python -m pip install -e ".[termux]" -c constraints-termux.txt`
`honcho`	AI 原生記憶（Honcho 集成）	`uv pip install -e ".[honcho]"`
`mcp`	模型上下文協議支持	`uv pip install -e ".[mcp]"`
`homeassistant`	Home Assistant 集成	`uv pip install -e ".[homeassistant]"`
`acp`	ACP 編輯器集成支持	`uv pip install -e ".[acp]"`
`slack`	Slack 消息	`uv pip install -e ".[slack]"`
`dev`	pytest 與測試工具	`uv pip install -e ".[dev]"`

您可以組合使用額外組件：uv pip install -e ".[messaging,cron]"

Termux 用戶

.[all] 當前在 Android 上不可用，因為 voice 額外組件依賴 faster-whisper，而 faster-whisper 依賴 ctranslate2 輪子，這些輪子尚未發佈到 Android。請使用 .[termux] 獲取經過測試的移動端安裝路徑，然後按需添加個別額外組件。

步驟 4：安裝可選子模塊（如需）

# 強化學習訓練後端（可選）
uv pip install -e "./tinker-atropos"

兩者均為可選 —— 如果跳過，相應工具集將不可用。

步驟 5：安裝 Node.js 依賴項（可選）

僅在需要 瀏覽器自動化（Browserbase 驅動）和 WhatsApp 橋接 時才需要：

npm install

步驟 6：創建配置目錄

# 創建目錄結構
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

# 複製示例配置文件
cp cli-config.yaml.example ~/.hermes/config.yaml

# 創建用於保存 API 密鑰的空 `.env` 文件
touch ~/.hermes/.env

第 7 步：添加您的 API 密鑰

打開 ~/.hermes/.env 文件，並至少添加一個 LLM 提供商的密鑰：

# 必填：至少配置一個大語言模型提供商
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 可選：啟用額外工具能力
FIRECRAWL_API_KEY=fc-your-key          # 網絡搜索和抓取（或自託管，請參閱文檔）
FAL_KEY=your-fal-key                   # 圖像生成（FLUX）

或者通過 CLI 設置：

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

第 8 步：將 `hermes` 添加到您的 PATH

mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

如果 ~/.local/bin 不在您的 PATH 中，請將其添加到您的 shell 配置文件中：

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Fish
fish_add_path $HOME/.local/bin

第 9 步：配置您的提供方

hermes model       # 選擇大語言模型提供商和具體模型

第 10 步：驗證安裝

hermes version    # 檢查命令是否可用
hermes doctor     # 運行診斷，確認環境工作正常
hermes status     # 檢查當前配置
hermes chat -q "你好，告訴我你當前可用的工具。"

快速參考：手動安裝（精簡版）

適用於只想獲取命令的用戶：

# 安裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆倉庫並進入目錄
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 使用 Python 3.11 創建虛擬環境
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# 安裝完整依賴
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"
npm install  # 可選：瀏覽器工具和 WhatsApp 橋接需要它

# 準備配置文件
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

# 讓 hermes 成為全局命令
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# 驗證安裝
hermes doctor
hermes

故障排除

問題	解決方案
`hermes: command not found`	重新加載您的 shell（`source ~/.bashrc`）或檢查 PATH
`API key not set`	運行 `hermes model` 來配置您的提供方，或運行 `hermes config set OPENROUTER_API_KEY your_key`
`hermes` 不是內部或外部命令	關閉並重新打開 PowerShell，或確認 `%LOCALAPPDATA%\hermes\bin` 已加入 PATH；WSL2 用戶請重新加載 shell
更新後配置丟失	運行 `hermes config check`，然後運行 `hermes config migrate`

如需更多診斷信息，請運行 hermes doctor —— 它將明確告知您缺少什麼以及如何修復。

快速安裝​

類 Linux / macOS / WSL2​

Windows 原生 PowerShell​

PowerShell 直裝小白步驟​

Android / Termux​

安裝程序執行的操作​

安裝後操作​

類 Unix / WSL2​

Windows PowerShell​

先決條件​

手動安裝​

步驟 1：克隆倉庫​

步驟 2：安裝 uv 並創建虛擬環境​

步驟 3：安裝 Python 依賴項​

步驟 4：安裝可選子模塊（如需）​

步驟 5：安裝 Node.js 依賴項（可選）​

步驟 6：創建配置目錄​

第 7 步：添加您的 API 密鑰​

第 8 步：將 hermes 添加到您的 PATH​

第 9 步：配置您的提供方​

第 10 步：驗證安裝​

快速參考：手動安裝（精簡版）​

故障排除​