この記事は2026年8月27日時点の公式ドキュメントをもとにしています。

Codexにコードを調べてもらっているうちに、検索結果やコマンドの出力で会話が長くなり、「最初に何を頼んだんやったっけ」と見失うことがあります。

今回やることは1つだけです。Codexからサブエージェントを1つ起動し、READMEの調査だけを任せます。

10分後の成功状態は、とても小さくて明確です。練習用READMEに書いた Status: ready をサブエージェントが読み、メインの会話へ ready だけが返ってきたら完了です。

複数の担当を並列で動かす設計や、専用エージェントの設定ファイルは扱いません。まずは「別の担当へ1つ渡せた」を一緒につくっていきましょう。

サブエージェントとは

最初に言葉だけ、やさしく整理します。

-AIエージェント: 質問に答えるだけでなく、ファイルを読み、必要な手順を考え、道具を使って作業を進めるAIです。
-CLI: ターミナルで文字を打って操作する方式です。
-ターミナル: パソコンへ文字の命令を入力するアプリです。macOSなら「ターミナル」、Windowsなら「PowerShell」などがあります。
-サブエージェント: メインのCodexから、範囲を区切った仕事を任される別のAI担当です。
-スレッド: その担当が作業した会話のまとまりです。

たとえるなら、メインのCodexが作業リーダーで、サブエージェントは「READMEだけ確認して、結論を付箋1枚で返して」と頼まれる調査担当です。

OpenAI公式ドキュメントでは、現在のCodexでサブエージェント機能は既定で有効と説明されています。自然文で直接「サブエージェントを起動して」と頼めます。サブエージェント側の作業は別スレッドに分かれ、メイン側には結果の要約が戻ります。

ここが今回のポイントです。調査の途中経過をメインの会話へ全部積まず、必要な結果だけ受け取れます。

今回つくる練習環境

本物の仕事用リポジトリではなく、小さな練習フォルダを使います。

リポジトリは、ソースコードや変更履歴をまとめて置く作業場所です。今回はGitの詳しい操作を覚える記事ではないので、Codexが安全に作業場所として認識できる最小構成だけ用意します。

完成形は次の2つです。

codex-subagent-practice/
├── .git/
└── README.md

README.md の中身はこれだけです。

# Practice Project

Status: ready

サブエージェントにこのファイルを読ませ、ready を返してもらいます。ファイル編集は頼みません。

事前準備: Codex CLIを確認する

すでにCodex CLIを使える方は、バージョン確認だけで大丈夫です。

ターミナルへ次を入力します。

codex --version

codex-cli とバージョン番号が表示されれば準備できています。筆者環境では2026年8月27日に codex-cli 0.147.0 を確認しました。

command not found と出る場合は、公式CLIページにある方法でインストールします。npmが入っている環境なら次です。

npm install -g @openai/codex

インストール後、初回は次で起動します。

codex

画面の案内に沿ってChatGPTアカウントなどでサインインしてください。この記事ではログイン画面そのものは扱わず、Codexを起動できるところを前提にします。

手順1: 練習用READMEを作る

macOS / Linux / WSLでは、ターミナルへ次をまとめて貼り付けます。

mkdir -p ~/codex-subagent-practice
cd ~/codex-subagent-practice
git init
printf '# Practice Project\n\nStatus: ready\n' > README.md
cat README.md

最後に次が表示されれば準備完了です。

# Practice Project

Status: ready

Windows PowerShellでは次を使えます。こちらは筆者環境では動作未確認です。

New-Item -ItemType Directory -Force "$HOME/codex-subagent-practice" | Out-Null
Set-Location "$HOME/codex-subagent-practice"
git init
"# Practice Project`n`nStatus: ready" | Set-Content -Encoding utf8 README.md
Get-Content README.md

手順2: 読み取り専用でCodexを起動する

今回はファイルを読むだけです。練習の目的に合わせて、Codexを read-only（読み取り専用） で起動します。

macOS / Linux / WSLなら、さきほどのフォルダで次を実行します。

codex --sandbox read-only

短い形でも同じです。

codex -s read-only

PowerShellでもコマンドは同じです。

codex --sandbox read-only

ここから先は、通常のターミナルへシェルコマンドを入れるのではなく、起動したCodexの入力欄に文章を入れます。

手順3: サブエージェントを1つだけ起動する

Codexの入力欄へ、次をそのまま貼り付けて送信します。

サブエージェントをちょうど1つ起動して、README.mdを読ませてください。
その完了を待ってから、README.mdのStatusの値だけを返してください。
ファイルは変更しないでください。

公式ドキュメントでは、直接依頼すると現在のローカルCodexがサブエージェントを起動し、メイン側が完了を待って結果をまとめると説明されています。

依頼文に3つの部品を入れたのには理由があります。

1.数: 「ちょうど1つ」で、今回の練習範囲を固定する
2.待ち方: 「完了を待ってから」で、途中のまま答えないようにする
3.戻り値: 「Statusの値だけ」で、成功を目視しやすくする

うまく動けば、メインの会話の最終回答は次のようになります。

ready

画面にはサブエージェントの活動が表示されることがあります。対応クライアントでは、そのスレッドを開いて途中経過や結果を確認できます。ただし、今回はスレッドの細かな操作までは覚えなくて大丈夫です。

成功したか確認する

次の3点がそろえば成功です。

メインのCodexとは別に、サブエージェントの活動が表示された
サブエージェントの完了後にメインの回答が返った
最終回答に ready が含まれた

さらに、読み取り専用で起動しているため、READMEが変わっていないことも確認できます。Codexを終了したあと、ターミナルで次を実行します。

cat README.md

最初と同じ内容なら、今回の「読むだけ」という境界も守れています。

