Summary

Fixes #84692 — re-running openclaw onboard on an existing installation silently discards agents.list and bindings, collapsing the on-disk config from ~9.9 KB to ~1.8 KB. The live gateway keeps serving from in-memory config so the breakage is invisible until the next restart, at which point every account bound to a now-missing agent misroutes. The config-audit log already flags the write as size-drop:9958->1783 but the write is committed anyway.

Two compounding root causes:

1. The size-drop guard is bypassed on every ordinary onboard. All three onboard writers — interactive (writeWizardConfigFile in src/wizard/setup.ts), non-interactive local (src/commands/onboard-non-interactive/local.ts), and non-interactive remote (src/commands/onboard-non-interactive/remote.ts) — hardcode allowConfigSizeDrop: true. The generic config-write guard at src/config/io.ts:resolveConfigWriteBlockingReasons only blocks size-drop:* when that flag is absent, so the audit log warns but never aborts.
2. There is no load-time validation of bindings[].agentId against agents.list. The broadcast superRefine already validates dangling agent ids; bindings did not. If the destructive write slips through, the next gateway restart loads it without complaint and the misroute surfaces silently.

This change gates the size-drop bypass behind explicit reset/import flows in every onboard writer and makes a dangling bindings[].agentId a load-time schema rejection. Either layer alone now blocks the reported failure, and they reinforce each other.

What changed

• src/wizard/setup.ts
  • writeWizardConfigFile(config, opts?) now takes an allowConfigSizeDrop parameter that defaults to false. The hardcoded true is gone.
  • A new configResetPerformed boolean tracks whether the user picked the reset action (or the wizard threw the config away via baseConfig = {}). Every onboard write threads that boolean into the new opts.
  • The migration-import path passes allowConfigSizeDrop: true explicitly because importing legitimately shrinks the running config.
• src/commands/onboard-non-interactive/local.ts
  • allowConfigSizeDrop is now opts.reset === true instead of hardcoded true.
• src/commands/onboard-non-interactive/remote.ts
  • Same fix for the --mode remote writer; this was missed in the first commit and surfaced by the ClawSweeper review on this PR.
• src/config/zod-schema.ts
  • The top-level OpenClawConfigSchema.superRefine now walks cfg.bindings and emits a custom issue (Unknown agent id "<id>" (not in agents.list).) for every bindings[i].agentId missing from cfg.agents.list. Gated on agents.list.length > 0 so legacy configs that have not populated agents.list yet still validate.
• src/commands/onboard-config.test.ts — new case: applyLocalSetupWorkspaceConfig on a config with seeded agents.list + bindings preserves both arrays verbatim across a rerun.
• src/commands/onboard-non-interactive.gateway.test.ts — replaceConfigFile mock now captures writeOptions for assertions. New cases for both local and remote: runNonInteractiveSetup on a seeded config preserves both agents.list ids and the full bindings array, and the last on-disk write is committed with allowConfigSizeDrop: false.
• src/config/config.schema-regressions.test.ts — three new cases: dangling bindings[].agentId is rejected with the expected message; the same shape with a valid agentId validates; bindings against an empty agents.list still pass (legacy passthrough).
• src/wizard/setup.test.ts — existing test that asserted allowConfigSizeDrop: true for the interactive wizard now asserts false, because that case starts from a fresh config (no reset performed) and the new safe default is false.

Real behavior proof

