1. 引言

为了让读者更快建立一套稳定的心智模型,博主采用 5W1H(What / Why / Who / When / Where / How)把七篇内容 打通总结,并尽量以“可落地、可复用、可验收”的方式组织。


2. 【WHAT】:Codex 是什么?

Codex 是面向真实工程场景的软件工程 AI 代理(Coding Agent):它不是“只会生成代码的聊天模型”,而是能在工程工作台里 读仓库、改文件、跑命令、做审查、产出可验证证据 的“工程级协作者”。

一、它的本质:一个“可执行”的工程智能体

  • 输入:自然语言提示(Prompts)+ 代码上下文(文件/选区/截图)+ 工程约束(规范/安全/验证标准)。
  • 过程:模型推理 → 调用工具(读写文件/运行命令/检索资源/连接外部系统)→ 根据结果迭代。
  • 输出:不仅是文字解释,更包括 跨文件变更、测试/构建结果、diff、PR 审查意见 等“可交付物”。

二、四个核心抽象:Prompts / Threads / Context / Workflows

1)Prompting(提示词)

  • 关键原则:Codex 在“可验证”时质量更高。复现步骤、验证命令、验收标准越明确,越容易形成闭环。
  • 复杂任务最好拆分成更小步骤:可以先让 Codex 给计划(例如 $plan),由读者审查后再执行。

2)Threads(线程/会话)

  • 一个 thread 包含:多轮提示 + 模型输出 + 期间的所有工具调用记录。
  • 线程可以恢复继续;也可以并行跑多个线程,但应避免多个线程同时改同一文件。
  • 本地线程(Local threads):在本地机器运行,可直接读写本地文件、运行本地命令,默认受沙箱保护。
  • 云端线程(Cloud threads):在云端隔离环境运行,会克隆仓库并检出分支;适合并行任务、跨设备委派、或长任务执行。

3)Context(上下文)

  • IDE 插件通常会自动带上“打开的文件 + 选中的代码”作为上下文;CLI 更依赖显式引用(如 @path/mention)。
  • 上下文需要适配模型的 context window;会话过长时 Codex 可能自动“压缩上下文”(summary + 丢弃无关细节),以便持续推进长任务。

4)Workflows(工作流程)
一个可复用的工程 workflow 通常应包含:

  • 适用场景:什么时候用、用 IDE/CLI/Cloud 哪个入口更合适。
  • 步骤与示例提示:能直接复制运行。
  • 上下文说明:哪些自动可见、哪些需要显式提供。
  • 校验方法:怎么证明“做对了”(测试/复现/对比/验收清单)。

三、它能“在哪些入口”工作:IDE / CLI / Web(Cloud) / 集成平台

IDE Extension(VS Code / Cursor / Windsurf 等兼容 VS Code 的编辑器)

  • 优势:上下文天然就在编辑器里(打开文件、选区、符号定位),适合 边读边改边验证
  • 常见能力:切换模型、调整推理强度、选择审批模式、在本地/云端之间切换、/review/status/auto-context/cloud/local 等斜杠命令。

CLI(终端)

  • 优势:天然与 shell/脚本/工具链结合,适合 批处理、跑测试、自动化执行、审查与记录
  • 支持:图像输入(如错误截图/设计稿)、恢复会话(codex resume)、非交互执行(codex exec)、云任务(codex cloud ...)、/review/diff/compact/model/approvals/mention 等斜杠命令。

Web / Cloud(云端 Codex)

  • 优势:后台并行执行、隔离容器、可直接产出 diff/PR,适合 复杂任务、并行执行、团队协作
  • 典型流程:创建容器 → checkout 仓库/分支 → 运行 setup/maintenance → agent 循环“编辑/运行检查/验证” → 输出 diff → 由读者审查并创建 PR 或继续迭代。
  • 网络访问策略:setup 阶段可联网安装依赖;agent 阶段默认禁网(可按环境开启并细粒度限制)。

Integrations(集成)

  • GitHub:PR/Issue 工作流中触发审查与任务委派(如评论 @codex review)。
  • Slack:在团队 IM 中把任务委派给 Codex,获取进度与结果(适合“协作入口”)。
  • Linear:可把 issue 分配给 Codex 或在评论里 @Codex,并可结合 MCP 在本地访问 Linear。

