Codex Cloud 怎麼用？從 GitHub Issue 到 PR 的背景交付循環

Codex Cloud 的重點是：不用把電腦留著，任務也能繼續跑

Codex Cloud 是 Codex 的背景執行環境。它會把 GitHub repository 放進隔離的 cloud environment，依照設定安裝依賴、checkout 指定的 branch 或 commit，讓 Codex 在裡面讀程式碼、改檔案、跑檢查，完成後回傳 summary 與 diff。

這和本地開一個 Codex session 的差異，在於工作不必綁著目前這台電腦。你可以把一個較長的任務交給 Codex Cloud，關掉本地 terminal，稍後再回來看結果；也可以讓本地 Codex 與 cloud Codex 分別處理不同 Issue，平行推進。

我這次實際跑下來，最有感的不是「多一個 coding agent」，而是它把原本散落在本地 terminal、GitHub Issue、PR review 和 merge 的動作，接成一條可以重複使用的交付循環：

flowchart TB
  A["GitHub Issue 定義任務"] --> B["切 bounded batch + branch + 驗收條件"]
  B --> C["使用 @codex 派送"]
  C --> D["Cloud container: setup、修改、測試"]
  D --> E["回傳 summary + diff"]
  E --> F["人工 Create / Update PR + review"]
  F --> G{"人是否接受結果？"}
  G -->|需要修正| C
  G -->|接受| H["merge main + 更新 tasks.md + 下一批"]
  H --> B

我會把這條流程定名為：

Agentic Delivery Loop

An issue-triggered, human-gated GitHub Flow.

中文就是：Agent 協作交付循環：由 Issue 觸發、經人工 PR 閘門的 GitHub Flow。如果只取一個業界比較容易理解的短名稱，我會用 Human-gated Agentic GitHub Flow。

先看重點

Codex Cloud 是背景 coding environment：任務交給雲端 container 跑，本地電腦不必一直開著。
GitHub 是交付中樞：repository 授權、Issue 派工、branch、PR、review 與 merge 都在同一條鏈上。
Environment 先設定好：runtime 版本、依賴、setup script、environment variables、secrets 與網路權限會直接影響任務能不能跑完。
Issue 要有邊界：不要只寫「把這個功能做好」，要寫清楚範圍、不要碰的地方、驗收條件與測試命令。
@codex 是委派入口：它啟動背景任務，但不代表會自動替你接受 diff 或合併 main。
PR 是人工閘門：Create／Update PR、Codex review、人工驗收與 merge 都保留決策權。
本地與 Cloud 可以並行：適合把長時間、可重現的任務交給 Cloud，本地則處理需要即時互動或未提交檔案的工作。
用量不要先當免費：這次介面看起來沒有明顯扣額度，但官方 pricing 仍把 cloud chats 納入 Codex／ChatGPT Work 的 shared usage。

先建立 GitHub 與 Codex Cloud 的連線

1. 在 ChatGPT 或 Codex 開啟專案

先從網頁或 Codex 進入要處理的專案，讓 Codex 取得 GitHub 授權。這一步不是把整個 GitHub 帳號無限制交出去，而是接著選擇哪些 repository 可以讓 Codex 存取。

官方的起手流程是：登入 Codex、連接 GitHub、選擇 Codex 可以存取的 repositories，再建立 cloud environment。

2. 授權允許的 GitHub repository

建議不要一開始把所有 repository 都開放。先選一個測試專案，確認下面幾件事：

Codex 能不能看到預期的 branch；
repository 裡的 AGENTS.md 是否包含正確的測試與 lint 指令；
setup script 是否會安裝齊依賴；
environment variables 與 secrets 是否分得正確；
task 完成後，你能不能看懂 summary、diff 與驗證結果。

Codex Cloud 的環境是針對 repository 建立的。它不是把你本地整個工作目錄直接搬上去，而是根據選定的 branch 或 commit 建立一個可執行的 cloud container。

建立 Codex Cloud environment

環境設定入口可以從 Codex environment settings 進入；你實際使用的建立頁面是 Create environment。

我會把設定分成五組。

設定	作用	實務建議
Repository	決定這個 environment 對哪個 repo 工作	一個環境先對應一個主要 repo，降低依賴與權限混亂
Package／runtime versions	固定 Python、Node.js 等版本	專案有版本要求時明確 pin，不要只依賴 universal image 的預設值
Environment variables	提供 setup 與 agent 執行期間需要的非敏感設定	放路徑、feature flag、測試模式等，不放 token
Secrets	給 setup script 使用的敏感值	不要假設 agent 階段仍看得到；官方文件說 secrets 會在 agent phase 前移除
Setup／maintenance script	安裝依賴、工具與 cache 恢復後的更新工作	讓 script 可重跑；不要只靠本地 shell 狀態

官方文件描述的執行順序是：Codex 建立 container、checkout repository 的 branch 或 commit、執行 setup script，接著依照網路設定啟動 agent，讓它用 terminal loop 修改程式碼與跑檢查。常見 package manager 如 npm、yarn、pnpm、pip、pipenv 與 poetry 可以走自動安裝；複雜專案再補自訂 setup script。

