Grok 로그인 3경로 · SSH/VNC 결정표 · 8단계 Runbook · 20분 검수
OpenClaw v2026.5.20(2026-05-21 릴리스)은 xAI Grok OAuth를 Gateway 로컬 브라우저 콜백 필수에서 device-code 원격 친화 경로로 옮겼습니다. CLI가 auth.x.ai에 디바이스 코드를 요청하고 터미널에 검증 URL과 짧은 코드를 출력합니다. 손에 든 PC 브라우저에서 SuperGrok/X Premium을 승인하면 SSH 프로세스가 폴링해 토큰을 받아 xai/oauth auth profile에 저장합니다. 원격 Mac을 임대해 Gateway를 돌리지만 주력 PC가 Windows/Linux라면 127.0.0.1:56121 콜백 불가로 막히기 쉬웠습니다. 본문은 감사 가능한 운영 관점으로 세 로그인 경로, SSH×VNC 결정표, 8단계 Runbook, 티켓용 네 결론, FAQ를 제공합니다. 먼저 10분 루트맵으로 CLI/Gateway를 띄우세요. OAuth 경로 이슈는 v2026.5.6 Doctor/Codex OAuth, 기업 출구망은 아웃바운드 프록시를 병행 증적으로 두세요.
5.20 이전 Grok 연결 경로는 대개 API Key(xAI 콘솔 발급, 구독 OAuth와 별 계열) 또는 loopback 브라우저 OAuth(Gateway 호스트가 127.0.0.1:56121 콜백을 열어야 함) 두 가지였습니다. SSH로 임대 Mac에 들어가 launchd가 Gateway를 돌리는 형태에서는 loopback OAuth가 포트 포워딩이나 VNC 브라우저 동의를 강요합니다. 사용자 A로 설치하고 Gateway는 B에서 돌면 HOME 불일치가 흔합니다.
5.20의 device-code는 브라우저 주체와 Gateway 주체를 분리합니다. 원격은 토큰 폴링, 사람은 손에 든 PC에서 xAI 동의만 하면 됩니다. 같은 릴리스의 Policy 플러그인도 있지만, 먼저 Grok 대화를 열려면 device-code가 임대 Mac 기본 경로입니다. OAuth 이후 Grok 검색·ACP까지 보려면 v2026.3.28 Grok 승인·ACP로 2단계 검수하세요.
버전 하한: openclaw --version ≥ 2026.5.20. CLI와 Gateway 데몬은 동일 빌드로 맞춥니다.
계정 자격: SuperGrok·X Premium 등 xAI 정책상 OAuth API 토큰을 받을 수 있는 계정이 전제입니다. 동의 화면의 Grok Build 표시는 OpenClaw가 Grok Build 앱을 요구한다는 뜻이 아닙니다.
상태 디렉터리: refresh 토큰은 OpenClaw 상태 디렉터리 auth profile에 저장됩니다. 임대 Mac은 고민감 자산으로 취급하고 공개 클라우드에 동기화하지 마세요.
| 경로 | 대표 명령 | 적합 상황 | 임대 Mac 통증 |
|---|---|---|---|
| API Key | XAI_API_KEY / SecretRef | API 과금·CI 무인 | 구독 OAuth와 별도 관리 |
| loopback OAuth | models auth login --provider xai --method oauth | 로컬 MacBook·동일 GUI | VNC 또는 56121 포워딩 |
| device-code(5.20+) | --provider xai --device-code | SSH 임대 Mac·Docker·VPS | 승인까지 터미널 유지·타임아웃 시 재 login |
임대 Mac의 기본 답은 device-code 우선입니다. 동일 사용자 VNC에서 loopback에 익숙할 때만 브라우저 OAuth를 고르세요.
| 검수 항목 | SSH만 | VNC 권장 | 통과 기준 |
|---|---|---|---|
| openclaw --version / doctor | 충분 | 선택 | ≥ 2026.5.20, provider 경고 없음 |
| xAI device-code login | 충분(URL+짧은 코드·로컬 브라우저) | 선택 | auth profile 생성 |
| loopback OAuth | 포워딩 필요 | 동일 사용자 데스크톱 브라우저 | 56121 콜백 |
| Gateway 18789 콘솔 | curl | Network·모델 선택 | 기본 xai/* |
| launchd 동일 사용자 | 로그 | 로그인 사용자 = Gateway 사용자 | launchd 체크리스트 일치 |
| 기업 프록시 | 환경 변수 | 시스템·CLI 프록시 일치 | auth.x.ai 도달 |
헤드리스 Linux 대 macOS+VNC와 병행하면, device-code로 macOS 임대 노드 OAuth는 SSH 중심에 가깝지만 콘솔 교차·키체인·TCC는 여전히 GUI가 필요합니다.
동결·백업: 버전·launchd 사용자 기록. 신규는 10분 루트맵.
≥ 2026.5.20: openclaw update 후 openclaw gateway restart.
device-code 로그인: Gateway와 동일 사용자에서 openclaw models auth login --provider xai --device-code 또는 openclaw onboard --auth-choice xai-device-code.
로컬 브라우저 승인: 검증 URL·짧은 코드를 복사해 SSH 폴링 창을 닫지 말고 xAI에서 완료하세요.
기본 모델: openclaw models set xai/grok-4.3(계정에 맞는 xai/*).
doctor: xai/oauth profile 확인. 401은 OAuth 경로부터 분기.
smoke: Gateway 재시작 후 짧은 프롬프트·로그 조각을 티켓에.
VNC 교차(권장): 동일 사용자 VNC에서 18789 콘솔·CLI 일치. 공개는 HTTPS 역프록시.
openclaw --version openclaw update openclaw doctor openclaw models auth login --provider xai --device-code openclaw onboard --install-daemon --auth-choice xai-device-code openclaw models set xai/grok-4.3 openclaw gateway restart openclaw models list
| 확인 | VNC 증거 | SSH 증거 | 통과 |
|---|---|---|---|
| 버전 ≥ 5.20 | 콘솔 About | openclaw --version | CLI/Gateway 일치 |
| device-code | (선택) 모델 UI | profile + 짧은 응답 | xai/* 응답 |
| OAuth refresh | 재시작 후 성공 | doctor 경고 없음 | 간헐 401 없음 |
| 동일 사용자 | 데스크톱 사용자 | launchctl print | HOME 어긋남 없음 |
VNCMac 임대 Apple Silicon에서는 Gateway와 OAuth 상태를 동일 VNC 세션에 두면 「SSH 로그인은 됐는데 Gateway는 구 모델」 설전을 20분 감사 가능 검수로 압축하기 쉽습니다.
CLI·Gateway·첫 대화.
읽기 →Codex 경로·fetch.
읽기 →OAuth 이후 2단계.
읽기 →임대 Mac 설치 경로.
읽기 →본 흐름은 가능합니다. 원격이 URL·짧은 코드를 출력하고 로컬 브라우저에서 승인하면 SSH가 폴링합니다. Gateway 콘솔·키체인은 동일 사용자 VNC 교차를 권장합니다.
models auth login --provider xai --device-code를 다시 실행하고 기업 프록시가 auth.x.ai를 막지 않는지 확인하세요.
여러 profile은 가능하나 기본 라우팅을 변경 티켓에 명시하고 CI key와 대화 OAuth를 models 계층에서 분리하세요.
v2026.5.20 xAI device-code OAuth가 푸는 것은 임대 Mac에서 가장 골치 아픈 localhost 콜백입니다. 장기 안정에는 버전 동일 원천, auth profile 네임스페이스, 명시적 기본 모델, CLI·Gateway 동일 사용자 증적이 여전히 결정적입니다. device-code를 「VNC 불필요」로 오해하면 둘째 주 refresh·콘솔 검증에서 뒤집힙니다. 정답은 SSH OAuth + VNC 20분 교차 검수입니다.
6절과 같은 검수용 VNCMac: Mac 클라우드 구매에서 노드·플랜 선택, 연결 헬프 센터(SSH-VNC)를 확인하세요.