Feishu

​

Quick start

openclaw channels login --channel feishu

openclaw gateway restart

​

Access control

​

Direct messages

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

​

Group chats

• Default: @mention required, except when the effective group policy is "open"; there it defaults to false so messages that cannot carry mentions (for example images) still reach the agent.
• Set true or false explicitly to override; per-group override: channels.feishu.groups.<chat_id>.requireMention.
• Broadcast-only @all and @_all are not treated as bot mentions. A message that mentions both @all and the bot directly still counts as a bot mention.

​

Group configuration examples

​

Allow all groups, no @mention required

{
  channels: {
    feishu: {
      groupPolicy: "open", // requireMention defaults to false under "open"
    },
  },
}

​

Allow all groups, still require @mention

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

​

Allow specific groups only

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Group IDs look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        oc_xxx: {
          requireMention: false,
        },
      },
    },
  },
}

​

Restrict senders within a group

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // User open_ids look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

​

Get group/user IDs

​

Group IDs (chat_id, format: oc_xxx)

​

User IDs (open_id, format: ou_xxx)

openclaw logs --follow

openclaw pairing list feishu

​

Common commands

​

Troubleshooting

​

Bot does not respond in group chats

1. Ensure the bot is added to the group
2. Ensure you @mention the bot (required by default)
3. Verify groupPolicy is not "disabled"
4. Check logs: openclaw logs --follow

​

Bot does not receive messages

1. Ensure the bot is published and approved in Feishu Open Platform / Lark Developer
2. Ensure event subscription includes im.message.receive_v1
3. Ensure persistent connection (WebSocket) is selected
4. Ensure all required permission scopes are granted
5. Ensure the gateway is running: openclaw gateway status
6. Check logs: openclaw logs --follow

​

QR setup does not react in the Feishu mobile app

1. Rerun setup: openclaw channels login --channel feishu
2. Choose manual setup
3. In Feishu Open Platform, create a self-built app and copy its App ID and App Secret
4. Paste those credentials into the setup wizard

​

App Secret leaked

1. Reset the App Secret in Feishu Open Platform / Lark Developer
2. Update the value in your config
3. Restart the gateway: openclaw gateway restart

​

Advanced configuration

​

Multiple accounts

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
          tts: {
            providers: {
              openai: { voice: "shimmer" },
            },
          },
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

​

Message limits

• textChunkLimit - outbound text chunk size (default: 4000 chars)
• chunkMode - "length" (default) splits at the limit; "newline" prefers newline boundaries
• mediaMaxMb - media upload/download limit (default: 30 MB)

​

Streaming

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

​

Quota optimization

• typingIndicator (default true): set false to skip typing reaction calls
• resolveSenderNames (default true): set false to skip sender profile lookups

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
    },
  },
}

​

Group session scope and topic threads

​

Feishu workspace tools

​

ACP sessions

​

Persistent ACP binding

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

​

Spawn ACP from chat

/acp spawn codex --thread here

​

Multi-agent routing

{
  agents: {
    list: [
      { id: "main" },
      { id: "agent-a", workspace: "/home/user/agent-a" },
      { id: "agent-b", workspace: "/home/user/agent-b" },
    ],
  },
  bindings: [
    {
      agentId: "agent-a",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "agent-b",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

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

​

Per-user agent isolation (Dynamic Agent Creation)

• Independent workspace directory
• Separate USER.md / SOUL.md / MEMORY.md
• Private conversation history
• Isolated skills and state

​

Quick setup

{
  channels: {
    feishu: {
      dmPolicy: "open",
      allowFrom: ["*"],
      dynamicAgentCreation: {
        enabled: true,
        workspaceTemplate: "~/.openclaw/workspace-{agentId}",
        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",
      },
    },
  },
  session: {
    // Critical: makes each user's DM their "main session"
    // Automatically loads USER.md / SOUL.md / MEMORY.md
    // For stronger isolation, use "per-channel-peer" instead
    dmScope: "main",
  },
}

​

How it works

1. The channel generates a unique agentId: feishu-{user_open_id} for the default account, or a bounded account-prefixed identity digest for a named account
2. Creates a new workspace at workspaceTemplate path
3. Registers the agent and creates a binding for this user
4. The workspace helper ensures bootstrap files (AGENTS.md, SOUL.md, USER.md, etc.) on first access
5. Routes all future messages from this user to their dedicated agent

​

Configuration options

• {agentId} - the generated agent ID (e.g., feishu-ou_xxxxxx or feishu-support-<identity_digest>)
• {userId} - the sender’s Feishu open_id (e.g., ou_xxxxxx)

​

Session scope

​

Typical multi-user deployment

{
  channels: {
    feishu: {
      appId: "cli_xxx",
      appSecret: "xxx",
      dmPolicy: "open",
      allowFrom: ["*"],
      groupPolicy: "open",
      requireMention: true,
      dynamicAgentCreation: {
        enabled: true,
        workspaceTemplate: "~/.openclaw/workspace-{agentId}",
        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",
      },
    },
  },
  session: {
    // Choose dmScope based on your isolation needs:
    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation
    dmScope: "main",
  },
  bindings: [], // Empty - dynamic agents auto-bind
}

​

Verification

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxx
  workspace: /home/user/.openclaw/workspace-feishu-ou_xxxxxx
  agentDir: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

ls -la ~/.openclaw/workspace-*

​

Notes

• Workspace isolation: Each user gets their own workspace directory and agent instance. Users cannot see each other’s conversation history or files within the normal messaging flow.
• Security boundary: This is a messaging-context isolation mechanism, not a hostile co-tenant security boundary. The agent process and host environment are shared.
• Config writes must stay enabled: Dynamic agent creation writes agents and bindings into the config; it is skipped when channels.feishu.configWrites is false (default: enabled).
• bindings should be empty: Dynamic agents auto-register their own bindings
• Upgrade path: Existing manual bindings continue to work alongside dynamic agents
• session.dmScope is global: This affects all channels, not just Feishu

​

Configuration reference

​

Supported message types

​

Receive

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

​

Send

• ✅ Text
• ✅ Images
• ✅ Files
• ✅ Audio
• ✅ Video/media
• ✅ Interactive cards (including streaming updates)
• ⚠️ Rich text (post-style formatting; doesn’t support full Feishu/Lark authoring capabilities)

​

Threads and replies

• ✅ Inline replies
• ✅ Thread replies
• ✅ Media replies stay thread-aware when replying to a thread message

​

Related

• Channels Overview - all supported channels
• Pairing - DM authentication and pairing flow
• Groups - group chat behavior and mention gating
• Channel Routing - session routing for messages
• Security - access model and hardening