官方文档：Codex Web/Cloud

第一阶段只解决三个问题：

1. Codex能做什么
2. 主要在哪个入口用
3. 它怎么拿到上下文

1.Codex能做什么

Codex是OpenAI的软件开发智能体。它的核心能力是：

• 阅读与修改代码
• 运行命令
• 理解陌生项目
• 修复bug与编写测试
• 做代码审查
• 生成diff或pull request
• 在云端后台执行较长任务
• 在明确要求时并行运行多个subagents

官方在Codex Web文档中把它描述为可以read,edit,and run code的coding agent。重点不是“聊天机器人懂代码”，而是它可以进入一个真实开发环境，读取项目、执行shell命令、编辑文件，并尝试验证自己的改动。

可以把Codex的能力分成三层：

1.1.代码助手

这是最基础的一层，适合日常回答与局部修改。

典型任务：

• 解释某个函数或者模块
• 梳理项目结构
• 找出某个bug可能的原因
• 补充一个组件，接口或者测试
• 梳理陌生仓库

这一层像是“懂项目上下文的pair programmer”（编程搭档）。

1.2.本地执行代理

Codex不只回答问题，还能在本地环境里行动。

典型任务：

• 在当前仓库中搜索代码
• 修改文件
• 运行测试、lint(代码规范)、typecheck(类型检查)
• 根据失败结果进行修复
• 生成最终变更说明

这个形态主要出现在：

• CLI
• IDE Extension
• Codex App的Local模式

本地执行代理适合正在开发，需要快速迭代的场景。

1.3.云端开发代理

Codex Cloud可以在OpenAI托管的云环境中执行任务。提交任务后，Codex会在云端环境中(OpenAI提供的服务器)checkout仓库、运行setup、修改代码、执行检查，最后返回结果和diff。

典型任务：

• 长时间重构：把一个老模块从Java8风格改成更现代的写法。
• 修复CI(持续集成)：GitHub Actions失败了，让他找原因并修复。
• 根据issue(需求单)实现功能：如Linear/GitHubissue写了需求，它直接按需求开发。
• 后台并行探索多个问题：比如同时让几个Codex任务分别尝试不同修复方案。
• 从GitHub、Slack(类似飞书，团队写作聊天)、Linear(任务管理工具)中派发任务不用一直盯着本地电脑，它可以在云端处理较长任务。

云端任务的价值在于：它可以脱离你当前本地工作流，在后台跑较长任务，并把结果变成可review的改动。

2.主要在哪个入口用

Codex不是单一产品入口，而是一组适配不同工作场景的入口

2.1.App

官方定位：Your Codex command center。

Codex App是桌面端体验，适合集中管理多个Codex threads、worktrees、自动化任务和Git操作。

适合场景：

• 同时处理多个项目或多个任务
• 使用worktree隔离并行改动
• 在一个桌面应用中review、commit、push
• 配合自动化任务或长期线程

一句话理解：

App是Codex的桌面工作台。

2.2.IDE Extension

官方定位：Pair with Codex in your IDE。

IDE Extension适合正在编辑代码时使用。它能利用打开文件、选区和@file引用，用更短的prompt给Codex更准确的上下文。

适合场景：

• 基于当前打开文件提问
• 让Codex修改选中的代码
• 在编辑器里跟进cloud task
• 快速生成、解释、重构局部代码

一句话理解：

IDE Extension是写代码时贴在旁边的pair programmer。

2.3.CLI

官方定位：Pair with Codex in your terminal。

CLI是终端里的Codex。在某个目录运行codex，它就可以围绕这个目录读取、修改、运行代码。

适合场景：

• 在repo中直接让Codex搜索、修改、测试
• 执行偏工程化的任务
• 自动化重复工作
• 做本地code review
• 使用subagents并行处理复杂任务

一句话理解：

CLI是最贴近工程师本地工作流的入口。

2.4.Web/Cloud

Web/Cloud入口适合把任务委派给云端Codex。通过网页提交任务，让Codex在云端环境后台执行。

适合场景：

• 长任务
• 后台任务
• 并行任务
• 根据repo创建PR
• 不想占用本地机器时的任务委派

一句话理解：

Web/Cloud是把任务交给Codex在云端完成。

2.5.GitHub集成

GitHub集成主要面向PR和issue工作流。

常见用法：

• 在PR评论中写@codex review，让Codex做代码审查
• 在评论中写@codex fix the CI failures，让Codex基于PR上下文启动cloud task
• 启用automatic reviews，让Codex自动审查PR

一句话理解：

GitHub集成适合PR审查和从代码协作平台直接派活。

2.6.Slack集成

Slack集成可以在频道或者thread中@Codex，让Codex创建cloud task，并在完成后回复结果。

特点：

• 可以引用Slackthread中的前文
• 可以在prompt中指定repo或environment
• 适合从团队讨论直接编程执行任务

一句话理解：

Slack集成适合把讨论中的任务直接派给Codex。

2.7.Linear集成

Linear集成让Codex从issue中接收任务。

常见用法：

• 把issue assign给Codex
• 在Linear评论中@Codex
• Codex回写进度、总结和任务链接

一句话理解：

Linear集成适合从issue生命周期中委派开发任务。

2.8.入口选择建议

日常使用可以按这个原则选：

场景	推荐入口
正在写代码，需要结合当前文件	IDE Extension
在终端里处理repo、跑测试、改文件	CLI
长任务、后台任务、并行任务	Web/Cloud
多项目、多线程、worktree、桌面集中管理	App
PR审查	GitHub
从团队讨论直接派任务	Slack
从issue派发开发任务	Linear

3.Codex怎么拿到上下文

Codex的上下文不是单一来源，而是由多个来源组合而成：

