액세스 토큰

Codex 액세스 토큰은 권한 범위가 Codex로 제한된 ChatGPT 워크스페이스 자격 증명입니다. 신뢰할 수 있는 비대화형 로컬 워크플로우에서 이 토큰을 사용하면 Codex CLI나 App Server 기반 자동화를 ChatGPT 워크스페이스 계정으로 인증할 수 있습니다. 스크립트, 예약 작업 또는 CI 러너에서 로컬 Codex에 반복적으로 액세스해야 할 때 사용하세요.

ChatGPT 관리 콘솔의 액세스 토큰 페이지에서 개인 액세스 토큰을 생성하세요. 각 토큰은 토큰을 생성한 사용자와 해당 사용자의 ChatGPT 워크스페이스에 속합니다. 프로그래밍 방식으로 실행하는 로컬 워크플로우에서는 토큰이 에이전트의 신원을 나타냅니다. 자동화 전용 워크스페이스 계정의 상세 페이지에서 생성하는 토큰에 대해서는 서비스 계정을 참고하세요.

액세스 토큰의 작동 방식

사용자가 브라우저에서 로그인하지 않고 Codex CLI 또는 App Server 클라이언트를 실행해야 할 때 액세스 토큰을 사용하세요. 토큰은 이를 생성한 ChatGPT 워크스페이스 사용자를 나타냅니다. 따라서 해당 사용자의 권한으로 작업을 실행할 수 있으며, 실행 기록은 워크스페이스 거버넌스 데이터에 표시될 수 있습니다.

클라이언트는 실행을 시작할 때 토큰을 확인하고 해당 실행을 워크스페이스 계정에 연결합니다. 다른 자동화 시크릿과 마찬가지로 토큰을 시크릿 관리자에 보관하고, 로그에 남기지 말고, 조직 정책에 따라 교체하세요.

다음과 같은 경우에 액세스 토큰을 사용하세요.

• 신뢰할 수 있는 자동화 환경에서 실행하는 codex exec 작업
• Codex CLI를 비대화형으로 반복 실행해야 하는 로컬 스크립트
• 신뢰할 수 있는 App Server 기반 자동화
• 사용량을 API 조직 키 대신 ChatGPT 워크스페이스 사용자와 연결하는 엔터프라이즈 워크플로우

다음 위험에 유의하세요.

• 시크릿 유출: 토큰을 가진 사람은 누구나 토큰 생성자의 계정으로 Codex CLI나 App Server 클라이언트를 통해 로컬 작업을 시작할 수 있습니다. 토큰을 시크릿 관리자에 보관하고, 로그에 남기지 말고, 조직 정책에 따라 교체하세요.
• 러너의 신뢰성: 공개 CI, 포크에서 제출한 Pull Request 또는 공유 머신을 통해 워크스페이스 외부 사용자에게 토큰이 노출될 수 있습니다. 신뢰할 수 있는 러너에서만 액세스 토큰을 사용하세요.
• 계정 공유: 서로 관련 없는 여러 팀에서 한 사람의 토큰을 재사용하면 담당자를 파악하거나 감사 기록을 추적하기 어렵습니다. 각 워크플로우의 담당자별로 토큰을 생성하세요.
• 사용하지 않는 자격 증명: 유효 기간이 긴 토큰은 워크플로우가 변경된 후에도 활성 상태로 남을 수 있습니다. 유효 기간이 정해진 토큰을 우선 사용하고, 더 이상 사용하지 않는 토큰은 폐기하세요.
• 잘못된 범위 또는 자격 증명 유형: Codex 자동화에는 Codex 액세스 권한이, 워크스페이스 에이전트 실행에는 워크스페이스 에이전트 액세스 권한이, 일반 OpenAI API 호출에는 Platform API 키가 필요합니다. 범위 항목이 표시되면 워크플로우에 필요한 권한만 부여하세요.

액세스 토큰 생성 허용하기

워크스페이스 설정에서 액세스 토큰 권한을 켜면 권한을 부여받은 멤버가 액세스 토큰을 생성할 수 있습니다.

액세스 토큰 권한은 토큰 생성을 제어합니다. 이 권한을 켜도 ChatGPT 데스크톱 앱, Codex CLI 또는 IDE 확장 프로그램에 대한 액세스 권한은 부여되지 않습니다. 멤버의 시트 유형, 기본 제공 워크스페이스 역할 또는 로컬 런타임 권한 프로필도 변경되지 않습니다. 토큰으로 인증하는 Codex CLI 및 App Server 워크플로우에는 사용자의 로컬 Codex 권한도 필요합니다.

각 설정의 관계는 역할 및 워크스페이스 권한을 참고하세요.

1. 워크스페이스 소유자에게 워크스페이스 설정 > 권한 및 역할을 열도록 요청하세요.
2. 액세스 토큰 섹션이 표시되면 사용자의 개인 액세스 토큰 생성 허용 옵션을 켜세요. 해당 섹션이 없으면 멤버의 Codex 액세스 토큰 사용 허용 옵션을 켜세요. 이 옵션은 Codex 및 Work 로컬 또는 Codex 로컬 섹션에 있습니다.
3. 워크플로우 담당자에게 해당하는 로컬 Codex 권한을 켜세요. 멤버의 로컬 Codex 및 Work 사용 허용 옵션은 Codex 및 Work 로컬 섹션에 있고, 멤버의 로컬 Codex 사용 허용 옵션은 Codex 로컬 섹션에 있습니다. Work 로컬 섹션이 따로 있는 경우 로컬에서 Work 사용 옵션은 Work를 제어하며, Codex 토큰을 사용하는 데는 필요하지 않습니다.

토큰을 어디에 보관하고 어떤 자동화에 사용할지, 언제 교체해야 하는지 아는 사용자나 서비스 담당자에게만 액세스 토큰 생성을 허용하세요.

로컬 Codex 권한을 끄면 해당 멤버가 소유한 활성 Codex 토큰은 일시 중지되지만 폐기되지는 않습니다. 로컬 Codex 액세스 권한을 복원하면 해당 토큰이 다시 활성화됩니다. 액세스를 영구적으로 종료해야 할 때는 토큰을 폐기하세요.

액세스 토큰의 최대 유효 기간 설정하기

워크스페이스 소유자는 멤버가 새 액세스 토큰에 지정할 수 있는 최대 유효 기간을 설정할 수 있습니다. 워크스페이스 설정 > 권한 및 역할을 여세요. 액세스 토큰 섹션이 표시되면 그 안에서 액세스 토큰 최대 유효 기간을 설정하세요. 해당 섹션이 없으면 Codex 및 Work 로컬 또는 Codex 로컬 섹션에서 이 설정을 찾으세요.

이 제한은 새 액세스 토큰에 적용됩니다. 기존 토큰의 유효 기간은 그대로 유지됩니다.

액세스 토큰 생성하기

액세스 토큰 페이지에서 토큰 이름을 지정하고, 선택할 수 있는 제품별 권한 범위를 확인한 다음 적절한 유효 기간을 선택하세요.

1. 액세스 토큰 페이지로 이동하세요.
2. 만들기를 선택하세요.

3. release-ci 또는 nightly-docs-check처럼 용도를 알 수 있는 이름을 입력하세요.

4. 대화 상자에 범위 항목이 표시되면 Codex를 선택하세요. 워크스페이스 에이전트는 같은 워크플로우에서 워크스페이스 에이전트도 실행해야 할 때만 선택하세요. 범위 선택 항목이 없으면 Codex 전용 토큰이 생성됩니다.
5. 7일, 30일, 60일 또는 90일처럼 만료일이 정해진 유효 기간을 선택하세요. 권한 범위를 지정하는 개인 액세스 토큰에는 반드시 만료일이 있어야 합니다. 이전 버전의 Codex 전용 대화 상자에는 만료 없음 옵션이 표시될 수 있습니다. 조직에서 이 옵션을 승인하고 정해진 일정에 따라 토큰을 교체하는 경우에만 사용하세요.
6. 만들기를 선택하세요.
7. 생성된 액세스 토큰을 즉시 복사하세요. 대화 상자를 닫으면 토큰을 다시 확인할 수 없습니다.
8. 토큰을 시크릿 관리자 또는 CI 시크릿 저장소에 보관하세요.

