飞书 CLI 集成基础教程

本教程基于 @larksuite/cli（lark-cli），讲解如何从零开始把飞书消息推送集成到自动化脚本中。内容来自实战，包含常见报错的根因与解决方法。

1. 什么是 lark-cli

lark-cli 是飞书/Lark 官方命令行工具，封装了飞书开放平台 API，让你可以在终端或脚本中直接完成以下操作：

发送消息（私聊 / 群聊）
管理群组、日历、联系人
调用任意开放平台 API

本文以"将每日邮件汇总报告推送到飞书"为例，介绍 lark-cli 的基础用法和脚本集成方式。

2. 安装

bash 复制代码

# 方式一：安装客户端（推荐，全局可用）
npx @larksuite/cli@latest install

# 方式二：每次用 npx 临时拉起（无需安装）
npx @larksuite/cli@latest <command>

安装后，命令名为 lark-cli。可以用下面的命令验证安装是否成功：

bash 复制代码

lark-cli --help

3. 认证与身份

3.1 两种发送身份

lark-cli 支持两种身份。理解它们的区别，是用好这个工具的关键：

身份	标识	说明	典型限制
bot（机器人）	应用本身	以应用/机器人名义操作	发送群消息前，机器人必须已在群内
user（用户）	登录的真人	以你本人名义操作	需要 `im:message.send_as_user` 权限

可以用 --as bot 或 --as user 指定发送身份；未指定时，一般使用 auto。

3.2 登录

bash 复制代码

# 基础登录（扫码或浏览器验证）
lark-cli auth login

# 申请特定权限范围登录
lark-cli auth login --scope "im:message.send_as_user"

⚠️ 交互式登录注意 ：auth login 会阻塞并输出一个验证 URL，需要在浏览器中打开并完成授权。在自动化或后台环境中，CLI 可能因为检测到非交互式终端而缓冲输出，导致验证 URL 无法及时显示。这一步建议在真实终端中手动运行，不要放到后台任务里执行。

3.3 查看当前授权状态

bash 复制代码

lark-cli auth status

输出通常会包含：

appId：当前应用 ID
identities.bot / identities.user：两种身份的就绪状态
user.scope：用户身份已授权的权限列表，排查权限问题时需要重点查看
user.openId：你本人的 open_id

4. 发送消息

核心命令：

bash 复制代码

lark-cli im +messages-send

4.1 发给个人（私聊）

bash 复制代码

# 纯文本
lark-cli im +messages-send --as bot --user-id "ou_xxx" --text "Hello World 👋"

# Markdown（自动优化为飞书富文本卡片）
lark-cli im +messages-send --as bot --user-id "ou_xxx" --markdown "## 标题\n正文内容"

✅ bot 给个人发私信不需要任何群成员关系，这是最省事的推送方式。

4.2 发到群聊

bash 复制代码

lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "群通知"

⚠️ 群消息的前提：机器人必须先被加进群（见第 6 节）。

4.3 常用参数

参数	说明
`--as`	发送身份：`bot` / `user` / `auto`
`--user-id`	目标用户 open_id（`ou_xxx`），与 `--chat-id` 互斥
`--chat-id`	目标群聊 chat_id（`oc_xxx`），与 `--user-id` 互斥
`--text`	纯文本内容
`--markdown`	Markdown 内容（自动转为富文本，图片 URL 自动解析）
`--dry-run`	只打印请求，不实际发送（注意：仍会校验权限）
`--idempotency-key`	幂等键，用于防止重复发送

5. 如何获取 user_id 和 chat_id

发送消息需要目标 ID。常用获取方法如下：

bash 复制代码

# 查找用户 open_id（ou_xxx）
lark-cli contact +search-user --query "张三"

# 列出机器人/你所在的群聊，查找 chat_id（oc_xxx）
lark-cli im +chat-list

# 按关键词搜索群聊
lark-cli im +chat-search --query "研发群"

# 查看自己的 open_id
lark-cli auth status   # 查看 user.openId 字段

6. 高频报错与解法

实战中最常遇到的错误主要有三个：

6.1 `230002: Bot/User can NOT be out of the chat`

原因：机器人不在目标群里。飞书禁止"群外机器人"向群内发送消息。

解法（只能手动操作，重试无效）：