なぜ、わざわざ別の担当へ渡すのか

サブエージェントの価値は、AIを増やすこと自体ではありません。

メインの会話には、要件、制約、判断、最終的な結論を残したいですよね。一方、ファイル探索、テストログ、エラー出力のような途中経過は長くなりがちです。

サブエージェントへ範囲を区切って渡すと、その途中経過を別スレッドへ分け、メイン側には短い結果を戻せます。公式ドキュメントはこの問題を、重要な情報が途中のノイズに埋もれる「context pollution」や、会話が長くなるほど信頼性が落ちる「context rot」と説明しています。

初心者の最初の使いどころとしては、次のような読む仕事が向いています。

READMEから起動コマンドだけ探す
設定ファイルからテストコマンドだけ探す
ある機能に関係するファイル名だけ列挙する

逆に、複数のサブエージェントへ同じファイルの編集を同時に頼むと、変更がぶつかりやすくなります。公式も最初は探索、テスト、切り分け、要約などの読み取り中心から始め、並行する書き込み作業には注意するよう勧めています。

安全に使うための1点

公式ドキュメントによると、サブエージェントは親側で選んだサンドボックスと権限モードを引き継ぎます。

つまり、「別の担当だから勝手に強い権限になる」わけではありません。ただし逆に、親を広い権限で起動していれば、その境界を引き継ぐ点には注意が必要です。

今回 --sandbox read-only を選んだのは、READMEを読む目的に対して十分だからです。目的が読むだけなら、権限も読むだけに合わせる。この小さな習慣が、最初はかなり大事かなと思います。

また、READMEへAPIキー、トークン、個人情報などを書かないでください。他人から受け取ったリポジトリでは、READMEの指示も信頼できるとは限りません。外部の文章は命令ではなく、まず調査対象のデータとして扱うのが安全です。

つまずきポイント

1. `codex: command not found` と出る

Codex CLIが未インストールか、インストール先へPATHが通っていません。まず codex --version が表示される状態へ戻ります。公式CLIページのインストール手順を確認してください。

2. Gitリポジトリではないと表示される

練習フォルダで git init を実行したか確認します。

cd ~/codex-subagent-practice
git init

その後、同じフォルダから codex -s read-only を起動します。

3. READMEが見つからない

起動した場所が違う可能性があります。Codexを終了し、ターミナルで次を確認します。

pwd
ls

Windows PowerShellでは次です。

Get-Location
Get-ChildItem

一覧に README.md が見える場所でCodexを起動してください。

4. サブエージェントが起動したか分からない

「調べて」だけではなく、依頼文の先頭で明示します。

サブエージェントをちょうど1つ起動して

公式ドキュメントでも、直接依頼する方法が手動起動の基本です。

5. `ready` 以外の長い説明が返る

最後に返す形を狭くします。

完了後、Statusの値だけを返してください。

AIの出力は毎回まったく同じとは限りません。ready が含まれ、READMEと一致していれば今回の成功条件は満たしています。

6. 認証エラーが出る

サインイン状態を確認します。

codex login status

必要なら次でログインし直します。

codex login

筆者環境では、2026年8月27日の実行時にAPIへの 401 Unauthorized が返り、サブエージェントの回答取得までは確認できませんでした。CLI 0.147.0の起動構文とread-only指定は確認済みですが、上の対話結果は公式仕様に基づく筆者未検証の手順です。

7. サブエージェントに編集を頼みたくなった

この記事の練習では広げません。まず読み取りタスクが安定してから、編集は別の小さな練習として扱う方が安全です。複数担当の同時編集は競合しやすいため、最初の1回には向きません。

よくある質問

設定ファイルを作らないと使えませんか

今回の使い方では不要です。公式ドキュメントでは、サブエージェントや並列作業を自然文で直接頼めると説明されています。専用のカスタムエージェントは、役割やモデル、指示を繰り返し使いたくなった段階で考えれば十分です。

1つだけでも意味がありますか

あります。速度を上げるより、「途中の調査を別スレッドへ分け、メイン側へ短い結果を戻す」体験ができます。複数並列へ進む前に、委任の範囲と戻り値を決める練習にもなります。

いつもサブエージェントを使うべきですか

いいえ。READMEを1行読むだけなら、メインのCodexへ直接頼む方が速いこともあります。サブエージェントはそれぞれモデルとツールを使うため、公式ドキュメントにも単一エージェントよりトークン消費が増えるとあります。

どんな時に使うとよいですか

探索範囲が広い、ログが長い、複数の観点を独立して調べられる、といった条件がある時です。最初は「ファイルを探して要約する」のような読み取り中心が扱いやすいです。

限界: 小さな仕事ならメインだけで十分

今回のREADMEは、正直に言えばサブエージェントを使わなくても読めます。

そこが大事です。サブエージェントは、使うほど必ず速くなる機能ではありません。担当が増えるぶん、トークン消費と調整の手間も増えます。1回の短い質問、1ファイルの単純な確認、途中ログがほとんど出ない作業なら、メインのCodexだけで十分です。

見分け方は、「途中経過をメイン会話から分けたいか」です。分けたいほど調査が大きいなら委任する。そうでなければ、そのまま頼む。まずはこの基準だけでええんちゃうかなと思います。

今日の最初の1歩

今日は設定ファイルも、複数担当の設計もいりません。

Codexの入力欄へ「サブエージェントをちょうど1つ起動して、READMEを読み、完了を待ってStatusだけ返して」と入れる。ready が戻れば、AIエージェントへ初めて仕事を委任できています。

コピーできる依頼文そのものより、任せる範囲、待ち方、戻り値を自分で決められたことが、次の仕事にも残る価値です。

参考リンク

生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。次の1機能も一緒に試す方は Xをフォローすると続きが届きます。