ChatGPT / Codex

codex 프로바이더는 매핑된 모델의 추론을 API 키 대신 ChatGPT / Codex 구독으로 라우팅합니다. Codex CLI가 이미 ~/.codex/auth.json에 기록한 자격 증명을 재사용하므로, 붙여넣을 것도 없고 토큰당 과금도 없습니다 — 요청은 사용자의 ChatGPT 계정으로 인증되고 codex CLI가 통신하는 것과 동일한 백엔드가 응답합니다.

이 페이지는 처음부터 끝까지의 설정입니다. 더 깊은 주제 페이지(노력 & 컨텍스트, 모델 디스커버리, 프로바이더)를 반복하는 대신 그쪽으로 링크합니다.

빠른 시작

코딩 에이전트가 대신 구성하도록 하세요. shunt add는 이 프로바이더의 설정 블루프린트를 출력합니다(오프라인·읽기 전용이며, 구성은 에이전트가 편집하고 이 명령은 절대 편집하지 않습니다):

shunt add upstream codex --print | claude

또는 아래의 수동 단계를 따르세요.

동작 방식

codex는 내장 kind = "responses" 프로바이더입니다: shunt는 Claude Code의 Anthropic Messages 요청을 OpenAI Responses API로 변환하여 ChatGPT 계정 Codex 백엔드로 보내고, 스트리밍된 응답을 다시 변환합니다. 이를 일반 OpenAI가 아닌 “Codex”로 만드는 세 가지 요소:

방언은 프로바이더 이름이 아니라 auth = "chatgpt_oauth"를 기준으로 결정됩니다.

Codex 계정을 풀로 사용하면 성공한 백엔드 응답의 x-codex-* 속도 제한 윈도우도 관리자 Pool health에 표시됩니다. 약 5시간 윈도우는 5h, 약 7일 윈도우는 7d에 표시되고, 지원하지 않는 일간·월간 윈도우는 무시됩니다. Codex에는 7d_oi에 대응하는 윈도우가 없습니다. 기록된 윈도우는 쿼터 인지 풀 선택에도 반영됩니다 — Codex 멀티 계정을 참고하세요.

1. 로그인

Codex CLI로 한 번 로그인하세요. shunt는 CLI가 기록한 파일을 읽고 갱신합니다 — Codex에 대해 자체 로그인을 실행하지는 않습니다.

codex login

이는 ~/.codex/auth.json을 생성합니다. 그 파일이 없거나, 토큰이 없거나, refresh 토큰이 사라졌으면, shunt는 codex login을 다시 실행하라는 authentication_error를 반환합니다.

2. 프로바이더 블록 (선택)

codex는 내장이므로 선언할 필요가 없습니다. 다음은 전체 기본값이며, 부분 테이블은 설정한 키만 오버라이드합니다(구성 맵은 깊은 병합됨):

[providers.codex]
kind = "responses"
base_url = "https://chatgpt.com/backend-api"   # shunt가 /codex/responses를 붙임
auth = "chatgpt_oauth"                          # ~/.codex/auth.json 읽기 + 자동 갱신
# effort = "high"                               # 선택적 기본 추론 노력 (§4)
# count_tokens = "tiktoken"                      # 기본값; "estimate"로 옵트아웃

일반적인 오버라이드: 모든 Codex 트래픽에 대한 기본 effort 고정, 또는 count_tokens = "estimate" 설정. api_key_env / api_key_header는 chatgpt_oauth에 적용되지 않습니다 — 자격 증명은 인증 파일에서 옵니다. 모든 키는 구성 레퍼런스를 참고하세요.

3. 모델을 codex로 라우팅

요청의 model id가 프로바이더를 선택합니다. 우선순위: 일치하는 [models.upstream_model] 항목 → 정확한 [[routes]] → [[route_prefixes]] → server.default_provider.

[[routes]]
model = "gpt-5.6-sol"        # Claude Code가 보내는 id (아래 §4 참고)
provider = "codex"
# upstream_model = "gpt-5.6-sol"   # 선택: 다른 슬러그를 업스트림으로 전달
# effort = "high"                  # 선택: 이 라우트의 effort 고정

