openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(sync): mirror docs from openclaw/openclaw@e8f13c625e

Browse Source
This commit is contained in:
openclaw-docs-sync[bot] 2026-05-03 00:41:54 +00:00
parent 43a9701e4c
commit 3eaa2a04f2
7 changed files with 138 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.openclaw-sync/source.json
View File

@ -1,5 +1,5 @@
{
"repository": "openclaw/openclaw",
"sha": "f30dc0aeb4ce87ada1aef40042fda5729951a0bf",
"syncedAt": "2026-05-03T00:07:48.136Z"
"sha": "e8f13c625e3458e8d97fbc1441a23a8ed9e0a536",
"syncedAt": "2026-05-03T00:39:49.253Z"
}

4
docs/cli/devices.md
View File

@ -137,7 +137,9 @@ When you set `--url`, the CLI does not fall back to config or environment creden
## Notes
- Token rotation returns a new token (sensitive). Treat it like a secret.
- These commands require `operator.pairing` (or `operator.admin`) scope.
- These commands require `operator.pairing` (or `operator.admin`) scope. Some
approvals also require the caller to hold the operator scopes that the target
device would mint or inherit; see [Operator scopes](/gateway/operator-scopes).
- `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for
fresh node device pairing only; it does not change CLI approval authority.
- Token rotation and revocation stay inside the approved pairing role set and

16
docs/docs.json
View File

@ -1519,6 +1519,7 @@
"pages": [
"gateway/security/index",
"gateway/security/audit-checks",
"gateway/operator-scopes",
"gateway/sandboxing",
"gateway/openshell",
"gateway/sandbox-vs-tool-policy-vs-elevated"
@ -3006,6 +3007,7 @@
"pages": [
"zh-TW/gateway/security/index",
"zh-TW/gateway/security/audit-checks",
"zh-TW/gateway/operator-scopes",
"zh-TW/gateway/sandboxing",
"zh-TW/gateway/openshell",
"zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -3878,6 +3880,7 @@
"pages": [
"ja-JP/gateway/security/index",
"ja-JP/gateway/security/audit-checks",
"ja-JP/gateway/operator-scopes",
"ja-JP/gateway/sandboxing",
"ja-JP/gateway/openshell",
"ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -4750,6 +4753,7 @@
"pages": [
"es/gateway/security/index",
"es/gateway/security/audit-checks",
"es/gateway/operator-scopes",
"es/gateway/sandboxing",
"es/gateway/openshell",
"es/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -5622,6 +5626,7 @@
"pages": [
"pt-BR/gateway/security/index",
"pt-BR/gateway/security/audit-checks",
"pt-BR/gateway/operator-scopes",
"pt-BR/gateway/sandboxing",
"pt-BR/gateway/openshell",
"pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -6494,6 +6499,7 @@
"pages": [
"ko/gateway/security/index",
"ko/gateway/security/audit-checks",
"ko/gateway/operator-scopes",
"ko/gateway/sandboxing",
"ko/gateway/openshell",
"ko/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -7366,6 +7372,7 @@
"pages": [
"de/gateway/security/index",
"de/gateway/security/audit-checks",
"de/gateway/operator-scopes",
"de/gateway/sandboxing",
"de/gateway/openshell",
"de/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -8238,6 +8245,7 @@
"pages": [
"fr/gateway/security/index",
"fr/gateway/security/audit-checks",
"fr/gateway/operator-scopes",
"fr/gateway/sandboxing",
"fr/gateway/openshell",
"fr/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -9110,6 +9118,7 @@
"pages": [
"ar/gateway/security/index",
"ar/gateway/security/audit-checks",
"ar/gateway/operator-scopes",
"ar/gateway/sandboxing",
"ar/gateway/openshell",
"ar/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -9982,6 +9991,7 @@
"pages": [
"it/gateway/security/index",
"it/gateway/security/audit-checks",
"it/gateway/operator-scopes",
"it/gateway/sandboxing",
"it/gateway/openshell",
"it/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -10854,6 +10864,7 @@
"pages": [
"vi/gateway/security/index",
"vi/gateway/security/audit-checks",
"vi/gateway/operator-scopes",
"vi/gateway/sandboxing",
"vi/gateway/openshell",
"vi/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -11726,6 +11737,7 @@
"pages": [
"nl/gateway/security/index",
"nl/gateway/security/audit-checks",
"nl/gateway/operator-scopes",
"nl/gateway/sandboxing",
"nl/gateway/openshell",
"nl/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -12598,6 +12610,7 @@
"pages": [
"tr/gateway/security/index",
"tr/gateway/security/audit-checks",
"tr/gateway/operator-scopes",
"tr/gateway/sandboxing",
"tr/gateway/openshell",
"tr/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -13470,6 +13483,7 @@
"pages": [
"uk/gateway/security/index",
"uk/gateway/security/audit-checks",
"uk/gateway/operator-scopes",
"uk/gateway/sandboxing",
"uk/gateway/openshell",
"uk/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -14342,6 +14356,7 @@
"pages": [
"id/gateway/security/index",
"id/gateway/security/audit-checks",
"id/gateway/operator-scopes",
"id/gateway/sandboxing",
"id/gateway/openshell",
"id/gateway/sandbox-vs-tool-policy-vs-elevated"
@ -15214,6 +15229,7 @@
"pages": [
"pl/gateway/security/index",
"pl/gateway/security/audit-checks",
"pl/gateway/operator-scopes",
"pl/gateway/sandboxing",
"pl/gateway/openshell",
"pl/gateway/sandbox-vs-tool-policy-vs-elevated"

110
docs/gateway/operator-scopes.md Normal file
View File

@ -0,0 +1,110 @@
---
summary: "Operator roles, scopes, and approval-time checks for Gateway clients"
read_when:
- Debugging missing operator scope errors
- Reviewing device or node pairing approvals
- Adding or classifying Gateway RPC methods
title: "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/security), [Gateway protocol](/gateway/protocol),
[Gateway pairing](/gateway/pairing), [Devices CLI](/cli/devices).
## 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 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.

2
docs/gateway/pairing.md
View File

@ -69,6 +69,8 @@ Notes:
metadata and the latest allowlisted declared command snapshot for operator visibility.
- Approval **always** generates a fresh token; no token is ever returned from
`node.pair.request`.
- Operator scope levels and approval-time checks are summarized in
[Operator scopes](/gateway/operator-scopes).
- Requests may include `silent: true` as a hint for auto-approval flows.
- `node.pair.approve` uses the pending request's declared commands to enforce
extra approval scopes:

3
docs/gateway/protocol.md
View File

@ -211,6 +211,9 @@ Side-effecting methods require **idempotency keys** (see schema).
## Roles + scopes
For the full operator scope model, approval-time checks, and shared-secret
semantics, see [Operator scopes](/gateway/operator-scopes).
### Roles
- `operator` = control plane client (CLI/UI/automation).

2
docs/gateway/security/index.md
View File

@ -92,6 +92,8 @@ Treat Gateway and node as one operator trust domain, with different roles:
- **Gateway** is the control plane and policy surface (`gateway.auth`, tool policy, routing).
- **Node** is remote execution surface paired to that Gateway (commands, device actions, host-local capabilities).
- A caller authenticated to the Gateway is trusted at Gateway scope. After pairing, node actions are trusted operator actions on that node.
- Operator scope levels and approval-time checks are summarized in
[Operator scopes](/gateway/operator-scopes).
- Direct loopback backend clients authenticated with the shared gateway
token/password can make internal control-plane RPCs without presenting a user
device identity. This is not a remote or browser pairing bypass: network