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

图:本站根据 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)

图:本站根据 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 exec 非交互模式怎么用
- Codex 代码审查怎么用
- Claude Code GitHub Actions 配置教程
- Codex 怎么收费:随订阅、Credits 与 API Key 对比
参考资料
- 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
0 条评论
还没有评论,来抢沙发~