跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/enterprise/access-tokens

Access tokens

为程序化工作流创建和管理 Codex access tokens

Codex access tokens 允许受信任的自动化以 ChatGPT 工作区身份运行本地 Codex。在脚本、定时任务或 CI runner 需要可重复、非交互式的 Codex 访问时，请使用它们。

Codex access tokens 当前支持 ChatGPT Business 和 Enterprise 工作区。

Access tokens 在 ChatGPT 管理控制台的 Access tokens 中创建。它们绑定到创建它们的 ChatGPT 用户和工作区，Codex 将它们用作程序化本地工作流中的代理身份。

如果 Platform API key 适用于你的自动化，请继续使用 API key 认证。当工作流明确需要 ChatGPT 工作区访问、由 ChatGPT 管理的 Codex 权限，或企业工作区控制时，请使用 Codex access tokens。

Access tokens 的工作原理​

当 Codex 需要在无需用户完成浏览器登录的情况下运行时，请使用 access token。该 token 代表创建它的 ChatGPT 工作区用户，因此运行可以使用该用户的 Codex 访问权限，并出现在工作区治理数据中。

Codex 会在运行开始时检查该 token，并将该次运行绑定到该工作区身份。像对待任何其他自动化密钥一样对待这个 token：将其存储在密钥管理器中，避免出现在日志里，并定期轮换。

Access tokens 适用于：

  • 从受信任自动化运行的 codex exec 作业。
  • 需要可重复、非交互式 Codex 运行的本地脚本。
  • 使用量应关联到 ChatGPT 工作区用户而不是 API organization key 的企业工作流。

需要避免的主要风险：

  • 密钥泄露： 任何持有该 token 的人都可以以 token 创建者的身份启动 Codex 运行。请将 tokens 存储在密钥管理器中，避免出现在日志里，并定期轮换。
  • 不受信任的 runner： 公共 CI、fork 的 pull request 或共享机器可能会将 tokens 暴露给工作区外部人员。仅在受信任的 runner 上使用 access tokens。
  • 共享身份： 一个人的 token 被不相关的团队重复使用，会让所有权和审计轨迹更难解释。请为特定工作流所有者创建 token。
  • 陈旧凭据： 长期有效的 tokens 在工作流变更后仍可能保持有效。优先使用有限过期时间，并撤销不再使用的 tokens。
  • 错误的凭据类型： access tokens 用于本地 Codex 工作流。常规 OpenAI API 调用请使用 Platform API keys。

启用 access token 创建​

使用工作区设置中的 Codex Local 控件，为允许的成员开启 access token 创建功能。

ChatGPT 工作区 RBAC 设置中的 Access token 访问权限

  1. 前往 Workspace Settings > Settings and Permissions。
  2. 在 Codex Local 部分，确保 Allow members to use Codex Local 已开启。
  3. 如果所有允许的成员都应能够创建 access tokens，请开启 Allow members to use Codex access tokens。
  4. 如果你使用自定义角色进行更小范围的发布，则仅将 access token 权限分配给需要创建 tokens 的组。

将 access token 创建权限限制在了解 token 将存储在哪里、哪些自动化会使用它以及如何轮换它的人员或服务所有者范围内。

创建 access token​

使用 Access tokens 页面命名 token 并选择其过期时间。

  1. 前往 Access tokens。
  2. 选择 Create。

带有 Create 按钮的 Access tokens 页面

  1. 输入一个描述性名称，例如 release-ci 或 nightly-docs-check。

创建 access token 的模态框，包含名称和过期时间字段

  1. 选择过期时间。优先选择有限的过期时间，例如 7、30、60 或 90 天。如果你选择 No expiration，请按固定计划轮换该 token。
  2. 选择 Create。
  3. 立即复制生成的 access token。关闭模态框后，你将无法再次查看它。
  4. 将该 token 存储到你的密钥管理器或 CI 密钥存储中。

最短的自定义过期时间为一天。已撤销和已过期的 tokens 不能用于启动新的 Codex 运行。

在 Codex CLI 中使用 access token​

对于临时自动化，将 token 存储在 CODEX_ACCESS_TOKEN 中，并正常运行 Codex：

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

对于持久化的本地登录，将 token 通过管道传给 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 认证存储中保存代理身份凭据。如果你不希望在机器上持久化保存凭据，请改用 CODEX_ACCESS_TOKEN 环境变量。

轮换或撤销 token​

像轮换其他自动化密钥一样轮换 access tokens：

  1. 创建一个替代 token。
  2. 更新 runner、scheduler 或密钥管理器中的密钥。
  3. 使用新 token 运行冒烟测试。
  4. 在 Access tokens 中撤销旧 token。

在 Access tokens 页面中，工作区所有者和管理员可以撤销工作区中的任何 token。拥有 access token 权限的成员只能撤销他们自己创建的 tokens。

权限模型​

Access token 权限与一般的 Codex local 权限是分开的。成员可以拥有 Codex app、CLI 或 IDE 扩展的访问权限，而不被允许创建 access tokens。

CapabilityWorkspace owners and adminsMember with access token permissionMember without access token permission
打开 Access tokens是是否
创建 access tokens是，针对其自己的 ChatGPT 工作区身份是，针对其自己的 ChatGPT 工作区身份否
列出 access tokens工作区列表，包括每个 token 的创建者仅他们创建的 tokens否
从 Access tokens 页面撤销 access tokens工作区中的任何 token仅他们创建的 tokens无页面访问权限
授予或移除 access token 权限是否否
管理其他 Codex enterprise 设置是，基于管理员角色和 Codex 管理员权限否，除非被单独授予否

简而言之：工作区所有者和管理员在工作区级别管理访问。成员需要 access token 权限才能创建和管理自己的 tokens，但该权限不会授予管理员权限，也不会授予对其他成员 tokens 的访问权限。

故障排查​

Access tokens 页面返回 404 或 forbidden​

请让工作区所有者或管理员确认 Codex access tokens 已启用，并且你的角色包含 access token 权限。

codex login --with-access-token 失败​

确认你复制的是生成的 access token，而不是浏览器 session token 或 Platform API key。同时确认该 token 尚未过期或被撤销。