OpenClaw 게이트웨이는 공유 비밀로 RPC 클라이언트를 인증한다. macOS에서는 그 비밀이 실제로 세 가지 경로로 들어온다: 디스크의 openclaw.json 트리, 설정을 다시 쓸 수 있는 macOS 앱 마법사, 헤드리스 세션에 변수를 주입하는 LaunchAgent 환경 블록이다. 어느 한 층이라도 어긋나면 운영자는 유령을 쫓는다: openclaw status는 건강해 보이지만 메뉴 막대 앱은 연결 끊김을 보인다. 이 글은 두 매트릭스, 여덟 단계 롤아웃, 일곱 단계 HowTo 시퀀스를 제공해 Mac mini M4 게이트웨이 호스트가 「고쳐짐」과 「401 Unauthorized」 사이를 더 이상 오가지 않게 한다.
시작: 토큰 인증과 launchd 드리프트. 에이전트 세션 밖에서 게이트웨이 재시작 유지. 기준 설치: 설치와 배포. 헬스 자동화: doctor와 진단. 계정: 도움말. 호스트 추가: 가격.
「토큰 분열」을 외치는 증상, 「나쁜 모델」이 아님
- 분열 인격: CLI는 성공하고 메뉴 막대 앱은 설정에서 루프한다.
- 재부팅 후에만 401: loginwindow 세션에 env가 없고 파일 토큰은 맞다.
- 업그레이드 후 401: 앱이 마이너 버전에서 JSON을 다시 썼는데 launchd는 여전히 옛 변수를보낸다.
- 간헐적 성공: 리로드 중 두 게이트웨이 프로세스가 다른 설정으로 잠깐 경쟁한다.
매트릭스 A: 각 클라이언트가 자격 증명을 어디서 읽는가
| 클라이언트 | 주요 출처 | 흔한 드리프트 | 안정화 |
|---|---|---|---|
| SSH 위의 CLI | 사용자 홈 openclaw.json |
서비스 사용자와 관리자의 $HOME 불일치 |
편집 전 항상 서비스 계정으로 sudo |
| macOS 앱 | 샌드박스된 기본설정 + JSON 병합 | 「게이트웨이 없음」 감지 후 마법사 덮어쓰기 | 변경 관리로 앱 버전 고정; 파일이 정식이 된 뒤에만 앱 열기 |
| launchd 게이트웨이 | Plist EnvironmentVariables + 작업 디렉터리 파일 | 오래된 OPENCLAW_GATEWAY_TOKEN export |
둘을 원자적으로 갱신하는 단일 라이터 스크립트 |
| 자동화 에이전트 | 부모 셸에서 상속한 env | 도구 샌드박스가 env를 제거하면 토큰 없음 | 도구 매니페스트에 명시적 구성 경로 플래그 |
매트릭스 B: 롤아웃 위험 대 완화
| 변경 | 영향 반경 | 완화 |
|---|---|---|
| 월간 토큰 로테이션 | 클라이언트가 다시 로드할 때까지 모든 채널 | 최소 15분간 구+신 듀얼 라이트, 401 비율 모니터 |
| 게이트웨이 사용자 이동 | 절대 경로와 plist 라벨 | 심볼릭 링크 재생성; 복구 글의 --force 패턴으로 재설치 |
| 두 번째 리전 호스트 추가 | 운영자가 잘못된 호스트에 토큰 붙여넣기 | 금고에 호스트별 비밀 이름; 클립보드 매크로 재사용 금지 |
| 비 loopback 바인드 활성화 | 더 엄격한 인증 요구 | 게이트웨이 속도 제한 허용 목록과 짝지음 |
수치 가드레일
- 로테이션 겹침: 디스크에 새 토큰을 게시한 뒤에도 구 토큰은 최소 900초 유효하게 둔다.
- 동등성 검사: 프로덕션 게이트웨이에서 plist env 대 파일 토큰을 6시간마다 자동 diff.
- 인시던트 예산: 401 비율이 5분간 RPC의 1%를 넘으면 앱 업그레이드를 자동 동결.
GUI 팁: macOS 개인정보 프롬프트가 무인 토큰 쓰기를 막을 때는 한 번 VNC로 승인한 뒤 SSH 전용 유지보수로 돌아간다.
여덟 단계 롤아웃
- 소유권 선언: 호스트마다 정식 토큰 파일 경로.
- launchd와 싸우는 셸에서 중복 export 제거.
- 백업 경로가 있는 단일 트랜잭션으로 JSON+plist 원자 갱신 스크립트.
- 층마다 해시가 다르면 배포 실패하는 CI 스타일 검사 추가.
- CMDB 행에 게이트웨이 semver 옆에 앱 버전 핀 문서화.
- 매 업그레이드 후 doctor 실행 뒤에만 「healthy」 선언.
- 온콜 교육: 401 로그를 먼저 설정 드리프트, 다음이 모델 장애로 읽기.
- 단일 라이터에 합의 못 하는 팀은 프로덕션과 랩을 다른 NodeMac Mac mini M4로 분리.
FAQ
토큰을 키체인에 두는 편이 더 나은가?
모든 소비자가 일관되게 지원하면 그럴 수 있다. 혼합 스택은 보통 먼저 파일+plist를 동기화한 뒤 이전한다.
팀원 노트북은?
프로덕션 토큰을 노트북에서 재사용하지 않는다. 짧은 수명 개발 토큰과 분리 게이트웨이 호스트로 카페에서의 실수 프로덕션 RPC를 막는다.
launchd가 셸 프로필을 상속하는가?
아니다. 그래서 재부팅 후 plist나 게이트웨이가 읽는 파일에 복사하기 전까지 토큰이 「사라지는」 것이다.
토큰 위생은 지루한 하드웨어를 선호한다: NodeMac의 전용 Mac mini M4는 상시 게이트웨이에 Apple Silicon 여유, 개발자 노트북과 동일한 네이티브 macOS 동작, GUI 동의가 자동화를 막을 때 SSH 플러스 VNC를 준다. 홍콩·일본·한국·싱가포르·미국 노드로 사용자 옆에 게이트웨이를 두면서 공유 노트북 밖으로 비밀을 뺀다. 구매 대신 임대로 「프로덕션 게이트웨이」와 「랩 게이트웨이」를 싸게 분리해 토큰 로테이션이 정치 싸움이 되지 않게 한다. 호스트를 나눌 때는 리전별 가격에서 시작한다.