把 AI 助手同时装进微信和飞书 - Hermes Agent 快速上手指南

在你的微信和飞书里装一个随叫随到的 AI：能写文章、搜论文、管理日程，还会从对话中自动学习你的习惯。
Hermes Agent 是 Nous Research 开发的开源 AI Agent 框架，内置 89 个开箱即用的技能，原生支持微信和飞书，200 多个 AI 模型随意切换。可以在 macOS、Linux、WSL2、甚至 Android Termux 上运行。
这篇文章记录了我从安装到接入微信和飞书的完整过程，以及日常使用中踩过的坑。我的环境是一台 M1 MacBook，安装脚本会自动检测并处理依赖，别的系统也一样。

安装

安装只需要一行命令：

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

脚本会检测系统并自动安装所有依赖：uv 包管理器 → Python 3.11 → 检查 Git 和 Node.js → Homebrew 装 ripgrep 和 ffmpeg → 克隆仓库到 ~/.hermes/hermes-agent → 创建虚拟环境 → 同步 89 个内置技能 → 装 Node.js 依赖。全程大约十分钟，理论上如果网络没有问题，不需要人工干预。

为什么依赖这么多

Python：Hermes 是 Python 写的，需要 Python 3.11 + 虚拟环境 + pip 依赖，这是标准 Python 项目部署流程。对比 Claude Code 需要 Node.js 和 npm，只是 Hermes 的安装脚本把每步都打印出来了。

Node.js：微信 iLink 连接器用 Node.js 实现。

ripgrep：Agent 在文件系统里搜索的工具，类似 grep 但快很多。

ffmpeg：处理语音消息，纯文字用不到但脚本默认装了。

简化安装的其他方式

不想装本地依赖可以用 Docker：

docker pull nousresearch/hermes-agentdocker run -it -v ~/.hermes:/root/.hermes nousresearch/hermes-agent

如果你已经在用 AI 编程工具（Claude Code、OpenCode 等），让 Agent 替你跑安装更省事。本文的安装就是通过 OpenCode + DeepSeek 自动完成的。安装AI 编程工具可以参考下面的文章：

OpenCode + 百炼一键链接国内大模型四小强

强强联合：Claude Code 接入 DeepSeek V4 的正确打开方式

告诉OpenCode "帮我装 Hermes Agent 并接入微信"，它会自己执行命令、处理报错、配置模型和密钥，依赖多、步骤长的问题完全不用操心。

安装日志

下面是我的实际输出，根据不同环境和版本可能有差异，仅供参考：

✓ Detected: macos (macos)→ Installing uv (fast Python package manager)...✓ uv installed (uv 0.11.11)→ Python 3.11 not found, installing via uv...Downloading cpython-3.11.15-macos-aarch64-none (25.8MiB)Installed Python 3.11.15 in 5.51s✓ Python installed: Python 3.11.15

脚本识别系统后装 uv（Rust 写的 Python 包管理器），再通过 uv 装 Python 3.11。即使系统有其他 Python 版本也不会冲突。

✓ Git 2.50.1 found✓ Node.js v25.8.0 found→ Installing ripgrep ffmpeg via Homebrew...✓ ripgrep installed (15.1.0)✓ ffmpeg installed (8.1.1)

检查 Git 和 Node.js，缺了就自动装。ripgrep 和 ffmpeg 通过 Homebrew 安装。

→ Installing to /Users/你的用户名/.hermes/hermes-agent...→ Trying SSH clone...→ SSH failed, trying HTTPS...Cloning into '/Users/你的用户名/.hermes/hermes-agent'...✓ Cloned via HTTPS

先尝试 SSH，没配置 Key 就自动退回 HTTPS。仓库克隆到 ~/.hermes/hermes-agent。

→ Creating virtual environment with Python 3.11...✓ Virtual environment ready (Python 3.11)→ Installing dependencies...✓ Main package installed✓ All dependencies installed

uv pip install -e ".[all]" 一步装完主包和所有扩展。

Syncing bundled skills into ~/.hermes/skills/ ...  + apple-reminders  + arxiv  + blogwatcher  + research-paper-writing  ... (共 89 个)Done: 89 new, 0 updated, 0 unchanged.

