Lark Toolkit

Prerequisites & Security

This skill is a documentation-only reference guide. It contains no executable code that accesses credentials automatically.

Required credentials (user-provided, never bundled):

- Lark App ID (app_id) — from Lark Developer Console
Lark App Secret (app_secret) — from the same console

How credentials are used:

- All API examples in SKILL.md use placeholders (<APP_ID>, <APP_SECRET>, CHAT_ID, etc.) — no real secrets
The scripts/get_token.sh helper obtains a temporary tenant_access_token from Lark's auth API. It reads credentials from (in order):

1. Command-line arguments
2. LARK_APP_ID / LARK_APP_SECRET environment variables
3. ~/.openclaw/openclaw.json (standard OpenClaw config, path channels.lark.accounts.default.appId/appSecret)

- The script prints the config source to stderr when falling back to the config file
No credentials are hardcoded, cached to disk, logged, or transmitted beyond the single Lark auth API call
The token is exported as LARK_TOKEN env var for subsequent commands in the same shell session

Three Access Paths

Need	Path	When
Send/receive messages	claw-lark plugin (message tool)	Basic text, media, reactions — simplest
Structured CRUD ops

Rule: claw-lark first → MCP second → direct API as fallback.

Authentication (Direct API)

CODEBLOCK0

Or use the helper: INLINECODE12

Token validity: ~2 hours. Cache it.

API Base URLs

Platform	API Base	Dev Console
Lark International	INLINECODE13	INLINECODE14
Feishu (China)

https://open.feishu.cn/open-apis/ | https://open.feishu.cn/app |

⚠️ Lark ≠ Feishu. Always confirm which platform the tenant uses.

Common API Patterns

Send a Message

CODEBLOCK1

Reply in Thread

CODEBLOCK2

Add Reaction

CODEBLOCK3

Emoji types: THUMBSUP HEART LAUGH OK COOL FINGERHEART SMILE INLINECODE24

List Department Users (MCP gap — direct API only)

CODEBLOCK4

Key fields: name, open_id, employee_type (1=regular, 2=intern), INLINECODE28

Read Chat History

CODEBLOCK5

Add Bot to Group

CODEBLOCK6

MCP Tools (38 available)

CODEBLOCK7

Full catalog with parameters: references/mcp-tools.md

MCP Coverage

Module	Key Tools
Bitable	create apps/tables, CRUD records, list fields
Calendar

MCP Gaps (use direct API)

- List users by department — INLINECODE29
List departments — INLINECODE30
Add/remove group members — INLINECODE31
Send reactions — INLINECODE32
Upload images/files — POST /im/v1/images / INLINECODE34

Pagination

Most list APIs use cursor-based pagination:

CODEBLOCK8

Check has_more in response.

Error Handling

Code	Meaning
0	Success
99991663

Token expired — refresh | | 99991664 | Token invalid | | 99991400 | Bad request | | 99991403 | No permission — check app permissions |

Critical Pitfalls

1. Lark ≠ Feishu — International uses open.larksuite.com, China uses INLINECODE37
openid is per-app — Same user has different openid across different Lark apps
Webhook 5s timeout — Return 200 immediately, process async
Event dedup — Use event_id (Lark retries up to 3x)
Bot-to-bot blind spot — Lark does NOT push Bot A's messages to Bot B's webhook
Publishing required — Permission/event changes only take effect after publishing a new app version
ngrok IPv6 trap — Use 127.0.0.1:PORT not localhost:PORT in ngrok config
ngrok free domain — Returns interstitial HTML that Lark rejects. Use paid domain.

Detailed References

- Bot setup playbook: references/bot-setup.md
API reference: references/api-reference.md
MCP tools catalog: references/mcp-tools.md
Webhook & tunnel: references/webhook-setup.md
Troubleshooting: references/troubleshooting.md
Permissions: references/permissions.md

Lark Toolkit

前提条件与安全性

本技能仅为文档参考指南，不包含任何自动访问凭据的可执行代码。

