Hermes Agent 完整指南——从零安装到微信接入

版本: Hermes Agent v0.18.0
平台: Windows 10/11 + DeepSeek API
日期: 2026-07-06
作者: 李享

目录

一、Hermes Agent 是什么

Hermes Agent 是由 Nous Research 开发的开源 AI 代理框架，类似于 Claude Code / OpenAI Codex，但完全开源且支持多模型、多平台。

对比维度 Hermes Agent Claude Code OpenAI Codex
开源 ✅ 完全开源 ❌ 闭源 ❌ 闭源
模型选择 20+ 提供商自由切换 仅 Claude 仅 OpenAI
消息平台 微信/Telegram/Discord 等 无 无
本地运行 ✅ ✅ 云端
技能系统 ✅ 自我进化 ❌ ❌

二、核心特性一览

2.1 自我进化的技能系统 (Skills)

AI 可以从任务中学习并永久保存技能，下次遇到类似问题自动调用。这是 Hermes 最亮眼的能力——越用越聪明。

2.2 持久化记忆

基于 SQLite 数据库存储对话历史和用户偏好，跨会话保留上下文，真正”记住”你的习惯。

2.3 跨平台消息网关

支持 20+ 消息平台：

平台 状态
微信 (WeChat) ✅ 通过 iLink Bot API
Telegram ✅
Discord ✅
Slack ✅
Mattermost ✅
Signal ✅

2.4 模型提供商无关

支持切换 20+ 模型服务商（OpenAI、Anthropic、DeepSeek、OpenRouter 等），一个框架，任意模型。

2.5 四大使用界面

  • CLI（命令行） — 终端直接交互
  • TUI（终端 UI） — 终端图形界面
  • Desktop（桌面应用） — Electron 桌面客户端
  • Web Dashboard — 浏览器管理面板

2.6 定时任务 (Cron)

内建定时任务引擎，可设置每日早报、定时备份、自动检查等自动化流程。

2.7 丰富的工具集

工具 能力
terminal 执行终端命令
file 读写文件、代码搜索
browser 网页浏览和自动化
web 网络搜索和信息提取
todo 任务规划和追踪
code_execution 沙箱代码执行

三、安装部署教程

3.1 系统要求

项目 最低要求
操作系统 Windows 10 (21H2+) 或 Windows 11
内存 4GB+
磁盘空间 2GB+
网络 能访问互联网
权限 管理员权限（安装时）

3.2 前置准备

注册 DeepSeek 开放平台账号并获取 API Key：

  1. 访问 DeepSeek 开放平台
  2. 注册/登录账号
  3. 进入「API Keys」页面，点击「创建 API Key」
  4. 复制生成的密钥（格式：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）

3.3 一键安装

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

1
2
3
4
5
# 步骤1：绕过 PowerShell 执行策略限制
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

# 步骤2：使用国内镜像安装
irm https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

国内用户注意：如果 ghfast.top 不可用，可使用以下备用镜像：

1
2
3
4
# 备用1
irm https://ghproxy.cn/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
# 备用2
irm https://mirror.ghproxy.com/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

脚本会自动完成（约 5-10 分钟）：

1
2
3
4
5
6
[OK] 安装 Python 3.11.15 (via uv)
[OK] 安装 Node.js、ripgrep、ffmpeg
[OK] 克隆 hermes-agent 仓库
[OK] 创建 Python 虚拟环境
[OK] 安装所有依赖
[OK] 配置 PATH 环境变量

安装完成后关闭当前终端，新开一个窗口使 PATH 生效。

3.4 配置 DeepSeek API

步骤1：写入 API 密钥

1
2
# 用记事本打开 .env 文件
notepad "$env:LOCALAPPDATA\hermes\.env"

在文件最开头添加：

1
2
3
4
5
6
# =============================================================================
# LLM PROVIDER (DeepSeek - 主模型)
# =============================================================================
OPENAI_API_KEY=你的DeepSeek-API-Key
OPENAI_BASE_URL=https://api.deepseek.com
DEEPSEEK_API_KEY=你的DeepSeek-API-Key

