ClawHub

Openclaw Config

MCP Tools

Edit and validate OpenClaw Gateway config (openclaw.json / JSON5). Use when adding/changing config keys (gateway.*, agents.*, models.*, channels.*, tools.*, skills.*, plugins.*, $include) or diagnosing openclaw doctor/config validation errors, to avoid schema mismatches that prevent the Gateway from starting or weaken security policies.

Install

openclaw skills install openclaw-config

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)
More in MCP Tools