본문으로 건너뛰기

xAI Grok OAuth(SuperGrok 구독)

Hermes 에이전트는 기존 SuperGrok 구독을 사용하여 accounts.x.ai에 대한 브라우저 기반 OAuth 로그인 흐름을 통해 xAI Grok을 지원합니다. XAI_API_KEY은 필요하지 않습니다. 한 번 로그인하면 Hermes가 자동으로 백그라운드에서 세션을 새로 고칩니다.

전송은 codex_responses 어댑터(xAI는 응답 스타일 엔드포인트를 노출함)를 재사용하므로 어댑터 변경 없이 추론, 도구 호출, 스트리밍 및 프롬프트 캐싱이 작동합니다.

동일한 OAuth 전달자 토큰은 Hermes의 모든 direct-to-xAI 표면(TTS, 이미지 생성, 비디오 생성 및 전사)에서도 재사용되므로 단일 로그인으로 이 네 가지를 모두 다룰 수 있습니다.

개요​

품목가치
제공자 IDxai-oauth
표시 이름xAI Grok OAuth(SuperGrok 구독)
인증 유형브라우저 OAuth 2.0 PKCE(루프백 콜백)
운송xAI 응답 API(codex_responses)
기본 모델grok-4.3
엔드포인트https://api.x.ai/v1
인증 서버https://accounts.x.ai
환경 변수가 필요합니다아니요(XAI_API_KEY은 이 제공자에 사용되지 않습니다)
구독SuperGrok(모든 활성 계층)

전제 조건​

  • 파이썬 3.9+
  • Hermes 에이전트 설치
  • xAI 계정의 활성 SuperGrok 구독
  • 로컬 시스템에서 사용 가능한 브라우저(또는 원격 세션의 경우 --no-browser 사용)

빠른 시작​

# Launch the provider and model picker
hermes model
# → Select "xAI Grok OAuth (SuperGrok Subscription)" from the provider list
# → Hermes opens your browser to accounts.x.ai
# → Approve access in the browser
# → Pick a model (grok-4.3 is at the top)
# → Start chatting

hermes

첫 번째 로그인 후 자격 증명은 ~/.hermes/auth.json에 저장되며 만료되기 전에 자동으로 새로 고쳐집니다.

수동으로 로그인​

모델 선택기를 거치지 않고도 로그인을 실행할 수 있습니다.

hermes auth add xai-oauth

원격/헤드리스 세션​

브라우저를 사용할 수 없는 서버, 컨테이너 또는 SSH 세션에서 Hermes는 원격 환경을 감지하고 브라우저를 여는 대신 인증 URL을 인쇄합니다.

