---
title: "在 Claude Code 里用 lark-cli 操作飞书"
wiki: cli
category: "集成"
slug: feishu-from-cli-agent
url: https://learnagent.wiki/cli/cards/feishu-from-cli-agent
tags: ["飞书", "Lark", "lark-cli", "MCP", "团队协作", "AI Skills"]
last_updated: 2026-04-22
reading_time: 14
---

> `lark-cli`（npm 包名 `@larksuite/cli`）是飞书在 **2026-03-28** 开源的官方命令行工具，定位非常清晰——**给 AI Agent 一双能在飞书里干活的手**，而不是再产出一份「让你自己复制粘贴的文字」。它是用 Go 写的（占比 98%），通过 npm 全局分发，遵循 MIT 协议。截至 2026-04-22，最新版本是 **v1.0.16**（2026-04-21 发布），内含 **200+ 命令**和 **22 个 AI Skills**，覆盖了飞书云协作里几乎所有能用到的业务域。

# 在 Claude Code 里用 lark-cli 操作飞书

## 基础概念

`lark-cli`（npm 包名 `@larksuite/cli`）是飞书在 **2026-03-28** 开源的官方命令行工具，定位非常清晰——**给 AI Agent 一双能在飞书里干活的手**，而不是再产出一份「让你自己复制粘贴的文字」。它是用 Go 写的（占比 98%），通过 npm 全局分发，遵循 MIT 协议。截至 2026-04-22，最新版本是 **v1.0.16**（2026-04-21 发布），内含 **200+ 命令**和 **22 个 AI Skills**，覆盖了飞书云协作里几乎所有能用到的业务域。

为什么 2026 年才出现？飞书原本就有完整的 OpenAPI（2500+ 接口），也有 MCP 版本 `lark-openapi-mcp`，但前者太底层、后者要把工具描述常驻在模型上下文里，二者都不太符合「Claude Code 这种终端 Agent 即开即用」的形态。`lark-cli` 是飞书针对「2026 年 Agent 工具爆发期」专门做的一版，**核心卖点是 CLI 自描述（`--help` 可发现）+ 内置 Skills 包（教 Agent 怎么用）**。这也是同一时期 Obsidian、GitHub gh CLI 等开始走「为 Agent 重做一版 CLI」的同一波趋势。

那为什么飞书要**同时维护官方 CLI 和官方 MCP**？因为两者覆盖的场景不重叠：CLI 适合 Claude Code / Codex CLI / Gemini CLI 等终端环境，按需调用、不占上下文；MCP 适合 Cursor / VS Code / Claude Desktop 等非终端的客户端，工具列表预注册、跨客户端复用。后面会专门对比这一段。

### 核心要素

| 要素 | 说明 |
|------|------|
| **官方维护** | 字节跳动飞书团队官方项目（`larksuite/cli`），不是社区方案 |
| **AI 原生设计** | 命令、错误信息、`--help` 文档都是按 Agent 的可读性优化过的 |
| **三层命令架构** | Shortcuts（`+` 前缀，Agent 友好）/ API Commands（结构化命令）/ Raw API（裸调 2500+ 接口） |
| **22 个内置 Skills** | 一行命令把 Skills 装到 Claude Code，Agent 立刻知道怎么发消息、查日程、写多维表 |
| **凭证安全** | 鉴权 Token 加密保存在系统 Keychain，不是明文落盘 |
| **支持双重身份** | `--as user`（以你本人身份）/ `--as bot`（以应用身份）可切换 |

### lark-cli + Claude Code 接入流

```mermaid
sequenceDiagram
    participant U as 你
    participant CC as Claude Code
    participant LLM as Claude 模型
    participant Skills as lark-cli Skills 包
    participant CLI as lark-cli (本地 Go 程序)
    participant Lark as 飞书 OpenAPI

    U->>CC: 「把今天会议的待办整理到我的多维表」
    CC->>Skills: 加载 lark-vc / lark-base 等 Skills 文档
    Skills-->>CC: 提示：先用 lark-cli vc minutes list 取妙记
    CC->>LLM: 发送任务 + Skills 指引
    LLM->>CC: 决定调用 lark-cli vc + lark-cli base
    CC->>CLI: 执行 lark-cli vc minutes list --json
    CLI->>Lark: 调 OpenAPI（带本地缓存的 OAuth Token）
    Lark-->>CLI: 返回妙记列表 JSON
    CLI-->>CC: 结构化结果回流
    CC->>CLI: 执行 lark-cli base record create ...
    CLI->>Lark: 写入多维表
    Lark-->>CLI: 成功
    CLI-->>CC: OK
    CC-->>U: 已写入 7 条待办
```

## 基础用法

### 1. 安装（CLI + Skills 两步）

```bash
# 第一步：装 lark-cli 本体（Go 程序，npm 分发）
npm install -g @larksuite/cli

# 第二步：装内置 AI Skills 包到全局 Claude Code
# 这一步是关键：装完之后 Claude Code 才知道飞书 22 个业务域怎么用
npx skills add larksuite/cli -y -g

# 校验
lark-cli --version    # 期望输出 v1.0.16 或更新
lark-cli --help       # 看到 calendar / im / docs / base ... 等业务域
```

> **常见踩坑**：只装了 `npm install -g @larksuite/cli` 没装 Skills，Claude Code 也能调，但成功率明显低（要靠模型猜命令名和参数）。Skills 是「写给 Agent 看的说明书」，强烈建议两步都做。

### 2. 配置（一次性三步）

```bash
# 初始化配置：会引导你创建/选择飞书自建应用，写入本地配置文件
lark-cli config init

# 推荐方式登录：自动选常用 scope，浏览器弹出 OAuth 同意页
lark-cli auth login --recommend

# 验证当前身份和已授权的 scope
lark-cli auth status
```

**身份切换**——同一台机器可以挂多个身份：

```bash
lark-cli auth login --as user   # 以个人身份（能看你自己的日程、邮件）
lark-cli auth login --as bot    # 以应用身份（在群里发通知、只读企业数据）
```

### 3. 最小操作示例

```bash
# 发一条群消息（Shortcut 用法，Agent 友好）
lark-cli im +send --chat "周会群" --text "今天 4 点开周会，议程见文档"

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

# 读一篇云文档的纯文本
lark-cli docs +read --doc-id "doccnxxxxxxxxxxxxxx"

# 在多维表里加一条记录
lark-cli base +add-record \
  --app "bascnxxxxxxxxxxxxxx" \
  --table "tblxxxxxxxxxxxxxx" \
  --fields '{"标题":"上线检查","负责人":"yang","状态":"进行中"}'
```

### 4. 在 Claude Code 里的对话示例

装好 CLI + Skills 之后，在 Claude Code 里直接说人话：

```text
你：把昨天 14:00 那场「Q2 复盘」的妙记拉出来，
    抽出所有「行动项」写到 base「待办」表，
    每条带负责人和截止日期。

Claude Code：
  → 调用 lark-cli vc minutes list --since "yesterday 14:00" --json
  → 调用 lark-cli vc minutes get <minute_id> --json
  → 解析出 6 条行动项
  → 调用 lark-cli base +add-record（× 6 次）
  → 完成，已写入「待办」表，链接：https://...

你：下周二上午 10 点找 @张伟 @李娜 开 30 分钟同步会，
    检查这些待办进度。

Claude Code：
  → 调用 lark-cli contact +find --name "张伟"
  → 调用 lark-cli calendar +book \
       --attendees "..." --start "2026-04-28 10:00" --duration 30 \
       --title "Q2 复盘待办同步"
  → 已下发邀请。
```

整个过程你不需要记任何命令、不需要查 OpenAPI 文档，**Skills 已经把命令名、参数、错误处置都教给 Agent 了**。

## 同类工具对比

