Codex CLI、IDE 拡張機能、Codex Cloud から利用している Codex は、プログラムからも制御できます。
次のような用途には SDK を使います。
- CI/CD パイプラインの中で Codex を制御する
- Codex と連携して複雑な開発タスクを実行する独自のエージェントを作成する
- 社内のツールやワークフローに Codex を組み込む
- 自分のアプリケーションに Codex を統合する
CI ジョブを含むコーディングタスクの自動化には、Codex SDK を使います。認証、会話履歴、承認、ストリーミングで届くエージェントのイベントを扱う独自のクライアントを構築するには、Codex App Server を使います。
codex mcp-server コマンドとスタンドアロンの codex-mcp-server バイナリは削除されました。既存の連携には Codex App Server を使ってください。
ベータ版を利用できる方が、リポジトリや変更内容をスキャンして、構造化されたセキュリティ検出結果とスキャン範囲を確認するには、Codex Security TypeScript SDK を使ってください。
TypeScript ライブラリ
TypeScript ライブラリを使うと、アプリケーションからローカルの Codex スレッドを開始し、同じスレッドで作業を続けたり、過去のスレッドを再開したりできます。
このライブラリはサーバー側で使います。Node.js 18 以降が必要です。
インストール
まず、npm で Codex SDK をインストールします。
npm install @openai/codex-sdk使い方
Codex でスレッドを開始し、プロンプトを渡して実行します。
import { Codex } from "@openai/codex-sdk";
const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
"Make a plan to diagnose and fix the CI failures"
);
console.log(result.finalResponse);run() を再度呼び出すと、同じスレッドで作業を続けられます。過去のスレッドを再開するには、スレッド ID を指定します。
// running the same thread
const result = await thread.run("Implement the plan");
console.log(result.finalResponse);
// resuming past thread
const threadId = thread.id!;
const thread2 = codex.resumeThread(threadId, {
sandboxMode: "workspace-write",
});
const result2 = await thread2.run("Pick up where you left off");
console.log(result2.finalResponse);連携先のシステムが作成したスレッドを識別できるようにするには、スレッドの作成時に threadSource を設定します。たとえば、codex.startThread({ threadSource: "ci" }) を呼び出すと、スレッドに ci というラベルが付きます。スレッドを再開しても、作成元の情報は保持されます。
設定の上書き
config を渡すと、Codex の設定を構造化形式で指定できます。ドット区切りのパスで表現できないキーには configOverrides を使い、TOML 文字列をそれぞれ個別の --config 引数として渡します。
const codex = new Codex({
config: { default_permissions: "audit" },
configOverrides: [
'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',
],
});TOML 文字列で指定した値は、構造化形式の config よりも優先されます。SDK はその後で baseUrl などの管理対象の設定とスレッド固有のオプションを適用するため、これらはどちらの指定よりも優先されます。この方法で設定を上書きしても、Codex の設定ファイルは変更されません。
詳しくは、TypeScript ライブラリのリポジトリを参照してください。
Python ライブラリ
Python SDK は、JSON-RPC を介してローカルの Codex App Server を制御します。Python 3.10 以降が必要です。配布されている SDK の依存関係には、バージョンが固定された Codex CLI ランタイムが含まれています。
インストール
SDK をインストールするには、次のコマンドを実行します。
pip install openai-codex配布版の SDK は、バージョンが固定されたランタイムを自動的に使います。ローカルにある特定の Codex 実行ファイルを使いたい場合に限り、CodexConfig(codex_bin=...) を渡してください。
Python SDK には安定版があります。pip install openai-codex を実行すると、最新の安定版がインストールされます。より新しいプレリリース版を使うには、pip install --pre openai-codex を実行してください。
使い方
Codex を起動してスレッドを作成し、プロンプトを渡して実行します。以下の例で使う GPT-6.1 Sol は、サインイン中のアカウントで利用できる必要があります。利用できない場合は、model を省略すると、デフォルトに設定されているモデルが使われます。詳しくは、プラン別の GPT-6.1 Sol の利用可否を参照してください。
from openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(
model="gpt-6.1-sol",
sandbox=Sandbox.workspace_write,
)
result = thread.run("Make a plan to diagnose and fix the CI failures")
print(result.final_response)アプリケーションがすでに非同期で動作している場合は、AsyncCodex を使います。
import asyncio
from openai_codex import AsyncCodex
async def main() -> None:
async with AsyncCodex() as codex:
thread = await codex.thread_start(model="gpt-6.1-sol")
result = await thread.run("Implement the plan")
print(result.final_response)
asyncio.run(main())別のシステムからのコンテンツの受け渡し
ツール、アプリケーション、または別のエージェントからコンテンツを受け取った場合は、ExternalMessage を thread.run() または thread.turn() の入力全体として渡します。たとえば、ExternalMessage(tool_name="issue_tracker", content=issue_body) では、イシューの説明を提供したツールを明示しています。Codex はその説明をツールの出力として扱い、ユーザーや開発者の指示よりも低い優先度を割り当てます。このメッセージで新しいターンを開始することも、進行中の通常のターンにメッセージを追加することもできます。
履歴を読み込まずにスレッドを再開
include_turns=False を codex.thread_resume() または codex.thread_fork() に渡すと、過去のターンをレスポンスに含めずに済みます。その場合も、モデルはスレッドのコンテキストを保持しています。後から履歴を取得するには、thread.read(include_turns=True) を呼び出します。
Codex CLI 0.166.0 以降では、スレッドを再開する際に、そのスレッドに保存されているモデルプロバイダーを使います。プロバイダーを切り替える場合は、codex.thread_fork(thread_id) を呼び出すと、新しいプロバイダーで同じ履歴を引き継いで作業を続けられます。
1 ターンだけのサービスティアの設定
新しいターンに限ってサービスティアを指定するには、turn_service_tier を run() または turn() に渡します。たとえば、turn_service_tier="default" を指定すると、そのターンは標準速度で実行されます。そのターンと後続のターンのサービスティアを変更するには、service_tier を渡します。進行中のターンに参加する場合は、そのターンのサービスティアが維持されます。
自分で用意した Codex 実行ファイルを使う場合、ExternalMessage の使用、スレッドを再開またはフォークする際の include_turns の明示的な指定、および turn_service_tier の使用には、Codex CLI 0.151.0 以降が必要です。
サンドボックスのプリセット
スレッドを作成するときも、後続のターンでファイルシステムへのアクセス権を変更するときも、同じ Sandbox プリセットを使えます。
from openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Make the requested change.")
review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)利用できるプリセットは次のとおりです。
Sandbox.read_only：ファイルは読み取り専用で、書き込みはできません。Sandbox.workspace_write：ファイルを読み取れます。ワークスペース内と、書き込み可能に設定されたルートディレクトリ配下では、書き込みもできます。Sandbox.full_access：ファイルシステムへのアクセスを制限せずに実行します。
sandbox= を省略すると、App Server は設定済みのデフォルト値を使います。run(...) または turn(...) に渡したサンドボックス設定は、そのターンと、同じスレッドの後続のターンに適用されます。
詳しくは、Python ライブラリのリポジトリを参照してください。