同步 89 个内置技能，安装后发 /<skill-name> 在聊天框里直接调用。

added 204 packages, audited 205 packages in 1m 20sfound 0 vulnerabilities

最后的 Node.js 依赖安装。脚本同时在 ~/.local/bin/hermes 创建启动脚本，如果提示找不到命令，执行 source ~/.zshrc 重新加载 shell。

安装完成后 ~/.hermes/ 下的目录结构：

~/.hermes/├── .env              # API 密钥和环境变量├── config.yaml       # 主配置文件├── SOUL.md           # Agent 人格定义（可以修改）├── cron/             # 定时任务├── sessions/         # 会话记录├── logs/             # 日志文件├── pairing/          # 配对信息├── hooks/            # 钩子脚本├── image_cache/      # 图片缓存├── audio_cache/      # 音频缓存├── memories/         # 记忆存储└── skills/           # 技能库

几个比较重要的配置：.env 存 API Key 和环境变量，不可泄露；config.yaml 是主配置；SOUL.md 定义了 Agent 的性格，可以按自己喜好改；logs/ 是出问题时第一个要查的地方。

验证安装

$ hermes --versionHermes Agent v0.12.0 (2026.4.30)Project: /Users/你的用户名/.hermes/hermes-agentPython: 3.11.15OpenAI SDK: 2.33.0Up to date

配置 AI 模型

hermes model

这是一个交互式的配置向导，会列出所有支持的模型提供商，选择后在提示下输入对应的 API Key 或完成 OAuth 登录就能完成配置。

Hermes 支持的模型提供商覆盖面很广：Nous Portal 可以通过 OAuth 一键登录，OpenAI 用 ChatGPT OAuth，Anthropic 支持 OAuth 或者 API Key 两种方式，DeepSeek、OpenRouter、Kimi 这些用 API Key，HuggingFace 用 HF_TOKEN，GitHub Copilot 用 OAuth。如果你有自己的模型服务，只要兼容 OpenAI API 格式就可以配置为自定义端点接入。

Hermes Agent 要求模型至少有 64,000 tokens 的上下文窗口。大部分主流模型都满足这个条件。

接入微信

Hermes v0.12.0 原生支持微信，通过腾讯的 iLink Bot API（https://ilinkai.weixin.qq.com）实现直连。iLink 是腾讯为个人微信提供的 Bot API，采用 HTTP 长轮询协议，每 35 秒轮询一次消息。这意味着你不需要公网 IP，不需要端口映射，不需要任何第三方桥接工具，只要你的电脑能上网就行。

扫码后会创建一个独立的 Bot 身份，比如 a5ace6fxxxx@im.bot，这不是你本人的微信号。因此 Bot 的限制也很明确：可以正常收发私聊消息，支持文字、图片、视频、文件和语音，但无法被拉入普通的微信群（这是腾讯在 iLink 层面的限制，和 Hermes 无关）。媒体文件通过微信 CDN 传输，数据用 AES-128-ECB 加密，Hermes Gateway 会自动处理加解密，不需要额外配置。

接入步骤

hermes gateway setup    # 选 14 = Weixin / WeChat

执行后终端会打印一个二维码，打开微信扫一扫扫描，在手机上确认登录。扫码过程中二维码最多自动刷新 3 次，不用担心扫慢了。扫码成功后凭证自动保存到 ~/.hermes/weixin/accounts/，不需要手动管理。

随后按提示配置 DM 策略等选项，一路回车使用默认值即可。

hermes gateway start    # 启动网关

启动后可以在微信里给 Bot 发消息测试。确认正常后，把网关设为后台服务：

hermes gateway install  # 安装为 macOS launchd 服务，开机自启hermes gateway status   # 查看网关运行状态tail -f ~/.hermes/logs/gateway.log   # 实时查看日志

安全策略

在 ~/.hermes/.env 中可以通过 WEIXIN_DM_POLICY 控制谁可以给 Bot 发消息。支持四种模式：open 表示任何人都可以发，这也是默认值；allowlist 只允许 WEIXIN_ALLOWED_USERS 中列出的用户；disabled 直接忽略所有私聊；pairing 会要求新用户输入配对码，需要你手动批准后才能对话。如果你不想随便什么人都能给 Bot 发消息，建议改成 allowlist 并添加自己的微信用户 ID。

