PCを閉じたいのに、AIの調査が終わるまでターミナルを見ている。最初にAIエージェントを使うと、こんな待ち時間に出会います。

今回やることは1つだけです。

Codex CLIの codex cloud exec で、設定済みのCodex cloud環境へREADME調査を1件送ります。

送信後に新しいクラウドタスクが作成されたことを確認できたら成功です。コード変更の取り込みや複数タスクの並列実行までは扱いません。まずは「手元のPCから、クラウド上のAIエージェントへ1件渡せた」という小さな成功を作りましょう。

この記事は、GitHubなどのリポジトリがCodex cloudへ接続され、クラウド環境が1つ設定済みの人を対象にしています。環境がまだない場合は、先に公式のCloud environmentsページから設定してください。

`codex cloud exec`とは

Codexは、ソースコードを読んだり、コマンドを実行したりしながら目的へ進むAIエージェントです。ここでいうAIエージェントは、質問に答えるだけでなく、与えられた環境で複数の手順を進めるAIのことです。

Codex CLIは、CLI、つまりターミナルへ文字を入力してCodexを操作する方式です。ターミナルは、黒や白の画面へコマンドを打ち込んでPCを操作するアプリだと思えば大丈夫です。

codex cloud execは、そのCodex CLIからCodex cloudへ新しいタスクを1件提出するコマンドです。

手元のターミナル
  └─ codex cloud execで依頼を送る
       └─ Codex cloudの隔離された環境
            └─ 接続済みリポジトリを読み、AIが作業する

リポジトリは、コードやREADMEなど、プロジェクトのファイルと変更履歴をまとめて置く場所です。Codex cloudは接続済みのリポジトリから指定されたブランチまたはコミットをチェックアウトし、設定された準備処理を実行してからAIエージェントを動かします。ブランチは、同じリポジトリ内で変更を分けて進める作業レーンのようなものです。

2026年8月31日時点の公式CLIリファレンスでは、codex cloudはexperimentalです。experimentalは、利用できるものの、今後コマンド名や表示が変わる可能性がある段階という意味です。この記事では確認日とCLI版を明記し、将来の差分を見分けやすくします。

なぜ便利なのか

ローカルのCodexは自分のPC上で動きます。短い作業なら、それが一番わかりやすいです。

一方、少し長い調査やテストを手元から切り離したい時は、クラウドへ渡せると助かります。公式ドキュメントでは、Codex cloudはタスクごとに隔離されたクラウド環境を使い、作業をバックグラウンドで進められると説明されています。

ただし、ここで大事な注意があります。

手元のフォルダを、そのまま丸ごとクラウドへ転送する機能ではありません。

Codex cloudが見るのは、接続済みリポジトリのブランチまたはコミットです。ローカルで保存しただけのファイルや、まだGitへ反映していない変更が自動で渡るとは考えないでください。この違いを最初に知っておくと、「手元では見えるのにクラウドでは見えない」という失敗を減らせます。

今日のゴール

今回は、設定済みのクラウド環境へ次の依頼を送ります。

README.mdだけを読み、このリポジトリの目的を日本語3行で説明してください。ファイルは変更しないでください。

読み取りだけの依頼なので、最初の練習に向いています。AIが返した説明の正しさは人間がREADMEと見比べます。人間が対象と合否を決め、AIが調査を進める。この役割分担が基本です。

事前準備

1. Codex CLIをインストールする

Node.jsとnpmが使えるmacOS、Linux、WSLでは、公式のインストールコマンドは次です。CLIはターミナルへ入力します。

npm install -g @openai/codex

インストール後、版を確認します。

codex --version

筆者環境では2026年8月31日に次を確認しました。

codex-cli 0.150.1

バージョンが違っても、すぐ異常とは限りません。まず自分のCLIでhelpを確認してください。

codex cloud exec --help

2. サインインする

まだサインインしていない場合は、次を実行します。

codex login

状態だけ確認したい場合は次です。

codex login status

3. Codex cloud環境を設定する

クラウド環境は、Codexがどのリポジトリを使い、どの依存関係や準備コマンドを用意するかをまとめた設定です。公式の環境設定画面で、対象リポジトリを接続しておきます。

今回必要なのは、環境を識別する ENV_ID です。ENV_IDは、人間向けの環境名とは別に、CLIが対象を間違えないために使う識別子です。

ターミナルで次を実行すると、設定済み環境とクラウドタスクを選ぶ対話画面を開けます。

codex cloud

自分が作成した練習用環境を確認し、そのENV_IDを控えます。画面の表示はCLIの更新で変わる可能性があります。知らない環境や、所有権を確認できないリポジトリは選ばないでください。

10分で1タスク送る

ここからが本番です。

1. 対象リポジトリのREADMEを確認する

GitHubなどで、クラウド環境へ接続したリポジトリに README.md があることを確認します。機密情報を含むリポジトリでは練習しない方が安心です。公開して問題のない練習用リポジトリを使いましょう。

2. ENV_IDを入れて送信する

次の YOUR_ENV_ID を自分のENV_IDへ置き換えます。

