Operator scopes

Operator scopes 문서는 OpenClaw 공식 문서(gateway/operator-scopes)를 한국어로 정리한 가이드입니다. Operator roles, scopes, and approval-time checks for Gateway clients 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Operator roles, scopes, and approval-time checks for Gateway clients

한국어 가이드 범위: gateway/operator-scopes 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Roles
Scope levels
Method scope is only the first gate
Device pairing approvals
Node pairing approvals
Shared-secret auth

상세 내용

본문

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.

Roles

Every Gateway WebSocket client connects with one role:

주요 항목:

operator: control-plane clients such as CLI, Control UI, automation, and
node: capability hosts (macOS, iOS, Android, headless) that expose

Scope levels

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

Scope	Meaning
`operator.read`	Read-only status, lists, catalog, logs, session reads, and other non-mutating calls.
`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.secrets`	Reading Talk configuration with secrets included.

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
node.invoke needs operator.write for ordinary relay commands and
talk.config needs operator.read; includeSecrets: true also needs
device.pair.approve is reachable with operator.pairing, but approving an
node.pair.approve is reachable with operator.pairing, then derives extra
chat.send is a write-scoped method, but the /config set and

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 request with no operator role does not need operator scope approval.
A request for a non-operator device role (for example node) requires
A request for operator.read, operator.write, operator.approvals,
A request for operator.admin requires operator.admin.
A repair request with no explicit scopes can inherit the existing operator

Node pairing approvals

Legacy node.pair.* methods use a separate Gateway-owned node pairing store. WS nodes use device pairing (role: node) instead, but the same approval vocabulary applies. See Gateway pairing for how the two stores relate.

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

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.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/operator-scopes
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Operator scopes

핵심 요약

Operator roles, scopes, and approval-time checks for Gateway clients

한국어 가이드 범위: gateway/operator-scopes 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Roles
Scope levels
Method scope is only the first gate
Device pairing approvals
Node pairing approvals
Shared-secret auth

상세 내용

본문

Roles

Every Gateway WebSocket client connects with one role:

주요 항목:

operator: control-plane clients such as CLI, Control UI, automation, and
node: capability hosts (macOS, iOS, Android, headless) that expose

Scope levels

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

Scope	Meaning
`operator.read`	Read-only status, lists, catalog, logs, session reads, and other non-mutating calls.
`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.secrets`	Reading Talk configuration with secrets included.

Method scope is only the first gate

주요 항목:

agent needs operator.write for ordinary turns and operator.admin for
node.invoke needs operator.write for ordinary relay commands and
talk.config needs operator.read; includeSecrets: true also needs
device.pair.approve is reachable with operator.pairing, but approving an
node.pair.approve is reachable with operator.pairing, then derives extra
chat.send is a write-scoped method, but the /config set and

Device pairing approvals

주요 항목:

A request with no operator role does not need operator scope approval.
A request for a non-operator device role (for example node) requires
A request for operator.read, operator.write, operator.approvals,
A request for operator.admin requires operator.admin.
A repair request with no explicit scopes can inherit the existing operator

Node pairing approvals

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

Shared-secret auth

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/operator-scopes
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Operator scopes

핵심 요약

문서 구성

상세 내용

본문

Roles

Scope levels

Method scope is only the first gate

Device pairing approvals

Node pairing approvals

Shared-secret auth

실습 체크리스트

관련 링크

관련 가이드

Operator scopes

핵심 요약

문서 구성

상세 내용

본문

Roles

Scope levels

Method scope is only the first gate

Device pairing approvals

Node pairing approvals

Shared-secret auth

실습 체크리스트

관련 링크

관련 가이드