게이트웨이에 연결하기

조직에서 제공하는 게이트웨이 URL, 모델 별칭, 자격 증명 또는 토큰 리졸버를 사용해 Codex를 LLM 게이트웨이에 연결하세요.

기존 구성 확인하기

설정을 추가하기 전에 관리자가 이미 Codex를 구성했는지 확인하세요.

• CLI에서는 선택된 프로필을 확인하고 codex doctor를 실행하세요. 시작 후에는 /status를 사용해 활성 모델과 공급자를 확인하세요.
• macOS 앱에서는 ~/.codex/config.toml 또는 조직에서 배포하는 관리형 구성을 확인하세요.
• Windows 앱에서는 %USERPROFILE%\.codex\config.toml 또는 조직에서 배포하는 시스템 구성을 확인하세요.

예상한 게이트웨이 공급자와 모델이 이미 활성화되어 있다면 연결 확인하기로 진행하세요.

게이트웨이 연결 정보 받기

Codex CLI 또는 조직에서 승인한 데스크톱 앱을 설치하세요. Codex를 직접 구성하려면 게이트웨이 담당 팀에서 다음 값을 받으세요.

• https://gateway.example.com/v1처럼 API 경로가 포함된 HTTPS 게이트웨이 기본 URL.
• 사용할 모델 이름과 공급자 ID.
• 권한 범위가 제한된 게이트웨이 자격 증명과 해당 환경 변수, 또는 설치된 토큰 리졸버와 해당 구성.
• 필요한 모델 카탈로그 파일과 해당 파일의 절대 로컬 경로.

공급자 구성하기

macOS 또는 Linux에서는 config.toml 파일을 ~/.codex/config.toml에서 열고, Windows에서는 %USERPROFILE%\.codex\config.toml에서 여세요.

이 예제를 기존 구성에 병합하고 URL과 모델을 관리자가 제공한 값으로 바꾸세요. 기존 키나 테이블을 중복으로 정의하지 마세요. 이 예제는 gpt-6-sol를 사용합니다. 관리자가 현재 Codex 버전에서 해당 모델을 인식하고 번들 메타데이터가 게이트웨이와 일치한다고 확인한 경우에만 사용자 지정 카탈로그 없이 사용하세요.

model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"

관리자가 모델 카탈로그를 제공하면 로컬에 저장하고 파일의 절대 경로를 사용해 첫 번째 TOML 테이블 앞에 model_catalog_json를 추가하세요. 사용자 지정 별칭에는 일치하는 카탈로그 메타데이터가 필요합니다. 예를 들면 다음과 같습니다.

model_catalog_json = "/etc/codex/gateway-models.json"

관리자가 함께 제공한 모델 이름과 카탈로그를 사용하세요. 해당 위치에 파일이 없으면 카탈로그 경로를 추가하지 마세요.

enterprise-gateway는 예시 공급자 ID입니다. model_provider, [model_providers.<id>], [model_providers.<id>.auth]에 동일한 ID를 사용하세요. 이 예제에서는 최초 연결 테스트를 위해 웹 검색을 비활성화합니다. 관리자는 웹 검색을 활성화하기 전에 기능 지원 여부를 확인해야 합니다.

조직의 비밀 정보 전달 메커니즘을 사용해 Codex를 시작하는 프로세스의 환경에서 게이트웨이 자격 증명을 CODEX_GATEWAY_API_KEY으로 사용할 수 있도록 설정하세요. 자격 증명을 TOML이나 저장소에 넣지 마세요. 터미널에서 설정한 변수는 데스크톱에서 실행한 앱에서 사용하지 못할 수 있습니다.

사용자 지정 인증 헤더 사용하기

게이트웨이에 bearer 토큰 대신 X-API-Key 같은 헤더가 필요하면, 공급자 테이블의 env_key를 다음으로 바꾸세요.

env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }

관리자가 제공한 헤더 이름을 정확히 사용하세요. Codex는 지정된 환경 변수에서 값을 읽습니다. 자격 증명을 구성 파일에 넣지 마세요. model_providers.<id>.env_http_headers에 대한 자세한 내용은 구성 참조를 참고하세요.

조직의 자격 증명 도우미 사용하기

관리자가 명령 기반 인증을 제공하면 env_key 대신 관리자가 설치한 도우미와 구성을 사용하세요. 두 방식을 동시에 구성하지 마세요. 도우미는 컴퓨터에 설치되어 있어야 하며, Codex가 설치해 주지는 않습니다. 예를 들어, 관리자가 제공한 리졸버 경로와 인수를 사용해 예제의 env_key 설정을 다음 테이블로 바꾸세요.

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

