OpenClaw从入门到应用——安装：Podman

作者：von  Neumann
通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》
Podman

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

Podman（无根模式）一次性设置时需要 sudo 权限（用于创建用户、构建镜像）

快速开始

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

1. ./setup-podman.sh

复制代码

该脚本还会创建一个最小化的 ~openclaw/.openclaw/openclaw.json 配置文件（设置 gateway.mode="local"），以便网关无需运行向导即可直接启动。
默认情况下，容器不会被安装为 systemd 服务，而是需要手动启动（见下文）。若希望实现生产级配置（自动启动和重启），请改用 systemd Quadlet 用户服务方式安装：

1. ./setup-podman.sh --quadlet

复制代码

（或者设置环境变量 OPENCLAW_PODMAN_QUADLET=1；使用 --container 选项则仅安装容器和启动脚本。）
可选的构建期环境变量（在运行 setup-podman.sh 前设置）：

OPENCLAW_DOCKER_APT_PACKAGES —— 在镜像构建过程中额外安装 apt 软件包OPENCLAW_EXTENSIONS —— 预先安装扩展依赖项（以空格分隔的扩展名称列表，例如 diagnostics-otel matrix）

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

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

复制代码

3. 初始化向导（例如用于添加通道或提供者）：

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

复制代码

然后打开 http://127.0.0.1:18789/，并使用 ~openclaw/.openclaw/.env 中的令牌（或 setup 过程中打印出的值）进行访问。
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 时，setup 脚本会自动启用），则服务将在系统启动时自动运行。
若初始设置未使用 Quadlet，但后续希望添加，只需重新运行：./setup-podman.sh --quadlet。
openclaw 用户（非登录用户）

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

Shell：nologin —— 禁止交互式登录，以减少攻击面。
Home 目录： 例如 /home/openclaw —— 存放 ~/.openclaw（配置与工作区）以及启动脚本 run-openclaw-podman.sh。

• Rootless Podman： 该用户必须拥有 subuid 和 subgid 范围。许多发行版在创建用户时会自动分配这些范围。如果 setup 脚本输出警告，请向 /etc/subuid 和 /etc/subgid 添加如下行：
  1. openclaw:100000:65536

  复制代码
  然后以该用户身份启动网关（例如通过 cron 或 systemd）：
  1. sudo-u openclaw /home/openclaw/run-openclaw-podman.sh
  2. 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（桥接）。您可以通过在启动时设置 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 会被 bind-mount 到容器内，并在主机上保留状态。临时沙箱 tmpfs： 如果您启用了 agents.defaults.sandbox，工具沙箱容器会在 /tmp、/var/tmp 和 /run 挂载 tmpfs。这些路径基于内存，随沙箱容器销毁而消失；顶层 Podman 容器设置本身不会添加自己的 tmpfs 挂载。磁盘增长热点： 需重点关注的主要路径包括 media/、agents//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 —— 主机上的配置和工作区将被保留

故障排除

配置或 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 用户的 Rootless 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/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 命令，并将配置和工作区指向您的家目录。不过，我们仍建议大多数用户使用 setup-podman.sh 并以 openclaw 用户身份运行，以实现配置与进程的隔离。

原文地址：https://blog.csdn.net/hy592070616/article/details/159547076