入口上下文+项目文件+配置规则+外部工具+用户prompt

理解上下文来源，是用好Codex的关键。

3.1.当前项目、目录、仓库

这是最基础的上下文。

不同入口中的表现：

• CLI：使用运行codex时所在的目录
• App：选择的project folder
• IDE Extension：当前编辑器工作区、打开文件、选区、@file
• Cloud：选择的repo、branch或commit
• GitHub：PR、issue、评论、diff
• Slack：频道或thread中的对话
• Linear：issue标题、描述、评论和关联仓库信息

Codex不是凭空知道项目，而是先拿到入口提供的上下文，再根据需要读取更多文件或运行命令。

3.2.AGENTS.md

AGENTS.md是给Codex的项目说明书。

官方说明：Codex在工作开始前会读取AGENTS.md文件。它可以放在全局目录、项目根目录或子目录中，用来提供稳定、可复用的项目规则。

适合写入：

• 项目结构说明
• 构建命令
• 测试命令
• lint/typecheck命令
• 代码风格
• review重点
• 安全注意事项
• 不希望Codex做的事情

Codex的发现顺序大致是：

1. 全局范围：默认从~/.codex读取AGENTS.override.md或AGENTS.md
2. 项目范围：从项目根目录向当前工作目录逐层查找
3. 合并顺序：从根目录到当前目录拼接，越靠近当前目录的说明越晚出现，因此更具体

使用建议：

• 全局AGENTS.md写个人偏好和通用工作习惯
• 项目根目录AGENTS.md写整个仓库的约定
• 子目录AGENTS.md写某个模块的特殊规则
• PRreview标准也可以写进AGENTS.md

3.3.config.toml和.codex/config.toml

配置文件决定Codex本地客户端的行为边界

用户级配置：

~/.codex/config.toml

项目级配置：

.codex/config.toml

常见配置项：

• 默认模型
• reasoning effort
• approval policy
• sandbox mode
• MCPservers
• web search模式
• shell环境变量策略
• log目录
• feature flags

配置优先级从高到低：

1. CLIflags和--config(即启动codex创建的子命令配置)
2. profile
3. 项目.codex/config.toml
4. 用户~/.codex/config.toml
5. 系统/etc/codex/config.toml
6. 内置默认值

注意：项目级.codex/配置只会在 trusted project 中加载。

3.4.MCP

MCP是Model Context Protocol，用来把第三方工具和外部上下文接入Codex。

它适合让Codex访问：

• 第三方文档
• 浏览器
• Figma
• 内部工具
• 数据源
• 其他开发者工具

Codex支持：

• 本地STDIO MCP server：本地电脑启动的工具程序，Codex命令行输入输出跟他通信。
• Streamable HTTP MCP server：部署在网络上的MCP工具服务，Codex通过URL访问它。
  • Bearer token auth：用token表明有权限访问对应MCP服务。
  • OAuth auth：通过浏览器登录授权。

CLI和IDE Extension共享MCP配置。配置通常写在：

~/.codex/config.toml

或trusted project的：

.codex/config.toml

一句话理解：

MCP是给Codex接外部工具和外部知识的标准接口。

3.5.Skills

Skills用来给Codex增加可复用的任务能力和专业工作流。 一个skill通常是一个目录，里面至少有：

my-skill/  
  SKILL.md

也可以包含：

scripts/  
references/  
assets/  
agents/

SKILL.md中必须包含：

• name
• description
• skill instructions Codex使用skills的方式：
• 显式调用：用户在prompt中点名某个skill
• 隐式调用：任务匹配skill的description时，Codex自己选择使用

Skills的重要机制是progressive disclosure：

1. Codex一开始只看到skill的名称、描述和路径
2. 只有决定使用某个skill时，才读取完整的SKILL.md
3. 这样可以避免大量技能说明挤占上下文窗口

一句话理解：

Skills是可复用的专业工作流包

3.6.Subagents

Subagents是Codex的并行协作能力。

当你明确要求时，Codex可以启动多个专门agent，让它们并行探索或实现不同子任务，最后汇总结果。

适合场景：

• 大型代码库探索
• 多维度PRreview
• 复杂功能拆分
• 并行调查多个bug线索
• 一个主任务下的多个独立子任务

内置agent类型包括：

• default：通用agent
• worker：偏实现和修复
• explorer：偏代码阅读和探索

重要限制：

• Codex只有在你明确要求时才会spawn subagents
• subagents会消耗更多tokens
• subagents会继承当前sandbox和approval设置
• 并行并不等于适合所有任务，只有可拆分任务才值得用

一句话理解：

Subagents是把一个复杂任务拆给多个专门Codexagent并行处理。

4. 总结

4.1 产品形态心智模型

产品形态	你在做什么	Codex在哪里工作
App	桌面集中管理任务	本地或云端
IDE Extension	边写代码边协作	本地，也可委派云端
CLI	在终端里让Codex操作repo	本地，也可委派云端
Web/Cloud	把任务交给云端后台跑	云端容器
GitHub	在PR/issue中审查或派任务	云端任务
Slack	从讨论线程派任务	云端任务
Linear	从issue派任务	云端任务

4.2 上下文心智模型

Codex的上下文可以这样理解：

入口提供初始上下文  
        +  
项目文件提供事实依据  
        +  
AGENTS.md提供项目规则  
        +  
config.toml提供运行边界  
        +  
MCP提供外部工具和知识  
        +  
Skills提供可复用工作流  
        +  
Subagents提供并行处理能力

一句话总结：

入口决定初始上下文，项目文件决定事实依据，AGENTS.md决定项目规则，config.toml决定运行边界，MCP和Skills扩展能力，Subagents扩展并行处理能力。