@xwang152/claw-lark 0.1.3 → 0.1.5

package/README.md

@@ -1,35 +1,57 @@
-# OpenClaw Feishu/Lark Plugin
 
-A channel plugin for OpenClaw that enables communication through the Feishu or Lark platform.
+# Lark Plugin for OpenClaw
+
+[中文文档](./README_zh.md)
+
+A channel plugin that enables OpenClaw to communicate via Lark (Larksuite) messaging platform.
 
 ## Features
 
-- **Dual Platform Support**: Full compatibility with Feishu (China) and Lark (International).
-- **WebSocket (Long Connection)**: Recommended for custom apps, low latency, no public IP required.
-- **Webhook Mode**: For traditional deployments, supports event verification and encryption.
-- **Multi-Mode Rendering**: Supports `auto` / `raw` / `card`, with Interactive Cards for Markdown, tables, and highlighting.
-- **Media Support**:
-  - **Inbound**: AI can receive images and files (PDF, Excel, Word, etc.).
-  - **Outbound**: Support for sending images and files.
-- **Advanced Interaction**:
-  - **Typing Indicator**: Simulated via message reactions.
-  - **@ Forwarding**: Automatic handling of @mentions in group chats.
-  - **Contextual Replies**: Support for message threading and replies.
-- **Auto-Recovery**: Automatic reconnection for WebSocket and server restarts for Webhooks.
+- **Direct Messages**: Chat with your bot one-on-one
+- **Group Chats**: Add your bot to group conversations
+- **Text Messages**: Send and receive text messages
+- **Multimedia Support**: Send and receive images and files (PDF, Excel, Word, etc.)
+- **Advanced Interaction**: Typing indicators, smart @mentions, and context quoting
+- **Multi-mode Rendering**: Support for `auto`, `raw`, and `card` modes
+- **Webhook Mode**: For individual Lark accounts (tested)
+- **WebSocket Mode**: For enterprise accounts (recommended for low latency)
+- **Auto-Recovery**: Webhook server automatically restarts on crashes
+
+## Requirements
+
+- OpenClaw installed and configured
+- A Lark Developer account
+- A Lark app with Bot capability enabled
 
 ## Installation
 
 ### 1. Automatic Installation (Recommended)
 
-Install directly via the OpenClaw CLI:
+Install directly via OpenClaw CLI:
 
 ```bash
 openclaw plugins install @xwang152/claw-lark
 ```
 
-### 2. Restart Gateway
+### 2. Manual Installation (Source Code)
 
-Restart the Gateway to load the plugin:
+If you wish to install from source or for development/debugging purposes:
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/xwang152/claw-lark.git
+cd claw-lark
+
+# Install dependencies
+npm install
+
+# Install plugin into OpenClaw
+openclaw plugins install --link .
+```
+
+### 3. Restart Gateway
+
+After installation, restart the Gateway to load the plugin:
 
 ```bash
 openclaw gateway restart
