Codex の使い方 — インストールから、サブスクなしで API キーで動かす方法まで

Codex は OpenAI のコーディングエージェントです。基本の使い方は、ターミナルで動く Codex CLI をインストールし（npm install -g @openai/codex）、作業したいリポジトリで codex を起動して、日本語で頼むことです。 使い始める方法は 2 つあります。ChatGPT のプラン（Plus・Pro・Business など）でサインインして利用枠の中で使う方法と、API キーで動かして使ったトークン分だけ払う方法です。日本語の解説記事はほぼ前者だけを扱っているので、このページは後者 — サブスクなしで Codex CLI を動かす設定、タスクごとのモデルの選び方、1 タスクの実額 — を順に説明します。

Codex はチャット画面にコードを貼るツールではなく、リポジトリの中でファイルを読み、書き換え、テストやコマンドを実行するエージェントです。どこまでを確認なしで任せるかは、起動後に /permissions で決められます。

Codex を使う 2 つの方法

API キーで動かす場合、請求は OpenAI のプランの利用枠とは別に数えられます。OpenAI の API キーをそのまま使うこともできますが、このページでは Responses API 互換のエンドポイントに向ける方法を扱います。GPT-6 Astra から GPT-5.6 Luna までを同じキーで切り替えられ、たとえば GPT-5.6 Sol は OpenAI の定価 $5.00 / $30.00 に対して、1M トークンあたり $2.00 / $12.00 です（料率はカタログから直接読み込んでいます）。

インストール — npm か Homebrew

# npm（Node.js が入っていれば macOS / Linux / Windows 共通）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

どちらも OpenAI の公式 README に載っている方法です。Windows でも npm のコマンドで入ります。インストールが終わったら、作業したいリポジトリのディレクトリで codex と打てば起動します。ChatGPT でサインインして使う場合はここで完了で、以降の設定は不要です。

API キーで動かす — config.toml に 1 ブロック

まず アカウントを作成し、$10 からチャージして API キーの画面 でキーを作ります。キーは一度しか表示されないので、すぐに控えてください。次に、Codex の設定ファイルにプロバイダを 1 ブロック書きます。

# ~/.codex/config.toml（無ければ作る）
model          = "gpt-5-6-sol"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "Kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"   # キーそのものではなく「環境変数の名前」
wire_api = "responses"        # 唯一の有効値。省略しても同じ

ここで一番間違えやすいのは env_key です。書くのはキーそのものではなく、キーを入れる環境変数の名前です。キーは設定ファイルに入らないので、config.toml はそのままコミットしたり、質問に貼ったりしても安全です。

# env_key で指定した名前の変数にキーを入れる（キーは sk-kn- で始まる）
export KUNAVO_API_KEY="sk-kn-..."

# 毎回 export しないよう、使っているシェルの設定ファイルに追記しておく
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

Windows の PowerShell なら setx KUNAVO_API_KEY sk-kn-... を実行してから、新しいターミナルを開き直します。設定ファイルの場所は %USERPROFILE%\.codex\config.toml です。Codex の起動前に、キーとエンドポイントが正しいかを 1 回のリクエストで確かめておくと、後の切り分けが楽になります。

# Codex を疑う前に、キーとエンドポイントだけを 1 回で確かめる
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5-6-sol", "input": "OK とだけ返して"}'

JSON が返ればキーもエンドポイントも正常で、残る問題があれば config.toml 側です。設定項目の詳細は Codex CLI 連携ドキュメント（英語）に、Claude モデルを Codex から呼ぶ方法まで含めた解説は Codex CLI の API キー設定ガイド（英語） にあります。

最初のタスク

# 1. 作業したいリポジトリに入って起動する
cd ~/work/my-app
codex

# 2. AGENTS.md の雛形を作らせる（テストの実行方法や決めごとを書くファイル）
> /init

# 3. あとは日本語で頼む。ファイル名を添えるほど速く、安く終わる
> src/utils/date.test.ts が落ちている。原因を調べて直し、テストが通るのを確認して

