如何安装 Feishu CLI

系统要求

Feishu CLI 支持所有主流操作系统和架构。安装前，请确保您的系统满足以下最低要求：

Node.js 16 或更高版本 — npm 安装方式和 AI Agent 技能系统均需要 Node.js。推荐使用 Node.js 18+ 以获得最佳体验。
操作系统 — 完全支持 macOS、Linux 和 Windows。所有平台均支持 x64 和 arm64 架构，包括 Apple Silicon Mac 和基于 ARM 的 Linux 服务器。
Go 1.23+ — 仅在从源码构建 Feishu CLI 时需要。通过 npm 安装的预编译二进制文件不需要 Go。

无需额外的系统依赖。CLI 以独立二进制文件形式分发，所有必需的库均已打包在内。

通过 npm 安装（推荐）

使用 npm 是开始使用 Feishu CLI 最快捷的方式。一步即可全局安装预编译二进制文件并设置 AI Agent 技能：

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

第一条命令会全局安装 lark-cli 二进制文件，使其可在任何终端会话中使用。第二条命令会全局安装所有 19 个 AI Agent 技能文件，使 Claude Code 和 Cursor 等 AI 编程助手能够自动理解和使用 Feishu CLI 命令。

安装完成后，您可以在终端中运行 lark-cli --version 来验证二进制文件是否可访问。如果在 macOS 或 Linux 上遇到权限错误，可能需要配置 npm 前缀或使用 nvm 等 Node 版本管理器。

从源码安装

如果您需要最新的开发版本或想为项目做贡献，可以从源码构建 Feishu CLI。这需要系统上安装 Go 1.23 或更高版本：

git clone https://github.com/larksuite/cli.git
cd cli
make install
npx skills add larksuite/cli -y -g

make install 命令会编译 Go 源代码，并将生成的二进制文件放置在 $GOPATH/bin 目录中。请确保该目录包含在系统 PATH 中。无论是通过 npm 还是从源码安装，技能安装步骤都是相同的。

从源码构建还可以访问完整的测试套件和开发工具。运行 make test 执行测试套件，运行 make lint 在提交贡献前检查代码质量问题。

创建 Lark 应用

在使用 Feishu CLI 之前，您需要在飞书开放平台上创建一个应用。该应用提供 CLI 用于验证 API 请求的凭证：

访问 open.larksuite.com/app（国际版）或 open.feishu.cn/app（中国版），使用您的 Lark 账号登录。
点击「创建自建应用」，填写应用名称和描述。
进入「凭证与基本信息」部分，找到您的 App ID 和 App Secret。
妥善保管这些凭证 — 在下一步配置中会用到它们。

Lark 应用作为您 CLI 会话的身份标识。通过 CLI 发出的所有 API 调用都在此应用的授权下进行，因此您授予应用的权限决定了 CLI 可以访问的内容。

配置凭证

获得 App ID 和 App Secret 后，使用交互式配置命令安全地存储它们：

lark-cli config init          # Interactive setup for humans
lark-cli config init --new    # For AI Agents, outputs auth URL

标准的 config init 命令会引导您完成交互式向导，提示输入 App ID、App Secret 和首选环境（Lark 或飞书）。--new 标志专为 AI Agent 工作流设计，在无法进行交互提示时输出可以编程方式打开的直接授权 URL。

凭证存储在 ~/.lark-cli/config.yaml 配置文件中。App Secret 在存储时已加密。您可以管理多个应用配置并按需在它们之间切换。

认证（OAuth 2.0 设备流）

配置应用凭证后，您需要以用户身份进行认证以访问用户范围的 API。Feishu CLI 使用 OAuth 2.0 设备授权流，可在无界面环境和 SSH 会话中使用：

lark-cli auth login --recommend     # Auto-select common scopes
lark-cli auth login --domain calendar,task  # Filter by domain
lark-cli auth login --no-wait       # Agent mode, non-blocking

--recommend 标志会自动选择最常用的权限范围，非常适合快速入门。如果您只需要访问特定的飞书业务领域，可以使用 --domain 标志请求更窄的权限集。--no-wait 标志专为 AI Agent 工作流设计，CLI 不会阻塞等待用户完成基于浏览器的授权。

认证成功后，OAuth 令牌会存储在操作系统原生的密钥链中（macOS 钥匙串、Windows 凭据管理器或 Linux Secret Service）。这确保令牌在存储时被加密，并受操作系统安全机制的保护。令牌过期时会自动刷新。

验证安装

完成安装和认证步骤后，验证一切是否正常工作：

lark-cli auth status
lark-cli doctor

auth status 命令显示当前的认证状态，包括已认证的用户、活跃的权限范围和令牌过期时间。doctor 命令运行全面的健康检查，验证配置文件、认证令牌、到飞书 API 的网络连接以及已安装的技能文件。

如果 doctor 报告了任何问题，它会为每个问题提供具体的修复步骤。常见问题包括令牌过期（使用 lark-cli auth login 解决）、配置缺失（使用 lark-cli config init 解决）和网络连接问题。

Shell 补全

Feishu CLI 支持在主流 Shell 中对所有命令、子命令和标志进行 Tab 补全。要启用 Shell 补全，请运行对应您 Shell 的命令：

lark-cli completion bash    # Bash completion
lark-cli completion zsh     # Zsh completion
lark-cli completion fish    # Fish completion
lark-cli completion powershell  # PowerShell completion

每个命令输出一个 Shell 脚本，您可以将其添加到 Shell 配置文件中（如 .bashrc、.zshrc）。配置完成后，您可以按 Tab 键自动补全命令名、标志名，某些情况下还可以补全参数值，如群聊 ID 和文档标题。

身份切换

Feishu CLI 支持以用户或机器人身份进行操作。许多 API 端点的行为因身份上下文不同而有所差异，因此理解这一区别很重要：

lark-cli im send --chat "group-name" --text "Hello" --as user
lark-cli im send --chat "group-name" --text "Hello" --as bot

--as user 标志以已认证用户的身份发送消息，而 --as bot 以应用机器人的身份发送消息。您可以使用 lark-cli config default-as user 或 lark-cli config default-as bot 设置默认身份，以避免每条命令都需要指定。

用户身份适用于需要用户特定上下文的操作，例如访问个人日历或发送邮件。机器人身份适用于自动化工作流和集成场景，消息应来自应用而非特定个人。

故障排除

如果您在安装或使用过程中遇到问题，内置的 doctor 命令是您的首选工具：

lark-cli doctor

doctor 命令会执行一系列诊断检查，涵盖配置有效性、认证状态、API 连接性和技能文件完整性。每项检查会报告通过/失败状态，并在发现问题时提供详细的错误消息和建议修复方案。

常见问题及其解决方案包括：

命令未找到 — 确保 npm 全局 bin 目录在您的 PATH 中。运行 npm bin -g 查找该目录。
认证错误 — 重新运行 lark-cli auth login --recommend 刷新令牌。
权限被拒绝 — 检查您的 Lark 应用是否在开放平台控制台中启用了所需的权限范围。
网络超时 — 验证网络是否可以访问 open.larksuite.com 或 open.feishu.cn。如有需要请配置代理。