게이트웨이에 연결하기

게이트웨이 담당 팀에서 제공한 공급자 설정과 인증 방식으로 Codex를 조직의 모델 게이트웨이에 연결하세요. 게이트웨이는 모델 요청을 Amazon Bedrock과 같은 백엔드로 전달합니다.

기존 설정 확인하기

관리자가 테스트한 Codex 클라이언트를 동일한 버전으로 설치하세요. 조직에서 설정을 관리한다면 해당 클라이언트를 열고 관리자가 안내한 로그인 절차를 완료하세요. 이 경우 아래의 공급자 구성 예시는 건너뛰어도 됩니다.

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

사용하려는 게이트웨이 공급자와 모델이 이미 활성화되어 있다면 관리자가 안내한 로그인 절차를 모두 완료한 후 연결 확인하기로 이동하세요. 조직에서 관리하는 컴퓨터에는 공급자 설정을 중복으로 추가하지 마세요. 현재 설정이 관리자의 안내와 다르다면 로컬 파일을 편집하기 전에 어느 구성 계층에서 해당 설정을 제공해야 하는지 관리자에게 확인하세요.

게이트웨이 연결 정보 받기

수동으로 설정하려면 ChatGPT 워크스페이스 로그인과 게이트웨이 인증 중 어느 것이 필요한지, 또는 둘 다 필요한지 확인하세요.

Codex를 직접 구성하려면 게이트웨이 담당 팀에서 다음 정보를 받으세요.

