Codex Desktop

Codex 데스크톱 앱을 사용자 config.toml로 PleumRouter에 연결합니다.

Codex Desktop은 OpenAI의 Codex를 아이콘 앱으로 쓰는 방식이고, CLI와 같은 사용자 파일 ~/.codex/config.toml을 읽습니다. CLI와 다른 점은 앱이 셸에서 export한 환경변수를 읽지 못한다는 것입니다. 그래서 키를 파일 안에 넣습니다. 터미널 버전은 Codex CLI를 보세요.

서드파티 도구입니다. Codex Desktop은(는) PleumRouter가 만들거나 보증하는 제품이 아니며, 모든 기능이 PleumRouter의 모델에서 동작한다고 보장하지 않습니다. Codex Desktop은(는) 제작사 모델에 맞춰 개발돼 있어, 다른 모델로 연결하면 도구 호출·추론 표시·이미지 입력 등이 다르게 동작할 수 있습니다.

PleumRouter 소스 코드와 Codex Desktop 공식 문서를 바탕으로 작성하고 2026-09-27에 마지막으로 검토했습니다. 도구가 업데이트되면 설정이 달라질 수 있으니 Codex Desktop 공식 문서를 우선하세요.

왜 Codex Desktop에 PleumRouter를 쓰나요?#

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

빠른 시작#

Codex 앱 설치
OpenAI Codex 앱 안내에서 받아 설치하세요. ChatGPT 데스크톱 안의 Codex도 같은 설정 파일을 씁니다.
API 키 발급
대시보드 → API 키에서 plm_ 키를 만드세요. 앱 전용 키를 따로 만들면 폐기하기 쉽습니다. pleum wire codex를 쓰면 전용 키를 자동으로 만들어 줍니다.

config.toml 작성

둘 중 하나를 고르세요. 프로젝트 안 파일이 아니라 사용자 홈의 파일입니다.

pleum wire codex

전용 `plm_` 키를 만들어 `~/.codex/config.toml`에 provider 블록을 넣습니다.

npm i -g pleumrouter
pleum login
pleum wire codex       # creates a dedicated plm_ key and edits ~/.codex/config.toml

`plm_xxxxxxxxxxxxxxxx`만 자기 키로 바꿔 저장합니다.

model = "gpt-4.1"
model_provider = "pleum"

[model_providers.pleum]
name = "PleumRouter"
base_url = "https://apirouter.pleum.ai/v1"
wire_api = "responses"
supports_websockets = false

[model_providers.pleum.http_headers]
Authorization = "Bearer plm_xxxxxxxxxxxxxxxx"

# macOS/Linux: ~/.codex/config.toml
# Windows:     C:\Users\<you>\.codex\config.toml

앱을 완전히 종료했다가 다시 열기
Dock이나 트레이에 남아 있으면 예전 설정을 읽습니다. 앱을 완전히 종료한 뒤 다시 열고, 한 턴에 응답이 오면 연결 성공입니다.

작동 방식#

앱은 CLI와 같은 방식으로 {base_url}/responses에 OpenAI Responses API 요청(POST /v1/responses)을 보냅니다. 앱은 셸의 환경변수를 상속하지 않으므로 env_key 대신 http_headers의 Authorization: Bearer plm_…로 인증합니다. pleum wire codex는 이 형태로 파일을 씁니다. PleumRouter 쪽 동작과 지원 범위는 Codex CLI와 같습니다.

설정 레퍼런스#

항목	설명
설정 파일~/.codex/config.toml	사용자 레벨 파일만 읽습니다. 프로젝트 안의 `.codex/config.toml`은 무시됩니다. Windows는 `C:\Users\이름\.codex\config.toml`입니다.
model_provider"pleum"	`[model_providers.pleum]` 블록을 가리킵니다.
base_urlhttps://apirouter.pleum.ai/v1	`/v1`까지. 앱이 `/responses`를 붙입니다.
wire_api"responses"	Responses API만 씁니다.
http_headers.Authorization"Bearer plm_…"	키를 파일에 직접 넣습니다. 앱은 셸 환경변수를 읽지 못합니다.
supports_websocketsfalse	PleumRouter는 WebSocket 전송을 지원하지 않습니다. 빼면 데스크톱에서 실패할 수 있습니다.

모델 선택#

model에 PleumRouter 카탈로그 ID를 넣으세요(예시는 gpt-4.1). 정확한 ID는 모델 카탈로그나 GET /v1/models에서 확인합니다. 다른 회사 모델도 연결되지만 도구 호출·추론 동작은 모델마다 다르고 보장하지 않습니다.

