生活分享
Claude Code、Codex、Gemini CLI 分工:規劃、執行、審查
把 Claude Code、Codex 與 Gemini CLI 接成規劃、執行、審查的一條管線,靠的是三支命令列各自的非互動旗標,本文查證的文件沒有跨工具的整合功能。這篇會列出 claude -p、codex exec 與 gemini -p 在腳本裡實際會用到的輸出格式旗標,並示範用 plan.md、patch 與 review.json 三個檔案讓三支工具接力完成同一件事;讀者需要能在終端機執行這三支 CLI 並各自登入,腳本只用 bash 與 Python 內建的 json 模組。
閱讀時間約 10 分鐘

本篇目錄
Claude Code 的 claude -p、Codex 的 codex exec 與 Gemini CLI 的 gemini -p,都能把提示詞丟進去、跑完一次任務就結束,不用打開對話畫面;但三家把『非互動』做成不同的樣子:核准旗標三家各叫各的名字,輸出格式旗標只有其中兩家同名,連文件有沒有寫「CLI 會照 JSON Schema 驗證輸出」也不一樣。這篇要回答:想讓這三支 CLI 接力完成同一個編碼任務——一支規劃、一支執行、一支審查——該讀哪幾個旗標、用什麼檔案交接;答案是非互動旗標得各自對官方文件核對,交接檔則要自己設計,因為本文查證的三家文件都沒有定義工具之間的交接格式。
讀完這篇,你會有一支串接三支 CLI 的 bash 腳本可以照抄修改,也會知道三支工具在非互動模式下各自用什麼旗標決定輸出格式與核准方式。你需要一台已經裝好 Claude Code、Codex 與 Gemini CLI 三支命令列代理(Agent),而且三支都完成官方要求的登入或金鑰設定的電腦,命令列環境能跑 bash 與 Python 3.11 以上——腳本裡只用標準函式庫內建的 json 模組,不必另外安裝套件;這篇不重講怎麼安裝或登入,只講三支工具湊在同一條腳本裡時,非互動旗標與交接檔要注意的地方。
為什麼三支 CLI 要分開規劃、執行、審查
把一個編碼任務拆成規劃、執行、審查三個階段,讓一支 CLI 只做其中一個階段,是為了讓每一步的產出可以被檢查,而不是整段過程交給同一個對話做到底。規劃階段只讀專案、寫出步驟,不改檔案;執行階段依規劃修改程式碼,產出一份 diff;審查階段讀 diff 與規劃,回報能不能合併。三個階段互相看不到對方的對話紀錄,只能靠檔案交換結果,這正是『非互動』模式派得上用場的地方——每一支 CLI 都是被腳本呼叫一次、印出結果就結束。
claude -p 本身的非互動用法與 JSON 輸出,站上《Claude Code|非互動執行與 JSON 輸出》已經介紹過;codex exec 的腳本寫法,《codex exec 與腳本整合》談過;Gemini CLI 怎麼理解、規劃、修改與測試,《CLI 寫程式:理解、規劃、修改與測試》也寫過,這篇不重講,只挑三支接在一起才需要的旗標。同一支工具開多個 session 分工可看《Claude Code|Agent Teams 協作》;那篇的角色都是 Claude Code 自己的 session,這篇要接的卻是三家不同廠商的 CLI,彼此不共用登入,只能靠檔案交換結果。
三支 CLI 的非互動旗標怎麼查
三家官方文件把『不開互動畫面、執行一次就結束』取了不同名字。Anthropic 的 Claude Code 文件稱為 print mode;OpenAI 的 Codex 文件把 codex exec 稱為 non-interactive mode,說明是給腳本與 CI(持續整合)用的,不會開啟互動式終端機介面;Google 的 Gemini CLI 文件則稱為 headless mode,說明是程式化的介面,回傳結構化文字或 JSON 輸出。名字不同,做的事情類似:丟進提示詞,等跑完,讀輸出,行程結束。
三支 CLI 觸發非互動模式的方式也不一樣:Claude Code 是 claude -p(完整寫法 --print)加提示詞,官方範例執行完就結束,也能用管線接檔案內容;Codex 的指令參考文件把 codex exec 標成 Stable 等級,提示詞接在後面就會開始跑;Gemini CLI 是 gemini -p(或 --prompt)加提示詞,官方文件寫位置引數在 TTY 裡預設是互動模式,要靠 -p/--prompt 才強制轉成非互動。輸出格式的旗標,Claude Code 與 Gemini CLI 同名都叫 --output-format,可選 text、json、stream-json;Codex 靠 --json(別名 --experimental-json)印換行分隔的 JSON 事件,細節列在下表。
| CLI | 非互動旗標 | 輸出格式旗標 | 結構化輸出驗證 | 這篇腳本裡的角色 |
|---|---|---|---|---|
| Claude Code | -p(完整寫法 --print) | --output-format:text、json、stream-json | --json-schema 直接在命令列吃一段 JSON Schema,文件寫代理流程跑完後給出符合 schema 的輸出;schema 本身不合法就以錯誤結束,format 關鍵字只當註解、不做用戶端驗證 | 規劃:只讀專案、寫步驟到 plan.md,不改檔案 |
| Codex | codex exec 加一段提示詞 | --json(別名 --experimental-json)印出換行分隔的 JSON 事件 | --output-schema 指定一份 JSON Schema 檔,文件寫 Codex 拿它驗證工具輸出;--output-last-message(-o)另外把最後一則訊息寫成檔案,stdout 仍會印出 | 執行:在 --sandbox workspace-write 下修改檔案,跑完用 git add -N 與 git diff 存成 patch |
| Gemini CLI | -p(完整寫法 --prompt) | --output-format(別名 -o):text、json、stream-json | 無頭模式文件列出 response、stats 與選用的 error 三個外層欄位;本文查證當天沒在那幾頁看到 schema 驗證旗標 | 審查:讀 patch 與 plan.md,把結論解析後寫成 review.json |
表格裡『結構化輸出驗證』這一欄差最多。Claude Code 的 --json-schema 在命令列直接吃一段 JSON Schema,文件寫它在代理流程跑完後給出符合 schema 的輸出,schema 本身不合法就以錯誤結束;Codex 的 --output-schema 吃的是一份 schema 檔,文件寫 Codex 會拿它驗證工具輸出。Gemini CLI 的無頭模式文件只列出 response、stats 與選用的 error 三個外層欄位,本文查證當天沒有在那幾頁看到對應的 schema 驗證旗標,response 裡的結構要自己解析後再檢查。旗標縮寫也不共通:-o 在 Codex 裡是 --output-last-message,在 Gemini CLI 裡卻是 --output-format,抄範例前要認清是哪一支工具。
本站的交接檔格式:plan.md、patch、review.json
plan.md、patch 與 review.json 是這個網站自己在這篇裡設計的交接慣例,本文查證的三家文件都沒有定義這三個檔名或欄位——上面那些非互動旗標只管一次呼叫怎麼跑、輸出長什麼樣子,怎麼接成下一步的輸入得自己決定。挑這三個檔案是因為它們對應規劃、執行、審查三個階段最自然的產出:規劃是文字步驟,寫成 Markdown 最好讀;執行是程式碼變更,patch(統一格式的 diff)是版本控制系統本來就看得懂的格式;審查是判斷加理由,適合寫成固定欄位的 JSON。
review.json 裡固定放哪些欄位,一樣是自訂:這篇用 verdict(approve 或 changes_requested)、issues(陣列,每一項是一個問題)與 summary(一句話結論)三個欄位,理由是下一步的腳本只需要靠 verdict 就能決定要不要往下走,issues 留給人工複查或串進下一輪規劃當輸入。想改欄位名稱或加欄位都可以,只要規劃、執行、審查三支呼叫用的是同一份定義;如果想用正式的 JSON Schema 把這份定義寫下來、讓上下游互相驗證,系列另一篇《模型之間交接資料:JSON Schema 與結構化輸出》談的正是這件事,這裡不重複。
實作:一支 bash 腳本串起規劃、執行、審查
下面這支腳本把三支 CLI 接成一條管線:Claude Code 用 --permission-mode plan 進入規劃模式,官方文件寫這個模式讓 Claude 讀檔案、寫計畫但不會修改原始碼,而且在沒有互動終端機的 -p 執行裡一樣擋著,輸出存成 plan.md;Codex 用 --sandbox workspace-write 允許它修改工作目錄——官方文件寫預設沙盒是唯讀——跑完先 git add -N 再 git diff,新建的檔案才會進到 change.patch;Gemini CLI 用 --approval-mode=plan 讀 patch 與 plan.md,--output-format json 回傳一個物件,審查結果包在 response 欄位的文字裡,腳本再用一段 Python 解析後寫成這篇定義的 review.json。把 Plan Mode 拿來審查是本文的延伸用法:官方文件說它是給實作前設計解法用的唯讀環境,只準在計畫目錄裡寫 .md 檔。三支呼叫都包了 timeout,模型跑太久時讓那一步先失敗。
#!/usr/bin/env bash
# workflow.sh -- plan with Claude Code, execute with Codex, review with Gemini CLI.
# Usage: ./workflow.sh "<task description>"
# Requires: claude, codex and gemini already installed and signed in, and a
# git repository: codex exec refuses to run outside one, and step 2 diffs it.
set -euo pipefail
task="$1"
out=".handoff"
mkdir -p "$out"
# 1) plan: Claude Code only reads the repo and writes plain-text steps.
timeout 300 claude -p \
"$task. List the files and steps to change; do not edit anything." \
--output-format text \
--permission-mode plan \
>"$out/plan.md"
# 2) execute: Codex edits the working tree, then we diff it ourselves. Codex
# prints progress on stderr and the final message on stdout; -o keeps that
# message for debugging. "git add -N" is what makes files Codex created
# show up in git diff; the handoff directory stays out of the patch.
timeout 900 codex exec \
--sandbox workspace-write \
--output-last-message "$out/codex-final.txt" \
"Follow $out/plan.md and make the smallest change that satisfies it."
git add -N -- . ":(exclude)$out"
git diff -- . ":(exclude)$out" >"$out/change.patch"
# 3) review: Gemini CLI grades the patch. --approval-mode=plan is this site's
# extension of a mode the docs describe for planning, not reviewing.
# --output-format json wraps the answer in a "response" string, so the
# review.json shape below is this site's own convention: parsed and
# rewritten here rather than validated by the CLI.
prompt="Read $out/change.patch against $out/plan.md. Reply with only a JSON "
prompt+='object: {"verdict": "approve" or "changes_requested", "issues": [], "summary": "..."}'
timeout 300 gemini -p "$prompt" \
--approval-mode=plan \
--output-format json \
>"$out/raw-response.json"
python3 - "$out/raw-response.json" "$out/review.json" <<'PY'
import json
import sys
raw_path, review_path = sys.argv[1], sys.argv[2]
with open(raw_path, encoding="utf-8") as handle:
envelope = json.load(handle)
try:
review = json.loads(envelope["response"])
except (KeyError, json.JSONDecodeError):
review = {
"verdict": "changes_requested",
"issues": [],
"summary": "reviewer did not return valid JSON",
}
with open(review_path, "w", encoding="utf-8") as handle:
json.dump(review, handle, ensure_ascii=False, indent=2)
PY
verdict=$(python3 -c "import json;print(json.load(open('$out/review.json'))['verdict'])")
if [[ "$verdict" == "approve" ]]; then
echo "approved: $out/change.patch"
else
echo "changes requested, see $out/review.json" >&2
exit 1
fi
腳本最後只看 review.json 裡的 verdict:不是 approve 就讓腳本以非零狀態結束,把要修的地方留在 review.json 裡,不自動合併。前面三支呼叫則交給 set -euo pipefail:任何一支回非零,管線就停在那一步,不會拿半成品往下走。
交接檔範例與檢查
下面是 review.json 寫完後的樣子,對應前一節腳本最後一步的輸出。issues 陣列裡每一項建議至少放檔名、行號與理由三個欄位,方便規劃階段的下一輪直接引用;verdict 只用兩種值,讓下游的判斷邏輯不用處理第三種可能。
{
"verdict": "changes_requested",
"issues": [
{
"file": "payment/client.py",
"line": 42,
"severity": "blocking",
"note": "retry loop has no upper bound; add max_attempts before merging"
},
{
"file": "payment/client.py",
"line": 58,
"severity": "minor",
"note": "log message still references the old timeout constant"
}
],
"summary": "fixes the flaky assertion but the retry loop still needs a ceiling"
}
這支腳本是教學用的最小版本,正式排程或 CI 裡至少要再加重試、人工通知與整條管線的總花費上限——這些留給系列另一篇《失敗案例與防護:迴圈、費用爆炸與代理間注入》,這裡只示範交接檔本身。退出碼部分,Gemini CLI 的無頭模式文件列出四個:0 是成功,1 是一般錯誤或 API 失敗,42 是輸入錯誤,53 是對話輪數超過上限;本文這次讀到的 Claude Code 與 Codex 頁面只在個別旗標的說明裡提到失敗會以錯誤結束,沒有列出這樣的數字對照,串接時只能統一用『退出碼是不是 0』當成敗依據。
常見問題
claude -p、codex exec 與 gemini -p 這三種非互動模式,官方文件各自怎麼稱呼?
三家用的名字不一樣:Claude Code 的文件稱為 print mode;Codex 的文件把 codex exec 稱為 non-interactive mode,說明是讓 Codex 在腳本或 CI 裡執行、不開啟互動式終端機介面;Gemini CLI 的文件則稱為 headless mode,說明是程式化的介面,回傳結構化文字或 JSON 輸出。三個名字指的是同一件事:給提示詞、跑完、讀輸出、結束。
claude -p、codex exec 與 gemini -p 都能拿到通過驗證的結構化 JSON 輸出嗎?
不完全一樣。Claude Code 的 --json-schema 直接吃一段 JSON Schema,文件寫它會在代理流程跑完後給出符合 schema 的輸出;Codex 的 --output-schema 吃的是一份 schema 檔,文件寫 Codex 會拿它驗證工具輸出。Gemini CLI 的無頭模式文件列出的是 response、stats 與選用的 error 三個外層欄位,本文查證當天沒有在那幾頁看到對應的 schema 驗證旗標,response 裡的結構得自己解析再檢查。
plan.md、patch、review.json 是 Claude Code、Codex 或 Gemini CLI 官方定義的檔案格式嗎?
不是。這三個檔名與欄位是這篇文章自己設計的交接慣例,本文查證的三家文件都只講一次呼叫怎麼跑、輸出長什麼樣子,沒有定義工具之間該怎麼交接。Markdown、patch 與 JSON 對應的是規劃、執行、審查最自然的產出,讀者可以照自己的流程改檔名或欄位。
為什麼腳本裡每一支 CLI 呼叫都包了一層 timeout?
因為模型要跑多久沒有上限,而三家對「沒人能回答核准提示」的處理各寫各的:Claude Code 可以指定工具回答或直接拒絕,Codex 用 --ask-for-approval 控制什麼時候暫停等人核准,Gemini CLI 的 Plan Mode 文件寫它會停下來等你確認。腳本用 timeout 幫每一步設上限,超時就讓那一步失敗,不是讓整條管線無限期等下去。
三支 CLI 的結束代碼(exit code)代表的意義一樣嗎?
不一樣,而且能查到的詳細程度也不同。Gemini CLI 的無頭模式文件列出 0、1、42、53 四個結束代碼與各自的意義;本文這次讀到的 Claude Code 與 Codex 頁面只在個別旗標的說明裡提到失敗會用錯誤結束,沒有列出這樣的數字對照。串接時能穩定依賴的只有『退出碼是不是 0』,不要假設某個非零數字在三支工具之間代表同一種錯誤。
一定要照這篇的分工——Claude Code 規劃、Codex 執行、Gemini CLI 審查——嗎?
不用。這篇示範的是規劃、執行、審查三個階段搭配 plan.md、patch、review.json 的做法,哪一家 CLI 負責哪一階段可以互換,只要每一步用的是那支工具當天有效的非互動旗標,輸出也確實寫進約定好的交接檔即可。
多模型 AI 工作流教學:從拆任務到串接不同模型多模型 AI 工作流教學:從拆任務到串接不同模型這個系列教的是怎麼把一件工作拆開、交給合適的模型,再把結果接回同一條流程:判斷該不該拆、拆給誰,換供應商不改程式,設計便宜先試的路由與級聯,讓模型之間用結構化輸出交接資料,再到代理式工具怎麼分工、同一套工具怎麼給多個客戶端共用、Claude Code 與 Codex 怎麼搭本機模型,以及上線後怎麼追蹤與防護。一般使用者可以從判斷該不該拆的觀念讀起,已經會寫 Python 的人能直接進到換供應商、寫路由與交接資料的幾篇。閱讀全文
Claude Code|非互動執行與 JSON 輸出Claude Code|非互動執行與 JSON 輸出用單次指令、管線與結構化輸出建立腳本。claude -p 讓你把一次任務放進腳本,由程序輸入提示並接收結果。本篇會先取得文字輸出,再保存 JSON 結果,最後使用 JSON Schema 要求固定欄位。你會同時檢查退出碼與結果內容,避免把一份存在的輸出檔誤認為執行成功。閱讀全文
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
Claude Code、Codex 搭本機模型:兩種接法怎麼選
Claude Code 與 Codex 搭配本機模型有兩種接法:代理照常連雲端、把大量雜務交給腳本或 MCP 工具去問本機模型,或是把代理的模型整個換成本機模型。這篇用資料能不能出門、上下文開得夠不夠長、工作的類型三個問題幫你選,並對照 Ollama、LM Studio、Anthropic 與 OpenAI 的官方文件,分清楚本機權重、Ollama 的 cloud 標籤與供應商端點是三種不同的東西。
引用本文的文章
資料來源
- CLI reference查證日期:
- Non-interactive mode查證日期:
- Developer commands查證日期:
- Gemini CLI查證日期:
- Headless mode reference查證日期:
- Gemini CLI cheatsheet查證日期:
- Choose a permission mode查證日期:
- Plan Mode查證日期:
本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。