OpenClaw Feishu Config Can Break Before the Official Plugin Even Loads

A newly reported OpenClaw regression can make a correct Feishu configuration look invalid at startup.

The core problem is not that the official Feishu plugin lacks support. The problem is that OpenClaw core validates your config against a bundled Feishu schema first, and that schema reportedly does not include several fields already supported by the official @larksuite/openclaw-lark plugin.

So teams can follow the official plugin docs, add those fields, and still get blocked before the plugin is even loaded.

Source:

• Issue report: openclaw/openclaw#57173

What the failure looks like

According to the report, this affects setups like:

• OpenClaw Core: 2026.3.28
• Official Feishu plugin: @larksuite/openclaw-lark 2026.3.26
• OS: macOS / Linux

A typical reproduction flow is:

1. Install the official plugin
2. Configure advanced Feishu options from the official docs
3. Start the Gateway
4. Hit a schema-validation error such as:

channels.feishu: invalid config: must NOT have additional properties

That means the failure happens during Gateway startup validation, not later at message-send time.

Which fields are reportedly rejected

The issue specifically calls out fields supported by the official plugin but missing from the bundled schema, including:

• footer
• replyMode
• threadSession
• dedup
• useStreamingCards
• configWrites
• capabilities
• uat

If your config includes one of those and your Gateway starts failing immediately, you may be hitting this exact mismatch.

Why this matters operationally

This is more than a cosmetic docs mismatch.

For teams using Feishu as an agent control surface, the blocked fields are often the ones that make the channel usable in production:

• replyMode affects how responses stream or land in chat
• threadSession affects whether conversations stay separated cleanly
• footer can expose execution status or elapsed time for debugging
• dedup and related switches can affect noisy or repeated delivery patterns

In short: your Feishu channel may not fail gracefully. It may fail at the point where the Gateway refuses to boot with the config you actually need.

The key diagnosis: schema mismatch, not plugin absence

The most important takeaway from the report is this:

Disabling the bundled plugin entry or loading the official plugin from plugins.load.paths does not solve the startup validation step.

Why? Because the bundled schema is checked before the official plugin takes over.

So if you were assuming:

• “I installed the official plugin, so its schema should apply”
• “I disabled the built-in entry, so the core should stop checking it”

…that assumption may be wrong for this version.

How to confirm you hit this exact problem

You are likely hitting the same issue if all three are true:

1. You followed the official Feishu plugin docs
2. You added advanced fields such as footer, replyMode, or threadSession
3. The Gateway fails immediately at startup with an “additional properties” validation error

That pattern is much more specific than a generic Feishu outage.

Who is most affected by this Feishu schema mismatch

This issue is especially painful for three groups:

• Teams migrating from the bundled Feishu path to the official plugin, because they are most likely to trust the official docs and ship a config block that never boots.
• Operators relying on advanced Feishu delivery behavior in production, because fields like replyMode, threadSession, and footer are usually added for operational clarity, not experimentation.
• Anyone rolling config changes directly into a shared Gateway, because a startup-time schema rejection can block the whole channel before any runtime fallback exists.

Practical workarounds right now

1) Remove unsupported advanced fields and keep only the bundled-schema-safe subset

The issue report suggests a reduced config shape like:

{
  "channels": {
    "feishu": {
      "streaming": true,
      "chunkMode": "newline",
      "typingIndicator": true,
      "replyInThread": "enabled"
    }
  }
}

This is not feature-complete, but it can help you get the Gateway booting again.

2) Treat the official docs and your local core version as separate compatibility layers

Before rolling a Feishu config change into production, verify both of these:

• the official plugin docs say the field exists
• your current OpenClaw core version accepts that field at startup

If either side is out of sync, a clean-looking config can still fail.

3) Avoid bundling multiple Feishu config changes into one rollout

If you are debugging a failing startup, add Feishu fields incrementally instead of pasting a fully featured block all at once. That makes it much easier to identify the first field rejected by startup validation.