步骤2：修改模型配置

1
notepad "$env:LOCALAPPDATA\hermes\config.yaml"

找到 model: 部分，修改为：

1
2
3
4
model:
  default: "deepseek-chat"
  provider: "custom"
  base_url: "https://api.deepseek.com"

原配置三处均需修改：default 为 deepseek-chat、provider 为 custom、base_url 为 DeepSeek 地址。

步骤3：设置数据目录（可选）

1
2
3
4
5
# 设置 HERMES_HOME 到指定目录
setx HERMES_HOME "D:\Program Files (x86)\ailuo\Hermes-Agent"

# 创建目录符号链接（管理员权限）
cmd /c mklink /J "D:\Program Files (x86)\ailuo\Hermes-Agent" "%LOCALAPPDATA%\hermes"

3.5 验证安装

1
2
hermes --version    # 输出: Hermes Agent v0.18.0 (2026.7.1)
hermes doctor       # 运行诊断，确认各项检查通过

首次对话测试：

1
hermes

在 CLI 中输入：

1
你好，请用中文回复。介绍一下你能做什么？

正常收到 DeepSeek 回复说明安装成功！

四、CLI 命令大全与使用指南

4.1 启动与退出

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 基本启动
hermes

# 指定模型
hermes --model deepseek-chat

# 指定工作目录
hermes --cwd D:\my-project

# 查看帮助
hermes --help

# 诊断
hermes doctor

退出方式：输入 /exit、/q、/quit 或按 Ctrl+C。

4.2 会话管理

命令 说明
/new 开始新对话（清空上下文）
/reset 重置当前会话
/search <关键词> 搜索历史对话
/sessions 查看最近会话列表
/resume <session_id> 恢复指定会话

4.3 模型控制

命令 说明
/model 列出所有可用模型
/model deepseek-chat 切换为通用模型
/model deepseek-reasoner 切换为推理模型
/provider <提供商> 切换 API 提供商
/reasoning show 显示推理过程
/reasoning hide 隐藏推理过程

可用 DeepSeek 模型：

模型 适用场景
deepseek-chat 日常对话、代码生成、文档写作
deepseek-reasoner 深度推理、复杂逻辑、数学运算
deepseek-v4-pro 高级编码、复杂任务
deepseek-v4-flash 快速经济、批量处理

4.4 工具管理

命令 说明
/tools 列出可用工具及状态
/tools enable <工具> 启用某工具
/tools disable <工具> 禁用某工具
/verbose 切换详细输出模式

4.5 显示与个性化

命令 说明
/personality 切换 AI 人格
/skin <主题> 切换终端主题（default/mono/slate）
/busy interrupt 忙时 Enter = 打断当前任务
/busy queue 忙时 Enter = 排队等待
/busy steer 忙时 Enter = 注入指令
/bell 开启/关闭任务完成提示音

4.6 文件与图片

命令 说明
/image <路径> 在对话中附加图片
/file <路径> 在对话中附加文件

4.7 技能系统

命令 说明
/skills 查看已学的技能列表
/skill <技能名> 加载指定技能

4.8 定时任务

命令 说明
/cron list 查看所有定时任务
/cron add 添加定时任务
/cron remove 删除定时任务

4.9 系统命令

命令 说明
/doctor 运行系统诊断
/update 检查并更新
/help 显示帮助

4.10 日常使用场景

代码开发辅助：

1
2
3
4
5
6
7
8
cd D:\my-project
hermes

# 然后可以这样对话：
# "帮我写一个 Flask REST API 接口"
# "分析这段代码的性能瓶颈"
# "修复这个 bug：..."
# "给这个项目写单元测试"

文档写作：

1
2
3
"请帮我写一份关于XXX的技术方案文档"
"根据这个项目的代码生成 API 文档"
"把这段英文文档翻译成中文"

数据分析：

1
2
"分析 data.csv 中的数据趋势"
"帮我写一个 Python 脚本处理这些 JSON 文件"

五、接入个人微信

5.1 工作原理

Hermes 通过腾讯官方 iLink Bot API 连接个人微信，架构如下：

