【AI工具】飞书 CLI 用法指南

引言

断更一个月的我终于回来了！断更一个月发生了很多有趣的事！搬家，回西安，折腾房子，黄毛来临，etc。最近加入了一个研究院AI落地小分队，在折腾打通飞书与Agent这件事。恰逢前段时间飞书 CLI 开源，本文会系统性地介绍一下飞书 CLI 的用法，以及在实际场景中的应用案例。

定义

官方对lark-cli的定位非常明确：给 AI Agent 一双操作飞书的手。这句话很准确，因为在没有执行层之前，Agent 只能阅读外部文本、生成建议，却无法进入飞书这一实际工作场景。飞书 CLI 的价值，恰恰在于把“生成建议”推进到了“执行任务”。

飞书 CLI 具备以下特点：

面向 人类用户与 AI Agent 双场景设计
覆盖 18 个业务域
提供 200+ 命令
配套 26 个 AI Agent Skills

飞书 CLI 能做什么

飞书 CLI 已经覆盖了飞书生态中的核心协作场景，任何已经暴露在飞书开放 API 中的能力，原则上都可以被 CLI 和 Agent 组合起来。主要能力包括：

业务域	典型能力
消息与群组	发消息、回复消息、搜索消息、管理群聊、下载文件与图片
文档	创建、读取、更新云文档，插入媒体，处理评论
云空间	上传下载文件、搜索文档、管理权限与评论
电子表格 / 多维表格	读写单元格、管理记录、字段、视图、仪表盘与自动化
日历	查询日程、创建会议、查忙闲、推荐空闲时间、预定会议室
邮箱	搜索邮件、读取邮件、起草、发送、回复、转发
任务	创建任务、管理清单、更新状态、拆分子任务
通讯录	搜索用户、读取用户资料
知识库 / Wiki	管理空间、节点、文档结构
会议 / 妙记	查询会议记录、纪要、待办、逐字稿与录制产物

核心概念：飞书 App 是一切的起点

理解飞书 CLI，首先必须理解 飞书 App。

lark-cli / 飞书开放 API 的底座，始终是一个飞书应用（app）。这个 app 负责三件事：

持有凭证：appId / appSecret
申请权限（scope）
完成 OAuth 授权

也就是说，CLI 不是绕开飞书开放平台直接操作飞书；它本质上仍然是在一个合法的 飞书应用 框架内工作，只是把配置、授权、调用、输出格式和 AI Agent 适配都包装得更易用。

因此，下面这几个判断非常重要：

没有 app：基本无法通过开放 API 正规地操作飞书
有 app 但没有用户授权（即登录）：仍可做部分应用身份操作，但无法访问用户个人资源
没有 bot 能力：仍可能代用户做事，但无法形成“飞书里有个机器人”的产品体验

飞书 CLI 的安装

在 AI Agent 中输入：

1	帮我安装飞书 CLI: https://open.feishu.cn/document/no_class/mcp-archive/feishu-cli-installation-guide.md

这个文档包含四个步骤：

安装：通过 npm 全局安装 @larksuite/cli，并用 npx 安装配套的 CLI Skill（必需组件）。Skill 的安装目录默认是在 ~/.lark-cli/skills/
配置应用凭证：Agent 运行 lark-cli config init --new 命令，需要用户在浏览器端配合完成授权。
登录：Agent 运行 lark-cli auth login --recommend，提取授权链接后发给用户完成登录。
验证：运行 lark-cli auth status 检查登录状态是否成功。（当前 app 是谁、bot 是否 ready、user 是否 ready、当前授权用户是谁、当前 token 是否有效）

其实这个自动化的安装流程使用了很多默认参数，适合初次简单配置.
下面介绍这几个命令的更多用法，适合定制化配置：

`lark-cli config init` — 配置应用凭证

--app-id：直接传入 App ID，跳过交互式输入
--app-secret-stdin：从标准输入读取 App Secret，避免密钥暴露在进程列表中
--brand：指定品牌，feishu（默认）或 lark（国际版）
--name：创建或更新一个命名配置，配合 --profile 管理多个应用
--new：直接创建新应用，跳过模式选择
--force-init：在 Agent 工作区（OPENCLAW_HOME / HERMES_HOME）中强制初始化，通常应改用 config bind

`lark-cli auth login` — 登录授权

--recommend：只申请推荐权限（可自动审批）
--domain：按业务模块申请权限，可逗号分隔，如 --domain calendar,im。支持：approval / base / calendar / contact / docs / drive / im / mail / sheets / task / wiki / all 等
--scope：精细化指定具体权限，与 --domain / --recommend 叠加生效
--exclude：从申请列表中排除指定权限
--no-wait：立即返回授权链接，不阻塞等待用户完成授权
--device-code：配合 --no-wait 使用，用上一步返回的 device code 完成授权
--json：以 JSON 格式输出结果，便于脚本解析

