JICHANG AIR · 2026机场推荐 | 梯子推荐与机场梯子评测

外观

Codex 是 OpenAI 的编程代理，可以在 CLI、IDE 扩展、桌面应用和云端（chatgpt.com/codex）使用。结论先说：从官方渠道安装 CLI 后先登录（ChatGPT 账号走订阅权益，API Key 按 API 用量计费）；在 Git 仓库里推荐 workspace-write 沙箱 + on-request 审批；仓库根目录写好 AGENTS.md；每个任务说清改哪里、不改哪里、怎样算完成；所有改动都在独立分支上审阅并跑测试。公司网络有 TLS 解密代理时，登录前先配置证书。

本页适合已经会用 Git、想让 AI 参与日常开发的读者。下面先给一张速查表，再讲安装与登录、config.toml、沙箱与审批、代理与证书、AGENTS.md、任务拆分与验收、审阅与自动化、故障排查；页面末尾的「官方资格入口」列出 OpenAI 的支持地区页面。命令和配置项按 2026-10-07 的官方文档核对，后续变化以官方文档为准。

核心结论 ​

核心结论

  • 官方入口：文档在 OpenAI 官方开发者文档站，源码在 github.com/openai/codex，云端任务在 chatgpt.com/codex，只从这些来源安装和查资料。
  • 安装后先登录：用 ChatGPT 账号登录走订阅权益；用 API Key 登录按 API 用量计费；无浏览器环境用 codex login --device-auth。
  • 默认就有沙箱：Git 仓库里推荐 workspace-write + on-request，命令联网默认关闭；danger-full-access 只在隔离环境使用。
  • 仓库要有 AGENTS.md：写清目录结构、构建 / 测试命令和约定，Codex 会从 Git 根目录到当前目录逐级读取，合并后有大小上限。
  • 任务要有边界：说明改哪里、不改哪里、怎样算完成，比「帮我优化代码」可靠得多。
  • 所有改动都要审阅并跑测试：在独立 Git 分支上工作，用 /diff、/review 和自己的测试命令双重确认，合并决定权留在人手里。
  • 企业网络先配证书：TLS 解密代理环境下，登录前设置 CODEX_CA_CERTIFICATE（或 SSL_CERT_FILE）。

Codex 速查表 ​

你要做的事怎么做本页章节
安装 CLI官方安装脚本、npm 或 Homebrew，装完运行 codex --version「安装与更新 Codex CLI」
登录codex login；无浏览器环境用 codex login --device-auth「身份验证与凭据保管」
查看登录与会话状态codex login status，会话内 /status「身份验证与凭据保管」「常见故障排查」
设定默认权限沙箱 workspace-write + 审批 on-request「沙箱、审批与权限安全」
告诉它项目约定在仓库写 AGENTS.md「AGENTS.md：写给 Codex 的项目说明」
公司网络证书报错登录前设置 CODEX_CA_CERTIFICATE 或 SSL_CERT_FILE「代理与受限网络环境下的配置」
放进脚本或 CIcodex exec 非交互运行「非交互运行与自动化」
并行跑独立任务云端任务 chatgpt.com/codex 或桌面应用「官方产品入口与使用方式」
确认所在地区能否使用OpenAI 官方支持地区页面「官方资格入口」

Codex 是什么，适合解决什么问题 ​

Codex 是 OpenAI 的编程代理（coding agent）：它不只是回答编程问题，而是能在你授权的范围内读取代码、修改文件、运行命令，并根据命令输出继续调整，直到完成任务或需要你确认。理解这一点很重要：你交给它的是「一件事」，而不是「一个问题」。

一次典型任务是怎么跑完的 ​

一次任务通常经历以下循环，理解它有助于判断该在哪个环节介入：

  1. 读取上下文：加载 AGENTS.md、你的提示和它主动打开的源码文件。
  2. 形成计划：判断要改哪些文件、需要运行什么命令来验证。
  3. 执行动作：编辑文件、运行构建或测试命令。每个动作都受沙箱和审批策略约束，超出范围时会停下来请求你批准。
  4. 读取结果并迭代：根据测试输出或报错继续修改。
  5. 汇报：总结改了什么、验证结果如何，等待你审阅。

在这个循环里，你能控制的杠杆主要有三个：项目说明（AGENTS.md，决定它「知道什么」）、任务描述（决定它「做什么、做到什么程度」）、权限设置（决定它「能做什么」）。本文后面的章节就是围绕这三个杠杆展开的。

与聊天式问答的区别 ​

对比项在 ChatGPT 中问编程问题使用 Codex
能否看到你的仓库只能看到你粘贴的片段能在授权范围内读取整个工作目录
能否修改文件不能，需要你手动复制能直接编辑，改动体现在 Git 工作区
能否运行命令不能能运行构建、测试等命令，受沙箱约束
结果如何验证你自己试它可以先跑测试自检，你再复核
主要风险答案不准确改动越界、误执行命令，需要权限与审阅兜底

官方产品入口与使用方式 ​

Codex 有多个入口，共享相同的工作理念：CLI 最透明、IDE 扩展最贴近编辑习惯、桌面应用适合管理多项目、云端任务适合并行和不依赖本地环境的工作。

