openclaw/docs/gateway/operator-scopes.md

summary, read_when, title

summary	read_when	title
Operator roles, scopes, and approval-time checks for Gateway clients	Debugging missing operator scope errors Reviewing device or node pairing approvals Adding or classifying Gateway RPC methods	Operator scopes

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

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

Roles

Gateway WebSocket clients connect with one role:

• operator: control-plane clients such as CLI, Control UI, automation, and trusted helper processes.
• node: capability hosts such as macOS, iOS, Android, or headless nodes 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, and other non-mutating control-plane calls.
operator.write	Normal mutating operator actions such as sending messages, invoking tools, updating talk/voice settings, and node command relay. Also satisfies operator.read.
operator.admin	Administrative control-plane access. Satisfies every operator.* scope. Required for config mutation, updates, native hooks, sensitive reserved namespaces, and high-risk approvals.
operator.pairing	Device and node pairing management, including listing, approving, rejecting, removing, rotating, and revoking pairing records or device tokens.
operator.approvals	Exec and plugin approval APIs.
operator.talk.secrets	Reading Talk configuration with secrets included.

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

Method scope is only the first gate

Each Gateway RPC has a least-privilege method scope. That method scope decides whether the request can reach the handler. Some handlers then apply stricter approval-time checks based on the concrete thing being approved or mutated.

Examples:

• 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 command list.
• chat.send is normally a write-scoped method, but persistent /config set and /config unset require operator.admin at command level.

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

Device pairing approvals

Device pairing records are the durable source of approved roles and scopes. Already paired devices do not get broader access silently: reconnects that ask for a broader role or broader scopes create a new pending upgrade request.

When approving a device request:

• A request with no operator role does not need operator token scope approval.
• A request for operator.read, operator.write, operator.approvals, operator.pairing, or operator.talk.secrets requires the caller to hold those scopes, or operator.admin.
• A request for operator.admin requires operator.admin.
• A repair request with no explicit scopes can inherit the existing operator token scopes. If that existing token is admin-scoped, approval still requires operator.admin.

For paired-device token sessions, management is self-scoped unless the caller also has operator.admin: non-admin callers see only their own pairing entries, can approve or reject only their own pending request, and can rotate, revoke, or remove only their own device entry.

Node pairing approvals

Legacy node.pair.* uses a separate Gateway-owned node pairing store. WS nodes use device pairing with role: node, but the same approval-level vocabulary applies.

node.pair.approve uses the pending request command list to derive additional required scopes:

• Commandless request: operator.pairing
• Non-exec node commands: operator.pairing + operator.write
• system.run, system.run.prepare, or system.which: operator.pairing + operator.admin

Node pairing establishes identity and trust. It does not replace the 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 and /tools/invoke restore the normal full operator default 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.