# 飞书 CLI 安装使用完整指南：命令行操作日历/文档/消息，AI Agent 接入实测（2026）

- 原文：[https://news.qiniu.com/archives/1783564178220](https://news.qiniu.com/archives/1783564178220)
- 发布时间：2026-07-09
- 分类：教程与实践
- 标签：AI Agent、Agent Skills

飞书 CLI（@larksuite/cli，命令名 lark-cli）是字节官方推出的命令行工具，一条命令安装：**npx @larksuite/cli@latest install**，三步完成登录（config init → auth login --recommend → 验证）。它覆盖 18 个业务域、200+ 命令——日历、消息、文档、多维表格、审批、OKR 全部能在终端里操作，还内置 26 个 AI Agent Skills，让 Claude Code、Cursor、Codex 直接替你操作飞书。本文从安装、登录、核心命令到 AI 接入完整走一遍，最后说说它真正的价值点（提示：不在人类用户身上）。

我是被一篇"Codex 直接在飞书文档里画泳道图"的帖子种草的。当时的第一反应和你一样：飞书是个 GUI 产品，要 CLI 干什么？装完用了一周，我改变了看法——**这个工具的目标用户根本不是人，是 AI Agent**。官方 README 里写得很直白：面向 “humans and AI Agents”，而且排在后面的那个才是重点。理解了这一点，这个工具的所有设计就都说得通了。

![](https://news-static.qiniu.com/legacy/images/60/603c022a68143ab112d26b5867e5341753aa6bfd6cd7d6dadb1275b1c62e56ee.jpg) 

## **飞书 CLI 是什么？先看它能干什么**

lark-cli 是飞书开放平台的官方 CLI（npm 包 @larksuite/cli，MIT 协议，字节官方维护，当前版本 1.0.67）。能力范围一句话：**飞书里你手点能干的事，它基本都有对应命令**。

覆盖的业务域（共 18 个）：

|  |  |
|---|---|
| **类别** | **具体能力** |
| 日程协作 | 日历（日程创建/查询/会议室/RSVP）、视频会议、任务 |
| 内容 | 文档增删改查、云盘、Markdown、电子表格、幻灯片、知识库 Wiki |
| 数据 | 多维表格 Base（表/字段/记录/视图/仪表盘/工作流） |
| 沟通 | 消息收发、群管理、搜索、媒体下载、邮件 |
| 办公流程 | 审批、考勤、OKR、通讯录、应用发布 |

三个设计细节说明它的"Agent-Native"定位：输入注入防护（防提示注入攻击）、凭据存进系统钥匙串（不是明文配置文件）、JSON 输出严格分流（成功走 stdout、错误走 stderr——这是给程序读的，不是给人看的）。

## **安装：一条命令，30 秒搞定**

前置要求只有 Node.js（有 npx 即可）。

**方式一：npm 安装（推荐）**

 

```
npx @larksuite/cli@latest install
```

**方式二：源码安装**（需要 Go 1.23+ 和 Python 3，普通用户不需要走这条路）

 

```
git clone https://github.com/larksuite/cli.git
cd cli
make install
npx skills add larksuite/cli -y -g   # 源码方式需手动装 AI Skills
```

**方式三：懒人方式**——把安装命令直接丢给你的 AI 工具。飞书官方文档自己都这么建议：把指令复制发给 TRAE、Cursor、Codex 或 Claude Code，让它替你完成安装。实测 Claude Code 能全程自助搞定，包括踩到 npm 权限问题时自己换目录重试。

## **登录授权：三步走 + 一个关键概念**

 

```
# 第 1 步：初始化配置
lark-cli config init
 
# 第 2 步：登录授权（--recommend 自动申请常用权限集）
lark-cli auth login --recommend
 
# 第 3 步：验证——拉今天的日程试试
lark-cli calendar +agenda
```

第 2 步会打开浏览器走 OAuth 授权，扫码确认即可。**关键概念是 scope（权限范围）**：--recommend 申请的是推荐权限集，够日常用；要精细控制可以按域授权：

 

```
lark-cli auth login --domain calendar,task        # 只授权日历和任务
lark-cli auth login --scope "calendar:calendar:read"  # 精确到单个权限点
```

配套命令一览：auth status（查登录态）、auth scopes(查已授权限)、auth logout（登出）。无浏览器的服务器环境用 --no-wait + --device-code 设备码流程。

**编者注：** 很多人卡在"装完就想跑命令"，跳过了 config init——它负责生成本地配置和钥匙串条目，跳过会报找不到凭据。另一个常见坑是换飞书账号：直接重新 login 可能残留旧缓存，干净的做法是先 auth logout 再登，还不行就卸载重装清缓存（社区已有专门讲这个问题的帖子，说明踩的人不少）。

## **核心用法：三层命令体系，从人类友好到全量 API**

lark-cli 的命令分三层，理解这个结构就掌握了整个工具：

**第 ① 层：Shortcuts（+ 前缀）——人类和 AI 都爱用**

 

```
# 看今日日程
lark-cli calendar +agenda
 
# 发消息到群
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
 
# 用 Markdown 直接建文档
lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
```

**第 ② 层：API Commands——与开放平台端点 1:1 映射（100+ 命令）**

 

```
lark-cli calendar calendars list
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'
```

**第 ③ 层：Raw API——直接打 2500+ 个开放平台接口**

 

```
lark-cli api GET /open-apis/calendar/v4/calendars
lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_id"}' --data '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'
```

**四个高频实用参数：**

● --format json/pretty/table/ndjson/csv——输出格式，写脚本用 json，人看用 table

● --page-all——自动翻完所有分页（拉全量数据必备）

● --dry-run——预演不执行，发消息前先看看会发出什么

● --as user / --as bot——身份切换，同一条命令可以以你的身份或机器人身份执行

--dry-run 值得特别表扬：让 AI Agent 替你发消息之前先预演一遍，这是防"AI 幻觉发错群"的保命参数。

## **重头戏：接入 Claude Code / Cursor / Codex**

这才是 lark-cli 的真正价值。它没走 MCP 路线，而是用 **Skills 机制**——内置 26 个 Agent Skills（lark-calendar、lark-im、lark-doc、lark-base、lark-mail 等），npm 安装时自动写入本机 Agent 工具的 skill 目录，**Claude Code / Cursor / Codex 无需任何额外配置**，装完就能用。

AI Agent 场景的四步快速开始：

 

```
npx @larksuite/cli@latest install
lark-cli config init --new
lark-cli auth login --recommend    # 授权 URL 会转给你，人工扫码确认
lark-cli auth status
```

之后你就可以对 Claude Code 说人话了：

● “把这份周报整理成飞书文档发到项目群”

● “查我明天的日程，有冲突的话给对方发消息改期”

● “把这个 CSV 导入多维表格并建一个按状态分组的视图”

实测体验：文档和日历操作成功率很高；多维表格的复杂操作（跨表关联、工作流）偶尔需要人工补一步。整体上，**"AI 操作飞书"从需要自己写开放平台对接代码，变成了装一个 CLI 的事**——这是质变。

**安全提醒（官方 README 原文强调，我原样转达）：** 授权后 Agent 是以你的身份操作飞书的。存在模型幻觉、提示注入风险。官方建议：不要修改默认安全设置、机器人只当私人助手用、**不要把它加进群聊**。我再加一条实践建议：给 Agent 用的授权尽量用 --domain 收窄范围，别图省事全量授权。

## **说句实话：谁该装，谁不该装**

用了一周，我的判断很明确：

**不该装的**：指望用 CLI 替代飞书客户端日常办公的人。终端里发消息不会比点鼠标快，+agenda 看日程也不会比手机瞄一眼快。作为"人类工具"，它的效率提升接近于零。

**该装的**：① 用 Claude Code/Cursor/Codex 的开发者——这是目前把 AI Agent 接入国内办公系统最低成本的方案，没有之一；② 需要批量操作的人——比如把 200 条记录导入多维表格、批量下载群文件，--page-all + csv 输出一条命令的事；③ 写自动化脚本的——比 SDK 对接开放平台省 80% 的代码。

一句话总结：**它是"给 AI 用的飞书键盘"，人类只负责装好和授权。**

## **FAQ：飞书 CLI 高频问题**

**Q：飞书 CLI 是官方的吗？安全性如何？**

是。npm 包 @larksuite/cli 由字节官方维护（maintainer 是 bytednpm），MIT 开源，代码在 GitHub larksuite/cli。凭据存系统钥匙串而非明文文件，带输入注入防护。真正的安全变量不是工具本身，而是你授权给 AI Agent 的权限范围——用 --domain 收窄它。

**Q：支持哪些系统？**

macOS / Linux / Windows 都支持，只要有 Node.js 环境。服务器无浏览器环境用设备码授权（--device-code）。

**Q：和飞书开放平台 SDK 什么关系？**

CLI 底层就是开放平台 API（第三层 Raw API 直接映射 2500+ 接口）。区别在使用成本：SDK 要写代码建应用，CLI 装完授权就能跑。轻量自动化和 AI Agent 场景用 CLI，正式应用开发用 SDK。

**Q：换账号登录出问题怎么办？**

先 lark-cli auth logout 再重新 login；仍有残留就卸载全局 npm 包重装，清掉本地缓存后重新授权新账号。

## **总结**

飞书 CLI 的安装使用可以压缩成四行命令：npx @larksuite/cli@latest install → lark-cli config init → lark-cli auth login --recommend → lark-cli calendar +agenda 验证。它对人类用户是个"还行"的工具，对 AI Agent 用户是个"必装"的工具——26 个内置 Skills 让 Claude Code、Cursor、Codex 零配置获得操作飞书全家桶的能力。如果你的办公流在飞书、开发流在 AI Coding 工具，这是 2026 年连接两者最短的那条线。

本文基于 @larksuite/cli v1.0.67 与官方 GitHub README 实测整理（2026 年 7 月），命令与权限机制以官方文档最新版为准。

## **参考资料**

● [lark-cli GitHub 仓库](https://github.com/larksuite/cli)

●[企业Token Plan](https://www.qiniu.com/ai/plan)
