2026 OpenClaw macOS: Gateway 토큰 순환 후 전 클라이언트 401 unauthorized — LaunchAgent에 박제된 낡은 OPENCLAW_GATEWAY_TOKEN, gateway install ‘이미 설치됨’ 함정과 강제 재설치 Runbook(원격 Mac)

2026.4.x 트레인에서 반복되는 패턴은 다음과 같습니다. 제어판이나 doctor로 새 Gateway 토큰을 받았는데 Telegram·사내 IM·브라우저 UI·통합 클라이언트가 동시에 401 unauthorized를 뱉고, openclaw gateway status만 간헐적으로 녹색인 것처럼 보입니다. 실제 게이트웨이는 LaunchAgent가 plist의 EnvironmentVariables에 박아 둔 OPENCLAW_GATEWAY_TOKEN으로 기동하며, zsh에서만 export를 바꿔서는 launchd 자식 프로세스에 전달되지 않습니다. 게다가 openclaw gateway install은 기존 에이전트가 있으면 “이미 설치됨”으로 끝나 plist를 덮어쓰지 않을 수 있습니다. 본문은 증상 표·세 가지 진실 소스( plist / 셸 / 금고 )·안전한 bootout·편집·bootstrap·필요 시 --force(실제 플래그는 설치한 CLI의 --help 기준)·headless Mac SSH 체크리스트·하드 게이트를 정리합니다. breaking·device auth v2, Docker·WS 토큰, 마이그레이션·launchd 복구, silent Gateway 진단, systemd·launchd 매트릭스와 함께 읽으세요.

1. “전 클라이언트 401”과 “로컬 녹색”이 공존하는 이유

채널 플러그인은 인증 실패를 즉시 표면화하지만 짧은 프로브는 Authorization 헤더를 검증하지 않을 수 있습니다. launchd는 plist 환경을 상속합니다. 서버가 이전 시크릿을 폐기했는데도 구 토큰으로 기동 중이면 브로커 경로는 줄줄이 거절됩니다. install 출력만 믿고 plist mtime을 확인하지 않으면 같은 사고를 반복합니다.

2. 증상—증거 매트릭스

현상	1차 가설	증거
모든 경로가 같은 시각에 401	게이트웨이가 폐기된 토큰 사용	실패 응답 본문과 순환 시각 정렬
launchd만 실패, 포그라운드는 성공	plist의 낡은 OPENCLAW_GATEWAY_TOKEN	`plutil -p ~/Library/LaunchAgents/openclaw.plist`
install 후에도 동일	plist 미변경	mtime 비교, `--force`
원격 Mac만	SSH 사용자 vs GUI 사용자 launchd 도메인	`launchctl print gui/$(id -u)`

3. LaunchAgent가 실수를 증폭하는 구조

plist는 선언적 구성입니다. 한 번 문자열이 박히면 bootout 후 수정·재로드하기 전까지 재부팅해도 동일합니다. 토큰 순환은 작은 릴리스처럼 취급하고 금고→plist·compose→재시작→실 채널 스모크까지 티켓 한 줄로 묶으세요.

4. 일곱 단계 Runbook

Step 01: 동결·버전 기록

CLI·게이트웨이 버전, Label, 순환 시각, 동시 작업자.

Step 02: plist 위치

~/Library/LaunchAgents/, 전용 유닉스 계정이면 그 홈 디렉터리.

