Amazon ECS と Bedrock で LiteLLM を用いた OpenAI ChatGPT Codex の設定

OpenAI ChatGPT Codex と LiteLLM を組み合わせることで、生成 AI コーディングエージェントに対する集中型の企業管理が可能になります。これらのエージェントは、開発者がリポジトリを理解し、コードを書き、テストを実行し、多段階のエンジニアリングタスクを完了するのを支援します。組織が個々の実験から管理された導入へと移行するにつれ、チームはモデルへのアクセス制御と消費量の追跡を一貫した方法で行う必要があります。また、予算やレート制限の適用、モデルアクセスパスの監視も不可欠です。

OpenAI Codex（Codex）は、開発者のワークステーション上でタスクループを実行します。ローカルファイルを読み取り、ローカルのサンドボックスと承認設定に基づいて許可されたツールを実行します。顧客は、モデル推論を自社の AWS アカウント内のインフラストラクチャ経由でルーティングすることも引き続き可能です。

本稿では、Amazon Elastic Container Service（Amazon ECS）上で顧客が運用する LiteLLM ゲートウェイのデプロイ方法を解説します。また、これを Amazon Bedrock 上の OpenAI モデルに接続し、Codex がゲートウェイの Responses API を使用するように設定する方法を示します。さらに、セマンティック継続、ストリーミング、関数呼び出しの有効性検証についても説明します。最後に、直接 AWS IAM Identity Center にアクセスするか、Portkey などのマネージドゲートウェイを利用する方が適しているケースについて解説します。

完全な実装は、guidance-codex リポジトリ で確認できます。本記事で主軸とする手順については、AWS 上の LiteLLM クイックスタート をご参照ください。

ソリューションの概要

以下のアーキテクチャでは、Codex と Amazon Bedrock の間に LiteLLM を配置します。LiteLLM はモデル認証、ルーティング、予算管理、レート制限、ゲートウェイのテレメトリを統括する共通の制御ポイントとなります。一方、ローカルでのタスク処理とツール実行ループは Codex が引き続き担当します。

以下の図は、開発者のワークステーションからゲートウェアを経由して Amazon Bedrock へ、そして戻ってくるまでの一連のリクエストフローを示しています。インフラ内を単一のモデルターンが通過する様子を、番号付きの 5 つのステップで追跡してみましょう。

Figure 1: Codex は LiteLLM を通じてモデルリクエストを送信しますが、ローカルのツール実行は開発者のワークステーション上で行われます

リクエストフローは以下の 5 つのステップで進行します。

• Codex が現在のタスクコンテキストと利用可能なツールの定義を、ゲートウェイの /v1/responses エンドポイントへ送信します。
• Application Load Balancer と AWS WAF がネットワーク層および Web レイヤーでの制御を適用した後、リクエストを AWS Fargate 上の LiteLLM に転送します。
• LiteLLM は呼び出し元の認証を行い、設定されたモデルと消費ポリシーを確認します。その後、ECS タスクロールを使用して Amazon Bedrock 上で承認されたモデルを呼び出します。

Amazon Bedrock は、LiteLLM を介してテキストまたは関数呼び出しを返します。

モデルがツールの使用を要求した場合、Codex はそのサンドボックス内および承認ポリシーに基づいてローカルでツールを実行します。その後、Codex は次の Responses リクエストでツール結果を LiteLLM を通じて送信し、このループは継続されます。

今回の参照デプロイメントでは、以下のサービスも併用されています。

• LiteLLM の状態、使用量、予算データを管理するために Amazon Relational Database Service (Amazon RDS) for PostgreSQL を利用しています。
• ゲートウェイおよびスコープ付きキーの保存には、AWS Secrets Manager と AWS Key Management Service (AWS KMS) を採用しました。
• 監視とデプロイメントの健全性確認には、Amazon CloudWatch のログ、Container Insights、アラーム機能を活用しています。
• イミュータブルなゲートウェイイメージの保管には、Amazon Elastic Container Registry (Amazon ECR) を使用しています。
• 必要に応じて、AWS WAF のマネージド保護機能や送信元 IP によるレート制限も設定可能です。