1
2
3
4
┌──────────────┐     扫码登录      ┌──────────────┐     长轮询      ┌──────────────┐
│  你的微信App  │ ◄──────────────► │  iLink Bot    │ ◄────────────► │ Hermes Agent │
│  (手机端)     │   收发消息/文件    │  API 服务器    │  35s 超时续订   │  (本机运行)   │
└──────────────┘                   └──────────────┘                └──────────────┘

关键特性：

  • 无需公网 IP、无需企业微信、无需中转服务器
  • 长轮询连接，自动重连断线
  • 支持文本、图片、视频、文件、语音全量消息类型
  • 消息通过 AES-128-ECB 加密传输
  • Markdown 原生渲染（表格、代码块等）

5.2 前置条件

要求 说明
Hermes Agent 已安装并正常运行
Python 3.10+
微信账号 个人微信号，强烈建议使用小号

⚠️ 为什么建议用小号：接入后微信账号将变成 Bot 身份，可能影响正常使用体验。

5.3 安装依赖

1
pip install aiohttp cryptography qrcode

或使用 uv：

1
uv pip install aiohttp cryptography qrcode

5.4 配置网关

1
hermes gateway setup

交互菜单操作：

  1. 使用方向键选择 Weixin / WeChat
  2. 按 Y 确认
  3. 终端将显示二维码，用手机微信扫描
  4. 手机上点「确认登录」
  5. 配置授权策略（推荐选 Use DM pairing approval）
  6. 群聊消息处理（推荐选 Disable group chats）

成功后显示：

1
2
微信连接成功，account_id=xxxxxxxxxxxx@im.bot
Gateway configuration saved.

5.5 配置环境变量

在 .env 文件中添加：

1
2
3
4
5
6
7
8
9
10
11
12
# =============================================================================
# WECHAT / WEIXIN CONFIGURATION
# =============================================================================
WEIXIN_ACCOUNT_ID=xxxxxxxxxxxx@im.bot
WEIXIN_TOKEN=xxxxxxxxxxxx@im.bot:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com

# 安全策略（推荐：仅白名单用户可用）
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=xxxxxxxxxxxx@im.wechat
WEIXIN_GROUP_POLICY=disabled
WEIXIN_ALLOW_ALL_USERS=false

5.6 启动网关

1
hermes gateway

成功启动后显示：

1
2
3
⚡ Gateway started
✓ Weixin adapter connected (account: xxxxxxxxxxxx@im.bot)
⏳ Waiting for messages...

5.7 在微信中使用

首次配对：

  1. 在微信中找到已连接的 Bot 对话
  2. 发送任意消息（如 “你好”）
  3. 切回 Hermes 终端，批准配对请求
  4. 也可直接在微信中发送 /whitelist 自动加入白名单

微信中可用命令：

命令 功能
/new 开始新对话
/reset 重置会话
/model <名称> 切换 AI 模型
/whitelist 将自己加入白名单
/help 查看帮助

5.8 网关管理命令

命令 功能
hermes gateway setup 配置网关
hermes gateway 启动网关
hermes gateway status 查看状态
hermes gateway stop 停止
hermes gateway restart 重启
hermes gateway install 安装为系统服务（开机自启）

5.9 安全策略说明

DM（私聊）策略：

策略 行为 推荐度
pairing 陌生人需手动批准，已批准直接通过 ⭐ 推荐
allowlist 仅白名单用户可对话 ⭐ 推荐
open 任何人可直接对话 ❌ 风险高
disabled 不响应任何私聊 —

群聊策略：

策略 行为
disabled（推荐） 不处理群聊消息
allowlist 仅响应白名单群组
open 响应所有群消息

注意：iLink Bot 身份通常无法被拉入普通微信群，群聊功能大概率不可用。私聊是唯一保证可靠的使用方式。

5.10 支持的消息类型

方向 类型 支持
接收 文本、图片、视频、文件、语音 ✅ 全部支持
发送 文本 (Markdown) ✅
发送 图片、视频、文件 ✅
发送 语音 ✅ (SILK 格式)

