OpenClaw를 «내 머신에선 된다»에서 «프로덕션에서 감사 가능»으로 끌어올릴 때 가장 자주 막히는 두 문구는 Unauthorized와 No API key for provider입니다. 각각 Gateway 세션 계층과 모델 프로바이더 자격 증명 계층에 해당하며, 고쳐야 할 명령과 파일이 다릅니다. 본문은 2026년 기준 최소 점검 순서(gateway status → doctor → models auth), 6단계 런북, 증상 매트릭스, 자격 증명 격리 체크리스트를 제공합니다. 출시 전에는 CVE-2026-25253 + Node 24 프로덕션 베이스라인 글을 먼저 완료하세요.
아래 각 항은 실제 지원에서 잘못 돌아간 경로를 반영합니다. 명령을 치기 전에 읽으세요.
Unauthorized를 전부 토큰 분실로 단정: 프록시가 헤더를 제거하거나, CLI에 빈 토큰이 캐시되거나, HTTPS가 아닐 때 WebCrypto가 막힐 수 있습니다.
프로바이더 키 부족을 Gateway 탓으로 돌리기: 대개 해당 Agent 신원에 models auth가 전달되지 않았거나 systemd 사용자 유닛에 환경 변수가 없습니다.
doctor 없이 재설치: PATH 이중화·설정 드리프트를 가립니다. 먼저 벤더 권장 순서를 따릅니다.
개발자 키를 CI에 복사: 최소 권한과 로테이션을 깨뜨립니다. 러너마다 신원을 나눕니다.
127.0.0.1 + Tailscale 조합 무시: 원격 CLI는 토큰과 DNS 해석 순서가 다릅니다. 양쪽을 검증합니다.
디스크 검증 생략: config:validate 등이 없으면 «명령은 성공했는데 프로세스는 못 읽었다»는 거짓 음성이 납니다.
| 증상 | 먼저 볼 계층 | 첫 명령 | 다음 단계 |
|---|---|---|---|
| CLI·WebSocket에서 401／Unauthorized | Gateway 세션 | openclaw gateway status | openclaw doctor 필요 시 Gateway 토큰 재발급 |
| 모델 호출 전 API 키 없음 | 프로바이더 자격 증명 | openclaw models status | openclaw models auth setup-token … 올바른 Agent 스코프로 |
| 간헐적 성공 | 이중 신원／설정 | which openclaw + 사용자 서비스 환경 | PATH와 systemd Environment= 정렬 |
| 원격 CLI만 실패 | 터널／토큰 전파 | 로컬 127.0.0.1 재검증 | Tailscale Serve와 HTTPS 요구 확인 |
«먼저 분류, 그다음 수술»—같은 Unauthorized라도 Gateway 경로와 프로바이더 경로의 처치가 다릅니다.
상태 고정: 오류 원문·시각·사용자／Agent ID를 기록하고 토큰과 프로바이더 키를 동시에 바꾸지 않습니다.
Gateway 최소 세트:openclaw gateway status → openclaw doctor 누락 시 공식 문서로 토큰 재생성.
디스크 검증: 권한이 Gateway 사용자와 일치하는지 확인하고 수정 후 사용자 서비스를 재시작합니다.
프로바이더 트랙으로 전환:openclaw models status 후 models auth setup-token 공유 셸 기록에 시크릿을 붙여넣지 않습니다.
자격 증명 격리: Agent／환경별 키 자료 또는 시크릿 매니저 참조 프로덕션에서 world-readable 디렉터리 금지.
감사 흔적: 토큰／키 로테이션 구간·영향 범위·롤백 지점을 변경 티켓에 남깁니다.
openclaw gateway status openclaw doctor openclaw models status # openclaw models auth setup-token --provider anthropic # 공식 문서에 따라 인자 채우기
참고: systemd 사용자 서비스에서는 프로바이더 환경 변수를 유닛 파일에 넣습니다—대화형 셸에만 export 해서는 전달되지 않을 수 있습니다.
주의: 공개 티켓에 전체 토큰／API 키를 붙여넣지 마세요. 앞뒤 4자 정도의 지문만 남깁니다.
잠자는 노트북에서 Gateway를 돌리면 전원·열 정책 때문에 인증이 들쭉날쭉합니다. 전용·상시 가동 macOS 노드가 프로덕션 에이전트 게이트웨이에 더 맞습니다. VPS처럼 SSH로 유지보수하고 감사하기 쉬운 Mac 용량이 필요하면 원격 모드·Tailscale 가이드와 같은 운영 관점으로 NodeMini Mac Mini 클라우드 렌탈이 현실적인 선택인 경우가 많습니다.
항상은 아닙니다. 2절 표로 분류한 뒤 gateway status와 doctor를 실행하세요. 다른 OpenClaw 글은 블로그 OpenClaw 필터에서.
피하세요. 신원과 로테이션을 분리합니다. 용량 계획: Mac mini 대여 가격.
먼저 PATH／이중 바이너리와 systemd 환경 드리프트를 확인한 뒤 이 런북을 다시 실행하세요. 도움말: 도움센터.