/add-feishu

name: add-feishu
description: Add Feishu (飞书/Lark) as a channel. Uses WebSocket long connection mode — no public URL needed. Bot responds to all messages (no trigger required).

Add Feishu Channel

This skill adds Feishu (飞书) 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 app already, or do you need to create one?

If they have one, collect `FEISHU_APP_ID` and `FEISHU_APP_SECRET` now. If not, we'll create one 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)

If `.nanoclaw/` directory doesn't exist yet:

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

Apply the skill

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

This deterministically:

• Adds `src/channels/feishu.ts` (FeishuChannel class implementing Channel interface)
• Three-way merges Feishu support into `src/index.ts` (reads credentials via `readEnvFile`, creates FeishuChannel if configured)
• Installs the `@larksuiteoapi/node-sdk` npm dependency
• Updates `.env` 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/index.ts.intent.md` — what changed and invariants for index.ts

Validate code changes

npm run build

Build must be clean before proceeding.

Phase 3: Setup

Create Feishu App (if needed)

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

> I need you to create a Feishu bot: > > 1. Go to [Feishu Open Platform](https://open.feishu.cn/app) and create a new app > 2. Under **Credentials**, copy the **App ID** and **App Secret** > 3. Under **Event Subscriptions**, enable **Long Connection (WebSocket)** mode > 4. Add the event: `im.message.receive_v1` (Receive messages) > 5. Under **Permissions**, add: > - `im:message:send_as_bot` (Send messages as bot) > - `im:message` (Read messages) > 6. **Publish** the app (or create a version and approve it)

Wait for the user to provide the App ID and App Secret.

Configure environment

Add to `.env`:

FEISHU_APP_ID=<their-app-id>
FEISHU_APP_SECRET=<their-app-secret>

Build and restart

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:

> 1. Start the bot: `npm run dev` > 2. Send any message to the bot in Feishu (DM or group) > 3. Check the logs — the chat_id will appear in the metadata > 4. The JID format is `{chat_id}@feishu`

Or check the database directly:

sqlite3 store/messages.db "SELECT jid FROM chats WHERE jid LIKE '%@feishu'"

Register the chat

Register directly in SQLite:

INSERT INTO registered_groups (jid, name, folder, trigger_pattern, added_at, requires_trigger)
VALUES ('{chat_id}@feishu', 'feishu', 'feishu', '@{ASSISTANT_NAME}', datetime('now'), 0);

Note: `requires_trigger` is set to `0` (false) so the bot responds to all messages without needing @mention.

Then restart the service to pick up the new registration.

Phase 5: Verify

Test the connection

Tell the user:

> Send a message to the bot in Feishu. It should respond within a few seconds.

Check logs if needed

tail -f logs/nanoclaw.log
# Or run interactively:
npm run dev

Look for:

• `Feishu bot info fetched` — bot connected and identified itself
• `Connected to Feishu via WebSocket` — WebSocket established
• `Feishu message sent` — outbound message delivered

Troubleshooting

Bot not responding

Check: 1. `FEISHU_APP_ID` and `FEISHU_APP_SECRET` are set in `.env` 2. Chat is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE '%@feishu'"` 3. App is published on Feishu Open Platform (draft apps don't receive events) 4. Event subscription `im.message.receive_v1` is enabled 5. Long Connection (WebSocket) mode is enabled (not webhook) 6. Service is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux)

Bot connects but doesn't receive messages

• Verify the app has `im:message` permission
• Verify the event `im.message.receive_v1` is subscribed
• Check that the app version is published and approved

Bot receives but can't send

• Verify the app has `im:message:send_as_bot` permission
• For group chats: the bot must be added to the group first

"Failed to fetch Feishu bot info"

Non-critical warning. Bot message detection (filtering own messages) won't work, but message sending/receiving still functions. Usually means the bot API endpoint isn't accessible — check network connectivity.

Removal

To remove Feishu integration:

1. Delete `src/channels/feishu.ts` 2. Remove `FeishuChannel` import and creation block from `src/index.ts` 3. Remove `readEnvFile` import if no other channel uses it 4. Remove `FEISHU_APP_ID` and `FEISHU_APP_SECRET` from `.env` 5. Remove Feishu registrations: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@feishu'"` 6. Uninstall: `npm uninstall @larksuiteoapi/node-sdk` 7. Rebuild: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)