How to Use OpenClaw Operator Scopes

Operator scopes are OpenClaw’s vocabulary for what a Gateway client may do after authentication. They matter for Control UI, CLI, devices, nodes, approval flows, and HTTP APIs. They are not magic multi-tenant security, but they are essential guardrails inside one trusted operator boundary.

30-second answer

Use operator.read for read-only control-plane calls, operator.write for normal mutating actions, operator.admin for administrative access, operator.pairing for device and node pairing management, operator.approvals for exec/plugin approvals, and operator.talk.secrets for reading Talk config with secrets. Treat shared Gateway token/password auth as trusted operator access.

When this pays off

This matters when a device cannot approve a pairing request, a Control UI action fails with missing scope, a node asks for commands, or an API caller needs narrowed access. For production buyers, scopes show that OpenClaw has internal control-plane discipline, but the docs are honest that separate Gateways are still required for real trust-boundary separation.

Operator runbook

1. Start with the role. Gateway WebSocket clients connect as operator or node. Operator clients include CLI, Control UI, automation, and trusted helper processes. Node clients are capability hosts such as macOS, iOS, Android, or headless machines that expose commands through node.invoke.
2. Map the method to the least-privilege scope. Read-only status, lists, logs, and session reads generally fit operator.read. Sending messages, invoking normal tools, and node command relay fit operator.write. Config mutation, updates, native hooks, sensitive namespaces, and high-risk approvals require operator.admin.
3. Handle pairing as its own permission. operator.pairing covers listing, approving, rejecting, removing, rotating, and revoking pairing records or device tokens. But approval handlers can apply stricter checks depending on what is being approved, especially operator devices or nodes with command surfaces.
4. Treat approvals separately. operator.approvals covers exec and plugin approval APIs. That does not mean every approved action is safe for every caller; approval-time checks and tool policy still matter. Scopes are the first gate, not the whole risk model.
5. Know shared-secret behavior. For shared Gateway token or password auth, the docs say HTTP OpenAI-compatible and /tools/invoke surfaces restore normal full operator defaults even if a caller sends narrower x-openclaw-scopes. Do not rely on that header to shrink a shared secret.
6. Split for real isolation. Operator scopes are guardrails inside one trusted domain. If two people, teams, tenants, or machines should not share delegated tool authority, use separate Gateways and preferably separate OS users or hosts.

Verification

When debugging a missing-scope error, record the client role, requested scopes, auth path, method being called, and approval target. Then test with the narrow scope you expect to work, not just operator.admin. For device upgrades, compare current approved scopes to requested scopes before approving.

Common mistakes

Do not grant operator.admin because it fixes everything. Do not confuse node role with lower risk; a node can expose host-local capabilities. Do not believe sessionKey is authorization. And do not present scopes to customers as tenant isolation when the security docs explicitly describe a single trusted Gateway boundary.

Turn it into a repeatable operating system

The Playbook helps translate scopes into roles humans understand: read-only observer, normal operator, pairing manager, approval owner, admin, and rescue operator. That makes scope decisions reviewable instead of buried inside random device prompts.

Before rollout

Before rollout, map scopes to named operator roles instead of granting them ad hoc. For example, observer gets read, pairing manager gets pairing, release operator gets approvals, and owner gets admin. The map makes device prompts understandable and keeps admin from becoming the default fix. Review it whenever a new HTTP surface, node, or rescue operator is added, and keep the review attached to the same change that introduced the new access path in production.