본문으로 건너뛰기
PleumRouter
시작하기

Codex CLI

OpenAI의 터미널 코딩 에이전트 Codex CLI를 PleumRouter의 Responses API로 연결합니다.

Codex CLI는 터미널에서 코드를 읽고 수정하고 명령을 실행하는 OpenAI의 코딩 에이전트입니다. Codex는 Chat Completions 경로를 없애고 Responses API(/v1/responses)만 쓰기 때문에, 설정에 wire_api = "responses"가 필요합니다. 데스크톱 앱은 Codex Desktop을 보세요.

빠른 시작#

  1. Codex CLI 설치

    이미 설치했다면 건너뛰세요.

    Terminal
    npm i -g @openai/codex
codex --version

  2. API 키 발급

    대시보드의 API 키 페이지에서 plm_로 시작하는 키를 만들어 복사하세요. 처음에는 일·주·월 예산을 함께 걸어 두는 것을 권장합니다.

  3. PleumRouter로 연결

    세 가지 중 하나만 고르세요.

    pleum launch

    `~/.codex`를 건드리지 않고 이번 실행에만 임시 설정을 씁니다.

    npm i -g pleumrouter
pleum login            # sign in with the browser
pleum launch codex     # applies the PleumRouter provider for this run only

  4. 실행하고 확인

    프롬프트 한 턴에 응답이 오면 연결 성공입니다. 401이면 키, 404면 base_url의 /v1을 확인하세요.

    Terminal
    cd your-project
codex

Codex CLI에서 PleumRouter를 쓰는 이유#

  • 선불 크레딧으로 사용한 만큼만 결제합니다. 도구 제작사의 구독과 별개로 크레딧이 차감됩니다.
  • 키마다 예산과 한도를 겁니다. API 키별 일·주·월 예산과 모델 허용 목록, 팀 예산으로 에이전트의 비용을 관리합니다.
  • 한 키로 여러 모델을 씁니다. Claude·GPT·Gemini·오픈 모델을 골라 쓰고, 공급자 장애 시 자동 재시도·폴백이 동작하며, 사용량은 대시보드에서 봅니다.

작동 방식#

Codex CLI는 {base_url}/responses로 OpenAI Responses API 요청(POST /v1/responses)을 보냅니다. PleumRouter는 이 요청을 받아 함수(function) 도구, 입력 이미지, reasoning effort를 변환해 선택한 모델의 공급자로 전달하고, Responses 형식의 출력(스트리밍 SSE 포함)으로 돌려줍니다. 인증은 env_key가 가리키는 환경변수 또는 http_headers의 Authorization: Bearer 헤더에 넣은 plm_ 키입니다.

설정 레퍼런스#

항목설명
modelgpt-6-solPleumRouter 카탈로그의 모델 ID.
model_reasoning_effort"high"추론 강도(low·medium·high·xhigh). 모델이 지원할 때 적용됩니다.
model_provider"pleum"아래 [model_providers.pleum] 블록을 가리킵니다.
base_urlhttps://apirouter.pleum.ai/v1/v1까지입니다. Codex가 /responses를 붙이므로 /v1을 빼거나 두 번 쓰면 404입니다.
wire_api"responses"Chat Completions는 Codex에서 제거돼 Responses만 씁니다.
env_key"PLEUM_API_KEY"키를 담은 셸 환경변수 이름. 셸에서 띄우는 CLI에 씁니다.
http_headers.Authorization"Bearer plm_xxxxxxxxxxxxxxxx"키를 파일에 직접 넣는 방식. pleum wire codex가 이렇게 씁니다.
supports_websocketsfalsePleumRouter는 Responses의 WebSocket 전송을 지원하지 않으므로 끕니다.

모델 선택#

model에 PleumRouter 카탈로그 ID를 넣으세요. 정확한 ID는 모델 카탈로그나 GET /v1/models에서 확인합니다. gpt-6-sol@openai처럼 @공급자를 붙이면 그 공급자로만 보냅니다(다른 공급자로의 자동 폴백은 꺼집니다). 참고로 pleum launch codex는 --model을 주지 않으면 모델을 지정하지 않고 Codex의 모델 설정을 따릅니다. pleum wire codex는 model에 gpt-6.1-sol을 적습니다.