직접 지정할 수 있는 최소 유효 기간은 1일입니다. 폐기되거나 만료된 토큰으로는 인증이 필요한 새 작업을 시작할 수 없습니다.

Codex CLI에서 액세스 토큰 사용하기

토큰 생성 대화 상자에 필요한 Codex CLI 버전이 표시되면 토큰을 사용하기 전에 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 인증 저장소에 저장합니다. 머신에 자격 증명을 계속 보관하고 싶지 않다면 CODEX_ACCESS_TOKEN 환경 변수를 사용하세요.

codex app-server는 CODEX_ACCESS_TOKEN 또는 codex login --with-access-token으로 설정한 로그인을 통해 같은 자격 증명으로 OpenAI 요청을 인증할 수 있습니다. 이 자격 증명은 클라이언트와 App Server 간의 전송 인증에 사용하는 자격 증명과 별개입니다. 원격 WebSocket 연결에는 별도의 베어러 토큰 또는 기능 토큰을 설정하세요. 설정 방법은 App Server를 참고하세요. Codex 액세스 토큰을 전송 인증용 토큰으로 재사용하지 마세요. 인증 및 네트워크 환경 변수도 참고하세요.

토큰 교체 또는 폐기하기

다른 자동화 시크릿과 같은 방식으로 액세스 토큰을 교체하세요.

1. 기존 토큰을 대체할 새 토큰을 생성하세요.
2. 러너, 스케줄러 또는 시크릿 관리자에 저장된 시크릿을 업데이트하세요.
3. 새 토큰으로 스모크 테스트를 실행하세요.
4. 액세스 토큰 페이지에서 기존 토큰을 폐기하세요.

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

권한 모델

워크스페이스의 액세스 토큰 권한은 토큰 생성을 제어합니다. 워크스페이스 설정 화면 구성에 따라 멤버의 로컬 Codex 및 Work 사용 허용 옵션(Codex 및 Work 로컬 섹션) 또는 멤버의 로컬 Codex 사용 허용 옵션(Codex 로컬 섹션)이 로컬 Codex 액세스를 제어합니다. Work 로컬 섹션이 따로 있으면 로컬에서 Work 사용 옵션은 Work만 제어하며 Codex 액세스 권한을 부여하지 않습니다. 멤버가 토큰으로 인증하는 Codex 워크플로우를 사용하려면 로컬 Codex 액세스 권한과 액세스 토큰 권한이 모두 필요합니다. 액세스 토큰을 생성할 권한이 없어도 로컬 Codex 액세스 권한은 가질 수 있습니다.

워크스페이스 소유자와 관리자는 워크스페이스 전체의 액세스를 관리합니다. 멤버가 자신의 토큰을 생성하고 관리하려면 액세스 토큰 권한이 필요합니다. 이 권한에는 관리자 권한이나 다른 멤버의 토큰에 액세스할 권한이 포함되지 않습니다.

문제 해결

액세스 토큰 페이지에 404 또는 접근 금지 오류가 표시되는 경우

워크스페이스 소유자에게 현재 인터페이스에 따라 본인의 역할에 사용자의 개인 액세스 토큰 생성 허용 또는 멤버의 Codex 액세스 토큰 사용 허용 권한이 있는지 확인해 달라고 요청하세요. 토큰으로 인증하는 Codex 워크플로우를 사용하려면 멤버의 로컬 Codex 및 Work 사용 허용 또는 멤버의 로컬 Codex 사용 허용 옵션도 켜져 있는지 확인하세요.

codex login --with-access-token이 실패하는 경우

브라우저 세션 토큰이나 Platform API 키를 복사하지 않았는지 확인하세요. 복사한 값은 토큰 생성 대화 상자에서 발급된 액세스 토큰이어야 합니다. 토큰이 활성 상태이고 만료되지 않았는지, 토큰 소유자에게 필요한 로컬 Codex 권한이 있는지도 확인하세요.

관련 문서

• 인증
• 서비스 계정
• 비대화형 모드
• 관리자용 도입 가이드
• 그룹 및 프로비저닝
• 사용자 수명 주기 관리
• 역할 및 워크스페이스 권한
• 거버넌스