Operator scopes 定义了 Gateway 客户端认证后能执行的操作范围，是控制平面安全边界。关键限制：配对审批时，审批者必须持有被审批的 scope 或 operator.admin；非 admin 用户只能管理自己的配对记录。配置入口：通过 CLI 的 openclaw onboard 或 devices 命令进行配对与 scope 分配。

OpenClaw 操作员作用域（Operator Scopes）配置排查

操作员作用域（Operator scopes）决定了 Gateway 客户端在认证后可以执行哪些操作。它是同一受信 Gateway 运营域内的控制平面护栏，并非多租户隔离机制。如果你需要严格隔离不同人员、团队或机器，请在不同的操作系统用户或主机上运行独立的 Gateway。

相关文档：安全、Gateway 协议、Gateway 配对、Devices CLI。

角色（Roles）

Gateway WebSocket 客户端连接时需指定一个角色：

• operator：控制平面客户端，如 CLI、Control UI、自动化脚本和受信辅助进程。
• node：能力宿主，如 macOS、iOS、Android 或无头节点，通过 node.invoke 暴露命令。

Operator 角色的 RPC 方法要求使用 operator 角色；Node 角色的方法要求使用 node 角色。

作用域层级（Scope levels）

作用域（Scope）	含义
operator.read	只读访问：状态、列表、目录、日志、会话读取等非修改型控制平面调用。
operator.write	常规修改型操作：发送消息、调用工具、更新对话/语音设置、节点命令转发。同时满足 operator.read。
operator.admin	管理级别的控制平面访问。满足所有 operator.* 作用域。配置修改、更新、原生钩子、敏感保留命名空间以及高风险审批必须使用此作用域。
operator.pairing	设备与节点的配对管理：列出、批准、拒绝、移除、轮换、撤销配对记录或设备令牌。
operator.approvals	执行（exec）和插件（plugin）批准的 API。
operator.talk.secrets	读取包含机密的 Talk 配置。

未来新增的 operator.* 作用域需要精确匹配才能通过，除非调用者持有 operator.admin。

方法作用域只是第一道门

每个 Gateway RPC 都定义了最小权限的方法作用域（method scope），决定请求能否到达处理程序。某些处理程序还会根据被批准或修改的具体对象执行更严格的审批时检查。

示例：

• device.pair.approve 可用 operator.pairing 访问，但批准操作员设备时，只能创建或保留调用者已持有的作用域。
• node.pair.approve 可用 operator.pairing 访问，然后根据待审批的节点命令列表推导出额外的审批作用域。
• chat.send 通常是 write 作用域的方法，但持久化的 /config set 和 /config unset 命令在命令级别要求 operator.admin。

这种设计允许低权限操作员执行低风险的配对操作，而不必将所有配对审批都限制为仅 admin 可操作。

设备配对审批

设备配对记录是已批准角色和作用域的持久来源。已配对的设备不会静默获得更宽权限：重新连接时如果请求更宽的角色或作用域，会创建一个新的待审批升级请求。

批准设备请求时：

• 不带 operator 角色的请求不需要操作员令牌作用域审批。
• 请求 operator.read、operator.write、operator.approvals、operator.pairing 或 operator.talk.secrets 时，调用者必须持有这些作用域，或持有 operator.admin。
• 请求 operator.admin 时必须持有 operator.admin。
• 修复（repair）请求未指定明确作用域时，可继承已有操作员令牌的作用域。如果已有令牌具有 admin 作用域，审批仍然需要 operator.admin。

对于已配对设备的令牌会话，管理是自我作用域限制的（除非调用者同时持有 operator.admin）：非 admin 调用者只能看到自己的配对记录，只能批准或拒绝自己的待审批请求，只能轮换、撤销或移除自己的设备条目。

节点配对审批

传统的 node.pair.* 使用 Gateway 独立维护的节点配对存储。WebSocket 节点使用 role: node 的设备配对，但审批级别词汇相同。

node.pair.approve 使用待审批请求的命令列表推导出额外必需的作用域：

• 无命令请求：operator.pairing
• 非 exec 节点命令：operator.pairing + operator.write
• system.run、system.run.prepare 或 system.which：operator.pairing + operator.admin

节点配对建立身份和信任，并不替代节点自身的 system.run 执行审批策略。

共享密钥认证

共享 Gateway 令牌/密码认证被视为该 Gateway 的受信操作员访问。对于 OpenAI 兼容的 HTTP 层、/tools/invoke 以及 HTTP 会话历史端点，即使调用者声明了较窄的作用域，也会恢复完整的默认操作员作用域集合（即共享密钥 bearer 认证使用全量作用域）。

身份承载模式（如受信代理认证或私有入口 none）可以仍然遵循显式声明的作用域。如需真正的信任边界隔离，请使用独立的 Gateway。

常见问题

配对审批时提示权限不足怎么办？

检查你当前使用的操作员令牌是否持有审批所需的作用域。例如，批准 operator.admin 请求需要你自身拥有 operator.admin；批准 operator.write 请求需要持有 operator.write 或 operator.admin。非 admin 用户只能管理自己的配对记录，无法跨设备操作。

operator.read 和 operator.write 有什么区别？

operator.read 仅允许只读的控制平面调用（如查看状态、日志）。operator.write 包含 operator.read 的全部权限，并额外允许发送消息、调用工具、修改设置等修改型操作。如果要执行持久化配置变更（如 /config set），则需要 operator.admin。

如何查看当前操作员的作用域？

通过 CLI 执行 openclaw devices list 或 openclaw onboard --status 可以查看当前操作员令牌的已批准作用域。如果使用 Control UI，可在用户设置中查看角色和作用域信息。