結論先說
- 官方目前提供兩款正式 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 條評論
還沒有評論,來搶沙發~