OpenClaw operator scopes

Every gateway WebSocket client connects with a role, operator or node, and every operator method then checks a scope. The scope page is the map of that second gate: what each scope means, how named roles cap them, how a verified identity earns them, and why approving someone else's access never grants more than you hold yourself. It is also explicit that none of this is tenant isolation.

Roles and scope levels

• operator is the control-plane role for the CLI, the Control UI, automation and trusted helpers, node the capability-host role for macOS, iOS, Android and headless hosts exposing commands through node.invoke; operator RPC methods require the operator role and node-originated methods the node role.
• operator.read covers status, lists, catalog, logs, session reads and retained audit diagnostics; operator.write covers sending messages, invoking tools, talk and voice settings and node command relay and also satisfies read; operator.admin satisfies every operator scope and is required for config mutation, updates, native hooks, reserved namespaces and high-risk approvals.
• operator.pairing manages device and node pairing, operator.approvals the exec and plugin approval APIs, operator.questions the interactive questions, operator.talk creates, steers and closes Talk sessions without general write access (write satisfies it too) and operator.talk.secrets reads Talk configuration with secrets; unknown future scopes need an exact match unless the caller already holds admin.
• Personal GitHub connection management is the one self-scoped exception to read-only behaviour: it needs operator.read plus the exact authenticated durable profile, so a person can connect, poll or disconnect only their own account, while system and per-agent GitHub changes stay admin and publication stays write plus session authorization.

Operator scopes gate what a Gateway client can do after it authenticates.

Named roles and identity grants

Team gateways bind authenticated durable profiles to named roles under gateway.roles, each combining four closed policies: access to other people's sessions (none, view, suggest or write), the agents available for session creation and runs (a list, a star or an empty array), a maximum scope set, and whether new sessions require sandboxing. users.setRole assigns a role and immediately closes that profile's connections, gateway.roles.default is required once roles exist, and when roles are configured identity-authenticated operators no longer receive reusable device or bootstrap tokens, because those are not bound to a person. A required sandbox is isolated per session creator, reduces a read-write workspace to read-only with a warning, is stamped immutably with the creator before the first run, is inherited by delegated children, never falls back to the gateway or a node, and cannot be bypassed by elevated mode, exec host overrides or configured host targets. gateway.auth.identityScopes then grants scopes to verified identities from trusted-proxy auth or Tailscale WhoIs, email keys matching case-insensitively; token, password and no-auth connections carry no identity and receive no grant, and node connections never do.

The method gate and what follows it

• Each RPC has a least-privilege method scope derived before dispatch: agent needs write for ordinary turns and admin for new or reset lifecycle commands; node.invoke needs write for ordinary relay and admin when relaying browser proxy, directory listing or terminal upload to a node; sessions.create needs write for ordinary creation and admin for incognito sessions or any execNode; session dispatch and move derive their scope from the target, write for devices and admin for profiles.
• Handlers then apply stricter checks on the concrete thing: device.pair.approve is reachable with pairing but approving an operator device can only mint or preserve scopes the caller already holds, node.pair.approve derives extra scopes from the pending node's declared commands (write for ordinary commands, admin for system.run, browser proxy, directory listing or exec-approval commands), and the config set and unset chat commands need admin on top of chat send.
• Connection authority resolves in order: the x-openclaw-scopes header first caps device enrolment or upgrade requests, a matching server-side identity grant is unioned in, the header then caps the final union (absent means no cap, present but empty means no scopes), and an effective named role intersects the result with its ceiling; the result feeds both hello.auth.scopes and method authorization.

OpenClaw pairing is where these approvals are filed and OpenClaw gateway security controls the wider control set the scopes belong to.

What scopes are not

The page repeats one boundary in several places: scopes are a control-plane guardrail inside one trusted gateway operator domain, not hostile multi-tenant isolation. Named roles organise collaboration within that domain; diagnostic audit methods stay shared-domain read surfaces not filtered by session role; operator.write still authorises gateway-wide tool invocation and node relay; and shared-secret token or password auth is treated as trusted operator access that restores the full default scope set on the OpenAI-compatible surfaces, the tools invoke route and the session-history endpoints even when a caller declares narrower scopes. For strong separation between people, teams or machines, the answer is separate gateways under separate OS users or hosts. OpenClaw sandboxing explained explains the per-creator sandbox a role can require and OpenClaw OpenAI-compatible HTTP API the HTTP surface where the shared-secret rule applies.

On Diali

On Diali each customer runs their own gateway, which is the separation the docs recommend, with the runtime configuration generated from the dashboard and replaced at each release. Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around each runtime.

• Write implies read and talk; admin implies everything.
• Approval never mints scopes the approver lacks.
• Scopes are a guardrail, not tenant isolation; separate gateways are.