Config writes
WednesdayAI refuses a config write that would drop top-level keys you did not name. Agents can still patch settings. Whole-document replace stays available, but it is denied by default. This page covers operator writes (config.set / config.apply / config.patch), tool policy, and secret-preserving startup writes. It does not replace the field reference. Chat-facing behavior is in Changing settings. Gateway client authors should read Config writes (developer).
Quickstart
Preferred path for a small change: merge a patch. Capturehash from config.get, then call config.patch.
~/.openclaw/openclaw.json, and restarts. Unnamed top-level keys stay on disk.
Named top-level removals
allowTopLevelKeyRemoval default: omitted (treated as []).
Write RPCs config.set, config.apply, and config.patch accept an optional string array. Only keys listed there may disappear from the top level of ~/.openclaw/openclaw.json. The gateway does not infer intent from the payload.
First-party removers already name the key for you:
- Control UI Save / Save & restart (form and Raw JSON5)
wednesdayai config unset <topLevelKey>- Chat
/config unset <topLevelKey>
config.apply and config.patch still restart the gateway after a successful write.
Optimistic concurrency (baseHash)
baseHash default: omitted in the schema; required at runtime when a config file already exists.
- Call
config.getand readpayload.hash. - Pass that value as
baseHashonconfig.set,config.apply, orconfig.patch. - If the file changed since that read, the RPC returns
INVALID_REQUEST(config changed since last load; re-run config.get and retry).
gateway tool does not fetch a hash for you. Missing baseHash fails closed.
Default-deny whole-document apply
gateway.config_apply default: denied for non-sandbox agents.
The gateway tool stays available. Reads, config.patch, restart, and update.run are not default-denied. Prefer tools.alsoAllow: ["gateway.config_apply"]. A restrictive tools.allow must include gateway (or a whole-tool glob) plus gateway.config_apply. Bare * does not re-enable apply.
tools.deny: ["gateway.config_apply"] keeps apply blocked even if alsoAllow lists it.
This change takes effect immediately (hot-reload).
Secret-preserving writes
Startup writes (activation migration, bundled reconcile, Control UI origin seed) restore object-form SecretRefs (source: "env" | "file" | "exec") and ${VAR} string refs. An ephemeral runtime gateway auth token generated for this process is stripped before persist.
After those writes, ~/.openclaw/openclaw.json still contains refs, not resolved plaintext. Persist a token on purpose with wednesdayai config set gateway.auth.mode token and wednesdayai config set gateway.auth.token <token>.
See Secrets management.
Rate limits
Control-plane write RPCs (config.apply, config.patch, update.run) are limited to 3 requests per 60 seconds per deviceId+clientIp. When limited, the RPC returns UNAVAILABLE with retryAfterMs.
Troubleshooting
Write returnsINVALID_REQUEST with details.code: CONFIG_WRITE_REFUSED
The payload dropped one or more top-level keys that the request did not name. The on-disk file is unchanged. Either keep those keys in the document, or list them in allowTopLevelKeyRemoval. Gateway log: Config write refused: <path> (...).
Agent says apply is denied (Gateway tool action denied by policy: gateway.config_apply)
Expected on a default install. Use config.patch for surgical edits, or add tools.alsoAllow: ["gateway.config_apply"] if you truly need whole-document replace. Do not set tools.allow: ["gateway.config_apply"] alone — the whole gateway tool must stay allowed.
config base hash required or config changed since last load
Re-run config.get and retry with the new hash. Do not omit baseHash when a config file exists.
Older build already truncated the file
Run wednesdayai doctor: when the config is invalid it offers to restore the newest valid backup (details). Or restore ~/.openclaw/openclaw.json.bak by hand, then restart:
Related
- Configuration (task-oriented setup and RPC examples)
- Configuration reference (
tools.allow/tools.alsoAllow) - Tools (gateway tool actions)
- Security
- Config writes (developer)
- Changing settings
- Control UI v2