게이트웨이에 연결
모델 게이트웨이를 구성하고 네이티브 게이트웨이 OAuth, API key 또는 자격 증명 도우미로 인증합니다.
게이트웨이 팀에서 제공하는 공급자 설정과 인증 방식을 사용하여 Codex를 조직의 모델 게이트웨이에 연결합니다. 게이트웨이는 모델 요청을 Amazon Bedrock 같은 백엔드로 라우팅합니다.
기존 구성 확인하기
관리자가 테스트한 Codex 클라이언트와 버전을 설치하세요. 조직에서 설정을 관리하는 경우 해당 클라이언트를 열고 인계받은 안내에 따라 로그인 단계를 완료하세요. 아래의 공급자 구성 예시는 건너뛰어도 됩니다.
- CLI에서는 선택된 프로필을 확인하고
codex doctor를 실행하세요. 시작 후에는/status를 사용해 활성 모델과 공급자를 확인하세요. - macOS 앱에서는
~/.codex/config.toml또는 조직에서 배포하는 관리형 구성을 확인하세요. - Windows 앱에서는
%USERPROFILE%\.codex\config.toml또는 조직에서 배포하는 시스템 구성을 확인하세요.
예상한 게이트웨이 공급자와 모델이 이미 활성화되어 있다면 관리자가 제공한 로그인 단계를 완료한 다음 연결 확인으로 진행하세요. 관리되는 컴퓨터에 두 번째 공급자 구성을 추가하지 마세요. 설정이 관리자에게 인계받은 안내와 다르다면 로컬 파일을 편집하기 전에 어느 구성 계층에서 해당 설정을 제공해야 하는지 문의하세요.
게이트웨이 연결 정보 받기
수동으로 설정하려면 ChatGPT 워크스페이스 로그인, 게이트웨이 인증 또는 둘 다 필요한지 확인하세요.
Codex를 직접 구성하려면 게이트웨이 담당 팀에서 다음 값을 받으세요.
https://gateway.example.com/v1과 같이 API 경로를 포함한 HTTPS 게이트웨이 기본 URL.- 사용할 모델 이름과 공급자 ID.
- 인증 방법: 네이티브 게이트웨이 OAuth, 범위가 지정된 API key 및 해당 환경 변수 또는 설치된 자격 증명 도우미.
- OAuth의 경우 인증 URL, 토큰 URL, 공개 클라이언트 ID, 필요한 범위. 쿠키나 사용자 지정 헤더를 사용하는 게이트웨이의 경우 해당 이름.
- 필요한 모델 카탈로그 URL 또는 카탈로그 파일과 해당 파일의 절대 로컬 경로.
공급자 구성하기
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"
requires_openai_auth = false그런 다음 게이트웨이 팀에서 제공하는 인증 설정을 추가합니다.
enterprise-gateway은 예시 공급자 ID입니다. 동일한 ID를
model_provider 및 해당 공급자와 인증 테이블에 사용하세요.
이 예시에서는 웹 검색을 비활성화하여
초기 연결을 테스트합니다. 관리자는 웹 검색을 활성화하기 전에
기능 지원 여부를 확인해야 합니다.
모델 카탈로그 구성
Codex가 선택한 모델의 기능과 지침을 가져오는 방법을 게이트웨이 팀에 확인하세요:
- 내장 이름: 게이트웨이가 사용 중인 Codex 버전에 포함된 정확한 모델 이름을 받아 해당 모델로 라우팅한다면,
model을 해당 이름으로 설정하세요. Codex에는 이미 해당 모델의 메타데이터가 있습니다. - 카탈로그 엔드포인트: 게이트웨이가 Codex 호환 메타데이터를 제공한다면, 전체 카탈로그 URL을 사용하세요. Codex 카탈로그 응답을 구현하는
/v1/models엔드포인트를 사용할 수 있습니다. 모델 ID만 나열하는 응답으로는 사용자 지정 별칭을 지원하기에 충분하지 않습니다. - 카탈로그 파일: 게이트웨이가 사용자 지정 별칭을 사용하고 관리자가 파일을 배포한다면, 로컬 models.json 예제를 사용하세요. 네이티브 게이트웨이 OAuth가 유일한 인증 수단이고 사용자 지정 메타데이터가 필요하다면 로컬 파일을 사용하세요.
API key 또는 도우미 인증을 사용하는 경우, 관리자가 카탈로그
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 key를 사용합니다. 조직에서 명령을 제공하는 경우 자격 증명 도우미를 사용합니다.
{/* prettier-ignore */}
네이티브 게이트웨이 OAuth 사용
게이트웨이 OAuth는 ChatGPT 로그인과 독립적으로 작동합니다. 게이트웨이가 Microsoft Entra ID 같은 조직의 ID 공급자가 발급한 액세스 토큰을 허용할 때 사용합니다. Codex는 브라우저 로그인과 암호화된 자격 증명 저장을 처리하며, 인증 서버가 새로 고침 토큰을 발급하면 토큰 갱신도 처리합니다.
게이트웨이 인증만 사용하는 경우, Codex CLI 0.166.0 이상은 기본적으로 Authorization: Bearer <gateway access token>에 액세스 토큰을 담아 전송합니다. 이 공급자의 http_headers 또는 env_http_headers에서 Authorization 항목을 모두 제거하세요.
게이트웨이 팀은 PKCE를 사용하는 인가 코드 흐름을 지원하는 공개 OAuth 클라이언트를
등록해야 합니다. 다음 테이블을 공급자 설정에 추가하고,
config.toml의 URL과 클라이언트 ID를 해당 값으로 바꾸세요:
[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이 테이블에 scopes와 필요한 경우 resource를 추가하고,
ID 공급자와 게이트웨이에서 요구하는 값을 사용합니다. 공급자가 새로 고침 토큰에 필요한
범위를 요구하면 해당 범위를 요청합니다. Codex는 기본적으로 사용 가능한 루프백 포트를 사용합니다.
ID 공급자가 고정 리디렉션 URI를 요구하면 redirect_port를 설정하고
이 예제에서는 http://127.0.0.1:43127/callback을 등록합니다.
게이트웨이가 쿠키나 사용자 지정 헤더를 요구한다면, OAuth 테이블에 선택 사항인 delivery 필드를 설정하세요. 게이트웨이가 검증하는 방식을 선택하세요:
delivery = { kind = "cookie", name = "auth-openid" }delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }배포 환경에서 ChatGPT 로그인도 필요하다면, 위에 나온 쿠키 또는 별도의 게이트웨이 헤더를 사용하세요. ChatGPT 로그인 활성화를 참고하세요.
고정 API key만 허용하는 게이트웨이는 이 흐름을 사용하기 전에 OAuth 토큰과 그 전달 방식을 지원하도록 수정해야 합니다. 게이트웨이는 Bedrock용 AWS 자격 증명과 같은 자체 업스트림 자격 증명을 계속 관리합니다.
OAuth가 유일한 인증 수단이라면 requires_openai_auth = false을 유지하고,
게이트웨이 자격 증명에 사용하던 기존 env_key, experimental_bearer_token 또는 auth 설정을
제거하세요. 사용자 지정 모델 메타데이터가 필요하다면 로컬 모델 카탈로그를
사용하세요. OAuth만으로는 원격 카탈로그를 검색할 수 없습니다.
데스크톱 앱을 다시 시작하고 게이트웨이 로그인 안내에 따라 브라우저를 엽니다.
CLI에서는 codex를 시작하고 Codex가 게이트웨이에 처음 액세스할 때
브라우저 로그인 절차를 따릅니다. 조직의 로그인과 MFA를 완료한 다음
클라이언트로 돌아옵니다. 권한 부여가 만료되거나 Codex가 갱신할 수 없으면 안내에 따라 다시 로그인합니다.
네이티브 게이트웨이 OAuth에는 브라우저와 연결 가능한 루프백 콜백이 필요합니다.
디바이스 코드 방식으로 전환하는 기능은 없습니다. SSH를 통해 CLI를 실행하는 경우
OAuth 테이블에 redirect_port = 43127을 설정하고 위에서 설명한 해당 리디렉션 URI를 등록합니다.
브라우저가 있는 컴퓨터에서 Codex를 시작하기 전에 해당 포트를 포워딩합니다.
ssh -L 43127:127.0.0.1:43127 user@remote해당 SSH 세션에서 codex를 시작하고 로컬 브라우저에서 게이트웨이 로그인 URL을
엽니다. 컨테이너 내의 CLI에도 브라우저에서 연결할 수 있는 콜백이
필요합니다. 콜백에 연결할 수 있도록 설정할 수 없다면 API key 또는 자격 증명
도우미를 대신 사용합니다.
API key 사용
게이트웨이가 Authorization 헤더에 API key를 요구하는 경우 이 설정을 사용하세요.
기존 테이블에 다음 설정을 추가하세요.
[model_providers.enterprise-gateway]:
env_key = "CODEX_GATEWAY_API_KEY"조직의 비밀 정보 전달 메커니즘을 사용해 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에 대한 자세한 내용은 구성 참조를
참고하세요.
ChatGPT 로그인을 사용하는 경우 Codex가 사용자의 OpenAI 자격 증명을 Authorization에 담아 보낼 수 있도록 게이트웨이 키에는 사용자 지정 헤더를 사용하세요.
사용자 지정 헤더가 유일한 인증 메커니즘인 경우
model_catalog_json을 사용하세요. 원격 카탈로그 검색은 실행되지 않습니다.
조직의 자격 증명 도우미 사용하기
관리자가 명령 기반 인증을 제공하는 경우 설치된 관리자의
도우미와 구성을 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사용자 지정 공급자 인증 참조에는 명령, 인수, 제한 시간, 갱신 간격, 토큰 출력 규약이 정의되어 있습니다. 도우미가 더 이상 토큰을 가져오지 못하면 관리자에게 로그인 갱신 방법을 문의하세요.
ChatGPT 로그인을 사용하는 경우 auth 테이블을 구성하는 대신 Codex를 시작하기 전에 도우미를 실행하고 사용자 지정 게이트웨이 헤더를 통해 출력을 전달하세요. 키가 만료되면 새 키를 발급받고 Codex를 다시 시작하세요.
도우미 실행 파일과 카탈로그 파일에는 실제 위치로 해석된 절대 경로를 사용하세요.
ChatGPT 로그인 활성화(권장)
조직에서 ChatGPT 워크스페이스를 사용하는 경우 사용자는 로그인하여 OpenAI 제공 플러그인 등 이용 자격이 있는 기능에 접근할 수 있습니다. 워크스페이스의 제어 설정이 적용되며, 모델 요청은 계속 게이트웨이가 처리합니다. 기능 이용 가능 여부 비교.
수동으로 설정하려면 로그인하기 전에 기존 [model_providers.enterprise-gateway] 테이블을 업데이트하세요:
requires_openai_auth = true을 설정하고base_url이 게이트웨이를 가리키도록 유지하세요. Codex가 기본 인증에 OpenAI 자격 증명을 사용하도록env_key,experimental_bearer_token및 공급자의auth설정을 모두 제거하세요.- 게이트웨이 자격 증명은 별도로 전송하세요. 네이티브 게이트웨이 OAuth의 경우, 게이트웨이가 허용하는 쿠키 또는 사용자 지정 헤더를 사용하도록
gateway_oauth.delivery를 설정하세요. API key 또는 자격 증명 도우미의 경우, 사용자 지정 인증 헤더를 사용하세요.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 server, 플러그인도 다른 네트워크 경로를 사용할 수 있습니다.
클라이언트 시작
ChatGPT 로그인을 사용하는 경우 클라이언트를 시작하고 관리형 구성을 제공하는 워크스페이스에 로그인하세요. 네이티브 게이트웨이 OAuth를 사용하는 경우 메시지가 표시되면 조직의 게이트웨이 로그인도 완료하세요. 그런 다음 연결을 확인하세요.
로컬에서 구성한 공급자를 사용하는 경우 해당 클라이언트의 지침을 따르세요.
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 = 300000Windows TOML에서 작은따옴표로 묶인 리터럴 문자열은 백슬래시를 그대로 보존합니다.
Unix 카탈로그 경로도 바꾸세요. 예를 들어,
'C:\ProgramData\OpenAI\Codex\models.json'처럼 관리자가 제공한 실제 경로를
사용하세요.
MCP server와 플러그인은 별도로 구성하세요. 모델 게이트웨이 자격 증명은 도구나 연결된 시스템에 대한 액세스 권한을 부여하지 않습니다.
연결 확인하기
관리자가 전달한 공급자 ID와 모델 별칭을 사용하세요. 공급자는 설정된 연결을 식별하고, 모델 별칭은 해당 연결을 통해 라우팅되는 모델을 식별합니다. ChatGPT 로그인과 게이트웨이 인증은 액세스를 제어하며, 둘 다 필요할 수 있습니다.
구성을 변경한 후 클라이언트를 다시 시작하세요. CLI에서는 codex를 시작하고
/status를 사용해 활성 모델과 공급자를 살펴보세요. 데스크톱 앱에서는
선택된 모델과 구성을 확인하세요.
새 작업에서 다음 프롬프트를 보내세요.
Reply with exactly: gateway-ok예상 응답은 gateway-ok입니다. 응답만으로는 어떤 경로에서 처리했는지 입증할 수 없습니다.
게이트웨이가 사용자, 모델 별칭, 의도한 업스트림 경로를 기록했는지
관리자에게 확인을 요청하세요. 모델에 이름을 물어서 모델을 식별하지 마세요.
연결 문제 해결하기
| 증상 | 확인 사항 |
|---|---|
| 예상한 공급자가 활성화되지 않습니다. | 선택한 프로필과 구성 우선순위를 확인하세요. 최상위 키가 공급자 테이블 안에 들어 있지 않은지 확인하세요. |
| OAuth 로그인 또는 토큰 전달에 실패합니다. | 공개 클라이언트 등록, 리디렉션 URI, 범위, 구성된 쿠키 또는 헤더를 확인하세요. 게이트웨이가 발급된 액세스 토큰을 허용하는지 확인하세요. |
| API key 또는 도우미 인증에 실패합니다. | 자격 증명 변수가 클라이언트 프로세스에 전달되는지, 또는 설치된 도우미가 유효한 토큰을 가져올 수 있는지 확인하세요. 관리자에게 게이트웨이 인증과 업스트림 인증을 구분해 확인하도록 요청하세요. |
| 모델을 찾을 수 없습니다. | 제공된 모델 이름을 확인하고 관리자에게 해당 경로를 확인하도록 요청하세요. |
| 모델이 예상과 다른 기능을 사용합니다. | 관리자에게 카탈로그 메타데이터가 별칭이 가리키는 모델과 일치하는지 확인하도록 요청하세요. |
| 스트리밍이 멈추거나 후속 요청에 실패합니다. | 게이트웨이 담당자에게 프록시 버퍼링, 종료 response.completed 이벤트, 게이트웨이 호환성을 확인하도록 요청하세요. |
| 카탈로그 또는 도우미 경로에 문제가 있습니다. | Codex가 실행되는 환경에서 구성된 절대 경로에 파일이 있는지 확인하세요. |
도움을 요청할 때는 클라이언트 버전, 운영 체제, 예상 공급자와 모델 별칭, 인증 방법, 실패한 단계를 포함하세요. 게이트웨이 담당자가 요청을 찾을 수 있도록 오류 메시지와 요청 시간도 포함하세요. 토큰, 쿠키, 인증 헤더, 민감한 프롬프트는 제거하세요. 자격 증명 파일이나 비밀 정보가 포함된 설정 덤프를 보내지 마세요.
기존 게이트웨이 배포 사용하기
게이트웨이 팀에 Codex 공급자 설정과 승인된 모델 별칭을 요청하세요. 팀에서 아직 Codex 경로를 활성화해야 한다면, 관리자 마이그레이션 체크리스트를 공유하세요.