Skip to main content

Config writes (developer)

Write RPCs share one contract: removal allowance comes from the request, never from a payload diff. The agent gateway 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 thrown writeConfigFile error)
  • 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.
Do not auto-fill baseHash with a fresh config.get. The hash must be the one the caller actually read.
The shipped agent tool follows the second pattern. It does not forward allowTopLevelKeyRemoval, so even an opted-in apply cannot drop top-level keys.

Action policy tokens

Composition, in order:
  1. Whole-tool gateway must be allowed.
  2. The action token must not be explicitly denied (operator tools.deny or the default-deny list).
  3. Otherwise the action is allowed.
Exact 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 against snapshot.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 write openclaw.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.
  • Config writes
  • Tools
  • ADR 0052 (request-level intent and action policy)
  • scripts/verify-config-write-hardening.sh