Codex 연결 가이드

0. 한 줄 결론

플랫폼은 OpenAI Responses API 엔드포인트 POST /v1/responses를 구현했으며, 구현 시 명확히 Codex 요구에 맞게 설계되었습니다(스트리밍 SSE 이벤트 시퀀스, function 도구 호출, store:false 무상태 호환). 따라서 Codex CLI에는 두 가지 연결 방법이 있습니다:

1. 직접 연결(권장): ~/.codex/config.toml에 wire_api = "responses"를 설정하고, 직접 /v1/responses를 사용합니다;
2. cc-switch: 그래픽 도구로 한 번의 클릭으로 Codex / Claude Code 등의 provider를 전환합니다.

두 방식의 과금은 완전히 동일합니다(동일한 사전 차감 → 라우팅 → 정산 → 원장 파이프라인).

1. 사전 조건

2. 플랫폼 측 기능 및 한계(/v1/responses)

• 엔드포인트: POST https://routeall.ai/v1/responses
• 인증: Authorization: Bearer sk-ra-...

2.1 지원 기능(Codex 호환)

2.2 한계(무상태 텍스트 서브셋)

2.3 과금 및 오류

• 과금: /v1/chat/completions와 완전히 동일한 파이프라인, 실제 charge는 동등; 응답 헤더 X-RouteAll-Charge-Credit는 소매 과금액(원가 아님).
• 오류 봉투: { "error": { "message", "type", "code", "param" } }; HTTP 상태: 401(키 없음/잘못됨), 402(잔액 부족), 429(속도 제한), 400(매개변수 오류), 503(업스트림 전체 불가).

3. 방법 1: Codex CLI 직접 연결(Responses API, 권장)

3.1 ~/.codex/config.toml 설정

model = "deepseek-v4-pro"           # 기본 모델, 스토어의 정식 명칭으로 변경
model_provider = "routeall"

[model_providers.routeall]
name = "RouteAll"
base_url = "https://routeall.ai/v1" # 플랫폼 OpenAI 호환 base URL(/responses 제외)
env_key = "ROUTEALL_API_KEY"
wire_api = "responses"              # responses = /v1/responses 사용(권장)

3.2 환경 변수 설정

# Linux / macOS
export ROUTEALL_API_KEY="sk-ra-당신의KEY"

# Windows PowerShell
# $env:ROUTEALL_API_KEY = "sk-ra-당신의KEY"

3.3 실행

codex

3.4 임시 모델 전환

codex --model Codex-haiku-4-5 "이 모듈을 리팩토링해줘"
codex --model deepseek-v4-flash "이 정규식을 설명해줘"

3.5 wire_api 정보

참고: 게이트웨이 api. 서브도메인은 현재 외부에 공개되지 않았습니다(서버 PUBLIC_API_DOMAIN=api.localhost 내부용); /v1/*은 메인 사이트 routeall.ai에서 직접 제공되므로 base_url은 https://routeall.ai/v1을 사용합니다.

4. 방법 2: cc-switch(그래픽 원클릭 전환)

cc-switch는 오픈소스 공급자 전환 도구(farion1231/cc-switch)로, Codex / Claude Code / OpenCode / Gemini 등의 provider 설정을 관리하고 클릭 한 번으로 전환할 수 있습니다.

4.1 설치

GitHub farion1231/cc-switch → Releases에서 해당 시스템 설치 패키지 다운로드(Windows / macOS / Linux).

4.2 새 공급자 추가

1. cc-switch를 열고 Codex 탭으로 이동 → 「새 공급자 추가」;
2. 입력:
   • 공급자 이름: RouteAll(임의)
   • API Host / Base URL: https://routeall.ai/v1
   • API Key: sk-ra-당신의KEY
   • 모델 목록: 플랫폼 정식 모델명(예: deepseek-v4-pro, Codex-haiku-4-5, 여러 줄 가능)
3. 저장.

4.3 적용 및 전환

RouteAll 선택 → 「전환 / 활성화」. cc-switch가 provider 설정을 ~/.codex/config.toml에 기록합니다(방법 1의 설정과 동일). 이후 정상적으로 codex를 실행하면 됩니다.

참고: cc-switch 일부 버전은 Codex의 프로토콜을 /v1/chat/completions(즉 wire_api = "chat")로 변경할 수 있습니다. 플랫폼은 두 경로 모두 지원합니다(B15에서 도구형 클라이언트의 chat 400 문제 수정). 만약 프로토콜 선택이 가능한 버전이라면, Responses를 선택하는 것이 네이티브에 더 적합합니다.

5. 검증

5.1 사용 가능한 모델 목록 가져오기(목록 기준, 모델명 추측 금지)

curl https://routeall.ai/v1/models \
  -H "Authorization: Bearer sk-ra-당신의KEY"
# 또는 공개 디렉터리(인증 불필요, 채널이 있는 모델만 나열)
curl https://routeall.ai/v1/public/models

5.2 비스트리밍(연결 확인)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-당신의KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "안녕, 한 문장으로 너를 소개해줘",
    "max_output_tokens": 200
  }'

성공 시 Responses 형식(output[].content[].output_text + output_text + usage)이 반환됩니다.

5.3 스트리밍(Codex 실제 형태)

curl -N https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-당신의KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "짧은 농담 하나 해줘",
    "stream": true
  }'

이벤트 순서: response.created → output_item.added → output_text.delta ×N → output_item.done → response.completed.

5.4 도구 호출(에이전트 루프 형태)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-당신의KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": [{"role": "user", "content": "17*23을 계산해줘"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "calculator",
        "description": "사칙연산 수행",
        "parameters": {
          "type": "object",
          "properties": { "expr": { "type": "string" } }
        }
      }
    }],
    "tool_choice": "auto"
  }'

output에 type: "function_call" 항목(call_id / name / arguments)이 포함되며, 이후 function_call_output 항목을 다시 보내 결과를 주입하고 멀티 턴을 계속할 수 있습니다.

6. 문제 해결

7. 과금 및 보안 안내

• 과금 기준: 모델 공식 가격 × 사용자 그룹 배율; 스트리밍은 실제 usage 기준 정산; 캐시 적중 시 전액 청구(B12 전략, 캐시 차익은 플랫폼 귀속, 고객 charge는 변함 없음).
• 과금 가시성: 응답 헤더 X-RouteAll-Charge-Credit(소매 금액); cost/margin은 사용자 응답에 절대 포함되지 않음(INV-8).
• 키 보안: sk-ra-는 sha256만 저장, 백오피스에서 확인 불가; 절대 클라이언트나 저장소에 포함하지 마세요.
• 작은 모델(curl 검증)로 먼저 연결을 확인한 후, Codex / 긴 작업으로 전환하는 것을 권장합니다.