工作区访问

介绍 workspaceAccess 向沙箱暴露了哪些内容、角色必需沙箱如何限制它，以及技能如何镜像到沙箱工作区。

工作区访问¶

agents.defaults.sandbox.workspaceAccess 控制沙箱可以看到的内容：

对于角色必需沙箱，OpenClaw 会将配置的 rw 工作区访问上限限制为 ro，并记录 agent/sandbox 警告。来宾会保留独立的沙箱 工作区，而共享的 agent 工作区仅以只读 挂载方式可用。这可防止来宾共享可写的 agent 工作区；none 和 ro 保持不变。没有角色必需沙箱的会话保留其 配置的工作区访问。

受管项目工作区¶

拥有会话自有受管 worktree 的沙箱会话在 Docker 和 Podman 上使用私有 Git 检出。当通过 worktree: true 选择已注册项目时，该项目可能位于 agent 配置的工作区之外。这仅授权 源准备，而不是直接访问该主机目录。任意外部 cwd 值和直接项目绑定仍受限制。

私有检出仅包含所选源提交，不包含主机共享的 Git 配置、凭据助手、其他分支，或 .worktreeinclude 选中的被忽略文件。来宾准备过程不会运行仓库的主机 setup 脚本。规范的仅源检出、快照和恢复操作使用 命令范围的受信任 Git 配置视图，因此仓库、worktree、全局以及 包含的 filter 程序无法在 Gateway 上执行——即使配置 在准备等待期间发生变化。私有检出打包使用相同的 配置边界，并且不会延迟获取缺失的 Git 对象。如果 源不完整，请通过受信任的主机工作流获取其对象，然后 重试准备。Git 仍拥有已注册的 worktree、 index、HEAD 和快照 refs；普通受信任维护者检出不受影响。 来宾的 Git 命令操作私有元数据。初始非忽略源 路径在来宾执行前被接纳，并保留在投影绑定中。 之后由主机创建的路径只有在主机将其暂存到规范 Git index（git add）后，才会进入现有投影；仅更改忽略规则不会 接纳主机文件，包括新配置的文件。已接纳的源 编辑和来宾创建的文件会继续协调，包括来宾创建 的被忽略文件。源文件名必须是有效 UTF-8；在重试准备前重命名无效的 Git 路径。发布使用相同的接纳边界。 规范恢复快照按现有规则保留主机数据，但 恢复不会将该数据接纳给来宾。使用 会话的受管 GitHub 发布操作来发布已接受更改；主机凭据不会被 复制到沙箱中。运行时拥有的 .openclaw/sandbox-skills 子树 被排除在工作区协调和发布之外；.openclaw 下的其他项目内容 会被保留。其空挂载目标由主机 工作区所有者在容器分配前创建，而技能挂载保持 只读。这也使常规保留清理独立于容器 user-namespace 所有权。

在 none 或 rw 工作区访问下，私有检出可写；显式 ro 仍为只读。这不会使共享的 agent 工作区变为可写。 其他沙箱后端无法使用此本地受管项目投影，并 会附带说明失败，而不是回退到主机执行。

受管 worktree 仍是文件、快照和 发布的规范工作区。OpenClaw 在捕获或应用更改时，会暂停挂载此检出的确切执行和浏览器运行时，在 SQLite 中记录待处理结果和 回滚日志，并仅在结算后恢复。捕获的工作区权限会在文件系统和引擎准备后再次检查，并立即在文件系统命令、 容器创建/启动/设置以及后期浏览器重启之前检查。在准备期间关闭所有者会阻止这些效果，而不是仅事后拒绝。 冲突会保留两个版本，并在解决前阻止进一步 结算。重试或重启会恢复相同的待处理结果。 归档、重置和删除会在退役其运行时之前结算更改； 投影清理遵循现有受管 worktree 快照保留。 已接纳的来宾创建的被忽略文件（包括符号链接）和空目录 通过相同的待处理结果恢复所有者在归档和恢复中保留。这 不会强制将被忽略路径纳入 Git 发布，也不会导入无关的被忽略主机 文件。旧版本会保留该恢复回执但不应用它； 在继续来宾工作前返回到支持版本。

在使用 OpenShell 后端时，mirror 模式在 exec 轮次之间仍使用本地工作区作为规范源，remote 模式在初始种子后使用远程 OpenShell 工作区作为规范。相同的访问规则适用：none 允许私有工作区写入，而 ro 禁用写入。

传入媒体会被复制到活动沙箱工作区（media/inbound/*）。

本地容器挂载和沙箱文件工具会强制执行这些只读根目录。 SSH 和 OpenShell shell 执行依赖于远程主机或 OpenShell 策略 来实施文件系统限制；仅 workspaceAccess 不会使远程 shell 路径变为只读。