この記事は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エージェントへ初めて仕事を委任できています。
コピーできる依頼文そのものより、任せる範囲、待ち方、戻り値を自分で決められたことが、次の仕事にも残る価値です。
参考リンク
- Codex CLI（OpenAI公式）
- Subagents（OpenAI公式）
- Authentication（OpenAI公式）
- openai/codex README（OpenAI公式GitHub）
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。次の1機能も一緒に試す方は Xをフォロー すると続きが届きます。