codex cloud exec \
  --env YOUR_ENV_ID \
  'README.mdだけを読み、このリポジトリの目的を日本語3行で説明してください。ファイルは変更しないでください。'

公式リファレンス上の基本構文は次です。

codex cloud exec --env ENV_ID [QUERY]

QUERYはAIへ渡す依頼文です。省略すると対話形式で入力を求められます。最初は何を送ったか後から見直しやすいので、上のように1つの引用符で囲んで書くのがおすすめです。

3. 成功を確認する

送信後、CLIまたはCodex cloudの画面で新しいタスクが作成されたことを確認します。表示はCLIの更新で変わりうるため、特定の文言ではなく、依頼したREADME調査のタスクが増えたことを成功条件にします。

今回のゴールはここまでです。

結果の差分をローカルへ適用する操作は、別の機能です。読み取りタスクではファイル変更を頼んでいないため、まずクラウド側で返答を読み、READMEの原文と照合してください。

公式リファレンスでは、送信に失敗した場合、Codex CLIは非ゼロの終了コードを返すとされています。新しいタスクを確認できない時は、下のつまずきポイントを順番に確認します。

人間とAIの役割を分ける

今回の最小タスクでも、全部をAI任せにはしません。

担当	やること
人間	対象リポジトリと環境を選ぶ
人間	「READMEだけ」「変更しない」「3行」という境界を決める
AI	クラウド環境でREADMEを読み、説明を作る
人間	説明をREADMEの原文と照合する

AIエージェントは、依頼を進める実行役にはなれます。でも、正しいリポジトリを選ぶこと、機密情報を渡してよいか決めること、結果が正しいか判断することは人間の仕事です。

つまずきポイント

1. `codex: command not found`になる

Codex CLIが未インストールか、インストール先へPATHが通っていません。まず次を確認します。

node --version
npm --version
codex --version

最初の2つも見つからない場合は、先にNode.jsの準備が必要です。

2. `Not logged in`と表示される

codex loginを実行し、ブラウザでサインインを完了します。その後、次で再確認します。

codex login status

3. `--env`が必要だと言われる

codex cloud execでは環境IDが必須です。YOUR_ENV_IDという文字をそのまま使わず、自分の設定済み環境のIDへ置き換えてください。

4. 選べるクラウド環境がない

公式のCodex settingsで、リポジトリ接続とクラウド環境の作成を先に行います。組織やワークスペースのポリシーでクラウド利用が許可されていない場合は、管理者への確認が必要です。権限を回避しようとはせず、ローカルのCodexへ切り替えましょう。

5. クラウド側でREADMEが見つからない

手元にだけある未保存・未反映のファイルは、クラウドへ自動で渡りません。接続したリポジトリの対象ブランチにREADMEが存在するか確認します。

6. 想定と違うブランチを読んでいる

公式CLIでは --branch BRANCH も指定できますが、最初の練習では環境の既定ブランチを使う方が迷いにくいです。既定ブランチに練習用READMEがある状態で試してください。別ブランチを使うのは、最初の成功後で十分です。

7. helpの表示が記事と違う

codex cloudは2026年8月31日時点でexperimentalです。最新版では構文や表示が変わる可能性があります。記憶で進めず、自分の環境のhelpを正として確認します。

codex cloud --help
codex cloud exec --help

8. タスクは送れたが、説明が正しいか分からない

タスク送信の成功と、回答内容の正しさは別です。READMEの見出し、目的、主要機能を原文と1行ずつ見比べます。AIの回答だけを根拠にしないことが大切です。

この方法が向かない時

正直、10秒で終わるファイル確認のために、毎回クラウド環境を使う必要はありません。対象ファイルが手元にあり、PCを開いたまま短時間で終わるなら、通常のローカルCodexで十分です。

codex

また、ローカルの未コミット変更だけを読ませたい仕事にも、そのままでは向きません。先ほど見た通り、クラウドタスクは手元の作業ツリーを自動継承しないからです。

codex cloud execが効くのは、接続済みリポジトリを基準に、少し長い仕事をクラウド側へ渡したい時です。前提が合わない時は、ローカルを選ぶ。その見分け方まで含めて、安全なAIエージェント入門やと思います。

動作確認範囲

2026年8月31日に、macOS環境のCodex CLI 0.150.1で次を確認しました。

codex --version
codex cloud --help
codex cloud exec --help
codex login status

確認結果は、版表示とhelpの構文、ローカル環境が未ログインであることです。筆者環境では認証済みクラウド環境を用意できなかったため、実際のタスク送信と回答取得は筆者未検証です。送信構文、--env必須、--attempts既定1、認証の扱いは当日の公式ドキュメントとCLI helpで照合しています。

まとめ

今日覚えるのは1行です。

codex cloud exec --env YOUR_ENV_ID 'README.mdだけを読み、目的を日本語3行で説明してください。ファイルは変更しないでください。'

設定済み環境があり、新しいクラウドタスクが作成されたことを確認できれば、最初のクラウド委任は成功です。まずは読み取りタスクを1件。AIエージェントに仕事を渡す感覚は、その小さな成功からつかめます。

参考リンク

生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。次は自分の設定済み環境へ、読み取りタスクを1件だけ送ってみてください。