OpenClaw 일상 운영 Runbook: Gateway 18789 헬스체크·단계적 업그레이드·로그 디스크 설계(2026)

본문을 읽기 전에 세 가지 운영 원칙을 기억해 두자:

이중 프로브로 I/O 스파이크를 오판하지 않기

포트 18789에 curl을 보내기 전에 lsof로 포트 소유자를 확인한다. Dashboard가 느리면 먼저 디스크 I/O를 의심하고 Gateway 장애와 혼동하지 않는다.

curl + lsof
단계적 업그레이드, 30분 롤백 창

버전 태그 기록 → 골든 노드 선행 → 프로덕션 배포. tarball 설정과 구 plist를 함께 복원하면 롤백은 30분 이내에 완료된다.

≤ 30분
로그와 루트 볼륨 분리

로그 디렉터리와 npm 캐시가 루트 디스크를 조용히 채우는 것이 Gateway 예기치 않은 종료의 주요 원인이다. logrotate로 주기적으로 분리·순환시킨다.

logrotate 7d

이 글이 답하는 하나의 질문

OpenClaw 설치 스크립트가 완료되고 Gateway 18789에 처음으로 초록불이 켜진 후, 많은 팀이 "잘 돌아가는 동안은 손대지 말자" 단계에 들어선다. 그러다 산발적인 401 오류, 업그레이드 후 노드 하나만 동작이 달라지는 현상, 또는 루트 디스크가 꽉 차서 Gateway가 조용히 종료되는 상황을 맞닥뜨린다. 이는 설치 가이드가 다루는 영역이 아니다.

이 글이 답하는 질문은 하나다: OpenClaw의 일상 운영 동작을 표준화해, 팀원 누구든 15분 내에 헬스체크나 롤백을 완료할 수 있는 Runbook을 어떻게 만드느냐. 범위는 Gateway 헬스 프로브 → 단계적 업그레이드 전략 → 롤백 절차 → Tailscale / SSH 선택 → 로그 디스크 설계다.

1. Gateway 18789 헬스 프로브

많은 팀의 "헬스체크"는 curl 한 번이 전부인데, 그것만으로는 부족하다. 포트가 다른 프로세스에 점유되거나 launchd가 서비스를 제대로 재시작하지 못한 경우, curl은 즉시 실패하지 않고 멈춰 버린다. 올바른 프로브는 HTTP 응답과 포트 소유자를 동시에 검증해야 한다.

Gateway 이중 프로브 (cron 작업에 통합 가능)

# 1. HTTP 생존 확인: 200 기대, 실패 시 경보
curl -fsS --max-time 3 http://127.0.0.1:18789/health \
  && echo "gateway OK" || echo "GATEWAY FAIL"

# 2. 포트 소유자 확인: PID가 node/openclaw에 속하는지 검증
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 3. 최근 오류 로그 (설치 경로에 맞게 조정)
tail -n 50 ~/.openclaw/logs/gateway.log | grep -i "error\|warn\|exit"

curl이 200을 반환해도 Dashboard가 느리다면 먼저 디스크 I/O를 확인하자: iostat -d 1 5로 쓰기 스파이크를 본다. 로그 대량 쓰기를 Gateway 장애로 오판하는 것이 가장 흔한 오탐 원인이다. "골든 노드"를 프로덕션과 동일 버전으로 유지하면 이상 발생 시 즉시 비교 대조할 수 있다.

포트 18789가 다른 프로세스에 점유된 경우

lsof -iTCP:18789가 OpenClaw가 아닌 PID를 반환하면, 먼저 launchctl list | grep openclaw로 서비스 상태를 확인한다. 이전 버전의 잔류 프로세스가 포트를 잡고 있는 경우가 많다. plist를 그대로 둔 채 해당 프로세스를 kill만 하면 다음 로그인 시 launchd가 다시 시작시킨다.

2. 업그레이드 전 세 가지 확인 사항

OpenClaw는 자주 업데이트가 출시된다. 최신 버전을 무분별하게 따라가면 두 가지 위험이 생긴다: 설정 키 변경으로 Gateway가 시작되지 않거나, 기존 Channel 설정과 호환되지 않는 경우다. 단계적 업그레이드가 표준 방식이지만, "한 대에서 먼저 시도해 보기"로만 해석하고 버전 기록과 디스크 여유 확인을 생략하는 팀이 많다.

