---
title: "飞书官方 CLI 完整指南：从安装到 AI Agent 自动化办公"
author: deletexiumu
pubDatetime: 2026-03-30T00:00:00+08:00
featured: false
draft: false
tags:
  - AI 工具
  - 教程
  - AI Agent
  - Claude Code
description: "飞书开源了官方 CLI 工具 lark-cli，覆盖 11 大业务域和 200+ 命令。本文从安装配置到 Claude Code 联动，手把手带你用命令行操作飞书、让 AI Agent 代你办公。"
---

![飞书官方 CLI 完整指南封面](/blog/lark-cli-guide/cover.png)

每周五下午，你打开飞书网页端，开始例行操作：切到日历看下周安排，打开多维表格更新项目进度，新建一篇文档写周报，最后把链接发到群里。四个窗口来回切换，每次都是同样的流程。

如果这些操作能在终端里一行命令搞定呢？再进一步，如果 AI Agent 能替你做这些事呢？

2026 年 3 月 28 日，飞书团队开源了 [lark-cli](https://github.com/larksuite/cli)——一个为人类和 AI Agent 双重设计的飞书命令行工具。上线首日 GitHub Stars 破千，增长迅速。开发者确实需要一个从终端操作飞书的方式。

本文是一份从零开始的实战指南。从安装配置、日常命令到 Claude Code 联动，所有命令基于 v1.0.0 官方文档整理，具体参数以 `--help` 和 Skill 文档为准。

## lark-cli 是什么：三层命令架构

lark-cli 的核心设计亮点是**三层命令架构**。理解这三层，基本就理解了整个工具的使用逻辑。

### 第一层：Shortcuts（+ 前缀）

面向人类的快捷命令，带智能默认值：

```bash
lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "周报已更新，请查阅"
lark-cli docs +create --title "项目周报" --markdown "# 本周进展\n- 完成功能 A\n- 修复 Bug B"
```

Shortcuts 用 `+` 前缀标识，参数名直观，不需要翻 API 文档就能上手。AI Agent 调用飞书时，绝大多数场景用 Shortcuts 就够了。

### 第二层：API Commands

飞书开放平台 API 的 1:1 映射，精选了 100 多个常用端点：

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

当 Shortcuts 覆盖不到你的需求时，降级到这一层。参数结构和飞书 OpenAPI 文档完全对应。

### 第三层：Raw API

2500+ 飞书 OpenAPI 端点全覆盖，万能后备：

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

Raw API 的意义在于：不管飞书开放平台新增什么接口，lark-cli 都能立即调用，不用等 Shortcuts 更新。

三层架构的设计思路很清晰——日常操作用 Shortcuts，复杂需求用 API Commands，边界情况用 Raw API。对 AI Agent 来说尤其友好：先尝试最简洁的 Shortcuts，失败了自动降级到更底层的接口。

### 11 大业务域

lark-cli v1.0.0 覆盖了飞书的主要业务场景：

| 业务域 | Skill 名称 | 核心能力 |
|--------|-----------|---------|
| 日历 | lark-calendar | 查看日程、创建事件、查忙闲、跨时区 |
| 即时通讯 | lark-im | 发送/回复消息、群聊管理、消息搜索 |
| 云文档 | lark-doc | 创建/读取/更新文档（Markdown 互转） |
| 云空间 | lark-drive | 上传下载文件、权限管理 |
| 多维表格 | lark-base | 表/字段/记录 CRUD、数据聚合 |
| 电子表格 | lark-sheets | 读写单元格、批量追加、条件查找 |
| 任务 | lark-task | 创建/完成任务、子任务、提醒 |
| 知识库 | lark-wiki | 知识空间、节点层级、文档管理 |
| 通讯录 | lark-contact | 按姓名/邮箱/手机号搜索同事 |
| 邮箱 | lark-mail | 收发邮件、草稿管理 |
| 会议 | lark-vc + lark-minutes | 会议记录、妙记摘要、逐字稿 |

此外还有 lark-event（WebSocket 实时事件监听）、lark-whiteboard（画板）等扩展 Skills。

## 安装与配置

### 环境准备与安装

lark-cli 用 Go 编写，通过 npm 分发。安装只需两条命令：

```bash
npm install -g @larksuite/cli
npx skills add larksuite/cli -y -g
```

第一条安装 CLI 本体，第二条安装配套的 Skills（后面会详细说 Skills 是什么）。

如果你更喜欢从源码构建：

```bash
git clone https://github.com/larksuite/cli.git
cd cli
make install   # 需要 Go v1.23+ 和 Python 3
npx skills add larksuite/cli -y -g
```

### 配置应用凭证

lark-cli 通过飞书开放平台的应用凭证来获取权限。首次使用需要创建应用：

**人类用户模式**（交互式引导）：

```bash
lark-cli config init
```

这条命令会启动一个交互式向导，自动在飞书开发者后台创建应用，全程跟着提示走就行。

**AI Agent 场景**：如果你在 Claude Code 等 AI Agent 环境中使用，用 `lark-cli config init --new`，它会在后台运行并输出授权 URL，在浏览器里打开完成授权即可。也可以先在普通终端完成 `config init` 和 `auth login`，配置好凭证后再让 AI Agent 调用命令。

有一个需要注意的地方：**如果你使用的是企业版飞书，创建的应用可能需要企业管理员审批后才能使用**。LINUX DO 论坛有用户反馈过这个问题——配置流程本身没问题，但应用创建后处于待审批状态，需要找 IT 管理员放行。

### 登录授权与身份机制

配置好应用后，下一步是登录授权：

```bash
lark-cli auth login --recommend
```

`--recommend` 参数会一次性开通多维表格、日历、文档、消息、邮箱等常用权限，省得后面一个个加。

这里有一个**必须搞清楚的概念**——user 和 bot 两种身份：

- **user 身份**：代表你个人，访问个人日历、个人云空间、个人邮箱等私人资源
- **bot 身份**：代表应用本身，执行应用级操作，通过 appId + appSecret 自动认证

选错身份是权限报错的最常见原因。举个例子：你想查看自己的日历日程，必须用 user 身份。如果用 bot 身份去调 calendar 接口，会拿到 Permission Denied。

还有一个容易忽略的机制：**scope 累积授权**。多次执行 `lark-cli auth login` 时，新授权的权限会叠加到已有权限上，不会覆盖之前的授权。所以不用担心重新 login 会丢失之前的权限。

验证当前状态：

```bash
lark-cli doctor         # 综合诊断（配置、认证、连接）
```

### Permission Denied 排查

权限错误是使用初期最常遇到的问题。好消息是 lark-cli 的错误提示做得不错——出现权限错误时，它会告诉你缺少哪个 scope，并给出修复命令。

常见排查路径：

1. 用 bot 身份访问个人资源 → 切换到 user 身份重新 login
2. 缺少特定 scope → 按错误提示中的命令补授权
3. 企业环境权限受限 → 联系管理员审批应用或开放对应 scope

## 基础用法：5 个日常场景

### 查看今日日程

```bash
lark-cli calendar +agenda
```

默认输出当天日程。如果需要不同的输出格式：

```bash
lark-cli calendar +agenda --format json     # JSON 格式，适合脚本处理
lark-cli calendar +agenda --format table    # 表格格式，终端阅读友好
lark-cli calendar +agenda --format pretty   # 美化输出
```

### 发送群消息

```bash
lark-cli im +messages-send --chat-id "oc_xxx" --text "周报已更新，请查阅"
```

chat-id 是飞书群聊的唯一标识，格式为 `oc_` 开头。获取方式：在飞书群设置里可以找到，或者通过 `lark-cli im +chat-search` 搜索你加入的群聊。

发送前想预览效果？用 dry-run：

```bash
lark-cli im +messages-send --chat-id "oc_xxx" --text "测试消息" --dry-run
```

`--dry-run` 会展示将要执行的 API 请求，但不实际发送。这是你的安全网，尤其在调试阶段建议养成习惯。

### 创建飞书文档

```bash
lark-cli docs +create --title "项目周报" --markdown "# 本周进展\n- 完成功能 A\n- 修复 Bug B"
```

lark-cli 会自动将 Markdown 转换为飞书文档格式。对于更长的内容，可以从文件读取：

```bash
lark-cli docs +create --title "技术方案" --markdown "$(cat design.md)"
```

### 多维表格操作

```bash
# 列出多维表格中的记录
lark-cli base +data-query --app-token <你的多维表格 app_token> --table "销售数据"
```

`--app-token` 是多维表格的唯一标识，从多维表格 URL 中获取（URL 里 `/base/` 后面那串字符，不是应用的 appId）。`+data-query` 也支持聚合查询，但查询语法和 SQL 不同，具体写法参照 [lark-cli 官方文档](https://github.com/larksuite/cli)。上面的命令先不加 `--query` 参数，确认能拿到数据后再尝试聚合。

### 邮件管理

```bash
lark-cli mail +send --to "name@company.com" --subject "会议通知" --body "明天下午 3 点开评审"
```

注意：`+send` 的默认行为是**保存为草稿**，需要确认后才会真正发送——这是一个安全设计，防止 AI Agent 误发邮件。lark-mail Skill 覆盖了发送、回复、转发和草稿管理等操作。邮件相关的 Shortcuts 命令名请以 `lark-cli mail --help` 的输出为准。

## 进阶玩法：与 Claude Code 联动

这是 lark-cli 最有意思的部分——它天然支持作为 AI Agent 的工具被调用。

### Skills 安装后 Claude Code 直接可用

前面安装时执行的第二条命令：

```bash
npx skills add larksuite/cli -y -g
```

这条命令安装了一批 Skills（覆盖日历、IM、文档、多维表格等 11 大业务域，外加事件监听、画板等扩展 Skill）。每个 Skill 本质上是一个 SKILL.md 文件，描述了这个 Skill 的能力、前置条件、参数格式和使用示例。Claude Code 启动时会自动扫描并加载这些 SKILL.md，然后就知道怎么调用 lark-cli 了。

每个 Skill 的设计有几个值得注意的特点：

- **前置条件检查**：Skill 会先验证 lark-cli 是否安装、是否已登录、权限是否足够
- **身份选择原则**：明确标注了该用 user 还是 bot 身份
- **权限修复引导**：遇到权限不足时，给出具体的修复步骤

这意味着你可以直接在 Claude Code 里用自然语言操作飞书：

> "帮我查一下今天的日程，如果下午有空，创建一个 3 点的评审会议"

Claude Code 会拆解这个请求：先调用 `lark-cli calendar +agenda` 查日程，判断下午是否有空，然后调用日历相关命令创建会议。

### 实战案例：AI 自动生成项目周报

一个实际场景——让 Claude Code 汇总本周 Git 提交记录，生成周报并发到飞书。

工作流程：

1. Claude Code 执行 `git log --since="last Monday" --oneline` 读取本周提交
2. 将提交记录整理成结构化的周报 Markdown
3. 调用 `lark-cli docs +create --title "第 N 周项目周报" --markdown "..."` 创建飞书文档
4. 调用 `lark-cli im +messages-send --chat-id "oc_xxx" --text "本周周报已生成：[文档链接]"` 通知群聊

如果想定时自动化，用系统级的定时任务调度：

- macOS：launchd
- Linux：cron

```bash
# crontab 示例：每周五下午 5 点自动生成周报
# 注意：cron 环境 PATH 很精简，需使用 claude 的完整路径（通过 which claude 获取）
0 17 * * 5 cd /path/to/project && /usr/local/bin/claude -p "生成本周项目周报并发到飞书群"
```

注意：这里用的是系统 cron，不是 Claude Code 的 Hooks。Hooks 是工具调用前后的触发机制（比如在执行某个命令前/后自动运行脚本），不是定时调度工具。

### 实战案例：智能会议管理

另一个实用场景：

> "帮我找一个下周所有人都有空的 1 小时时段，创建技术评审会议"

Claude Code 的执行路径：

1. 通过 lark-cli calendar 查询相关人员的忙闲状态
2. 计算交集，找到合适的时间段
3. 推荐几个候选时段供你确认
4. 确认后创建日历事件并发送邀请通知

人来决策，AI 来执行查询和操作。

### 安全注意事项

把飞书操作交给 AI Agent，安全是绕不开的话题。几个要点：

**飞书机器人定位**：建议将 lark-cli 创建的飞书机器人定位为私人助手，谨慎使用群聊权限，避免机器人在群里误操作。

**写入操作确认**：lark-cli 在执行写入或删除操作前会要求确认。这是一道防线，防止 AI 幻觉导致的误操作。

**dry-run 习惯**：调试阶段，所有写入命令都先加 `--dry-run` 预览。确认无误后再实际执行。

**数据安全边界**：社区讨论中，安全顾虑是最高频的话题。LINUX DO 论坛有用户提到"不建议吧，除非本地部署"——这里的"本地部署"指的是 LLM 模型本地化，担心的是企业数据经过云端模型。务实的做法是：用 AI Agent 处理非敏感的日常操作（查日程、发通知、建文档），涉及敏感数据的操作还是手动来。

## 当前限制与生态

### v1.0.0 已知限制（截至 2026-03-29）

lark-cli 刚发布，有些能力还没补齐：

- **飞书审批**：尚未支持，社区已提 Issue（[#42](https://github.com/larksuite/cli/issues/42)）
- **飞书项目**：目前只支持任务管理，完整的项目管理功能待补（[#38](https://github.com/larksuite/cli/issues/38)）
- **Wiki 能力**：知识库相关功能需要补强（[#58](https://github.com/larksuite/cli/issues/58)）
- **云盘浏览**：无法列出文件夹内的文件列表（[#51](https://github.com/larksuite/cli/issues/51)）
- **Windows 兼容**：`--params` 传 JSON 时可能解析失败（[#64](https://github.com/larksuite/cli/issues/64)）
- **配置体验**：有用户反馈初次配置流程不够顺畅（[#54](https://github.com/larksuite/cli/issues/54)）

这些都是 v1.0.0 的状态，后续版本大概率会逐步解决。

### Skills vs MCP：怎么选

飞书官方同时提供了两种 AI Agent 集成方案：

**lark-cli Skills**：轻量方案。不需要启动额外进程，Agent 读取 SKILL.md 文件就能理解如何调用 CLI 命令。适合 Claude Code 这类直接在终端工作的 Agent。

**lark-openapi-mcp**（[larksuite/lark-openapi-mcp](https://github.com/larksuite/lark-openapi-mcp)）：标准 MCP Server 方案。需要启动一个服务进程，通过 MCP 协议与 Agent 通信。适合需要标准化集成的场景，比如在 IDE 插件或自定义 Agent 框架中使用。

两者互补。如果你用 Claude Code，Skills 方案更简单直接；如果你在搭建自己的 Agent 系统且已经支持 MCP 协议，MCP Server 方案集成更规范。

社区也有第三方生态：

- [Feishu-MCP](https://github.com/cso1z/Feishu-MCP)：同时支持 MCP 和 CLI+Skill 双模式
- [Claude-to-IM-skill](https://github.com/op7418/Claude-to-IM-skill)：让 Claude Code 连接飞书、QQ、Telegram 等 IM

## 结尾

回到开头的场景：查日程、更新表格、写周报、发群通知。现在你可以在终端里用几条命令搞定，或者让 Claude Code 替你做。

企业协作软件开始为 AI Agent 提供原生的命令行接口——不是在 Web API 上面包一层 SDK，而是从设计之初就考虑了 Agent 的使用方式：结构化输出、分层命令、内置权限引导。

飞书审批、飞书项目等更多业务域的支持还在路上。装完跑一下 `lark-cli calendar +agenda`，30 秒看到效果。

---

**参考资料**

- [lark-cli GitHub 仓库](https://github.com/larksuite/cli)
- [lark-openapi-mcp](https://github.com/larksuite/lark-openapi-mcp) — 飞书官方 MCP Server
- [Claude-to-IM-skill](https://github.com/op7418/Claude-to-IM-skill) — Claude Code 连接飞书/QQ/Telegram
- [Feishu-MCP](https://github.com/cso1z/Feishu-MCP) — 飞书 MCP + CLI+Skill 双模式
- [LINUX DO 社区讨论：飞书出了官方 CLI](https://linux.do/t/topic/1841144)
- [LINUX DO 社区讨论：飞书 CLI 用法灵感](https://linux.do/t/topic/1841680)

---

## 相关阅读

- [Claude Code 完整安装与配置教程（支持国内模型）](/posts/claude-code-installation/) — lark-cli 的 Claude Code 联动需要先安装好 Claude Code
- [Skill 设计手册：Anthropic 内部数百个 Skill 的经验总结](/posts/claude-code-skill-design-guide/) — lark-cli 的 19 个 Skill 遵循了这些设计原则
- [Claude Code 实用插件与工具分享](/posts/claude-code-plugins-tools/) — 更多 Claude Code 生态工具推荐