From fd2fccbc8ed7b8cc35a451be806249e450570788 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 19 Aug 2026 13:08:34 -0700 Subject: [PATCH] docs(agents): restore the non-default scope for systemAgent ownership (#126431) Live-testing #126377 in a real explicit fleet surfaced an inaccuracy that PR introduced. It dropped 'Other agent-scoped methods do not use this setting as a general default', which is still true: only models.list, models.authStatus, skills.status, and doctor.memory.status opt in, while the generic Gateway resolver in agent-id-shared.ts deliberately does not. Verified against a live gateway and CLI on a three-agent explicit fleet with systemAgent.agentId set: 'openclaw models list', 'openclaw sessions', stored session lookup, and TUI startup all still require an explicit agent. Name those surfaces so operators know where the owner does and does not apply. --- docs/gateway/config-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index 3932c29acd0f..094acb5086a2 100644 --- a/docs/gateway/config-agents.md +++ b/docs/gateway/config-agents.md @@ -588,7 +588,7 @@ Selects the agent whose model and credentials own ambient OpenClaw system work: } ``` -An explicit request `agentId` always wins. Delegated consults with a requesting agent keep that requester as their owner. Surfaces that enumerate or narrow across agents deliberately do not adopt this owner, because silently picking one agent would hide the others: session-store selection (`openclaw sessions`) and `openclaw hooks` status still require `--agent ` (or `--all-agents`). When `systemAgent.agentId` is absent, a sole configured agent resolves implicitly; ambient work in a multi-agent fleet then fails with an actionable error, except queued-delivery recovery, which records the failing delivery and keeps draining the rest of the queue. Upgrade-only ownership lives at `agents.defaults.authInheritance.agentId` for inherited credentials and `agents.defaults.sessionStore.agentId` for retired `main` session rows or unscoped rows in a fixed `session.store`. +An explicit request `agentId` always wins. Delegated consults with a requesting agent keep that requester as their owner. The four reads above opt in individually; other agent-scoped Gateway methods, such as `tools.*`, `commands.*`, chat history, and session-catalog reads, do not use this setting as a general default. Surfaces that pick one agent's view also keep requiring an explicit choice, because silently adopting this owner would hide the other agents: `openclaw sessions` (add `--agent ` or `--all-agents`), `openclaw hooks` status, `openclaw models`, stored session lookup by id, and TUI startup. When `systemAgent.agentId` is absent, a sole configured agent resolves implicitly; ambient work in a multi-agent fleet then fails with an actionable error, except queued-delivery recovery, which records the failing delivery and keeps draining the rest of the queue. Upgrade-only ownership lives at `agents.defaults.authInheritance.agentId` for inherited credentials and `agents.defaults.sessionStore.agentId` for retired `main` session rows or unscoped rows in a fixed `session.store`. ### `agents.defaults.compaction`