Skip to main content

​
openclaw fleet

openclaw fleet 用于管理称为 单元 的完整 OpenClaw 实例。每个单元都有自己独立的 Gateway、状态、凭据、频道账户、容器，以及仅限回环的主机端口。每个租户信任边界使用一个单元；不要将一个共享 Gateway 用作恶意的多租户边界。 Fleet 是实验性功能。命令名称、标志、输出形式以及容器配置文件可能会在不同版本之间更改，而不会提供弃用过渡期。 Fleet 支持 Docker 和 Podman。默认镜像是 ghcr.io/openclaw/openclaw:latest。 Fleet 已在 Linux 和 macOS 主机上测试。Windows 主机目前尚未测试。

​
快速开始

fleet create 会将生成的 Gateway token 与 cell URL 一并仅打印一次。请立即保存该 token，然后在该租户的 cell 内配置每个租户的渠道账号。

​
租户 ID

租户 ID 必须匹配：
这允许 1 到 40 个小写字母、数字和内部连字符。ID 必须以字母或数字开头和结尾。不允许大写字母、下划线、斜杠、点、空白字符，以及诸如 ../acme 之类的路径遍历字符串。 该 ID 会成为容器名称的一部分：openclaw-cell-<tenant>。

​
fleet create

创建一个 cell 并启动它：
在固定端口上创建一个 Podman cell，但不启动它：
通过重复使用 --env 传递租户特定的环境变量：
环境键使用字母、数字和下划线，且不能以数字开头。值必须是单行的，因为 Fleet 会将它们通过受保护的运行时环境文件传递。Fleet 会拒绝覆盖存储和容器布局中列出的受管容器路径和 Gateway 令牌变量的尝试。

​
创建选项

自动分配会选择第一个未使用且大于等于 19100 的注册端口。Fleet 会拒绝重复的租户 ID，以及已分配给其他 cell 的显式端口。 镜像引用会作为一个容器运行时参数传递。空引用以及以 - 开头的值会被拒绝，因此镜像不会被解释为 Docker 或 Podman 选项。 所选的 Docker 或 Podman 端点必须是本地端点。Fleet 会在保留端口或创建本地状态之前，拒绝远程 Docker 上下文、DOCKER_HOST 端点以及远程 Podman 服务。不支持远程 cell 主机。 当 Fleet 启动一个新 cell 时，create 最多会等待大约一分钟，直到它的 Gateway 响应 /healthz。如果该 cell 没有变为健康状态，Fleet 会保留其容器和注册表行，以便 fleet status、fleet logs 或显式移除使用。--no-start 会跳过这个健康检查门。新建但不健康的 cell 所生成的 Gateway 令牌不会丢失——它仍保留在容器环境中（docker|podman inspect 可见），并且因为该 cell 还未服务任何流量，fleet rm --force 后再重新创建始终是安全的替代方案。

​
按摘要固定

create 和 upgrade 接受按摘要固定的镜像引用，例如 --image ghcr.io/openclaw/openclaw@sha256:<digest>。Fleet 会将该镜像引用原样传递给 Docker 或 Podman，这使操作员可以让 cell 保持在不可变的镜像字节上，而不是会变化的标签上。 create 的结果包含租户 ID、容器名称、主机端口、Gateway 令牌和本地 URL。即使在 JSON 输出中，也应将结果视为包含秘密，因为它包含令牌。

​
磁盘限制

--disk 只限制容器可写层。按租户绑定挂载的状态目录和认证目录仍然是主机存储；如果这些目录也需要硬性限制，请使用主机文件系统项目配额。

​
出站策略

对于 Docker，请保持 bridge 模式，并使用主机防火墙规则（例如 DOCKER-USER 链）来实施出站策略。

​
fleet list

按 tenant-ID 顺序列出单元：
该表包含： 当 Docker 或 Podman 不可用时，注册表行仍然可见；只有实时状态会变为 unknown。

​
fleet status

检查一个单元：
状态会结合舰队注册表中的行、实时容器检查，以及一次简短的尽力请求到：
健康结果为 ok、failed 或 skipped。/healthz 证明的是 Gateway 存活，而不是所有已配置通道或插件的完全就绪状态。当没有可用的本地端点可供检查时，会跳过该探测。

​
fleet logs

将单元的容器日志直接流式输出到终端：
Fleet 在读取任何日志之前会验证已注册容器的所有权标签，因此它会拒绝使用期望单元名称的外部容器。该流会绑定到经过检查的容器 ID，因此并发替换不会将其重定向到更新的代际。按 Ctrl-C 可结束 --follow，且不会将操作员停止视为命令失败。日志输出会经过脱敏过滤器处理，该过滤器会在任何内容到达终端之前，将单元当前的 Gateway token 替换为 <redacted>。 fleet logs 没有 --json 模式，因为容器日志是原始的 stdout/stderr 流。对于脚本，请使用 --tail 限制输出，并使用普通的 shell 重定向或管道。

​
fleet start、fleet stop 和 fleet restart

使用其记录的运行时控制现有的单元：
这些命令作用于已注册的容器名称。如果租户未知，或者记录的运行时无法执行该操作，则会失败。

​
fleet upgrade

重新拉取已记录的镜像并替换单元容器：
将单元切换到另一个镜像：
升级会拉取目标镜像，检查现有容器和每个单元的网络，停止并移除该容器，然后重新创建并启动它。替换后的容器会保留相同的主机端口、数据目录、每个单元的桥接网络、运行时配置、资源限制、重启策略、Fleet 管理的环境，以及最初通过 --env 提供的值。挂载的状态在容器替换后仍会保留；镜像默认环境可能会随着目标镜像而变化。 只有当其 Gateway 在该单元的回环端口上对 /healthz 作出响应后，替换才会被提交，这与官方 compose 文件使用的健康检查契约一致。若替换后的容器退出、进入崩溃循环，或在大约一分钟内未能变为健康状态，它会被移除并恢复之前的容器，因此有问题的镜像不会导致正常工作的单元下线。 Gateway 令牌故意不会存储在 fleet registry 中。在移除旧容器之前，Fleet 会读取其环境并将 OPENCLAW_GATEWAY_TOKEN 带入替换后的容器。若该令牌没有存放在你可控制的其他任何地方，在升级前不要手动移除旧容器。

​
fleet backup 和 fleet restore

备份一个已停止的 cell：
将该归档恢复到已注册的 cell 中：
这些都是需要主机运维者权限的命令。归档包含租户状态和认证密钥，创建时权限为 0600，必须像凭据一样存储。备份会拒绝对运行中的 cell 执行，以便 SQLite 状态被一致地捕获。除非提供 --force，恢复会拒绝对运行中的 cell 执行；它只替换该租户的状态，轮换 Gateway token，并且只打印一次新的 token。Fleet 一次只备份一个租户；全租户备份是单独的运维操作。 恢复需要一个现有的已停止容器，因为其检查到的运行时配置会提供替换后的限制、用户映射、环境来源以及镜像。如果已注册的容器在外部被移除，请先在不使用 --purge-data 的情况下运行 fleet rm <tenant> --force，然后使用预期的镜像和 --no-start 重新创建该 cell，再重试恢复。第一次移除会保留两个租户数据目录不变。 这两个命令都接受 --max-bytes <bytes> 来限制归档或解压后的文件数据大小，并且都应用相同的固定一百万档案路径段预算，这样仅包含元数据的归档炸弹就无法耗尽主机的 inode，同时每个被接受的备份都仍然可以恢复。备份接受 --out <path>，而这两个命令都支持 --json。 归档只包含普通文件和目录。备份从不跟随或存储符号链接、硬链接、套接字或设备节点；跳过的数量会在结果中报告。恢复会拒绝包含任何其他条目类型的归档，忽略归档中的所有权信息，并在应用 cell 运行时所有者之前对恢复的文件和目录模式进行夹紧。像工作区 node_modules 这类可重建的符号链接树，在恢复后必须在 cell 内重新安装。

​
fleet doctor

审计每个单元或单个租户，而不更改运行时或文件系统状态：
Doctor 会检查运行时本地性、所有权标签、健康状态、加固、资源限制、回环端口绑定、令牌存在性、网络所有权和出站模式，以及私有状态目录权限。警告会描述已停止的单元或所有权差异；任何失败的发现都会设置非零的进程退出码。

​
fleet rm