形态入口适合的场景
Codex CLI终端中运行 codex在本地仓库中交互式开发、调试、执行命令
IDE 扩展VS Code 及兼容编辑器（如 Cursor、Windsurf）边看代码边让 Codex 修改，就地查看改动
桌面应用Codex App（可在 CLI 中运行 codex app 打开）同时管理多个项目和较长时间运行的任务
云端任务chatgpt.com/codex在云端环境中并行运行任务，适合不依赖本地环境的工作

如何选择 ​

  • 改动需要本地环境（本地数据库、私有依赖、特定硬件）：用 CLI 或 IDE 扩展。
  • 想并行跑多个相互独立的任务：考虑云端任务或桌面应用。
  • 刚开始接触：建议从 CLI 起步，所有操作都在眼前，最容易理解代理在做什么。
  • 需要放进脚本或 CI：用 CLI 的非交互命令 codex exec（见后文「非交互运行与自动化」）。

几种形态之间并不互斥。常见的组合是：日常在 IDE 扩展或 CLI 中处理需要本地环境的改动；把相互独立、耗时较长的任务（例如为多个模块分别补测试）交给云端并行运行，完成后在 GitHub 上以 PR 的形式审阅。需要注意，云端任务运行在远程环境中，代码会被拉取到云端处理，涉及保密代码时先确认所在单位是否允许；本地 CLI 的改动则直接落在你的工作区，更便于逐步审阅。

地区与账号

Codex 需要 ChatGPT 账号或 OpenAI API 账号，服务仅在 OpenAI 支持的国家和地区提供，名单以 OpenAI 帮助中心为准。网络问题可参考 常见问题 与 AI 机场推荐，并请遵守所在地法律法规与服务条款。

安装与更新 Codex CLI ​

Codex CLI 官方提供独立安装脚本、npm 和 Homebrew 三种安装方式，任选其一即可；Windows 使用官方 PowerShell 安装脚本。

bash
# macOS / Linux：官方安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 或使用 npm 全局安装
npm install -g @openai/codex

# 或使用 Homebrew
brew install --cask codex

Windows 可在 PowerShell 中运行官方安装脚本：

powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

安装后自检 ​

  1. 重新打开一个终端窗口，让新的 PATH 生效。
  2. 运行 codex --version，能输出版本号说明命令可用。
  3. 进入一个 Git 仓库，运行 codex，确认能进入交互界面并提示登录。
  4. 在交互界面输入 /status，查看当前会话的模型、权限与用量配置。

更新方式 ​

更新方式与安装方式保持一致：npm 安装的用 npm install -g @openai/codex 重新安装最新版，Homebrew 安装的用 brew upgrade --cask codex，脚本安装的重新运行官方脚本即可。不要混用多种方式安装，否则 PATH 中可能同时存在新旧两个 codex，出现「升级了却没变化」的情况——用 which codex（Windows 用 where codex）确认实际调用的是哪一个。

只从官方来源安装

安装命令以官方 README 和文档为准。不要使用来源不明的「加速版」「破解版」安装包；通过管道执行脚本前，确认网址确实是官方域名。npm 包名是 @openai/codex，注意与名字相近的第三方包区分。

身份验证与凭据保管 ​

Codex 支持「用 ChatGPT 登录」和「用 API Key 登录」两种方式，二者的计费体系不同；凭据默认以明文缓存在本机，必须像密码一样保管。

方式命令计费
ChatGPT 账号登录运行 codex 选择 Sign in with ChatGPT，或 codex login使用 ChatGPT 方案中的 Codex 权益，以官方说明为准
API Key 登录通过标准输入传入 API Key（见下方命令）按 OpenAI API 用量计费
无浏览器环境codex login --device-auth设备码方式：在任意有浏览器的设备上打开链接并输入一次性代码

API Key 登录与常用的账号管理命令：

bash
# 用环境变量中的 API Key 登录（避免 Key 出现在命令历史里）
printenv OPENAI_API_KEY | codex login --with-api-key

codex login status   # 查看当前登录状态
codex logout         # 退出登录

凭据存放位置 ​

登录信息的存放方式由 config.toml 中的 cli_auth_credentials_store 控制：

取值行为适合
file写入 ~/.codex/auth.json（明文）个人电脑、需要简单迁移时
keyring存入操作系统的凭据管理器希望凭据不以明文落盘
auto优先系统凭据管理器，不可用时退回 auth.json多数桌面环境
ephemeral只保存在内存，进程结束即失效临时环境、共享机器
toml
# ~/.codex/config.toml（示例）
cli_auth_credentials_store = "keyring"

auth.json 等同于密码

~/.codex/auth.json 不要提交到仓库、不要拷贝进 Docker 镜像、不要发给他人。怀疑泄露时，ChatGPT 登录方式应退出并重新登录，API Key 方式应立即在 OpenAI 控制台吊销该 Key。