@@ -41,67 +63,200 @@ Verify installation:
 openclaw plugins list
 ```
 
-You should see the `feishu` plugin with a `loaded` status.
+You should see `lark` with status `loaded`.
+
+## Lark App Setup
+
+1. Go to [Lark Developer Console](https://open.larksuite.com/app)
+
+2. Create a new app or use an existing one
+
+3. Enable **Bot** capability under App Features
+
+4. Add the following permissions under Permissions & Scopes:
+
+| Permission | Scope | Description |
+| :--- | :--- | :--- |
+| `contact:user.base:readonly` | User Info | Get basic user info (to resolve sender names and avoid identity confusion) |
+| `im:message` | Message | Send and receive messages |
+| `im:message.p2p_msg:readonly` | P2P Message | Read direct messages sent to the bot |
+| `im:message.group_at_msg:readonly` | Group Message | Receive messages where the bot is @mentioned in groups |
+| `im:message:send_as_bot` | Send | Send messages as the bot |
+| `im:resource` | Resource | Upload/download images and files |
+
+**Optional Permissions (add as needed):**
+
+| Permission | Scope | Description |
+| :--- | :--- | :--- |
+| `im:message.group_msg` | Group | Read all group messages (Sensitive permission) |
+| `im:message:readonly` | Read | Get historical messages |
+| `im:message:update` | Edit | Update/edit sent messages |
+| `im:message:recall` | Recall | Recall sent messages |
+| `im:message.reactions:read` | Reaction | View message emoji reactions |
+| `im:chat` | Group | Get group list info |
+| `contact:user.employee:readonly` | Contact | Read employee info (alternative to user.base) |
+
+5. Note your **App ID** and **App Secret** from Credentials & Basic Info (you'll need these for configuration)
+
+6. Publish your app under Version Management
 
 ## Configuration
 
-### Example Configuration (`openclaw.yaml`)
-
-```yaml
-channels:
-  feishu:
-    accounts:
-      default:
-        enabled: true
-        appId: "cli_a9f722ad2cb9dccb"
-        appSecret: "********"
-        # Domain: "feishu" (China) or "lark" (International)
-        domain: "feishu"
-        # Mode: "websocket" (recommended) or "webhook"
-        connectionMode: "websocket"
-        # Webhook settings (required only for webhook mode)
-        # verificationToken: "********"
-        # encryptKey: "********"
-        # webhookPort: 3000
-        # DM Policy: "pairing" | "open" | "allowlist"
-        dmPolicy: "pairing"
-        # DM allowlist (only when dmPolicy=allowlist, OpenID)
-        # dmAllowlist:
-        #   - "ou_xxx"
-        # Group Policy: "open" | "allowlist" | "disabled"
-        groupPolicy: "allowlist"
-        # Group allowlist (only when groupPolicy=allowlist, ChatID)
-        # groupAllowlist:
-        #   - "oc_xxx"
-        # Require @mention in groups
-        requireMention: true
-        # Max media size (MB, default 30)
-        mediaMaxMb: 30
-        # Rendering mode: "auto" | "raw" | "card"
-        renderMode: "auto"
-        # History limit (default 10)
-        # historyLimit: 10
+### Using Config Commands
+
+```bash
+# Required settings
+openclaw config set channels.lark.accounts.default.appId 'cli_xxxxx'
+openclaw config set channels.lark.accounts.default.appSecret 'your-app-secret'
+openclaw config set channels.lark.accounts.default.connectionMode 'webhook'
+
+# Optional settings
+openclaw config set channels.lark.accounts.default.webhookPort 3000
+openclaw config set channels.lark.accounts.default.domain 'lark'
+openclaw config set channels.lark.accounts.default.dmPolicy 'open'
+openclaw config set channels.lark.accounts.default.groupPolicy 'open'
+openclaw config set channels.lark.accounts.default.groupMentionGated false
+
+# Security settings (from Lark Developer Console > Events & Callbacks > Encryption Strategy)
+openclaw config set channels.lark.accounts.default.encryptKey 'your-encrypt-key'
+openclaw config set channels.lark.accounts.default.verificationToken 'your-verification-token'
+```
+
+### Using Environment Variables
+
+For the default account, you can use environment variables:
+
+```bash
+LARK_APP_ID=cli_xxxxx
+LARK_APP_SECRET=your-app-secret
+
+# Security settings (from Lark Developer Console > Events & Callbacks > Encryption Strategy)
+LARK_ENCRYPT_KEY=your-encrypt-key          # Optional, for decrypting event payloads
+LARK_VERIFICATION_TOKEN=your-token         # Optional, for verifying request authenticity
 ```
 