この分離構造は重要です。ゲートウェイは AWS アカウント内で汎用的なシェルを受け取るわけではなく、Codex のローカル承認プロセスを置き換えるものでもありません。あくまで各モデルのターン（応答サイクル）を統制する役割を果たします。

なぜこのパターンに LiteLLM を使うのか

LiteLLM は、API 互換エンドポイントの背後でモデルルーティング、バーチャルキー、予算管理、レート制限、使用量テレメトリを提供するオープンソースの AI ゲートウェイです。本パターンでは、顧客は LiteLLM とその基盤インフラを自社の AWS アカウント内で運用します。

ネイティブの AWS 認証、AWS Identity and Access Management (IAM) ポリシー、および AWS CloudTrail ログが顧客要件を満たす場合、Amazon Bedrock への直接アクセスが最も複雑度が低い選択肢となります。一方、開発者やチーム、モデルプロバイダー間の一貫した追加制御が必要な場合は、ゲートウェイの導入が有効です。

LiteLLM は、以下のようなニーズがある場合に、ユーザーが運用する有用なオプションです。

• 承認されたモデルエイリアスのみ許可する。
• ユーザーまたはチームスコープのゲートウェイキーを発行する。
• 厳格な予算や、1 分あたりのリクエスト数・トークン数の制限を適用する。
• ルーティングとフォールバックポリシーを一元管理する。

• アップストリームのモデルが共有 ECS タスクロールを使用している場合でも、ゲートウェイレベルのアイデンティティを維持する。
• ゲートウェイ、データベース、ネットワーク、ログ、アップグレードプロセスを自社の AWS アカウント内で運用する。

このアプローチにおける主なトレードオフは運用責任にあります。チーム側で、ゲートウェイの可用性、データベースのライフサイクル管理、バージョンアップグレード、インシデント対応、キャパシティプランニングをすべて担当することになります。

Amazon ECS 上で Codex 用の LiteLLM ゲートウェイを展開する

このセクションでは、LiteLLM ゲートウェイの展開方法、Amazon Bedrock との接続方法、そして Codex からリクエストをゲートウェイ経由で送信するための設定手順について解説します。

事前準備

本チュートリアルを実行するには、以下の環境が必要です。

• AWS アカウントおよび、仮想プライベートクラウド (VPC)、Amazon ECS、Elastic Load Balancing、Amazon RDS、Amazon ECR、AWS WAF、IAM、AWS KMS、Secrets Manager、CloudWatch リソースの作成権限。

デプロイ先の AWS リージョンで、選択した OpenAI モデルへの Amazon Bedrock へのアクセス権限が必要です。

認証済みプロファイルを持つ AWS Command Line Interface (AWS CLI) バージョン 2 も用意してください。

Docker と Buildx のインストールも必須です。

Codex CLI を利用可能な状態にしておきます。

Python 3 の環境も必要になります。

HTTPS デプロイを行う場合は、パブリックな Amazon Route 53 ホストゾーンか、同じリージョン内の既存の AWS Certificate Manager (ACM) 証明書が必要です。

今回の手順検証は、ゲートウェイエイリアス openai.gpt-5.5 を用いて米国東部（バージニア北部）リージョン（us-east-1）で行いました。このエイリアスは LiteLLM の設定において bedrock_mantle/openai.gpt-5.5 にマッピングされます。モデルの利用可否はアカウントやリージョンによって異なります。

コストに関する注意: このソリューションでは、アプリケーションロードバランサー、Fargate タスク、Amazon RDS、AWS WAF、ログ、およびモデル推論など、課金対象のリソースが作成されます。サンプル VPC を利用するとネットワーク関連の料金が発生する可能性もあります。ご自身のリージョンにおける現在の価格を確認し、手順完了後のクリーンアップセクションを必ず参照してください。

Amazon ECS への LiteLLM のデプロイ

リポジトリをクローンして、ローカルのデプロイ環境用ファイルを作成します：