What maintainers likely need to fix

The issue proposes three directions:

• Sync the bundled schema with the official plugin
• Deprecate the bundled Feishu plugin path and rely fully on the official plugin
• Load the official plugin schema dynamically when it is present

From an operator perspective, the first priority is simple: the schema checked at startup must not reject fields that the official plugin is supposed to support.

Common rollout questions

When should you stop debugging the plugin install and suspect core schema first

If the official plugin is installed correctly, the Gateway fails immediately at startup, and the error specifically says must NOT have additional properties, the faster hypothesis is usually schema mismatch, not a broken plugin install.

What is the lowest-risk way to restore Feishu service while keeping evidence for later

Roll back to the smallest Feishu config that the current core accepts, get the Gateway booting again, and save the rejected advanced block plus the startup error for follow-up. That contains the blast radius without losing the exact incompatibility evidence.

Which teams should turn this incident into a standing preflight check

Any team that treats Feishu as a production control surface should promote this from a one-off bug to a release checklist item. If you regularly change channels.feishu, rotate plugin versions, or maintain separate staging and production Gateways, add a preflight step that validates the config against the exact core build you are deploying.

What should you compare first when only one environment breaks

Start with the boring but decisive checks: OpenClaw core version, official plugin version, deployment image tag, and whether the environment is still loading a cached plugin package. In this failure pattern, version drift usually explains the “works in staging, fails in prod” split faster than message-level debugging does.

What should you test before re-adding all Feishu fields after a rollback

Do not treat “Gateway boots again” as proof that the underlying compatibility problem is gone. After a rollback, re-add Feishu fields in a strict order and restart each time:

1. add one display-only field such as footer
2. add one reply-behavior field such as replyMode
3. add one session-shaping field such as threadSession
4. keep a copy of the exact startup error after each restart

That sequence gives you a cleaner blame line and usually produces a much more actionable incident note than restoring the whole advanced block at once.

Which operator mistake makes this incident look like a random deploy failure

The most common trap is bundling a Feishu config change together with a Core upgrade, plugin upgrade, and deployment image refresh in one release. When all four move together, the startup rejection looks like a vague deploy failure instead of a schema compatibility break. Split those changes whenever possible.

What to capture if you escalate this internally

If you are filing a follow-up or reporting it to your team, keep these details together:

• OpenClaw core version
• official plugin version
• exact channels.feishu block
• full startup validation error
• whether the Gateway starts again after removing advanced fields

That will help separate this schema mismatch from unrelated Feishu runtime bugs.

Bottom line

If your Feishu setup suddenly fails after you add documented advanced options, do not assume you misconfigured the official plugin.

On OpenClaw 2026.3.28, the faster explanation may be a core schema mismatch that rejects valid official-plugin fields before runtime even begins.

Who is most likely to hit this schema mismatch

This issue shows up most often when a team mixes an updated OpenClaw core with an older community or official Feishu plugin build, or when a staging environment and a production environment are not actually running the same plugin revision. If the error appears only in one environment, version drift is one of the first things to verify.

What should you check before blaming the whole Feishu integration

Before you conclude that the entire Feishu channel is broken, check these items first:

• whether OpenClaw core and the Feishu plugin were upgraded together
• whether the environment is still loading an older plugin package from cache or a stale deployment image
• whether the payload shape changed in the current release notes or upgrade guide
• whether the same action still works in a different environment with aligned versions

These checks usually tell you faster whether the problem is a compatibility mismatch, a stale deploy, or a broader integration failure.

A fast preflight checklist before you touch production Feishu config

If this page is catching search traffic, many readers are likely in the exact moment before a risky rollout. Give them a short preflight checklist:

1. confirm the exact OpenClaw core version on the target Gateway
2. confirm the exact @larksuite/openclaw-lark version installed there
3. compare the target channels.feishu block with the last known bootable config
4. add only one advanced field at a time and restart after each change
5. save the full startup validation error before making the next edit

