2026 OpenClaw 헤드리스 Linux Docker: onboard 정체, pending.json·dashboard --no-open 검증 런북

약 16분 읽기 · MACCOME

데스크톱과 브라우저 없이 헤드리스 Linux VPS에서 Docker만으로 OpenClaw를 돌릴 때 마법사나 onboard가 pending에 멈추거나, 로컬 브라우저를 열라는 로그가 나오거나, DISPLAY 없이 dashboard가 실패한다면 이 글은 변경 티켓에 바로 붙일 수 있는 헤드리스 합격 사다리입니다. compose 트랙 하나와 TOKEN 단일 출처를 고정한 뒤, “Control UI를 봤다”를 dashboard --no-open, gateway status/probe, 구조화된 로그로 바꿉니다. 세 OS 설치 총람, Windows Docker 분류, Docker 없는 Linux systemd+Tunnel, Compose 페어링 1006/1008을 보완하고, 프로덕션 앵커는 SSH 포워딩 전용 Gateway와 짝을 이룹니다.

헤드리스 Linux Docker에서 OpenClaw 장애로 오인하기 쉬운 여섯 가지 ‘거짓 실패’

  1. “브라우저를 열어야 한다”를 합격 조건으로 두기: 헤드리스에서는 테스트 스크립트가 잘못된 경우가 많고 Gateway 단독 결함은 아닐 수 있습니다. CLI 계약으로 검증하세요.
  2. onboard 트랙과 compose 이중화: 두 진입점이 pending.json과 환경 변수를 반쯤만 써서 pending이 들쭉날쭉하거나 TOKEN이 어긋납니다(Compose 페어링 글과 같은 뿌리).
  3. 무음·헤드리스 스위치 누락: 마법사는 상호작용을 기다리는데 헬스 체크만 초록으로 보일 수 있습니다.
  4. cgroup, 그래프 드라이버, 기본 ulimits: 작은 VPS는 OOM이나 fd 고갈로 WebSocket 1006과 혼동됩니다.
  5. 기업 MITM·투명 프록시: 이미지 pull은 되고 WebSocket 핸드셰이크만 깨질 수 있습니다. TLS 기대치와 신뢰 저장소를 확인하세요.
  6. Windows 숙제를 Linux에 복사: WSL2와 Docker Desktop 전제는 Linux 엔진과 다릅니다. 설치 후 doctor 분류의 “엔진 먼저” 순서를 따르세요.

헤드리스 가치는 공격면 축소와 자동화 강화입니다. 합격이 브라우저 클릭에 달려 있으면 데스크톱 혼란을 SSH 세션으로 옮긴 것에 불과합니다. Docker 프로덕션 런북을 볼 때도 이미지 태그, compose 해시, TOKEN 주입을 같은 티켓에 묶으세요.

팀이 systemd 베어메탈과 Docker를 동시에 유지한다면 기본 진실(어느 쪽이 CI 이미지 통합이고 어느 쪽이 프로덕션인지)을 문서화하세요. 혼합 호스트가 디버깅이 가장 어렵습니다.

차원 헤드리스 Docker(본문) Linux systemd+Tunnel(컨테이너 없음)
재현·업그레이드 이미지 태그와 compose로 버전 관리가 빠르고 롤백도 쉬움 배포판 패키지와 유닛에 의존. 커스터마이징은 깊지만 이미지 스토리는 약함
헤드리스 합격 --no-open와 컨테이너 로그 드라이버에 자연스럽게 맞음 journald와 curl 프로브. Docker와 경로가 다름
네트워크 네임스페이스 1006/1008이 브리지·publish 조합과 자주 연결됨 호스트 스택. 이슈는 Tunnel과 bind에 많이 걸림
전용 원격 Mac과 함께 Gateway를 전용 호스트로 옮기면 노트북은 CLI만 있어도 됨 결론 동일. 운영 습관은 다름
흔한 오용 라벨 없이 CI와 프로덕션 compose가 갈라짐 한 대에서 Tunnel Gateway와 Docker Gateway 진실을 이중으로 세우는 사고방식
info

참고: 커뮤니티에서 pending.json의 silent를 true로 두어 블로킹 마법사를 건너뛴다는 안내는 파이프라인에 넣기 전 현행 OpenClaw 문서와 반드시 대조하세요. 업그레이드 후 회귀를 다시 돌려 silent가 묵음 교착으로 바뀌지 않게 하세요.