git clone https://github.com/openai-on-aws/guidance-codex.git
cd guidance-codex
git checkout feat/enterprise-gateway-readiness

cp deployment/litellm/.env.deploy.example \
deployment/litellm/.env.deploy

実際の .env.deploy ファイルは Git によって無視されます。ここでは、使用する AWS プロファイル、リージョン、ソース CIDR、DNS または証明書に関する値を設定してください。以下の抜粋は、本番環境向けの設定を示しています：

AWS_PROFILE=your-profile
AWS_REGION=us-east-1
BEDROCK_REGION=us-east-1

ENABLE_TLS=true
GATEWAY_DOMAIN_NAME=codex-gateway.example.com
ROUTE53_HOSTED_ZONE_ID=Z0123456789EXAMPLE
ALB_CERTIFICATE_ARN=
ALLOWED_CIDR=203.0.113.10/32

ENABLE_WAF=true
DB_MULTI_AZ=true
DESIRED_COUNT=2
MIN_TASK_COUNT=2
MAX_TASK_COUNT=10

既存の証明書を使用する場合は、ROUTE53_HOSTED_ZONE_ID の代わりに ALB_CERTIFICATE_ARN を設定してください。カスタマーランディングゾーンを利用する場合、本番環境デプロイガイドに記載されている通り、既存の VPC と、パブリックサブネット、プライベートアプリケーションサブネット、そしてプライベートデータベースサブネットをそれぞれ用意する必要があります。

読み取り専用の事前チェックを実行します。

make litellm-check
# Direct helper invocation used by Make:
# deployment/scripts/litellm-stack.sh check

この事前チェックでは、AWS CLI v2、AWS 認証情報、Docker の存在、不変なイメージ参照、リージョンの一貫性、CIDR の制限、TLS 入力、ローカルドキュメントへのリンク、そして cfn-lint が利用可能な場合の AWS CloudFormation 構文が検証されます。

レビュー済みの LiteLLM イメージをビルドし、Amazon ECR にプッシュします。

CONFIRM_AWS_WRITE=1 make litellm-build
# Direct helper invocation used by Make:
# CONFIRM_AWS_WRITE=1 deployment/scripts/litellm-stack.sh build

本ビルドでは、ダイジェスト固定化された LiteLLM ベースイメージを使用し、生成された ECR のダイジェストをローカルの無視対象のステートファイルに記録します。CloudFormation には可変なイメージタグではなく、不変のダイジェストが渡されます。

内部ヘルパーは、不変の Amazon ECR リポジトリを作成または再利用し、Amazon ECR にサインインした上で docker buildx build --push を実行して、プッシュされたイメージのダイジェストを解決します。

CloudFormation の変更セットを実行せずに作成するには：

make litellm-plan
# Direct helper invocation used by Make:
# deployment/scripts/litellm-stack.sh plan

これはネットワークまたはゲートウェイテンプレートに対して aws cloudformation deploy --no-execute-changeset を呼び出す処理です。レビュー可能な変更セットを作成しますが、実行はしません。

変更セットを確認した後、デプロイを実行します：

CONFIRM_AWS_WRITE=1 make litellm-deploy
make litellm-status
# Direct helper invocations used by Make:
# CONFIRM_AWS_WRITE=1 deployment/scripts/litellm-stack.sh deploy
# deployment/scripts/litellm-stack.sh status

デプロイヘルパーは、まずネットワークスタックに対して aws cloudformation deploy を実行し、続いて LiteLLM ゲートウェイのスタックをデプロイします。ステータスヘルパーは aws cloudformation describe-stacks を実行して、各スタットのステータスと出力情報を表示します。

ECS サービスでは、デプロイメントのサーキットブレーカーによるロールバックと、Application Load Balancer のヘルスチェックが利用されます。参照テンプレートには、ターゲット追跡型オートスケーリング、暗号化されたログおよびデータ、RDS バックアップ、ALB アクセスログ、運用アラームの設定も含まれています。

顧客環境では、ENABLE_TLS=true を設定し、信頼できる DNS 名と ACM 証明書を使用してください。また、Application Load Balancer は承認された企業ネットワークまたは VPN の CIDR に制限します。ECS タスクと Amazon RDS はプライベートサブネットに配置し、ECS タスクのポート 4000 や PostgreSQL のポート 5432 を公開しないように注意してください。

スコープ付きゲートウェイIDの作成

開発者に LiteLLM のマスターキーを配布しないでください。無視されるデプロイメントファイルで、ユーザーまたはチームの ID とポリシーを設定します：

CODEX_API_SECRET_ID=codex-litellm-gateway/alice-key
CODEX_KEY_ALIAS=alice@example.com
CODEX_KEY_USER_ID=alice@example.com
CODEX_KEY_MODELS=gpt-5.5
CODEX_KEY_MAX_BUDGET=50
CODEX_KEY_BUDGET_DURATION=30d
CODEX_KEY_TPM_LIMIT=100000
CODEX_KEY_RPM_LIMIT=1000

キーのプロビジョニングは以下の通りです：

CONFIRM_AWS_WRITE=1 make litellm-provision-key
# Direct helper invocation used by Make:
# CONFIRM_AWS_WRITE=1 deployment/scripts/litellm-stack.sh provision-key

このヘルパーは子プロセス内でマスター認証情報を解決し、設定されたモデル、予算、レートポリシーを指定して LiteLLM の /key/generate API を呼び出します。生成されたキーは KMS で暗号化された Secrets Manager シークレットに直接書き込まれます。いずれの認証情報もコマンド引数に含まれたり、ターミナルに出力されたりすることはありません。

エンタープライズ展開では、各開発者プロファイルに対して、割り当てられたスコープ付きキーシークレットを読み取り、スタックの KMS キーで復号化する権限のみを付与します。チームや環境ごとに異なるシークレットパスと IAM ポリシーを使用してください。

Codex の設定

プロバイダーブロックを生成します：

make litellm-codex-config
# Direct helper invocation used by Make:
# deployment/scripts/litellm-stack.sh codex-config

ヘルパーは、CloudFormation からデプロイされたゲートウェイエンドポイントを読み取り、以下の Codex プロバイダー設定を出力します。ただし、ユーザー設定ファイルに自動的に書き込むわけではありません。

この出力結果を手動で、ユーザーレベルの ~/.codex/config.toml に追加してください。プロバイダー情報と認証設定は、必ずユーザーレベルの設定ファイルに記載する必要があります。Codex はプロジェクトローカルの .codex/config.toml ファイル内のこれらの設定を無視します。

生成される設定ファイルの形式は以下の通りです。

model = "gpt-5.5"
model_provider = "litellm-gateway"
web_search = "disabled"

[model_providers.litellm-gateway]
name = "LiteLLM Gateway"
base_url = "https://codex-gateway.example.com/v1"
wire_api = "responses"

[model_providers.litellm-gateway.auth]
command = "/absolute/path/to/python3"
args = [
"/absolute/path/to/deployment/scripts/aws-secret-auth.py",
"--aws-cli", "/absolute/path/to/aws",
"--region", "us-east-1",
"--secret-id", "codex-litellm-gateway/alice-key",
"--field", "LITELLM_API_KEY",
"--profile", "developer-profile",
"print-token"
]
timeout_ms = 30000
refresh_interval_ms = 300000

Codex は標準入力を介さずに認証コマンドを実行し、その標準出力からベアータークンを取得します。ヘルパーは指定された AWS プロファイルを使用して現在のシークレットを取得するため、トークンは config.toml 内に保存されません。

LiteLLM の管理 UI において、Models + Endpoints ページには開発者が利用可能な安定したエイリアスと、それらが Amazon Bedrock とどのようにマッピングされているかが表示されます。これにより、開発者が Codex 設定をプロバイダー固有のモデル ID に直接結合するのではなく、ゲートウェイ経由でエイリアスを参照していることを視覚的に確認できます。

次の図は、2 つのモデルエイリアスが設定された Models + Endpoints ページを示しています。Codex の設定に進む前に、ゲートウェイのエイリアスがリストに表示されているか必ず確認してください。

