액세스 토큰

Codex 액세스 토큰은 Codex 권한 범위로 제한된 ChatGPT 워크스페이스 자격 증명입니다. 이 토큰은 Codex CLI 및 app-server 기반 자동화를 비롯해 신뢰할 수 있는 비대화형 로컬 워크플로를 ChatGPT 워크스페이스 ID로 인증합니다. 스크립트, 예약 작업 또는 CI 러너에 반복 가능한 로컬 액세스가 필요할 때 사용하세요.

액세스 토큰은 ChatGPT 관리 콘솔의 액세스 토큰에서 생성합니다. 토큰은 토큰을 생성한 ChatGPT 사용자 및 해당 사용자의 워크스페이스에 연결됩니다. 이 토큰은 프로그래매틱 로컬 워크플로에서 에이전트 ID 역할을 합니다.

액세스 토큰의 작동 방식

사용자가 브라우저 로그인을 완료하지 않은 상태에서 Codex CLI 또는 app-server 클라이언트를 실행해야 할 때 액세스 토큰을 사용하세요. 토큰은 토큰을 생성한 ChatGPT 워크스페이스 사용자를 나타내므로, 실행 시 해당 사용자의 액세스 권한을 사용할 수 있으며 워크스페이스 거버넌스 데이터에도 기록될 수 있습니다.

클라이언트는 실행이 시작될 때 토큰을 확인하고 해당 실행을 그 워크스페이스 ID에 연결합니다. 토큰을 다른 자동화 비밀 정보와 동일하게 취급하세요. 비밀 관리자에 저장하고 로그에 남지 않도록 하며 정기적으로 교체하세요.

다음 용도로 액세스 토큰을 사용하세요.

• 신뢰할 수 있는 자동화에서 실행되는 codex exec 작업.
• 반복 가능한 비대화형 Codex CLI 실행이 필요한 로컬 스크립트.
• 신뢰할 수 있는 app-server 기반 자동화.
• 사용량을 API 조직 키가 아닌 ChatGPT 워크스페이스 사용자와 연결해야 하는 엔터프라이즈 워크플로.

피해야 할 주요 위험은 다음과 같습니다.

• 비밀 정보 유출: 토큰을 가진 사람은 누구나 토큰 생성자의 권한으로 Codex CLI 또는 app-server 클라이언트를 통해 로컬 실행을 시작할 수 있습니다. 토큰을 비밀 관리자에 저장하고 로그에 남지 않도록 하며 정기적으로 교체하세요.
• 러너 신뢰성: 공개 CI, 포크된 풀 리퀘스트 또는 공유 컴퓨터에서는 워크스페이스 외부 사람에게 토큰이 노출될 수 있습니다. 액세스 토큰은 신뢰할 수 있는 러너에서만 사용하세요.
• 공유 ID: 한 사람의 토큰을 관련 없는 여러 팀에서 재사용하면 소유권과 감사 추적을 해석하기 어려워집니다. 특정 워크플로 소유자별로 토큰을 생성하세요.
• 오래된 자격 증명: 수명이 긴 토큰은 워크플로가 변경된 후에도 계속 활성 상태로 남을 수 있습니다. 기한이 설정된 토큰을 사용하고 더 이상 사용하지 않는 토큰은 취소하세요.
• 잘못된 자격 증명 유형: Codex 액세스 토큰은 Codex CLI 또는 app-server 클라이언트를 통한 신뢰할 수 있는 로컬 자동화용입니다. 게시된 ChatGPT 워크스페이스 에이전트를 트리거하려면 Workspace Agent 액세스 토큰을 사용하고, 일반적인 OpenAI API 호출에는 Platform API key를 사용하세요.

액세스 토큰 생성 활성화

워크스페이스 설정의 액세스 토큰 권한을 사용해 허용된 구성원의 액세스 토큰 생성을 활성화하세요.

액세스 토큰 권한은 토큰 생성을 제어합니다. 이 권한은 ChatGPT 데스크톱 앱, Codex CLI 또는 IDE 확장 프로그램에 대한 액세스를 부여하지 않으며, 구성원의 시트 유형, 기본 제공 워크스페이스 역할 또는 로컬 런타임 권한 프로필도 변경하지 않습니다. 필요에 따라 이러한 제어를 구성하세요.

이러한 제어 간의 관계는 역할 및 워크스페이스 권한을 참조하세요.

1. 워크스페이스 설정 > 권한 및 역할로 이동합니다.
2. 허용된 모든 구성원이 액세스 토큰을 생성할 수 있어야 한다면 액세스 토큰 섹션에서 사용자의 액세스 토큰 생성 허용을 켭니다.
3. 워크플로에 적용 대상 로컬 환경도 필요하다면 Codex Local 섹션에서 구성원의 Codex Local 사용 허용이 켜져 있는지 확인합니다. 이 제어는 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램에서의 로컬 사용에 적용됩니다.

토큰이 저장될 위치, 토큰을 사용할 자동화 및 토큰 교체 방법을 이해하는 사람이나 서비스 소유자만 액세스 토큰을 생성할 수 있도록 제한하세요.

액세스 토큰 만료 한도 설정

