Mystpet's Blog

重点：

codex exec：在脚本、CI、批处理里运行Codex
Codex SDK：在程序中控制Codex本地agent
GitHub Action：在GitHub Actions中自动运行Codex
Subagents：把复杂任务拆给多个agent并行处理
Background mode：API侧长任务异步执行，避免超时和连接问题

1.简介

前四个阶段解决：

第1阶段：Codex是什么、有哪些入口、怎么拿上下文
第2阶段：如何在CLI/IDE中读代码、改代码、跑命令、解释报错、做review
第3阶段：如何把需求写成可执行任务
第4阶段：如何用AGENTS.md、Rules、Hooks、Skills、MCP治理上下文

第5阶段解决：如何把Codex从“人手动发起一次任务”扩展到“脚本、CI、批处理、并行agent和自动化系统中反复执行”。

只有能稳定地完成这些事情，自动化才有价值：

prompt写得清楚
AGENTS.md有项目规则
测试命令明确
权限边界明确
review标准明确
失败时知道怎么定位

否则，把一个不稳定的手工流程自动化，只会得到更快、更批量的不稳定结果。

text

日常开发=CLI/IDE
批量任务=codex exec
系统集成=Codex SDK
CI/PR自动化=GitHub Action
复杂并行任务=Subagents
API长任务=Background mode

第5阶段不是让Codex更会写代码，而是让Codex进入自动化流水线。

2.Non-interactive mode：用`codex exec`跑自动化任务

官方说明：Non-interactive mode让你可以不用打开交互式TUI，而是在脚本、CI、定时任务或命令管道中运行Codex。入口是：

bash

codex exec

基础用法：

bash

codex exec "summarize the repository structure and list the top 5 risky areas"

它适合：

CI流程
pre-merge检查
scheduled jobs
自动生成release notes
自动总结仓库风险
批量处理文件或日志
把其他命令输出通过stdin交给Codex
用固定sandbox和approval设置运行任务

一个重要特性是：codex exec会把进度输出到stderr，最终agent message输出到stdout。这让它很适合接进管道。

示例：

bash

codex exec "generate release notes for the last 10 commits" > release-notes.md

或者：

bash

git diff main...HEAD | codex exec "review this diff for behavior regressions"

一句话理解：

codex exec是把Codex从聊天界面变成命令行自动化工具。

3.codex exec的权限和安全

自动化里最重要的是权限边界。

官方文档说明：codex exec默认运行在read-only sandbox中。也就是说，它默认更适合做分析、总结、review，而不是直接改文件。

常见权限：

bash

codex exec "review this repository"

默认只读。

如果允许修改工作区：

bash

codex exec --sandbox workspace-write "fix the failing tests"

如果允许更大权限：

bash

codex exec --sandbox danger-full-access "run the migration task"

danger-full-access只应该用于受控环境，比如隔离的CI runner或容器。不要在普通本地项目中随便使用。

其他常用选项：

选项	作用
`--ephemeral`	不把session rollout文件持久化到磁盘
`--json`	用JSON Lines输出完整事件流，方便脚本消费
`--output-last-message <path>`/`-o <path>`	把最终消息写入文件
`--output-schema`	要求最终输出符合JSON Schema
`--ignore-user-config`	不加载用户级`config.toml`
`--ignore-rules`	跳过用户和项目rules

自动化里建议：

默认只读
只有明确需要改文件时才用workspace-write
不在普通机器上用danger-full-access
用--json或--output-schema生成机器可读结果
用AGENTS.md固定任务规范
用Rules固定命令边界

4.codex exec的典型场景

4.1.自动PR review

bash

git diff origin/main...HEAD | codex exec "
请以code review方式检查这个diff。
重点看bug、行为回归、安全风险、错误处理和缺失测试。
输出findings优先，每条包含文件路径和具体风险。
"

4.2.自动生成release notes

bash

git log --oneline -20 | codex exec "
根据这些commit生成中文release notes。
按Features、Fixes、Chores分类。
不要编造commit中不存在的内容。
"

4.3.自动排查失败日志

bash

cat test-output.log | codex exec "
解释测试失败的根因。
输出：
1.最可能原因
2.相关文件线索
3.推荐修复步骤
4.是否需要重新运行测试
"

4.4.自动修复小问题

bash

codex exec --sandbox workspace-write "
修复当前项目中的lint错误。
只做机械修复，不做无关重构。
修复后运行最小相关lint命令。
最后总结修改文件和验证结果。
"

4.5.结构化输出

适合给下游脚本消费：

bash

