Lark OpenClaw Plugin

一个 OpenClaw Gateway lifecycle 插件：在 before_agent_start 识别飞书/Lark 文档链接，拉取文档内容（blocks -> markdown-ish）注入上下文；在 agent_end 将本次对话追加写回该文档。

本插件不包含 index/检索能力，只做“读上下文 + 写回”。

功能

before_agent_start
从 event.prompt 中提取飞书/Lark 文档链接（/docx/<token> 或 /docs/<token>）
调用 Lark OpenAPI 拉取 docx blocks（支持分页）
将 blocks 转为可读文本（markdown-ish），截断后写入 prependContext
记录该 sessionId 对应的 docId，供 agent_end 写回
agent_end
从 event.messages 中抽取对话内容（smart/last_turn/full_session）
追加写入到上一步捕获的 Lark 文档（按段落拆分写入 docx text blocks）

目录结构

lark-openclaw-plugin/index.js：插件入口与 lifecycle hooks
lark-openclaw-plugin/src/clients/lark-client.js：Lark OpenAPI client（token 获取/缓存、blocks 拉取、追加写入）
lark-openclaw-plugin/src/services/lark-doc.js：doc 链接解析 + blocks 转 markdown-ish + 构建注入上下文
lark-openclaw-plugin/src/services/conversation-extractor.js：对话抽取/过滤/格式化
lark-openclaw-plugin/src/services/lark-doc-writer.js：写入节流/段落切分
lark-openclaw-plugin/openclaw.plugin.json：OpenClaw 插件声明与配置 schema

配置

插件会尝试读取：

1) ~/.openclaw/lark.config.json（可选） 2) 环境变量（可选，优先级更高） 3) 默认值（内置）

环境变量

LARK_API_BASE_URL：默认 https://open.feishu.cn/open-apis（国际版可用 https://open.larksuite.com/open-apis）
LARK_AUTH_MODE：app 或 token
LARK_APP_ID / LARK_APP_SECRET：authMode=app 时必填
LARK_ACCESS_TOKEN：authMode=token 时必填（直接作为 Bearer token）

提示：如果你只设置了 LARK_ACCESS_TOKEN 而没设置 LARK_AUTH_MODE，插件也会自动回退使用该 token。

运行时更新配置（可选）

插件支持两种“运行时更新”方式：

1) 本地 HTTP 管理接口（推荐，独立于 OpenClaw host 的调用方式） 2) 直接调用插件导出的函数（需要你的 OpenClaw host 支持调用）

1) 本地 HTTP 管理接口

开启方式（任一即可）：

环境变量：
LARK_MGMT_ENABLED=true
LARK_MGMT_HOST=127.0.0.1（可选）
LARK_MGMT_PORT=17888（可选）
LARK_MGMT_API_KEY=xxx（可选；启用后需要请求头 x-api-key）
或配置文件：

{
  "management": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 17888,
    "apiKey": "xxx"
  }
}

接口：

GET /status
POST /config（body 为 partial config，做 deep merge）
POST /token（{ "accessToken": "...", "apiBaseUrl?": "..." }）
POST /app（{ "appId": "...", "appSecret": "...", "apiBaseUrl?": "..." }）

示例：

curl -s http://127.0.0.1:17888/status

curl -s -X POST http://127.0.0.1:17888/token \
  -H 'Content-Type: application/json' \
  -d '{"accessToken":"YOUR_TOKEN","apiBaseUrl":"https://open.larksuite.com/open-apis"}'

2) 直接调用导出函数

插件入口 lark-openclaw-plugin/index.js 额外导出了这些函数，便于你的 OpenClaw host 在运行时动态修改配置：

updateConfig(partialConfig)：合并到当前配置并重建 LarkClient
setAccessToken(accessToken, { apiBaseUrl? })：快捷切到 authMode=token
setAppCredentials(appId, appSecret, { apiBaseUrl? })：快捷切到 authMode=app

（注：插件本身不会持久化写回配置文件；仅更新进程内配置。）

配置文件示例

~/.openclaw/lark.config.json

{
  "lark": {
    "apiBaseUrl": "https://open.feishu.cn/open-apis",
    "authMode": "app",
    "appId": "cli_xxx",
    "appSecret": "xxx"
  },
  "read": {
    "enabled": true,
    "maxContextChars": 8000
  },
  "write": {
    "enabled": true,
    "captureStrategy": "smart",
    "minContentLength": 50,
    "throttleMs": 3000,
    "maxAppendChars": 8000
  }
}

文档链接识别规则

在 event.prompt 中识别形如：

https://xxx.feishu.cn/docx/<docToken>
https://xxx.larksuite.com/docx/<docToken>
https://xxx.feishu.cn/docs/<docToken>（旧路径）

命中多个链接时，当前实现使用第一个链接作为写回目标。

对话内命令（可选）

你可以直接在对话里发送这些命令来运行时更新配置：

/lark token <accessToken> [apiBaseUrl]
/lark app <appId> <appSecret> [apiBaseUrl]
/lark status

注意：命令中的敏感信息在日志/状态输出中会被 mask。

写回格式

写回内容会被格式化为纯文本（包含时间戳、channel/sessionId、User/Assistant 分段），再按空行拆成多个段落，逐段写入为 docx 的 text block。

注意：这里不会把 markdown 结构（标题/列表/代码块）转换成对应的 docx block 类型，目标是“稳定写入、不报错”。

已知限制

读取侧 blocks->markdown-ish 只覆盖常见 block_type；不支持的类型会尽力提取 elements 文本。
Sheet/Table（block_type=30）当前为占位/降级输出（不拉取 sheets API）。
before_agent_start 目前只从 event.prompt 里找链接；如果你希望也从 event.messages/event.context 里找，可以再扩展。
暂时不做 channel 路由/分发能力（目前只把 event.channel 作为元信息写入文本）；后续会逐步增加一些 skills（例如按指令定向写入、结构化摘录等）。
如果未提供文档链接，默认不会写回；你可以开启 write.autoCreate.enabled=true 来在 agent_end 时自动创建一个 doc 并写入。

自动创建文档（可选）

当 agent_end 触发且本次 session 没有命中文档链接时，如果开启：

{
  "write": {
    "autoCreate": {
      "enabled": true,
      "folderToken": "",
      "titlePrefix": "OpenClaw"
    }
  }
}

插件会调用 Lark OpenAPI 创建一个新的 docx 文档，并将其作为该 session 的写回目标。

开发/测试

在仓库根目录运行（复用根目录 vitest）：

npx vitest run lark-openclaw-plugin/tests

TODO

支持多维表格/Sheets（block_type=30）：拉取 sheets API 并转为 markdown 表格
支持关键词识别与匹配：按关键词决定写入策略/自动路由/结构化摘要
支持 Lark webhook 机器人：通过机器人事件触发写入/更新配置/文档联动

lark-openclaw-plugin

Summary

Install to Claude Code