중요: 루프백 수신기는 127.0.0.1:56121의 원격 시스템에서 계속 실행됩니다. xAI 리디렉션은 해당 리스너에 도달해야 하므로 포트를 전달하지 않으면 노트북에서 URL을 열 수 없습니다(Could not establish connection. We couldn't reach your app.).

# In a separate terminal on your local machine:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Then in your SSH session on the remote machine:
hermes auth add xai-oauth --no-browser
# Open the printed authorize URL in your local browser.

점프 상자/요새를 통해: -J jump-user@jump-host을 추가합니다.

ProxyJump 체인, mosh/tmux 및 ControlMaster 문제를 포함한 전체 단계별 내용은 SSH/원격 호스트를 통한 OAuth를 참조하세요.

로그인 작동 방식​

  1. Hermes는 브라우저에서 accounts.x.ai을 엽니다.
  2. 로그인(또는 기존 세션 확인)하고 액세스를 승인합니다.
  3. xAI는 Hermes로 다시 리디렉션되고 토큰은 ~/.hermes/auth.json에 저장됩니다.
  4. 그 이후부터 Hermes는 백그라운드에서 액세스 토큰을 새로 고칩니다. hermes auth remove xai-oauth하거나 xAI 계정 설정에서 액세스를 취소할 때까지 로그인 상태가 유지됩니다.

로그인 상태 확인​

hermes doctor

◆ Auth Providers 섹션에는 xai-oauth을 포함하여 모든 제공자의 현재 상태가 표시됩니다.

스위칭 모델​

hermes model
# → Select "xAI Grok OAuth (SuperGrok Subscription)"
# → Pick from the model list (grok-4.3 is pinned to the top)

또는 모델을 직접 설정하세요.

hermes config set model.default grok-4.3
hermes config set model.provider xai-oauth

구성 참조​

로그인 후 ~/.hermes/config.yaml에는 다음이 포함됩니다.

model:
default: grok-4.3
provider: xai-oauth
base_url: https://api.x.ai/v1

제공자 별칭​

다음은 모두 xai-oauth으로 확인됩니다.

hermes --provider xai-oauth        # canonical
hermes --provider grok-oauth # alias
hermes --provider x-ai-oauth # alias
hermes --provider xai-grok-oauth # alias

Direct-to-xAI 도구(TTS/이미지/비디오/녹화)​

OAuth를 통해 로그인하면 모든 direct-to-xAI 도구는 동일한 전달자 토큰을 자동으로 재사용합니다. API 키를 사용하지 않는 한 별도 설정은 없습니다.

각 도구의 백엔드를 선택하려면 다음 안내를 따르세요.

hermes tools
# → Text-to-Speech → "xAI TTS"
# → Image Generation → "xAI Grok Imagine (image)"
# → Video Generation → "xAI Grok Imagine"

OAuth 토큰이 이미 저장된 경우 선택기는 이를 확인하고 자격 증명 프롬프트를 건너뜁니다. OAuth나 XAI_API_KEY이 모두 설정되지 않은 경우 선택기는 OAuth 로그인, API 키 붙여넣기, 건너뛰기 등 3가지 선택 메뉴를 제공합니다.

Video generation is off by default

video_gen 도구 세트는 기본적으로 비활성화되어 있습니다. 에이전트가 video_generate을 호출하기 전에 hermes tools → 🎬 Video Generation(누르기 공간)에서 활성화하세요. 그렇지 않으면 에이전트는 비디오 생성을 위해 태그가 지정된 번들 ComfyUI 기술로 대체될 수 있습니다.

모델​

도구모델메모
채팅grok-4.3기본값; OAuth를 통해 로그인하면 자동 선택됨
채팅grok-4.20-0309-reasoning추론 변형
채팅grok-4.20-0309-non-reasoning비 추론 변형
채팅grok-4.20-multi-agent-0309다중 에이전트 변형
이미지grok-imagine-image기본값; 510초
이미지grok-imagine-image-quality더 높은 충실도; 1020초
비디오grok-imagine-video텍스트를 비디오로, 이미지를 비디오로; 최대 7개의 참조 이미지
TTS(기본 음성)xAI /v1/tts 엔드포인트

채팅 카탈로그는 온디스크 models.dev 캐시에서 실시간으로 파생됩니다. 캐시가 새로 고쳐지면 새로운 xAI 릴리스가 자동으로 나타납니다. grok-4.3은 항상 목록 상단에 고정되어 있습니다.

환경 변수​

변수효과
XAI_BASE_URL기본 https://api.x.ai/v1 엔드포인트를 재정의합니다(드물게 필요함).
HERMES_INFERENCE_PROVIDER런타임에 활성 제공자를 강제합니다. HERMES_INFERENCE_PROVIDER=xai-oauth hermes.

문제 해결​

토큰이 만료되었습니다. 자동으로 다시 로그인되지 않습니다.​

Hermes는 각 세션 전에 토큰을 새로 고치고 401에서 다시 반응합니다. invalid_grant으로 새로 고침이 실패하는 경우(새로 고침 토큰이 취소되었거나 계정이 교체된 경우) Hermes는 충돌 대신 입력된 재인증 메시지를 표시합니다.

수정: hermes auth add xai-oauth을 다시 실행하여 새로운 로그인을 시작하세요.

승인 시간이 초과되었습니다.​

루프백 리스너에는 유한한 만료 기간(기본값 180초)이 있습니다. 시간 내에 로그인을 승인하지 않으면 Hermes에서 시간 초과 오류가 발생합니다.

수정: hermes auth add xai-oauth(또는 hermes model)을 다시 실행하세요. 흐름이 새로 시작됩니다.

상태 불일치(CSRF 가능)​

Hermes는 인증 서버에서 반환된 state 값이 전송한 값과 일치하지 않음을 감지했습니다.

수정: 로그인을 다시 실행하세요. 지속되는 경우 OAuth 응답을 수정하는 프록시 또는 리디렉션을 확인하세요.

원격 서버에서 로그인​

SSH 또는 컨테이너 세션에서 Hermes는 브라우저를 여는 대신 인증 URL을 인쇄합니다. 루프백 콜백 리스너는 여전히 원격 호스트에서 127.0.0.1:56121을 바인딩합니다. 노트북의 브라우저는 SSH 로컬 전달 없이는 연결할 수 없습니다.

# Local machine, separate terminal:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Remote machine:
hermes auth add xai-oauth --no-browser

전체 연습(점프 박스, mosh/tmux, 포트 충돌): SSH를 통한 OAuth / 원격 호스트.

런타임 시 "xAI 자격 증명을 찾을 수 없음" 오류​

인증 저장소에는 xai-oauth 항목이 없으며 XAI_API_KEY이 설정되어 있지 않습니다. 아직 로그인하지 않았거나 자격 증명 파일이 삭제되었습니다.

수정: hermes model을 실행하고 xAI Grok OAuth 제공자를 선택하거나 hermes auth add xai-oauth을 실행하세요.

로그아웃​

저장된 모든 xAI Grok OAuth 자격 증명을 제거하려면:

hermes auth logout xai-oauth

이렇게 하면 auth.json의 싱글톤 OAuth 항목과 xai-oauth의 자격 증명 풀 행이 모두 지워집니다. 단일 풀 항목만 삭제하려면 hermes auth remove xai-oauth <index|id|label>을 사용하세요(이 항목을 보려면 hermes auth list xai-oauth을 실행하세요).

참조​