第一章 认识 Hermes Agent

🎯 本章目标： 了解 Hermes Agent 是什么、能干什么、和别的工具有什么区别，判断它是否适合你。

1.1 什么是 Hermes Agent

Hermes Agent 是一个开源的终端 AI 网关，运行在命令行中，充当用户与多个大语言模型之间的统一入口。

与 ChatGPT 网页版、Claude 桌面应用不同，Hermes 完全跑在终端里，提供三种交互方式：

• TUI（终端界面）：带快捷键的交互式界面，适合日常对话和复杂任务
• CLI（命令行模式）：单次问答模式，适合脚本调用和自动化
• Web Dashboard：浏览器管理界面

💡 一句话概括： 一个命令行工具，让你在终端里通过 AI 完成各种任务，不用离开键盘。对话历史和配置文件都在你自己的电脑上（API 调用数据会发到对应模型服务商）。

Hermes 基于 MIT 协议开源，由 Nous Research 维护。安装后所有配置文件位于 ~/.hermes/ 目录下。

⚠️ 重要： Hermes 本身不包含大语言模型。它是一个”中间人”，帮你对接 DeepSeek、OpenAI、Anthropic 等模型服务商的 API。你需要自己准备 API Key（见第四章）。

1.2 谁需要它

如果你属于以下情况，Hermes 很适合你： - 经常在终端里工作，不想切到浏览器去问 AI - 用多个模型（DeepSeek、GPT、Claude），想要一个统一的入口 - 想要把 AI 接入消息平台，让群里也能用（支持 QQ / Telegram / Discord / 企业微信 / 飞书 / 钉钉 等 15+ 平台） - 需要一个轻量级的开源 AI 网关，不想装 Docker 或 Node.js

1.3 对比其他终端 AI 工具

市面上有多个终端 AI 工具，以下是主要对比：

💡 Hermes 的独特优势： 自动多模型路由 + 消息网关(QQ/Telegram/Discord/飞书/钉钉等15+平台) + 轻量纯 Python 安装，这三点是目前任何其他工具都不具备的组合。

1.4 核心功能总览

1.5 系统要求与基础概念

系统要求： - macOS（Intel / Apple Silicon） - Linux（Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Arch / Fedora） - Windows（通过 WSL2，或原生 Windows 早期测试版 PowerShell） - 内存：建议 4GB 以上 - 硬盘：约 500MB（含 Python 环境和依赖） - 网络：需要能访问模型提供商的 API

一些需要了解的概念：

• API Key：模型服务商给你的”密码”，Hermes 用它来调用模型
• Provider：模型提供商，如 DeepSeek、OpenAI
• 虚拟环境：隔离 Python 依赖的沙箱，避免和其他软件冲突
• TUI：终端用户界面，类似 Vim 那种键盘操作界面

第二章 快速上手（5分钟）

🎯 本章目标： 从零开始，5 分钟内让 Hermes 运行起来并回答第一个问题。跟着下面的步骤一步一步做。

2.1 安装 Hermes

打开终端（Terminal），粘贴以下命令之一：

💡 推荐方式（官方一键安装脚本）：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

如果国内下载慢，尝试用镜像：

curl -fsSL https://ghfast.top/raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

备选方式（手动虚拟环境安装，完全可控）：

如果上面的脚本不管用，或者你想完全控制安装过程，一条一条执行以下命令：

# 确保 Python 已安装
python3 --version

#创建虚拟环境
python3 -m venv ~/.hermes-venv

#激活虚拟环境
source ~/.hermes-venv/bin/activate

#安装 Hermes
pip install hermes-agent

2.2 配置第一个 API Key

Hermes 本身是空的，你需要告诉它用哪个模型的 API。

这里以 DeepSeek 为例（国内直连，速度快，价格最低）：

1. 打开 https://platform.deepseek.com/ 注册账号
2. 进入 API Keys 页面，点击”创建 API Key”
3. 复制生成的 Key（一串以 sk- 开头的字符）
4. 在终端执行以下命令把 Key 写入配置文件：

echo 'DEEPSEEK_API_KEY="sk-你的完整key"' > ~/.hermes/.env

⚠️ 如果 .env 已有内容，> 会覆盖。要追加请用 >>，建议先查看：cat ~/.hermes/.env

2.3 运行第一条指令

# 确保在虚拟环境中（终端前面有 (.hermes-venv) 提示）
hermes chat -q "你好，回复hello world就行"

如果看到 AI 的回答（比如”hello world”），安装配置全部成功。 如果提示找不到命令，检查是否在虚拟环境中。

2.4 三个必做检查

以下三个检查来自实操教训。很多人跳过这步，后面浪费几小时。

检查 1：配置快捷命令（避免每次手动激活）

编辑 shell 配置文件，在末尾添加以下函数。注意是函数不是 alias，alias 会导致无限循环！

# 注意：这是函数，不是 alias！alias 会导致无限循环
hermes() {
    source ~/.hermes-venv/bin/activate
    command hermes "$@"
}

然后执行：

source ~/.zshrc   # macOS
#或
source ~/.bashrc  # Linux

现在在任何终端输入 hermes 都会自动激活虚拟环境。

💡 原理说明： 函数 hermes() 先激活 venv，再调用原始 hermes 命令（command hermes 跳过函数）。如果用 alias hermes="source ~/.hermes-venv/bin/activate && hermes" 会导致无限循环——输入 hermes → 激活 → 执行 hermes → 再激活 → 无休止。

检查 2：关终端重开一次再测试

hermes --version

如果正常输出版本号（如 0.9.x），函数配置成功。如果报错，重新检查上一步。

检查 3：确认配置文件已生成

ls ~/.hermes/

应该看到 config.yaml 和 .env 文件。如果没有，手动启动一次 Hermes 再退出：

hermes
然后按 Ctrl+D 退出

检查 4（可选）：运行诊断工具

hermes doctor

如果所有检查通过，说明 Hermes 已就绪。

第三章 安装指南（全平台）

🎯 本章是第二章的完整版。如果第二章已经装好，跳过本章。

3.1 环境准备

通用依赖： - Python 3.10 ~ 3.12（推荐 3.11） - pip（Python 包管理器） - Git（可选，用于安装高级功能） - 网络连接

检查方法：

python3 --version
pip3 --version

3.2 macOS 安装

步骤 1：安装 Homebrew（如未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

步骤 2：安装 Python

brew install python@3.11

步骤 3：创建虚拟环境并安装

python3.11 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

步骤 4：配置快捷命令

编辑 ~/.zshrc，在文件末尾添加：

# Hermes 自动激活函数（用函数，不用 alias）
hermes() {
    source ~/.hermes-venv/bin/activate
    command hermes "$@"
}

source ~/.zshrc
hermes --version

3.3 Linux 安装

Ubuntu / Debian：

sudo apt update
sudo apt install python3 python3-pip python3-venv git -y

python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

CentOS / Rocky：

sudo yum install python3 python3-pip git -y
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

配置快捷命令（Linux 用 bash）：

编辑 ~/.bashrc，添加函数：

hermes() {
    source ~/.hermes-venv/bin/activate
    command hermes "$@"
}

source ~/.bashrc

3.4 Windows 安装（WSL2）

⚠️ Hermes 不支持原生 Windows，必须在 WSL2 环境中运行（原生 Windows 早期测试版 PowerShell 正在开发中）

步骤 1：安装 WSL2

以管理员身份打开 PowerShell，执行：

wsl --install -d Ubuntu

重启电脑。首次启动 WSL 时需要设置 Linux 用户名和密码。

如果 wsl --install 无效，先开启 WSL 功能：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

步骤 2：进入 WSL 并安装 Hermes

# 更新包列表
sudo apt update
sudo apt install python3 python3-pip python3-venv git -y

#创建虚拟环境
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate

#安装 Hermes
pip install hermes-agent

配置快捷命令（同 Linux）：

编辑 ~/.bashrc，添加函数，然后 source ~/.bashrc。（和上节 Linux 操作一样）

3.5 验证安装完成

hermes --version    # 应该输出版本号
hermes --help       # 应该输出帮助信息
ls ~/.hermes/       # 应该看到 config.yaml

如果以上都正常，安装成功。

第四章 配置详解

🎯 本章教你怎么让 Hermes “有脑子”——配置 API Key 连接大模型。

4.1 选择模型提供商

💡 国内用户建议： 优先用 DeepSeek（直连+便宜），有境外模型需求时再配代理或中转。

4.2 获取 API Key 详细步骤

以 DeepSeek 为例：

1. 打开 https://platform.deepseek.com/
2. 点击右上角”登录/注册”（支持手机号）
3. 注册成功后，进入控制台
4. 左侧菜单找到 “API Keys”
5. 点击”创建 API Key”，取名（如 “hermes”）
6. 复制生成的 Key（以 sk- 开头）
7. 立即保存！ 关闭页面后将无法再次查看完整 Key

⚠️ Key 泄露处理： 如果不小心把 Key 发到公开地方了，立即去平台删除并重新生成。检查是否有异常调用记录。