选择哪种登录方式 ​

  • 个人日常开发：用 ChatGPT 账号登录最省事，权益与限额以所订阅方案的官方说明为准。
  • 团队统一计费或需要精细预算控制：用组织的 API Key，并在 OpenAI 控制台为项目设置用量上限。
  • 远程服务器、容器：用 --device-auth，或通过环境变量注入 API Key，不要把个人电脑上的 auth.json 复制过去。
  • 企业管理员：可在配置中用 forced_login_method（取值 chatgpt 或 api）限制允许的登录方式。

配置文件 config.toml ​

Codex 的持久配置写在 TOML 格式的 config.toml 里：用户级在 ~/.codex/config.toml，项目级覆盖在仓库的 .codex/config.toml，后者只在你信任该项目时才会加载。

位置作用范围说明
~/.codex/config.toml本机所有项目个人默认值，如模型、审批策略、凭据存放方式
<仓库>/.codex/config.toml当前项目项目级覆盖，仅在受信任项目中加载
CODEX_HOME 环境变量改变 Codex 主目录默认是 ~/.codex，设置后配置、AGENTS.md 全局说明等都从新目录读取

常用配置项 ​

配置项作用
model默认使用的模型，填官方模型列表中的 ID
approval_policy何时暂停请求批准，取值见后文
sandbox_mode沙箱模式：read-only、workspace-write、danger-full-access
[sandbox_workspace_write] 下的 network_access在 workspace-write 模式下是否允许命令联网
project_doc_max_bytes读取 AGENTS.md 等说明文件的总字节上限
project_doc_fallback_filenamesAGENTS.md 缺失时尝试的其他文件名
cli_auth_credentials_store凭据存放方式
model_provider / openai_base_url模型服务提供方与 OpenAI 接口地址覆盖，一般无需修改

一个偏保守的个人配置示例（MODEL_ID 替换为官方模型列表中的 ID）：

toml
# ~/.codex/config.toml（示例）
model = "MODEL_ID"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
cli_auth_credentials_store = "keyring"

# 合并后的项目说明上限，默认 32 KiB，这里放宽到 64 KiB
project_doc_max_bytes = 65536

[sandbox_workspace_write]
# 默认关闭；需要安装依赖等联网操作时再临时打开
network_access = false

改完配置怎么确认生效

重启 Codex 后运行 /status 查看当前会话的配置与用量；如果怀疑多层配置互相覆盖，可以用 /debug-config 打印各配置层的诊断信息。

沙箱、审批与权限安全 ​

Codex 的安全模型由两层组成：沙箱（sandbox，操作系统层面限制命令能读写什么、能否联网）和审批策略（approval policy，决定什么时候停下来问你）。两者配合使用，默认设置已经相当克制，不建议一上来就放宽。

三种沙箱模式 ​

模式能做什么适合
read-only读取文件、在沙箱内执行命令；越界动作需要批准阅读陌生仓库、只做分析和规划
workspace-write在工作目录内读写文件和运行命令；越界与联网需要批准日常开发，Git 仓库中的推荐默认值
danger-full-access不受沙箱限制仅限一次性的隔离容器或虚拟机

Codex 会自动识别目录类型：在受版本控制的目录中推荐 workspace-write + on-request；在不受版本控制的目录中默认 read-only。这背后的逻辑是：有 Git 兜底时改错了还能回退，没有 Git 时应更谨慎。

审批策略 ​

取值行为
on-request在需要越出沙箱、联网或执行被拦截的命令时询问你
never从不弹出审批，但仍受沙箱约束；被拦截的动作直接失败
granular按类别细粒度控制哪些情况需要审批

旧的 untrusted 取值已经停用，官方建议改用 on-request 并搭配合适的沙箱模式。

命令行参数与会话内切换 ​

bash
# 只读方式启动，适合先让它读懂项目
codex --sandbox read-only

# 明确指定沙箱与审批策略
codex --sandbox workspace-write --ask-for-approval on-request

-s 是 --sandbox 的简写，-a 是 --ask-for-approval 的简写。会话进行中可以用 /permissions 切换，例如规划阶段先切到只读，确认方案后再切回可写。

受保护路径与网络 ​

  • 即使在可写模式下，.git（以及其指向的 gitdir）、.agents、.codex 目录仍保持只读，防止代理篡改版本历史和自身配置。
  • workspace-write 下命令的网络访问默认关闭。需要时在 [sandbox_workspace_write] 中设置 network_access = true；更精细的做法是启用官方的网络代理功能，按域名设置允许 / 拒绝规则，拒绝规则优先。

关于 --yolo

--dangerously-bypass-approvals-and-sandbox（别名 --yolo）会同时关闭审批和沙箱。不要在保存有 SSH 私钥、云平台凭据、生产数据库连接信息的日常电脑上使用它；确有需要时，只在用完即弃的容器或虚拟机里使用。

一份权限选择决策表 ​

场景建议组合
第一次接触某个仓库read-only，只让它读和讲
日常修 bug、写功能workspace-write + on-request
需要安装依赖或访问内部包仓库保持 on-request，在提示时临时批准联网，或只为该项目打开 network_access
CI 中只读审查read-only + never
一次性容器内的批量改造在隔离环境中才考虑放宽，完成后销毁环境

代理与受限网络环境下的配置 ​

在公司代理、TLS 解密网关或其他受限网络中使用 Codex，要分清两条连接：一条是 Codex 本身连接 OpenAI 服务（登录、模型请求），另一条是 Codex 在沙箱里执行的命令联网（如 npm install）。前者靠证书和代理环境变量解决，后者靠沙箱的网络设置解决。

Codex 自身的连接：证书 ​

企业网络常用 TLS 解密代理，它会用公司私有根证书重新签发 HTTPS 证书，未信任该根证书的程序会报证书错误。官方文档给出的做法是在登录前设置：

bash
# 指向企业根证书（PEM 格式），然后再登录
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

如果没有设置 CODEX_CA_CERTIFICATE，Codex 会读取 SSL_CERT_FILE 作为后备。证书文件请向公司 IT 部门索取，不要从网上下载来源不明的「根证书」。

Codex 自身的连接：代理环境变量 ​

终端程序通常通过 HTTPS_PROXY、HTTP_PROXY、NO_PROXY 这几个标准环境变量走代理。社区实践中 Codex 一般也会读取它们，但官方文档目前没有逐项列出各变量的支持细节，部分版本中个别连接路径（如登录流程）的代理支持也有过变化。稳妥做法是：

bash
# 示例：在启动 Codex 的同一个终端里设置（地址替换为你实际的代理）
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
codex

设置后先用 codex login status 和一个简单任务验证；若登录可用而某个功能失败，记下具体报错，到 openai/codex 仓库的 issue 中检索。是否支持 SOCKS 代理、系统代理（PAC）等细节，以官方文档和发行说明为准。

沙箱内命令的联网 ​

现象原因处理
Codex 能对话，但它运行的 npm install、pip install 失败workspace-write 默认禁止命令联网在提示时批准，或为该项目设置 network_access = true
打开了 network_access 仍然连不上内部仓库命令本身没有拿到代理或证书配置在项目的包管理器配置中设置代理和证书（如 npm、pip 自己的配置）
只想允许访问少数域名全开网络风险过大使用官方网络代理功能的域名允许 / 拒绝规则

请遵守网络与合规要求

公司网络的代理和证书配置应遵循所在单位的 IT 安全规定。个人网络环境的选择可参考 AI 机场推荐 中的判断标准，并请遵守所在地法律法规与服务条款。

AGENTS.md：写给 Codex 的项目说明 ​

AGENTS.md 是写给编程代理看的项目说明文件，是让 Codex「少猜、少犯错」最有效的手段。在 Codex CLI 中运行 /init 可以在当前目录生成初稿，再由你补充修订。

读取顺序与优先级 ​

Codex 每次开始工作时按以下顺序组装说明：

  1. 全局说明：先读 Codex 主目录（默认 ~/.codex，可用 CODEX_HOME 修改）中的 AGENTS.override.md，不存在则读 AGENTS.md。
  2. 项目说明：从 Git 根目录开始，逐级走到当前工作目录，在每一层依次查找 AGENTS.override.md、AGENTS.md，以及 project_doc_fallback_filenames 中配置的备用文件名。
  3. 每层最多一个文件：同一目录只取找到的第一个。
  4. 按顺序拼接：越靠近当前目录的说明越靠后，相互冲突时以它为准。
  5. 大小上限：空文件会被跳过；拼接总大小达到 project_doc_max_bytes（默认 32 KiB）后不再追加。
文件用途
~/.codex/AGENTS.md你个人在所有项目通用的习惯，如回复语言、提交信息风格
<仓库根>/AGENTS.md团队共享的项目说明，提交到仓库
<子目录>/AGENTS.md只对该子目录生效的补充规则，适合 monorepo
AGENTS.override.md临时覆盖同层的 AGENTS.md，用完记得删除

一个实用的 AGENTS.md 示例 ​

markdown
# 项目说明

## 结构
- `src/api/`：后端接口
- `src/web/`：前端页面
- `tests/`：单元测试与集成测试

## 常用命令
- 安装依赖：`npm install`
- 运行测试：`npm test`
- 代码检查：`npm run lint`

## 约定
- 使用 TypeScript 严格模式，不引入 `any`。
- 新增功能必须附带测试。
- 不修改 `migrations/` 下已合并的迁移文件。
- 提交前确保 `npm test` 与 `npm run lint` 通过。

## 完成标准
- 在回复中列出改动的文件和原因。
- 说明运行了哪些验证命令以及结果。

写什么、不写什么 ​

应该写不应该写
构建、测试、lint 的准确命令API Key、数据库密码等任何密钥
目录职责和模块边界从代码一眼就能看出来的信息
团队约定与禁区（不准动的目录、不准引入的依赖）大段产品文档、会议记录
业务术语的含义含糊的要求，如「写出高质量代码」
「怎样算完成」的通用标准只对某一次任务有用的临时指令

示例场景：monorepo 中的分层说明 ​

示例场景：一个仓库同时包含前端 apps/web 和后端 services/api，两边的测试命令、代码风格都不同。合理的组织方式是：根目录的 AGENTS.md 只写全仓库通用的内容（目录总览、提交规范、禁止修改的公共目录）；apps/web/AGENTS.md 写前端的安装、测试和组件约定；services/api/AGENTS.md 写后端的测试命令和数据库迁移规则。当你在 services/api 下启动 Codex 时，它会依次读到根目录和后端两份说明，后端规则排在后面、优先级更高，而前端说明不会混进来占用上下文。这样既避免单个文件过长被截断，也让每个子团队只维护自己那一份。

