How to Use Codex — From Installation to Running It with an API Key Without a Subscription

Codex is OpenAI’s coding agent. To get started, install the Codex CLI, which runs in your terminal (npm install -g @openai/codex), then launch codex in the repository you want to work on and give it instructions in Japanese. There are two ways to get started: sign in with a ChatGPT plan (Plus, Pro, Business, etc.) and use its included allowance, or use an API key and pay for the tokens you use. Japanese-language guides mostly cover the first option, so this page explains the second: configuring the Codex CLI without a subscription, choosing a model for each task, and the actual cost per task.

Codex is not a tool for pasting code into a chat window. It is an agent that reads and edits files in your repository and runs tests and commands. After starting it, you can use /permissions to decide what it can do without asking for confirmation.

Two ways to use Codex

When you use an API key, billing is counted separately from your OpenAI plan allowance. You can use an OpenAI API key directly, but this page covers connecting to a Responses API-compatible endpoint. You can switch between GPT-6 Astra and GPT-5.6 Terra using the same key. For example, GPT-5.6 Sol costs $2.00 / $12.00 per 1M tokens, compared with OpenAI’s standard rates of $5.00 / $30.00(OpenAI currently offers it at the promotional price of $4.00 / $20.00. According to the pricing page, this lasts at least until November 21, 2026) (rates are read directly from the catalog).

Installation — npm or Homebrew

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

# Homebrew（macOS）
brew install --cask codex

Both are methods listed in OpenAI’s official README. The npm command also works on Windows. Once installed, run codex in the directory of the repository you want to work on. If you are signing in with ChatGPT, you are done here; no further configuration is needed.

Use an API key — add one block to config.toml

First, create an account, add at least $10 in credits, and create a key on the API keys page. The key is shown only once, so save it right away. Then add one provider block to the Codex configuration file.

# ~/.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"        # 唯一の有効値。省略しても同じ

The easiest thing to get wrong here is env_key. Enter the name of the environment variable containing the key, not the key itself. The key is not stored in the configuration file, so it is safe to commit config.toml as is or paste it into a question.

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

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

In Windows PowerShell, run setx KUNAVO_API_KEY sk-kn-... and then open a new terminal. The configuration file is at %USERPROFILE%\.codex\config.toml. Before starting Codex, verify the key and endpoint with a single request; this makes troubleshooting easier later.

# 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 とだけ返して"}'

If you get JSON back, both the key and endpoint are working, and any remaining issue is on the config.toml side. Details for each setting are in the Codex CLI integration documentation (English). For instructions on calling Claude models from the Codex CLI as well, see the Codex CLI API key setup guide (English).

Your first task

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

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

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

The AGENTS.md created by /init is a file for decisions “that you cannot figure out by reading the code,” such as how to run tests, which libraries to use, and which paths not to touch. It is automatically loaded in future sessions. The generated content is a draft, so review and edit it manually.

As with Claude Code, it helps to include file names and paths and avoid sending a large request all at once. This reduces the tokens spent exploring, so results are faster and more accurate, and bills are lower. You can adjust how often confirmation dialogs appear with /permissions. For Claude Code workflows, see How to use Claude Code.

Choose a model for each task — actual cost per task

The main advantage of using an API key is that you can choose a model to match the complexity of the work. model is just the model name on the endpoint, so switching models does not require another key or configuration.

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

“One task” is calculated as 20 steps for fixing one failing test. Each step uses 25,000 input tokens (system prompt, conversation history, and files read) and 1,200 output tokens (one edit or explanation), so one task uses 500,000 input and 24,000 output tokens. At GPT-5.6 Sol, it costs $1.29; paying OpenAI directly for the same number of tokens at the current promotional rates would cost $2.48 (or $3.22 at standard rates). Cheaper models can require more back-and-forth, so a practical approach is to move up one tier if the task is not done in one pass.

This calculation does not account for caching. Codex resends the conversation history at each step, so cached input is billed at 0.10x the input rate (GPT-5.6 Sol costs $0.20 per 1M tokens), while newly cached input is billed at 1.25x the input rate. Also, for the GPT-5.6 family and GPT-6 Astra, when a request’s prompt exceeds 272K tokens, that entire request is billed at 2x input and 1.5x output rates. To be safe, don’t pack too many tasks into one session; start a new one for each task. Reasoning tokens for reasoning models are billed as output, so harder tasks use more output. Check the actual amounts in the response’s usage and usage history. Model specifications are on the GPT-5.6 Sol model page, and rates for all models are in the pricing table.

Common errors

To be candid — when a ChatGPT plan is a better deal

If you work with Codex for hours every day, a flat-rate plan is usually cheaper. Pay-as-you-go is directly proportional to token usage, so the more and more consistently you use it, the greater the benefit of a flat-rate plan. The break-even point is “monthly fee ÷ cost per task,” calculated against plans in Codex pricing.

There are two other points to know. According to OpenAI’s documentation, features that depend on ChatGPT workspaces or the cloud are limited or unavailable when using an API key. Also, the Kunavo route uses shared capacity, with no dedicated quota or contractual SLA. If you need a guaranteed quota or SLA, contracting directly with OpenAI is more suitable.

An API key is a better fit if your usage varies significantly from day to day, you want to choose a model for each task, you need to separate limits and usage history by key for your team, or you want to keep working only on days when your plan allowance runs out. The two options can be combined. Remove the model_provider line from config.toml to return to ChatGPT sign-in, or use Codex’s --profile to switch for each launch.

Payment supports cards including JCB, Apple Pay, and Google Pay, and balances do not expire. Convenience-store payments and PayPay are not supported. Failed requests are not charged. If you are unsure whether to use Codex or Claude Code, see Codex vs. Claude Code.

Frequently asked questions