打开目标群聊
进入群设置 → 群机器人 → 添加机器人
选择你登录 lark-cli 时使用的应用（即 auth status 里的 appId）
添加完成后，再重新发送消息

注意：这不是临时故障。只要机器人没有进群，重试多少次都会报同一个错误。

6.2 `missing required scope(s): im:message.send_as_user`

原因：使用 --as user 发送消息，但应用没有开通"以用户身份发送消息"权限。

解法：

在飞书开放平台为应用添加 im:message.send_as_user 权限（可能需要管理员审批）

重新授权登录：

bash 复制代码

lark-cli auth login --scope "im:message.send_as_user"

💡 替代方案 ：如果只是想把通知发出去，优先使用 --as bot，可以避开 user 权限审批。 bot 私信个人通常无需额外权限，是更稳的路径。

6.3 `auth login` 在后台不输出验证 URL

原因：CLI 检测到非交互式终端时，可能会缓冲输出，导致验证 URL 无法显示。

解法：在真实终端里前台运行 auth login，不要放到后台任务或管道里执行。

7. 在脚本中集成（Python 示例）

通过 subprocess 调用 lark-cli，是脚本集成最简单的方式：

python 复制代码

import subprocess


def push_to_feishu(content, target_id, target_type="user", identity="bot", dry_run=False):
    """推送 Markdown 消息到飞书。返回 (是否成功, 输出/错误信息)。"""
    cmd = ["lark-cli", "im", "+messages-send", "--as", identity, "--markdown", content]

    if target_type == "chat":
        cmd += ["--chat-id", target_id]
    else:
        cmd += ["--user-id", target_id]

    if dry_run:
        cmd.append("--dry-run")

    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        return False, result.stderr.strip() or result.stdout.strip()
    return True, result.stdout.strip()

7.1 多目标批量推送

python 复制代码

def push_to_targets(content, user_ids, chat_ids, identity="bot"):
    """同时推送给多个用户和群聊。"""
    targets = [(uid, "user") for uid in user_ids] + [(cid, "chat") for cid in chat_ids]
    for target_id, target_type in targets:
        ok, msg = push_to_feishu(content, target_id, target_type, identity)
        print(f"{'✅' if ok else '❌'} {target_type} {target_id}")
        if not ok:
            print(f"   错误: {msg}")

7.2 从配置文件读取接收人

把接收人放进 .env，并用英文逗号分隔多个值：

env 复制代码

# 接收用户的 open_id，多个用英文逗号分隔
FEISHU_USER_IDS=ou_aaa,ou_bbb

# 接收群聊的 chat_id，多个用英文逗号分隔
FEISHU_CHAT_IDS=oc_xxx,oc_yyy

# 发送身份
FEISHU_SEND_AS=bot

读取并拆分：

python 复制代码

import os


def split_csv(value):
    if not value:
        return []
    return [x.strip() for x in value.split(",") if x.strip()]


user_ids = split_csv(os.environ.get("FEISHU_USER_IDS", ""))
chat_ids = split_csv(os.environ.get("FEISHU_CHAT_IDS", ""))

8. 最佳实践

优先使用 bot 身份：bot 给个人发私信门槛更低，可以省去 user 权限审批的麻烦。
群推送前先确认机器人在群里：这是群消息发送成功的硬前提。
接收人配置化 ：放在 .env 中，而不是硬编码到脚本里，方便增减接收人和复用脚本。
支持多目标推送：用逗号分隔列表，一次推送给多个用户或多个群。
失败不中断：批量推送时，单个目标失败应记录错误并继续执行，最后汇总成功/失败数量。
交互式登录手动完成 ：auth login 不要放到后台任务中执行。
定时任务前先执行 --dry-run：确认接收人和内容无误；但要记住，dry-run 仍会校验权限。

9. 配合定时任务

把推送脚本加入 cron，即可实现每日自动推送：

bash 复制代码

crontab -e

# 每天早上 8:00 推送昨日邮件汇总（接收人从 .env 读取）
0 8 * * * cd /path/to/enterprise-email-manager && \
  python scripts/push_feishu.py --days 1 2>&1 | tee -a logs/feishu_push.log

参考链接

飞书开放平台文档：open.feishu.cn/document/
lark-cli GitHub：github.com/larksuite/c...
错误码查询：在报错信息中的 troubleshooter URL 中查看具体建议

飞书 CLI 集成基础教程