微信中的命令

在微信聊天框里，通过 / 开头的命令控制 Agent。常用的包括 /new 或 /reset 开始一段新对话（之前的上下文会清空），/model 查看当前使用的模型或切换到其他模型，/retry 让 AI 对上一个问题的回答重新生成一次，/undo 撤销上一轮对话（相当于撤回刚才说的内容和 AI 的回复），/stop 强制停止 AI 正在执行的任务。另外每个已安装的技能都可以通过 /<skill-name> 直接调用，比如发 /arxiv 量子计算 就能搜索相关论文。

常见问题

如果 Bot 不回消息，首先检查 .env 中的 WEIXIN_DM_POLICY 设置，确认不是 disabled 或错误的 allowlist 配置；然后运行 hermes gateway status 确认网关在正常运行。

会话过期时（错误码 errcode=-14），重新跑 hermes gateway setup 扫码登录即可。Token 冲突也需要注意，同一个 Token 只能被一个 Gateway 实例使用，如果你在另一台机器上同时跑了 Hermes，会导致当前 Gateway 掉线。

媒体消息（图片、视频、文件）收发失败，通常是 cryptography 这个 Python 包没装上，执行 pip list | grep cryptography 确认一下。

群聊无法使用是 iLink Bot 本身的限制，除非将来腾讯放开这个能力，否则目前没有解决办法。

微信多开

如果你需要在同一个微信号上同时使用 Hermes 和其他 Agent（比如 OpenClaw、OpenCode），社区有一个叫 HermesClaw 的项目可以做到：

curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh | bash

装好后在微信里通过 /hermes、/openclaw、/opencode 命令在三个 Agent 之间切换。

接入飞书

Hermes 从 v0.6.0 开始原生支持飞书，通过飞书开放平台的 WebSocket 协议直连，同样不需要公网 IP 和端口映射。

和微信接入流程几乎一样：

hermes gateway setup   # 选 Feishu / Lark

终端打印二维码后，用飞书 App 扫码。Hermes 会自动在飞书开放平台创建应用，不需要你手动去后台填写回调地址、申请权限、配置事件订阅这些。扫码后飞书的机器人就出现在通讯录里了，直接开始对话就行。

如果你的网关安全策略配了配对码（微信那头设了 WEIXIN_DM_POLICY=pairing），飞书这边同样需要先配对。Bot 会发一段提示，输入配对码确认身份后才能正常对话。

设置主频道

进入私聊或者频道后，发 /sethome 告诉 Hermes 把当前会话当作主频道。之后一些定时任务、系统通知都会发到这里。每个平台可以各设一个主频道，互不影响。

和微信同时在线

同一个网关进程可以同时跑多个平台。配好微信和飞书后，hermes gateway start 启动一次就行：

$ hermes gateway statusConnected: weixin(active), feishu(active)

两个平台同时在线，一个终端只跑一个进程。

飞书的功能支持

飞书适配器是目前功能最完整的几个平台之一，支持私聊和群聊、文字和富文本消息、图片和文件收发、语音消息（TTS + 转写）、表情反应、消息卡片交互、文档评论回复，基本你在飞书日常用的消息类型都覆盖了。

安全策略方面，~/.hermes/.env 中通过 FEISHU_ALLOWED_USERS 控制白名单，FEISHU_DM_POLICY 控制私聊权限，和微信的配置方式一致。

配置 Web 搜索

装好之后我发现让 Bot 搜东西会失败。原因有两层：

第一层：hermes tools 里虽然开启了 web 工具集，但 web 只是一个开关，真正的搜索能力需要一个后端。你可以选 Firecrawl、Tavily、Exa 等付费/免费 API，在 ~/.hermes/.env 里配对应的 API Key：

TAVILY_API_KEY=tvly-xxx    # 推荐，1000 次/月免费# 或FIRECRAWL_API_KEY=fc-xxx   # 500 credits/月免费# 或EXA_API_KEY=xxx             # 1000 次/月免费

第二层：如果不想搞 API Key，可以用 MCP 方式接入免费的 DuckDuckGo 搜索。但不是 pip install ddgs 就完事了，ddgs 只是一个 Python 包，Hermes 不会自动把它当成工具使用。需要以 MCP Server 的方式接入。

