OpenClaw 🦞

Podman

Podman

在无根 Podman 容器中运行 OpenClaw 网关。使用与 Docker 相同的镜像（从仓库 Dockerfile 构建）。

要求

  • Podman（无根）
  • Sudo 用于一次性设置（创建用户、构建镜像）

快速开始

1. 一次性设置（从仓库根目录；创建用户、构建镜像、安装启动脚本）：

./setup-podman.sh

这还会创建最小的 ~openclaw/.openclaw/openclaw.json（设置 gateway.mode="local"），以便网关可以在不运行向导的情况下启动。

默认情况下，容器不安装为 systemd 服务，你手动启动它（见下文）。对于带有自动启动和重启的生产风格设置，改为将其安装为 systemd Quadlet 用户服务：

./setup-podman.sh --quadlet

（或设置 OPENCLAW_PODMAN_QUADLET=1；使用 --container 仅安装容器和启动脚本。）

2. 启动网关（手动，用于快速冒烟测试）：

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

3. 入门向导（例如添加频道或提供商）：

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

然后打开 http://127.0.0.1:18789/ 并使用来自 ~openclaw/.openclaw/.env 的令牌（或设置打印的值）。

Systemd（Quadlet，可选）

如果运行了 ./setup-podman.sh --quadlet（或 OPENCLAW_PODMAN_QUADLET=1），会安装 Podman Quadlet 单元，以便网关作为 openclaw 用户的 systemd 用户服务运行。服务在设置结束时启用并启动。

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

quadlet 文件位于 ~openclaw/.config/containers/systemd/openclaw.container。要更改端口或环境变量，编辑该文件（或其引用的 .env），然后 sudo systemctl --machine openclaw@ --user daemon-reload 并重启服务。启动时，如果为 openclaw 启用了 linger（设置时在 loginctl 可用时执行此操作），服务会自动启动。

要在未使用 quadlet 的初始设置后添加 quadlet，重新运行：./setup-podman.sh --quadlet。

openclaw 用户（非登录）

setup-podman.sh 创建专用的系统用户 openclaw：

  • Shell： nologin — 无交互式登录；减少攻击面。

  • Home： 例如 /home/openclaw — 包含 ~/.openclaw（配置、工作区）和启动脚本 run-openclaw-podman.sh。

  • 无根 Podman： 用户必须有 subuid 和 subgid 范围。许多发行版在创建用户时自动分配这些。如果设置打印警告，添加行到 /etc/subuid 和 /etc/subgid：

    openclaw:100000:65536

    然后作为该用户启动网关（例如从 cron 或 systemd）：

    sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup

  • 配置： 只有 openclaw 和 root 可以访问 /home/openclaw/.openclaw。要编辑配置：网关运行后使用 Control UI，或 sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json。

环境和配置

  • 令牌： 存储在 ~openclaw/.openclaw/.env 中为 OPENCLAW_GATEWAY_TOKEN。如果缺少，setup-podman.sh 和 run-openclaw-podman.sh 会生成它（使用 openssl、python3 或 od）。
  • 可选： 在该 .env 中你可以设置提供商密钥（例如 GROQ_API_KEY、OLLAMA_API_KEY）和其他 OpenClaw 环境变量。
  • 主机端口： 默认情况下，脚本映射 18789（网关）和 18790（桥接）。启动时使用 OPENCLAW_PODMAN_GATEWAY_HOST_PORT 和 OPENCLAW_PODMAN_BRIDGE_HOST_PORT 覆盖主机端口映射。
  • 网关绑定： 默认情况下，run-openclaw-podman.sh 使用 --bind loopback 启动网关以进行安全的本地访问。要在 LAN 上暴露，设置 OPENCLAW_GATEWAY_BIND=lan 并在 openclaw.json 中配置 gateway.controlUi.allowedOrigins（或明确启用主机头回退）。
  • 路径： 主机配置和工作区默认为 ~openclaw/.openclaw 和 ~openclaw/.openclaw/workspace。使用 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 覆盖启动脚本使用的主机路径。

有用的命令

  • 日志： 使用 quadlet：sudo journalctl --machine openclaw@ --user -u openclaw.service -f。使用脚本：sudo -u openclaw podman logs -f openclaw
  • 停止： 使用 quadlet：sudo systemctl --machine openclaw@ --user stop openclaw.service。使用脚本：sudo -u openclaw podman stop openclaw
  • 再次启动： 使用 quadlet：sudo systemctl --machine openclaw@ --user start openclaw.service。使用脚本：重新运行启动脚本或 podman start openclaw
  • 移除容器： sudo -u openclaw podman rm -f openclaw — 主机上的配置和工作区保留

故障排除

  • 配置或 auth-profiles 上的权限被拒绝（EACCES）： 容器默认使用 --userns=keep-id 并以与运行脚本的主机用户相同的 uid/gid 运行。确保你的主机 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 由该用户拥有。
  • 网关启动被阻止（缺少 gateway.mode=local）： 确保 ~openclaw/.openclaw/openclaw.json 存在并设置 gateway.mode="local"。如果缺少，setup-podman.sh 会创建此文件。
  • 用户 openclaw 的无根 Podman 失败： 检查 /etc/subuid 和 /etc/subgid 包含 openclaw 的行（例如 openclaw:100000:65536）。如果缺少则添加并重启。
  • 容器名称在使用中： 启动脚本使用 podman run --replace，因此再次启动时会替换现有容器。要手动清理：podman rm -f openclaw。
  • 作为 openclaw 运行时找不到脚本： 确保运行了 setup-podman.sh 以便 run-openclaw-podman.sh 被复制到 openclaw 的 home（例如 /home/openclaw/run-openclaw-podman.sh）。
  • Quadlet 服务未找到或启动失败： 编辑 .container 文件后运行 sudo systemctl --machine openclaw@ --user daemon-reload。Quadlet 需要 cgroups v2：podman info --format '{{.Host.CgroupsVersion}}' 应显示 2。

可选：作为你自己的用户运行

要作为你的普通用户运行网关（无专用的 openclaw 用户）：构建镜像，创建包含 OPENCLAW_GATEWAY_TOKEN 的 ~/.openclaw/.env，并使用 --userns=keep-id 和挂载到你的 ~/.openclaw 运行容器。启动脚本专为 openclaw 用户流程设计；对于单用户设置，你可以改为手动运行脚本中的 podman run 命令，将配置和工作区指向你的 home。推荐大多数用户：使用 setup-podman.sh 并作为 openclaw 用户运行，以便配置和进程隔离。