워크스페이스 소유자와 관리자는 구성원이 Codex 액세스 토큰을 생성할 때 선택할 수 있는 최장 만료 기간을 설정할 수 있습니다. 워크스페이스 설정 > 권한 및 역할로 이동한 다음 Codex Local 섹션에서 액세스 토큰 만료 한도를 설정하세요.

이 한도는 새 액세스 토큰에 적용됩니다. 기존 토큰은 현재 만료 시점을 그대로 유지합니다.

액세스 토큰 생성

액세스 토큰 페이지에서 토큰 이름을 지정하고 만료 시점을 선택하세요.

1. 액세스 토큰으로 이동합니다.
2. 생성을 선택합니다.

3. release-ci 또는 nightly-docs-check처럼 용도를 알 수 있는 이름을 입력합니다.

4. 만료 기간을 선택합니다. 7일, 30일, 60일 또는 90일처럼 유한한 만료 기간을 권장합니다. 만료 없음을 선택한 경우 정기적인 일정에 따라 토큰을 교체하세요.
5. 생성을 선택합니다.
6. 생성된 액세스 토큰을 즉시 복사합니다. 모달을 닫은 후에는 다시 볼 수 없습니다.
7. 토큰을 비밀 관리자 또는 CI 비밀 정보 저장소에 저장합니다.

사용자 지정 만료 기간은 최소 하루입니다. 취소되거나 만료된 토큰으로는 인증이 필요한 새 실행을 시작할 수 없습니다.

Codex CLI에서 액세스 토큰 사용

임시 자동화의 경우 토큰을 CODEX_ACCESS_TOKEN에 저장하고 Codex CLI를 평소와 같이 실행합니다.

export CODEX_ACCESS_TOKEN="<access-token>"
codex exec --json "review this repository and summarize the top risks"

지속적인 로컬 로그인을 설정하려면 토큰을 codex login --with-access-token으로 파이프합니다.

printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token
codex exec "summarize the last release diff"

codex login --with-access-token은 Codex CLI 인증 저장소에 에이전트 ID 자격 증명을 저장합니다. 컴퓨터에 자격 증명을 유지하지 않으려면 대신 CODEX_ACCESS_TOKEN 환경 변수를 사용하세요.

codex app-server은 CODEX_ACCESS_TOKEN 또는 codex login --with-access-token으로 생성한 로그인을 통해 동일한 자격 증명을 사용하여 OpenAI 요청을 인증할 수 있습니다. 이 자격 증명은 클라이언트와 app-server 간 전송 인증과는 별개입니다. 원격 WebSocket 연결의 경우 App server에서 설명한 대로 별도의 bearer 또는 capability 토큰을 구성하세요. Codex 액세스 토큰을 전송 토큰으로 재사용하지 마세요. 자세한 내용은 인증 및 네트워크 환경 변수를 참조하세요.

토큰 교체 또는 취소

다른 자동화 비밀 정보를 교체하는 것과 같은 방식으로 액세스 토큰을 교체하세요.

1. 대체 토큰을 생성합니다.
2. 러너, 스케줄러 또는 비밀 관리자에서 비밀 정보를 업데이트합니다.
3. 새 토큰으로 스모크 테스트를 실행합니다.
4. 액세스 토큰에서 이전 토큰을 취소합니다.

액세스 토큰 페이지에서 워크스페이스 소유자와 관리자는 워크스페이스의 모든 토큰을 취소할 수 있습니다. 액세스 토큰 권한이 있는 구성원은 자신이 생성한 토큰만 취소할 수 있습니다.

권한 모델

워크스페이스 액세스 토큰 권한은 토큰 생성을 제어합니다. 구성원의 Codex Local 사용 허용 워크스페이스 권한은 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램에서의 로컬 액세스를 별도로 제한합니다. 구성원은 액세스 토큰 생성 권한 없이도 이러한 로컬 액세스 권한을 가질 수 있습니다.

요약하면 워크스페이스 소유자와 관리자는 워크스페이스 수준에서 액세스를 관리합니다. 구성원이 자신의 토큰을 생성하고 관리하려면 액세스 토큰 권한이 필요하지만, 이 권한으로 관리자 권한이나 다른 구성원의 토큰에 대한 액세스 권한이 부여되지는 않습니다.

문제 해결

액세스 토큰 페이지에서 404 또는 접근 금지 오류가 반환됨

워크스페이스 소유자나 관리자에게 자신의 역할에 사용자의 액세스 토큰 생성 허용이 포함되어 있는지 확인해 달라고 요청하세요. 워크플로에 적용 대상 로컬 환경도 필요하다면 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램에서 로컬로 사용할 수 있도록 구성원의 Codex Local 사용 허용이 활성화되어 있는지 확인하세요.

codex login --with-access-token 실패

브라우저 세션 토큰이나 Platform API key가 아니라 생성된 액세스 토큰을 복사했는지 확인하세요. 또한 토큰이 만료되거나 취소되지 않았는지 확인하세요.

관련 문서

• 인증
• 비대화형 모드
• 관리자 도입 가이드
• 그룹 및 프로비저닝
• 역할 및 워크스페이스 권한
• 거버넌스