헤드리스 여섯 단계 런북: 이미지 pull부터 gateway probe 초록까지

  1. 단일 진입 트랙 고정: compose 전용 또는 공식 docker-setup 전용 중 하나만 선택하고 다른 경로는 참고만 합니다.
  2. 엔진과 디스크 검증: docker info, Docker 데이터 루트 여유 공간, ulimit -n. 아주 작은 VPS는 기능보다 먼저 swap이나 동시성 상한을 조정합니다.
  3. onboard·pending 처리: 문서화된 헤드리스 스위치를 적용합니다. 변경 뒤에는 pending 파일 해시를 CI 로그에 출력해 감사 추적을 남깁니다.
  4. Gateway 기동 후 CLI로만 검증: openclaw gateway status → openclaw gateway probe(가능 시) → openclaw dashboard --no-open. “브라우저에서만 봤다”를 유일한 통과 신호로 두지 마세요.
  5. doctor 실행 및 면제 등록: 설치 후 doctor 분류와 필드를 맞춥니다. 면제에는 담당자와 만료일이 필요합니다.
  6. 회귀 추가: 컨테이너 재빌드 후에도 같은 스크립트가 10분 안에 통과해야 합니다. 실패 시 compose 해시와 이미지 digest를 넣어 인시던트를 엽니다.
bash
# 예: CLI만으로 확인(compose 서비스 이름은 환경에 맞게 조정)
docker compose ps
docker compose logs -f --tail=200 openclaw-gateway

openclaw gateway status || true
openclaw dashboard --no-open || true
openclaw doctor --yes || true

SLO나 온콜 메모용 세 지표(SKU에 맞게 조정)

  • 첫 성공 프로브까지 콜드 스타트(G2P): compose up -d부터 첫 성공 gateway probe까지 중앙값(분). 이미지 태그가 같을 때 주간 대비 40% 넘게 악화되면 모델 탓하기 전에 디스크와 fd를 확인합니다.
  • 헤드리스 호스트의 브라우저 의존 단계: 목표는 0입니다. DISPLAY가 필요한 새 단계는 제품화로 되돌리거나 개발 전용 compose 프로필로 격리합니다.
  • 이중 Gateway 이벤트: 18789 이중 바인딩이나 TOKEN 이중 출처 알림을 센다. 두 주 연속 0이 아니면 TOKEN 이중 출처 글 기준으로 아키텍처 검토를 트리거해야 합니다.

왜 “경량 데스크톱+VNC”나 “운 좋아질 때까지 onboard 재시도”가 2026년에는 나쁜 거래인가

경량 데스크톱은 패치 면과 세션 감사 비용을 키웁니다. 공개 VNC는 고전적인 고위험 패턴입니다. onboard를 무한 재시도하면 필드 드리프트가 자동화가 아니라 근육 기억 뒤에 숨습니다.

CI에 맞춘 감사 가능한 Gateway를 7×24로 필요하면서 헤드리스 Linux는 엣지 시험이나 짧은 PoC에 두고 싶다면, 권위 있는 Gateway를 문서화된 SSH 포워딩이나 tailnet 정책을 갖춘 전용 Apple Silicon 원격 Mac에 두는 편이 작은 VPS의 cgroup 한계와 오래 싸우는 것보다 낫습니다. MACCOME은 여섯 지역에서 Mac mini(M4/M4 Pro)를 유연한 임대로 제공합니다. 확정 전 공개 노드·임대 가이드로 토폴로지를 맞추세요.

마무리: 헤드리스 합격은 채팅이 아니라 DOCKER_GATEWAY.md에 둔다

내보낼 것: compose 버전, 이미지 digest, silent/pending 정책, CLI 출력 샘플, 브라우저 불필요 명시. 두 번째 헤드리스 박스에서 재생할 수 없는 단계는 미완 문서입니다.

Windows Docker 분류와 비교할 때 사다리는 같고 호스트·엔진이 다르다는 점을 기억하세요. Docker Desktop 로그 경로와 Linux 엔진 경로를 섞지 마세요.

FAQ

헤드리스 서버에서 onboard가 계속 pending입니다. 데스크톱이 필요한가요?

대개 아닙니다. 헤드리스 스위치와 CLI 합격으로 진행하고 pending.json 필드를 문서와 대조하세요. 전용 노드 프로덕션 Gateway는 Mac mini 대여 요금 페이지에서 확인하세요.

Linux Docker와 systemd+Tunnel을 한 머신에서 같이 쓸 수 있나요?

기술적으로는 가능하지만 환경을 나누지 않으면 이중 Gateway·이중 TOKEN 진실이 흔합니다. 기본값을 문서화하세요. Tunnel 런북과 Compose 페어링 글을 함께 보세요.