upstream_model은 Claude Code가 보내는 id와 백엔드가 받는 슬러그가 다르도록 해줍니다 — 디스커버리 별칭의 메커니즘이자, Claude Code env를 건드리지 않고 실제 슬러그를 교체하는 방법입니다.

4. Claude Code에서 모델 선택

Claude Code의 /model 선택기는 claude/anthropic으로 시작하는 디스커버리 id만 존중하므로, 원시 gpt-* id는 두 경로 중 하나가 필요합니다 — 이들은 claude- 프리픽스를 기준으로 갈리며 겹치지 않습니다:

기본 경로 — 슬러그를 선택기에 직접 추가:

export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"

그 id가 바로 shunt가 라우팅하는 대상이므로, 일치하는 [models.upstream_model] 항목, [[routes]], 또는 [[route_prefixes]] 규칙으로 해석되어야 합니다. 이것이 권장 경로입니다 — 정확한 컨텍스트 윈도우까지 설정할 수 있는 유일한 경로이기도 합니다. 대신 여러 Codex 모델을 선택기에 자동 등록하려면, claude- 이름의 디스커버리 별칭을 사용하세요(200k 윈도우 트레이드오프를 감수).

서브에이전트를 Codex 슬러그에 올리기

서브에이전트는 메인 세션이 Claude에 머무는 동안 Codex 슬러그에서 실행될 수 있습니다. model: 프론트매터 필드는 임의의 문자열을 받아들입니다(내장 별칭만 받는 Agent/Task 도구의 model 파라미터와 달리). 기존 서브에이전트를 gpt-5.6-sol로 가리키게 하려면, .claude/agents/<name>.md를 편집하여 model:을 설정하세요:

---
name: researcher
description: Deep research agent.
model: gpt-5.6-sol        # 이전: sonnet (또는 없음 → 상속됨)
---

<the agent's system prompt — unchanged>

model 오버라이드 없이 스폰하세요(도구 파라미터가 프론트매터보다 우선). 해석 순서: CLAUDE_CODE_SUBAGENT_MODEL > 도구 model > 프론트매터 > inherit. 모든 서브에이전트를 하나의 슬러그로 강제하려면 export CLAUDE_CODE_SUBAGENT_MODEL="gpt-5.6-sol"을 설정하세요.

어느 쪽이든 슬러그는 일치하는 [models.upstream_model] 항목, [[routes]], 또는 [[route_prefixes]] 규칙을 통한 명시적 라우팅이 필요하며, 비-claude-이므로 CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1과 CLAUDE_CODE_MAX_CONTEXT_TOKENS를 따릅니다 — 윈도우는 id를 자동으로 따라갑니다.

티어 별칭을 Codex로 재매핑

커스텀 id 하나를 추가하는 대신, Claude Code의 내장 티어 별칭을 Codex 슬러그로 다시 가리키게 하면, 세션 전체의 티어 시스템이 ChatGPT 구독으로 해석됩니다(model-config env 변수).

2티어 설정 — haiku → gpt-5.6-luna, sonnet → gpt-5.6-sol:

export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5.6-luna"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5.6-sol"

# 더 나은 선택기 레이블 (_NAME/_DESCRIPTION 짝은 게이트웨이에서 동작)
export ANTHROPIC_DEFAULT_SONNET_MODEL_NAME="GPT-5.6-Sol"
export ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION="ChatGPT/Codex Sol via shunt"
export ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME="GPT-5.6-Luna"
export ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION="ChatGPT/Codex Luna via shunt (background tier)"

# shunt.toml — 해석된 두 id 모두 라우트가 필요
[[routes]]
model = "gpt-5.6-luna"
provider = "codex"

[[routes]]
model = "gpt-5.6-sol"
provider = "codex"

이제 /model에서 Sonnet을 선택하면 Codex를 통해 gpt-5.6-sol이 실행되고, 모든 백그라운드/haiku 작업은 gpt-5.6-luna가 실행합니다 — 해석된 id가 바로 shunt가 라우팅하는 대상이므로 ANTHROPIC_CUSTOM_MODEL_OPTION이 필요 없습니다.

5. 추론 노력

