本文基于實際踩坑過程整理,從 Hermes 安裝到飛書 Bot + 飛書 CLI 完整打通,包含所有可能遇到的報錯和解決方案。跟著做 30 分鐘就能讓 AI 在飛書里替你干活。

前言:為什么是 Hermes Agent

Hermes Agent 是 Nous Research 開源的 AI Agent 框架,和 OpenClaw 同類,最大特點是會自我成長:

• 記住跨會話的上下文
• 自動沉淀技能文檔(Skill)
• 越用越懂你

定位是"一個運行在你自己服務器上、用得越久越聰明的開源 AI Agent"。

接入飛書后能實現:

• 飛書里直接 @ 機器人對話
• 讀取聊天記錄、云文檔、多維表格
• 自動創(chuàng)建文檔、發(fā)消息、約會議
• 24 小時在線,手機隨時喚起

一、前置準備:安裝基礎依賴

1. 安裝 Homebrew

打開 Mac 終端,粘貼執(zhí)行:

/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

安裝過程會自動:

• 克隆倉庫
• 創(chuàng)建 venv
• 安裝所有依賴
• 把 hermes 命令加到 PATH

不要用 sudo,否則后續(xù) 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(便宜穩(wěn)定)、Kimi、智譜 GLM
2. 粘貼 API Key — 去對應官網申請
3. 選具體模型
4. 是否配消息平臺 — 可以先跳過,后面單獨配
5. 可選工具 Key — Firecrawl、FAL 等,全部跳過,用到再配

常用服務商申請地址:

5. 驗證對話能力

hermes doctor          # 全綠就 OK
hermes chat -q "你好"  # 能返回 回復

三、在飛書開放平臺創(chuàng)建應用

在接入 Hermes 之前,必須先在飛書后臺建一個自建應用。

1. 創(chuàng)建應用

訪問 open.feishu.cn → 開發(fā)者后臺 → 創(chuàng)建企業(yè)自建應用

填好名字、描述、頭像后創(chuàng)建。

2. 記錄憑證

應用詳情 → 憑證與基礎信息,記下:

• App ID
• App Secret

后面 Hermes 配置要用。

3. 啟用機器人能力

應用能力 → 啟用 機器人。

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

權限管理 → 添加下面這些權限:

5. 訂閱事件(關鍵)

事件與回調 → 事件配置:

1.訂閱方式選 長連接 (不是 Webhook)

2.添加訂閱事件:

• im.message.receive_v1 — 接收消息事件(必需)
• im.message.message_read_v1 — 消息已讀(可選)

90% 的"機器人沒反應"都是因為沒訂閱這個事件

6. 發(fā)布版本

版本管理與發(fā)布 → 創(chuàng)建版本 → 填版本號(如 1.0.0)→ 提交審批。

• 企業(yè)管理員:自己在飛書里審批,秒過
• 普通成員:找管理員審批

可用范圍建議選 全員可用,省得自己不在白名單里。

四、在 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. 私聊發(fā)消息

發(fā)一句"你好",機器人應該能直接回復(因為已經開了 ALLOW_ALL_USERS)。

3. Gateway 管理命令

hermes gateway status   # 查看狀態(tài)
hermes gateway start    # 啟動
hermes gateway stop     # 停止
hermes gateway restart  # 重啟
hermes gateway run      # 前臺運行,方便看日志

看日志的正確方式(Mac launchd 服務):

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

六、常見問題排查

機器人完全沒反應

按概率排查:

1. 應用沒發(fā)布(80% 是這個)

去 open.feishu.cn → 版本管理與發(fā)布 → 確認有"已發(fā)布"版本。

2. 沒訂閱 im.message.receive_v1 事件

事件與回調 → 事件配置 → 添加訂閱事件。

3. 權限不全

至少要有 im:message 和 im:message.p2p_msg:readonly,改完要重新創(chuàng)建版本并發(fā)布。

4. 機器人能力沒啟用

應用能力 → 確認機器人是"已啟用"。

報錯:Access denied. Scope required: application:application:self_manage

這是可選的權限,不影響私聊,但群聊 @ 識別會受影響。處理方式:

1. 開放平臺 → 權限管理 → 添加 application:application:self_manage
2. 創(chuàng)建新版本并發(fā)布
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 能做什么

• 讀取:即時消息、云文檔、電子表格、多維表格、日歷、妙記、郵箱、知識庫、任務、通訊錄
• 操作:創(chuàng)建文檔、發(fā)消息、建多維表格、約會議、處理郵件

