Codex 完整介绍：从本地编码到云端任务

本文根据 OpenAI 官方 Codex 手册整理，信息更新至 2026 年 7 月。Codex 更新很快，模型、套餐和命令请以当前客户端与官方文档为准。

Codex 到底是什么

Codex 是 OpenAI 提供的一套 AI 编程代理，而不只是一个“帮你补全代码”的模型。它可以读取仓库、搜索调用关系、编辑文件、执行命令、运行测试，并根据执行结果继续调整方案。

普通聊天工具通常给出一段代码，剩下的复制、运行和排错仍由人完成。Codex 更接近一名能够操作开发环境的协作者：你描述目标和边界，它在仓库中完成理解、修改与验证，再交付可以审查的 diff。

目前常见的使用入口包括：

Codex CLI：运行在终端中，适合本地开发、脚本和 CI
IDE 扩展：在编辑器侧边栏中工作，可直接使用打开的文件和选中代码作为上下文
ChatGPT 桌面应用中的 Codex：适合同时管理项目、文件、工具和较长任务
Codex cloud：在隔离的云端环境中执行任务，适合并行处理、后台运行和生成可审查的改动

它们并不是四套完全独立的产品。本地 CLI、IDE 和桌面端共享不少账号与配置约定；云端则把执行环境放进隔离容器中，工作方式和网络策略会有所不同。

安装 Codex CLI

macOS 与 Linux

官方提供独立安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

也可以使用 npm 或 Homebrew：

npm install -g @openai/codex

# 或者
brew install --cask codex

Windows PowerShell

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

安装完成后检查版本：

codex --version

如果使用 npm 或 Homebrew 安装，后续升级仍通过对应的包管理器完成。直接执行远程安装脚本前，也应确认链接来自 Codex CLI 官方页面。

登录方式怎么选

进入项目目录并运行 codex，首次启动会引导登录。Codex 本地客户端支持两种主要认证方式。

使用 ChatGPT 账号

codex login

CLI 会打开浏览器完成登录。CLI 与 IDE 通常可以共享登录状态，适合已经通过 ChatGPT 套餐使用 Codex 的个人或团队。

使用 OpenAI API Key

printenv OPENAI_API_KEY | codex login --with-api-key

API Key 适合按 API 用量计费、本地脚本或自动化环境。需要注意的是，API Key 登录不包含部分依赖 ChatGPT 账号的云端能力；Codex cloud 需要使用 ChatGPT 登录。

可以随时检查或清除登录状态：

codex login status
codex logout

认证文件可能保存在系统钥匙串或 ~/.codex/auth.json。后者包含敏感凭据，不能提交到 Git、上传到网盘或复制进工单。

第一次任务应该怎么写

进入一个已经使用 Git 管理的项目：

cd 你的项目目录
codex

不要只输入“优化一下项目”。一个容易执行和验收的任务，至少应包含四部分：

目标：修复文章列表在手机端横向溢出的问题。

上下文：页面位于 src/pages/posts，样式使用 Tailwind CSS。

约束：不要修改桌面端布局，不新增依赖，保持现有组件接口不变。

完成标准：在 375px 和 768px 宽度下检查页面，运行现有测试，并总结修改文件和验证结果。

这四部分分别回答“做什么、从哪里入手、什么不能动、怎样才算完成”。任务越复杂，完成标准越重要。

如果改动范围较大，可以先进入计划模式：

/plan

让 Codex 先梳理方案、风险和验证方法，再开始修改。计划不是形式上的步骤列表，而是提前暴露依赖、歧义和潜在破坏面。

权限机制：沙盒和审批是两件事

Codex 本地客户端用两层机制限制风险：

沙盒决定命令在操作系统层面能够访问哪些文件、是否能够联网
审批策略决定遇到越界或高风险操作时，是询问用户、拒绝，还是按预设方式继续

常见沙盒模式包括：

模式	能力	适合场景
`read-only`	可以读取，但不能修改工作区	陌生仓库分析、代码审查
`workspace-write`	可以在工作区内修改，越界操作需要审批	日常开发，推荐默认使用
`danger-full-access`	不受工作区沙盒限制	仅限已经隔离且完全受控的环境

在使用 Git 管理的仓库中，日常工作通常保持 workspace-write 和按需审批即可。Codex 默认不会让本地代理任意访问网络；安装依赖、请求外部 API 等操作可能需要额外授权。

可以在交互界面使用 /permissions 查看或调整当前权限。不要因为审批提示频繁，就长期启用 danger-full-access。更好的办法是把可信目录、允许命令和联网范围收窄到任务真正需要的部分。

用配置文件保存个人与项目偏好

Codex 的主要配置文件使用 TOML 格式：

~/.codex/config.toml：当前用户的默认设置
.codex/config.toml：项目级设置，适合团队共享

一个保守的本地配置可以这样写：

model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

项目级配置只会在仓库被标记为可信时加载。这样可以避免刚打开一个陌生仓库，就自动执行其中的钩子、规则或外部连接配置。

配置存在多层优先级：临时 CLI 参数通常高于项目配置，项目配置高于个人默认值。排查“为什么设置没有生效”时，先运行 /status，再检查是否有更高优先级的参数覆盖了它。

AGENTS.md：把团队规则写进仓库

AGENTS.md 是 Codex 自动读取的项目指令文件。它适合记录：

项目结构和主要入口
安装、构建、测试、Lint 命令
代码风格与架构边界
禁止修改的文件或兼容性要求
每类任务完成前必须执行的验证

在项目中运行 /init 可以生成一个起始版本，然后再按真实工作流删改。一个简短、准确的 AGENTS.md，通常比堆满抽象原则的长文档更有用。

Codex 支持分层指令：个人规则可以放在 ~/.codex/AGENTS.md，仓库根目录保存团队通用规则，子目录还可以提供更具体的 AGENTS.md。越接近当前工作目录的规则优先级越高。

例如，仓库根目录可以要求所有改动运行完整测试，而 docs/AGENTS.md 可以补充文档链接和术语规范。这样无需把所有细节塞进一个文件。

几个最实用的命令

交互命令

命令	作用
`/status`	查看模型、账号、工作目录和权限状态
`/model`	查看或切换当前可用模型与推理设置
`/permissions`	管理沙盒与审批策略
`/plan`	先规划任务，暂不直接修改文件
`/review`	只读审查分支、提交或未提交改动
`/init`	为当前项目生成 `AGENTS.md` 起始文件

终端子命令

# 审查尚未提交的改动
codex review --uncommitted

# 恢复之前的交互会话
codex resume

# 检查本地安装和配置
codex doctor

提交前至少完成三件事：查看 diff、运行与改动相关的测试、确认没有意外加入密钥或生成文件。AI 能够缩短修改时间，但不能替你承担合并错误改动的责任。

用 codex exec 做脚本和 CI

codex exec 会完成一次非交互任务，输出结果后退出：

codex exec "梳理仓库结构并列出五个高风险模块"

非交互模式默认使用只读沙盒。如果任务确实需要修改文件，要显式开放工作区写权限：

codex exec --sandbox workspace-write \
  "修复当前失败的单元测试，限制改动在 src/utils，并说明验证结果"

自动化还可以输出 JSON Lines，便于下游程序处理事件：

codex exec --json "审查当前仓库并按严重程度输出问题" | jq

在 CI 中不要把长期有效的 API Key 暴露给不可信的构建脚本。官方对 GitHub Actions 推荐使用 openai/codex-action，并把生成补丁与获得仓库写权限拆到不同任务中。

本地执行和云端任务怎么选

本地 Codex 更适合下面这些情况：

项目依赖本机数据库、设备或内部服务
需要和编辑器、终端频繁来回验证
源码不能离开受控开发环境
希望逐条审批命令和文件访问

Codex cloud 更适合：

把耗时任务放到后台执行
同时处理多个相互独立的问题
在隔离环境中复现、测试并生成 diff
围绕 GitHub 仓库创建可审查的改动

云端任务会在隔离容器中检出仓库并运行配置好的安装步骤。环境的 setup 阶段可以联网准备依赖，代理工作阶段默认不开放网络，除非你显式配置。云端同样会读取仓库中的 AGENTS.md。

Codex 适合做什么，不适合替代什么

Codex 很适合理解陌生代码、修复范围明确的 bug、补测试、批量迁移、重构、代码审查和生成项目文档。它也能把重复流程封装成 skills、MCP 连接、钩子或自动化任务。

但它不能替代产品决策、权限治理和最终代码责任。需求含糊时，它可能很高效地完成错误目标；测试不足时，“测试通过”也不代表行为正确；权限过宽时，一个错误命令仍可能造成真实损失。

比较稳妥的工作方式是：先让 Codex 调查并给出证据，再限定改动范围，最后用测试、diff 和人工审查闭环。把它当作能够执行任务的工程协作者，而不是永远正确的自动驾驶。