跳转至

Podman 后端

将原生 Podman CLI 作为内置后端进行选择、它所复用的 Docker 设置,以及其无根(rootless)用户映射规则。

本页介绍 Podman 作为 agent 工具执行的沙箱后端。在无根(rootless)Podman 容器中运行 Gateway 本身是另一套独立设置:请参阅 Podman。

Podman 后端

使用 sandbox.backend: "podman" 直接选择原生 podman CLI。这是一个内置后端,不是插件。即使已安装 docker 可执行文件,它也不会检查或选择 Docker。

Podman 复用现有的 sandbox.docker.* 设置以及当前生效的原生 podman CLI 上下文;它不额外提供独立的连接配置界面。

Rootless(无根)Podman 默认为可写工作区挂载使用 --userns=keep-id。长时间运行的沙箱可能会保留从属 ID,并阻止无关的 --userns=auto 工作负载;在启动这些工作负载之前请先移除该沙箱。设置 sandbox.docker.user 为非零数字 UID 或 UID:GID 可控制容器用户。Rootless Podman 会拒绝 UID 或 GID 0,因为 Podman 4.x 无法在保留工作区绑定挂载所属关系的同时重映射命名空间根用户;请将需要 root 的初始化设置构建进镜像,或使用 rootful(有根)Podman。否则,rootful Podman 在可用时会使用工作区属主。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "podman",
        scope: "session",
        workspaceAccess: "rw",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          network: "none",
          readOnlyRoot: true,
          capDrop: ["ALL"],
        },
      },
    },
  },
}

在启用后端之前,先将沙箱镜像构建或拉取到所选 Podman 存储中。在源码检出目录中,使用 Podman 构建同一个沙箱 Dockerfile:

podman build -t openclaw-sandbox:bookworm-slim -f scripts/docker/sandbox/Dockerfile .

更改连接与升级现有沙箱

当两个环境选择器都已设置时,OpenClaw 遵循所安装的 Podman 客户端: Podman 4.8 及更新版本优先选择非空的 CONTAINER_CONNECTION;Podman 4.7 则在 CONTAINER_HOST 存在时优先选择它。引擎的服务端版本不决定此优先级。如果在两个选择器都已设置的情况下 OpenClaw 无法识别客户端版本,它会拒绝这种有歧义的选择。请取消设置未使用的选择器, 或修复客户端的 podman --version 命令。

每个沙箱都会记录其引擎 URI,对于 Podman Machine 还会记录其 SSH 身份。 更早的 OpenClaw 版本可能即使在客户端选择了 CONTAINER_CONNECTION 时仍固定使用 CONTAINER_HOST。升级后,这些现有沙箱可能会报告 "The active Podman connection changed."。 OpenClaw 会保留旧沙箱和注册表条目,而不会在新选择的引擎上移除容器。

切换前,请通过其记录的端点停用旧沙箱:

  1. 暂停使用受影响沙箱的运行。对于下面的命令,请使用与 Gateway 相同的操作系统用户、OpenClaw 配置文件、配置和状态目录。
  2. 恢复原始的 CONTAINER_HOST,对于 Podman Machine 还要恢复原始的 CONTAINER_SSHKEY。在该命令环境中取消设置 CONTAINER_CONNECTION。原始端点必须可访问,且 Podman Machine 必须正在运行。
  3. 使用受影响沙箱的确切 sessionKey。当所有已注册沙箱都使用恢复后的目标时,openclaw sandbox list --json 会显示该键以及 backendTarget.globalArgs 中记录的 URI 和身份。在更改连接之前保存这些值。如果条目已经横跨多个引擎,全局列表可能会失败;请使用之前记录的键配合下面的限定作用域重建操作。如果该键未知,请保留注册表并先确定确切作用域再继续。
  4. 保留容器可写层中任何需要的数据,然后运行 openclaw sandbox recreate --session "<sessionKey>"。确认前请先审查预览。这会移除选定的容器;已挂载的工作区文件会保留。
  5. 设置预期的 CONTAINER_CONNECTION,并取消设置未使用的 CONTAINER_HOST 和 CONTAINER_SSHKEY。同时将该环境应用于 Gateway。确保沙箱镜像和工作区在所选引擎上可用。下次使用会在那里创建新的沙箱;它不会传输旧容器的可写层。

如果无法恢复原始端点或身份,请保留注册表条目并先修复该连接。不要通过编辑记录的目标或删除注册表条目来绕过检查。recreate --force 只会跳过确认;它不会绕过端点验证。

主机 init 前提条件

OpenClaw 使用 --init 创建 Podman 沙箱,以便回收孤立的工具进程。Podman 引擎主机需要其 init 可执行文件,通常是 catatonit。仅将其安装在沙箱镜像中并不能满足此要求。对于 Podman Machine,该可执行文件属于机器内部,而不是客户端主机上。

在 Debian 或 Ubuntu 上,使用 --no-install-recommends 的最小安装可能会省略该辅助程序。在配置引擎主机时请显式安装它:

sudo apt-get install podman catatonit

如果沙箱创建报告 lookup init binary 或 container-init binary not found on the host,请安装该辅助程序,或修复 containers.conf 中 Podman 配置的 init_path/helper_binaries_dir,然后重试。Podman 可以解析 PATH 之外的辅助程序;podman info 成功并不证明 --init 可用。请保持沙箱功能和 --init 启用,而不要绕过此前提条件。

Podman 说明:

  • Podman 不支持浏览器沙箱;请保持 sandbox.browser.enabled 为关闭状态,或安装 Docker 并选择 backend: "docker"。
  • 支持本地 Podman 引擎和 Podman Machine。Podman Machine 的绑定挂载源必须位于主机 home 目录下,该目录是其默认共享卷。任意远程 Podman 连接都会被拒绝;远程执行请使用 SSH 后端。
  • 自定义 tmpfs 或绑定挂载不得覆盖 /run/podman-init;OpenClaw 会拒绝它们,以便沙箱清理继续正常工作。

Warning

Podman-outside-of-Podman 约束

容器化 Gateway 通过宿主机的本地 Podman 引擎或 Podman Machine 创建同级沙箱。

  • 始终使用主机路径:使用其主机绝对路径配置 workspace,然后将完整的状态根目录和工作区以相同路径挂载到 Gateway 中。否则,沙箱可能挂载了工作区,但 Gateway 无法写入 skill-workspace 文件。
  • Podman Machine 设置:绑定源必须位于主机主目录下。将 Gateway 的 HOME 设置为该路径,并将 OPENCLAW_HOME、OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_DIR 指向规范挂载的状态根目录。镜像需要一个兼容的 Podman 客户端、其命名连接和 SSH 身份,以及一个用于 known-host 元数据的专用可写 SSH 目录。
  • 保持 Podman 访问仅限 Gateway:切勿将引擎套接字、连接材料或 SSH 身份挂载到代理沙箱中。不支持任意远程连接;请改用 SSH 后端。

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