PR #77151: fix(channels): do not mark optional-with-default fields as required in channel config json schema

• Repository: openclaw/openclaw
• Author: ai-hpc
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77151

Description (problem / solution / changelog)

Summary

• Problem: Pre-existing channel configs (Feishu, Bluebubbles, IRC, Line, Nextcloud Talk, Zalouser) crash the gateway in a restart loop after upgrading to 2026.5.x because the bundled JSON schema marks .optional().default(X) fields as required. Existing configs that omit these defaulted fields fail validation with "must have required property" errors.
• Why it matters: Users on 2026.4.22 with valid Feishu configs hit a ~80x restart loop after upgrading to 2026.5.2; only workaround was downgrading. Affects all six channels listed above.
• What changed: Pass io: 'input' to schema.toJSONSchema() in buildChannelConfigSchema so the generated JSON schema reflects user input requirements (not Zod's output type). Regenerated bundled-channel-config-metadata.generated.ts. Added a regression unit test.
• What did NOT change (scope boundary): No plugin schema changes, no validator changes, no defaults removed — defaults still apply at runtime via Zod's safeParse. Only the JSON schema's required array shrinks to truly mandatory fields.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Integrations
• API / contracts

Linked Issue/PR

• Closes #77116
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Zod 4's toJSONSchema() defaults to io: 'output'. With .optional().default(X), the output type is always X (never undefined), so the converter marks the field as required in the generated JSON schema. The runtime config validator validates user input via Ajv with useDefaults: false against this generated schema, so any pre-existing config that omits a defaulted field is rejected.
• Missing detection / guardrail: buildChannelConfigSchema did not specify io, so it used Zod's default. No test covered the input-vs-output JSON schema distinction.
• Contributing context: Six bundled channels use the .optional().default() pattern (Feishu has 8 such fields, the others have 1-2 each). Issue #77116 surfaced via Feishu because it has the most fields, but the same class of bug exists in Bluebubbles, IRC, Line, Nextcloud Talk, Zalouser.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/channels/plugins/config-schema.test.ts — new test does not mark optional-with-default fields as required (#77116).
• Scenario the test should lock in: A schema with one mandatory field, one .optional().default() field, and one .optional() field generates required: ["mandatory"] only.
• Why this is the smallest reliable guardrail: Asserts the exact required shape that the runtime validator consumes. If a future change reverts to io: 'output' or removes the option, the test fails immediately.
• Existing test that already covers this (if any): None — passes draft-07 compatibility options to toJSONSchema was updated to also assert io: 'input'.

User-visible / Behavior Changes

Pre-existing Feishu/Bluebubbles/IRC/Line/Nextcloud-Talk/Zalouser configs that omit fields like domain, connectionMode, webhookPath, dmPolicy, groupPolicy, reactionNotifications, typingIndicator, resolveSenderNames are accepted again. Defaults still apply at runtime via the Zod safeParse path. No new permissions or surfaces.

Diagram (if applicable)

Before:
[user config: {accounts: {...}}] -> [JSON schema with required:[domain, ...]] -> [Ajv reject: missing required] -> [gateway crash loop]

After:
[user config: {accounts: {...}}] -> [JSON schema with required:[]] -> [Ajv ok] -> [Zod safeParse applies defaults] -> [gateway ready]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS (Darwin 25.2.0, arm64)
• Runtime: Node 24, gateway via node dist/index.js gateway --port 18789
• Integration/channel: Feishu (with 6+ named accounts)
• Relevant config (redacted): see #77116 — channels.feishu with enabled, dmPolicy: "allowlist", groupPolicy: "allowlist", allowFrom: ["*"], accounts.{main,finance,...,default} with appId/appSecret.

Steps

1. Use the redacted config from #77116 at ~/.openclaw/openclaw.json.
2. Run gateway under stock 2026.5.2: gateway crashes in restart loop with must NOT have additional properties (paraphrased) / must have required property "domain" etc.
3. Apply this PR's commit, regenerate, restart: gateway starts cleanly.

Expected

• Gateway boots, Feishu plugin loads, no validation errors.

Actual (after fix)

• Verified with the user's exact config from #77116 against the regenerated bundled-channel-config-metadata.generated.ts via Ajv: validates ok.

Evidence

• Failing-before / passing-after via 1 new test in src/channels/plugins/config-schema.test.ts
• Updated existing passes draft-07 compatibility options test to assert io: 'input'
• Re-ran user's exact reported config through Ajv → validates ok

Human Verification (required)

• Verified scenarios: Validated user's reported config from #77116 against the regenerated schema via Ajv — passes. Ran pnpm vitest run src/channels/plugins/config-schema.test.ts src/config/validation.channel-metadata.test.ts extensions/feishu/src/config-schema.test.ts — 36/36 pass. Ran pnpm vitest run src/config/ — 1231/1232 pass (1 unrelated pre-existing bun fallback test failure that fails on stock main too).
• Edge cases checked (in tests): mandatory-only field stays in required; .optional() only stays out of required; .optional().default() stays out of required.
• What I did not verify manually: End-to-end gateway restart on the user's exact config — relied on Ajv-level validation since the gateway pipeline uses the same generated schema.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — only relaxes input validation; no semantics change at runtime.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Other consumers of the JSON schema (UI pickers, doc generators) may have implicitly relied on required reflecting the output type rather than input requirements.
  • Mitigation: required for .optional().default() fields is widely considered a Zod 4 footgun; the input-shape semantics is the canonical interpretation for runtime input validation. UI consumers that need the output shape can use the Zod schema directly (still exported by each plugin).

Changed files

• src/channels/plugins/config-schema-input-mode.test.ts (added, +45/-0)
• src/channels/plugins/config-schema-input-mode.ts (added, +37/-0)
• src/channels/plugins/config-schema.test.ts (modified, +21/-0)
• src/channels/plugins/config-schema.ts (modified, +4/-10)
• src/config/bundled-channel-config-metadata.generated.ts (modified, +152/-192)