Codex 圖片任務
所有專案或批次圖片任務都必須透過執行器來執行。請勿手動呼叫 codex exec 或 codex-imagegen 來處理這些任務。
python scripts/codex_image.py "<提示詞或 @prompt.txt>" out.png [--ref room.jpg] [--size 1536x1024] [--force]
該執行器會印出絕對路徑的輸出檔。給予 Bash 呼叫的超時時間應高於執行器自身的 --timeout（預設 420 秒）。
| 退出碼 | 意義 | 處理方式 |
|---|---|---|
| 0 | 已儲存 | 檢視圖片 |
| 1 | 用法錯誤，例如輸出已存在 | 修正呼叫；--force 會取代輸出，但絕不取代自己的參考圖 |
| 2 | Codex 結束但未產生圖片 | 讀取印出的輸出內容，修正原因後重試一次 |
| 3 | 圖片呼叫遺漏了參考圖，因此未儲存任何內容 | 使用相同指令重試一次 |
| 124 | 無可用 session 或未在時間內產生圖片 | 檢查 codex login status 及網路連線 |
規則
- 將每個輸出與其簡要描述對照檢視。 退出碼 0 只證明本次 session 產出了一張圖片，不保證圖片正確。
- 一次只進行一個變更的鏈式編輯： 每個輸出成為下一個
--ref。每一步都寫入一個新檔案。 - 保持房間不變： 指出哪些部分不得改變（相機、幾何、開口），並在有兩個以上參考圖時命名每個參考圖的角色。最多 4 個參考圖。
- 計算配額。 每次執行耗費一張圖片，且執行可以並行進行，但在批次大量執行前應先確認配額數量，並確保第一張圖片成功後再進行後續。
- 含 Alpha 通道的 PNG 參考圖： 傳遞
--keep-png-refs，因為 JPG 轉換會將其扁平化。
為什麼需要執行器
使用 codex-cli 0.164.0 於 2026-11-04 進行測量，來自 30 次圖片執行的 session 日誌。
| 失敗情況 | 原因 | 執行器的處理方式 |
|---|---|---|
| 直到超時才停止 | codex exec 等待 stdin 管道開啟：使用管道時 45 秒（由超時停止），關閉後 4 秒 | 在 stdin 上發送提示詞，然後關閉 stdin |
| 名稱對應到錯誤圖片 | 被告知要儲存，Codex 搜尋共享的 ~/.codex/generated_images，取用最新的一張並複製其他執行的圖片 | Codex 永不儲存；執行器只讀取 generated_images/<其 session id>/ |
| 一次輸出最多產生 7 次圖片呼叫 | Codex 找不到儲存方式，因此再次生成 | 在第一張完整圖片出現後停止 Codex |
| 忽略參考圖，憑空創造房間 | 圖片工具只有在呼叫設定 num_last_images_to_include 時才能看到附件 | 命名該參數，讀取 session 日誌，若遺漏則退出碼為 3 |
| 鏈式傳遞時房間遺失 | 每次家具傳遞都會遺失 PNG 房間；JPG 搭配命名參數則保留（相關性，非證明的因果關係） | 當 ffmpeg 在 PATH 中時，將 PNG 參考圖轉換為 JPG |
同日使用真實 CLI 驗證：三次編輯，其中兩次在 PNG 參考圖上並行執行，每次約需 25 秒與一次圖片呼叫，且各自保留自己的顏色變更。
如果必須使用外掛的 codex-imagegen
codex-bridge 1.2.0 有以下失敗情況。請使用 </dev/null、一次一個任務、JPG 參考圖，並在提示詞中加入「只呼叫圖片工具一次，並設定 num_last_images_to_include:1」，然後檢視結果。