让 AGENTS.md 持续变好 ​

AGENTS.md 不是写一次就结束的文件。比较有效的维护习惯是：每当你在任务中第二次纠正 Codex 同一个问题（例如又用错了测试命令、又改了不该改的目录），就把这条纠正写进 AGENTS.md；每隔一段时间删掉已经过时的命令和目录说明。把它当作代码的一部分，通过 PR 修改、让团队成员审阅，比私下各自维护一份更可靠。

验证说明是否生效 ​

官方提供了一个简单的核对方法：在仓库目录运行下面的命令，让 Codex 复述它读到的指令。

bash
codex --ask-for-approval never "Summarize the current instructions."

如果复述内容不对，按以下顺序检查：启动目录是否在仓库内；文件是否为空；上层目录是否有 AGENTS.override.md 覆盖了你的文件；备用文件名是否拼写正确；内容是否因超过上限被截断（可调大 project_doc_max_bytes 或拆分到子目录）；echo $CODEX_HOME 确认主目录是否是你以为的那个。

从已有仓库组织开发任务 ​

Codex 在已有仓库中最能发挥作用，但前提是它能快速理解项目。建议按「先理解、再计划、后修改」的顺序推进，并用 Git 分支隔离每个任务。

开始前的本地准备清单 ​

  1. 仓库已用 Git 管理，工作区干净（git status 无未提交改动）。
  2. 为本次任务新建分支，例如 git switch -c codex/fix-login-timeout。
  3. 依赖已安装、项目能在本地构建，测试命令可以正常运行。
  4. 敏感配置（.env、密钥文件）已加入 .gitignore，不在仓库中明文出现。
  5. 在仓库根目录启动 codex，让它以项目为工作范围。

第一步：让它先读懂项目 ​

text
请先阅读这个仓库，不要修改任何文件。
告诉我：
1. 项目的主要模块和各自职责；
2. 构建、运行和测试的命令；
3. 与「用户登录」相关的代码在哪些文件。

把它的回答与你的认知对照，有偏差就当场纠正，并考虑把正确信息写进 AGENTS.md。这一步最好在 read-only 模式下进行。

第二步：先要计划，再动手 ​

对于涉及多个文件的任务，先让 Codex 给出计划：要改哪些文件、每处改什么、如何验证。可以用 /plan 切换到计划模式并附上任务描述。确认计划合理后再让它执行；计划不清楚的地方，执行时只会更混乱。

第三步：按可验证的小步执行 ​

任务规模建议做法
小修复（单文件、明确报错）直接描述问题和期望行为，一次完成
中等功能（若干文件）先计划，再分 2–3 步执行，每步跑测试
大型改造（跨模块、重构）拆成多个独立任务，每个任务单独分支和提交

拆分任务的四条原则 ​

  • 每个任务只有一个目的：「修 bug」「重构」「升级依赖」分开做。
  • 每个任务都能独立验证：拆出来的子任务完成后，测试应该能跑通。
  • 先补测试，再改实现：对没有测试覆盖的旧代码，先让它补上能反映当前行为的测试，再动手修改。
  • 上下文过长就换会话：长对话可以用 /compact 压缩，切换到无关任务时用 /new 开新对话，避免旧上下文干扰。

一次只做一件事

把「修 bug + 顺便重构 + 升级依赖」放在同一个任务里，改动会难以审阅，出问题也难以回滚。拆开做，每个提交只有一个目的。

会话与上下文管理 ​

上下文（context）指模型在一次对话中能同时「看到」的全部内容，包括说明文件、对话历史和读过的代码。上下文越杂，越容易遗忘早先的约定。Codex CLI 提供了几个用于管理会话的斜杠命令：

命令作用什么时候用
/mention把指定文件附加到对话你明确知道相关代码在哪，想让它少走弯路
/compact总结当前可见对话以释放空间同一任务还要继续，但对话已经很长
/new在同一个 CLI 中开始新对话切换到无关的新任务
/fork把当前对话复制成一个新对话想尝试另一种方案，又不想破坏现有进度
/resume恢复已保存的对话回到之前中断的工作
/status查看会话配置与 token 用量判断是否该压缩或换会话

经验法则：一个会话对应一个任务分支；任务切换就开新会话，而不是在旧会话里接着说「现在换个事情」。

示例场景：修复一个线上报错 ​

示例场景：日志中出现某接口偶发返回 500。合理的推进方式是：先把报错堆栈和复现条件贴给 Codex，要求它在只读模式下定位可能原因并给出两三种假设；你确认最可能的一种后，让它先写一个能复现问题的失败测试；测试确实失败后，再让它修改实现直到测试通过；最后由你审阅 diff、运行完整测试并提交。整个过程中，「失败的测试」就是客观的验收标准。

任务范围与验收要求 ​

任务描述里最关键的两条信息是范围（改哪里、不改哪里）和验收（怎样算完成）；缺了它们，代理往往会改动过多或提前宣布完成。

任务描述模板 ​

text
目标：登录接口在网络超时后应返回明确错误，而不是一直等待。
范围：只修改 src/api/auth/ 下的文件和对应测试；不要改动数据库结构。
约束：沿用现有错误码格式；不新增第三方依赖。
验收：
- 新增一个模拟超时的测试，并通过；
- npm test 与 npm run lint 全部通过；
- 在回复中说明改动了哪些文件以及原因。

好与差的任务描述对比 ​

差的描述问题改进后的描述
帮我优化一下代码没有目标，改动范围不可控把 src/report/ 中重复的日期格式化逻辑抽成一个函数，不改变输出
修一下登录 bug没有现象和复现方式用户输入错误密码 5 次后仍能继续尝试，期望第 6 次返回锁定提示
加个缓存没有约束和验收为商品详情查询加内存缓存，过期时间可配置，新增命中与过期两个测试
把测试修好可能被理解为「删掉失败的测试」找出 tests/order 失败的原因并修复实现；不允许删除或跳过测试

验收清单（Definition of Done） ​

  • [ ] 改动只涉及任务范围内的文件；
  • [ ] 新增或修改的行为有对应测试；
  • [ ] 原有测试没有被删除、跳过或放宽断言；
  • [ ] 构建、测试、lint 全部通过，且由你本人复跑过；
  • [ ] 没有新增未说明的依赖；
  • [ ] 没有引入密钥、调试输出或临时文件；
  • [ ] Codex 的总结与实际 diff 一致。

把这份清单的通用部分写进 AGENTS.md 的「完成标准」，可以让 Codex 在每次任务结束时主动自查。

改动审阅、测试验证和代码审查 ​

AI 生成的改动和同事提交的代码一样，需要审阅后才能合并；Codex 自带的 /diff 和 /review 能帮你提速，但不能替代你自己看 diff 和跑测试。

审阅流程 ​

  1. 看改动范围：在会话内用 /diff 查看改动（包括 Git 尚未跟踪的新文件），或在终端用 git status 与 git diff --stat，确认没有超出任务范围的文件。
  2. 逐个看 diff：git diff 检查逻辑，重点看错误处理、边界条件和删除的代码。
  3. 跑测试和检查：自己执行一遍测试和 lint，不只看 Codex 的汇报。
  4. 请它自审：用 /review 让 Codex 审查工作区改动；官方说明审查可以针对未提交改动、某个提交或相对基准分支进行，审查过程不会修改你的工作区。
  5. 小步提交：确认无误后提交，提交信息写清改了什么、为什么改。
bash
git status
git diff --stat
git diff
npm test
git add -A
git commit -m "fix(auth): return explicit error on login timeout"

审阅时重点关注 ​

风险表现检查方法
改动越界修改了任务范围外的文件或配置git diff --stat 对照任务范围
测试被弱化删除、跳过或放宽了原有断言在 diff 中搜索 skip、only、被删除的 assert / expect
隐藏的副作用改了公共函数签名、全局配置或依赖版本重点看锁文件、配置文件和导出接口
安全问题把密钥写进代码、关闭了校验、拼接未转义的输入搜索 key、token、password 等关键字
看似通过的假修复用特殊判断绕过测试数据阅读实现逻辑，而不是只看测试结果

不要直接合并未审阅的改动

即使测试全部通过，也可能存在测试未覆盖的问题。生产代码的合并决定权应始终在人。

改错了怎么办 ​

  • 还没提交：git restore <文件> 撤销单个文件，git stash 暂存全部改动再对比。
  • 已经提交：git revert <提交> 生成反向提交，保留历史。
  • 方向整体错了：直接删除任务分支，从主分支重新开始，并把教训写进任务描述或 AGENTS.md。

非交互运行与自动化 ​

codex exec 是 Codex CLI 的非交互命令，适合在脚本或 CI 中执行可重复的任务；它不会停下来等你输入，所以权限设置比交互模式更要从严。

bash
# 示例：在只读沙箱中让 Codex 总结最近改动的风险
codex exec --sandbox read-only "阅读当前分支相对 main 的改动，列出可能的风险点，不要修改文件"

# 恢复上一次的非交互会话，继续追加指令
codex exec resume --last "针对你发现的第一个风险，给出修复建议"

交互会话同样可以恢复：codex resume 会列出最近的会话供你选择。

在 CI 中使用的注意事项 ​

  • 默认只读：大多数 CI 场景（审查、生成报告）不需要写权限。
  • 凭据用密钥管理：通过 CI 平台的加密变量注入 API Key，不要写在流水线文件里。
  • 限制触发来源：不要让来自外部贡献者的 PR 内容直接驱动有写权限或带凭据的任务，防止提示注入（prompt injection，指在代码或文档中埋入诱导代理执行恶意操作的文字）。
  • 结果必须人工确认：CI 中生成的改动应以 PR 形式提交，由人审阅后合并。

团队协作、交接与过程记录 ​

在团队中使用 Codex，关键是让「代理做了什么、为什么这样做」可追溯：改动走正常的分支和 PR 流程，经验沉淀到 AGENTS.md，而不是只留在某个人的会话记录里。

推荐的团队约定 ​

约定做法目的
分支命名用统一前缀，如 codex/ 开头一眼看出哪些分支由代理参与
提交粒度一个提交只做一件事，提交信息写原因便于审阅和回滚
PR 描述写明任务描述、验收标准和运行过的验证命令审阅者能按同一标准检查
人工审阅代理参与的 PR 至少由一位同事审阅避免「作者和审阅者都是 AI」
共享说明AGENTS.md 提交到仓库并通过 PR 修改所有人和所有会话使用同一套规则
个人偏好写在 ~/.codex/AGENTS.md，不放进仓库不把个人习惯强加给团队

任务交接小结 ​

一个任务告一段落、但还没有全部完成时，让 Codex 输出一份交接小结，并保存到 issue 或 PR 描述中：

text
请用以下格式总结本次工作，不要修改文件：
1. 已完成：改了哪些文件，每处改动的目的；
2. 已验证：运行了哪些命令，结果如何；
3. 未完成：还剩哪些步骤；
4. 已知问题与风险：需要人工确认的地方；
5. 下一步建议：如果明天继续，应该从哪里开始。

第二天继续时，可以用 codex resume 回到原会话；如果原会话上下文已经很长，更好的做法是开新会话，把这份小结作为第一条消息贴进去，让它在干净的上下文中继续工作。

自己验证的顺序 ​

Codex 装好却用不了时，按下面的顺序逐步排除，每一步确认没问题再进入下一步：

  1. 确认资格：打开下文「官方资格入口」中的 OpenAI 支持地区页面，确认你所在的国家或地区在名单内；用 API Key 登录时同时看 API 名单。
  2. 确认安装：运行 codex --version，能输出版本号说明命令可用。
  3. 确认登录：运行 codex login status，确认登录方式（ChatGPT 账号或 API Key）符合预期。
  4. 确认网络与证书：在启动 Codex 的同一个终端里检查代理环境变量；公司网络有 TLS 解密代理时，先配置 CODEX_CA_CERTIFICATE 再重新登录。
  5. 确认会话配置：在会话中运行 /status，看模型、沙箱和审批策略是否符合预期；命令无法联网时，先确认沙箱是否默认关闭了网络。
  6. 从小任务到大任务：先让它只读地总结项目结构，再执行一个改动小、能用测试验证的任务。

怎样记录一次有效测试

每次只改一个变量，并写下：时间（含时区）、使用的入口或命令、网络环境（家庭宽带 / 手机网络 / 公司网络）、做了什么操作、结果与报错原文。连续几次记录都指向同一环节，再去对应章节处理或向官方支持反馈，比凭印象判断可靠得多。

常见故障排查 ​

Codex 的大多数问题集中在安装路径、登录凭据、网络证书、沙箱权限和项目说明五类，先判断属于哪一类再对症处理。

症状、原因与处理对照表 ​

现象可能原因处理思路
找不到 codex 命令安装目录不在 PATH 中重新打开终端；用 which codex / where codex 检查；按安装方式的说明修复 PATH
升级后版本没变多种安装方式并存确认实际调用的路径，卸载多余的那一份
登录后仍提示未授权凭据过期或登录方式不符codex login status 查看，必要时 codex logout 后重新登录
登录时报证书 / TLS 错误企业 TLS 解密代理，根证书未被信任设置 CODEX_CA_CERTIFICATE 或 SSL_CERT_FILE 后重新登录
服务器上无法打开浏览器登录无图形环境使用 codex login --device-auth
连接超时或频繁中断网络不稳定或代理未生效确认代理环境变量设置在启动 Codex 的同一终端；参考 速度慢与断流
它运行的安装依赖命令失败沙箱默认禁止命令联网批准该次联网，或为项目开启 network_access
提示无法写入某些文件文件在工作目录外或属于受保护路径确认启动目录；.git、.codex 等本就只读
不遵守项目约定AGENTS.md 缺失、被覆盖或被截断用前文的核对命令检查实际读到的说明
改动过多、偏离目标任务缺少范围与验收用上文模板重写任务描述
回复变慢、遗忘前文上下文过长/compact 压缩，或 /new 开新对话并附上小结
用量很快用完任务过大、上下文过多拆小任务；用 /status、/usage 查看用量，规则以官方说明为准
配置似乎没生效多层配置覆盖，或项目未受信任/debug-config 查看配置层；项目级配置只在受信任项目中加载

通用排查步骤 ​

  1. 记录完整报错原文，不要只记「失败了」。
  2. 运行 codex --version 与 codex login status，排除安装和登录问题。
  3. 在会话中运行 /status，确认模型、沙箱、审批策略是否符合预期。
  4. 换一个最简单的任务（如「列出仓库根目录的文件」）测试，判断是环境问题还是任务问题。
  5. 网络相关问题，先在同一终端用其他命令确认能访问外网，再检查证书和代理变量。
  6. 仍无法解决时，用 /feedback 向官方反馈日志，或到 openai/codex 仓库检索 issue。

适合与不太适合的工作 ​

