<!-- source: https://deepwiki.com/openclaw/openclaw/2.3.1-configuration-reference -->

# Configuration Reference

- docs/automation/index.md
- docs/channels/groups.md
- docs/channels/slack.md
- docs/cli/migrate.md
- docs/concepts/agent-workspace.md
- docs/concepts/context.md
- docs/concepts/soul.md
- docs/concepts/system-prompt.md
- docs/gateway/config-agents.md
- docs/gateway/config-channels.md
- docs/gateway/configuration-examples.md
- docs/gateway/configuration-reference.md
- docs/gateway/configuration.md
- docs/gateway/heartbeat.md
- docs/help/faq.md
- docs/nodes/camera.md
- docs/plugins/codex-native-plugins.md
- docs/reference/rich-output-protocol.md
- docs/reference/token-use.md
- docs/start/openclaw.md
- extensions/codex/index.ts
- extensions/codex/src/app-server/auth-bridge.test.ts
- extensions/codex/src/app-server/auth-bridge.ts
- extensions/codex/src/app-server/rate-limits.test.ts
- extensions/codex/src/app-server/rate-limits.ts
- extensions/codex/src/app-server/request.test.ts
- extensions/codex/src/command-account.ts
- extensions/codex/src/command-formatters.ts
- extensions/codex/src/command-handlers.ts
- extensions/codex/src/command-rpc.ts
- extensions/codex/src/commands.test.ts
- extensions/codex/src/conversation-binding-data.ts
- extensions/codex/src/conversation-binding.test.ts
- extensions/codex/src/conversation-binding.ts
- extensions/github-copilot/embeddings.test.ts
- extensions/slack/src/approval-auth.ts
- extensions/slack/src/approval-handler.runtime.test.ts
- extensions/slack/src/approval-handler.runtime.ts
- extensions/slack/src/approval-native-gates.ts
- extensions/slack/src/approval-native.test.ts
- extensions/slack/src/approval-native.ts
- extensions/slack/src/monitor.test-helpers.ts
- extensions/slack/src/send.ts
- extensions/slack/src/send.unfurl.test.ts
- extensions/telegram/src/status-reaction-variants.ts
- extensions/whatsapp/src/auto-reply/monitor/on-message.audio-preflight.test.ts
- extensions/whatsapp/src/auto-reply/monitor/on-message.ts
- src/agents/auth-profiles/credential-state.test.ts
- src/agents/auth-profiles/credential-state.ts
- src/agents/auth-profiles/order.test.ts
- src/agents/auth-profiles/order.ts
- src/agents/auth-profiles/session-override.test.ts
- src/agents/auth-profiles/session-override.ts
- src/agents/bootstrap-files.test.ts
- src/agents/embedded-agent-helpers/bootstrap.ts
- src/agents/runtime-plan/auth.ts
- src/auto-reply/reply/commands-context-report.test.ts
- src/config/types.agent-defaults.ts
- src/config/types.messages.ts
- src/config/types.slack.ts
- src/config/zod-schema.agent-defaults.ts
- src/infra/heartbeat-runner.model-override.test.ts
- ui/src/ui/views/config-quick.test.ts
- ui/src/ui/views/config-quick.ts

This document provides a comprehensive technical reference for all configuration keys available in `~/.openclaw/openclaw.json`. It covers types, defaults, validation rules, and subsystem effects.

