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（subordinate IDs），并阻塞无关的 --userns=auto 工作负载；在启动这些工作负载之前，请先移除该沙箱。

将 sandbox.docker.user 设置为非零数字 UID 或 UID:GID，以控制容器用户。Rootless Podman 拒绝 UID 或 GID 为 0，因为 Podman 4.x 无法在保留工作区绑定挂载属主的同时重映射命名空间 root；请将需要 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 profile、配置和状态目录。
2. 恢复原始的 CONTAINER_HOST，对于 Podman Machine，还要恢复原始的 CONTAINER_SSHKEY。在该命令环境中取消设置 CONTAINER_CONNECTION。原端点必须可达，且 Podman Machine 必须处于运行状态。
3. 使用受影响沙箱的精确 sessionKey。当所有已注册沙箱都使用恢复后的目标时，openclaw sandbox list --json 会显示该键以及 backendTarget.globalArgs 中记录的 URI 和身份。请先保存这些值，再更改连接。如果条目已经跨引擎，全局列表可能会失败；请使用先前记录的键执行下面的作用域内重建。如果该键未知，请保留注册表，并在继续之前确定确切的 scope。
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 的绑定挂载源必须位于宿主机主目录下，该目录是其默认共享卷。任意远程 Podman 连接都会被拒绝；远程执行请使用 SSH 后端。
• 自定义的 tmpfs 或绑定挂载不得覆盖 /run/podman-init；OpenClaw 会拒绝这类配置，以确保沙箱清理功能继续正常工作。