ls ~/Library/LaunchAgents/*openclaw* 2>/dev/null
launchctl list | grep -i openclaw
                

Step 03: 세 소스 맞추기

(A) plist (B) 대화형 셸(C) 금고 지문. 생 시크릿은 채팅에 금지.

Step 04: bootout → 편집 → bootstrap

공식 도메인·Label로 내린 뒤 값 갱신 후 재등록.

Step 05: CLI로 덮을 때 force

gateway install --force 등. 수락 기준은 plist 해시·mtime 변경.

Step 06: 계층 검증

로그 ready → 실제 메시지 왕복 → UI. 두 번째 plist·Docker 이중 기동 점검.

Step 07: 보안

구 토큰 revoke, 백업 암호화, 가능하면 키체인·0600 파일 참조.

5. 원격 Mac: SSH 열 항목

동일 유닉스 사용자, $HOME, launchctl print 중복 Label, ProgramArguments 실제 바이너리, 이전 디스크 경로 잔재, 방화벽 최소화, Aqua 로그인 필요 여부, 로그 디렉터리 권한, Docker 병행 시 env 우선순위(Docker 문서), 마스킹된 로그만 티켓에.

하드 게이트

A: 순환 후 10분 내 plist mtime 변경 또는 force 기록. B: 프로브가 아닌 업무 요청 200. C: 구 토큰 vault에서 revoked.

6. 흔한 오해

.env만 수정, install 성공 문구 맹신, localhost curl만으로 합격선 선언은 위험합니다.

7. 업그레이드·이전 경계

breaking은 장치 신원과 검증 정책을 동시에 움직입니다. doctor만 통과하고 plist를 놓치면 “반쯤만 녹색”이 됩니다. 이전 Runbook과 단일 시크릿 파이프라인으로 수렴하세요.

8. 인시던트 타임라인(순환 직후 0–30분)

T+0–2분：이차 install·추측 재시작 금지, 라벨·빌드 고정.T+3–8분：401 본문과 게이트웨이 auth 로그 매칭；클라만 울리면 다른 리버스 프록시·포트.T+9–15분：plist·compose·vault 병렬 대조, 두 소스 불일치면 “서버 다운”이 아니라 드리프트.T+16–25분：bootout→편집/force→bootstrap, 롤 순서는 사건당 하나.T+26–30분：하드 게이트 미달 시 녹등 금지. 원격 맥 미니는 어깨 두드리기가 안 되므로 문자 절차가 MTTR을 결정합니다.

9. 이중 게이트웨이·포트·리버스 프록시

포그라운드 디버그 인스턴스와 launchd 상주가 서로 다른 루프백 포트를 쓰거나, TLS는 새로운데 proxy_pass만 예전 백엔드를 보거나, Docker가 세 번째 환경변수층을 추가하는 경우 — 모두 “토큰은 맞는데 401”처럼 보입니다. 빌드/커밋 헬스를 루프백과 공개 DNS 양쪽에서 받아 해시가 같아야 합니다. 감독자는 launchd 또는 compose 하나로 모으거나 RFC에서 dual-write를 강제하세요.

10. plist ↔ launchctl ↔ 프로세스 삼각증거

층	건강 신호	깨짐
파일	mtime 변동, plutil 정상	XML 깨짐·퍼미션 표류
launchctl	print 경로가 which와 일치	삭제된 nvm 접두
프로세스 env	지문이 vault와 일치	키 없이 기동 → 다른 로더
로그	401 물결과 인증 거절 동시	CPU만 높음 → jsonl/bootstrap 먼저

systemd EnvironmentFile 습관을 그대로 가져오지 마십시오. macOS는 XML 리터럴이 기본이며 증거 삼각형 없이 원격 헤드리스에서는 길을 잃습니다.

11. FAQ(남는 401 가지)

Q: plist 고쳤는데도. A: launchctl print가 가리키는 실경로인지, 클라우드 동기 사본을 고치지 않았는지.Q: 먼저 revoke? A: 위험, 순서를 Runbook으로 고정.Q: doctor 녹색인데 IM 죽음. A: 실제 메시지 왕복만 합격.Q: 다사용자 미니? A: Unix 계정별 plist 분리.

12. 맺음말

macOS에서 순환 직후 전 채널 401의 주원인은 거의 항상 진실 소스 분열입니다. 유휴 없이 상주 게이트웨이를 올릴 Apple Silicon이 필요하면 MACGPU 가격과 Telegram(키워드 MACGPU)을 보세요. 플래그는 공식 CLI 도움말이 최종 기준입니다.