지원 범위#

기능	상태	설명
스트리밍·함수 도구·이미지 입력	✓ 지원	Codex CLI와 같은 `/v1/responses` 엔드포인트를 씁니다. 함수 도구만 변환합니다.
내장 도구(web_search 등)	✗ 미지원	지원하지 않으며 요청에서 건너뜁니다.
서버 compact	✗ 미지원	`/v1/responses/compact`는 501을 돌려줍니다. 로컬 compact를 쓰세요.
WebSocket 전송	✗ 미지원	`supports_websockets = false`로 두세요.
셸 환경변수로 키 전달	✗ 미지원	앱이 셸 프로필의 `export`를 읽지 못합니다. 파일의 `http_headers`를 쓰세요.

키를 파일에 두고 싶지 않다면#

provider 블록의 http_headers 대신 env_key = "PLEUM_API_KEY"를 쓰고, 앱이 볼 수 있는 곳에 환경변수를 등록하세요. macOS는 launchctl setenv PLEUM_API_KEY plm_…, Windows는 setx PLEUM_API_KEY plm_…입니다. 등록 뒤 앱을 완전히 종료했다가 다시 열어야 하며, macOS의 launchctl setenv는 재부팅하면 사라집니다.

문제 해결#

증상	원인과 조치
인증 오류(401)가 납니다	앱은 셸의 `export`를 읽지 못합니다. `http_headers`로 키를 파일에 넣거나, 위의 환경변수 등록 방법을 쓴 뒤 앱을 완전히 종료했다 다시 여세요.
설정을 바꿨는데 반영되지 않습니다	앱을 완전히 종료하지 않았을 수 있습니다. 그리고 파일이 사용자 홈의 `~/.codex/config.toml`인지 확인하세요. 프로젝트 안 파일은 읽지 않습니다.
404 Not Found	`base_url`이 `https://apirouter.pleum.ai/v1`인지 확인하세요. `/v1`이 빠졌거나 두 번 들어간 경우가 대부분입니다.
model not found / Unknown model	`model` ID가 카탈로그에 없습니다. `GET /v1/models`로 정확한 ID를 확인하세요.
`Model metadata … not found` 경고가 뜹니다	Codex의 내장 모델 목록에 없는 ID라서 메타데이터를 모르고 기본값을 쓴다는 경고입니다. 동작은 하지만 컨텍스트 길이 같은 값이 기본값으로 잡혀 성능이 떨어질 수 있습니다.
연결이 반복해서 끊깁니다	`supports_websockets = false`가 있는지 확인하세요.
`pleum wire codex`가 다른 설정을 덮어쓸까 걱정됩니다	처음 실행할 때 원본을 `config.toml.pleum.bak`로 한 번 백업하고, PleumRouter 블록만 표시(마커)해서 넣습니다. 되돌릴 때는 `pleum unwire codex`를 쓰세요.

지원 범위와 면책#

제휴·보증 없음. PleumRouter는 Codex Desktop의 제작사와 제휴 관계가 아니며 이 문서는 참고용입니다. Codex Desktop의 동작·지원 범위·정책은 제작사가 정하고 예고 없이 바뀔 수 있습니다.
약관은 사용자 책임입니다. 도구 제작사와 모델 제공사의 이용약관·사용 정책을 지킬 책임은 사용자에게 있습니다.
비용이 빨리 쌓일 수 있습니다. 에이전트는 한 작업에서 모델을 수십~수백 번 호출하고 긴 컨텍스트를 반복 전송합니다. 사용량만큼 PleumRouter 크레딧이 차감되므로, 처음에는 API 키에 일·주·월 예산을 걸어 두세요.
키는 비밀번호처럼 다루세요. 설정 파일이나 셸 프로필에 평문으로 두면 같은 PC의 다른 프로그램이 읽을 수 있습니다. 설정 파일을 git에 커밋하지 말고, 유출이 의심되면 대시보드에서 즉시 폐기하고 새로 발급하세요.
코드가 외부로 전송됩니다. 프롬프트·코드·파일 내용은 선택한 모델의 제공사로 전송되며 국외 서버일 수 있습니다. 민감한 코드는 데이터 처리 위치, 개인정보 마스킹, 개인정보처리방침을 확인한 뒤 사용하세요.
상표. 모든 제품명과 상표는 각 소유자의 자산이며, 호환성을 설명하기 위해서만 사용합니다.