openclaw doctor와 openclaw gateway status --format json 판단이 흔들립니다. 2026년 게이트웨이 문서의 로컬(127.0.0.1) 바인딩과 상태·헬스 프로브에 맞춰, 공식 install 스크립트 또는 npm install -g 한 갈래에서 config validate→doctor→status→curl /health까지를 최소 재현으로 묶었습니다. JSON·CI 연동은 status JSON·doctor·18789 CI 게이트, 토큰·SecretRef는 게이트웨이 토큰·원격 Mac, 설정 스키마 선행 검증은 config validate CI 게이트 글과 함께 보시면 됩니다.
자주 막히는 세 가지
터미널에서는 Node 22 이상인데 로그인 항목만 예전 바이너리를 잡는 경우, 18789에 다른 프로세스가 남아 JSON의 listening과 lsof의 PID가 어긋나는 경우, 토큰 없이 이차 프로브만 통과시켜 운영과 행동이 달라지는 경우입니다. 아래 H2를 위에서부터 순서대로 닫으면 같은 러너에서도 재현성이 좋아집니다.
Node 22+ 전제와 경로 고정
메이저가 22 미만이면 먼저 올립니다. node -v와 node -p "process.execPath"를 작업 로그 첫머리에 남기고, launchd plist의 ProgramArguments와 같은 절대 경로를 쓰는 정책으로 맞춥니다. nvm이 셸 함수로만 PATH를 바꾸는 구성이면 로그인 항목에서 node를 못 찾는 일이 잦으므로, 검증 사용자 기준으로 실제 파일 위치를 고정하는 편이 안전합니다.
설치 경로 선택（공식 install 스크립트 vs npm 전역）
팀에서는 둘 중 하나만 채택합니다. OpenClaw 공식 문서에 안내된 install 절차를 따르거나, 재현성을 위해 npm install -g openclaw@<고정 태그>로 핀을 박습니다. 설치 직후 which openclaw와 openclaw --version 한 줄을 티켓이나 런북에 붙여 두면 이후 롤백 비교가 빨라집니다.
| 경로 | 장점 | 주의 |
|---|---|---|
| 공식 install 스크립트 | 문서와 동일한 순서로 감사·온보딩하기 쉬움 | 다운로드 출처·무결성 확인을 운영 규칙으로 박제 |
| npm 전역 | 태그 핀으로 CI·스테이징 버전을 맞추기 좋음 | 전역 prefix·권한·여러 Node 공존 시 PATH 감사 필요 |
루프백 게이트웨이와 토큰（18789·로컬 바인딩）
2026년 게이트웨이 설명에 맞추면 검증은 127.0.0.1 루프백과 TCP 기본 포트 18789에 두는 것이 가장 단순합니다. Bearer로 헬스를 보려면 OPENCLAW_GATEWAY_TOKEN을 대화형 셸과 LaunchAgent plist의 EnvironmentVariables에 같은 값으로 넣고, 아래 수락 단계에서 curl에 Authorization: Bearer …를 붙입니다. 루프백 밖으로 리슨을 넓히기 전에는 반드시 보안 가이드와 앞서 인용한 토큰 글을 따릅니다.
데몬·로그인 항목과 재부팅 후 검증
openclaw onboard --install-daemon으로 로그인 시 동일 사용자 계정에서 게이트웨이가 뜨게 합니다. plist의 Label, WorkingDirectory, 환경 블록, 필요 시 OPENCLAW_HOME이 실제 홈과 일치하는지 확인합니다. 재부팅 직후에도 같은 계정으로 openclaw doctor를 한 번 더 돌리고, 18789를 점유한 프로세스가 기대한 openclaw 바이너리인지 대조합니다.
전형 오류 지문과 롤백
| 지문·현상 | 우선 조치 |
|---|---|
address already in use 또는 lsof에 다른 실행 파일 |
이전 리스너를 내리고 설정·포트를 다시 동기화한 뒤 status 재확인 |
| connection refused·status 타임아웃 | plist의 Node 경로·환경을 점검하고 수 초 대기 후 gateway status 재조회 |
| curl 401 Unauthorized | 토큰 누락·오타·다른 plist를 읽는지 확인, Bearer 헤더와 변수명 재대조 |
doctor의 홈·권한 경고 |
OPENCLAW_HOME과 데이터 디렉터리 권한을 맞추고, 변경 전 tarball이 있으면 그 지점으로 복귀 |
상용 수락 연쇄（validate → doctor → status → 이차 프로브）
TTY가 없는 자동화에서는 공식 문서의 비대화형 플래그를 함께 적용합니다. 이 글에서 다루는 CLI 범위는 openclaw config validate·openclaw doctor·openclaw gateway status --format json·openclaw onboard --install-daemon뿐이며, 확인되지 않은 다른 서브커맨드는 문서 목록을 본 뒤에만 사용하세요.
운영 메모 세 가지입니다. 첫째, status JSON의 listening 정보와 lsof PID·명령행을 한 화면에 붙입니다. 둘째, 실패 시 gateway-status.json 스냅샷과 포트 지문 로그를 티켓에 첨부합니다. 셋째, 성공 시에도 openclaw --version 한 줄을 남겨 이후 업그레이드 diff를 쉽게 만듭니다.
FAQ
status는 정상인데 API 호출만 실패합니다
앞단 리버스 프록시나 이중 인스턴스를 의심하고, 127.0.0.1에 직접 붙는 curl 결과와 비교하세요.
문서에 없는 서브커맨드를 써도 되나요?
본 글은 위에 열거한 명령만 전제로 합니다. 그 외는 공식 CLI 목록을 확인한 뒤 팀 런북에 추가하세요.