사용자 지정 공급자 인증 참조에는 명령, 인수, 제한 시간, 갱신 간격, 토큰 출력 규약이 정의되어 있습니다. 도우미가 더 이상 토큰을 가져오지 못하면 관리자에게 로그인 갱신 방법을 문의하세요.

도우미 실행 파일과 카탈로그 파일에는 실제 위치로 해석된 절대 경로를 사용하세요.

CLI 구성하기

CLI는 macOS 또는 Linux에서 기본적으로 ~/.codex/config.toml를 읽습니다. 공급자 설정을 저장한 후 codex를 실행하세요. WSL에서는 CODEX_HOME가 다른 위치를 가리키지 않는 한 Linux 구성과 경로를 사용하세요.

macOS 앱 구성하기

macOS 앱은 동일한 ~/.codex/config.toml를 읽습니다. 공급자 설정을 저장한 후 앱을 다시 시작하세요. 자격 증명에 환경 변수를 사용하는 경우, 앱 프로세스에서 해당 변수를 사용할 수 있는지 확인하세요.

Windows 앱 구성하기

공급자 설정을 %USERPROFILE%\.codex\config.toml에 넣은 다음 앱을 다시 시작하세요. 명령 기반 인증에는 관리자가 설치한 리졸버를 사용하세요. 예를 들어, Unix 인증 테이블을 다음으로 바꾸세요.

[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

Windows TOML에서 작은따옴표로 묶인 리터럴 문자열은 백슬래시를 그대로 보존합니다. Unix 카탈로그 경로도 바꾸세요. 예를 들어, 'C:\ProgramData\OpenAI\Codex\models.json'처럼 관리자가 제공한 실제 경로를 사용하세요.

MCP server와 플러그인은 별도로 구성하세요. 모델 게이트웨이 자격 증명은 도구나 연결된 시스템에 대한 액세스 권한을 부여하지 않습니다.

연결 확인하기

구성을 변경한 후 클라이언트를 다시 시작하세요. CLI에서는 codex를 시작하고 /status를 사용해 활성 모델과 공급자를 살펴보세요. 데스크톱 앱에서는 선택된 모델과 구성을 확인하세요.

새 작업에서 다음 프롬프트를 보내세요.

Reply with exactly: gateway-ok

예상 응답은 gateway-ok입니다. 응답만으로는 어떤 경로에서 처리했는지 입증할 수 없습니다. 게이트웨이가 사용자, 모델 별칭, 의도한 업스트림 경로를 기록했는지 관리자에게 확인을 요청하세요. 모델에 이름을 물어서 모델을 식별하지 마세요.

이 과정은 최초 연결을 확인합니다. 관리자는 스트리밍, 도구, 후속 턴에 대한 도입 점검도 완료해야 합니다.

연결 문제 해결하기

도움을 요청할 때는 토큰과 민감한 프롬프트를 제거한 오류 메시지를 포함하세요.

기존 게이트웨이 배포 사용하기

조직에서 이미 다른 코딩 도구에 게이트웨이를 사용하고 있다면, 해당 네트워크 경로, 로깅, 공급자 액세스를 재사용할 수 있습니다. 게이트웨이 담당 팀과 함께 Codex 연결을 구성하고 테스트하세요.

1. 기존 게이트웨이 URL, 자격 증명 메커니즘, 필수 헤더, 모델 경로, 구성 배포 방법을 파악하세요.
2. 게이트웨이 담당 팀에 게이트웨이가 Codex에 필요한 API 동작을 지원하는지 확인하고 Codex 모델 경로를 구성하도록 요청하세요.
3. 게이트웨이 담당 팀에서 권한 범위가 제한된 게이트웨이 자격 증명 또는 자격 증명 도우미, 모델 이름, 필요한 모델 카탈로그를 받으세요.
4. 해당 값으로 Codex를 구성하세요.
5. 사용하려는 CLI 또는 데스크톱 앱에서 연결을 확인하세요. 게이트웨이 담당 팀에 스트리밍, 도구, 후속 턴 점검을 완료하도록 요청하세요.
6. 시범 운영을 통과하면 게이트웨이를 통한 Codex 배포에 따라 다른 개발자에게 구성을 배포하세요.

관리자 마이그레이션 체크리스트와 구성 매핑은 기존 게이트웨이 배포 재사용하기를 참고하세요.

관련 문서

• Codex CLI
• MCP server
• 플러그인