会话权限模式
会话权限模式设定会话的文件系统边界和 exec 升级审查者。边界是会话记录的规范 sessionRoot;若未记录根目录,则为所选代理的规范工作区。该模式决定边界内外可进行的操作。
| 模式 | 文件系统访问 | exec 升级审查者 |
|---|---|---|
read-only |
在 sessionRoot 下读取;受管变更工具被省略 |
无;exec 被拒绝 |
guarded |
在 sessionRoot 下读取和写入 |
允许列表快速路径之后的人工审查 |
workspace |
在 sessionRoot 下读取和写入 |
LLM 审查:允许、拒绝或询问人工 |
full |
不受限制的文件系统访问 | 无 |
这些工具可见性和 exec 规则描述的是 OpenClaw 管理的工具。原生 harness 可以在其权限控制下保留自己的工具面;参见 Codex 运行时策略。
在 full 模式下,必需的工作区根目录和沙箱限制仍会约束文件工具。内存刷新(memory-flush)运行仅暴露 read 和仅追加的 write。
Control UI 文件预览遵循此文件系统边界;打开会话根目录之外的文件还需要当前权限才能在该会话中开始一个回合。
在 workspace 模式下,exec 审查者的拒绝会向代理返回原因,而不会创建人工批准卡片。代理必须选择实质上更安全的替代方案或询问用户;它不得绕过该拒绝。审查者的 ask 裁定和审查失败会请求人工批准。连续三次网关审查者拒绝也会升级给人工处理。现有的命令绑定检查和显式人工批准要求仍然有效;参见 Exec 模式。
网关的批准支持命令会在审查前绑定每个已解析的命令段可执行文件,并在启动前重新检查:受保护的可执行文件仅使用解析后的真实路径标识,而可写可执行文件还使用内容哈希。节点身份检查覆盖从本地策略评估到分发的全过程,并带有一个远程 shell 包装器批准限制。POSIX 登录或交互式 shell 包装器在绑定成功时跳过自动审查并要求人工批准;现有的绑定拒绝仍被拒绝。它们的隐式启动文件不在操作数绑定范围内。
full 需要 operator.admin。其他模式需要 operator.write。
会话根目录与默认值¶
任何会话都可以设置权限模式。当会话记录了 sessionRoot 时,该规范路径就是其文件系统边界。显式工作目录和受管工作树(managed worktree)都会固定其会话的根目录。当未记录根目录时,边界默认为运行准备时所选代理的规范工作区。
受管工作树会话使用工作树检出作为 sessionRoot。嵌套的工作目录仍然是运行时的 cwd,因此相对路径从那里开始,而文件系统隔离涵盖整个检出。
文件工具识别会话可信根目录和工作目录的别名,包括使用这些别名的绝对路径。这不会扩大边界:指向内部的不相关外部符号链接仍然被拒绝,逃逸出根目录的符号链接和原始 symlink/.. 遍历同样被拒绝。在 read-only 模式下,OpenClaw 管理的变更工具仍然被省略。
未指定模式时,新会话(包括受管工作树会话)继承配置的全局或按代理的工具/exec 策略。Exec 和文件工具设置相互独立:即使 tools.exec.mode 为 full,apply_patch 默认仍保持工作区范围内。参见 apply_patch 隔离 了解文件设置、会话模式优先级以及整个代理 worker 的默认值。
创建工作树会固定工作目录,但不会选择权限模式。显式模式以及已在现有会话上保存的模式保持不变。
Control UI 权限选择器在代理的已解析 exec 姿态与会话模式匹配时,会将该姿态标注在 Default 标签上,例如对于 tools.exec.mode: "ask" 且没有更严格的主机批准策略,显示 Default (Guarded)。解析过程包括全局设置、代理覆盖和主机批准下限。如果没有这些设置或沙箱,默认就是完全访问。仅允许列表策略以及不等价的 security/ask 组合(包括 ask: "always")会保留纯 Default 标签。沙箱配置可能应用于其会话的代理也保留纯 Default,因为有效策略无法在代理范围内说明。这是显示元数据,不是授权决定或文件系统访问保证;工具策略仍然适用。选择 Default 会清除会话覆盖;它不会将显示的 mode 保存到会话中。
委派设置与修复¶
当普通代理通过其 openclaw 工具委派持久性更改时,主机将请求运行的生效权限策略应用于所提出的确切操作。Full Access 会自动应用,无需批准提示,即使 Full Access 来自配置的默认值而非显式会话模式。来自消息通道的受限运行会向请求聊天请求批准:在通道支持时为原生批准卡片,否则通过 /approve <id> allow-once|deny 回复。Webchat 和终端运行在 Control UI 或应用中决定,这些应用也可以决定任何聊天的批准。诸如“yes”的自由文本回复绝不会授权该更改。请求工具会等待人工决策和应用结果。停止运行会取消其待处理的批准;之后批准也无法恢复该运行。
独立的文件系统与沙箱边界、工具策略以及系统代理操作限制仍然适用。主机还会检查请求的运行和已验证的推理路由是否仍然有效。交互式设置向导和代理交接仍然需要直接操作员会话。参见 OpenClaw 操作与审批。
任务期间更改权限¶
从聊天编辑器的 执行权限 菜单中选择一个模式。仅图标选择器会在更改生效期间立即显示所选模式的图标,并暂时阻止该会话中的其他选择。其他客户端会在 Gateway 发布更新后的会话后看到该模式。如果更改失败,选择器会与权威会话状态进行协调并显示错误;如果该状态暂时无法刷新,则保留乐观选择,直到针对该会话的新权限读取或更新确认已保存的模式。
- Codex: OpenClaw 会中断当前活动原生轮次并停止其后台终端,然后以新权限和内部 权限更改 通知在同一对话中继续。它不会重置对话或重放原始请求。
- OpenClaw 原生运行时: OpenClaw 会刷新活动工具策略,而不会重启对话。后续工具调用将使用更新后的权限。
来自旧权限的待处理审批将被取消,而不是被授予。更改权限不会撤销已完成的写入或其他副作用。已经启动的命令和后台进程不会被回滚。
由 CLI 支持的活动运行以及整个代理在 worker 上执行的运行(worker-turn)不支持实时权限更改。OpenClaw 会在保存之前拒绝该更改。停止任务,更改权限,然后在同一会话中继续。仅运行远程命令的 worker 部署(remote-exec)遵循其本地运行的代理运行时的行为。
策略优先级与钳制¶
会话范围的 exec 策略属于权限模式。当模式未设置时,应用常规全局或按代理配置。/exec security=... ask=... 仅适用于其消息,并且只能收紧显式会话模式;host 和 node 仍为会话放置默认值。参见 Exec 会话覆盖.
在升级包含旧版会话 exec 策略的存储后恢复会话之前,请运行 openclaw doctor --fix;运行时不再读取该策略。缺失的策略值将继承分层的全局和按代理 exec 策略。当历史沙箱可用性未知时,迁移会使用更严格的沙箱基础进行自动主机选择。限制性策略在迁移时不会将 exec 访问范围扩大到 read-only 或 guarded。现有权限模式保持不变。旧版完全访问策略会附带通知移除,以便配置生效,而不会转换为 full 权限授予。
已弃用的 execSecurity 和 execAsk 字段仍保留在 sessions.patch 和 sessions.patchMany 的协议 v4 模式中。包含任一字段(包括 null)的请求将被拒绝,并返回 INVALID_REQUEST 以及设置 permissionMode(read-only、guarded、workspace 或 full)或针对单次运行使用 /exec 的指引。这两个字段均不会作为运行时会话策略存储。
显式 full 模式是主机审批文件下限的管理员授权例外:除非轮次范围覆盖收紧它,否则其 OpenClaw exec 策略保持 full 且审批关闭。审批文件下限会继续收紧配置驱动的 exec 策略、未设置模式以及所有非 full 会话模式。收紧 full 会话的安全性会恢复这些下限;仅收紧 ask 则不会。沙箱限制和工具允许/拒绝策略保持独立,harness 可以将不支持的模式钳制为兼容的更安全策略元组。Codex 也继续遵循外部强制的 requirements.toml 约束。
关于独立的沙箱、工具策略和提权 exec 控制,请参见 沙箱与工具策略与提权。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw