Codex CLI Tutorial: Install, doctor and sandbox_mode Setup

Codex CLI Installation, Login and Your First Task

Codex CLI is an OpenAI coding agent that reads and edits project files in your terminal. Install the CLI, launch it in your project directory and log in, then start with a small task. You can sign in with ChatGPT, or use an OpenAI API key, which is billed by usage. Official docs verified: 2026-09-24.

Installation and Login

1. Choose your operating system on the official Codex CLI install page; for npm installation, you can use npm install -g @openai/codex@latest.
2. Enter a Git project folder and run codex. On first launch, choose ChatGPT sign-in or another available method.
3. If you choose an API key, first create a key in an OpenAI Platform project, store it in OPENAI_API_KEY, and run printenv OPENAI_API_KEY | codex login --with-api-key following the official login method. In PowerShell, use $env:OPENAI_API_KEY | codex login --with-api-key.
4. Run codex login status to confirm the current login method. Then ask it to explain the project first, before giving it a small, clearly scoped task.

Codex CLI installation and authentication docs: official CLI quickstart, Codex Authentication, OpenAI project key management. Verified: 2026-09-24. ChatGPT subscription login and API key login are billed differently; API key usage is priced at OpenAI API rates. OpenAI manages ChatGPT and API Platform billing separately (verified 2026-09-24): ChatGPT and API Platform billing notes.

First API Request and Compatible Endpoints

To call the OpenAI API directly from the terminal, the Responses API uses OPENAI_API_KEY:

export OPENAI_API_KEY="your OpenAI project key"
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"Explain Codex CLI in one sentence."}'

If you use BazaarLink's OpenAI-compatible Responses API, take the model ID from the public catalog:

export BAZAARLINK_API_KEY="your BazaarLink key"
curl https://api.bazaarlink.ai/v1/responses \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"Explain Codex CLI in one sentence."}'

Codex CLI custom model settings use the Responses protocol, per the OpenAI official config reference. Do not conflate the API call examples with Codex's ChatGPT login. To check local model selection and usage limits, read Codex quota and usage limits; for installation details, see the English Codex CLI install guide. Model information verified: 2026-09-24: Codex CLI config reference, OpenAI GPT-6 Sol pricing, BazaarLink GPT-6 Sol page.

Applying for an OpenAI API key and organizing Taiwan payment receipts is covered in the OpenAI API Taiwan purchasing guide. To compare with Claude Code, see the Claude CLI tutorial.

Codex is OpenAI's terminal coding agent: you type one sentence in a project folder, and it reads files, edits code and runs tests on its own, then lays out the diff in front of you. The biggest difference from copying code into a chat window is that it can actually touch your file system. That is why permissions and the sandbox are the focus of this tutorial, rather than how to write prompts.

This article covers installation, your first task, common modes, config.toml, sandbox and custom model settings. Codex CLI updates often, so run codex --version before you start and check current options against the official docs. For differences in usage and plans, see Codex quota and usage limits and AI API price comparison.

Custom provider settings for Codex CLI depend on your installed version. The official config reference lists the base_url, env_key and wire_api fields and uses the Responses protocol. Verified: 2026-09-24.

Install Codex CLI

Codex is published as an npm package:

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

macOS users can also use Homebrew (note: it is a cask, not a formula):

brew install --cask codex

On Windows, the npm command above works directly; WSL is not needed.

After installing, run codex doctor in any project. It checks the installation, config files, authentication and the runtime environment, which is much faster than guessing where things broke.

First Task: Have It Edit One File

cd into a project with git (Codex requires a git repo by default, because it uses git to give you a way back), then:

codex

Once inside the interactive interface, describe what you want in plain language:

Change formatDate in src/utils/date.ts to support a timezone parameter, and add matching unit tests

It starts reading files, proposes commands to run and waits for your approval, then prints a diff when it is done. At that point you have three choices: accept, ask it to fix something, or run git checkout . to throw everything away. Build the habit of committing before you have Codex start working, so you always have a way back.

To skip the interactive interface and put it in a script, use exec:

codex exec "Fix all no-unused-vars errors that eslint currently reports"

Four Subcommands You Will Actually Use

codex resume is worth remembering in particular. Codex sessions can be resumed, so if a meeting interrupts you halfway through, you do not need to re-explain the context. To branch off a different path from a given point, use codex fork.

Config File: ~/.codex/config.toml

This is the control panel for the whole tool. On Windows it lives at C:\Users\<you>\.codex\config.toml. The minimal working config looks like this:

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