四种「让 AI 操作飞书」的路径横向对比：

| 维度 | **lark-cli**（本卡） | **lark-openapi-mcp** | **直调 OpenAPI** | **社区 lark-bot 工具** |
|------|---------------------|----------------------|------------------|------------------------|
| 维护方 | 飞书官方 | 飞书官方 | 飞书官方 SDK | 社区个人/小团队 |
| 适配形态 | 终端 CLI（Claude Code / Codex CLI / Gemini CLI） | MCP Server（Cursor / Claude Desktop / VS Code） | 任意可发 HTTP 的程序 | 看具体项目 |
| 上下文成本 | **零常驻**（按需调用） | 工具描述常驻在 token 里 | 零（自己写胶水） | 零 |
| Agent 可发现性 | `--help` + Skills 自描述 | MCP `tools/list` 返回结构化 schema | 0（要看官方文档） | 通常 0 |
| 学习/接入成本 | 装两个包，5 分钟搞定 | 改 MCP 配置，重启客户端 | 自建应用 + 写 OAuth + 写胶水代码，几小时 | 各项目差异巨大 |
| 跨客户端复用 | ❌ 仅终端类 Agent | ✅ 任意 MCP 客户端 | ✅（你自己包一层就行） | 看项目 |
| 命令/工具数量 | 200+ 命令 + 2500+ 裸 API | 数十个工具（不支持文件上传/文档编辑） | 全量 2500+ | 通常 < 20 |
| 内置 AI Skills | ✅ 22 个业务域 | ❌ 仅工具 schema | ❌ | ❌ |
| 凭证存储 | 系统 Keychain 加密 | 配置文件（明文 app_id/secret） | 自己处理 | 自己处理 |

**核心区别一句话**：

- **lark-cli** = 终端 Agent 的「飞书外挂」——按需调用，零上下文成本，Skills 教模型怎么干活。**Claude Code / Codex CLI / Gemini CLI 用户首选**。
- **lark-openapi-mcp** = 跨客户端复用的「工具菜单」——把工具描述常驻在 Cursor / Claude Desktop 等客户端的上下文里，**非终端环境的首选**。
- **直调 OpenAPI** = 你自己写后端服务时用，Agent 场景几乎不会直接走这条路。
- **社区 lark-bot 工具** = 历史遗物，2026-03 之后基本被官方两条路完全覆盖。