-### Rendering Modes
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appId` | string | - | Lark App ID (required) |
+| `appSecret` | string | - | Lark App Secret (required) |
+| `connectionMode` | string | `websocket` | `webhook` or `websocket` |
+| `webhookPort` | number | `3000` | Port for webhook server |
+| `domain` | string | `lark` | `lark` (international) or `feishu` (China) |
+| `encryptKey` | string | - | Encrypt key for decrypting event payloads (from Events & Callbacks > Encryption Strategy) |
+| `verificationToken` | string | - | Token for verifying request authenticity (from Events & Callbacks > Encryption Strategy) |
+| `dmPolicy` | string | `pairing` | `open`, `pairing`, or `allowlist` |
+| `groupPolicy` | string | `open` | `open`, `allowlist`, or `disabled` |
+| `requireMention` | boolean | `true` | Require @mention in groups (previously `groupMentionGated`) |
+| `renderMode` | string | `auto` | `auto`, `raw`, or `card` |
+| `mediaMaxMb` | number | `30` | Max size for media files in MB |
+| `historyLimit` | number | `10` | Number of historical messages to read |
+
+## Render Modes
 
 | Mode | Description |
 | :--- | :--- |
-| **auto** | (Default) Automatic detection: Use cards for code blocks, lists, or tables, otherwise use plain text. |
-| **raw** | Always use plain text. Tables are converted to ASCII text. |
-| **card** | Always use Feishu Interactive Cards with Markdown syntax highlighting. |
+| **auto** | (Default) Automatically detects code blocks, lists, or tables to use card rendering; otherwise uses plain text |
+| **raw** | Always use plain text; tables are converted to ASCII text |
+| **card** | Always use Lark interactive cards; supports Markdown highlighting and advanced layouts |
+
+## Webhook Mode Setup
+
+Choose the setup method based on your deployment environment.
+
+### 1. Development (Using ngrok)
+
+Recommended for local development and testing.
+
+> **Security & Privacy Notice**: ngrok exposes your local server to the internet. Keep the following in mind:
+> - Never share your ngrok URL publicly — anyone with the URL can send requests to your local machine
+> - Use a paid ngrok plan with authentication or IP restrictions for production use
+> - Stop ngrok when not in use to close the tunnel
+> - Consider using Lark's `encryptKey` and `verificationToken` for additional request validation
 
-## Development
+1. Start ngrok to expose your local webhook server:
 
 ```bash
-git clone https://github.com/xwang152-jack/claw-lark.git
-cd claw-lark
-npm install
-npm run typecheck
-openclaw plugins install --link .
+ngrok http 3000
 ```
 
-### Commands
-- `npm run lint`: Lint code
-- `npm run format`: Format code
-- `npm test`: Run tests
+2. Copy the HTTPS URL from ngrok (e.g., `https://abc123.ngrok.io`)
+
+3. Configure Events & Callbacks in Lark Developer Console:
+   - Add event subscription: `im.message.receive_v1`
+   - Set Request URL to your ngrok HTTPS URL (e.g., `https://abc123.ngrok.io`)
+
+### 2. Production (Server Deployment)
+
+When deploying on a server, ngrok is **not** required.
+
+1. **Open Port**: Ensure your server's firewall (Security Group) allows traffic on the port used by the plugin (default is `3000`).
+2. **Configure URL**: In Lark Developer Console, configure "Events & Callbacks":
+   - Set the "Request URL" to your server's public address: `http://your-server-ip:3000`.
+3. **(Recommended) Reverse Proxy**: Use Nginx or Caddy to set up a reverse proxy with SSL (HTTPS) and forward traffic to port `3000`.
+
+### 3. Start the Plugin
+
+1. Start OpenClaw:
+
+```bash
+openclaw start
+```
+
+2. The webhook server will start automatically and handle URL verification.
+
+## WebSocket Mode
+
+WebSocket mode is available for enterprise Lark accounts that support long connections. Set `connectionMode` to `websocket`:
+
+```bash
+openclaw config set channels.lark.accounts.default.connectionMode 'websocket'
+```
+
+> **Note**: WebSocket mode requires enterprise Lark accounts and does not need a public IP or webhook configuration.
+
+## Multiple Accounts
+
+You can configure multiple Lark accounts:
+
+```bash
+openclaw config set channels.lark.accounts.work.appId 'cli_work_app'
+openclaw config set channels.lark.accounts.work.appSecret 'work-secret'
+openclaw config set channels.lark.accounts.personal.appId 'cli_personal_app'
+openclaw config set channels.lark.accounts.personal.appSecret 'personal-secret'
+```
+
+## Troubleshooting
+
+### Bot not receiving messages
+
+1. Verify the event subscription `im.message.receive_v1` is added
+2. Check that the callback URL is correctly configured
+3. Ensure the required permissions are enabled
+4. Make sure the app is published (not just saved as draft)
+
+### Permission errors when sending images
+
+Add the `im:resource` permission in Lark Developer Console and republish your app.
+
+### Webhook server not starting
+
+Check if port 3000 is already in use. Change the port:
+
+```bash
+openclaw config set channels.lark.accounts.default.webhookPort 3001
+```
+
+### Connection issues with WebSocket mode
+
+WebSocket mode requires enterprise Lark accounts. If you have an individual account, use webhook mode instead.
+
+## Contributing
+
+Issues and pull requests are welcome! If you encounter bugs or have feature requests, please open an issue at https://github.com/xwang152-jack/claw-lark/issues.
+
+## License
+
+MIT
+

