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, 이미지 생성, 비디오 생성 및 전사)에서도 재사용되므로 단일 로그인으로 이 네 가지를 모두 다룰 수 있습니다.
개요
| 품목 | 가치 |
|---|---|
| 제공자 ID | xai-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+
- 헤르메스 에이전트 설치
- 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를 참조하세요.
로그인 작동 방식
- Hermes는 브라우저에서
accounts.x.ai을 엽니다. - 로그인(또는 기존 세션 확인)하고 액세스를 승인합니다.
- xAI는 Hermes로 다시 리디렉션되고 토큰은
~/.hermes/auth.json에 저장됩니다. - 그 이후부터 Hermes는 백그라운드에서 액세스 토큰을 새로 고칩니다.
hermes auth remove xai-oauth하거나 xAI 계정 설정에서 액세스를 취소할 때까지 로그인 상태가 유지됩니다.
로그인 상태 확인
hermes doctor
``◆ Auth Providers` 섹션에는 `xai-oauth`을 포함하여 모든 공급자의 현재 상태가 표시됩니다.
## 스위칭 모델 \{#switching-models}
```bash
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_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 | 기본값; |
| 이미지 | grok-imagine-image-quality | 더 높은 충실도; |
| 비디오 | 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을 실행하세요).
참조
- SSH를 통한 OAuth / 원격 호스트 — Hermes가 브라우저와 다른 컴퓨터에 있는 경우 읽어야 합니다.
- AI 공급자 참조
- 환경변수
- 구성
- 음성 및 TTS