--- read_when: - 你在一台機器上託管多個租戶信任網域 - 你需要建立、檢查、升級或移除機群單元 summary: 用於佈建及管理隔離的每租戶 OpenClaw 單元之命令列介面參考文件 title: 機群 x-i18n: generated_at: "2026-07-12T14:22:09Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 15 provider: openai source_hash: 1160c1242073f506c2a2f98481f4ec933a073fd3da0bc20c4cee3e146a38e293 source_path: cli/fleet.md workflow: 16 --- # `openclaw fleet` `openclaw fleet` 管理稱為 **cell** 的完整 OpenClaw 執行個體。每個 cell 都有自己的閘道、狀態、認證資訊、頻道帳號、容器，以及僅限迴路介面的主機連接埠。每個租戶信任邊界應使用一個 cell；請勿將單一共用閘道用作不受信任的多租戶邊界。 Fleet 目前為**實驗性功能**。在介面穩定之前，命令名稱、旗標、輸出格式及容器設定檔可能會在各版本之間變更，且不提供棄用過渡期。 Fleet 支援 Docker 與 Podman。預設映像檔為 `ghcr.io/openclaw/openclaw:latest`。 Fleet 已在 Linux 與 macOS 主機上測試。目前尚未測試 Windows 主機。 ## 快速開始 ```bash openclaw fleet create acme openclaw fleet status acme openclaw fleet list ``` `fleet create` 會連同 cell URL 一次性顯示產生的閘道權杖。請立即儲存權杖，然後在各租戶自己的 cell 中設定其頻道帳號。 ## 租戶 ID 租戶 ID 必須符合： ```text ^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$ ``` 此格式允許 1 至 40 個小寫字母、數字及內部連字號。ID 的開頭與結尾必須是字母或數字。大寫字母、底線、斜線、句點、空白，以及 `../acme` 等路徑遍歷字串都會遭到拒絕。 此 ID 會成為容器名稱的一部分：`openclaw-cell-`。 ## `fleet create` 建立並啟動 cell： ```bash openclaw fleet create acme ``` 在固定連接埠上建立 Podman cell，但不啟動： ```bash openclaw fleet create acme \ --runtime podman \ --port 19125 \ --no-start ``` 重複使用 `--env` 以傳入租戶專屬的環境變數： ```bash openclaw fleet create acme \ --env TZ=America/Los_Angeles \ --env OPENCLAW_DISABLE_BONJOUR=1 ``` 環境變數鍵可使用字母、數字與底線，且不得以數字開頭。由於 Fleet 會透過受保護的執行階段環境檔案傳遞值，因此值必須為單行。若嘗試覆寫[儲存空間與容器配置](#storage-and-container-layout)中列出的受管理容器路徑與閘道權杖變數，Fleet 會予以拒絕。 ### 建立選項 | 選項 | 預設值 | 說明 | | ------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ | | `--image ` | `ghcr.io/openclaw/openclaw:latest` | cell 的容器映像檔。 | | `--runtime ` | `docker` | 容器命令列介面：`docker` 或 `podman`。 | | `--port ` | 從 `19100` 起自動配置 | 迴路介面主機連接埠。明確選取的連接埠不得屬於另一個已註冊的 cell。 | | `--memory ` | `2g` | 使用 Docker/Podman 語法指定的容器記憶體限制。 | | `--cpus ` | `2` | 容器 CPU 限制。 | | `--disk ` | 無 | 當儲存後端支援配額時，限制容器可寫入層。 | | `--network ` | `bridge` | 對外網路模式：`bridge` 或 `internal`。 | | `--pids-limit ` | `512` | 容器中的程序數量上限。 | | `--env ` | 無 | 將環境變數傳入 cell。可重複使用以傳入多個值。 | | `--gateway-token ` | 隨機的 32 字元十六進位權杖 | 使用提供的閘道權杖，而非產生新權杖。請參閱[權杖處理](#token-handling)。 | | `--no-start` | cell 會啟動 | 建立容器但不啟動。 | | `--json` | 人類可讀輸出 | 顯示機器可讀輸出。 | 自動配置會選取註冊表中 `19100` 以上第一個未使用的連接埠。Fleet 會拒絕重複的租戶 ID，以及已指派給其他 cell 的明確連接埠。 映像檔參照會以單一容器執行階段引數傳入。空白參照與以 `-` 開頭的值會遭到拒絕，以免映像檔被解讀為 Docker 或 Podman 選項。 選取的 Docker 或 Podman 端點必須位於本機。Fleet 會在保留連接埠或建立本機狀態之前，拒絕遠端 Docker context、`DOCKER_HOST` 端點及遠端 Podman 服務；遠端 cell 主機需要個別的儲存空間與端點合約，因此不納入此 MVP。 Fleet 啟動新的 cell 時，建立程序最多會等待約一分鐘，直到其閘道回應 `/healthz`。如果 cell 未進入健康狀態，Fleet 會保留其容器與註冊表資料列，以供 `fleet status`、`fleet logs` 或明確移除使用。`--no-start` 會略過此健康狀態關卡。健康狀態異常之新 cell 所產生的閘道權杖不會遺失——它仍保留在容器環境中（`docker|podman inspect`）；而且因為該 cell 尚未處理任何流量，執行 `fleet rm --force` 後再重新建立，始終是安全的替代方案。 ### 使用摘要固定映像檔 建立與升級操作接受以摘要固定的映像檔參照，例如 `--image ghcr.io/openclaw/openclaw@sha256:`。Fleet 會將映像檔參照原封不動地傳給 Docker 或 Podman，讓操作人員能將 cell 固定在不可變的映像檔位元組上，而非會變動的標籤。 建立結果包含租戶 ID、容器名稱、主機連接埠、閘道權杖及本機 URL。即使使用 JSON 輸出，也應將結果視為含有機密資訊，因為其中包含權杖。 ### 磁碟限制 `--disk` 只限制容器可寫入層。以繫結掛載方式掛載的每租戶狀態與驗證目錄仍使用主機儲存空間；若這些目錄也需要硬性限制，請使用主機檔案系統的專案配額。 | 執行階段／儲存後端 | `--disk` 支援情況 | | ------------------------- | ---------------------------------------------------------------------------- | | XFS 上的 Docker overlay2 | 需要 XFS `pquota` 掛載選項。 | | Docker btrfs 或 zfs | 由儲存驅動程式支援。 | | Podman overlay | 需要 XFS 後端儲存空間。 | | 其他後端 | 容器建立會失敗，並顯示常駐程式錯誤與 Fleet 的後端指引。 | ### 對外連線政策 | 模式 | Docker | Podman | | ---------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `bridge` | 支援；預設不限制對外連線。 | 支援；預設不限制對外連線。 | | `internal` | 拒絕，因為 Docker 不會在內部網路上保留已發布的迴路介面閘道連接埠。 | 支援；阻擋對外連線時，迴路介面閘道仍會保持發布狀態。 | 若使用 Docker，請保留 bridge 模式，並透過主機防火牆規則（例如 `DOCKER-USER` 鏈）強制執行對外連線政策。 ## `fleet list` 依租戶 ID 順序列出 cell： ```bash openclaw fleet list openclaw fleet ls openclaw fleet list --json ``` 表格包含： | 欄位 | 意義 | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tenant` | 租戶 ID。 | | `state` | 來自 Docker 或 Podman 檢查的即時容器狀態。`unknown` 表示執行階段無法使用，或存在使用該 cell 名稱的容器，但其 Fleet 擁有權標籤與註冊表記錄不符（表示可能發生命名衝突或遭到竄改——請在採取動作前手動檢查）。 | | `port` | 對應至 cell 閘道的迴路介面主機連接埠。 | | `image` | 已記錄的容器映像檔。 | | `created` | cell 建立時間。 | Docker 或 Podman 無法使用時，註冊表資料列仍會顯示；只有即時狀態會變成 `unknown`。 ## `fleet status` 檢查單一 cell： ```bash openclaw fleet status acme openclaw fleet status acme --json ``` 狀態會結合 Fleet 註冊表資料列、即時容器檢查，以及對下列位址發出的短暫盡力請求： ```text http://127.0.0.1:/healthz ``` 健康狀態結果為 `ok`、`failed` 或 `skipped`。`/healthz` 證明閘道仍在運作，但不代表每個已設定的頻道或外掛都已完全就緒。沒有可供檢查的本機端點時，會略過探測。 ## `fleet logs` 將 cell 的容器日誌直接串流至終端： ```bash openclaw fleet logs acme openclaw fleet logs acme --follow openclaw fleet logs acme --tail 200 openclaw fleet logs acme --since 10m ``` Fleet 會在讀取任何日誌前驗證已註冊容器的擁有權標籤，因此會拒絕使用預期 cell 名稱的外來容器。按 Ctrl-C 可結束 `--follow`，且不會將操作人員的停止動作視為命令失敗。日誌輸出會通過遮蔽篩選器，在任何內容到達終端前，將 cell 目前的閘道權杖替換為 ``。 `fleet logs` 沒有 `--json` 模式，因為容器日誌是原始 stdout/stderr 串流。若用於指令碼，請使用 `--tail` 限制輸出，並使用一般的 Shell 重新導向或管線。 ## `fleet start`、`fleet stop` 與 `fleet restart` 使用已記錄的執行階段控制現有 cell： ```bash openclaw fleet start acme openclaw fleet stop acme openclaw fleet restart acme ``` 這些命令會操作已註冊的容器名稱。如果租戶不明，或已記錄的執行階段無法執行該操作，命令就會失敗。 ## `fleet upgrade` 重新拉取已記錄的映像檔並取代 cell 容器： ```bash openclaw fleet upgrade acme ``` 將單元移至另一個映像： ```bash openclaw fleet upgrade acme --image ghcr.io/openclaw/openclaw: ``` 升級會拉取目標映像、檢查現有容器與每個單元的網路、停止並移除容器，然後重新建立並啟動容器。替換後會保留相同的主機連接埠、資料目錄、每個單元的橋接網路、執行階段設定檔、資源限制、重新啟動原則、由 Fleet 管理的環境，以及最初透過 `--env` 提供的值。掛載的狀態會在容器替換後保留；映像預設環境可能會隨目標映像而變更。 只有在替換容器的閘道能於單元的迴送連接埠回應 `/healthz` 後，替換才會提交，這與官方 compose 檔案使用的健康狀態合約一致。若替換容器結束、反覆崩潰，或未能在約一分鐘內進入健康狀態，系統會將其移除並還原先前的容器，因此損壞的映像不會使正常運作的單元停擺。 閘道權杖刻意不儲存在 Fleet 登錄中。移除舊容器前，Fleet 會讀取其環境，並將 `OPENCLAW_GATEWAY_TOKEN` 帶入替換容器。如果權杖不存在於你控制的其他位置，升級前請勿手動移除舊容器。 ## `fleet backup` 與 `fleet restore` 備份一個已停止的單元： ```bash openclaw fleet stop acme openclaw fleet backup acme --out ./acme.tgz ``` 將該封存檔還原至已登錄的單元： ```bash openclaw fleet restore acme --from ./acme.tgz ``` 這些是需要主機操作者權限的命令。封存檔包含租戶狀態與驗證祕密，會以 `0600` 模式建立，且必須像認證資訊一樣妥善儲存。備份會拒絕處理執行中的單元，以確保一致地擷取 SQLite 狀態。除非提供 `--force`，否則還原會拒絕處理執行中的單元；還原只會替換該租戶的狀態、輪替閘道權杖，並只顯示一次新權杖。Fleet 一次只備份一個租戶；備份所有租戶是另一項獨立的操作者動作。 這兩個命令都接受 `--max-bytes `，以限制封存或解壓縮的檔案資料量；兩者也套用相同的固定一百萬個封存路徑區段預算，避免僅含中繼資料的封存炸彈耗盡主機 inode，並確保每個接受的備份皆可還原。備份接受 `--out `，兩個命令也都支援 `--json`。 封存檔只能包含一般檔案與目錄。備份絕不會追蹤或儲存符號連結、硬式連結、通訊端或裝置節點；結果中會回報略過的數量。還原會拒絕包含任何其他項目類型的封存檔。還原後，必須在單元內重新安裝可重建的符號連結樹狀結構，例如工作區的 `node_modules`。 ## `fleet doctor` 稽核所有單元或單一租戶，而不變更執行階段或檔案系統狀態： ```bash openclaw fleet doctor openclaw fleet doctor acme --json ``` Doctor 會檢查執行階段的本機性、擁有權標籤、健康狀態、強化措施、資源限制、迴送連接埠繫結、權杖是否存在、網路擁有權與輸出模式，以及私有狀態目錄權限。警告會說明已停止的單元或擁有權差異；任何失敗的檢查結果都會讓程序設定非零結束代碼。 ## `fleet rm` 從執行階段與登錄中移除已停止的單元，同時保留租戶資料： ```bash openclaw fleet rm acme ``` 執行中的容器需要 `--force`： ```bash openclaw fleet rm acme --force ``` 同時永久移除單元資料： ```bash openclaw fleet rm acme --purge-data --force ``` Fleet 會先移除單元容器，再移除其專用橋接網路。`--purge-data` 需要搭配 `--force`。在遞迴刪除前，Fleet 會解析兩個由 Fleet 擁有的根目錄，以及兩個各租戶目錄。每個目標都必須是完全符合預期的租戶葉節點、嚴格位於其根目錄內，且不得為符號連結。這些包含範圍檢查可防止損毀的登錄路徑或跨租戶符號連結將刪除作業重新導向至其他位置。 當完全符合預期的租戶目錄已不存在時，可以重試清除。這可讓後續呼叫在部分檔案系統失敗後完成清理，而不會放寬對仍存在目錄的路徑檢查。 ## 儲存空間與容器配置 單元狀態與驗證設定檔加密金鑰，會使用作用中 OpenClaw 狀態目錄下彼此分離的每租戶主機路徑： ```text /fleet/cells// /fleet/auth-profile-secrets// ``` 第一個目錄掛載於 `/home/node/.openclaw`。第二個目錄掛載於 `/home/node/.config/openclaw`，與官方 Docker 設定的加密金鑰掛載方式一致。因此，加密金鑰不會暴露在一般狀態掛載之下，也不會在只備份或分享單元狀態目錄時納入其中。這兩個目錄在一般移除與升級後都會保留；`fleet rm --purge-data --force` 會在分別完成包含範圍檢查後刪除兩者。 首次啟動前，Fleet 會以 `gateway.mode=local`、權杖驗證、LAN 容器繫結，以及配置給主機連接埠的 Control UI 來源，初始化單元設定。權杖值不會寫入該設定；它會保留在容器環境中。 Fleet 會使用以下環境值固定官方映像的容器路徑： | 變數 | 容器值 | | ------------------------ | ------------------------------------ | | `HOME` | `/home/node` | | `OPENCLAW_HOME` | `/home/node` | | `OPENCLAW_STATE_DIR` | `/home/node/.openclaw` | | `OPENCLAW_CONFIG_PATH` | `/home/node/.openclaw/openclaw.json` | | `OPENCLAW_WORKSPACE_DIR` | `/home/node/.openclaw/workspace` | | `OPENCLAW_GATEWAY_TOKEN` | 產生或提供的單元權杖 | 官方映像預設使用 UID 1000 的非 root `node` 使用者。Fleet 會讓私有的 `0700` 繫結掛載保持可寫入，同時不允許所有人存取。具 root 權限的 Docker 會使用呼叫者的非 root UID 與 GID 執行單元；無 root 權限的 Docker 則使用容器 UID 0，此 UID 會在常駐程式的使用者命名空間內對應至呼叫者在主機上的非特權使用者。Podman 使用 `keep-id` 搭配呼叫者的 UID 與 GID。當 Fleet 本身以 root 身分搭配具 root 權限的執行階段執行時，它會保留映像使用者，並將初始掛載檔案指派給 UID/GID 1000。 在 SELinux 主機上，Docker 與 Podman 掛載會套用私有的 `:Z` 重新標記。如果你還原或重新放置單元資料，請確保有效的容器使用者可寫入繫結掛載路徑。此設定檔適合無 root 權限環境，但主機上的 Docker 或 Podman 必須已設定為無 root 權限運作；Fleet 不會將具 root 權限的常駐程式轉換成無 root 權限。 ## 安全性設定檔 Fleet 會將以下設定檔套用至每個單元： | 控制措施 | 套用的設定檔 | 原因 | | -------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Linux 權能 | `--cap-drop=ALL` | 閘道是 Node.js 程序，不需要新增任何 Linux 權能。 | | 權限提升 | `--security-opt no-new-privileges` | 防止程序透過 setuid 或 setgid 二進位檔取得更高權限。 | | Init 程序 | `--init` | 回收後代程序並轉送容器生命週期訊號。 | | 程序限制 | 預設為 `--pids-limit 512` | 限制程序分叉與程序資源耗盡。 | | 記憶體限制 | 預設為 `--memory 2g` | 限制單元的記憶體使用量。 | | CPU 限制 | 預設為 `--cpus 2` | 限制單元的 CPU 使用量。 | | 可寫入層磁碟 | 選用的 `--disk` | 當執行階段儲存後端支援配額時，限制容器層。 | | 重新啟動原則 | `--restart unless-stopped` | 重新啟動失敗的單元，但不會覆寫刻意停止的狀態。 | | 主機發布 | 僅限 `127.0.0.1::18789` | 避免閘道暴露於主機的萬用字元介面。 | | 單元網路 | 每個單元一個橋接或 Podman 內部網路 | 隔離容器 IP 流量，並可選擇封鎖 Podman 對外輸出流量。 | | 容器身分 | 與主機相符的使用者對應 | 讓私有繫結掛載保持可寫入，而不授予所有人存取權。 | | 持久狀態 | 每個單元各自掛載；不共用狀態掛載 | 將租戶設定、認證資訊、工作階段與工作區保留在該租戶的資料樹狀結構中。 | | 容器命令 | `node dist/index.js gateway --bind lan --port 18789` | 在容器網路上監聽，讓僅限迴送介面的主機連接埠對應可以連線。 | Fleet 絕不會掛載 `/var/run/docker.sock`、使用 `--privileged` 或主機網路，也不會新增權能。每個單元的橋接網路是跨單元的隔離邊界，而不是對外防火牆：單元會保留供供應商與頻道使用的必要網路輸出能力。請在迴送連接埠前端配置符合你部署方式的 Proxy、SSH 通道或 tailnet。只有 Fleet 主機可直接連線至 `http://127.0.0.1:`。 此設定檔會隔離租戶容器，但無法保護租戶免受 Fleet 操作者、容器執行階段管理員或遭入侵主機的影響。如需完整的信任模型與更強的隔離選項，請參閱[多租戶託管](/gateway/multi-tenant-hosting)。 ## 權杖處理 根據預設，`fleet create` 會產生一個以密碼學方式隨機生成的 32 字元十六進位閘道權杖，並在建立結果中只顯示一次。請將它儲存在你核准的祕密管理工具中，並避免將建立輸出擷取到記錄中。 `--gateway-token` 會將自訂權杖放入本機程序引數中，這些引數可能保留在 Shell 歷程記錄中，或顯示於程序清單中。除非現有祕密管理工作流程要求提供指定值，否則請優先使用產生的權杖。 權杖與透過 `--env` 傳入的每個值都存在於容器環境中。Fleet 會將它們寫入一個短期存在且模式為 `0600` 的環境檔案，只將該檔案的路徑傳給 Docker 或 Podman，並在執行階段命令完成後移除檔案。在 `openclaw fleet create --gateway-token ...` 或 `--env KEY=VALUE` 中明確輸入的值，仍可能顯示於外層 `openclaw` 程序引數與 Shell 歷程記錄中。 容器環境值不會對受信任的主機操作者隱藏：Docker 或 Podman 管理員可透過容器檢查讀取這些值。Fleet 的「只顯示一次」說明指的是一般命令列介面輸出，而不是防止主機管理員存取。 ## 相關內容 - [多租戶託管](/gateway/multi-tenant-hosting) - [Docker](/zh-TW/install/docker) - [Podman](/zh-TW/install/podman) - [閘道安全性](/zh-TW/gateway/security)