<!-- source: https://deepwiki.com/openclaw/openclaw/2.3.2-schema-generation-and-ui-integration -->

# Schema Generation & UI Integration

- docs/.generated/config-baseline.sha256
- docs/channels/discord.md
- docs/cli/mcp.md
- docs/web/control-ui.md
- extensions/discord/src/config-schema.test.ts
- extensions/discord/src/config-ui-hints.ts
- extensions/discord/src/voice/manager.e2e.test.ts
- extensions/discord/src/voice/manager.ts
- extensions/discord/src/voice/realtime.ts
- src/agents/agent-scope-config.ts
- src/agents/embedded-agent-runner/tool-schema-runtime.ts
- src/agents/tools-effective-inventory-groups.ts
- src/agents/tools-effective-inventory.ts
- src/agents/tools-effective-inventory.types.ts
- src/commands/doctor-config-flow.include-warning.test.ts
- src/config/bundled-channel-config-metadata.generated.ts
- src/config/schema.help.ts
- src/config/schema.labels.ts
- src/config/schema.test.ts
- src/config/types.agents.ts
- src/config/types.discord.ts
- src/config/types.mcp.ts
- src/config/types.tools.ts
- src/config/zod-schema.agent-defaults.test.ts
- src/config/zod-schema.agent-runtime.ts
- src/config/zod-schema.providers-core.ts
- src/config/zod-schema.ts
- src/gateway/server-methods/config.test.ts
- src/gateway/server-methods/config.ts
- src/gateway/server-methods/node-child-process.test-support.ts
- src/gateway/server-methods/tools-effective.runtime.ts
- src/gateway/server-methods/tools-effective.test.ts
- src/gateway/server-methods/tools-effective.ts
- src/gateway/server-methods/update-managed-service-handoff.test.ts
- src/gateway/server-methods/update-managed-service-handoff.ts
- src/gateway/server-methods/update.test.ts
- src/gateway/server-methods/update.ts
- src/infra/errors.test.ts
- src/infra/errors.ts
- src/infra/is-main.test.ts
- src/infra/is-main.ts
- src/infra/push-web.test.ts
- src/infra/push-web.ts
- ui/src/styles/chat/grouped.css
- ui/src/styles/config.css
- ui/src/styles/usage.css
- ui/src/ui/app-settings.refresh-active-tab.node.test.ts
- ui/src/ui/app-settings.ts
- ui/src/ui/controllers/config.test.ts
- ui/src/ui/controllers/config.ts
- ui/src/ui/controllers/config/form-coerce.ts
- ui/src/ui/controllers/config/form-utils.node.test.ts
- ui/src/ui/controllers/config/form-utils.ts
- ui/src/ui/controllers/cron-filters.test.ts
- ui/src/ui/controllers/cron.test.ts
- ui/src/ui/controllers/cron.ts
- ui/src/ui/format.test.ts
- ui/src/ui/format.ts
- ui/src/ui/provider-quota-summary.test.ts
- ui/src/ui/provider-quota-summary.ts
- ui/src/ui/types.ts
- ui/src/ui/views/activity.ts
- ui/src/ui/views/config-form.shared.ts
- ui/src/ui/views/config.browser.test.ts
- ui/src/ui/views/config.ts
- ui/src/ui/views/cron.test.ts
- ui/src/ui/views/cron.ts
- ui/src/ui/views/overview-cards.ts
- ui/src/ui/views/overview-event-log.ts
- ui/src/ui/views/overview.render.test.ts
- ui/src/ui/views/usage-render-details.test.ts
- ui/src/ui/views/usage-render-details.ts
- ui/src/ui/views/usage-render-overview.test.ts
- ui/src/ui/views/usage-render-overview.ts

This page explains how OpenClaw builds, caches, and merges configuration schemas with plugin extensions to drive the dynamic forms in the Control UI. The system transforms static **Zod** definitions and **JSON Schema** into interactive forms with rich metadata for validation and visual rendering.

## Schema Generation Pipeline

OpenClaw uses a multi-stage pipeline to convert runtime schemas into the structured metadata required by the Control UI. This pipeline bridges the gap between static code definitions and the dynamic JSON-based configuration required by the frontend.

### Architecture Overview

The pipeline transforms core configuration definitions and plugin-provided schemas into serialized metadata that the Control UI uses to render forms.

```

```

**Sources:** [src/config/zod-schema.ts49-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L49-L50) [src/config/schema.help.ts4-51](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L4-L51) [src/config/schema.labels.ts3-100](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.labels.ts#L3-L100) [src/gateway/server-methods/config.ts12-17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/config.ts#L12-L17) [src/config/bundled-channel-config-metadata.generated.ts17-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L17-L20)

## JSON Schema Generation & Caching

The core configuration is defined using Zod but projected as JSON Schema for the UI. To ensure performance, the Gateway caches these schema builds.

### Base Schema Generation

The configuration keys found in `openclaw.json` are managed via a root Zod schema named `OpenClawSchema` [src/config/zod-schema.ts49](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L49-L49) This is supplemented by provider-specific schemas like `TelegramGroupSchema` [src/config/zod-schema.providers-core.ts171](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.providers-core.ts#L171-L171) and `DiscordPreviewStreamingConfigSchema` [src/config/zod-schema.providers-core.ts124](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.providers-core.ts#L124-L124)

The system relies on a pre-generated metadata registry for bundled channels, stored in `RAW_BUNDLED_CHANNEL_CONFIG_METADATA` [src/config/bundled-channel-config-metadata.generated.ts17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L17-L17) This includes full JSON Schema definitions for every supported channel (e.g., Discord, ClickClack) [src/config/bundled-channel-config-metadata.generated.ts18-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L18-L20)

**Sources:** [src/config/zod-schema.ts49](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L49-L49) [src/config/zod-schema.providers-core.ts171](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.providers-core.ts#L171-L171) [src/config/zod-schema.providers-core.ts124](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.providers-core.ts#L124-L124) [src/config/bundled-channel-config-metadata.generated.ts17-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L17-L20)

### Caching and Performance

Because building the full schema (merging core, plugins, and help text) is expensive, the Gateway implements a caching layer:

1. Response Cache : loadGatewayRuntimeConfigSchema results are cached to reuse schema builds across burst requests src/gateway/server-methods/config.ts 155-161
2. Cache Invalidation : The cache is cleared via clearConfigSchemaResponseCacheForTests or when configuration writes change schema inputs src/gateway/server-methods/config.ts 3-7 src/gateway/server-methods/config.test.ts 163-169
3. Baseline Hashes : The system tracks config-baseline.sha256 for core and plugin surfaces to detect drift docs/.generated/config-baseline.sha256 1-4

**Sources:** [src/gateway/server-methods/config.ts155-161](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/config.ts#L155-L161) [src/gateway/server-methods/config.test.ts163-169](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/config.test.ts#L163-L169) [docs/.generated/config-baseline.sha2561-4](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/.generated/config-baseline.sha256#L1-L4)

## UI Hints & Form Metadata

The Control UI uses **UI Hints** and field metadata to create a user-friendly experience, mapping technical JSON paths to human-readable elements.

### Hint Categories

**Sources:** [src/config/schema.help.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L4-L4) [src/config/schema.labels.ts3](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.labels.ts#L3-L3) [src/config/bundled-channel-config-metadata.generated.ts13](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L13-L13)

### Specialized Field Metadata

Certain subsystems define their own metadata, such as `MEDIA_AUDIO_FIELD_HELP` and `MEDIA_AUDIO_FIELD_LABELS`, which are merged into the main registries [src/config/schema.help.ts1](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L1-L1) [src/config/schema.labels.ts1](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.labels.ts#L1-L1) This includes complex logic like `describeTalkSilenceTimeoutDefaults` for dynamic help text [src/config/schema.help.ts2](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L2-L2)

**Sources:** [src/config/schema.help.ts1-2](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L1-L2) [src/config/schema.labels.ts1](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.labels.ts#L1-L1)

## UI Integration & State Management

The Control UI consumes the generated schemas and validation state to drive its `config` view.

### Configuration View State

The UI maintains a complex state for the configuration form, managed in `ConfigProps` [ui/src/ui/views/config.browser.test.ts4-64](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.browser.test.ts#L4-L64) This includes:

- formMode : Toggle between "form" (visual) and "raw" (JSON) ui/src/ui/views/config.browser.test.ts 23
- schema : The JSON Schema Draft-07 object fetched from the Gateway ui/src/ui/views/config.browser.test.ts 17-20
- uiHints : Labels and help text used to annotate the form ui/src/ui/views/config.browser.test.ts 22

### Form Validation and Safety

The UI implements safety checks to prevent invalid saves. Buttons like `Save` and `Apply` are disabled if the form contains invalid data or if the schema is missing [ui/src/ui/views/config.browser.test.ts174-190](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.browser.test.ts#L174-L190) The `onFormPatch` callback handles incremental updates as the user interacts with the dynamic fields [ui/src/ui/views/config.browser.test.ts32](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.browser.test.ts#L32-L32)

```

```

**Sources:** [ui/src/ui/views/config.browser.test.ts4-64](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.browser.test.ts#L4-L64) [ui/src/ui/views/config.browser.test.ts174-190](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.browser.test.ts#L174-L190) [ui/src/ui/controllers/config.ts30](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/controllers/config.ts#L30-L30)

## Summary of Key Symbols

**Sources:** [src/gateway/server-methods/config.ts12](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/config.ts#L12-L12) [src/config/zod-schema.ts49](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L49-L49) [src/config/schema.help.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L4-L4) [src/config/schema.labels.ts3](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.labels.ts#L3-L3) [src/config/bundled-channel-config-metadata.generated.ts17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L17-L17) [ui/src/ui/views/config.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.ts#L4-L4) [ui/src/ui/views/config.browser.test.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.browser.test.ts#L4-L4)
