Podman

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

设计模型如下：

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

前置条件

• rootless 模式的 Podman
• 宿主机上已安装 OpenClaw CLI
• 可选： 若需要 Quadlet 自动启动，需 systemd --user
• 可选： 若需要在无头宿主机上开机自启，需 sudo（用于 loginctl enable-linger）

快速开始

第一步：一次性初始化

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

第二步：启动 Gateway 容器

运行 ./scripts/run-openclaw-podman.sh launch。

第三步：在容器内完成初始配置

运行 ./scripts/run-openclaw-podman.sh launch setup，然后打开 http://127.0.0.1:18789/。

第四步：从宿主机 CLI 管理运行中的容器

设置 OPENCLAW_CONTAINER=openclaw，然后在宿主机上正常使用 openclaw 命令。

配置细节：

• ./scripts/podman/setup.sh 默认在你的 rootless Podman 仓库中构建 openclaw:local，也可以通过 OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE 指定已有镜像。
• 如果 ~/.openclaw/openclaw.json 不存在，会自动创建并设置 gateway.mode: "local"。
• 如果 ~/.openclaw/.env 不存在，会自动创建并设置 OPENCLAW_GATEWAY_TOKEN。
• 手动启动时，辅助脚本只从 ~/.openclaw/.env 中读取小部分 Podman 相关键，并以显式运行时环境变量传入容器，不会把整个 env 文件直接交给 Podman。

Quadlet 管理模式：

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

Quadlet 仅支持 Linux（依赖 systemd user services）。也可以设置 OPENCLAW_PODMAN_QUADLET=1。

可选的构建/初始化环境变量：

• OPENCLAW_IMAGE 或 OPENCLAW_PODMAN_IMAGE — 使用已有/已拉取的镜像，而不是构建 openclaw:local
• OPENCLAW_DOCKER_APT_PACKAGES — 镜像构建时安装额外的 apt 包
• OPENCLAW_EXTENSIONS — 构建时预装扩展依赖

容器启动：

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

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

初始配置：

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

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

宿主机 CLI 默认设置：

export OPENCLAW_CONTAINER=openclaw

之后以下命令会自动在容器内执行：

openclaw dashboard --no-open
openclaw gateway status --deep
openclaw doctor
openclaw channels login

在 macOS 上，Podman machine 可能让浏览器对 gateway 显示为非本地连接。如果控制界面在启动后报设备认证错误，推荐使用 macOS Podman SSH 隧道方案。远程 HTTPS 访问请参考 Podman + Tailscale 章节。

macOS Podman SSH 隧道

在 macOS 上，即使发布端口仅绑定在 127.0.0.1，Podman machine 也可能让浏览器显示为非本地连接。

本地浏览器访问时，推荐用 SSH 隧道进入 Podman VM，然后打开隧道的 localhost 端口。

推荐的本地隧道端口：

• Mac 宿主机上使用 28889
• 转发到 Podman VM 内的 127.0.0.1:18789

在另一个终端启动隧道：

ssh -N \
  -i ~/.local/share/containers/podman/machine/machine \
  -p <podman-vm-ssh-port> \
  -L 28889:127.0.0.1:18789 \
  core@127.0.0.1

<podman-vm-ssh-port> 是 Podman VM 在 Mac 宿主机上的 SSH 端口，用以下命令查看：

podman system connection list

首次使用隧道时，需要一次性允许隧道浏览器来源（因为启动器可以自动设置 Podman 发布端口，但无法推断你选择的隧道端口）：

OPENCLAW_CONTAINER=openclaw openclaw config set gateway.controlUi.allowedOrigins \
  '["http://127.0.0.1:18789","http://localhost:18789","http://127.0.0.1:28889","http://localhost:28889"]' \
  --strict-json
podman restart openclaw

这是默认 28889 隧道的一次性操作。

然后打开：

http://127.0.0.1:28889/

注意事项：

• 18789 通常已被 Podman 发布的 gateway 端口占用，因此隧道使用 28889 作为本地浏览器端口。
• 如果界面要求配对确认，优先使用显式容器定向或显式 URL 命令，避免宿主机 CLI 回落到本地配对文件：

