結論先說
--output-schema <路徑>用於強制約束codex exec的最終輸出結構。按官方文檔說明,傳入 Schema 文件後,模型在標準輸出(stdout)返回的最終結果會嚴格匹配定義好的字段名與類型。- 它和
--json參數用途完全不同。--output-schema把最終答案變成單個業務 JSON 對象;而--json是把整個執行期間的會話啟動、工具調用和消息輸出變成逐行 JSONL 事件流。 - 編寫 Schema 時每個對象層級都要寫嚴約束。參照 OpenAI 結構化輸出規範,根對象及嵌套對象均需設定
additionalProperties為false,並把當前層所有屬性列入required數組。 - 提取報告時建議搭配
--sandbox read-only。只讀沙箱能防止 Codex 在分析過程中修改業務代碼,保證流水線檢查安全可控。 - 自動化審查流水線對帳號額度消耗較集中。國內缺少外幣卡或綁卡受阻的用戶,可在本站自助開通 ChatGPT Plus 或更高額度的 ChatGPT Pro,團隊集中採購可諮詢 ChatGPT Business 團隊定製。

圖:本站根據 OpenAI Codex 官方文檔:Non-interactive mode 整理的示意圖
本文根據 OpenAI Codex 官方文檔《Non-interactive mode》《Command line options》及 OpenAI API《Structured Outputs》指南整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 在 GitHub Actions、GitLab CI 或本地腳本里調用
codex exec,需要下游程序穩定解析返回字段的開發者; - 用提示詞要求只輸出 JSON,卻仍偶發遇到多餘代碼塊圍欄或字段缺漏的人;
- 分不清
codex exec裏--output-schema與--json兩個參數各自用途的用戶。
一、--output-schema 與 --json 參數對比
查閱命令幫助(見 /guides/codex-cli-commands-cheatsheet)時容易混淆這兩個選項,核心差異如下:
| 對比項 | --output-schema ./schema.json | --json |
|---|---|---|
| 輸出格式 | 單個符合自定義 Schema 的 JSON 對象 | 多行換行分隔的 JSONL 系統事件流 |
| 關注重點 | 業務結論的字段結構(如問題列表、嚴重級別) | 運行全鏈路軌跡(思考、讀文件、跑命令事件) |
| 下游解析方式 | 直接交給 jq 或腳本 json.load 解析 | 按行流式讀取並過濾末尾完成事件 |
| 典型場景 | 自動生成審查單、變更元數據、風險評級卡 | 自研外部監控面板、審計代理每一步動作 |
若業務腳本只關心最終審查結論,直接使用 --output-schema 最穩妥。底層 Schema 語法規則可參考 /guides/openai-api-structured-outputs。
二、實戰步驟:提取標準格式代碼審查報告
第 1 步:生成 review-schema.json
在項目根目錄用 Python 生成標準 Schema 文件,確保根類型為 object 且所有屬性列入 required:
python
import json
schema = dict(
type='object',
additionalProperties=False,
required=['passed', 'summary', 'issues'],
properties=dict(
passed=dict(type='boolean'),
summary=dict(type='string'),
issues=dict(
type='array',
items=dict(
type='object',
additionalProperties=False,
required=['file', 'line', 'severity', 'reason'],
properties=dict(
file=dict(type='string'),
line=dict(type='integer'),
severity=dict(type='string', enum=['high', 'medium', 'low']),
reason=dict(type='string'),
),
),
),
),
)
json.dump(schema, open('review-schema.json', 'w', encoding='utf-8'), indent=2)
第 2 步:結合 git diff 執行審查並做門禁判斷
bash
git diff origin/main...HEAD | codex exec \
--sandbox read-only \
--output-schema ./review-schema.json \
"審查當前分支相對於 main 的變更。存在 high 級別缺陷時將 passed 設為 false,用中文填寫 summary 與 reason。" \
> review-report.json
jq -e '.passed == true' review-report.json >/dev/null || exit 1
專用審查命令對比也可查看 /guides/codex-code-review。
訂閱與帳號準備提示:在本地和腳本里批量跑結構化代碼審查會持續佔用模型推理配額。遇到額度見底時,可在本站自助升級 ChatGPT Pro 充值 或選用 ChatGPT Pro 5x 空白號檔;日常輕量審查開通 ChatGPT Plus 會員 即可滿足需求。
三、常見 Schema 報錯與排錯決策

圖:本站根據 OpenAI Structured Outputs 官方指南 整理的示意圖
遇到命令報錯或解析失敗時(更多錯誤見 /guides/codex-common-errors-summary),按三點核查:
- 報
invalid_json_schema400 錯誤:通常是嵌套對象漏寫了additionalProperties: false,或properties裏的字段未全部放進required。需要可空字段時,把類型設為['string', 'null']並保留在required中。 - 根節點寫成了
array:結構化輸出頂層必須是object,返回列表時包一層issues屬性即可。 - 輸出文件混入進度日誌:檢查是否在
codex exec右側誤加了2>&1。保持預設分離才能讓stdout只輸出純 JSON。 - 字段描述(
description)寫得含糊導致取值偏離預期:雖然 Schema 能鎖死字段名和數據類型,但對於評分口徑、嚴重等級劃分標準等語義邊界,建議在每個屬性的description字段中用一兩句中文寫清判定依據(例如明確寫出「僅當可導致線上崩潰、數據越權或資金計算錯誤時標為 high,代碼風格建議一律標為 low」),能顯著減少誤報攔截。 - 超長差異導致響應緩慢或超時:當合並請求包含自動生成的鎖文件(如
package-lock.json、pnpm-lock.yaml)或編譯產物時,直接將全量git diff塞進管道會拖慢審查速度;上游命令可用路徑排除語法(如git diff origin/main...HEAD -- . ':(exclude)lock')提前過濾無關文件。
常見問題
問:--output-schema 支持所有 JSON Schema 校驗語法嗎?
答:它遵循 OpenAI Structured Outputs 支持子集,基礎類型、enum 枚舉、嵌套對象與數組均支持;若包含不受支持的關鍵字,接口會返回 400 並指出具體字段。
問:能不能用命令行參數直接指定輸出文件路徑?
答:可以。除標準輸出重定向外,官方命令參考中 codex exec 也支持輸出文件選項,具體參數名可運行 codex exec --help 核對當前 CLI 版本。
問:國內沒有境外信用卡,或團隊需要開增值稅發票報銷,怎麼開通訂閱?
答:可前往本站 AI 會員充值總覽 選用 ChatGPT Plus 或 ChatGPT Pro,支持支付寶、微信支付及 AlipayHK 結算,提供卡密自助兌換(無需交出密碼)與團隊定製,支持開具增值稅發票。實時價格以頁面顯示為準;售後遵循掉訂閱按剩餘天數折退、封號不在質保範圍的規則。
相關教學
參考資料
- OpenAI Codex 官方文檔:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode
- OpenAI Codex 官方文檔:Command line options — https://learn.chatgpt.com/docs/developer-commands
- OpenAI API 官方文檔:Structured Outputs — https://platform.openai.com/docs/guides/structured-outputs
0 條評論
還沒有評論,來搶沙發~