This checklist matters because it turns a vague "Feishu broke after upgrade" incident into a narrow compatibility test with a clean evidence trail.

Search-intent takeaway for operators looking for feishu additional properties

If an operator lands here from a query like feishu additional properties startup, the main decision tree should be simple:

• fails before Gateway startup completes: suspect schema mismatch first
• boots but cannot send messages later: suspect auth, permissions, or runtime delivery next
• only one environment fails: suspect version drift or stale deploy artifacts before blaming the whole integration

That framing matches how production incidents are usually triaged and makes this page more useful as a search entry point, not just a postmortem summary.

What to test before you reapply the rejected Feishu fields

Once the Gateway is stable again, do not paste the full advanced block back in one shot. Reapply the rejected fields in a narrow order so you can isolate the first startup-breaking property.

A low-risk sequence is:

1. add one visibility-oriented field such as footer
2. restart the Gateway and confirm startup succeeds
3. add one conversation-shaping field such as replyMode or threadSession
4. restart again and capture whether the error returns
5. only then add deduplication or capability-related switches

This gives you a cleaner compatibility matrix for your exact core build instead of a vague “Feishu config broke again” conclusion.

Fast release checklist for teams that manage multiple Gateways

If you operate separate staging, canary, and production Gateways, this bug is a good reason to turn Feishu config rollout into a tiny release checklist:

• record the exact OpenClaw core version
• record the exact @larksuite/openclaw-lark version
• diff the channels.feishu block between environments
• restart one non-critical Gateway first
• keep the last known good minimal config ready for immediate rollback

That checklist is boring, but it is exactly what reduces downtime when schema-level incompatibilities slip into a release.

Fast compatibility matrix you can build during the incident

If you need to shorten repeat outages, do not stop at “field X broke startup.” Build a tiny compatibility matrix for the exact build you run in production:

Field	Needed for	Startup accepted?	Notes
footer	visible execution/debug context	yes / no	usually the safest first re-test
replyMode	reply rendering behavior	yes / no	often the first production-critical switch
threadSession	thread/session isolation	yes / no	useful when Feishu is a true control plane
dedup	duplicate/noise control	yes / no	re-test only after core reply behavior is stable
capabilities	plugin feature exposure	yes / no	worth checking after basic delivery works

That table becomes more useful than a one-off startup error because it tells the next operator exactly which fields are safe on the current core build.

FAQ for production Feishu rollouts

Why is this bug easy to misread as a bad plugin install instead of a schema mismatch?

Because the failure happens so early that teams often assume the plugin never installed correctly. But in this pattern, the plugin may be fine, and the real break is earlier: core startup validation rejects the config shape before the official plugin can even take over.

That is why the same field can look “documented and valid” in plugin docs yet still crash Gateway startup on a mismatched core build.

What is the safest evidence bundle to keep before you strip fields for recovery?

Before deleting advanced Feishu fields just to get the Gateway back up, save a minimal evidence bundle:

• the exact channels.feishu block that failed
• the full startup validation error
• core version and official plugin version
• whether another environment accepts the same block

That bundle is usually enough to reopen the compatibility question later without re-breaking production just to re-prove it.

When should you stop treating this as a message-delivery bug and move the check earlier?

If the Gateway never finishes booting, stop spending time on downstream delivery behavior. At that point, replyMode, thread rendering, and card behavior are not the first problem. The first problem is whether startup validation accepts the config at all.

For on-call teams, that shift matters because it changes the recovery path from chat-debugging to config-shape isolation and version comparison.

Search-intent FAQ

Why does Feishu config fail even when the official plugin docs show the field as valid

Because the failure can happen before the official plugin schema is allowed to govern the config. In this regression pattern, OpenClaw core validates channels.feishu against its bundled schema first, so documented plugin fields can still be rejected during startup.

Which Feishu field should you re-test first after you recover service

Start with footer or another display-oriented field. If that passes, move to replyMode, then threadSession. That order gives you a cleaner signal than restoring all advanced properties at once.

