@noah-claw/feishu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m1heng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+# openclaw-feishu
+
+Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+### Installation
+
+```bash
+openclaw plugins install @noah-claw/feishu
+```
+
+Or install via npm:
+
+```bash
+npm install @noah-claw/feishu
+```
+
+### Configuration
+
+1. Create a self-built app on [Feishu Open Platform](https://open.feishu.cn)
+2. Get your App ID and App Secret from the Credentials page
+3. Enable required permissions (see below)
+4. **Configure event subscriptions** (see below) ⚠️ Important
+5. Configure the plugin:
+
+#### Required Permissions
+
+| Permission | Scope | Description |
+|------------|-------|-------------|
+| `contact:user.base:readonly` | User info | Get basic user info (required to resolve sender display names for speaker attribution) |
+| `im:message` | Messaging | Send and receive messages |
+| `im:message.p2p_msg:readonly` | DM | Read direct messages to bot |
+| `im:message.group_at_msg:readonly` | Group | Receive @mention messages in groups |
+| `im:message:send_as_bot` | Send | Send messages as the bot |
+| `im:resource` | Media | Upload and download images/files |
+
+#### Optional Permissions
+
+| Permission | Scope | Description |
+|------------|-------|-------------|
+| `im:message.group_msg` | Group | Read all group messages (sensitive) |
+| `im:message:readonly` | Read | Get message history |
+| `im:message:update` | Edit | Update/edit sent messages |
+| `im:message:recall` | Recall | Recall sent messages |
+| `im:message.reactions:read` | Reactions | View message reactions |
+
+#### Event Subscriptions ⚠️
+
+> **This is the most commonly missed configuration!** If the bot can send messages but cannot receive them, check this section.
+
+In the Feishu Open Platform console, go to **Events & Callbacks**:
+
+1. **Event configuration**: Select **Long connection** (recommended)
+2. **Add event subscriptions**:
+
+| Event | Description |
+|-------|-------------|
+| `im.message.receive_v1` | Receive messages (required) |
+| `im.message.message_read_v1` | Message read receipts |
+| `im.chat.member.bot.added_v1` | Bot added to group |
+| `im.chat.member.bot.deleted_v1` | Bot removed from group |
+
+3. Ensure the event permissions are approved
+
+```bash
+openclaw config set channels.feishu.appId "cli_xxxxx"
+openclaw config set channels.feishu.appSecret "your_app_secret"
+openclaw config set channels.feishu.enabled true
+```
+
+### Configuration Options
+
+```yaml
+channels:
+  feishu:
+    enabled: true
+    appId: "cli_xxxxx"
+    appSecret: "secret"
+    # Domain: "feishu" (China) or "lark" (International)
+    domain: "feishu"
+    # Connection mode: "websocket" (recommended) or "webhook"
+    connectionMode: "websocket"
+    # DM policy: "pairing" | "open" | "allowlist"
+    dmPolicy: "pairing"
+    # Group policy: "open" | "allowlist" | "disabled"
+    groupPolicy: "allowlist"
+    # Require @mention in groups
+    requireMention: true
+    # Max media size in MB (default: 30)
+    mediaMaxMb: 30
+    # Render mode for bot replies: "auto" | "raw" | "card"
+    renderMode: "auto"
+```
+
+#### Render Mode
+
+| Mode | Description |
+|------|-------------|
+| `auto` | (Default) Automatically detect: use card for messages with code blocks or tables, plain text otherwise. |
+| `raw` | Always send replies as plain text. Markdown tables are converted to ASCII. |
+| `card` | Always send replies as interactive cards with full markdown rendering (syntax highlighting, tables, clickable links). |
+
+### Features
+
+- WebSocket and Webhook connection modes
+- Direct messages and group chats
+- Message replies and quoted message context
+- **Inbound media support**: AI can see images, read files (PDF, Excel, etc.), and process rich text with embedded images
+- Image and file uploads (outbound)
+- Typing indicator (via emoji reactions)
+- Pairing flow for DM approval
+- User and group directory lookup
+- **Card render mode**: Optional markdown rendering with syntax highlighting
+
+### FAQ
+
+#### Bot cannot receive messages
+
+Check the following:
+1. Have you configured **event subscriptions**? (See Event Subscriptions section)
+2. Is the event configuration set to **long connection**?
+3. Did you add the `im.message.receive_v1` event?
+4. Are the permissions approved?
+
+#### 403 error when sending messages
+
+Ensure `im:message:send_as_bot` permission is approved.
+
+#### How to clear history / start new conversation
+
+Send `/new` command in the chat.
+
+#### Why is the output not streaming
+
+Feishu API has rate limits. Streaming updates can easily trigger throttling. We use complete-then-send approach for stability.
+
+#### Windows install error `spawn npm ENOENT`
+
+If `openclaw plugins install` fails, install manually:
+
+```bash
+# 1. Download the package
+curl -O https://registry.npmjs.org/@noah-claw/feishu/-/feishu-0.1.1.tgz
+
+# 2. Install from local file
+openclaw plugins install ./feishu-0.1.1.tgz
+```
+
+#### Cannot find the bot in Feishu
+
+1. Ensure the app is published (at least to test version)
+2. Search for the bot name in Feishu search box
+3. Check if your account is in the app's availability scope
+
+---
+
+## 中文
+
+### 安装
+
+```bash
+openclaw plugins install @noah-claw/feishu
+```
+
+或通过 npm 安装：
+
+```bash
+npm install @noah-claw/feishu
+```
+
+### 配置
+
+1. 在 [飞书开放平台](https://open.feishu.cn) 创建自建应用
+2. 在凭证页面获取 App ID 和 App Secret
+3. 开启所需权限（见下方）
+4. **配置事件订阅**（见下方）⚠️ 重要
+5. 配置插件：
+
+#### 必需权限
+
+| 权限 | 范围 | 说明 |
+|------|------|------|
+| `contact:user.base:readonly` | 用户信息 | 获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者） |
+| `im:message` | 消息 | 发送和接收消息 |
+| `im:message.p2p_msg:readonly` | 私聊 | 读取发给机器人的私聊消息 |
+| `im:message.group_at_msg:readonly` | 群聊 | 接收群内 @机器人 的消息 |
+| `im:message:send_as_bot` | 发送 | 以机器人身份发送消息 |
+| `im:resource` | 媒体 | 上传和下载图片/文件 |
+
+#### 可选权限
+
+| 权限 | 范围 | 说明 |
+|------|------|------|
+| `im:message.group_msg` | 群聊 | 读取所有群消息（敏感） |
+| `im:message:readonly` | 读取 | 获取历史消息 |
+| `im:message:update` | 编辑 | 更新/编辑已发送消息 |
+| `im:message:recall` | 撤回 | 撤回已发送消息 |
+| `im:message.reactions:read` | 表情 | 查看消息表情回复 |
+
+#### 事件订阅 ⚠️
+
+> **这是最容易遗漏的配置！** 如果机器人能发消息但收不到消息，请检查此项。
+
+在飞书开放平台的应用后台，进入 **事件与回调** 页面：
+
+1. **事件配置方式**：选择 **使用长连接接收事件**（推荐）
+2. **添加事件订阅**，勾选以下事件：
+
+| 事件 | 说明 |
+|------|------|
+| `im.message.receive_v1` | 接收消息（必需） |
+| `im.message.message_read_v1` | 消息已读回执 |
+| `im.chat.member.bot.added_v1` | 机器人进群 |
+| `im.chat.member.bot.deleted_v1` | 机器人被移出群 |
+
+3. 确保事件订阅的权限已申请并通过审核
+
+```bash
+openclaw config set channels.feishu.appId "cli_xxxxx"
+openclaw config set channels.feishu.appSecret "your_app_secret"
+openclaw config set channels.feishu.enabled true
+```
+
+### 配置选项
+
+```yaml
+channels:
+  feishu:
+    enabled: true
+    appId: "cli_xxxxx"
+    appSecret: "secret"
+    # 域名: "feishu" (国内) 或 "lark" (国际)
+    domain: "feishu"
+    # 连接模式: "websocket" (推荐) 或 "webhook"
+    connectionMode: "websocket"
+    # 私聊策略: "pairing" | "open" | "allowlist"
+    dmPolicy: "pairing"
+    # 群聊策略: "open" | "allowlist" | "disabled"
+    groupPolicy: "allowlist"
+    # 群聊是否需要 @机器人
+    requireMention: true
+    # 媒体文件最大大小 (MB, 默认 30)
+    mediaMaxMb: 30
+    # 回复渲染模式: "auto" | "raw" | "card"
+    renderMode: "auto"
+```
+
+#### 渲染模式
+
+| 模式 | 说明 |
+|------|------|
+| `auto` | （默认）自动检测：有代码块或表格时用卡片，否则纯文本 |
+| `raw` | 始终纯文本，表格转为 ASCII |
+| `card` | 始终使用卡片，支持语法高亮、表格、链接等 |
+
+### 功能
+
+- WebSocket 和 Webhook 连接模式
+- 私聊和群聊
+- 消息回复和引用上下文
+- **入站媒体支持**：AI 可以看到图片、读取文件（PDF、Excel 等）、处理富文本中的嵌入图片
+- 图片和文件上传（出站）
+- 输入指示器（通过表情回复实现）
+- 私聊配对审批流程
+- 用户和群组目录查询
+- **卡片渲染模式**：支持语法高亮的 Markdown 渲染
+
+### 常见问题
+
+#### 机器人收不到消息
+
+检查以下配置：
+1. 是否配置了 **事件订阅**？（见上方事件订阅章节）
+2. 事件配置方式是否选择了 **长连接**？
+3. 是否添加了 `im.message.receive_v1` 事件？
+4. 相关权限是否已申请并审核通过？
+
+#### 返回消息时 403 错误
+
+确保已申请 `im:message:send_as_bot` 权限，并且权限已审核通过。
+
+#### 如何清理历史会话 / 开启新对话
+
+在聊天中发送 `/new` 命令即可开启新对话。
+
+#### 消息为什么不是流式输出
+
+飞书 API 有请求频率限制，流式更新消息很容易触发限流。当前采用完整回复后一次性发送的方式，以保证稳定性。
+
+#### Windows 安装报错 `spawn npm ENOENT`
+
+如果 `openclaw plugins install` 失败，可以手动安装：
+
+```bash
+# 1. 下载插件包
+curl -O https://registry.npmjs.org/@noah-claw/feishu/-/feishu-0.1.1.tgz
+
+# 2. 从本地安装
+openclaw plugins install ./feishu-0.1.1.tgz
+```
+
+#### 在飞书里找不到机器人
+
+1. 确保应用已发布（至少发布到测试版本）
+2. 在飞书搜索框中搜索机器人名称
+3. 检查应用可用范围是否包含你的账号
+
+---
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,41 @@
+import type { ClawdbotPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { feishuPlugin } from "./src/channel.js";
+import { setFeishuRuntime } from "./src/runtime.js";
+
+export { monitorFeishuProvider } from "./src/monitor.js";
+export {
+  sendMessageFeishu,
+  sendCardFeishu,
+  updateCardFeishu,
+  editMessageFeishu,
+  getMessageFeishu,
+} from "./src/send.js";
+export {
+  uploadImageFeishu,
+  uploadFileFeishu,
+  sendImageFeishu,
+  sendFileFeishu,
+  sendMediaFeishu,
+} from "./src/media.js";
+export { probeFeishu } from "./src/probe.js";
+export {
+  addReactionFeishu,
+  removeReactionFeishu,
+  listReactionsFeishu,
+  FeishuEmoji,
+} from "./src/reactions.js";
+export { feishuPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "feishu",
+  name: "Feishu",
+  description: "Feishu/Lark channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setFeishuRuntime(api.runtime);
+    api.registerChannel({ plugin: feishuPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "feishu",
+  "channels": ["feishu"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@noah-claw/feishu",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw Feishu/Lark channel plugin",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noah/openclaw-feishu.git"
+  },
+  "keywords": [
+    "openclaw",
+    "feishu",
+    "lark",
+    "飞书",
+    "chatbot",
+    "ai",
+    "claude"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "feishu",
+      "label": "Feishu",
+      "selectionLabel": "Feishu/Lark (飞书)",
+      "docsPath": "/channels/feishu",
+      "docsLabel": "feishu",
+      "blurb": "飞书/Lark enterprise messaging.",
+      "aliases": [
+        "lark"
+      ],
+      "order": 70
+    },
+    "install": {
+      "npmSpec": "@noah-claw/feishu",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.30.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "openclaw": "2026.1.29",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.24"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,53 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "clawdbot/plugin-sdk";
+import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
+
+export function resolveFeishuCredentials(cfg?: FeishuConfig): {
+  appId: string;
+  appSecret: string;
+  encryptKey?: string;
+  verificationToken?: string;
+  domain: FeishuDomain;
+} | null {
+  const appId = cfg?.appId?.trim();
+  const appSecret = cfg?.appSecret?.trim();
+  if (!appId || !appSecret) return null;
+  return {
+    appId,
+    appSecret,
+    encryptKey: cfg?.encryptKey?.trim() || undefined,
+    verificationToken: cfg?.verificationToken?.trim() || undefined,
+    domain: cfg?.domain ?? "feishu",
+  };
+}
+
+export function resolveFeishuAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedFeishuAccount {
+  const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  const enabled = feishuCfg?.enabled !== false;
+  const creds = resolveFeishuCredentials(feishuCfg);
+
+  return {
+    accountId: params.accountId?.trim() || DEFAULT_ACCOUNT_ID,
+    enabled,
+    configured: Boolean(creds),
+    appId: creds?.appId,
+    domain: creds?.domain ?? "feishu",
+  };
+}
+
+export function listFeishuAccountIds(_cfg: ClawdbotConfig): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultFeishuAccountId(_cfg: ClawdbotConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function listEnabledFeishuAccounts(cfg: ClawdbotConfig): ResolvedFeishuAccount[] {
+  return listFeishuAccountIds(cfg)
+    .map((accountId) => resolveFeishuAccount({ cfg, accountId }))
+    .filter((account) => account.enabled && account.configured);
+}