package/README_zh.md

@@ -1,21 +1,26 @@
 # OpenClaw 飞书/Lark 插件
 
+[English Document](./README.md)
+
 这是一个为 OpenClaw 开发的频道插件，使 OpenClaw 能够通过飞书 (Feishu) 或 Lark 平台进行通信。
 
 ## 功能特性
 
-- **双平台支持**：全面兼容飞书 (国内) 和 Lark (国际)
-- **长连接 (WebSocket)**：企业自建应用推荐使用，低延迟，无需公网 IP
-- **Webhook 模式**：适用于传统部署，支持事件验证和加密
-- **多模式渲染**：支持 `auto` / `raw` / `card` 三种模式，卡片模式支持 Markdown 语法高亮和表格
-- **多媒体支持**：
-  - **进站**：AI 可以接收图片、文件 (PDF, Excel, Word 等)
-  - **出站**：支持发送图片和文件
-- **高级交互**：
-  - **输入指示器**：通过消息表情回复模拟 "正在输入" 状态
-  - **@ 转发**：自动处理群聊中的 @ 提及
-  - **上下文引用**：支持消息引用和回复上下文
-- **自动恢复**：连接中断后自动重连，服务崩溃自动重启
+- **私聊 (Direct Messages)**：与机器人一对一聊天
+- **群聊 (Group Chats)**：将机器人添加到群组对话中
+- **文本消息 (Text Messages)**：发送和接收文本消息
+- **多媒体支持 (Multimedia Support)**：发送和接收图片及文件（PDF, Excel, Word 等）
+- **高级交互 (Advanced Interaction)**：输入状态指示、智能 @提及 和 上下文引用
+- **多模式渲染 (Multi-mode Rendering)**：支持 `auto`、`raw` 和 `card` 模式
+- **Webhook 模式 (Webhook Mode)**：适用于个人飞书账号（已测试）
+- **WebSocket 模式 (WebSocket Mode)**：适用于企业账号（推荐用于低延迟）
+- **自动恢复 (Auto-Recovery)**：Webhook 服务崩溃后自动重启
+
+## 环境要求
+
+- 已安装并配置 OpenClaw
+- 拥有飞书/Lark 开发者账号
+- 一个已启用**机器人**能力的应用
 
 ## 安装步骤
 
