OpenAI Codex完整上手指南：CLI安装、VS Code配置与实战技巧

OpenAI Codex是什么

OpenAI Codex 是一款面向开发者的AI编码代理，支持CLI终端、VS Code IDE扩展和云端三种使用方式。它背后由最新的GPT 5.1 Codex Max模型驱动，专门针对代理式编码场景进行训练，能够在Linux、macOS和Windows环境中可靠运行。

开发者可以将日常重复性任务委托给Codex，从而将更多精力投入到设计和架构等复杂挑战中。Codex支持代码审查、Slack集成、SDK编程调用等多种工作流，覆盖从规划设计到文档维护的软件开发全生命周期。

view on GitHub buttons and maybe a download button

to diagnose any production issues as well.

how to fire off the code review.

Codex安装与环境配置

CLI命令行安装步骤

Codex CLI是开源的，推荐通过brew或NPM安装以获取最新版本（团队每周可能发布多次更新）：

brew install codex
# 或
npm install -g @openai/codex

安装后运行codex login即可通过工作邮箱登录，支持企业SSO认证。登录后CLI和IDE扩展同时生效。

VS Code扩展安装与配置

在VS Code扩展市场搜索"OpenAI Codex"，认准官方发布的版本。建议开启自动更新以保持最新功能同步。扩展支持本地运行和云端容器两种模式，可在聊天模式、代理模式和完全访问模式之间切换。

config.toml配置文件详解

Codex CLI使用TOML格式的配置文件，支持以下自定义项：

默认模型与推理强度：指定模型和reasoning effort级别
沙箱模式：默认workspace write，仅写入当前目录
审批策略：默认request模式，需要提权时会询问用户
配置文件（Profile）：可创建如"fast"等快速配置，用codex -p fast启动
终端通知：任务完成时弹出提醒
Web搜索：默认关闭，可在配置中开启

Agents.md编写指南：给AI的项目说明书

为什么需要Agents.md

编码代理在会话之间不保留上下文，每次启动都是全新的上下文窗口。Agents.md确保项目的核心指令在每次启动时自动加载，相当于给AI一份轻量级的项目速查手册。

创建与组织方式

创建方式有三种：

在CLI中使用/init命令自动生成
在Codex home文件夹创建全局agents.md
在项目根目录或子目录创建特定的agents.md

典型内容包括：项目概述与结构、构建和测试命令、工作流说明、以及指向其他任务文档的指针。

Agents.md编写最佳实践

保持简洁：OpenAI内部的agents.md文件大多不超过100行。过多指令反而会让代理困惑。

解锁代理循环：给代理提供验证工具（linter、测试等），让它能自我检查。如果你发现自己总是手动运行某些检查命令，就把它们加入agents.md。

持续更新：当观察到Codex犯错或花费过多时间推导某个命令时，将正确做法添加到agents.md中。

任务文档分层：使用plans.md、frontend.md、architecture.md等独立文件，让agents.md指向它们，实现渐进式发现。OpenAI工程师曾借助plans.md成功完成超过10小时的大规模重构任务。

Codex提示词技巧与使用最佳实践

核心原则

使用@提及锚定文件：用@filename指向代码库中的特定文件，避免代理在无关代码中迷失
从小任务开始：新手先用小任务测试，逐步增加复杂度，也可以让Codex帮你拆解大任务
包含验证步骤：在提示词中明确要求运行测试、linter等检查
调试时粘贴完整堆栈：直接粘贴stack trace，Codex能据此导航代码库定位问题
尝试开放式提问：如"实现这个功能后，你建议接下来做什么？"Codex往往会给出有价值的建议

CLI与IDE实用技巧

图片输入功能

当难以用文字描述UI元素时，直接截图粘贴给Codex。例如截图后说"把这些内联代码块的背景改成橙色"，Codex能理解图片内容并定位到对应代码进行修改。

会话恢复

使用codex resume可以回到之前的会话继续对话，保留所有上下文。也可以通过session ID直接跳转到特定会话。建议将不同任务维护在不同会话中，如测试会话、前端功能会话等。

TODO集成

在代码中写入TODO注释，IDE扩展会显示"Implement with Codex"按钮，一键触发实现。

自定义命令

在Codex home文件夹创建prompts/目录，添加如test.md文件定义自定义命令。之后在CLI中输入/prompts即可调用预设指令，如自动为变更文件生成单元测试。

代码审查功能

CLI支持四种审查方式：

codex review --base main          # 对比基准分支
codex review --uncommitted        # 审查未提交更改
codex review --commit abc123      # 审查特定提交
codex review --instructions "..." # 自定义审查规则

模型经过训练只关注P0/P1级别的关键问题，避免噪音过多导致开发者忽视。

MCP集成：连接外部工具扩展能力

Codex支持通过MCP（Model Context Protocol）连接外部工具，支持标准I/O和HTTP传输。

常用MCP服务器

Figma MCP：根据设计稿生成前端代码
Jira/Linear MCP：读取工单、实现代码、更新状态
Context7 MCP：获取第三方框架最新文档
Datadog MCP：诊断生产环境问题

MCP配置方法

codex mcp add --name "context7" --command "npx context7-mcp"

添加后会自动写入config.toml。可在全局agents.md中添加指令如"实现新功能时，始终先在Context7中搜索相关文档"，让Codex自动调用而无需每次手动指定。

高级用例：编程式调用与自动化

结构化输出（Headless模式）

使用codex exec进入无头模式，配合JSON Schema获取结构化输出：

codex exec "分析代码质量问题" --output-schema codex-output-schema.json

输出为标准JSON，包含文件数、问题数、评分、每个问题的文件位置和严重级别等，可直接集成到CI/CD管道中。

与Agents SDK协作

Codex可作为MCP服务器嵌入OpenAI Agents SDK，构建多代理协作流程：前端代理、后端代理、PM代理各司其职，通过handoff机制协调工作，自动生成执行追踪日志。

实际应用场景

自动修复CI：测试失败时自动触发Codex修复并提交PR
Issue自动标签：新Issue创建时自动分类打标签
本地代码审查：为非GitHub的SCM系统构建自有审查流程
发布自动化：每次发版自动生成changelog和README

总结

Codex正在快速迭代，Windows支持和长时间任务是近期最大的功能更新。要充分利用Codex的能力，关键在于：写好agents.md建立项目上下文、善用MCP扩展能力边界、通过自定义命令和结构化输出实现自动化流程。从小任务开始，逐步将Codex融入开发工作流的每个环节。