Codex のインストールは難しくありません。本当に詰まりやすいのは接続設定です：API Key をどこに置くか、config.toml をどう書くか、Windows と macOS で何が違うか、なぜ VS Code はターミナル内の変数を読み取れないのか、モデルを固定すべきか……

Codex をできるだけ早く動かしたいだけなら、設定は次の 3 つの値に絞り込めます：

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

完了後、Codex CLI、Desktop、VS Code 拡張機能で ~/.codex/config.toml を共有でき、モデルは起動後に直接選択できるため、モデルを切り替えるたびに接続設定を変更し続ける必要はありません。

以下では、ゼロから設定を 1 回完了させます。

準備作業

開始前に以下を確認してください：

  • Ace Data Cloud に登録してログイン済みであること
  • 利用可能なアプリケーションを作成済み、または所有していること
  • ローカルに Node.js と npm がインストールされていること
  • ターミナルまたは PowerShell を使用できること
  • Codex CLI、Codex Desktop、または VS Code 拡張機能の少なくとも 1 つを使用する予定であること

第 1 ステップ：Ace Data Cloud API Key を取得する

Ace Data Cloud アプリケーション一覧を開き、利用可能なアプリケーションに入り、API Key をコピーします。

以下に注意してください：

  • API Key は機密認証情報であり、公開リポジトリに書き込まないでください
  • 実際の Key をチュートリアルのスクリーンショットに載せないでください
  • 環境または用途ごとに認証情報を作成・管理することを推奨します
  • 漏洩が疑われる場合は、速やかにローテーションまたは取り消しを行う必要があります

本記事では、平文の認証情報を Codex 設定ファイルへ直接書き込むことを避けるため、環境変数 ACEDATACLOUD_API_KEY を統一して使用します。

第 2 ステップ：Codex CLI をインストールする

npm を使用して Codex をグローバルインストールします：

npm install -g @openai/codex

インストール後に確認します：

codex --version

コマンドが見つからないと表示される場合は、まず npm のグローバル実行可能ディレクトリが PATH に追加されていることを確認し、その後ターミナルを再度開いてください。

主に VS Code を使用する場合は、OpenAI が公開している Codex 拡張機能もインストールできます：

code --install-extension openai.chatgpt

CLI と VS Code 拡張機能は設定ファイルを共有するため、まず Provider と環境変数を設定してから、エディタを起動して検証することを推奨します。

第 3 ステップ：API Key 環境変数を設定する

macOS / Linux：現在のターミナルセッション

export ACEDATACLOUD_API_KEY="你的 API Key"

このコマンドは、現在の Shell とその子プロセスにのみ有効です。ターミナルを閉じると変数は消えます。

macOS / Linux：永続的に有効にする

Zsh を使用している場合：

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

Bash を使用している場合：

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

共有コンピュータでは、実際の Key を含む Shell 設定を安易にコピーしないでください。チーム環境では、認証情報管理ツールと最小権限ポリシーを組み合わせる必要があります。

Windows PowerShell

setx ACEDATACLOUD_API_KEY "你的 API Key"

実行後、PowerShell を閉じて再度開いてください。setx は現在すでに開いているプロセスを自動更新しないため、既存のターミナルと VS Code では新しい値をまだ読み取れない場合があります。

現在の PowerShell セッションだけで一時的に設定する必要がある場合：

$env:ACEDATACLOUD_API_KEY="你的 API Key"

第 4 ステップ：config.toml を作成または編集する

Codex CLI、Desktop、VS Code 拡張機能は、以下の設定ファイルを共有します：

  • macOS / Linux：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml

ディレクトリが存在しない場合は、先に作成してください。

macOS / Linux：

mkdir -p ~/.codex

その後、以下を書き込みます：

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows では同じ Provider と Base URL を使用しますが、認証コマンドは PowerShell に変更します：

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

設定内の 3 つの名前は厳密に一致させる必要があります：

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Base URL にも /v1 を完全に含める必要があります。

第 5 ステップ：Codex を起動してモデルを選択する

設定を保存した後、ターミナルを再度開いて実行します：

codex

Codex に入った後、以下を実行します：

/model

現在の Provider が acedatacloud であることを確認し、その後、利用可能な一覧からモデルを選択します。

接続設定で model を固定する必要はありません。Provider とモデルの選択を分けることで、モデル切り替え時に TOML を繰り返し編集するコストを削減できます。実際のモデル名と利用可能な範囲は更新されるため、/model とプラットフォームのリアルタイム一覧を基準にしてください。

第 6 ステップ：最小リクエストで検証する

最初から Codex にリポジトリ全体のリファクタリングを要求しないでください。まずは、結果をすばやく判断できる簡単なリクエストを送信します。例：

请概括当前项目的目录结构，不要修改任何文件。

続いて、Ace Data Cloud Usage Historyを開き、リクエストが到達していることを確認し、ステータスと消費量を確認します。

最小リクエストが成功したら、ファイルの読み取り、変更案の生成、コード編集、テスト実行を段階的に試してください。

VS Code の設定ポイント

