macOS의 OpenClaw: openclaw gateway restart가 성공해도 리스너가 오래된 채로 남는 문제

원격 Mac에서 OpenClaw 게이트웨이를 상시 구동하면 확장 배포, 헬스 프로브, 페어링 재악수까지 한 장기 프로세스에 몰리기 쉽습니다. 그런데 `openclaw gateway restart`는 종료 코드 0으로 돌아오는데 리스닝 포트나 유닉스 소켓, 관리 엔드포인트 응답만 어제 빌드 문자열에 고정되는 장면이 반복됩니다. 이는 네트워크 유령이 아니라 `launchd`가 사용자 LaunchAgent `com.openclaw.gateway`에 남겨 둔 `ProgramArguments`·`WorkingDirectory`의 오래된 맵을 재평가하지 못했을 때가 많습니다.

SSH 비대화 셸과 GUI 로그인 콘솔 사용자는 PATH·키체인 가시성이 다릅니다. 대화형 셸에서 재시작이 자식만 바꾸고 외부 디스크립터를 쥔 본체는 이전 세대로 남으면, 대시보드는 초록인데 깊은 라우트만 구 API라는 분열이 생깁니다.

이 글은 먼저 공식 단계별 트러블슈팅 사다리를 최우선으로 두고, launchd 기반 설치·강제 재설치 런북, lastTouchedVersion과 딥 경로 스플릿, 원격 CLI·설정 드리프트 헬스 프로브, 429·무반응 채널 증상, 메모리·jsonl 회귀와 롤백, Compose·토큰·웹소켓 페어링과 교차해 읽는 전제를 둡니다.

먼저 증상을 말로 고정합니다. CLI는 성공, 로그는 온순하지만 `curl` 헤더나 관리 버전 줄만 낡았습니다. 확장은 로드된 것처럼 보이나 행동이 안 바뀝니다. 여기서 곧바로 `bootout`은 이릅니다.

공식 사다리는 429·자격 증명·이중 토글·확장 격리처럼 launchd 밖 원인을 먼저 가릅니다. 타임스탬프가 있는 기록을 남겨 다음 담당이 같은 미로에 빠지지 않게 합니다.

`~/Library/LaunchAgents/com.openclaw.gateway.plist`는 디스크 진실의 입구입니다. `plutil -p`로 `ProgramArguments`와 `WorkingDirectory`를 읽고 절대 경로가 이번 설치 루트와 맞는지 확인합니다.

도메인을 헷갈리면 명령은 깨끗이 끝나도 보는 에이전트는 그대로입니다. SSH 부트스트랩과 GUI 사용자 도메인을 섞지 않도록 `launchctl print` 차이를 남깁니다.

복구의 축은 `launchctl bootout`과 `bootstrap`의 쌍입니다. 모호한 `kick`보다 등록 재구성이 필요한 사례에 맞습니다. 짧은 공백이 있으니 짧은 점검 공지를 합니다.

plist 메타가 설치 레이아웃과 어긋나면 `gateway install --force`를 검토합니다. 토큰·페어링 JSON을 먼저 대피하고 복원 절차까지 세트로 계획합니다.

CLI·게이트웨이·영구 메타의 세맥 줄이 맞지 않으면 스플릿브레인 같은 부분 성공이 이어집니다. brew와 수동 설치를 섞은 호스트일수록 래퍼와 실체 이중화를 경계합니다.

확장 팩은 코어 semver와 별계약입니다. 코어만 올라가 확장 API면이 뒤처지면 리스닝은 새 것처럼 보여도 깊은 경로만 구동작이라는 함정이 납니다.

원격 Mac은 업데이트 창이 갈라지면 증상이 시간차로 드러납니다. 월요일에 CLI만 올리고 금요일까지 LaunchAgent가 낡은 전형입니다. 설치 후 훅으로 plist 절대경로 검증을 자동화하면 재발이 줄어듭니다.

모니터링에는 시작 한 줄 버전과 주기 하트비트를 넣습니다. 얕은 초록만 믿지 않는 문화를 만듭니다.

베이스라인은 semver 줄, plist 지문, `launchctl print` 발췌, 리스닝 목록, 최소 프로브 묶음입니다. 주간으로 돌리고 업그레이드 직후엔 필수입니다.

백업은 장식이 아니라 복원 연습까지 포함합니다. 대피한 토큰을 실제로 되돌릴 수 있는지 스테이징에서 한 번 검증합니다.

1. 성공처럼 보이는 증상

종료 코드 0은 헬스 체크가 아닙니다. 사용자 LaunchAgent는 래퍼만 바뀌고 긴 수명 사이드카가 옛 유닉스 소켓을 쥔 채 남을 수 있습니다.

