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

Hermes Agent 完整指南——从零安装到微信接入目录一、Hermes Agent 是什么二、核心特性一览三、安装部署教程四、CLI 命令大全与使用指南五、接入个人微信六、配置文件结构七、常见问题排查八、总结一、Hermes Agent 是什么Hermes Agent 是由Nous Research开发的开源 AI 代理框架类似于 Claude Code / OpenAI Codex但完全开源且支持多模型、多平台。对比维度Hermes AgentClaude CodeOpenAI Codex开源✅ 完全开源❌ 闭源❌ 闭源模型选择20 提供商自由切换仅 Claude仅 OpenAI消息平台微信/Telegram/Discord 等无无本地运行✅✅云端技能系统✅ 自我进化❌❌二、核心特性一览2.1 自我进化的技能系统 (Skills)AI 可以从任务中学习并永久保存技能下次遇到类似问题自动调用。这是 Hermes 最亮眼的能力——越用越聪明。2.2 持久化记忆基于 SQLite 数据库存储对话历史和用户偏好跨会话保留上下文真正记住你的习惯。2.3 跨平台消息网关支持20 消息平台平台状态微信 (WeChat)✅ 通过 iLink Bot APITelegram✅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访问 DeepSeek 开放平台注册/登录账号进入「API Keys」页面点击「创建 API Key」复制生成的密钥格式sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3.3 一键安装以管理员身份打开 PowerShell执行# 步骤1绕过 PowerShell 执行策略限制Set-ExecutionPolicy-ScopeProcess-ExecutionPolicy Bypass-Force# 步骤2使用国内镜像安装irmhttps://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1|iex国内用户注意如果ghfast.top不可用可使用以下备用镜像# 备用1irmhttps://ghproxy.cn/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1|iex# 备用2irmhttps://mirror.ghproxy.com/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1|iex脚本会自动完成约 5-10 分钟[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 密钥# 用记事本打开 .env 文件notepad$env:LOCALAPPDATA\hermes\.env在文件最开头添加# # LLM PROVIDER (DeepSeek - 主模型) # OPENAI_API_KEY你的DeepSeek-API-Key OPENAI_BASE_URLhttps://api.deepseek.com DEEPSEEK_API_KEY你的DeepSeek-API-Key步骤2修改模型配置notepad$env:LOCALAPPDATA\hermes\config.yaml找到model:部分修改为model:default:deepseek-chatprovider:custombase_url:https://api.deepseek.com原配置三处均需修改default为deepseek-chat、provider为custom、base_url为 DeepSeek 地址。步骤3设置数据目录可选# 设置 HERMES_HOME 到指定目录setx HERMES_HOMED:\Program Files (x86)\ailuo\Hermes-Agent# 创建目录符号链接管理员权限cmd/c mklink/JD:\Program Files (x86)\ailuo\Hermes-Agent%LOCALAPPDATA%\hermes3.5 验证安装hermes--version# 输出: Hermes Agent v0.18.0 (2026.7.1)hermes doctor# 运行诊断确认各项检查通过首次对话测试hermes在 CLI 中输入你好请用中文回复。介绍一下你能做什么正常收到 DeepSeek 回复说明安装成功四、CLI 命令大全与使用指南4.1 启动与退出# 基本启动hermes# 指定模型hermes--model deepseek-chat# 指定工作目录hermes--cwd D:\my-project# 查看帮助hermes--help# 诊断hermes doctor退出方式输入/exit、/q、/quit或按CtrlC。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 日常使用场景代码开发辅助cd D:\my-project hermes# 然后可以这样对话# 帮我写一个 Flask REST API 接口# 分析这段代码的性能瓶颈# 修复这个 bug...# 给这个项目写单元测试文档写作请帮我写一份关于XXX的技术方案文档 根据这个项目的代码生成 API 文档 把这段英文文档翻译成中文数据分析分析 data.csv 中的数据趋势 帮我写一个 Python 脚本处理这些 JSON 文件五、接入个人微信5.1 工作原理Hermes 通过腾讯官方iLink Bot API连接个人微信架构如下┌──────────────┐ 扫码登录 ┌──────────────┐ 长轮询 ┌──────────────┐ │ 你的微信App │ ◄──────────────► │ iLink Bot │ ◄────────────► │ Hermes Agent │ │ (手机端) │ 收发消息/文件 │ API 服务器 │ 35s 超时续订 │ (本机运行) │ └──────────────┘ └──────────────┘ └──────────────┘关键特性无需公网 IP、无需企业微信、无需中转服务器长轮询连接自动重连断线支持文本、图片、视频、文件、语音全量消息类型消息通过 AES-128-ECB 加密传输Markdown 原生渲染表格、代码块等5.2 前置条件要求说明Hermes Agent已安装并正常运行Python3.10微信账号个人微信号强烈建议使用小号⚠️ 为什么建议用小号接入后微信账号将变成 Bot 身份可能影响正常使用体验。5.3 安装依赖pip install aiohttp cryptography qrcode或使用 uvuv pip install aiohttp cryptography qrcode5.4 配置网关hermes gateway setup交互菜单操作使用方向键选择Weixin / WeChat按Y确认终端将显示二维码用手机微信扫描手机上点「确认登录」配置授权策略推荐选Use DM pairing approval群聊消息处理推荐选Disable group chats成功后显示微信连接成功account_idxxxxxxxxxxxxim.bot Gateway configuration saved.5.5 配置环境变量在.env文件中添加# # WECHAT / WEIXIN CONFIGURATION # WEIXIN_ACCOUNT_IDxxxxxxxxxxxxim.bot WEIXIN_TOKENxxxxxxxxxxxxim.bot:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx WEIXIN_BASE_URLhttps://ilinkai.weixin.qq.com # 安全策略推荐仅白名单用户可用 WEIXIN_DM_POLICYallowlist WEIXIN_ALLOWED_USERSxxxxxxxxxxxxim.wechat WEIXIN_GROUP_POLICYdisabled WEIXIN_ALLOW_ALL_USERSfalse5.6 启动网关hermes gateway成功启动后显示⚡ Gateway started ✓ Weixin adapter connected (account: xxxxxxxxxxxxim.bot) ⏳ Waiting for messages...5.7 在微信中使用首次配对在微信中找到已连接的 Bot 对话发送任意消息如 “你好”切回 Hermes 终端批准配对请求也可直接在微信中发送/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 格式)六、配置文件结构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.yamlmodel:default:deepseek-chatprovider:custombase_url:https://api.deepseek.com添加模型别名— 在config.yaml中添加model_aliases:ds-pro:model:deepseek-chatprovider:custombase_url:https://api.deepseek.comds-reasoner:model:deepseek-reasonerprovider:custombase_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 过期重新生成并更新.envhermes doctor显示 API key 未配置检查.env格式确保无多余空格变量名全大写7.3 微信接入问题原因解决方法扫码后无反应网络或 API 超时CtrlC后重新hermes gateway setup二维码过期有时效性重新执行配置向导缺少 aiohttp/cryptography依赖未安装pip install aiohttp cryptography qrcode终端无法显示二维码未安装 qrcode复制 URL 到浏览器扫码机器人不响应私聊DM 策略问题检查WEIXIN_DM_POLICY配置会话过期errcode-14Token 过期重新hermes gateway setup扫码WEIXIN_TOKEN缺失凭据丢失重新运行网关配置向导Token 被占用已有 Gateway 在用hermes gateway stop停止旧实例7.4 运行阶段问题解决方案回复乱码在对话中说「请用中文回复」工具调用失败运行hermes doctor诊断会话历史空白检查HERMES_HOME环境变量ripgrep 未找到winget install BurntSushi.ripgrep.MSVC7.5 诊断速查hermes doctor# 全面诊断hermes doctor--fix# 自动修复hermes setup# 重新配置向导hermes update# 升级到最新版八、总结Hermes Agent 是一个功能强大的开源 AI 编程助手框架五大核心优势完全开源— 代码透明社区驱动免费使用模型灵活— 支持 20 模型提供商DeepSeek 国内直连免翻墙微信原生接入— 通过腾讯官方 iLink Bot API安全合规自我进化— Skill 系统让 AI 越用越聪明持久记忆跨会话全平台覆盖— CLI / TUI / Desktop / Web按需切换无论你是开发者、研究人员、还是内容创作者Hermes Agent 都能成为得力的 AI 伙伴。从代码编写到文档生成从自动化任务到微信助手一个框架全搞定。参考资源Hermes Agent GitHubHermes 官方中文文档DeepSeek 开放平台iLink Bot API文档编写于 2026-07-06 · Hermes Agent v0.18.0 · Windows DeepSeek