四、它如何“被工程化”:配置 + 安全边界 + 可复用资产

1)config.toml:Codex 的运行“总开关”

  • 核心位置:~/.codex/config.toml(CLI 与 IDE 共享)。
  • 可控制:默认模型、推理强度、审批策略、沙箱模式、网络访问、环境变量传递、MCP 服务器、实验性功能开关等。

2)Approvals & Sandbox:把“能做事”变成“可控地做事”

  • approval_policy:控制“什么时候需要确认”。
    • untrusted:仅安全只读命令自动执行,其余都要确认
    • on-failure:沙箱内自动执行,失败时才提示升级/放权
    • on-request:由模型决定何时询问(常见默认)
    • never:从不询问(风险很高)
  • sandbox_mode:控制文件系统/网络边界。
    • read-only(默认):只读
    • workspace-write:允许写工作区(但某些目录仍可能只读)
    • danger-full-access:无沙箱(极其危险,只建议在已有外部隔离时使用)

术语澄清:文章(尤其是 CLI/IDE 章节)里也会出现“批准模式/Approval Modes(如 Auto / Read-Only / Full Access)”的说法,它更像是产品界面上的一组预设;而 config.toml 中的 approval_policy / sandbox_mode底层配置键。不同版本/不同入口可能在命名上略有差异,但本质都是在控制“是否需要确认”以及“可访问的文件/网络边界”。

