Lark Toolkit

前置条件与安全说明

本技能为仅文档参考性质，不包含任何可执行代码，不会自动访问凭证。

必需的凭证（由用户自行提供，不会内置）：

• 飞书应用 ID (app_id) — 来自 [飞书开发者控制台](https://open.larksuite.com/app)
• 飞书应用密钥 (app_secret) — 同一控制台获取

凭证使用方式：

• 所有 SKILL.md 中的 API 示例均使用占位符（<APP_ID>、<APP_SECRET>、CHAT_ID 等）—— 不包含真实密钥
• scripts/get_token.sh 辅助脚本从飞书认证 API 获取临时 tenant_access_token。该脚本按以下顺序读取凭证：

1. 命令行参数

2. LARK_APP_ID / LARK_APP_SECRET 环境变量

3. **~/.openclaw/openclaw.json**（标准 OpenClaw 配置文件，路径为 channels.lark.accounts.default.appId/appSecret）

• 当脚本回退到配置文件时，会将来源信息输出至 stderr
• 无凭证硬编码、磁盘缓存、日志记录或超出单次飞书认证 API 调用范围的传输
• 获取的令牌以 LARK_TOKEN 环境变量形式导出，供同一 Shell 会话中后续命令使用

三种访问路径

使用规则： 先尝试 claw-lark → 再试 MCP → 最后使用直接 API 作为备选。

认证（直接 API）

TOKEN=$(curl -s -X POST 'https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")

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

令牌有效期：约 2 小时。建议缓存使用。

API 基础地址

⚠️ 飞书 ≠ 飞书中国版。请确认租户所用平台。

常见 API 模式

发送消息

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

在线程中回复

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 '{"msg_type":"text","content":"{\"text\":\"reply\"}","reply_in_thread":true}'

添加表情反应

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 '{"reaction_type":{"emoji_type":"THUMBSUP"}}'

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

列出部门成员（MCP 缺失功能 —— 必须使用直接 API）

# 列出根部门
curl -s -H "Authorization: Bearer $TOKEN" \
  'https://open.larksuite.com/open-apis/contact/v3/departments?parent_department_id=0&page_size=50&fetch_child=true'

# 列出某部门下的用户
curl -s -H "Authorization: Bearer $TOKEN" \
  'https://open.larksuite.com/open-apis/contact/v3/users?department_id=<DEPT_ID>&page_size=50'

关键字段：name、open_id、employee_type（1=正式员工，2=实习生）、department_ids

读取聊天历史

curl -s -H "Authorization: Bearer $TOKEN" \
  'https://open.larksuite.com/open-apis/im/v1/messages?container_id_type=chat&container_id=<CHAT_ID>&page_size=20&sort_type=ByCreateTimeDesc'

将机器人添加至群组

curl -X POST "https://open.larksuite.com/open-apis/im/v1/chats/<CHAT_ID>/members?member_id_type=app_id" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id_list":["<BOT_APP_ID>"]}'

MCP 工具（共 38 个可用）

mcporter call lark-mcp.<tool_name> key=value

完整工具列表及参数说明：[references/mcp-tools.md](references/mcp-tools.md)

MCP 功能覆盖范围

MCP 功能缺失项（需使用直接 API）

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

分页处理

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

?page_size=50&page_token=<上一次响应返回的 token>

请检查响应中的 has_more 字段判断是否还有更多数据。

错误处理

关键注意事项

Lark 工具包 (Lark Toolkit)

核心注意事项

1. Lark 与 飞书 的区别 — 国际版使用 open.larksuite.com，中国版使用 open.feishu.cn
2. open_id 为应用级唯一 — 同一用户在不同 Lark 应用中拥有不同的 open_id
3. Webhook 超时限制为 5 秒 — 必须立即返回 200 响应，后续处理需异步进行
4. 事件去重机制 — 使用 event_id 进行去重（Lark 可能重试最多 3 次）
5. 机器人间消息盲区 — Lark 不会将机器人 A 发送的消息推送到机器人 B 的 Webhook
6. 发布生效要求 — 权限或事件配置的变更仅在发布新版本应用后才生效
7. ngrok IPv6 陷阱 — ngrok 配置中请使用 127.0.0.1:PORT 而非 localhost:PORT
8. ngrok 免费域名限制 — 免费域名会返回中间页 HTML，Lark 会拒绝此类响应。请使用付费域名

详细参考文档

• 机器人设置指南: [references/bot-setup.md](references/bot-setup.md)
• API 接口参考: [references/api-reference.md](references/api-reference.md)
• MCP 工具目录: [references/mcp-tools.md](references/mcp-tools.md)
• Webhook 与隧道配置: [references/webhook-setup.md](references/webhook-setup.md)
• 故障排查手册: [references/troubleshooting.md](references/troubleshooting.md)
• 权限配置说明: [references/permissions.md](references/permissions.md)