Codex Cloud 実践ガイド：GitHub タスクをクラウド Agent に渡して結果をレビューする

GitHub issue に「CI の webhook テストが失敗しているが、いまローカルで完全な環境を動かせない」と書かれています。Codex Cloud にクラウド上のリポジトリで修正を走らせ、最後に diff、テストログ、PR だけを受け取って確認したい場面です。

ここで大事なのは、「クラウドだから自動化が強い」という話ではありません。Cloud task は、ノート PC から切り離された、クリーンで再現しやすいリポジトリ環境で動くという点です。ローカルの未コミットファイル、ブラウザセッション、ローカルの .env は読みません。この境界は制約でもあり、便利な安全柵でもあります。

ここでは実際の流れに沿って、タスクを Cloud に置くべきか判断し、environment を設定し、prompt を書き、結果を確認し、最後に PR、ローカル引き戻し、または @codex review のどれを使うか決めます。

まず判断する：この要求は Cloud に置くか、ローカルに残すか

Local、Worktree、Cloud、SSH host の境界

Codex の各入口は別々の問題を解きます。単純な強弱関係ではありません。

シナリオ	向いている入口	理由	主な検証物
ローカルの小修正、未コミットファイルや localhost に依存	CLI / IDE / Local	ローカルの作業ツリー、ブラウザ、ローカルサービスに直接アクセスできる	ローカル diff、テスト出力
2〜3 個の独立した案を並行で試す	Codex app Worktree	Git 状態と依存ディレクトリを分離できる	worktree diff、review queue
GitHub issue、CI failure、ドキュメント更新、再現可能なリポジトリタスク	Codex Cloud	リモート checkout で、PC から離れても動く	Cloud summary、diff、PR
PR の二段階目レビュー	GitHub @codex review	PR diff に基づいて標準 review を投稿できる	GitHub review comments
プロジェクトが devbox や社内マシン上にある	Remote connection / SSH host	リモート host のファイル、shell、認証情報、ツールを使える	remote diff、terminal output

Cloud は「より強い Worktree」ではありません。Worktree は自分のマシン上で動き、Git ディレクトリだけを分けます。Cloud は configured cloud environment で、GitHub リポジトリを checkout し、リモートコンテナ内でタスクを実行します。

Cloud に向いているタスクには、だいたい 4 つの条件があります。目標が明確で、リポジトリ状態を再現でき、環境を script 化でき、Done when をコマンドや diff で検証できること。CI failure の修正、ドキュメントの補足、PR review の follow-up、単一モジュールへのテスト追加などです。

Cloud に渡すべきではないタスク

AI アシスタントには向いていても、ローカルから出さないほうがよいタスクがあります。

• ローカルの未コミットファイルに依存する：Cloud が見るのは、リモートリポジトリから checkout された状態だけです。
• ブラウザセッションやローカル dev server に依存する：Cloud コンテナは、Chrome、localhost、デスクトップアプリへ自動ではアクセスしません。
• agent phase で本番 secrets が必要になる：secrets を agent loop に渡す設計は避けるべきです。
• 範囲の曖昧な大規模リファクタリング：検証コマンドがなければ、不確実性を遠くへ移すだけです。
• プロダクト判断やチームの取捨選択が必要：Codex に分析を手伝わせることはできますが、方向性そのものを丸ごと書き換えさせるべきではありません。

私なら、最初の Cloud task は小さくします。「どのコマンドを走らせれば完了とわかるか」を書けないなら、そのタスクはまだ Cloud に渡す準備ができていません。

Cloud task を始める前に、environment でリポジトリを再現できるようにする

Cloud task の実行順序

Cloud task はおおむね次の順序で動きます。

1. リモート container を作成する。
2. 選択した branch または commit SHA を checkout する。
3. setup script を実行する。cached container を復元した場合は、maintenance script を実行できる。
4. ネットワークポリシーを適用する。
5. agent が terminal command loop でファイルを読み、コードを修正し、チェックを走らせ、検証を試みる。
6. answer、summary、diff を返す。続けて質問することも、PR を作ることもできる。

Cloud task が失敗する原因は、agent がコードを書けないことではない場合が多いです。environment がリポジトリを再現できていないのです。依存関係が入らない、テスト DB がない、lockfile と runtime が合わない、setup script がローカルにしかないファイルを前提にしている、という形で表に出ます。

setup script、maintenance script、cache

setup script の役割は、container を「checkout 直後」から「検証コマンドを実行できる状態」まで持っていくことです。最小例は短くてもかまいません。

pnpm install
pnpm run typecheck
pnpm test -- --runInBand

これは全プロジェクト共通のテンプレートではありません。Cloud environment には、依存関係のインストール方法、テスト環境の準備方法、問題を露出できるチェックの実行方法が必要だ、という意味です。

setup に含めることが多いものは次のとおりです。

• 依存関係、linter、formatter、typechecker、test tools をインストールする。
• テスト DB を初期化する、または安全なローカル設定の代替を生成する。
• private package のインストールに必要な一時認証を準備する。
• 永続させたい非機密値は、script 内の一時的な export ではなく environment settings に置く。