Setup script 與 maintenance script 要分清楚

setup script 是建立或重建環境時的初始化工作；maintenance script 則可以在 cached container 恢復時更新依賴或做維護。官方文件也提到 container cache 最長可維持 12 小時，改動 setup script、maintenance script、environment variables 或 secrets 時，cache 會失效。

這代表 setup script 不要寫成一次性的「只在我電腦跑過一次」腳本。它應該可以從乾淨 container 重新執行，並且在 branch 變更或 cache reset 後仍能建立出可測試的環境。

網路權限不要直接全開

Codex Cloud 的 setup script 本身可以使用網路安裝依賴；agent 階段則預設關閉網路。需要 agent 查文件、下載測試資料或操作外部服務時，才在 Agent internet access 裡開啟，並盡量用 domain allowlist 與 HTTP method 限制。

這個限制不是多餘的。Issue、網頁、第三方 dependency README 都可能包含 prompt injection。官方文件直接用「修理 GitHub Issue」的情境提醒：如果 agent 讀到不可信內容，內容可能誘導它外傳資料或執行不該執行的動作。

實務上我會採這個順序：

setup script 開網路，讓依賴安裝完成；
agent phase 預設關網路；
任務真的需要網路時，只開必要網域；
不把 production token 放進 agent 可以長時間讀取的環境；
對第三方 Issue、PR、README 與下載內容保持 prompt injection 警覺。

回到專案對話，啟動協作交付循環

環境開好以後，回到專案對話框，輸入這段 prompt：

codex cloud 環境開好了，請基於 issue 、branch 啟動一個協作交付循環，將我的需求開單，並指定 @codex 進行。我會驗收以後發送 PR ，再請你驗收規劃一下個任務。

接著專案會跳出 repository 授權流程。完成授權後，就可以把需求落到 GitHub Issue，再交給 cloud task 背景執行。

這裡要注意「基於 issue、branch」這個前提。Issue 不只是讓 agent 看到一句自然語言，它應該包含：

這一批要交付的範圍；
不要碰哪些檔案或模組；
驗收條件；
要跑哪些測試與 lint；
依賴哪一個 branch 或前置 PR；
完成後應該回報什麼。

一張好用的 Issue，至少可以整理成下面這個格式：

## 目標
一句話描述這一批要完成的結果。

## 範圍
- 要修改的模組或路徑
- 不處理的範圍

## 驗收條件
- 功能條件
- 錯誤處理
- 相容性或回歸條件

## 驗證命令
- lint
- unit test
- integration test 或 build

## 完成時回報
- 修改摘要
- 測試結果
- 尚未解決的問題

重點是不要直接把「把整個專案做好」丟給 agent，而是先在 Issue 裡寫清楚這一批的範圍、branch、驗收條件與回報格式。這樣 Codex Cloud 收到的是一個有邊界、可驗收、可回滾的工作單位。

Issue 派任務，PR 才是人工閘門

我目前使用的循環是：

GitHub Issue 定義任務
  → 切 bounded batch
  → `@codex` 派送
  → Codex Cloud 背景實作
  → 人工 Create／Update PR
  → Reviewer 驗收與追修
  → 合併 main
  → 勾選 tasks.md
  → 派下一批

這裡的自動化邊界要寫清楚：Issue 可以觸發 Codex 背景任務，Codex 會在 cloud environment 裡執行；但完成後是否 Create／Update PR、是否接受 diff、是否合併 main、何時派下一批，仍然由人決定。

所以 @codex 比較準確的定位是：Agent 委派與執行機制。它不是一個「Issue 送出後自動替你 merge」的機器人。

PR 階段怎麼請 Codex 審查

PR 建立後，可以使用 Codex GitHub code review。官方文件目前明確記載的操作包括：

手動 review

在 PR comment 輸入：

@codex review

也可以把審查焦點寫進去：

@codex review for issues in the database migration

Codex 會以 PR diff 與 repository context 做 review，官方文件表示一般 Code Review 主要標出 P0 與 P1 問題，讓 review comment 聚焦高優先級風險。

叫 Codex 直接修正

看到問題後，可以在同一個 PR 留下：

@codex fix the P1 issue

Codex 會以該 PR 為 context 開 cloud chat，並在有權限時把修正推回 branch。

Automatic reviews

如果想讓每個符合條件的新 PR 自動觸發 review，可以到 Codex code review settings 開啟 Automatic reviews。這和手動留言 @codex review 是兩種模式：前者是 repository 設定，後者是單次請求。

無論使用哪一種，都不應該把 Codex review 當成測試、branch protection 或 required human approval 的替代品。它是多一個高訊號 review pass，不是 merge policy 本身。

一張表看懂每一階段的責任

階段	Codex／雲端負責什麼	人要保留的決定
Issue／bounded batch	依 Issue 與 branch 執行一小批工作	決定批次邊界與檔案 ownership
Cloud task	建 container、跑 setup、改程式、測試、回報 diff	查看 log、判斷驗證是否可信
Create／Update PR	把可交付結果放到 GitHub review surface	決定何時值得開 PR、是否補充說明
Codex review	讀 diff、檢查 repository guidance、提出 P0／P1 風險	判斷建議是否成立，要求追修
Merge main	沒有自動替你決定產品正確性	人工驗收、合併與發布
下一批	依 tasks.md 與現況繼續處理	決定是否進入下一個 bounded batch

