openclaw - 💡(How to fix) Fix `openclaw onboard` re-run discards existing `agents.list` and `bindings` — silent loss of all configured agents

Summary

Re-running openclaw onboard on an existing installation rewrites the config file and discards the existing agents.list and bindings arrays instead of merging or preserving them. The command reports success and exits normally. Every previously configured agent is silently orphaned: the on-disk config collapses from ~9.9 KB to ~1.8 KB.

The running gateway keeps serving from its in-memory config, so the breakage stays invisible until the next gateway restart. At that point the stripped config is loaded, and any account whose bound agent no longer exists in agents.list stops routing to the correct agent.

Notably, OpenClaw's own config-audit log flags the write as suspicious (size-drop), but the write is committed anyway — no block, no prompt, no rollback.

Environment

• OpenClaw 2026.5.12 (commit f066dd2)
• Runtime: claude-cli agent runtime, local gateway mode, systemd-supervised
• Node v22.22.2
• OS: Linux 6.17.0-29-generic (x64)
• Config: ~/.openclaw/openclaw.json
• Audit log: ~/.openclaw/logs/config-audit.jsonl

Minimal reproduction

1. Start from an installation with several configured agents and bindings (config ~9.9 KB).
2. Run openclaw onboard again.
3. Inspect the config: agents.list and bindings are now empty; size collapses to ~1.8 KB.
4. Restart the gateway — accounts bound to now-missing agents misroute.

Captured from config-audit.jsonl:

{"ts":"2026-05-16T19:58:53.694Z","event":"config.write","result":"rename","argv":["node","openclaw","onboard"],"previousBytes":9958,"nextBytes":1783,"suspicious":["size-drop:9958->1783"]}
{"ts":"2026-05-16T19:58:54.709Z","event":"config.observe","argv":["node","openclaw","onboard"],"suspicious":["size-drop-vs-last-good:9958->1783"]}

Backups confirm the loss:

# pre-onboard backup:  agents.list = [ 8 agents ], bindings populated
# post-onboard backup: agents.list = [], bindings = []

Expected vs actual

Expected: onboard on an existing config preserves (merges) existing agents.list and bindings, or at minimum refuses to overwrite without explicit confirmation / --force and writes a restorable backup first.

Actual: Existing agents.list and bindings are silently discarded; the command reports success; the destructive write is detected as suspicious by config-audit but committed regardless.

Impact

• All custom agents are lost from config; multi-agent setups break.
• Failure is delayed and non-obvious: the live gateway keeps working from memory, giving no immediate signal. Breakage surfaces only on the next restart (possibly days later), making root-cause attribution hard.
• After restart, any account whose bound agentId is missing from agents.list stops behaving correctly.

Possibly related sub-bug

When a bindings[] entry references an agentId absent from agents.list, the gateway does not fail loudly at load time (no validation error). Load-time validation of dangling agentId references would have surfaced this immediately.

Suggestions

• Make onboard merge-by-default for agents.list / bindings, or require --force / explicit confirmation to overwrite an existing config.
• Treat config-audit size-drop / size-drop-vs-last-good as actionable: abort the write and/or auto-restore the last-good backup, rather than only logging.
• Add load-time validation of bindings[].agentId against agents.list.

Workaround

Re-add the lost agents and bindings to agents.list / bindings and restart the gateway. A pre-onboard config backup, if present, can be restored directly.

Discovery context

Found after a gateway restart caused an account to route to the wrong agent. Tracing config-audit.jsonl showed agents.list / bindings had been emptied by an earlier openclaw onboard run, flagged as a suspicious size-drop but committed.