Claude Code의 일반 컨트롤(/effort, /model 슬라이더, --effort)로 노력을 설정하세요. shunt는 이를 Responses reasoning.effort로 매핑하며, max를 지원하지 않는 슬러그에 대해서는 max → xhigh로 접습니다(gpt-5.6 및 gpt-6 계열만 지원).

전체 우선순위와 effort 테이블: 노력 & 컨텍스트.

Fast 모드

Codex CLI의 /fast 토글은 모델이나 노력을 바꾸는 것이 아닙니다. Responses API의 최상위 필드 service_tier: "priority"를 보내며, 이 티어를 “Fast”(사용량이 늘어나는 대신 더 빠른 응답)라고 부릅니다. shunt는 같은 설정을 구성 키로 노출하며, effort와 똑같이 프로바이더 수준과 라우트 수준 모두에서 설정할 수 있습니다.

[[routes]]
model = "gpt-5.6-sol"
provider = "codex"
# service_tier = "priority"   # 선택: Codex의 "Fast" 모드 사용

허용 값은 fast(레거시 별칭으로, priority로 정규화됨), priority, flex, default(클라이언트 전용 센티널로, 와이어로는 절대 전송되지 않음)입니다. 기본값은 꺼짐이며 명시적으로 구성했을 때만 전송됩니다. effort와 마찬가지로 라우트 수준 값이 프로바이더 수준 기본값보다 우선합니다. 라우트를 명시적으로 default로 설정하면 프로바이더 수준의 priority/flex 티어를 상속하지 않고 해당 라우트만 제외됩니다. 전체 키 레퍼런스: 구성 레퍼런스.

Codex CLI 자체는 gpt-6-sol과 gpt-6-luna의 기본 티어를 Fast(priority)로 둡니다. 두 모델의 models.json 항목이 default_service_tier를 설정하기 때문입니다. 이는 백엔드가 적용하지 않는 클라이언트 측 기본값이므로, 이 가이드에서 구성하는 Claude Code 라우트에서는 service_tier = "fast"를 설정하지 않는 한 이 모델들이 표준 티어로 실행됩니다. shunt에 연결한 Codex CLI는 다릅니다. 그 엔드포인트는 요청을 그대로 전달하므로 CLI가 직접 보내는 티어가 유지됩니다.

실제로 와이어에 실린 티어는 Codex CLI의 x-codex-routing-hint 헤더로도 백엔드에 전달되며, 형식은 model=<upstream model>;tier=<tier>입니다(티어를 보내지 않으면 model=<upstream model>만). shunt는 Codex CLI와 똑같이 ChatGPT OAuth 경로에서만 이 헤더를 보냅니다. HTTP 요청에서는 요청 헤더로, WebSocket 전송에서는 핸드셰이크 헤더로 보냅니다. 프리픽스 라우트나 default_provider를 거치면 upstream 모델이 클라이언트가 보낸 model 문자열 그대로이므로, 헤더는 방어적으로 만들어집니다. 그럴듯한 슬러그(비어 있지 않고 128바이트 이하이며, ASCII 영문자·숫자와 - _ . : / +만 포함)일 때만 보내고, 그렇지 않으면 헤더만 빼고 요청은 그대로 보냅니다.

6. 컨텍스트 윈도우

Claude Code는 매핑된 id에 대해 컨텍스트 바를 고정된 200k로 크기 조정합니다. gpt-5.6-sol의 실제 윈도우는 372k이므로(gpt-5.5는 272k), 비-claude- id에 대해서는 올려주세요:

export CLAUDE_CODE_MAX_CONTEXT_TOKENS=372000

이 값은 전역이며(세션당 하나의 값), 실제 윈도우보다 크게 설정하면 prompt is too long 오버플로 churn을 유발합니다 — 매핑된 모델 중 가장 작은 실제 윈도우에 맞추세요. shunt는 그 오버플로를 다시 써서 Claude Code가 자동 압축(auto-compact)하고 재시도하도록 하지만, 각 왕복은 낭비되는 지연입니다. 자세한 내용, 실시간 검증된 경계, count_tokens 동작: 노력 & 컨텍스트.

전체 예시

shunt.toml:

[server]
bind = "127.0.0.1:3001"
default_provider = "anthropic"

[providers.codex]
effort = "high"     # 선택: 모든 Codex 트래픽에 high effort 고정

[[routes]]
model = "gpt-5.6-sol"
provider = "codex"

셸(shunt와 Claude Code 모두 이 설정으로 실행):

codex login                                          # 일회성
./target/release/shunt run                           # 게이트웨이 시작

export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"   # /model 선택기에 추가
export CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1            # effort 슬라이더가 Codex에 닿도록
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=372000         # gpt-5.6-sol의 실제 윈도우

/model에서 gpt-5.6-sol을 선택하세요. 세션의 나머지는 모두 여전히 변경 없이 Anthropic으로 흐르며, 오직 매핑된 모델의 추론만 ChatGPT/Codex 구독이 응답합니다.

웹 검색

Claude Code의 내장 웹 검색은 별도 설정 없이 Codex 경로에서 동작합니다. 웹 검색을 활성화하면 Claude Code가 호스티드 web_search_20250305 도구를 보내고, shunt는 이를 Responses API의 호스티드 web_search 도구로 등록합니다. 따라서 검색이 처리되지 않은 도구 호출로 되돌아오는 대신 백엔드에서 실제로 수행됩니다.

• 도메인 필터가 그대로 전달됩니다 — Claude Code의 allowed_domains / blocked_domains가 Responses web_search의 filters가 됩니다.
• codex(ChatGPT) 및 openai(스톡 Responses) 프로바이더에 적용됩니다.
• xAI / Grok 라우트는 지원하지 않습니다 — Grok의 Responses API는 함수 도구만 허용하므로 shunt가 호스티드 웹 검색 도구를 제거합니다. 웹 검색에는 codex 또는 openai 라우트를 사용하세요.

도구 검색

Claude Code의 도구 검색 — MCP / LSP 도구 스키마를 미뤄 두었다가 ToolSearch 도구로 필요할 때만 드러내어, 호출하지 않을 도구에 컨텍스트를 쓰지 않게 하는 기능 — 은 Codex 경로에서 동작합니다. 클라이언트 쪽에서 활성화하세요:

export ENABLE_TOOL_SEARCH=true

Claude Code는 base URL이 퍼스트파티 Anthropic 호스트가 아니면 낙관적 도구 검색을 비활성화하는데, shunt는 그에 해당하지 않습니다. 따라서 이 플래그가 없으면 첫 턴부터 모든 도구의 전체 스키마가 업스트림으로 전송되어 기능이 무의미해집니다(동작은 하지만 절약되는 것이 없습니다). 클라이언트 자체 규약은 프록시가 tool_reference 블록을 전달한다면 ENABLE_TOOL_SEARCH=true를 설정하라는 것이며, shunt는 이를 전달합니다.

이 플래그를 켜면 shunt는 이미 지원이 검증된 업스트림에 한해 도구 검색을 OpenAI Responses API 자체의 네이티브 클라이언트 실행 tool_search 프로토콜에 매핑하고, 그 외의 모든 곳에서는 #43 텍스트 shim을 유지합니다: Claude Code의 ToolSearch 도구는 tool_search(execution: "client") 도구가 되고, 그 tool_use는 tool_search_call이 되며, tool_reference 결과는 로드된 도구들의 전체 스키마를 구조화된 JSON으로 담아 input 끝에 덧붙는 tool_search_output 항목이 됩니다. 이 차이가 중요한 이유는, 대안 방식 — 드러난 도구의 스키마를 요청의 tools 배열에 다시 접어 넣는 방식 — 이 드러날 때마다 캐시된 프롬프트 프리픽스를 무효화하기 때문입니다: tools는 그 캐시 가능한 프리픽스의 일부이고 shunt는 매 턴 클라이언트 히스토리로부터 이를 다시 도출하므로, 배열이 커질수록 백엔드가 도구 경계 이후의 대화를 처음부터 다시 처리하게 됩니다. 네이티브 프로토콜은 append-only인 input 히스토리를 사용해 tools를 건드리지 않으므로, 드러날 때마다 캐시 프리픽스가 그대로 유지됩니다.

• codex와 openai 내장 프로바이더의 기본(네이티브) 동작을 쓰는 데는 shunt.toml 변경이 필요 없습니다 — 순수하게 ENABLE_TOOL_SEARCH 수준의 Claude Code 환경 변수입니다.
• kind = "responses" 프로바이더 전반에 적용됩니다. 다만 어떤 프로바이더가 기본으로 네이티브를 쓰는지, 아니면 shim을 쓰는지는 업스트림 호스트에 달려 있습니다 — 아래 네이티브 프로토콜을 참고하세요.
• 미루지 않는 도구(및 위의 호스티드 web_search 도구)는 항상 전달됩니다. 점진적으로 드러나는 것은 미룰 수 있는 도구뿐입니다.

네이티브 프로토콜

요구 사항 — 지원되지 않는 조합은 오류 없이 조용히 #43 텍스트 shim으로 폴백합니다. 이 shim은 아직 드러나지 않은 지연 도구는 여전히 tools에서 제외하지만, Claude Code가 도구 하나를 드러내면 그 전체 스키마를 tool_reference 텍스트로 렌더링하는 동시에 그 도구를 tools에 다시 추가해 모델이 호출할 수 있게 합니다 — 그 시점부터 스키마가 두 번 전송되고, 매 노출마다 위에서 설명한 캐시 무효화 비용을 치릅니다:

• 업스트림은 스톡 OpenAI 또는 ChatGPT/Codex 계열 Responses 백엔드여야 합니다. xAI / Grok 라우트는 항상 shim을 유지합니다.
• 라우팅되는 모델은 gpt-5.4 이상(gpt-5.4, gpt-5.5, 또는 gpt-5.6 패밀리)이어야 합니다. 정확한 슬러그 gpt-6-astra, gpt-6-sol, gpt-6-luna, gpt-6.1-sol도 대상입니다. 이전 슬러그(gpt-5.2 이하)는 tool_search와 무관하게 shim을 유지합니다.
• Claude Code 쪽에서는 여전히 ENABLE_TOOL_SEARCH=true가 필요합니다 — 이 플래그는 shunt가 그 기능을 업스트림으로 어떻게 변환하는지만 바꿀 뿐, Claude Code가 애초에 도구를 지연시키는지 여부는 바꾸지 않습니다.

tool_search는 [providers.<name>] 아래에서 세 가지 상태를 갖는 설정입니다. 미설정(기본값, “auto”) 상태에서는 이미 프로토콜 지원이 검증된 호스트 — ChatGPT/Codex 백엔드(내장 codex 프로바이더)와 api.openai.com(내장 openai 프로바이더) — 에서만 네이티브로 해석되고, LiteLLM·vLLM·OpenRouter·자체 호스팅 프록시를 가리키는 커스텀 kind = "responses" 프로바이더를 포함한 그 외 모든 OpenAI 호환 엔드포인트에서는 텍스트 shim으로 해석됩니다: 대부분의 서드파티 Responses 백엔드는 tool_search 항목을 구현하지 않으므로, 그런 곳에서 네이티브를 자동으로 켜면 부드럽게 폴백하는 대신 턴 자체가 실패할 수 있습니다. 네이티브 형태는 2026-07-13에 gpt-5.6에서 ChatGPT/Codex 백엔드를 대상으로 라이브 프로브로 검증되었으며(pleaseai/shunt#86), tool_search는 gpt-5.4+ 모델에 대해 공개 OpenAI Responses API 문서에도 실려 있습니다.

프로토콜을 구현하는 것을 확인한 커스텀 엔드포인트를 네이티브 경로에 옵트인하려면 tool_search = true로 설정하세요 — 위의 계열·모델 요구 사항은 여전히 적용됩니다:

[providers.my-litellm]
kind = "responses"
base_url = "https://litellm.internal/v1"
tool_search = true

기본적으로(또는 옵트인으로) 네이티브 경로를 쓰게 될 프로바이더에서 텍스트 shim을 강제하려면 tool_search = false로 설정하세요:

[providers.codex]
tool_search = false

문제 해결

더 많은 내용은 전체 문제 해결 레퍼런스를 참고하세요.