> 元卡：选型框架见 [/cli/cards/cli-vs-mcp-integration-paths](/cli/cards/cli-vs-mcp-integration-paths)；不熟悉 MCP 的先看 [/mcp/cards/what-is-mcp](/mcp/cards/what-is-mcp)。

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为 lark-cli 必须自建飞书应用、配 app_id/app_secret 才能用 | `lark-cli config init` 会引导你完成应用创建，且支持以**个人身份 OAuth 登录**，普通用户场景不需要手动配凭证 |
| 以为 200+ 命令都要自己记 | 你不用记。Skills 包就是为此存在的——装完 Skills 之后，Claude Code 拿到任务会自己查 Skills 文档决定调哪个命令，你说人话即可 |
| 以为 lark-cli 只支持 Claude Code | 它是普通 CLI，任何能跑 shell 的 Agent 都能调。Codex CLI、Gemini CLI、自己写的 LangChain 脚本都行；Skills 主要适配 Claude Code 的 Skill 协议，但命令本身通用 |
| 以为 lark-cli 和 lark-openapi-mcp 是替代关系，二选一 | 飞书官方明确两者**互补**：CLI 给终端 Agent 用、MCP 给非终端客户端用。同一台机器同时装两个完全不冲突 |
| 以为只能操作个人数据，不适合团队场景 | `--as bot` 模式可以以应用身份执行，配上企业级权限可以做群通知、值班播报、自动审批催办等团队场景 |
| 以为装了就能在群聊里直接 @AI 让它办事 | CLI 是本地工具，Agent 在你本地跑，群消息里的 @AI 是另一回事（要靠飞书机器人 + Webhook + 后端服务）。CLI 的典型场景是**你本地的 Claude Code 帮你处理飞书相关任务** |
| 以为 Skills 装一次就一直管用 | Skills 跟 lark-cli 版本绑定，CLI 升级后建议 `npx skills add larksuite/cli -y -g` 再跑一次刷新 |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **AI 原生设计**：`--help`、错误信息、参数命名都是为 Agent 可读性优化过的，比直调 OpenAPI 友好一个数量级 | **必须装两个包**（CLI + Skills），少一步就发挥不出实力，新手容易漏 |
| **自带 22 个业务域 Skills**：装完即用，Agent 不需要靠瞎试探索命令名 | **CLI 版本和 Skills 版本绑定**，CLI 升级要顺手刷新 Skills，否则可能命令对不上 |
| **零常驻上下文成本**：和 MCP 不同，CLI 工具描述不进 token 预算，对长会话非常友好 | **不跨客户端**：Cursor、Claude Desktop 这类非终端客户端用不了，只能走 MCP |
| **凭证安全**：Token 加密在系统 Keychain，不是明文配置文件落盘 | **OAuth 流程依赖浏览器**：纯无界面服务器（裸 SSH）首次登录会卡住，需要本地走完流程后把凭证迁过去 |
| **官方维护 + MIT 开源**：版本节奏快，2026-03 首发到 2026-04 已经迭代到 1.0.16；遇到 bug 在 GitHub 直接报 | **覆盖功能仍有边界**：MCP 文档明确不支持文件上传/文档编辑，CLI 大部分覆盖了，但部分新接口还在补 |
| **三层命令架构**：Shortcuts 给 Agent 用、API Commands 给脚本用、Raw API 给开发者用，自由切换 | **学习曲线在「选哪一层」**：同一件事用 `+send` 还是 `im messages create` 结果不同，新人会困惑 |

## 思考题

<details>
<summary>初级：飞书既然已经有 lark-openapi-mcp 了，为什么还要做 lark-cli？这两者重复吗？</summary>

**参考答案**：不重复，两者覆盖**完全不同的客户端形态**。

- **lark-openapi-mcp** 解决的是「Cursor / Claude Desktop / VS Code 这类非终端客户端怎么调飞书」——这些客户端是图形界面，没法直接 spawn 一个 CLI 进程，必须通过 MCP 协议把工具列表预注册到客户端内部的会话上下文里。代价是工具描述要常驻在每次请求的 token 里。
- **lark-cli** 解决的是「Claude Code / Codex CLI / Gemini CLI 这类终端 Agent 怎么调飞书」——终端 Agent 本身就在 shell 里跑，最自然的工具调用方式就是 spawn 子进程执行 CLI 命令。代价是只能在终端环境用，但好处是工具描述不占 token、按需调用。

更深一层看，飞书做这两条路也反映了 2026 年 AI 工具集成的两种主流形态：**MCP 是「客户端预先知道有哪些工具」的模式，CLI 是「按需自描述发现工具」的模式**。它们各有适用场景，不存在谁替代谁。

如果你团队既有人用 Cursor 又有人用 Claude Code，**两个都装、各用各的**就是最优解。

</details>

<details>
<summary>中级：你打算让团队里所有 Claude Code 用户都能用 lark-cli 给飞书发消息，应该怎么规划权限模型？</summary>

**参考答案**：分两类场景设计，**永远不要让所有人共享同一套凭证**。

**场景一：操作个人数据（看自己的日程、回自己的邮件、读个人能看到的文档）**

- 每个人在自己机器上跑 `lark-cli auth login --as user --recommend`，独立 OAuth 授权
- 凭证加密存在各自的系统 Keychain，跟其他人完全隔离
- 飞书企业管理员可以在后台审计每个用户的授权范围

**场景二：操作团队/应用数据（在群里发自动化通知、写公共多维表、查全员通讯录）**

