OpenClaw 会话权限模式Session Permission Modes实战指南文件系统边界与 exec 升级审核机制【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文聚焦 OpenClaw Gateway 的会话权限模式Session Permission Modes——一套在单个 agent 会话级别同时约束文件系统访问边界与exec 命令升级审核人的授权机制。阅读本文后你将掌握read-only、guarded、workspace、full四种模式的语义与适用场景理解sessionRoot边界的解析规则、任务中途切换权限的行为差异、委托设置/修复流程中的审批边界以及旧版execSecurity/execAsk协议字段退役后的迁移路径并能在 Control UI 与 CLI 中正确配置和排障。一、会话权限模式是什么一个会话的边界与审核人在 OpenClaw 中**会话权限模式permission mode**决定两件事文件系统边界会话能读写哪些路径。exec 升级审核人escalation reviewer当命令超出快速放行路径时由谁来审核。边界即会话记录的标准sessionRootcanonical root当会话没有记录 root 时则取所选 agent 的标准工作区canonical workspace。模式决定了在边界之内、之外分别可以发生什么。四种模式的官方语义如下表模式文件系统访问exec 升级审核人read-only仅sessionRoot下读取管理性变更工具managed mutation tools被省略无exec 被拒绝guardedsessionRoot下读写人类审核allowlist 快速路径之后workspacesessionRoot下读写LLM 审核allow、deny 或询问人类full不受限的文件系统访问无权限门槛full模式要求调用方具备operator.admin权限其余三种模式仅需operator.write。工具可见性边界上表描述的可见性与 exec 规则仅针对OpenClaw 管理的工具managed tools。原生 harnessnative harness可以在自身权限控制下保留自己的工具面——例如 Codex 的原生工具面由其自身运行时策略管理详见 Codex 运行时策略。即便在full模式下仍有约束必需的工作区根required workspace roots与沙箱限制sandbox restrictions依然约束文件工具此外memory-flush 运行只暴露read和 append-only 的write因此即使在full模式下apply_patch也不可用详见下文 apply_patch 一节与 apply_patch 工具。协议层验证这四种模式在 Gateway 协议中是一个封闭联合类型。见 sessions-row.tsexport const SessionPermissionModeSchema Type.Union([ Type.Literal(read-only), Type.Literal(guarded), Type.Literal(workspace), Type.Literal(full), ]);同时SessionRowSchema在会话行上持久化了permissionMode、permissionModePending切换尚未落定时为 true以及sessionRoot三个字段见 sessions-row.ts创建会话的请求体上permissionMode也是可选字段见 sessions-create.ts。这意味着权限模式是会话级的持久状态而非单次运行参数。二、四种模式的纵深解析2.1read-only只读边界exec 被拒绝read-only是最严格的模式文件工具只能在sessionRoot之下读取OpenClaw 管理的变更类工具被整体省略omitted即 agent 看不到写、编辑、打补丁等变更入口exec 被直接拒绝不存在升级审核路径。该模式适合审计、阅读代码、调试只读场景或作为需要绝对防止副作用的观察者会话使用。2.2guarded人类审核每个越界命令guarded模式允许在sessionRoot内读写但当 exec 命令未命中 allowlist 快速路径时升级审核人固定为人类——即每次越界命令都需要操作员在 OpenClaw 操作员 UI 中审批。它没有 LLM 自动审核环节适合对命令执行有强人工把关要求的场景。2.3workspaceLLM 审核 人类兜底workspace模式的文件系统访问与guarded相同但 exec 升级审核人是LLM 审核器其裁决有三种allow放行该次命令单次有效deny拒绝。此时只把原因返回给 agent不创建人类审批卡片。agent 必须选择实质更安全的替代方案或直接询问用户不得绕过拒绝例如不能通过改写命令规避审核ask请求人类审批。审核失败reviewer failure、超时、无效响应等也会升级为人类审批同一会话连续三次 Gateway 审核器拒绝第三次命令也会升级到人类。此外既有的命令绑定检查command-binding checks与显式人类审批要求仍然生效参见 Exec 模式。审核前的可执行文件绑定Gateway 上由审批背书的命令会在审核前绑定每个已解析命令段的可执行文件并在启动前重新校验受保护的可执行文件protected executables使用解析后的真实路径身份real-path identity绑定可写的可执行文件writable executables额外使用内容哈希绑定。这意味着即使审核已通过若PATH上出现了更靠前的新可执行文件导致解析结果变化已批准的运行也会被拒绝。Node 身份检查覆盖从本地策略评估到派发的全过程但对远端 shell 包装器存在一个审批局限interpreter/runtime 命令详见 Exec approvals 进阶。POSIX 登录/交互式 shell 包装器bash -lc ...这类登录或交互式 shell 包装器会跳过自动审核当绑定成功时如bash -lc printf ok要求人类审批因为其隐式启动文件startup files位于操作数绑定之外。既有的绑定拒绝仍然生效。2.4full不受限访问管理员专属full模式授予不受限的文件系统访问且无 exec 审核人。它需要operator.admin权限是信任该主机、跳过常规审批提示的姿势。仍须注意必需工作区根与沙箱限制继续约束文件工具memory-flush 运行仍只暴露read与 append-onlywrite配置驱动的 exec 策略的收紧approval-file floors仍会作用于未设置模式的会话与所有非full模式详见第六节策略优先级与钳制。三、会话根sessionRoot与默认值边界如何确定任何会话都可以设置权限模式。边界的确定规则如下有记录的sessionRoot该标准路径即文件系统边界显式工作目录explicit working directory与managed worktree各自会固定pin其会话的 root无记录 root在运行准备阶段边界默认取所选 agent 的标准工作区canonical workspace。managed worktree 会话使用 worktree checkout 作为sessionRoot嵌套的工作目录仍是运行时的cwd因此相对路径从该嵌套目录开始解析而文件系统包含containment覆盖整个 checkout。别名识别文件工具识别会话受信任 root 与工作目录的别名aliases包括使用这些别名的绝对路径。但这不会扩展边界指向内部inward的无关外部符号链接仍被拒绝逃逸 root 的符号链接、以及symlink/..形式的原始路径遍历都被拒绝read-only模式下OpenClaw 管理的变更工具保持省略。默认继承未指定模式的新会话包括 managed worktree 会话继承配置的全局或 per-agent 工具/exec 策略。exec 与文件工具设置相互独立tools.exec.mode: full并不会让apply_patch越出工作区——apply_patch默认就是工作区包含workspace-contained。文件设置、会话模式优先级与整 agent worker 默认值见 apply_patch 包含说明。创建 worktree 只固定工作目录不选择权限模式显式设置的模式以及既有会话已保存的模式保持不变。Control UI 权限选择器的 Default 标签逻辑当解析出的 agent exec 姿势posture与某个会话模式匹配时选择器会把 Default 标注为该姿势例如tools.exec.mode: ask且没有更严格的主机审批策略时显示Default (Guarded)。解析过程包含全局设置、agent 覆盖与主机审批下限host approval floors。以下情况保持纯Default标签没有这些设置或沙箱配置默认即为完全访问仅 allowlist 策略非等价的security/ask组合包括ask: alwaysagent 的沙箱配置可能应用于其会话因为有效策略无法在 agent 范围内声明。需要强调这是展示元数据既不是授权决定也不是文件系统访问保证——工具策略仍然生效。选择 Default 会清除会话覆盖但不会把当前显示的模式保存进会话。四、委托设置与修复Delegated Setup and Repair审批如何生效当普通 agent 通过其openclaw工具委托一个持久变更时宿主host会把请求运行的有效权限策略应用到该具体提议操作上Full Access自动应用不弹出审批提示——即使 Full Access 来自配置的默认值而非显式会话模式受限运行restricted runs必须在 OpenClaw 操作员 UI 中由人类审批对话中声称的审批conversational claims of approval绝不授权变更。请求工具会等待人类决定与应用结果。停止运行会取消其待处理审批事后审批无法复活该已停止的运行。仍然适用的约束包括独立的文件系统/沙箱边界工具策略系统 agent 的操作限制宿主还会校验请求运行与已验证的推理路由verified inference route仍然有效交互式设置向导与 agent 交接handoffs仍需要直接的 operator 会话。完整流程见 OpenClaw 操作与审批。五、任务中途更改权限客户端行为与副作用边界从聊天撰写器的Permissions菜单选择模式即可切换。选择器在变更落定期内立即显示所选模式的图标与标签并临时阻止该会话的另一次选择其他客户端在 Gateway 发布更新后的会话后才看到新模式。变更失败时选择器会与权威会话状态协调并显示错误若该状态暂时无法刷新则保留乐观选择直到下次会话更新而不是回退到可能过期的模式。不同运行时的行为差异CodexOpenClaw 中断当前原生 turn 并停止其后端终端然后在同一对话中以新权限继续并插入一条内部的Permission change通知不会重置对话或重放原始请求。OpenClaw 原生运行时在不重启对话的前提下刷新活动工具策略后续工具调用即使用更新后的权限。副作用边界重要安全语义旧权限下的待处理审批被取消而不是被授予更改权限不会撤销已完成的写入或其他副作用已经启动的命令与后台进程不会被回滚。不支持实时更改的场景活动中的 CLI-backed 运行以及整个 agent 都在 worker 上执行worker-turn的运行不支持实时权限更改——OpenClaw 会在保存前拒绝该变更。正确做法是停止任务 → 更改权限 → 在同一会话中继续。仅运行远端命令的 worker 放置remote-exec则遵循其本地运行的 agent 运行时行为。六、策略优先级与钳制Precedence and Clamping6.1 会话级 exec 策略属于权限模式当会话设置了模式会话级 exec 策略由该模式决定未设置时正常的全局或 per-agent 配置生效。/exec security... ask...只应用于当前单条消息并且只能收紧显式会话模式例如在full会话中对本回合执行securitydeny会阻断 exec不能放宽。host与node则属于会话放置默认值session placement defaults参见 Exec 会话覆盖/exec。6.2 旧策略升级迁移升级带旧版会话 exec 策略的 store 之后、恢复会话之前需要运行openclaw doctor --fix——运行时不再读取旧策略。迁移细节缺失的策略值继承分层的全局与 per-agent exec 策略历史沙箱可用性未知时自动主机选择采用更严格的沙箱基础限制性策略迁移时不会把 exec 访问放宽到read-only或guarded既有权限模式保持不变旧版 full-access 策略会被移除并附带通知以便配置生效绝不转换为full权限授予。6.3execSecurity/execAsk字段退役协议 v4 中的拒绝语义已退役的execSecurity与execAsk字段仍存在于协议 v4 的sessions.patch与sessions.patchManyschemas 中见 sessions-patch.ts但包含任一字段包括null的请求都会被拒绝返回INVALID_REQUEST并附带引导请设置permissionModeread-only、guarded、workspace或full或对单次运行使用/exec。这两个字段不再作为运行时会话策略存储。协议变更记录见 gateway-protocol CHANGELOG。6.4full模式的例外与钳制显式full模式是对主机审批文件下限host approval-file floors的管理员授权例外其 OpenClaw exec 策略保持full且审批关闭除非回合级覆盖将其收紧。规则如下审批文件下限继续收紧配置驱动的 exec 策略、未设置模式以及每个非full会话模式收紧 full 会话的security会恢复这些下限仅收紧ask不会恢复沙箱限制与工具 allow/deny 策略保持独立harness 可以把不支持的钳制到兼容的更安全策略元组Codex 还会继续遵守外部强制的requirements.toml约束。6.5 独立控制面沙箱、工具策略与提升式 execelevated exec是互相独立的控制面参见 沙箱 vs 工具策略 vs 提升。七、与tools.exec.mode、apply_patch的关系分清两个模式容易混淆的是会话权限模式本文主题作用于文件系统边界 exec 审核人与tools.exec.mode主机 exec 的审批策略旋钮是两个不同的东西。tools.exec.mode是持久化的主机 exec 策略旋钮每个模式解析为一对security/ask见 Exec 模式tools.exec.modesecurity / ask行为denydeny/offexec 被拒绝allowlistallowlist/off仅 allowlist/安全二进制可运行其余静默拒绝askallowlist/on-missallowlist 匹配直接运行其余询问人类autoallowlist/on-missallowlist 匹配直接运行可审核的未命中由原生审核器给出 allow/deny/askfullfull/off无常规策略提示其中workspace会话模式的 LLM 审核正是把auto模式的审核器复用到了会话级。而guarded则等价于ask姿势的人类审批。在 会话权限模式 中Default (Guarded)标签即来自tools.exec.mode: ask的解析。apply_patch的包含containmenttools.exec.applyPatch.workspaceOnly默认true工作区包含且与tools.exec.mode独立——设置tools.exec.mode: full不会解除 apply_patch 的工作区边界。但显式会话权限模式会覆盖这两个配置设置见 apply_patch 工具full移除其包含guarded与workspace包含 apply_patchread-only省略该工具。八、实践建议与排障路径选择模式时可参照以下决策目标建议模式/配置只读观察、审计会话read-onlyexec 被拒绝允许边界内读写但每个越界命令都需人类审批guarded编码会话需要实用受限访问先 LLM 审核、人类兜底workspace可信主机跳过常规审批提示需operator.adminfull需要跨消息保持策略时使用会话权限模式仅对单条消息收紧时使用/exec security... ask...见 Exec 会话覆盖。切换模式后命令仍提示或失败时逐层检查openclaw approvals get查看生效审批来源openclaw exec-policy show查看最终生效策略见 权限模式主机 exec 模式。升级旧 store 后先运行openclaw doctor --fix并确认客户端不再发送已退役的execSecurity/execAsk字段。记住安全边界对话中的口头审批声明不授权任何委托变更停止运行即取消待审批权限切换不撤销已发生的写入与已启动的进程。相关文档沙箱 vs 工具策略 vs 提升三个独立控制面的对比Exec 工具与模式exec 参数、tools.exec.mode模式表、/exec会话覆盖Exec approvals 进阶绑定、安全二进制与 interpreter/runtime 命令边界apply_patch 工具结构化补丁、workspaceOnly 与会话模式覆盖关系Codex 运行时策略原生 harness 的独立工具面OpenClaw 操作与审批CLI 层面的操作、委托与审批流程协议 schema 定义SessionPermissionModeSchema与SessionRowSchema的permissionMode/sessionRoot字段【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考