openclaw --container openclaw devices list
openclaw --container openclaw devices approve --latest

等效的显式 URL 形式：

openclaw devices list \
  --url ws://127.0.0.1:28889 \
  --token "$(sed -n 's/^OPENCLAW_GATEWAY_TOKEN=//p' ~/.openclaw/.env | head -n1)"

Podman + Tailscale

HTTPS 或远程浏览器访问，请参考主 Tailscale 文档。

Podman 特有注意事项：

• 保持 Podman 发布宿主机为 127.0.0.1。
• 优先使用宿主机管理的 tailscale serve，而不是 openclaw gateway --tailscale serve。
• macOS 本地浏览器无 HTTPS 访问时，优先使用上面的 SSH 隧道方案。

参考：

• Tailscale
• 控制界面

Systemd（Quadlet，可选）

如果你运行了 ./scripts/podman/setup.sh --quadlet，会在以下位置安装 Quadlet 文件：

~/.config/containers/systemd/openclaw.container

常用命令：

• 启动： systemctl --user start openclaw.service
• 停止： systemctl --user stop openclaw.service
• 状态： systemctl --user status openclaw.service
• 日志： journalctl --user -u openclaw.service -f

编辑 Quadlet 文件后：

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

在 SSH/无头宿主机上启用开机自启：

sudo loginctl enable-linger "$(whoami)"

配置、环境变量和存储

• 配置目录： ~/.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

默认使用宿主机目录，而不是匿名容器状态，因此配置和工作区在容器替换后仍然保留。Podman 配置还会为 127.0.0.1 和 localhost 预设 gateway.controlUi.allowedOrigins，使本地仪表板能与容器的非 loopback 绑定正常工作。

手动启动器的可用环境变量：

• OPENCLAW_PODMAN_CONTAINER — 容器名称（默认 openclaw）
• OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE — 要运行的镜像
• OPENCLAW_PODMAN_GATEWAY_HOST_PORT — 映射到容器 18789 的宿主机端口
• OPENCLAW_PODMAN_BRIDGE_HOST_PORT — 映射到容器 18790 的宿主机端口
• OPENCLAW_PODMAN_PUBLISH_HOST — 发布端口的宿主机接口，默认 127.0.0.1
• OPENCLAW_GATEWAY_BIND — 容器内 gateway 绑定模式，默认 lan
• OPENCLAW_PODMAN_USERNS — keep-id（默认）、auto 或 host

手动启动器会在确定容器/镜像默认值前先读取 ~/.openclaw/.env，因此可以在那里持久化这些配置。

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

Quadlet 注意事项：

• 生成的 Quadlet 服务使用固定的硬化默认配置：127.0.0.1 发布端口、容器内 --bind lan、keep-id 用户命名空间。
• 仍会读取 ~/.openclaw/.env 中的 gateway 运行时环境变量（如 OPENCLAW_GATEWAY_TOKEN），但不使用手动启动器的 Podman 特定覆盖白名单。
• 如需自定义发布端口、发布宿主机或其他容器运行参数，使用手动启动器或直接编辑 ~/.config/containers/systemd/openclaw.container，然后重新加载并重启服务。

常用命令

• 容器日志： podman logs -f openclaw
• 停止容器： podman stop openclaw
• 删除容器： podman rm -f openclaw
• 从宿主机 CLI 打开仪表板 URL： openclaw dashboard --no-open
• 通过宿主机 CLI 检查健康/状态： openclaw gateway status --deep

常见问题排查

• 配置或工作区权限拒绝（EACCES）： 容器默认以 --userns=keep-id 和 --user <你的 uid>:<你的 gid> 运行。确保宿主机配置/工作区路径归当前用户所有。
• Gateway 启动被阻止（缺少 gateway.mode=local）： 确保 ~/.openclaw/openclaw.json 存在并设置了 gateway.mode="local"。scripts/podman/setup.sh 会在缺失时自动创建。
• 容器 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 故障排查