Figure 2: The model management view shows the gpt-5.4 and gpt-5.5 aliases and their Amazon Bedrock Mantle mappings

Test Codex through LiteLLM

新しいインタラクティブな Codex セッションを開始し、/status コマンドを実行して litellm-gateway が選択されたプロバイダーであることを確認してください。反復可能な非対話型のテストを行う場合は、まず最小限の smoke リクエストを実行します。

codex exec --sandbox read-only --ephemeral \
"Reply with exactly LITELLM_GATEWAY_OK and no other text."

コマンドは正常に終了し、LITELLM_GATEWAY_OK を表示する必要があります。次に、モデル推論とローカルツールの両方を必要とするタスクでエージェントループを実行してください。

codex exec --sandbox read-only --ephemeral \
"Read README.md with shell tools and summarize the deployment architecture. Do not modify files."

Codex は、タスクとツールの定義を LiteLLM を通じて送信します。モデルがファイルの読み取りを要求した場合、Codex はそのコマンドをローカルで実行し、結果を同じゲートウェイを通じて返します。

LiteLLM の管理 UI でログを開き、リクエストログを選択してテスト期間にフィルターをかけます。以下の項目を確認してください。

• リクエストのステータスが Success になっていること。
• キーエイリアスで、専用のウォークスルー用キーまたは開発者用キーが特定されていること。
• モデルが期待される Amazon Bedrock のマッピングに解決されていること。
• トークン数、リクエストの実行時間、コストが正しく表示されていること。

ツール使用タスクでは、Codex が後続のレスポンス要求でツール結果を送信するたびに、複数の行が作成されます。

LiteLLM で行が表示される前に 403 レスポンスが返された場合、これは通常、アップストリームのネットワーク障害または AWS WAF によるブロックを示しています。一方、401 レスポンスは、ゲートウェイ認証情報が不足しているか無効であることを意味します。スクリーンショットには、プロンプトやレスポンス内容、生キー、完全なリクエスト ID、あるいは実際の従業員名などを公開しないでください。

以下の図は、複数の Codex リクエストが正常にゲートウェイを通過した後の LiteLLM のRequest Logsページを示しています。このページを使用して、リクエストが Amazon Bedrock に到達しているかを確認し、ステータスコードに基づいてエラーのトラブルシューティングを行ってください。

Figure 3: リクエストログには、codex-walkthrough キーエイリアスに紐づく Codex の成功したターンが記録されており、モデル名、コスト、実行時間、最初のトークン到達までの時間が含まれています

レスポンス API 契約の検証

テキストプロンプトが成功しただけでは、エージェントワークフローが互換性があることを証明できません。Codex は基本的なチャット完了レスポンスだけでなく、より高度な要件を満たす必要があります。以下の厳格なプローブを実行してください。

make litellm-validate
# Direct helper invocation used by Make:
# deployment/scripts/litellm-stack.sh validate

このヘルパーは、スコープ内のキーを子プロセスの環境変数として解決し、デプロイされたゲートウェイに対して deployment/scripts/validate-responses-contract.py を実行します。

プローブが検証するのは以下の項目です。

• 必須のレスポンスオブジェクトフィールドと出力形状
• previous_response_id を用いた意味的な継続性
• 完了した終端レスポンスを含むサーバー送信イベント（SSE）ストリーミング
• コール ID を伴う強制された関数ツール呼び出し

継続性のテストでは、最初のレスポンスに一意のテストマーカーを記録し、その後のレスポンスでそれが正しく参照できるかを確認します。これにより、previous_response_id 文法上は受け付けていても、過去のレスポンス状態を保持していないゲートウェイを検出できます。

本番環境でのデプロイは完全な契約テストに合格しました。CloudFormation は正常に完了し、ECS サービスは目標タスク数に達し、デプロイのロールアウトも成功しました。ALB のターゲットは健全な状態であり、暗号化された PostgreSQL データベースも利用可能で、公衆アクセスは制限されています。

以下の図は、エンドツーエンドのデプロイ検証ダッシュボードを示しています。