The Type 2 Agent Config Page: A Self-Populating Control Panel That Speaks Schema

Type 2 agents -- Reggie and Henry -- run on remote VMs under OpenClaw, and OpenClaw publishes a new minor release roughly every three days. Each release tends to add, rename, or restructure config keys. If you tried to keep a hand-rolled admin page in sync with that, you would lose. The Type 2 Agent CONFIG page in RABS solves it the only way that scales: it does not know about specific settings at all. Each time it loads, it asks each VM "what is your config schema right now?", walks the answer, and renders a row for every settable variable -- titles, descriptions, types, validation hints, and current values, all the way down. When OpenClaw 2026.4.30 adds a new field next week, the page just shows it. No code change, no deploy. That's the design intent and tonight we made it actually work end-to-end.

What the page does

Two VMs, side by side: Reggie on the left, Henry on the right. For each one the page shows:

• A status header: hostname, version, port, RPC reachability, config validity, warnings
• A tabbed body: Overview, Gateway, Agents, Channels, Sessions, Models, Tools & Safety, Automate, Browser & Nodes, Memory, Skills, Security & Secrets, Logging & Diagnostics, Advanced
• One row per schema field, with a description, the current value on each VM, and per-VM apply / dry-run / unset / copy-across buttons

The list of variables is not maintained in RABS. Every time the page loads it asks /api/v1/openclaw/schema, gets back the live JSON-schema document from each VM (it's huge -- think dozens of pages of properties), flattens it into a list of fields, and renders a row for each. So when OpenClaw releases a new version with new knobs, those knobs just appear.

What was broken until tonight

The schema fetch was working fine -- the page knew what slots existed. But the values fetch, which populates each slot's "this is what the VM thinks is set right now" data, was returning empty. Every row showed UNSET regardless of what was actually configured on the VM. That's catastrophic for a control panel: you can see the shape of the system but you can't see its current state, and you can't safely change anything if you don't know where you're starting from.

There were two distinct backend bugs in backend/services/openclaw-control.js, both in the config(targetId) method. We needed both paths to work, because the values endpoint runs them in parallel and merges:

Bug 1: tilde never expanded

The cat-fallback path runs openclaw config file to find the config file path. That returns a literal ~/.openclaw/openclaw.json. Bash does not tilde-expand inside double quotes, so cat "~/.openclaw/openclaw.json" looks for a literal file named ~. The previous code used a case statement and ${F#~/} parameter substitution to strip the leading tilde, but the ~ in the pattern itself was being tilde-expanded by the shell, producing nonsense like:

RESOLVED PATH: ~/.openclaw/openclaw.json
ls: cannot access '~/.openclaw/openclaw.json': No such file or directory

The fix uses sed so the substitution happens textually before bash sees the path:

cat "$(openclaw config file | sed "s|^~|$HOME|")"

The same fix went into backupRemote, which had the same latent issue.

Bug 2: RPC banner breaking JSON parse

The other path uses the gateway's RPC: openclaw gateway call config.get --params '{}'. That returns a JSON document with the parsed config -- but it prints a banner line first:

Gateway call: config.get
{
  "path": "...",
  "exists": true,
  "raw": null,
  "parsed": { ... }
}

Our safeJsonParse(stdout) was choking because stdout starts with text, not {. So the JSON came back as null, the route returned rpc: null, and the page got nothing useful out of either path. The fix strips everything before the first {:

openclaw gateway call config.get --params '{}' 2>&1 | sed -n '/^{/,$p'

Once both paths started returning real data, every value-row on the page populated correctly. No frontend change needed.

The new wrinkle: object-maps

The catalog-trim work in the OpenClaw modernisation post revealed something else. OpenClaw 2026.4.29 added a safety guard:

Error: Refusing to replace agents.defaults.models; it would remove existing
entries: openai/gpt-5.4, openai/gpt-5.4-pro, openai/gpt-5.4-mini.
Use --merge to merge object values or --replace to replace intentionally.

That guard fires on a specific class of field -- object-maps -- where the keys are dynamic identifiers chosen by the user, and the value of every key has the same shape. A few examples Brett will hit:

Path	Stores	Keys are
agents.defaults.models	Model catalog	model IDs like openai/gpt-5.5
auth.profiles	API credential profiles	profile names like openai:default
hooks.internal.entries	Internal hook registrations	hook IDs
env.vars	Environment variable overrides	variable names
channels.modelByChannel	Per-channel model pinning	channel keys
diagnostics.otel.headers	OTel HTTP headers	header names

If you save one of these with fewer keys than were there before, OpenClaw refuses unless you tell it explicitly that you meant to remove things. That makes sense as a safety policy and we did not want the CONFIG page to silently swallow the error and pretend a save worked when it didn't.

The mode-aware save flow

The CONFIG page now understands three save modes and chooses based on what kind of field you're editing:

• strict (default for everything else): the original behaviour. OpenClaw rejects ambiguous shrinks. Used for scalar, array, and fixed-shape object fields.
• merge (default for object-maps): the new JSON is merged into the existing object. Keys you don't include are kept. Used when adding entries, updating entries, or just touching one value inside a map.
• replace (opt-in for object-maps): the new JSON replaces the existing object atomically. Keys missing from your JSON are removed. Used when intentionally shrinking or wiping a map.

To make this idiot-proof (the term Brett used and which I'm reluctantly admitting is correct, because future-Brett will forget what he did tonight), every map field in the page now gets:

1. A bright MAP badge in the field's badge cluster, next to MATCH/DIFFERENT/RESTART/etc.
2. A collapsible "How to edit this dictionary field" panel that explains what an object-map is, shows a worked example of the value-shape (auto-generated from the schema's additionalProperties), and tells you when to leave Replace OFF and when to turn it ON.
3. A per-target Replace mode toggle directly under each editor textarea. Off by default (safer = merge). Turn it on to allow removals.
4. A confirm dialog that goes red and explicitly tells you "Map mode: REPLACE (will remove keys missing from your JSON)" so you can't tick it by accident and miss it.

The first time you click a field that happens to be a map, you see the badge, the help panel is one click away, and the toggle is right there with the editor. Nothing else changes. Scalars, arrays, and fixed-shape objects look and behave exactly like they always did.

Surfacing OpenClaw's own errors

Previously, when OpenClaw rejected a save (refused to replace, validation failure, anything), the page showed a generic warning toast. The actual OpenClaw stderr was buried in the response payload but never surfaced. Now runMutation deep-walks the response payload looking for any stderr or error string and surfaces the deepest message in the toast, so you immediately see things like:

Apply agents.defaults.models: Refusing to replace agents.defaults.models; it would remove existing entries: openai/gpt-5.4. Use --merge to merge object values or --replace to replace intentionally.

The page also still shows the full structured response in the modal so you can dig into what each VM said separately.

How the schema becomes the UI

Worth a moment on the mechanic, because it's pretty. OpenClaw publishes a JSON-schema document describing every key its current version understands, with title, description, type, enum, validation bounds, examples, and nested properties. The backend flattenSchema walker visits every node in that schema, computes a dotted path (agents.defaults.model.primary), and emits a flat field record:

{
  "path": "agents.defaults.models",
  "title": "Model Catalog",
  "description": "Map of model IDs to per-model overrides...",
  "type": "object",
  "isObject": true,
  "isMap": true,
  "mapValueShape": { "alias": "<string>", "reasoning": { "effort": "minimal" } },
  "tab": "Models",
  "accordion": "Model Defaults",
  "restartPolicy": "restart"
}

The frontend takes the flat list, filters by tab, groups by accordion, and renders a row per field. Map detection (isMap) and example-shape generation (mapValueShape) are both new tonight and unlock the help panel. When OpenClaw adds a new field next week, all of this plumbing just lights up for it. We don't need to touch the page.

Quick Reference

Action	What you do
Edit a scalar (e.g. gateway.bindHost)	Type the new value, click Apply. Same as before.
Edit an array (e.g. agents.defaults.model.fallbacks)	Edit the JSON array, click Apply. OpenClaw replaces atomically.
Add or update an entry in a MAP field	Leave Replace OFF. Add or change keys in the JSON, click Apply.
Remove an entry from a MAP field	Tick Replace ON. Remove keys from the JSON, click Apply. Confirm dialog goes red.
Wipe a MAP field	Tick Replace ON, set the JSON to {}, click Apply.
See the value-shape for a MAP field	Click "How to edit this dictionary field" under the field title.
See OpenClaw's actual error	Read the warning toast -- it now contains the deepest stderr from the response.
Trust the page when OpenClaw upgrades	The schema and value endpoints repopulate automatically. New keys appear; removed keys disappear.

The CONFIG page is now what the design wanted from day one: a control panel that knows what slots exist and what's in each slot in real time, on every load, for every version of OpenClaw -- with safety rails for the only class of field where saving rules differ.

-- Reginald