openclaw-config
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 via CLI (Recommended)
clawhub install openclaw/skills/skills/caopulan/openclaw-configOpenClaw 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/openclawsource-of-truth, primarily:src/config/zod-schema.ts(OpenClawSchemaroot keys likegateway/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) orconfig.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 reportedpath+message. - Do not run
openclaw doctor --fix/--yeswithout 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. channelsis.passthrough(): extension channels (matrix/zalo/nostr, etc.) can add custom keys, but most provider configs remain strict.envis.catchall(z.string()): you can put string env vars directly underenv, and you can also useenv.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
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-caopulan-openclaw-config": {
"enabled": true,
"auto_update": true
}
}
}