OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

网关

Podman 后端

选择本机 Podman CLI 作为内置后端、其重用的 Docker 设置及其无根用户映射规则。

本页面介绍了 Podman 作为代理工具执行的沙箱后端。在无根 Podman 容器中运行网关本身是一个单独的设置：请参阅 Podman。

Podman 后端

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

Podman 会复用现有的 sandbox.docker.* 设置和当前原生 podman CLI 上下文；它不会添加单独的连接配置界面。

对于可写工作区挂载，无根 Podman 默认为 --userns=keep-id。长期存在的沙箱可以保留从属 ID 并阻止不相关的 --userns=auto 工作负载；在开始这些工作负载之前将其删除。将 sandbox.docker.user 设置为非零数字 UID 或 UID：GID 以控制容器用户。 Rootless Podman 拒绝 UID 或 GID 0，因为 Podman 4.x 无法在保留工作空间绑定所有权的同时重新映射名称空间根；将需要 root 的设置烘焙到映像中或使用 root Podman。 Rootful Podman 否则将使用可用的工作区所有者。

json5
{  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：

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

更改连接并升级现有沙箱

当设置了两个环境选择器时，OpenClaw 遵循已安装的 Podman client：Podman 4.8 和更新版本更喜欢非空 CONTAINER_CONNECTION； Podman 4.7 在存在时更喜欢 CONTAINER_HOST。引擎的服务器版本不决定此优先级。如果 OpenClaw 无法识别设置了两个选择器的客户端版本，则它会拒绝不明确的选择。取消设置未使用的选择器或修复客户端的 podman --version 命令。

每个沙箱记录其引擎 URI，对于 Podman 机器，记录其 SSH 身份。即使客户选择了 CONTAINER_CONNECTION，早期的 OpenClaw 版本也可以固定 CONTAINER_HOST。升级后，这些现有沙箱可以报告“活动 Podman 连接已更改”。 OpenClaw 保留旧的沙箱和注册表项，而不是删除新选择的引擎上的容器。

在切换之前通过其记录的端点退出旧沙箱：

  1. Pause 使用受影响沙箱的运行。使用相同的 OS 用户、OpenClaw 配置文件、配置和状态目录作为以下命令的网关。
  2. 恢复原始 CONTAINER_HOST，对于 Podman 机器，恢复原始 CONTAINER_SSHKEY。在该命令环境中取消设置 CONTAINER_CONNECTION。 The original endpoint must be reachable， and a Podman Machine must be running。
  3. 使用受影响的沙箱的确切值sessionKey。虽然所有注册的沙箱都使用恢复的目标，openclaw sandbox list --json显示该键和录制的URI和身份在backendTarget.globalArgs。在更改连接之前保存这些值。如果条目已经跨引擎，则全局列表可能会失败；将之前录制的密钥与下面的范围内的游戏一起使用。如果该密钥未知，请保留注册表并确定确切的范围，然后再继续。
  4. 将任何需要的数据保留在容器的可写层中，然后运行openclaw sandbox recreate --session "<sessionKey>"。确认前查看预览。这将删除选定的容器；已安装的工作区文件仍然存在。
  5. 设置预期的CONTAINER_CONNECTION并取消设置未使用的CONTAINER_HOST和CONTAINER_SSHKEY。将该环境也应用到网关。检查沙盒映像和工作区在所选引擎上是否可用。下一次使用会在那里创建一个新的沙箱；它不会转移旧容器的可写层。

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

主机初始化先决条件

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

在 Debian 或 Ubuntu 上，使用 --no-install-recommends 的最小安装可以省略帮助程序。在配置引擎主机时明确包含它：

bash
sudo apt-get install podman catatonit

如果沙箱创建报告 lookup init binary 或 container-init binary not found on the host，请安装帮助程序或修复 Podman 在 containers.conf 中配置的 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 会拒绝这些配置，以确保沙箱清理继续正常工作。
本页有帮助吗？