關鍵差異:

安裝 lark-cli

# 海外網絡
npm install -g @larksuite/cli

# 國內走鏡像
npm install -g @larksuite/cli --registry https://registry.npmmirror.com

安裝 Skills

npx skills add larksuite/cli -y -g

驗證

lark-cli --version

如果找不到命令:

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

創(chuàng)建 CLI 專用應用

lark-cli config init

會彈瀏覽器鏈接,創(chuàng)建一個新應用(和 Hermes Bot 是兩個獨立應用),起個名比如 "Lark CLI",創(chuàng)建完回終端自動拿到憑證。

登錄授權

lark-cli auth login --recommend

--recommend 自動勾選常用權限(消息、文檔、日歷、多維表格、郵件等),省得一個個選。

瀏覽器彈出后掃碼同意即可。

驗證登錄

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

讓 Hermes 用上 lark-cli

方法 A:讓 Hermes 自動學習

直接在飛書私聊 Hermes:

用飛書 CLI 拉一下我最近的聊天會話列表

Hermes 會自己摸索命令,并把經驗沉淀成 skill。

方法 B:手動創(chuàng)建 skill 指南(推薦)

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

當用戶要求操作飛書(讀消息、寫文檔、查日歷、查多維表格、收發(fā)郵件等)時,使用 lark-cli 命令行工具。

## 常用命令

### 即時消息
- lark-cli im +chats-list - 列出聊天會話
- lark-cli im +messages-list --chat-id <id> - 讀取某個聊天的消息
- lark-cli im +messages-send --chat-id <id> --text "內容" - 發(fā)送消息
- lark-cli im +files-download --message-id <id> --file-key <key> - 下載聊天文件

### 云文檔
- lark-cli docs +create --title "標題" --markdown "# 內容" - 創(chuàng)建文檔
- 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 "..." - 創(chuàng)建日程

### 郵箱
- lark-cli mail +messages-list - 列出郵件
- lark-cli mail +messages-send --to "..." --subject "..." --body "..." - 發(fā)郵件

### 妙記(會議紀要)
- lark-cli minutes +list - 列出妙記
- lark-cli minutes +transcript --minute-id <id> - 獲取逐字稿

## 調用提示
- 不確定參數時運行 lark-cli <module> --help 查看
- 輸出默認是 JSON,便于解析
- 出錯時 CLI 會告訴你缺什么權限,直接跟著提示補授權
EOF

hermes gateway restart

八、實戰(zhàn)玩法

配好之后,在飛書私聊 Hermes 試這些:

1. 用飛書 CLI 列出我最近的 5 個聊天會話

2. 幫我查一下我今天的飛書日程

3. 把 [群聊名] 里今天的消息總結成要點

4. 讀一下我昨天那篇文檔 [文檔名],總結核心內容

5. 在多維表格 [名字] 里新增一條記錄:...

6. 把這份 Markdown 內容創(chuàng)建成飛書文檔,排版要好看

Hermes 會自動調 lark-cli 完成任務,并把經驗沉淀成 skill,下次更順。

九、關于 Token 消耗參考

很多人關心 1M tokens 能用多久,粗略參考:

省 token 技巧:

• 便宜模型做日常,貴模型做關鍵任務(hermes model 切換)
• 定期清理會話歷史
• 關閉不用的 skills
• 任務說清楚,減少 Agent 試錯

個人用戶推薦 DeepSeek — 國內訪問快、便宜、Agent 能力夠用,10 塊錢能撐挺久。

十、總結

到這一步,你已經擁有了:

• 一個運行在 Mac Mini 上 24 小時在線的 AI Agent
• 可以在飛書里隨時喚起它對話
• 能讓它讀取飛書聊天、文檔、多維表格
• 能讓它自動創(chuàng)建文檔、發(fā)消息、約會議
• 越用越懂你的使用習慣

Hermes 的核心賣點是會自我成長——每次你教它做一件事,它都會沉淀成 skill,第二次再做就熟練很多。

建議把一些高頻任務寫成固定的觸發(fā)話術,比如:

• "整理本周會議紀要"
• "給 [某人] 發(fā)份周報"
• "把 [文檔] 翻譯成英文重新發(fā)到飛書"

用上一兩周,你會發(fā)現它真的在進化。

以上就是Mac從零部署Hermes Agent并接入飛書的保姆級教程的詳細內容，更多關于Hermes Agent接入飛書的資料請關注腳本之家其它相關文章！

最新評論