업그레이드 전 체크리스트: 하느냐 안 하느냐의 차이
확인 항목	실시함 단계적 업그레이드	생략함 npm update 직접 실행
버전 기록 (현재 태그 저장)	`npm install openclaw@이전태그`로 즉시 롤백	이전 버전 불명, tarball 복원만 가능
골든 노드 선행	장애가 테스트 노드에 격리, 프로덕션 영향 없음	모든 Channel이 동시에 다운
루트 디스크 여유 ≥15%	npm install 임시 파일에 충분한 공간 확보	설치 중간에 디스크가 꽉 차 불완전한 상태 잔존

업그레이드 전 스냅샷 (.upgrade-memo에 저장)

# 현재 버전 기록
npm list -g openclaw --depth=0 > .upgrade-memo

# 현재 설정 아카이브
tar czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/config/ \
  ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 디스크 여유 확인 ≥15%
df -h / | awk 'NR==2 {print "여유："$4, "사용률："$5}'

3. 롤백: tarball + plist 이중 복원 절차

롤백 실패의 가장 흔한 원인은 바이너리 버전이 아니라 설정 키 비호환이다. 새 버전이 필수 필드를 추가했다면, 바이너리를 되돌려도 새 설정이 남아 있으면 Gateway 시작 오류가 발생한다. 올바른 순서는 bootout → tarball 복원 → 바이너리 다운그레이드 → bootstrap이다.

롤백 전체 절차 (목표: ≤ 30분)

# 1단계: 서비스 중지
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 2단계: 설정 tarball 복원
tar xzf openclaw-config-20260604.tar.gz -C /

# 3단계: npm 패키지 다운그레이드
npm install -g openclaw@1.x.x   # 기록해 둔 버전 태그로 교체

# 4단계: 서비스 재시작
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 5단계: 확인 (시작에 약 10초 소요)
sleep 10 && curl -fsS http://127.0.0.1:18789/health && echo "롤백 성공"

plist 경로 변경에 주의하자. 새 버전 설치 프로그램이 ProgramArguments 경로를 수정했다면, bootout은 새 plist 경로로, bootstrap은 복원된 구 plist 경로로 실행해야 한다. 두 경로가 다를 수 있다——업그레이드 전에 구 plist와 새 plist를 diff해서 차이를 upgrade-memo에 기록해야 하는 이유가 여기 있다.

4. Tailscale과 SSH/rsync: 어떤 상황에 무엇을 쓸까

"Tailscale을 써야 하나, 직접 SSH로 해야 하나"라는 팀 내 논쟁은 이분법적 선택이 아니다. 각각 최적화된 사용 사례가 다르다. Tailscale은 방화벽 규칙 없이 멀티 디바이스·크로스 리전 상시 접속에 강하다. SSH/rsync는 병목이 프로토콜 오버헤드가 아닌 egress 대역폭인 대용량 파일 전송에 적합하다.

Tailscale vs SSH/rsync 의사결정 매트릭스
관점	Tailscale WireGuard 메시	SSH / rsync 직접 암호화 전송
권장 상황	여러 기기에서 Dashboard 상시 확인, 팀원 원격 접속	CI 결과물 다운로드, 로그 아카이브 취득, 정기 대용량 동기화
지연 특성	DERP 중계 시 약 +50ms (아시아↔캐나다), 직접 연결 시 bare RTT에 근접	bare TCP로 낮은 지연. 포트 개방 또는 점프 호스트 필요
대역폭 소비	프로토콜 오버헤드 약 +5%, 저처리량 상시 세션에 적합	`--bwlimit`으로 제한 권장, 캐나다 egress 포화 방지
접근 제어	Tailscale ACL로 디바이스·사용자 단위 세밀한 제어	SSH 키 관리, `authorized_keys` 정기 감사 필요
문제 해결	ACL 규칙, DERP 노드, MagicDNS 해석	라우팅, MTU, 타임아웃 및 재개 처리

rsync 속도 제한 예시 (캐나다 egress 보호)

# 캐나다 노드에서 로그 아카이브 취득, 50 MB/s 제한, 중단 재개
rsync -avz --bwlimit=50000 --partial \
  user@canada-m4.hashvps.com:~/.openclaw/logs/archive/ \
  ./local-logs/

# Tailscale이 직접 연결을 사용하는지 확인 (DERP 중계 아님)
tailscale ping canada-m4 --until-direct

5. 로그 디스크 설계: logrotate 설정과 파티션 권장사항