所需凭据（由用户提供，绝不捆绑）：

- Lark App ID（appid）— 来自 Lark 开发者控制台
Lark App Secret（app_secret）— 来自同一控制台

凭据使用方式：

- SKILL.md 中的所有 API 示例均使用占位符（ID>、SECRET>、CHATID 等）— 不包含真实密钥
scripts/gettoken.sh 辅助脚本从 Lark 认证 API 获取临时 tenantaccesstoken。它按以下顺序读取凭据：

1. 命令行参数
2. LARKAPPID / LARKAPPSECRET 环境变量
3. ~/.openclaw/openclaw.json（标准 OpenClaw 配置，路径为 channels.lark.accounts.default.appId/appSecret）

- 当回退到配置文件时，脚本会将配置来源打印到 stderr
除单次 Lark 认证 API 调用外，不会硬编码、缓存到磁盘、记录或传输任何凭据
Token 会导出为 LARK_TOKEN 环境变量，供同一 shell 会话中的后续命令使用

三种访问路径

需求路径适用场景
发送/接收消息 claw-lark 插件（消息工具）基本文本、媒体、反应 — 最简单
结构化 CRUD 操作
通过 mcporter 使用 MCP 工具 | Bitable、日历、文档、任务、OKR — 38 个工具 | | 其他所有操作 | 直接 API（curl） | 联系人、成员管理、MCP 未覆盖的任何内容 |
规则： 优先使用 claw-lark → 其次 MCP → 最后直接 API。

认证（直接 API）

bash
TOKEN=$(curl -s -X POST https://open.larksuite.com/open-apis/auth/v3/tenantaccesstoken/internal \
-H Content-Type: application/json \
-d {appid:ID>,appsecret:SECRET>} \
| python3 -c import sys,json; print(json.load(sys.stdin)[tenantaccesstoken]))

或使用辅助脚本：bash scripts/get_token.sh

Token 有效期：约 2 小时。请缓存。

API 基础 URL

平台 API 基础地址开发者控制台
Lark 国际版 https://open.larksuite.com/open-apis/ https://open.larksuite.com/app
飞书（中国版）
https://open.feishu.cn/open-apis/ | https://open.feishu.cn/app |
⚠️ Lark ≠ 飞书。请务必确认租户使用的平台。

常见 API 模式

发送消息

bash
curl -X POST https://open.larksuite.com/open-apis/im/v1/messages?receiveidtype=chat_id \
-H Authorization: Bearer $TOKEN -H Content-Type: application/json \
-d {receiveid:CHATID,msg_type:text,content:{\text\:\hello\}}

在主题中回复

bash
curl -X POST https://open.larksuite.com/open-apis/im/v1/messages/MSG_ID/reply \
-H Authorization: Bearer $TOKEN -H Content-Type: application/json \
-d {msgtype:text,content:{\text\:\reply\},replyin_thread:true}

添加反应

bash
curl -X POST https://open.larksuite.com/open-apis/im/v1/messages/MSG_ID/reactions \
-H Authorization: Bearer $TOKEN -H Content-Type: application/json \
-d {reactiontype:{emojitype:THUMBSUP}}

表情类型：THUMBSUP HEART LAUGH OK COOL FINGERHEART SMILE JIAYOU

列出部门用户（MCP 未覆盖 — 仅直接 API）

bash

列出根部门

curl -s -H Authorization: Bearer $TOKEN \
https://open.larksuite.com/open-apis/contact/v3/departments?parentdepartmentid=0&pagesize=50&fetchchild=true

列出部门中的用户
curl -s -H Authorization: Bearer $TOKEN \ https://open.larksuite.com/open-apis/contact/v3/users?departmentid=ID>&page_size=50
关键字段：name、openid、employeetype（1=正式员工，2=实习生）、department_ids

读取聊天历史

bash
curl -s -H Authorization: Bearer $TOKEN \
https://open.larksuite.com/open-apis/im/v1/messages?containeridtype=chat&containerid=ID>&pagesize=20&sorttype=ByCreateTimeDesc