cache は依存関係を毎回入れ直す時間を減らします。ただし、排障時に見るべき層も 1 つ増えます。setup script、maintenance script、env vars、secrets を変えると cache は失効し、新しく実行されます。依存関係の挙動が急に変わったときは、cache reset も妥当な手です。

Secrets、環境変数、ネットワーク：誤解しやすい 3 つの境界

secrets と environment variables のライフサイクル

secrets と environment variables の違いは、名前ではなく「いつ見えるか」です。

設定項目	いつ使うか	入れるべきではないもの	検証すべき問い
environment variable	非機密の runtime 設定	token、秘密鍵、本番 connection string	agent が本当に読む必要があるか
secret	setup 段階で依存関係を取得する、または tool をインストールする	agent が直接読む必要のある値	setup 後に削除されているか
setup internet	依存関係のインストール、private package の取得	信頼できない script の任意実行	lockfile は安定しているか
agent internet access	タスクが公開 API やドキュメントへアクセスする必要がある	unrestricted な全ネットワーク	allowlist と method は最小か

secrets は setup 段階に向いています。たとえば private dependency を入れる、internal package を取得する、といった用途です。agent phase が始まる前に削除されるべきものです。つまり、agent がコード修正中に本番 token を読む必要がある Cloud task は設計しないほうが安全です。

environment variables は task 全体で残ります。NODE_ENV=test、公開 API base URL、feature flag など、非機密の値に向いています。

agent internet access は必要なときだけ開く

setup script は依存関係のインストールにネットワークを使えますが、agent phase はデフォルトでネットワークなしです。このデフォルトは重要です。agent が外部ページや API を読むと、リスクも変わるからです。

agent internet access をどうしても有効にするなら、保守的に設定します。

1. 全ネットワークを開かず、具体的な domain だけを allowlist する。
2. 可能なら HTTP methods を制限する。たとえば GET、HEAD、OPTIONS だけにする。
3. agent に機密ファイルを読ませたり、結合させたり、外部へ upload させたりしない。
4. ネットワークで確認すべき事実を明記し、agent に自由探索させない。

よくあるリスクは prompt injection、コードや secret の外部送信、悪意ある依存関係の download、license 問題です。「手間を 1 つ減らすため」に unrestricted network を開くのは、たいてい割に合いません。

Cloud への prompt は issue のように書く

そのまま使える prompt テンプレート

Cloud prompt は願いごとではなく、小さな GitHub issue のように書くべきです。目標、背景、範囲、環境、検証、停止条件を入れます。

Goal: Fix the failing webhook.test.ts test in GitHub Actions.
Context: The failure log is below; the relevant code is probably in src/webhooks/ and tests/webhooks/.
Scope: Only fix Stripe webhook signature verification. Do not change the payment public API or refactor the test framework.
Environment: The Cloud environment has pnpm dependencies installed. Please run pnpm test tests/webhooks/webhook.test.ts first.
Done when: The target test passes; list changed files, commands you ran, checks you did not run, and risks I need to confirm manually.
Stop if: You need to add a new secret, change the database schema, modify shared/http-client.ts, or cannot reproduce the failure.

重要なのは形式ではありません。Codex が守れる境界を渡すことです。Cloud task が issue に近いほど、review できる diff が返ってきやすくなります。

「慎重に」より Stop if のほうが効く

「慎重に」は抽象的すぎます。agent には、どこからが越境なのか判断しにくい。Stop if なら、リスクを具体的な条件にできます。

たとえば、次のように書けます。

• Stop if you need to add a new secret.
• Stop if you need to change the database schema.
• Stop if you must touch the shared auth middleware.
• Stop if the target test cannot be reproduced.
• Stop if the task requires broad renaming or file migration.

こう書くと、Cloud task が高リスク地点に当たったとき、diff を広げ続けるのではなく、止まって説明する可能性が高くなります。

Cloud task が終わったら、summary、diff、コマンドログを見る

追問するか、PR を開くか

Cloud が完了しても、「done」だけで判断しないようにします。まず 4 つを読みます。

1. summary が目標と変更内容を正しく言い直しているか。
2. diff が scope 内に収まっているか。
3. コマンドログに、依頼した test、lint、typecheck が含まれているか。
4. 未実行チェックと、人が確認すべきリスクが明記されているか。

diff が scope 外のファイルに触れているなら、先に聞きます。

The diff touches shared/http-client.ts, which was outside scope. Explain why it was necessary. If not necessary, revert that part and keep the webhook fix minimal.

対象テストを実行していないなら、それも先に聞きます。

You did not run the target test. Run pnpm test tests/webhooks/webhook.test.ts and summarize the result before opening a PR.

変更範囲が明確で、検証コマンドが信用でき、残るリスクが名前付きで書かれているときだけ、PR に進みます。

ローカルに戻すときに見るもの

どちらのルートも使えます。