Is this more likely a bad Feishu token or a schema mismatch

If the Gateway fails at startup with must NOT have additional properties, that points much more strongly to schema mismatch than to token/auth trouble. Token problems usually appear after startup, when the channel is already trying to connect or send.

How do you keep Feishu online while still gathering evidence for a maintainer fix

Run the smallest config block that boots, then re-add one advanced field per restart and save each exact validation error. That gives you both service recovery and a precise repro trail.

Search-intent comparison: schema mismatch vs other Feishu failures

When Feishu breaks during an OpenClaw rollout, operators often waste time debugging the wrong layer first. A quick comparison helps:

Symptom	More likely cause	First thing to check
Gateway fails before it finishes booting	startup schema mismatch	remove footer, replyMode, threadSession and restart
Gateway boots, but messages fail later	token, permissions, or runtime delivery issue	channel auth, bot scopes, and send logs
/stop or /new is accepted, but the active task keeps running	command interrupt / session control bug	whether the current Feishu command path actually interrupts the run
ACP run finished, but history looks empty	transcript projection lag	whether the .jsonl transcript exists on disk

That distinction matters because this issue is primarily a boot-time validation failure, not a generic Feishu integration outage.

What should you document for the next operator on call

If this incident hit production once, leave behind a short operator note instead of relying on memory. The most useful note usually includes:

• the exact OpenClaw core version that rejected the config
• the exact Feishu plugin version that was installed
• the last known good minimal channels.feishu block
• the first field that reintroduced the startup failure
• the exact validation message from the failed restart

That tiny handoff note reduces repeat downtime much more than a vague comment like "Feishu was flaky after upgrade."

Minimal reproduction bundle before you change the schema

Before you loosen validation or delete Feishu fields in production, package a small reproduction bundle that lets another operator prove the same boundary:

1. Rejected field list: copy the exact additional properties keys and the plugin version that rejected them.
2. Gateway startup log: keep the first startup failure, not only the later successful boot after fields were removed.
3. Clean config sample: save a redacted config that removes secrets but preserves the failing Feishu block shape.
4. Official plugin expectation: note whether the field came from official Feishu docs, an older OpenClaw example, or a local override.
5. Rollback decision: state whether you temporarily removed fields, pinned a version, or disabled the Feishu channel while waiting for a schema fix.

That bundle turns a vague "Feishu plugin does not start" report into a schema compatibility issue that maintainers and operators can route quickly.

If troubleshooting traffic lands here, separate schema rejection from Feishu plugin failure

GA4 now places this page beside setup and agent troubleshooting entries, so readers may arrive before they know whether Feishu itself failed or OpenClaw rejected the configuration earlier.

Before editing tokens or reinstalling the plugin, split the incident into three checks:

1. The process fails before plugin load: treat it as a core schema compatibility issue and capture the rejected config path, schema error, and OpenClaw version.
2. The plugin loads but Feishu auth fails: keep the app id, redirect/callback setup, and permission scope evidence separate from the schema report.
3. Only one environment breaks: compare the exact config file, plugin package version, and runtime channel so the fix targets validation drift rather than Feishu API behavior.

This keeps high-intent setup readers from rotating Feishu credentials when the blocker is actually local schema validation.

Fifteen-minute hotfix path: restore Gateway first, keep schema evidence

If this is a production Feishu channel, do not change tokens, scopes, bot permissions, and schema at the same time. Keep the recovery loop tight:

1. Copy the failing config block: save a redacted channels.feishu block first, especially rejected fields such as footer, replyMode, and threadSession.
2. Boot with the smallest field removal: remove only the fields rejected by schema validation so Gateway can start; do not reconfigure the Feishu app at the same time.
3. Confirm the channel can still receive and send: send one minimal message so Feishu delivery is tested separately from the schema hotfix.
4. Lock the change window: record that this was a temporary schema-compatibility hotfix, not the final plugin configuration decision.
5. Queue the upstream fix: hand maintainers the Core version, plugin version, and rejected fields together so the next upgrade does not reintroduce the same fields blindly.

