Codex

Codex は、OpenAIが提供するコーディングエージェントです。ターミナルで Codex CLI を使用したり、デスクトップアプリでプロジェクトやタスクを管理したりできます。カスタムモデルProviderを構成すると、Codex は AGTCloud の OpenAI Responses 互換エンドポイントを使用できます。

モデルが異なれば、ツールの呼び出し、推論、マルチエージェント、およびコンテキストの長さの対応範囲が異なる場合があります。現在のAPI Keyで利用可能で、Responses プロトコルをサポートしているモデルを選択してください。

事前準備

開始前に、次の項目を確認してください。

ターミナル環境と開く必要があるローカルプロジェクトを準備します。
AGTCloudに登録してログインします。
API Keys ページでトークンを作成します。
現在のトークンが利用可能で、Responses プロトコルをサポートしているモデルIDをモデルマーケットプレイスからコピーします。

Codexをインストールする

現在の環境に応じたインストール方法を選択してください。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

インストールが完了したら、ターミナルを再度開き、バージョンを確認します。

codex --version

API Keyを設定する

Codex は、カスタム Provider で指定された環境変数から API Keyを読み取ります。このチュートリアルでは、OpenAI または他のプラットフォームキーとの混合を避けるために、独立した AGTCLOUD_API_KEY を使用します。

一時的に設定する

次の設定は、現在のターミナルセッションでのみ有効です。

export AGTCLOUD_API_KEY="your-api-key"

永続的に設定する

ターミナルを開くたびに自動的に有効にしたい場合は、変数をシェル設定ファイルまたは Windows ユーザー環境変数に書き込むことができます。

~/.zshrc を編集して以下を追加します。

export AGTCLOUD_API_KEY="your-api-key"

保存後に構成をロードします。

source ~/.zshrc

API Keyを config.toml に書き込まないでください

config.toml 環境変数名のみが保存されます。 API Key はローカル環境設定にクリアテキストで保存されます。この方法は個人の信頼できるデバイスでのみ使用してください。

AGTCloud Providerを設定する

Codex のユーザーレベルの設定は ~/.codex/config.toml にあります。ファイルが既に存在する場合は、まずそれをバックアップしてから、AGTCloud Providerを既存の構成にマージしてください。他の設定を直接上書きしないでください。

mkdir -p ~/.codex

if [[ -f ~/.codex/config.toml ]]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi

~/.codex/config.toml に次を追加します。

model_provider = "agtcloud"
model = "MODEL_ID"

[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"

設定項目	機能
`model_provider`	デフォルトのモデルProviderを AGTCloud に切り替えます
`model`	Codex で使用されるモデルIDを指定します。
`base_url`	このページに表示されている AGTCloud API アドレスに Responses リクエストを送信します。
`env_key`	保存する環境変数名を指定 API Key
`wire_api`	OpenAI Responses プロトコルを使用して指定します

Providerはユーザーレベルの設定に配置する必要があります

プロジェクト内の .codex/config.toml はプロジェクト設定を保存できますが、model_provider と model_providers を上書きすることはできません。上記の Provider 設定をユーザーディレクトリの ~/.codex/config.toml に配置してください。

モデルを選ぶ

MODEL_ID は、実際のモデル名ではなく、置き換える必要があるプレースホルダーです。モデルマーケットプレイスから、現在のAPI Keyで利用可能で Responses プロトコルをサポートしているモデルIDをコピーし、config.toml の MODEL_ID を置き換えてください。

Codex CLI を入力すると、/model を使用してモデルを表示または切り替えることができます。カスタム Provider のオプションの範囲は、Codex のバージョンと現在の API Key によって異なります。対象のモデルが表示されない場合は、config.toml 内の model を直接更新してください。

Codex CLIを使用する

プロジェクトディレクトリへ移動する

cd /path/to/your/project

Codexを起動する

codex

現在の設定を確認する

Codex で実行します。

/status

現在の Provider、モデル、および設定ファイルが期待どおりであることを確認します。 Base URL は、このページに表示される /v1 API アドレスである必要があり、重複する /v1/v1 があってはなりません。

読み取り専用テストを開始する

README.md を含むテストプロジェクトに次のように開きます。

README.mdを読み、プロジェクトの目的を3点で要約してください。ファイルは変更しないでください。

内容が正常に返されれば、基本的な接続を確認できます。この手順では通常の API 利用量が発生します。

Codex Appを使用する

アプリを再起動する

~/.codex/config.toml と環境変数を保存した後、Codex アプリを完全に終了し、再度開きます。

ローカルプロジェクトを開く

デスクトップアプリで Codex に切り替え、機密コードが含まれていないテストプロジェクトを選択します。

モデルを確認して確認してください

現在のモデルが config.toml と一致していることを確認してから、CLI と同じ README 読み取り専用タスクを使用して確認します。

アプリの環境変数の読み込みはバージョンと起動方法によって異なります

Codex アプリは Codex のローカル設定を再利用しますが、デスクトップアプリケーションがシェル環境変数をロードする方法はバージョンやオペレーティングシステムによって異なる場合があります。 CLI は利用可能だが、アプリが API Keyを読み取れない場合は、ユーザーレベルの設定変数と環境変数を確認する前に、まずアプリを完全に再起動します。

よくある質問

現象	優先して確認する項目	対処方法
`codex` コマンドが見つかりません	インストール結果と `PATH`	ターミナルを再度開き、`codex --version` を実行し、必要に応じて公式のインストールコマンドを再実行します。
API Key が読み込まれない	現在のプロセスで `AGTCLOUD_API_KEY` が有効か	ターミナルまたはアプリを開き直し、ユーザー環境設定を再読み込みします
Provider 構成が有効になりません	誤ってプロジェクトレベル `.codex/config.toml` に書き込まれたかどうか	`model_provider` と `model_providers` を `~/.codex/config.toml` に移動します
リクエストパスに `/v1/v1` が含まれる	`base_url` に `/v1` を重複して追加していないか	このページに表示されている `https://api.agtcloud.cn/v1` をそのまま指定します。
`401` を返す	API Key と環境変数	有効な API Keyを使用し、`env_key` 名が一致することを確認してください。
`403` を返す	トークンの権限、モデルの権限、およびアカウントのステータス	コンソールでトークンとモデルの利用可能な範囲を確認します
`404` を返す	Base URL、Responses エントリとモデルID	`base_url` を確認し、現在のAPI Keyで利用可能なモデルIDを再コピーします。
モデルが存在しないか、利用できません	モデルの可視性と Responses プロトコルのサポート	モデルマーケットプレイスから完全な ID をコピーし、現在のキーで呼び出すことができるモデルを選択します
CLI 正常ですが、アプリは設定を読み取れませんでした	アプリのバージョン、設定パス、環境変数	アプリを完全に再起動します。まず、CLI を使用して同じユーザーレベルの設定を確認します。
一部の高度な機能を利用できない	対象モデルの機能と現在の対応範囲	まず基本的な読み取り専用タスクで検証します。高度な機能の対応状況は、実際の API 呼び出し結果で確認してください。

特定できない問題が発生した場合は、リクエスト時間、Base URL、モデルID、HTTP ステータス、および機密情報を除いたエラー情報を記録し、エラーとトラブルシューティングを確認してください。完全なAPI Keyを送信しないでください。

セキュリティ上の推奨事項

Codex に別の API Keyを作成して、アクセス許可の管理と認証情報の無効化を容易にします。
実際のキーを config.toml、コード、リポジトリ、スクリーンショット、ログ、または共有スクリプトに書き込まないでください。
共有デバイスまたはチーム環境では、オペレーティングシステムの認証情報管理または組織的に一貫したキー配布スキームを優先します。
API Keyの漏えいの疑いがある場合は、コンソールで直ちに無効にするか削除し、新しいキーを作成します。

次に、API Key、Base URL と認証、OpenAI Responses、エラーとトラブルシューティングを参照してください。

このページの内容