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:
更改连接与升级现有沙箱¶
当两个环境选择器都已设置时,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 会保留旧沙箱和注册表条目,而不会在新选择的引擎上移除容器。
切换前,请通过其记录的端点停用旧沙箱:
- 暂停使用受影响沙箱的运行。对于下面的命令,请使用与 Gateway 相同的操作系统用户、OpenClaw 配置文件、配置和状态目录。
- 恢复原始的
CONTAINER_HOST,对于 Podman Machine 还要恢复原始的CONTAINER_SSHKEY。在该命令环境中取消设置CONTAINER_CONNECTION。原始端点必须可访问,且 Podman Machine 必须正在运行。 - 使用受影响沙箱的确切
sessionKey。当所有已注册沙箱都使用恢复后的目标时,openclaw sandbox list --json会显示该键以及backendTarget.globalArgs中记录的 URI 和身份。在更改连接之前保存这些值。如果条目已经横跨多个引擎,全局列表可能会失败;请使用之前记录的键配合下面的限定作用域重建操作。如果该键未知,请保留注册表并先确定确切作用域再继续。 - 保留容器可写层中任何需要的数据,然后运行
openclaw sandbox recreate --session "<sessionKey>"。确认前请先审查预览。这会移除选定的容器;已挂载的工作区文件会保留。 - 设置预期的
CONTAINER_CONNECTION,并取消设置未使用的CONTAINER_HOST和CONTAINER_SSHKEY。同时将该环境应用于 Gateway。确保沙箱镜像和工作区在所选引擎上可用。下次使用会在那里创建新的沙箱;它不会传输旧容器的可写层。
如果无法恢复原始端点或身份,请保留注册表条目并先修复该连接。不要通过编辑记录的目标或删除注册表条目来绕过检查。recreate --force 只会跳过确认;它不会绕过端点验证。
主机 init 前提条件¶
OpenClaw 使用 --init 创建 Podman 沙箱,以便回收孤立的工具进程。Podman 引擎主机需要其 init 可执行文件,通常是 catatonit。仅将其安装在沙箱镜像中并不能满足此要求。对于 Podman Machine,该可执行文件属于机器内部,而不是客户端主机上。
在 Debian 或 Ubuntu 上,使用 --no-install-recommends 的最小安装可能会省略该辅助程序。在配置引擎主机时请显式安装它:
如果沙箱创建报告 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