openclaw fleet

openclaw fleet는 셀이라고 하는 완전한 OpenClaw 인스턴스를 관리합니다. 각 셀에는 자체 Gateway, 상태, 자격 증명, 채널 계정, 컨테이너 및 루프백 전용 호스트 포트가 있습니다. 테넌트 신뢰 경계마다 하나의 셀을 사용하십시오. 하나의 공유 Gateway를 적대적 멀티테넌트 경계로 사용하지 마십시오.

Fleet은 실험적 기능입니다. 기능이 안정화되는 동안 명령어 이름, 플래그, 출력 형식 및 컨테이너 프로필은 지원 중단 유예 기간 없이 릴리스 간에 변경될 수 있습니다.

Fleet은 Docker와 Podman을 지원합니다. 기본 이미지는 ghcr.io/openclaw/openclaw:latest입니다.

Fleet은 Linux 및 macOS 호스트에서 테스트되었습니다. Windows 호스트는 현재 테스트되지 않았습니다.

빠른 시작

openclaw fleet create acmeopenclaw fleet status acmeopenclaw fleet list

fleet create는 생성된 Gateway 토큰을 셀 URL과 함께 한 번만 출력합니다. 토큰을 즉시 저장한 다음 각 테넌트의 채널 계정을 해당 테넌트의 셀 내부에서 구성하십시오.

테넌트 ID

테넌트 ID는 다음 정규식과 일치해야 합니다.

^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$

1~40개의 소문자, 숫자 및 내부 하이픈을 사용할 수 있습니다. ID는 문자나 숫자로 시작하고 끝나야 합니다. 대문자, 밑줄, 슬래시, 점, 공백 및 ../acme 같은 경로 순회 문자열은 거부됩니다.

ID는 컨테이너 이름의 일부가 됩니다: openclaw-cell-<tenant>.

fleet create

셀을 생성하고 시작합니다.

openclaw fleet create acme

고정 포트에 Podman 셀을 생성하되 시작하지 않습니다.

openclaw fleet create acme \  --runtime podman \  --port 19125 \  --no-start

--env를 반복하여 테넌트별 환경 변수를 전달합니다.

openclaw fleet create acme \  --env TZ=America/Los_Angeles \  --env OPENCLAW_DISABLE_BONJOUR=1

환경 변수 키에는 문자, 숫자 및 밑줄을 사용하며 숫자로 시작할 수 없습니다. Fleet은 보호된 런타임 환경 파일을 통해 값을 전달하므로 값은 한 줄이어야 합니다. Fleet은 스토리지 및 컨테이너 레이아웃에 나열된 관리 대상 컨테이너 경로 및 Gateway 토큰 변수를 재정의하려는 시도를 거부합니다.

생성 옵션

자동 할당은 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 순서로 셀을 나열합니다.

openclaw fleet listopenclaw fleet lsopenclaw fleet list --json

표에는 다음 항목이 포함됩니다.

Docker 또는 Podman을 사용할 수 없는 경우에도 레지스트리 행은 계속 표시되며, 실시간 상태만 unknown이 됩니다.

fleet status

셀 하나를 검사합니다.

openclaw fleet status acmeopenclaw fleet status acme --json

상태에는 Fleet 레지스트리 행, 실시간 컨테이너 검사 및 다음 주소에 대한 짧은 최선형 요청이 결합됩니다.

http://127.0.0.1:<host-port>/healthz

상태 확인 결과는 ok, failed 또는 skipped입니다. /healthz는 Gateway의 활성 상태를 입증하지만 구성된 모든 채널이나 Plugin이 완전히 준비되었음을 입증하지는 않습니다. 확인할 수 있는 로컬 엔드포인트가 없으면 프로브를 건너뜁니다.

fleet logs

셀의 컨테이너 로그를 터미널로 직접 스트리밍합니다.

openclaw fleet logs acmeopenclaw fleet logs acme --followopenclaw fleet logs acme --tail 200openclaw fleet logs acme --since 10m

Fleet은 로그를 읽기 전에 등록된 컨테이너의 소유권 레이블을 확인하므로 예상 셀 이름을 사용하는 외부 컨테이너의 로그는 읽지 않습니다. 운영자가 중지한 것을 명령 실패로 처리하지 않고 --follow를 종료하려면 Ctrl-C를 누르십시오. 로그 출력은 터미널에 도달하기 전에 셀의 현재 Gateway 토큰을 <redacted>로 대체하는 수정 필터를 통과합니다.

컨테이너 로그는 원시 stdout/stderr 스트림이므로 fleet logs에는 --json 모드가 없습니다. 스크립트에서는 --tail로 출력 범위를 제한하고 일반적인 셸 리디렉션이나 파이프라인을 사용하십시오.

fleet start, fleet stop 및 fleet restart

기록된 런타임으로 기존 셀을 제어합니다.

openclaw fleet start acmeopenclaw fleet stop acmeopenclaw fleet restart acme

이 명령은 등록된 컨테이너 이름을 대상으로 작동합니다. 테넌트를 알 수 없거나 기록된 런타임이 작업을 수행할 수 없으면 실패합니다.

fleet upgrade

기록된 이미지를 다시 가져와 셀 컨테이너를 교체합니다.

openclaw fleet upgrade acme

셀을 다른 이미지로 이동합니다.

openclaw fleet upgrade acme --image ghcr.io/openclaw/openclaw:<version>

업그레이드는 대상 이미지를 가져오고, 기존 컨테이너와 셀별 네트워크를 검사하며, 컨테이너를 중지하고 제거한 다음 다시 생성하여 시작합니다. 교체 후에도 동일한 호스트 포트, 데이터 디렉터리, 셀별 브리지 네트워크, 런타임 프로필, 리소스 제한, 재시작 정책, Fleet 관리 환경 및 원래 --env로 제공된 값이 유지됩니다. 마운트된 상태는 컨테이너 교체 후에도 유지되지만, 이미지 기본 환경은 대상 이미지에 따라 변경될 수 있습니다.

