Codex tutorial — install Codex CLI, use an API key instead of a subscription, and calculate the cost of one task

Codex is OpenAI’s AI coding agent. The most basic way to use it is to install Codex CLI (npm install -g @openai/codex), which runs in the terminal, launch codex in the project folder you want to work on, and tell it what to do in Chinese.There are two ways to get started: sign in with a ChatGPT plan (Plus, Pro, Business, etc.) and use its allowance, or run it with an API key and pay for the tokens you use. Chinese-language guides almost all cover only the first route; this article covers the second — how to run Codex CLI without a subscription, choose a model for each task, and estimate the actual cost of a task.

Codex isn’t a tool for pasting code into a chat window; it’s an agent that reads and edits files and runs tests and commands in your project. Configure which actions it can take without confirmation after launch with /permissions.

Two ways to use Codex

When you run with an API key, its costs are calculated separately from your ChatGPT plan allowance. You can also use an OpenAI API key directly, but this article covers connecting to a Responses API-compatible endpoint: the same key can switch between GPT-6 Astra and GPT-5.6 Terra. For example, the official OpenAI pricing for GPT-5.6 Sol is $5.00 / $30.00(OpenAI currently offers it at the promotional price of $4.00 / $20.00, which the official pricing page states will last at least until November 21, 2026), while here it is $2.00 / $12.00 per 1M tokens (rates are read directly from the catalog on this site, not entered manually).

Install Codex CLI — npm or Homebrew

# npm（有 Node.js 就能用，macOS / Linux / Windows 通用）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

Both are installation methods listed in the official OpenAI README, and the same npm command works on Windows. After installing, enter codex in your project folder to start it. If you plan to sign in with ChatGPT, you’re done here and can skip the configuration below.

Run with an API key — add a block to config.toml

First, create an account, add at least $10, and then create a key on the API keys page. The key is shown only once, so save it immediately. Next, add a provider block to Codex’s 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 field to get wrong is env_key: enter the name of the environment variable that stores the key, not the key itself. The key won’t appear in the configuration file, so you can safely commit config.toml to git or post it in a forum when asking for help.

# 把金鑰放進 env_key 指定名稱的變數（金鑰以 sk-kn- 開頭）
export KUNAVO_API_KEY="sk-kn-..."

# 寫進 shell 的設定檔，就不必每次都 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 launching Codex, make one request to confirm that the key and endpoint work, so it’s easier to identify which part is causing problems later.

# 懷疑 Codex 之前，先用一個請求確認金鑰和端點
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 it returns JSON, the key and endpoint are both working; any remaining problem is in config.toml. See the Codex CLI integration docs (English) for an explanation of each configuration field, including how to call Claude models from Codex in the Codex CLI API key guide (English).

Your first task

# 1. 進到要處理的專案資料夾，啟動 Codex
cd ~/work/my-app
codex

# 2. 讓它產生 AGENTS.md 草稿（寫測試怎麼跑、專案規則的檔案）
> /init

# 3. 之後直接用中文交代。附上檔名，做得更快也更省
> src/utils/date.test.ts 一直失敗，找出原因修好，並確認測試通過

The /init generated by AGENTS.md is a file for documenting “rules that aren’t obvious from looking at the code” — how to run tests, which libraries to use, and which paths not to touch — and it will be read automatically in every future session. The generated content is only a draft, so be sure to review and edit it yourself.

The prompting tips are the same as for Claude Code: include filenames and paths, and don’t send a large task all at once. This reduces the tokens spent exploring and makes results faster and more accurate, which also lowers the bill.

Choose a model for the task — the actual cost of one task

The main benefit of using an API key is that you can choose a model based on the complexity of the work. model are just model names on the endpoint; switching models doesn’t require a new key or additional configuration.

# config.toml 的預設（gpt-5-6-sol）不動，只有這次啟動換模型
codex -m gpt-6-astra     # 找不到原因的 bug、跨模組的修改
codex -m gpt-5-6-terra   # 例行修改、大量取代、整理日誌這類輕量工作

This estimate treats “one task” as 20 steps to fix one failing test. Each step uses 25,000 input tokens (system prompt + conversation history + files read) and 1,200 output tokens (one change or explanation), so one task uses 500,000 input and 24,000 output tokens. On GPT-5.6 Sol, that’s about $1.29; the same token counts paid directly to OpenAI cost $2.48 at the current promotional price (or $3.22 at list price). Cheaper models may need more back-and-forth to get the change right, so in practice, move up one tier if the first attempt doesn’t solve it.

This estimate doesn’t account for caching. Codex resends the conversation history at every step; cached input is billed at 0.10 times the input rate (GPT-5.6 Sol costs $0.20 per 1M tokens), while newly written cache content is billed at 1.25 times the input rate. Also, for the GPT-5.6 series and GPT-6 Astra, if a single request’s prompt exceeds 272K tokens, the entire request is billed at 2x input and 1.5x output rates. So avoid putting too much work into one session; restarting for each task is safer. Reasoning tokens are billed at the output rate, and harder problems generate more output. For actual costs, check usage in the response and the usage records. Model specifications are on the GPT-5.6 Sol model page, and rates for all models are on the pricing table.

Common errors

Honestly — when a ChatGPT plan is a better deal

If you spend several hours a day going back and forth with Codex, a fixed monthly plan is usually cheaper. Pay-as-you-go costs scale with token usage, so the more and more consistently you use it, the greater the advantage of a monthly plan. The break-even point is “monthly fee ÷ cost per task”; the comparison between plans is calculated on the Codex pricing page.

There are two more things to know. According to OpenAI’s documentation, features that rely on a ChatGPT workspace or cloud services are limited or unavailable when using an API key. Also, Kunavo uses shared capacity, with no dedicated quota or contract-backed SLA; if you need guaranteed capacity or an SLA, contracting directly with OpenAI is a better fit.

Conversely, the API key route suits people with variable usage, those who want to choose a model for each task, teams that want separate limits and usage records by key, and anyone who simply wants to keep working on the day their plan allowance runs out. You can use both: delete the model_provider line from config.toml to return to ChatGPT login; to switch on each launch, use Codex’s --profile.

Payment uses an international credit card (including JCB), Apple Pay, or Google Pay; Taiwan has no local payment channel — JKoPay and LINE Pay are not on the available list. The prepaid system charges the card only when topping up, balances do not expire, and failed requests are not charged. If you are deciding between Codex and Claude Code, see Claude Code vs Codex CLI (English); for how Claude Code is priced, see Claude Code pricing.

Frequently asked questions