Configuration

OpenClaw loads an optional JSON5 configuration file from ~/.openclaw/openclaw.json (or the path set by OPENCLAW_CONFIG_PATH). If the file is absent, safe defaults are used. The file must be a regular file; symlinked layouts are unsupported for writes.

JSON5 format

The parser accepts JSON5, including comments, trailing commas, and unquoted keys in some contexts. A top-level $schema string is allowed for editor support. All other unknown root keys are rejected.

Modular configuration with $include

Use $include to compose configuration from multiple files:

{
  "$include": "./base.json5",
  "agents": { "$include": "./agents.json5" },
  "broadcast": { "$include": ["./c.json5", "./d.json5"] }
}
  • A string includes a single file.
  • An array merges files in order.
  • Content is deep-merged; arrays are concatenated; primitives from the including file win.
  • Includes are resolved relative to the including file's directory and validated for containment (respecting OPENCLAW_INCLUDE_ROOTS).
  • Maximum depth is 10. Maximum included file size is 2 MiB. Circular includes are reported with the full chain.

Merging happens before schema validation.

Validation and last-known-good snapshots

Configuration is validated against OpenClawSchema on load, hot reload, openclaw doctor, and openclaw config commands. Invalid configuration prevents Gateway startup (except for diagnostic commands). On failure the Gateway retains its last-known-good snapshot.

openclaw doctor --fix (or --fix --yes) repairs prefixed/clobbered entries and can restore the last-known-good copy. Promotion of a snapshot is skipped if it contains redacted secret placeholders (***).

Core sections

agents.defaults

Supplies baseline settings for all agents (overridable per-agent under agents.list and via bindings):

  • workspace
  • model (primary plus fallbacks)
  • sandbox (mode, scope, policy)
  • heartbeat (every, target, directPolicy, ackMaxChars)
  • skills, compaction, contextPruning
  • imageMaxDimensionPx, talk, sendPolicy, verboseLevel

Per-agent overrides appear under agents.list[]. Bindings route channels/accounts/peers to specific agents.

gateway.*

Controls the control plane:

  • port, bind (loopback/lan/tailnet/auto/custom), customBindHost
  • auth (mode, token, password, allowTailscale, trustedProxies)
  • tailscale (mode, serve/funnel options)
  • controlUi (enabled, basePath, root, allowedOrigins)
  • http (endpoints.chatCompletions, endpoints.responses, securityHeaders)
  • handshakeTimeoutMs, channelHealthCheckMinutes, channelStaleEventThresholdMinutes

Non-loopback binds require explicit shared-secret auth (or trusted-proxy) unless Tailscale identity is used.

hooks

HTTP ingress for webhooks:

{
  "hooks": {
    "enabled": true,
    "token": "...",
    "path": "/hooks",
    "defaultSessionKey": "hook:ingress",
    "mappings": [ ... ]
  }
}

Token is header-only (Authorization: Bearer or x-openclaw-token). All payloads are treated as untrusted.

cron

{
  "cron": {
    "enabled": true,
    "maxConcurrentRuns": 8,
    "sessionRetention": "24h",
    "runLog": { "maxBytes": "2mb", "keepLines": 2000 }
  }
}

sessionRetention prunes isolated cron-run sessions.

plugins and channels

Plugin entries live under plugins.entries.<id> with enabled and config. Channel configuration lives under channels.<provider>. Bundled channel metadata supplies per-channel JSON Schema for validation.

Managing configuration

Use the CLI:

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set agents.defaults.models '<json>' --strict-json --merge
openclaw config schema

openclaw doctor surfaces validation failures, risky DM policies, port collisions, and plugin load errors.

See Secrets and auth for SecretRef handling and HTTP API for gateway.http.* endpoints. For daemon and container layouts see Deployment and Linux server.

Updated June 17, 2026