操作员范围
操作员作用域控制网关客户端在身份验证后可以执行的操作。 它们是一个受信任网关操作员域内的控制平面护栏, 而不是对抗性多租户隔离。若要在人员、 团队或机器之间实现强隔离,请在不同的操作系统用户或主机下运行独立的网关。
连接角色¶
每个网关 WebSocket 客户端都以一个角色连接:
operator:控制平面客户端,例如 CLI、Control UI、自动化以及 受信任的辅助进程。node:能力主机(macOS、iOS、Android、无头),通过node.invoke暴露命令。
操作员 RPC 方法要求 operator 角色。源自节点的方法
要求 node 角色。
作用域级别¶
| 作用域 | 含义 |
|---|---|
operator.read |
只读状态、列表、目录、日志、会话读取、保留的审计和执行身份诊断,以及其他非变更调用。 |
operator.sessions.read |
读取可见会话、历史记录和会话元数据,而不需要通用网关读取访问权限。 |
operator.sessions.write |
读取可见会话、整理自有会话,并启动或继续已认证用户自己的工作。 |
operator.write |
变更型操作员操作:发送消息、调用工具、更新 talk/voice 设置、节点命令中继。同时满足 operator.read。 |
operator.admin |
管理访问权限。满足所有 operator.* 作用域。配置变更、更新、原生钩子、保留命名空间以及高风险审批所需。 |
operator.pairing |
设备和节点配对管理:列出、批准、拒绝、移除、轮换、撤销。 |
operator.approvals |
执行和插件审批 API。 |
operator.questions |
列出、读取、回答和解决交互式问题。 |
operator.talk |
创建、引导和关闭 Talk 会话,而不需要通用网关写入访问权限。operator.write 也满足此作用域。 |
operator.talk.secrets |
读取包含密钥的 Talk 配置。 |
个人 GitHub 连接管理是只读行为的一个狭窄自作用域例外:
users.github.* 需要 operator.read 以及精确的已认证持久配置。该用户只能连接、轮询、取消、
重连或断开自己的账户。这些方法不会暴露团队密钥、修改共享配置,
或授予 OpenClaw 写入/管理作用域。系统和每个代理的 GitHub 更改仍需要 operator.admin。
会话作用域读取者可以通过 sessions.github.options 和
sessions.github.status 读取其可查看会话的共享 GitHub 发布选项和回执。对于这些受限调用者,
仅当会话具有当前受管理的 worktree 或具有受支持 GitHub 远程的仓库工作区时,
共享发布选项才可用。正向 worktree 目标发现最多复用已验证的 Git 元数据 15 秒;
每次请求都会检查 worktree 所有权、注册表变更和会话访问权限。发布时总会再次解析当前 Git 远程。
不可用的目标不会隐藏现有共享回执。在受管理工作区更改后,重新打开聊天或重新连接以刷新其选项。
个人账户发现和个人回执仍需要 operator.read 和已认证所有者。在返回等待的读取之前,
会重新检查身份、角色、访问授权、连接和会话可见性。
使用 operator.sessions.write 时,请求者可以通过共享 GitHub 账户发布其创建的会话中的普通更改。
工作流定义更改需要原始请求者当前完整的 operator.write 权限。个人发布也需要 operator.write。
每次发布仍需要当前会话授权。参见 GitHub 连接。
未知的未来 operator.* 作用域需要精确匹配,除非调用者已持有 operator.admin。
operator.sessions.write 包含 operator.sessions.read。广义的 operator.read 也包含会话读取,
而 operator.write 包含两个会话作用域。会话作用域不授予通用诊断、配置更改、
网关范围的工具调用,或上述自有会话共享账户路径之外的发布权限。
会话读取者可以浏览可见对话并接收其更新。Control UI 可以将可见历史复制为 Markdown。 会话写入者可以重命名、置顶、归档或恢复自己现有的对话。在这些授权下, 其他人的可见会话仍为只读,包括共享会话。会话授权从不授权删除或更改现有会话的共享和可见性。 归档会话不会授予删除它的权限。
会话读取者可以使用 sessions.files.list、sessions.files.get 和
sessions.files.assets 访问可见会话工作区内的文件。读取该根目录之外的内容还要求会话的文件工具允许网关主机访问,
并且调用者当前有权在那里开始一轮,包括所有权、共享角色、代理和沙箱检查。此类预览为只读。
canvas.document.preview 也接受会话读取访问权限:它返回调用者的 HTML 和隔离沙箱位置,
而不读取会话数据。存储的 Canvas 文档仍需要通过 canvas.document.view 获得更广泛的读取访问权限。
在 Control UI 中,会话写入者可以使用 新建会话,在自己的对话中发送消息,并停止自己正在运行的活动。他们的模型、effort、fast-mode 和非完全权限选择使用相同的会话授权以及 Gateway 的允许模型目录。完全权限模式、沙箱更改以及对现有会话上下文窗口的更改仍需要管理员访问权限。重新连接会在为其原始运行重放 Stop 之前重新检查当前权限。
自有工作方法(包括消息发送、普通会话创建、恢复和 fork)在其参数不需要管理员访问权限时接受 operator.sessions.write。会话所有权、当前权限、agent 访问权限以及运行时和沙箱要求仍然适用。artifacts.list、artifacts.get 和 artifacts.download API 需要更广泛的 operator.read 范围。
通过 sessions_spawn 启动的隐藏原生子 agent 会使用发起人的会话写入权限,用于其确切拥有的子项及其私有父级完成。子项保留该人员当前的权限、模型策略和所需沙箱。直接 agent RPC 调用保持其现有的更广泛范围要求;复制子会话或运行标识符不会授予启动权限。
RPC、事件和后台工具使用相同的范围规则。具有 operator.write 的延续可以读取其 GitHub 身份和会话状态,而无需另一条交互式消息。会话访问和运行生命周期检查仍然适用。
question.* 对于绑定到调用者自身已准入运行和拥有会话的普通问题也接受 operator.sessions.write。Gateway 从可信运行权限记录该绑定,绝不从调用者提供的会话或运行标识符记录。相同的所有权检查会过滤问题事件和恢复读取。仅会话可见性或成员资格不会授予此访问权限。仅 operator.sessions.read 无法回答问题。无会话问题、秘密提示和其他特权问题工作流保留其现有的 operator.questions 和管理员检查。
命名操作员角色¶
团队 Gateway 可以将经过身份验证的持久配置文件绑定到命名操作员角色。每个角色控制对其他人员会话的访问权限、可用于会话创建和 agent 运行的 agent、操作员范围的最大集合,以及新创建的会话是否需要沙箱。它还可以要求由插件提供的访问策略。
{
gateway: {
roles: {
default: "guest",
assignments: {
byGithubLogin: { octocat: "maintainer" },
},
definitions: {
maintainer: {
sessions: { others: "write" },
agents: ["roboclaw"],
scopes: ["operator.read", "operator.write", "operator.approvals"],
},
guest: {
sessions: { others: "view" },
agents: ["roboclaw"],
scopes: ["operator.sessions.read", "operator.sessions.write"],
sandbox: "required",
},
},
},
},
}
使用管理员范围的 users.setRole Gateway 方法并传入 { profileId, role } 来分配已配置的角色。设置 role: null 以清除分配。分配更改会立即使该配置文件的活跃 Gateway 连接失效并关闭它们。重新连接会应用当前角色和范围上限。如果返回结果失败,已提交的更改仍会使先前的访问权限退役。经过授权的自我降级会在其连接关闭之前收到响应。
使用 gateway.roles.assignments.byGithubLogin 在人员首次登录之前声明分配,或在多个 Gateway 之间共享相同映射。键是 GitHub 登录名,在修剪后不区分大小写进行匹配;格式错误的登录名和重复的规范化登录名会被拒绝。每个映射的角色必须存在于 definitions 中。有效的显式 users.setRole 分配优先,其次是配置文件的缓存已验证主要 GitHub 身份的映射,然后是 gateway.roles.default。没有缓存 GitHub 身份的配置文件永远不会匹配此映射。使用 role: null 清除显式分配后,会再次暴露已配置的映射或默认值。
users.list 将 role 保留为显式分配,并报告带有 roleSource("assigned"、"githubLogin" 或 "default")的 effectiveRole。只要配置了角色,gateway.roles.default 就是必需的,并且必须指定一个现有定义。完全省略 gateway.roles 会使单人部署和共享密钥部署保持不变。
当某个插件必须确认人员的当前访问权限时,将角色的可选 accessPolicyPlugin 设置为确切的插件 ID。例如,Visitor Access 插件要求其受限默认角色具有 accessPolicyPlugin: "visitor-access"。被拒绝的连接会收到 OPERATOR_ACCESS_DENIED 连接错误详情,Control UI 会解释该账户没有访问权限。该要求属于 Gateway 配置,并在插件或其清单缺失、禁用、损坏或仍在启动时保持强制执行。已加载的插件必须返回该人员的当前权限;其他插件的策略无法满足该要求。配置验证允许不可用的插件引用,以便 Gateway 仍可以启动以进行修复。没有此绑定的独立 staff 角色和 Gateway 所有者保留其现有访问权限。恢复所需插件以准入绑定的角色。移除或更改绑定通过下面描述的相同实时角色策略更新生效。
启用实时配置重载后,对 gateway.roles(包括 GitHub 登录分配)和 gateway.auth.identityScopes 的编辑无需重启 Gateway 即可生效。现有 Gateway 客户端会重新连接以接收当前范围上限,但仅限于模型策略的更改(如下所述)以及不改变操作员 WebSocket 登录已解析授权集的 identity-scope 编辑除外。编辑其他登录名或重新排序相同范围会保留该连接、其已接受的运行和排队输入。更改其自身已解析的授权会撤销保留和委托的工作;恢复授权不会恢复原始权限。没有已验证身份、节点连接、HTTP 请求和插件身份验证 cookie 的客户端不会消耗 identity-scope 授权,并且不受这些编辑影响。待处理握手和变更在获取权限之前重新检查策略;已准入的运行保留其正常的完成和取消生命周期,包括当其原始访问策略授权过期或被撤销时取消。
当配置了角色后,经过身份验证的 operator 连接不会获得可复用的 device Token 或 bootstrap Token:这些 Token 未绑定到个人,可能会绕过角色上限。对于 operator Gateway 连接和 HTTP 请求,如果 device Token 或 bootstrap Token 认证没有经过验证的用户身份,将被拒绝。请通过可信代理或另一种受支持的已验证身份重新连接,例如 Tailscale。Node 连接、共享密钥/密码访问,以及未配置角色的 Gateway 保留其现有行为。
对于由其他人创建的会话,sessions.others 支持以下值:
"none":从列表和定向访问中隐藏外部会话,将会话级用量过滤为可见会话,并拒绝 Gateway 范围的usage.cost,因为其聚合值可能包含隐藏会话。"view":允许读取但不允许变更,即使会话在其他方面已共享。"suggest":允许查看以及现有的建议流程。"write":允许参与外部会话。草稿和隐身限制仍然有效。
个人始终拥有自己的会话。显式会话成员身份可以提高特定会话的 "view" 或 "suggest" 访问权限,而已经持有 operator.admin 的连接保留其管理会话访问权限。
设置 agents: "*" 以允许在每个 agent 上创建会话和运行 agent,列出 agent ID 以仅允许这些 agent,或使用空数组以同时禁止两者。
当运行目标为已存在的会话时,允许列表也适用。
Agent 发现功能和 Control UI 的 agent 选择器仅显示调用者角色允许的 agent。空允许列表返回空的 agent 名册;Gateway 的会话路由所有权保持不变。
发现功能不会授予或撤销对现有会话的访问权限:角色的独立会话读取策略仍决定调用者可以读取哪些会话。
Control UI 在加载或重新连接后会等待实时 agent 名册,因此旧浏览器名册无法恢复被当前角色排除的 agent。
设置角色的可选 modelPolicy 以限制其请求使用的模型:
```json5 validate=false // Inside gateway.roles.definitions.guest modelPolicy: { sourceAgent: "shared-agent", deny: ["provider/restricted-*"], }
如果没有 `allow` 覆盖,策略将按顺序遵循该 agent 配置的主模型和回退模型。省略 `sourceAgent` 会使用已配置的系统 agent 或默认 agent,或者唯一的 agent。没有此类源 agent 的多 agent Gateway 必须指定一个源 agent。这会读取现有的 agent 配置;它不会复制模型列表,也不会授予对所有已安装模型的访问权限。
使用 `allow` 集中替换允许集合,使用 `deny` 从任一来源中排除模型。空的 `allow: []` 拒绝所有模型。两个列表都接受精确的 `provider/model` 引用、源 agent 模型设置中的别名,以及尾部通配符,例如 `provider/*`、`provider/family/*` 或 `provider/restricted-*`。其他通配符位置会被拒绝。排除项匹配已解析的身份,因此别名无法绕过它们,且 family 前缀也会排除新配置的 family 成员。
角色策略是额外的上限。现有 agent 规则仍控制手动模型选择。默认可以使用目标 agent 已允许的第一个允许的源模型,无论是手动允许还是通过其配置的主模型和回退链允许。自动重试会在准备 provider 之前过滤该链;空的允许结果会返回错误,而不是扩大访问权限。
启用配置重载后,仅限于现有角色 `modelPolicy` 设置的编辑会在配置事务提交时生效,无需重启 Gateway 或重新连接其客户端。其他角色更改会热应用,并以当前权限重新连接客户端,包括与模型策略编辑组合的情况。禁用配置重载会使当前策略保持有效,直到配置应用恢复。
原始角色上限会跟随排队的工作和子运行。已接受的工作必须同时满足其原始模型上限和当前策略。移除一个源模型会取消其活动的模型请求,并阻止后续使用它的调用,而仍被允许的兄弟模型和不相关工作保留其权限。新请求使用更新后的源选择。直接模型请求、标题预览以及用户调用的模型补全或决策工具应用相同策略。交互式插件运行时尝试在执行受限请求之前,必须证明已精确执行模型策略,无论其凭据由谁提供。目前,内置 OpenClaw 运行时支持这些尝试;未认证的插件运行时(包括 Codex)会以兼容运行时错误拒绝它们。添加策略还会取消在没有策略的情况下启动的未认证工作,包括其前台轮次结束后保留的工作。外层选择的模型不会确定原生运行时实际使用哪个模型。隔离的仅提示补全保留其独立的精确路由契约,并在补全和清理过程中绑定所选模型。
有界的自动元数据、operator 配置的入站媒体预处理,以及主机拥有的执行审批保留其现有服务权限。省略 `modelPolicy` 会保留角色的现有模型访问权限,共享密钥 System 访问保持不变。
没有模型策略的原生 Codex 员工工作,在合格的原生钩子被禁用或不可用时,存在有限的归属情况:先前已接受的不受限制输入与其他工作混合后,可能在其发送者失去授权或变为受限后,继续在接收者的有效权限下运行。直接且无歧义绑定的工作仍遵守撤销。参见[原生模型策略边界](../plugins/codex-harness/routing.md#operator-role-model-permissions)。Visitor Access 需要显式模型策略;其 Codex 运行需要合格的集成。
可选的 `sandbox` 策略默认为 `"inherit"`,它会保留 agent 的已配置沙箱模式。设置 `sandbox: "required"` 会为具有该角色的已认证人员创建的每个新会话启用沙箱,即使 agent 的沙箱模式为 `"off"`。该示例允许维护者在 `roboclaw` 上使用主机执行,同时同一 agent 上由访客创建的会话仍保持沙箱化。
必需沙箱按已认证会话创建者隔离,而不仅仅是按 agent 或按会话隔离。使用同一 agent 的不同访客会获得独立的沙箱环境和工作区。同一访客创建的多个会话会复用该访客的环境和工作区。无论配置的沙箱范围如何,这种按访客划分的边界都适用。如果 agent 配置了 `workspaceAccess: "rw"`,OpenClaw 会将角色必需会话的访问权限降低为 `"ro"`,并记录一条 `agent/sandbox` 警告,防止共享 agent 工作区成为访客之间可写的桥梁。维护者会话以及其他没有角色必需沙箱的会话会保留其配置的范围和工作区访问权限。
Gateway 会在新会话首次运行前,将已认证创建者及其沙箱要求一起记录,涵盖聊天、OpenAI 兼容的 HTTP 端点、Talk、恢复、分叉、检查点分支、cron、出站消息以及派生的子任务。委托的子工作会继承必需父级的原始创建者和沙箱策略,即使角色发生变化。由另一人请求的恢复和分支会使用该人自己的角色,而不是源会话的策略。
必需的创建溯源不可变。角色变更、共享、参与、`sessions.patch`、整条替换、旧版导入以及规范键修复都不能移除或替换现有的必需标记。被阻止的持久化覆盖会发出 `session-sqlite` 警告。使用 [`openclaw logs --follow`](../cli/logs.md) 检查它们。现有未标记会话以及创建者不要求沙箱的新会话会保留其现有行为。
角色要求沙箱的人员无法在现有主机执行会话中启动运行,即使被明确邀请。如果其沙箱后端不可用或配置失败,必需会话会失败。它们绝不会回退到 Gateway 或节点。`/elevated`、`exec` 主机覆盖以及已配置的主机目标无法绕过此限制。
默认情况下,agent 的托管 GitHub 身份不会注入到沙箱执行中:`GH_CONFIG_DIR` 不存在,`GH_TOKEN` 和 `GITHUB_TOKEN` 会被置空。管理员可以设置 `agents.entries.<id>.tools.github.allowInSandbox: true`,以将该 agent 的托管身份暴露给其自身的 Docker 或 Podman 沙箱,包括按创建者隔离的角色必需沙箱。配置文件会以只读方式挂载到 `/openclaw/github`;沙箱命令会收到托管 token 和 Git 作者。生效的 `"shared"` 范围会拒绝此注入,并记录一条指明该 agent 的警告。`openclaw security audit` 会为每个选择加入的 agent 发出警告。有关凭据边界和后端要求,请参阅 [GitHub 身份](config-tools/github-identity.md#sandbox-opt-in)。
角色的 `scopes` 列表会限制通过连接认证、身份授权、配对、范围升级以及已认证的 trusted-proxy HTTP 请求所授予的范围。该上限使用常规范围蕴含关系:`operator.admin` 允许所有 operator 范围,`operator.write` 允许 `operator.read` 和 `operator.talk`。它只过滤现有授权。它不能添加连接尚未收到的范围。该上限会与能力求交集,包括由更宽泛授权隐含的能力。被收窄到只读角色的 write 授权会保留 `operator.read`;被收窄到 write 角色的仅限 admin 授权会保留 `operator.write`。角色不能授予原始凭据未允许的能力,空授权或角色会保持为空。
会话读取和组织使用最后一次成功应用的角色配置。被拒绝的配置重载不会改变这些权限。
这包括插件 HTTP 请求和 WebSocket 升级:在没有 scope 头时,普通 Gateway 认证的插件路由仅以 `operator.write` 开始,然后应用角色上限。因此,只读角色在该路径上会保留 `operator.read`,而空角色不会获得任何运行时范围。Control UI 插件授权会在签名 cookie 中携带已认证配置文件。插件 HTTP 请求会重新应用该配置文件当前的角色上限,并在启用角色时拒绝没有匹配持久身份的授权。仅当该角色应保留管理连接权限时,才显式包含 `operator.admin`。
由管理员证明的[频道身份链接](../concepts/user-model.md#channel-identity-links)还允许发送者从其生效角色的 `operator.admin` 范围继承频道所有者权限。这不需要额外的身份范围授权。当不存在角色时,频道所有权会改用匹配的管理身份范围授权。连接范围授权和上限保持不变。
命名角色适用于已认证的持久配置文件及其经过证明的频道身份。它们在一个受信任的 Gateway 域内组织协作;当需要敌对租户隔离时,它们不能替代独立的 Gateway。诊断审计方法(包括 `audit.run.inspect`)仍然是共享域的 `operator.read` 表面,并且不会按会话角色过滤。同样,`operator.write` 仍然授权 Gateway 范围的操作,例如工具调用、普通节点命令中继以及其他 write 范围的控制平面操作。会话限制不会将该范围变成按人员划分的隔离边界。当互不信任的人员不能共享诊断或控制平面写权限时,请使用独立的 Gateway。
## 身份范围授权 {#identity-scope-grants}
`gateway.auth.identityScopes` 会为来自 trusted-proxy 认证或 Tailscale WhoIs 的已验证用户身份授予 operator 范围:
```json5
{
gateway: {
auth: {
identityScopes: {
"admin@example.com": ["operator.admin"],
"operator@example.com": ["operator.read", "operator.write"],
},
},
},
}
键是经过验证的代理身份或 Tailscale WhoIs 登录名。电子邮件键 不区分大小写进行匹配。非电子邮件身份必须完全匹配。配置验证 会拒绝上述封闭集合之外的作用域名称。
连接权限按以下顺序解析:
- 对于受信任代理的 Control UI 连接,
x-openclaw-scopes首先为设备注册或升级请求设置上限。设备授权随后建立 持久作用域。无设备会话不会贡献任何自声明 作用域。 - OpenClaw 将匹配的服务器端身份授权与这些作用域取并集。
- OpenClaw 将
x-openclaw-scopes作为会话上限应用于最终并集。 缺失该请求头表示没有上限。存在但为空的请求头不产生任何作用域。 - 如果已认证 profile 具有生效的命名 operator 角色, OpenClaw 会将结果与该角色配置的作用域上限取交集。
结果同时用于 hello.auth.scopes 和 Gateway 方法
授权。身份授权仅限会话:它们不会创建或修改
配对记录,也不会请求设备作用域升级。Token、密码和无认证
连接不携带经过验证的身份,也不会获得授权。
身份授权仅适用于 operator 角色连接。node 角色连接永远不会获得它们。
方法作用域只是第一道门禁¶
每个 Gateway RPC 都有一个最小权限方法作用域,用于决定请求 是否到达其处理器。感知参数的方法会在 分发之前推导该作用域,因此授权失败具有一个规范的结构化响应:
agent普通轮次需要operator.write,/new或/reset会话生命周期命令需要operator.admin。node.invoke普通中继命令需要operator.write,中继browser.proxy、browser.proxy.upload.v1、fs.listDir或terminal.upload到节点时需要operator.admin。- 顶层
fs.listDirRPC 对 Gateway 主机请求需要operator.write,当nodeId指向节点时需要operator.admin。其处理器将非管理员的 Gateway 主机浏览限制在已配置的 agent 工作区。 plugins.sessionAction要求具备所选操作requiredScopes中声明的每个作用域。省略或空列表默认为operator.write。operator.write满足operator.read和operator.talk。其他作用域需要精确匹配,或operator.admin。sessions.create接受operator.sessions.write用于普通自有会话创建,包括带有projectId的情况,或更广泛的operator.write作用域。隐身会话和任何execNode请求需要operator.admin。对于非管理员调用者,处理器将cwd限制在已配置的 agent 工作区。projectId不能与cwd或execNode组合使用。environments.list普通清单需要operator.read,当runtimeId请求运行时特定命令资格时需要operator.write。会话放置方法会在模式验证之前根据请求目标推导其作用域:sessions.dispatch对deviceId需要operator.write,对profileId或无目标的cloudWorkers.projectProfiles查找需要operator.admin。sessions.move对 Gateway 或设备目标需要operator.write,对 profile 目标需要operator.admin。abandonSource: true仍为operator.write,但仅在 Gateway 目标下模式有效,且仅对精确的离线设备源运行时有效。sessions.reclaim仍为operator.write。格式错误的 dispatch 参数或格式错误的 move 目标使用operator.write,以便处理器返回精确的模式错误。这三种方法均保留会话所有权、参与关系以及提交时重新验证防护。仅operator.read不能启动、停止或移动会话。云 profile 分配和变更、配对和 Connect 机器、原始environments.create或environments.destroy、隐身会话、直接execNode执行以及任意主机或节点路径仍为operator.admin。worktrees.branches需要operator.write。其处理器将非管理员调用者限制在工作区包含的路径或已注册项目根目录。其他主机路径需要operator.admin。talk.config需要operator.read。includeSecrets: true还需要operator.talk.secrets。talk.client.*、talk.session.*、talk.speak和talk.mode需要operator.talk(或兼容的更广泛operator.write)。sessions.patch和sessions.patchMany接受operator.sessions.write用于自有会话的组织字段、model、agentRuntime、思考级别、快速模式和非完整权限模式。元数据补丁要求存在一个已拥有的会话;它们不能声明未使用的键。广泛的operator.write保留其现有会话访问权限。完整权限模式、沙箱变更、原生运行时同意以及特权或未知字段需要operator.admin。运行时可用性和沙箱检查仍然适用。将所选模型持久化为已配置的 agent 默认值仅限管理员。sessions.delete对于带有受支持字段的仅归档请求需要operator.write,否则需要operator.admin。任何会话作用域都不授权删除。session.reactions.list接受operator.sessions.read或更广泛的读取访问权限,并要求当前会话可见性。session.reactions.set需要operator.write、已识别的作者,以及在会话中发送或建议的权限。仅查看的 operator 角色不能做出反应。
项目 RPC 使用这些作用域:
| 方法 | 所需作用域及附加门禁 |
|---|---|
| 方法 | 所需范围及附加门控 |
|---|---|
projects.list |
operator.sessions.read 或更广泛的读取访问权限;只有满足 operator.write 的调用者才会收到 repoRoot 和 originUrl。 |
projects.add |
operator.write 以及 controlPlaneWrite 方法标志。 |
projects.register、projects.remove |
operator.admin。 |
projects.searchRemote |
operator.read。 |
一些处理器随后会根据被批准或被修改的具体对象应用更严格的检查:
device.pair.approve可通过operator.pairing访问,但批准一个 operator 设备只能签发或保留调用者已经持有的范围。node.pair.approve可通过operator.pairing访问,然后从待处理节点声明的命令列表中派生额外的批准范围。chat.send是写范围方法,但/config set和/config unset聊天命令在此之上还要求operator.admin,无论调用者的聊天发送范围如何。
这让较低范围的 operator 可以执行低风险配对操作,而无需将所有配对批准都限制为仅管理员。
会话变更 RPC 由其协商的 operator 范围授权,独立于连接客户端的 client.id 或 client.mode。客户端身份仍可能影响连接和设备认证策略,但它既不授予也不移除会话变更权限。
audit.run.inspect 有意使用 operator.read。在 Gateway operator 域中,拥有该范围的每个客户端都可能收到保留的执行身份上下文,包括有界的假名化引用和已脱敏的显示标签。operator.read 不是按人员或敌对多租户的隐私边界。必须将此数据隔离的 operator 需要单独的 Gateway 信任域。
设备配对审批¶
设备配对记录是已批准角色和范围的持久来源。已配对设备不会静默获得更广泛的访问权限:请求更广泛角色或更广泛范围的重新连接会创建一个新的待处理升级请求。
一个已连接且具有广泛读取访问权限的受限 Control UI,可以通过 收件箱 > 系统 > 受限访问 > 请求管理员 提交同一待处理请求,而无需尝试更广泛的重新连接。该请求绑定到实时连接上的签名设备身份。批准仍然来自 device.pair.approve,因此需要 operator.pairing 以及对每个请求范围的权限。批准轮换 operator token 后,Gateway 仅将该新 token 返回给该设备的实时等待者。浏览器在重新连接前会存储它。取消等待或在批准前断开连接,将在下次连接时回退到普通配对修复流程。
仅具有 operator.admin 的角色允许 Control UI 的完整 operator 范围请求。仍然需要批准。角色上限本身不会授予设备范围。
超出已认证人员所分配角色上限的请求会被拒绝,而不是排队等待设备批准。Gateway 在批准后、返回 token 前会再次检查当前角色,因此等待期间的角色降级仍会阻止超出角色的结果。Control UI 会显示拒绝信息和管理员指导,而不显示 重试。管理员必须先更改角色。
明确的例外是直接在 Gateway 主机上由 openclaw dashboard 或图形化入门向导签发的具有管理员能力的 Control UI 所有者配置文件。其短期、一次性的引导只有在绑定到同一签名浏览器密钥对时,才能批准全新浏览器的精确封闭范围集,或升级现有受限凭据。通用 Control UI 和 Telegram 移交、移动设置配置文件、共享凭据、本地性以及调用者选择的范围均不享受此例外。
批准设备请求:
- 没有 operator 角色的请求不需要 operator 范围批准。
- 请求非 operator 设备角色(例如
node)需要operator.admin,尽管device.pair.approve本身只需要operator.pairing。 - 请求
operator.read、operator.write、operator.approvals、operator.sessions.read、operator.sessions.write、operator.questions、operator.pairing、operator.talk或operator.talk.secrets需要调用者已经持有该范围,或operator.admin。 - 请求
operator.admin需要operator.admin。 - 没有显式范围的修复请求可以继承现有 operator token 的范围。如果该 token 具有管理员范围,批准仍需要
operator.admin。
非管理员共享密钥和可信代理会话只能批准其自身声明的 operator 范围内的 operator 设备请求。即使这些会话在其他情况下可以使用 operator.pairing,批准非 operator 角色也仅限管理员。
对于配对设备 token 会话,除非调用者具有 operator.admin,否则管理范围仅限于自身:非管理员调用者只能看到自己的配对条目,并且只能批准、拒绝、轮换、吊销或删除自己的设备条目。
节点配对审批¶
node.pair.* 能力批准存储在共享 SQLite 配对存储中的配对设备记录上。Gateway 在启动时一次性将已退役的独立 nodes/paired.json 存储中任何剩余条目迁移到这些记录中。有关详细信息,请参阅 Gateway 配对。
node.pair.approve 从待处理请求的命令列表中派生额外所需范围:
| 已声明的命令 | 所需权限范围 |
|---|---|
| 无 | operator.pairing |
| 普通节点命令 | operator.pairing + operator.write |
system.run, system.run.prepare, system.which, browser.proxy, browser.proxy.upload.v1, fs.listDir, 或 system.execApprovals.get/set |
operator.pairing + operator.admin |
此处,fs.listDir 是通过 node.invoke 中继声明的节点命令,
而不是上文描述的顶层 Gateway RPC。
批准节点声明会记录其命令面。对于 computer.act,
节点仅在本地启用 Computer Control 后才广播该命令面。
一旦配对更新获批,通过 node.invoke 调用它时,
每个操作都需要 write 权限范围,但不需要 admin 权限范围。被归类为
危险或涉及隐私的命令,除配对外,仍需要一条持久的
gateway.nodes.commands.allow 条目。
节点配对建立身份和信任。它不会替代节点自身的
system.run 执行审批策略。
共享密钥身份验证¶
共享网关 token/密码身份验证被视为对该 Gateway 的受信任操作员访问。
OpenAI 兼容的 HTTP 接口、/tools/invoke 以及 HTTP
会话历史端点会为共享密钥 bearer 身份验证恢复完整的默认操作员权限范围集,
即使调用方发送了更窄的已声明权限范围。
携带身份的模式(例如受信任代理身份验证或私有入口 none)
仍可以遵循显式已声明的权限范围。请使用独立的 Gateway 实现真正的信任
边界隔离。
相关¶
- 受信任代理身份验证 — 受信任代理如何提供这些权限范围所附加的操作员身份
- Gateway 协议 — 这些权限范围所授权的方法
- Cloud Workers — worker 调度,其环境和会话调用会针对这些权限范围进行授权
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw