Codex CLI

Codex CLI は CC Switch のワンクリックインポートで HiAPI に接続できます。手動で設定することもできます（手順 9）。以下の手順は gpt-6-astra を例にしており、HiAPI は OpenAI Responses プロトコルを使います。本チュートリアルは Mac の Codex CLI 0.162.1 で検証済みで、Mac の手順を主な流れとし、Windows の手順は別に記載しています。すでにインストール済みのソフトウェアは飛ばして構いません。

1. Node.js をインストールする

Node.js の準備 の手順で LTS 22.19 以降 をインストールしてください。すでにあれば飛ばします。その後、ターミナルで以下の 2 つのコマンドを実行します。バージョン番号が表示されれば十分です。

node --version
npm --version

2. Codex CLI をインストールする

いま開いたターミナルで、各行を実行します。

npm install -g @openai/codex
codex --version

codex-cli のバージョン番号が表示されれば十分です。手動設定（手順 9）には 0.134 以降が必要です。Windows の PowerShell では、npm.cmd install -g @openai/codex と codex.cmd --version を使います。

3. CC Switch をインストールして開く

CC Switch のインストールとワンクリックインポート の手順で CC Switch をダウンロード、インストールし、開きます。すでにある場合は、そのまま開いてください。

すでにプロバイダーをお持ちの場合は、まず Codex ページで「In use」と表示されたカードの名前を控えておき、必要に応じて 現在の設定のバックアップ の手順で SQL バックアップをエクスポートします。

4. HiAPI の API キーを選ぶ

API キーの取得 の手順でキーを選ぶか作成し、その名前を控えます。ここでキーをコピーする必要はありません。インポートが引き継ぎます。

5. Web でワンクリックインポートを準備する

1. HiAPI の Codex 接続ページ を開き、API Key setup → Codex → Command line → gpt-6-astra → macOS を選びます。Windows ではシステムとして Windows を選びます。

2. Import to CC Switch をクリックし、API Key のドロップダウンから先ほど控えたキーの名前を選び、下部に Responses API · https://api.hiapi.ai/v1 と表示されていることを確認します。

3. Prepare import をクリックし、続いて Open CC Switch をクリックします。ブラウザからの確認には許可を出してください。

各手順のスクリーンショットは 接続ページでインポートを準備する にあります。

6. CC Switch でインポートを確認する

「Confirm provider import」ウィンドウで以下の項目を確認し、Switch to this provider immediately after import をオフのままにして、Import をクリックします。

CC Switch の Codex ページに戻り、HiAPI - gpt-6-astra のカードがあればインポートは成功しています（まだ有効にはなっていません）。スクリーンショットは CC Switch でインポートを確認する を参照してください。

7. HiAPI を有効にする

1. まず Codex で実行中のタスクが終わるのを待ちます。CC Switch の Codex → Direct ページで、HiAPI - gpt-6-astra カードの Switch / Enable ボタンをクリックします。カードに「In use」が表示されている場合にのみ、HiAPI は有効です。スクリーンショットは HiAPI を有効にする を参照してください。
2. Codex を完全に終了して開き直し、新しい設定を反映させます。CLI と Desktop はローカルの Codex 設定を共有している場合があります。後で元のプロバイダーに戻す場合は、ここでそのカードに切り替えてから、クライアントを開き直してください。

8. Codex を開き、モデルを選んで開始する

1. 新しいターミナルを開いて、使いたいプロジェクトのフォルダに移動します。まだない場合は先に空のフォルダを作ります。

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows の PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. 初回にディレクトリを信頼するか確認されたら、パスがいま選んだフォルダであることを確認し、案内に従って確認して、権限は既定のままにします。ワンクリックインポートを使った場合は codex を直接実行し、手動設定用の --profile hiapi は付けないでください。

3. Codex の入力欄で /model と入力して Enter を押します。矢印キーで GPT-6 Astra / gpt-6-astra を選び、Enter を押します。思考レベルがあれば 1 つ選んで確定し、Esc を押して戻ります。

① 矢印キーで GPT-6-Astra を選びます。② Enter を押して確定します。

4. 「こんにちは。自己紹介を一文でお願いします。」と送ります。正常に返答があれば接続できています。HiAPI コンソールの リクエストログ にこのリクエストが表示されれば、HiAPI 経由で通っています。あとは入力欄にやりたいことを書くだけです。

9. 手動設定（CC Switch を使わない場合）

ワンクリックインポートを使った場合はこの手順を飛ばしてください。手動設定は Codex CLI にのみ当てはまり、Codex Desktop には使えません。

1. Mac では、ターミナルで以下の 3 行を実行します。同名のファイルがすでにある場合は、先に自動でバックアップされます。

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. 新規ファイルの場合は、以下の内容をすべて貼り付けます。ファイルが既にある場合は、同じ名前のフィールドとテーブルだけを更新し、それ以外はそのまま残して、重複を追記しないでください。トップレベルのフィールドは [model_providers.hiapi] より前に置く必要があります。env_key = "HIAPI_API_KEY" は Codex が環境変数を読み込むための指定なので、そのままにしてください。

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. Ctrl+O → Enter → Ctrl+X を押して保存し、終了します。ファイル名は hiapi.config.toml である必要があり、.toml.txt にはできません。CODEX_HOME を設定している場合は、そのディレクトリにファイルを保存してください。

4. HiAPI コンソール → API キー に戻り、キーの横にあるコピーアイコンをクリックして、完全な HiAPI API キー をコピーします。Codex を起動するのと同じターミナルで以下のコマンドを実行し（YOUR_HIAPI_API_KEY をご自身の HiAPI API キー に置き換え、引用符はそのまま残します）、プロジェクトのディレクトリに移動して起動します。

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. Windows では、PowerShell で $env:USERPROFILE\.codex ディレクトリを作成し、メモ帳で hiapi.config.toml を開いて同じ TOML を貼り付けます。既存のファイルがある場合は先にバックアップしてください。Save as では「All files」と UTF-8 を選び、.txt の拡張子が付いていないことを確認します。同じ PowerShell ウィンドウ、同じプロジェクトディレクトリで以下を実行します。

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

環境変数は現在のターミナルにのみ適用されます。ターミナルを閉じたら、もう一度設定してください。起動後は手順 8 と同じようにモデルを選びます。

トラブルシューティング

ここには Codex CLI 固有の問題だけを記載しています。401、404、429 などの一般的なエラーは よくあるエラー を参照してください。