Hermes Agent 安装与 Setup —— 一键安装、交互式配置、doctor 诊断
简介
前一篇我们完成了 AI 编程 Agent 的全景图梳理，从 Claude Code 到 Codex CLI，再到各类开源工具。本篇开始，我们正式进入 Hermes Agent 的实战系列。
Hermes Agent 是一个面向开发者的开源 AI 编程 Agent 框架，支持 20+ 模型提供商、灵活的权限控制、TUI 交互模式，以及可扩展的插件系统。它的核心设计理念是：
让开发者用最小的配置成本，获得最强大的 AI 编程助手体验。
但"最小配置成本"的前提是——安装过程足够简单、配置流程足够直观、遇到问题时能快速诊断。
本文将带你完整走一遍 Hermes Agent 的安装、初始配置和健康诊断流程。无论你是 Mac/Linux 用户、Windows WSL 用户，还是想在 Docker 容器中部署的运维工程师，都能找到对应的方案。
目录
一键安装：四种安装方式
Hermes Agent 提供了四种安装方式，覆盖从「最简单」到「最可控」的全部场景。
方式一：一键安装脚本（推荐新手）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/install.sh | bash这条命令会：
- 检测你的操作系统（macOS / Linux / WSL）
- 自动下载对应架构的二进制文件
- 安装到
/usr/local/bin/hermes-agent - 自动配置 shell 补全
- 创建默认配置文件模板
安装完成后的输出示例：
╔══════════════════════════════════════════════╗
║ Hermes Agent 安装成功！ ║
║ ║
║ 版本: 1.2.0 ║
║ 路径: /usr/local/bin/hermes-agent ║
║ 配置: ~/.config/hermes-agent/config.yaml ║
║ ║
║ 下一步: 运行 hermes-agent setup ║
║ 配置你的首选 AI 模型提供商 ║
╚══════════════════════════════════════════════╝方式二：npm 安装（Node.js 开发者友好）
如果你已经安装了 Node.js，这是最便捷的方式：
npm install -g @nousresearch/hermes-agentnpm 安装的优势：
- 版本管理简单：通过 npm 即可更新和回退
- 与现有 Node 生态集成：可以作为项目依赖安装
- 自动处理 shell 补全
查看安装结果：
hermes-agent --version
# 输出: 1.2.0方式三：Homebrew 安装（macOS/Linux 用户）
# macOS
brew tap nousresearch/hermes-agent
brew install hermes-agent
# Linux (如果已安装 Homebrew)
brew install nousresearch/hermes-agent/hermes-agentHomebrew 安装的额外好处：
# 更新
brew upgrade hermes-agent
# 卸载
brew uninstall hermes-agent
# 查看安装信息
brew info hermes-agent方式四：源码编译（高级用户）
如果你需要自定义编译选项或参与开发：
# 1. 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
# 2. 安装依赖
npm install
# 3. 编译
npm run build
# 4. 全局链接（开发模式）
npm link
# 5. 运行
hermes-agent --version源码编译适合以下场景：
- 需要修改源代码后重新编译
- 需要针对特定 CPU 架构优化
- 想要贡献代码并测试
安装验证
无论使用哪种方式，安装完成后都应该验证：
# 检查版本
hermes-agent --version
# 检查帮助信息
hermes-agent --help
# 检查安装路径
which hermes-agent交互式配置向导
安装完成后，运行 hermes-agent setup 启动交互式配置向导。这是 Hermes Agent 最人性化的设计之一——你不需要手动编辑配置文件，向导会引导你完成所有设置。
启动向导
hermes-agent setup第一步：选择模型提供商
向导会列出所有支持的模型提供商：
╔═══════════════════════════════════════════════════════╗
║ 选择你的 AI 模型提供商 ║
╠═══════════════════════════════════════════════════════╣
║ ║
║ 1. OpenAI (gpt-4o, o3-mini, o4-mini) ║
║ 2. Anthropic (Claude 4 Sonnet, Opus) ║
║ 3. Google (Gemini 2.5 Pro, Flash) ║
║ 4. OpenRouter (聚合 200+ 模型) ║
║ 5. DeepSeek (DeepSeek-V3, R1) ║
║ 6. Mistral (Mistral Large, Codestral) ║
║ 7. Groq (超快速推理) ║
║ 8. 本地模型 (Ollama, LM Studio) ║
║ 9. 自定义 OpenAI 兼容 API ║
║ 10. 稍后配置 ║
║ ║
║ 选择 [1-10]: ║
╚═══════════════════════════════════════════════════════╝每个选项旁边标注了代表性模型，帮助你快速判断。
第二步：输入 API Key
选择提供商后，向导会提示输入 API Key：
┌─ OpenAI API Key ──────────────────────────────────────┐
│ │
│ 请输入你的 OpenAI API Key: │
│ sk-proj-•••••••••••••••••••••••••••• │
│ │
│ 💡 提示：你可以在 https://platform.openai.com/api-keys│
│ 创建新的 API Key │
│ │
└───────────────────────────────────────────────────────┘向导会立即验证 API Key 是否有效：
✓ API Key 验证成功！
账户: user@example.com
可用模型: gpt-4o, o3-mini, o4-mini, gpt-4o-mini
余额状态: 充足第三步：选择默认模型
┌─ 选择默认模型 ────────────────────────────────────────┐
│ │
│ 你的账户可用以下模型： ║
│ │
│ 1. gpt-4o - 全能型，适合大多数任务 ║
│ 2. o3-mini - 快速编程，性价比高 ║
│ 3. o4-mini - 最新编程模型 ║
│ 4. gpt-4o-mini - 经济型，适合简单任务 ║
│ │
│ 选择 [1-4]: ║
╚═══════════════════════════════════════════════════════╝第四步：设置权限模式
┌─ 权限模式 ────────────────────────────────────────────┐
│ │
│ Hermes Agent 需要权限来执行文件操作和命令。 ║
│ 选择你的默认权限模式： ║
│ │
│ 1. 只读模式 - 只能读取文件，不能修改 ║
│ 2. 询问模式 - 每次操作前都需要你确认（推荐） ║
│ 3. 自动模式 - 自动执行所有操作（仅限可信环境） ║
│ 4. 沙箱模式 - 在隔离环境中执行操作 ║
│ │
│ 选择 [1-4]: ║
╚═══════════════════════════════════════════════════════╝第五步：配置完成
╔═══════════════════════════════════════════════════════╗
║ 配置完成！🎉 ║
╠═══════════════════════════════════════════════════════╣
║ ║
║ 提供商: OpenAI ║
║ 模型: gpt-4o ║
║ 权限: 询问模式 ║
║ 配置: ~/.config/hermes-agent/config.yaml ║
║ ║
║ 你现在可以开始使用了！ ║
║ ║
║ $ hermes-agent ║
║ ║
╚═══════════════════════════════════════════════════════╝配置文件详解
交互式配置向导生成的配置文件位于 ~/.config/hermes-agent/config.yaml（macOS/Linux）或 %APPDATA%\hermes-agent\config.yaml（Windows）。
完整配置模板
# Hermes Agent 配置文件
# 生成时间: 2025-05-22
# 版本: 1.2.0
# ===== 模型提供商配置 =====
providers:
# 主提供商（默认使用）
primary:
name: openai
api_key: "${OPENAI_API_KEY}" # 支持环境变量引用
model: gpt-4o
base_url: https://api.openai.com/v1
timeout: 60 # 请求超时（秒）
max_retries: 3
# 备用提供商（主提供商不可用时自动切换）
fallback:
name: anthropic
api_key: "${ANTHROPIC_API_KEY}"
model: claude-sonnet-4-20250514
base_url: https://api.anthropic.com
timeout: 120
# ===== 权限配置 =====
permissions:
mode: ask # ask | readonly | auto | sandbox
file_operations:
read: true
write: ask
delete: ask
execute: ask
command_execution:
safe_commands: ["ls", "cat", "grep", "find"]
dangerous_commands: ["rm", "dd", "mkfs"]
require_approval: true
# ===== 系统配置 =====
system:
language: zh-CN # zh-CN | en | ja | ko
theme: auto # auto | light | dark
max_context_tokens: 128000
enable_streaming: true
log_level: info # debug | info | warn | error
# ===== 插件配置 =====
plugins:
enabled:
- git
- github
- docker
config:
git:
auto_commit: false
branch_prefix: "hermes-agent/"
# ===== 自定义规则 =====
rules:
- name: code-style
description: "遵循项目编码规范"
enabled: true
- name: security-first
description: "优先考虑安全性"
enabled: true环境变量引用
配置文件中支持 ${ENV_VAR} 语法引用环境变量，这样可以把敏感信息（API Key）放在环境变量中：
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export OPENAI_API_KEY="sk-proj-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"# config.yaml 中引用
providers:
primary:
api_key: "${OPENAI_API_KEY}" # 启动时自动替换多提供商配置
Hermes Agent 支持同时配置多个提供商，运行时动态切换：
providers:
openai:
name: openai
api_key: "${OPENAI_API_KEY}"
model: gpt-4o
anthropic:
name: anthropic
api_key: "${ANTHROPIC_API_KEY}"
model: claude-sonnet-4-20250514
deepseek:
name: deepseek
api_key: "${DEEPSEEK_API_KEY}"
model: deepseek-chat
base_url: https://api.deepseek.com/v1
openrouter:
name: openrouter
api_key: "${OPENROUTER_API_KEY}"
model: anthropic/claude-sonnet-4
base_url: https://openrouter.ai/api/v1doctor 诊断工具
配置完成后，运行 hermes-agent doctor 进行全面的系统健康检查。这个工具是 Hermes Agent 的"体检中心"，会逐一检查安装、配置、网络、权限等各个环节。
运行诊断
hermes-agent doctor诊断报告示例
╔═══════════════════════════════════════════════════════╗
║ Hermes Agent 诊断报告 ║
║ 2025-05-22 17:30:45 ║
╠═══════════════════════════════════════════════════════╣
║ ║
║ 🔧 系统检查 ║
║ ───────────────────────────────────────────── ║
║ ✓ 操作系统: macOS 14.4 (Apple Silicon) ║
║ ✓ Node.js: v20.11.0 ║
║ ✓ npm: 10.2.4 ║
║ ✓ 安装路径: /usr/local/bin/hermes-agent ║
║ ✓ 安装版本: 1.2.0 ║
║ ✓ 最新版本: 1.2.0 ✅ 已是最新 ║
║ ║
║ 📁 配置文件检查 ║
║ ───────────────────────────────────────────── ║
║ ✓ 配置文件: ~/.config/hermes-agent/config.yaml ║
║ ✓ 配置文件权限: -rw------- (600) ✅ ║
║ ✓ YAML 语法: 解析成功 ║
║ ✓ 必要字段: 全部存在 ║
║ ║
║ 🔑 API 连接检查 ║
║ ───────────────────────────────────────────── ║
║ ✓ OpenAI: 连接正常 (延迟: 45ms) ║
║ 可用模型: gpt-4o, o3-mini, o4-mini ║
║ ✓ Anthropic: 连接正常 (延迟: 120ms) ║
║ 可用模型: claude-sonnet-4, opus ║
║ ✗ DeepSeek: 连接失败 (超时) ║
║ 建议: 检查网络或 API Key ║
║ ║
║ 🌐 网络检查 ║
║ ───────────────────────────────────────────── ║
║ ✓ DNS 解析: 正常 ║
║ ✓ 代理设置: 无代理 ║
║ ✓ SSL 证书: 有效 ║
║ ║
║ 🔒 安全检查 ║
║ ───────────────────────────────────────────── ║
║ ✓ 配置文件权限: 仅所有者可读 ✅ ║
║ ✓ API Key 存储: 环境变量 ✅ ║
║ ⚠ 日志级别: info (生产环境建议改为 warn) ║
║ ║
║ 📊 总结 ║
║ ───────────────────────────────────────────── ║
║ ✅ 通过: 18 ║
║ ⚠ 警告: 1 ║
║ ❌ 失败: 1 ║
║ ║
║ 需要修复的问题: ║
║ 1. DeepSeek 连接失败 —— 请检查网络连通性和 API Key ║
║ 2. 日志级别建议调为 warn 以减少日志输出 ║
║ ║
╚═══════════════════════════════════════════════════════╝诊断项详解
doctor 工具检查以下维度：
| 维度 | 检查项 | 说明 |
|---|---|---|
| 系统 | 操作系统 | 检测 OS 类型和版本 |
| 系统 | Node.js 版本 | 确保版本 >= 18.0 |
| 系统 | 安装完整性 | 检查二进制文件是否完整 |
| 系统 | 版本检查 | 检查是否需要更新 |
| 配置 | 文件存在性 | 配置文件是否存在 |
| 配置 | 文件权限 | 确保 API Key 不会泄露 |
| 配置 | YAML 语法 | 配置文件格式是否正确 |
| 配置 | 必要字段 | 必填配置项是否完整 |
| 网络 | API 连接 | 每个提供商的连接测试 |
| 网络 | 延迟测量 | API 响应延迟 |
| 网络 | 可用模型 | 列出该账户可用的模型 |
| 网络 | DNS/代理/SSL | 基础网络环境检查 |
| 安全 | 文件权限 | 配置文件权限是否安全 |
| 安全 | Key 存储方式 | 是否使用了环境变量 |
诊断修复建议
如果诊断发现问题，doctor 会给出具体修复建议：
# 修复 DeepSeek 连接问题
hermes-agent doctor --fix deepseek
# 自动修复所有可自动修复的问题
hermes-agent doctor --fix-all
# 仅输出 JSON 格式的诊断结果（适合 CI 集成）
hermes-agent doctor --jsonCI 集成示例
doctor 的 --json 输出可以集成到 CI/CD 流程中：
# .github/workflows/hermes-check.yaml
name: Hermes Agent Health Check
on:
schedule:
- cron: '0 8 * * 1' # 每周一早上 8 点
jobs:
health-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Hermes Agent Doctor
run: hermes-agent doctor --json > health-report.json
- name: Check Status
run: |
if [ $(cat health-report.json | jq '.status') != "ok" ]; then
echo "Hermes Agent 健康检查失败！"
cat health-report.json | jq '.issues'
exit 1
fi常见问题排查
问题一：安装后命令找不到
# 检查安装路径
which hermes-agent
# 如果不在 PATH 中，手动添加
export PATH="/usr/local/bin:$PATH"
# npm 安装后找不到命令
npm config get prefix
# 确保 npm prefix 在 PATH 中问题二：API Key 验证失败
# 检查环境变量是否正确设置
echo $OPENAI_API_KEY
# 手动测试 API 连接
curl -s https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200
# 使用 doctor 诊断
hermes-agent doctor问题三：配置文件权限问题
# 查看配置文件权限
ls -la ~/.config/hermes-agent/config.yaml
# 修复权限（仅所有者可读写）
chmod 600 ~/.config/hermes-agent/config.yaml
# doctor 会自动检测权限问题
hermes-agent doctor问题四：网络代理问题
# 如果使用代理，配置代理设置
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
# 或者在配置文件中设置
# config.yaml:
# system:
# proxy: http://proxy.example.com:8080问题五：多配置冲突
# 查看配置加载顺序
hermes-agent config --show-stack
# 输出示例：
# 1. 系统默认: /usr/local/lib/hermes-agent/defaults.yaml
# 2. 全局配置: ~/.config/hermes-agent/config.yaml
# 3. 项目配置: .hermes/config.yaml ← 当前生效
# 4. 环境变量: 运行时覆盖
# 查看当前生效的完整配置
hermes-agent config --show-effectiveDocker 容器部署
对于需要隔离环境或团队共享部署的场景，Hermes Agent 支持 Docker 容器部署。
Dockerfile
FROM node:20-alpine
# 安装 Hermes Agent
RUN npm install -g @nousresearch/hermes-agent
# 创建配置目录
RUN mkdir -p /root/.config/hermes-agent
# 复制配置文件
COPY config.yaml /root/.config/hermes-agent/config.yaml
# 设置工作目录
WORKDIR /workspace
# 启动命令
ENTRYPOINT ["hermes-agent"]docker-compose 配置
version: "3.8"
services:
hermes-agent:
build: .
volumes:
- ./workspace:/workspace
- ./config.yaml:/root/.config/hermes-agent/config.yaml:ro
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
working_dir: /workspace
stdin_open: true
tty: true运行容器
# 构建并启动
docker-compose up -d
# 进入交互式会话
docker-compose exec hermes-agent hermes-agent
# 运行诊断
docker-compose exec hermes-agent hermes-agent doctor总结
本文完整介绍了 Hermes Agent 的安装与配置流程：
- 四种安装方式：一键脚本（最简单）、npm（Node 开发者）、Homebrew（macOS/Linux）、源码编译（高级用户）
- 交互式配置向导：
hermes-agent setup引导你完成提供商选择、API Key 验证、模型选择、权限设置 - 配置文件详解：YAML 格式、环境变量引用、多提供商配置、权限分级
- doctor 诊断工具：一键检查系统、配置、网络、安全四大维度，支持自动修复和 CI 集成
- 常见问题排查：从命令找不到到多配置冲突的解决方案
- Docker 部署：容器化部署方案
核心要点：
- 安装很简单：一条命令搞定，无需复杂依赖
- 配置很直观：交互式向导代替手动编辑
- 诊断很全面：doctor 工具像体检中心，逐一检查各个环节
- 问题可自愈：很多常见问题可以一键自动修复
📌 下篇预告
Provider 配置 —— 20+ 模型自由切换：OpenRouter 聚合路由、Anthropic Claude 全家桶、DeepSeek 高性价比选择、本地 Ollama 部署。当你配置好多个模型提供商后，如何智能选择？如何在不同任务间自动路由？如何实现降级容灾？下一篇将全面解析。