Feishu bot setup wizard and durable inbound event handling

Use the channel setup wizard, then read on to learn how OpenClaw accepts inbound Feishu events durably.

Quick start

Note

OpenClaw 2026.5.29 or newer is required. To verify, run openclaw --version. To upgrade, use openclaw update.

Run the channel setup wizard

openclaw channels login --channel feishu

The @openclaw/feishu plugin gets installed by this command when absent, and setup then proceeds interactively:

• Manual setup: supply an App ID and App Secret taken from Feishu Open Platform (https://open.feishu.cn) or Lark Developer (https://open.larksuite.com).
• QR setup: create a bot automatically by scanning a QR code inside the Feishu app. DMs created this way are restricted to your own account (dmPolicy: "allowlist" with your open_id).

You will also be prompted for the API domain (Feishu or Lark) and the group policy. Should the QR code go unanswered in the domestic Feishu mobile app, run setup again and pick manual setup.

Verify the channel after setup

Configuration updates are applied through hot reload. Verify that Feishu is ready:

openclaw channels status --probe

If the Gateway is offline, start it.

Inbound durability

Before dispatching to the agent, OpenClaw durably queues authenticated im.message.receive_v1 and drive.notice.comment_add_v1 envelopes. Under webhook mode, x-openclaw-delivery-accepted: durable is carried by the durable 200; verification challenges, event types that are not durable, and error responses leave the marker out, which lets reverse proxies require it to tell durable acceptance apart from a generic 200. Events that are pending or retryable survive a Gateway restart, stay serialized per chat or document, and rely on Feishu's event ID to block duplicate queue entries for as long as the active or retained completion record exists.

Where a WebSocket event still cannot be persisted after bounded retries, OpenClaw shuts that socket and forces a new authenticated connection rather than moving past an uncommitted turn. Normal event paths handle other Feishu event types, reactions and VC meeting invitations among them, and these get no durable-queue guarantee.

On account stop, OpenClaw halts admission for the message, menu, card, meeting, and reaction handlers, then waits for accepted handlers and replay-guard writes to settle before account resources are released. The per-chat queue limit of five minutes frees the ordering slot only: the original handler is not cancelled, and account cleanup cannot complete while that handler still runs.

Webhook delivery window

Every webhook delivery is signed by Feishu at send time, so a captured signed callback keeps a valid signature indefinitely. Webhook mode therefore rejects, before the body is parsed, any signed callback whose x-lark-request-timestamp lies more than one hour ahead of or behind the Gateway host's clock. This guards against replay and pairs with the per-message replay guard (a 24-hour window), so a signed callback delivered again cannot re-trigger the same action.

What this means in practice:

• Keep the Gateway host clock synchronized (NTP). Fresh deliveries are rejected once the host clock drifts more than one hour from Feishu's servers.
• Because Feishu signs deliveries when sending them, ordinary redeliveries arrive with fresh timestamps and are unaffected.
• This window does not apply to WebSocket mode.
• No configuration key exists for this window; it is fixed on purpose.