액세스 토큰

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

ChatGPT 관리자 콘솔의 액세스 토큰 페이지에서 개인 액세스 토큰을 만드세요. 각 토큰은 생성자와 해당 사용자의 ChatGPT 워크스페이스에 속합니다. 토큰은 프로그래밍 방식의 로컬 워크플로우에서 에이전트 ID 역할을 합니다. 사람 사용자가 아닌 전용 워크스페이스 ID의 상세 페이지에서 생성하는 토큰에 대해서는 서비스 계정을 참조하세요.

액세스 토큰 작동 방식

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

클라이언트는 실행이 시작될 때 토큰을 확인하고 해당 실행을 워크스페이스 ID에 연결합니다. 토큰을 다른 자동화 시크릿처럼 취급하세요. 시크릿 관리자에 저장하고 로그에 기록되지 않도록 하며 조직의 정책에 따라 교체하세요.

액세스 토큰은 다음 용도로 사용하세요:

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

피해야 할 주요 위험:

• 시크릿 유출: 토큰을 가진 사람은 누구나 토큰 생성자의 자격으로 Codex CLI 또는 App Server 클라이언트를 통해 로컬 실행을 시작할 수 있습니다. 토큰을 시크릿 관리자에 저장하고 로그에 기록되지 않도록 하며 조직의 정책에 따라 교체하세요.
• 러너 신뢰성: 공개 CI, 포크된 Pull Request 또는 공유 머신을 사용하면 워크스페이스 외부 사용자에게 토큰이 노출될 수 있습니다. 액세스 토큰은 신뢰할 수 있는 러너에서만 사용하세요.
• 공유 ID: 한 사람의 토큰을 서로 관련 없는 팀에서 재사용하면 소유권과 감사 기록을 파악하기 어려워집니다. 특정 워크플로우 소유자를 위한 토큰을 만드세요.
• 오래된 자격 증명: 유효 기간이 긴 토큰은 워크플로우가 변경된 뒤에도 계속 활성 상태로 남을 수 있습니다. 유효 기간이 제한된 토큰을 우선 사용하고 더 이상 사용하지 않는 토큰은 폐기하세요.
• 잘못된 권한 범위 또는 자격 증명 유형: 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 시크릿 저장소에 저장하세요.

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

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 인증 저장소에 에이전트 ID 자격 증명을 저장합니다. 머신에 자격 증명을 저장하지 않으려면 대신 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 권한이 있는 사용자의 토큰인지도 확인하세요.

관련 문서

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