Skip to main content
在一个无根 Podman 容器中运行 OpenClaw Gateway，由你当前的非 root 用户管理。 模型：
  • Podman 运行网关容器。
  • 你主机上的 openclaw CLI 作为控制平面。
  • 持久化状态默认保存在主机上的 ~/.openclaw 下。
  • 日常管理使用 openclaw --container <name> ...，而不是 sudo -u openclaw、podman exec 或单独的服务用户。

​
前提条件

  • Podman 处于无根模式
  • 主机上已安装 OpenClaw CLI
  • 可选： 如果你想要由 Quadlet 管理的自动启动，则需要 systemd --user
  • 可选： 仅当你希望在无头主机上通过 loginctl enable-linger "$(whoami)" 实现开机持久化时才需要 sudo。

​
快速开始

1

一次性设置

从仓库根目录运行 ./scripts/podman/setup.sh。这会在你的无 root Podman 存储中构建 openclaw:local（或在已设置时拉取 OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE），在缺失时创建带有 gateway.mode: "local" 的 ~/.openclaw/openclaw.json，并在缺失时创建带有生成的 OPENCLAW_GATEWAY_TOKEN 的 ~/.openclaw/.env。可选的构建时环境变量：如果想改用 Quadlet 管理的设置方式（仅限 Linux + systemd 用户服务）：
或设置 OPENCLAW_PODMAN_QUADLET=1。
2

启动 Gateway 容器

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

在容器内运行引导流程

然后打开 http://127.0.0.1:18789/，并使用 ~/.openclaw/.env 中的令牌。模型认证：在设置过程中使用 OpenClaw 管理的认证（Anthropic API 密钥，或用于 Codex 支持的 OpenAI 的 OpenAI Codex 浏览器 OAuth/device-code 认证）。Podman 启动器不会将主机 CLI 的凭据目录（例如 ~/.claude 或 ~/.codex）挂载到设置或 gateway 容器中。现有的主机 CLI 登录仅是同一主机上的便利路径——对于容器安装，请将提供方认证保留在设置所管理的已挂载 ~/.openclaw 状态中。
4

从主机 CLI 管理正在运行的容器

然后普通的 openclaw 命令会自动在该容器内运行：
在 macOS 上，Podman machine 可能会让浏览器对 gateway 看起来不像本地端。若 Control UI 在启动后报告设备认证错误，请参考 Podman and Tailscale 中的 Tailscale 指引。
手动启动器只会从 ~/.openclaw/.env 读取一小部分与 Podman 相关的允许列表键，并将显式的运行时环境变量传递给容器；它不会将整个 env 文件交给 Podman。

​
Agent 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 和 控制界面。

​
Systemd（Quadlet，可选）

如果你运行了 ./scripts/podman/setup.sh --quadlet，安装程序会在 ~/.config/containers/systemd/openclaw.container 安装一个 Quadlet 文件。 编辑 Quadlet 文件后：
对于 SSH/无头主机上的开机持久化，请为当前用户启用 lingering：
生成的 Quadlet 服务保持固定、加固后的默认配置：发布到 127.0.0.1 的端口（18789 网关、18790 桥接）、容器内使用 --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
  • 令牌文件： ~/.openclaw/.env
  • 启动辅助脚本： ./scripts/run-openclaw-podman.sh
启动脚本和 Quadlet 会将宿主机状态绑定挂载到容器中：OPENCLAW_CONFIG_DIR -> /home/node/.openclaw，OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace。默认情况下，这些是宿主机目录，而不是匿名容器状态，因此 openclaw.json、每个 agent 的 auth-profiles.json、通道/提供方状态、会话以及工作区在容器替换后仍会保留。安装过程还会为已发布的网关端口上的 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，然后正常重启网关：
在启用了 SELinux 的主机上，如果 Podman 阻止访问已挂载状态，请在两个绑定挂载上都添加 ,Z。

​
有用的命令

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

​
故障排除

  • 配置或工作区权限被拒绝（EACCES）： 容器默认使用 --userns=keep-id 和 --user <your uid>:<your gid> 运行。请确保主机上的配置/工作区路径归当前用户所有。
  • 网关启动被阻止（缺少 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 阻止 bind 挂载： 保持默认挂载行为不变；当 Linux 上 SELinux 处于 enforcing 或 permissive 模式时，启动器会自动添加 :Z。

​
相关内容