工作区访问

workspaceAccess 向沙箱公开的内容、角色所需的沙箱如何对其进行限制，以及技能如何镜像到沙箱工作区中。

工作区访问

agents.defaults.sandbox.workspaceAccess 控制沙箱可见的内容：

对于需要角色的沙箱，OpenClaw 会限制在 ro 处配置的 rw 工作区访问权限，并记录 agent/sandbox 警告。来宾保留一个单独的沙箱工作区，而共享代理工作区仅作为只读安装可用。这可以防止来宾共享可写代理工作区； none 和 ro 保持不变。没有角色所需的沙箱的会话保留其配置的工作区访问权限。

托管项目工作区

具有会话拥有的托管工作树的沙盒会话在 Docker 和 Podman 上使用私有 Git 签出。当使用 worktree: true 选择注册项目时，该项目可能位于代理的配置工作区之外。这授权准备源代码，而不是直接访问该主机目录。任意外部 cwd 值和直接项目绑定仍然受到限制。

可见子会话将其托管工作树保留为以后的沙箱工作区，包括更新之前创建的会话。

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

私人结帐可通过 none 或 rw 工作区访问权限进行写入；显式 ro 保持只读。这不会使共享代理工作区变得可写。其他沙箱后端无法使用此本地托管项目投影，并且会失败并给出解释，而不是退回到主机执行。

托管工作树仍然是文件、快照和发布的真实来源。 OpenClaw 在捕获或应用更改时暂停安装此签出的确切执行和浏览器运行时，在 SQLite 中记录待处理结果和回滚日志，并仅在结算后恢复。新的 shell 调用和命令准备等待活动检查点释放工作空间，然后再继续；后台命令不会在其整个生命周期内保留该准备租约。在文件系统和引擎准备之后、文件系统命令、容器 creation/start/setup 和后期浏览器重新启动之前，将再次检查捕获的工作区权限。在准备过程中关闭所有者可以防止这些影响，而不是事后才拒绝。停止运行会阻止新命令和文件操作，同时允许其接受的工作区更改以完成检查点。接受的命令清理会保留工作区所有者，直到最终完成，即使在父级退出之后也是如此。结算仍需要原始会话和工作树绑定以及实时网关所有权；替换会话或未解决的检查点故障不能报告为干净停止。冲突会保留两个版本，并在解决之前阻止进一步的解决。重试或重新启动将恢复相同的待处理结果。归档、重置和删除在退出其运行时间之前解决更改；投影清理遵循现有的托管工作树快照保留。接受的来宾创建的忽略文件（包括符号链接）和空目录通过相同的待结果恢复所有者进行存档和恢复。这不会强制忽略的路径进入 Git 发布或导入不相关的忽略的主机文件。旧版本保留恢复收据完好无损，但不应用它；在继续来宾工作之前返回到支持版本。

对于 OpenShell 后端，mirror 模式仍然使用本地工作区作为执行轮次之间的事实来源，而 remote 模式在初始种子之后使用远程 OpenShell 工作区作为事实来源。应用相同的访问规则：none 允许私有工作区写入，而 ro 禁用写入。

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

image_generate、video_generate 和 music_generate 还将本地保存的输出复制到请求沙箱中 media/inbound/ 下的私有、Git 忽略的目录中。工具结果和异步完成报告 Sandbox file 路径，用于后续读取、编辑和 shell 处理。渠道交付仍使用托管原件。每个副本仅限于配置的介质大小限制和 50 MiB 中较小的一个。不会下载仅限远程的视频 URL 进行暂存。如果工作区是只读的或者暂存失败，结果会报告沙盒副本不可用；生成和交付仍然成功。重置或删除请求会话会停止进一步的沙箱复制，并阻止完成传送到替换会话。如果配置重新加载在复制之前更改了沙箱策略、工作区选择或介质大小限制，则暂存会停止并显示相同的警告，而原始文件仍然可用。