<!-- source: https://deepwiki.com/openclaw/openclaw/2.3-configuration-system -->

# Configuration System

- docs/.generated/config-baseline.sha256
- docs/channels/discord.md
- docs/cli/mcp.md
- docs/web/control-ui.md
- extensions/codex/src/app-server/attempt-startup.ts
- 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/openai-routing.test.ts
- src/agents/openai-routing.ts
- src/cli/plugins-install-record-commit.ts
- src/commands/agent-command.test-mocks.ts
- src/commands/agents.bind.test-support.ts
- src/commands/doctor-disk-space.test.ts
- src/commands/doctor-disk-space.ts
- src/commands/doctor-lint.test.ts
- src/commands/doctor/shared/codex-route-warnings.test.ts
- src/commands/doctor/shared/codex-route-warnings.ts
- src/commands/doctor/shared/stale-plugin-config.test.ts
- src/commands/doctor/shared/stale-plugin-config.ts
- src/config/bundled-channel-config-metadata.generated.ts
- src/config/codex-plugin-diagnostics.ts
- src/config/config.plugin-validation.test.ts
- src/config/config.ts
- src/config/doc-baseline.integration.test.ts
- src/config/io.ts
- src/config/io.write-config.test.ts
- src/config/mutate.test.ts
- src/config/mutate.ts
- src/config/runtime-snapshot.ts
- src/config/schema.help.ts
- src/config/schema.labels.ts
- src/config/schema.test.ts
- src/config/session-parent-fork-config-keys.test.ts
- src/config/types.agents.ts
- src/config/types.discord.ts
- src/config/types.mcp.ts
- src/config/types.tools.ts
- src/config/validation.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/flows/doctor-core-checks.test.ts
- src/flows/doctor-core-checks.ts
- src/flows/doctor-health-contributions.test.ts
- src/flows/doctor-health-contributions.ts
- src/flows/doctor-health-conversion-plan.ts
- src/flows/doctor-lint-flow.ts
- src/gateway/server-methods/config-write-flow.ts
- src/gateway/server-methods/config.shared-auth.test.ts
- src/gateway/server-startup-config.ts
- src/infra/push-web.test.ts
- src/infra/push-web.ts
- src/secrets/runtime-fast-path.ts
- src/secrets/runtime-request-secret-refs.test.ts
- src/secrets/runtime-secret-scan.ts
- src/secrets/runtime-web-tools.test.ts
- src/secrets/runtime-web-tools.ts
- src/secrets/runtime.gateway-auth.integration.test.ts
- src/secrets/runtime.test.ts
- src/secrets/runtime.ts

