Config writes (developer)
Write RPCs share one contract: removal allowance comes from the request, never from a payload diff. The agentgateway tool keeps config.apply, but policy matches action tokens and default-denies whole-document apply.
Operator runbook: Config writes. This page is the client and tool-policy contract.
Request shape
config.set, config.apply, and config.patch accept the same write fields (apply/patch also take restart metadata):
allowTopLevelKeyRemoval is optional on the wire. The handler treats a missing or non-array value as []. Only non-empty trimmed strings are kept.
writeConfigFile refuses a candidate that drops a top-level key not in that list:
- RPC error
code:INVALID_REQUEST details.code:CONFIG_WRITE_REFUSED(same code on the thrownwriteConfigFileerror)- On-disk bytes unchanged (no tmp rename, no backup rotation)
- Message names the blocking risks and tells the caller to pass the exact keys
baseHash is optional in the TypeBox schema. requireConfigBaseHash still requires it whenever the configured config file exists (the default is ~/.openclaw/openclaw.json):
What not to do
Do not derive allowance from the payload. That is the 2026-08-10 failure mode: the guard always saw exactly the keys the suspect document dropped.baseHash with a fresh config.get. The hash must be the one the caller actually read.
allowTopLevelKeyRemoval, so even an opted-in apply cannot drop top-level keys.
Action policy tokens
- Whole-tool
gatewaymust be allowed. - The action token must not be explicitly denied (operator
tools.denyor the default-deny list). - Otherwise the action is allowed.
gateway does not glob-match gateway.config_*. Re-enable apply with tools.alsoAllow: ["gateway.config_apply"], or with a restrictive tools.allow that lists both gateway (or a whole-tool glob) and gateway.config_apply (or a non-all glob such as gateway.config_*). tools.allow: ["gateway.config_apply"] alone fails the whole-tool gate.
Bare * does not override default-deny. alsoAllow without an allowlist synthesizes * for ordinary tools; that implicit allow-all is filtered out before default-deny is waived.
Denied execute throws Gateway tool action denied by policy: gateway.config_apply before any RPC.
config.set is a gateway RPC and Control UI path. It is not a GATEWAY_ACTIONS entry.
Control UI
The console’s config editor diffs the submit document againstsnapshot.parsed ?? snapshot.config (JSON5 in raw mode). It sends allowTopLevelKeyRemoval only when that list is non-empty, including on the drain-confirmed retry.
Keep that helper in sync with src/config/removed-keys.ts ($include is ignored). The UI cannot import the core helper (it pulls node:fs).
Plugins
Do not writeopenclaw.json with raw fs.writeFileSync. Use the existing writeConfigFile path and pass named allowTopLevelKeyRemoval only when your caller explicitly deleted those keys.
These types are core gateway contract, not openclaw/plugin-sdk exports.
Related
- Config writes
- Tools
- ADR 0052 (request-level intent and action policy)
scripts/verify-config-write-hardening.sh