Codex SDK 与 GitHub Action 怎么用:TypeScript、Python 库与流水线集成

想在代码或 CI 里编程控制 Codex?按官方文档整理:TypeScript(@openai/codex-sdk)、Python(openai-codex)两个官方 SDK 的安装与线程用法,以及 openai/codex-action@v1 的安全工作流配置。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Plus 账号

结论先说

  1. 官方目前提供两款正式 SDK(TypeScript 与 Python)和一款官方 GitHub Action(openai/codex-action@v1)。
  2. TypeScript SDK 包名为 @openai/codex-sdk(需 Node.js 18+,仅限服务端运行);Python SDK 包名为 openai-codex(需 Python 3.10+,自带锁定的 CLI 运行时)。
  3. 旧版 codex mcp-server 已被官方移除:如果要自建完整的图形客户端管理登录、审批和流式事件,官方要求改用 codex app-server。
  4. 在 GitHub Actions 里优先用 openai/codex-action@v1,它会自动装好 CLI、启动本地 Responses API 代理,并通过默认 drop-sudo 策略隔离内存里的 API 密钥。
  5. 在 CI 中务必做读写权限分离:跑 Codex 的 Job 只给 contents: read,写评论或提 PR 放到不接触 OPENAI_API_KEY 的下游独立 Job。

Codex 三种代码级与流水线集成方式

图:本站根据 Codex 官方文档:Codex SDK 与 GitHub Action 文档整理的示意图

本文根据 Codex 官方文档《Codex SDK》《Codex GitHub Action》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。若你只需要在 Shell 脚本里跑单行命令,可先看 codex exec 非交互模式怎么用;Claude Code 的同类流水线方案见 Claude Code GitHub Actions 配置教程。

适用于谁

  • 想把 Codex 嵌入自研内部研发平台、代码助手或自动化服务的 Node.js 与 Python 开发者;
  • 想在 GitHub Actions 里自动审 PR、失败后生成修复补丁,同时防止构建脚本窃取 API 密钥的团队;
  • 还在找已废弃的 codex mcp-server,想知道官方现在推荐什么集成接口的人。

一、TypeScript SDK(@openai/codex-sdk)

TypeScript 库用于在服务端启动、继续和恢复本地 Codex 线程,运行环境要求 Node.js 18 及以上。

安装命令:

bash
npm install @openai/codex-sdk

最小起停与恢复线程示例(摘自官方用法结构):

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

const codex = new Codex({
  config: { default_permissions: "audit" },
});

// 创建新线程并打上来源标签
const thread = codex.startThread({ threadSource: "ci" });
const step1 = await thread.run("诊断当前测试失败原因并给出修复计划");
console.log(step1.finalResponse);

// 在同一线程继续执行,或按 thread.id 恢复历史线程并指定可写沙箱
const resumed = codex.resumeThread(thread.id!, {
  sandboxMode: "workspace-write",
});
const step2 = await resumed.run("按刚才的计划实施最小化修改");
console.log(step2.finalResponse);

需要传复杂 TOML 嵌套项时,可在初始化 new Codex() 时传 configOverrides 字符串数组;这些内存覆盖不会改动磁盘上的 config.toml 文件。

二、Python SDK(openai-codex)

Python 库通过 JSON-RPC 控制本地 app-server,要求 Python 3.10 及以上。官方发布的包内已自带锁定的 Codex CLI 运行时,直接装完就能跑:

bash
pip install openai-codex

同步与沙箱切换示例(异步项目可改用 AsyncCodex):

python
from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-6.1-sol",
        sandbox=Sandbox.workspace_write,
    )
    thread.run("修复失败的单测")
    # 下一回合临时收紧为只读沙箱做复核
    review = thread.run("仅审阅刚才的 diff 是否有遗漏", sandbox=Sandbox.read_only)
    print(review.final_response)

Python SDK 还提供了几个很实用的工程特性:

  • 外部系统低优先级注入(ExternalMessage):把工单正文包装成 ExternalMessage(tool_name="issue_tracker", content=body) 传给 thread.run(),Codex 会把它当作工具输出而非高优先级指令处理,降低工单内容夹带提示词注入的风险。
  • 不拉取旧回合历史恢复(include_turns=False):调 codex.thread_resume() 时跳过把旧轮次拉回客户端响应,模型侧依然保有完整上下文。
  • 单回合独立速度档位:传 turn_service_tier="default" 可只改变当前回合的速度档。

三、官方 GitHub Action(openai/codex-action@v1)

GitHub Actions 接入 Codex 五步

