跳转至

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