인증

OpenAI 인증

Codex는 OpenAI 모델을 사용할 때 두 가지 로그인 방식을 지원합니다.

구독 접근을 위한 ChatGPT 로그인
사용량 기반 접근을 위한 API 키 로그인

Codex cloud는 ChatGPT 로그인이 필요합니다. Codex CLI와 IDE 확장은 두 로그인 방식을 모두 지원합니다.

로그인 방식은 적용되는 관리자 제어와 데이터 처리 정책도 결정합니다.

ChatGPT로 로그인하면 Codex 사용량은 ChatGPT 워크스페이스 권한, RBAC, ChatGPT Enterprise retention 및 residency 설정을 따릅니다.
API 키로 로그인하면 사용량은 대신 API 조직의 retention 및 data-sharing 설정을 따릅니다.

CLI에서는 유효한 세션이 없을 때 ChatGPT 로그인이 기본 인증 경로입니다.

ChatGPT로 로그인

Codex 앱, CLI, IDE 확장에서 ChatGPT로 로그인하면 Codex가 브라우저 창을 열어 로그인 흐름을 완료하게 합니다. 로그인 후 브라우저는 access token을 CLI 또는 IDE 확장으로 반환합니다.

API 키로 로그인

Codex 앱, CLI, IDE 확장에 API 키로 로그인할 수도 있습니다. API 키는 OpenAI dashboard에서 가져옵니다.

OpenAI는 API 키 사용량을 OpenAI Platform 계정에 표준 API 요금으로 청구합니다.

빠른 모드처럼 ChatGPT credit에 의존하는 기능은 ChatGPT로 로그인한 경우에만 사용할 수 있습니다. API 키로 로그인하면 Codex는 대신 표준 API 가격을 사용합니다.

프로그래밍 방식 Codex CLI 워크플로, 예: CI/CD job, 에는 API 키 인증을 사용하는 것이 좋습니다. 신뢰할 수 없거나 공개 환경에 Codex 실행을 노출하지 마십시오.

Codex cloud 계정 보안

Codex cloud는 코드베이스와 직접 상호작용하므로 다른 많은 ChatGPT 기능보다 더 강한 보안이 필요합니다. 다중 인증(MFA)을 활성화하십시오.

Google, Microsoft, Apple 같은 social login provider를 사용한다면 ChatGPT 계정에서 MFA를 활성화할 필요는 없지만, social login provider에서 설정할 수 있습니다.

설정 방법:

SSO로 ChatGPT에 접근한다면 조직의 SSO 관리자가 모든 사용자에게 MFA를 강제해야 합니다.

이메일과 비밀번호로 로그인하는 경우 Codex cloud에 접근하기 전에 계정에 MFA를 설정해야 합니다.

계정이 여러 로그인 방식을 지원하고 그중 하나가 이메일과 비밀번호라면, 다른 방식으로 로그인하더라도 Codex에 접근하기 전에 MFA를 설정해야 합니다.

로그인 캐싱

ChatGPT 또는 API 키로 Codex 앱, CLI, IDE 확장에 로그인하면 Codex는 로그인 정보를 cache하고 다음에 CLI나 확장을 시작할 때 재사용합니다. CLI와 확장은 같은 cached login details를 공유합니다. 둘 중 하나에서 로그아웃하면 다음에 CLI나 확장을 시작할 때 다시 로그인해야 합니다.

Codex는 로그인 정보를 ~/.codex/auth.json의 plaintext 파일 또는 OS별 credential store에 로컬 cache합니다.

ChatGPT 로그인 세션의 경우 Codex는 사용 중 만료 전에 token을 자동으로 refresh하므로, 활성 세션은 보통 다시 브라우저 로그인하지 않아도 계속됩니다.

자격 증명 저장

Codex CLI가 cached credential을 저장하는 위치는 cli_auth_credentials_store로 제어합니다.

# file | keyring | auto
cli_auth_credentials_store = "keyring"

file: credential을 CODEX_HOME 아래의 auth.json에 저장합니다. 기본값은 ~/.codex입니다.
keyring: 운영체제 credential store에 credential을 저장합니다.
auto: 사용할 수 있으면 OS credential store를 사용하고, 그렇지 않으면 auth.json으로 fallback합니다.

파일 기반 저장을 사용한다면 ~/.codex/auth.json을 비밀번호처럼 취급하십시오. access token이 포함되어 있습니다. commit하거나, ticket에 붙여 넣거나, chat에서 공유하지 마십시오.

로그인 방식 또는 워크스페이스 강제

관리형 환경에서는 관리자가 사용자가 인증할 수 있는 방식을 제한할 수 있습니다.

# ChatGPT 로그인만 허용하거나 API 키 로그인만 허용합니다.
forced_login_method = "chatgpt" # 또는 "api"

# ChatGPT 로그인을 사용할 때 사용자를 특정 워크스페이스로 제한합니다.
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

활성 credential이 구성된 제한과 일치하지 않으면 Codex는 사용자를 로그아웃시키고 종료합니다.

이 설정은 보통 사용자별 설정이 아니라 관리형 구성으로 적용됩니다.

로그인 진단

