---
summary: "none、ro 和 rw 工作区访问模式、角色所需上限和技能镜像"
title: "工作区访问"
read_when: "您正在决定沙箱可以看到代理工作区的哪些内容。"
---

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

## <a id="workspace-access"></a> 工作区访问

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

| 值            | 行为                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `none`（默认） | 工具可以读写`~/.openclaw/sandboxes`下的隔离沙箱工作区；代理工作区未公开。 |
| `ro`             | 将代理工作区以只读方式挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）。                                 |
| `rw`             | 将代理工作区 read/write 安装在 `/workspace` 处。                                                                    |

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

## <a id="managed-project-workspaces"></a> 托管项目工作区

具有会话拥有的托管工作树的沙盒会话在 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 进行暂存。如果工作区是只读的或者暂存失败，结果会报告沙盒副本不可用；生成和交付仍然成功。重置或删除请求会话会停止进一步的沙箱复制，并阻止完成传送到替换会话。如果配置重新加载在复制之前更改了沙箱策略、工作区选择或介质大小限制，则暂存会停止并显示相同的警告，而原始文件仍然可用。

<Note>
**Skills**：`read` 工具是基于沙箱的。通过 `workspaceAccess: "none"`、OpenClaw 将符合条件的技能镜像到沙箱工作区 （`.../skills`） 作为只读指令根；其他私有工作区文件保持可写。使用 `"rw"`，工作区技能可从 `/workspace/skills` 读取，并且合格的托管、捆绑或插件技能将具体化到生成的只读路径 `/workspace/.openclaw/sandbox-skills/skills` 中。

本地容器挂载和沙箱文件工具强制执行这些只读根。生成的技能副本带有自己的 Git 忽略规则，因此普通的 Git 发现会忽略它们，而跟踪的更改和其他项目文件仍然可见。即使较早的副本继承了只读目录权限，网关也会刷新自己的镜像副本；无需手动权限修复。 SSH 和 OpenShell shell 执行依赖于远程主机或 OpenShell 文件系统限制策略； `workspaceAccess` 本身不会使远程 shell 路径变为只读。
</Note>