Operator scopes

Operator scopes gate what a Gateway client can do after it authenticates. They are a control-plane guardrail inside one trusted Gateway operator domain, not hostile multi-tenant isolation. For strong separation between people, teams, or machines, run separate Gateways under separate OS users or hosts.

Related: Security, Gateway protocol, Gateway pairing, Devices CLI.

Connection roles

Every Gateway WebSocket client connects with one role:

• operator: control-plane clients such as CLI, Control UI, automation, and trusted helper processes.
• node: capability hosts (macOS, iOS, Android, headless) that expose commands through node.invoke.

Operator RPC methods require the operator role. Node-originated methods require the node role.

Scope levels

Scope	Meaning
operator.read	Read-only status, lists, catalog, logs, session reads, retained audit and execution-identity diagnostics, and other non-mutating calls.
operator.sessions.read	Read visible sessions, history, and session metadata without general Gateway read access.
operator.sessions.write	Read visible sessions, organize owned sessions, and start or continue the authenticated person’s own work.
operator.write	Mutating operator actions: sending messages, invoking tools, updating talk/voice settings, node command relay. Also satisfies operator.read.
operator.admin	Administrative access. Satisfies every operator.* scope. Required for config mutation, updates, native hooks, reserved namespaces, and high-risk approvals.
operator.pairing	Device and node pairing management: list, approve, reject, remove, rotate, revoke.
operator.approvals	Exec and plugin approval APIs.
operator.questions	Listing, reading, answering, and resolving interactive questions.
operator.talk	Creating, steering, and closing Talk sessions without general Gateway write access. operator.write also satisfies this scope.
operator.talk.secrets	Reading Talk configuration with secrets included.

Personal GitHub connection management is a narrowly self-scoped exception to read-only behavior: users.github.* requires operator.read plus the exact authenticated durable profile. That person can connect, poll, cancel, reconnect, or disconnect only their own account. These methods do not expose team secrets, mutate shared configuration, or grant OpenClaw write/admin scopes. System and per-agent GitHub changes remain operator.admin.

With operator.sessions.write, a requester can publish ordinary changes from sessions they created through the shared GitHub account. Workflow definition changes require the original requester’s current full operator.write authority. Personal publication also requires operator.write. Every publication still requires current session authorization. See GitHub connections.

Unknown future operator.* scopes require an exact match unless the caller already holds operator.admin.

operator.sessions.write includes operator.sessions.read. Broad operator.read also includes session reads, and operator.write includes both session scopes. The session scopes do not grant general diagnostics, configuration changes, Gateway-wide tool invocation, or publication.

Session readers can browse visible conversations and receive their updates. The Control UI can copy visible history as Markdown. Session writers can rename, pin, archive, or restore their own existing conversations. Other people’s visible sessions remain read-only under these grants, including shared sessions. Session grants never authorize deletion or changes to an existing session’s sharing and visibility. Archiving a session does not grant permission to delete it.

In the Control UI, session writers can use New Session, send messages in their own conversations, and stop their own active runs. Their model, effort, fast-mode, and non-full permission choices use the same session grant and the Gateway’s allowed model catalog. Full permission mode, sandbox changes, and changes to an existing session’s context window still require administrator access. Reconnecting rechecks current permission before replaying a Stop for its original run.

Own-work methods, including message sending, ordinary session creation, recovery, and forks, accept operator.sessions.write where their parameters do not require administrator access. Session ownership, current authority, agent access, and runtime and sandbox requirements still apply. The artifacts.list, artifacts.get, and artifacts.download APIs require the broader operator.read scope.

RPCs, events, and background tools use the same scope rules. A continuation with operator.write can read its GitHub identity and session state without another interactive message. Session access and execution-lifetime checks still apply.

question.* also accepts operator.sessions.write for ordinary questions bound to the caller’s own admitted run and owned session. The Gateway records that binding from trusted run authority, never from caller-supplied session or run identifiers. The same ownership check filters question events and recovery reads. Session visibility or membership alone does not grant this access. operator.sessions.read alone cannot answer questions. Sessionless questions, secret prompts, and other privileged question workflows retain their existing operator.questions and administrative checks.