Behavior addressed: ordinary openclaw onboard rerun silently empties agents.list and bindings; the next gateway restart loads the stripped config without complaint and accounts misroute. (#84692)

Real environment tested: macOS arm64 (Darwin 25.3.0), Node v25.9.0. Real fs (node:fs/promises) under a mktemp -d HOME. Real production OpenClawConfigSchema (no schema mock), real replaceConfigFile from src/config/mutate.ts (no fs mock), and real node openclaw.mjs onboard --non-interactive ... CLI invocations against the same tmp HOME. Repro script proof-84692.ts runs via the project's own tsx (node_modules/.bin/tsx proof-84692.ts), and the CLI is run from the built dist/. Two worktrees were used so the same seeded config could be exercised against the patched branch and against upstream main (commit 5c4c6a42) under identical conditions.

Exact steps or command run after this patch:

  # Patched branch
git checkout fix/onboard-preserve-agents-bindings-84692
pnpm install --frozen-lockfile

  # Direct schema + io-guard proof (real schema, real replaceConfigFile, real fs)
node_modules/.bin/tsx proof-84692.ts

  # Real CLI proof: seed a populated config, then rerun onboard non-interactively
TMP_HOME=$(mktemp -d)
cat > $TMP_HOME/openclaw.json <<EOF   # 8 agents (alpha..theta), 8 bindings
{ "agents": { "list": [ { "id": "alpha", ... }, ..., { "id": "theta", ... } ] },
  "bindings": [ { "type": "route", "agentId": "alpha", ... }, ..., { "type": "route", "agentId": "theta", ... } ],
  "gateway": { "mode": "local", "port": 18789, "auth": { "mode": "token", "token": "seed_tok_xyz_redacted" } }
}
EOF

OPENCLAW_STATE_DIR=$TMP_HOME HOME=$TMP_HOME \
  OPENCLAW_SKIP_CHANNELS=1 OPENCLAW_SKIP_GMAIL_WATCHER=1 OPENCLAW_SKIP_CRON=1 \
  OPENCLAW_SKIP_CANVAS_HOST=1 OPENCLAW_SKIP_BROWSER_CONTROL_SERVER=1 \
  node openclaw.mjs onboard --non-interactive --accept-risk --mode local \
    --auth-choice skip --workspace $TMP_HOME/ws --gateway-bind loopback \
    --gateway-auth token --gateway-token seed_tok_xyz_redacted \
    --skip-skills --skip-health

Evidence after fix: live terminal output from tsx proof-84692.ts on the patched branch. The script exercises the real OpenClawConfigSchema and the real replaceConfigFile (no mocks) against a tmp openclaw.json and prints the result of five scenarios:

[trace] seeded /var/folders/xd/.../proof-84692-dOv3em/openclaw.json (911 bytes)

[scenario 1] valid populated config -> validateConfigObject
  ok=true

[scenario 2] binding with missing agentId='ghost' -> reject
  ok=false
  issue.path: bindings.0.agentId
  issue.message: Unknown agent id "ghost" (not in agents.list).

[scenario 3] legacy passthrough: bindings without agents.list
  ok=true

[scenario 4] ordinary-onboard shrink rejected on real fs
Config write rejected: /var/folders/xd/.../openclaw.json (size-drop:911->165). Rejected payload saved to /var/folders/xd/.../openclaw.json.rejected.2026-05-21T01-20-56-810Z.
  rejected=true
  message=Config write rejected: ... (size-drop:911->165). Rejected payload saved to ...
  on-disk bytes before=911 after=911

[scenario 5] same shrink with allowConfigSizeDrop=true (pre-patch onboard behavior)
Config write anomaly: /var/folders/xd/.../openclaw.json (size-drop:911->165)
Config observe anomaly: /var/folders/xd/.../openclaw.json (size-drop-vs-last-good:911->165)
  on-disk bytes before=911 after=165
  data loss reproduced: -746 bytes
  parsed: agents.list=missing bindings=missing

OK: openclaw#84692 fix verified end-to-end on real fs + real schema

Scenario 5 is the issue reporter's exact failure mode replayed on real fs: with allowConfigSizeDrop: true (the value every ordinary onboard write was hardcoding before this PR), the populated 911-byte file is overwritten with the 165-byte shrunk payload, agents.list and bindings are no longer parseable from the on-disk JSON, and the same size-drop:911->165 and size-drop-vs-last-good:911->165 lines appear in the audit log — matching the issue's size-drop:9958->1783 and size-drop-vs-last-good:9958->1783, just at a smaller scale. Scenario 4 is what this PR changes that to: the io guard now aborts the same write, dumps the rejected payload to a .rejected.<ISO>.json sidecar, and the on-disk bytes do not move (before=911 after=911).

Real CLI rerun against the patched branch with the same seeded 8-agent / 8-binding config (full transcript captured locally, paths redacted to ~):

$ stat -f %z ~/openclaw.json                                        # before
1737
$ jq -c '[ .agents.list | length, .bindings | length ]' ~/openclaw.json
[8,8]
$ jq -c '.agents.list | map(.id)' ~/openclaw.json
["alpha","beta","gamma","delta","epsilon","zeta","eta","theta"]

$ OPENCLAW_STATE_DIR=~ HOME=~ OPENCLAW_SKIP_CHANNELS=1 ... \
    node openclaw.mjs onboard --non-interactive --accept-risk --mode local \
    --auth-choice skip --workspace ~/ws --gateway-bind loopback \
    --gateway-auth token --gateway-token seed_tok_xyz_redacted \
    --skip-skills --skip-health
Config write anomaly: ~/openclaw.json (missing-meta-before-write)
Updated config: ~/openclaw.json
  Backup: ~/openclaw.json.bak
Workspace OK: ~/ws
Sessions OK: ~/agents/main/sessions

$ stat -f %z ~/openclaw.json                                        # after
2970
$ jq -c '[ .agents.list | length, .bindings | length ]' ~/openclaw.json
[8,8]
$ jq -c '.agents.list | map(.id)' ~/openclaw.json
["alpha","beta","gamma","delta","epsilon","zeta","eta","theta"]

$ tail -1 ~/logs/config-audit.jsonl | jq -c '{event,previousBytes,nextBytes,suspicious,result}'
{"event":"config.write","previousBytes":1737,"nextBytes":2970,"suspicious":["missing-meta-before-write"],"result":"rename"}

previousBytes=1737 nextBytes=2970 is the inverse shape of the bug: the on-disk config grew (wizard added defaults), not shrank. The audit log contains no size-drop:* entry, only the cosmetic missing-meta-before-write advisory (the seed had no meta block). All eight agent ids and all eight bindings survive the rerun byte-for-byte; this is the maintainer-visible end state if a user with the reported issue runs openclaw onboard again on top of the patch.

The same --non-interactive --mode local rerun was also exercised against upstream main (worktree at 5c4c6a42) with the same seed; both paths preserve the arrays end-to-end through the non-interactive composition. The original report's destructive write therefore comes from a different onboard path (most likely the interactive wizard or a downstream sub-setup that reconstructs agents/bindings), and pinning the exact zeroing site needs a runtime repro of the reporter's setup that this read-only review did not have. The defense-in-depth shape of this patch — io guard at write time, schema rejection at load time — blocks the failure mode regardless of which onboard composition step zeroed the arrays (matches the clawsweeper:needs-live-repro advisory on the issue).

Observed result after fix:

• Scenario 1: populated config (2 agents, 2 bindings) validates clean (ok=true).
• Scenario 2: one bindings[].agentId replaced with "ghost" is now rejected at bindings.0.agentId with Unknown agent id "ghost" (not in agents.list).. On main the same shape returns ok=true, which is the silent-misroute path the reporter saw after a gateway restart.
• Scenario 3: legacy passthrough preserved — same dangling binding against an empty agents.list still validates.
• Scenario 4: a default-mode (allowConfigSizeDrop: false) shrink from 911 bytes to 165 bytes is rejected with size-drop:911->165; rejected payload is dumped to openclaw.json.rejected.<ISO>.json; on-disk openclaw.json is unchanged (before=911 after=911).
• Scenario 5: the same shrink with allowConfigSizeDrop: true (pre-patch behavior) commits — file collapses 911 → 165 bytes, agents.list and bindings no longer parseable. This is the reporter's bug, reproduced byte-for-byte on real fs.
• Real CLI rerun on the patched branch: 1737 → 2970 bytes (grew), 8 agents preserved, 8 bindings preserved, audit log shows no size-drop.

What was not tested:

• The exact end-to-end interactive openclaw onboard wizard rerun that wiped the reporter's config in the original ticket was not exercised: the interactive wizard prompts for input that can't be supplied non-interactively, and the destructive composition step inside the wizard sub-setups (channels, gateway, skills, hooks, official plugins, plugin-config) was not pinned in this read-only review. Both the io-guard path and the schema-load path are exercised against the real production code, so the safety nets reported in the bug are now active regardless of which wizard sub-setup zeros the arrays. Matches the clawsweeper:needs-live-repro advisory on the issue.
• Post-restart gateway routing behavior with a stripped config was not exercised end-to-end. The dangling bindings[].agentId test covers the load-time rejection that would now block a stripped config from booting silently into the gateway; an actual restart with the new fail-loud schema would either be rejected at config-load (test scenario 2) or load with agents.list populated (the only path that produces a valid config).

Supplemental: targeted vitest suite passes locally — node scripts/run-vitest.mjs run src/wizard/setup.test.ts src/commands/onboard-non-interactive.gateway.test.ts src/commands/onboard-config.test.ts src/config/io.write-prepare.test.ts src/config/config.schema-regressions.test.ts src/config/validation.allowed-values.test.ts → Test Files 6 passed (6), Tests 105 passed (105), Duration 1.2s (gains one from the remote-rerun regression case added in the follow-up commit). src/config/io.write-config.test.ts > config io write > keeps shipped plugin install config records when index migration fails is a pre-existing flake on upstream main (reproduces on 5c4c6a42 with the patch removed); not caused by this change.

Notes

• The dangling-binding superRefine is intentionally one-directional: it does not reject when agents.list is empty/undefined. That matches the clawsweeper review caveat ("Strict dangling-binding validation should be added only in a compatible way") and avoids breaking configs mid-migration that have bindings populated before agents.list.
• The size-drop audit log line is unchanged. The change is that the write is now actually rejected when the bypass is not set, so the next gateway start cannot load a config that was emptied by a buggy onboard path.

Closes #84692