What the three fields mean:

model — which model to use. You can also override it for a single launch: codex -m gpt-5.3-codex.

approval_policy — when it asks you. Three values:

• untrusted: only safe commands like ls and cat run on their own; everything else asks you. Most conservative.
• on-request: the model decides when to ask. The everyday balance point; recommended as a starting point.
• never: never asks. Only use it when you are sure the sandbox is tight enough.

sandbox_mode — what it can touch. Three values:

• read-only: can only read; cannot write or connect to the network. Safest for code walkthroughs.
• workspace-write: can modify files under the current working directory. Use this for most situations.
• danger-full-access: it can do anything to the whole machine. Don't, unless you are inside a container or VM.

There is one sandbox default that bites: outbound network access is off by default under workspace-write. So npm install, or any command that needs a connection, will fail, and the error message does not always make clear that the network was blocked. To enable it, say so explicitly:

[sandbox_workspace_write]
network_access = true

approval_policy and sandbox_mode are two independent gates, and many people assume that setting one of them makes them safe. In practice, the most comfortable combination is on-request + workspace-write: it can freely modify files inside the project, but it stops and asks you before running rm -rf or installing anything.

To let it write to one more directory, add --add-dir at launch:

codex --add-dir ../shared-types

Teach It Your Project Rules with AGENTS.md

Put an AGENTS.md in the project root, and Codex reads it every time it starts work. This is the highest-return step. Instead of repeating "we use pnpm, not npm" in every prompt, write it down once:

# AGENTS.md

- Use pnpm for package management; do not use npm or yarn.
- Put all API response types in `src/types/api.ts`; do not define interfaces inline.
- Always run `pnpm test -- --run` after changes and confirm it is green before reporting back.
- Write commit messages in Traditional Chinese, in the format `type(scope): description`.

AGENTS.md can be layered: a file in your home directory for personal preferences, one in the project root for team conventions, and one in subdirectories for rules specific to that module. The closer the file is to the code, the higher its priority.

Custom OpenAI-Compatible Responses Endpoints

Codex CLI's custom providers communicate through the Responses API. The fields below follow the OpenAI official config reference; the BazaarLink model ID comes from the public catalog. Environment variables hold the key; the config file only stores the variable name.

model = "gpt-6-sol"
model_provider = "bazaarlink"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.bazaarlink]
name = "BazaarLink"
base_url = "https://api.bazaarlink.ai/v1"
wire_api = "responses"
env_key = "BAZAARLINK_API_KEY"

On macOS/Linux, set export BAZAARLINK_API_KEY="your key"; in Windows PowerShell, use $env:BAZAARLINK_API_KEY = "your key". Then launch codex from the project directory, first have it explain the current working directory, and then hand it a small-scope task. Check model IDs and pricing first in the public catalog and on the GPT-6 Sol model page.

Official config field verification date: 2026-09-24: Codex config reference. Here, Codex settings use the Responses API; the Chat Completions example above is for general applications that use the OpenAI SDK format.

CLI Troubleshooting

If you see Model metadata for ... not found, first check the model ID, the provider and the CLI version. The official issue tracker discusses cases where model metadata fallback can affect functionality: Codex CLI issue #34739. Verified: 2026-09-24.

"not a git repository" won't start — Codex requires a git repo by default. For temporary testing you can add --skip-git-repo-check, but for real work, use git properly, or you will have no way to undo changes.

It keeps asking whether to run commands — approval_policy is set too conservatively. Move it from untrusted to on-request.

It says it has no permission to write files — sandbox_mode is read-only; change it to workspace-write. If the file you want to write is outside the working directory, add that directory with --add-dir.

You broke something and want to revert everything — git checkout . (uncommitted changes) or git reset --hard HEAD (including staged changes). This is why you should commit first.

A config change did not take effect — launch with --strict-config. It reports an error for unrecognized fields in the config file instead of silently ignoring them. Especially useful for typos.

Summary

Codex's learning curve is not in the prompts. It lies in understanding the two-dimensional table of approval_policy × sandbox_mode, and in whether you are willing to spend ten minutes writing AGENTS.md. Finish those two things and it goes from an interesting toy to a colleague that can deliver work.

You can adjust custom model endpoints according to the official config fields, so you do not have to relearn a whole tool just to try another vendor's model. Changing four lines of config is enough.

TWD billing · Taiwan invoices · leading AI models · OpenAI-compatible API