Lark Plugin for OpenClaw

中文文档

A channel plugin that enables OpenClaw to communicate via Lark (Larksuite) messaging platform.

Features

- 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
- Message Reactions: Add and remove emoji reactions to messages
- Multi-mode Rendering: Support for auto, raw, and card modes
- Document Operations: Create, read, write, and manage Lark documents with Markdown support
- Directory Integration: List users and groups from Lark address book
- 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

$3

Install directly via OpenClaw CLI:

``bash
openclaw plugins install @xwang152/claw-lark
`

$3

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

After installation, restart the Gateway to load the plugin:

`bash
openclaw gateway restart
`

Verify installation:

`bash
openclaw plugins list
`

You should see claw-lark with status loaded.

Upgrade Plugin

$3

`bash
openclaw plugins update @xwang152/claw-lark
openclaw gateway restart
`

$3

`bash
cd claw-lark
git pull
npm install
openclaw gateway restart
`

Lark App Setup

1. Go to Lark Developer Console

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 Message | Send messages as the bot |
| im:resource | Resource | Upload/Download images and files |
| im:message:send_as_bot | Send Message | Send messages as the bot |

Optional Permissions for Advanced Features (Add as needed):

| Permission | Scope | Description |
| :--- | :--- | :--- |
| 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:recall | Recall | Recall sent messages |
| 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) |

Document Permissions (Required for document operations):

| Permission | Scope | Description |
| :--- | :--- | :--- |
| docx:document | Document | Create, read, and update documents |
| docx:document:readonly | Document | Read document content |
| drive:drive:readonly | Drive | Access files and folders |

6. Note down your App ID and App Secret from "Credentials & Basic Info"

6. Publish your app under "Version Management & Release"

Configuration

$3

`bash


Required

openclaw config set channels.lark.accounts.default.appId 'cli_xxxxx'
openclaw config set channels.lark.accounts.default.appSecret 'your-app-secret'

Optional

openclaw config set channels.lark.accounts.default.connectionMode 'websocket'
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'

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'
`

$3

For the default account, you can use environment variables:

`bash
LARK_APP_ID=cli_xxxxx
LARK_APP_SECRET=your-app-secret

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
`

$3

| 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 | Webhook server port |
| domain | string | feishu | lark (international) or feishu (China) |
| 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 | Whether mentions are required in groups |
| renderMode | string | auto | auto, raw, or card |
| mediaMaxMb | number | 30 | Max size for media files (MB) |
| historyLimit | number | 10 | Number of history messages to fetch |

Troubleshooting

$3

If installation fails and leaves a partial folder, you may see this error when trying to reinstall.

Fix:
Manually delete the extension folder:
`bash
rm -rf ~/.openclaw/extensions/claw-lark
`
Then try installing again.

WebSocket Mode Guide (Long Connection)

Recommended for enterprise self-built apps. This mode requires no public IP or firewall port configuration. Data is transmitted via an encrypted tunnel, offering better security and lower latency.

$3

1. OpenClaw Configuration

Set connection mode to websocket (default).

`bash
openclaw config set channels.lark.accounts.default.connectionMode websocket
`

2. Lark Developer Console Configuration

1. Log in to Lark Developer Console and enter your app.
2. Ensure Bot capability is enabled.
3. Go to Event Subscriptions.
4. No need to configure "Request URL".
5. (Optional) Configure Encrypt Key and Verification Token in Encrypt Strategy for enhanced security, and update OpenClaw config accordingly.

Webhook Mode Guide

Choose setup method based on your deployment environment.

$3

Recommended for local development and testing.

> Security & Privacy Warning: ngrok exposes your local server to the internet. Please note:
> - Never share your ngrok URL publicly — anyone with the URL can send requests to your local machine
> - Use paid ngrok plans with authentication or IP restrictions for production
> - Stop ngrok when not in use to close the tunnel
> - Recommended to use Lark's encryptKey and verificationToken for extra request verification

1. Start ngrok to expose local webhook server:

`bash
ngrok http 3000
`

2. Copy the generated HTTPS URL (e.g., https://xxxx-xx-xx-xx-xx.ngrok-free.app)

3. Configure in Lark Developer Console:
- Go to Event Subscriptions
- Set Request URL to your ngrok URL
- Example: https://xxxx-xx-xx-xx-xx.ngrok-free.app`

$3

1. Ensure server port 3000 (or configured port) is open to the internet.
2. In Lark Developer Console, set Request URL to your server public IP/Domain:3000

License

MIT License - See LICENSE file