Mac 从零部署 Hermes Agent 并接入飞书:一篇就够的保姆级教程前言:为什么是 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

向导会问:

选 LLM 服务商 — 国内推荐 DeepSeek(便宜稳定)、Kimi、智谱 GLM
粘贴 API Key — 去对应官网申请
选具体模型
是否配消息平台 — 可以先跳过,后面单独配
可选工具 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. 订阅事件(关键)

事件与回调 → 事件配置:

订阅方式选 长连接 (不是 Webhook)
添加订阅事件:
- im.message.receive_v1 — 接收消息事件(必需)
- im.message.message_read_v1 — 消息已读(可选)

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

6. 发布版本

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

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

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

四、在 Hermes 里接入飞书

1. 运行 Gateway 配置

hermes setup gateway

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

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

看到平台列表时:

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

⚠️ 如果没按空格直接回车,会显示 "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`

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

开放平台 → 权限管理 → 添加 application:application:self_manage
创建新版本并发布
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 命令行工具。大部分 im 命令支持 `--as user|bot`,默认 user。`--as user` 以登录用户身份能看到所有私聊群聊文档,读取类操作用这个;`--as bot` 以机器人身份只能看到机器人参与的聊天,主动发消息可以用。读取用户数据省略 --as 即可,遇到 "Bot 身份无法列出私聊" 时显式加 --as user。

即时消息(im)相关命令:搜索聊天会话用 `lark-cli im +chat-search --query "关键词"`,注意 +chat-search 必须提供 --query 或 --member-ids 不能空参数调用;按成员 open_id 搜私聊用 `lark-cli im +chat-search --member-ids "ou_xxx"`;只搜私聊加 `--search-types private`;按最近活跃排序加 `--sort-by update_time_desc`;表格输出加 `--format table`。真正列出全部最近聊天 chat-search 不支持,用原生 API:`lark-cli api --method GET --path "/open-apis/im/v1/chats?page_size=20"`。读取消息用 `lark-cli im +chat-messages-list --chat-id <id>` 或 `--user-id <id>` 自动解析 P2P 私聊;跨所有聊天搜消息用 `lark-cli im +messages-search --query "关键词"` 这个 user-only 最实用;批量取消息详情用 `lark-cli im +messages-mget --ids om_xxx,om_yyy`;读话题回帖用 `lark-cli im +threads-messages-list --message-id <id>`。发送消息用 `lark-cli im +messages-send --chat-id <id> --text "内容"` 或 `--user-id <id>`;回复某条消息用 `lark-cli im +messages-reply --message-id <id> --text "回复"`。下载图片文件用 `lark-cli im +messages-resources-download --message-id <id> --file-key <key>`。群管理:建群 `lark-cli im +chat-create --name "群名"`,改群信息 `lark-cli im +chat-update --chat-id <id> --name "新群名"`。

通讯录从姓名拿 open_id(很多命令需要):`lark-cli contact +user-search --query "姓名"`,具体命令查 `lark-cli contact --help`。云文档 `lark-cli docs --help` 查具体命令,创建用 `lark-cli docs +create --title "标题" --markdown "# 内容"`。多维表格查 `lark-cli base --help`。日历今日议程 `lark-cli calendar +agenda`,其他查 `lark-cli calendar --help`。邮箱查 `lark-cli mail --help`。妙记会议纪要查 `lark-cli minutes --help`。云盘查 `lark-cli drive --help`。

调用规则 Agent 必须遵守:不确定命令或参数时先跑 `lark-cli <模块> --help` 再跑 `lark-cli <模块> +<命令> --help` 核对,绝不凭记忆瞎猜命令名;命令用 + 前缀如 +chat-search 不是破折号;输出格式 --format 支持 json pretty table ndjson csv 默认 json 便于解析;jq 筛选用 `--jq '.items[] | {chat_id, name}'` 只保留关心字段;分页用 --page-size(1-100)和 --page-token;不确定时加 --dry-run 只打印请求不执行;CLI 没封装的接口用 `lark-cli api --method GET --path "/open-apis/..."` 兜底。

常见错误及处理:报 `unknown flag: --xxx` 跑 --help 核对参数名不同版本 flag 可能不同;报 `invalid choice: 'xxx'` 命令名错了跑 `lark-cli <模块> --help` 看实际命令列表;报 `Bot 身份无法列出私聊` 显式加 --as user 或重新用户身份登录 `lark-cli auth login --recommend --domain all`;报 `--query and --member-ids cannot both be empty` chat-search 必须带查询条件见上文 workaround;报 `Scope required: xxx` 补授权 `lark-cli auth login --scope "xxx"`;命令返回空或报权限确认登录身份 `lark-cli auth whoami` 和已授权 scope `lark-cli auth status`。

重要原则:遇到报错不要硬猜命令,先 --help,命令错了就换,参数错了就改,lark-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

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

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