`lark-cli auth` — 授权管理

login：Device Flow 授权登录
logout：退出登录，清除 token
status：查看当前登录状态：
list：列出所有已登录的用户
check：检查当前 token 是否具备指定权限
scopes：查询当前应用已开启的权限范围
qrcode：为授权链接生成二维码，支持 ASCII 和 PNG 格式

飞书 CLI 的常用功能

消息相关

# 以用户身份发消息
lark-cli im +messages-send --as user --chat-id "oc_xxx" --text "大家好"

# 以机器人身份发消息
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "大家好"

# 搜索消息
lark-cli im messages search --query "项目进展"

文档相关

# 读取文档
lark-cli docs +fetch --api-version v2 --doc "<文档链接或 token>"

# 创建文档
lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'

# 更新文档（追加内容）
lark-cli docs +update --api-version v2 --doc "<文档链接或 token>" --command append --content '<p>补充内容</p>'

日历/会议等

# 查看日程
lark-cli calendar +agenda

# 查询会议
lark-cli calendar events list

`--as user` 与 `--as bot`

与身份有关的 lark-cli 命令（例如聊天）通常会有 --as user 与 --as bot 两个参数，他们的区别如下：

权限类型	CLI 身份	Token 类型	含义
用户身份权限	`--as user`	`user_access_token`	以用户身份调用 API 或订阅事件
应用身份权限	`--as bot`	`tenant_access_token`	以应用 / 机器人身份调用 API 或订阅事件

`--as user`

适用于：

代用户本人发消息
读取或修改用户可访问的文档
读取用户日历、邮箱、任务等个人资源
以“用户自己的身份”执行操作

本质上，是一种“用户授权后的代理执行”。

`--as bot`

适用于：

让机器人自己在群里发消息
让机器人被 @ 后自动回复
以应用名义参与群聊或工作流
执行应用级别、bot 级别的自动化能力

本质上，它是一种“应用作为独立主体执行”。

权限申请与授权

飞书 CLI 的权限体系，本质上仍然遵循飞书开放平台规则。通常可以拆成两个步骤：

第一步：开通 App / Bot 权限

涉及应用身份或用户身份的能力时，都需要先在飞书开发者后台开通相应 scope。

如果权限受组织控制，往往还需要：

提交应用权限修改申请
等待组织内部审批通过

例如，涉及 bot 能力时，通常需要先完成这一层，否则即使命令写对了，也拿不到可用权限。

第二步：进行用户授权

如果任务涉及用户资源，则还需要用户自己确认授权。

在 Agent 场景下，CLI 会生成一个授权链接，用户在浏览器中确认后，CLI 才能获得 user_access_token。

在实际体验里，这两步经常可以被“串起来”

CLI 直接先发起用户授权流程
如果某些 scope 尚未开通，飞书授权页会自动把未审批的权限一并提交申请

典型应用：代替用户操作飞书

当用户完成授权后，Agent 可以在 --as user 模式下：

代用户发消息
读取未读消息并整理摘要
读取文档并自动改写、补充、评论
读取日历并安排会议
搜索邮箱并起草回复
操作表格、多维表格、知识库、任务等资源

这类能力的本质不是“生成一段建议让用户手动执行”，而是直接进入飞书工作现场替用户完成动作。

这使得飞书 CLI 适合被用作：

个人办公助理
跨应用工作流执行器
企业内部协作自动化入口
连接 AI 规划能力与企业业务系统的操作层

典型应用：Hermes / OpenClaw 这类聊天机器人

像 Hermes、OpenClaw 这类产品，经常表现为：用户在飞书里和一个机器人对话，然后机器人再去执行本地或云端任务。

从技术上看，这类系统通常不是单纯的 as user 或单纯的 as bot，而是入口与执行分离：

入口通常是 `as bot`

因为用户是在飞书里“和一个机器人说话”：

它需要被 @
需要在群里出现
需要接收消息并回复

这部分天然属于 bot 身份。

执行用户资源操作时可能切到 `as user`

如果机器人要：

读用户日历
改用户文档
发用户邮件
读取用户私聊与任务

那就必须切到用户授权身份，也就是 --as user。

因此，比较成熟的 Agent 架构通常是：

聊天入口：bot
资源执行：user（必要时）

这也是为什么这类应用看起来像“飞书里的机器人”，但实际背后往往同时依赖 bot 授权链路和 user 授权链路。

参考资料

Larksuite 官方 GitHub 仓库：https://github.com/larksuite/cli
官方介绍文档《飞书 CLI：给 Agent 一双操作飞书的手》：https://open.larkoffice.com/document/mcp_open_tools/feishu-cli-let-ai-actually-do-your-work-in-feishu.md
飞书CLI安装与使用指南：让AI Agent真正接入飞书！：https://www.feishu.cn/content/article/7623291503305083853

引言

定义