【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 的基本用法

人类了解一下就好

安装

官方推荐安装方式：

1	npx @larksuite/cli@latest install

安装完成后，通常还需要重启 AI 工具或终端环境，以确保相关 Skills 正常加载。

初始化应用配置

1	lark-cli config init

如果是 AI Agent 场景，官方推荐：

1	lark-cli config init --new

这一步会创建或绑定一个飞书应用，并生成后续授权所需的配置。

用户授权

1	lark-cli auth login --recommend

也可以按业务域申请：

1	lark-cli auth login --domain calendar,docs,im

或者按具体 scope 精确申请：

1	lark-cli auth login --scope "im:message:readonly"

在 AI Agent 场景中，经常使用非阻塞授权：

1	lark-cli auth login --domain all --no-wait --json

拿到授权链接后，发给用户；用户完成授权，再用 device_code 续上轮询。

查看当前状态

1	lark-cli auth status

它能告诉你：

当前 app 是谁
bot 是否 ready
user 是否 ready
当前授权用户是谁
当前 token 是否有效

查看已授予权限

1	lark-cli auth scopes

发送消息

以用户身份发消息：

1	lark-cli im +messages-send --as user --chat-id "oc_xxx" --text "大家好"

以机器人身份发消息：

1	lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "大家好"

读取和更新文档

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

1	lark-cli docs +update --api-version v2 --doc "<文档链接或 token>" --command append --content '<p>补充内容</p>'

`--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

引言

定义