飞书 CLI + Hermes Agent：让 AI 以你的身份接管飞书

2026年5月12日 · 阅读需 6 分钟

全栈开发者

飞书官方在 2026 年 4 月开源了飞书 CLI（lark-cli），一个月内 GitHub Stars 飙到 9.8k。这个工具最大的亮点是：让 AI Agent 能以用户的个人身份操作飞书。我花了一个下午把它接入了 Hermes Agent，这篇文章记录整个过程和踩过的坑。

为什么需要飞书 CLI

在接入飞书 CLI 之前，我们已经通过飞书开放平台的 App 机制和飞书打通了——创建了一个企业自建应用，拿到 App ID 和 App Secret，用 tenant_access_token 调 API。

这套方案能用，但有几个绕不过去的问题：

文档写入受限：tenant_access_token 调 POST blocks 接口写文档正文，返回权限不足。文档只能创建空壳，内容写不进去
身份是机器人：所有操作都显示为"应用"发出的，不是我本人
能力覆盖不全：日历、邮箱、任务、知识库、审批这些个人级资源，应用身份根本没法访问

飞书 CLI 用的是 OAuth Device Flow，走用户个人授权。授权完成后，所有操作都以你本人的身份执行。

安装

一行命令搞定：

npx @larksuite/cli@latest install --lang zh

安装过程会自动升级到最新版本（目前是 v1.0.28）并安装 Skills。

如果你的环境已经有 Hermes Agent 在运行，安装时可能会遇到这个提示：

config init is refused inside hermes context

这是因为飞书 CLI 检测到 Hermes 环境，不允许自动创建新的飞书应用配置（避免和 Hermes 已绑定的飞书应用冲突）。需要手动绑定。

绑定 Hermes Agent

飞书 CLI 支持直接绑定到 Hermes 已有的飞书应用凭证：

lark-cli config bind --source hermes --identity user-default

这里有两种身份模式可选：

模式	说明	适用场景
`bot-only`	仅应用身份，不模拟用户	安全优先，不需要个人资源
`user-default`	以用户身份操作	需要读写文档、日历、邮箱等

选 user-default 才能发挥飞书 CLI 的全部能力。绑定成功后会输出：

{
  "app_id": "cli_a92291d0bf789bce",
  "identity": "user-default",
  "message": "已绑定应用到 Hermes"
}

个人授权

绑定完还需要用飞书账号登录授权。飞书 CLI 用的是 Device Flow（设备码授权），流程是这样的：

# 第一步：获取设备码和授权链接
lark-cli auth login --domain all --no-wait --json

会返回一个授权链接和 device_code：

{
  "device_code": "OgqtsP12yXL01Nb...",
  "verification_url": "https://accounts.feishu.cn/oauth/v1/device/verify?...",
  "expires_in": 600
}

把 verification_url 发给用户，在浏览器中打开并用飞书账号登录授权。

# 第二步：轮询等待授权完成
lark-cli auth login --device-code "OgqtsP12yXL01Nb..."

这个命令会阻塞等待（最长 10 分钟），用户在浏览器完成授权后自动返回。

踩坑提醒：

授权链接 10 分钟过期，过期后必须重新获取 device_code
不要短 timeout 反复重试——每次重启会作废上一轮的 device code，导致用户已打开的授权链接失效
如果用 AI Agent 自动化这个流程，timeout 设置要 ≥ 600 秒

授权成功后可以验证状态：

lark-cli auth status

{
  "identity": "user",
  "userName": "张志",
  "tokenStatus": "valid",
  "expiresAt": "2026-05-12T19:09:41+08:00",
  "refreshExpiresAt": "2026-05-19T17:09:41+08:00"
}

能力一览

飞书 CLI 目前支持 200+ 命令，覆盖以下业务域：

lark-cli im          # 消息与群组
lark-cli docs        # 云文档
lark-cli drive       # 云空间
lark-cli sheets      # 电子表格
lark-cli base        # 多维表格
lark-cli calendar    # 日历
lark-cli vc          # 视频会议
lark-cli minutes     # 妙记
lark-cli mail        # 邮箱
lark-cli task        # 任务
lark-cli approval    # 审批
lark-cli wiki        # 知识库
lark-cli contact     # 通讯录
lark-cli okr         # OKR
lark-cli slides      # 演示文稿
lark-cli attendance  # 考勤
lark-cli whiteboard  # 白板
lark-cli markdown    # Markdown 文档
lark-cli event       # 事件订阅

每个命令都有 + 前缀的快捷方式（Skills），比如：

# 发消息
lark-cli im +messages-send --chat-id oc_xxx --text "Hello"

# 查日程
lark-cli calendar +agenda

# 搜索群聊
lark-cli im +chat-search --query "项目组"

和之前方案的对比

能力	之前（应用身份）	现在（飞书 CLI）
发消息	✅ 机器人身份	✅ 个人身份
写文档正文	❌ 权限不足	✅
日历管理	❌	✅
邮箱收发	❌	✅（需开通企业邮箱）
任务管理	❌	✅
知识库	❌	✅
审批流程	❌	✅
消息搜索	❌	✅
会议纪要	❌	✅

在 Hermes Agent 中使用

接入之后，Hermes Agent 可以通过 terminal 工具直接调用 lark-cli 命令。比如：

# 以张志的身份给群里发消息
lark-cli im +messages-send --chat-id oc_xxx --text "这条消息是以我的个人身份发的"

# 查看今天的日程
lark-cli calendar +agenda

# 搜索最近的消息
lark-cli im +messages-search --query "周报"

也可以配置为 MCP Server，写到 Hermes 的 config.yaml 里：

mcp:
  servers:
    feishu:
      command: lark-cli
      args: ["mcp"]

这样 Hermes 就能把飞书 CLI 的所有能力当成原生工具调用。

注意事项

授权有效期：access_token 2 小时过期，refresh_token 7 天过期。飞书 CLI 会自动刷新 access_token，但 7 天后需要重新授权
企业管控：企业管理员可以控制 CLI 的 API 权限范围，某些敏感操作可能被限制
邮箱前提：邮箱功能需要企业开通了飞书企业邮箱，否则会返回 user does not have email
共存关系：飞书 CLI 和已有的飞书应用可以共存，两套认证体系互不影响。CLI 走用户 OAuth，应用走 tenant_token
安全提醒：user-default 模式下，AI Agent 以你的身份操作飞书。不要把绑定了 CLI 的机器人分享给其他人

总结

飞书 CLI 补齐了 AI Agent 操作飞书的最后一块拼图——个人身份。之前用应用身份做不到的事（写文档、管日历、收邮件），现在都能做了。

整个接入过程大概 10 分钟：安装 → 绑定 → 授权。对于已经在用 Hermes Agent 的场景，这是一个投入产出比很高的升级。

相关链接：

为什么需要飞书 CLI​

安装​

绑定 Hermes Agent​

个人授权​

能力一览​

和之前方案的对比​

在 Hermes Agent 中使用​

注意事项​

总结​