Mac 从零部署 Hermes Agent 并接入飞书:一篇就够的保姆级教程

本文基于实际踩坑过程整理,从 Hermes 安装到飞书 Bot + 飞书 CLI 完整打通,包含所有可能遇到的报错和解决方案。跟着做 30 分钟就能让 AI 在飞书里替你干活。

前言:为什么是 Hermes Agent?

Hermes Agent 是 Nous Research 开源的 AI Agent 框架,和 OpenClaw 同类,最大特点是会自我成长:

• 记住跨会话的上下文
• 自动沉淀技能文档(Skill)
• 越用越懂你

定位是"一个运行在你自己服务器上、用得越久越聪明的开源 AI Agent"。

接入飞书后能实现:

• 飞书里直接 @ 机器人对话
• 读取聊天记录、云文档、多维表格
• 自动创建文档、发消息、约会议
• 24 小时在线,手机随时唤起

---

一、前置准备:安装基础依赖

1. 安装 Homebrew

打开 Mac 终端,粘贴执行:

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

装完根据提示把 brew 加到 PATH。验证:

brew --version

2. 安装必要依赖

brew install python@3.11 node git ripgrep uv

各依赖用途:

• python@3.11 --- Hermes 需要 Python 3.10+
• node --- 飞书 CLI 用
• git --- 克隆仓库
• ripgrep --- Hermes 搜索能力依赖
• uv --- Python 包管理器

验证:

python3 --version   # 3.11.x
node --version
uv --version

3. Apple Silicon 用户注意 PATH

确认 which python3 指向 /opt/homebrew/bin/python3。如果指向系统自带的 /usr/bin/python3:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

---

二、安装 Hermes Agent

1. 一键安装

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

安装过程会自动:

• 克隆仓库
• 创建 venv
• 安装所有依赖
• 把 hermes 命令加到 PATH

不要用 sudo,否则后续 skill 写入会有权限问题。

2. 安装中可能遇到的报错

报错:/Users/xxx/.profile: Permission denied

不影响安装,只是脚本试图往 .profile 写 PATH 失败。Mac 用 zsh,真正生效的是 .zshrc 和 .zprofile,已经写入成功。

修复方式(可选):

ls -la ~/.profile
# 如果 owner 是 root
sudo chown $(whoami):staff ~/.profile
sudo chmod 644 ~/.profile

3. 验证安装

source ~/.zshrc
hermes version
hermes doctor

如果 hermes: command not found:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4. 配置模型 API Key

首次 hermes doctor 会提示让你跑 setup:

hermes setup

向导会问:

1. 选 LLM 服务商 --- 国内推荐 DeepSeek(便宜稳定)、Kimi、智谱 GLM
2. 粘贴 API Key --- 去对应官网申请
3. 选具体模型
4. 是否配消息平台 --- 可以先跳过,后面单独配
5. 可选工具 Key --- Firecrawl、FAL 等,全部跳过,用到再配

常用服务商申请地址:

服务商	地址
DeepSeek	platform.deepseek.com
Kimi	platform.moonshot.cn
智谱 GLM	bigmodel.cn

5. 验证对话能力

hermes doctor          # 全绿就 OK
hermes chat -q "你好"  # 能返回回复

---

三、在飞书开放平台创建应用

在接入 Hermes 之前,必须先在飞书后台建一个自建应用。

1. 创建应用

访问 open.feishu.cn → 开发者后台 → 创建企业自建应用

填好名字、描述、头像后创建。

2. 记录凭证

应用详情 → 凭证与基础信息,记下:

• App ID
• App Secret

后面 Hermes 配置要用。

3. 启用机器人能力

应用能力 → 启用 机器人。

4. 配置权限(最容易漏的地方)

权限管理 → 添加下面这些权限:

权限	作用
im:message	接收/发送消息(必需)
im:message.p2p_msg:readonly	读私聊消息(必需)
im:message.group_at_msg:readonly	读群里 @ 消息
im:resource	读图片/文件
application:application:self_manage	让机器人认出自己名字
contact:user.base:readonly	读用户基本信息

5. 订阅事件(关键)

事件与回调 → 事件配置:

1. 订阅方式 选 长连接 (不是 Webhook)

2. 添加订阅事件:

   • im.message.receive_v1 --- 接收消息事件(必需)
   • im.message.message_read_v1 --- 消息已读(可选)

⚠️ 90% 的"机器人没反应"都是因为没订阅这个事件

6. 发布版本

版本管理与发布 → 创建版本 → 填版本号(如 1.0.0)→ 提交审批。

• 企业管理员:自己在飞书里审批,秒过
• 普通成员:找管理员审批

