Podman

在 rootless Podman 容器中运行 OpenClaw Gateway，由你当前的非 root 用户管理。

模型：

• Podman 运行 Gateway 容器。
• 你主机上的 openclaw CLI 是控制平面。
• 持久化状态默认保存在主机的 ~/.openclaw 下。
• 日常管理使用 openclaw --container <name> ...，而不是 sudo -u openclaw、podman exec 或单独的服务用户。

先决条件¶

• Podman 处于 rootless 模式，并且其主机 init 可执行文件（通常是 catatonit）可用于启动器的 --init 标志。在最小化的 Debian/Ubuntu 主机上，请显式安装两者：sudo apt-get install podman catatonit。对于 Podman Machine，该辅助程序必须在机器内部可用。
• 主机上已安装 OpenClaw CLI
• 可选： 如果你希望 Quadlet 管理的自动启动，则使用 systemd --user
• 可选： 仅当你希望在无头主机上通过 loginctl enable-linger "$(whoami)" 实现开机持久化时，才需要 sudo

快速开始¶

1. 一次性设置

从仓库根目录运行 ./scripts/podman/setup.sh。

这会在你的 rootless Podman 存储中构建 openclaw:local（如果设置了 OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE，则拉取该镜像），如果缺失则创建包含 gateway.mode: "local" 的 ~/.openclaw/openclaw.json，如果缺失则创建包含生成的 OPENCLAW_GATEWAY_TOKEN 的 ~/.openclaw/.env。

可选的构建时环境变量：

若要改用 Quadlet 管理的设置（仅限 Linux + systemd 用户服务）：

./scripts/podman/setup.sh --quadlet

或设置 OPENCLAW_PODMAN_QUADLET=1。

2. 启动 Gateway 容器

./scripts/run-openclaw-podman.sh launch

以当前 uid/gid 启动容器，使用 --userns=keep-id，并将你的 OpenClaw 状态绑定挂载到容器中。

3. 在容器内运行 onboarding

./scripts/run-openclaw-podman.sh launch setup

然后打开 http://127.0.0.1:18789/ 并使用 ~/.openclaw/.env 中的 token。

模型认证：在 setup 期间使用 OpenClaw 管理的认证（Anthropic API 密钥，或用于 Codex 支持的 OpenAI 的 OpenAI Codex 浏览器 OAuth/设备代码认证）。Podman 启动器不会将主机 CLI 凭据目录（如 ~/.claude 或 ~/.codex）挂载到 setup 或 Gateway 容器中。现有主机 CLI 登录只是同主机上的便捷路径——对于容器安装，请将提供商认证保留在 setup 管理的已挂载 ~/.openclaw 状态中。

4. 从主机 CLI 管理运行中的容器

export OPENCLAW_CONTAINER=openclaw

然后普通的 openclaw 命令会自动在该容器内运行：

openclaw dashboard --no-open
openclaw gateway status --deep   # includes extra service scan
openclaw doctor
openclaw channels login

在 macOS 上，Podman machine 可能使浏览器对 Gateway 而言看起来不是本地的。如果启动后 Control UI 报告设备认证错误，请使用 Podman 和 Tailscale 中的 Tailscale 指南。

手动启动器仅从 ~/.openclaw/.env 读取一小部分 Podman 相关键的允许列表，并向容器传递显式的运行时环境变量；它不会将整个 env 文件交给 Podman。

代理沙箱后端¶

本页介绍如何在 Podman 容器中运行 Gateway 本身。Agent 沙箱是独立的。设置 agents.defaults.sandbox.backend: "podman" 可直接选择原生 Podman CLI。默认的 "docker" 后端仍仅限 Docker。

Podman 复用与 Docker 相同的 agents.defaults.sandbox.docker.* 容器设置，但通过原生 podman CLI 执行。浏览器沙箱目前仍仅限 Docker。

有关配置示例和镜像构建命令，请参阅 沙箱。

Podman 和 Tailscale¶

对于 HTTPS 或远程浏览器访问，请遵循主 Tailscale 文档。

Podman 特定说明：

• 将 Podman 发布主机保持为 127.0.0.1。
• 优先使用主机管理的 tailscale serve，而不是 openclaw gateway --tailscale serve。
• 在 macOS 上，如果本地浏览器设备认证上下文不可靠，请使用 Tailscale 访问，而不是临时本地隧道变通方案。

请参阅 Tailscale 和 Control UI。

Systemd（Quadlet，可选）¶

如果你运行了 ./scripts/podman/setup.sh --quadlet，setup 会在 ~/.config/containers/systemd/openclaw.container 安装一个 Quadlet 文件。

编辑 Quadlet 文件后：

systemctl --user daemon-reload
systemctl --user restart openclaw.service

要在 SSH/无头主机上实现开机持久化，请为当前用户启用 lingering：

sudo loginctl enable-linger "$(whoami)"

生成的 Quadlet 服务保持固定的、经过加固的默认形态：127.0.0.1 发布端口（18789 Gateway、18790 bridge）、容器内的 --bind lan、keep-id 用户命名空间、OPENCLAW_NO_RESPAWN=1、Restart=on-failure 和 TimeoutStartSec=300。它将 ~/.openclaw/.env 作为运行时 EnvironmentFile 读取，用于 OPENCLAW_GATEWAY_TOKEN 等值，但不会使用手动启动器的 Podman 特定覆盖允许列表。对于自定义发布端口、发布主机或其他容器运行标志，请改用手动启动器，或直接编辑 ~/.config/containers/systemd/openclaw.container，然后重新加载并重启服务。

配置、环境变量和存储¶

• 配置目录： ~/.openclaw
• 工作区目录： ~/.openclaw/workspace
• Token 文件： ~/.openclaw/.env
• 启动辅助脚本： ./scripts/run-openclaw-podman.sh

启动脚本和 Quadlet 会将主机状态绑定挂载到容器中：OPENCLAW_CONFIG_DIR -> /home/node/.openclaw，OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace。默认情况下，这些是主机目录，而不是匿名容器状态，因此 openclaw.json、共享和按 agent 划分的 SQLite 认证存储、通道/提供商状态、会话以及工作区都能在容器替换后保留。设置过程还会为已发布的网关端口上的 127.0.0.1 和 localhost 预置 gateway.controlUi.allowedOrigins，以便本地仪表盘能够配合容器的非回环绑定使用。

手动启动器有用的环境变量（请将这些变量持久化到 ~/.openclaw/.env；启动器在确定容器/镜像默认值之前会读取该文件）：

如果使用非默认的 OPENCLAW_CONFIG_DIR 或 OPENCLAW_WORKSPACE_DIR，请为 ./scripts/podman/setup.sh 以及后续的 ./scripts/run-openclaw-podman.sh launch 命令设置相同的变量——仓库本地启动器不会跨 shell 持久化自定义路径覆盖。

升级镜像¶

重新构建或拉取新镜像后，重启容器或 Quadlet 服务。 对于新的 OpenClaw 版本，首次启动时，网关会在报告就绪之前运行安全状态和插件修复。

如果网关退出而不是进入就绪状态，请使用相同的挂载状态/配置，对同一镜像运行一次 openclaw doctor --fix，然后正常重启网关：

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"
OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}"

podman run --rm -it \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/node \
  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \
  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \
  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \
  "$OPENCLAW_PODMAN_IMAGE" \
  openclaw doctor --fix

在 SELinux 主机上，如果 Podman 阻止访问已挂载状态，请为两个绑定挂载都添加 ,Z。

使用更新后的镜像重启 Gateway 后，通过容器感知的主机 CLI 运行只读部署预检：

export OPENCLAW_CONTAINER=openclaw
openclaw doctor --json

常用命令¶

• 容器日志： podman logs -f openclaw
• 停止容器： podman stop openclaw
• 删除容器： podman rm -f openclaw
• 从主机 CLI 打开仪表盘 URL： openclaw dashboard --no-open
• 通过主机 CLI 检查健康/状态： openclaw gateway status --deep（RPC 探测 + 额外服务扫描）

故障排查¶

• Token 生成失败： 当所选随机源（openssl、Python 或 od）失败时，设置和启动会在保存生成的 Token 或启动容器之前停止。修复该命令并重试。
• 缺少 Init 可执行文件（lookup init binary / container-init binary not found on the host）： 在 Podman 引擎主机上安装 catatonit，或修复 containers.conf 中配置的 init_path/helper_binaries_dir，然后重试。在 Gateway 或沙箱镜像内部安装辅助程序无法修复引擎主机。保持启用 --init；参见主机 Init 先决条件.
• 配置或工作区出现权限被拒绝（EACCES）： 容器默认以 --userns=keep-id 和 --user <your uid>:<your gid> 运行。确保主机上的配置/工作区路径由当前用户拥有。
• Gateway 启动被阻止（缺少 gateway.mode=local）： 确保 ~/.openclaw/openclaw.json 存在并设置 gateway.mode="local"。如果缺失，scripts/podman/setup.sh 会创建它。
• 镜像更新后容器重启： 运行升级镜像中的一次性 openclaw doctor --fix 命令，然后再次启动网关。
• 容器 CLI 命令命中了错误目标： 显式使用 openclaw --container <name> ...，或在 shell 中导出 OPENCLAW_CONTAINER=<name>。
• openclaw update 使用 --container 时失败： 这是预期行为。重新构建/拉取镜像，然后重启容器或 Quadlet 服务。
• Quadlet 服务未启动： 运行 systemctl --user daemon-reload，然后运行 systemctl --user start openclaw.service。在无头系统上，可能还需要 sudo loginctl enable-linger "$(whoami)"。
• SELinux 阻止绑定挂载： 保持默认挂载行为不变；当 SELinux 处于 enforcing 或 permissive 时，启动器会在 Linux 上自动添加 :Z。

相关¶

• Docker
• 沙箱
• Gateway 后台进程
• Gateway 故障排查