Codex 最适合目标清楚、能用测试验证的工程任务；需求模糊、风险高或需要接触生产环境的工作，应由人主导、代理辅助。

适合需要谨慎
根据报错定位并修复 bug涉及资金、权限、安全的核心逻辑
为已有代码补充测试没有测试覆盖的大规模重构
按明确规范做批量修改需求本身尚未想清楚的新功能
阅读陌生代码库、写说明文档需要访问生产环境或真实用户数据的操作
代码审查前的自查处理受保密协议约束、不允许外传的代码

数据与合规提醒

使用 Codex 时，你的代码片段和命令输出会发送到 OpenAI 服务进行处理。处理公司代码前，请确认符合所在单位的数据政策；数据使用规则以 OpenAI 官方隐私政策和企业协议为准。

官方资格入口 ​

Codex 需要 ChatGPT 账号或 OpenAI API 账号，服务只在 OpenAI 支持的国家和地区提供。下面只列官方页面：

产品官方页面说明
ChatGPT（网页版与应用）OpenAI 帮助中心：ChatGPT 支持的国家和地区ChatGPT 与 Codex 的地区要求以此为准
OpenAI APIOpenAI 开发者文档：API 支持的国家和地区与 ChatGPT 名单分开列出，两份不一定相同

以官方页面为准

名单会随时调整，本站只提供官方页面的入口，不代为判断某个账号能否使用，请以官方页面当前内容为准，并遵守所在地法律法规与各服务的使用条款。

依据与来源 ​

信息来源核验时间
安装命令（脚本、npm、Homebrew、Windows PowerShell）、开源许可证、IDE 扩展与桌面应用GitHub openai/codex 仓库 README（github.com/openai/codex）；Codex CLI 文档 learn.chatgpt.com/docs/codex/cli.md2026-10-07
斜杠命令（/init、/permissions、/review、/diff、/status、/compact、/new、/plan、/debug-config 等）Codex 命令文档 learn.chatgpt.com/docs/developer-commands.md?surface=cli2026-10-07
codex login、--with-api-key、--device-auth、凭据存放方式、CODEX_CA_CERTIFICATE、SSL_CERT_FILE、forced_login_methodCodex 身份验证文档 learn.chatgpt.com/docs/auth2026-10-07
沙箱模式、审批策略、--sandbox、--ask-for-approval、--yolo、受保护路径、网络默认关闭Codex 审批与安全文档 learn.chatgpt.com/docs/agent-approvals-security2026-10-07
config.toml 位置与配置项Codex 配置参考 learn.chatgpt.com/docs/config-file/config-reference2026-10-07
AGENTS.md 读取顺序、override 文件、32 KiB 默认上限、核对命令Codex AGENTS.md 文档 learn.chatgpt.com/docs/agent-configuration/agents-md2026-10-07

常见问题 ​

Codex 有哪些使用方式？

OpenAI Codex 提供命令行工具 Codex CLI、编辑器扩展、桌面应用，以及在 chatgpt.com/codex 使用的云端任务。它们面向同一类编程代理工作，适合的场景略有不同。

Codex CLI 怎么登录？

运行 codex 后选择用 ChatGPT 账号登录，或执行 codex login；也可以把 API Key 通过标准输入传给 codex login --with-api-key，此时按 OpenAI API 的用量计费。没有浏览器的服务器可用 codex login --device-auth。

AGENTS.md 是什么？

AGENTS.md 是放在仓库中的说明文件，告诉 Codex 项目结构、构建与测试命令和编码约定。在 Codex CLI 中运行 /init 可以生成初稿，Codex 会从 Git 根目录到当前目录逐级读取。

Codex CLI 是开源的吗？

是。Codex CLI 的源代码托管在 GitHub 的 openai/codex 仓库，采用 Apache-2.0 许可证。

Codex 的沙箱模式有哪几种？

官方提供 read-only、workspace-write 和 danger-full-access 三种沙箱模式。在 Git 仓库中通常建议 workspace-write 搭配 on-request 审批，danger-full-access 只应在隔离环境中使用。

为什么 Codex 执行的命令无法联网？

在 workspace-write 沙箱中，命令的网络访问默认关闭。确有需要时可以在 config.toml 的 [sandbox_workspace_write] 中设置 network_access = true，或在需要时通过审批临时放行。

公司网络有 TLS 解密代理，Codex 登录报证书错误怎么办？

官方文档建议在登录前设置 CODEX_CA_CERTIFICATE 指向企业根证书的 PEM 文件，Codex 也会读取 SSL_CERT_FILE 作为后备，然后重新执行 codex login。

AGENTS.md 写了但 Codex 好像没读到怎么办？

先确认文件不是空的、启动目录在仓库内，再检查上层目录有没有 AGENTS.override.md 覆盖了它。可以运行 codex --ask-for-approval never 加一句让它总结当前指令的提示来核对。

延伸阅读 ​

更新记录 ​

日期变更
2026-10-07首次发布完整内容
2026-10-07扩写为深度指南
2026-10-08按搜索结果页结构调整：开头直接回答、增加速查表、「自己验证的顺序」与「官方资格入口」（仅链接官方页面）

本专题文章 ​

暂无文章，敬请期待。