codex exec --json "summarize the repo structure"

或者用schema约束输出：

bash

codex exec --output-schema risk-report.schema.json "
检查当前diff的风险，输出结构化风险报告。
"

5.Codex SDK：程序化控制Codex

官方说明：如果你已经使用CLI、IDE Extension或Codex Web，也可以通过Codex SDK程序化控制Codex。

SDK适合：

在CI/CD pipeline中更细粒度地控制Codex
构建内部工程工具
构建自己的agent，调用Codex完成复杂工程任务
把Codex集成到自己的应用或平台
管理thread、继续同一个任务、恢复历史任务

TypeScript SDK安装：

bash

npm install @openai/codex-sdk

基础用法：

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result);

继续同一个thread：

const result = await thread.run("Implement the plan");
console.log(result);

恢复历史thread：

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

一句话理解：

codex exec适合简单脚本，Codex SDK适合把Codex嵌进你自己的系统。

6.codex exec和Codex SDK怎么选

场景	推荐
一条命令完成任务	`codex exec`
CI中跑一次review	`codex exec`或GitHub Action
shell管道处理日志、diff、commit	`codex exec`
需要机器可读输出	`codex exec --json`或`--output-schema`
需要在程序中管理多个thread	Codex SDK
需要把Codex接进内部平台	Codex SDK
需要连续多轮控制任务状态	Codex SDK
需要和业务系统、队列、数据库整合	Codex SDK

选择原则：

text

脚本优先codex exec
系统集成优先Codex SDK
GitHub CI优先GitHub Action

7.GitHub Action：把Codex接入PR和CI

官方说明：Codex GitHub Action使用openai/codex-action@v1，可以在CI/CD job中运行Codex、应用patch或从GitHub Actions workflow中发布review。

它适合：

自动PR review
release前检查
CI中的Codex质量门禁
定期运行重复任务
自动生成迁移建议
自动检查测试缺口

前提：

把OpenAI key存为GitHub secret，例如OPENAI_API_KEY
使用Linux或macOS runner
在运行action前checkout代码
准备prompt，可以用inline prompt，也可以用repo中的prompt-file

最小示例：

yaml

name: Codex pull request review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v5

      - name: Run Codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md
          safety-strategy: drop-sudo
          sandbox: workspace-write

推荐把prompt单独放到repo中：

text

.github/codex/prompts/review.md
.github/codex/prompts/release-notes.md
.github/codex/prompts/test-gap-analysis.md

这样做的好处：

prompt可以review
prompt可以版本化
团队可以统一标准
不需要在workflow YAML中塞大量任务描述

8.GitHub Action的安全和设计原则

GitHub Action中的Codex自动化要保守设计。

建议：

先从只读review开始
对外部贡献者PR更谨慎
权限最小化，例如contents: read
需要评论PR时才给pull-requests: write
prompt文件写清楚“只review，不修改”
自动patch前必须有测试和人工review
不要在不受信任PR上暴露secrets
不要让Codex自动部署生产环境

适合自动化的任务：

PR风险总结
缺失测试提示
release notes初稿
迁移影响分析
lint/test失败原因解释

不适合一开始自动化的任务：

自动改数据库schema
自动部署生产
自动合并PR
自动处理密钥、权限、账单配置
大范围架构重构后直接提交

一句话理解：

GitHub Action适合把Codex接进工程流程，但默认应该先做“辅助判断”，再逐步扩展到“自动修改”。

9.Subagents：并行处理复杂任务

官方说明：Codex可以通过spawning specialized agents并行运行subagent workflows，然后汇总结果。

Subagents适合：

大型代码库探索
多角度code review
测试缺口分析
安全审查
日志分析
多模块迁移评估
把大任务拆成多个相互独立的子任务

它不适合：

简单单文件修改
强耦合实现
多个agent同时改同一批文件
需求还没说清楚的任务
预算或token非常敏感的任务

官方文档强调：Codex不会自动spawn subagents。只有你明确要求“spawn agents”“parallel agents”“delegate this work in parallel”等，它才应该使用。

示例：

text

Review this branch with parallel subagents.
Spawn one subagent for security risks, one for test gaps, and one for maintainability.
Wait for all three, then summarize the findings by category with file references.

更工程化的写法：

text

请使用3个subagents并行分析当前PR：
1.安全风险agent：只看鉴权、输入校验、敏感信息泄露
2.测试缺口agent：只看新增/修改行为是否有测试覆盖
3.可维护性agent：只看复杂度、重复代码、模块边界

