2026 OpenClaw: 닥터, 게이트웨이 진단, 클라우드 Mac에서의 안정 실행

OpenClaw가 웹훅에 응답하지 않거나 게이트웨이가 401을 뿜기 시작하면 가장 빠른 복구는 무작정 재시작이 아닙니다. openclaw doctor, 구조화된 로깅, 채널 프로브로 이어지는 진단 루틴입니다. 이 글은 2026년 명령 세트를 정리하고 흔한 장애와 수정을 표로 매핑하며, 뚜껑을 닫을 때마다 잠드는 노트북 대신 Apple Silicon Mac mini를 임대해 같은 루프를 스테이징하는 이유를 설명합니다. 운영팀이 doctor 출력을 주간 템플릿으로 남기면 사고 때 “무엇이 바뀌었는지” 설명 비용이 크게 줄어듭니다.

먼저 doctor가 필요한 신호

다음 패턴이 반복되면 포럼을 건너뛰세요. 게이트웨이는 건강한데 에이전트가 작업을 집지 않거나, 로그에 Unauthorized와 코드 1008, 터널을 고친 뒤 Slack 이벤트가 두 번 옵니다. 모두 openclaw doctor가 버전 드리프트, 빠진 환경 변수, 오래된 토큰을 무관한 스택 트레이스를 몇 시간 쫓기 전에 드러냅니다. 첫 단계로 doctor를 고정하고 출력을 인시던트 채널에 붙이면 에스컬레이션 품질이 올라갑니다.

최근 Node를 올렸다면 openclaw status --deep을 doctor와 함께 실행하세요. OpenClaw 2026 문서는 여러 CLI 경로에 Node 22.16 이상 또는 Node 24를 가정합니다. 오래된 런타임은 설치는 통과해도 플러그인이 ESM 전용 헬퍼를 import하는 순간 실패합니다. CI와 스테이징의 Node 버전을 맞추지 않으면 로컬만 성공하는 지옥이 이어집니다.

사고가 시작되는 순간 스냅샷을 남기세요. doctor 출력을 복사하고 비밀을 마스킹한 뒤 openclaw logs의 처음 200줄을 첨부합니다. 이 습관이 있는 팀은 티켓을 40~60% 빨리 닫습니다. 벤더와 내부 리뷰어가 같은 사실을 공유하기 때문입니다. 스크린샷을 재구성하는 데 시간을 쓰지 않아도 됩니다.

VPN 스플릿 터널을 바꾼 직후에는 게이트웨이가 쓰는 네트워크 경로와 동일한 경로에서 doctor를 다시 실행하세요. 비대칭 라우팅은 노트북 프로브는 성공하는데 데몬 계정에서는 실패하는 전형적인 이유입니다. 클라우드 Mac에 SSH로 들어가 그곳에서 실행하면 프로덕션에 가까운 경로로 검증할 수 있습니다. 터널·프록시 상세는 게이트웨이·프록시·터널 강화를 참고하세요.

프로필이 여러 개인 환경에서는 어떤 ~/.openclaw를 읽는지 doctor가 짚어 줄 때가 있습니다. 환경 변수로 덮어쓴다면 LaunchAgent plist와 대화형 셸의 .zshrc를 모두 확인하고 의도치 않은 이중 정의를 제거하세요. “보이는 설정”과 “실제로 적용되는 설정”이 어긋나면 토큰을 갱신해도 오래된 프로세스가 옛 파일을 붙잡을 수 있습니다.

증상 매트릭스: 명령과 의미

매트릭스는 트리아지 보드처럼 쓰세요. 명령은 프로덕션에 준하는 스테이징에서 안전하게 실행할 수 있고, 게이트웨이 재시작이 필요한 변경은 유지보수 창에서 진행하세요.

