Codex CLI 上手指南：完成首个任务，配好团队协作

如果你已有能正常运行的项目和具备访问权限的账号，可以先留出 15 分钟完成初次上手。安装、登录或运行较慢的测试套件可能需要更长时间。首次尝试的理想结果，是完成一项经过验证的小改动，或者准确说明卡在哪里。本文命令核对于 2026 年 10 月 11 日。

Codex CLI 安装后，先完成一个有用的小任务

Codex 直接在项目中工作，可以查看和修改文件，也能调用你电脑上已安装的工具。可以把它当作在另一张工作台上工作的项目贡献者：任务和边界由你来定，结果是否应该进入产品，仍由你决定。OpenAI CLI 指南

第 0 至 3 分钟：选定一种安装方式

在 macOS 或 Linux 上，可以使用独立安装脚本：

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

如果其他方式更适合现有环境，也可以选择下面的途径。确定一种即可，后续升级时也更清楚该怎么操作。

在 Windows 上，文档给出的命令如下，需要在新开的 PowerShell 窗口中运行：powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"。

以上方式均来自当前 CLI 文档和官方仓库。启动 Codex 前，先在终端中进入项目目录。

第 3 至 5 分钟：选择 ChatGPT 登录或 API 密钥

首次进行交互式操作时，如果你的套餐和工作区提供访问权限，可以直接用 ChatGPT 登录。运行 codex login，然后在浏览器中完成登录流程。尚未登录时直接运行 codex，也会看到 Sign in with ChatGPT（使用 ChatGPT 登录） 选项。

如果打算使用 OpenAI Platform 账号，例如运行程序化工作流，则选择 API 密钥认证。先在 shell 环境中设置好 OPENAI_API_KEY，再运行文档提供的 macOS/Linux 命令：printenv OPENAI_API_KEY | codex login --with-api-key。不要把密钥写入仓库文件。

运行 codex login status，确认当前使用哪种认证方式。团队使用时尤其要分清：ChatGPT 认证遵循 ChatGPT 工作区的管控规则，API 认证则遵循 API 组织的管控规则。认证指南

**费用：**通过 ChatGPT 登录，使用的是符合条件的套餐所包含的访问权限；使用 API 密钥则由 OpenAI Platform 按 API 费率单独计费。套餐对比可查看我们的 Codex 定价指南。团队试用时，应把人工完成任务的耗时，与编写提示词、审查和修正结果的总耗时进行比较，再从实际节省时间的价值中扣除新增使用费用。只有最终验收所需的总工作量下降，更快得到初稿才真正划算。OpenAI 对认证与计费方式的说明

第 5 至 8 分钟：先检查，再修改

先用 Git 留下一个可回退的检查点。在项目的 shell 提示符下，使用文档给出的命令启动检查会话：codex --sandbox read-only --ask-for-approval on-request。

给它一个范围明确的排查任务。例如，可以按项目情况调整下面这段提示词：

这是一种工作流程建议，并非 Codex 的特殊命令。读完回答后，确认它找对了应用中的相关部分。只读沙箱允许在自身边界内检查内容和执行命令，超出边界的操作可能需要审批。审批与沙箱指南

第 8 至 12 分钟：授权一项小改动

准备好后，用 /permissions 切换到允许编辑工作区的权限。若要新开会话，文档给出的组合是 codex --sandbox workspace-write --ask-for-approval on-request。

接着明确验收条件：

从你能迅速判断对错的任务开始。为已知行为补测试，比笼统地要求它改进架构更适合作为首次任务。

第 12 至 15 分钟：检查代码差异和验证结果

用 /diff 查看补丁，用 /review 发起审查。核对实际测试输出、改动涉及的文件，以及结果是否满足验收条件。自己审查通过后再提交。这些斜杠命令应在 Codex 会话内使用，不能直接输入 shell 提示符。CLI 命令参考

先建立基准，再选择模型

先用当前会话中可用的模型完成任务，再通过 /model 切换模型或调整推理强度。OpenAI 当前给出的启动示例是 codex --model gpt-6.1-sol。

在账号和客户端支持的前提下，目前复杂编程任务推荐使用 GPT-6.1 Sol，范围集中、重复性强的任务推荐使用 GPT-6 Luna。更高的推理强度有助于处理困难的分析任务，但也会增加耗时和 token 用量。比较结果时，应保持初始任务和推理强度设置一致。Codex 模型指南

团队上手时，把所用模型、任务内容和测试结果一并记录。选中了某个模型名称，并不意味着账号就获得了该模型的访问权限。

沙箱访问范围与审批策略要分别设置

沙箱规定命令能访问什么，审批策略规定 Codex 何时必须先征求同意。可以把沙箱理解为工作间的墙，审批策略则决定什么时候需要请求开门。

交互式操作可以使用 on-request：沙箱内获准的操作可以直接执行，需要更广访问范围的操作则可能发起审批请求。never 表示 Codex 无法请求审批，并不代表移除了沙箱限制。被阻止的操作仍可能无法执行。

设置写入边界，并不意味着每次编辑前都会弹出审批。使用 workspace-write 和 on-request 时，Codex 可以自动修改工作区文件并运行获准的命令。通过 /permissions 可以查看当前设置。OpenAI 对沙箱与审批行为的说明

如果团队旧模板中还写着 approval_policy = "untrusted"，应及时更新。OpenAI 已停用这一显式设置，并指出它可能导致启动失败。旧的 codex exec --full-auto 用法也已弃用。应改用文档中的沙箱与审批设置。当前迁移指南

用 AGENTS.md 写清团队工作约定

把仓库的工作方式写进 AGENTS.md，就不用在每次任务中重复交代。Codex 会在任务开始时读取这些说明。/init 可以生成初始模板，但团队正式使用前，应由维护者修改确认。

一份有用的仓库说明应回答四个问题：

• 开发者如何安装依赖、运行项目？
• 一项改动需要运行哪些测试和检查？
• 哪些目录包含生成文件，或需要格外谨慎地处理？
• 完成报告应包含哪些内容，例如行为变化、已运行的测试和尚未解决的失败？

写入实际使用的命令和约定，避免堆砌泛泛的愿望。个人偏好放在 ~/.codex/AGENTS.md，团队共用的仓库说明则放在项目根目录并提交到版本库。

Codex 先加载全局说明，再从项目根目录沿路径读取到当前目录。越靠近当前目录的说明，优先级越高；同一目录下，AGENTS.override.md 优先于 AGENTS.md。修改说明后，应重启会话，并让 Codex 概述它加载了哪些规则。AGENTS.md 查找规则

把这个文件当作项目贡献者手册。需要在技术层面强制执行的限制，应通过配置和受管理的要求来实现。

config.toml 保持精简，便于审查

个人默认设置保存在 ~/.codex/config.toml。团队共用的项目默认设置放在 .codex/config.toml，Codex 只会在受信任的项目中加载它。这些文件使用 TOML，一种以名称组织配置项的文本格式。

下面的起步配置组合了 OpenAI 配置指南中的取值。只有账号能使用该模型时，才保留模型这一行：

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

CLI 参数和 --config 覆盖项优先于项目配置。受信任的项目设置优先于选定的配置档和用户默认设置。无论默认值是什么，组织要求都可能进一步约束允许使用的设置。配置基础

web_search = "cached" 表示使用缓存的网页搜索结果，与 shell 命令的网络访问权限是两回事。即使 Codex 有网页搜索工具，下载依赖仍可能需要审批。应在团队上手说明中讲清这一区别，避免命令一失败就放宽权限。

有明确需求时，再添加 MCP 服务器

MCP 即 Model Context Protocol（模型上下文协议），用于让 Codex 连接工具和外部上下文。本地服务器以进程运行，远程服务器则通过 HTTP 地址访问。当任务所需的信息或操作无法由仓库本身提供时，再添加相应服务器。

OpenAI 文档中的示例是 codex mcp add context7 -- npx -y @upstash/context7-mcp。这会通过 npx 启动文档服务器，因此环境中必须能使用该启动器。运行 codex mcp list 查看已配置的服务器，再在会话内用 /mcp 检查当前连接。对于支持 OAuth 的服务器，使用 codex mcp login <server-name>，把占位符替换成配置中的服务器名称。

服务器配置放在同一套 TOML 配置系统的 [mcp_servers.<server-name>] 下。团队可以通过 enabled_tools 和 disabled_tools 限制对外开放的工具；先应用允许列表，再应用禁用列表。起步时只开放满足需求的最小工具集合。MCP 设置与配置

工具响应过大是另一个问题，可阅读我们的 Codex CLI MCP 输出限制详解。连接服务器与控制返回内容的长度，需要分别考虑。

任务需要独立检出目录时，再用 worktree

Git worktree 能为任务提供独立的仓库检出目录。当你希望把实验性修改与当前正在处理的文件分开时，它就很有用。

OpenAI 在 0.154.0 版本中为 CLI 任务、交互式会话和会话分支加入了受管理的 worktree。该功能受实验性 worktrees 开关控制，目前仅支持本地会话。先使用 CLI 文档中的功能启用命令 codex features enable worktrees 打开这个开关，再通过 codex --worktree 启动。发布说明、交互式 worktree 实现、功能管理命令

在支持这一功能的会话内，/worktree 可以让你在受管理的检出目录中开启新对话，或从当前会话创建分支。分支会携带对话历史，新对话则从空白开始。使用这些选项需要先启用功能，并在本地 Git 仓库中操作。Worktree 会话命令

审查、整合和清理工作需要自行安排。CLI 实现中，这些受管理检出目录的自动清理仍处于关闭状态。独立检出目录也不能替代沙箱设置或合并前的审查。受管理检出目录的生命周期

准备开始并行任务时，可参考我们的 Codex CLI worktree 指南。首次尝试补测试，用一个检出目录就够了。

小团队值得先尝试的六类任务

下面是任务建议，并非经过测量的效率结论。优先选择最容易核对验收条件的任务。

Codex 无法替你补齐缺失的产品决策，也不能证明通过测试就覆盖了所有风险。验收条件和人工审查仍是工作的一部分。更全面的评估可阅读我们的 Codex 评测；选购对比可查看 Codex 与 Claude Code 对比。

技术型创始人可以做的两款小工具

更值得优先尝试的是面向单一技术栈的回归测试服务。为已有明确 bug、测试覆盖又不足的小团队，提供经过审查的测试补丁。最小可用版本接收一个可复现的用例，在独立检出目录中执行范围受限的 Codex 任务，然后交付补丁和测试证据。2026 年 10 月 11 日获取的 DataForSEO 美国关键词估算显示，“automated software testing services”每月搜索量为 880。这反映的是对这类工作的需求，而非购买该产品的意愿。难点在于可靠的测试夹具和有意义的断言；只是重复实现逻辑的测试，价值有限。

第二个方向是面向特定仓库的审查助手。如果审查能遵循团队已记录的约定，并给出简短、可验证的问题清单，工程负责人可能愿意付费。可以先从一个仓库、它的 AGENTS.md 和可重复执行的审查流程开始。同一次需求核查估算，“ai code review”在美国的月搜索量为 1,300。难点在于差异化：Codex 本来就能审查代码，因此产品必须让结果更贴合项目，并减少误报。相比之下，测试生成的初始交付物更明确，因为买方可以直接检查并运行你交付的内容。

Codex CLI 上手常见问题

周一可以请一位维护者和两位队友一起跑一遍同样的小任务，记录审查与修正所需的投入，并针对交接不顺畅的地方修改共用说明。等团队能够稳定重复这一流程，再扩大使用范围。

如果你希望围绕这些控制机制建立仓库工作流程，可以了解我们的 AI 生产系统开发服务。