可用范围 建议选 全员可用,省得自己不在白名单里。

---

四、在 Hermes 里接入飞书

1. 运行 Gateway 配置

hermes setup gateway

⚠️ 注意 :子命令是 gateway 不是 messaging。

2. 选择平台(关键操作)

看到平台列表时:

1. 用 ↑↓ 方向键移动到 Feishu/Lark
2. 按空格键选中 (出现 [x] 标记)--- 这一步最容易漏
3. 再按回车确认

⚠️ 如果没按空格直接回车,会显示 "No platforms selected",什么都不会配。

3. 按向导填信息

• How would you like to set up Feishu/Lark? → 选 2(使用已有应用)
• App ID → 粘贴
• App Secret → 粘贴
• Domain → feishu(中国版)/ lark(国际版)
• Connection mode → websocket(强烈推荐,不要公网 IP)
• How should direct message be authorized? → 选 1(pairing code 私聊配对)
• How should group chats be handled? → 选 1
• Install as launchd service? → Mac Mini 等常开设备选 Y(后台自启)

4. 放开用户白名单

启动后会看到 WARNING:

No user allowlists configured. All unauthorized users will be denied.

测试阶段最快的办法:

echo 'GATEWAY_ALLOW_ALL_USERS=true' >> ~/.hermes/.env
hermes gateway restart

5. 验证连接

查看日志:

tail -f ~/.hermes/logs/agent.log

看到这行就说明连上飞书了:

[Lark] connected to wss://msg-frontier.feishu.cn/...

---

五、测试对话

1. 在飞书里找到机器人

• 在飞书 App 顶部搜索你的应用名字
• 或在开放平台应用详情点"添加到工作台"

2. 私聊发消息

发一句"你好",机器人应该能直接回复(因为已经开了 ALLOW_ALL_USERS)。

3. Gateway 管理命令

hermes gateway status   # 查看状态
hermes gateway start    # 启动
hermes gateway stop     # 停止
hermes gateway restart  # 重启
hermes gateway run      # 前台运行,方便看日志

看日志的正确方式(Mac launchd 服务):

ls ~/.hermes/logs/
tail -f ~/.hermes/logs/agent.log

---

六、常见问题排查

机器人完全没反应

按概率排查:

1. 应用没发布(80% 是这个)

去 open.feishu.cn → 版本管理与发布 → 确认有"已发布"版本。

2. 没订阅 im.message.receive_v1 事件

事件与回调 → 事件配置 → 添加订阅事件。

3. 权限不全

至少要有 im:message 和 im:message.p2p_msg:readonly,改完要重新创建版本并发布。

4. 机器人能力没启用

应用能力 → 确认机器人是"已启用"。

报错:Access denied. Scope required: application:application:self_manage

这是可选的权限,不影响私聊,但群聊 @ 识别会受影响。处理方式:

1. 开放平台 → 权限管理 → 添加 application:application:self_manage
2. 创建新版本并发布
3. hermes gateway restart

WARNING:No user allowlists configured

测试阶段可以跳过或者直接放开:

echo 'GATEWAY_ALLOW_ALL_USERS=true' >> ~/.hermes/.env
hermes gateway restart

生产建议走 pairing 或配置白名单。

---

七、进阶:安装飞书 CLI 让 Hermes 能读聊天记录和文件

Hermes Bot 本身只能收到 @ 或私聊它的消息,读不了群里历史聊天、云文档、多维表格。要让 Hermes 真正"接管"飞书,需要装飞书 CLI。

飞书 CLI 能做什么?

• 读取:即时消息、云文档、电子表格、多维表格、日历、妙记、邮箱、知识库、任务、通讯录
• 操作:创建文档、发消息、建多维表格、约会议、处理邮件

关键差异:

	Hermes 的 Feishu 应用	lark-cli 应用
身份	机器人(Bot)	你本人(User)
用途	接收消息、发消息	读你能看到的一切
权限范围	机器人权限	你账号的权限

1. 安装 lark-cli

# 海外网络
npm install -g @larksuite/cli

# 国内走镜像
npm install -g @larksuite/cli --registry https://registry.npmmirror.com

2. 安装 Skills

npx skills add larksuite/cli -y -g

3. 验证

lark-cli --version

如果找不到命令:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4. 创建 CLI 专用应用

lark-cli config init

会弹浏览器链接,创建一个新应用(和 Hermes Bot 是两个独立应用),起个名比如 "Lark CLI",创建完回终端自动拿到凭证。

5. 登录授权

lark-cli auth login --recommend

--recommend 自动勾选常用权限(消息、文档、日历、多维表格、邮件等),省得一个个选。

