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 條評論

登入 後參與評論

還沒有評論,來搶沙發~