# 国内安装Hermes Agent避坑指南：解决网络超时、依赖失败、模型连接全问题
Hermes Agent是Nous Research开源的「自我进化」AI Agent框架，拥有75000+Star，支持从使用经验中自动创建Skill，可接入Telegram、Discord等多平台，原生支持DeepSeek、Kimi等国产大模型，是当前最热门的开源Agent方案之一。
但国内用户照着官方文档安装会遇到大量网络问题，本文整理了全流程的踩坑解决方案，帮你跳过弯路快速部署。
—
## 📋 安装前环境要求
先确认你的系统满足以下依赖：
| 依赖 | 版本要求 | 检查命令 |
| — | — | — |
| Python | 3.11+ | `python3 –version` |
| Git | 任意 | `git –version` |
| Node.js | 22+ | `node –version` |
| 磁盘空间 | ≥2GB | 含Playwright Chromium浏览器 |
Python/Node版本不符合的话推荐用pyenv/nvm管理，国内安装可搭配镜像加速。
—
## 🚫 常见踩坑与解决方案
### 坑1：git clone 仓库超时
官方默认从GitHub拉取代码，国内直连大概率卡死：
– **方案A（推荐）**：用GitCode国内镜像
“`bash
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent
“`
– **方案B**：用GitHub代理站
“`bash
git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
“`
– **方案C**：配置Git全局代理（有代理的情况下）
“`bash
git config –global http.proxy http://127.0.0.1:7890
git config –global https.proxy http://127.0.0.1:7890
“`
### 坑2：uv/pip 依赖安装失败
Hermes使用uv作为Python包管理器，默认PyPI源国内访问慢：
– 配置uv镜像（阿里云/清华源二选一）
“`bash
# 临时生效
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
# 持久化写入配置
echo ‘export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/’ >> ~/.bashrc
source ~/.bashrc
“`
– 若使用pip则配置pip镜像
“`bash
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com
“`
– 手动安装依赖（如果脚本中途失败）
“`bash
cd ~/.hermes/hermes-agent
uv venv venv –python 3.11
source venv/bin/activate
uv pip install -e “.[all]” # 全量安装，最小安装用 “.[cli,cron,mcp,pty,honcho]”
“`
### 坑3：npm依赖安装卡住
浏览器工具和WhatsApp Bridge需要Node.js依赖，默认npm源国内访问慢：
– 配置npm国内镜像
“`bash
npm config set registry https://registry.npmmirror.com
“`
– 手动安装依赖
“`bash
cd ~/.hermes/hermes-agent
npm install –registry=https://registry.npmmirror.com
cd scripts/whatsapp-bridge
npm install –registry=https://registry.npmmirror.com
“`
### 坑4：Playwright浏览器下载失败
Playwright需要下载Chromium浏览器（约150MB），默认微软CDN国内超时率高：
– **方案A**：配置Playwright镜像
“`bash
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
npx playwright install chromium
“`
– **方案B**：跳过浏览器安装（暂时不用浏览器工具的情况下）
“`bash
hermes config set tools.browser.enabled false
“`
– **方案C**：用系统自带Chromium
“`bash
sudo apt install chromium-browser
export PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium-browser
“`
### 坑5：首次setup向导网络问题
setup向导的在线OAuth验证和API连接测试在国内容易失败，建议跳过向导手动写配置：
1. 编辑配置文件 `~/.hermes/config.yaml`：
“`yaml
model:
provider: deepseek
name: deepseek-chat
providers:
deepseek:
api_key: ${DEEPSEEK_API_KEY}
“`
2. 在 `~/.hermes/.env` 写入API密钥：
“`bash
echo ‘DEEPSEEK_API_KEY=sk-your-key-here’ >> ~/.hermes/.env
“`
### 坑6：大模型API国内可用性问题
Hermes要求模型至少64K上下文，国内实测可用模型推荐：
| 提供商 | 国内直连 | 配置难度 | 推荐度 |
| — | — | — | — |
| DeepSeek | ✅ 直连，速度快 | 低 | 首选 |
| Kimi/Moonshot | ✅ 直连 | 低 | 推荐 |
| MiniMax | ✅ 直连 | 低 | 推荐 |
| 阿里通义千问 | ✅ 直连 | 低 | 推荐 |
| OpenAI/Anthropic | ❌ 不通 | 需代理 | 有代理可用 |
> 国内最省心选择是DeepSeek：API申请快、价格便宜、直连稳定、中文能力优秀。
—
## ⚡ 国内一键安装脚本
作者已经把所有镜像配置整合为一键安装脚本，直接运行即可：
“`bash
curl -fsSL https://raw.githubusercontent.com/itech001/theaiera/main/scripts/install-cn.sh | bash
“`
脚本自动替换所有源为国内镜像：Git用GitCode、Python用阿里云PyPI、npm用npmmirror、Playwright用国内镜像，全程无需手动配置。
—
## ✅ 安装后验证
安装完成后运行诊断命令：
“`bash
hermes doctor
“`
所有检查项通过则说明安装成功，启动交互式界面测试：
“`bash
hermes
“`
—
## 🔗 参考来源
本文参考自博客园文章：[国内安装 Hermes Agent 踩坑全记录：从 GitHub 超时到正常跑起来的每一步](https://www.cnblogs.com/itech/p/19862085)