04 · 雲端、CI 與非互動模式

三條不同的自動化路子

方式	跑在哪	適合
codex exec	你的機器 / 你的 CI 執行器	流水線、合併前檢查、定時作業、跟別的指令拼管道
Codex GitHub Action	GitHub 執行器	PR 審查、CI 質量門、可重複的工作流任務
Codex 雲端	OpenAI 託管的隔離容器	你想把活扔出去、回頭看結果

codex exec：給指令碼用的 Codex

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

輸出分流很關鍵：執行期間進度流到 stderr，只有最終的智慧體訊息打到 stdout。 所以重定向和管道都很乾淨：

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

不想在磁碟上留工作階段記錄：

codex exec --ephemeral "triage this repository and suggest next steps"

stdin 也能用。如果同時給了提示參數和管道輸入，提示當指令，管道內容當額外上下文：

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md

權限：預設就是對的

codex exec 預設在只讀沙盒裡跑。 自動化裡請按需要的最低權限來：

codex exec --sandbox workspace-write "<task>"     # 允许改文件
codex exec --sandbox danger-full-access "<task>"  # 只在隔离的运行器或容器里用

舊的 --full-auto 還留著，但已棄用並會告警，新指令碼直接寫明 --sandbox workspace-write。

兩個在受控自動化裡有用的開關：

• --ignore-user-config：這次執行不載入 $CODEX_HOME/config.toml
• --ignore-rules：跳過使用者和專案的 execpolicy .rules 檔案

另外：如果某個啟用的 MCP 伺服器配了 required = true 而初始化失敗， codex exec 會報錯退出，不會在缺伺服器的情況下硬跑。這是好事，別繞過它。

機器可讀的輸出

codex exec --json "summarize the repo structure" | jq

--json 之後 stdout 變成 JSON Lines 流，能拿到執行期間的每個事件： thread.started、turn.started、turn.completed、turn.failed、item.*、error。 條目型別涵蓋智慧體訊息、推理、指令執行、檔案更改、MCP 工具呼叫、網頁搜尋、計劃更新。

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

只要最終訊息用 -o <path> / --output-last-message <path>，會寫檔案同時照樣打到 stdout。

下游要結構化資料就用 --output-schema 要一個符合 JSON Schema 的最終響應—— 作業摘要、風險報告、釋出後設資料這類需要穩定欄位的場景。

接著上一次跑

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

也可以 codex exec resume <SESSION_ID> 指定具體工作階段。兩階段流水線用得上。

它要求在 Git 倉庫裡跑

這是防破壞性改動的保護。確定環境安全的話可以 --skip-git-repo-check 跳過， 但在 CI 裡一般沒必要跳——程式碼本來就是簽出來的。

GitHub Action

- 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

官方建議用這個 Action，而不是自己裝 CLI 再把 API 金鑰傳給 shell 步驟。 它會裝 Codex、啟動 Responses API 代理、按你指定的權限跑 codex exec， 把金鑰暴露面收窄。

前提條件：金鑰存成 GitHub 機密；在 Linux 或 macOS 執行器上跑 （Windows 必須設 safety-strategy: unsafe）；先 checkout 再呼叫它。

safety-strategy 值得單獨說

值	效果
drop-sudo（預設）	跑 Codex 前移除 sudo，對該作業不可逆，保護記憶體中的機密
unprivileged-user	配合 codex-user，以特定非特權賬戶執行
read-only	阻止 Codex 改檔案或聯網，但執行時仍有提升的權限——別隻靠它保護機密
unsafe	不加保護，絕不要在多租戶執行器上保持這個模式

另有 sandbox 限制 Codex 自己對檔案系統和網路的存取， 以及 allow-users / allow-bots 限制誰能觸發工作流 （預設只有有寫權限的使用者能跑）。

安全檢查清單

官方列的四條，每條都是踩出來的：

1. 限制誰能啟動工作流——用受信任的事件或顯式核准，別讓所有人都能對你的倉庫跑 Codex。
2. 清洗來自 PR、提交訊息、議題正文的提示輸入，防提示注入。 HTML 註釋和隱藏文本在餵給 Codex 前先看一眼。
3. 保護 OPENAI_API_KEY：safety-strategy 保持 drop-sudo，或讓 Codex 以非特權使用者跑。
4. 讓 Codex 在作業的最後一步跑，免得後續步驟繼承意外的狀態改動。

金鑰怎麼放

這一條特別重要：如果工作流會簽出或執行由程式碼庫控制的程式碼， 不要把 OPENAI_API_KEY 或 CODEX_API_KEY 設成作業級環境變數。 同一作業裡的構建指令碼、測試、依賴生命週期鉤子，或者一個被入侵的 Action，都能讀到它。

單次執行用不同金鑰的話內聯給：

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

如果你的雲環境或 CI 執行時本來就有短期工作負載令牌， 優先用工作負載身份聯合，別存 OpenAI 憑據。

用 Codex 使用者賬戶（而不是 API 金鑰）跑 CI 也是可以的，但注意： ~/.codex/auth.json 裡是存取令牌，像密碼一樣保護，別提交、別貼工單、別在聊天裡發。 官方明確說了不要把這個工作流用於公開或開源倉庫。 API 金鑰更容易預配和輪換，是自動化的合適預設選擇。

Codex 雲端

雲端聊天跑在 OpenAI 管理的隔離容器裡，碰不到你的主機系統。 它是兩階段的：

1. 設定階段：可以存取網路，裝你指定的依賴。
2. 智慧體階段：預設離線，除非你為這個環境啟用了網際網路存取。

給雲端環境配的機密只在設定階段可用，進智慧體階段之前就被移除了。 這個設計意味著：需要在智慧體階段用到的憑據，得換個方式給—— 把它當成一條約束，而不是一個 bug。

用雲端必須用 ChatGPT 賬號登入，API 金鑰這條路走不通（見 快速上手 02）。

相關官方文件

• 非互動模式
• GitHub Action · openai/codex-action
• 雲端環境 · 智慧體網際網路存取
• Codex SDK
• 工作負載身份