lark-claw-cli

AI Agent 友好的飞书/Lark 工具 CLI。封装 @larksuiteoapi/feishu-openclaw-plugin，暴露 35 个工具能力，所有输出为结构化 JSON。

安装

npm install -g lark-claw-cli

配置

方式一：直接编辑配置文件（推荐）

mkdir -p ~/.lark-claw && cat > ~/.lark-claw/context.json << 'EOF'
{
  "appId": "cli_xxx",
  "appSecret": "your_app_secret"
}
EOF

首次调用时 CLI 会自动查询 App Owner 并补全 userOpenId、chatId、resolvedForAppId 字段。

方式二：环境变量

export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx

环境变量优先级高于配置文件。首次运行后凭证会自动写入 ~/.lark-claw/context.json，后续无需再设环境变量。

配置项

| 配置 | 环境变量 | context.json 字段 | 说明 | |------|---------|-------------------|------| | App ID | FEISHU_APP_ID | appId | 飞书应用 App ID | | App Secret | FEISHU_APP_SECRET | appSecret | 飞书应用 App Secret | | Domain | FEISHU_DOMAIN | — | feishu（默认）或 lark |

context.json 完整结构

{
  "appId": "cli_xxx",           // 飞书 App ID
  "appSecret": "xxx",           // 飞书 App Secret
  "userOpenId": "ou_xxx",       // App Owner Open ID（自动查询）
  "chatId": "ou_xxx",           // 授权卡片发送目标（自动解析）
  "resolvedForAppId": "cli_xxx" // userOpenId 对应的 App ID（用于变更检测）
}

userOpenId 和 chatId 由 CLI 自动填充。当 appId 与 resolvedForAppId 不一致时（手动更换了 App 或切换了环境变量），CLI 会自动重新查询 App Owner 并更新缓存。

使用

列出所有工具

lark-claw list

查看工具 Schema

# 所有工具
lark-claw schema

# 单个工具
lark-claw schema feishu_task_task

调用工具

# 创建任务
lark-claw call feishu_task_task '{"action":"create","summary":"我的任务"}'

# 查询日历
lark-claw call feishu_calendar_event '{"action":"list","start_time":"2026-03-10T00:00:00+08:00","end_time":"2026-03-10T23:59:59+08:00"}'

# 创建文档
lark-claw call feishu_create_doc '{"title":"标题","markdown":"# Hello\n\n正文内容"}'

# 从 stdin 传参
echo '{"action":"list"}' | lark-claw call feishu_task_task

查看 Skills

# 列出所有 skill
lark-claw skills

# 查看单个 skill 的完整内容（含调用指南和参数说明）
lark-claw skills feishu-task

用户授权

# 手动授权（自动检测 App Owner）
lark-claw auth

# 指定用户和权限
lark-claw auth ou_xxx --scope "task:task:write calendar:calendar:read"

# 查看授权状态
lark-claw auth-status

# 撤销授权
lark-claw auth-revoke

授权机制

工具调用时如果缺少用户授权，CLI 会：

1. 自动发送授权卡片到用户（通过 Bot DM）
2. 等待用户点击卡片完成授权（最多 3 分钟 × 5 轮）
3. 自动重试工具调用

支持多轮增量授权 —— 不同工具需要不同权限，按需授权即可。Token 存储在系统安全存储中：

| 平台 | 存储方式 | |------|---------| | macOS | Keychain | | Linux | AES-256-GCM 加密文件 (~/.local/share/openclaw-feishu-uat/) | | Windows | AES-256-GCM 加密文件 (%LOCALAPPDATA%\openclaw-feishu-uat\) |

输出格式

所有命令输出 JSON 到 stdout，状态日志到 stderr。

// 成功
{"ok": true, "data": {...}}

// 失败
{"ok": false, "error": "error_code", "data": {...}}

Exit code: 0 成功，1 失败。

工具列表