This hotfix path helps readers who already found the additional properties error but need to restore the Feishu entrypoint first. Recover first, preserve evidence, and avoid turning one schema mismatch into hours of credential debugging.

Before the upgrade window, add this Feishu schema release gate

If the team is about to upgrade OpenClaw or the official Feishu plugin, do not wait until the Gateway fails to boot. Add a small release gate before the maintenance window:

1. List the production fields: inventory the actual channels.feishu keys and flag high-risk fields such as footer, replyMode, and threadSession.
2. Dry-run startup on the target version: load the same redacted config in a non-production environment and confirm whether schema validation rejects it first.
3. Prepare a minimal bootable config: keep a Feishu block with only required fields as the fast rollback point during the window.
4. Delay token and scope debugging: only investigate Feishu credentials, permissions, and message delivery after the Gateway passes schema validation.
5. Write the go-live rule: expand to the production channel only after dry-run startup passes, the minimal fallback config is available, and send/receive checks work.

This gate moves the risk of “Feishu broke after upgrade” ahead of the maintenance window and gives high-intent operators a repeatable way to prevent the next outage.

After recovery, turn the incident into a durable Feishu compatibility note

Once the Gateway is booting again, do not let the incident end as a private chat thread. Convert the recovery into a short compatibility note that future operators can find from search:

1. Record the exact rejected fields: keep footer, replyMode, threadSession, or any local-only fields in one list with the Core and plugin versions.
2. Name the working fallback: document the smallest Feishu config that booted successfully so the next maintainer has a known-safe baseline.
3. Separate credential status: state whether Feishu tokens, app permissions, and callback setup were unchanged, so later readers do not repeat credential rotation.
4. Link the upstream issue or release note: when the schema catches up, the note should tell operators whether to reapply fields, pin versions, or keep the fallback.

That post-incident note turns one production outage into a reusable search entry for the next feishu additional properties operator.

Preflight schema checks before loading the Feishu plugin

If you found this page after searching for “Feishu plugin will not load” or “OpenClaw schema rejects Feishu config,” do not start by reinstalling the plugin. First prove whether the failure happens in core config validation or inside the official Feishu integration:

1. Validate the root config shape: confirm plugins.entries uses the structure expected by the current OpenClaw core version before any Feishu-specific field is inspected.
2. Isolate one Feishu entry: temporarily compare a minimal known-good Feishu entry with the failing entry so extra keys do not hide the first schema error.
3. Record the rejection layer: keep the exact error text and whether it is thrown before plugin initialization, during credential loading, or during the first Feishu API call.
4. Only then rotate credentials: if the core schema rejects the config before the plugin loads, replacing app id, app secret, or tenant credentials will not change the failure.

This preflight turns broad Feishu setup traffic into a faster answer: schema mismatch first, credential outage second, plugin runtime bug last.

Related reading

• OpenClaw Feishu Bug: /stop and /new May Not Interrupt a Running Session
• OpenClaw ACP One-Shot Run Looks Empty in sessions_history (Even When .jsonl Transcript Exists)
• Troubleshooting OpenClaw Agents: What to Check When Tasks Stall or Tools Misbehave
• OpenClaw Complete Installation Guide: From Environment Setup to First Successful Run
• OpenClaw Quick Install Guide for Mac
• Top 5 OpenClaw Skills in 2026: Where Automation Pays Off Fastest

If you are triaging multiple chat-surface failures at once

Operators often discover this schema problem in the same maintenance window as other control-surface bugs, especially when they are validating a new Feishu rollout and an ACP workflow at the same time. To keep the incident narrow, separate the checks into three buckets:

• startup schema rejection: the Gateway never boots after adding fields like replyMode or threadSession
• command interrupt failure: Feishu accepts /stop or /new, but the active run continues anyway
• session history projection lag: ACP one-shot runs finish, but sessions_history briefly looks empty even though the transcript file exists

