Codex 是 OpenAI 面向软件工程的编程智能体：同一套能力可以出现在终端 CLI、IDE 扩展、ChatGPT / Codex Web，以及桌面端等入口。它不只「补全几行代码」，而是能读仓库、改文件、跑命令、做审查，并在权限与沙箱策略下推进到可验收结果。本文按「它是什么 → 安装 → 登录配置 → 日常写代码 → 文档与非代码辅助 → 安全与进阶 → 官方入口」展开，尽量写细，方便对照上手。
一、Codex 是什么：先建立正确预期
可以把 Codex 理解成「能干活的工程助手」，而不是「只会聊天的补全插件」。
1. 同一 Agent，多种表面
| 入口 | 适合谁 | 典型用途 |
| --- | --- | --- |
| Codex CLI | 习惯终端、要进 CI 的人 | 本地交互改码、无头脚本、流水线 |
| IDE 扩展 | 长期泡在编辑器里的人 | VS Code / Cursor / Windsurf 等就地改码与看 diff |
| Codex Web / ChatGPT | 要并行、要云端长任务的人 | 浏览器发起任务、开 PR、远程继续 |
| Desktop / App | 想统一盯多任务的人 | 可视化会话、调度与监控（以产品当前能力为准） |
CLI 是开源组件（Apache-2.0，仓库见 GitHub openai/codex），本机运行；云端任务则在隔离环境中执行。配置目录常见为 ~/.codex/，多入口可共享同一套登录与配置习惯。
2. 它擅长什么
- 跨文件实现功能、重构、修 bug
- 跑测试 / 构建并根据失败继续改
- 写提交说明、整理变更、辅助开 PR
- 代码审查（找风险点、兼容性问题）
- 把重复流程沉淀成 Skills / 可复用指令
3. 它不替代什么
- 不替代你对业务目标与上线风险的最终判断
- 不替代代码审查里的人工拍板
- 不保证「一次提示就完美」——需要审查 diff、补充约束、必要时回滚重来
二、安装：CLI / IDE / Web 三条路径
建议至少装通 CLI + 一个编辑器扩展；云端入口用浏览器即可，不必本机再装。
1. 安装 Codex CLI（推荐优先）
macOS / Linux（官方脚本）：
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows（PowerShell）：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"其他常见方式：
# npm（需本机已有 Node.js，版本要求以官方当前说明为准）
npm install -g @openai/codex
# Homebrew（macOS）
brew install --cask codex也可以从 GitHub Release 下载对应平台二进制。装好后执行：
codex --version
codex第一次运行会引导登录。
2. 安装 IDE 扩展
在 VS Code、Cursor、Windsurf 的扩展市场搜索 Codex（发布方为 OpenAI / 官方扩展名以商店为准）并安装。
JetBrains、Xcode 等环境可能有独立集成路径，不等同于 VS Code 扩展包，需按对应 IDE 文档配置。
IDE 里的价值是：改动直接落在工作区，diff 更直观，适合「边看文件边指挥 Agent」。
3. 使用 Codex Web（浏览器）
打开 https://chatgpt.com/codex，用 ChatGPT 账号登录后即可发起云端任务。适合：
- 本机暂时不方便跑重任务
- 要并行多条任务
- 希望任务在云沙箱里跑完再回来看 PR / 结果
4. 桌面端（可选）
若你使用 ChatGPT / Codex 桌面应用，可在其中进入 Code / Codex 相关入口（界面文案以当前版本为准），用于盯会话、调度任务。CLI 用户也可关注 codex app 一类启动方式（以 codex --help 与官网说明为准）。
三、登录、权限与第一次安全配置
1. 登录方式
- 推荐：Sign in with ChatGPT
使用 Plus / Pro / Business / Edu / Enterprise 等计划中的 Codex 额度（具体包含项以 OpenAI 帮助中心当前说明为准）。
- 备选：API Key
按量计费，适合自动化与独立账单；部分云端能力可能受限，需按官方鉴权文档额外配置。
2. 先搞懂两个安全旋钮
Codex CLI 的安全模型可以粗分为两轴：
沙箱（Sandbox）——它「物理上」能碰哪里
| 常见档位 | 含义（概念） |
| --- | --- |
| read-only | 偏只读探索，改动能力受限 |
| workspace-write | 可在工作区内写入（日常本地开发常用起点） |
| danger-full-access | 权限很大，仅在你明确清楚风险时使用 |
审批（Ask for approval）——它「要不要先问你」
| 常见档位 | 含义（概念） |
| --- | --- |
| untrusted / 更严 | 更多动作需要确认 |
| on-request | 按策略在需要时询问（常见默认思路） |
| on-failure | 失败相关场景再介入 |
| never | 尽量不问（只适合高度可信、隔离环境） |
本地新手建议从「可写工作区 + 需要时询问」开始，而不是一上来全自动绕过审批。
示例（具体枚举以当前 CLI --help 为准）：
codex --sandbox workspace-write --ask-for-approval on-request3. 配置文件放哪
全局配置常见路径：~/.codex/config.toml
可在此固定默认模型、沙箱、审批策略、MCP、profile 等。项目级还可以放说明文件（如 AGENTS.md / 团队指令文件，名称以你团队约定与当前 Codex 文档为准），让 Agent 每次都读到仓库规范。
4. 第一次验证清单
codex --version有输出codex能进入交互界面并完成登录- 在一个练习仓库里让它「只解释项目结构，先不改文件」
- 再给一个小改动任务，确认你会看到审批 / diff
四、日常写代码：从交互会话到无头执行
1. 交互模式（最常用）
进入项目目录：
cd your-project
codex然后用完整句子下任务。好提示通常包含：
- 目标：要完成什么
- 范围：哪些目录可以动 / 不能动
- 验收：如何证明做完（测试命令、页面路径、接口行为）
- 约束：不要升级大版本依赖、不要改 CI 密钥等
示例：
给 user 模块补上邮箱格式校验：
1) 修改校验函数与对应单测
2) 跑相关测试并修到通过
3) 不要改无关模块
4) 最后用中文写一段变更说明2. 会话内斜杠命令（提高操控感）
在交互界面输入 / 可调出命令（具体列表随版本变化，以当前会话为准），常见用途包括：
| 命令（示例） | 作用 |
| --- | --- |
| /model | 切换模型与推理力度 |
| /plan | 先出计划再执行 |
| /review | 审查工作区变更 |
| /permissions | 调整权限/自主度 |
| /status | 查看当前状态 |
| /agent / /subagents | 查看或切换子代理线程 |
| /compact | 压缩过长上下文 |
| /new | 开新会话 |
大改动前先 /plan，能减少「上来就改炸」的概率。
3. 无头模式：给脚本和 CI 用
# 概念示例：非交互执行（子命令名以 codex --help 为准）
codex exec "review the changed files for obvious security issues"也可配合输出格式、指定目录、附加图片等参数。适合：
- GitHub Actions / GitLab CI 自动审查
- 定时巡检
- 批量对变更集做检查
4. IDE 里写代码的推荐节奏
- 打开仓库，确认在正确分支
- 用 Codex 面板描述任务（可 @ 文件）
- 看着它改文件，逐个确认 diff
- 本地运行测试 / 启动服务验证
- 让它起草 commit message，你再精修后提交
5. 代码任务分层（避免一次塞太多）
| 层级 | 例子 | 建议 |
| --- | --- | --- |
| 小 | 改一个函数、补日志 | 直接交互执行 |
| 中 | 一个小功能跨 3–5 文件 | 先 plan，再执行 |
| 大 | 模块迁移、鉴权改造 | 拆成里程碑，每步可回滚 |
6. 审查清单（每次都该过一眼）
- 是否改到了范围外的文件？
- 是否引入了秘密信息（密钥、token）？
- 测试是否真的跑过，还是只写了「应该可以」？
- 错误处理与边界条件有没有被简化掉？
- 文档 / changelog 要不要同步？
五、不止写代码：文档、知识与其他领域辅助
Codex 的「工程能力」迁移到其他文字与流程工作时，关键是：给真实上下文 + 明确产出物格式 + 禁止编造。
1. 写与改技术文档
适用：README、docs/、接口说明、迁移指南、Onboarding 文档。
请阅读 package.json 与实际目录，更新 docs/getting-started.md：
- 安装与启动步骤分 macOS/Windows/Linux
- 列出真实存在的 npm scripts
- 增加 5 条常见报错与处理
- 不确定的地方标 TODO，不要编造命令2. 生成变更说明与发布说明
根据当前 git diff 写一份面向非技术人员的更新说明：
- 用户能感知的变化
- 风险与回滚建议
- 不要提无关重构细节3. 代码审查与安全初检
审查这次变更：关注注入、权限绕过、敏感日志、错误的缓存键。
输出：问题列表（严重级别 + 文件位置 + 复现/影响 + 修复建议）4. 测试与质量辅助
- 为未覆盖模块补单测
- 把失败日志贴进去，让它定位并修到绿灯
- 生成最小复现用例说明
5. 数据分析 / 脚本辅助（工程向）
不一定替代专业 BI，但很适合：
- 写数据清洗脚本
- 解释一段 SQL / pandas 逻辑
- 把「口头统计需求」落成可运行 notebook/脚本草稿
务必要求：标注假设、不要假装已经跑过真实数据结果。
6. 运营与协作文档（谨慎使用）
可用于：
- 把会议要点整理成行动项（你提供原始笔记）
- 把 API 变更翻译成对业务同学的说明
- 写 RFC / 方案骨架（你负责拍板与事实核对）
不建议：在无事实来源时让它「编造」竞品数据或未发生的进度。
7. 把重复流程变成 Skills
当你发现自己每周都在说同一段话（发版检查、日志排查模板、文档结构），就把它沉淀成可复用 Skill / 提示模板，让 Codex 按团队标准执行，减少漂移。
六、云端、并行与自动化
1. 云端任务什么时候更香
- 本机要开会，但任务很长
- 需要同时推进多个互不阻塞的改造
- 希望结果直接落到 PR，方便异步审查
2. CI 中的定位
把 Codex 无头模式嵌进流水线，适合「自动初审」，不适合「无人值守直接合并到生产」。推荐人类对高风险仓库保留必经审查门禁。
3. MCP 与外部工具
通过 MCP 连接文档、工单、监控等系统后，Codex 能把「查资料 → 改代码 → 回写说明」串起来。接入前确认权限最小化，避免把生产写权限随手交给 Agent。
七、推荐学习路径（两周）
第 1–2 天：装通 + 只读
- 安装 CLI 与扩展
- 用只读任务熟悉审批与输出风格
第 3–5 天：小改动闭环
- 每天完成 1 个「单测级」小任务
- 强制自己审查每一个 diff
第 6–10 天：中等功能
- 先 plan 后执行
- 同步更新 README 一小节
第 11–14 天：流程化
- 固定团队 AGENTS/指令文件
- 试一条 CI 审查
- 整理自己的高频提示词模板
八、常见问题
Q：Codex 和 Cursor / Claude Code 怎么选？
A：没有唯一答案。Codex 强在 OpenAI 生态与多表面统一；Cursor 是 AI 原生 IDE 体验；Claude Code 强在 Anthropic 模型与其工具链。可以按团队已有订阅与工作流选择，也可以组合使用。
Q：为什么它改得很勤但不对？
A：多半是目标含糊或缺少验收命令。把「做什么 / 不做什么 / 如何验证」写清楚，成功率会明显上升。
Q：可以关掉所有审批吗？
A：技术上往往可以，但只建议在隔离仓库或一次性沙箱里实验；主仓库保持人工确认更稳妥。
九、官方入口
- 产品页：https://openai.com/codex
- Codex Web：https://chatgpt.com/codex
- 开发者文档：https://developers.openai.com/codex
- CLI 仓库：https://github.com/openai/codex
- macOS/Linux 安装脚本：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
十、小结
- 先装 CLI，再补 IDE 扩展；云端用浏览器即可。
- 登录优先 ChatGPT 计划；安全上先「工作区可写 + 需要时询问」。
- 写代码：交互做日常，plan 控大改，exec 进 CI；每次看 diff。
- 写文档与其他辅助：给真实仓库上下文，禁止编造，产出物格式写死。
- 把重复流程沉淀成配置与 Skills，才能从「会用」变成「团队提效」。