| 类别 | 工具 | 说明 | |------|------|------| | 通讯录 | feishu_get_user, feishu_search_user | 查询/搜索用户 | | 消息 | feishu_im_user_message, feishu_im_user_get_messages, feishu_im_user_search_messages 等 | 发送、获取、搜索消息 | | 群组 | feishu_chat, feishu_chat_members | 群管理和成员管理 | | 日历 | feishu_calendar_* | 日历、日程、参与者、空闲查询 | | 任务 | feishu_task_* | 任务、清单、评论、子任务 | | 多维表格 | feishu_bitable_* | 表格、记录、字段、视图 | | 文档 | feishu_create_doc, feishu_update_doc, feishu_fetch_doc | 云文档读写 | | 知识库 | feishu_wiki_* | 知识空间和节点 | | 云盘 | feishu_drive_file, feishu_doc_media | 文件和媒体管理 | | 表格 | feishu_sheet | 电子表格操作 |

运行 lark-claw schema 查看每个工具的完整参数定义。

AI Agent 集成指南

以下内容可直接放入 Agent 的系统提示词（System Prompt）中，让大模型知道如何以用户身份操作飞书。

# 飞书/Lark 工具 — lark-claw-cli

你可以通过 `lark-claw` CLI 以当前用户的身份操作飞书。该工具已配置好用户凭证，可直接调用。

## 何时使用

当用户要求你执行以下操作时，使用 lark-claw：
- 创建、查询、更新任务（Task）
- 查询或创建日历日程（Calendar）
- 创建、读取、编辑飞书文档（Doc）
- 发送或搜索消息（IM）
- 查询用户信息或通讯录
- 操作多维表格（Bitable）、知识库（Wiki）、云盘（Drive）等

## 使用流程

### 1. 了解可用工具

```bash
# 列出所有工具名
lark-claw list

# 查看某个工具的参数定义
lark-claw schema feishu_task_task

2. 了解使用指南

每个工具领域都有对应的 skill 文档，包含详细的参数说明和使用模式：

# 查看任务工具的完整使用指南
lark-claw skills feishu-task

# 查看文档工具的使用指南
lark-claw skills feishu-create-doc

可用的 skills：feishu-task、feishu-calendar、feishu-create-doc、feishu-update-doc、feishu-fetch-doc、feishu-bitable、feishu-im-read

3. 调用工具

lark-claw call <tool_name> '<json_params>'

4. 处理输出

所有输出为 JSON 格式：

• {"ok": true, "data": {...}} — 成功
• {"ok": false, "error": "...", "data": {...}} — 失败

典型用例

# 创建任务
lark-claw call feishu_task_task '{"action":"create","summary":"完成周报","due":{"date":"2026-03-14"}}'

# 查看今天的日程
lark-claw call feishu_calendar_event '{"action":"list","start_time":"2026-03-10T00:00:00+08:00","end_time":"2026-03-10T23:59:59+08:00"}'

# 创建飞书文档
lark-claw call feishu_create_doc '{"title":"会议纪要","markdown":"# 会议纪要\n\n## 参会人\n- 张三\n- 李四\n\n## 决议\n1. ..."}'

# 读取文档内容
lark-claw call feishu_fetch_doc '{"document_id":"doxcnxxxxx"}'

# 搜索用户
lark-claw call feishu_search_user '{"query":"张三"}'

# 发送消息
lark-claw call feishu_im_user_message '{"action":"create","receive_id":"ou_xxx","receive_id_type":"open_id","msg_type":"text","content":"{\"text\":\"你好\"}"}'

授权

调用工具时如果缺少权限，CLI 会自动向用户发送授权卡片并等待确认，无需你额外处理。如遇授权超时，提示用户在飞书中查看并点击授权卡片即可。

注意事项

• 不确定参数时，先用 lark-claw schema <tool> 和 lark-claw skills <skill> 查看定义
• 所有时间参数使用 ISO 8601 格式，注意时区
• JSON 参数中的字符串值需要正确转义
• 输出可能较长，关注 ok 字段判断成功与否

</details>

---

## 原理

lark-claw-cli 通过拦截 `@larksuiteoapi/feishu-openclaw-plugin` 的 `registerTool()` 调用来提取工具定义，使用插件内部的 OAuth Device Flow 和 Token Store 管理用户授权。一个最小的 `openclaw/plugin-sdk` shim 满足插件的运行时依赖。

更新 `@larksuiteoapi/feishu-openclaw-plugin` 包即可自动获得新工具和能力。