2026 Codex 教程：从安装登录到第一个真实任务

30 秒路线

Codex 新手先完成这 8 步

1. 只选一个入口

   桌面 App、CLI、IDE、Cloud 先选最符合当前代码位置的一种，不要同时配置四套。

2. 确认账号与计费

   个人交互式使用通常先用 ChatGPT 登录；API Key 是单独 Platform 账单。

3. 准备测试仓库或新分支

   确保 git status 可理解，重要文件已有备份，避免把第一次任务放进生产目录。

4. 从小任务开始

   选择能在 10–20 分钟内验收的 Bug、测试或文档改动，不要第一句就要求重写整个系统。

5. 写清四项 Prompt

   目标、上下文、约束、完成标准。

6. 复杂任务先 Plan

   让 Codex 先读代码、提出计划和风险，确认范围后再写。

7. 要求自动验证

   运行相关测试、lint、类型检查或最小复现，记录无法运行的检查。

8. 人工检查 Diff

   确认只修改了预期文件、没有泄露凭证、错误确实消失，再决定提交。

想把菜单或回答改成中文：查看 Codex App、CLI、IDE 中文设置与不生效排查。

先选入口

Codex App、CLI、IDE、Cloud 怎么选

想进一步理解入口边界，先读 Codex App、CLI、IDE 与 Cloud 的完整区别。Windows、macOS/Linux 的安装错误分别进入对应专题，不在本页复制所有平台细节。

安装与登录

CLI 最短安装路线与账号检查

CLI 用户可按 OpenAI 当前包名安装；如果已经安装，先看版本，不要无目的地反复重装：

npm install --global @openai/codex
codex --version
codex login
codex login status

# 进入你真正要处理的仓库后再启动
cd /path/to/your/repository
codex

macOS/Linux 的 install.sh、npm、Homebrew、PATH 与多版本问题见 Codex macOS/Linux 安装更新；Windows App、PowerShell CLI 与 WSL2 见 Codex Windows 安装。

真正上手

第一个任务不要选“重写整个项目”

优秀的第一个任务具备三个特点：范围小、结果可观察、验证命令明确。例如修复一个已有复现的 Bug、为一个纯函数补测试、更新失真的 README 步骤，或者解释某段代码并提出不写入文件的方案。

目标：修复登录表单连续点击时会重复提交的问题。
上下文：先阅读 src/auth/LoginForm.tsx 和现有测试；不要修改服务端 API。
约束：保持现有 UI 与错误文案；不要新增依赖；先说明根因和计划。
完成标准：新增回归测试，运行相关测试和 lint，最后总结改动文件、验证结果与剩余风险。

Prompt 模板

把目标、上下文、约束、完成标准写全

复杂任务先输入 /plan 或明确要求“先调查和规划，确认后再修改”。它的价值不是增加文字，而是提前暴露错误范围、缺失信息和高风险操作。

权限与安全

第一次使用保持默认权限，不要直接 YOLO

• 工作目录就是权限边界启动前检查路径；不要为了方便从用户目录或磁盘根目录运行。
• 审批和 Sandbox 是两件事审批决定何时询问，Sandbox 决定实际能读写和联网的范围。
• 先读命令再批准特别检查删除、覆盖、数据库迁移、发布、发消息和包含环境变量的命令。
• 不要提交 SecretsAPI Key、Cookie、Session、私钥和生产凭证不应进入 Prompt、日志、截图或 Git Diff。
• 只放宽具体需要默认权限无法完成时，先理解失败原因，再对明确目录或命令授权。

遇到 permission denied、read-only、网络受限，按 Codex Sandbox 与权限分流处理，不要把 --dangerously-bypass-approvals-and-sandbox 当成通用安装参数。

让效果可复用

第一个任务成功后再写 AGENTS.md

CLI 中可用 /init 生成起点，但生成后要人工精简。最有用的内容是仓库结构、构建测试命令、工程约束、禁止事项和完成标准，不是泛泛而谈“写高质量代码”。

# AGENTS.md

## Commands
- Install: npm ci
- Test: npm test
- Lint: npm run lint

## Constraints
- Do not edit generated files under dist/.
- Do not add dependencies without explaining why.
- Preserve existing public API behavior.

## Done when
- Relevant tests and lint pass.
- Summarize changed files and remaining risks.

全局、仓库、子目录的覆盖顺序与 32 KiB 限制见 Codex AGENTS.md 完整教程。

验收闭环

不要在 Codex 说“完成”时立刻合并

1. 查看 git status 和完整 Diff，确认文件范围。
2. 运行与改动直接相关的测试，再按项目约定运行 lint、类型检查或构建。
3. 核对 Codex 的测试命令是否真的执行成功，而不是只写“应该通过”。
4. 检查错误处理、边界条件、日志、凭证与数据迁移风险。
5. 使用 /review 或独立审查检查未提交变更，但最终仍由人决定是否接受。
6. 提交前总结变更、证据、没有运行的检查和仍需人工确认的事项。

把“运行测试、检查 Diff、解释剩余风险”写进 Prompt 或 AGENTS.md，Codex 才更可能稳定地执行同一套完成标准。

CLI 速查

新手最常用的 Codex 命令

按错误分流

Codex 第一次运行常见问题

FAQ

Codex 入门与使用常见问题

Codex 新手应该用 App、CLI 还是 IDE？

想可视化管理项目、聊天和 Diff 可先用桌面 App；长期在终端工作选 CLI；希望边编辑边对话选 IDE。需要远端仓库、并行任务或 PR 工作流时再进入 Cloud。

Codex CLI 第一次怎么运行？

进入目标 Git 仓库，运行 codex login 完成认证，再运行 codex。先保持默认权限做一个小任务，完成后运行测试并检查 Diff。

ChatGPT Plus 包含 Codex 吗？

符合当前套餐与地区条件时，可通过 ChatGPT 登录使用套餐内 Codex 用量。API Key 登录走独立 Platform API 计费；购买 Plus 不能修复 API Billing 不足。

Codex 改错代码如何恢复？

优先在 Git 分支或 Worktree 中运行，先检查 Diff，再用版本控制恢复明确的目标文件。不要在范围不清时使用覆盖整个工作区的命令。

第一个 Codex Prompt 应该怎么写？

至少包含目标、相关文件或错误、约束和完成标准。复杂任务先要求计划；写入完成后要求运行测试、检查 Diff、列出没有验证的事项。