从运行时和注册表中移除已停止的 cell，同时保留租户数据：
运行中的容器需要 --force：
同时永久删除 cell 数据：
Fleet 会先移除 cell 容器，然后再移除其专用 bridge 网络。--purge-data 需要 --force。在递归删除之前，Fleet 会解析两个 Fleet 所拥有的根目录以及两个每租户目录。每个目标必须是完全符合预期的租户叶子节点，严格位于其根目录内，并且不能是符号链接。这些包含性检查可防止损坏的注册表路径或跨租户符号链接将删除重定向到其他位置。 如果一个完全符合预期的租户目录已经不存在，Purge 可重试。这使得在部分文件系统故障之后，后续调用可以完成清理，而不会对仍然存在的目录放宽路径检查。

​
存储和容器布局

单元状态和 auth-profile 加密密钥使用位于活动 OpenClaw 状态目录下、按租户划分的独立主机路径：
第一个目录挂载到 /home/node/.openclaw。第二个目录挂载到 /home/node/.config/openclaw，与官方 Docker 设置的加密密钥挂载保持一致。因此，加密密钥不会暴露在普通状态挂载下，也不会在仅备份或共享单元状态目录时被包含进去。这两个目录在正常删除和升级后都会保留；fleet rm --purge-data --force 会在分别进行隔离检查后删除两者。 在首次启动前，Fleet 会用 gateway.mode=local、token 认证、LAN 容器绑定以及所分配主机端口的 Control UI 来源来初始化单元配置。token 值不会写入该配置；它仍保留在容器环境中。 Fleet 使用以下环境值固定官方镜像的容器路径： 官方镜像默认使用非 root 的 node 用户，UID 为 1000。Fleet 保持私有的 0700 绑定挂载可写，而不将其设为全局可访问。rootful Docker 以调用者的非 root UID 和 GID 运行该单元；rootless Docker 使用容器 UID 0，它在守护进程的用户命名空间中映射为调用者的非特权主机用户。Podman 使用 keep-id，并采用调用者的 UID 和 GID。当 Fleet 本身以 root 身份在 rootful 运行时环境上运行时，它会保留镜像用户，并将初始挂载文件分配给 UID/GID 1000。 在启用 SELinux 的主机上，Docker 和 Podman 挂载会收到私有的 :Z 重新标记。如果你恢复或迁移单元数据，请保持绑定挂载路径对有效的容器用户可写。该配置文件对 rootless 友好，但 Docker 或 Podman 必须已在主机上配置为 rootless 运行；Fleet 不会将 rootful 守护进程转换为 rootless 守护进程。

​
安全配置文件

Fleet 会将以下配置文件应用于每个 cell： Fleet 从不挂载 /var/run/docker.sock，不使用 --privileged 或主机网络，也不添加 capabilities。按 cell 划分的 bridge 是跨 cell 的隔离边界，而不是出站防火墙：cell 仍保留提供程序和通道所需的网络出站能力。请在回环端口前放置一个与您的部署相匹配的代理、SSH 隧道或 tailnet 配置。http://127.0.0.1:<port> 只能从 Fleet 主机直接访问。 此配置文件将租户容器彼此隔离，但它并不能保护租户免受 Fleet 操作员、容器运行时管理员或被攻陷主机的影响。有关完整的信任模型和更强的隔离选项，请参阅 多租户托管。

​
令牌处理

默认情况下，fleet create 会生成一个加密学随机的 32 字符十六进制 Gateway 令牌，并在创建结果中仅打印一次。请将其存储在你批准使用的密钥管理器中，并避免将创建输出捕获到日志里。 --gateway-token 会把自定义令牌放入本地进程参数中，这些参数可能会保留在 shell 历史记录里，或在进程列表中可见。除非现有的密钥管理工作流需要提供一个值，否则请优先使用生成的令牌。 令牌以及通过 --env 传入的每个值都会存在于容器环境中。Fleet 会将它们写入一个短生命周期、权限为 0600 的环境文件，只把该文件路径传给 Docker 或 Podman，并在运行时命令结束后将其删除。在 openclaw fleet create --gateway-token ... 或 --env KEY=VALUE 中显式输入的值，仍可能在外层 openclaw 进程参数和 shell 历史记录中可见。 容器环境变量并不会对受信任的主机操作员隐藏：Docker 或 Podman 管理员可以通过容器检查读取它们。Fleet 中“仅显示一次”的说明描述的是正常的 CLI 输出，而不是对主机管理员的防护。

​
相关内容