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

​
先决条件

  • Podman 无 root 模式
  • 主机上已安装 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。可选的构建时环境变量：
变量作用
OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE使用现有/已拉取的镜像，而不是构建 openclaw:local
OPENCLAW_IMAGE_APT_PACKAGES在镜像构建期间安装额外的 apt 包（也接受旧版 OPENCLAW_DOCKER_APT_PACKAGES）
OPENCLAW_IMAGE_PIP_PACKAGES在镜像构建期间安装额外的 Python 包；固定版本，并且只使用你信任的包索引
OPENCLAW_EXTENSIONS在构建时预安装插件依赖
OPENCLAW_INSTALL_BROWSER为浏览器自动化预安装 Chromium 和 Xvfb（设为 1）
如需改用 Quadlet 管理的设置（仅限 Linux + systemd 用户服务）：
./scripts/podman/setup.sh --quadlet
或设置 OPENCLAW_PODMAN_QUADLET=1。
2

启动 Gateway 网关容器

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

在容器内运行新手引导

./scripts/run-openclaw-podman.sh launch setup
然后打开 http://127.0.0.1:18789/，并使用 ~/.openclaw/.env 中的令牌。模型凭证：在设置期间使用 OpenClaw 管理的凭证（Anthropic API 密钥，或用于 Codex 支持的 OpenAI 的 OpenAI Codex 浏览器 OAuth/设备码凭证）。Podman 启动器不会将主机 CLI 凭据主目录（例如 ~/.claude 或 ~/.codex）挂载到设置或 Gateway 网关容器中。现有主机 CLI 登录只是同主机便利路径 — 对于容器安装，请将提供商凭证保存在设置流程管理的已挂载 ~/.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 相关键名的允许列表，并向容器传递显式运行时环境变量；它不会将完整环境文件交给 Podman。

​
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，设置流程会在 ~/.config/containers/systemd/openclaw.container 安装 Quadlet 文件。
操作命令
启动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/无头主机上实现开机持久化，请为当前用户启用 linger： 
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
  • 令牌文件： ~/.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、渠道/提供商状态、会话和工作区会在容器替换后保留。设置流程还会为已发布的 Gateway 网关端口上的 127.0.0.1 和 localhost 播种 gateway.controlUi.allowedOrigins，以便本地仪表板能配合容器的非 loopback 绑定工作。 手动启动器可用的环境变量（将这些持久化在 ~/.openclaw/.env 中；启动器会在最终确定容器/镜像默认值前读取该文件）：
变量默认值作用
OPENCLAW_PODMAN_CONTAINERopenclaw容器名称
OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGEopenclaw:local要运行的镜像
OPENCLAW_PODMAN_GATEWAY_HOST_PORT18789映射到容器 18789 的主机端口
OPENCLAW_PODMAN_BRIDGE_HOST_PORT18790映射到容器 18790 的主机端口
OPENCLAW_PODMAN_PUBLISH_HOST127.0.0.1已发布端口的主机接口
OPENCLAW_GATEWAY_BINDlan容器内的 Gateway 网关绑定模式
OPENCLAW_PODMAN_USERNSkeep-idkeep-id、auto 或 host
如果你使用非默认的 OPENCLAW_CONFIG_DIR 或 OPENCLAW_WORKSPACE_DIR，请为 ./scripts/podman/setup.sh 和之后的 ./scripts/run-openclaw-podman.sh launch 命令设置相同变量 — 仓库本地启动器不会跨 shell 持久化自定义路径覆盖。

​
有用命令

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

​
故障排查

  • 配置或工作区出现 Permission denied (EACCES)： 容器默认使用 --userns=keep-id 和 --user <your uid>:<your 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 阻止绑定挂载： 保持默认挂载行为不变；当 Linux 上 SELinux 处于 enforcing 或 permissive 模式时，启动器会自动添加 :Z。

​
相关