MCP 接入 DuckDuckGo（免费，无需 API Key）

正确的 MCP 包名是 ddg-mcp-search，不是网上常见的 duckduckgo-mcp-server（那个有 VQD bug）。

编辑 ~/.hermes/config.yaml，新增：

mcp_servers:  ddg-search:    command: "npx"    args: ["-y", "ddg-mcp-search"]    timeout: 60

验证配置：

hermes mcp test ddg-search# ✅ 成功会发现 2 个工具：search + fetch_content

MCP 工具只有在 Hermes 启动时才会注册，配完后必须重启：

hermes gateway restart

重启后 Bot 就会多一个 mcp_ddg_search_search 工具，搜东西一步直达。

注意：

上面这个结论不是看文档看出来的，是让 Hermes 自己排查出来的。它先发现 web.backend 配置为空所以 web_search 函数没注册，然后反复尝试不同 MCP 包名、处理 VQD 报错、最终锁定 ddg-mcp-search 并自动写入了 config.yaml。整个过程在飞书聊天框里完成，我只负责 /approve 审批两步操作。这也是 Hermes 的一个实用场景，让它自己解决自己的配置问题。

日常使用

通过终端使用 Hermes 时，直接输入 hermes 进入交互式 CLI，或者用 hermes --tui 启动更现代的 TUI 界面。TUI 支持多行编辑、自动补全、流式输出。不过在微信和飞书里聊就能完成大部分操作，不需要一直盯着终端。

真实使用场景

举几个我实际用到的例子：

写文章：比如想写一篇技术分享，手上只有几个要点。把大纲发给它，说"帮我扩写成一篇 1500 字的文章，面向非技术读者"。由它检索相关资料、整理了段落结构、在微信或飞书里边聊边改，最终定稿。

搜索和验证：问"帮我查一下 Nous Research 最新的 Hermes 模型参数是多少"，它用 DuckDuckGo 搜索、打开 GitHub Release 页面、抓取参数表、整理成表格回复。微信对话框就变成了一个能上网的研究助手。

自我修复：Web 搜索配置那事，我没有查文档，在飞书里问"为什么没有 web search 工具"。Hermes 自己检查 config.yaml、排查 MCP 配置、尝试不同包名、处理 VQD 报错、最终把正确的配置写好。我只需要审批两步操作。

这三个场景只是日常使用中的一小部分。加上 89 个内置技能，还能做论文检索、博客监控、定时推送、创建提醒、管理日程这些事，翻译、总结、日常问答也都很顺手。

内置技能

每个技能通过 /<skill-name> 在聊天框直接调用。常用场景：/arxiv 量子计算 搜论文，/blogwatcher 监控博客更新，/apple-reminders 明天下午三点开会 创建提醒。在聊天框发 /skills 查看完整列表，hermes skills 浏览技能市场装新技能。

常用命令

hermes model 随时切换 AI 模型，不同任务用不同模型互不干扰。hermes tools 管理工具开关。hermes cron 配定时任务，比如每天早上九点推送新闻摘要。遇到问题 hermes doctor 自动诊断。hermes --continue 恢复上次会话。定期 hermes update 保持版本更新。

保持服务常驻

Hermes 的微信网关需要持续运行才能收发消息，但个人电脑默认会在闲置时自动休眠，休眠后所有进程暂停，Bot 直接掉线，唤醒后也不会自动恢复。

如果你只是偶尔用用，每次用之前手动启动网关就行。如果希望 Bot 随时在线，需要阻止系统进入休眠。

macOS

先用 hermes gateway install 安装 launchd 服务，开机自动启动。但光有自启不够，系统休眠仍然会中断服务。

临时方案是在启动网关的同时执行：

caffeinate -i hermes gateway start

caffeinate -i 会阻止系统在程序运行期间进入闲置休眠。缺点是终端不能关，关了 caffeinate 也停了。

如果不需要合盖也能正常工作，可以全局禁止休眠：

sudo pmset -a disablesleep 1

恢复默认：sudo pmset -a disablesleep 0。这个命令对电池续航影响很大，插电用的话问题不大。

