macOS에서 OpenClaw 게이트웨이는 흔히 launchd로 감독된다. 운영자와 때로 에이전트가 그에 의존하는 동일 세션에서 게이트웨이를 재시작하려 한다. 그 패턴은 재시작 RPC가 아직 붙어 있는 동안 LaunchAgent를 언로드할 수 있으며, 별도 셸로 로그인하기 전까지 게이트웨이가 돌아오지 않는 현장 사례와 맞닿는다. 이 글은 이유, 안전 대 위험 행동 표, 7가지 실행 단계와 수치 가이드, 복구·동시성 심화 링크를 정리한다.
변경 전에 LaunchAgent 게이트웨이 복구와 대화형 채팅 대 장시간 작업 동시성을 읽어 재시작이 무거운 작업 공간과 충돌하지 않게 하라. 최초 설치는 설치 및 배포를 따른다. 계정 질문은 도움말, 게이트웨이와 CI 분리 비용은 가격. 토큰·plist 드리프트는 구성 드리프트, 예약 작업 정렬은 스케줄 정렬, 429·백오프는 속도 제한 매트릭스를 참고한다.
실패 모드: launchd 아래 자기 참수
게이트웨이를 서버이자 실행 중인 명령의 의존성으로 동시에 본다. 에이전트가 게이트웨이가 소유한 동일 RPC 채널로 openclaw gateway restart(또는 동등 래퍼)를 내면, launchd는 깨끗한 인계 전에 작업을 bootout할 수 있다. 재시작을 시작한 CLI는 전송 오류로 종료되고 bootstrap으로 건강이 복구된다는 감독이 남지 않을 수 있다—SSH만 있는 헤드리스에서 특히.
- 징후 A: 에이전트가 재시작을 호출한 같은 초에
gateway status가 실행 중에서 사라짐으로 변한다. - 징후 B: 로그에 launchd 언로드 줄과 RPC 끊김 오류가 나란히 있다.
- 징후 C: 외부 모니터(HTTP 상태 또는 TCP)가 수분간 타임아웃하지만 loginwindow 사용자 세션이 없다.
매트릭스: 누가 게이트웨이를 재시작할 수 있는가
| 행위자 | 전형적 맥락 | 판정 | 더 안전한 대안 |
|---|---|---|---|
| 사람(두 번째 SSH) | screen 또는 ssh user@host | 선호 | 문서화된 bootout·bootstrap 순서 실행 및 로그 보관 |
| OpenClaw 내부 자동화 에이전트 | 채팅 처리 중 도구 호출 | 재시작 회피 | 티켓 발행. 외부 오케스트레이터가 뮤텍스 후 재시작 |
| 예약 LaunchAgent | 야간 드리프트 수리 | plist가 격리되면 허용 | 채팅 피크와 어긋나게. 스케줄 정렬 기사 참조 |
| 동일 Mac의 CI 작업 | 파이프라인 단계 게이트웨이 바운스 | 비권장 | 전용 관리 작업 대기열과 분리 자격 증명 |
두 번째 매트릭스: 재시작 전 체크리스트
| 점검 | 합격 기준 |
|---|---|
| 리스너 소유권 | 구성된 게이트웨이 포트 패밀리에 정확히 하나의 PID가 일치. 롤백 메모에 PID 기록 |
| 로그 디스크 여유 | 상태와 로그 볼륨에 최소 8 GB 여유. 재시작 중 쓰기 실패 방지 |
| 긴 작업과 뮤텍스 | 워크스페이스 작업이 게이트웨이 유지보수용 컴파일 뮤텍스 계층을 잡고 있지 않음 |
| 인증 토큰 연속성 | 클라이언트가 대화형 GUI 없이 디스크에서 토큰을 다시 로드할 수 있음 |
매번 기록할 운영 수치
- 콜드 스타트 예산:
bootstrap후 실패 선언 전 최대 90초. 백신 또는 전체 디스크 액세스 대화 상자가 대기 중이면 더 길게. - RPC 프로브 간격: 첫 1분은 5초마다, 이후 지수 백오프.
- 동시 관리 작업: 호스트당 게이트웨이를 바꾸는 작업은 하나로 제한. 병렬 plist 편집은 어떤 변경이 건강을 망췄는지 추적하기 어렵다.
헤드리스 팁: GUI 권한 대화 상자가 의심되면 잠시 VNC로 접속해 한 번 클릭한 뒤 SSH만으로 돌아온다.
호스트에서 7단계(HowTo 서술)
- 고장 난 게이트웨이를 통한 명령 중단. 동일 Mac mini M4에 두 번째 SSH를 연다. 이 세션은 곧 재활용할 RPC에 의존하면 안 된다.
- 증거 수집: 상태, 최근 로그, 권위 있다고 믿는 plist 경로—구성 드리프트 기사와 대조.
lsof등으로 리스너 확인. 공유 랩 장비에서 잘못된 PID를bootout하지 않는다.- macOS 버전에 맞는 launchd 의미로 언로드한 뒤 디스크에서 bootstrap하여 EnvironmentVariables와 WorkingDirectory를 적용.
- 외부 셸에서 헬스 프로브로 RPC가 성공할 때까지. 그때만 채팅 클라이언트 재연결.
- 인시던트 한 줄 메모: 타임스탬프, 이유, 채팅 또는 CI 영향—나중에 속도 제한 기사와 상관하기 쉽다.
- 여전히 비정상이면 LaunchAgent 복구로 돌아가 알려진 양호 plist로 전환하고 에이전트 세션 안에서 재시작 루프를 반복하지 않는다.
자주 묻는 질문
Ansible으로 재시작을 자동화할 수 있나요?
가능합니다. 단, 플레이북의 제어 연결이 재시작하려는 게이트웨이 프로세스를 경유하지 않아야 합니다. 게이트웨이를 데이터베이스처럼 취급하고 오케스트레이션 평면에서 바운스하세요.
개발과 운영에 게이트웨이가 각각 있을 때
plist, 포트, 상태 디렉터리를 분리합니다. 어떤 LaunchAgent 레이블이 어떤 환경인지 문서화하여 bootout이 잘못된 레이블을 치지 않게 합니다.
언제 호스트를 완전히 나눌까요?
채팅 SLO와 CI 선점이 뮤텍스 계층 뒤에서도 충돌할 때—단일 launchd 그래프에 쌓는 대신 NodeMac에서 두 번째 전용 Mac mini M4를 추가하세요.
신뢰할 수 있는 OpenClaw 운영은 빌드와 같은 하드웨어 이야기의 이점을 누린다: 전용 Mac mini M4가 Apple Silicon 성능과 네이티브 macOS를 주고, 헤드리스 유지보수용 SSH와 UI 권한 프롬프트용 선택적 VNC를 결합하며, 홍콩·일본·한국·싱가포르·미국으로 새벽 3시에 깨울 머신에 운영자를 가깝게 한다. 구매 대신 임대는 이 런북이 실험 에이전트와 운영 채팅을 하나의 launchd 그래프에 두면 안 된다는 것을 증명했을 때 게이트웨이 전용 두 번째 호스트를 경제적으로 만든다. 다음 리스크를 쌓기 전에 지역별 요금을 비교하라.