OpenClaw에서 흔한 「가짜 정상」은 openclaw gateway status에서 RPC 점검이 정상인데 클라이언트는 gateway closed (1000)을 던지거나, 업그레이드 직후 도구가 갑자기 동작하지 않는 패턴입니다. 본문은 증상 → 유력 원인 → 검증 명령 → 조치 순으로 정리하고, 토큰·scope·워크스페이스 경로·모델 백엔드(CLI-only로 도구가 꺼지는 경우 포함) 세 가지 고빈도 실패를 다루며 6단계 복구 Runbook과 systemd·Docker에서 봐야 할 로그 줄을 제시합니다. 사이트의 운영 관측, 보안 강화, 크로스플랫폼 설치 글과 역할을 나누며, 여기서는 연결과 세션 일관성에 초점을 둡니다. 먼저 경로를 복구하고, 장기 모니터링·변경 관리는 관측 편에 맡깁니다.
Gateway 제어 평면 프로브는 보통 프로세스 존재와 포트 응답만 확인합니다. 반면 gateway closed (1000) 같은 클라이언트 오류는 서버가 WebSocket·세션을 닫은 뒤나 인증·정책 불일치 뒤에 자주 나타납니다. 아래 7가지는 현장 자가 점검용입니다. 해당이 많을수록 UI 새로고침만 믿지 말고 3절의 순서대로 재시작·설정 검증을 실행하세요.
프로브 녹색을 E2E 녹색으로 오인: status의 RPC OK는 좁은 검사입니다. scope 부족·세션 만료로 디바이스 계열 명령과 도구 실행 채널은 여전히 실패할 수 있습니다.
토큰 드리프트: 환경 변수·설정 파일·Gateway 프로세스가 읽은 토큰이 동일하지 않습니다. 한쪽만 비밀을 회전하면 간헐적 성공과 대량 실패가 섞입니다.
워크스페이스 경로 불일치: agents.defaults.workspace가 오래된 디렉터리를 가리키거나 컨테이너 바인드가 어긋나면 도구 계층이 거부하거나 곧 끊깁니다.
CLI-only 모델 백엔드: 일부 *-cli/... 라우트는 설계상 파일류 도구를 비활성합니다. 「Gateway는 온라인인데 도구만 안 됨」으로 보여 closed(1000)와 혼동하기 쉽습니다.
업그레이드 후 이중 프로세스: 패키지는 갱신됐지만 옛 Gateway가 포트를 쥐거나 PID 파일이 남아 새 프로세스가 반쯤만 기동하고 프로브가 옛 리스너를 칩니다.
보안 정책 강화 직후: dmPolicy / networkPolicy 활성화 뒤 핸드셰이크는 성공해도 첫 페이로드가 정책에 걸립니다. 보안 강화 글의 허용 목록과 대조하세요.
최소 재현 묶음 없음: 에러 반 줄만 있고 CLI 버전·설정 발췌·최근 변경이 없으면 2차 대응이 추측이 되어 복구가 길어집니다.
공통 원인은 분산 시스템의 다층 헬스를 단일 불리언으로 압축하는 것입니다. 다음 표로 보이는 문자열과 먼저 돌릴 명령을 매핑해 로그 바다에서 헤매지 않도록 합니다.
온콜 Runbook 맨 위에 붙여 두고, 보이는 문자열을 맞춘 뒤 가장 짧은 검증 경로를 고릅니다. 세부 서브커맨드는 설치한 OpenClaw 빌드에 따르며, 아래는 의도를 나타내는 예시입니다.
| 보이는 증상 | 유력 원인 | 먼저 돌릴 점검 |
|---|---|---|
| RPC OK인데 디바이스·채널 작업에서 closed(1000) | 세션 scope가 실제 동작과 다르거나, 토큰이 Gateway 런타임과 다름 | openclaw status --all·토큰 출처 추적·보안 설정 allowlist 검토 |
| 업그레이드 후 「도구 전부 비활성」 | 모델 라우팅이 CLI-only 백엔드이거나 Gateway가 재시작되지 않아 새 설정 미적용 | openclaw models list·CLI-only 해제 후 openclaw gateway restart |
| 가끔 성공·대량 실패 | 여러 터미널에 서로 다른 토큰, 또는 리버스 프록시가 오래된 연결 유지 | 단일 셸에서 env 통일·클라이언트 세션 정리·프록시 idle timeout 확인 |
| 경로류 도구 거부 | workspace 설정과 실제 저장소 경로 불일치 | openclaw config get agents.defaults.workspace와 디스크 diff |
| 정책 변경 직후 끊김 | dmPolicy·networkPolicy 강화로 첫 패킷 거부 | 보안 강화 절 재확인·알려진 세션만 일시 완화해 검증 |
프로브 녹색은 제어 평면이 살아 있다는 것만 증명합니다. 안정적으로 일하려면 토큰·워크스페이스·모델 백엔드·정책 네 줄을 맞춰야 합니다.
로그·롤백 리듬은 운영 관측 글을 보세요. 여기서는 약 10분 안에 「재시작+검증」인지 「설정 롤백」인지 가르는 데 초점을 둡니다.
순서는 의도적으로 저비용 조치를 앞에, 설정 롤백을 뒤에 두어 곧바로 방화벽을 열거나 재설치하지 않게 합니다. 운영 티켓에는 영향이 「해당 CLI만」인지 「다중 사용자 세션 포함」인지 적어 두세요.
동시 작업 동결: 동료에게 새 세션·배치 작업을 잠시 멈추게 해 Gateway 재시작 시 재연결 폭주를 피합니다.
상태 스냅샷: openclaw --version, openclaw status --all(가능 시) 실행 후 출력 저장. 최근 토큰 회전·openclaw.json 변경을 기록합니다.
워크스페이스·모델 라우팅 검증: 실제 디렉터리를 가리키는지 확인. openclaw models list로 CLI-only 백엔드 오선택 여부를 봅니다.
doctor·validate 실행: CLI의 openclaw doctor, config:validate 또는 동등 명령으로 명백한 불일치를 고칩니다.
Gateway 순서 재시작: openclaw gateway restart 또는 systemd·컨테이너 유닛 재시작으로, 새 프로세스가 listen 하기 전에 이전 프로세스가 종료되게 합니다.
최소 수락 테스트: 읽기 전용 도구 1회·쓰기 도구 1회. 통과한 뒤에만 타인 사용을 재개합니다. 실패 시 4절 시스템 로그로 이동합니다.
openclaw --version openclaw status --all 2>&1 | tee /tmp/openclaw-status.txt openclaw config get agents.defaults.workspace openclaw models list openclaw doctor openclaw gateway restart # 이어서 최소 읽기·쓰기 도구를 각각 한 번 실행해 세션과 scope 확인
참고: Gateway가 전용 원격 Mac에서 돌면 긴 SSH 세션·GUI 프롬프트가 여전히 체인을 끊을 수 있습니다. 무인 실행을 안정화하려면 에이전트 노드 글의 디렉터리·세션 분리 체크리스트와 병행하세요.
3절 재시작 후에도 closed(1000)이면 먼저 종료되지 않은 프로세스나 컨테이너 내부 바인드 마운트 드리프트를 의심합니다. 관측 글과 같이, 설정 논쟁 전에 누가 listen 중인지·어떤 사용자가 기동했는지를 밝힙니다.
systemd(베어메탈 Linux): systemctl status로 메인 프로세스 루프 여부 확인. journalctl -u <unit> -n 200 --no-pager로 종료 코드·정책 키워드 검색. Docker Compose: docker compose ps와 docker compose logs --tail=200 gateway로 재시작 시각 정렬. Linux systemd + Tunnel 가이드로 배포했다면 Tunnel·루프백 바인딩이 낡은 포트를 가리키지 않는지 확인합니다.
주의: 어떤 인터페이스가 listen 중인지 모른 채 Gateway를 공인망에 잠시 노출해 「연결 테스트」를 하지 마세요. 보안 강화 글의 제약 안에서 검증해 점검이 사고로 번지지 않게 합니다.
아래 항목이 있으면 2차 진단이 짧아집니다. 외부 공유 전 비식별 처리하세요.
노트북만 Gateway 호스트로 쓰면 절전·OS 업데이트·다중 사용자 데스크톱 세션에 취약합니다. 소형 Linux만으로는 필요한 macOS 툴체인·그래픽 경계 시나리오가 부족한 경우가 많습니다. OpenClaw를 장기 가동·계약 가능한 실행 계층에 올릴 때는 하드웨어를 반복 대여하는 것보다 전용 원격 Mac이 보통 더 안정적입니다. 자체 Mac 랙 대비 NodeMini Mac Mini 클라우드 대여는 반복 가능한 노드 프로필을 정의하기 쉬워 「Gateway+툴체인」을 VPS 단지처럼 인수인계하기 좋습니다.
프로브는 좁은 경로만 봅니다. 세션·scope·토큰·모델 백엔드는 여전히 어긋날 수 있습니다. 3절 순서로 재시작하고 doctor·validate를 실행하세요. 실행 계층 용량 계획은 Mac Mini 대여 요금과 고객센터를 참고하세요.
모델 라우팅이 CLI-only 백엔드인지, Gateway가 재시작되어 새 설정을 읽었는지, 워크스페이스 경로와 토큰 로테이션이 CLI·서비스 전역에 완료됐는지 확인합니다.
블로그 OpenClaw 카테고리에서 설치·systemd·Docker·보안·관측 글로 들어가고, 연결 기준선은 고객센터와 맞춰 보세요.