每个agent只输出findings，不要修改文件。
等全部完成后，由主agent汇总：
- 严重问题优先
- 每条包含文件路径、风险和建议
- 最后给出是否建议合并

10.Subagents的上下文和成本

Subagents的价值是降低主线程的上下文污染。

复杂任务中会产生很多中间信息：

探索笔记
测试日志
stack trace
搜索结果
大量文件片段
多轮推理过程

如果全部塞进主线程，主任务会变得越来越重。Subagents可以把这些noisy work放到子线程里，最后只把摘要返回给主线程。

但代价也明确：

每个subagent都会消耗模型和工具资源
并行越多，token和成本越高
写代码时可能发生冲突
需要更清楚地拆分任务边界
需要主agent汇总和判断

使用原则：

优先用于read-heavy任务：探索、review、triage、summarization
write-heavy任务必须拆清楚文件所有权
每个subagent的任务要具体、独立、可验收
明确是否等待全部agent
明确每个agent应返回什么格式

11.自定义agents

Codex内置agent类型包括：

Agent	适合任务
`default`	通用任务
`worker`	实现、修复、执行
`explorer`	读代码、探索、分析

官方文档说明，也可以定义自定义agents。位置：

text

~/.codex/agents/
.codex/agents/

每个自定义agent文件至少需要：

name
description
developer_instructions

可选字段包括：

model
model_reasoning_effort
sandbox_mode
mcp_servers
skills.config
nickname_candidates

示例：

toml

