openclaw fleet
openclaw fleet는 셀이라고 하는 완전한 OpenClaw 인스턴스를 관리합니다. 각 셀에는 자체 Gateway, 상태, 자격 증명, 채널 계정, 컨테이너 및 루프백 전용 호스트 포트가 있습니다. 테넌트 신뢰 경계마다 하나의 셀을 사용하십시오. 하나의 공유 Gateway를 적대적 멀티테넌트 경계로 사용하지 마십시오.
Fleet은 실험적 기능입니다. 기능이 안정화되는 동안 명령어 이름, 플래그, 출력 형식 및 컨테이너 프로필은 지원 중단 유예 기간 없이 릴리스 간에 변경될 수 있습니다.
Fleet은 Docker와 Podman을 지원합니다. 기본 이미지는 ghcr.io/openclaw/openclaw:latest입니다.
Fleet은 Linux 및 macOS 호스트에서 테스트되었습니다. Windows 호스트는 현재 테스트되지 않았습니다.
빠른 시작
fleet create는 생성된 Gateway 토큰을 셀 URL과 함께 한 번만 출력합니다. 토큰을 즉시 저장한 다음 각 테넌트의 채널 계정을 해당 테넌트의 셀 내부에서 구성하십시오.
테넌트 ID
테넌트 ID는 다음 정규식과 일치해야 합니다.../acme 같은 경로 순회 문자열은 거부됩니다.
ID는 컨테이너 이름의 일부가 됩니다: openclaw-cell-<tenant>.
fleet create
셀을 생성하고 시작합니다.
--env를 반복하여 테넌트별 환경 변수를 전달합니다.
생성 옵션
자동 할당은
19100 이상의 레지스트리 포트 중 사용되지 않은 첫 번째 포트를 선택합니다. Fleet은 중복된 테넌트 ID와 다른 셀에 이미 할당된 명시적 포트를 거부합니다.
이미지 참조는 단일 컨테이너 런타임 인수로 전달됩니다. 이미지가 Docker 또는 Podman 옵션으로 해석되지 않도록 빈 참조와 -로 시작하는 값은 거부됩니다.
선택한 Docker 또는 Podman 엔드포인트는 로컬이어야 합니다. Fleet은 포트를 예약하거나 로컬 상태를 생성하기 전에 원격 Docker 컨텍스트, DOCKER_HOST 엔드포인트 및 원격 Podman 서비스를 거부합니다. 원격 셀 호스트에는 별도의 스토리지 및 엔드포인트 계약이 필요하므로 이 MVP에서는 지원이 보류됩니다.
Fleet이 새 셀을 시작하면 create는 해당 Gateway가 /healthz에 응답할 때까지 최대 약 1분 동안 기다립니다. 셀이 정상 상태가 되지 않으면 Fleet은 fleet status, fleet logs 또는 명시적 제거를 위해 해당 컨테이너와 레지스트리 행을 그대로 유지합니다. --no-start는 이 상태 확인 단계를 건너뜁니다. 정상 상태가 아닌 새 셀의 생성된 Gateway 토큰은 손실되지 않습니다. 토큰은 컨테이너 환경(docker|podman inspect)에 남아 있으며, 셀이 아직 트래픽을 처리하지 않았으므로 fleet rm --force 실행 후 새로 생성하는 방법도 항상 안전한 대안입니다.
다이제스트로 고정
create 및 upgrade는--image ghcr.io/openclaw/openclaw@sha256:<digest>와 같이 다이제스트로 고정된 이미지 참조를 허용합니다. Fleet은 이미지 참조를 Docker 또는 Podman에 그대로 전달하므로 운영자는 셀을 변경되는 태그 대신 변경 불가능한 이미지 바이트에 유지할 수 있습니다.
생성 결과에는 테넌트 ID, 컨테이너 이름, 호스트 포트, Gateway 토큰 및 로컬 URL이 포함됩니다. JSON 출력에서도 결과에 토큰이 포함되므로 비밀 정보가 포함된 것으로 취급하십시오.
디스크 제한
--disk는 컨테이너의 쓰기 가능 계층만 제한합니다. 바인드 마운트된 테넌트별 상태 및 인증 디렉터리는 호스트 스토리지에 그대로 유지됩니다. 해당 디렉터리에도 엄격한 제한이 필요한 경우 호스트 파일 시스템의 프로젝트 할당량을 사용하십시오.
송신 정책
Docker에서는 브리지 모드를 유지하고
DOCKER-USER 체인 같은 호스트 방화벽 규칙으로 아웃바운드 정책을 적용하십시오.
fleet list
테넌트 ID 순서로 셀을 나열합니다.
Docker 또는 Podman을 사용할 수 없는 경우에도 레지스트리 행은 계속 표시되며, 실시간 상태만
unknown이 됩니다.
fleet status
셀 하나를 검사합니다.
ok, failed 또는 skipped입니다. /healthz는 Gateway의 활성 상태를 입증하지만 구성된 모든 채널이나 Plugin이 완전히 준비되었음을 입증하지는 않습니다. 확인할 수 있는 로컬 엔드포인트가 없으면 프로브를 건너뜁니다.
fleet logs
셀의 컨테이너 로그를 터미널로 직접 스트리밍합니다.
--follow를 종료하려면 Ctrl-C를 누르십시오. 로그 출력은 터미널에 도달하기 전에 셀의 현재 Gateway 토큰을 <redacted>로 대체하는 수정 필터를 통과합니다.
컨테이너 로그는 원시 stdout/stderr 스트림이므로 fleet logs에는 --json 모드가 없습니다. 스크립트에서는 --tail로 출력 범위를 제한하고 일반적인 셸 리디렉션이나 파이프라인을 사용하십시오.
fleet start, fleet stop 및 fleet restart
기록된 런타임으로 기존 셀을 제어합니다.
fleet upgrade
기록된 이미지를 다시 가져와 셀 컨테이너를 교체합니다.
--env로 제공된 값이 유지됩니다. 마운트된 상태는 컨테이너 교체 후에도 유지되지만, 이미지 기본 환경은 대상 이미지에 따라 변경될 수 있습니다.
교체는 공식 compose 파일에서 사용하는 상태 확인 계약과 동일하게, 셀의 루프백 포트에서 Gateway가 /healthz에 응답한 후에만 확정됩니다. 교체 컨테이너가 종료되거나, 충돌을 반복하거나, 약 1분 이내에 정상 상태가 되지 못하면 제거되고 이전 컨테이너가 복원되므로, 손상된 이미지로 인해 작동 중인 셀이 중단되지 않습니다.
Gateway 토큰은 의도적으로 Fleet 레지스트리에 저장되지 않습니다. 이전 컨테이너를 제거하기 전에 Fleet은 해당 환경을 읽고 OPENCLAW_GATEWAY_TOKEN을 교체 컨테이너로 전달합니다. 토큰이 사용자가 관리하는 다른 위치에 존재하지 않는다면 업그레이드 전에 이전 컨테이너를 수동으로 제거하지 마십시오.
fleet backup 및 fleet restore
중지된 셀 하나를 백업합니다.
0600으로 생성되므로, 자격 증명과 동일하게 보관해야 합니다. SQLite 상태를 일관되게 캡처할 수 있도록 백업은 실행 중인 셀을 거부합니다. 복원은 --force가 제공되지 않으면 실행 중인 셀을 거부하고, 해당 테넌트의 상태만 교체하며, Gateway 토큰을 교체하고, 새 토큰을 한 번만 출력합니다. Fleet은 한 번에 하나의 테넌트를 백업합니다. 모든 테넌트의 백업은 별도의 운영자 작업입니다.
두 명령 모두 아카이브하거나 추출할 파일 데이터의 크기를 제한하는 --max-bytes <bytes>를 허용하며, 메타데이터만 포함된 아카이브 폭탄이 호스트 inode를 고갈시키지 못하고 허용된 모든 백업을 복원할 수 있도록 동일하게 고정된 100만 개의 아카이브 경로 세그먼트 한도를 적용합니다. 백업은 --out <path>를 허용하며, 두 명령 모두 --json을 지원합니다.
아카이브에는 일반 파일과 디렉터리만 포함됩니다. 백업은 심볼릭 링크, 하드 링크, 소켓 또는 장치 노드를 따라가거나 저장하지 않으며, 건너뛴 개수는 결과에 보고됩니다. 복원은 그 외의 항목 유형이 포함된 아카이브를 거부합니다. 워크스페이스의 node_modules와 같이 다시 생성할 수 있는 심볼릭 링크 트리는 복원 후 셀 내부에서 다시 설치해야 합니다.
fleet doctor
런타임 또는 파일 시스템 상태를 변경하지 않고 모든 셀이나 하나의 테넌트를 검사합니다.
fleet rm
테넌트 데이터는 유지하면서 중지된 셀을 런타임과 레지스트리에서 제거합니다.
--force가 필요합니다.
--purge-data에는 --force가 필요합니다. 재귀적으로 삭제하기 전에 Fleet은 Fleet이 소유한 두 루트와 테넌트별 디렉터리 두 개를 모두 확인합니다. 각 대상은 루트 내부에 엄격하게 위치한 정확히 예상된 테넌트 리프여야 하며 심볼릭 링크여서는 안 됩니다. 이러한 포함 범위 검사는 손상된 레지스트리 경로나 테넌트 간 심볼릭 링크가 삭제 작업을 다른 위치로 리디렉션하지 못하도록 방지합니다.
정확히 예상된 테넌트 디렉터리가 이미 없다면 제거 작업을 다시 시도할 수 있습니다. 따라서 부분적인 파일 시스템 오류가 발생한 후에도, 여전히 존재하는 디렉터리에 대한 경로 검사를 완화하지 않고 후속 실행으로 정리를 완료할 수 있습니다.
스토리지 및 컨테이너 레이아웃
셀 상태와 인증 프로필 암호화 키는 활성 OpenClaw 상태 디렉터리 아래에서 서로 분리된 테넌트별 호스트 경로를 사용합니다./home/node/.openclaw에 마운트됩니다. 두 번째 디렉터리는 공식 Docker 설정의 암호화 키 마운트와 일치하도록 /home/node/.config/openclaw에 마운트됩니다. 따라서 암호화 키는 일반 상태 마운트 아래에 노출되지 않으며, 셀 상태 디렉터리만 백업하거나 공유할 때 포함되지 않습니다. 두 디렉터리 모두 일반적인 제거 및 업그레이드 후에도 유지됩니다. fleet rm --purge-data --force는 별도의 포함 범위 검사를 수행한 후 두 디렉터리를 모두 삭제합니다.
처음 시작하기 전에 Fleet은 gateway.mode=local, 토큰 인증, LAN 컨테이너 바인딩 및 할당된 호스트 포트에 대한 Control UI 오리진으로 셀 구성을 초기화합니다. 토큰 값은 해당 구성에 기록되지 않고 컨테이너 환경에 남습니다.
Fleet은 다음 환경 값으로 공식 이미지의 컨테이너 경로를 고정합니다.
공식 이미지는 기본적으로 UID 1000의 루트가 아닌
node 사용자를 사용합니다. Fleet은 비공개 0700 바인드 마운트를 누구나 접근할 수 있게 만들지 않으면서 쓰기 가능한 상태로 유지합니다. 루트 권한 Docker는 호출한 루트가 아닌 사용자의 UID와 GID로 셀을 실행합니다. 루트리스 Docker는 컨테이너 UID 0을 사용하며, 이는 데몬의 사용자 네임스페이스 내에서 호출한 권한 없는 호스트 사용자에게 매핑됩니다. Podman은 호출한 UID와 GID로 keep-id를 사용합니다. Fleet 자체가 루트 권한으로 루트 권한 런타임을 대상으로 실행되면 이미지 사용자를 유지하고 초기 마운트 파일을 UID/GID 1000에 할당합니다.
SELinux 호스트에서는 Docker 및 Podman 마운트에 비공개 :Z 레이블 재지정이 적용됩니다. 셀 데이터를 복원하거나 재배치하는 경우 바인드 마운트된 경로를 실효 컨테이너 사용자가 쓸 수 있는 상태로 유지하십시오. 이 프로필은 루트리스 환경에 적합하지만, Docker 또는 Podman이 호스트에서 루트리스 작업을 수행하도록 이미 구성되어 있어야 합니다. Fleet은 루트 권한 데몬을 루트리스 데몬으로 변환하지 않습니다.
보안 프로필
Fleet은 모든 셀에 다음 프로필을 적용합니다.
Fleet은
/var/run/docker.sock을 마운트하거나, --privileged 또는 호스트 네트워킹을 사용하거나, 기능을 추가하지 않습니다. 셀별 브리지는 셀 간 분리 경계이지 외부 송신 방화벽이 아닙니다. 셀은 공급자 및 채널에 필요한 네트워크 송신 기능을 유지합니다. 배포 환경에 맞는 프록시, SSH 터널 또는 tailnet 구성으로 루프백 포트의 앞단을 구성하십시오. http://127.0.0.1:<port>에는 Fleet 호스트에서만 직접 접근할 수 있습니다.
이 프로필은 테넌트 컨테이너를 분리하지만, Fleet 운영자, 컨테이너 런타임 관리자 또는 침해된 호스트로부터 테넌트를 보호하지는 않습니다. 전체 신뢰 모델과 더 강력한 격리 옵션은 멀티테넌트 호스팅을 참조하십시오.
토큰 처리
기본적으로fleet create는 암호학적으로 안전한 임의의 32자 16진수 Gateway 토큰을 생성하고 생성 결과에 한 번만 출력합니다. 승인된 비밀 정보 관리자에 저장하고 생성 출력을 로그에 기록하지 마십시오.
--gateway-token은 사용자 지정 토큰을 로컬 프로세스 인수에 배치하며, 셸 기록에 보존되거나 프로세스 목록에 표시될 수 있습니다. 기존 비밀 정보 관리 워크플로에 제공된 값이 필요하지 않다면 생성된 토큰을 사용하십시오.
토큰과 --env로 전달된 모든 값은 컨테이너 환경에 존재합니다. Fleet은 이를 수명이 짧은 모드 0600 환경 파일에 기록하고, 해당 파일의 경로만 Docker 또는 Podman에 전달하며, 런타임 명령이 완료된 후 파일을 제거합니다. openclaw fleet create --gateway-token ... 또는 --env KEY=VALUE에 명시적으로 입력한 값은 여전히 외부 openclaw 프로세스 인수와 셸 기록에 표시될 수 있습니다.
컨테이너 환경 값은 신뢰할 수 있는 호스트 운영자에게 숨겨지지 않습니다. Docker 또는 Podman 관리자는 컨테이너 검사를 통해 해당 값을 읽을 수 있습니다. Fleet의 “한 번만 표시” 안내는 일반적인 CLI 출력을 설명하는 것이며, 호스트 관리자에 대한 보호를 의미하지 않습니다.