• 小さな変更：Create PR し、GitHub review、CI、チームのプロセスに流します。
• 高リスク変更：まず check out locally し、ローカルツール、Codex app review pane、IDE で検証します。

ローカルに戻すときは、少なくとも次を確認します。

• git status が clean か、独立した branch / worktree 上にいるか。
• diff が Cloud task の目標だけを含んでいるか。
• 対象 test、lint、typecheck がローカルでも通るか。
• .env*、secrets、CI config、lockfile、generated files が変わっていないか。
• 今回の失敗や判断を AGENTS.md のルールにする必要があるか。

Cloud diff は merge ボタンではありません。リモートで行われた 1 回の試行が、review のために戻ってきただけです。

GitHub の @codex review：二段階目の門であり、merge 許可ではない

手動トリガーと automatic reviews

前提条件を満たした PR では、コメント欄に次の 1 行を送ります。

@codex review

焦点を絞ることもできます。

@codex review for security regressions

Codex review は PR diff を読み、変更ファイルに最も近い AGENTS.md の指示に従い、デフォルトでは高優先度の問題に集中します。チームは automatic reviews を有効にして、PR opened for review のタイミングで自動実行することもできます。

ただし automatic review は automatic merge ではありません。P0/P1 級の問題を早く見つける助けにはなりますが、business owner、CI、最終的な人間の判断を置き換えるものではありません。

Codex review が得意なこと	人がまだ決めること
明らかな回帰、漏れた検証、危険な権限変更を見つける	要求が正しいか、取捨選択が妥当か
AGENTS.md review guidelines に沿って PR diff を見る	アーキテクチャ方針、プロダクト上の意味、リリース時期
P0/P1 問題に高シグナルのコメントを出す	リスクを受け入れるか、merge するか

review で問題が出たら、PR context から Codex に修正を依頼できます。たとえば @codex fix the P1 issue とコメントします。これは Cloud task の流れに入り、返ってきた diff はやはり review が必要です。

@codex が反応しないときは順番に見る

PR に同じコメントを何度も投げる前に、順番に確認します。

1. この repository に Codex Cloud が設定されているか。
2. Codex settings で、この repository の Code review が有効か。
3. コメントが正確に @codex review を含んでいるか。
4. automatic review が有効で、trigger event が一致しているか。
5. GitHub app / repository permission が PR diff、コメント、push branch の読み書きを許可しているか。
6. workspace/admin policy、GitHub Enterprise、private repo access に制限がないか。
7. usage limit に達していないか。特に code review limit は通常の chat usage と異なる場合があります。

Cloud task、review、review 以外の @codex comment で挙動が違うなら、task、comment、repository、時刻を記録してから、公式サポートや workspace admin に確認します。

Remote devbox / SSH host は Cloud ではない

remote connection を使うべき場面

Local にも Cloud にも向かないタスクがあります。プロジェクトがすでに devbox、GPU マシン、社内ネットワーク、企業の remote development host にある場合です。

ここは分けて考えます。

• Codex Cloud：OpenAI managed / configured cloud environment。GitHub リポジトリを checkout し、PC から離れたリポジトリタスクや PR に向いています。
• Remote connection / SSH host：Codex app がリモート host に接続し、そのマシンの files、credentials、permissions、plugins、browser setup、local tools を使います。

タスクが社内サービス、GPU、リモート DB、devbox 上に設定済みの tool を必要とするなら、remote connection のほうが実環境に近いです。安全境界も違います。その host 上で Codex が使える permission、credential、tool が、そのまま境界になります。

保守的には、trusted SSH keys と least-privilege accounts を使い、app-server transport を public internet に出さないようにします。ネットワークをまたぐ接続には VPN や mesh networking を優先します。

保守的な Codex Cloud SOP

最初の Codex Cloud 導入は、この順序で進めると安全です。

1. リポジトリ状態を再現できる小さなタスクを選び、大規模リファクタリングは選ばない。
2. repository に Cloud environment を設定する。
3. 依存関係のインストールと対象チェックを再実行できる setup script を書く。
4. setup 段階で必要な機密値だけを secrets に入れ、非機密設定だけを env vars に入れる。
5. agent internet access はデフォルトでオフにする。必要な場合だけ、必要な domain と method を allowlist する。
6. task prompt を issue のように書く：Goal、Context、Scope、Environment、Done when、Stop if。
7. 実行中は plan、commands、failures を見る。
8. 完了後は summary、diff、test results、skipped checks を読む。
9. 小さな変更は PR にする。高リスク変更は先に check out locally する。
10. PR で @codex review を二段階目の確認に使う。
11. merge するかどうかは、人、CI、チームのプロセスで決める。
12. 繰り返し出る review の学びは AGENTS.md のルールにする。

Cloud を安定させるのは、自動化の強さではありません。各段階に境界があることです。environment は repo を再現できる。prompt は実行可能である。diff は review できる。review の履歴は追跡できる。そうして初めて、不確実性を遠くへ投げるのではなく、明確な要求をクラウド Agent に渡せます。