2026 OpenClaw Linux 상주 장애: systemd·openclaw logs·게이트웨이 포트 프로브 단계별 FAQ

소형 VPS에서 OpenClaw 게이트웨이를 상주시키면 장애는 대개 세 갈래로 수렴합니다. systemd 유닛이 재시작 루프에 빠졌는지, openclaw logs에 원인이 찍히는지, 혹은 리스닝 포트·리버스 프록시 뒤 경로만 어긋났는지입니다. 이 글은 현장에서 시간 낭비를 줄이기 위해 L0(1분)·L1(10분)·L2(30분)으로 나눠 같은 순서로 점검하는 런북입니다. macOS의 launchd와 혼동하기 쉬운 차이는 2026 클라우드 Mac에서 OpenClaw 배포: Linux VPS와 다른 macOS 검증, launchd 상주, 재현 가능한 FAQ에서 따로 정리했습니다.

L0: 1분 안에 하는 세 가지

먼저 프로세스가 살아 있는지와 최근 로그 한 줄이 말하는 바를 확인합니다. systemctl status openclaw-gateway.service(실제 유닛 이름은 배포 스크립트에 맞춤)로 Active 상태와 마지막 Exit 코드를 보고, 이어서 openclaw logs --follow 또는 배포본이 제공하는 동일 명령으로 최근 200줄을 봅니다. 마지막으로 호스트 루프백에 직접 붙습니다: curl -fsS http://127.0.0.1:<게이트웨이 포트>/health 같은 고정 엔드포인트가 있다면 그 경로를, 없다면 문서화된 최소 핸드셰이크 URL을 사용하세요. 여기서 실패하면 외부 DNS나 인증서 이전에 로컬 바인딩·유닛 자체 문제일 확률이 큽니다.

# 유닛 이름은 설치 가이드와 일치시키세요
sudo systemctl status openclaw-gateway.service --no-pager
openclaw logs --since "15 min ago"
curl -fsS http://127.0.0.1:18789/health

L1: systemd가 말해 주는 것과 숨기는 것

journalctl -u openclaw-gateway.service -b로 부팅 이후 전체를 보고, Restart=always 계열이면 짧은 간격으로 재시작 카운트가 올라가는지 확인합니다. 환경 변수는 systemctl show로 실제 로드된 값을 검증하고, User=·WorkingDirectory= 불일치로 인한 설정 파일 미탐색을 의심하세요. 소켓 활성화(.socket)를 쓰는 배포라면 서비스 유닛보다 소켓 유닛 쪽 권한(SELinux/AppArmor)이 먼저 걸리는 경우가 많습니다. 장애 후 복구 순서는 stop → 상태 플러시 → doctor/fix(있다면) → start로 고정해 두면 온콜이 흔들리지 않습니다.

L2: 게이트웨이 포트 프로브와 엣지 매트릭스

ss -lntp | grep <port>로 실제 리스닝 PID를 확인하고, Docker나 다른 에이전트가 같은 포트를 선점했는지 봅니다. 리버스 프록시 뒤라면 TLS 종료 계층과 업스트림 스킴(http/https) 불일치, proxy_read_timeout, WebSocket 업그레이드 헤더 누락이 전형적입니다. 공인망에서만 실패한다면 보안 그룹·클라우드 방화벽·fail2ban을 순서대로 좁히고, 엣지에서의 TLS 핑거프린트 변화는 롤백 게이트로 묶어 두는 편이 안전합니다. 개통 직후 네트워크·토큰 체크리스트는 2026년 단주기 급증 빌드 연계: 클라우드 Mac 개통 후 Runner 등록·네트워크 자가 점검·최소 권한 토큰의 30–60분 실무 체크리스트와 FAQ와 같은 방식으로 시간 박스를 두면 재발 분석이 쉬워집니다.