Feishu

このコンテンツはまだ日本語訳がありません。

Feishu bot

Feishu (Lark) is a team chat platform used by companies for messaging and collaboration. This plugin connects CoderClaw to a Feishu/Lark bot using the platform’s WebSocket event subscription so messages can be received without exposing a public webhook URL.

Plugin required

Install the Feishu plugin:

coderclaw plugins install @coderclaw/feishu

Local checkout (when running from a git repo):

coderclaw plugins install ./extensions/feishu

Quickstart

There are two ways to add the Feishu channel:

Method 1: onboarding wizard (recommended)

If you just installed CoderClaw, run the wizard:

coderclaw onboard

The wizard guides you through:

Creating a Feishu app and collecting credentials
Configuring app credentials in CoderClaw
Starting the gateway

✅ After configuration, check gateway status:

coderclaw gateway status
coderclaw logs --follow

Method 2: CLI setup

If you already completed initial install, add the channel via CLI:

coderclaw channels add

Choose Feishu, then enter the App ID and App Secret.

✅ After configuration, manage the gateway:

coderclaw gateway status
coderclaw gateway restart
coderclaw logs --follow

Step 1: Create a Feishu app

1. Open Feishu Open Platform

Visit Feishu Open Platform and sign in.

Lark (global) tenants should use https://open.larksuite.com/app and set domain: "lark" in the Feishu config.

2. Create an app

Click Create enterprise app
Fill in the app name + description
Choose an app icon

Create enterprise app

3. Copy credentials

From Credentials & Basic Info, copy:

App ID (format: cli_xxx)
App Secret

❗ Important: keep the App Secret private.

Get credentials

4. Configure permissions

On Permissions, click Batch import and paste:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

Configure permissions

5. Enable bot capability

In App Capability > Bot:

Enable bot capability
Set the bot name

Enable bot capability

6. Configure event subscription

⚠️ Important: before setting event subscription, make sure:

You already ran coderclaw channels add for Feishu
The gateway is running (coderclaw gateway status)

In Event Subscription:

Choose Use long connection to receive events (WebSocket)
Add the event: im.message.receive_v1

⚠️ If the gateway is not running, the long-connection setup may fail to save.

Configure event subscription

7. Publish the app

Create a version in Version Management & Release
Submit for review and publish
Wait for admin approval (enterprise apps usually auto-approve)

Step 2: Configure CoderClaw

Configure with the wizard (recommended)

coderclaw channels add

Choose Feishu and paste your App ID + App Secret.

Configure via config file

Edit ~/.coderclaw/coderclaw.json:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "My AI assistant",
        },
      },
    },
  },
}

Configure via environment variables

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark (global) domain

If your tenant is on Lark (international), set the domain to lark (or a full domain string). You can set it at channels.feishu.domain or per account (channels.feishu.accounts.<id>.domain).

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

Step 3: Start + test

1. Start the gateway

coderclaw gateway

2. Send a test message

In Feishu, find your bot and send a message.

3. Approve pairing

By default, the bot replies with a pairing code. Approve it:

coderclaw pairing approve feishu <CODE>

After approval, you can chat normally.

Overview

Feishu bot channel: Feishu bot managed by the gateway
Deterministic routing: replies always return to Feishu
Session isolation: DMs share a main session; groups are isolated
WebSocket connection: long connection via Feishu SDK, no public URL needed

Access control

Direct messages

Default: dmPolicy: "pairing" (unknown users get a pairing code)

Approve pairing:

coderclaw pairing list feishu
coderclaw pairing approve feishu <CODE>

Allowlist mode: set channels.feishu.allowFrom with allowed Open IDs

Group chats

1. Group policy (channels.feishu.groupPolicy):

"open" = allow everyone in groups (default)
"allowlist" = only allow groupAllowFrom
"disabled" = disable group messages

2. Mention requirement (channels.feishu.groups.<chat_id>.requireMention):

true = require @mention (default)
false = respond without mentions

Group configuration examples

Allow all groups, require @mention (default)

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // Default requireMention: true
    },
  },
}

Allow all groups, no @mention required

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

Allow specific users in groups only

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

Get group/user IDs

Group IDs (chat_id)

Group IDs look like oc_xxx.

Method 1 (recommended)

Start the gateway and @mention the bot in the group
Run coderclaw logs --follow and look for chat_id