직접 실행한 codex login은 구성된 로그 디렉터리 아래에 전용 codex-login.log 파일을 씁니다. 브라우저 로그인 또는 device-code 실패를 디버깅해야 하거나 support가 로그인 관련 로그를 요청할 때 사용합니다.

사용자 지정 CA bundle

네트워크에서 corporate TLS proxy 또는 private root CA를 사용한다면 로그인하기 전에 CODEX_CA_CERTIFICATE를 PEM bundle로 설정합니다. CODEX_CA_CERTIFICATE가 설정되지 않으면 Codex는 SSL_CERT_FILE로 fallback합니다. 같은 사용자 지정 CA 설정은 로그인, 일반 HTTPS 요청, secure websocket 연결에 적용됩니다.

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

headless 기기에서 로그인

Codex CLI로 ChatGPT에 로그인할 때 브라우저 기반 로그인 UI가 작동하지 않을 수 있는 상황이 있습니다.

remote 또는 headless 환경에서 CLI를 실행 중입니다.
로그인 후 OAuth token을 CLI로 반환하는 localhost callback을 로컬 네트워킹 구성이 차단합니다.

이 경우 device code authentication(beta)을 선호합니다. 대화형 로그인 UI에서 Sign in with Device Code를 선택하거나 codex login --device-auth를 직접 실행합니다. device code authentication이 환경에서 작동하지 않으면 fallback 방법 중 하나를 사용합니다.

권장: device code authentication(beta)

ChatGPT 보안 설정(개인 계정) 또는 ChatGPT 워크스페이스 권한(워크스페이스 관리자)에서 device code login을 활성화합니다.
Codex를 실행 중인 터미널에서 다음 중 하나를 선택합니다.
- 대화형 로그인 UI에서 Sign in with Device Code를 선택합니다.
- codex login --device-auth를 실행합니다.
브라우저에서 링크를 열고 로그인한 뒤 일회성 코드를 입력합니다.

서버에서 device code login이 활성화되어 있지 않으면 Codex는 표준 브라우저 기반 로그인 흐름으로 fallback합니다.

fallback: 로컬에서 인증하고 auth cache 복사

브라우저가 있는 컴퓨터에서 로그인 흐름을 완료할 수 있다면 cached credential을 headless 컴퓨터로 복사할 수 있습니다.

브라우저 기반 로그인 흐름을 사용할 수 있는 컴퓨터에서 codex login을 실행합니다.
로그인 cache가 ~/.codex/auth.json에 있는지 확인합니다.
~/.codex/auth.json을 headless 컴퓨터의 ~/.codex/auth.json으로 복사합니다.

~/.codex/auth.json은 비밀번호처럼 취급하십시오. access token이 포함되어 있습니다. commit하거나, ticket에 붙여 넣거나, chat에서 공유하지 마십시오.

OS가 credential을 ~/.codex/auth.json 대신 credential store에 저장하는 경우 이 방법이 적용되지 않을 수 있습니다. 파일 기반 저장 구성 방법은 자격 증명 저장을 참고하십시오.

SSH로 원격 컴퓨터에 복사:

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

scp를 피하는 one-liner:

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

Docker container로 복사:

# MY_CONTAINER를 container 이름 또는 ID로 바꿉니다.
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

신뢰된 CI/CD runner에서 같은 패턴을 더 고급으로 사용하는 방법은 CI/CD에서 Codex 계정 auth 유지(고급)를 참고하십시오. 이 가이드는 일반 실행 중 Codex가 auth.json을 refresh하고 다음 job을 위해 업데이트된 파일을 유지하는 방법을 설명합니다. 자동화의 기본 권장은 여전히 API 키입니다.

fallback: SSH로 localhost callback 전달

로컬 컴퓨터와 원격 host 사이에 port forwarding을 할 수 있다면 Codex의 로컬 callback server, 기본값 localhost:1455, 를 tunnel해 표준 브라우저 기반 흐름을 사용할 수 있습니다.

로컬 컴퓨터에서 port forwarding을 시작합니다.

ssh -L 1455:localhost:1455 user@remote

해당 SSH 세션에서 codex login을 실행하고 로컬 컴퓨터에서 출력된 주소를 따릅니다.

대체 모델 provider

구성 파일에 사용자 지정 모델 provider를 정의할 때 다음 인증 방식 중 하나를 선택할 수 있습니다.

OpenAI 인증: OpenAI 인증을 사용하려면 requires_openai_auth = true를 설정합니다. 이후 ChatGPT 또는 API 키로 로그인할 수 있습니다. LLM proxy server를 통해 OpenAI 모델에 접근할 때 유용합니다. requires_openai_auth = true이면 Codex는 env_key를 무시합니다.
환경 변수 인증: 로컬 환경 변수 {ENV_VARIABLE_NAME}의 provider-specific API 키를 사용하려면 env_key = "{ENV_VARIABLE_NAME}"을 설정합니다.
인증 없음: requires_openai_auth를 설정하지 않거나 false로 설정하고 env_key도 설정하지 않으면 Codex는 provider가 인증을 요구하지 않는 것으로 가정합니다. 로컬 모델에 유용합니다.