• API 경로를 포함한 게이트웨이의 HTTPS 기본 URL(예: https://gateway.example.com/v1)
• 사용할 모델 이름과 공급자 ID
• 인증 방식. 네이티브 게이트웨이 OAuth, 권한 범위가 지정된 API 키와 해당 환경 변수, 또는 설치된 자격 증명 헬퍼 중 하나입니다.
• OAuth를 사용하는 경우 인가 URL, 토큰 URL, 공개 클라이언트 ID 및 필요한 권한 범위. 게이트웨이가 쿠키 또는 사용자 지정 헤더를 사용한다면 해당 쿠키나 헤더의 이름도 확인하세요.
• 모델 카탈로그가 필요한 경우 카탈로그 URL 또는 카탈로그 파일과 해당 파일의 로컬 절대 경로

공급자 구성하기

config.toml을 여세요. macOS 또는 Linux에서는 ~/.codex/config.toml, Windows에서는 %USERPROFILE%\.codex\config.toml에 있습니다.

아래 예시를 기존 설정에 병합하고 URL과 모델을 관리자가 제공한 값으로 바꾸세요. 이미 있는 키나 테이블을 중복 정의하지 마세요. 이 예시의 모델은 gpt-6-sol입니다. 현재 Codex 버전이 이 모델을 인식하고 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"
requires_openai_auth = false

이어서 게이트웨이 담당 팀에서 제공한 인증 설정을 추가하세요.

enterprise-gateway는 예시용 공급자 ID입니다. model_provider와 해당 공급자 테이블 및 인증 테이블에 같은 ID를 사용하세요. 이 예시에서는 초기 연결 테스트를 위해 웹 검색을 비활성화합니다. 관리자는 웹 검색을 활성화하기 전에 지원 여부를 확인해야 합니다.

모델 카탈로그 구성하기

선택한 모델의 기능 정보와 지침을 Codex가 어떻게 가져오는지 게이트웨이 담당 팀에 확인하세요.

• 기본 제공 모델 이름: 게이트웨이가 현재 Codex 버전에 포함된 모델 이름을 그대로 받아 해당 모델로 요청을 전달한다면 model을 그 이름으로 설정하세요. 해당 모델의 메타데이터는 이미 Codex에 포함되어 있습니다.
• 카탈로그 엔드포인트: 게이트웨이가 Codex와 호환되는 메타데이터를 제공한다면 카탈로그의 전체 URL을 사용하세요. Codex 카탈로그 응답을 구현한 /v1/models 엔드포인트도 사용할 수 있습니다. 모델 ID만 나열하는 응답으로는 사용자 지정 별칭을 사용할 수 없습니다.
• 카탈로그 파일: 게이트웨이가 사용자 지정 별칭을 사용하고 관리자가 카탈로그 파일을 배포한다면 로컬 models.json 예시를 따르세요. 네이티브 게이트웨이 OAuth가 유일한 인증 수단이고 사용자 지정 메타데이터가 필요하다면 로컬 파일을 사용하세요.

API 키나 헬퍼로 인증할 때 관리자가 카탈로그 URL을 제공했다면 기존 [model_providers.enterprise-gateway] 테이블에 다음 설정을 추가하세요.

model_catalog_url = "https://gateway.example.com/codex/models.json"

현재 적용되는 model_catalog_json 설정이 있다면 제거하세요. 이 설정이 URL보다 우선합니다. 관리자는 원격 카탈로그 설정에서 엔드포인트 요구 사항을 확인할 수 있습니다.

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

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

관리자가 함께 제공한 모델 이름과 카탈로그를 사용하세요. 해당 위치에 파일이 있을 때만 카탈로그 경로를 추가하세요.

인증 방식 선택하기

브라우저로 로그인하려면 네이티브 게이트웨이 OAuth를 사용하세요. 권한 범위가 지정된 자격 증명을 사용하려면 API 키를 사용하고, 조직에서 인증 명령어를 제공한다면 자격 증명 헬퍼를 사용하세요.

[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127

delivery = { kind = "cookie", name = "auth-openid" }

delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }

ssh -L 43127:127.0.0.1:43127 user@remote

env_key = "CODEX_GATEWAY_API_KEY"

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

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

ChatGPT 로그인 활성화하기(권장)

조직에서 ChatGPT 워크스페이스를 사용한다면 사용자는 로그인 후 OpenAI가 제공하는 플러그인 등 이용 자격이 있는 기능을 사용할 수 있습니다. 워크스페이스의 제어 설정이 적용되며 모델 요청은 계속 게이트웨이가 처리합니다. 기능별 이용 가능 여부 비교를 참고하세요.

수동으로 설정하는 경우 로그인하기 전에 기존 [model_providers.enterprise-gateway] 테이블을 다음과 같이 수정하세요.

1. requires_openai_auth = true로 설정하고 base_url은 게이트웨이를 계속 가리키도록 하세요. Codex가 기본 인증에 사용자의 OpenAI 자격 증명을 사용하도록 env_key, experimental_bearer_token 및 공급자의 auth 설정이 있다면 모두 제거하세요.
2. 게이트웨이 자격 증명은 별도로 보내세요. 네이티브 게이트웨이 OAuth를 사용한다면 게이트웨이가 허용하는 쿠키나 사용자 지정 헤더를 사용하도록 gateway_oauth.delivery를 설정하세요. API 키나 자격 증명 헬퍼를 사용한다면 사용자 지정 인증 헤더를 사용하세요. Authorization 헤더는 OpenAI 자격 증명 전용으로 두세요.

관리자가 지정한 ChatGPT 워크스페이스에 로그인하세요. 게이트웨이 로그인 안내가 표시되면 로그인을 완료한 후 연결을 확인하세요.

관리자는 관리형 공급자 설정을 배포하고 자격 증명이 제대로 전달되는지 확인할 수 있습니다.

게이트웨이에서 자격 증명 처리하기

게이트웨이는 모델 요청마다 자격 증명 두 개를 받습니다. 예를 들어 Codex가 게이트웨이 OAuth 토큰을 쿠키로 보내면 요청은 다음과 같습니다.

POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>

게이트웨이 자격 증명을 검증한 후 해당 쿠키나 사용자 지정 헤더를 요청에서 제거하세요. 로그에는 자격 증명과 민감한 요청 데이터가 노출되지 않도록 마스킹하세요. 업스트림 요청에 사용할 자격 증명은 다음 두 방식 중 하나로 선택하세요.

• OpenAI에 직접 추론을 요청할 때 사용자의 자격 증명을 전달하세요(권장). 이 방식에서는 OpenAI가 해당 사용자의 사용량을 집계하고 그 사용자의 추론 설정을 적용할 수 있습니다. 이 경로를 사용하려면 게이트웨이가 /models와 /responses 요청을 https://chatgpt.com/backend-api/codex로 프록시해야 합니다. Authorization 헤더를 그대로 전달하고, ChatGPT-Account-ID 헤더가 있으면 이 헤더도 그대로 전달해야 합니다.
• 게이트웨이가 추론 공급자에 직접 인증하도록 하세요. 게이트웨이에 설정된 해당 공급자용 자격 증명을 사용하세요. 업스트림 요청에서는 사용자의 OpenAI 토큰과 ChatGPT-Account-ID 헤더를 제외하세요.

다음 그림은 OpenAI 추론에 권장되는 경로를 보여 줍니다.

ChatGPT 로그인과 게이트웨이 키를 함께 사용할 때의 동작 방식

ChatGPT 로그인과 게이트웨이 OAuth를 함께 사용할 때의 동작 방식

라우팅 헤더 추가하기(선택 사항)

관리자가 제공한 라우팅 설정을 사용하세요. 게이트웨이 운영자는 이 설정을 배포하고 게이트웨이 로그에서 선택된 경로를 확인할 수 있습니다.

모델 공급자에게 보내는 요청만 이 게이트웨이 경로를 사용합니다. 음성 세션은 별도의 경로를 사용합니다. 워크스페이스 로그인, MCP 서버, 플러그인도 다른 네트워크 경로를 사용할 수 있습니다.

클라이언트 시작하기

ChatGPT 로그인을 사용하는 경우 클라이언트를 시작하고 관리형 설정을 제공하는 워크스페이스에 로그인하세요. 네이티브 게이트웨이 OAuth도 사용한다면 안내가 표시될 때 조직의 게이트웨이 로그인도 완료하세요. 그런 다음 연결을 확인하세요.

공급자를 로컬에서 구성한 경우에는 사용하는 클라이언트에 맞는 안내를 따르세요.

CLI 구성하기

macOS 또는 Linux에서 CLI는 기본적으로 ~/.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 서버와 플러그인은 별도로 구성하세요. 모델 게이트웨이 자격 증명은 도구나 연결된 시스템에 대한 접근 권한을 부여하지 않습니다.

연결 확인하기

관리자가 안내한 공급자 ID와 모델 별칭을 사용하세요. 공급자 ID는 구성된 연결을 식별하고, 모델 별칭은 해당 연결을 통해 요청을 받을 모델을 식별합니다. ChatGPT 로그인과 게이트웨이 인증은 각각 접근 권한을 제어하며, 두 가지 모두 필요할 수 있습니다.

설정을 변경한 후 클라이언트를 다시 시작하세요. CLI에서는 codex를 시작하고 /status로 현재 사용 중인 모델과 공급자를 확인하세요. 데스크톱 앱에서는 선택한 모델과 설정을 확인하세요.

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

Reply with exactly: gateway-ok

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

연결 문제 해결하기

도움을 요청할 때는 클라이언트 버전, 운영 체제, 사용하려던 공급자와 모델 별칭, 인증 방식, 실패한 단계를 알려 주세요. 게이트웨이 담당자가 해당 요청을 찾을 수 있도록 오류 메시지와 요청 시각도 포함하세요. 공유할 내용에서 토큰, 쿠키, 인가 헤더, 민감한 프롬프트를 제거하세요. 자격 증명 파일이나 비밀 정보가 담긴 설정 덤프는 보내지 마세요.

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

게이트웨이 담당 팀에 Codex 공급자 설정과 승인된 모델 별칭을 요청하세요. 담당 팀에서 아직 Codex용 경로를 활성화해야 한다면 관리자용 마이그레이션 체크리스트를 공유하세요.

관련 문서

• Codex CLI
• MCP 서버
• 플러그인