The Configuration System provides runtime configuration loading, validation, hot-reload, and management for the OpenClaw gateway and all its subsystems (channels, agents, tools, models, etc.). It reads configuration from `~/.openclaw/openclaw.json` in **JSON5** format [src/config/paths.ts21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/paths.ts#L21-L21) validates it against a strict **Zod schema** [src/config/zod-schema.ts1](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L1-L1) resolves secrets, and exposes a runtime snapshot to all gateway components. The system supports programmatic updates via transactional mutations and automatic migration from legacy formats through the `doctor` utility.

For channel-specific configuration patterns, see [Messaging Channels](/openclaw/openclaw/4-messaging-channels). For agent and model configuration, see [Agent Runtime](/openclaw/openclaw/3-agent-runtime). For the complete field reference, see page [Configuration Reference](/openclaw/openclaw/2.3.1-configuration-reference).

## Architecture Overview

The configuration system operates as a multi-stage pipeline that transforms raw JSON5 files into a validated, resolved runtime snapshot. It integrates core configuration with plugin-provided schemas to create a unified state.

### Configuration Loading & Validation Flow

```

```

Sources: [src/config/io.ts5-81](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L5-L81) [src/config/validation.ts42-47](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/validation.ts#L42-L47) [src/config/io.ts111-114](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L111-L114)

## Core Configuration Modules

### Config I/O and Validation

The primary validation engine is built on **Zod**, ensuring that every field in the configuration file matches the expected type and structure. The system uses a hierarchical schema approach where sub-schemas handle specific domains like `AgentRunRetriesConfigSchema` and `SandboxDockerSchema` [src/config/zod-schema.agent-runtime.ts58-210](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.agent-runtime.ts#L58-L210)

Validation is not limited to static types; it includes complex logic such as `validateSandboxBindEntries` to ensure absolute paths for security [src/config/zod-schema.agent-runtime.ts26-56](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.agent-runtime.ts#L26-L56) and duration parsing for heartbeat intervals [src/config/zod-schema.agent-runtime.ts110-122](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.agent-runtime.ts#L110-L122)

### Config Schema Entity Mapping

```

```

Sources: [src/config/schema.labels.ts3-128](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.labels.ts#L3-L128) [src/config/schema.help.ts4-72](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/schema.help.ts#L4-L72) [src/config/zod-schema.agent-runtime.ts58-210](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.agent-runtime.ts#L58-L210) [src/config/validation.ts46-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/validation.ts#L46-L50)

### SecretRef System

OpenClaw implements a `SecretRef` pattern to keep sensitive credentials out of the main configuration file. Fields marked as sensitive can accept either a plain string or a `SecretRef` object [src/config/types.secrets.ts22-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/types.secrets.ts#L22-L30)

Supported sources include:

- env : Loads from process environment variables src/config/types.secrets.ts 24
- file : Reads from a local file path src/config/types.secrets.ts 25
- exec : Resolves via external process execution src/config/types.secrets.ts 26

Sources: [src/config/types.secrets.ts22-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/types.secrets.ts#L22-L30) [src/secrets/runtime.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/src/secrets/runtime.ts#L1-L10) [src/config/validation.ts48](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/validation.ts#L48-L48)

## Plugin Configuration Integration

OpenClaw allows plugins to extend the configuration schema. When `validateConfigObjectWithPlugins` is called, it loads the `PluginMetadataSnapshot` [src/config/io.ts28-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L28-L30) and merges plugin-defined schemas (from `openclaw.plugin.json`) into the validation process using `validateJsonSchemaValue` [src/config/validation.ts25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/validation.ts#L25-L25)

- Bundled Channels : Metadata for built-in channels like Discord and Slack is auto-generated and includes their specific JSON schemas src/config/bundled-channel-config-metadata.generated.ts 17-20
- Dynamic Validation : The system identifies enabled plugins and validates their specific config blocks against the manifest's configSchema src/config/config.plugin-validation.test.ts 35-46

For details on how plugin schemas are merged and used by the Control UI, see [Schema Generation & UI Integration](/openclaw/openclaw/2.3.2-schema-generation-and-ui-integration).

Sources: [src/config/validation.ts130-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/validation.ts#L130-L140) [src/config/bundled-channel-config-metadata.generated.ts1-15](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/bundled-channel-config-metadata.generated.ts#L1-L15) [src/config/config.plugin-validation.test.ts120-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/config.plugin-validation.test.ts#L120-L130)

## Configuration Repair & Health

The `doctor` system provides a robust health-check and auto-repair mechanism for configuration state. It identifies legacy patterns, ambiguous settings, and environment issues [src/flows/doctor-health-contributions.ts100-120](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L100-L120)

- Health Contributions : Core health checks cover gateway auth modes, UI protocol freshness, and auth profile integrity src/flows/doctor-health-contributions.ts 135-170
- Migrations : The system handles complex migrations, such as rewriting legacy openai-codex/* model references to the canonical openai/* format src/commands/doctor/shared/codex-route-warnings.ts 34-37
- Integrity Checks : doctor verifies that required directories exist and that the configuration file is writable src/flows/doctor-health-contributions.ts 21-29

Sources: [src/flows/doctor-health-contributions.ts31-53](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L31-L53) [src/commands/doctor/shared/codex-route-warnings.test.ts57-75](https://github.com/openclaw/openclaw/blob/fbdf5937/src/commands/doctor/shared/codex-route-warnings.test.ts#L57-L75) [src/config/io.ts149-167](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L149-L167)

## Key Configuration Files

Sources: [src/config/paths.ts21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/paths.ts#L21-L21) [src/config/io.ts82](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L82-L82) [src/config/io.ts169-177](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L169-L177)
