Add Feishu Channel

This skill adds Feishu (飞书/Lark) support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.

Phase 1: Pre-flight

Check if already applied

Read

.nanoclaw/state.yaml

. If

feishu

is in

applied_skills

, skip to Phase 3 (Setup). The code changes are already in place.

Ask the user

Use

AskUserQuestion

to collect configuration:

AskUserQuestion: Do you have a Feishu (Lark) app already created, or do you need to create one?

If they have one, ask for the App ID and App Secret. If not, walk them through creation in Phase 3.

Phase 2: Apply Code Changes

Run the skills engine to apply this skill's code package. The package files are in this directory alongside this SKILL.md.

Initialize skills system (if needed)

.nanoclaw/

directory doesn't exist yet:

bash

npx tsx scripts/apply-skill.ts --init

Apply the skill

bash

npx tsx scripts/apply-skill.ts .claude/skills/add-feishu

This deterministically:

Adds
```
src/channels/feishu.ts
```
(FeishuChannel class with self-registration via
```
registerChannel
```
)
Adds
```
src/channels/feishu.test.ts
```
(unit tests)

Appends

import './feishu.js'

to the channel barrel file

src/channels/index.ts

Installs the
```
@larksuiteoapi/node-sdk
```
npm dependency

Updates

.env.example

with

FEISHU_APP_ID

and

FEISHU_APP_SECRET

Records the application in
```
.nanoclaw/state.yaml
```

If the apply reports merge conflicts, read the intent file:

```
modify/src/channels/index.ts.intent.md
```
— what changed and invariants

Validate code changes

bash

npm test
npm run build

All tests must pass (including the new feishu tests) and build must be clean before proceeding.

Phase 3: Setup

Create Feishu App (if needed)

If the user doesn't have an app, tell them:

I need you to create a Feishu app:
Go to Feishu Open Platform (or Lark Open Platform for international)

Click Create App → Custom App

Fill in app name and description (e.g., "NanoClaw Assistant")

Go to Credentials & Basic Info — copy the App ID and App Secret
Go to Event Subscriptions → Add Events → search and add:
im.message.receive_v1
(Receive messages — v2.0)
Go to Permissions & Scopes → add the following permissions:
im:message
(Send & receive messages)
im:message:send_as_bot
(Send messages as bot)
im:chat
(Read chat info)
im:chat.members:read
(Read chat members)
Go to Bot tab → enable the bot feature

Click Publish / Apply for Release
Note: For enterprise use, your IT admin may need to approve the app.

Wait for the user to provide the App ID (format:

cli_xxxxxxxxxxxxxxxxxx

) and App Secret.

Configure environment

Add to

.env

bash

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here

Channels auto-enable when their credentials are present — no extra configuration needed.

Sync to container environment:

bash

mkdir -p data/env && cp .env data/env/env

The container reads environment from

data/env/env

, not

.env

directly.

Build and restart

bash

npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
# Linux: systemctl --user restart nanoclaw

Phase 4: Registration

Get Chat ID

Tell the user:

To register a Feishu chat with NanoClaw, I need the chat's ID:

For a direct (p2p) chat:
Add the bot to your Feishu contacts

Open a direct message to the bot
Send any message — NanoClaw will log the JID as
fs:p2p:<your_open_id>
Check
logs/nanoclaw.log
for:
Message from unregistered Feishu chat
For a group chat:
Add the bot to the group: Group Settings → Members → Add Bot

Send any message in the group (or @mention the bot)
NanoClaw will log the JID as
fs:oc_<chat_id>
Check
logs/nanoclaw.log
for:
Message from unregistered Feishu chat

Tell user to check the log:

bash

tail -f logs/nanoclaw.log | grep "unregistered Feishu"

Wait for the user to provide the JID (format:

fs:oc_xxxxx

fs:p2p:ou_xxxxx

Register the chat

For a main chat (responds to all messages):

typescript

registerGroup("fs:<chat-id>", {
  name: "<chat-name>",
  folder: "feishu_main",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: false,
  isMain: true,
});

For additional chats (trigger-based, responds only when @mentioned or triggered):

typescript

registerGroup("fs:<chat-id>", {
  name: "<chat-name>",
  folder: "feishu_<group-name>",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: true,
});

Phase 5: Verify

Test the connection

Tell the user:

Send a message to your registered Feishu chat:

For main chat: Any message works

For non-main: @mention the bot or include a question/request keyword

The bot should respond within a few seconds.

Check logs if needed

bash

tail -f logs/nanoclaw.log

Troubleshooting

Bot not receiving messages

Check:

```
im.message.receive_v1
```
event is added in the app's Event Subscriptions
App is published / enabled (enterprise apps need admin approval)
For groups: the bot is added as a member of the group

FEISHU_APP_ID

and

FEISHU_APP_SECRET

are set in

.env

AND synced to

data/env/env

Service is running:

launchctl list | grep nanoclaw

(macOS) or

systemctl --user status nanoclaw

(Linux)

Bot not responding in groups

By default, NanoClaw only responds in groups when:

The bot is @mentioned
The message contains a request keyword (帮, 请, 分析, etc.)
The message ends with ? or ？

To make the bot respond to all messages in a group, register it with

requiresTrigger: false

"Message from unregistered Feishu chat" in logs

This is normal — it means the bot is receiving messages, but the chat isn't registered yet. Follow Phase 4 to register.

Finding the JID

If the log message is hard to find:

bash

sqlite3 store/messages.db "SELECT DISTINCT chat_jid FROM chats WHERE channel = 'feishu'"

App Secret security

The App Secret is sensitive. Store it only in

.env

and

data/env/env

. Do NOT commit these files to version control.

JID Format Reference

Chat type	JID format	Example
Group chat	`fs:oc_<id>`	`fs:oc_4e359893776d45f7cd05d40e3ee10f55`
Direct (p2p)	`fs:p2p:<open_id>`	`fs:p2p:ou_7a66d6bd1baa3e6e3d7b3df9a8c90000`

After Setup

If running

npm run dev

while the service is active:

bash

# macOS:
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
npm run dev
# When done testing:
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
# Linux:
# systemctl --user stop nanoclaw
# npm run dev
# systemctl --user start nanoclaw

Removal

To remove Feishu integration:

Delete

src/channels/feishu.ts

and

src/channels/feishu.test.ts

Remove

import './feishu.js'

from

src/channels/index.ts

Remove
```
FEISHU_APP_ID
```
and
```
FEISHU_APP_SECRET
```
from
```
.env
```

Remove Feishu registrations from SQLite:

sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'fs:%'"

Uninstall:
```
npm uninstall @larksuiteoapi/node-sdk
```

Rebuild:

npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw

(macOS) or

npm run build && systemctl --user restart nanoclaw

(Linux)

add-feishu

NPX Install

Tags

SKILL.md Content

Add Feishu Channel

Phase 1: Pre-flight

Check if already applied

Ask the user

Phase 2: Apply Code Changes

Initialize skills system (if needed)

Apply the skill

Validate code changes

Phase 3: Setup

Create Feishu App (if needed)

Configure environment

Build and restart

Phase 4: Registration

Get Chat ID

Register the chat

Phase 5: Verify

Test the connection

Check logs if needed

Troubleshooting

Bot not receiving messages

Bot not responding in groups

"Message from unregistered Feishu chat" in logs

Finding the JID

App Secret security

JID Format Reference

After Setup

Removal