feat(xai): expose Grok X Search as a hosted tool surface (x_search)

[lidge-jun]

Why

Grok 페이지의 X Search를 OpenCodex에 새 툴 서페이스로 올리려고 한다. #2188 웹서치 사이드카와는 다른 선이다.

• #2188은 ChatGPT/Claude 호스트 web_search를 사이드카로 빌려 쓰는 선택 규칙이다.
• 이 이슈는 xAI가 서버에서 실행하는 x_search 를 Codex/라우티드 턴에 노출하는 조사+구현이다. 웹이 아니라 X(트위터) 포스트/유저/스레드를 검색한다.

Grok 페이지에서 하는 방법 (2026-08-20 문서)

공식 문서:

• Overview: https://docs.x.ai/developers/tools/overview
• X Search: https://docs.x.ai/developers/tools/x-search
• Web Search (형제, 이 이슈 범위 아님): https://docs.x.ai/developers/tools/web-search
• Streaming / include: https://docs.x.ai/developers/tools/streaming-and-sync
• Pricing: https://docs.x.ai/developers/pricing

xAI는 툴을 두 종류로 나눈다. Built-in (서버 실행) 과 Function calling (클라 실행). X Search는 built-in이다. 우리가 함수로 흉내 내서 X API를 두들기면 안 되고, https://api.x.ai/v1/responses에 도구를 실어 보내면 xAI가 실행한다.

최소 호출 (문서 그대로):

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "input": [{"role":"user","content":"What are people saying about xAI on X?"}],
    "tools": [{"type":"x_search"}]
  }'

OpenAI SDK도 된다. base_url=https://api.x.ai/v1, tools: [{ type: "x_search" }]. xAI SDK는 x_search(), Vercel AI SDK는 xai.tools.xSearch().

문서에 적힌 파라미터:

키	의미	제한
allowed_x_handles	이 핸들만	max 20, excluded와 동시 불가
excluded_x_handles	이 핸들 제외	max 20
from_date / to_date	기간	ISO8601 YYYY-MM-DD
enable_image_understanding	포스트 이미지 분석	토큰 과금 (view_image)
enable_video_understanding	포스트 비디오 분석	X Search만. 웹서치에는 없음

가격: x_search $5 / 1k calls. view_image / view_x_video는 별도 토큰. Web Search와 같은 호출당 가격이지만 인덱스가 다르다.

스트림에서 서버 아이템 타입은 x_search_call이다 (web_search_call과 형제). raw output을 받으려면 Chat Completions 쪽에 include: ["x_search_call_output"]. Responses 쪽 include 표는 문서가 web_search_call.action.sources만 자세히 적고 x_search는 덜 적혀 있다. 프로브에서 확인할 것.

옛 Live Search (search_parameters on Chat Completions)는 2026-01-12 deprecate / 410. 이 이슈는 그 경로를 부활시키지 않는다.

web_search와 x_search는 한 요청에 같이 넣을 수 있다. 문서 overview 예제가 둘을 나란히 넣는다. 그래도 제품 서페이스는 분리한다. 웹서치 사이드카가 X를 흉내 내면 안 된다.

지금 레포가 하는 일 / 안 하는 일

