온보드는 통과했는데 CLI 나 대시보드가 오래 Gateway not ready / not ready 에 머무는 경우는 대개 프로세스가 실제로 리스닝하기 전 단계입니다. 사이트의 gateway closed(1000) 점검 글(세션·scope·토큰 층)과는 다릅니다. 본문은 플랫폼 엔지니어에게 가장 짧은 경로를 줍니다. 7가지 체크로 포트, 메모리, 타임아웃, 이미지, 볼륨 권한을 거르고, 베어 메탈 systemd 대 Docker 비교표로 로그 표면을 고른 뒤 openclaw doctor 와 로그 명령 예시를 포함한 6단계 Runbook을 실행하며, 설치 총람, Docker 프로덕션, 관측 글과 역할을 나눠 읽으세요.
not ready 는 보통 컨트롤 플레인이 아직 리스닝 성공, 의존 프로세스 준비, 헬스 프로브 통과 중 하나도 확인하지 못했다는 뜻입니다. WebSocket 이 열린 뒤 정책으로 끊기는 경우와는 층이 다릅니다. 그쪽은 먼저 closed (1000) 글을 보세요. 아래 7가지는 설치 후 첫 주 플랫폼 자가 점검용입니다.
오래된 프로세스나 다른 서비스가 포트를 잡고 있음: 업그레이드나 반복된 docker compose up 뒤에도 호스트에 옛 Gateway 가 같은 포트를 물고 있으면 새 프로세스는 반쯤만 뜨고 CLI 는 not ready 만 보여 줍니다.
메모리·swap 부족으로 OOM: 작은 VPS 에서 모델 풀과 Gateway 를 동시에 돌리면 Node 프로세스가 ready 전에 죽습니다. 로그에 exit 137 이 찍히거나 조용히 사라집니다.
시작 타임아웃이 너무 짧음: 콜드 풀이나 네이티브 빌드가 기본 startupTimeout 을 넘기면 헬스체크가 일찍 실패하고 “영원히 not ready” 처럼 보입니다.
로그를 잘못 읽음: systemd 와 Docker 를 섞어 디버깅할 때 컨테이너만 tail 하다 호스트 unit 이 여전히 옛 바이너리를 올리는 경우(또는 그 반대)를 놓칩니다.
네임드 볼륨 권한과 UID 매핑: 컨테이너 사용자가 상태 디렉터리에 쓸 수 없어 Gateway 가 크래시 루프를 돌고 밖에서는 not ready 만 보입니다.
이미지 digest 와 설정 드리프트: compose 가 :latest 를 가리키는데 캐시 레이어가 새 openclaw.json 필드와 맞지 않아 엔트리 스크립트가 일찍 종료합니다.
네트워크 문제를 시작 실패로 오인: 모델·플러그인 레지스트리 타임아웃이면 초기화에 멈춥니다. DNS/이그레스와 Gateway 자체를 분리하세요.
공통점은 프로세스가 서비스 가능한 상태에 도달하지 못한다는 것이고, 그래서 status/RPC 가 “반쯤만 녹색”처럼 보입니다. 티켓 템플릿에 넣은 뒤 아래 표로 로그 표면을 고르고 journal 과 docker logs 사이를 오가지 마세요.
크로스 플랫폼 설치 글은 “설치된다”까지, 본문은 “안 뜬다”까지를 다룹니다. 관측 글은 장기 메트릭과 업그레이드/롤백, 본문은 첫 ready 이전의 하드 장애입니다.
Gateway 를 전용 원격 Mac 이나 작은 Linux VPS 에 올린다면 변경 검토에 최소 메모리와 디스크 여유까지 적고 버전 핀만 보지 마세요. 그렇지 않으면 데모 직전에 not ready 가 몰립니다. 아래 표가 “어떤 로그를 읽을지”를 한 번에 정리합니다.
리스닝 면을 확인하기 전에 Gateway 를 공중망에 잠깐 노출해 “연결 테스트”를 하지 마세요. 보안 강화 글의 최소 노출 순서를 따르세요.
not ready 를 볼 때 첫 결정은 진입 형태입니다. systemd 가 프로세스를 올리는지, compose 가 컨테이너에서 올리는지. 섞어 보면 시간이 낭비됩니다.
| 차원 | Linux/macOS 베어 메탈 + systemd(또는 launchd) | Docker/Compose |
|---|---|---|
| 첫 로그 화면 | journalctl -u <unit> -n 200 --no-pager 또는 플랫폼 동등 명령 | docker compose logs --tail=200 <service>, 재시작 타임스탬프에 맞춤 |
| 포트 충돌 확인 | 호스트에서 lsof -nP -iTCP:<port> -sTCP:LISTEN (예시) | 호스트와컨테이너 안 리스너 모두, publish 포트와 기존 호스트 서비스 충돌 |
| 권한/볼륨 | 상태 디렉터리 소유자와 런타임 사용자 일치 | 네임드 볼륨 UID, 읽기 전용 루트와 쓰기 마운트 분리. Docker 프로덕션 글 참고 |
| 타임아웃·재시도 | unit 의 TimeoutStartSec, Restart= 정책 | healthcheck start_period, retries 와 이미지 콜드 스타트 시간 |
| 업그레이드/롤백 훅 | 패키지 버전 + 마지막으로 정상이었던 설정 백업 경로 | 고정 이미지 digest + 버전 관리된 compose. 관측 글의 롤백 절과 같은 취지 |
“먼저 리스닝을 확인하고, 그다음 세션”: not ready 단계에서 가장 ROI 가 큰 것은 포트+리소스+올바른 로그 시간창이지, 먼저 토큰을 바꾸는 일이 아닙니다.
Ubuntu 24.04+systemd+Tunnel 배포라면 Tunnel 업스트림이 여전히 현재 포트를 가리키는지도 확인하세요. 어긋나면 밖에서는 계속 not ready 인데 로컬 curl 127.0.0.1 만 정상처럼 보입니다.
Docker 에서 흔한 오독은 “컨테이너는 Exited 인데 compose 는 creating 에 머문 것처럼 보임”입니다. docker compose ps -a 로 종료 코드를 보고 볼륨 권한과 엔트리 스크립트로 돌아갑니다.
프로세스가 리스닝하고 프로브도 통과했는데 클라이언트가 이상하면 closed (1000) 의 세션 경로로 전환합니다.
아래 순서는 값싼 점검을 앞에 둡니다. 리소스와 포트를 확인한 뒤 설정과 이미지를 만집니다. 세부 서브커맨드는 사용 중인 OpenClaw 빌드에 맞추세요.
동시 재시도 동결: 동료의 자동 재연결 스크립트를 잠시 멈춰 연결 폭풍이 조사를 덮지 않게 합니다.
버전·리소스 스냅샷: openclaw --version, uname -a, 여유 메모리/디스크를 티켓에 적습니다.
포트와 오래된 프로세스 검증: 설정 포트에서 리스닝을 확인하고 오래된 PID 가 있으면 systemd/Docker 문서 순서대로 정지 후 기동합니다.
doctor/validate 실행: openclaw doctor 또는 동등 명령으로 빈틈을 메운 뒤 다시 시작합니다.
시작 관측 창을 넓힘: 지원되면 일시적으로 gateway.startupTimeout 이나 compose healthcheck start_period 를 올려 “느림”과 “죽음”을 구분합니다.
최소 수락 기준: 로컬 curl 헬스나 공식 status 서브커맨드가 ready 를 반환한 뒤 다른 사용자를 되돌립니다. 여전히 실패하면 4절 로그 샘플과 함께 에스컬레이션합니다.
openclaw --version openclaw doctor # systemd 예: # journalctl -u openclaw-gateway -n 120 --no-pager # Docker 예: # docker compose logs --tail=120 gateway # 이후 배포판 문서에 따라 unit/compose 서비스 재시작
안내: CLI 에 모델·플러그인 다운로드 타임아웃이 보이면 이그레스와 Gateway 를 분리합니다. 유지보수 창에서 일시적으로 egress 화이트리스트를 넓혔다가 다시 조입니다. 보안 강화 글을 참고하세요.
설치 총람과 맞춥니다. Anthropic 과금이나 API 키 형태를 바꾼 직후에는 환경 변수와 설정 파일을 한 출처로 맞추지 않으면 키 파싱에서 막혀 not ready 처럼 보일 수 있습니다.
전용 원격 Mac 에서 Gateway 를 장기 실행한다면 launchd/unit 재시작 정책과 디스크 정리를 같은 Runbook 에 넣어 디스크가 가득 찬 뒤 not ready 가 반복되지 않게 합니다.
아래 “말로 하는 증상 → 조치” 표를 온콜 채널에 고정하면 잡음이 줄어듭니다. WebSocket 종료 코드가 섞이면 closed (1000) 으로 넘어가세요.
포트 사용 중: 옛 프로세스를 멈춘 뒤 새 프로세스를 올리고, 포트를 비우지 않은 채 scale 하지 않습니다. 메모리 부족: 먼저 동시 실행을 줄이거나 swap/스펙을 올린 뒤 튜닝합니다. 이미지 풀 실패: 먼저 docker pull 이나 레지스트리 자격을 고친 다음 Gateway 설정을 봅니다.
주의: 기록 없이 프로덕션에서 docker system prune 류를 실행하지 마세요. 쓰는 중인 네임드 볼륨 백업까지 지울 수 있습니다. 정리 경로는 변경 기록에 적습니다.
관측 글과 연계해 not ready 가 풀린 뒤 대시보드에 근본 원인 태그(포트/메모리/이미지/볼륨)를 남겨 다음 주 같은 클래스가 다시 열리지 않게 합니다.
Gateway 와 MCP 자식 프로세스를 같은 호스트에 두면 시작 단계에서 자식 바이너리 경로와 샌드박스 마운트가 컨테이너 안에서 보이는지도 봐야 합니다. 안 보이면 부모가 도구 발견 단계에서 멈춥니다.
팀 간 정렬용 필드입니다. 외부로 보내기 전에 비식별화하세요.
개인 노트북만으로 Gateway 를 돌리면 절전·OS 업데이트에 취약하고, 메모리 작은 VPS 는 콜드 스타트에서 자주 OOM 납니다. OpenClaw 와 툴체인을 위해 오래 가동되고 계약상 명확한 macOS 실행층이 필요하면 전용 원격 Mac 이 노트북 빌려 쓰기보다 안정적입니다. 들쭉날쭉한 자체 장비보다 NodeMini Mac Mini 클라우드 대여는 고정 SSH 와 디스크 단계가 분명해 “Gateway+툴체인”을 인프라 노드처럼 인수인계하기 쉽습니다. 사양과 가격은 Mac Mini 대여 요금, 온보딩 질문은 고객센터, OpenClaw 시리즈는 블로그 OpenClaw 카테고리에서 시작하세요.
프로세스가 리스닝하지 않거나 포트·메모리·타임아웃이 의심될 때는 본문. WebSocket 이 열린 뒤 정책이나 세션으로 닫혔을 때는 closed (1000) 글입니다. 용량·온보딩 계획은 Mac Mini 대여 요금과 고객센터를 보세요.
같은 시간대의 docker compose logs --tail=120 gateway 와 호스트 dmesg/리소스 스냅샷입니다. 볼륨 권한이 의심되면 docker compose ps -a 종료 코드도 첨부합니다.
블로그 OpenClaw 카테고리에서 설치, Docker, systemd, 보안, 관측, MCP 글로 들어가세요. 본문은 “안 뜨는” 단계용입니다.