Codex 액세스 토큰은 Codex 권한 범위로 제한된 ChatGPT 워크스페이스 자격 증명입니다. ChatGPT 워크스페이스 ID를 사용해 Codex CLI 및 App Server 기반 자동화를 비롯한 신뢰할 수 있는 비대화형 로컬 워크플로우를 인증합니다. 스크립트, 예약 작업 또는 CI 러너에서 반복적으로 로컬에 액세스해야 할 때 사용하세요.
Codex 액세스 토큰은 현재 ChatGPT Business 및 ChatGPT Enterprise 워크스페이스에서 지원됩니다.
ChatGPT 관리자 콘솔의 액세스 토큰 페이지에서 만든 개인 액세스 토큰은 이를 생성한 ChatGPT 사용자와 해당 사용자의 워크스페이스에 연결됩니다. 이 토큰은 프로그래밍 방식의 로컬 워크플로우에서 에이전트 ID 역할을 합니다. 사람 사용자가 아닌 전용 워크스페이스 ID의 상세 페이지에서 생성하는 토큰에 대해서는 서비스 계정을 참조하세요.
자동화에 Platform API 키를 사용할 수 있다면 API 키 인증을 계속 사용하세요. 신뢰할 수 있는 로컬 워크플로우에 ChatGPT 워크스페이스 액세스, 워크스페이스에서 관리하는 사용 자격 또는 엔터프라이즈 제어가 필요한 경우 Codex 액세스 토큰을 사용하세요.
자체 시스템에서 게시된 ChatGPT 워크스페이스 에이전트를 트리거해야 하나요? 그렇다면 Workspace Agents API용 Workspace Agent 액세스 토큰을 사용하세요. Codex 액세스 토큰은 Codex CLI 또는 App Server 클라이언트를 통해 신뢰할 수 있는 로컬 워크플로우를 인증하며, 워크스페이스 에이전트 트리거 호출은 인증하지 않습니다. 자세한 내용은 Workspace Agent 액세스 토큰을 사용한 인증을 참조하세요.
액세스 토큰 작동 방식
사용자가 브라우저 로그인을 완료하지 않아도 Codex CLI 또는 App Server 클라이언트를 실행해야 할 때 액세스 토큰을 사용하세요. 토큰은 이를 생성한 ChatGPT 워크스페이스 사용자를 나타내므로 실행 시 해당 사용자의 액세스 권한을 사용할 수 있으며, 실행 내역이 워크스페이스 거버넌스 데이터에 표시됩니다.
클라이언트는 실행이 시작될 때 토큰을 확인하고 해당 실행을 워크스페이스 ID에 연결합니다. 토큰을 다른 자동화 시크릿처럼 취급하세요. 시크릿 관리자에 저장하고 로그에 기록되지 않도록 하며 정기적으로 교체하세요.
액세스 토큰은 다음 용도로 사용하세요:
- 신뢰할 수 있는 자동화에서 실행되는
codex exec작업. - Codex CLI를 반복해서 비대화형으로 실행해야 하는 로컬 스크립트.
- 신뢰할 수 있는 App Server 기반 자동화.
- 사용 내역을 API 조직 키 대신 ChatGPT 워크스페이스 사용자와 연결해야 하는 엔터프라이즈 워크플로우.
피해야 할 주요 위험:
- 시크릿 유출: 토큰을 가진 사람은 누구나 토큰 생성자의 자격으로 Codex CLI 또는 App Server 클라이언트를 통해 로컬 실행을 시작할 수 있습니다. 토큰을 시크릿 관리자에 저장하고 로그에 남기지 않으며 정기적으로 교체하세요.
- 러너 신뢰성: 공개 CI, 포크된 Pull Request 또는 공유 머신을 사용하면 워크스페이스 외부 사용자에게 토큰이 노출될 수 있습니다. 액세스 토큰은 신뢰할 수 있는 러너에서만 사용하세요.
- 공유 ID: 한 사람의 토큰을 서로 관련 없는 팀에서 재사용하면 소유권과 감사 기록을 파악하기 어려워집니다. 특정 워크플로우 소유자를 위한 토큰을 만드세요.
- 오래된 자격 증명: 유효 기간이 긴 토큰은 워크플로우가 변경된 뒤에도 계속 활성 상태로 남을 수 있습니다. 유효 기간이 제한된 토큰을 우선 사용하고 더 이상 사용하지 않는 토큰은 폐기하세요.
- 잘못된 자격 증명 유형: Codex 액세스 토큰은 Codex CLI 또는 App Server 클라이언트를 통한 신뢰할 수 있는 로컬 자동화에 사용됩니다. 게시된 ChatGPT 워크스페이스 에이전트를 트리거하려면 Workspace Agent 액세스 토큰을 사용하고, 일반적인 OpenAI API 호출에는 Platform API 키를 사용하세요.
액세스 토큰 생성 활성화
워크스페이스 설정의 액세스 토큰 권한을 사용해 허용된 멤버가 액세스 토큰을 생성할 수 있도록 설정하세요.
액세스 토큰 권한은 토큰 생성을 제어합니다. 이 권한만으로는 ChatGPT 데스크톱 앱, Codex CLI 또는 IDE 확장의 사용 권한이 부여되지 않으며, 멤버의 시트 유형, 기본 제공 워크스페이스 역할 또는 로컬 런타임 권한 프로필도 변경되지 않습니다. 필요에 따라 해당 제어 항목을 구성하세요.
이러한 제어 항목 간의 관계에 대한 자세한 내용은 역할 및 워크스페이스 권한을 참조하세요.
- 워크스페이스 설정 > 권한 및 역할로 이동하세요.
- 허용된 모든 멤버가 액세스 토큰을 만들 수 있어야 한다면 액세스 토큰 섹션에서 사용자가 액세스 토큰을 만들 수 있도록 허용 설정을 켜세요.
- 워크플로우에 해당 로컬 인터페이스도 필요한 경우, 멤버의 Codex 로컬 사용 허용 설정이 Codex 로컬 섹션에서 켜져 있는지 확인하세요. 이 설정은 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장의 로컬 사용에 적용됩니다.
토큰의 저장 위치, 토큰을 사용할 자동화, 교체 방법을 이해하는 사람이나 서비스 소유자만 액세스 토큰을 생성할 수 있도록 제한하세요.
액세스 토큰 만료 기간 제한 설정
워크스페이스 소유자와 관리자는 멤버가 Codex 액세스 토큰을 생성할 때 선택할 수 있는 최대 만료 기간을 설정할 수 있습니다. 워크스페이스 설정 > 권한 및 역할로 이동한 다음, 액세스 토큰 만료 기간 제한 항목을 Codex 로컬 섹션에서 설정하세요.
이 제한은 새 액세스 토큰에 적용됩니다. 기존 토큰의 만료 시점은 변경되지 않습니다.
액세스 토큰 만들기
액세스 토큰 페이지에서 토큰 이름을 지정하고 만료 시점을 선택하세요.
- 액세스 토큰으로 이동하세요.
- 만들기를 선택하세요.
release-ci또는nightly-docs-check처럼 용도를 알 수 있는 이름을 입력하세요.
- 만료 기간을 선택하세요. 가능하면 7일, 30일, 60일 또는 90일처럼 만료 기간이 정해진 옵션을 선택하세요. 만료 없음을 선택했다면 정해진 일정에 따라 토큰을 교체하세요.
- 만들기를 선택하세요.
- 생성된 액세스 토큰을 즉시 복사하세요. 모달을 닫으면 다시 확인할 수 없습니다.
- 토큰을 시크릿 관리자 또는 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의 안내에 따라 설정하세요. Codex 액세스 토큰을
전송 토큰으로 재사용하지 마세요. 자세한 내용은
인증 및 네트워크 환경 변수를 참조하세요.
토큰 교체 또는 폐기
다른 자동화 시크릿과 같은 방식으로 액세스 토큰을 교체하세요:
- 대체 토큰을 만드세요.
- 러너, 스케줄러 또는 시크릿 관리자에서 시크릿을 업데이트하세요.
- 새 토큰으로 스모크 테스트를 실행하세요.
- 액세스 토큰에서 이전 토큰을 폐기하세요.
액세스 토큰 페이지에서 워크스페이스 소유자와 관리자는 워크스페이스 내 어떤 토큰이든 폐기할 수 있습니다. 액세스 토큰 권한이 있는 멤버는 자신이 생성한 토큰만 폐기할 수 있습니다.
권한 모델
워크스페이스 액세스 토큰 권한은 토큰 생성을 제어합니다. 멤버의 Codex 로컬 사용 허용 워크스페이스 권한은 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장의 로컬 사용 권한을 별도로 제어합니다. 멤버는 액세스 토큰 생성 권한이 없어도 이러한 로컬 사용 권한을 가질 수 있습니다.
| 기능 | 워크스페이스 소유자 및 관리자 | 액세스 토큰 권한이 있는 멤버 | 액세스 토큰 권한이 없는 멤버 |
|---|---|---|---|
| 액세스 토큰 열기 | 예 | 예 | 아니요 |
| 액세스 토큰 생성 | 예, 자신의 ChatGPT 워크스페이스 사용자 자격으로만 | 예, 자신의 ChatGPT 워크스페이스 사용자 자격으로만 | 아니요 |
| 액세스 토큰 목록 조회 | 각 토큰의 생성자 정보가 포함된 워크스페이스 전체 토큰 목록 | 자신이 생성한 토큰만 | 아니요 |
| 액세스 토큰 페이지에서 액세스 토큰 취소 | 워크스페이스 내 모든 토큰 | 자신이 생성한 토큰만 | 페이지 접근 권한 없음 |
| 액세스 토큰 권한 부여 또는 제거 | 예 | 아니요 | 아니요 |
| 기타 로컬 클라이언트 또는 Codex 클라우드 설정 관리 | 예, 워크스페이스 관리자 권한에 따라 | 아니요, 별도로 권한을 부여받은 경우 제외 | 아니요 |
요약하면, 워크스페이스 소유자와 관리자는 워크스페이스 수준에서 액세스 권한을 관리합니다. 멤버가 자신의 토큰을 생성하고 관리하려면 액세스 토큰 권한이 필요하지만, 이 권한으로 관리자 권한이나 다른 멤버의 토큰에 대한 접근 권한이 부여되지는 않습니다.
문제 해결
액세스 토큰 페이지에 404 또는 접근 금지 오류가 표시됨
워크스페이스 소유자나 관리자에게 본인의 역할에 사용자의 액세스 토큰 생성 허용 권한이 포함되어 있는지 확인해 달라고 요청하세요. 워크플로우에서 해당 로컬 환경도 사용해야 한다면 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장에서 로컬 기능을 사용할 수 있도록 멤버의 Codex 로컬 사용 허용 설정이 활성화되어 있는지 확인하세요.
codex login --with-access-token 실패
브라우저 세션 토큰이나 Platform API 키가 아니라 생성된 액세스 토큰을 복사했는지 확인하세요. 토큰이 만료되거나 취소되지 않았는지도 확인하세요.