/init が作る AGENTS.md は、テストの実行方法、使うライブラリ、触ってはいけないパスなど「コードを読んでも分からない決めごと」を書いておくファイルで、以降のセッションで自動的に読み込まれます。生成された内容は下書きなので、手で直してください。

頼み方のコツは Claude Code と同じで、ファイル名とパスを添えることと、大きな依頼を一度に投げないことです。探索に使うトークンが減るぶん、結果は速く正確になり、請求額も下がります。確認ダイアログの頻度は /permissions で調整できます。Claude Code 側の運用は Claude Code の使い方 にまとめています。

タスクごとにモデルを選ぶ — 1 タスクの実額

API キーで動かす最大の利点は、作業の重さに合わせてモデルを選べることです。model はエンドポイント上のモデル名にすぎないので、切り替えにキーや設定の追加は要りません。

# config.toml の既定（gpt-5-6-sol）はそのまま、この起動だけモデルを変える
codex -m gpt-6-astra     # 原因の見えないバグ、設計をまたぐ変更
codex -m gpt-5-6-luna    # 一括置換、ログの要約などの軽い作業

「1 タスク」は、落ちているテストを 1 つ直す作業を 20 ステップと見た計算です。1 ステップは入力 25,000 トークン（システムプロンプト + 会話履歴 + 読んだファイル）と出力 1,200 トークン（1 回の編集や説明）なので、1 タスクで入力 500,000・出力 24,000 トークン。GPT-5.6 Sol なら $1.29、同じトークン数を OpenAI の API 定価で払うと $3.22です。安いモデルほど手戻りで往復が増えることがあるので、1 回で終わらなければ 1 段上げる、という使い方が現実的です。

この計算はキャッシュを考慮していません。Codex は毎ステップ会話履歴を送り直すため、キャッシュに乗った入力は入力単価の 0.10 倍（GPT-5.6 Sol なら 1M トークンあたり $0.20）で課金され、新しくキャッシュに書き込まれる分は入力単価の 1.25 倍です。また GPT-5.6 系と GPT-6 Astra は、1 リクエストのプロンプトが 272K トークンを超えると、そのリクエスト全体が入力 2 倍・出力 1.5 倍で課金されます。1 つのセッションに作業を詰め込みすぎず、タスクごとに起動し直すのが安全です。推論モデルの思考トークンは出力として課金されるため、難しいタスクほど出力も増えます。実額はレスポンスの usage と 利用履歴 で確認してください。モデルの仕様は GPT-5.6 Sol のモデルページ、全モデルの単価は 料金表 にあります。

よくあるエラー

正直なところ — ChatGPT プランのほうが得なとき

毎日何時間も Codex と対話しながら作業するなら、定額のプランのほうがたいてい安くなります。従量課金はトークンの量にそのまま比例するので、使う量が多く安定している人ほど定額の利点が大きくなります。分岐点は「月額 ÷ 1 タスクの単価」で、プランとの損益分岐は Codex の料金 で計算しています。

ほかにも知っておくべき点が 2 つあります。OpenAI のドキュメントによると、ChatGPT のワークスペースやクラウドに依存する機能は、API キーでの利用では制限されるか使えません。また Kunavo の経路は共有キャパシティで、専用のクォータも契約上の SLA もありません。保証された枠や SLA が必要なら、OpenAI と直接契約するほうが適切です。

逆に API キーが向いているのは、使う日と使わない日の差が大きい人、タスクごとにモデルを選びたい人、チームでキーごとに上限と利用履歴を分けたい人、そしてプランの枠が尽きた日だけ作業を続けたい人です。2 つは両立できます。config.toml の model_provider の行を消せば ChatGPT のサインインに戻り、起動ごとに切り替えたい場合は Codex の --profile が使えます。

支払いはカード（JCB を含む）と Apple Pay などで、残高に有効期限はありません。コンビニ払いと PayPay には対応していません。失敗したリクエストは課金されません。Codex と Claude Code のどちらを使うかで迷っている場合は Codex と Claude Code の比較 を参照してください。

よくある質問