本页介绍如何用 rootless Podman 代替 Docker 来"养龙虾"。Podman 以你当前用户身份运行容器，持久化状态挂载到主机 ~/.openclaw，日常管理用 openclaw --container <name> 替代 podman exec。覆盖快速启动、Tailscale、systemd Quadlet 自启和故障排查。

用 Podman 部署 OpenClaw

以 rootless 模式运行 OpenClaw 网关容器，由当前非 root 用户管理。

运行模型：

• Podman 负责运行网关容器
• 主机 openclaw CLI 是控制平面
• 持久化状态默认存储在主机 ~/.openclaw
• 日常管理用 openclaw --container <name> ... 替代 sudo -u openclaw、podman exec 或单独的服务用户

前置条件

• Podman（rootless 模式）
• OpenClaw CLI 已安装到主机
• 可选： systemd --user，用于 Quadlet 管理的自启
• 可选： sudo，仅在无头主机需要启用 linger 时使用

快速启动

第一步：一次性初始化

./scripts/podman/setup.sh

• 默认构建 openclaw:local 到 rootless Podman 存储，或使用 OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE 指定镜像
• 若 ~/.openclaw/openclaw.json 不存在，自动创建并写入 gateway.mode: "local"
• 若 ~/.openclaw/.env 不存在，自动创建并写入 OPENCLAW_GATEWAY_TOKEN

第二步：启动网关容器

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

容器以 --userns=keep-id 和你当前用户 uid/gid 运行，将 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 可能导致浏览器对网关来说不是"本地"的。Control UI 报设备认证错误时，请使用 Podman + Tailscale 方案。

Podman + Tailscale

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

Podman 专项注意：

• Podman publish 主机保持 127.0.0.1
• 优先使用主机管理的 tailscale serve，而非 openclaw gateway --tailscale serve
• macOS 上本地浏览器设备认证上下文不可靠时，使用 Tailscale 访问替代临时本地 tunnel 的临时方案

相关文档：Tailscale、Control UI

Systemd Quadlet（可选）

如果运行了 ./scripts/podman/setup.sh --quadlet，setup 会安装 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)"

Quadlet 默认配置说明：

• 固定发布 127.0.0.1:18789:18789（网关）和 127.0.0.1:18790:18790（bridge）
• 容器内使用 --bind lan，keep-id 用户命名空间
• 固定设置 OPENCLAW_NO_RESPAWN=1、Restart=on-failure 和 TimeoutStartSec=300
• 读取 ~/.openclaw/.env 作为运行时 EnvironmentFile，提供 OPENCLAW_GATEWAY_TOKEN 等值，但不消耗手动启动器的 Podman 特定覆盖允许列表
• 如需自定义端口、发布主机或其他 container-run 参数，使用手动启动脚本或直接编辑 Quadlet 文件

配置、环境变量和存储

• Config 目录： ~/.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、per-agent auth-profiles.json、渠道/提供商状态、会话和工作区在容器替换后依然保留。

手动启动器常用环境变量：

变量	说明
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	容器内网关绑定模式（默认 lan）
OPENCLAW_PODMAN_USERNS	keep-id（默认）、auto 或 host

常用命令

• 查看容器日志： podman logs -f openclaw
• 停止容器： podman stop openclaw
• 删除容器： podman rm -f openclaw
• 从主机 CLI 查看 Dashboard URL： openclaw dashboard --no-open
• 健康/状态检查： openclaw gateway status --deep

故障排查

• EACCES 权限拒绝： 容器默认以 --userns=keep-id 运行，确保主机 config/workspace 目录由你当前用户所有
• 网关启动被阻断（缺少 gateway.mode=local）： 确保 ~/.openclaw/openclaw.json 存在并设置了 gateway.mode="local"，scripts/podman/setup.sh 会自动创建
• 容器 CLI 命令打到了错误目标： 用 openclaw --container <name> ... 显式指定，或在 shell 中 export OPENCLAW_CONTAINER=<name>
• openclaw update 使用 --container 失败： 符合预期，重建/拉取镜像后重启容器或 Quadlet 服务
• Quadlet 服务无法启动： 运行 systemctl --user daemon-reload 后再 start；无头系统可能还需要 sudo loginctl enable-linger "$(whoami)"
• SELinux 阻断挂载： 无需处理，启动脚本在 Linux SELinux enforcing/permissive 时自动添加 :Z

相关文档

• Docker 部署
• 网关后台进程
• 网关故障排查

常见问题

Q: 在 macOS 上用 Podman 部署后，Control UI 一直报设备认证错误？

A: macOS 上 Podman machine 会使浏览器看起来不是本地访问，导致设备认证失败。建议使用 Tailscale Serve 获得 wss:// 端点，然后通过 Tailscale URL 访问 Control UI。

Q: 容器重启后数据会丢失吗？

A: 不会。状态通过挂载存储在主机 ~/.openclaw 目录，容器替换不影响配置、会话和工作区数据。

Q: Quadlet 服务启动失败怎么办？

A: 先运行 systemctl --user daemon-reload 重新加载配置，再执行 systemctl --user start openclaw.service。无头系统还需要执行 sudo loginctl enable-linger "$(whoami)" 以支持开机自启。