将机器人添加到群组

bash
curl -X POST https://open.larksuite.com/open-apis/im/v1/chats/ID>/members?memberidtype=appid \
-H Authorization: Bearer $TOKEN -H Content-Type: application/json \
-d {idlist:[APP_ID>]}

MCP 工具（38 个可用）

bash
mcporter call lark-mcp. key=value

完整目录及参数：references/mcp-tools.md

MCP 覆盖范围

模块关键工具
Bitable 创建应用/表格、CRUD 记录、列出字段
日历
创建/获取/更新事件、忙闲状态、主日历 | | 文档 | 读取内容、搜索、导入、设置权限 | | 即时通讯 | 创建/列出群组、获取成员、发送消息、列出历史 | | OKR | 批量获取、列出周期、CRUD 进度、查询评审 | | 报告 | 查询规则/任务、管理视图 | | 任务 | 创建/更新任务、添加成员/提醒 | | 知识库 | 搜索节点、获取节点详情 | | 通讯录 | 通过邮箱/手机号批量获取用户 ID |
MCP 未覆盖项（使用直接 API）

- 按部门列出用户 — GET /contact/v3/users?departmentid=
列出部门 — GET /contact/v3/departments
添加/移除群组成员 — POST /im/v1/chats/{chatid}/members
发送反应 — POST /im/v1/messages/{msg_id}/reactions
上传图片/文件 — POST /im/v1/images / POST /im/v1/files

分页

大多数列表 API 使用基于游标的分页：

?pagesize=50&pagetoken=fromprevious_response>

检查响应中的 has_more 字段。

错误处理

代码含义
0 成功
99991663
Token 过期 — 刷新 | | 99991664 | Token 无效 | | 99991400 | 错误请求 | | 99991403 | 无权限 — 检查应用权限 |
关键陷阱

1. Lark ≠ 飞书 — 国际版使用 open.larksuite.com，中国版使用 open.feishu.cn
openid 因应用而异 — 同一用户在不同 Lark 应用中具有不同的 openid
Webhook 5 秒超时 — 立即返回 200，异步处理
事件去重 — 使用 event_id（Lark 最多重试 3 次）
机器人间盲区 — Lark 不会将机器人 A 的消息推送到机器人 B 的 webhook
需要发布 — 权限/事件更改仅在发布新应用版本后生效
ngrok IPv6 陷阱 — 在 ngrok 配置中使用 127.0.0.1:PORT 而非 localhost:PORT
ngrok 免费域名 — 返回 Lark 拒绝的插页式 HTML。请使用

需求	路径	适用场景
发送/接收消息	claw-lark 插件（消息工具）	基本文本、媒体、反应 — 最简单
结构化 CRUD 操作

平台	API 基础地址	开发者控制台
Lark 国际版	https://open.larksuite.com/open-apis/	https://open.larksuite.com/app
飞书（中国版）

模块	关键工具
Bitable	创建应用/表格、CRUD 记录、列出字段
日历

代码	含义
0	成功
99991663

lark-toolkit飞书工具包

lark-toolkit

Lark Toolkit

Prerequisites & Security

Three Access Paths

Authentication (Direct API)

API Base URLs

Common API Patterns

Send a Message

Reply in Thread

Add Reaction

List Department Users (MCP gap — direct API only)

Read Chat History

Add Bot to Group

MCP Tools (38 available)

MCP Coverage

MCP Gaps (use direct API)

Pagination

Error Handling

Critical Pitfalls

Detailed References

Lark Toolkit

前提条件与安全性

三种访问路径

认证（直接 API）

API 基础 URL

常见 API 模式

发送消息

在主题中回复

添加反应

列出部门用户（MCP 未覆盖 — 仅直接 API）

列出根部门

列出部门中的用户

读取聊天历史

将机器人添加到群组

MCP 工具（38 个可用）

MCP 覆盖范围

MCP 未覆盖项（使用直接 API）

分页

错误处理

关键陷阱

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement