xai provider plugin이 번들로 제공됩니다.
권장 방식은 자격을 갖춘 SuperGrok 또는 X Premium 구독으로 Grok OAuth를 사용하는 것입니다.
Gateway, 구성, 라우팅, 도구는 로컬에 유지되며, Grok 요청만
xAI의 API로 전송됩니다.
OAuth에는 xAI API 키나 Grok Build 앱이 필요하지 않습니다. OpenClaw가 xAI의 공유
OAuth 클라이언트를 사용하므로 xAI가 동의 화면에 Grok Build를
표시할 수는 있습니다.
설정
1
새 설치
데몬 설치와 함께 온보딩을 실행한 다음, 모델/인증 단계에서 xAI/Grok OAuth를
선택하십시오.VPS 또는 SSH 환경에서는 xAI OAuth를 직접 선택하십시오. 기기 코드
검증을 사용하므로 localhost 콜백이 필요하지 않습니다.
2
기존 설치
xAI에만 로그인하십시오. Grok을 연결하기 위해 전체 온보딩을 다시 실행하지 마십시오.Grok을 기본 모델로 별도로 적용하십시오.Gateway, 데몬, 채널, 작업 공간 또는 기타 설정 항목을 의도적으로 변경하려는
경우에만 전체 온보딩을 다시 실행하십시오.
3
API 키 방식
xAI Console 키 및 키 기반 provider 구성이 필요한 미디어 기능에서도
API 키 설정을 계속 사용할 수 있습니다.
4
모델 선택
OpenClaw는 번들 xAI 전송 방식으로 xAI Responses API를 사용합니다.
openclaw models auth login --provider xai --method oauth 또는
--method api-key의 동일한 자격 증명은 web_search(provider ID grok), x_search,
code_execution, 음성/전사 및 xAI 이미지/동영상 생성에도 사용됩니다.
plugins.entries.xai.config.webSearch.apiKey에 xAI 키를 저장하면
번들 xAI 모델 provider도 이를 대체 수단으로 재사용합니다.OAuth 문제 해결
-
SSH, Docker, VPS 또는 기타 원격 설정에서는
openclaw models auth login --provider xai --method oauth을 사용하십시오. localhost 콜백이 아니라 기기 코드 검증을 사용합니다. -
로그인에 성공했지만 Grok이 기본 모델이 아닌 경우
openclaw models set xai/grok-4.3을 실행하십시오. -
저장된 xAI 인증 프로필을 확인하십시오.
- OAuth API 토큰을 받을 수 있는 계정은 xAI가 결정합니다. 계정이 자격을 충족하지 않으면 API 키 방식을 사용하거나 xAI 측에서 구독을 확인하십시오.
기본 제공 카탈로그
모델 선택기에서 선택할 수 있는 ID입니다. 기존 구성을 위해 plugin은 이전 Grok 3, Grok 4, Grok 4 Fast, Grok 4.1 Fast 및 Grok Code ID도 계속 해석합니다. 레거시 호환성 및 이동형 별칭을 참조하십시오.기능 지원 범위
번들 plugin은 지원되는 xAI API를 OpenClaw의 공유 provider 및 도구 계약에 매핑합니다. 공유 계약에 맞지 않는 기능은 아래 또는 알려진 제한 사항에 나열되어 있습니다.OpenClaw는 미디어 생성 및 일괄 전사에 xAI의 REST 이미지/동영상/TTS/STT API를,
실시간 음성 통화 전사에 xAI의 스트리밍 STT WebSocket을,
Talk 실시간 세션에 xAI의 Grok Voice Agent WebSocket을,
채팅, 검색 및 코드 실행 도구에 Responses API를 사용합니다.
레거시 고속 모드 호환성
/fast on 또는 agents.defaults.models["xai/<model>"].params.fastMode: true은
이전 xAI 구성을 계속 다음과 같이 다시 작성합니다. 이러한 대상 ID는
호환성을 위해서만 유지됩니다. 새 구성에는 현재 선택 가능한 모델을
사용하십시오.
레거시 호환성 및 이동형 별칭
이전 별칭은 다음과 같이 정규화됩니다.
날짜가 지정된 0309 ID가 선택 가능한 카탈로그 항목입니다. OpenClaw는 그 밖의
모든 현재 Grok 4.20 별칭을 그대로 전송하여 xAI가 안정, 최신,
베타, 실험 및 날짜 지정 별칭의 의미를 계속 제어하도록 합니다. 전역
grok-latest 별칭도
그대로 보존됩니다.
xAI는 다음의 정확한 ID를 폐기했습니다. OpenClaw는 출시된 구성을 위해 이를 숨겨진 호환성
행으로 유지하며, 현재 리디렉션 대상의 제한 및 가격을 적용합니다.
openclaw doctor --fix은 저장된 xAI 서버 도구 기본값과
폐기된 품질 이미지 슬러그를 업데이트하고, 오래된 생성 카탈로그 행을 제거하며,
활성 4.20 행의 오래된 컨텍스트 메타데이터를 복구합니다. 활성 4.20
beta-latest 별칭을 날짜가 지정된 스냅샷에 고정하지는 않습니다.
기능
웹 검색
웹 검색
번들
grok 웹 검색 provider는 xAI OAuth를 우선 사용한 후,
XAI_API_KEY 또는 plugin 웹 검색 키를 대체 수단으로 사용합니다.동영상 생성
동영상 생성
번들
xai plugin은 공유
video_generate 도구를 통해 동영상 생성을 등록합니다.- 기본 모델:
xai/grok-imagine-video - 추가 모델:
xai/grok-imagine-video-1.5 - 클래식 모드: 텍스트-동영상, 이미지-동영상, 참조 이미지 생성, 원격 동영상 편집 및 원격 동영상 확장
- Video 1.5 모드: 정확히 하나의 첫 프레임 이미지를 사용하는 이미지-동영상만 지원
- 화면 비율:
1:1,16:9,9:16,4:3,3:4,3:2,2:3; 생략하면 클래식 및 Video 1.5 이미지-동영상은 소스 이미지 비율을 상속합니다. - 해상도: 클래식
480P/720P; Video 1.5는1080P도 지원하며, 모든 생성 모드의 기본값은480P입니다. - 길이: 생성/이미지-동영상은 1-15초, 클래식
reference_image역할을 사용할 때는 1-10초, 클래식 확장은 2-10초 - 참조 이미지 생성: 제공하는 모든 이미지에 대해
imageRoles을reference_image으로 설정하십시오. xAI는 이러한 이미지를 최대 7개까지 허용합니다. - 동영상 편집/확장은 입력 동영상의 화면 비율과 해상도를 상속하며, 이러한 작업에는 기하 구조 재정의를 사용할 수 없습니다.
- 기본 작업 제한 시간:
video_generate.timeoutMs또는agents.defaults.videoGenerationModel.timeoutMs이 설정되지 않은 경우 600초
grok-imagine-video-1.5-preview 및
grok-imagine-video-1.5-2026-05-30 식별자도 인식합니다. OpenClaw는
선택한 식별자를 변경하지 않고 전달하지만 동일한 이미지 전용 검증을 적용합니다.xAI를 기본 동영상 provider로 사용하려면 다음과 같이 설정하십시오.공유 도구 매개변수, provider 선택 및 장애 조치 동작은
동영상 생성을 참조하십시오.
이미지 생성
이미지 생성
번들
xai plugin은 공유
image_generate 도구를 통해 이미지 생성을 등록합니다.- 기본 이미지 모델:
xai/grok-imagine-image - 추가 모델:
xai/grok-imagine-image-quality - 모드: 텍스트-이미지 생성 및 참조 이미지 편집
- 참조 입력:
image1개 또는images최대 3개 - 가로세로 비율:
1:1,16:9,9:16,4:3,3:4,3:2,2:3,2:1,1:2,19.5:9,9:19.5,20:9,9:20 - 해상도:
1K,2K - 개수: 최대 4개 이미지
- 기본 작업 제한 시간:
image_generate.timeoutMs또는agents.defaults.imageGenerationModel.timeoutMs이 설정되지 않은 경우 600초
b64_json 이미지 응답을 요청합니다. 로컬
참조 이미지는 데이터 URL로 변환되며, 원격 http(s) 참조는
변경 없이 전달됩니다.xAI를 기본 이미지 제공자로 사용하려면 다음과 같이 설정하십시오.xAI는
quality, mask, user 및 auto 가로세로 비율도 문서화합니다.
현재 OpenClaw는 제공자 간에 공통으로 지원되는 이미지 제어만 전달하며,
이러한 xAI 전용 설정은 image_generate을 통해 노출되지 않습니다.텍스트 음성 변환
텍스트 음성 변환
번들로 제공되는
xai Plugin은 공유 tts
제공자 인터페이스를 통해 텍스트 음성 변환을 등록합니다.- 음성: xAI에서 인증을 거쳐 가져오는 실시간 카탈로그이며, 다음 명령으로 나열할 수 있습니다.
openclaw infer tts voices --provider xai - 오프라인 대체 음성:
ara,eve,leo,rex,sal - 기본 음성:
eve - 계정의 사용자 지정 음성 ID는 기본 제공 카탈로그 응답에 없더라도 전달됩니다.
- 형식:
mp3,wav,pcm,mulaw,alaw - 언어: BCP-47 코드 또는
auto - 속도: 제공자 네이티브 속도 재정의
- 네이티브 Opus 음성 메시지 형식은 지원되지 않습니다.
OpenClaw는 버퍼링된 합성에 xAI의 배치
/v1/tts 엔드포인트를 사용하고,
인증된 /v1/tts/voices 카탈로그 검색과 스트리밍 합성에 네이티브
wss://api.x.ai/v1/tts을 사용합니다. 스트리밍은 네이티브 api.x.ai
호스트로 제한되므로 사용자 지정 baseUrl 값은 이 경로에서 거부됩니다.
기존 언어, 음성, 코덱 및 속도 제어를 사용하며, 샘플 레이트와 비트 레이트에는
xAI 기본값이 적용됩니다. 오디오 파일 합성은 구성된 모든 코덱을 따릅니다.
xAI의 원시 코덱에는 코덱/레이트 메타데이터가 포함되지 않으므로 음성 메시지
대상은 스트리밍 및 버퍼링된 대체 처리에 MP3를 사용합니다. 스트림은
text.delta를 보낸 다음
text.done을 보내고, audio.delta, audio.done 또는 error을 수신하며,
각 오디오 청크마다 갱신되는 유휴 timeoutMs을 적용합니다. 이는 실시간
음성 세션과 별개입니다. xAI의 스트리밍 TTS API 계약을 참조하십시오.음성 텍스트 변환
음성 텍스트 변환
번들로 제공되는 언어는 공유 오디오 미디어 구성 또는 호출별 전사 요청을 통해 지정할 수
있습니다. 공유 OpenClaw 인터페이스는 프롬프트 힌트를 허용하지만, 현재 공개
xAI 엔드포인트에 매핑되는 항목은 파일과 언어뿐이므로 xAI REST STT 통합은
이 두 항목만 전달합니다.
xai Plugin은 OpenClaw의 미디어 이해
전사 인터페이스를 통해 배치 음성 텍스트 변환을 등록합니다.- 엔드포인트: xAI REST
/v1/stt - 입력 경로: 멀티파트 오디오 파일 업로드
- 모델 선택: xAI가 내부적으로 전사 모델을 선택하며, 엔드포인트에는 모델 선택기가 없습니다.
- Discord 음성 채널 세그먼트와 채널 오디오 첨부 파일을 포함하여
수신 오디오 전사가
tools.media.audio을 읽는 모든 곳에서 사용됩니다.
스트리밍 음성 텍스트 변환
스트리밍 음성 텍스트 변환
번들로 제공되는 제공자가 소유하는 구성은
xai Plugin은 실시간 음성 통화 오디오를 위한
실시간 전사 제공자도 등록합니다.- 엔드포인트: xAI WebSocket
wss://api.x.ai/v1/stt - 기본 인코딩:
mulaw - 기본 샘플 레이트:
8000 - 기본 발화 종료 감지:
800ms - 중간 전사: 기본적으로 활성화됨
plugins.entries.voice-call.config.streaming.providers.xai 아래에 있습니다. 지원되는
키는 apiKey, baseUrl, sampleRate, encoding (pcm, mulaw 또는
alaw), interimResults, endpointingMs 및 language입니다.이 스트리밍 제공자는 Voice Call의 실시간 전사 경로용입니다.
Discord 음성은 짧은 세그먼트를 녹음하고 대신 배치
tools.media.audio 전사 경로를 사용합니다.실시간 음성(Talk)
실시간 음성(Talk)
번들로 제공되는 Voice Call 또는 공유 실시간 선택기가 동일한 제공자 맵을 재사용하는 경우,
제공자가 소유하는 구성은
xai Plugin은 공유 registerRealtimeVoiceProvider 계약을 통해
Talk 모드용 Grok Voice Agent 실시간 세션을 등록합니다.- 엔드포인트:
wss://api.x.ai/v1/realtime?model=<voice-model> - 기본 모델:
grok-voice-latest - 기본 음성:
eve - 전송 방식:
gateway-relay(iOS, Android 및 Control UI 릴레이 경로) - 오디오: PCM16 24 kHz 또는 G.711 µ-law 8 kHz
- 끼어들기: xAI 서버 VAD가 응답을 중단하며, OpenClaw는 대기 중인 재생을 비우고 재생되지 않은 제공자 기록을 잘라냅니다.
plugins.entries.voice-call.config.realtime.providers.xai에서도
확인됩니다. 지원되는 키는
apiKey, baseUrl, model, voice, vadThreshold, silenceDurationMs,
prefixPaddingMs, reasoningEffort 및 sessionResumption입니다.
reasoningEffort은 xAI Voice Agent API에 맞게 high 또는 none만 허용합니다.xAI의 서버 VAD는 항상 응답을 생성하고 오디오 중단을 처리합니다.
consultRouting: "provider-direct"을 사용하십시오. 강제 전사 라우팅 및
입력 오디오 중단 비활성화는 xAI Voice Agent 프로토콜에서 지원되지 않습니다.xAI OAuth 또는
XAI_API_KEY으로 실시간 음성을 인증할 수 있습니다. 브라우저가
소유하는 WebRTC는 아직 이 제공자 인터페이스에 포함되지 않습니다. 네이티브 Node
또는 Control UI 릴레이 경로에서 gateway-relay Talk를 사용하십시오.sessionResumption의 기본값은 false입니다. true로 설정하면 OpenClaw는
재연결 후 동일한 대화를 재개할 수 있을 만큼의 세션 상태를 유지하도록 xAI에
요청한 다음, 반환된 대화 ID로 다시 연결합니다. 제공자 측 재생/보존을 허용할 수
없다면 비활성화된 상태로 두십시오. 그러면 중단된 소켓은 조용히 새 대화를 시작하지
않고 안전하게 실패합니다.x_search 구성
x_search 구성
번들로 제공되는 xAI Plugin은 Grok을 통해 X(이전의 Twitter) 콘텐츠를 검색하기 위한
OpenClaw 도구로
x_search을 노출합니다.구성 경로: plugins.entries.xai.config.xSearch코드 실행 구성
코드 실행 구성
번들로 제공되는 xAI Plugin은 xAI의 샌드박스 환경에서 원격 코드를 실행하기 위한
OpenClaw 도구로
code_execution을 노출합니다.구성 경로: plugins.entries.xai.config.codeExecution이는 로컬
exec이 아니라 원격 xAI 샌드박스 실행입니다.알려진 제한 사항
알려진 제한 사항
- xAI 인증에는 API 키, 환경 변수, 플러그인 구성 폴백 또는 적격 xAI 계정의 OAuth를 사용할 수 있습니다. OAuth는 localhost 콜백 없이 기기 코드 검증을 사용합니다. OAuth API 토큰을 받을 수 있는 계정은 xAI가 결정하며, OpenClaw에는 Grok Build 앱이 필요하지 않더라도 동의 페이지에 Grok Build가 표시될 수 있습니다.
- OpenClaw는 현재 xAI 다중 에이전트 모델 제품군을 제공하지 않습니다. xAI는 Responses API를 통해 이러한 모델을 제공하지만, 해당 모델은 OpenClaw의 공유 에이전트 루프에서 사용하는 클라이언트 측 도구 또는 사용자 지정 도구를 허용하지 않습니다. xAI 다중 에이전트 제한 사항을 참조하십시오.
- 현재 xAI 실시간 음성은 게이트웨이 릴레이 Talk 전송만 제공합니다. 브라우저가 소유하는 제공자 WebSocket 세션은 아직 Control UI에 연결되지 않았습니다.
- xAI 이미지
quality, 이미지mask및 추가 네이티브 전용 종횡비는 공유image_generate도구에 상응하는 제공자 간 제어 기능이 마련될 때까지 제공되지 않습니다.
고급 참고 사항
고급 참고 사항
- OpenClaw는 공유 러너 경로에서 xAI 전용 도구 스키마 및 도구 호출 호환성 수정 사항을 자동으로 적용합니다.
- 네이티브 xAI 요청은 기본적으로
tool_stream: true합니다. 비활성화하려면agents.defaults.models["xai/<model>"].params.tool_stream을false(으)로 설정하십시오. - 번들 xAI 래퍼는 네이티브 xAI 요청을 보내기 전에 지원되지 않는 contains-count 스키마 경계와
지원되지 않는 추론 노력 수준 페이로드 키를 제거합니다.
Grok 4.5는 낮음, 중간, 높음 노력 수준을 지원합니다(기본값: 높음).
Grok 4.3은 없음, 낮음, 중간, 높음 노력 수준을 지원합니다(기본값: 낮음).
추론을 지원하는 다른 xAI 모델은 구성 가능한 노력 수준 제어 기능을 제공하지 않지만,
후속 턴에서 이전에 암호화된 추론을 재생할 수 있도록
여전히
include: ["reasoning.encrypted_content"]을 요청합니다. web_search,x_search및code_execution은 OpenClaw 도구로 제공됩니다. OpenClaw는 모든 채팅 턴에 모든 네이티브 도구를 연결하는 대신, 각 도구에 필요한 특정 xAI 내장 기능만 해당 도구의 요청에 연결합니다.- Grok
web_search은plugins.entries.xai.config.webSearch.baseUrl을 읽습니다.x_search은plugins.entries.xai.config.xSearch.baseUrl을 읽은 다음, Grok 웹 검색 기본 URL로 폴백합니다. x_search및code_execution은 핵심 모델 런타임에 하드코딩되지 않고 번들 xAI 플러그인이 소유합니다.code_execution은 로컬exec이 아니라 원격 xAI 샌드박스 실행입니다.
라이브 테스트
xAI 미디어 경로에는 단위 테스트와 선택형 라이브 제품군이 적용됩니다. 라이브 프로브를 실행하기 전에 프로세스 환경에서XAI_API_KEY을 내보내십시오.
관련 항목
모델 선택
제공자, 모델 참조 및 장애 조치 동작을 선택합니다.
동영상 생성
공유 동영상 도구 매개변수 및 제공자 선택입니다.
모든 제공자
더 광범위한 제공자 개요입니다.
문제 해결
일반적인 문제와 해결 방법입니다.