SSH 后端

该后端仅播种一次的远程工具契约、认证材料和远程规范工作区。

SSH 后端¶

使用 backend: "ssh" 在任意可通过 SSH 访问的机器上对 exec、文件工具和媒体读取进行沙箱隔离。

远程环境必须为文件系统桥接提供 /bin/sh、python3 以及 GNU 兼容的 stat（-c）和 readlink（-f、-n）。这些工具必须可供非交互式 SSH 命令使用， 而不仅仅是交互式登录 shell。Gateway 主机不需要这些远程工具：macOS 或 Windows Gateway 可以使用提供这些工具的 SSH 目标。这是一个远程工具契约， 而不是仅限 Linux 的 Gateway 要求。

在远程读取和写入期间，规范工作区路径和父目录路径会保留其空白字符， 包括嵌入的换行符和末尾换行符。删除和重命名操作会遵循挂载内父目录别名， 同时作用于最终条目本身。删除最终符号链接会保留其目标不变；解析到允许挂载之外的父目录会被拒绝。

创建新的远程工作区还需要原子性不替换目录重命名：Linux 上的 renameat2 或 macOS 上的 renameatx_np， 并且需要远程文件系统支持。不具备该能力的旧版 libc 或文件系统无法发布新的暂存工作区。 初始化失败，且不会替换现有目录；它也不会回退到覆盖或嵌套移动。现有远程工作区会继续被采用，而无需重新播种。

{
  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、Prompt 媒体读取以及入站媒体暂存都会通过 SSH 直接针对远程工作区运行。OpenClaw 不会自动将远程更改同步回本地工作区。
• 认证材料：identityFile/certificateFile/knownHostsFile 引用现有本地文件。identityData/certificateData/knownHostsData 接受内联字符串或 SecretRefs，通过正常的 secrets 运行时快照解析，以模式 0600 写入临时文件，并在 SSH 会话结束时删除。如果同一项同时设置了 *File 和 *Data 变体，则该会话中 *Data 优先。
• 远程规范后果：初始播种后，远程 SSH 工作区成为真实的沙箱状态。播种步骤之后，在 OpenClaw 外部对主机本地所做的编辑，在重建沙箱之前远程不可见。openclaw sandbox recreate 会删除按作用域划分的远程根目录，并在下次使用时再次从本地播种。此后端不支持浏览器沙箱，且 sandbox.docker.* 设置不适用于它。