3)Rules:控制“哪些命令可以在沙箱外跑”

  • ~/.codex/rules/*.rules:通过规则语言定义允许/提示/禁止的命令前缀(如 prefix_rule(pattern=["gh","pr","view"], decision="prompt", ...))。
  • 多规则匹配时选“限制性最强”的结果:forbidden > prompt > allow

4)AGENTS.md:让 Codex“默认懂项目与规范”

  • Codex 会在启动时按路径分层发现并合并指令文件(全局 + 仓库根 + 子目录 override)。
  • 典型用途:写清楚“怎么跑测试/怎么 lint/改动要注意什么/不能做什么”。

5)Custom Prompts vs Skills:提示复用的两条路

  • 自定义提示词(Custom Prompts):存放在 ~/.codex/prompts/*.md,显式调用(如 /prompts:draftpr),更偏“个人复用”。
  • Skills(Agent Skills):指令 + 资源 + 可选脚本打包,可显式或隐式调用,可仓库级共享,更适合“团队 SOP 固化与复用”。

6)MCP:把智能体连接到外部真实系统

  • config.toml 中配置 [mcp_servers.<name>],支持 STDIO 进程型与可流式 HTTP 服务器型。
  • 可让 Codex 访问第三方文档、设计工具(Figma)、浏览器控制(Playwright/Chrome DevTools)、日志平台(Sentry)、项目管理(GitHub/Linear)等。

五、学习资源:251 篇官方 Cookbooks(索引型内容)

第三篇文章本质上是一个“官方实战指南导航”,把 251 篇 Cookbooks(去除归档)按主题整理,覆盖:

  • 开源与自部署(gpt-oss 本地/自托管生态)
  • 多模态(图像/视觉/视频)、音频/语音
  • 检索/RAG/搜索(占比最大)
  • ChatGPT 生态、工具调用与扩展、代理与自动化
  • 微调/训练与提示词、评测/安全/合规
  • 开发工具与工程实践、基础 API 与性能优化

3. 【WHY】:为什么要用 Codex?

一、它解决的核心不是“会不会写代码”,而是“交付闭环效率”

真实工程里最耗时的往往不是敲代码,而是:

  • 跨文件定位真正的改动点、理解依赖与数据流
  • 改完后跑测试/构建/脚本 → 根据报错继续修 → 再验证(闭环)
  • 代码审查、补测试、写变更说明与文档、整理证据

Codex 的价值在于:它能在同一工作台里,把“理解 → 修改 → 执行 → 验证 → 复盘”尽量跑完,让人把时间更多用在架构判断与需求决策上。

二、它把“工程经验”变成默认流程(团队价值)

当团队开始把 Codex 当“工程成员”使用时,效率之外更重要的是稳定性:

  • AGENTS.md 把团队约束写出来(测试、lint、目录结构、禁忌操作、提交规范等)。
  • config.toml 固化安全边界(审批策略、沙箱模式、网络访问、环境变量传递)。
  • 用 Rules 把“沙箱外命令”做门禁(允许/提示/禁止),降低误操作风险。
  • 用 Skills 把 SOP(比如“发版前检查”“迁移可回滚”“PR 必须附证据”)封装成可复用能力,让不同项目输出一致。

三、它让 SDLC 全阶段都能引入智能体(AI-Native Team)

第二篇文章把 SDLC 分成 Plan / Design / Build / Test / Review / Document / Deploy&Maintain,并给出“智能体能做什么、人类要做什么、入门清单”。核心结论是:

  • 智能体越来越适合做“多步、重复、可验证”的工程任务;
  • 人类更应聚焦:需求意图、架构取舍、安全与性能边界、上线决策与责任。

四、多端形态让 Codex“放在合适的位置”

第四篇文章强调:入口选对了,体验会从“能用”变成“顺手”:

  • 写代码/改代码/读代码:IDE 最顺
  • 批处理、跑脚本、审查、记录:CLI 更强
  • 并行大任务、产出 PR、隔离执行:Cloud 更合适
  • 团队协作委派入口:GitHub/Slack/Linear 集成更自然

4. 【WHO】:谁适合用?团队如何协作?

一、个人开发者

  • 快速理解陌生仓库、修 Bug、补测试、做本地审查、整理文档与变更摘要。
  • 适合从 CLI/IDE 开始,用“可验证提示 + 小步迭代”建立正反馈。

二、Tech Lead / 架构与平台团队

  • 更关心“把能力变成流程”:配置、权限、规范、复用模板、质量门禁。
  • 典型抓手:AGENTS.md(规则与约束)、Skills(SOP 固化)、Rules(沙箱外命令门禁)、Cloud/Integrations(接入团队系统)。

三、测试 / 质量工程

  • 让 Codex 按项目约定补测试、跑测试并回传证据;把测试作为独立步骤纳入工作流。
  • 典型抓手:在 AGENTS.md 写清测试框架、覆盖要求、常用命令;用 workflow 指定“先写测试再修 bug”等策略。

四、运维 / 安全 / 合规

  • 重点是边界与审计:审批策略、沙箱、网络访问风险、prompt injection 风险、密钥处理方式。
  • 典型抓手:config.toml 的 sandbox_mode / approval_policy、Rules 的 forbidden/prompt、Cloud 的网络访问策略与 secrets 生命周期、MCP 的工具白名单/黑名单。

五、协作场景的“入口角色”

  • GitHub:PR/Review/Issue 让 Codex 成为协作者(例如评论触发 review)。
  • Slack:更像“团队机器人”,适合问答、委派、进度同步。
  • Linear:更像“任务执行者”,可分配 issue、自动更新进展、并能通过 MCP 在本地读取任务上下文。

5. 【WHEN】:什么时候用哪些能力/入口?

这一部分把七篇内容里的“案例、能力与阶段”合并成一张“时间点地图”:读者可以按任务阶段(SDLC)或按任务类型来选入口与能力。

一、按 SDLC 阶段选 Codex 的用法(来自 AI-Native Team 章节)

  • Plan(规划):读规范/工单/仓库,拆任务、估复杂度、标依赖与风险;人类负责优先级与关键路径决策。
  • Design(设计):搭骨架、生成样板、从设计稿/截图生成组件、提出可访问性建议;人类审核设计一致性与可扩展性。
  • Build(构建):跨文件实现功能、补错误处理/遥测/安全包装、修构建报错;人类把控架构、安全与性能边界。
  • Test(测试):生成测试用例、补边界场景、随代码演进维护测试;人类审核测试有效性与覆盖目标。
  • Review(审查):本地 /review 或 PR review;人类做最终合并判断与架构一致性把关。
  • Document(文档):更新 README/指南/排障文档,生成结构化说明与变更摘要;人类审核准确性与信息组织。
  • Deploy & Maintain(部署运维):结合日志/遥测/工单系统做排障建议;人类决定修复与发布策略并保持最终控制。

二、按“任务类型”选入口:IDE / CLI / Cloud / 集成

任务类型 更推荐入口 原因(概括)
理解代码、追数据流、解释模块职责 IDE 打开文件/选区天然就是上下文
修 Bug(可复现)、跑测试验证 CLI / IDE CLI 更擅长执行命令与记录;IDE 更适合定位与修改
写测试(对齐项目习惯) IDE(选区)/ CLI IDE 选中函数更快;CLI 便于明确文件路径与批量跑测
从截图/设计稿生成 UI CLI / IDE 支持图像输入;可要求可运行交付物 + README
UI 快速迭代(改样式→预览→再改) CLI + 本地 dev server 双终端循环更顺畅
大型重构(本地规划 + 云端并行实现) IDE → Cloud 本地审计划、云端跑实现与验证,最后拉 diff/PR
提交前质量检查 CLI /review 不改文件,集中输出可执行建议
审查 PR(无需拉分支) GitHub 集成 评论触发 review,适合团队协作
更新文档与变更说明 IDE / CLI 方便引用文档并做链接校验

三、Workflows 里的 9 个典型案例(可直接当“模板”)

第二篇文章给了 9 个 workflow 案例,读者可以把它们理解为“最常用的九种提问方式”:

  1. 解析代码库(模块职责、数据校验点、潜在坑)
  2. Bug 修复(复现步骤 + 约束 + 回归测试 + 验证)
  3. 编写测试(对齐项目约定、覆盖 happy path 与 edge cases)
  4. 从截图原型生成代码(约束技术栈 + 交付物 + 运行方式)
  5. 迭代 UI(提出多方案 → 选定 → 细化)
  6. 将重构任务委派到云端(先计划再执行里程碑)
  7. 本地代码审查(/review,聚焦边界与安全)
  8. 审查 PR(GitHub 评论 @codex review ...
  9. 更新文档(明确要更新的章节、验证链接与渲染)

6. 【WHERE】:它运行在哪?配置/文件放哪?边界在哪里?

一、本地:读者需要记住的“Codex 工作目录体系”

1)主目录(CODEX_HOME,默认 ~/.codex

  • ~/.codex/config.toml:核心配置(模型/审批/沙箱/MCP/功能开关等)
  • ~/.codex/rules/*.rules:沙箱外命令规则(allow/prompt/forbidden)
  • ~/.codex/prompts/*.md:自定义提示(显式调用 /prompts:<name>
  • ~/.codex/skills/:用户级技能(可跨仓库复用)
  • 可能的状态文件:auth.jsonhistory.jsonl、日志与缓存等

2)项目/仓库内(随代码走的沉淀)

  • AGENTS.md / AGENTS.override.md:项目与子目录的指令(分层合并)
  • <repo>/.codex/skills/:仓库级技能(团队共享、随仓库分发)
  • 其他项目资料:README、docs、团队指南(可通过 fallback 文件名让 Codex 识别)

二、云端:任务在隔离容器内如何跑?

Cloud 任务大致流程:

  1. 创建容器并 checkout 仓库/分支或指定 commit
  2. 运行 setup(必要时运行 maintenance;使用缓存容器会更常见)
  3. 应用网络策略:setup 阶段可联网;agent 阶段默认禁网(可按环境开启)
  4. agent 循环执行:编辑代码 → 运行检查(测试/lint 等)→ 根据结果迭代
  5. 输出结果:展示 diff/日志/验证信息 → 由读者审查并开 PR 或继续追问

三、Secrets 与网络访问:云端边界要特别注意

  • 环境变量:可在任务全过程(setup + agent)可用。
  • secrets:运行期加密存储,通常只在 setup 阶段可用,agent 阶段会移除(降低泄露风险)。
  • 网络访问风险:agent 阶段开网会引入 prompt injection、敏感信息外泄、恶意依赖下载、许可证风险等;建议尽量限制可信域名并审查日志。

四、指令发现“在哪里发生”:AGENTS 的分层合并

Codex 启动时会构建指令链:

  • 全局:~/.codex/AGENTS.override.md(若存在)否则 ~/.codex/AGENTS.md
  • 项目:从项目根到当前工作目录逐层检查:
    • AGENTS.override.mdAGENTS.mdproject_doc_fallback_filenames 中的文件名
  • 合并顺序:从根到叶拼接,越靠近当前目录优先级越高;默认最多嵌入 project_doc_max_bytes(32 KiB)

五、技能“在哪里加载”:Skills 的作用域优先级

同名技能会被“更高优先级作用域”覆盖(从高到低概括):

  • REPO:当前目录或仓库根的 .codex/skills
  • USER:$CODEX_HOME/skills(默认 ~/.codex/skills
  • ADMIN:/etc/codex/skills
  • SYSTEM:随 Codex 打包的系统技能

7. 【HOW】:怎么从 0 到工程化落地(可直接照做)

这一章把七篇文章里所有“操作型内容”串成一条落地路径:先能用 → 再顺手 → 最后团队化与平台化。

Step 1:准备账号与入口(Web / CLI / IDE)

  1. 明确使用入口:IDE(编辑器内)、CLI(终端)、Cloud(Web)或团队集成(GitHub/Slack/Linear)。
  2. CLI 常见安装方式:
# npm
npm install -g @openai/codex

# Homebrew(macOS)
# 两种写法在文章中都出现过,按安装渠道选择其一:
brew install codex
brew install --cask codex
  1. 运行 codex,选择 ChatGPT 登录API Key,完成授权。

Step 2:先把“安全边界”设好(配置 + 审批 + 沙箱)

~/.codex/config.toml 里优先关注三件事:

  1. 默认模型(影响质量/成本/速度)
  2. approval_policy(影响“什么时候询问确认”)
  3. sandbox_mode(影响“它能改哪里、能不能联网”)

示例(偏稳妥、适合日常开发):

model = "gpt-5.2-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

如果需要让工作区之外某些路径可写(如特定工具链目录),可在 sandbox_workspace_write.writable_roots 精确放行;如果要开网络访问,尽量只在必要时按环境开启,并配合 Rules/日志审计。


Step 3:学会写“工程级提示词”(把任务变成可验证的闭环)

博主建议提示至少包含 5 个元素(顺序可调):

  1. 目标(Goal):需要交付什么结果
  2. 上下文(Context):相关文件、入口、运行环境(IDE 可少写,CLI 要写清)
  3. 约束(Constraints):不改 API、不引入依赖、最小 diff、性能/安全边界
  4. 交付物(Deliverables):需要哪些文件/改动/说明
  5. 验证(Verification):复现步骤、测试命令、lint、验收清单

示例(Bug 修复类):

  • “问题是什么 + 复现步骤 + 不允许改什么 + 必须补什么测试 + 修完怎么验证”

示例(功能实现类):

  • “按项目规范实现 X,要求跑通 npm test,并给出变更摘要与验证结果”

Step 4:把常用任务套进 Workflows(九大模板直接复用)

  • 解析代码库:让它输出“请求流编号步骤 + 涉及文件列表 + 校验点 + 潜在坑”
  • 修 Bug:让它先复现(或解释如何复现)→ 修复 → 跑测 → 回归测试
  • 写测试:选中函数/引用文件 → 明确覆盖 edge cases → 对齐项目 conventions
  • UI 从截图:给技术栈、路由/页面交付物、README 运行说明
  • UI 迭代:先要 2-3 个方案,再逐步收敛
  • 大重构:本地先计划(里程碑)→ 云端执行里程碑 → 拉 diff/PR
  • 本地审查:/review,加上安全/边界/性能关注点
  • PR 审查:GitHub 评论 @codex review for ...
  • 文档更新:指定章节、要求校验链接与渲染

Step 5:选模型与推理强度(把“质量/成本/速度”调到合适)

文章给出的典型模型选择思路:

  • 默认推荐:gpt-5.2-codex(工程任务最强通用)
  • 成本敏感:gpt-5.1-codex-mini(更省但能力略弱)
  • 长任务/更深推理:gpt-5.1-codex-max(更适合长链路编码任务)
  • 通用智能体:gpt-5.2 / gpt-5.1(更泛化)

备注:在配置参考(config reference)片段中写明 “默认:所有平台均为 gpt-5.2-codex”。如果在某些地方看到 “macOS/Linux 默认 gpt-5-codex、Windows 默认 gpt-5” 之类描述,通常意味着它来自更早的版本/文档表述;以当前安装版本的 /status~/.codex/config.toml 生效值为准。

CLI 可临时切换:

codex -m gpt-5.1-codex-mini

也可在会话中 /model 切换。


Step 6:用 Rules 给“沙箱外命令”上门禁(允许/提示/禁止)

  1. ~/.codex/rules/ 下创建 *.rules
  2. prefix_rule() 匹配命令前缀,指定 decision
    • allow:直接放行
    • prompt:每次提示确认
    • forbidden:直接拒绝(建议写替代方案)
  3. match/not_match 当“内联单测”,避免误配。
  4. 注意 bash -lc 这类包装器可能隐藏复合命令,Codex 会做特殊处理;能拆分时会拆分后再判定规则。

Step 7:用 AGENTS.md 让它“默认懂项目”(全局 + 仓库 + 子目录覆盖)

读者可以从两层开始:

1)全局 ~/.codex/AGENTS.md(个人工作约定)

  • 常用测试命令、依赖管理偏好、是否允许加生产依赖、提交规范等。

2)仓库根 AGENTS.md(项目规范)

  • 如何运行/测试/构建、目录结构、禁忌操作、安全要求、文档要求。

当某个子目录(如某个微服务)有特殊规则,用 AGENTS.override.md 放在子目录里覆盖。

验证是否生效:

codex --ask-for-approval never "Summarize the current instructions."

Step 8:把高频提示做成“自定义提示词”(个人复用)

  1. 创建 ~/.codex/prompts/xxx.md,在 YAML front matter 写 descriptionargument-hint
  2. 在内容里使用占位符(如 $FILES$PR_TITLE$1..$9)。
  3. 重启 Codex 后用 /prompts:xxx 调用。

适用:个人常用的“草稿 PR”“变更摘要”“统一 review 模板”等。
不适用:需要随仓库共享、希望隐式触发的 SOP(这更适合 Skills)。


Step 9:接入 MCP,让它能用“外部工具与真实系统”

两种方式:

  • CLI:codex mcp add ...
  • 直接改 ~/.codex/config.toml[mcp_servers.<name>]

读者需要重点理解的配置维度:

  • STDIO(本地进程):command/args/env/env_vars/cwd
  • HTTP(远程服务):url、token 与 headers、OAuth(codex mcp login <name>
  • 运行控制:enabledstartup_timeout_sectool_timeout_secenabled_tools/disabled_tools

Step 10:用 Skills 把 SOP 封装成“团队可复用能力”

技能的核心是一个目录 + SKILL.md(可以附带脚本/资源/模板),Codex 采用“渐进式披露”:

  • 启动时只加载 skills 的 name/description(省上下文)
  • 显式调用:/skills 或在提示中 $SkillName
  • 隐式调用:任务与 description 匹配时自动选择技能

保存位置的三种常用方式:

  • 用户级:~/.codex/skills/<skill>/SKILL.md(个人跨仓库复用)
  • 仓库级:<repo>/.codex/skills/<skill>/SKILL.md(团队随仓库共享)
  • 符号链接:把“公司技能仓库”链接到 ~/.codex/skills/(统一维护)

常见排查点:

  • 文件名必须是 SKILL.md
  • YAML/name/description 需符合格式与长度限制
  • 触发不明显:description 写得不够明确或多个技能意图重叠

社区/官方资源:

  • openai/skills(官方推荐,可直接用/可做模板)
  • agentskills/agentskills(更偏规范与写技能指南)
  • anthropics/skills(可借鉴复杂技能组织方式)
  • agentskills.io(索引/市场)

8. 文末

把这七篇文章合起来看,博主认为 Codex 的“主线”非常清晰:

  • WHAT:它是能读/改/跑/审的工程智能体,而不是聊天生成器。
  • WHY:它提升的是“工程交付闭环效率”,并能把经验固化成流程。
  • WHO:个人、团队负责人、测试、运维与安全都能以不同方式参与其闭环。
  • WHEN:按 SDLC 阶段与任务类型选择合适入口与 workflow。
  • WHERE:本地(配置/规则/指令/技能)+ 云端(隔离容器与网络策略)+ 集成平台(协作入口)。
  • HOW:用 config/approvals/sandbox 画边界,用 rules/agents/prompts/mcp/skills 做工程化落地与团队复用。

希望本文能帮助大家理解 Codx 的设计边界与工程定位。感谢大家的阅读,本文完!

Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