VS Code에서 Codex를 설정할 때 먼저 성공 기준을 바꾸는 편이 좋습니다. “확장을 설치했다”가 아니라 “어떤 확장, 어떤 인증, 어떤 provider/model이 활성 상태이며 첫 diff가 검증됐는가”가 기준입니다.
이 기준을 쓰면 API 키를 입력했는데도 다른 모델이 호출되는 문제, 타사 확장의 설정을 공식 Codex에 복사하는 문제, 대화가 된다는 이유로 tool compatibility까지 믿는 문제를 피할 수 있습니다.
한 줄 설정 대신 네 개의 owner를 확인한다
| 레이어 | 확인할 항목 | 실패를 소유하는 곳 |
|---|---|---|
| Editor | OpenAI 공식 Codex extension과 sidebar | VS Code, extension, local/remote host |
| Auth | ChatGPT 로그인 또는 OpenAI API key | ChatGPT workspace 또는 OpenAI Platform project |
| Provider | built-in OpenAI, company gateway, local runtime | 해당 endpoint 운영자 |
| Result | 실제 model ID, 제한된 diff, test 결과 | provider capability와 현재 repository |
네 레이어를 동시에 바꾸지 마세요. extension을 확인한 다음 인증을 확인하고, 기본 OpenAI 경로가 필요한지 custom provider가 필요한지 결정한 뒤 작은 작업으로 검증합니다.
공식 Codex 확장에서 시작한다
OpenAI의 Codex IDE 공식 문서에서 Visual Studio Code 설치 링크를 엽니다. Marketplace에서 공식 페이지가 가리키는 extension과 publisher를 확인하세요. 이름에 Codex가 들어간 예전 확장이나 Continue, Cline, CodeGPT 같은 제품은 각자 다른 설정 계약을 사용합니다.
설치 후 안전하게 테스트할 Git 프로젝트를 엽니다. Activity Bar의 Codex 아이콘을 선택합니다. 아이콘이 없다면 Command Palette에서 Codex: Open Codex Sidebar를 실행합니다.
sidebar가 열리면 extension loading만 통과한 것입니다. 계정 권한, 결제 경로, 프로젝트 context, 모델 capability는 아직 증명되지 않았습니다.
ChatGPT 로그인과 API 키 로그인을 구분한다
공식 Codex 인증 문서는 로컬 IDE에서 두 OpenAI 인증 방식을 제공합니다.
- Sign in with ChatGPT: 선택한 ChatGPT account와 workspace 권한을 사용합니다.
- Use API Key: OpenAI Platform API key를 사용하며 표준 API 사용량으로 청구됩니다.
API key login은 ChatGPT 구독 사용량을 API 잔액으로 바꾸지 않습니다. 또한 ChatGPT workspace나 cloud service에 의존하는 일부 기능은 API-key 경로에서 제한될 수 있습니다.
이미 로그인된 상태라면 profile menu에서 현재 방식을 확인한 다음 Log out을 사용하세요. 정상적인 전환을 위해 ~/.codex/auth.json을 비우거나 삭제할 필요는 없습니다. CLI와 IDE extension은 로그인 cache를 공유하므로, 파일을 수동으로 지우면 원래 auth owner를 확인하기 어려워집니다.
key는 prompt, source file, commit 대상 .env, screenshot, issue, log에 넣지 마세요. 인증/청구 선택이 먼저 필요하면 Codex API 키와 구독 경로 비교를 참고할 수 있습니다.
VS Code Settings에서 Base URL을 찾지 않아도 된다
공식 extension에는 두 설정 공간이 있습니다.
chatgpt.*는 VS Code 안에서 extension UI와 상호작용을 제어합니다.- Codex
config.toml은 model, provider, permissions, sandbox 같은 agent 동작을 제어합니다.
OpenAI의 config 기본 문서에 따르면 CLI와 IDE extension은 같은 config layer를 읽습니다. Codex sidebar의 gear에서 Codex Settings > Open config.toml을 선택하세요.
개인 provider를 넣을 파일은 일반적으로 다음입니다.
text~/.codex/config.toml
다른 AI extension 설명에 나온 extension.apiBaseUrl 같은 JSON 필드를 VS Code settings.json에 복사하지 마세요. 공식 Codex가 읽는 provider 계약이 아닙니다. 또한 provider와 개인 endpoint를 repository의 .codex/config.toml에 넣지 않는 것이 안전합니다. 프로젝트를 열었다는 이유만으로 모델 트래픽 목적지가 바뀌어서는 안 됩니다.
Secret 없이 custom provider를 정의한다
다음은 구조를 보여 주는 placeholder입니다. provider 문서의 실제 Base URL, 환경 변수 이름, model ID로 교체해야 합니다.
toml# ~/.codex/config.toml model = "EXACT_MODEL_ID" model_provider = "team_provider" [model_providers.team_provider] name = "Team provider" base_url = "https://gateway.example.com/v1" env_key = "TEAM_PROVIDER_API_KEY" wire_api = "responses"
복사보다 중요한 검증 항목은 다음과 같습니다.
model_provider와 table의team_provider가 정확히 일치한다.- custom ID로 예약된
openai,ollama,lmstudio를 재사용하지 않는다. base_url은 dashboard URL이 아니라 provider가 문서화한 API root다.env_key는 secret 값이 아니라 환경 변수의 이름이다.model은 provider의 정확한 API model ID다.- endpoint가 필요한 Responses 동작, streaming, tool call을 실제로 지원한다.
macOS/Linux의 현재 shell에서 VS Code를 시작하는 예시는 다음과 같습니다.
bashexport TEAM_PROVIDER_API_KEY="<provider-key>" code .
현재 PowerShell session에서는 다음과 같습니다.
powershell$env:TEAM_PROVIDER_API_KEY = "<provider-key>" code .
Dock, Start menu, WSL, Remote SSH, dev container에서 연 VS Code는 서로 다른 environment를 가질 수 있습니다. 401 오류가 발생하면 새 key를 만들기 전에 Codex가 실행되는 환경에 변수가 전달됐는지 확인하세요. 값을 출력하거나 공유할 필요는 없습니다.
OpenAI의 custom model provider 문서는 환경 변수뿐 아니라 OpenAI auth, command 기반 token, 인증 없는 local service도 설명합니다. provider가 요구하는 방식 하나만 선택해 원인을 추적 가능하게 유지하세요.
OpenAI-compatible을 기능별로 시험한다
타사 서비스가 OpenAI-compatible이라고 해도 Codex agent의 모든 기능을 보장하는 것은 아닙니다. 간단한 text request는 성공하지만 stream event, tools, reasoning metadata, error format, web search, model alias에서 실패할 수 있습니다.
다음 질문에 각각 답할 수 있어야 합니다.
- 정확한 Base URL과 wire API가 문서화돼 있는가?
- credential이 선택 model ID를 사용할 권한이 있는가?
- response stream이 정상적으로 끝나는가?
- 현재 작업에 필요한 tool call을 endpoint와 model이 지원하는가?
- quota, billing, retention, incident support owner는 누구인가?
TOML parsing 성공은 config shape의 증거입니다. 한 번의 답변 성공은 그 request path의 증거입니다. 둘 다 전체 feature compatibility 증거는 아닙니다.
첫 작업은 익숙한 함수 하나로 제한한다
시작 전에 원래 worktree를 기록합니다.
bashgit status --short
동작을 이해하는 파일을 열고 함수 하나를 선택한 다음 범위를 명확히 합니다.
text선택한 parseConfig 함수만 검토하세요. 빈 문자열은 프로젝트의 기존 오류 타입을 반환해야 합니다. public API, 다른 파일, dependency는 변경하지 마세요. 예상 변경과 실행할 기존 test를 알려 주세요.
응답이 끝난 후 설명보다 diff를 먼저 봅니다.
bashgit diff -- path/to/file git status --short
다음 네 조건을 분리해 확인하세요.
- auth/account 오류 없이 request가 시작된다.
- 설정한 provider/model의 endpoint 오류가 없다.
- 답변이 선택한 코드의 실제 변수와 분기를 다룬다.
- diff가 허용 범위에 있고 기존 test/check가 통과한다.
대화가 된다고 해서 코드가 맞는 것은 아닙니다. text가 된다고 해서 tools와 streaming까지 호환되는 것도 아닙니다.
오류 메시지를 첫 실패 레이어에 돌려보낸다
Codex 아이콘이나 명령이 없다
공식 extension identity, 현재 window의 enabled state, Remote/WSL 설치 위치를 확인합니다. API key 변경은 loading 문제를 해결하지 않습니다.
로그인 단계에서 멈춘다
ChatGPT workspace와 OpenAI Platform project 중 어느 쪽이 owner인지 확인합니다. 해당 account 상태를 확인하되 key를 공유하지 마세요. 이 단계에서는 model ID나 Base URL을 바꾸지 않습니다.
Custom provider가 무시된다
user-level 파일을 수정했는지, provider ID가 일치하는지, 더 높은 priority layer가 값을 덮는지 확인합니다. Codex config.toml 문제 해결은 config loading과 provider call failure를 나눠 설명합니다.
401/403 또는 404/model-not-found가 나온다
401/403은 먼저 environment, credential owner, provider entitlement를 확인합니다. 404/model-not-found는 Base URL path, 정확한 ID, provider mapping을 확인합니다. 원본 error와 시간을 남기되 token, headers, account ID, private code는 제거합니다.
Text는 되지만 tools나 stream이 실패한다
filesystem 권한을 더 주지 말고, 실패한 capability 하나로 task를 줄입니다. provider 문서에서 endpoint와 model이 그 기능을 지원하는지 확인합니다.
마지막으로 secret 없는 설정 기록을 남기세요. VS Code/extension version, auth method, provider ID, Base URL hostname, model ID, error text, diff scope, test command이면 충분합니다. 다음 업데이트에서 문제가 생겨도 어떤 owner가 바뀌었는지 알 수 있고 전체 설정을 반복하지 않아도 됩니다.
