Codex access token 使用教程

Codex 本地认证：生成 Codex access token，并把它用于本地 Codex CLI 与桌面 App —— 无需每次浏览器交互登录。

最后更新：

一、适用场景

🔐 安全提醒：把 access token 和 ~/.codex/auth.json 都当作密码处理。 不要提交到 Git，不要发到群聊、工单或日志里；一旦怀疑泄露，立即撤销并重新生成。 文中出现的 at-xxx... 都是占位符，请替换为你自己复制到的真实 token。

Codex access token 让 Codex 在没有浏览器交互登录的情况下运行，适合可信的本地机器、私有脚本、调度任务或私有 CI runner。

它携带你的 ChatGPT 工作区身份和 Codex 权限，因此更适合需要工作区管控的 Codex 本地流程，而不是普通的 API 调用。

⚠️ 前提：access token 仅面向 Business / Enterprise 工作区（原「Team」现已改名为 Business），且需管理员开启创建权限。 个人计划（Free / Go / Plus / Pro）能正常使用 Codex，但没有工作区管理后台，也就没有此功能。
💡 如果只是调用通用 OpenAI API，请继续使用 Platform API key； 只有当你需要 ChatGPT 工作区身份、Codex 权限或企业工作区管控时，才用 access token。

二、生成 access token

只有 workspace owner 或 admin 能开启创建权限；开启后，有权限的成员即可自助创建。

1
确认权限（管理员操作，当前已开启） 访问 Workspace Settings > Permissions & roles， 开启 Allow users to create access tokens。若要用于 Codex app、CLI 或 IDE extension，还需开启 Allow members to use Codex Local。
2
打开 Access tokens 页面 进入 chatgpt.com/admin/access-tokens，点击 Create。
3
填写名称与过期时间 名称建议能看出用途，例如 local-codex、release-ci 或 nightly-docs-check。 过期时间建议使用有限期限（如 7、30、60 或 90 天）方便定期轮换；可选的最长期限受管理员在 Access token expiration limit 中设置的上限限制。
4
创建并立即复制 点击 Create 后立刻复制生成的 token。关闭弹窗后通常无法再次查看完整 token，只能重新生成。

三、写入 auth.json

推荐直接编辑 ~/.codex/auth.json，把生成的 access token 写入 access token 字段。改动前请先备份原文件。

1. 备份原文件

# 备份并加时间戳，避免覆盖原文件
cp ~/.codex/auth.json ~/.codex/auth.json.bak.$(date +%Y%m%d%H%M%S)

也可以手动把原来的 ~/.codex/auth.json 复制到安全位置。该文件里可能包含登录凭据，务必自己保存好。

2. 编辑并写入 JSON

vim ~/.codex/auth.json

也可以使用你熟悉的编辑器，例如 code 或 Finder 里的文本编辑工具。清空内容，仅保留以下 JSON：

{
  "OPENAI_API_KEY": null,
  "personal_access_token": "at-xxx..."
}

其中 at-xxx... 就是刚才在 Access tokens 页面复制出来的 access token。

3. 校验 JSON 格式

python3 -m json.tool ~/.codex/auth.json

如果命令能正常格式化输出，说明 JSON 语法没有问题。常见错误是漏写双引号、末尾多写逗号，或 token 没有完整复制。

四、命令方式（可选）

如果不想手动改文件，也可以使用环境变量或登录命令。这种方式更适合临时脚本、CI secret，或不希望手动维护 auth.json 的场景。

1. 临时使用，不写入本机

export CODEX_ACCESS_TOKEN="at-xxx..."
codex exec "summarize this repository"

2. 持久登录，写入认证存储

export CODEX_ACCESS_TOKEN="at-xxx..."
printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token
codex login status
💡 如果不希望机器上保留认证信息，用 CODEX_ACCESS_TOKEN 环境变量即可； 若希望之后打开 Codex 就能复用登录状态，再用 codex login --with-access-token 写入认证存储。

五、Codex App 说明

Codex app 是 Codex 的桌面端，适合在本机打开项目、创建线程，并让 Codex 以 Local 模式在你的电脑上工作。安装并打开后，可以用 ChatGPT 账号或 OpenAI API key 登录；如果使用本文的 access token 方式，则重点是让 app 读取本机的 ~/.codex/auth.json。

手动写入 ~/.codex/auth.json 后，建议完全退出 Codex app 再重新打开。进入项目后确认使用的是本地工作流，也就是选择 Local。如果 app 仍提示登录，先检查 JSON 格式和 token 是否完整，再用下面的验证命令确认本机 Codex 认证状态。

🖥️ Codex app、Codex CLI 和 IDE extension 都属于 Codex 本地使用场景。本文写入的是本机认证文件； 如果当前机器配置为使用系统 keychain / keyring 存储凭据，手动改 auth.json 可能不会被 app 优先采用， 这时改用 codex login --with-access-token 写入认证存储即可。

六、验证是否生效

保存后重新打开 Codex，或在终端执行：

codex login status

也可以跑一个很小的命令，确认 Codex 能正常启动：

codex exec "hello"

七、常见问题

现象 可能原因 处理方式
Access tokens 页面 404 或 forbidden 工作区没有给你创建 token 的权限，或 Codex Local 权限未开启。 联系 workspace owner 或 admin 开启 access token 创建权限，并确认 Codex Local 可用。
codex login --with-access-token 失败 复制的不是 Codex access token，或 token 已过期、已撤销。 重新生成 token，并确认格式类似 at-xxx...。
手动写入后仍未生效 JSON 格式错误、路径不对，或当前 Codex 使用系统 keychain 而不是文件。 先运行 python3 -m json.tool ~/.codex/auth.json 检查格式；仍不行时改用 printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token。
Codex app 仍提示登录 app 没有重新读取认证文件，或当前机器优先使用系统凭据存储。 完全退出并重新打开 Codex app；仍不生效时，用 codex login --with-access-token 写入认证存储。
担心 token 泄露 token 可能出现在日志、截图、仓库或共享机器上。 立刻到 Access tokens 页面撤销旧 token，创建新 token，并更新本地或 CI secret。

八、轮换与撤销

token 有过期时间，也可能需要在泄露时紧急更换。安全的轮换顺序是先换新、验证可用，再撤销旧的，避免中途断档：

1
在 Access tokens 页面创建一个新的 access token。
2
更新本机 auth.json、脚本或 CI secret 中保存的 token。
3
运行一次小任务（如 codex exec "hello"）确认新 token 可用。
4
回到 Access tokens 页面撤销旧 token。

参考链接