증상	첫 명령	“좋은” 상태
게이트웨이는 떠 있는데 UI가 연결 안 됨	openclaw gateway status	리스너 PID 하나, 예상 바인드(대개 프록시 뒤 127.0.0.1)
무작위 끊김	openclaw logs --follow	채팅 왕복 후 5분 동안 TLS·토큰 오류가 반복되지 않음
Slack/Discord 침묵	openclaw channels status --probe	켜진 각 채널이 엔드포인트 도달 가능·OAuth 스코프 유효
배포 후 포트 충돌	lsof -nP -iTCP:PORT | grep LISTEN	OpenClaw 관련 프로세스가 포트를 하나만 점유
LLM 401	API 키 환경 변수·과금 확인	자동화에는 종량제 개발자 키가 필요(일반 구독 아님)

게이트웨이 토큰과 allowedOrigins

설정이 플랫 gateway.token에서 gateway.auth.token으로 옮겨갈 때 많은 팀의 대시보드 연동이 깨졌습니다. 리버스 프록시가 레거시 헤더를 주입한다면 openclaw doctor --generate-gateway-token으로 재발급하고 프록시와 로컬 ~/.openclaw/openclaw.json 사본을 모두 갱신하세요.

브라우저 클라이언트에는 명시적 allowedOrigins가 필요합니다. 개발은 http://localhost:3000, 운영은 호스트명을 나열합니다. 와일드카드 *는 편하지만 위험하며 인터넷에 노출된 OpenClaw는 감사에서 바로 지적됩니다. 터널 구성에서는 오리진을 게이트웨이·프록시·터널 강화 지침에 맞추세요.

EADDRINUSE는 두 프로필이나 좀비 node가 같은 포트를 잡았을 때가 많습니다. 오래된 PID를 종료하고 두 번째 lsof로 확인한 뒤 문서화된 서비스 매니저로 재시작하세요. macOS 서버에서는 LaunchAgent 대 cron 패턴을 따라 재시작을 결정적으로 유지합니다. plist 라벨 중복이나 수동 실행과 LaunchAgent 이중 등록은 전형적인 함정입니다.

토큰을 로테이션한 뒤에는 프록시 캐시나 오래된 systemd·launchd 유닛이 옛 환경을 읽지 않는지도 확인하세요. 설정 파일을 고친 직후 프로세스가 재시작되지 않으면 doctor는 새 설정을 읽는데 실제 프로세스는 옛 토큰을 쥐는 상태가 될 수 있습니다.

HTTP 200 너머의 채널 프로브

웹훅이 200 OK여도 서명 검증이 조용히 실패하면 이벤트는 떨어집니다. 시크릿을 돌린 뒤 openclaw channels status --probe를 실행하고 각 채팅 표면에서 합성 메시지를 보내세요. 로그의 상관 ID를 남깁니다. 많은 팀이 스테이징에서 14일 로그 보존을 유지해 운영 사고와 비교합니다.

HTTP 콜백을 수동으로 디버그할 때는 연동이 보내는 것과 동일한 헤더로 curl 하세요. Authorization: Bearer … 접두사가 빠지거나 붙여 넣은 토큰에 불필요한 줄바꿈이 있으면 프로바이더 장애처럼 보이는 401이 납니다. 본문 크기도 비교하세요. 일부 프록시는 1 MB를 넘는 페이로드를 잘라 큰 JSON 도구 호출을 깨뜨립니다. 한도를 올리거나 청크 업로드로 바꾸세요.

WhatsApp이나 모바일 우선 브리지에서는 벤더 권고대로 충돌하는 데스크톱 세션을 로그아웃하세요. 중복 세션은 “어디에나 오는데 OpenClaw만 빈다”처럼 보입니다. Discord·Slack은 워크스페이스 관리자가 정책을 죈 뒤 메시지 기록 읽기나 메시지 보내기 인텐트가 빠진 경우가 많습니다.

주간 5분 프로브 작업을 예약하세요. openclaw health --json을 때리고 비영 종료면 메일 한 통—cron 한 줄로도 됩니다. 월요 스탠드업보다 데모 중에 터지는 회귀를 줄입니다. 장기 운영에서는 프로브 결과를 시계열로 저장하고 주간 실패율을 대시보드로 보면 추세가 보입니다.

