OpenClaw merged PR #120896, "fix(cli): guard embedded agent state ownership for --local runs", adding a stricter ownership check around openclaw agent --local.
The problem was a cross-process state hole. A local embedded agent turn could run against the same agent SQLite state that a live Gateway already owned. The old guard was a session-write lease, but the PR notes that lease is scheduled for removal and was not the right ownership layer for this problem.
If both processes wrote to the same agent database, a local run and the Gateway could interleave state updates.
What Changed
The CLI now uses the Gateway state-directory lock as the ownership boundary. A new agent-embedded lock role lets openclaw agent --local claim exclusive state ownership while it runs.
When a live Gateway owns the state directory, --local now refuses to start. The failure is intended to be actionable: the PR says the built CLI produced an exit code of 1, wrote no stdout, and printed the remediation on stderr.
When no Gateway is running, the local agent path still works. It takes the state lock for the run and releases it on completion or during SIGINT and SIGTERM unwind.
The change also keeps Gateway identity probes from mistaking the new embedded role for a Gateway. Conversely, if Gateway startup finds an embedded local holder, the error names that holder instead of falsely claiming another Gateway is already running.
Why It Matters
SQLite-backed agent state is only as reliable as the ownership rules around it. OpenClaw has been steadily moving state durability into explicit owners: session stores, recovery stores, worktree registries, and Gateway process locks. This PR applies that same discipline to the local-agent shortcut.
For users, the new behavior is intentionally conservative. A command that might have silently double-written now fails fast. That is mildly less convenient in the moment, but much better than discovering later that two processes wrote overlapping history or session state into the same database.
It also clarifies the operating model:
- Use the Gateway as the live owner of an agent state directory.
- Use
openclaw agent --localwhen the Gateway is not currently owning that state. - Treat concurrent local and Gateway writes as a configuration error, not a best-effort mode.
Validation
The PR reports 40 passing Gateway-lock tests, 100 passing Agent and Gateway command tests with one skipped test, 43 broader agent tests, and a full pnpm build.
It also names follow-up surfaces that were explicitly out of scope, including agent exec --state-dir, the TUI embedded backend, models status --probe, and an attempt-execution session-lease path. That list is useful because it shows the maintainers are narrowing the fix to --local rather than claiming every embedded execution mode has been solved at once.
For OpenClaw operators, PR #120896 is a practical guardrail: the local CLI path now respects the same state ownership reality that the Gateway depends on.