OpenAI 모델을 쓰는 구성을 기준으로 설명합니다. 다른 회사 모델도 Responses 형식으로 연결되지만 도구 호출 품질은 모델마다 다를 수 있습니다.

지원 범위#

기능상태설명
스트리밍(SSE)지원response.output_item.done과 response.completed 이벤트를 보냅니다.
함수 도구 호출일부function 유형 도구만 변환합니다. 다른 유형은 건너뜁니다.
이미지 입력지원input_image를 변환합니다. 모델이 이미지 입력을 지원해야 합니다.
reasoning effort지원model_reasoning_effort 값이 요청으로 전달됩니다. 모델이 지원할 때 적용됩니다.
내장 도구(web_search 등)미지원지원하지 않으며 요청에서 건너뜁니다.
서버 compact(/v1/responses/compact)미지원항상 501을 돌려줍니다. Codex의 로컬 compact를 쓰세요.
WebSocket 전송미지원supports_websockets = false로 두세요.

문제 해결#

증상원인과 조치
401 Unauthorizedenv_key의 환경변수가 비었거나 http_headers의 키가 틀렸습니다. 셸에서 echo $PLEUM_API_KEY로 확인하고 plm_ 키인지 보세요.
Windows에서 401이 납니다setx로 사용자 환경변수를 설정한 뒤 Codex를(데스크톱 앱 포함) 완전히 종료했다가 다시 여세요. 이미 열려 있던 터미널·앱은 새 변수를 보지 못합니다.
404 Not Foundbase_url이 https://apirouter.pleum.ai/v1인지 확인하세요. /v1이 빠졌거나 두 번 들어간 경우가 대부분입니다.
model not found / Unknown modelmodel이 카탈로그에 없는 ID입니다. GET /v1/models로 정확한 ID를 확인하세요.
Model metadata … not found 경고가 뜹니다Codex의 내장 모델 목록에 없는 ID라서 메타데이터를 모르고 기본값을 쓴다는 경고입니다. 동작은 하지만 컨텍스트 길이 같은 값이 기본값으로 잡혀 성능이 떨어질 수 있습니다.
연결이 반복해서 끊기거나 재연결 표시가 뜹니다supports_websockets = false가 빠졌을 수 있습니다. provider 블록에 넣고 다시 실행하세요.
설정이 무시됩니다provider 설정은 프로젝트 안 파일이 아니라 사용자 홈의 ~/.codex/config.toml에 두세요. pleum launch는 임시 설정을 넘기므로 그 실행에서만 적용되고 ~/.codex/config.toml에는 저장되지 않습니다.
웹 검색 도구가 동작하지 않습니다내장 도구(web_search 등)는 지원하지 않습니다. 웹 접근이 필요하면 MCP 서버나 셸 도구로 대신하세요.
대화 압축(compact)이 실패합니다서버 compact는 501을 돌려줍니다. Codex의 로컬 compact를 사용하세요.

비용·보안 팁#

  • 키에 예산을 걸어 두세요. 코딩 에이전트는 한 작업에서 모델을 여러 번 호출하고 긴 컨텍스트를 반복해 보냅니다. API 키에 일·주·월 예산을 설정하면 비용을 예측하기 쉽습니다.
  • 키는 git에 올리지 마세요. 셸 프로필이나 설정 파일에 넣은 키가 저장소에 커밋되지 않게 하고, 유출이 의심되면 대시보드에서 바로 폐기한 뒤 새로 발급하세요.
  • 민감한 코드라면 처리 위치를 확인하세요. 프롬프트와 코드는 고른 모델의 공급자에게 전달됩니다. 데이터 처리 위치와 개인정보 마스킹으로 범위를 정할 수 있습니다.
이전Claude Desktop다음Codex Desktop