교체는 공식 compose 파일에서 사용하는 상태 확인 계약과 동일하게, 셀의 루프백 포트에서 Gateway가 /healthz에 응답한 후에만 확정됩니다. 교체 컨테이너가 종료되거나, 충돌을 반복하거나, 약 1분 이내에 정상 상태가 되지 못하면 제거되고 이전 컨테이너가 복원되므로, 손상된 이미지로 인해 작동 중인 셀이 중단되지 않습니다.

Gateway 토큰은 의도적으로 Fleet 레지스트리에 저장되지 않습니다. 이전 컨테이너를 제거하기 전에 Fleet은 해당 환경을 읽고 OPENCLAW_GATEWAY_TOKEN을 교체 컨테이너로 전달합니다. 토큰이 사용자가 관리하는 다른 위치에 존재하지 않는다면 업그레이드 전에 이전 컨테이너를 수동으로 제거하지 마십시오.

fleet backup 및 fleet restore

중지된 셀 하나를 백업합니다.

openclaw fleet stop acmeopenclaw fleet backup acme --out ./acme.tgz

해당 아카이브를 등록된 셀에 복원합니다.

openclaw fleet restore acme --from ./acme.tgz

이 명령에는 호스트 운영자 권한이 필요합니다. 아카이브에는 테넌트 상태와 인증 비밀 정보가 포함되고 모드 0600으로 생성되므로, 자격 증명과 동일하게 보관해야 합니다. SQLite 상태를 일관되게 캡처할 수 있도록 백업은 실행 중인 셀을 거부합니다. 복원은 --force가 제공되지 않으면 실행 중인 셀을 거부하고, 해당 테넌트의 상태만 교체하며, Gateway 토큰을 교체하고, 새 토큰을 한 번만 출력합니다. Fleet은 한 번에 하나의 테넌트를 백업합니다. 모든 테넌트의 백업은 별도의 운영자 작업입니다.

두 명령 모두 아카이브하거나 추출할 파일 데이터의 크기를 제한하는 --max-bytes <bytes>를 허용하며, 메타데이터만 포함된 아카이브 폭탄이 호스트 inode를 고갈시키지 못하고 허용된 모든 백업을 복원할 수 있도록 동일하게 고정된 100만 개의 아카이브 경로 세그먼트 한도를 적용합니다. 백업은 --out <path>를 허용하며, 두 명령 모두 --json을 지원합니다.

아카이브에는 일반 파일과 디렉터리만 포함됩니다. 백업은 심볼릭 링크, 하드 링크, 소켓 또는 장치 노드를 따라가거나 저장하지 않으며, 건너뛴 개수는 결과에 보고됩니다. 복원은 그 외의 항목 유형이 포함된 아카이브를 거부합니다. 워크스페이스의 node_modules와 같이 다시 생성할 수 있는 심볼릭 링크 트리는 복원 후 셀 내부에서 다시 설치해야 합니다.

fleet doctor

런타임 또는 파일 시스템 상태를 변경하지 않고 모든 셀이나 하나의 테넌트를 검사합니다.

openclaw fleet doctoropenclaw fleet doctor acme --json

Doctor는 런타임의 로컬 여부, 소유권 레이블, 상태, 강화 설정, 리소스 제한, 루프백 포트 바인딩, 토큰 존재 여부, 네트워크 소유권과 송신 모드 및 비공개 상태 디렉터리 권한을 확인합니다. 경고에는 중지된 셀 또는 소유권 차이가 설명되며, 하나라도 확인에 실패하면 프로세스 종료 코드가 0이 아닌 값으로 설정됩니다.

fleet rm

테넌트 데이터는 유지하면서 중지된 셀을 런타임과 레지스트리에서 제거합니다.

openclaw fleet rm acme

실행 중인 컨테이너에는 --force가 필요합니다.

openclaw fleet rm acme --force

셀 데이터도 영구적으로 제거합니다.

openclaw fleet rm acme --purge-data --force

Fleet은 전용 브리지 네트워크를 제거하기 전에 셀 컨테이너를 제거합니다. --purge-data에는 --force가 필요합니다. 재귀적으로 삭제하기 전에 Fleet은 Fleet이 소유한 두 루트와 테넌트별 디렉터리 두 개를 모두 확인합니다. 각 대상은 루트 내부에 엄격하게 위치한 정확히 예상된 테넌트 리프여야 하며 심볼릭 링크여서는 안 됩니다. 이러한 포함 범위 검사는 손상된 레지스트리 경로나 테넌트 간 심볼릭 링크가 삭제 작업을 다른 위치로 리디렉션하지 못하도록 방지합니다.

정확히 예상된 테넌트 디렉터리가 이미 없다면 제거 작업을 다시 시도할 수 있습니다. 따라서 부분적인 파일 시스템 오류가 발생한 후에도, 여전히 존재하는 디렉터리에 대한 경로 검사를 완화하지 않고 후속 실행으로 정리를 완료할 수 있습니다.

스토리지 및 컨테이너 레이아웃

셀 상태와 인증 프로필 암호화 키는 활성 OpenClaw 상태 디렉터리 아래에서 서로 분리된 테넌트별 호스트 경로를 사용합니다.

<state-dir>/fleet/cells/<tenant>/<state-dir>/fleet/auth-profile-secrets/<tenant>/

첫 번째 디렉터리는 /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 출력을 설명하는 것이며, 호스트 관리자에 대한 보호를 의미하지 않습니다.

관련 문서

• 멀티테넌트 호스팅
• Docker
• Podman
• Gateway 보안