@@ -27,7 +32,21 @@
 openclaw plugins install @xwang152/claw-lark
 ```
 
-### 2. 重启 Gateway
+### 2. 手动安装 (源码安装)
+
+```bash
+# 克隆仓库
+git clone https://github.com/xwang152-jack/claw-lark.git
+cd claw-lark
+
+# 安装依赖
+npm install
+
+# 安装插件到 OpenClaw
+openclaw plugins install --link .
+```
+
+### 3. 重启 Gateway
 
 安装完成后，重启 Gateway 以加载插件：
 
@@ -41,83 +60,225 @@ openclaw gateway restart
 openclaw plugins list
 ```
 
-您应该能看到 `feishu` 插件且状态为 `loaded`。
+您应该能看到 `lark` 插件且状态为 `loaded`。
 
 ## 飞书应用设置
 
 1. 前往 [飞书开放平台](https://open.feishu.cn/app) (国内) 或 [Lark Developer Console](https://open.larksuite.com/app) (国际)
-2. 创建新应用，在“应用能力”中启用 **机器人** 能力
-3. 在“权限管理”中添加以下权限：
-   - `im:message` (消息)
-   - `im:message.p2p_msg:readonly` (读取私聊)
-   - `im:message.group_at_msg:readonly` (读取群聊 @ 提及)
-   - `im:message:send_as_bot` (以机器人身份发送消息)
-   - `im:resource` (媒体文件权限)
-   - `im:chat` (群组管理，用于获取群列表)
-   - `contact:user.employee:readonly` (通讯录读取，可选)
-4. 在“版本管理与发布”中发布应用。
+
+2. 创建新应用或使用现有应用
+
+3. 在“应用能力”下启用 **机器人** 能力
+
+4. 在“权限管理”中添加以下权限：
+
+| 权限 | 作用范围 | 描述 |
+| :--- | :--- | :--- |
+| `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` | 表情回应 | 查看消息的表情回应 |
+| `im:chat` | 群组 | 获取群组列表信息 |
+| `contact:user.employee:readonly` | 通讯录 | 读取员工信息（user.base 的替代方案） |
+
+5. 在“凭证与基础信息”中记录您的 **App ID** 和 **App Secret**（配置时需要用到）
+
+6. 在“版本管理与发布”中发布您的应用
 
 ## 配置说明
 
-### 配置文件示例 (`openclaw.yaml`)
-
-```yaml
-channels:
-  feishu:
-    accounts:
-      default:
-        enabled: true
-        appId: "cli_a9f722ad2cb9dccb"
-        appSecret: "********"
-        # 域名: "feishu" (国内) 或 "lark" (国际)
-        domain: "feishu"
-        # 连接模式: "websocket" (推荐) 或 "webhook"
-        connectionMode: "websocket"
-        # Webhook 相关 (仅在 webhook 模式需要)
-        # verificationToken: "********"
-        # encryptKey: "********"
-        # webhookPort: 3000
-        # 私聊策略: "pairing" | "open" | "allowlist"
-        dmPolicy: "pairing"
-        # 私聊白名单 (仅 dmPolicy=allowlist 时生效，填写 OpenID)
-        # dmAllowlist:
-        #   - "ou_xxx"
-        # 群聊策略: "open" | "allowlist" | "disabled"
-        groupPolicy: "allowlist"
-        # 群聊白名单 (仅 groupPolicy=allowlist 时生效，填写 ChatID)
-        # groupAllowlist:
-        #   - "oc_xxx"
-        # 群聊是否需要 @机器人
-        requireMention: true
-        # 媒体文件最大大小 (MB, 默认 30)
-        mediaMaxMb: 30
-        # 回复渲染模式: "auto" | "raw" | "card"
-        renderMode: "auto"
-        # 历史消息读取条数 (默认 10)
-        # historyLimit: 10
+### 使用配置命令
+
+```bash
+# 必填设置
+openclaw config set channels.lark.accounts.default.appId 'cli_xxxxx'
+openclaw config set channels.lark.accounts.default.appSecret 'your-app-secret'
+openclaw config set channels.lark.accounts.default.connectionMode 'webhook'
+
+# 选填设置
+openclaw config set channels.lark.accounts.default.webhookPort 3000
+openclaw config set channels.lark.accounts.default.domain 'lark'
+openclaw config set channels.lark.accounts.default.dmPolicy 'open'
+openclaw config set channels.lark.accounts.default.groupPolicy 'open'
+openclaw config set channels.lark.accounts.default.requireMention true
+openclaw config set channels.lark.accounts.default.renderMode 'auto'
+
+# 安全设置 (来自 飞书开发者后台 > 事件订阅 > 加密策略)
+openclaw config set channels.lark.accounts.default.encryptKey 'your-encrypt-key'
+openclaw config set channels.lark.accounts.default.verificationToken 'your-verification-token'
 ```
 
-### 渲染模式说明
+### 使用环境变量
+
+对于默认账号，您可以使用环境变量进行配置：
+
+```bash
+LARK_APP_ID=cli_xxxxx
+LARK_APP_SECRET=your-app-secret
+
+# 安全设置 (来自 飞书开发者后台 > 事件订阅 > 加密策略)
+LARK_ENCRYPT_KEY=your-encrypt-key          # 可选，用于解密事件负载
+LARK_VERIFICATION_TOKEN=your-token         # 可选，用于验证请求真实性
+```
+
+### 配置选项
+
+| 选项 | 类型 | 默认值 | 描述 |
+|--------|------|---------|-------------|
+| `appId` | string | - | 飞书 App ID (必填) |
+| `appSecret` | string | - | 飞书 App Secret (必填) |
+| `connectionMode` | string | `websocket` | `webhook` 或 `websocket` |
+| `webhookPort` | number | `3000` | Webhook 服务器端口 |
+| `domain` | string | `lark` | `lark` (国际版) 或 `feishu` (国内版) |
+| `encryptKey` | string | - | 加密密钥，用于解密事件负载 (来自 事件订阅 > 加密策略) |
+| `verificationToken` | string | - | 验证令牌，用于验证请求真实性 (来自 事件订阅 > 加密策略) |
+| `dmPolicy` | string | `pairing` | `open` (开放), `pairing` (配对), 或 `allowlist` (白名单) |
+| `groupPolicy` | string | `open` | `open` (开放), `allowlist` (白名单), 或 `disabled` (禁用) |
+| `requireMention` | boolean | `true` | 群聊中是否需要 @提及 (原 `groupMentionGated`) |
+| `renderMode` | string | `auto` | `auto`, `raw`, 或 `card` |
+| `mediaMaxMb` | number | `30` | 媒体文件最大大小 (MB) |
+| `historyLimit` | number | `10` | 读取历史消息的数量 |
 
-| 模式 | 说明 |
+## 渲染模式
+
+| 模式 | 描述 |
 | :--- | :--- |
-| **auto** | (默认) 自动检测：检测到代码块、列表或表格时使用卡片渲染，否则使用纯文本 |
-| **raw** | 始终使用纯文本渲染，表格会被转换为 ASCII 文本 |
-| **card** | 始终使用飞书交互式卡片渲染，支持 Markdown 语法高亮和高级布局 |
+| **auto** | (默认) 自动检测：检测到代码块、列表或表格时使用卡片渲染；否则使用纯文本 |
+| **raw** | 始终使用纯文本渲染；表格会被转换为 ASCII 文本 |
+| **card** | 始终使用飞书交互式卡片渲染；支持 Markdown 语法高亮和高级布局 |
+
+## Webhook 模式指引
+
+根据您的部署环境选择设置方法。
+
+### 1. 开发环境 (使用 ngrok)
+
+推荐用于本地开发和测试。
+
+> **安全与隐私提示**：ngrok 会将您的本地服务器暴露给互联网。请注意以下几点：
+> - 永远不要公开分享您的 ngrok URL —— 任何拥有该 URL 的人都可以向您的本地机器发送请求
+> - 生产环境请使用带有身份验证或 IP 限制的付费 ngrok 计划
+> - 不使用时请停止 ngrok 以关闭隧道
+> - 建议使用飞书的 `encryptKey` 和 `verificationToken` 进行额外的请求验证
+
+1. 启动 ngrok 以暴露本地 webhook 服务器：
+
+```bash
+ngrok http 3000
+```
+
+2. 从 ngrok 复制 HTTPS URL (例如 `https://abc123.ngrok.io`)
+
+3. 在飞书开发者后台配置“事件订阅”：
+   - 添加事件订阅：`im.message.receive_v1`
+   - 将请求网址 URL 设置为您的 ngrok HTTPS URL (例如 `https://abc123.ngrok.io`)
+
+### 2. 生产环境 (服务器部署)
+
+部署在服务器上时，**不需要** ngrok。
+
+1. **开放端口**：确保您服务器的防火墙 (安全组) 允许插件使用的端口流量 (默认为 `3000`)。
+2. **配置 URL**：在飞书开发者后台，配置“事件订阅”：
+   - 将“请求网址 URL”设置为您服务器的公网地址：`http://your-server-ip:3000`。
+3. **(推荐) 反向代理**：使用 Nginx 或 Caddy 设置带有 SSL (HTTPS) 的反向代理，并将流量转发到端口 `3000`。
+
+### 3. 启动插件
+
+1. 启动 OpenClaw：
+
+```bash
+openclaw start
+```
+
+2. Webhook 服务器将自动启动并处理 URL 验证。
+
+## WebSocket 模式
+
+WebSocket 模式适用于支持长连接的企业自建应用。将 `connectionMode` 设置为 `websocket`：
+
+```bash
+openclaw config set channels.lark.accounts.default.connectionMode 'websocket'
+```
+
+> **注意**：WebSocket 模式需要企业自建应用，无需配置公网 IP 或回调地址。
+
+## 多账号配置
+
+您可以配置多个飞书账号：
+
+```bash
+openclaw config set channels.lark.accounts.work.appId 'cli_work_app'
+openclaw config set channels.lark.accounts.work.appSecret 'work-secret'
+openclaw config set channels.lark.accounts.personal.appId 'cli_personal_app'
+openclaw config set channels.lark.accounts.personal.appSecret 'personal-secret'
+```
+
+## 故障排除
+
+### 机器人无法接收消息
+
+1. 验证是否已添加事件订阅 `im.message.receive_v1`
+2. 检查回调 URL 是否配置正确
+3. 确保已启用所需的权限
+4. 确保应用已发布（不仅仅是保存为草稿）
+
+### 发送图片时出现权限错误
+
+在飞书开发者后台添加 `im:resource` 权限并重新发布应用。
+
+### Webhook 服务无法启动
+
+检查端口 3000 是否已被占用。更改端口：
+
+```bash
+openclaw config set channels.lark.accounts.default.webhookPort 3001
+```
+
+### WebSocket 模式连接问题
+
+WebSocket 模式需要企业自建应用。如果您是个人账号，请改用 webhook 模式。
 
 ## 开发者相关
 
+欢迎提交 Issue 和 Pull Request！如果您遇到 Bug 或有功能请求，请在 https://github.com/xwang152-jack/claw-lark/issues 提交 Issue。
+
+### 开发环境设置
+
 如果您想参与开发：
 
 ```bash
+# 克隆仓库
 git clone https://github.com/xwang152-jack/claw-lark.git
 cd claw-lark
+
+# 安装依赖
 npm install
+
+# 运行类型检查
 npm run typecheck
+
+# 链接插件以进行本地开发
 openclaw plugins install --link .
 ```
 
 ### 常用命令
+
 - `npm run lint`: 代码风格检查
 - `npm run format`: 自动格式化代码
-- `npm test`: 运行自动化测试
+- `npm test`: 运行测试
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xwang152/claw-lark",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Lark/Feishu channel plugin for OpenClaw with WebSocket and Webhook support",
   "license": "MIT",