安装

安装遇到困难？

点击加入中文社区微信群，提问并获取群内专家帮助。

完全没有经验？ 强烈建议先下载 WorkBuddy（微信扫码即用，无需任何配置），然后让它安装中文社区文档 MCP 来协助你安装 Hermes Agent。如果后续 Hermes 出现问题，也可以让 WorkBuddy 对其进行修复，反之亦然——两个 Agent 互为主备，这是社区推荐的最佳方案。

电脑上已经有 Agent？ 如果你已经在用龙虾 OpenClaw 或国内版本（QClaw、AutoClaw），或者 Trae、Claude Code、Codex、Cursor、Qoder 等 Coding Agent，都可以让它读文档来协助你完成安装，你可以不用关心任何技术细节。

如何让你的 Agent 接入中文社区文档？

方式一（最简单）：把中文社区网址 https://hermesagent.org.cn 发给它，让它自己访问并阅读文档。

方式二（更精准，推荐）：直接把下面这段话复制发给你的 Agent，它会自己完成配置：

请把这个 Hermes 中文文档 MCP server 加到你的配置里：
https://mcp.hermesagent.org.cn/v1
（Streamable HTTP，无需 API Key、无需登录）
加完后用它帮我查 Hermes Agent 中文文档来指导我完成安装。

方式二配好后，Agent 就能按关键词直接检索并读取中文社区全部文档的全文。

其他求助途径：也可以先询问豆包、DeepSeek 等 AI 助手。

Sponsor · 开箱即用方案不想折腾安装环境？可以直接使用专属 Hermes 盒子。拿到盒子后连接网络，用浏览器即可访问 Web 可视化管理后台，免安装、开箱即用，适合想快速体验 Hermes 的用户。下单时提到「HermesAgent中文社区」，立减 20 元，并送 1 亿额度 Token（价值 100+ 元）。购买 Hermes 盒子 ↗

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 步：验证安装​

快速参考：手动安装（精简版）​

故障排除​