Method 2

Use the Feishu API debugger to list group chats.

User IDs (open_id)

User IDs look like ou_xxx.

Method 1 (recommended)

Start the gateway and DM the bot
Run coderclaw logs --follow and look for open_id

Method 2

Check pairing requests for user Open IDs:

coderclaw pairing list feishu

Common commands

Command	Description
`/status`	Show bot status
`/reset`	Reset the session
`/model`	Show/switch model

Note: Feishu does not support native command menus yet, so commands must be sent as text.

Gateway management commands

Command	Description
`coderclaw gateway status`	Show gateway status
`coderclaw gateway install`	Install/start gateway service
`coderclaw gateway stop`	Stop gateway service
`coderclaw gateway restart`	Restart gateway service
`coderclaw logs --follow`	Tail gateway logs

Troubleshooting

Bot does not respond in group chats

Ensure the bot is added to the group
Ensure you @mention the bot (default behavior)
Check groupPolicy is not set to "disabled"
Check logs: coderclaw logs --follow

Bot does not receive messages

Ensure the app is published and approved
Ensure event subscription includes im.message.receive_v1
Ensure long connection is enabled
Ensure app permissions are complete
Ensure the gateway is running: coderclaw gateway status
Check logs: coderclaw logs --follow

App Secret leak

Reset the App Secret in Feishu Open Platform
Update the App Secret in your config
Restart the gateway

Message send failures

Ensure the app has im:message:send_as_bot permission
Ensure the app is published
Check logs for detailed errors

Advanced configuration

Multiple accounts

{
  channels: {
    feishu: {
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

Message limits

textChunkLimit: outbound text chunk size (default: 2000 chars)
mediaMaxMb: media upload/download limit (default: 30MB)

Streaming

Feishu supports streaming replies via interactive cards. When enabled, the bot updates a card as it generates text.

{
  channels: {
    feishu: {
      streaming: true, // enable streaming card output (default true)
      blockStreaming: true, // enable block-level streaming (default true)
    },
  },
}

Set streaming: false to wait for the full reply before sending.

Multi-agent routing

Use bindings to route Feishu DMs or groups to different agents.

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "coderclaw-fan",
        workspace: "/home/user/coderclaw-fan",
        agentDir: "/home/user/.coderclaw/agents/coderclaw-fan/agent",
      },
      {
        id: "coderclaw-xi",
        workspace: "/home/user/coderclaw-xi",
        agentDir: "/home/user/.coderclaw/agents/coderclaw-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "coderclaw-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "coderclaw-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

Routing fields:

match.channel: "feishu"
match.peer.kind: "direct" or "group"
match.peer.id: user Open ID (ou_xxx) or group ID (oc_xxx)

See Get group/user IDs for lookup tips.

Configuration reference

Full configuration: Gateway configuration

Key options:

Setting	Description	Default
`channels.feishu.enabled`	Enable/disable channel	`true`
`channels.feishu.domain`	API domain (`feishu` or `lark`)	`feishu`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	Per-account API domain override	`feishu`
`channels.feishu.dmPolicy`	DM policy	`pairing`
`channels.feishu.allowFrom`	DM allowlist (open_id list)	-
`channels.feishu.groupPolicy`	Group policy	`open`
`channels.feishu.groupAllowFrom`	Group allowlist	-
`channels.feishu.groups.<chat_id>.requireMention`	Require @mention	`true`
`channels.feishu.groups.<chat_id>.enabled`	Enable group	`true`
`channels.feishu.textChunkLimit`	Message chunk size	`2000`
`channels.feishu.mediaMaxMb`	Media size limit	`30`
`channels.feishu.streaming`	Enable streaming card output	`true`
`channels.feishu.blockStreaming`	Enable block streaming	`true`

dmPolicy reference

Value	Behavior
`"pairing"`	Default. Unknown users get a pairing code; must be approved
`"allowlist"`	Only users in `allowFrom` can chat
`"open"`	Allow all users (requires `"*"` in allowFrom)
`"disabled"`	Disable DMs

Supported message types

Receive

✅ Text
✅ Rich text (post)
✅ Images
✅ Files
✅ Audio
✅ Video
✅ Stickers

Send

✅ Text
✅ Images
✅ Files
✅ Audio
⚠️ Rich text (partial support)