VS Code 拡張機能は同じ ~/.codex/config.toml を読み取りますが、API Key を確認できるかどうかは、拡張機能の実行プロセスの環境に依存します。

設定後は、VS Code を完全に終了してから再度開いてください。macOS / Linux で、グラフィカルインターフェースから起動した後も変数を読み取れない場合は、すでに Key を設定したターミナルから以下を実行できます：

code .

以下の環境を使用する場合は、拡張機能が実際に実行される側で変数を設定する必要があります：

  • Remote SSH：リモートホスト
  • WSL：WSL Linux 環境
  • Dev Container：コンテナ環境
  • Codespaces または類似のリモート環境：対応するリモートセッション

ローカルの Shell でのみ変数を設定しても、リモート拡張機能が自動的にそれを取得できるとは限りません。

Codex Desktop の設定ポイント

Desktop と CLI は設定ファイルを共有しますが、グラフィカルアプリケーションはターミナルで一時的に実行した export を必ずしも継承しません。

Desktop が Key を読み取れない場合：

  1. 環境変数を永続的またはシステムレベルで設定する
  2. Desktop を完全に終了する
  3. アプリケーションを再起動する
  4. Provider とモデルを再確認する

よくあるエラーのトラブルシューティング

1. 401、Unauthorized または Incorrect API Key

確認する順序：

  1. API Key が完全にコピーされているか
  2. 環境変数名が ACEDATACLOUD_API_KEY になっているか
  3. 現在のプロセスが変数設定後に起動されているか
  4. auth.command が現在のオペレーティングシステムに適合しているか
  5. 認証情報がまだ有効であるか 完全な Key をログやチャットに出力しないでください。「存在するかどうか」のみを判定する方法で変数を確認できます。

macOS / Linux：

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell：

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Provider が acedatacloud に変わらない

設定ファイルのパスと TOML の階層を確認してください。よくあるエラーには以下が含まれます：

  • ファイル名を config.toml.txt としている
  • 別のユーザーディレクトリを編集している
  • テーブル名のスペルが一致していない
  • 引用符または配列の形式が誤っている
  • 保存後にクライアントを再起動していない

3. Base URL リクエストが失敗する

アドレスが以下であることを確認してください：

https://api.acedata.cloud/v1

https:// や末尾の /v1 を省略しないでください。また、コンソールページのアドレスを誤って使用しないでください。

4. CLI では使えるが、VS Code では使えない

これは通常 Provider の設定問題ではなく、VS Code プロセスが環境変数を読み取っていないことが原因です。変数を設定したターミナルから code . を起動するか、システムレベルの変数を設定してから VS Code を完全に再起動してください。

5. WSL、SSH、またはコンテナ内で Key を読み取れない

環境変数は、Codex または拡張機能が実際に実行される環境に設定する必要があります。Windows ホスト上の setx は自動的に WSL へ書き込まれません。また、ローカル変数も自動的にリモート SSH ホストやコンテナへ渡されません。

6. 使用したいモデルが見つからない

古いモデル ID を手動で推測しないでください。/model を実行してリアルタイムの選択肢を確認し、アプリケーションの権限、残高、および現在の Provider を確認してください。

7. リクエストは到達するが、複雑なタスクを完了できない

まずタスクの範囲を絞り込んでください：Codex に読み取り専用の分析と計画作成をさせ、その後段階的に変更とテストを許可します。モデルの接続に成功したことは、すべてのリポジトリタスクを一度に完了すべきことを意味するわけではありません。複雑な変更には、依然として明確な受け入れ基準、テスト、および人手によるレビューが必要です。

推奨設定チェックリスト

最初の正式なタスクを送信する前に、項目ごとに確認してください：

  • アプリケーション一覧から有効な API Key を取得した
  • Key が ACEDATACLOUD_API_KEY に保存されている
  • Key を Git リポジトリに書き込んでいない
  • model_provider が acedatacloud である
  • Base URL が https://api.acedata.cloud/v1 である
  • auth.command がオペレーティングシステムと一致している
  • Codex または VS Code を完全に再起動した
  • /model で Provider とモデルを確認できる
  • 最小限のテストリクエストが成功する
  • Usage History で対応する呼び出し記録を確認できる

1 つの Provider で、重複設定を減らす

この接続方法の要点は、TOML をもう 1 段書くことではなく、安定した境界を構築することです：

  • API Key は環境変数で管理する
  • Provider 接続は config.toml で管理する
  • モデルは Codex 内でタスクに応じて選択する
  • 呼び出し記録と消費量は Ace Data Cloud コンソールで一元的に確認する
  • CLI、Desktop、および VS Code は 1 つの設定を共有する

認証、Provider、およびモデル選択が明確に分離されていれば、多くの「なぜ Codex がまた使えないのか」という問題を迅速に特定でき、繰り返しログインしたり、再インストールしたり、複数の設定をコピーしたりする必要がありません。

Codex 設定センターを開いて各クライアントの公式ガイドを確認するか、アプリケーション一覧へ移動して API Key を取得してください。

参考資料