跳转至

工作区访问

workspaceAccess 向沙箱暴露了什么,需要角色(role-required)的沙箱如何对其加以限制,以及技能如何镜像到沙箱工作区。

工作区访问

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

Value Behavior
none(默认) 工具可以在 ~/.openclaw/sandboxes 下读写一个隔离的沙箱工作区;智能体工作区不会暴露。
ro 将智能体工作区以只读方式挂载到 /agent(禁用 write/edit/apply_patch)。
rw 将智能体工作区以读写方式挂载到 /workspace。

对于需要角色(role-required)的沙箱,OpenClaw 会将配置的 rw 工作区访问权限限制为 ro,并记录一条 agent/sandbox 警告。访客保留独立的沙箱工作区,而共享的智能体工作区仅以只读挂载方式可用。这可以防止访客共享可写的智能体工作区;none 和 ro 保持不变。没有需要角色的沙箱的会话会保留其配置的工作区访问权限。

托管项目工作区

具有会话自有托管工作树(managed worktree)的沙箱会话在 Docker 和 Podman 上使用私有 Git 检出。当注册项目以 worktree: true 被选中时,它可能位于智能体配置的工作区之外。这授权的是源准备操作,而不是对该主机目录的直接访问。任意的外部 cwd 值和直接项目绑定仍受到限制。

可见的子会话在后续轮次中会继续将其托管工作树作为沙箱工作区,包括在更新之前创建的会话。

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

私有检出在 none 或 rw 工作区访问权限下是可写的;显式的 ro 保持只读。这不会使共享的智能体工作区变为可写。其他沙箱后端无法使用此本地托管项目投影,并且会给出说明而失败,而不是回退到主机执行。

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

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

入站媒体会被复制到活动沙箱工作区中(media/inbound/*)。

Note

技能:read 工具以沙箱为根。当 workspaceAccess: "none" 时,OpenClaw 会将符合条件的技能镜像到沙箱工作区(.../skills)中,作为只读指令根;其他私有工作区文件仍保持可写。当为 "rw" 时,工作区技能可从 /workspace/skills 读取,符合条件的受管理的、捆绑的或插件技能会被物化到生成的只读路径 /workspace/.openclaw/sandbox-skills/skills。

本地容器挂载和沙箱文件工具会强制实施这些只读根。 Gateway 会刷新其自身的镜像副本,即使早期副本继承了 只读目录权限;无需手动修复权限。 SSH 和 OpenShell shell 执行依赖远程主机或 OpenShell 策略 来实施文件系统限制;仅 workspaceAccess 不会使远程 shell 路径变为只读。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw