Codex cloudの始め方｜Agents API対応と利用条件・確認方法

Codex cloudの意味を先に整理する

「Codex run in cloud」は、ローカルの端末をそのまま別の場所から操作する意味にも、クラウド上の計算環境でCodexにコード作業をさせる意味にも読めます。ここを区別しないまま始めると、手元のファイルが見えると思い込んだり、画面で使えるモデルとAPIで指定できるモデルを同じ条件だと考えたりします。現在の公式資料では、エージェントを動かす中心、コードやファイルを置く環境、利用者のアプリケーションという三つの役割に分けて説明されています。Codex cloudを理解する第一歩は、サービス名を暗記することではなく、作業のどの部分をクラウドへ移すのかを決めることです。詳しくはOpenAIの公式アーキテクチャガイド（https://developers.openai.com/api/docs/guides/agents-api/architecture）を確認してください。

作業を動かす中心とファイル置き場

モデルはコードの理解や判断を担当しますが、ファイルを読み、コマンドを実行し、結果を保存する場所は別に必要です。Agents APIの説明では、OpenAIが管理するCodexの実行基盤がセッションを保ち、環境がコマンド、コード、ファイルを扱い、利用者のアプリケーションが依頼の送信と結果の受け取りを担います。この分離を意識すると、モデルを変えても環境は同じにする、環境を変えても入力と確認条件は同じにする、といった比較ができます。作業がファイルを必要としない質問なら環境を持たずに進める選択もあります。

ローカル利用との違い

ローカル利用では、現在の端末にあるフォルダー、導入済みのパッケージ、端末固有の設定が作業の前提になります。クラウド側の環境では、それらが勝手に同じ状態になるとは限りません。必要なファイルを渡し、必要なパッケージを指定し、ネットワークへの接続先を決めてから作業を開始します。逆に、クラウド側で作ったファイルを手元へ戻す方法も先に確認しておく必要があります。「クラウドなら全部見える」と考えず、入力と出力の境界を文章にしておくことが、失敗の早期発見につながります。

2026年9月に確認したAgents APIの新情報

Codex cloudをいま調べる理由は、2026年9月10日にOpenAIがAgents APIを公開ベータとして発表したことです。公式発表では、タスク、モデル、ツール、環境を一度のAPI呼び出しで指定し、OpenAIが管理する実行基盤を使ってクラウドのエージェントを動かせると説明されています。長い作業の途中で状況を受け取り、道具の結果を返し、必要に応じて複数のエージェントへ仕事を分ける設計も示されています。ただし、これはCodexのすべての画面に新しいボタンが追加されたという告知ではありません。API、Codexアプリ、CLIはそれぞれ公開範囲と確認項目が違うため、入口ごとに公式資料を読みます。出典 URL: https://openai.com/index/introducing-the-agents-api/

9月10日公開ベータのポイント

Agents APIのセッションには、利用するモデル、エージェントへの指示、最初の入力、必要なら実行環境を渡します。公式クイックスタートでは、OpenAIが管理する環境にスクリプトを作成し、実行し、結果を返す例が示されています。進捗はストリーミングで受け取れるため、最後の文章だけを待つのではなく、どこまで進んだか、どの段階で止まったかを確認できます。Codex cloudを試すときは、最初から大きなリポジトリ全体を渡さず、結果を目で確かめられる小さな作業にします。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/quickstart

Codexの版番号とAPIの公開範囲を分ける

GitHubのopenai/codex公式リリース一覧では、2026年9月11日時点で0.155.0-alpha.3.9などの先行版が掲載されています。これはCodexのクライアントや実行部分の版を示す情報であり、Agents APIの公開ベータとは別の軸です。先行版を入れたからAPIの利用条件が変わる、あるいはAPIが使えるから手元の版も同じになる、と決めつけないようにします。ニュースを記録するときは、確認した日付、入口、モデル、環境の種類を一つのメモに分けて残します。出典 URL: https://github.com/openai/codex/releases

3つの環境から目的に合うものを選ぶ

クラウドでコードを扱う環境は、一つに決まっているわけではありません。OpenAIの公式ガイドは、OpenAIが用意する環境、自分で管理する環境、ファイルや計算資源を持たない環境を分けています。前者は準備の負担を抑えて試しやすく、後者は私有ネットワークや独自のソフトウェアを使いやすい一方で、接続や停止の管理が必要です。質問への回答や外部サービスの呼び出しだけなら、コードを実行する場所そのものを用意しない選択もあります。作業の難しさではなく、必要なファイルと接続先から選ぶと判断しやすくなります。

OpenAI-hosted環境を選ぶケース

OpenAI-hosted環境は、Python、Node.js、コマンドラインツールを含むLinuxの作業場所をOpenAIが用意し、利用者のアプリケーションが依頼と結果を扱う形です。作業ディレクトリ、必要なパッケージ、入力ファイル、ネットワークの扱いをセッションごとに指定できます。公開資料には、準備が失敗した場合はエージェントが開始されないこと、環境の接続状態を確認してからファイルを扱うことも書かれています。まず一つのスクリプトを作成して実行結果を確認する用途なら、選択肢を増やさず始められます。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted

self-hosted環境を選ぶケース

self-hostedは、ノートパソコン、コンテナ、遠隔のサンドボックスなど、自分が信頼できる計算資源をエージェントへ接続する方法です。自分のネットワークや独自の依存関係を使える反面、接続先の起動、再接続、保有するファイル、停止のタイミングを利用者側で管理します。公式資料では、環境接続専用の制限されたキーを使い、通常のアプリケーション用キーを作業場所へ置かないよう案内しています。最初から社内の大きな環境を接続せず、隔離した小さな環境で読み取りと一つの変更を確認してから広げるのが安全です。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted

環境を持たない選択

環境をnoneにすると、エージェントは組み込みのシェルや作業場所を使わず、質問への回答や設定した外部ツールの呼び出しを中心に動きます。コードの説明、複数の資料の比較、検索結果の整理のように、利用者のアプリケーション側が情報を用意できる作業では十分な場合があります。反対に、ファイルを作成する、依存関係を入れる、テストを実行する、といった依頼にはOpenAI-hostedまたはself-hostedの環境が必要です。環境を足せば便利になるとは限らないため、必要な能力から逆算します。

始める前に決める3つの入力

クラウドでエージェントを動かすときは、モデルを選ぶ前に入力を整えます。対象ファイルが不明、完了条件が曖昧、失敗時に誰が判断するか不明という状態では、結果が返ってきても良し悪しを判定できません。OpenAIの設定ガイドも、モデルと指示から始め、必要なツールと出力の扱いを加える構成を示しています。依頼文を長くするより、対象、やってよいこと、見てほしい結果を先に分けることが大切です。この準備が、後から結果を比べる基準になります。

Step 1: 完了条件を一文で決める

最初の課題は、「何ができれば終わりか」を観察できる形にします。たとえば「一つのPythonファイルを作り、指定した入力で実行し、標準出力を示す」のように、作るもの、実行するもの、返すものを一文へ落とします。「きれいにする」「使いやすくする」だけでは判定が人によって変わるため、表示、テスト、出力、差分のどれを見るかも書きます。完了条件が小さければ、環境やモデルを変えたときの比較もできます。

Step 2: 扱うファイルと範囲を決める

エージェントへ渡すファイルは、作業に必要な最小範囲から始めます。入力ファイルの名前、読み取り専用の資料、変更してよいファイル、触れないフォルダーを分け、不要な個人データや大きな生成物を入れないようにします。既存のリポジトリと同じ状態が必要なら、何を持ち込んだか、依存関係をどうそろえたかを記録します。クラウド側で作成した結果をダウンロードするのか、APIの結果として受け取るのかも、依頼を始める前に決めておきます。

Step 3: 停止条件と確認者を決める

長い作業では、成功したときだけでなく、失敗、キャンセル、接続切れ、環境の準備失敗をどう扱うかを決めます。途中で人が追加指示を出すのか、一定のエラーで止めるのか、実行結果だけを保存して後で判断するのかを明記します。コードが変更された場合は、エージェントの説明をそのまま採用せず、差分、実行結果、関連する確認を人が見ます。終了の合図と採用の判断を分けると、クラウドで処理が終わったことと、成果物を使ってよいことを混同しません。

最初のリクエストを小さく組み立てる

Agents APIのクイックスタートは、セッション作成時にモデル、指示、環境、入力、ストリーム指定を渡す形です。下の例は構造を理解するための最小形で、実際に使うモデル名、入力内容、利用可能な機能は公式資料とアカウントの条件に合わせて調整します。APIキーは作業ファイルへ書き込まず、実行元だけで扱います。最初の試行は読み取りと短いファイル生成に限定し、結果を確認してから変更範囲を広げてください。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/quickstart

curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "対象を確認し、変更理由と実行結果を報告してください。"
    },
    "environment": { "type": "openai_hosted" },
    "input": "小さなサンプルファイルを作り、実行結果と確認方法を示してください。",
    "stream": true
  }'

Step 1: モデルと指示を分ける

モデル名は判断の中心を指定し、指示は作業時の振る舞いと報告形式を指定します。「このモデルなら必ず完成する」と考えず、対象、変更範囲、実行してよい確認、返してほしい情報を指示へ含めます。モデルの公開状況と利用条件は変わり得るため、コード例のモデル名を固定的な保証として使わず、公式のモデル一覧で確認します。モデルを変えて比較するときは、指示と入力を可能な範囲で同じにします。

Step 2: 環境と入力を一緒に指定する

ファイル生成を頼むなら、環境の種類だけでなく、作業場所、必要なパッケージ、渡すファイル、ネットワークの要否を決めます。入力文には、作業の目的と終了条件を置き、環境設定には実行に必要な項目だけを置くと、原因を切り分けやすくなります。入力ファイルを追加したのに結果へ反映されない場合は、ファイルが準備済みか、環境が接続済みかを確認してから再試行します。

Step 3: 進捗と最終結果を両方見る

ストリーミングを使うと、エージェントが何を確認し、どの作業へ進んだかを受け取れますが、イベントが流れたことだけで成功とは判定しません。公式クイックスタートでは、完了イベントの後に実行結果を確認し、失敗、キャンセル、セッション失敗を区別するよう説明しています。接続が途中で切れた場合も、すぐ同じ依頼を二重に送らず、まずセッションと保存済みの結果を取得します。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/quickstart

料金はモデルと環境を分けて見る

Codex cloudの料金を考えるとき、モデルの利用量とコードを動かす環境の費用を一つの月額として扱わないことが重要です。OpenAI-hosted環境の公式ガイドは、環境に標準のコンテナ料金がかかり、モデル利用は選択したモデルのAPI料金として別に請求されると説明しています。self-hostedでは自分の計算資源や接続の費用が別に発生します。契約型のCodex画面で見える利用枠と、Agents APIの請求を同じ数字で説明せず、使う入口、モデル、環境、入力と出力の量を分けて見積もります。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted

モデル利用量を見積もる

入力に大きなリポジトリや不要なログを含めると、内容を読む量が増え、結果を確認する負担も大きくなります。最初は対象ファイル、再現手順、完了条件に絞り、必要な資料だけを追加します。長い会話を続ける場合は、前の結果をそのまま繰り返し渡すのではなく、残すべき判断と不要な履歴を分けます。料金だけを下げる目的で説明を削りすぎると、やり直しが増えることがあるため、最小で判定できる入力を探します。

環境の稼働時間を見積もる

ファイルの準備、パッケージの導入、コードの実行、結果の保存にどれくらい時間が必要かを分けて考えます。セットアップが毎回大きい場合は、必要な依存関係を整理し、版を固定して準備の失敗を減らします。作業が終わったのに環境を残し続ける設計は、費用とデータの保管範囲を広げます。OpenAI-hosted環境でも、作業が完了したときに結果を取得し、不要なものを残さない扱いを決めておきます。

利用上限と確認単位を決める

試す回数、同時に動かす作業数、入力の最大サイズ、許容する待ち時間をあらかじめ決めます。上限に達したときは、同じ依頼を繰り返すより、失敗した段階の記録を見て入力か環境かを直します。利用量の確認画面やAPIの応答を日付付きで残すと、請求や結果に差が出たときに原因を追えます。公式の料金ページと利用状況の表示は、記事公開後も変わる可能性があるため、確認日を付けて参照します。

APIキーとデータの境界を守る

クラウドでコードを実行する場合、便利さより先に「何を環境へ渡すか」を決めます。公式クイックスタートは、アプリケーション用APIキーをエージェントのサンドボックス外に置くよう案内しています。OpenAI-hosted環境ではネットワーク接続を有効、無効、許可したホストだけに制限する設定があり、self-hostedでは環境接続専用の制限されたキーを使います。APIキーをソースコード、作業ファイル、ログへ書かない、入力ファイルを必要なものに絞る、結果を誰が見られるかを決めるという三つを、最初の試行から守ります。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted

OpenAI-hostedのネットワークを確認する

OpenAI-hosted環境のネットワークは、設定によって外部接続を許可、禁止、指定したホストだけに制限できます。既定値やテンプレートから受け継いだ設定が、想定と同じとは限りません。外部パッケージを取得するのか、外部APIへ接続するのか、完全に閉じた作業でよいのかを依頼ごとに決めます。接続を広く許可することを成功条件にせず、必要な接続先だけを確認し、結果に含まれるデータも見直します。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted

self-hosted環境を分けて使う

self-hosted環境を複数の利用者や作業で共有すると、同じファイル、キー、設定へ互いに触れられる可能性があります。公式資料も、利用者や作業単位で環境を分け、接続用のキーを通常のアプリケーション用キーと分離するよう説明しています。接続が切れたときの再接続や、作業の停止時に実行中の処理がないかを確認する責任も自分側にあります。小さな環境、短い作業、限定した権限から始め、必要性を確認してから共有範囲を広げます。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted

結果を人が確認してから採用する

エージェントがファイルを作り、コードを実行し、成功を報告しても、成果物をそのまま採用してよいとは限りません。変更されたファイル、実行した入力、出力、失敗した確認、残った注意点をまとめて見ます。特に依存関係の追加、外部接続、データの移動を含む場合は、目的に不要な変更がないかを人が確認します。クラウドで処理が済んだことと、製品やサービスへ反映してよいことを分けるだけで、見落としを減らせます。

最初の導入を確認する手順

ここまでの内容を、初回の小さな確認へまとめます。Agents APIのクイックスタートでは、OpenAI Platformのプロジェクトでセッション操作とモデル推論に必要な権限を持つAPIキーを用意し、作業場所をOpenAI-hostedにして進捗を受け取る流れが示されています。実際の権限名や利用可能なモデルは、アカウントの状態と公式ドキュメントで確認してください。大きな変更を始める前に、次の順で結果を一つずつ記録します。

Step 1: 利用条件と権限を確認する

OpenAI Platformの対象プロジェクト、利用できるモデル、Agents APIの公開範囲、セッション操作に必要な権限を確認します。公式クイックスタートは、api.agents.read、api.agents.write、api.responses.writeを例として示していますが、将来の変更や組織の設定を含めて現在の案内を優先します。自分のアプリケーション用キーと環境接続用キーを混同せず、キーを置く場所と廃棄する時期を決めてから次へ進みます。

Step 2: 一つのファイルを作る

入力は「一つの小さなファイルを作り、実行し、実際の出力とファイル一覧を返す」のように限定します。環境はOpenAI-hostedを選び、必要なパッケージやネットワーク接続がなければ追加しません。ここで見るのは、セッションが作られたか、環境が接続されたか、ファイルが作られたか、実行結果が返ったかです。見えない部分を想像して成功と判定せず、返ってきたイベントと保存された結果を確認します。

Step 3: 変更前後を比べる

次の試行では、入力を大きく変えずに一つだけ条件を変えます。たとえば環境の種類、モデル、入力ファイルの有無のどれかを変え、完了までの時間、出力の正しさ、追加確認の回数を記録します。複数の条件を同時に変えると、何が結果へ影響したのか分からなくなります。良い結果だけでなく、環境の準備失敗や途中停止も記録すれば、実際の作業へ広げるときの判断材料になります。

Step 4: ファイルとキーを整理する

確認が終わったら、作成したファイル、ログ、入力データ、利用したキーの扱いを見直します。残す必要がある成果物だけを保存し、キーをコードやログへ書いていないか、入力に不要なデータが含まれていないかを確認します。self-hostedへ移る場合は、環境ごとの接続、再接続、停止の責任範囲を別に書きます。後から同じ作業を再現できる記録と、残してはいけないデータを混ぜないことが重要です。

Step 5: 作業範囲を一つずつ広げる

小さな確認が通った後で、複数ファイル、テスト、外部ツール、長いセッションの順に必要なものを一つずつ追加します。各段階で完了条件、利用量、ネットワーク、結果の確認方法を更新します。複数のエージェントを使う場合も、同じファイルを同時に編集させず、独立した調査やレビューなど分けやすい仕事から始めます。公式のマルチエージェントガイドは、各エージェントへ明確な質問と期待する結果を渡すよう説明しています。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/multi-agent

まとめ

Codex run in cloudを始めるときは、まず「モデルをどこで動かすか」ではなく、「どのファイルをどの環境で扱い、何を結果とするか」を決めます。OpenAIのAgents APIは2026年9月10日に公開ベータとして案内され、Codexで培われた実行基盤をクラウドのエージェントへ組み込む入口になりました。ただし、API、Codexアプリ、CLIの版番号と公開範囲は同じではありません。入口を分けて考えることが、最初の確認を迷わせないコツです。

最初はOpenAI-hosted環境で一つの小さな作業を試し、モデル、指示、入力、環境、進捗、最終結果を分けて記録します。私有ネットワークや独自の計算資源が必要な場合だけself-hostedへ進み、キー、ファイル、ネットワーク接続を環境単位で分けます。料金もモデル利用と環境利用を別に見積もり、作業が終わった後に残すデータを決めておきます。

公開状況や利用条件は更新されるため、開始前にはOpenAIのAgents API公式ガイド（https://developers.openai.com/api/docs/guides/agents-api/overview）、クイックスタート（https://developers.openai.com/api/docs/guides/agents-api/quickstart）、環境ガイド（https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted）を確認してください。公式情報と手元の結果を分けて記録し、小さな確認から段階的に広げることが、Codex cloudを安心して使うための現実的な始め方です。