Gateway 예기치 않은 종료의 상당 부분이 루트 디스크가 꽉 찼기 때문이다. OpenClaw는 기본적으로 사용자 홈 디렉터리에 로그를 기록한다——npm 글로벌 캐시와 같은 볼륨이다. Xcode 내보내기나 CI 임시 파일까지 더해지면 512 GB 디스크가 몇 주 만에 조용히 꽉 찬다. 주기적인 rm이 아닌 logrotate가 올바른 해결책이다.

~/.openclaw/logrotate.conf (경로를 환경에 맞게 조정)

/Users/mac/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    dateext
    copytruncate
}

# crontab 추가 (매일 새벽 3시 실행):
# crontab -e 에서 추가:
# 0 3 * * * /usr/local/bin/logrotate /Users/mac/.openclaw/logrotate.conf

npm 캐시는 npm config set cache-max 10240으로 10 GB 상한을 설정하고, 업그레이드 후 npm cache clean --force로 구 패키지 캐시를 정리한다. 1 TB 노드에서는 ~/.openclaw/logs와 npm 캐시를 별도 볼륨으로 이동시키는 것을 권장한다. 로그가 급증해도 루트 디스크와 Gateway 프로세스에 영향이 없다.

6. FAQ: 자주 묻는 운영 질문 여섯 가지

Gateway 18789 헬스체크가 200이 아닌 값을 반환한다. 어디서 먼저 확인해야 하나?

lsof -nP -iTCP:18789 -sTCP:LISTEN을 실행해 리스닝 상태를 확인한다. 출력이 없으면 프로세스가 실행 중이 아닌 것이다. launchctl list | grep openclaw로 launchd 상태를 확인하고, ~/.openclaw/logs/gateway.log의 최근 50줄에서 오류 원인을 찾는다. 포트는 리스닝 중인데 HTTP가 500을 반환한다면 설정 키 오류일 가능성이 높다——업그레이드 전 tarball과 비교한다.

롤백 후 plist 경로를 수동으로 수정해야 하나?

새 버전 설치 프로그램이 plist를 수정한 경우에만 필요하다. 순수한 npm 버전 업그레이드로 설치 프로그램 변경이 없었다면 tarball 복원 후 경로는 그대로다. 바이너리 경로가 변경됐다면 bootstrap 전에 plist의 ProgramArguments를 구 바이너리 경로로 수정해야 한다——업그레이드 전에 구 plist와 새 plist를 diff해야 하는 이유다.

여러 노드를 동시에 업그레이드해야 하나, 하나씩 해야 하나?

반드시 하나씩이다. 골든 노드를 먼저 업그레이드하고 24시간 동안 Gateway 상태와 Channel SLA를 관찰한다. 문제가 없으면 프로덕션 노드를 최소 30분 간격으로 순차적으로 배포한다. 동시 업그레이드는 문제가 생겼을 때 비교 기준이 없어져 모든 노드가 동시에 다운된다.

Dashboard에 CPU 100%가 표시된다. OpenClaw 버그인가?

반드시 그렇지는 않다. top -o cpu나 Activity Monitor로 실제 CPU를 소비하는 PID를 먼저 파악한다. 정상적인 OpenClaw Gateway 프로세스의 CPU 사용률은 평상시 1~5%여야 한다. node 프로세스가 스파이크한다면 Channel 요청 적체나 비정상적인 로그 쓰기를 확인한다. 전용 Mac mini에서는 renice로 Xcode 빌드 프로세스의 우선순위를 낮춰 OpenClaw와의 경합을 줄일 수 있다.

Tailscale은 연결됐는데 Dashboard에 접근이 안 된다. 원인은?

Tailscale ACL 정책에서 해당 기기에 포트 18789가 허용되는지 확인한다. 그런 다음 tailscale ip -4로 tailnet IP를 얻어 curl http://<tailnet-ip>:18789/health로 직접 테스트한다. IP로는 접근되는데 MagicDNS 호스트명으로는 안 된다면 DNS 해석 문제이지 Gateway 문제가 아니다.

logrotate 실행 후 Gateway는 계속 로그 파일에 쓸 수 있나?

copytruncate를 사용하면 logrotate가 파일을 복사한 뒤 원본을 잘라낸다. Gateway의 파일 디스크립터는 그대로 유효하므로 서비스 중단 없이 로그를 계속 쓸 수 있다. 기본 create 모드를 쓴다면 Gateway에 SIGHUP 시그널을 보내거나 postrotate 스크립트로 launchctl kickstart를 실행해 로그 핸들을 다시 열어야 한다. copytruncate가 더 간단하고 서비스 중단이 없다.