OpenClaw uses a centralized configuration system built on **JSON5** and **Zod**, providing strict type safety while allowing comments and trailing commas in the configuration file [[docs/gateway/configuration-reference.md30](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/gateway/configuration-reference.md?plain=1#L30-L30) [src/config/io.ts5-15](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L5-L15)].

## Configuration Architecture

The configuration system is organized into a hierarchical structure that separates infrastructure, runtime, and agent-specific settings.

### Top-Level Organization

```

```

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/configuration-reference.md?plain=1#L34-L156" min=34 max=156 file-path="docs/gateway/configuration-reference.md">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L1-L32" min=1 max=32 file-path="src/config/zod-schema.ts">Hii</FileRef>`

## Schema Validation System

OpenClaw employs a strict validation pipeline. Configuration is validated against a base schema merged with dynamic schemas provided by plugins and channels.

### Zod Schema Pipeline

The configuration loading process uses `getRuntimeConfig` to handle runtime state and `validateConfigObjectWithPlugins` for validation [[src/config/io.ts111-114](https://github.com/openclaw/openclaw/blob/fbdf5937/[src/config/io.ts#L111-L114)]. During runtime initialization, the system merges defaults, environment variables, and plugin-specific schemas. The `openclaw config schema` command prints the live JSON Schema used for validation and Control UI integration [[docs/gateway/configuration-reference.md15-17](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/gateway/configuration-reference.md?plain=1#L15-L17)].

```

```

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L75-L114" min=75 max=114 file-path="src/config/io.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/zod-schema.ts#L1-L32" min=1 max=32 file-path="src/config/zod-schema.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/configuration-reference.md?plain=1#L13-L22" min=13 max=22 file-path="docs/gateway/configuration-reference.md">Hii</FileRef>`

## Agent & Automation Configuration

The `agents` section defines core LLM parameters, while the `automation` features like `cron` handle scheduled tasks [[docs/gateway/config-agents.md10-13](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/gateway/config-agents.md?plain=1#L10-L13)].

### Agent Defaults & Context

### Model Auth & Failover

Authentication is managed via `AuthProfileStore`. The `resolveAuthProfileOrder` function determines which credentials to use based on provider aliases and explicit configuration [[src/agents/auth-profiles/order.ts31](https://github.com/openclaw/openclaw/blob/fbdf5937/[src/agents/auth-profiles/order.ts#L31-L31) [src/agents/auth-profiles/order.ts52-55](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/auth-profiles/order.ts#L52-L55)].

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L10-L130" min=10 max=130 file-path="docs/gateway/config-agents.md">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/auth-profiles/order.ts#L31-L150" min=31 max=150 file-path="src/agents/auth-profiles/order.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/command-account.ts#L145-L161" min=145 max=161 file-path="extensions/codex/src/command-account.ts">Hii</FileRef>`

## Messaging Channels

The `channels` section configures integration with platforms like Slack, Telegram, and WhatsApp [[docs/gateway/config-channels.md10-15](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/gateway/config-channels.md?plain=1#L10-L15)].

### Global Channel Defaults

### Platform-Specific Examples

### Group Reply Logic

OpenClaw supports different visible reply modes for groups. The `visibleReplies` setting determines if the agent must use the `message` tool or can return raw text [[docs/channels/groups.md47-52](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/channels/groups.md?plain=1#L47-L52)].

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-channels.md?plain=1#L10-L156" min=10 max=156 file-path="docs/gateway/config-channels.md">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/channels/slack.md?plain=1#L1-L50" min=1 max=50 file-path="docs/channels/slack.md">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/channels/groups.md?plain=1#L45-L112" min=45 max=112 file-path="docs/channels/groups.md">Hii</FileRef>`

## Infrastructure & Diagnostics

### MCP (Model Context Protocol)

Managed MCP server definitions live under `mcp.servers`. These allow the agent to connect to external tool providers [[docs/gateway/configuration-reference.md91-95](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/gateway/configuration-reference.md?plain=1#L91-L95)].

### Memory & QMD ( memory )

The `memory` section controls vector search and session retention behavior via the QMD (Queryable Memory Document) backend [[docs/gateway/configuration-reference.md26](https://github.com/openclaw/openclaw/blob/fbdf5937/[docs/gateway/configuration-reference.md?plain=1#L26-L26)].

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/configuration-reference.md?plain=1#L91-L156" min=91 max=156 file-path="docs/gateway/configuration-reference.md">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L188-L221" min=188 max=221 file-path="docs/gateway/config-agents.md">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/config.js#L12-L13" min=12 max=13 file-path="extensions/codex/src/app-server/config.js">Hii</FileRef>`
