写给每一个在安装环节”卡到怀疑人生”的国内用户。本文把所有踩坑点、所有国内镜像配置、所有报错解决方案，一次性讲透。

---

开篇：为什么安装这么难？

如果你在国内，照着 Hermes Agent 的官方文档敲下第一条命令，大概率会卡死。

git clone 超时、pip install 挂掉、npm 依赖下不动、Playwright 浏览器下载失败……每一个环节都能让你怀疑人生。有人在社区里吐槽：“我花了一整天，从早上装到晚上，最后连第一句对话都没跑通。”

这不是你的问题，而是国内网络环境的”特产”。 Hermes Agent 的官方安装脚本默认从 GitHub、PyPI、npmjs.org、Microsoft CDN 这些境外源拉取依赖，国内直连要么超时，要么龟速。

好消息是：这些问题全都有成熟的解决方案，而且国内镜像源非常稳定。本文把一位开发者”花一整天踩完所有坑”的完整经验，整理成一份可以照抄的指南。只要你跟着做，30 分钟内就能把 Hermes 跑起来。

我们先从最基础的准备工作说起。

---

第一节：准备工作——什么机器能跑？需要装什么？

1.1 硬件要求：你的机器够不够格？

Hermes Agent 本身是一个 Agent 框架（“指挥官”），真正干活的”大脑”是云端 API 或本地大模型。所以硬件要求分两种情况：

使用场景	内存	显存	说明
纯应用层（用云端 API）	1GB+	不需要	最低 1 核 1GB 的云服务器就能跑
本地推理（跑 70B 大模型）	48GB+	48GB+	需要强力 GPU，不适合 VPS

✅ 新手建议：90% 的人应该先用云端 API（如 DeepSeek、Kimi），完全不需要本地显卡，一台几十块钱的云服务器、甚至你的笔记本就能跑。

1.2 支持哪些系统？

平台	支持情况	备注
macOS	✅ 原生支持	首选
Linux	✅ 原生支持	服务器推荐 Ubuntu 22.04+
Windows	❌ 不支持原生	必须用 WSL2
Windows + WSL2	✅ 推荐	装 Ubuntu 22.04
Android	✅ 通过 Termux	手机也能玩

⚠️ Windows 用户特别注意：Hermes Agent 不支持 Windows 原生环境！必须先装 WSL2（Windows 自带的 Linux 子系统）。下面所有命令，都要在 WSL2 终端里执行，千万不要在 PowerShell 或 CMD 里执行。

1.3 软件依赖：装之前先确认这些

在开始之前，先确认你的机器上有这几样东西：

依赖	版本要求	检查命令
Python	3.11+	python3 --version
Git	任意	git --version
Node.js	22+	node --version
磁盘空间	~2GB	含 Playwright Chromium

如果版本不对，需要先升级。下面给出国内可用的升级方法。

安装 Python 3.11（用 pyenv）：

curl -fsSL https://pyenv.run | bash
pyenv install 3.11
pyenv global 3.11

⚠️ 这两个命令本身在国内也可能超时。别急，下文的镜像配置会一并解决。

Windows 用户先装 WSL2（管理员身份打开 PowerShell）：

wsl --install -d Ubuntu-22.04

装完重启电脑，打开 Ubuntu 终端，后续操作全部在这里进行。

---

第二节：一步一步装——从零到 hermes 运行

这一节是全文的核心。我会把官方安装脚本里每一个可能卡住的环节，都配上国内镜像解决方案。

2.1 第一步：配好所有国内镜像（关键！）

在开始安装之前，先把所有镜像源配置好，这样后续每一步都能畅通无阻。把下面这些命令一次性执行：

# ① 配置 uv（Hermes 的包管理器）使用阿里云 PyPI 镜像
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# 持久化写入 bash 配置（下次开机不用重设）
echo 'export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/' >> ~/.bashrc
source ~/.bashrc

# ② 配置 pip 镜像（备用）
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com

# ③ 配置 npm 镜像（浏览器工具和 WhatsApp 桥接需要 Node 依赖）
npm config set registry https://registry.npmmirror.com
npm config get registry   # 验证，应输出 npmmirror 地址

# ④ 配置 Playwright 浏览器下载镜像（这是最大的坑之一）
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright

✅ 为什么要这么做：Hermes 安装脚本会从 PyPI 拉 Python 包、从 npmjs.org 拉 Node 包、从微软 CDN 下载浏览器，这三个源在国内都不稳定。换成阿里云、npmmirror 镜像后，速度会有质的飞跃。

2.2 第二步：克隆代码（解决 git clone 超时）

官方第一步是 git clone https://github.com/...，国内直连大概率卡死。用国内镜像替代：

# 方案 A：GitCode 镜像（最推荐，稳定快速）
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent

# 方案 B：GitHub 加速代理
git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

如果你有代理，也可以给 Git 单独配代理：

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
# 用完记得取消
git config --global --unset http.proxy
git config --global --unset https.proxy

2.3 第三步：安装 Python 依赖（解决编译报错）

cd ~/.hermes/hermes-agent

# 创建 Python 3.11 虚拟环境
uv venv venv --python 3.11
source venv/bin/activate

# 安装完整依赖（前面已配好阿里云镜像，这一步会很顺）
uv pip install -e ".[all]"

⚠️ 如果报 Failed to build wheel for xxx，是缺少 C 编译工具链，先装它：

sudo apt update && sudo apt install -y build-essential python3-dev

⚠️ 如果报 ResolutionImpossible（依赖冲突），删掉虚拟环境重建：

rm -rf venv
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all]"

✅ 小技巧：如果不想装全部依赖，可以先装最小集，后面需要再加：

uv pip install -e ".[cli,cron,mcp,pty,honcho]"

2.4 第四步：安装 Node 依赖（解决 npm 卡住）

cd ~/.hermes/hermes-agent
npm install --registry=https://registry.npmmirror.com

cd scripts/whatsapp-bridge
npm install --registry=https://registry.npmmirror.com

2.5 第五步：安装 Playwright 浏览器（最大的坑）

Playwright 需要下载约 150MB 的 Chromium，默认从微软 CDN 下载，国内经常超时。前面我们已经配了镜像，现在直接装：

cd ~/.hermes/hermes-agent
npx playwright install chromium

⚠️ 如果还是失败，可以先用系统的 Chromium 顶替：

sudo apt install chromium-browser
export PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium-browser

✅ 或者直接跳过：如果你暂时不需要浏览器工具（网页搜索、抓取），可以先禁用它，等网络好了再装：

hermes config set tools.browser.enabled false

2.6 第六步：一键安装脚本（懒人福音）

如果你觉得上面手动一步步太麻烦，社区已经有人把所有镜像配置打包成了一键脚本。这个脚本把官方源的 GitHub、PyPI、npm、Playwright、Node.js 下载地址全部换成了国内镜像：

# 一行命令安装（国内镜像版）
curl -fsSL https://raw.githubusercontent.com/itech001/theaiera/main/scripts/install-cn.sh | bash

# 或者先下载再运行（方便检查脚本内容）
curl -fsSL https://raw.githubusercontent.com/itech001/theaiera/main/scripts/install-cn.sh -o install-cn.sh
chmod +x install-cn.sh
./install-cn.sh

脚本启动时会显示它使用的所有镜像源，让你心里有数：

⚑ Using China mirror sources:
  Git:        gitcode.com
  PyPI:       https://mirrors.aliyun.com/pypi/simple/
  npm:        https://registry.npmmirror.com
  Playwright: https://npmmirror.com/mirrors/playwright
  Node.js:    https://npmmirror.com/mirrors/node

装完后，加载环境变量：

source ~/.bashrc   # bash 用户
source ~/.zshrc    # zsh 用户（macOS 默认）

验证安装成功：

hermes --version

能输出版本号，恭喜你，最难的安装环节已经过去了。

---

第三节：hermes setup 向导详解——每一步选什么

安装完成后，运行配置向导：

hermes setup

这个向导会引导你完成几个关键选择。下面逐一说清楚每一步该怎么选。

第一步：确认风险提示

向导会提示”This is powerful and inherently risky”。选 Yes，表示你了解 Agent 拥有执行命令、操作文件的权限。

第二步：选择模型提供商（最关键的一步）

⚠️ 国内用户的痛就在这里：向导会做在线连接测试，OpenAI、Anthropic 这些在国内连不上，会导致验证失败。