name = "security-reviewer"
description = "Use for security-focused review of authentication, authorization, input validation, and sensitive data handling."
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
Focus only on security risks.
Report findings with file paths, concrete exploit or failure mode, and recommended fix.
Do not comment on style unless it creates a security risk.
Do not modify files.
"""

一句话理解：

自定义agents是把某类并行角色固定下来，避免每次都重新描述角色和标准。

12.Background mode：API侧长任务异步执行

Background mode是OpenAI API的能力，不是Codex CLI的slash command。

官方说明：对于需要几分钟的复杂推理任务，Background mode可以让请求异步执行，开发者随后轮询response状态，避免超时或连接中断问题。

开启方式是在Responses API请求中设置：

json

{
  "model": "gpt-5.5",
  "input": "Run a long analysis task",
  "background": true
}

Node示例：

import OpenAI from "openai";

const client = new OpenAI();

let resp = await client.responses.create({
  model: "gpt-5.5",
  input: "Run a long analysis task",
  background: true,
});

while (resp.status === "queued" || resp.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  resp = await client.responses.retrieve(resp.id);
}

console.log(resp.status);
console.log(resp.output_text);

适合：

长文档分析
长时间推理
大型报告生成
复杂规划
需要异步轮询的API集成

注意：

Background mode会暂存response数据以支持轮询
官方文档说明它不兼容Zero Data Retention保证
如果你的项目有严格数据保留要求，需要先确认政策和数据边界

Background mode解决的是API请求长时间运行的问题；codex exec和GitHub Action解决的是Codex工程任务自动化的问题。

13.五种进阶能力怎么分工

能力	入口	解决的问题
Non-interactive mode	`codex exec`	在脚本、CI、管道中运行Codex
Codex SDK	TypeScript/Python SDK	在程序中控制Codex thread和任务
GitHub Action	`openai/codex-action@v1`	在GitHub Actions中自动review、检查、运行任务
Subagents	CLI/App中显式要求	并行探索、review、triage、拆分复杂任务
Background mode	Responses API	长时间API请求异步执行和轮询

最容易混淆的是：

text

codex exec vs GitHub Action
本地/CI命令行自动化=>GitHub workflow封装

codex exec vs SDK
单次脚本任务=>程序化、多轮、系统集成

Subagents vs Background mode
并行agent工作流=>API长任务异步运行

14.推荐落地顺序

不要一开始就把所有自动化都接上。

推荐顺序：

第一步：先写稳定prompt

来自第3阶段：

text

目标+上下文+范围+约束+验证+输出要求

如果prompt还不稳定，不要自动化。

第二步：先用`codex exec`做只读任务

例如：

总结diff
review PR
分析测试失败
生成release notes草稿

第三步：加入结构化输出

使用：

bash

--json
--output-schema
--output-last-message

让结果方便被脚本或CI读取。

第四步：接GitHub Action

先做只读PR review或风险总结。

第五步：引入Subagents

只在任务天然可并行时使用，例如多角度review、多模块探索。

第六步：用SDK做内部系统集成

当codex exec已经不够用，需要管理thread、状态、队列、用户界面或内部平台时，再上SDK。

第七步：API长任务再考虑Background mode

如果你是在构建自己的API应用，而不是直接用Codex CLI/IDE，才重点考虑Background mode。

15.自动化前的检查清单

把Codex放进CI或批处理前，检查：

prompt是否已经在手工场景跑稳定？
AGENTS.md是否写清项目规则？
是否明确sandbox权限？
是否默认只读？
需要写文件时是否只给workspace-write？
是否避免danger-full-access？
是否有明确验证命令？
输出是否方便机器读取？
是否有失败时的处理路径？
是否避免泄露secrets？
GitHub Action是否使用最小权限？
外部贡献者PR是否有更严格策略？
自动修改是否需要人工review？
Subagents是否真的可并行？
SDK集成是否有日志、超时、重试和错误处理？

16.总结

text

稳定手工流程
        ->
codex exec脚本化
        ->
JSON/schema结构化
        ->
GitHub Action接入CI
        ->
Subagents并行处理复杂任务
        ->
SDK接入内部系统
        ->
Background mode支撑API长任务

第5阶段的核心不是“让Codex自己随便跑”，而是把已经清晰、可验证、有边界的工程任务接进脚本、CI、GitHub workflow和内部系统，让自动化放大稳定流程，而不是放大不确定性。

1.短信登录

2.商户查询缓存

3.优惠卷秒杀

4.达人探店

5.好友关注

6.附近商铺

7.用户签到

8.UV统计

项目

项目

1.简介

2.Non-interactive mode：用`codex exec`跑自动化任务

3.codex exec的权限和安全

4.codex exec的典型场景

4.1.自动PR review

4.2.自动生成release notes

4.3.自动排查失败日志

4.4.自动修复小问题

4.5.结构化输出

5.Codex SDK：程序化控制Codex

6.codex exec和Codex SDK怎么选

7.GitHub Action：把Codex接入PR和CI

8.GitHub Action的安全和设计原则

9.Subagents：并行处理复杂任务

10.Subagents的上下文和成本

11.自定义agents

12.Background mode：API侧长任务异步执行

13.五种进阶能力怎么分工

14.推荐落地顺序

第一步：先写稳定prompt

第二步：先用`codex exec`做只读任务

第三步：加入结构化输出

第四步：接GitHub Action

第五步：引入Subagents

第六步：用SDK做内部系统集成

第七步：API长任务再考虑Background mode

15.自动化前的检查清单

16.总结

1.简介 ​

2.Non-interactive mode：用codex exec跑自动化任务 ​

3.codex exec的权限和安全 ​

4.codex exec的典型场景 ​

4.1.自动PR review ​

4.2.自动生成release notes ​

4.3.自动排查失败日志 ​

4.4.自动修复小问题 ​

4.5.结构化输出 ​

5.Codex SDK：程序化控制Codex ​

6.codex exec和Codex SDK怎么选 ​

7.GitHub Action：把Codex接入PR和CI ​

8.GitHub Action的安全和设计原则 ​

9.Subagents：并行处理复杂任务 ​

10.Subagents的上下文和成本 ​

11.自定义agents ​

12.Background mode：API侧长任务异步执行 ​

13.五种进阶能力怎么分工 ​

14.推荐落地顺序 ​

第一步：先写稳定prompt ​

第二步：先用codex exec做只读任务 ​

第三步：加入结构化输出 ​

第四步：接GitHub Action ​

第五步：引入Subagents ​

第六步：用SDK做内部系统集成 ​

第七步：API长任务再考虑Background mode ​

15.自动化前的检查清单 ​

16.总结 ​

1.简介

2.Non-interactive mode：用`codex exec`跑自动化任务

3.codex exec的权限和安全

4.codex exec的典型场景

4.1.自动PR review

4.2.自动生成release notes

4.3.自动排查失败日志

4.4.自动修复小问题

4.5.结构化输出

5.Codex SDK：程序化控制Codex

6.codex exec和Codex SDK怎么选

7.GitHub Action：把Codex接入PR和CI

8.GitHub Action的安全和设计原则

9.Subagents：并行处理复杂任务

10.Subagents的上下文和成本

11.自定义agents

12.Background mode：API侧长任务异步执行

13.五种进阶能力怎么分工

14.推荐落地顺序

第一步：先写稳定prompt

第二步：先用`codex exec`做只读任务

第三步：加入结构化输出

第四步：接GitHub Action

第五步：引入Subagents

第六步：用SDK做内部系统集成

第七步：API长任务再考虑Background mode

15.自动化前的检查清单

16.总结