浏览器弹出后扫码同意即可。

6. 验证登录

lark-cli auth status
lark-cli auth whoami
lark-cli calendar +agenda      # 看今天日程
lark-cli im +chats-list        # 列出聊天会话

7. 让 Hermes 用上 lark-cli

方法 A:让 Hermes 自动学习

直接在飞书私聊 Hermes:

用飞书 CLI 拉一下我最近的聊天会话列表

Hermes 会自己摸索命令,并把经验沉淀成 skill。

方法 B:手动创建 skill 指南(推荐)

mkdir -p ~/.hermes/skills/lark-cli
cat > ~/.hermes/skills/lark-cli/SKILL.md <<'EOF'
# 飞书 CLI (lark-cli) 使用指南

当用户要求操作飞书(读消息、写文档、查日历、查多维表格、收发邮件等)时,使用 lark-cli 命令行工具。

## 常用命令

### 即时消息
- lark-cli im +chats-list - 列出聊天会话
- lark-cli im +messages-list --chat-id <id> - 读取某个聊天的消息
- lark-cli im +messages-send --chat-id <id> --text "内容" - 发送消息
- lark-cli im +files-download --message-id <id> --file-key <key> - 下载聊天文件

### 云文档
- lark-cli docs +create --title "标题" --markdown "# 内容" - 创建文档
- lark-cli docs +read --doc-token <token> - 读取文档内容
- lark-cli docs +search --query "关键词" - 搜索文档

### 多维表格
- lark-cli base +records-list --app-token <token> - 列出表格记录
- lark-cli base +records-create --app-token <token> --fields '{...}' - 新增记录

### 日历
- lark-cli calendar +agenda - 今日议程
- lark-cli calendar +events-create --title "标题" --start "..." - 创建日程

### 邮箱
- lark-cli mail +messages-list - 列出邮件
- lark-cli mail +messages-send --to "..." --subject "..." --body "..." - 发邮件

### 妙记(会议纪要)
- lark-cli minutes +list - 列出妙记
- lark-cli minutes +transcript --minute-id <id> - 获取逐字稿

## 调用提示
- 不确定参数时运行 lark-cli <module> --help 查看
- 输出默认是 JSON,便于解析
- 出错时 CLI 会告诉你缺什么权限,直接跟着提示补授权
EOF

hermes gateway restart

---

八、实战玩法

配好之后,在飞书私聊 Hermes 试这些:

1. 用飞书 CLI 列出我最近的 5 个聊天会话

2. 帮我查一下我今天的飞书日程

3. 把 [群聊名] 里今天的消息总结成要点

4. 读一下我昨天那篇文档 [文档名],总结核心内容

5. 在多维表格 [名字] 里新增一条记录:...

6. 把这份 Markdown 内容创建成飞书文档,排版要好看

Hermes 会自动调 lark-cli 完成任务,并把经验沉淀成 skill,下次更顺。

---

九、关于 Token 消耗参考

很多人关心 1M tokens 能用多久,粗略参考:

使用强度	单次消耗	1M tokens 能用
纯聊天	500-2000 tokens	1-3 个月(每天 20 轮)
一般 Agent 任务	5k-20k tokens	10-40 天(每天 5 个任务)
重度任务(读大文档)	50k-200k tokens	3-10 天(每天 2 个)

省 token 技巧:

• 便宜模型做日常,贵模型做关键任务(hermes model 切换)
• 定期清理会话历史
• 关闭不用的 skills
• 任务说清楚,减少 Agent 试错

个人用户推荐 DeepSeek --- 国内访问快、便宜、Agent 能力够用,10 块钱能撑挺久。

---

十、总结

到这一步,你已经拥有了:

• ✅ 一个运行在 Mac Mini 上 24 小时在线的 AI Agent
• ✅ 可以在飞书里随时唤起它对话
• ✅ 能让它读取飞书聊天、文档、多维表格
• ✅ 能让它自动创建文档、发消息、约会议
• ✅ 越用越懂你的使用习惯

Hermes 的核心卖点是会自我成长------每次你教它做一件事,它都会沉淀成 skill,第二次再做就熟练很多。

建议把一些高频任务写成固定的触发话术,比如:

• "整理本周会议纪要"
• "给 [某人] 发份周报"
• "把 [文档] 翻译成英文重新发到飞书"

用上一两周,你会发现它真的在进化。

参考链接

• GitHub 仓库:github.com/NousResearc...
• 官方文档:hermes-agent.nousresearch.com/docs/
• 飞书 CLI:github.com/larksuite/c...
• 飞书开放平台:open.feishu.cn

---

如果这篇文章帮到你,欢迎点赞收藏转发 👍