開發流程使用情境

Codex Cloud 不適合把所有工作都丟過去。比較適合的是：任務可以用 branch 隔離、環境可以重現、驗收條件可以寫清楚，而且不需要一直看著本地畫面。

情境一：CI failure 或測試回歸

這是最適合從 GitHub Issue 派給 Codex Cloud 的類型之一。

Issue 內容：貼上失敗的 job、錯誤訊息、重現命令與預期結果。
Cloud 任務：checkout branch、安裝依賴、重現 failure、修正程式、重新跑 CI 對應測試。
人要驗收：確認修正沒有只把測試刪掉或放寬條件，並看 diff 是否碰到不相關模組。
PR review：可以先用 @codex review for issues in the failing test path，再由人檢查根因是否真的解決。

這種任務的優點是輸入與輸出都比較清楚，Codex 不需要先理解整個產品，只要從一個可重現的錯誤開始往回追。

情境二：背景 feature 開發

例如要加一個 API endpoint、補一個後台頁面、替某個資料表加欄位，這類工作通常不需要本地電腦一直開著。

Issue 先寫清楚：API contract、資料欄位、權限邊界、錯誤回應、測試案例。
指定 branch：不要讓 Cloud task 直接和本地未提交工作共用同一個 branch。
設定 environment：確保 Node／Python、資料庫 client、測試工具與 build command 都能在 cloud container 裡跑。
完成後看三件事：summary 是否有說明實作方式、diff 是否符合範圍、測試是否真的執行成功。
PR 才交付：未經人工確認前，不把 cloud task 的結果直接視為可以進 main 的程式碼。

情境三：文件、測試與機械式整理

這類工作不一定困難，但很容易佔掉本地時間，適合讓 Cloud 背景處理。

補 API 文件與使用範例；
為既有 service 補 unit tests；
統一錯誤訊息、命名或 import 順序；
依現有程式碼更新 README；
找出過期設定與相關測試並提出修正。

這時 Issue 要特別限制範圍，避免 agent 把「更新文件」擴張成重寫整個架構。文件任務也要跑最基本的 link check、build 或測試，不要因為沒有 production code 就跳過驗證。

情境四：本地 Codex 與 Cloud Codex 平行工作

這是最容易提高吞吐量、也最容易撞車的用法。

適合的分工：

本地 Codex：處理需要看未提交檔案、即時討論、桌面工具或本機服務的任務；
Codex Cloud：處理乾淨 branch 上的背景重構、測試、CI failure 或文件工作；
人：維持 Issue、branch、PR 與檔案 ownership 的分配。

避免衝突的規則：

不要讓兩個 agent 同時寫同一組核心檔案；
每一個 Issue 指定明確 branch；
依賴前一批結果的任務，等前一個 PR merge 後再派；
如果兩個任務一定會改同一模組，改成串行，不要為了平行而平行；
merge 前看完整 diff，不要只看 agent 的文字摘要。

本地 Codex 與 Codex Cloud 可以一起用嗎？

可以，但要把任務切開。

一種方式是本地處理需要即時互動、未提交檔案、桌面工具或敏感環境的任務；Codex Cloud 則跑可以用乾淨 branch 重現的背景工作，例如補測試、批量重構、文件整理、CI failure 修正或一個已經寫清楚驗收條件的 Issue。

另一種方式是同一個 repository 開不同 Issue，但每一個 Issue 都指定不同 branch 與檔案 ownership。不要讓本地 Codex 和 Cloud Codex 同時修改同一個模組，最後才期待 Git 自己解決需求衝突；Git 可以合併文字差異，不能替你判斷兩個 agent 的設計決策哪一個才是對的。

實務規則很簡單：

一個 Issue 對應一個 bounded batch；
一個 batch 指定 branch、驗收條件與測試命令；
同一時間不要讓兩個 agent 擁有同一組核心檔案的寫入權；
先 merge 前置 batch，再派依賴它的下一批；
tasks.md 是進度索引，不是測試通過的替代品。

最後的工作定義

Codex Cloud 說明文件把它定位成可以從 web、GitHub、Linear 或 Slack 啟動的背景 coding task；GitHub 文件則把 PR review、@codex review、Automatic reviews 與 follow-up fix 分開描述。

放回這套實際流程，可以得到一個清楚的分工：

Issue／branch：定義這一批要交付什麼，以及在哪個分支工作；
@codex：委派與啟動 cloud agent；
Codex Cloud：在隔離環境執行、測試與回報 diff；
PR：讓結果進入可審查的交付面；
Codex review：補一輪高訊號風險檢查；
人：驗收、決定 merge，並決定下一批做什麼。

這就是我目前會採用的名稱：

Human-gated Agentic GitHub Flow

Issue 派出，Codex 背景執行，PR 由人把關，merge 之後再繼續下一批。