另外也可以装 Amphetamine 这类菜单栏工具，按需切换防休眠状态，比命令行更灵活。

Linux

最常见的方案是用 systemd-inhibit 阻止休眠：

systemd-inhibit --what=sleep --why="Hermes gateway" hermes gateway start

如果用的是 GNOME 桌面，可以在设置 → 电源中把"空白屏幕"改为"从不"，或者装 Caffeine 扩展一键切换。

KDE 和 XFCE 也有类似的电源管理选项。

Windows

Windows 需要在 WSL2 里运行 Hermes，但 WSL2 同样受宿主机休眠影响。在 Windows 设置 → 系统 → 电源和电池中，把睡眠改为"从不"。或者用 PowerToys 的 Awake 功能，托盘图标一键保持唤醒状态。

另外 WSL2 还有一个额外问题：如果长时间不操作终端，WSL2 自己可能会被挂起。在 Windows 上跑 wsl --list --verbose 观察一下 WSL 实例的 State，如果是 "Stopped" 就说明被挂起了。可以创建一个计划任务定时 ping WSL 保持活跃，或者把网关跑在 tmux/screen 里。

长驻服务的现实

个人电脑本来就不是为 7×24 服务设计的。笔记本有电池管理、合盖休眠、功耗控制，台式机虽然好一点但也有自动休眠和系统更新重启的问题。如果对 Bot 的在线率有要求，最简单的办法是把 Hermes 部署到一台低功耗的小机器上。树莓派、旧笔记本装 Linux、或者便宜的轻量云服务器（一年几十块那种 1C1G 的就行），装上之后基本不用管。Hermes 对硬件要求不高，主要开销是 API 调用在远端完成，本地只负责消息收发。

如果暂时只能用个人电脑，记住 caffeinate（macOS）、systemd-inhibit（Linux）、PowerToys Awake（Windows）这三个工具，出问题时先检查系统是不是自己睡了。

与 OpenClaw 对比

OpenClaw 是另一款知名的个人 AI 助手，由 Peter Steinberger 开发，比 Hermes 更早出圈。GitHub 上 370k stars、42000 多次提交，支持 24 种以上的消息通道（WhatsApp、Telegram、Slack、Discord、微信、QQ、飞书、iMessage、Matrix 等），有 macOS 菜单栏 App、iOS/Android 节点端、语音唤醒和连续对话、Live Canvas 可视化工作区。社区更大、文档更全，赞助方包括 OpenAI、GitHub、NVIDIA。

Hermes 的核心差异在于它的自我学习循环。Agent 会从和你的对话中自动抽取经验、创建新技能，用着用着就变成只属于你的形状。89 个内置技能开箱即用，安装完扫码就能在微信里干活，不需要额外折腾。这个学习闭环是 Hermes 独有的，OpenClaw 没有。

数据来自 GitHub 首页（2026 年 5 月）：

Hermes：138k stars，7600+ commits，v0.13.0，MIT，Python
OpenClaw：370k stars，42000+ commits，MIT，TypeScript/Node.js

故障排除

hermes 命令找不到，通常是 shell 还没加载新的 PATH 配置，执行 source ~/.zshrc 即可。如果用的不是 zsh，对应改为 source ~/.bashrc 或 source ~/.bash_profile。

模型配置有问题或者切换模型后无响应，重新运行 hermes model 检查一下 API Key 和端点地址是否正确。

其他不确定的问题，先运行 hermes doctor，它会自动检查各项配置和环境依赖。想用上次的会话继续，hermes --continue。版本更新直接 hermes update。

写在最后

几点真实感受：

装 Hermes 比我预想的顺利。一行命令跑完，十分钟后就有了一个在微信里能说话的 Bot。配置模型是交互式的，接入微信和飞书都是扫码就好，没要我填过 App ID、回调地址这些东西。

遇到的坑是搜索不工作。我把它写成文档里详细的一节，下一个装 Hermes 的人不用再排查同一件事。MCP 接入 DuckDuckGo 免费好用，配完重启就行。

Windows 用户注意走 WSL2，iLink Bot 不在微信群工作，模型至少 64K token 上下文，个人电脑当服务器记得防休眠。这几个问题在正文里都有交代，不展开了。

安装