OpenClaw Gateway 설치는 시작일 뿐이고, 프로덕션에서 당번 시간을 잡아먹는 것은 헬스 체크 왜곡, 로그를 찾을 수 없음, 업그레이드 뒤 설정 드리프트 입니다. 이 글은 Linux systemd + Tunnel, Docker Compose, 세 플랫폼 설치를 마친 팀을 위해 최소 관측면, 로그 라우팅, 업그레이드·롤백, 증상 대조표를 보강합니다. 라우팅 정책은 modelRouting 글로 이어집니다.
설치 튜토리얼은 해피 패스를 검증합니다. 프로덕션은 가짜로 살아 있는 프로세스, 포트 충돌, 권한 변화, 다운스트림 모델 타임아웃 같은 꼬리 위험을 다룹니다. 아래 여섯 가지는 당번을 추측에서 조사로 바꾸는 체크리스트입니다.
헬스 체크가 너무 느슨함: 프로세스 존재만 보고 Gateway가 실제로 라우팅하는지 확인하지 않아, 트래픽을 넣은 뒤에야 반쯤 죽은 상태를 발견합니다.
로그 분산: systemd, 컨테이너, 앱 표준 출력, 리버스 프록시가 각각 다른 곳에 쌓여 장애 시 타임라인을 못 맞춥니다.
업그레이드에 기준선 없음: 이전 이미지 digest나 npm 전역 버전을 기억하지 못해 롤백이 「다시 깔아보기」가 됩니다.
설정과 비밀 혼재: openclaw.json과 환경 주입이 어긋나 간헐적 401이나 조용한 라우팅 실패로 나타납니다.
관측이 변경과 엇박: 리스닝 주소나 Tunnel 대상을 바꿨는데 모니터링 프로브 경로는 그대로입니다.
Gateway를 만능 실행기로 취급: 무거운 Xcode 작업을 같은 작은 VPS에 얹어 CPU를 꽉 채우고 「모델이 느리다」로 오판합니다.
두 가지 이상 해당되면 먼저 최소 관측면을 채운 뒤 기능을 쌓으세요. 그렇지 않으면 매 릴리스마다 같은 유형의 장애로 학비를 냅니다.
표로 역할을 나눠 「설치할 수 있다」와 「안정적으로 굴릴 수 있다」를 한 번에 리뷰하지 않게 합니다.
| 주제 | 설치·상주 글(systemd · Docker · 세 플랫폼) | 이 글(프로덕션 관측과 변경) |
|---|---|---|
| 프로세스와 노출면 | unit·Compose, 루프백 리스닝, Tunnel 또는 방화벽 정책 | 생존 프로브, 포트 충돌 순찰, 변경 후 프로브 경로 회귀 |
| 설정 모델 | 최초 openclaw.json 기록, 디렉터리 권한 | diff 리뷰, 백업, 카나리와 롤백 순서 |
| 로그 | 먼저 디스크에 남기거나 journal·docker로 수집 | 필드 의미, 상관 ID, 흔한 오류 패턴 정리 |
| 업그레이드 | 복사 가능한 업그레이드 명령 또는 이미지 pull 경로 제공 | digest·버전 기록, 백업 시점, 롤백 검증 체크리스트 |
| 모델 라우팅 | 선택적으로 언급 | 깊은 전략은 modelRouting 전용 글 참고 |
운영의 재현성은 담당자 기억이 아니라 같은 점검 명령과 같은 롤백 순서에서 나옵니다.
순서는 systemd와 Docker 모두에 맞습니다. 먼저 사실층(프로세스·포트·헬스 엔드포인트), 다음 해석층(로그와 다운스트림). 명령은 배포판마다 조금 다르지만 체크포인트는 같게 유지하세요.
주 프로세스 확인: systemd는 systemctl status, Docker는 docker compose ps. 재시작 횟수와 종료 코드를 봅니다.
리스닝 대조: ss -lntp 또는 컨테이너 포트 매핑이 Tunnel·리버스 프록시 대상과 맞는지.
헬스 체크: 문서 또는 자체 프로브 경로에 HTTP 프로브. 「프로세스 기동」과 「라우팅 가능」을 구분합니다.
최근 로그 가져오기: journalctl -u 또는 docker compose logs --tail=200. 시간 창을 정한 뒤 전문 검색합니다.
다운스트림 모델 검증: 최소 요청으로 「Gateway는 정상인데 상류 API가 문제」를 배제합니다.
변경 기록 출력: 릴리스마다 버전·digest, 설정 diff, 프로브 스크린샷을 남겨 다음 당번이 이어갑니다.
# 예: 빠른 순찰(unit·컨테이너 이름은 바꿔 쓰기) systemctl status openclaw-gateway.service --no-pager || true ss -lntp | grep -E '18789|LISTEN' || true # Docker 경로(예) # docker compose -f /opt/openclaw/docker-compose.yml ps # docker compose -f /opt/openclaw/docker-compose.yml logs --tail=200 gateway
안내: Cloudflare Tunnel을 쓰면 변경 후 공개 프로브와 호스트 루프백 프로브를 함께 확인하세요. 엣지에 오래된 라우트가 남아 「내부만 통한다」는 오판을 피합니다.
롤백 가능한 업그레이드에는 세 가지가 필요합니다. 릴리스 전 스냅샷, 릴리스 중 변경 벡터는 하나만, 릴리스 후에는 같은 프로브 집합으로 인수 확인. Docker 경로는 고정 digest나 프라이빗 레지스트리 태그 전략을 우선하고, 베어메탈·npm은 전역 패키지 버전과 lockfile(해당 시)을 고정합니다.
카나리: 스테이징 또는 저트래픽 복제본에서 먼저 검증한 뒤 프로덕션으로 롤합니다. Gateway 뒤에 원격 실행 노드가 있으면 계층형 릴리스로 제어면을 먼저 확인하고 실행면을 키웁니다.
주의: openclaw.json과 환경 주입을 백업하지 않은 채 「겸사겸사 라우팅도 손대기」를 병행하지 마세요. 프로덕션 중단의 흔한 원인은 설정의 반쯤 적용 상태입니다.
아래 숫자는 리뷰를 맞추기 위한 경험적 규모입니다. 실제 타임아웃과 쿼터는 공급사와 계약을 따릅니다.
| 증상 | 먼저 의심 | 대응 방향 |
|---|---|---|
| 시작 직후 종료 | 설정 JSON 문법, 환경 변수 누락, 포트 점유 | 포그라운드로 한 번 재현하고 설치 글 체크포인트와 대조 |
| 간헐적 401 | 키 로테이션 비동기, 여러 설정 파일 경로 | 주입 원천을 하나로 정리하고 오래된 셸 프로파일 오염 제거 |
| CPU 장기 포화 | 실행 부하를 Gateway와 동일 기기에 쌓음 | 무거운 작업을 전용 실행 노드나 원격 Mac으로 이동 |
| 지연 급증 | 다운스트림 속도 제한, DNS, TLS 핸드셰이크 | 로그·캡처를 층별로 하고 네트워크를 분리한 뒤 모델을 조정 |
무거운 macOS 빌드, 서명, GUI 의존 작업을 Gateway와 같은 작은 Linux VPS에 얹으면 단기적으로는 편하지만 제어면 안정성과 장애 대응 시 신호 대 잡음비를 함께 떨어뜨립니다. 순수 로컬 노트북만으로는 24시간 운영과 감사 가능한 격리도 어렵습니다. 안정적인 iOS CI, 자동화 에이전트, 계약으로 묶을 수 있는 연산력이 필요한 팀은 Gateway는 범용 VPS에 두고 macOS 실행은 전용 원격 Mac 노드에 두는 편이 낫습니다. 운영 경계와 확장 탄력 면에서 NodeMini 클라우드 Mac Mini 대여가 그 실행층에 맞습니다. 리전과 디스크로 노드를 고르고 OpenClaw 제어면과 계층을 나누면 당번은 명확한 관측면만 보면 됩니다.
블로그 목록에서 OpenClaw 카테고리 필터를 쓰고, systemd → Docker → 관측 → modelRouting 순으로 읽으세요.
헬프 센터를 확인한 뒤, 이 글의 헬스 체크와 로그 절과 교차 검증하세요.