第 11 章
團隊協作、CI/CD 與雲端委派
Codex CLI 不只能在你的電腦上幫你寫程式,還能被接進團隊的「自動化生產線」(CI/CD),甚至把整包大工程外包到 OpenAI 的雲端背景默默跑完。
想像一下:第 10 章學的 codex exec,是你寫好一張紙條塞進機器、機器自己跑完交差。這一章更進一步——
- 第一台機器:把這台「自動小幫手」搬進 GitHub 工廠的生產線。每當有人開 Pull Request(改動提案),它自動幫你看一遍、抓 bug、甚至自己提修正。
- 第二件法寶:你在自己終端機敲一行指令,就能把任務「外包」到 OpenAI 雲端的一台臨時電腦上跑,跑完再把改動拉回你本機,你連終端機都不用離開。
這一章你會學會:
- 「老闆,每次有人交 PR,你幫我先審一遍。」(GitHub Action 自動 review)
- 「CI 測試掛了,你重現一次、找出最小的修法、開一個修正 PR 給我。」(autofix 自動修復)
- 「這個重構工程很大,你去雲端慢慢跑,跑好叫我。」(
codex cloud委派) - 「同一個任務你跑三種解法,我挑最好的。」(
--attemptsbest-of-N)
重要提醒
這一章橫跨「CLI(終端)」與「Cloud / GitHub(雲端)」兩個世界。本書主軸是 CLI,所以凡是雲端/GitHub 才有的功能,我都會明講「這是 cloud / GitHub 的功能,不是你終端機打的 CLI 指令」,別搞混了。
時效鐵則
Codex CLI 更新非常快(本書對照版本 0.140.0,2026-06-15 釋出)。書裡每個逐字旗標、子指令、模型名稱,安裝後請務必用實機的 codex --help / codex cloud --help / codex exec --help 再核對一次,不要把書當成最後真相。
11.1 GitHub Action 一鍵接 CI(PR review / autofix)
先搞懂:為什麼 CI 不要自己裝 CLI
你可能會想:「我在第 2 章學會了安裝 CLI,那 GitHub Actions 裡是不是也自己 npm install 一下就好?」
官方的答案是:別這樣。CI 場景請改用官方的 GitHub Action。
官方明確建議用 openai/codex-action@v1,而不是在 runner(GitHub 幫你跑流程的那台臨時機器)裡自己安裝並認證 CLI。原因官方原文是:這個 Action 會幫你
「reduce API key exposure by installing Codex, starting a Responses API proxy, and running Codex with a configurable safety strategy.」
白話說就是三件好事:
- 幫你裝好 Codex——你不用自己寫安裝步驟。
- 自己起一個 Responses API proxy——你的 API key 不會直接暴露在跑 Codex 的環境裡,降低外洩風險。
- 內建「安全策略」(safety strategy)——預設就幫你把權限收緊(細節見 11.2)。
一句話記住
CI 裡跑 Codex = 用 openai/codex-action@v1,不要手動裝 CLI。安全、省事、官方背書。
場景一:每次有人開 PR,自動幫你 code review
最常見的用法,就是「有人開新的 Pull Request → Codex 自動審查 → 把意見貼回 PR」。下面是官方提供的完整 workflow(逐字),你可以直接放進 repo 的 .github/workflows/ 目錄:
name: Perform a code review when a pull request is created.
on:
pull_request:
types: [opened]
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
persist-credentials: false
- name: Pre-fetch base and head refs for the PR
env:
PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
git fetch --no-tags origin \
"$PR_BASE_REF" \
"+refs/pull/$PR_NUMBER/head"
- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: |
This is PR #${{ github.event.pull_request.number }} for ${{ github.repository }}.
Review ONLY the changes introduced by the PR.
Suggest improvements, potential bugs, or issues.
Pull request title and body:
----
${{ github.event.pull_request.title }}
${{ github.event.pull_request.body }}
post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
permissions:
issues: write
pull-requests: write
steps:
- name: Report Codex feedback
uses: actions/github-script@v7
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
with:
github-token: ${{ github.token }}
script: |
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: process.env.CODEX_FINAL_MESSAGE,
});
看不懂沒關係,抓住三個重點就好:
codexjob 只給contents: read——讓 Codex 只能讀,不能改你的 repo。它讀完 PR 把審查意見輸出。- 它輸出
final-message——Codexexec跑完的最終訊息,被接到 job 的 output 上。 post_feedback是另一個 job——拿到上一步的final_message,才用「能寫」的權限把意見貼成 PR 留言。
為什麼拆成兩個 job?
因為「跑 Codex(拿 API key)」和「寫 GitHub(留言)」的權限被刻意分開。API key 只給讀的那個 job,降低風險。這個「最小權限」思路是 11.2 的核心。
Action 的常用輸入參數
openai/codex-action@v1 在 with: 底下可以填很多參數。下面是官方逐字列出的常用幾項(預設值多為空字串 ""):
| 參數 | 說明(官方節錄) |
|---|---|
prompt | 內聯指令文字(與 prompt-file 二選一) |
prompt-file | 含 prompt 的 repo 檔案路徑(Markdown / 文字) |
openai-api-key | 用 OpenAI 時,啟動 Responses API proxy 用的 secret |
model | agent 使用的模型 |
effort | reasoning effort(推理強度)等級 |
sandbox | workspace-write / read-only / danger-full-access |
working-directory | 傳給 codex exec --cd 的工作目錄 |
output-file | 把最終訊息寫檔(方便當 artifact 上傳) |
output-schema / output-schema-file | 約束最終輸出符合 JSON Schema(見第 10 章) |
codex-version | 要安裝的 @openai/codex 版本(預設最新) |
codex-args | 額外轉發給 codex exec 的參數 |
safety-strategy | 權限縮減策略,預設 drop-sudo(見 11.2) |
Action 的輸出只有一個關鍵:
final-message:codex exec回傳的最終訊息。你可以像上面範例那樣,映射到 job output 給下游步驟用。
場景二:CI 測試掛了,自動提修(autofix)
第二個經典用法是「自動修復」:當你原本的 CI workflow(例如跑測試)失敗時,觸發另一個 workflow,讓 Codex 重現失敗、找最小修法、開一個修正 PR。
官方 autofix 指南的設計重點,是把工作拆成兩個權限分離的 job:
| Job | 權限 | 拿不拿 API key |
|---|---|---|
| generate_fix(產生修正) | 只給 contents: read | 拿 OPENAI_API_KEY |
| open_pr(開 PR) | 給 contents: write + pull-requests: write | 不拿 API key |
這樣設計的好處是:API key 永遠不會出現在「有寫入權限」的 job 裡。負責跑 Codex 的 job 只能讀,負責開 PR 的 job 雖然能寫卻碰不到 key。萬一哪個環節出包,key 也不會跟著寫權限一起外洩。
成敗怎麼判斷?官方範例不是只看退出碼,而是看「有沒有產出一個非空的修正檔(patch)」:
needs: generate_fix
if: needs.generate_fix.outputs.has_patch == 'true'
退出碼不是唯一真相(呼應第 10 章)
CI 判斷成敗,建議用「退出碼非零」加上「產出 artifact 是否存在」雙保險。官方 autofix 就是看「有沒有產出 patch 檔」來決定要不要開 PR,而不是只信退出碼。
autofix 的 prompt 通常寫得很窄:重現失敗(例如跑 npm test --silent)→ 找最小必要改動 → 只實作該修復 → 重跑測試驗證 → 不重構無關程式碼。範圍越窄,Codex 越不會「順手」改壞別的東西。
11.2 最小權限與安全策略(safety-strategy)
比喻:給機器人發識別證,但只發剛好夠用的那張
讓 AI 在 CI 裡自動跑,最怕兩件事:API key 外洩,以及 AI 權限太大、闖禍範圍太廣。openai/codex-action@v1 的 safety-strategy 參數,就是用來控制「給這個機器人多大的活動範圍」。
safety-strategy 的四個值(官方逐字):
| 值 | 行為 | 適合誰 |
|---|---|---|
drop-sudo(預設) | 移除 sudo(超級使用者)權限 | 一般 CI ✅ |
read-only | 唯讀,不准改任何東西 | 純 review / 分析 ✅ |
unprivileged-user | 以指定的非特權帳號執行(搭配 codex-user) | 要更嚴格隔離時 |
unsafe | 不做任何權限縮減,以 runner 預設使用者(通常有 sudo)執行 | ⚠️ 只在你完全清楚風險時 |
重要提醒(Windows runner 限制)
GitHub 託管的 Windows runner 沒有受支援的 sandbox,所以 safety-strategy 在 Windows 上只能用 unsafe,指定其他值會直接失敗。官方原文:「GitHub-hosted Windows runners lack a supported sandbox. Set safety-strategy: unsafe.」如果你的 CI 跑在 Linux(ubuntu-latest),就用預設的 drop-sudo 即可。
三條最小權限鐵律
把 11.1 的兩個範例濃縮成可以照抄的原則:
- 跑 Codex 的 job 只給「讀」——
permissions: contents: read。讓 AI 看得到 code,但改不了。 - 「寫 repo / 開 PR」拆成另一個 job——把寫入權限隔離出去。
- API key 只給「讀」的 job——確保 credentials 永遠不落在有寫權限的 job 裡。
誰可以觸發 workflow?
Action 還有 allow-users / allow-bots / allow-bot-users 等輸入,用來控制「誰留言或開 PR 才會啟動 Codex」。預設只允許對 repo 有 write 權限的協作者觸發,避免任何路人留一句話就啟動你的 AI(燒你的 API 額度)。確切參數與預設值以實機與 Action repo 為準。
留意:PR 標題、留言、AGENTS.md 都算「不可信輸入」
官方另外為 openai/codex-action 寫了一份專門的安全指引,特別提醒一件新手很容易漏想的事:「不可信輸入」不是只有留言區那句 @codex review。PR 標題、PR 內文(包括刻意藏在 HTML 註解裡的字)、commit message、甚至改動範圍內的那份 AGENTS.md 本身、留言裡貼的截圖,全部都算——任何有心人能編輯的欄位,理論上都可能夾帶一段偽裝成指令的文字,企圖騙 Codex 執行不該做的事。這種手法叫 prompt injection(把惡意指令偽裝成普通內容,混進 AI 會讀到的資料裡)。第 5 章提過 NVIDIA 紅隊示範的「偽造 AGENTS.md」攻擊,其實就是同一套手法在另一個場景的翻版。
指引落到實作,主要是三個具體動作:
- 不可信的字串一定要用環境變數傳,並加引號——分支名稱、PR 標題、留言內容如果要塞進 shell 指令,直接字串內插等於開了一個 shell injection(利用沒消毒過的輸入夾帶額外指令)的後門。
- 把
openai/codex-action放在 job 的最後一步——避免 Codex 跑完之後,後面的步驟不小心執行了它剛動過、還沒人審查的程式碼或設定。 - API key 不要設成整個 job 共用的環境變數——同個 job 裡如果還跑了其他不可信的測試腳本或 build hook,這些腳本理論上讀得到 job 層級的環境變數。用 Action 自己的
openai-api-key輸入(走它起的 proxy)才是正確姿勢,不要用裸的env:全域曝露金鑰。
進階:讓 CI runner「保持登入」(搬 auth.json 的規矩)
如果你有特殊需求,不走 Action 而是自己在持久型(self-hosted)runner 上維持 Codex 登入,官方有一套搬運 auth.json(憑證檔,見第 3 章)的規矩。重點是這條鐵律:
官方原文:「Do not overwrite a persistent runner's refreshed file from the original seed on every run.」
(不要每次 run 都用原始種子檔,去覆蓋持久 runner 上已經自動 refresh 過的憑證檔。)
簡單說:
- 持久 runner:只在
auth.json缺檔時才「種」一次,之後讓 Codex 自己 refresh,job 之間保留 refresh 後的檔案——別每次都覆蓋回舊種子。 - 短命(ephemeral)runner:從安全儲存還原
auth.json→ 跑codex exec --json "your-prompt"→ 把 refresh 後的檔案寫回安全儲存。 - CI 場景官方建議明確設
cli_auth_credentials_store = "file",這樣auth.json才能被搬運 / 注入。
重要提醒
auth.json 等同密碼,禁止 commit、貼工單、寫進 log,搬運時用 chmod 600,只放在你信得過的私有基礎設施。詳見第 3 章。
官方參考
11.3 從 CLI 委派雲端任務(codex cloud)
先分清楚四個「Codex」與一個容易搞混的指令
Codex 其實有四個「介面」(surface):CLI(終端)、IDE 擴充、Cloud / Web(背景任務)、ChatGPT 內 / GitHub @codex。它們共用同一個帳號,差別只在「程式跑在哪」。本書講的是 CLI,但 CLI 有個很方便的能力——它可以當成委派任務到雲端的入口。
官方原文形容 CLI 能:
「launch a Codex Cloud task, choose environments, and apply the resulting diffs without leaving your terminal」
(啟動一個 Codex Cloud 任務、選執行環境、套用跑出來的 diff——全程不用離開你的終端機。)
最容易搞混的一個字
codex exec(本機非互動,第 10 章)和 codex cloud exec(委派到雲端)是兩個不同指令,只差一個 cloud。前者在你電腦上跑,後者送到 OpenAI 雲端跑。看清楚再敲。
登入方式會決定你摸不摸得到雲端功能
第 3 章教過 Codex 有兩種登入路:瀏覽器登入 ChatGPT 帳號(含 headless 環境用的裝置碼流程),以及 codex login --api-key 純 API key 認證。這裡先提醒一個很多人踩過的認知落差:純 API key 登入沒有 ChatGPT workspace 存取權,本節教的 codex cloud,以及11.4的雲端 @codex review、Automatic reviews,全部都用不了——API key 模式只能跑本機的 App / CLI / IDE 擴充功能。CI 裡用 API key 完全沒問題(那正是 11.1、11.2 的場景),但如果你想要「團隊在 GitHub 上跟 Codex 互動」這條路,得先有人用 ChatGPT 帳號完整跑過一次 GitHub 整合設定,兩件事不能互相取代。
雲端任務不是只能從 CLI 丟:常見的五個入口
本節主講「從 CLI 丟任務上雲端」,但雲端任務池其實是共通的——不管從哪個入口丟進去,最後都在同一份任務清單裡,用同一份帳號額度。除了 codex cloud exec,團隊裡常見的入口還有:
- GitHub:在 PR 或 issue 留言
@codex(11.4 細講); - Slack:在頻道裡標記
@Codex,例如「@Codex fix the null pointer in the payment processor — see the stack trace above」,或指定 repo:「@Codex implement the feature described here in myorg/backend-api」; - Linear:在 issue 留言
@Codex,或直接把 issue 指派給 Codex 帳號; - Codex 網頁介面(chatgpt.com/codex):直接在網頁上開新任務。
這五個入口的差別只在「你人當下習慣待在哪裡打字」——PM 可能習慣在 Linear 留言指派,工程師習慣留在終端機或 PR 留言區。知道任務池是共通的之後,挑順手的那個用就好,不用每次都堅持切回終端機。
多 repo 團隊:Linear 怎麼決定丟去哪個環境?
用 Linear 觸發時,Codex 判斷「這個任務該用哪個雲端環境(也就是對應哪個 repo)」是照順序找:留言裡有沒有明講 repo → Linear 依上下文建議 → repo map 裡有沒有相符的環境 → 最近用過的環境 → 都沒有就直接報錯。團隊如果不只一個 repo,記得先把常用的都建好對應的 Cloud Environment,不然容易派錯地方或直接失敗。
企業版可以關掉「自動貼出結果」
如果團隊用的是企業方案,管理員可以把「Codex 任務完成後直接把答案貼回 Slack 頻道」這個自動行為關掉,改成需要有人先審過才對外曝光。頻道裡如果有機敏資訊、不希望 AI 產出的東西未經人看就公開,這個開關值得先跟管理員確認一下。
委派指令速查
| 指令 | 作用(官方原文) |
|---|---|
codex cloud | 開啟互動 picker:瀏覽進行中或已完成的雲端任務,並把改動 apply 回本機專案 |
codex cloud exec --env ENV_ID "Summarize open bugs" | 直接啟動一個雲端任務(指定環境 + 指令) |
codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs" | 加 --attempts(範圍 1–4),要 Codex 雲端產生多組解法 |
--env ENV_ID 裡的 Environment ID(環境 ID) 來自你的 Codex cloud 設定。你可以用互動 picker,或到 web dashboard(chatgpt.com/codex)查 ID 值。認證直接沿用 CLI 既有的登入憑證,不用再登一次。
把雲端 diff 套回本機:codex apply
互動 picker 是最保險的作法,但如果你已經知道任務的 Task ID(雲端任務的唯一編號,picker 清單或 web dashboard 都看得到),也可以直接下指令:
codex apply <TASK_ID> # 把該任務最新的 diff 套用回本機工作樹(別名 codex a)
codex cloud diff <TASK_ID> # 只看 diff 內容,先不套用
codex apply 底層是跑 git apply,也就繼承了它的老規矩:如果你本機的檔案跟雲端任務開始時的版本已經不一樣(例如你自己也手動改過同一份檔案),套用會直接失敗、回傳非零結束碼,不會幫你自動合併。遇到這種情況,先 codex cloud diff <TASK_ID> 看一眼雲端到底改了什麼,再決定要自己處理衝突還是重新描述一次讓 Codex 重跑。
--attempts = best-of-N(挑最好的)
同一個任務讓 Codex 跑 2~4 種不同解法,你再挑最滿意的那個。重要或難搞的任務值得這樣花,簡單任務沒必要。範圍是 1–4。
平行跑多個任務,小心套用時互相打架
常見情境:你同時開了兩個 codex cloud exec 任務,剛好都動到同一份檔案(例如 CHANGELOG.md)。第一個先 apply/合併之後,第二個任務的 diff 再套用時多半會衝突。--attempts 產生的多組解法也是同樣道理——它們往往是「各自都成立、但彼此不相容」的不同寫法,不能全部合併,還是得由你挑一個。盡量讓平行任務各自動到不同檔案/目錄;衝突真的發生時,把兩邊任務的意圖一起寫進新的 prompt 交給 Codex 判斷怎麼合併,會比手動理 conflict marker 有效率。
要用得起 cloud,先有方案
官方說明:「Your Plus, Pro, Business, Edu, or Enterprise plan includes Codex」——也就是 Plus / Pro / Business / Edu / Enterprise 方案內含 Codex(部分 Enterprise workspace 需要 admin 先設定才能用)。
⚠️ 雲端委派的兩個社群來源指令(請實機確認)
下面這幾個查任務狀態的子指令,出現在 GitHub issue 討論裡,官方 CLI features 頁並未逐字列出,屬於低信心。使用前請務必用 codex cloud --help 在你的版本上確認:
codex cloud list --json # 列出一般 cloud 任務
codex cloud list --env ENV_ID --json # 限定某環境
codex cloud status <task_id> # 查特定任務狀態
已知限制(社群 issue #23853)
Codex Web 的「Code reviews」分頁任務,目前無法從 CLI 列出。codex cloud list 只列一般 cloud 任務;若你已經知道 task ID,才能用 codex cloud status <task_id> 查。此為 issue 討論內容,非官方正式聲明,以實機為準。
以實機為準
上面三個 codex cloud list / status 子指令,官方 CLI features 頁並未逐字列出,屬於較低信心的資訊。前面提過的 codex apply / codex cloud diff 套用 diff 指令,文件與社群交叉核對後可信度稍高,但不管哪一組,指令旗標、別名、確切輸出格式都以你實機的 codex cloud --help / codex apply --help 為準,不要照書寫死。
雲端執行環境(environment)的觀念與一個大坑
當你把任務丟上雲端,Codex 會在一台臨時容器裡:建立 container → checkout 你的 repo → 跑 setup script(裝依賴)→ (resume 快取時)跑 maintenance script → 套用網路設定 → 開始做事。
新手最該記住的兩個雷:
大坑一:setup 裡的 export 不會帶進 agent 階段
官方原文:「Setup scripts run in a separate Bash session from the agent, so commands like export do not persist into the agent phase.」也就是說,你在 setup script 寫 export MY_VAR=...,等 Codex 真正開始改 code 時,那個變數已經消失了。若只是非敏感設定,才可評估寫進 ~/.bashrc 或環境設定的「Environment variables」欄;token、密碼與私鑰不要為了跨階段可見而從 Secrets 降級出去。
大坑二:agent 階段預設「沒有網路」
官方原文:「By default, Codex blocks internet access during the agent phase.」setup script 裝依賴時有網路,但等 Codex 開始改 code 的 agent 階段,網路預設是關的。要連網得在環境設定裡明確開(並承擔 prompt injection、secret 外洩等風險)。
要連網?三檔白名單選一個
環境設定裡把網路存取切成 On 之後,還能再用網域白名單(allowlist)收緊,官方給三種預設:None(空白,自己一條條加)、Common dependencies(常見套件來源的預設清單,例如 npm、PyPI 這類登記處)、All(不限)。所有對外流量都會經過 Codex 起的 HTTP/HTTPS proxy,不是容器直接連外網。能不開就不開;真的要開,優先選 Common dependencies,別一步到位選 All。
順帶兩個觀念:
- Secrets vs 環境變數:Secrets 只有 setup script 看得到,agent 階段開始前會被移除;一般環境變數則整個任務都看得到。敏感的東西放 Secrets。
- 容器快取最長 12 小時:改了 setup / maintenance script、環境變數或 secrets,快取會自動失效。
真實踩雷:想在 agent 階段用 PAT 做 git push,結果失敗
社群回報過一個很容易誤踩的情境:把 personal access token(PAT,個人存取權杖)設成 Secrets,指望雲端任務能拿它去 git push 或處理 merge conflict,結果 setup script 一跑完,agent 階段就完全讀不到那個 token 了——因為前面講過,Secrets 設計上本來就只給 setup script 用,agent 階段開始前會被清除,這不是 bug,是設計如此。
排除法有三種:
- 不要把 Secret 改寫到
~/.git-credentials或一般環境變數交給 agent;agent、它啟動的命令與 repo 控制的腳本都可能讀到 PAT。 - 能從 PR 發起時,選擇權限已限定在該 repo/PR 的流程;先確認實際權限範圍,不要把它當成萬用 push 權限。
- 把 push 留給人工,或留給獨立、最小權限的 CI 步驟;若做不到,就讓雲端 agent 只提出 diff 與說明。
重點不是想辦法把 PAT 帶進 agent 階段,而是把「分析與修改」和「推送」拆開。別假設 Secrets 設好,agent 階段就能一路用到底。
這些 environment 設定在哪改?
在 Codex 的 web 設定頁(chatgpt.com/codex)管理,不是你終端機打的 CLI 指令。這屬於 Cloud 的功能,CLI 只是把任務送進去而已。
11.4 本機 /review vs 雲端 @codex review 與團隊 review 準則
兩條獨立的 review 路徑,別搞混
Codex 有兩種「幫你 code review」的方式,走的是完全不同的路:
本機 /review | 雲端 @codex review | |
|---|---|---|
| 在哪觸發 | CLI session 內,輸入 /review | GitHub 的 PR / issue 留言 |
| 跑在哪 | 你的電腦(本機) | OpenAI 雲端 |
| 怎麼用 | 互動式 picker(選清單,不是旗標) | 在留言區打 @codex review |
| 結果去哪 | 印在你終端機,不動工作樹 | 貼成 GitHub code review |
重要提醒
/review 前面有斜線,是 CLI session 內的 slash 指令;@codex review 前面有小老鼠,是 GitHub 留言觸發雲端任務。一個本機、一個雲端,別混用。
本機 /review:在終端機裡先自審一遍
在 CLI session 裡輸入 /review,會啟動一個專責的 reviewer,給你幾個互動選項(picker,不是命令列旗標):
- Review against a base branch——比對你的本地 branch 和它的 upstream merge base
- Review uncommitted changes——檢查 staged / unstaged / untracked 的變更
- Review a commit——分析某一個 commit 的改動
- Custom review instructions——自訂審查重點(例:「Focus on accessibility regressions」聚焦無障礙退步)
本機 review「reads the diff you select and reports prioritized, actionable findings without touching your working tree」——只讀你選的 diff、給出排序後的可行建議,不會動你的工作樹。很安全,適合 push 前自己先過一遍。
重要提醒
網路上有些第三方文章宣稱有 codex review --base <branch>、--pr NUMBER、--diff HEAD~1、--uncommitted、--commit <sha> 之類的命令列旗標。官方 CLI features 頁只記載互動式的 /review,並未列這些旗標。 是否真有 codex review 子指令旗標,請以你安裝版本的 codex review --help / codex --help 為準,不要照那些文章寫死。
雲端 @codex review:在 GitHub PR 上喊它來審
以下屬於 Cloud / GitHub 面向,不是你終端機打的 CLI 指令——但和「委派任務」高度相關,所以一併講清楚。
在 PR 或 issue 的留言區打這些(逐字):
| 觸發留言 | 作用 |
|---|---|
@codex review | 要求一次 code review |
@codex review for [focus area] | 聚焦某面向(例:@codex review for security regressions) |
@codex fix the P1 issue | 要求修正已發現的問題 |
@codex [其他任務] | 啟動與 review 無關的一般雲端任務 |
留言送出後,Codex 通常會先回一個 👀(眼睛)表情,代表「收到了,我在看」;實際的審查意見要再等一下才會貼出來——別看到沒有立刻跳出長篇留言,就以為沒觸發成功。
Codex 會分析 PR 的 diff,貼出 GitHub code review,把問題標成 P0 / P1(P0 最嚴重)。有權限時,還能把修正直接 push 回 branch。
你也可以在設定裡開啟 Automatic reviews(自動審查),這樣每次有人開新 PR 都自動觸發,不必每次手動留 @codex review。
@codex review 留言完全沒反應?照這個順序排查
- 先確認在 Codex 設定裡,對「這個 repo」個別開啟了 Code review 開關——這是 repo 層級各自獨立的開關,不是帳號整體打開一次就好。
- 確認這個 repo 本身已經完成 Codex cloud 的環境設定;不是每個你連結過的 repo 都自動具備雲端能力。
- 觸發字必須精確是
@codex review,寫法不對(漏字、順序顛倒)不保證命中。 - 以上都確認過還是沒反應:社群回報過一個有效的排除法,到 ChatGPT 帳號設定把 GitHub 整合先斷開再重新連接,repo 授權範圍先切成「all repos」再切回你要的清單,重新整合後通常會恢復正常。這是社群驗證有效的 workaround,不是官方保證的修法。
- 如果走的是
openai/codex-action(Action 觸發而非留言觸發),GitHub 只顯示「Script exited with code 1」、沒有更多資訊:先確認codex-version有沒有釘選版本、AGENTS.md有沒有語法問題,必要時用output-file把完整 transcript 存成 artifact 幫助除錯,不要只盯著final-message看。
用 AGENTS.md 訂團隊的 review 準則(交叉引用第 5 章)
這是團隊協作最實用的一招:把你們團隊的 review 紅線寫進 AGENTS.md,Codex review 時會自動遵守。官方逐字範例:
## Review guidelines
- Don't log PII.
- Verify that authentication middleware wraps every route.
關鍵機制:Codex 套用距離變更檔最近的那份 AGENTS.md。所以你可以在巢狀的子套件裡放更嚴格的專屬準則——例如某個處理金流的目錄,放一份要求更高的 AGENTS.md,只對那塊生效。
AGENTS.md 是 review 準則的單一真相源
同一份 AGENTS.md,本機 /review、雲端 @codex review、日常寫 code 都會讀。團隊規矩寫一次,到處生效。AGENTS.md 的完整探索順序、32 KiB 上限等細節,複習第 5 章。
11.5 🎓 高手進階
前面 11.1~11.4 已經夠你把 Codex 接進團隊與雲端跑起來了。這一節是給「已經跑起來、想再收緊一格」的人:讓 autofix 的最小權限更滴水不漏、讓 CI 的登入更省心、讓團隊規矩寫一次到處生效、讓多步驟 workflow 能接力共享狀態、讓本機除錯不用每次陪 CI 跑一輪。看不懂可以先跳過,不影響你用前面的內容。
⚠️ 分界先講清楚: 本節只談團隊協作與雲端委派這一面。至於「codex exec 的 --json 事件流怎麼用 jq 拆、退出碼怎麼三重判斷、cron / launchd 無人值守、git worktree 平行多開」這些管線深用與平行編排,屬於更硬的自動化主題,完整內容在第 14 章(多代理、平行工作流與自動化管線),這裡不重複,只在需要時指過去。
進階一:autofix 最小權限——把「key 永不碰寫權限」做到底
11.2 已經給了三條最小權限鐵律。這裡補上官方 autofix 指南的結構性細節,讓你知道為什麼要這樣切,以及切到什麼程度才算到位。
官方 autofix 的兩個 job,權限是這樣分的(逐字):
# Job 1:generate_fix —— 有 API key、但「只能讀」
permissions:
contents: read
# Job 2:open_pr —— 「能寫」、但完全碰不到 key
permissions:
contents: write
pull-requests: write
官方一句話總結這個設計的核心(逐字):
「The
OPENAI_API_KEYonly flows to the read-only job that doesn't modify the repository.」
(OPENAI_API_KEY只流進那個「唯讀、不會改 repo」的 job。)
兩個 job 之間怎麼把「修好的東西」傳過去?不是把 key 一起傳,而是只傳一份序列化的 patch(改動檔)。官方範例在 generate_fix job 裡這樣產 patch、這樣判斷有沒有東西要修(逐字):
# 在 generate_fix job 內:把 Codex 改出來的東西打成一個 patch 檔
git diff --binary HEAD > codex.patch
if [ -s codex.patch ]; then
echo "has_patch=true" >> "$GITHUB_OUTPUT"
fi
# open_pr job:只有「真的產出了非空 patch」才執行
needs: generate_fix
if: needs.generate_fix.outputs.has_patch == 'true'
流程是:generate_fix 把 codex.patch 當 artifact 上傳 → open_pr 下載、git apply、開 PR。credentials 永遠不會落在有 write 權限的 job 裡。
if [ -s codex.patch ] 在做什麼?
-s 是「檔案存在且非空」。所以這行的意思是「只有真的修出了東西(patch 不是空的)才繼續開 PR」。這正是第 10 章那條「退出碼不是唯一真相」的具體做法——不只看程式有沒有報錯,還看有沒有實際產出 artifact。
進階二:Action 還藏了哪些輸入(含一個萬用逃生口)
11.1 的表格列了最常用的幾個 with: 參數。下面補上官方逐字、但入門表沒收的進階輸入,團隊版 CI 常會用到:
| 輸入 | 官方逐字描述 | 預設 |
|---|---|---|
codex-args | "Extra arguments forwarded to codex exec. Accepts JSON arrays (["--flag", "value"]) or shell-style strings." | "" |
codex-home | "Directory to use as the Codex CLI home" | "" |
allow-users | "List of GitHub usernames who can trigger the action" | "" |
allow-bots | "Allow runs triggered by trusted GitHub bot accounts" | false |
allow-bot-users | "List of GitHub bot usernames that can bypass write-access check" | "" |
codex-args 是萬用逃生口
Action 本身只把一部分 codex exec 旗標包成輸入。萬一你要用的某個進階旗標 Action 沒暴露(例如 --json、--output-schema、-c key=value、resume),就用 codex-args 直接轉發給底層的 codex exec。它收「JSON 陣列」(["--flag", "value"])或「shell 風格字串」兩種寫法。這幾個進階旗標各自怎麼用,見第 14 章。
allow-users / allow-bots 控制「誰能觸發」
呼應 11.2 提過的——預設只有對 repo 有 write 權限的人能觸發 Codex,避免路人留一句話就燒你的 API 額度。團隊裡若要放行特定機器人帳號(例如某個自動化 bot),才用 allow-bots / allow-bot-users 點名放行。確切預設與行為以實機與 Action repo 為準。
進階三:讓 CI「保持登入」的搬檔規矩(深一層)
11.2 末尾講過「持久 runner 別每次覆蓋 refresh 過的 auth.json」這條鐵律。這裡把兩種 runner 的標準動作整理成可照抄的口訣:
- 持久(self-hosted)runner:只在
auth.json缺檔時才「種」一次種子檔;之後讓 Codex 自己 refresh,job 之間保留 refresh 後的版本。絕不每次 run 都拿原始種子覆蓋回去(會把已 refresh 的新憑證洗掉)。 - 短命(ephemeral)runner:每次 job 開始時從安全儲存還原
auth.json→ 跑codex exec --json "your-prompt"→ 把 refresh 後的檔案寫回安全儲存,給下次用。 - 兩者共通:CI 場景官方建議明確設
cli_auth_credentials_store = "file",這樣auth.json才能被搬運 / 注入。
auth.json 等同密碼
禁止 commit、貼工單、寫進 log;搬運時 chmod 600,只放在你信得過的私有基礎設施。詳見第 3 章。
以官方頁為準的一點
官方 openai/codex-action@v1 內部也有一套把憑證(例如 base64 編碼的 auth.json)傳進去的機制,但官方文件未逐字公開這段細節。若你要走「Action + 自帶登入憑證」這條路,確切做法請讀 Action repo 的 action.yml 原始碼,別照社群文章寫死。
進階四:用 AGENTS.md 當團隊規矩的「單一真相源」
11.4 已經教過把 review 準則寫進 AGENTS.md。這裡點出它在團隊協作上真正值錢的兩個性質:
- 就近生效(nearest-file): Codex 套用距離變更檔最近的那份
AGENTS.md。所以你可以在 repo 根目錄放一份通用準則,再在某個敏感子目錄(例如處理金流、處理個資的資料夾)放一份更嚴格的專屬AGENTS.md,只對那塊生效。團隊不必把所有規矩塞進同一份檔。 - 一處寫、處處讀: 同一份
AGENTS.md,本機/review、雲端@codex review、日常寫 code 都會讀。團隊規矩寫一次,三條路徑同步遵守,不會「本機審得嚴、雲端審得鬆」。
想把規矩變成「擋得住的閘門」?
AGENTS.md 是「給 Codex 看的準則」,屬於軟約束(Codex 盡量遵守,但不保證 100%)。如果你要的是「碰到危險指令就機械式擋下」(例如禁止 git push、禁止改測試檔),Codex 有更硬的對應物——官方的 hooks(PreToolUse 事件回 permissionDecision: "deny")。那是把「文字守則」升級成「不可繞過的閘門」,完整講法在第 14 章。
進階五:用 codex-home 讓多個 Action 步驟接力,不必每次重建 context
11.1 的表格提過 codex-home 這個輸入,官方描述是「Directory to use as the Codex CLI home」(指定 Codex CLI 的家目錄要用哪個路徑)。平常不太起眼,但在「一個 workflow 分好幾步、每步都呼叫一次 openai/codex-action」的場景,它是很好用的接力棒:把多次呼叫都指到同一個路徑,前一步 Codex 留下的東西(例如一份規劃檔、或它連過的 MCP server 設定)就能延續到下一步,不必每次重新建立 context。典型用法是「先生成計畫、再照計畫實作」的兩階段 workflow:
- uses: openai/codex-action@v1
with:
codex-home: /tmp/codex-shared
prompt: "分析這個 issue,把實作計畫寫進 PLAN.md,先別動手改程式碼。"
- uses: openai/codex-action@v1
with:
codex-home: /tmp/codex-shared
prompt: "照 PLAN.md 的計畫實作,完成後跑一次測試。"
一句話記
codex-home 給一樣的路徑 = 狀態延續;不設或設不同路徑 = 每一步都是全新的 Codex,互相不知道對方做過什麼。
進階六:把 prompt 存成檔案進版控,本機也能重放同一套 CI 邏輯
CI 裡的 prompt 如果直接寫死在 workflow yaml 裡,每次想調整一個用詞都要動 yaml、還得等一次 CI 才知道效果,不太划算。更好的作法是把常用 prompt 存成獨立檔案(例如 .github/codex/prompts/pr-review.md),連同 --output-schema 要用的 JSON Schema 檔(例如 .github/codex/schemas/review.json)一起進版控,workflow 改成指向這些檔案:
- uses: openai/codex-action@v1
with:
prompt-file: .github/codex/prompts/pr-review.md
output-schema-file: .github/codex/schemas/review.json
好處是本機除錯可以直接重放同一套邏輯,不必每次改個用詞就要動 workflow、等 CI 跑完才知道效果。用第 10 章教過的 - 哨符從檔案餵 prompt、--output-schema 指到同一份 schema 檔即可:
codex exec - --output-schema ./.github/codex/schemas/review.json < ./.github/codex/prompts/pr-review.md
這樣本機測出來的行為,跟 CI 上跑的是同一套邏輯,除錯不用再靠「改 yaml → push → 等 CI」這種慢迴圈。
進階七:CI 用的 profile,照「用途」命名,不要照人名
第 8 章教過 profile 是切換設定情境的獨立 overlay 檔。放進 CI 情境時有個實務上很好用的慣例:用「用途」命名,不要用人名或團隊名——例如建立 ci、fast、deep、review 這樣的 profile,而不是 alice-profile 或 frontend-team。原因是 CI 的取捨跟人的日常互動取捨方向相反:CI 通常「可以等、但要省」,適合搭配較便宜的模型、較低的 model_reasoning_effort;日常互動要的是「快、準」,取捨完全不同。用途命名讓任何人接手 CI 設定時,看名字就知道這個 profile 是為了什麼權衡而存在,不用去猜是哪個人的個人偏好。一個 CI 專用 profile 大致長這樣(完整鍵位說明見第 8 章、第 15 章的成本旋鈕):
# ~/.codex/ci.config.toml
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
tool_output_token_limit = 8000
呼叫方式一樣是 codex exec --profile ci "..."。
延伸認識:Codex Security(原代號 Aardvark)——相關但不是同一條賽道
如果你想找的是「幫我掃這個 repo 有沒有資安漏洞」,OpenAI 另外有一個獨立的安全審查 agent,官方名稱是 Codex Security(開發代號 Aardvark,2026 年 3 月上線)。運作方式跟本章教的 GitHub Action / cloud review 不太一樣:它會先替 repo 建一份「威脅模型」(這個系統在做什麼、信任邊界在哪、暴露面有哪些),找到看起來有意義的漏洞後,還會在沙箱裡實際驗證一次「這個漏洞真的能被利用嗎」,最後才產出修補建議——比起「看 diff 抓問題」的一般 code review,這更接近資安研究員的工作模式。
定位提醒
Codex Security 是獨立產品線,不是 openai/codex-action 的內建功能,也不是本章講的 @codex review,更不會取代滲透測試或 DAST(動態應用程式安全測試)工具。適合當成 PR 審查之外再多一層的過濾網,而不是唯一的安全把關。細節與是否已對你的方案開放,請查官方最新公告。
11.6 小結
走到這裡,你已經把單機的 Codex CLI,接進了團隊與雲端:
- CI 自動化用官方
openai/codex-action@v1,不要自己裝 CLI——它幫你裝、起 proxy、收緊權限;PR 標題、留言、AGENTS.md都算「不可信輸入」,小心 prompt injection。 - 最小權限是鐵律:跑 Codex 的 job 只給讀、API key 只給讀的 job、寫入拆成另一個 job;
safety-strategy預設drop-sudo,Windows runner 只能unsafe。 - 雲端委派入口不只 CLI,GitHub / Slack / Linear / 網頁都能丟任務進同一個任務池;
codex cloud exec --env ID、--attempts 1–4挑最好的解法、codex apply <TASK_ID>套回本機;記住幾個大坑——setup 的export不持久、agent 階段預設沒網路、Secrets 過了 setup 就消失。 - 兩條 review 路徑別搞混:本機
/review(slash、互動、不動工作樹)vs 雲端@codex review(GitHub 留言、先回 👀 再貼 P0/P1);團隊準則統一寫進AGENTS.md。 - 登入方式決定摸不摸得到雲端功能:純 API key 登入沒有 ChatGPT workspace 存取權,用不了
codex cloud、@codex review、自動審查這一整組團隊功能。
動手試試
- (需 GitHub repo) 把 11.1 的 PR review workflow 放進你 repo 的
.github/workflows/,在 repo secrets 設好OPENAI_API_KEY,開一個小 PR,看 Codex 是否自動貼出 review。 - (本機) 在一個有未提交改動的專案裡跑
codex,輸入/review,選「Review uncommitted changes」,看它怎麼挑你的 diff、報告問題。 - (查指令) 跑
codex cloud --help,對照 11.3 的指令表,確認你安裝的版本實際支援哪些子指令與旗標。 - (查登入) 跑
codex login status,確認自己目前是用 ChatGPT 帳號還是 API key 登入——如果是 API key,記得本章教的雲端委派與 GitHub review 這兩塊都用不了。 - (查 apply) 跑
codex apply --help與codex cloud diff --help,對照 11.3 教的用法,確認你安裝的版本實際支援哪些旗標。
本章官方文件參考
- GitHub Action 文件:https://developers.openai.com/codex/github-action
- 官方 Action repo:https://github.com/openai/codex-action
- openai/codex-action 官方安全指引:https://github.com/openai/codex-action/blob/main/docs/security.md
- CI 自動修復指南:https://developers.openai.com/codex/guides/autofix-ci/
- CI/CD 維持登入(advanced):https://developers.openai.com/codex/auth/ci-cd-auth
- Authentication(登入與 API key):https://developers.openai.com/codex/auth
- Codex Cloud 總覽:https://developers.openai.com/codex/cloud
- Cloud environments:https://developers.openai.com/codex/cloud/environments
- Agent internet access:https://developers.openai.com/codex/cloud/internet-access
- Codex CLI features(cloud / exec / review / model):https://developers.openai.com/codex/cli/features
- GitHub 整合與 code review:https://developers.openai.com/codex/integrations/github
- Codex 非互動模式(
codex exec):https://developers.openai.com/codex/noninteractive