From 8b74dcdf1e46889e18c3ded7cd63feac4752da5c Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 20:53:11 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/install/podman.md | 132 ++++++++++++++++++----------------- 1 file changed, 67 insertions(+), 65 deletions(-) diff --git a/docs/zh-CN/install/podman.md b/docs/zh-CN/install/podman.md index 3638689c5..0b3a6243c 100644 --- a/docs/zh-CN/install/podman.md +++ b/docs/zh-CN/install/podman.md @@ -1,32 +1,32 @@ --- read_when: - - 你想使用 Podman 而不是 Docker 来运行容器化 Gateway 网关 -summary: 在 rootless Podman 容器中运行 OpenClaw + - 你想使用 Podman 而不是 Docker 运行容器化的 Gateway 网关 +summary: 在无 root 权限的 Podman 容器中运行 OpenClaw title: Podman x-i18n: - generated_at: "2026-04-23T20:52:51Z" - model: gpt-5.4 + generated_at: "2026-04-28T20:52:39Z" + model: gpt-5.5 provider: openai - source_hash: 559ac707e0a3ef173d0300ee2f8c6f4ed664ff5afbf1e3f1848312a9d441e9e4 + source_hash: bfdcbbdb62c2f8ca2d6d370b742003e6f92f6921a38c00ba19e810d83e350647 source_path: install/podman.md - workflow: 15 + workflow: 16 --- 在 rootless Podman 容器中运行 OpenClaw Gateway 网关，并由你当前的非 root 用户管理。 -推荐的模型是： +预期模型是： -- Podman 运行 gateway 容器。 -- 你主机上的 `openclaw` CLI 是控制平面。 -- 持久化状态默认保存在主机上的 `~/.openclaw` 下。 +- Podman 运行 Gateway 网关容器。 +- 你的主机 `openclaw` CLI 是控制平面。 +- 默认情况下，持久状态位于主机的 `~/.openclaw` 下。 - 日常管理使用 `openclaw --container ...`，而不是 `sudo -u openclaw`、`podman exec` 或单独的服务用户。 -## 前置条件 +## 前提条件 -- 以 rootless 模式运行的 **Podman** -- 安装在主机上的 **OpenClaw CLI** -- **可选：** 如果你想使用 Quadlet 托管自动启动，需要 `systemd --user` -- **可选：** 仅当你希望在无头主机上使用 `loginctl enable-linger "$(whoami)"` 实现开机持久化时，才需要 `sudo` +- **Podman**，以 rootless 模式运行 +- 主机上已安装 **OpenClaw CLI** +- **可选：** 如果你希望使用 Quadlet 管理自动启动，则需要 `systemd --user` +- **可选：** 仅当你希望在无头主机上通过 `loginctl enable-linger "$(whoami)"` 实现开机持久运行时，才需要 `sudo` ## 快速开始 @@ -43,19 +43,19 @@ x-i18n: 运行 `./scripts/run-openclaw-podman.sh launch setup`，然后打开 `http://127.0.0.1:18789/`。 - - 设置 `OPENCLAW_CONTAINER=openclaw`，然后在主机上使用普通的 `openclaw` 命令。 + + 设置 `OPENCLAW_CONTAINER=openclaw`，然后从主机使用常规 `openclaw` 命令。 设置详情： -- `./scripts/podman/setup.sh` 默认会在你的 rootless Podman 存储中构建 `openclaw:local`，或者如果你设置了 `OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`，则会使用它们。 -- 如果缺失，它会创建 `~/.openclaw/openclaw.json`，并写入 `gateway.mode: "local"`。 -- 如果缺失，它会创建 `~/.openclaw/.env`，并写入 `OPENCLAW_GATEWAY_TOKEN`。 -- 对于手动启动，辅助脚本只会从 `~/.openclaw/.env` 中读取一小部分与 Podman 相关的 allowlist 键，并将显式运行时环境变量传给容器；它不会把整个 env 文件直接交给 Podman。 +- `./scripts/podman/setup.sh` 默认会在你的 rootless Podman 存储中构建 `openclaw:local`，如果你设置了 `OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`，则使用该镜像。 +- 如果缺失，它会创建带有 `gateway.mode: "local"` 的 `~/.openclaw/openclaw.json`。 +- 如果缺失，它会创建带有 `OPENCLAW_GATEWAY_TOKEN` 的 `~/.openclaw/.env`。 +- 对于手动启动，该辅助脚本只会从 `~/.openclaw/.env` 读取一小组与 Podman 相关的允许键，并向容器传递明确的运行时环境变量；它不会把完整的环境文件交给 Podman。 -Quadlet 托管设置： +Quadlet 管理的设置： ```bash ./scripts/podman/setup.sh --quadlet @@ -67,9 +67,10 @@ Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。 可选的构建/设置环境变量： -- `OPENCLAW_IMAGE` 或 `OPENCLAW_PODMAN_IMAGE` —— 使用现有/已拉取镜像，而不是构建 `openclaw:local` -- `OPENCLAW_DOCKER_APT_PACKAGES` —— 在镜像构建期间安装额外的 apt 包 -- `OPENCLAW_EXTENSIONS` —— 在构建时预安装插件依赖 +- `OPENCLAW_IMAGE` 或 `OPENCLAW_PODMAN_IMAGE` -- 使用已有/已拉取的镜像，而不是构建 `openclaw:local` +- `OPENCLAW_DOCKER_APT_PACKAGES` -- 在镜像构建期间安装额外的 apt 软件包 +- `OPENCLAW_EXTENSIONS` -- 在构建时预安装插件依赖 +- `OPENCLAW_INSTALL_BROWSER` -- 为浏览器自动化预安装 Chromium 和 Xvfb（设置为 `1` 以启用） 容器启动： @@ -77,7 +78,7 @@ Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。 ./scripts/run-openclaw-podman.sh launch ``` -该脚本会以你当前的 uid/gid 和 `--userns=keep-id` 启动容器，并将你的 OpenClaw 状态通过 bind mount 挂载进容器。 +该脚本会以你当前的 uid/gid，使用 `--userns=keep-id` 启动容器，并将你的 OpenClaw 状态绑定挂载到容器中。 新手引导： @@ -93,18 +94,18 @@ Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。 export OPENCLAW_CONTAINER=openclaw ``` -然后以下命令会自动在该容器中运行： +随后，这些命令会自动在该容器内运行： ```bash openclaw dashboard --no-open -openclaw gateway status --deep # 包括额外服务扫描 +openclaw gateway status --deep # includes extra service scan openclaw doctor openclaw channels login ``` -在 macOS 上，Podman machine 可能会让浏览器对 gateway 来说看起来不像本地浏览器。 -如果启动后控制 UI 报告 device-auth 错误，请使用 -[Podman + Tailscale](#podman--tailscale) 中的 Tailscale 指引。 +在 macOS 上，Podman machine 可能会让浏览器对 Gateway 网关而言看起来不像本地访问。 +如果 Control UI 在启动后报告设备认证错误，请使用 +[Podman + Tailscale](#podman--tailscale) 中的 Tailscale 指南。 @@ -114,18 +115,18 @@ openclaw channels login Podman 特定说明： -- 保持 Podman 发布主机为 `127.0.0.1`。 -- 优先使用由主机托管的 `tailscale serve`，而不是 `openclaw gateway --tailscale serve`。 -- 在 macOS 上，如果本地浏览器 device-auth 上下文不可靠，请使用 Tailscale 访问，而不是临时性的本地隧道变通方案。 +- 将 Podman 发布主机保持为 `127.0.0.1`。 +- 优先使用由主机管理的 `tailscale serve`，而不是 `openclaw gateway --tailscale serve`。 +- 在 macOS 上，如果本地浏览器设备认证上下文不可靠，请使用 Tailscale 访问，而不是临时的本地隧道变通方法。 -请参阅： +参见： - [Tailscale](/zh-CN/gateway/tailscale) -- [控制 UI](/zh-CN/web/control-ui) +- [控制界面](/zh-CN/web/control-ui) ## Systemd（Quadlet，可选） -如果你运行了 `./scripts/podman/setup.sh --quadlet`，setup 会在以下位置安装一个 Quadlet 文件： +如果你运行了 `./scripts/podman/setup.sh --quadlet`，设置会在以下位置安装 Quadlet 文件： ```bash ~/.config/containers/systemd/openclaw.container @@ -135,7 +136,7 @@ Podman 特定说明： - **启动：** `systemctl --user start openclaw.service` - **停止：** `systemctl --user stop openclaw.service` -- **状态：** `systemctl --user status openclaw.service` +- **Status：** `systemctl --user status openclaw.service` - **日志：** `journalctl --user -u openclaw.service -f` 编辑 Quadlet 文件后： @@ -145,7 +146,7 @@ systemctl --user daemon-reload systemctl --user restart openclaw.service ``` -若要在 SSH/无头主机上实现开机持久化，请为你当前用户启用 lingering： +要在 SSH/无头主机上实现开机持久运行，请为你当前用户启用 lingering： ```bash sudo loginctl enable-linger "$(whoami)" @@ -158,36 +159,36 @@ sudo loginctl enable-linger "$(whoami)" - **令牌文件：** `~/.openclaw/.env` - **启动辅助脚本：** `./scripts/run-openclaw-podman.sh` -启动脚本和 Quadlet 都会将主机状态通过 bind mount 挂载进容器： +启动脚本和 Quadlet 会将主机状态绑定挂载到容器中： - `OPENCLAW_CONFIG_DIR` -> `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR` -> `/home/node/.openclaw/workspace` -默认情况下，这些都是主机目录，而不是匿名容器状态，因此 -`openclaw.json`、每智能体的 `auth-profiles.json`、渠道/提供商状态、 -会话以及工作区都能在容器替换后保留。 -Podman 设置还会为 `127.0.0.1` 和 `localhost` 在已发布的 gateway 端口上初始化 `gateway.controlUi.allowedOrigins`，以便本地仪表盘能够与容器的非 loopback 绑定配合工作。 +默认情况下，这些是主机目录，而不是匿名容器状态，因此 +`openclaw.json`、每个智能体的 `auth-profiles.json`、渠道/提供商状态、 +会话和工作区都会在容器替换后保留下来。 +Podman 设置还会为已发布的 Gateway 网关端口上的 `127.0.0.1` 和 `localhost` 填充 `gateway.controlUi.allowedOrigins`，使本地仪表板能够配合容器的非 loopback 绑定正常工作。 -手动启动器有用的环境变量： +手动启动器的常用环境变量： -- `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` —— 容器内的 gateway 绑定模式；默认是 `lan` -- `OPENCLAW_PODMAN_USERNS` —— `keep-id`（默认）、`auto` 或 `host` +- `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` -- 容器内的 Gateway 网关绑定模式；默认是 `lan` +- `OPENCLAW_PODMAN_USERNS` -- `keep-id`（默认）、`auto` 或 `host` -手动启动器会在确定容器/镜像默认值之前读取 `~/.openclaw/.env`，因此你可以将这些值持久化在那里。 +手动启动器会在最终确定容器/镜像默认值之前读取 `~/.openclaw/.env`，因此你可以在那里持久保存这些设置。 -如果你使用了非默认的 `OPENCLAW_CONFIG_DIR` 或 `OPENCLAW_WORKSPACE_DIR`，请确保在 `./scripts/podman/setup.sh` 和后续的 `./scripts/run-openclaw-podman.sh launch` 命令中都设置相同变量。仓库内的启动器不会在不同 shell 会话之间持久化自定义路径覆盖项。 +如果你使用非默认的 `OPENCLAW_CONFIG_DIR` 或 `OPENCLAW_WORKSPACE_DIR`，请为 `./scripts/podman/setup.sh` 和之后的 `./scripts/run-openclaw-podman.sh launch` 命令设置相同变量。仓库本地启动器不会在不同 shell 之间持久保存自定义路径覆盖。 Quadlet 说明： -- 生成的 Quadlet 服务有意保持固定、加固后的默认形态：发布端口为 `127.0.0.1`，容器内使用 `--bind lan`，以及 `keep-id` 用户命名空间。 +- 生成的 Quadlet 服务会有意保持固定、加固的默认形态：`127.0.0.1` 发布端口、容器内 `--bind lan`，以及 `keep-id` 用户命名空间。 - 它固定设置 `OPENCLAW_NO_RESPAWN=1`、`Restart=on-failure` 和 `TimeoutStartSec=300`。 -- 它会同时发布 `127.0.0.1:18789:18789`（gateway）和 `127.0.0.1:18790:18790`（bridge）。 -- 它会把 `~/.openclaw/.env` 读取为运行时 `EnvironmentFile`，用于如 `OPENCLAW_GATEWAY_TOKEN` 之类的值，但不会消费手动启动器的 Podman 专用覆盖 allowlist。 +- 它同时发布 `127.0.0.1:18789:18789`（Gateway 网关）和 `127.0.0.1:18790:18790`（bridge）。 +- 它会将 `~/.openclaw/.env` 作为运行时 `EnvironmentFile` 读取，用于 `OPENCLAW_GATEWAY_TOKEN` 等值，但不会使用手动启动器的 Podman 特定覆盖允许列表。 - 如果你需要自定义发布端口、发布主机或其他容器运行标志，请使用手动启动器，或直接编辑 `~/.config/containers/systemd/openclaw.container`，然后重新加载并重启服务。 ## 常用命令 @@ -195,17 +196,18 @@ Quadlet 说明： - **容器日志：** `podman logs -f openclaw` - **停止容器：** `podman stop openclaw` - **移除容器：** `podman rm -f openclaw` -- **从主机 CLI 打开仪表盘 URL：** `openclaw dashboard --no-open` -- **通过主机 CLI 查看健康/状态：** `openclaw gateway status --deep`（RPC 探测 + 额外服务扫描） +- **从主机 CLI 打开仪表板 URL：** `openclaw dashboard --no-open` +- **通过主机 CLI 查看健康/状态：** `openclaw gateway status --deep`（RPC 探测 + 额外的 + 服务扫描） ## 故障排除 -- **配置或工作区出现 Permission denied（EACCES）：** 容器默认使用 `--userns=keep-id` 和 `--user :` 运行。请确保主机上的配置/工作区路径属于你当前用户。 -- **Gateway 网关启动被阻止（缺少 `gateway.mode=local`）：** 请确保 `~/.openclaw/openclaw.json` 存在，并设置了 `gateway.mode="local"`。如果缺失，`scripts/podman/setup.sh` 会创建它。 -- **容器 CLI 命令命中了错误目标：** 请显式使用 `openclaw --container ...`，或在 shell 中导出 `OPENCLAW_CONTAINER=`。 -- **`openclaw update` 在 `--container` 下失败：** 这是预期行为。请重新构建/拉取镜像，然后重启容器或 Quadlet 服务。 -- **Quadlet 服务未启动：** 运行 `systemctl --user daemon-reload`，然后执行 `systemctl --user start openclaw.service`。在无头系统上，你还可能需要 `sudo loginctl enable-linger "$(whoami)"`。 -- **SELinux 阻止 bind mounts：** 保持默认挂载行为不变；当 SELinux 处于 enforcing 或 permissive 模式时，启动器会在 Linux 上自动添加 `:Z`。 +- **配置或工作区上权限被拒绝（EACCES）：** 默认情况下，容器使用 `--userns=keep-id` 和 `--user :` 运行。确保主机配置/工作区路径归你当前用户所有。 +- **Gateway 网关启动被阻止（缺少 `gateway.mode=local`）：** 确保 `~/.openclaw/openclaw.json` 存在，并设置了 `gateway.mode="local"`。如果缺失，`scripts/podman/setup.sh` 会创建它。 +- **容器 CLI 命令命中了错误目标：** 显式使用 `openclaw --container ...`，或在你的 shell 中导出 `OPENCLAW_CONTAINER=`。 +- **`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`。 ## 相关内容