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

OpenAI Codex是什么

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

GPT 5.1 Codex Max是OpenAI专门为代码生成和软件工程任务优化的大语言模型变体。与通用对话模型不同，它在训练过程中大量使用了代码仓库、技术文档、测试用例和软件工程最佳实践数据。"代理式编码"（Agentic Coding）是区别于传统代码补全的新范式——模型不仅生成代码片段，还能自主规划任务步骤、执行命令、观察结果并迭代修正，形成完整的"思考-行动-观察"循环。这种能力使得AI能够处理跨文件重构、端到端功能实现等复杂任务，而非仅限于单行或单函数级别的补全。

开发者可以将日常重复性任务委托给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搜索：默认关闭，可在配置中开启

Codex的沙箱（Sandbox）机制是其安全架构的核心组成部分。默认的"workspace write"模式意味着代理只能在当前工作目录内创建和修改文件，无法访问系统级目录或其他项目。这借鉴了容器化技术的隔离思想，类似于Docker容器的文件系统隔离。审批策略中的"request模式"则实现了人机协作的安全边界——当代理需要执行网络请求、安装依赖包或修改配置文件等敏感操作时，必须获得用户明确授权。这种设计在自动化效率和安全可控之间取得了平衡。

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

为什么需要Agents.md

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

大语言模型的上下文窗口（Context Window）是指模型在单次推理中能处理的最大token数量。尽管现代模型的上下文窗口已扩展到数十万甚至百万token，但编码代理在会话之间仍然是无状态的——每次新会话启动时，模型对项目的了解从零开始。这与人类开发者的持续记忆形成鲜明对比。Agents.md的设计正是为了解决这一根本性限制：通过在每次会话开始时自动注入项目关键信息，模拟一种"持久记忆"效果，同时避免将整个代码库塞入上下文窗口造成的注意力稀释问题。

创建与组织方式

创建方式有三种：

在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能理解图片内容并定位到对应代码进行修改。这得益于GPT 5.1 Codex Max的多模态能力——模型不仅能处理文本，还能理解图像中的视觉元素，将UI截图中的组件与代码库中的样式定义建立关联，实现从视觉描述到代码修改的端到端转换。

会话恢复

使用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级别的关键问题，避免噪音过多导致开发者忽视。这里的P0/P1是问题优先级分类体系：P0代表阻断性缺陷（如安全漏洞、数据丢失风险、生产环境崩溃），P1代表严重功能缺陷（如逻辑错误、性能退化）。通过过滤掉P2及以下的风格建议和微小优化，Codex确保每条审查意见都值得开发者立即关注和处理。

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

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

MCP（Model Context Protocol）是由Anthropic最初提出、后被行业广泛采纳的开放协议标准，旨在为AI模型提供统一的外部工具调用接口。它定义了工具发现、参数传递、结果返回的标准化流程，类似于Web领域的REST API规范。MCP支持两种传输方式：标准I/O（stdio）适用于本地进程间通信，模型通过stdin/stdout与工具进程交互；HTTP传输则适用于远程服务调用，支持跨网络的工具访问。这种协议化设计使得任何遵循MCP规范的工具都能即插即用，无需为每个AI平台单独开发集成。

常用MCP服务器

Figma MCP：根据设计稿生成前端代码，将设计师在Figma中创建的组件、布局和样式信息转化为结构化数据，供Codex生成对应的HTML/CSS/React代码
Jira/Linear MCP：读取工单、实现代码、更新状态，实现从需求管理到代码实现的闭环自动化
Context7 MCP：获取第三方框架最新文档，解决模型训练数据滞后的问题，确保生成的代码使用最新API
Datadog MCP：诊断生产环境问题，将监控指标、日志和APM追踪数据提供给Codex进行根因分析

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管道中。

结构化输出（Structured Output）是指模型按照预定义的JSON Schema生成严格符合格式要求的数据，而非自由格式的自然语言文本。这对于自动化流程至关重要——CI/CD（持续集成/持续部署）管道中的每个环节都需要机器可解析的数据格式。通过JSON Schema约束，Codex的输出可以直接被下游工具（如GitHub Actions、Jenkins、GitLab CI）解析和处理，无需额外的自然语言解析步骤。这将AI从"对话助手"提升为"自动化管道组件"，能够无缝嵌入现有的DevOps工作流中。

与Agents SDK协作

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

多代理协作（Multi-Agent Collaboration）是AI系统架构的前沿方向，其核心思想是将复杂任务分解给多个专业化代理，每个代理负责特定领域。Handoff机制是代理间任务交接的协议——当前端代理完成UI组件开发后，通过handoff将API接口需求传递给后端代理，后端代理完成实现后再将集成测试需求传递给QA代理。OpenAI Agents SDK提供了这种编排能力的框架支持，包括代理定义、工具绑定、状态传递和执行追踪。执行追踪日志（Execution Trace）记录了每个代理的决策路径和工具调用序列，便于调试和审计整个协作流程。

实际应用场景

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

总结

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