sugarforever/add-feishu

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 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)