- 由企业管理员创建一个**自建应用**，配置最小必要的应用权限
- 应用凭证（app_id / app_secret）走团队的 secret manager（Vault / 1Password / SOPS），**不进 git**
- 每个用户的 lark-cli 用 `--as bot` 模式调用，但凭证从环境变量或临时下发渠道注入
- 关键操作（发群消息、改多维表）开 `--dry-run` 让 Agent 先预演，人工确认后再执行
- 高危操作（删数据、撤回消息）放进 Claude Code 的 `permissions.deny` 白名单里

进阶建议：

- 设审计日志，所有 lark-cli 调用都记录到中央日志，方便事后追溯
- 用 git worktree 给团队 Agent 工作流隔离上下文，避免不同任务共享 Token 状态
- 长期看，团队场景应该评估是否走「飞书机器人 + 后端服务」的传统方案，CLI 更适合个人/小团队的快速场景

</details>

<details>
<summary>进阶：lark-cli 的「三层命令架构」（Shortcuts / API Commands / Raw API）背后的设计哲学是什么？这种分层对其他官方 CLI 有什么借鉴意义？</summary>

**参考答案**：本质是**为不同消费者优化不同的接口粒度**。

- **Shortcuts（`+` 前缀）**——目标用户是 **AI Agent 和懒得查文档的人类**。它把高频操作打包成一个带智能默认值的命令，参数最少、输出结构化、错误信息带「下一步建议」。例如 `lark-cli calendar +agenda` 默认查今天、按时间排序、人类可读输出。
- **API Commands**——目标用户是**写脚本的开发者**。它由飞书 OpenAPI 元数据自动生成，命令名、参数和官方 API 一一对应，适合需要精确控制的自动化场景。
- **Raw API**——目标用户是**需要调用所有 2500+ 接口、含最新 beta 接口**的开发者。本质是 `curl` 的语义封装，给你完全的控制权，但你要自己处理一切细节。

设计哲学有三点值得别的官方 CLI 借鉴：

1. **不要假设一个抽象层级能服务所有人**。Agent 要的是「告诉我能做什么、参数怎么填」，开发者要的是「让我精准调任何接口」。把它们硬塞进一层，结果是 Agent 嫌复杂、开发者嫌包装太多。
2. **Agent 友好层（Shortcuts）值得专门为 Agent 投入**。命名、错误信息、`--help` 输出都按「让模型一次读懂」标准做，这部分投入会直接转化为 Agent 调用成功率。
3. **API 自动生成层（API Commands）能让 CLI 始终跟得上服务端 API**。手写命令的 CLI 永远落后于 API 演进，自动生成则可以做到「服务端发布新接口当天 CLI 就有」。

这套思路对 GitHub gh CLI、Notion CLI、Linear CLI 都有借鉴价值——2026 年开始，「为 Agent 重做的官方 CLI」基本都在朝这个三层结构收敛。

</details>

## 参考资料

1. larksuite/cli 官方仓库：<https://github.com/larksuite/cli>（查询日期 2026-04-22，最新版本 v1.0.16）
2. 中文 README：<https://github.com/larksuite/cli/blob/main/README.zh.md>
3. npm 包页：<https://www.npmjs.com/package/@larksuite/cli>
4. 飞书官方介绍文：<https://open.feishu.cn/document/mcp_open_tools/feishu-cli-let-ai-actually-do-your-work-in-feishu>
5. larksuite/lark-openapi-mcp 仓库（对比项）：<https://github.com/larksuite/lark-openapi-mcp>（v0.5.1，2025-08-06）
6. 宝玉对 lark-cli 的解读：<https://baoyu.io/blog/2026-03-28/lark-cli-ai-agents>
7. heyuan110 的 lark-cli 实操指南：<https://www.heyuan110.com/zh/posts/ai/2026-03-29-lark-cli-guide/>

---
*Source: https://learnagent.wiki/cli/cards/feishu-from-cli-agent*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*