SSH 后端
远程工具契约、认证材料,以及该后端仅初始化一次的远程规范工作区。
SSH 后端¶
使用 backend: "ssh" 可在任意可通过 SSH 访问的机器上对 exec、文件工具和媒体读取进行沙箱隔离。
远程环境必须提供 /bin/sh、python3,以及 GNU 兼容的
stat(-c)和 readlink(-f、-n),用于文件系统桥接。这些工具
必须可供非交互式 SSH 命令使用,而不仅仅是交互式
登录 shell。Gateway 主机不需要这些远程工具:macOS 或
Windows Gateway 可以使用提供这些工具的 SSH 目标。这是一个远程
工具契约,而不是仅限 Linux 的 Gateway 要求。
规范工作区和父目录路径在远程读取和写入期间保留其空白字符,包括 嵌入的和末尾的换行符。 删除和重命名操作遵循挂载内父目录别名,同时作用于 最终条目本身。删除最终符号链接会保留其目标; 解析到允许挂载之外的父目录会被拒绝。
新的远程工作区在发布前会上传到私有暂存目录。
在受支持时,fs-safe 使用原子不可替换目录
重命名进行发布:Linux 上的 renameat2 或 macOS 上的 renameatx_np。
在拒绝 RENAME_NOREPLACE 的 Linux 文件系统上,包括 gVisor 卷
挂载,fs-safe 会检查目标不存在,并回退到目录
重命名。这绝不会将空占位暴露为已完成的工作区。检查时
存在的目标会被保留,文件或非空目录竞争者
不能被替换。在该检查之后创建的空目录可以被替换。
macOS 仍然需要其原生不可替换原语。现有远程工作区
继续被采用而无需重新初始化。
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "ssh",
scope: "session",
workspaceAccess: "rw",
ssh: {
target: "user@gateway-host:22",
workspaceRoot: "/tmp/openclaw-sandboxes",
strictHostKeyChecking: true,
updateHostKeys: true,
identityFile: "~/.ssh/id_ed25519",
certificateFile: "~/.ssh/id_ed25519-cert.pub",
knownHostsFile: "~/.ssh/known_hosts",
// Or use SecretRefs / inline contents instead of local files:
// identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
// certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
// knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
},
},
},
},
}
默认值:command: "ssh"、workspaceRoot: "/tmp/openclaw-sandboxes"、strictHostKeyChecking: true、updateHostKeys: true。
- 生命周期:OpenClaw 在
sandbox.ssh.workspaceRoot下创建每个作用域的远程根目录。在创建或重建后的首次使用时,它会从本地工作区一次性初始化该远程工作区。之后,exec、read、write、edit、apply_patch、提示媒体读取和入站媒体暂存直接通过 SSH 针对远程工作区运行。OpenClaw 不会自动将远程更改同步回本地工作区。 - 认证材料:
identityFile/certificateFile/knownHostsFile引用现有本地文件。identityData/certificateData/knownHostsData接受内联字符串或 SecretRefs,通过正常的 secrets 运行时快照解析,写入模式为0600的临时文件,并在 SSH 会话结束时删除。如果同一项同时设置了*File和*Data变体,则在该会话中*Data优先。 - 远程规范影响:初始初始化后,远程 SSH 工作区成为真实的沙箱状态。在初始化步骤之后,在 OpenClaw 之外进行的主机本地编辑在远程不可见,直到你重建沙箱。
openclaw sandbox recreate会删除每个作用域的远程根目录,并在下次使用时再次从本地初始化。此后端不支持浏览器沙箱,并且sandbox.docker.*设置不适用于它。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw