OceanBase MaaSを使用したCodex CLIとCodex Appの利用

本記事では、OceanBase MaaSゲートウェイを通じてCodex CLIとCodex Appを使用する方法について説明します。

設定の説明

Codexは、OpenAIが提供するプログラミング向けインテリジェントエージェントで、以下の2つの利用方法をサポートしています：

• Codex CLI：ローカル端末でコードを読み取り、変更、実行するためのオープンソースのコマンドラインツールです。
• Codex App：そのまま使えるデスクトップのグラフィカルアプリケーションです。

Codex CLIとCodex Appは、~/.codex/config.toml設定ファイルと関連する環境変数を共有します。一度設定すれば、CLIとAppで使用できます。

OceanBase MaaSゲートウェイに接続すると、GPTやCodexなどのシリーズモデルを使用できるようになり、OpenAI公式APIに直接アクセスする必要はありません。

Codexのインストール

npm install -g @openai/codex

設定手順

MaaS API Keyの取得

OceanBase MaaSコンソール、または社内の手続きを通じてAPI Keyを申請します。形式は通常sk_xxxxです。API Keyは大切に保管し、コードリポジトリには絶対に提出しないでください。詳細な操作については、AI API Keyの管理を参照してください。

Shell環境変数の設定（推奨）

API KeyをShell設定ファイルに書き込み、Codexが起動するたびに自動的に読み取れるようにします。

1. 現在ご利用のShellを確認します。

   echo "$SHELL"
   

   • 出力が /bin/zsh の場合：エディタを使用して ~/.zshrc を開きます。例えば、nano ~/.zshrc または vim ~/.zshrc を実行します。
   • 出力が /bin/bash の場合：エディタを使用して ~/.bashrc を開きます。例えば、nano ~/.bashrc または vim ~/.bashrc を実行します。

2. Shell設定ファイル（zshを例とする）を開き、ファイルの末尾に以下の内容を追加します。

# ============ OceanBase MaaS + Codex設定 =============
export MAAS_API_KEY="sk_xxxx"   # ご自身のMaaS APIキーに置き換えてください

3. 設定を有効にします。

   source ~/.zshrc   # zsh
   # または
   source ~/.bashrc  # bash
   

Codexの設定

Codexの設定ファイルを編集し、MaaSゲートウェイをモデルプロバイダーとして指定します。

1. ~/.codex ディレクトリが存在しない場合、まずそのディレクトリを作成してください。

   mkdir -p ~/.codex
   

2. エディタを使用して ~/.codex/config.toml を作成または開きます。例えば、nano ~/.codex/config.toml または vim ~/.codex/config.toml を実行し、以下の内容を記述します。

   model_provider = "maas"
   model = "gpt-5.3-codex"
   
   [model_providers.maas]
   name = "OceanBase MaaS"
   base_url = "https://ai-api-g.oceanbase.com/api/v1"
   env_key = "MAAS_API_KEY"
   wire_api = "responses"
   

   パラメータの説明は以下の表のとおりです。

   フィールド	説明
   model_provider	MaaSをモデルプロバイダーとして指定します。
   model	使用するモデルを指定します。詳細については、サポートされているモデルを参照してください。
   base_url	MaaSのOpenAI互換エンドポイントで、/api/v1 を含みます。
   env_key	APIキーを格納する環境変数名です。
   wire_api	Responses APIを使用します。

Codexの起動

source ~/.zshrc   # zsh
# または
source ~/.bashrc  # bash

cd /path/to/your/project
codex

サポートされているモデル

config.toml の model フィールドを変更することでモデルを切り替えることができます。その他の設定は変更不要です。

GPTおよびCodexシリーズ（ネイティブ名の使用を推奨）

GPTおよびCodexシリーズのモデルについては、ネイティブモデル名の使用を推奨します。例えば、gpt-5.3-codex のように指定することで、Codexがモデルを正しく認識し、推論機能やその他の専用機能を有効にできます。

# 推奨：ネイティブモデル名を使用する
model = "gpt-5.3-codex"

# 推奨されない：プロバイダープレフィックス付きのモデルIDは正しく認識されない可能性があります
model = "openai/gpt-5.3-codex"

現在のMaaSゲートウェイでサポートされているGPTおよびCodexモデル（/api/v1/models インターフェースの実際の返却結果に準拠）は以下の表のとおりです。

接続の検証

設定が完了したら、環境変数、ゲートウェイの接続性、モデル呼び出しが正常に機能するかを順次検証します。

環境変数の確認

APIキーがShell設定ファイルに書き込まれ、現在の端末環境に読み込まれていることを確認します。

test -n "$MAAS_API_KEY" && echo "MAAS_API_KEY is set"

ゲートウェイ接続性のテスト

MaaSゲートウェイにリクエストを送信し、ネットワーク接続性とAPIキーが有効であることを検証します。

curl -i -sS https://ai-api-g.oceanbase.com/api/v1/models \
  -H "Authorization: Bearer $MAAS_API_KEY" | head -c 500

Responses APIのテスト

最小化されたResponses APIリクエストを送信し、モデル呼び出しのパスが完全に利用可能であることを検証します。

curl -i -sS https://ai-api-g.oceanbase.com/api/v1/responses \
  -H "Authorization: Bearer $MAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "say ok",
    "max_output_tokens": 16
  }'

HTTP 200が返され、応答に出力テキストが含まれていれば、設定は正しいことを意味します。

故障診断

APIキーが無効または未認可

1. echo $MAAS_API_KEY を実行し、MAAS_API_KEY が設定されていることを確認します。

2. APIキーが sk_ で始まり、余分な空白や改行文字が含まれていないか確認します。

3. APIキーがMaaSコンソールで有効な状態にあることを確認します。

4. 現在のShellに応じて設定を再読み込みします。

   source ~/.zshrc   # zsh
   # または
   source ~/.bashrc  # bash
   

接続失敗

• ネットワークが ai-api-g.oceanbase.com にアクセス可能か確認します。
• config.toml 内の base_url の値が https://ai-api-g.oceanbase.com/api/v1。URLに /api/v1 を含む必要があることを確認します。
• ファイアウォールやプロキシが外出接続を遮断していないか確認します。

環境変数が反映されない

• ターミナルを再起動するか、source ~/.zshrc または source ~/.bashrc を実行します。
• echo "$SHELL" を実行し、APIキーが現在のShellに対応する設定ファイルに書き込まれていることを確認します。

設定ファイルが反映されない

• 設定ファイルのパスが ~/.codex/config.toml であることを確認します。
• cat ~/.codex/config.toml を実行して、設定ファイルの内容を確認します。
• ディレクトリが存在しない場合は、まず mkdir -p ~/.codex を実行します。
• 設定を変更した後、Codexアプリを再起動してください。

モデルが利用できない

• /api/v1/models インターフェースを呼び出し、返された結果に対象モデルが含まれていることを確認します。
• model フィールドの値がモデルリスト内の id と完全に一致するかどうかを確認します。
• GPTおよびCodexシリーズのモデルは、gpt-5.3-codex のようなネイティブ名を優先的に使用します。
• Responses APIリクエストの max_output_tokens は 16 以上でなければなりません。