✅ 最佳实践：跳过向导里的在线验证，手动写配置文件。

如果你坚持用向导，推荐选国内能直连的提供商。国内可用性实测如下：

提供商	国内直连	配置难度	推荐度
DeepSeek	✅ 直连，速度快	低（填 API Key 即可）	⭐⭐⭐⭐⭐ 首选
Kimi / Moonshot	✅ 直连	低	⭐⭐⭐⭐ 推荐
阿里通义千问	✅ 直连	低（DashScope Key）	⭐⭐⭐⭐ 推荐
智谱 GLM	✅ 直连	低	⭐⭐⭐⭐ 推荐
MiniMax	✅ 直连	低	⭐⭐⭐ 推荐
OpenAI	❌ 不通	需代理或转发	备选
Anthropic	❌ 不通	需代理或转发	备选
OpenRouter	⚠️ 偶尔能通	不稳定	备选

✅ 国内最省心的选择是 DeepSeek：API 申请快（几小时）、价格便宜、直连稳定、中文能力好。

第三步：选择默认模型

选一个上下文够大的模型。⚠️ Hermes 要求模型至少 64K token 上下文，否则容易报上下文不足。例如 DeepSeek 选 deepseek-chat。

第四步：配置工具集

建议新手先开核心工具集：

hermes tools --set web,terminal,file,memory,skills,cron

✅ 等熟悉了再开 --set all，避免一上来加载太多工具导致上下文臃肿。

---

第四节：装完后的必做配置

配置文件都在 ~/.hermes/ 目录下，结构如下：

~/.hermes/
├── config.yaml     # 主配置（模型、终端、TTS、压缩等）
├── .env            # API Keys 和密钥（不要提交到 git！）
├── auth.json       # OAuth 凭据
├── SOUL.md         # 全局人格定义（可选但强烈推荐）
├── memories/       # 持久记忆
├── skills/         # 沉淀的技能
├── cron/           # 定时任务
└── sessions/       # 对话会话

4.1 config.yaml 核心字段

如果你跳过了向导，手动写配置（以 DeepSeek 为例）：

# ~/.hermes/config.yaml
model:
  provider: deepseek
  name: deepseek-chat

providers:
  deepseek:
    api_key: ${DEEPSEEK_API_KEY}

其他常用配置：

# 设置默认模型
hermes config set model.default deepseek-chat

# 设置人格（helpful / creative / teacher）
hermes config set display.personality helpful

# 设置最大对话轮数
hermes config set agent.max_turns 100

# 开启上下文压缩（省 token 神器）
# 在 config.yaml 中添加：
# compression:
#   enabled: true
#   threshold: 0.50

# 查看当前配置
hermes config show

4.2 .env 文件——放 API Key 的地方

⚠️ API Key 千万不要直接写进 config.yaml（那个文件可能被分享），应该放进 .env：

# 写入 API Key（以 DeepSeek 为例）
echo 'DEEPSEEK_API_KEY=sk-你的key' >> ~/.hermes/.env

如果你用 OpenRouter：

echo 'OPENROUTER_API_KEY=sk-or-你的key' >> ~/.hermes/.env

4.3 SOUL.md——给 AI 定”性格”

这是最容易被忽略、却最影响体验的配置。SOUL.md 是全局人格定义，告诉 Hermes 它是谁、怎么说话。例如：

# ~/.hermes/SOUL.md

你是一个名叫"小赫"的私人助手。
- 说话简洁直接，不啰嗦
- 用中文回复，代码和命令用英文
- 我是程序员，喜欢技术细节
- 遇到不确定的事，直接说不确定，不要瞎编

✅ 最佳实践：SOUL.md 不要写太长，几十字到几百字最好。写得太长每轮都会注入上下文，白白烧 token（这一点我们在《模型配置与零成本方案》那篇会详细讲）。

4.4 安全配置（联网必做）

Hermes 拥有执行终端命令、操作文件的权限，一旦接入 Telegram/Discord 等聊天平台，一定要配置白名单：

# ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=你的用户ID
DISCORD_ALLOWED_USERS=你的用户ID

