OpenClaw Config

Overview

Safely edit ~/.openclaw/openclaw.json (or the path set by OPENCLAW_CONFIG_PATH) using a schema-first workflow. Validate before and after changes to avoid invalid keys/types that can break startup or change security behavior.

Workflow (Safe Edit)

Identify the active config path

Precedence: OPENCLAW_CONFIG_PATH > OPENCLAW_STATE_DIR/openclaw.json > ~/.openclaw/openclaw.json
The config file is JSON5 (comments + trailing commas allowed).

Get an authoritative schema (do not guess keys)

If the Gateway is running: use openclaw gateway call config.schema --params '{}' to fetch a JSON Schema matching the running version.
Otherwise: use openclaw/openclaw source-of-truth, primarily:
- src/config/zod-schema.ts (OpenClawSchema root keys like gateway/skills/plugins)
- src/config/zod-schema.*.ts (submodules: channels/providers/models/agents/tools)
- docs/gateway/configuration.md (repo docs + examples)

Apply changes with the smallest safe surface

Prefer small edits: openclaw config get|set|unset (dot path or bracket notation).
If the Gateway is online and you want "write + validate + restart" in one step: use RPC config.patch (merge patch) or config.apply (replaces the entire config; use carefully).
For complex setups, split config with $include (see below).

Validate strictly

Run openclaw doctor, then fix issues using the reported path + message.
Do not run openclaw doctor --fix/--yes without explicit user consent (it writes to config/state files).

Guardrails (Avoid Schema Bugs)

Most objects are strict (.strict()): unknown keys usually fail validation and the Gateway will refuse to start.
channels is .passthrough(): extension channels (matrix/zalo/nostr, etc.) can add custom keys, but most provider configs remain strict.
env is .catchall(z.string()): you can put string env vars directly under env, and you can also use env.vars.
Secrets: prefer environment variables/credential files. Avoid committing long-lived tokens/API keys into openclaw.json.

$include (Modular Config)

$include is resolved before schema validation and lets you split config across JSON5 files:

Supports "$include": "./base.json5" or "$include": ["./a.json5", "./b.json5"]
Relative paths are resolved against the directory of the current config file.
Deep-merge rules (per implementation):
- objects: merge recursively
- arrays: concatenate (not replace)
- primitives: later value wins
If sibling keys exist alongside $include, sibling keys override included values.
Limits: max depth 10; circular includes are detected and rejected.

Common Recipes (Examples)

Set default workspace

openclaw config set agents.defaults.workspace '"~/.openclaw/workspace"' --json
openclaw doctor

Change Gateway port

openclaw config set gateway.port 18789 --json
openclaw doctor

Split config (example)

// ~/.openclaw/openclaw.json
{
  "$include": ["./gateway.json5", "./channels/telegram.json5"],
}

Telegram open DMs (must explicitly allow senders)

Schema constraint: when dmPolicy="open", allowFrom must include "*".

openclaw config set channels.telegram.dmPolicy '"open"' --json
openclaw config set channels.telegram.allowFrom '["*"]' --json
openclaw doctor

Discord token (config or env fallback)


# Option A: write to config
openclaw config set channels.discord.token '"YOUR_DISCORD_BOT_TOKEN"' --json

# Option B: env var fallback (still recommend a channels.discord section exists)

# export DISCORD_BOT_TOKEN="..."

openclaw doctor

Enable web_search (Brave / Perplexity)

openclaw config set tools.web.search.enabled true --json
openclaw config set tools.web.search.provider '"brave"' --json

# Recommended: provide the key via env var (or write tools.web.search.apiKey)

# export BRAVE_API_KEY="..."

openclaw doctor

Resources

Load these when you need a field index or source locations:

references/openclaw-config-fields.md (root key index + key field lists with sources)
references/schema-sources.md (how to locate schema + constraints in openclaw repo)
scripts/openclaw-config-check.sh (print config path + run doctor)

Openclaw Config