@xwang152/claw-lark 0.1.11 → 0.1.12

package/README.md

@@ -98,44 +98,45 @@ openclaw gateway restart
 | `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 |
+| `im:message.group_at_msg:readonly` | Group Message | Receive messages where the bot is mentioned in groups |
+| `im:message:send_as_bot` | Send Message | Send messages as the bot |
+| `im:resource` | Resource | Upload/Download images and files |
 
-**Optional Permissions (add as needed):**
+**Optional Permissions (Add as needed):**
 
 | Permission | Scope | Description |
 | :--- | :--- | :--- |
-| `im:message.group_msg` | Group | Read all group messages (Sensitive permission) |
+| `im:message.group_msg` | Group | Read all group messages (Sensitive) |
 | `im:message:readonly` | Read | Get historical messages |
-| `im:message:update` | Edit | Update/edit sent 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) |
+| `im:message.reactions:read` | Reactions | View message reactions |
+| `im:chat` | Group | Get group chat information |
+| `contact:user.employee:readonly` | User Info | 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)
+5. Note down your **App ID** and **App Secret** from "Credentials & Basic Info"
 
-6. Publish your app under Version Management
+6. Publish your app under "Version Management & Release"
 
 ## Configuration
 
 ### Using Config Commands
 
 ```bash
-# Required settings
+# Required
 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
+# Optional
 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
+openclaw config set channels.lark.accounts.default.requireMention true
+openclaw config set channels.lark.accounts.default.renderMode 'auto'
 
-# Security settings (from Lark Developer Console > Events & Callbacks > Encryption Strategy)
+# Security (from Lark Developer Console > Event Subscriptions > Encrypt Strategy)
 openclaw config set channels.lark.accounts.default.encryptKey 'your-encrypt-key'
 openclaw config set channels.lark.accounts.default.verificationToken 'your-verification-token'
 ```
@@ -148,7 +149,7 @@ For the default account, you can use environment variables:
 LARK_APP_ID=cli_xxxxx
 LARK_APP_SECRET=your-app-secret
 
-# Security settings (from Lark Developer Console > Events & Callbacks > Encryption Strategy)
+# Security (from Lark Developer Console > Event Subscriptions > Encrypt Strategy)
 LARK_ENCRYPT_KEY=your-encrypt-key          # Optional, for decrypting event payloads
 LARK_VERIFICATION_TOKEN=your-token         # Optional, for verifying request authenticity
 ```
@@ -157,124 +158,36 @@ LARK_VERIFICATION_TOKEN=your-token         # Optional, for verifying request aut
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `appId` | string | - | Lark App ID (required) |
-| `appSecret` | string | - | Lark App Secret (required) |
+| `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 |
+| `webhookPort` | number | `3000` | Webhook server port |
 | `domain` | string | `feishu` | `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) |
+| `encryptKey` | string | - | Encryption key for decrypting event payloads |
+| `verificationToken` | string | - | Token for verifying request authenticity |
 | `dmPolicy` | string | `pairing` | `open`, `pairing`, or `allowlist` |
 | `groupPolicy` | string | `open` | `open`, `allowlist`, or `disabled` |
-| `requireMention` | boolean | `true` | Require @mention in groups (previously `groupMentionGated`) |
+| `requireMention` | boolean | `true` | Whether mentions are required in groups |
 | `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) 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
-
-1. Start ngrok to expose your local webhook server:
-
-```bash
-ngrok http 3000
-```
-
-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'
-```
+| `mediaMaxMb` | number | `30` | Max size for media files (MB) |
+| `historyLimit` | number | `10` | Number of history messages to fetch |
 
 ## 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.
+### "Invalid config ... plugin not found: lark"
 
-## License
+If you see this error after upgrading/renaming the plugin:
+`Invalid config at .../openclaw.json: - plugins.entries.lark: plugin not found: lark`
 
-MIT
+This happens because the old plugin ID `lark` is still in your configuration but the plugin files are gone or renamed.
 
+**Fix:**
+1. Open `~/.openclaw/openclaw.json` (or your config file)
+2. Remove the line `"lark": "lark"` or `"lark": "..."` from `plugins.entries`
+3. Save the file
+4. Re-install the plugin using the new name:
+   ```bash
+   openclaw plugins install @xwang152/claw-lark
+   # or for manual install
+   openclaw plugins install --link .
+   ```

package/README_zh.md

@@ -1,3 +1,4 @@
+
 # OpenClaw 飞书/Lark 插件
 
 [English Document](./README.md)
@@ -177,6 +178,26 @@ LARK_VERIFICATION_TOKEN=your-token         # 可选，用于验证请求真实
 | **raw** | 始终使用纯文本渲染；表格会被转换为 ASCII 文本 |
 | **card** | 始终使用飞书交互式卡片渲染；支持 Markdown 语法高亮和高级布局 |
 
+## 常见问题 / 迁移指南
+
+### "Invalid config ... plugin not found: lark"
+
+如果您在升级或重命名插件后看到此错误：
+`Invalid config at .../openclaw.json: - plugins.entries.lark: plugin not found: lark`
+
+这是因为旧的插件 ID `lark` 仍然存在于您的配置中，但插件文件已被移除或重命名。
+
+**解决方法：**
+1. 打开 `~/.openclaw/openclaw.json` (或您的配置文件)
+2. 找到 `plugins.entries`，删除 `"lark": "lark"` 或类似行
+3. 保存文件
+4. 使用新名称重新安装插件：
+   ```bash
+   openclaw plugins install @xwang152/claw-lark
+   # 或者手动安装
+   openclaw plugins install --link .
+   ```
+
 ## Webhook 模式指引
 
 根据您的部署环境选择设置方法。
@@ -197,106 +218,14 @@ LARK_VERIFICATION_TOKEN=your-token         # 可选，用于验证请求真实
 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 .
-```
-
-### 常用命令
+2. 复制生成的 HTTPS URL（例如 `https://xxxx-xx-xx-xx-xx.ngrok-free.app`）
 
-- `npm run lint`: 代码风格检查
-- `npm run format`: 自动格式化代码
-- `npm test`: 运行测试
+3. 在飞书开发者后台中配置：
+   - 转到 **事件订阅**
+   - 将 **请求地址** 设置为您的 ngrok URL + `/webhook`
+     - 例如：`https://xxxx-xx-xx-xx-xx.ngrok-free.app/webhook`
 
-## 许可证
+### 2. 生产环境 (Docker/服务器)
 
-MIT
+1. 确保服务器的 3000 端口（或配置的端口）对外开放
+2. 在飞书开发者后台中，将 **请求地址** 设置为您的服务器公网 IP/域名 + `/webhook`

package/package.json

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