Those three failures can feel related because they all make the control plane look unreliable. But they happen at different layers, and separating them early usually shortens time-to-recovery.

FAQ for search and startup-schema triage

If the Gateway fails at startup with must NOT have additional properties, what should operators assume first?

They should not start with token, permission, or message-delivery debugging.

The safer first assumption is boot-time schema incompatibility, because this error appears before the system even reaches the real Feishu connection or send path.

When should teams suspect version drift between Core and the official plugin before blaming config typos?

If the config follows the official plugin docs, the same field set boots in another environment, and only one environment gets rejected during startup, then version drift deserves priority.

Start by checking:

1. whether the Core version differs
2. whether the official plugin version differs
3. whether the environment is still loading an older cached plugin package or deployment image

That split is often a much better explanation than a random config typo.

If someone searches for feishu additional properties startup, what are the first three branches this page should help them split?

Help them separate these first:

1. whether the failure happens before startup completes or only later during message delivery
2. whether every environment breaks or only one environment breaks
3. whether removing footer, replyMode, and threadSession allows the Gateway to boot again

Those three checks are the fastest route from “the whole Feishu integration is broken” to “this Core build rejects official-plugin fields during startup validation”.

Search-entry triage: what to check first when schema compatibility breaks

If you landed here from searches like “Feishu plugin schema incompatible”, “official Feishu plugin will not load”, or “OpenClaw core schema mismatch”, do not start by editing plugin code. Use this order first:

1. Check the core version: verify whether the OpenClaw core build already supports the schema version required by the plugin.
2. Check the plugin source: separate the official plugin, an older fork, and an internal modified copy so a fork issue does not look like an upstream regression.
3. Check the failure layer: if registration fails, inspect schema compatibility first; if tool execution fails later, inspect permissions, tokens, and Feishu API behavior.
4. Check whether pinning is safer: in production, pinning to a known-good core/plugin pair is usually safer than changing schema definitions during an on-call window.

The common time sink is misreading a load-time schema mismatch as a Feishu authorization failure. A schema mismatch usually blocks the plugin before runtime. Authorization failures surface later, when a real API call is attempted.

Related reading

• Troubleshooting OpenClaw Agents: What to Check When Tasks Stall or Tools Misbehave
• OpenClaw Update Guide (2026-02-02): What to Check Before and After You Upgrade
• OpenClaw Complete Installation Guide: From Local Setup to Maintainable Deployment
• What to Check First When the Feishu Plugin Cannot Get a Token

Exact searches this Feishu schema bug page should answer next

Use this section when the operator is not asking about Feishu permissions, but about a plugin that worked before and now fails because the OpenClaw core schema no longer matches the official Feishu plugin contract.

• OpenClaw Feishu plugin schema incompatible: compare the core schema version loaded by the gateway with the official Feishu plugin version before changing document permissions.
• official Feishu plugin fails after OpenClaw core update: pin the last working core/plugin pair, then test one read-only doc operation before re-enabling write actions.
• Feishu plugin validation error after upgrade: preserve the exact schema validation message, plugin package version, and gateway startup log so maintainers can separate schema drift from auth failure.

Compatibility triage before changing Feishu plugin code

If this page matches your search because a Feishu plugin stops loading after an OpenClaw core upgrade, avoid editing the plugin first. Prove the mismatch layer in this order:

1. capture the OpenClaw core version and the exact Feishu plugin package or commit;
2. compare the plugin manifest/schema fields against the runtime error, not only against TypeScript types;
3. test the same plugin in a clean workspace so stale generated files do not hide the real incompatibility;
4. pin either core or plugin version before attempting a schema migration;
5. keep the failing payload and the successful payload side by side for the upstream issue.

This checklist targets searches like “OpenClaw Feishu plugin schema incompatible” and “Feishu plugin fails to load after OpenClaw upgrade”. It helps operators separate a real SDK contract change from local cache, stale build output, or an accidental mixed-version deployment.

Source

• openclaw/openclaw#57173