VS Code Codex 설정: API 키와 타사 모델을 검증하는 방법

VS Code에서 Codex를 설정할 때는 공식 확장 설치, 로그인 방식, 모델 제공업체와 모델 ID를 차례로 확인하세요. 설정을 마친 뒤에는 작은 코드 변경을 요청하고 실제 변경 내용과 테스트 결과까지 확인해야 합니다.

이 기준을 쓰면 API 키를 입력했는데도 다른 모델이 호출되는 문제, 타사 확장의 설정을 공식 Codex에 복사하는 문제, 대화가 된다는 이유로 도구 호출까지 호환된다고 믿는 문제를 피할 수 있습니다.

확장, 인증, 제공업체와 결과를 따로 확인한다

네 설정을 동시에 바꾸지 마세요. 확장과 인증을 확인하고, 기본 OpenAI 연결을 사용할지 별도의 제공업체를 추가할지 정한 다음 작은 작업으로 시험합니다.

공식 Codex 확장에서 시작한다

OpenAI의 Codex IDE 공식 문서에서 Visual Studio Code 설치 링크를 엽니다. Marketplace에서 공식 페이지가 가리키는 확장 이름과 게시자를 확인하세요. 이름에 Codex가 들어간 예전 확장이나 Continue, Cline, CodeGPT 같은 제품은 각자 다른 설정 형식을 사용합니다.

설치 후 안전하게 테스트할 Git 프로젝트를 엽니다. Activity Bar의 Codex 아이콘을 선택합니다. 아이콘이 없다면 Command Palette에서 Codex: Open Codex Sidebar를 실행합니다.

사이드바가 열리면 확장이 로드된 것입니다. 계정 권한, 결제 방식, 프로젝트의 코드 문맥과 모델 기능은 별도로 확인해야 합니다.

ChatGPT 로그인과 API 키 로그인을 구분한다

공식 Codex 인증 문서는 로컬 IDE에서 두 OpenAI 인증 방식을 제공합니다.

• Sign in with ChatGPT: 선택한 ChatGPT 계정과 워크스페이스 권한을 사용합니다.
• Use API Key: OpenAI Platform API key를 사용하며 표준 API 사용량으로 청구됩니다.

API 키 로그인은 ChatGPT 구독 사용량을 API 잔액으로 바꾸지 않습니다. 또한 ChatGPT 워크스페이스나 클라우드 서비스에 의존하는 일부 기능은 API 키 로그인 시 제한될 수 있습니다.

이미 로그인된 상태라면 프로필 메뉴에서 현재 방식을 확인한 다음 Log out을 사용하세요. 정상적인 전환을 위해 ~/.codex/auth.json을 비우거나 삭제할 필요는 없습니다. CLI와 IDE 확장은 로그인 정보를 공유합니다. 파일을 수동으로 지우기 전에 현재 어떤 계정과 인증 방식을 쓰는지 확인하세요.

키를 프롬프트, 소스 파일, 커밋할 .env, 스크린샷, 이슈나 로그에 넣지 마세요. 인증/청구 선택이 먼저 필요하면 Codex API 키와 구독 경로 비교를 참고할 수 있습니다.

VS Code Settings에서 Base URL을 찾지 않아도 된다

공식 확장에는 두 설정 공간이 있습니다.

• chatgpt.*는 VS Code 안에서 확장 화면과 상호작용을 제어합니다.
• Codex config.toml은 모델, 제공업체, 권한, 샌드박스 같은 에이전트 동작을 제어합니다.

OpenAI의 기본 설정 문서에 따르면 CLI와 IDE 확장은 같은 설정 체계를 사용합니다. Codex 사이드바의 톱니바퀴 메뉴에서 Codex Settings > Open config.toml을 선택하세요.

개인용 제공업체 설정을 넣을 파일은 일반적으로 다음입니다.

~/.codex/config.toml

다른 AI 확장 설명에 나온 extension.apiBaseUrl 같은 JSON 필드를 VS Code settings.json에 복사하지 마세요. 공식 Codex가 읽는 제공업체 설정 형식과 다릅니다. 제공업체와 개인 엔드포인트 설정은 저장소의 .codex/config.toml 대신 사용자 설정 파일에 두세요. 프로젝트를 열었다는 이유만으로 모델 트래픽 목적지가 바뀌어서는 안 됩니다.

키를 파일에 넣지 않고 제공업체를 설정한다

다음 예시에서 기본 URL, 환경 변수 이름, 모델 ID는 사용할 제공업체의 문서에 맞게 바꿔야 합니다.

# ~/.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"

복사보다 중요한 검증 항목은 다음과 같습니다.

1. model_provider와 설정 테이블의 team_provider가 정확히 일치한다.
2. 사용자 지정 ID로 이미 예약된 openai, ollama, lmstudio를 재사용하지 않는다.
3. base_url은 대시보드 주소가 아니라 제공업체가 안내한 API 기본 주소다.
4. env_key는 비밀 키 값이 아니라 환경 변수의 이름이다.
5. model은 제공업체가 지원하는 정확한 API 모델 ID다.
6. 엔드포인트가 필요한 Responses 동작, 스트리밍, 도구 호출을 실제로 지원한다.

macOS/Linux의 현재 셸에서 VS Code를 시작하는 예시는 다음과 같습니다.

