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 则只安装容器和启动脚本。）

可选的构建时环境变量（在运行 setup-podman.sh 前设置）：

OPENCLAW_DOCKER_APT_PACKAGES — 构建时安装额外的 apt 包
OPENCLAW_EXTENSIONS — 预安装扩展依赖（空格分隔的扩展名，如 diagnostics-otel matrix）

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

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

3. 引导向导（例如添加渠道或提供商）：

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

然后打开 http://127.0.0.1:18789/ 并使用 ~openclaw/.openclaw/.env 中的 token（或配置时打印的值）。

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 用户启用了 lingering（setup 会在 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 范围。多数发行版会在创建用户时自动分配。如果 setup 打印警告，在 /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。

环境变量和配置

Token： 存储在 ~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（bridge）。启动时通过 OPENCLAW_PODMAN_GATEWAY_HOST_PORT 和 OPENCLAW_PODMAN_BRIDGE_HOST_PORT 覆盖主机端口映射。
网关绑定： 默认 run-openclaw-podman.sh 以 --bind loopback 启动网关，确保安全的本地访问。要暴露到局域网，设置 OPENCLAW_GATEWAY_BIND=lan 并在 openclaw.json 中配置 gateway.controlUi.allowedOrigins（或显式启用 host-header 回退）。
路径： 主机配置和工作区默认为 ~openclaw/.openclaw 和 ~openclaw/.openclaw/workspace。通过 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 覆盖启动脚本使用的主机路径。

存储模型

持久化主机数据： OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 被绑定挂载到容器中，状态保留在主机上。
临时沙箱 tmpfs： 如果启用了 agents.defaults.sandbox，工具沙箱容器会在 /tmp、/var/tmp 和 /run 挂载 tmpfs。这些路径基于内存，随沙箱容器消失而消失；顶层 Podman 容器配置不会添加自己的 tmpfs 挂载。
磁盘增长热点： 主要关注 media/、agents/<agentId>/sessions/sessions.json、转录 JSONL 文件、cron/runs/*.jsonl，以及 /tmp/openclaw/ 下的滚动文件日志（或你配置的 logging.file）。

setup-podman.sh 现在将镜像 tar 暂存在私有临时目录中，并在配置过程中打印所选的基础目录。对于非 root 运行，仅在基础目录安全可用时才接受 TMPDIR；否则回退到 /var/tmp，再到 /tmp。保存的 tar 文件仅所有者可读，并通过流式传输到目标用户的 podman load，因此调用者的私有临时目录不会阻碍配置。

常用命令

日志： 使用 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 — 主机上的配置和工作区会保留

排错

配置或认证文件权限拒绝（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/.env 并设置 OPENCLAW_GATEWAY_TOKEN，然后用 --userns=keep-id 运行容器并挂载到你的 ~/.openclaw。启动脚本是为 openclaw 用户流程设计的；对于单用户配置，你可以直接手动运行脚本中的 podman run 命令，将配置和工作区指向你的 home 目录。对大多数用户推荐：使用 setup-podman.sh 并以 openclaw 用户运行，这样配置和进程都是隔离的。