진단을 클라우드 Mac에서 하는 이유

노트북은 절전되고 VPN은 흔들리고 MDM은 데몬을 막습니다. 72시간 소크 테스트에는 맞지 않습니다. Apple Silicon 임대 Mac mini는 항상 온라인이고 로컬 macOS와 같은 Unix 도구를 주며 개인 BYOD에서 비밀을 분리합니다. SSH로 반복이 빠릅니다: doctor, vim으로 설정, 서비스 재시작, 로그 스트림을 책상까지 걸어가지 않고 돌립니다.

비용은 탄력 임대 하루 16.9달러와 엔지니어가 오후 내내 막히는 기회비용을 비교하세요. 진단에 GPU는 필요 없습니다. 안정 전원, 정확한 시계, 트리아지 중 OS 패치로 멋대로 재부팅하지 않는 머신이 필요합니다. 사고가 닫히면 임대를 끌 수 있습니다. 창고에 자산으로 둔 하드로는 불가능합니다.

운영 팁: 클라우드 호스트와 CI 이미지에서 디렉터리 레이아웃을 맞춰 openclaw.json 경로를 이식 가능하게 하세요. /Users/alice/Projects처럼 하드코딩하면 공유 자동화 계정으로 옮길 때 몇 시간을 다시 씁니다.

메모리 계획도 중요합니다. 작은 Mac mini 티어에서 여러 채널 브리지를 동시에 켜기 전에 여유 RAM을 최소 4 GB 남기세요. doctor는 스왑 스래싱이 시작될 때까지 경고하지 않습니다. 프로브 부하 테스트 중에는 Activity Monitor의 memory_pressure나 vm_stat을 봅니다.

클라우드 쪽에서는 타임존과 NTP 어긋남도 로그 상관을 망칩니다. 진단 벤치에서 date와 프로바이더 타임스탬프를 맞추고 서명 웹훅의 시간 창 오류가 없는지 확인하세요. Apple Silicon은 전력 대 성능이 좋아 여러 tail을 동시에 열어도 노트보다 조용합니다.

자주 묻는 질문

최신 OpenClaw 빌드에서 gateway.token은 어디로 갔나요?

최근 릴리스는 인증을 gateway.auth.token 아래에 중첩합니다. 대시보드가 오래된 플랫 키를 읽는다면 openclaw doctor --generate-gateway-token으로 재생성하고 리버스 프록시나 UI가 기대하는 모든 위치에 붙여 넣으세요.

재부팅 직후 EADDRINUSE가 보이는 이유는?

LaunchAgent, 수동 터미널, 고아 node가 같은 게이트웨이 포트를 잡을 수 있습니다. lsof -i :PORT로 PID를 찾고 중복 프로필을 중지하며 프로필당 openclaw gateway 인스턴스가 하나만 돌게 하세요.

클라우드 Mac mini가 OpenClaw 진단에 유용한가요?

예. Apple Silicon Mac mini는 로컬 macOS와 같은 Unix 도구, 긴 로그 tail을 위한 안정 전원, 수면하는 노트북과의 분리를 제공합니다. 임대는 비용을 탄력적으로 유지하면서 게이트웨이 강화를 반복할 수 있게 합니다.

호스트가 지루할수록 OpenClaw는 빛납니다. 믿을 만한 전원, 빠른 SSD, 운영에 가까운 macOS 동작. Apple Silicon은 doctor 동시 실행, 로그 집계, 웹훅 테스트용 가벼운 브라우저에 여유를 주고 거대 타워의 팬 소음 없이 돌아갑니다. SSH 자동화에 선택적 VNC를 더하면 사고 때는 키우고 조용한 주에는 줄이는 진단 벤치가 됩니다. AI 에이전트가 배포 패브릭의 일부가 된 Mac 스타일 HTML 샵에 딱 맞는 탄력입니다.