export TEAM_PROVIDER_API_KEY="<provider-key>"
code .

현재 PowerShell 세션에서는 다음과 같습니다.

$env:TEAM_PROVIDER_API_KEY = "<provider-key>"
code .

Dock, Start menu, WSL, Remote SSH, dev container에서 연 VS Code는 서로 다른 환경 변수를 가질 수 있습니다. 401 오류가 발생하면 새 키를 만들기 전에 Codex가 실행되는 환경에 변수가 전달됐는지 확인하세요. 값을 출력하거나 공유할 필요는 없습니다.

OpenAI의 사용자 지정 모델 제공업체 문서는 환경 변수뿐 아니라 OpenAI 인증, 명령으로 가져오는 토큰, 인증 없는 로컬 서비스도 설명합니다. 제공업체가 요구하는 방식 하나만 선택해 원인을 추적 가능하게 유지하세요.

OpenAI-compatible을 기능별로 시험한다

타사 서비스가 OpenAI-compatible이라고 해도 Codex 에이전트의 모든 기능을 보장하는 것은 아닙니다. 간단한 텍스트 요청은 성공해도 스트리밍 이벤트, 도구 호출, 추론 메타데이터, 오류 형식, 웹 검색이나 모델 별칭 처리에서는 실패할 수 있습니다.

다음 질문에 각각 답할 수 있어야 합니다.

• 정확한 Base URL과 wire API가 문서화돼 있는가?
• 인증 정보에 선택한 모델 ID를 사용할 권한이 있는가?
• 응답 스트림이 정상적으로 끝나는가?
• 현재 작업에 필요한 도구 호출을 엔드포인트와 모델이 지원하는가?
• 할당량, 결제, 데이터 보존과 장애 지원은 누가 담당하는가?

TOML 파일을 읽었다는 것은 설정 문법이 맞는다는 뜻입니다. 답변을 한 번 받았다는 것은 해당 요청이 처리됐다는 뜻입니다. 어느 쪽도 모든 기능의 호환성을 확인한 결과는 아닙니다.

첫 작업은 익숙한 함수 하나로 제한한다

시작 전에 기존 작업 파일 상태를 기록합니다.

git status --short

동작을 이해하는 파일을 열고 함수 하나를 선택한 다음 범위를 명확히 합니다.

선택한 parseConfig 함수만 검토하세요.
빈 문자열은 프로젝트의 기존 오류 타입을 반환해야 합니다.
public API, 다른 파일, dependency는 변경하지 마세요.
예상 변경과 실행할 기존 test를 알려 주세요.

응답이 끝난 후 설명보다 코드 변경 내용을 먼저 봅니다.

git diff -- path/to/file
git status --short

다음 네 조건을 분리해 확인하세요.

• 인증·계정 오류 없이 요청이 시작된다.
• 설정한 제공업체·모델의 엔드포인트 오류가 없다.
• 답변이 선택한 코드의 실제 변수와 분기를 다룬다.
• 변경이 허용 범위에 있고 기존 테스트와 검사가 통과한다.

대화가 된다고 해서 코드가 맞는 것은 아닙니다. 텍스트 응답을 받았다고 해서 도구와 스트리밍까지 호환되는 것도 아닙니다.

처음 실패한 단계부터 원인을 확인한다

Codex 아이콘이나 명령이 없다

공식 확장이 맞는지, 현재 창에서 활성화되어 있는지, Remote/WSL 환경의 올바른 위치에 설치되어 있는지 확인합니다. API 키를 바꿔도 확장 로드 문제는 해결되지 않습니다.

로그인 단계에서 멈춘다

ChatGPT 워크스페이스로 로그인할지 OpenAI Platform 프로젝트의 키를 쓸지 확인합니다. 해당 계정의 상태를 확인하되 키를 공유하지 마세요. 이 단계에서는 모델 ID나 기본 URL을 바꾸지 않습니다.

사용자 지정 제공업체 설정이 적용되지 않는다

사용자 설정 파일을 수정했는지, 제공업체 ID가 일치하는지, 우선순위가 높은 다른 설정이 값을 덮어쓰는지 확인합니다. Codex config.toml 문제 해결은 설정 로드 문제와 제공업체 호출 실패를 나눠 설명합니다.

401/403 또는 404/model-not-found가 나온다

401/403이면 먼저 환경 변수, 키가 속한 계정과 제공업체의 사용 권한을 확인합니다. 404/model-not-found이면 API 기본 경로, 정확한 모델 ID와 제공업체의 모델 연결 설정을 확인합니다. 오류 원문과 발생 시각을 남기되 공유할 때는 토큰, 인증 헤더, 계정 ID와 비공개 코드를 제거하세요.

텍스트 응답은 오지만 도구나 스트리밍이 실패한다

파일 시스템 권한을 늘리기 전에 실패한 기능 하나만 시험하세요. 제공업체 문서에서 해당 엔드포인트와 모델이 그 기능을 지원하는지 확인합니다.

마지막으로 비밀 키를 제외한 설정 기록을 남기세요. VS Code와 확장 버전, 인증 방식, 제공업체 ID, API 호스트명, 모델 ID, 오류 문구, 변경 범위와 테스트 명령을 적으면 됩니다. 업데이트 뒤 문제가 생겼을 때 이 기록과 비교하면 달라진 부분부터 확인할 수 있습니다.