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)

1. •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).

1. •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)

1. •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).

1. •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)

1. •Set default workspace

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

1. •Change Gateway port

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

1. •Split config (example)

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

1. •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

1. •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

1. •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)