Named operator roles

Team Gateways can bind authenticated durable profiles to named operator roles. Each role controls access to other people’s sessions, agents available for session creation and agent runs, a maximum set of operator scopes, and whether newly created sessions require sandboxing. It can also require an access policy supplied by a plugin.

{
  gateway: {
    roles: {
      default: "guest",
      definitions: {
        maintainer: {
          sessions: { others: "write" },
          agents: ["roboclaw"],
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
        guest: {
          sessions: { others: "view" },
          agents: ["roboclaw"],
          scopes: ["operator.sessions.read", "operator.sessions.write"],
          sandbox: "required",
        },
      },
    },
  },
}

Use the administrator-scoped users.setRole Gateway method with { profileId, role } to assign a configured role. Set role: null to clear an assignment. Assignment changes immediately invalidate and close that profile’s active Gateway connections. Reconnecting applies the current role and scope ceiling. A committed change still retires the previous access if returning the result fails. An authorized self-downgrade receives its response before its connection closes. gateway.roles.default is required whenever roles are configured, must name an existing definition, and applies to profiles without a valid assigned role. Omitting gateway.roles entirely leaves solo and shared-secret deployments unchanged.

Set a role’s optional accessPolicyPlugin to the exact plugin ID when that plugin must confirm the person’s current access. For example, the Visitor Access plugin requires accessPolicyPlugin: "visitor-access" on its restricted default role. The requirement belongs to Gateway configuration and remains enforced when the plugin or its manifest is missing, disabled, broken, or still starting. A loaded plugin must return current authority for the person; another plugin’s policy cannot satisfy the requirement. Configuration validation permits an unavailable plugin reference so the Gateway can still start for repair. Independent staff roles without this binding and the Gateway owner retain their existing access. Restore the required plugin to admit the bound role. Removing or changing the binding applies through the same live role-policy update described below.

With live configuration reload enabled, edits to gateway.roles and gateway.auth.identityScopes apply without restarting the Gateway. Existing Gateway clients reconnect to receive the current scope ceiling, except for changes confined to model policies as described below. Pending handshakes and mutations recheck the policy before acquiring authority; already-admitted runs retain their normal completion and cancellation lifecycle, including cancellation when their original access-policy grant expires or is revoked.

When roles are configured, identity-authenticated operator connections do not receive reusable device or bootstrap tokens: those tokens are not bound to a person and could bypass the role ceiling. Device-token or bootstrap-token authentication without a verified user identity is rejected for operator Gateway connections and HTTP requests. Reconnect through the trusted proxy or another supported verified identity, such as Tailscale. Node connections, shared-secret/password access, and Gateways without role configuration retain their existing behavior.

For sessions created by other people, sessions.others supports these values:

• "none": hides foreign sessions from lists and targeted access, filters session-level usage to visible sessions, and denies Gateway-wide usage.cost because its aggregate can include hidden sessions.
• "view": allows reading but does not allow mutation, even when a session is otherwise shared.
• "suggest": allows viewing and the existing suggestion flow.
• "write": allows participation in foreign sessions. Draft and incognito restrictions remain in force.

A person always owns their own sessions. Explicit session membership can raise "view" or "suggest" access for a specific session, and connections already holding operator.admin retain their administrative session access.

Set agents: "*" to allow session creation and agent runs on every agent, list agent IDs to allow only those agents, or use an empty array to disallow both. The allowlist also applies when a run targets an already-existing session.

Set a role’s optional modelPolicy to limit the models used by its requests:

validate=false

// Inside gateway.roles.definitions.guest
modelPolicy: {
  sourceAgent: "shared-agent",
  deny: ["provider/restricted-*"],
}

With no allow override, the policy follows that agent’s configured primary and fallback models in order. Omitting sourceAgent uses the configured system or default agent, or the sole agent. A multi-agent Gateway without such an owner must name a source agent. This reads the existing agent configuration; it does not copy a model list or grant access to every installed model.

Use allow to replace the permitted set centrally, and deny to exclude models from either source. An empty allow: [] denies all models. Both lists accept exact provider/model references, aliases from the source agent’s model settings, and trailing wildcards such as provider/*, provider/family/*, or provider/restricted-*. Other wildcard placements are rejected. Exclusions match resolved identities, so aliases cannot bypass them and a family prefix also excludes newly configured family members.

The role policy is an additional ceiling. Existing agent rules still govern manual model selection. Default can use the first permitted source model that the target agent already allows manually or through its configured primary and fallback chain. Automatic retries filter that chain before preparing providers; an empty permitted result returns an error instead of widening access.

With config reload enabled, edits confined to existing roles’ modelPolicy settings apply when the config transaction commits, without restarting the Gateway or reconnecting its clients. Other role changes hot-apply and reconnect clients with current authority, including when combined with a model-policy edit. Disabling config reload leaves the current policy active until config application resumes.

The original role ceiling follows queued work and child runs. Accepted work must satisfy both its original model ceiling and the current policy. Removing one source model cancels its active model requests and blocks later calls using it, while still-permitted sibling models and unrelated work retain their authority. New requests use the updated source choices. Direct model requests, title previews, and user-invoked model completion or decision tools apply the same policy. Interactive plugin runtime attempts must certify exact model-policy enforcement before they can execute restricted requests, regardless of who supplies their credentials. Currently the built-in OpenClaw runtime supports these attempts; uncertified plugin runtimes, including Codex, refuse them with a compatible-runtime error. Adding a policy also cancels uncertified work that started without one, including retained work after its foreground turn finishes. An outer selected model does not establish which model a native runtime actually uses. Isolated prompt-only completions keep their separate exact-route contract and bind the selected model through completion and cleanup.

Bounded automatic metadata, operator-configured inbound media preprocessing, and host-owned execution approval keep their existing service authority. Omitting modelPolicy preserves the role’s existing model access, and shared-secret System access is unchanged.

Native Codex staff work without a model policy has a limited attribution case when qualified native hooks are disabled or unavailable: previously accepted unrestricted input mixed with other work may continue under the receiver’s valid authority after its sender loses authorization or becomes restricted. Direct and otherwise unambiguously bound work still observes revocation. See the native model-policy boundary. Visitor Access requires an explicit model policy; its Codex runs require the qualified integration.

The optional sandbox policy defaults to "inherit", which keeps the agent’s configured sandbox mode. Set sandbox: "required" to sandbox every new session created by an authenticated person with that role, even when the agent’s sandbox mode is "off". The example lets maintainers use host execution on roboclaw while guest-created sessions on the same agent remain sandboxed.

Required sandboxes are isolated per authenticated session creator, not merely per agent or per session. Different guests using the same agent receive separate sandbox environments and workspaces. Multiple sessions created by the same guest reuse that guest’s environment and workspace. This per-guest boundary applies regardless of the configured sandbox scope. If the agent configures workspaceAccess: "rw", OpenClaw reduces access to "ro" for role-required sessions and logs an agent/sandbox warning, preventing the shared agent workspace from becoming a writable bridge between guests. Maintainer sessions and other sessions without a role-required sandbox keep their configured scope and workspace access.

The Gateway records the authenticated creator and their sandbox requirement together before a new session first runs, including chat, the OpenAI-compatible HTTP endpoints, Talk, recovery, forks, checkpoint branches, cron, outbound messages, and spawned children. Delegated child work inherits a required parent’s original creator and sandbox policy, even after role changes. Recovery and branching requested by another person use that person’s own role rather than the source session’s policy.

Required creation provenance is immutable. Role changes, sharing, participation, sessions.patch, whole-entry replacement, legacy imports, and canonical-key repair cannot remove or replace an existing required stamp. Blocked persisted overwrites emit a session-sqlite warning. Inspect them with openclaw logs --follow. Existing unstamped sessions and new sessions whose creator does not require sandboxing retain their existing behavior.

A person whose role requires sandboxing cannot start a run in an existing host-execution session, even when explicitly invited. Required sessions fail if their sandbox backend is unavailable or provisioning fails. They never fall back to the Gateway or a node. /elevated, exec host overrides, and configured host targets cannot bypass this restriction. The agent’s managed GitHub identity is not injected into sandboxed execution: GH_CONFIG_DIR is absent, and GH_TOKEN and GITHUB_TOKEN are blanked.

The role’s scopes list caps scopes granted through connection auth, identity grants, pairing, scope upgrades, and authenticated trusted-proxy HTTP requests. The ceiling uses the normal scope implications: operator.admin permits every operator scope, and operator.write permits operator.read and operator.talk. It only filters existing grants. It cannot add scopes the connection did not already receive. The ceiling intersects capabilities, including those implied by a broader grant. A write grant narrowed to a read-only role retains operator.read; an admin-only grant narrowed to a write role retains operator.write. The role cannot grant capabilities that the original credential did not allow, and an empty grant or role remains empty.

Session reads and organization use the last successfully applied role configuration. A rejected configuration reload leaves those permissions unchanged.

This includes plugin HTTP requests and WebSocket upgrades: without a scope header, ordinary Gateway-authenticated plugin routes start with only operator.write, then apply the role ceiling. A read-only role therefore retains operator.read on that path, while an empty role receives no runtime scopes. Control UI plugin grants carry the authenticated profile inside a signed cookie. Plugin HTTP requests reapply the profile’s current role ceiling and reject grants without a matching durable identity when roles are enabled. Include operator.admin explicitly only when that role should retain administrative connection authority.

An administrator-attested channel identity link also lets a sender inherit channel-owner authority from their effective role’s operator.admin scope. This does not require an additional identity-scope grant. When roles are absent, channel ownership uses a matching administrative identity-scope grant instead. Connection scope grants and ceilings are unchanged.

Named roles apply to authenticated durable profiles and their attested channel identities. They organize collaboration within one trusted Gateway domain and do not replace separate Gateways when hostile-tenant isolation is required. Diagnostic audit methods, including audit.run.inspect, remain shared-domain operator.read surfaces and are not filtered by session role. Likewise, operator.write still authorizes Gateway-wide operations such as tool invocation, ordinary node command relay, and other write-scoped control-plane actions. Session restrictions do not turn that scope into a per-person isolation boundary. Use separate Gateways when mutually untrusted people must not share diagnostics or control-plane write authority.

Identity scope grants

gateway.auth.identityScopes grants operator scopes to verified user identities from trusted-proxy auth or Tailscale WhoIs:

{
  gateway: {
    auth: {
      identityScopes: {
        "[e-mail]": ["operator.admin"],
        "[e-mail]": ["operator.read", "operator.write"],
      },
    },
  },
}

The key is the verified proxy identity or Tailscale WhoIs login. Email keys match case-insensitively. Non-email identities match exactly. Config validation rejects scope names outside the closed set above.

Connection authority is resolved in this order:

1. For trusted-proxy Control UI connections, x-openclaw-scopes first caps device enrollment or upgrade requests. Device authorization then establishes the persistent scopes. A device-less session contributes no self-declared scopes.
2. OpenClaw unions a matching server-side identity grant with those scopes.
3. OpenClaw applies x-openclaw-scopes to the final union as the session cap. An absent header means no cap. A present-but-empty header yields no scopes.
4. If the authenticated profile has an effective named operator role, OpenClaw intersects the result with that role’s configured scope ceiling.

The result is used for both hello.auth.scopes and Gateway method authorization. Identity grants are session-only: they do not create or modify pairing records or request a device scope upgrade. Token, password, and no-auth connections carry no verified identity and receive no grant. Identity grants apply only to operator-role connections. node-role connections never receive them.

Method scope is only the first gate

Each Gateway RPC has a least-privilege method scope that decides whether a request reaches its handler. Params-aware methods derive that scope before dispatch so authorization failures have one canonical structured response:

• agent needs operator.write for ordinary turns and operator.admin for /new or /reset session lifecycle commands.
• node.invoke needs operator.write for ordinary relay commands and operator.admin when relaying browser.proxy, browser.proxy.upload.v1, fs.listDir, or terminal.upload to a node.
• The top-level fs.listDir RPC needs operator.write for Gateway-host requests and operator.admin when nodeId targets a node. Its handler limits non-admin Gateway-host browsing to configured agent workspaces.
• plugins.sessionAction requires every scope declared in the selected action’s requiredScopes. Omitted or empty lists default to operator.write. operator.write satisfies operator.read and operator.talk. Other scopes require an exact match, or operator.admin.
• sessions.create accepts operator.sessions.write for ordinary own-session creation, including a projectId, or the broader operator.write scope. Incognito sessions and any execNode request require operator.admin. For non-admin callers, the handler limits cwd to configured agent workspaces. projectId cannot be combined with cwd or execNode.
• environments.list needs operator.read for plain inventory and operator.write when runtimeId requests runtime-specific command eligibility. Session placement methods derive their scope from the requested target before schema validation: sessions.dispatch needs operator.write for deviceId and operator.admin for profileId or a target-less cloudWorkers.projectProfiles lookup. sessions.move needs operator.write for Gateway or device targets and operator.admin for profile targets. abandonSource: true remains operator.write but is schema-valid only with a Gateway target and runtime-valid only for an exact offline device source. sessions.reclaim remains operator.write. Malformed dispatch params or a malformed move target use operator.write so the handler can return the precise schema error. All three methods retain session ownership, participation, and commit-time revalidation fences. operator.read alone cannot start, stop, or move a session. Cloud profile allocation and mutation, pairing and Connect machine, raw environments.create or environments.destroy, incognito sessions, direct execNode execution, and arbitrary host or node paths remain operator.admin.
• worktrees.branches needs operator.write. Its handler limits non-admin callers to workspace-contained paths or registered-project roots. Other host paths require operator.admin.
• talk.config needs operator.read. includeSecrets: true also needs operator.talk.secrets.
• talk.client.*, talk.session.*, talk.speak, and talk.mode need operator.talk (or the compatible broader operator.write).
• sessions.patch and sessions.patchMany accept operator.sessions.write for organization fields, model, agentRuntime, thinking level, fast mode, and non-full permission modes on owned sessions. Metadata patches require an existing owned session; they cannot claim an unused key. Broad operator.write retains its existing session access. Full permission mode, sandbox changes, native runtime consent, and privileged or unknown fields require operator.admin. Runtime availability and sandbox checks still apply. Persisting a selected model as the configured agent default is admin-only.
• sessions.delete requires operator.write for an archived-only request with the supported fields, and operator.admin otherwise. Neither session scope authorizes deletion.

Project RPCs use these scopes:

Method	Required scope and additional gate
projects.list	operator.sessions.read or broader read access; only callers satisfying operator.write receive repoRoot and originUrl.
projects.add	operator.write and the controlPlaneWrite method flag.
projects.register, projects.remove	operator.admin.
projects.searchRemote	operator.read.

Some handlers then apply stricter checks based on the concrete thing being approved or mutated:

• device.pair.approve is reachable with operator.pairing, but approving an operator device can only mint or preserve scopes the caller already holds.
• node.pair.approve is reachable with operator.pairing, then derives extra approval scopes from the pending node’s declared command list.
• chat.send is a write-scoped method, but the /config set and /config unset chat commands require operator.admin on top of that, regardless of the caller’s chat-send scope.

This lets lower-scope operators perform low-risk pairing actions without making all pairing approval admin-only.

Session mutation RPCs are authorized by their negotiated operator scopes, independent of the connecting client’s client.id or client.mode. Client identity can still affect connection and device-auth policy, but it neither grants nor removes session mutation authority.

audit.run.inspect intentionally uses operator.read. Every client with that scope in a Gateway operator domain may receive the retained execution-identity context, including bounded pseudonymized references and secret-redacted display labels. operator.read is not a per-person or hostile multi-tenant privacy boundary. Operators who must keep this data separate need separate Gateway trust domains.

Device pairing approvals

Device pairing records are the durable source of approved roles and scopes. An already-paired device does not get broader access silently: a reconnect that asks for a broader role or broader scopes creates a new pending upgrade request.

A connected limited Control UI with broad read access can file that same pending request through Inbox > System > Limited access > Request admin without attempting a broader reconnect. The request is bound to the signed device identity on the live connection. Approval still comes from device.pair.approve and therefore requires operator.pairing plus authority for every requested scope. After approval rotates the operator token, the Gateway returns the new token only to that device’s live waiter. The browser stores it before reconnecting. Canceling the wait or disconnecting before approval falls back to the ordinary pairing repair flow on the next connection.

A role with only operator.admin permits the Control UI’s full operator scope request. Approval is still required. The role ceiling does not grant device scopes on its own.

Requests outside the authenticated person’s assigned role ceiling are denied, not queued for device approval. The Gateway checks the current role again after approval, before returning the token, so a role demotion during the wait still blocks an out-of-role result. The Control UI shows the denial and administrator guidance without Retry. An administrator must change the role first.

The explicit exception is the administrator-capable Control UI owner profile issued directly on the Gateway host by openclaw dashboard or graphical onboarding. Its short-lived, single-use bootstrap can approve the exact closed scope set for a fresh browser or upgrade an existing limited credential only when it binds to that same signed browser keypair. Generic Control UI and Telegram handoffs, mobile setup profiles, shared credentials, locality, and caller-selected scopes do not receive this exception.

Approving a device request:

• A request with no operator role does not need operator scope approval.
• A request for a non-operator device role (for example node) requires operator.admin, even though device.pair.approve itself only needs operator.pairing.
• A request for operator.read, operator.write, operator.approvals, operator.sessions.read, operator.sessions.write, operator.questions, operator.pairing, operator.talk, or operator.talk.secrets requires the caller to already hold that scope, or operator.admin.
• A request for operator.admin requires operator.admin.
• A repair request with no explicit scopes can inherit the existing operator token’s scopes. If that token is admin-scoped, approval still requires operator.admin.

Non-admin shared-secret and trusted-proxy sessions can only approve operator-device requests within their own declared operator scopes. Approving non-operator roles is admin-only even when those sessions can otherwise use operator.pairing.

For paired-device token sessions, management is self-scoped unless the caller has operator.admin: a non-admin caller sees only its own pairing entries, and can approve, reject, rotate, revoke, or remove only its own device entry.

Node pairing approvals

node.pair.* capability approvals are stored on the paired device record in the shared SQLite pairing store. Gateways migrate any remaining entries from the retired standalone nodes/paired.json store into those records once at startup. See Gateway pairing for details.

node.pair.approve derives extra required scopes from the pending request’s command list:

Declared commands	Required scopes
none	operator.pairing
ordinary node commands	operator.pairing + operator.write
system.run, system.run.prepare, system.which, browser.proxy, browser.proxy.upload.v1, fs.listDir, or system.execApprovals.get/set	operator.pairing + operator.admin

Here, fs.listDir is the node command declared for relay through node.invoke, not the top-level Gateway RPC described above.

Approving a node declaration records its command surface. For computer.act, the node advertises that surface only after Computer Control is enabled locally. Once the pairing update is approved, invoking it through node.invoke requires write scope but not admin scope for each action. Commands classified as dangerous or privacy-heavy still require a persistent gateway.nodes.commands.allow entry in addition to pairing.

Node pairing establishes identity and trust. It does not replace a node’s own system.run exec approval policy.

Shared-secret auth

Shared gateway token/password auth is treated as trusted operator access for that Gateway. OpenAI-compatible HTTP surfaces, /tools/invoke, and HTTP session-history endpoints restore the full default operator scope set for shared-secret bearer auth, even if a caller sends narrower declared scopes.

Identity-bearing modes, such as trusted proxy auth or private-ingress none, can still honor explicit declared scopes. Use separate Gateways for real trust boundary separation.

Related

• Trusted proxy auth — how a trusted proxy supplies the operator identity these scopes attach to
• Gateway protocol — the methods these scopes authorize
• Cloud Workers — worker dispatch, whose environment and session calls are authorized against these scopes