액세스 토큰

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

ChatGPT 관리 콘솔의 Access tokens에서 개인용 액세스 토큰을 생성하세요. 각 토큰은 토큰 생성자와 해당 사용자의 ChatGPT 워크스페이스에 속합니다. 토큰은 프로그래밍 방식의 로컬 워크플로에서 에이전트 ID 역할을 합니다. 전용 비인간 워크스페이스 ID의 세부 정보 페이지에서 생성한 토큰에 관해서는 서비스 계정을 참조하세요.

액세스 토큰의 작동 방식

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

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

액세스 토큰의 용도는 다음과 같습니다.

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

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

• 보안 비밀 유출: 토큰을 가진 사람은 누구나 토큰 생성자의 권한으로 Codex CLI 또는 app-server 클라이언트를 통해 로컬 실행을 시작할 수 있습니다. 토큰을 비밀 관리자에 저장하고, 로그에 기록되지 않도록 하며, 조직의 정책에 따라 교체하세요.
• 러너 신뢰성: 공개 CI, 포크된 풀 리퀘스트 또는 공유 머신은 워크스페이스 외부 사용자에게 토큰을 노출할 수 있습니다. 액세스 토큰은 신뢰할 수 있는 러너에서만 사용하세요.
• 공유 ID: 한 사람의 토큰을 서로 관련 없는 여러 팀에서 재사용하면 소유권과 감사 추적이 불명확해집니다. 특정 워크플로 소유자를 위한 토큰을 생성하세요.
• 오래된 자격 증명: 수명이 긴 토큰은 워크플로가 변경된 후에도 활성 상태로 남을 수 있습니다. 기간 제한 토큰을 우선 사용하고 더 이상 사용하지 않는 토큰은 폐기하세요.
• 잘못된 범위 또는 자격 증명 유형: Codex 자동화에는 Codex 액세스가 필요하고, 워크스페이스 에이전트 트리거에는 Workspace Agents 액세스가 필요하며, 일반 OpenAI API 호출에는 Platform API keys가 필요합니다. Scopes가 표시되면 워크플로에 필요한 권한만 부여하세요.

액세스 토큰 생성 활성화

워크스페이스 설정의 액세스 토큰 권한을 사용하여 허용된 구성원의 액세스 토큰 생성을 켭니다.

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

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

1. 워크스페이스 소유자가 Workspace settings > Permissions & roles을 열도록 합니다.
2. Access tokens 섹션이 표시되면 Allow users to create personal access tokens를 활성화합니다. 해당 섹션을 사용할 수 없으면 Codex and Work Local 또는 Codex Local에서 Allow members to use Codex access tokens를 활성화합니다.
3. 워크플로 소유자에게 해당하는 로컬 Codex 권한을 활성화합니다. Codex and Work Local에서는 Allow members to use Codex and Work Locally를, Codex Local에서는 Allow members to use Codex locally를 활성화합니다. Work Local에 별도 섹션이 있는 경우 Use Work locally는 Work를 제어하며 Codex 토큰에는 필요하지 않습니다.

토큰의 저장 위치, 사용하려는 자동화 및 교체 일정을 이해하는 사용자나 서비스 소유자에게만 액세스 토큰 생성을 허용하세요.

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

액세스 토큰 만료 한도 설정

워크스페이스 소유자는 멤버가 새 액세스 토큰을 만들 때 선택할 수 있는 최장 유효 기간을 설정할 수 있습니다. Workspace settings > Permissions & roles을 여세요. Access tokens 섹션이 표시되면 해당 섹션에서 Access token expiration limit을 설정합니다. 그렇지 않으면 Codex and Work Local 또는 Codex Local에서 해당 설정을 찾으세요.

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

액세스 토큰 생성

Access tokens 페이지에서 토큰 이름을 지정하고, 사용 가능한 제품 범위를 검토하고, 적절한 유효 기간을 선택하세요.

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

3. release-ci 또는 nightly-docs-check처럼 설명이 명확한 이름을 입력합니다.

4. 대화 상자에 범위가 표시되면 Codex를 선택합니다. 동일한 워크플로에서 워크스페이스 에이전트도 실행해야 하는 경우에만 Workspace Agents를 선택합니다. 대화 상자에 범위 선택기가 없으면 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에 설명된 대로 별도의 bearer 또는 capability 토큰을 구성하세요. Codex 액세스 토큰을 전송 토큰으로 재사용하지 마세요. 인증 및 네트워크 환경 변수를 참조하세요.

토큰 교체 또는 취소

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

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

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

권한 모델

워크스페이스 액세스 토큰 권한은 토큰 생성을 제어합니다. 워크스페이스 구성에 따라 Codex and Work Local의 Allow members to use Codex and Work Locally 또는 Codex Local의 Allow members to use Codex locally가 로컬 Codex 액세스를 제어합니다. Work Local이 별도 섹션으로 제공되는 경우 Use Work locally는 Work를 제어하며 Codex 액세스 권한을 부여하지 않습니다. 구성원이 토큰으로 인증하는 Codex 워크플로를 사용하려면 로컬 Codex 액세스 권한과 액세스 토큰 권한이 모두 필요합니다. 구성원은 액세스 토큰 생성 권한 없이도 로컬 Codex 액세스 권한을 가질 수 있습니다.

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

문제 해결

액세스 토큰 페이지에서 404 또는 금지 오류가 반환되는 경우

워크스페이스 소유자에게 사용 가능한 인터페이스에 따라 본인의 역할에 Allow users to create personal access tokens 또는 Allow members to use Codex access tokens가 포함되어 있는지 확인해 달라고 요청하세요. 토큰으로 인증하는 Codex 워크플로의 경우 Allow members to use Codex and Work Locally 또는 Allow members to use Codex locally도 활성화되어 있는지 확인하세요.

codex login --with-access-token 실패

브라우저 세션 토큰이나 Platform API key가 아니라 생성된 액세스 토큰을 복사했는지 확인하세요. 또한 토큰이 활성 상태이고 만료되지 않았으며 필수 로컬 Codex 권한을 보유한 사용자의 토큰인지 확인하세요.

관련 문서

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