图:本站根据 Codex 官方文档:Codex GitHub Action 整理的示意图

相比自己写脚本装 CLI 并直接注入密钥,官方推荐在工作流里用 openai/codex-action@v1。下面是按官方范例整理的 PR 自动审查工作流骨架:

yaml
name: Codex PR Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: read-only
          output-file: codex-output.md

拿到 outputs.final-message 后,再起第二个带 pull-requests: write 但不传 OPENAI_API_KEY 的 Job 把评审结果发到 PR 评论区(若是原生 GitHub 应用审查用法,另见 Codex 代码审查怎么用)。

常用输入项与排错要点:

  • prompt 与 prompt-file 二选一:同时填两个会直接报错;额外 CLI 参数(如 ["--ephemeral"] 或 --output-schema)通过 codex-args 传入。此外还支持用 model 和 effort 指定模型与推理档位,用 codex-version 锁定固定 CLI 版本号,用 codex-home 指向共享配置目录复用 MCP 设置。
  • safety-strategy 特权控制:在 Linux 与 macOS Runner 上默认是 drop-sudo(不可逆地移除 sudo 保护内存中的代理密钥),也可配合 codex-user 设为 unprivileged-user;如果在 Windows Runner 上运行,官方说明必须显式设为 safety-strategy: unsafe,且绝不要在多租户共享机器上留用 unsafe 模式。
  • allow-users 与 allow-bots:默认仅仓库有写权限的协作者能触发该 Action,防止陌生外部账号消耗你的额度。
  • 官方安全清单补充:把外部 PR 标题、提交说明或工单正文喂给 Codex 前要先清洗掉隐藏的 HTML 注释以防提示词注入;尽量把 Codex 放在当前 Job 的最后一步运行,避免后续步骤继承意外的工作区状态变更。

SDK 与 GitHub Action 在无人值守环境通常走 API Key 按量计费;开发者日常在本机交互调试若想用订阅额度,计费差异见 Codex 怎么收费,开通个人订阅可看本站 ChatGPT Plus 充值说明。

常见问题

问:运行 Action 时报 responses-api-proxy didn't write server info 怎么办?

答:官方排错清单指出,内置代理只有在提供了有效的 openai-api-key 输入时才会启动,请检查仓库 Secrets 名称是否拼对且密钥未失效。

问:drop-sudo 之后报工作区文件无权限写入怎么办?

答:如果任务需要改文件生成补丁,在调用 Action 之前的步骤先给工作区目录补好组读写权限(例如 chmod -R g+rwX "$GITHUB_WORKSPACE"),或改用官方 unprivileged-user 模式。

问:想自己做一套带自定义界面的 IDE 插件,该用 SDK 还是别的接口?

答:SDK 适合后端任务编排;若要做管理登录、历史列表、实时审批弹窗和流式事件的完整客户端,官方建议对接 codex app-server(支持 stdio 与 WebSocket)。

相关教程

参考资料

  • Codex 官方文档:Codex SDK — https://learn.chatgpt.com/docs/codex-sdk
  • Codex 官方文档:Codex GitHub Action — https://learn.chatgpt.com/docs/github-action
  • GitHub 仓库:openai/codex-action — https://github.com/openai/codex-action

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  2. 02

    多 Agent 的成本为什么翻倍、怎么控制:Token 膨胀根源与五项降本措施

    刚把单智能体拆成多 Agent,用量往往暴涨好几倍。Anthropic 工程报告统计单智能体约为聊天的 4 倍 Token,多智能体可达约 15 倍。本文拆解固定前缀重复加载、历史搬运、工具链定义与缓存失效四大根源,并给出五条实操控费办法。

    ChatGPTClaude0
  3. 03

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  4. 04

    多 Agent 编排模式详解:编排者-工作者、交接(Handoffs)、并行与评估循环怎么选

    搜「multi-agent orchestration 中文」会被各家框架的不同术语绕晕。本文对照 Anthropic《Building effective agents》与 OpenAI 智能体指南,把编排者-工作者、去中心化交接、并行分片投票与生成-评估循环四种标准编排拓扑讲透。

    ChatGPTClaude0
  5. 05

    多智能体(Multi-Agent)是什么、什么时候该用:Anthropic 与 OpenAI 官方判断标准

    多智能体不是代理越多越聪明。本文依据 Anthropic 研究系统架构文章与 OpenAI 官方智能体指南,讲清确定性工作流、单智能体与多智能体的区别,以及哪三类瓶颈才值得上多智能体协同。

    ChatGPTClaude0
  6. 06

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~