• src/responses/parser.ts buildTools는 OpenAI 호스트 툴로 web_search와 image_generation만 명시적으로 drop한다 (:230-231). x_search는 이름 있는 기타 툴로 떨어져 function으로 flatten된다 (:223-228). 서버 실행이어야 할 도구가 클라 function이 된다. 라우티드 Grok이어도 호스트 실행이 아니라 모델이 가짜 함수를 부른다.
• 호스트 web_search만 stash한다 (extractHostedWebSearch, :784-787). x_search extractor가 없다.
• src/adapters/openai-responses.ts stripInvalidItemIds prefix 표에 web_search_call: "ws_"는 있고 x_search_call은 없다 (:98-106). #2173이 tsc_/ctc_를 넣은 것과 같은 구멍이다. 업스트림이 x_search_call을 돌려주면 다음 턴 id가 잘리거나 item_이 된다.
• SPARK_SAFE_TOOL_TYPES는 function / web_search / web_search_preview만 (openai-responses.ts:295). x_search 없음.
• src/web-search/*는 ChatGPT/Claude 사이드카다. xAI x_search를 실행하지 않는다.
• Grok 인증은 있다. API 키, ocx login xai OAuth (src/oauth/xai.ts), Grok CLI ~/.grok/auth.json import. 문서 예제는 API 키 + api.x.ai. OAuth/Grok CLI/Build 경로가 같은 Responses 툴을 받는지는 라이브 프로브 필요.

구현 방향 (조사 후)

1. 라이브 프로브 (머지 전 필수).
   api.x.ai API 키로 위 curl을 실제로 보낸다. 확인: HTTP 200, x_search_call 아이템, citations, allowed_x_handles 동작, 스트림 이벤트 이름, id prefix. 그다음 OAuth/Grok CLI 경로를 같은 payload로 친다. 실패하면 그 인증 모드는 노출하지 않는다.
2. 새 툴 서페이스.
   Codex/클라에 x_search를 호스트 툴로 보이게 한다. web_search 사이드카로 접지 않는다. GUI/CLI에 X Search on/off, handle allow/deny, 날짜 범위를 둔다.
3. xAI Responses로 갈 때만 호스트 패스스루.
   라우트가 xAI Responses(또는 프로브된 Grok OAuth)일 때 tools: [{type:"x_search", ...}]를 그대로 보낸다. buildTools flatten을 이 타입만 예외로 뺀다. 다른 프로바이더로 라우트되면 호스트 실행이 불가능하니 숨기거나 disable. feat(sidecar): unify web-search and vision sidecar selection (auth slot + picker/probe filters) #2188 거름망과 같이 "로직+프로브된 active만".
4. 와이어.
   x_search_call id prefix를 stripInvalidItemIds / responses-field-backfill에 넣는다. 프로브가 준 prefix를 쓴다. 스트림에 x_search_call begin/end를 릴레이한다. include로 output을 받을지 정한다.
5. 과금/가드.
   호출당 $5. video/image understanding은 기본 끄고 옵트인. handle 필터는 문서대로 20개, allow/exclude 동시 금지.

하지 않는 것

• 옛 search_parameters Live Search.
• X 공식 API를 우리가 직접 두들기는 클라 function 구현.
• feat(sidecar): unify web-search and vision sidecar selection (auth slot + picker/probe filters) #2188 웹서치 사이드카 백엔드로 x_search를 몰래 넣기.
• 프로브 없이 Grok 피커에 켜 두기.

Acceptance

• 조사 코멘트로 프로브 결과 (API 키 / OAuth / CLI)와 실제 이벤트 타입·id prefix를 남긴다.
• xAI로 가는 턴에서 x_search가 호스트 툴로 나가고, function으로 flatten되지 않는다.
• 비-xAI 라우트에는 노출되지 않는다.
• 문서 파라미터(handles, dates, image/video understanding)가 설정 가능하고 동시 allow+exclude는 거절한다.

[coderabbitai]

🔗 Related PRs

#2145 - fix(responses): bridge routed tool_search through the Responses passthrough [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[lidge-jun]

xAI 문서에 x_search가 Responses 서버툴로 따로 있음. 웹서치랑 이름만 비슷한 형제가 아니라 인덱스가 X임. overview에 web_search랑 한 요청에 같이 넣는 예제도 있는데, 과금이 호출당 $5라서 사이드카로 몰래 태우면 사고남.

지금 레포는 호스트 툴을 web_search / image_generation만 알고 있음. src/responses/parser.ts buildTools가 그 둘만 drop하고 (:230-231), 이름 있는 기타 툴은 function으로 flatten함 (:223-228). x_search가 들어오면 서버 실행이어야 할 게 클라 함수가 됨. extractHostedWebSearch도 웹만 stash함 (:784-787). x_search extractor가 없음.

어댑터도 구멍임. src/adapters/openai-responses.ts stripInvalidItemIds에 web_search_call: "ws_"는 있고 x_search_call은 없음 (:98-106). responses-field-backfill.ts prefix 표도 마찬가지. 업스트림이 x_search_call을 주면 다음 턴 id가 잘리거나 item_이 됨. #2173이 tsc_/ctc_ 넣었던 그 패턴임.

인증은 API 키 + ocx login xai + Grok CLI ~/.grok/auth.json이 이미 있음. 문서 예제는 api.x.ai + Bearer 키임. OAuth/CLI 경로가 같은 Responses 툴을 받는지는 프로브 전엔 모름. 옛 Live Search search_parameters는 2026-01 deprecate라서 부활시키면 안 됨.

#2188이랑 선 갈라야 함. 저건 ChatGPT/Claude 호스트 web_search 사이드카 선택 규칙임. 이건 Codex/ocx에 Grok x_search를 새 툴 서페이스로 노출하는 거임. 웹서치 백엔드 목록에 grok를 넣는 걸로 퉁치면 안 됨.

우선순위 62 / 80

해결방안: 머지 전에 api.x.ai로 문서 curl을 실제로 쳐서 x_search_call 이벤트/id prefix/citations를 확인함. 그다음 OAuth/CLI를 같은 payload로 침. 되는 인증만 노출함. buildTools에서 x_search flatten 예외를 빼고, xAI Responses로 갈 때만 호스트 패스스루함. prefix 표에 x_search_call을 넣음. handle allow/exclude(max 20, 동시 금지), 날짜, image/video understanding은 기본 끄고 옵트인. 비-xAI 라우트엔 숨김.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

제품 방향 메모.

1순위는 웹서치처럼 xAI/Grok 페이지에 X Search를 툴로 노출하는 것. 라우트가 Grok이면 tools: [{ type: "x_search" }]를 모델이랑 같이 실어 보내고, 모델이 알아서 부르게 한다.

Codex/클라가 x_search 호스트 타입을 모르거나 그 페이지에 호스트 툴 토글을 못 올리면, 폴백은 "아무 X나 서치해" 넛지 + 호출 가능한 툴로 노출. 모델이 그 툴을 부르면 우리가 xAI x_search로 패스스루한다. 웹서치 사이드카(#2188)에 접지 않는다.

지금 Grok 페이지(gui/src/pages/Grok.tsx)는 모델 on/off만 있고 툴 토글은 없다. 웹서치는 대시보드 사이드카 설정에 있다. X Search는 그 사이드카가 아니라 xAI 페이지(또는 그 옆)에 새 툴 서페이스로 올리는 쪽이 맞다.

[lidge-jun]

범위 좁힘.

xAI OAuth는 이미 있다. X Search 툴은 그 xAI/Grok 페이지에만 붙인다. 대시보드 웹서치 사이드카, 다른 프로바이더 페이지, 글로벌 툴 목록에는 안 넣는다.

인증 경로를 API 키/CLI까지 넓혀서 프로브하는 작업은 이 이슈에서 빼 둔다. 그 페이지의 기존 OAuth 세션으로 x_search를 실어 보내는 쪽이 구현이다.