⚠️ 严禁设置 GATEWAY_ALLOW_ALL_USERS=true，否则任何人都能控制你的 Agent！

危险命令审批也要开：

# ~/.hermes/config.yaml
security:
  dangerous_command_approval: always   # 始终审批
  # 或 high_risk_only                    # 仅高风险审批

---

第五节：十大常见报错与解决方案

下面这张表，是无数国内用户用血泪换来的经验。照着抄就能修。

#	报错现象	根本原因	解决方案
1	安装后 hermes: command not found	shell 配置没重新加载	source ~/.bashrc；手动安装需 sudo ln -sf "$(pwd)/.venv/bin/hermes" /usr/local/bin/hermes
2	git clone 超时卡死	直连 GitHub 被墙	换镜像：git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git
3	pip install / uv 报 ConnectionTimeout	PyPI 源超时	配阿里云镜像：export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
4	Failed to build wheel for xxx	缺少 C 编译工具链	sudo apt install build-essential python3-dev
5	Playwright 浏览器下载失败	微软 CDN 被墙	export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright 后重试
6	模型报 401/403 错误	API Key 错误或格式不对	hermes config show | grep API_KEY 检查；运行 hermes doctor 诊断
7	上下文窗口不足（context too long）	模型上下文太小	换更大上下文模型；开启 compression.enabled: true
8	消息平台收不到消息	网关服务没启动	hermes gateway start；检查白名单 TELEGRAM_ALLOWED_USERS
9	工具执行报权限错误	终端后端权限不足	检查 config.yaml 的 terminal 配置；Docker 后端需 sudo usermod -aG docker $USER
10	安装报 Python/Cython 编译错误	部分依赖需编译环境	sudo apt install -y python3-dev build-essential 后 pip install --no-cache-dir -e ".[all]"

常用排错命令速查

遇到问题别慌，先跑这几条命令定位：

hermes doctor        # 诊断环境、依赖、模型连接（最重要！）
hermes config show   # 查看当前配置
which hermes         # 确认命令是否在 PATH 里
hermes --version     # 确认版本

⚠️ 安装时报 ResolutionImpossible（依赖版本冲突）：90% 的情况是虚拟环境污染了，删掉 venv 重建是最快的办法。

---

结尾：验证成功的标志

怎么确认你真的装好了？三步验证：

① 跑诊断（全部通过）：

hermes doctor

hermes doctor 会检查环境配置、依赖完整性、模型连接。全部绿色通过，就说明基础设施没问题。

② 启动第一次对话：

hermes

你会看到一个 TUI 界面，显示当前模型、可用工具和技能。输入一句话试试：

❯ 你好，介绍一下你自己

③ 能正常回复：如果它用你配置的模型正常回答了，恭喜你——所有坑都过了，Hermes 已经在你机器上活过来了。

常用命令速查表

命令	功能
hermes	启动交互式 CLI
hermes chat -q "你的问题"	单次查询（不进交互界面）
hermes model	切换 / 选择模型和提供商
hermes tools	配置启用的工具集
hermes setup	完整配置向导
hermes doctor	诊断问题（必记！）
hermes update	更新版本
hermes gateway	启动消息网关（Telegram 等）
hermes --continue	恢复上次对话
/new 或 /reset	会话内开始新对话
/skills	查看和管理技能

---

一句话总结

国内安装 Hermes Agent 的核心，就一句话：把所有境外源换成国内镜像。GitHub 换 GitCode，PyPI 换阿里云，npm 换 npmmirror，Playwright 换 npmmirror 镜像，模型用 DeepSeek/Kimi 等国产直连 API。把这五个”换成”做好，安装就再也不会卡了。

装好之后，下一步就是让 Hermes 既”用得起”又”用得好”。模型怎么选、token 怎么省、报错怎么修——请看系列第二篇《模型配置与零成本方案》。

延伸阅读

• 知识管理与记忆系统 — 让AI拥有记忆
• Skill 技能系统与多Agent协作 — 从单兵变团队
• 消息平台接入实战 — 出现在你每个屏幕
• 模型配置与零成本方案 — 用得起、用得好
• 安全防护与进阶玩法 — 别让你的AI裸奔
• cron 调度指南 — 让AI每天自动干活

祝你一次跑通，告别踩坑。🚀