1---2name: openclaw-schema-map3description: Complete map of the OpenClaw config schema from source code. THE single source of truth for valid config keys.4metadata:5 source: https://skillmd.com/skills/nickgallick/openclaw-schema-map6---78# Changelog9- 2026-03-19: Initial extraction from repos/openclaw/src/config/zod-schema.ts1011# OpenClaw Config Schema Map (from source code)1213## SOURCE14Extracted from Zod schema: `repos/openclaw/src/config/zod-schema.ts`15THIS IS AUTHORITATIVE. If docs disagree with this, this is correct.1617## How to Regenerate18```bash19cd /data/.openclaw/workspace-clawexpert/repos/openclaw && git pull20cat src/config/zod-schema.ts21```2223---2425## Root-Level Keys (ALL valid keys — schema is `.strict()`)2627| Key | Type | Required | Notes |28|-----|------|----------|-------|29| `$schema` | string | No | Schema URL |30| `meta` | object | No | lastTouchedVersion, lastTouchedAt |31| `env` | object | No | shellEnv, vars, catchall string |32| `wizard` | object | No | lastRunAt, lastRunVersion, etc. |33| `diagnostics` | object | No | enabled, flags, stuckSessionWarnMs, otel, cacheTrace |34| `logging` | object | No | level, file, maxFileBytes, consoleLevel, consoleStyle, redactSensitive, redactPatterns |35| `cli` | object | No | banner.taglineMode |36| `update` | object | No | channel (stable/beta/dev), checkOnStart, auto |37| `browser` | object | No | enabled, cdpUrl, headless, profiles, ssrfPolicy, etc. |38| `ui` | object | No | seamColor, assistant.name, assistant.avatar |39| `secrets` | object | No | providers, defaults, resolution |40| `auth` | object | No | profiles, order, cooldowns |41| `acp` | object | No | enabled, dispatch, backend, defaultAgent, allowedAgents, stream, runtime |42| `models` | object | No | mode, providers, bedrockDiscovery |43| `nodeHost` | object | No | browserProxy |44| `agents` | object | No | defaults, list[] |45| `tools` | object | No | web, media, links, sessions, exec, fs, etc. |46| `bindings` | array | No | route and acp bindings |47| `broadcast` | object | No | agent-to-agent broadcast config |48| `audio` | object | No | audio config |49| `media` | object | No | preserveFilenames, ttlHours |50| `messages` | object | No | MessagesSchema |51| `commands` | object | No | CommandsSchema |52| `approvals` | object | No | ApprovalsSchema |53| `session` | object | No | SessionSchema |54| `cron` | object | No | enabled, store, maxConcurrentRuns, retry, webhook, sessionRetention, runLog, failureAlert, failureDestination |55| `hooks` | object | No | enabled, path, token, mappings, gmail, internal, etc. |56| `web` | object | No | enabled, heartbeatSeconds, reconnect |57| `channels` | object | No | ChannelsSchema (all channel types) |58| `discovery` | object | No | wideArea, mdns |59| `canvasHost` | object | No | enabled, root, port, liveReload |60| `talk` | object | No | provider, providers, voiceId, modelId, apiKey, etc. |61| `gateway` | object | No | port, mode, bind, customBindHost, controlUi, auth, tls, http, etc. |62| `memory` | object | No | backend, citations, qmd |63| `mcp` | object | No | servers record (stdio MCP servers) |64| `skills` | object | No | allowBundled, load, install, limits, entries |65| `plugins` | object | No | enabled, allow, deny, load, slots, entries, installs |6667**REJECTED/INVALID ROOT KEYS**: Any key not in the above list will crash the gateway (`.strict()` mode).6869---7071## `agents` schema7273### `agents.defaults`74See AgentDefaultsSchema — same shape as agent entries but all optional.7576### `agents.list[]` item (AgentEntrySchema)77| Key | Type | Required | Notes |78|-----|------|----------|-------|79| `id` | string | **YES** | Unique agent identifier |80| `default` | boolean | No | Is this the default agent? |81| `name` | string | No | Display name |82| `workspace` | string | No | Path to workspace directory |83| `agentDir` | string | No | Alternative: agent directory path |84| `model` | AgentModelSchema | No | Model string or object |85| `skills` | string[] | No | Skill IDs to load |86| `memorySearch` | MemorySearchSchema | No | Memory search config |87| `humanDelay` | HumanDelaySchema | No | mode, minMs, maxMs |88| `heartbeat` | HeartbeatSchema | No | every, activeHours, model, prompt, etc. |89| `identity` | IdentitySchema | No | name, theme, emoji, avatar |90| `groupChat` | GroupChatSchema | No | mentionPatterns, historyLimit |91| `subagents` | object | No | allowAgents, model, thinking |92| `sandbox` | AgentSandboxSchema | No | docker, network, etc. |93| `params` | record | No | Arbitrary key-value params |94| `tools` | AgentToolsSchema | No | Per-agent tool overrides |95| `runtime` | AgentRuntimeSchema | No | Runtime config |9697---9899## `gateway` schema100101| Key | Type | Notes |102|-----|------|-------|103| `port` | int | Gateway port |104| `mode` | "local" \| "remote" | |105| `bind` | "auto" \| "lan" \| "loopback" \| "custom" \| "tailnet" | |106| `customBindHost` | string | **VALID** — use with bind:"custom" |107| `controlUi` | object | enabled, basePath, allowedOrigins, etc. |108| `auth` | object | mode, token, password, rateLimit, trustedProxy |109| `auth.mode` | "none" \| "token" \| "password" \| "trusted-proxy" | |110| `tls` | object | enabled, autoGenerate, certPath, keyPath |111| `tailscale` | object | mode (off/serve/funnel), resetOnExit |112| `remote` | object | url, transport, token, sshTarget, etc. |113| `reload` | object | mode (off/restart/hot/hybrid), debounceMs |114| `http` | object | endpoints (chatCompletions, responses), securityHeaders |115| `push` | object | apns relay config |116| `nodes` | object | browser mode/node, allowCommands, denyCommands |117| `tools` | object | deny, allow arrays |118| `channelHealthCheckMinutes` | int | 0=disabled, default 5 |119| `channelStaleEventThresholdMinutes` | int | Must be >= healthCheckMinutes |120| `channelMaxRestartsPerHour` | int | |121| `trustedProxies` | string[] | |122| `allowRealIpFallback` | boolean | |123124---125126## `channels` schema127Defined in `zod-schema.providers.ts` — includes: telegram, discord, slack, signal, whatsapp, imessage, irc, msteams, googlechat, feishu, webchat, and more.128129---130131## `cron` schema132| Key | Type | Notes |133|-----|------|-------|134| `enabled` | boolean | |135| `store` | string | Storage path |136| `maxConcurrentRuns` | int | |137| `retry` | object | maxAttempts, backoffMs[], retryOn[] |138| `retry.retryOn` | enum[] | rate_limit, overloaded, network, timeout, server_error |139| `webhook` | http url | |140| `webhookToken` | SecretInput | |141| `sessionRetention` | string \| false | Duration string (ms/s/m/h/d) or false |142| `runLog` | object | maxBytes (string/number), keepLines |143| `failureAlert` | object | enabled, after, cooldownMs, mode, accountId |144| `failureDestination` | object | channel, to, accountId, mode |145146---147148## `mcp` schema (NATIVE stdio MCP — not mcporter)149```150mcp:151 servers:152 <server-name>:153 command: string # stdio server command154 args: string[]155 env: record156 cwd: string157 workingDirectory: string158 url: http url # for HTTP-based servers159```160ACP capabilities (http/sse) are `false` — but stdio MCP works via `mcp.servers`.161162---163164## `memory` schema165| Key | Type | Notes |166|-----|------|-------|167| `backend` | "builtin" \| "qmd" | |168| `citations` | "auto" \| "on" \| "off" | |169| `qmd` | object | command, mcporter, searchMode, paths, sessions, update, limits, scope |170| `qmd.searchMode` | "query" \| "search" \| "vsearch" | |171| `qmd.mcporter.enabled` | boolean | Route QMD through mcporter daemon |172173---174175## `skills` schema176| Key | Type | Notes |177|-----|------|-------|178| `allowBundled` | string[] | |179| `load.extraDirs` | string[] | Additional skill dirs |180| `load.watch` | boolean | |181| `install.preferBrew` | boolean | |182| `install.nodeManager` | npm/pnpm/yarn/bun | |183| `limits` | object | maxCandidatesPerRoot, maxSkillsLoadedPerSource, etc. |184| `entries.<id>` | SkillEntrySchema | enabled, apiKey, env, config |185186---187188## `plugins` schema189| Key | Type | Notes |190|-----|------|-------|191| `enabled` | boolean | |192| `allow` | string[] | |193| `deny` | string[] | |194| `load.paths` | string[] | |195| `slots.memory` | string | Plugin ID for memory slot |196| `slots.contextEngine` | string | Plugin ID for context engine slot |197| `entries.<id>` | PluginEntrySchema | enabled, hooks, subagent, config |198| `installs.<id>` | PluginInstallRecordShape | |199200---201202## `secrets` schema203| Key | Type | Notes |204|-----|------|-------|205| `providers.<name>` | SecretProviderSchema | source: env/file/exec |206| `defaults.env` | string | Default env provider alias |207| `defaults.file` | string | Default file provider alias |208| `defaults.exec` | string | Default exec provider alias |209| `resolution` | object | maxProviderConcurrency, maxRefsPerProvider, maxBatchBytes |210211SecretInput type accepts: plain string OR `{ source: "env"/"file"/"exec", provider: string, id: string }`212213---214215## `auth` schema216| Key | Type | Notes |217|-----|------|-------|218| `profiles.<name>` | object | provider, mode (api_key/oauth/token), email |219| `order` | record | provider → auth profile order |220| `cooldowns` | object | billingBackoffHours, failureWindowHours, etc. |221222---223224## `logging` schema225| Key | Type | Notes |226|-----|------|-------|227| `level` | silent/fatal/error/warn/info/debug/trace | |228| `file` | string | Log file path |229| `maxFileBytes` | int | |230| `consoleLevel` | same enum | |231| `consoleStyle` | pretty/compact/json | |232| `redactSensitive` | "off" \| "tools" | |233| `redactPatterns` | string[] | |234235---236237## `update` schema238| Key | Type | Notes |239|-----|------|-------|240| `channel` | "stable" \| "beta" \| "dev" | |241| `checkOnStart` | boolean | |242| `auto.enabled` | boolean | |243| `auto.stableDelayHours` | number | Max 168 |244| `auto.betaCheckIntervalHours` | number | Max 24 |245246---247248## `acp` schema249| Key | Type | Notes |250|-----|------|-------|251| `enabled` | boolean | |252| `dispatch.enabled` | boolean | |253| `backend` | string | |254| `defaultAgent` | string | |255| `allowedAgents` | string[] | |256| `maxConcurrentSessions` | int | |257| `stream` | object | coalesceIdleMs, maxChunkChars, deliveryMode, etc. |258| `runtime.ttlMinutes` | int | |259| `runtime.installCommand` | string | |260261---262263## `diagnostics.otel` schema264| Key | Type | Notes |265|-----|------|-------|266| `enabled` | boolean | |267| `endpoint` | string | |268| `protocol` | "http/protobuf" \| "grpc" | |269| `headers` | record | |270| `traces/metrics/logs` | boolean | |271| `sampleRate` | 0-1 | |272| `flushIntervalMs` | int | |273274---275276## Rejected / Invalid Root Keys277- `mcpServers` — NEVER a root key; use `mcp.servers` instead278- Any unknown key at root level → Zod `.strict()` throws → gateway crash