4.3 配置到 Hermes（三种方式）

方式一：环境变量（临时测试）

export DEEPSEEK_API_KEY="sk-你的完整key"
hermes

每次新开终端都要重新设置。仅用于快速测试 Key 是否有效。

方式二：.env 文件（推荐） ⭐

echo 'DEEPSEEK_API_KEY="sk-你的完整key"' > ~/.hermes/.env

> ⚠️ 如果 .env 已有内容，`>` 会覆盖。要追加请用 `>>`，建议先查看：`cat ~/.hermes/.env`
**方式三：直接写入 config.yaml（不推荐）**

```bash
hermes config set providers.deepseek.api_key "sk-你的完整key"

不推荐。如果分享配置文件，Key 就暴露了。

配置后测试：

hermes chat -q "你好，配置成功了吗"

有回答就是成功了。

4.4 配置多个提供商

这是 Hermes 的核心优势之一——同时配置多个模型，按需切换。

步骤 1：在 .env 中添加多个 Key

cat >> ~/.hermes/.env << 'EOF'
DEEPSEEK_API_KEY="sk-你的deepseek-key"
OPENAI_API_KEY="sk-你的openai-key"
ANTHROPIC_API_KEY="sk-ant-你的anthropic-key"
EOF

步骤 2：在 config.yaml 中定义提供商

编辑 ~/.hermes/config.yaml，内容如下：

model:
  default: deepseek-chat
  provider: deepseek

providers:
  deepseek:
    base_url: "https://api.deepseek.com/v1"
  openai:
    base_url: "https://api.openai.com/v1"
  anthropic:
    base_url: "https://api.anthropic.com/v1"

步骤 3：切换模型

在 TUI 中输入：

/model deepseek-chat
/model gpt-4o-mini

4.5 国内网络配置

这是中文用户遇到最多的问题。以下方案覆盖 95% 场景。

场景一：有代理工具（Clash / v2ray / Surge）

在 .env 中添加：

HTTP_PROXY="http://127.0.0.1:7890"
HTTPS_PROXY="http://127.0.0.1:7890"

场景二：用国内中转服务（无需代理）

如果你不想配置代理，可以用国内 API 中转站：

providers:
  openai:
    base_url: "https://你的中转地址/v1"

场景三：网络连通性测试

# 测试 DeepSeek（国内直连，应该通）
curl -s -o /dev/null -w "%{http_code}" https://api.deepseek.com/v1

#测试 OpenAI（需要代理或中转）
curl -s -o /dev/null -w "%{http_code}" https://api.openai.com/v1

200 或 401 = 通；000 = 不通

第五章 日常使用

🎯 学会日常操作，包括快捷键、命令和 Dashboard。

5.1 TUI 界面与快捷键

启动：在终端输入 hermes（不带任何参数）

界面布局：

快捷键表：

5.2 CLI 命令大全

所有命令在 TUI 输入框中以 / 开头：

|| 命令 | 功能 | 示例 | ||——|——|——| || /help | 查看所有命令 | /help | || /model <名称> | 切换模型 | /model deepseek-chat | || /new | 新对话 | /new | || /retry | 重新发送上一条消息 | /retry | || /undo | 撤销上一轮对话 | /undo | || /save | 保存对话 | /save | || /export | 导出对话 | /export chat.txt | || /config | 查看配置 | /config | || /stats | 使用统计 | /stats | || /tools | 列出工具集 | /tools | || /skill <名称> | 加载技能到当前会话 | /skill code-review | || /skills | 搜索和安装社区技能 | /skills | || /clear | 清屏 | /clear | || /compress | 手动压缩上下文 | /compress | || /verbose | 切换详细输出模式 | /verbose |

5.3 Web Dashboard

⚠️ Dashboard 需要额外安装：pip install "hermes-agent[web]"。如果没装，先执行下面第一行命令。

pip install "hermes-agent[web]"
hermes dashboard

浏览器打开 http://127.0.0.1:9119。提供：

• 对话管理：查看、搜索、删除历史
• 模型监控：调用次数、Token 消耗统计
• 配置管理：界面中修改设置
• 日志查看：排查问题第一入口

💡 TUI 出问题时，Dashboard 查日志是最快的排查方式。

5.4 对话管理与历史

Hermes 自动保存所有对话。

# 查看历史目录
ls ~/.hermes/sessions/

• /new 开始新对话（老对话自动保存）
• hermes sessions list 查看所有会话
• hermes sessions browse 交互式浏览和恢复会话
• hermes sessions delete <ID> 删除指定会话
• Dashboard 可搜索历史
• 对话存储在 ~/.hermes/sessions/（SQLite），可以用 hermes sessions stats 查看统计

💡 历史太多影响性能时，删除 ~/.hermes/sessions/ 下不需要的对话即可。默认保留最近 30 天。

第六章 实战场景（付费核心价值）

🎯 本章是整本教程最有价值的部分。 5 个真实场景，每个都是可以直接复用的实操案例。

场景 1：批量文件处理

场景： 下载了一个文件夹，里面有 200 张 .jpg 图片，需要全部压缩到 800px 宽、改成 .webp 格式、文件名加日期前缀。

手动操作： 打开 Photoshop 一张一张改 → 至少 2 小时

用 Hermes： 在 TUI 中输入以下指令：

帮我在当前目录写一个脚本：
1. 扫描当前目录所有 .jpg 文件
2. 每张压缩至宽度 800px
3. 转成 .webp 格式
4. 文件名加日期前缀：20260509_原文件名.webp
5. 处理完打印统计

我用 Python 3，Pillow 已安装

结果： Hermes 生成完整 Python 脚本，确认后直接执行。200 张图的处理脚本 30 秒搞定。

💡 价值点： 不用记住 PIL/Pillow 的 API 参数，不用查 resize 和 save 的语法。自然语言直接出结果。

场景 2：代码审查与改进

场景： 写了一个 Python 函数，但总觉得有 bug 和性能问题。

在 TUI 中输入：

请审查以下 Python 函数，指出：
1. 安全漏洞
2. 性能瓶颈
3. 代码质量问题
4. 给修复建议

def get_user_data(user_id):
    conn = sqlite3.connect('users.db')
    cursor = conn.cursor()
    query = "SELECT * FROM users WHERE id = " + str(user_id)
    cursor.execute(query)
    data = cursor.fetchone()
    conn.close()
    return data

结果： Hermes 会指出 SQL 注入风险、连接未用上下文管理器、错误处理缺失，并给出修复后的完整代码。

💡 价值点： AI 代码审查可以替代第二双人眼，且 7x24 可用。

场景 3：Git 操作助手

场景： 提交历史搞乱了，需要回退到某个 commit 但保留工作区文件。

在 TUI 中输入：

我的 Git 历史：
A → B → C → D（当前 HEAD）

我需要：
1. 回退到 commit B
2. 保留 C 和 D 的工作区文件
3. 把 C 和 D 的改动整理成新的 commit

帮我写出每一步要执行的 Git 命令，附带解释

结果： Hermes 给出精确的 git reset --soft、git stash、git commit 命令序列。

💡 价值点： 不用背 Git 命令参数。日常高频 Git 操作（rebase、cherry-pick、冲突解决）Hermes 直接帮你写。

场景 4：日志分析与排错

场景： 服务器日志文件里有一百万行，要找出 5xx 错误的分布规律。

# 直接把日志喂给 Hermes
cat server.log | hermes -z "
分析这份 Nginx 访问日志，找出：
1. 5xx 错误占比多少
2. 按 URL 统计错误最多的是哪 5 个
3. 按时间段统计：哪些时间段错误率最高
4. 给我修复建议

日志格式：IP 时间 方法 URL 状态码 大小
"

场景 5：文档与脚本生成

场景： 要为一个开源项目写 README，还包括自动部署脚本。

在 TUI 中输入：

帮我生成以下文件：

1. README.md - 一个 Python 命令行工具的说明文档
   项目名：logwatcher
   功能：实时监控日志文件变化，匹配关键词发通知
   安装：pip install logwatcher
   作者：xxx

2. deploy.sh - 自动化部署脚本
   - 从 Git 拉取最新代码
   - 安装依赖
   - 重启 systemd 服务
   - 检查服务状态

README 要包括：项目介绍、安装、使用示例、配置说明、许可证

结果： 2 个完整文件，直接复制就能用。

💡 价值点： 写文档是最费时间但 AI 做得最好的事之一。

第七章 技能系统

7.1 什么是技能

技能（Skills）是 Hermes 的特色功能——把常用的 Prompt 封装成可复用的命令。

举个例子： 你经常做代码审查，每次都要写”请审查这段代码，关注安全性、性能…“。把它做成技能之后，只需要说”用 code-review 技能审查以下代码”。

7.2 内置技能查看

ls ~/.hermes/skills/

每个技能是一个目录，包含一个 SKILL.md 文件。

如何使用技能：

在 TUI 对话中直接提及技能名称即可激活。有两种方式：

方式一：自然语言引用

用 code-review 技能审查以下代码：

方式二：在 Prompt 中指定技能名

使用 translate 技能：把下面这段翻译成中文

💡 Hermes 会扫描对话中的技能名称，自动匹配对应的 SKILL.md 定义。不需要手动”加载”技能。

7.3 创建自定义技能（含 3 套模板）

模板 1：代码审查技能

mkdir -p ~/.hermes/skills/code-review

创建 ~/.hermes/skills/code-review/SKILL.md，内容如下：

---
name: code-review
description: "审查一段代码，指出安全问题、性能问题、代码质量问题"
version: 1.0.0
---

#Code Review Skill

收到代码审查请求时，按以下维度分析：

1. **安全性（高优先级）**：SQL 注入、XSS、认证漏洞、命令注入
2. **性能**：不必要的循环、大对象创建、I/O 瓶颈、缓存缺失
3. **可维护性**：命名规范、注释完善度、函数长度、重复代码
4. **健壮性**：边界情况、错误处理、类型安全、资源泄露
5. **兼容性**：Python 版本兼容、跨平台问题

每个问题标注：严重程度（高/中/低）+ 具体修复代码。

模板 2：翻译技能

mkdir -p ~/.hermes/skills/translate

创建 ~/.hermes/skills/translate/SKILL.md：

---
name: translate
description: "将英文技术文档翻译成中文，保留代码块和格式"
version: 1.0.0
---

#Translate Skill

翻译技术文档时遵循以下原则：

1. 保留所有代码块不变
2. 技术术语首次出现时标注英文原文（如：网关 Gateway）
3. 保持 Markdown 格式不变
4. 段落结构保持原样
5. 表格格式保留
6. 链接地址不翻译

输出格式：翻译后的完整文档。

模板 3：命令生成技能

mkdir -p ~/.hermes/skills/command-gen

创建 ~/.hermes/skills/command-gen/SKILL.md：

---
name: command-gen
description: "根据自然语言描述生成终端命令，附带解释"
version: 1.0.0
---

#Command Generator Skill

用户描述一个终端操作需求，你生成对应的命令。

分析维度：
1. 用户的需求是什么
2. 需要哪些命令组合
3. 命令的作用（简短解释）
4. 安全注意事项（如果涉及 rm、dd、format 等危险操作，加入警告）

输出格式：

命令

具体的命令

说明

每行命令的作用

使用技能：

在 TUI 中输入：

用 code-review 技能审查以下 Python 代码：

def save_user(name, email):
    conn = sqlite3.connect('users.db')
    sql = f"INSERT INTO users VALUES('{name}', '{email}')"
    conn.execute(sql)
    conn.commit()
    conn.close()

7.4 进阶功能：Subagent 与 Cron

以下三个功能是 Hermes 的高级用法，入门后可以逐步尝试。

Subagent（多代理并行）：

Hermes 可以一次性派多个”子代理”并行执行任务。

请并行执行以下任务：
1. 读取 src/main.py 总结其功能
2. 检查 test/ 目录的测试覆盖率
3. 搜索 TODO 和 FIXME 注释

Cron 定时任务：

让 Hermes 定时自动执行任务：

# 每天早上 9 点自动检查服务器日志
hermes cron create "0 9 * * *" "检查 /var/log/system.log 最近一小时的错误"

#每 30 分钟检查一次磁盘空间
hermes cron create "30m" "检查磁盘空间，如果超过 80% 则告警"

MCP（外部工具集成）：

MCP（Model Context Protocol）是让 Hermes 连接外部数据和工具的开放标准。你可以通过 MCP 让 Hermes 读取数据库、操作文件、调用 Web API。

💡 MCP 配置相对高级，入门阶段可以跳过。需要时查阅官方文档：https://github.com/modelcontextprotocol

Skills Hub 技能市场：

除了自己创建技能，你也可以从社区安装现成的技能：

# 浏览社区热门技能
hermes skills browse

#搜索特定技能
hermes skills search 代码审查

#安装社区技能
hermes skills install code-review

#查看已安装的技能
hermes skills list

💡 社区技能中心在 skills.sh，涵盖代码审查、翻译、命令行生成、Git 操作等多种场景。安装后自动可用，和自定义技能用法一样。

第八章 进阶技巧（新手不知道的）

🎯 官方文档不会仔细教的实操经验。建议先通读再按需查阅。

8.1 Python 虚拟环境管理

为什么必须用虚拟环境？

很多人直接 pip install hermes-agent 全局安装，遇到各种问题：

• error: externally-managed-environment（Linux 新系统禁止全局 pip）
• 升级系统 Python 后 Hermes 无法启动
• 和其他 Python 项目依赖冲突

升级 Hermes：

有两种方式，推荐使用第一种：

💡 推荐方式（一键升级）： 直接运行 hermes update，自动完成升级。如果升级后出了问题，可以用 hermes doctor --fix 自动修复。

hermes update
hermes --version

备选方式（手动升级，可控性更强）：

source ~/.hermes-venv/bin/activate
pip install --upgrade hermes-agent
hermes --version

卸载重装：

# 先备份配置（重要！）
cp -r ~/.hermes ~/.hermes.backup

#删除虚拟环境
rm -rf ~/.hermes-venv

#重新创建
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

8.2 推荐模型组合方案（省钱策略）

以下方案基于实际使用经验。选一个适合你的预算的：

省钱型配置参考（日常问答和编码完全够用）：

在 ~/.hermes/config.yaml 中配置：

model:
  default: deepseek-chat
  provider: deepseek

providers:
  deepseek:
    base_url: "https://api.deepseek.com/v1"

均衡型配置参考（推荐大多数开发者）：

model:
  default: deepseek-chat
  provider: deepseek

router:
  mode: auto
  rules:
    - pattern: ".*(编码|bug|重构|代码|review).*"
      model: claude-sonnet-4-5
      provider: anthropic
    - pattern: ".*"
      model: deepseek-chat
      provider: deepseek

providers:
  deepseek:
    base_url: "https://api.deepseek.com/v1"
  anthropic:
    base_url: "https://api.anthropic.com/v1"

8.3 API Key 安全与测试

测试 Key 是否有效（不用启动 Hermes）：

# 测试 DeepSeek Key
curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer 你的DeepSeek Key" \
  | head -c 200

#测试 OpenAI Key
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer 你的OpenAI Key" \
  | head -c 200

返回 JSON 数组说明 Key 有效。返回 401 说明 Key 无效。

最佳实践：

• 每个服务单独申请 Key，设置备注方便追踪
• 定期轮换（每 3-6 个月重新生成一次）
• 不要把 Key 写死在代码或配置文件中提交到 Git
• Key 泄露了：立即删除 → 重新生成 → 更新 .env

8.4 版本升级与配置迁移

更新 Hermes：

source ~/.hermes-venv/bin/activate
pip install --upgrade hermes-agent

配置迁移（换电脑）：

需要迁移的文件： 1. ~/.hermes/config.yaml 2. ~/.hermes/.env 3. ~/.hermes/skills/（自定义技能）

不需要迁移： 1. ~/.hermes/sessions/（除非要保留） 2. ~/.hermes-venv/（在新电脑重新创建）

迁移步骤：

# 旧电脑打包
tar czf hermes-config.tar.gz ~/.hermes/config.yaml ~/.hermes/.env ~/.hermes/skills/

#传到新电脑后安装 Hermes（按第三章），然后解压
tar xzf hermes-config.tar.gz -C ~/

8.5 ~/.hermes/ 目录结构详解

~/.hermes/
├── config.yaml          # 主配置文件（模型、Provider、路由）
├── .env                 # 环境变量（API Key、代理设置）
├── auth.json            # OAuth 令牌缓存
├── SOUL.md              # AI 人格定义（可选，自定义助手性格）
├── sessions/            # 对话历史（SQLite）
├── skills/              # 自定义技能
│   └── <技能名>/
│       └── SKILL.md
├── cron/                # 定时任务配置
├── logs/                # 运行日志（排查问题）
│   ├── agent.log
│   └── errors.log
└── memory/              # 持久记忆（不要手动改）
    └── *.json

重要操作提醒：

• 不要手动修改 memory/ 目录下的文件
• 可以安全删除 sessions/ 下的对话记录（不会影响配置）
• 建议备份 config.yaml 和 .env
• 日志文件 logs/agent.log 是排查问题的第一入口。如果遇到异常，先看这里

8.6 消息网关接入指南

消息网关是 Hermes 的一大特色——你可以把 AI 助手接入 QQ / Telegram / Discord / 企业微信 / 飞书 / 钉钉 等 15+ 平台，让群成员直接在聊天软件里使用 AI。

支持的平台对比：

QQ Bot（中国区特色功能）

QQ Bot 是 Hermes 在中国区独有的差异化功能。其他终端 AI 工具要么不支持 QQ，要么配置极其复杂。

前置条件： - 一个 QQ 号（用于创建机器人） - 一个 QQ 机器人 AppID（在 QQ 开放平台申请） - Hermes 已正确安装配置

开通 QQ 机器人步骤：

1. 打开 https://q.qq.com/，登录你的 QQ
2. 创建机器人应用，获取 AppID 和 AppSecret
3. 配置到 Hermes 的消息网关

在 ~/.hermes/config.yaml 中添加：

# 在 config.yaml 中添加
gateway:
  qqbot:
    app_id: "你的AppID"
    app_secret: "你的AppSecret"

4. 启动网关（在前台运行）：

hermes gateway run

Telegram Bot

前置条件： - 一个 Telegram 账号 - 在 @BotFather 创建机器人，获取 Bot Token - Hermes 已正确安装配置

配置方法：

# 在 config.yaml 中添加
gateway:
  telegram:
    bot_token: "你的Bot Token"

启动网关（前台运行）：

hermes gateway run

Discord Bot

前置条件： - 一个 Discord 账号 - 在 Discord Developer Portal 创建应用，获取 Bot Token - Hermes 已正确安装配置

配置方法：

# 在 config.yaml 中添加
gateway:
  discord:
    bot_token: "你的Bot Token"

启动网关（前台运行）：

hermes gateway run

💡 配置一次，所有平台同时生效： config.yaml 中配置了 qqbot + telegram + discord 后，一条 hermes gateway run 命令同时启动所有网关。Hermes 还支持 Slack、WhatsApp、Signal、飞书、钉钉、企业微信等 15+ 消息平台，配置方式类似。

💡 QQ Bot 是国内用户最推荐的方式： 无需代理、中文原生、企业微信群场景丰富。

8.7 语音模式（Voice Mode）

Hermes 支持语音对话——你可以直接用语音提问，Hermes 语音回复。

# 先安装语音依赖
pip install "hermes-agent[voice]"

#在 TUI 中开启语音
输入 /voice on

💡 需要麦克风权限。目前支持 macOS 和 Linux。

8.8 更多实用命令

# 查看运行日志（排查问题首选）
hermes logs

#一键备份配置
hermes backup

#恢复备份
hermes import ~/hermes-backup-xxx.zip

#生成诊断报告（分享给他人求助）
hermes dump

第九章 常见问题与排错

9.1 安装问题

Q：command not found: pip3

A：Python 未安装或 pip 未包含。回到第三章按你的系统指引安装 Python。

Q：error: externally-managed-environment

A：Linux 新版本的常见问题。你在系统全局 Python 中安装包。解决方法：

# 方案一（推荐）：使用虚拟环境
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

#方案二（临时测试用）
pip install --break-system-packages hermes-agent

Q：安装后 hermes 命令找不到

A：pip 安装路径没在 PATH 中，或者函数没配好。

# 先确认安装位置
python3 -m pip show hermes-agent | grep Location

#然后检查函数配置
cat ~/.zshrc | grep "hermes()"
#或者
cat ~/.bashrc | grep "hermes()"

Q：Windows 上直接安装报错

A：Hermes 推荐在 WSL2 中运行，原生 Windows 早期测试版（PowerShell）正在开发中。回到第三章 3.4 节。

9.2 配置问题

Q：API Key 认证失败或 401 错误

A：按顺序排查：

1. Key 复制完整了吗（包含 sk- 前缀）
2. 用 curl 直接测试 Key（见 8.3 节）
3. .env 文件格式正确吗（没有多余空格、引号完整）
4. .env 在 ~/.hermes/ 目录下吗（不是用户根目录）
5. config.yaml 中 base_url 拼写正确吗

# 快速检查
cat ~/.hermes/.env

Q：切换模型后报 “provider not found”

A：你在 .env 中配了 Key，但 config.yaml 中没有定义对应的 providers 配置。检查是否有完整的 providers 定义。

Q：启动后 “no providers configured”

A：完全没有配任何 API Key。回到第四章。

也可以运行 hermes doctor 自动诊断问题，然后 hermes doctor --fix 尝试自动修复。

9.3 运行问题

Q：对话速度很慢

A：慢通常是网络问题：

1. 用 curl 测 API 响应时间（8.3 节）
2. 如果是境外模型，检查代理是否正常
3. 切换国内模型（DeepSeek）对比速度
4. 公共 API 池的响应时间可能不稳定

Q：TUI 显示乱码

A：终端字体不支持中文。

• macOS：终端 > 设置 > 描述文件 > 文本 > 字体，选 SF Mono 或 PingFang
• Linux：安装中文字体包：

sudo apt install fonts-noto-cjk

Q：对话记录丢失

A：检查三点： 1. ~/.hermes/sessions/ 目录是否存在 2. 是否有读写权限 3. 磁盘空间是否充足

如果文件存在但 Hermes 不显示，重启 Hermes。

Q：升级后配置不兼容

# 恢复备份
cp ~/.hermes.backup/config.yaml ~/.hermes/config.yaml

#或看日志
tail -50 ~/.hermes/logs/agent.log

Q：占用内存过高

Hermes 本身约 50-100MB。如果偏高： - 对话历史过长 → /new 开始新对话 - 同时运行了 Dashboard → 增加约 50MB - 系统内存不足 → 建议 4GB+

9.4 网络问题（国内用户）

Q：DeepSeek 连接超时

A：偶尔网络波动，重试一次。持续超时检查：

ping api.deepseek.com
curl -s -o /dev/null -w "%{http_code}" https://api.deepseek.com/v1

Q：境外模型通不了

A：检查： 1. 代理工具是否运行 2. 代理端口和 .env 配置一致吗 3. 代理支持 HTTPS 吗

Q：代理配了还是不通

A：按顺序排查：

1. 确认代理工具（Clash / v2ray / Surge）正在运行
2. 检查 .env 中的端口号是否和代理工具一致（Clash 默认 7890，v2ray 默认 10808）
3. 用 curl 测试代理是否生效：

# 测试代理是否工作（替换为你的代理地址）
curl -x http://127.0.0.1:7890 -s -o /dev/null -w "%{http_code}" https://api.openai.com/v1
返回 200 或 401 = 代理通；000 = 代理不通

4. 检查代理是否支持 HTTPS（有些免费代理只支持 HTTP）
5. 如果代理工具本身需要登录认证，在代理地址中加上用户名密码：http://user:pass@127.0.0.1:7890

💡 最彻底的排查方法：关掉代理，用国内直连模型（DeepSeek）确认 Hermes 本身正常，再排查网络问题。

附录：命令速查表

# =====================
#安装与验证
#=====================
pip install hermes-agent
pip install "hermes-agent[web]"
hermes --version
hermes --help
hermes doctor
hermes doctor --fix

#=====================
#启动方式
#=====================
hermes               # 启动 TUI 交互界面
hermes chat "你的问题"  # 单次问答模式
hermes chat -z "问题"   # 从管道输入
hermes dashboard     # Web 管理界面
hermes setup         # 初始化设置向导

#=====================
#TUI 内斜杠命令
#=====================
/help                # 查看所有命令
/model <名称>        # 切换模型
/new                 # 开始新对话
/retry               # 重新发送上一条
/undo                # 撤销最后一轮
/save                # 保存当前对话
/export <文件名>     # 导出对话
/config              # 查看当前配置
/stats               # 使用统计
/tools               # 列出可用工具
/skill <名称>        # 加载技能
/skills              # 搜索社区技能
/clear               # 清屏
/compress            # 手动压缩上下文
/verbose             # 切换详细输出

#=====================
#配置管理
#=====================
hermes config set model.default deepseek-chat
hermes config set model.provider deepseek
hermes config set model.temperature 0.1
hermes config --edit   # 用编辑器打开
hermes config show     # 查看完整配置

#=====================
#模型切换命令
#=====================
/model deepseek-chat          # 日常对话
/model deepseek-v4-flash      # 简单任务
/model claude-sonnet-4-5      # 深度分析
/model gemini-2.5-pro         # 大神模型
/model gpt-5.1-all            # 真神模型

#=====================
#环境变量（.env 文件）
#=====================
OPENAI_API_KEY=sk-...          # OpenAI 相关模型
ANTHROPIC_API_KEY=sk-ant-...   # Claude 系列
DEEPSEEK_API_KEY=sk-...        # DeepSeek
GOOGLE_API_KEY=...             # Gemini
HTTP_PROXY=http://127.0.0.1:7890    # 代理（国内用户）
HTTPS_PROXY=http://127.0.0.1:7890   # 代理（国内用户）

#=====================
#排错命令
#=====================
hermes doctor                # 自动诊断
hermes doctor --fix          # 自动修复
tail -50 ~/.hermes/logs/agent.log   # 查看日志
cat ~/.hermes/.env           # 检查 API Key
cat ~/.hermes/config.yaml    # 检查配置
ls ~/.hermes/sessions/       # 对话记录
curl -x http://127.0.0.1:7890 -s -o /dev/null -w "%{http_code}" https://api.openai.com/v1  # 测代理