社内ツールには Codex SDK と App Server のどちらを使うべきか

社内ツールに「コード変更をレビュー」ボタンを追加したいとします。押すと Codex がリポジトリを読み、確認すべき点を一覧にし、最終判断は人間のレビュアーに任せます。ここで使うのは Codex SDK と Codex App Server のどちらでしょうか。この記事では約30分で統合方法を選び、読み取り専用の Python サンプルを試せます。Codex の利用権限、機密情報を含まないテスト用リポジトリ、サンプル用の Python 3.10 以降、結果を確認する担当者が必要です。

OpenAI の Codex SDK ドキュメントによると、SDK はプログラム、CI、社内ツールからプログラミング作業を実行する用途に向いています。Codex App Serverは、認証、会話履歴、承認、エージェントのイベント配信をアプリ側で管理するためのプロトコルインターフェースです。Python SDK 自体も JSON-RPC を通じてローカルの app-server を制御します。選ぶのは統合の深さであり、異なる二つの AI を選ぶわけではありません。

準備

要件を「リポジトリを選択して「コード変更をレビュー」ボタンを押すと、人間が確認できる指摘一覧を返す」と明記します。誰がリポジトリを選べるか、どのマシンで実行するか、どのデータを読めるか、誰が変更を承認するかを決めます。

開発者がターミナルで一つの問題を修正するだけなら、Codex CLI のガイドで足りるかもしれません。チームに繰り返し使う工程が必要になってから統合を検討してください。AI エージェントとチャットボットの違いでは、境界と検証が必要な理由を説明しています。

安全に実行できるテストコマンドを備えたテスト用リポジトリを用意します。最初から顧客のリポジトリは使わないでください。実行環境での Codex の認証方法とサンドボックスの方針を確認します。秘密鍵をコードやプロンプトに入れないでください。ファイルの編集があり得る場合は、チームで Codex の権限を制限する方法も参照してください。

手順

1. ジョブの結果だけが必要なら SDK を選ぶ

社内ツールに「リポジトリを確認」ボタンがあると想像してください。ジョブがプロジェクトのディレクトリを受け取り、Codex に読ませて回答を得て、要約を作業チケットに保存します。ユーザーは細かなイベントをすべて見たり、実行中に質問を変えたり、画面内でコマンドを承認したりする必要がありません。この場合は SDK から始めるのが適切です。

TypeScript SDK は Node.js 18 以降のサーバー側で動作し、thread の開始、継続、再開ができます。Python SDK は Python 3.10 以降が必要です。安定版は pip install openai-codex で導入でき、バージョンが固定された Codex CLI の依存物が含まれます。既存システムに合う言語を選べばよく、両方を入れる必要はありません。公式の Python ドキュメントには read_only、workspace_write、full_access のサンドボックス設定が記載されています。

最初のレビューは読み取り専用にします。テスト用リポジトリでパッケージをインストールします。

pip install openai-codex

次のコードを review_repo.py として保存します。クラス名とメソッド名は公式 SDK ドキュメントに沿っています。特定のモデルを指定せず、アカウントで使えるデフォルトモデルを利用します。

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.read_only)
    result = thread.run(
        "Read this repository and list three possible test gaps. "
        "Cite the relevant files. Do not edit anything."
    )
    print(result.final_response)

テスト用リポジトリ内で python3 review_repo.py、または相当する Python コマンドを実行します。出力は人が確かめるための材料であり、リポジトリの安全性を証明するものではありません。認証やサンドボックスでエラーが出たら、該当する権限を正しく直してください。サンプルを動かすためだけに full_access へ変更しないでください。

この最小の API サンプルは OpenAI のドキュメントと照合し、Python の構文も確認済みです。ただし、あなたのプロジェクトで Codex を実際に呼び出したものではありません。出力内容やアカウント権限は保証できません。実際に試す際は、SDK のバージョン、リポジトリ、日時、サンドボックス、エラーを記録して再現できるようにします。

2. 完全な Codex アプリを作るなら App Server を選ぶ

エージェントの作業を段階ごとに表示し、複数の会話を保持し、承認要求を受け、ユーザーが thread を再開でき、イベントへリアルタイムに反応する社内ツールには App Server が向いています。たとえばチームリーダーが社内ページで Codex のテスト実行を見て、操作を承認し、見つかった失敗について続けて質問する場合です。基本的な SDK は作業を始めて結果を得られますが、このようなアプリには処理の流れをより細かく制御する必要があります。

ドキュメントによると、App Server は双方向の JSON-RPC メッセージを使います。ローカル接続では codex app-server はデフォルトで stdio を使い、1 行が 1 件の JSON メッセージです。最小限の流れは次のとおりです。

1. App Server を起動してクライアントを接続する。
2. 接続ごとに一度 initialize を送り、続けて initialized 通知を送る。
3. thread/start を呼び、会話の ID を受け取る。
4. その ID とユーザーのメッセージを使って turn/start を呼ぶ。
5. turn/completed まで進捗通知を読み、権限の判断が必要な要求にも対応する。

これは処理の流れの概略であり、完成したクライアントコードではありません。実際のクライアントはエラー、切断、承認、認証、セッション状態を扱う必要があります。App Server には履歴を引き継ぐ thread/resume と、実行中の turn に指示を補う turn/steer もあります。文脈を保持する製品なら、ユーザーの入力ごとに新しい thread を作らないでください。

単純なジョブのためにプロトコルクライアントを自作すると、メッセージ、thread、承認、エラーを自分たちで管理することになります。App Server を選ぶ前に、画面側で本当に必要か確認してください。

3. 他の人が使う前に権限と停止点を決める

どちらを選ぶ場合も、読み取りと提案を編集と書き込みから分けます。最初の版はファイルパス付きの指摘だけを返します。レビュアーがコードを開き、テストを実行し、各指摘を確認します。後で Codex に編集させるなら、適切な書き込み範囲を与え、対象リポジトリを限定し、差分のレビューを必須にします。SDK ドキュメントによると、Sandbox.read_only は読み取りのみ、workspace_write はワークスペースと設定された書き込み可能なルート内への書き込みを許し、full_access はファイルシステムへのアクセスを制限しません。

App Server クライアントは承認要求とイベントに対応する必要があります。turn/completed はコードのレビューが済んだ証拠ではありません。失敗したジョブ、提案された変更、人が承認した変更を区別してください。

ツールがリポジトリやプログラミングツールを扱わず、一般的な AI への質問を送るだけなら、Python の Responses API ガイドを参考に適切な API を選んでください。Codex SDK はプログラミングエージェントの作業向けであり、Responses API の別名ではありません。

4. 三つの状況で試作品を検証する

明らかにテストが不足しているリポジトリ、明白な問題がないリポジトリ、読み取り権限が足りないリポジトリの三つを試します。要求、権限、応答、エラー、レビュアーの結論を記録します。権限不足で自動的に権限が広がらないこと、問題が見当たらない時に問題を捏造しないこと、指摘が人の再確認できる場所を示すことを確かめます。

App Server ではさらに、turn の途中でクライアントが切断された場合、承認が拒否された場合、古い thread を再開する場合を試します。SDK ではジョブの失敗と、結果を社内システムへ保存する処理を試します。目標は最高の実行結果のスクリーンショットを残すことではなく、作業が完了しなかった時にユーザーに何が見えるか把握することです。

結果の例

ある架空のチームがリポジトリ管理画面に「テストの抜けを探す」ボタンを追加するとします。初期段階では指摘一覧だけでよいため、Sandbox.read_only を指定した Python SDK を選びます。テスト用リポジトリでジョブを実行し、レビュアーが確認する三つの項目を得ます。コードを調べると、一つは正しく、一つは別ディレクトリのテストで既にカバーされ、残り一つは判断材料が不足していました。システムは三つの状態を記録し、pull request を自動作成しません。

数週間後、チームは進捗の表示、同じ会話での追加質問、画面からのコマンド承認を望むようになります。そこでローカルの App Serverを試作し、thread、turn、承認の流れを評価します。これは説明のための例であり、SDK や App Server が必ず三件の問題を正確に見つけるという意味ではありません。

結果を良くするヒント

ユーザー画面から選ぶ。 ジョブを実行して結果を受け取るだけなら、SDK が簡潔な出発点です。履歴、イベント、承認ボタンが製品に必要なら App Server を検討します。

ライブラリを権限設計と取り違えない。 SDK は Codex を呼ぶ方法です。サンドボックスとアクセス権は別途設計が必要です。read_only が使えるなら、プロンプトの「編集しないで」だけを境界にしないでください。

試作品を小さく保つ。 サンプルのリポジトリ一つ、ボタン一つ、レビュアー一人、テストケース三つの方が、大きなダッシュボードをいきなり作るより設計上の問題を早く発見できます。

知っておくべき制限

公式ドキュメントでは、App Server の WebSocket 接続は現在実験的で、本番ワークロードには対応していないとされています。ローカルの試作品には stdio を使い、リモート接続を設計する前に対応状況を再確認してください。localhost の例をそのまま使って、認証、TLS、アクセス権を処理せずに WebSocket を社内ネットワークやインターネットへ公開しないでください。この記事は本番環境へのデプロイ手順ではありません。

SDK のサンプルを見て、すべてのアカウントで同じモデルを使えると判断しないでください。そのためコードはデフォルトモデルを使います。実際には認証し、ワークスペースの方針を満たし、アクセス権を確かめる必要があります。エージェントの結果は誤ったり欠けたりすることがあります。担当者がコードを読み、テストを確認し、変更を承認してください。

よくある質問

SDK と App Server は別の Codex を使うのですか？ いいえ。Codex を制御する二つのインターフェース階層です。OpenAI のドキュメントによると、Python SDK は JSON-RPC 経由でローカルの app-server を制御します。

SDK を CI や定期ジョブで使えますか？ はい。公式ドキュメントは CI/CD と自動ジョブを SDK の用途として挙げています。ただし環境に応じて認証、権限、エラー処理、レビューを設計する必要があります。

SDK ではなく App Server が必要なのはいつですか？ 会話履歴、承認、進捗通知、thread と turn の制御を持つクライアントが製品に必要な時です。ジョブの結果だけでよければ SDK から始めます。

Python のサンプルは Codex を実際に動かしましたか？ いいえ。コードは公式ドキュメントと照合し、構文も確認しました。ただし実行には、手元のパッケージ、認証、リポジトリ、権限が関わります。

権限エラーを避けるため full_access を使うべきですか？ デフォルトにはしないでください。コードレビューの例には read_only で足ります。後で編集が必要になったら書き込み範囲を限定し、承認を記録し、適用前に差分を確認します。

主な出典: OpenAI Learn の Codex SDK と Codex App Server。2026年10月5日に確認。#Codex #CodexSDK #AppServer #AI開発 #VibeCoding