六、配置文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
HERMES_HOME\
├── config.yaml          ← 主配置文件（模型、终端、工具等）
├── .env                 ← API 密钥等敏感配置
├── SOUL.md              ← AI 人设描述文件
├── MEMORY.md            ← Agent 自动保存的记忆
├── USER.md              ← 用户偏好档案
│
├── sessions\            ← 会话历史
├── logs\                ← 运行日志
├── skills\              ← 已安装/创建的技能
├── memories\            ← 记忆存储
├── cron\                ← 定时任务配置
├── hooks\               ← 钩子脚本
├── audio_cache\         ← 音频缓存
│
└── hermes-agent\        ← 程序代码 (git 仓库)
    └── venv\            ← Python 虚拟环境 (3.11.15)

关键配置文件速改

切换默认模型 — 编辑 config.yaml：

1
2
3
4
model:
  default: "deepseek-chat"
  provider: "custom"
  base_url: "https://api.deepseek.com"

添加模型别名 — 在 config.yaml 中添加：

1
2
3
4
5
6
7
8
9
model_aliases:
  ds-pro:
    model: deepseek-chat
    provider: custom
    base_url: "https://api.deepseek.com"
  ds-reasoner:
    model: deepseek-reasoner
    provider: custom
    base_url: "https://api.deepseek.com"

配置后可用 /model ds-pro 快速切换。

七、常见问题排查

7.1 安装阶段

问题 解决方案
irm : 未能解析此远程名称 GitHub 被墙，使用镜像 ghfast.top / ghproxy.cn
无法加载文件 ... 未签名 先执行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
安装脚本中途卡住 网络不稳定，关闭终端重新执行

7.2 配置阶段

问题 解决方案
hermes 命令无效 关闭当前终端，重新打开
API 返回 401 错误 DeepSeek API Key 过期，重新生成并更新 .env
hermes doctor 显示 API key 未配置 检查 .env 格式，确保无多余空格，变量名全大写

7.3 微信接入

问题 原因 解决方法
扫码后无反应 网络或 API 超时 Ctrl+C 后重新 hermes gateway setup
二维码过期 有时效性 重新执行配置向导
缺少 aiohttp/cryptography 依赖未安装 pip install aiohttp cryptography qrcode
终端无法显示二维码 未安装 qrcode 复制 URL 到浏览器扫码
机器人不响应私聊 DM 策略问题 检查 WEIXIN_DM_POLICY 配置
会话过期 errcode=-14 Token 过期 重新 hermes gateway setup 扫码
WEIXIN_TOKEN 缺失 凭据丢失 重新运行网关配置向导
Token 被占用 已有 Gateway 在用 hermes gateway stop 停止旧实例

7.4 运行阶段

问题 解决方案
回复乱码 在对话中说「请用中文回复」
工具调用失败 运行 hermes doctor 诊断
会话历史空白 检查 HERMES_HOME 环境变量
ripgrep 未找到 winget install BurntSushi.ripgrep.MSVC

7.5 诊断速查

1
2
3
4
hermes doctor              # 全面诊断
hermes doctor --fix         # 自动修复
hermes setup                # 重新配置向导
hermes update               # 升级到最新版

八、总结

Hermes Agent 是一个功能强大的开源 AI 编程助手框架，五大核心优势：

  1. 完全开源 — 代码透明，社区驱动，免费使用
  2. 模型灵活 — 支持 20+ 模型提供商，DeepSeek 国内直连免翻墙
  3. 微信原生接入 — 通过腾讯官方 iLink Bot API，安全合规
  4. 自我进化 — Skill 系统让 AI 越用越聪明，持久记忆跨会话
  5. 全平台覆盖 — CLI / TUI / Desktop / Web，按需切换

无论你是开发者、研究人员、还是内容创作者，Hermes Agent 都能成为得力的 AI 伙伴。从代码编写到文档生成，从自动化任务到微信助手，一个框架全搞定。

参考资源：

文档编写于 2026-07-06 · Hermes Agent v0.18.0 · Windows + DeepSeek