부분 리로드는 혼란스럽습니다. doctor 요약은 초록인데 깊은 프로브만 구 정책을 돌려줍니다. 시맨틱 불일치와 429 무반응과 구분이 어렵습니다.

2. 공식 사다리를 먼저 끝내는 이유

건너뛰면 한 시간 단위로 길을 잃습니다. 구조화된 진단은 데몬 재시작 실패와 설정이 나쁜 재시작 성공을 분리합니다.

429·자격 증명이면 launchd를 고쳐도 같은 지옥입니다. 기록을 타임라인화합니다.

3. plist 진실과 bootout/bootstrap

등록 재구성이 필요하면 `launchctl bootout`과 `bootstrap` 쌍이 현실적입니다. 도메인 문자열은 문맥 의존이니 런북에 치환 규칙을 적습니다.

4. 번호가 붙은 복구 체크리스트

1. 기대 semver, 실행 중 semver, plist mtime, 사다리 각 단 출력을 한 벌로 모읍니다.
2. 공식 사다리를 위에서 아래로 실행해 429·자격 증명을 먼저 제외합니다.
3. `plutil -p ~/Library/LaunchAgents/com.openclaw.gateway.plist`로 ProgramArguments를 확인합니다.
4. 올바른 bootstrap 도메인에서 `launchctl bootout` 후 `bootstrap`을 실행합니다.
5. `launchctl print`로 `com.openclaw.gateway`가 기대 바이너리를 가리키는지 확인합니다.
6. 메타가 깨졌다면 토큰을 대피한 뒤 `gateway install --force`를 검토합니다.
7. 정렬 후 최소 프로브와 깊은 라우트를 모두 다시 실행합니다.

# 1) 먼저 공식 사다리(doctor/프로브/확장 순)
#    참고: 20260506-openclaw-official-troubleshooting-gateway-probe-extensions-429-runbook-2026-ko.html

# 2) 사용자 LaunchAgent 실체 확인
/usr/bin/plutil -p ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 3) DOMAIN을 환경에 맞게 바꾼 뒤 재등록
/usr/bin/launchctl bootout DOMAIN ~/Library/LaunchAgents/com.openclaw.gateway.plist || true
/usr/bin/launchctl bootstrap DOMAIN ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 4) Label com.openclaw.gateway 생존 확인
/usr/bin/launchctl print DOMAIN | /usr/bin/grep -n "com.openclaw.gateway" || true

# 5) ProgramArguments가 여전히 어긋나면 대피 후 강제 설치
#    openclaw gateway install --force

5. 개입 비교표

최소 개입으로 불변 조건을 되돌리는 지표입니다. 세부는 링크 런북이 정본입니다.

6. 시맨틱 버전 정렬과 원격 드리프트

CLI·게이트웨이·영구 메타는 세트로 움직이는 것이 건강합니다. lastTouchedVersion 불일치는 성공 메시지와 모순된 행동을 만듭니다.

원격 Mac은 업데이트 시점이 갈라지므로 설치 후 훅으로 plist 절대경로 검증을 자동화하세요.

7. 원격 Mac 운영 베이스라인

복구 후 semver 줄, plist 지문, `launchctl` 발췌, 리스닝 목록, 얕은·깊은 프로브를 한 파일에 묶습니다. 헤더에 호스트명을 적습니다.

주간과 도구 체인 변경 직후에 돌려 느린 부패를 잡습니다.

8. 번호가 붙은 고통 포인트

1. 종료 코드 0과 응답 헤더 세대가 어긋남.
2. GUI 도메인과 SSH 도메인 혼동으로 보는 프로세스가 다름.
3. 시맨틱은 맞는 듯하지만 확장 API면만 구 계약.
4. 토큰은 새로운데 리스닝이 옛 시크릿이라는 클라이언트 분열.

9. FAQ

질문: 곧바로 `bootout`해도 되나요? 답: 짧은 중단이 있습니다. 먼저 429·자격 증명을 사다리로 가르세요.

질문: `gateway install --force`가 만능인가요? 답: 설치 불일치엔 효과적이나 상류 장애나 잘못된 설정 가면을 쓸 수 있습니다.

10. 결론과 호스티드 Mac

성공 메시지는 계약 이행을 보장하지 않습니다. 공식 사다리로 상층 원인을 가르고 `com.openclaw.gateway`를 `bootout`/`bootstrap`으로 재등록한 뒤 필요하면 강제 설치와 시맨틱 정렬로 갑니다.

베이스라인화가 마무리입니다. 증적이 모일수록 재발 설명이 빨라집니다.

재현 가능한 원격 Mac 환경을 찾는다면 SFTPMAC 호스티드 Mac 요금도 함께 검토하세요. 공개 런북과 병행하면 야간 분석이 가벼워집니다.