天天AI
教程 登录
注册

首页 / 教程

Codex CLI: step-by-step install

Install the OpenAI Codex CLI, skip official login with Tiantian AI, and code in the terminal.

Want an AI that reads your project, edits code, and runs commands right in the terminal — without a ChatGPT subscription?

Try Codex: OpenAI's official terminal AI coding agent. Install it, point it at Tiantian AI, and start chatting.

This guide covers the CLI only. IDE extensions and the cloud version are out of scope — see the official site if you need those.

About the links in this article: We include official docs for deeper reading or later reference. Following the steps here is usually enough; you do not need to open every link.

More guides in this series:

1. What it is

Codex is OpenAI's official terminal agent: it can read your repo, edit files, run a shell, and help with Git. Talk to it in natural language.

2. Install

The official recommendation is npm (requires Node 22+). Run this in a terminal first:

node -v

If it prints a version → go to Case 1; if the command is not found → go to Case 2.

Case 1: Node.js already installed (npm)

No Node yet? Download the LTS from https://nodejs.org/, open a new terminal, confirm node -v / npm -v print versions, then come back.

npm install -g @openai/codex

Open a new terminal, then confirm:

codex --version

A version starting with codex-cli means it worked.

Case 2: macOS with Homebrew

brew install --cask codex

Open a new terminal and run codex --version as well.

Windows users: use WSL and follow Case 1; native Windows support is still rough: https://learn.microsoft.com/en-us/windows/wsl/install

3. Configure (smallest working loop)

The goal is simple: let Codex reach a model and start working.
The official "sign in with a ChatGPT subscription" path is expensive and roundabout. Skip it as a beginner. This guide wires Tiantian AI in one shot.

About official login
The first time you run codex, it may ask you to sign in with a ChatGPT account (see https://developers.openai.com/codex/cli/).

We do not use that path. Write Tiantian AI into the config file as below. Once a custom provider is configured, Codex no longer prompts for official login.

Do this instead:

  1. Download the model catalog and write the config file below first
  2. Then start codex
  3. Ask for what you need in plain language

1. Get a Tiantian AI key

  1. Open https://ai.ttshuli.com, sign up, and sign in
  2. In the console, create an API key (usually looks like sk-mt-...)
  3. Copy and keep it — you will paste it into the config file. Do not post it in chats or screenshots.

The site docs have the same integration notes for comparison: https://ai.ttshuli.com/docs.html

2. Download the model catalog

Run this once before starting codex so /model lists the models we serve:

mkdir -p ~/.codex
curl -fsSL https://ai.ttshuli.com/codex-model-catalogs.json -o ~/.codex/model-catalogs.json

3. Write config.toml

Directory (create it if missing):

  • macOS / Linux: ~/.codex/
  • Windows (WSL): ~/.codex/

Create or edit config.toml and paste this block (replace the key):

model = "auto"
model_provider = "tiantian"
model_catalog_json = "~/.codex/model-catalogs.json"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.tiantian]
name = "Tiantian AI"
base_url = "https://ai.ttshuli.com/v1"
wire_api = "responses"
http_headers = { "Authorization" = "Bearer replace-with-your-key" }

Notes:

  • base_url is the OpenAI-compatible URL with /v1: https://ai.ttshuli.com/v1. Codex uses the OpenAI protocol; the Claude Code guide uses the site root without /v1 — do not mix them up.
  • wire_api = "responses" is the protocol switch. Codex only supports the Responses protocol (the legacy chat/completions protocol was removed in February 2026, see the official announcement https://github.com/openai/codex/discussions/7782). Older tutorials telling you to write wire_api = "chat" will fail with a config error on current Codex — do not copy them.
  • The key lives right in the config file: the http_headers line is the auth header. There is one space between Bearer and the key — keep the whole string intact. To rotate the key, change that line only.
  • Set model to auto so Tiantian AI picks the best model. The catalog changes; beginners should not hard-code a specific name.
  • Context window lives in the model catalog: each entry in model-catalogs.json has context_window / max_context_window, set to 180000 on this platform. Codex does not read the window from /v1/models — only from this file. Re-run the curl above after switching machines or when the catalog is updated.
  • approval_policy and sandbox_mode must sit at the top of the file, next to model and model_provider. Nested under [model_providers.tiantian] they are ignored, and Codex keeps prompting with the defaults (confirm each step, workspace-write only). sandbox_mode = "danger-full-access" has no colon (legacy sandbox field); the newer permission profile is default_permissions = ":danger-full-access". Do not mix the two; this guide uses sandbox_mode only. Start a new session after saving.

4. Open Codex

Go to your project and start:

cd /path/to/your/project
codex
  • The first launch in a directory asks whether to trust the folder — accept it
  • Because a custom provider is configured, an official login is usually not required; if a ChatGPT login page does appear, exit and double-check that the top-level model_provider = "tiantian" matches [model_providers.tiantian] exactly, character for character

Then type something like:

What does this project do?

A normal answer means the config works.

4. How to use it (enough to start)

Ask first, then edit

On a new project, let it map the structure before changing code. For example:

What stack does this project use? Where is the entry point?

Then give a concrete task:

Add nickname search on the user list page, reuse the existing table component, do not change the API contract

Saying "what to change and what not to touch" saves tokens and rework versus "just fix it."

Permissions: do not nest those two keys

The sample above already sets approval_policy = "never" and sandbox_mode = "danger-full-access": skip command prompts and turn off the filesystem sandbox (full access on this machine — your risk).

Those two keys belong at the top of the file. Nested under [model_providers.tiantian] they do nothing. Start a new session after saving. If you use the Codex panel in VS Code / Cursor, its Approvals / Sandbox UI overrides config.toml — set Never + Full Access there too.

To keep confirming every command, delete those two lines, or change them back with /approvals in a session.

Common launch options

From your system terminal:

Command What it does
codex Interactive session in the current directory
codex resume Resume the last conversation
codex "one task" Start a chat with an initial task
codex --version Show the version

In-session commands

Command What it does
/help List slash commands
/init Generate AGENTS.md (project notes, see below)
/diff Show what changed in this session
/quit Exit (or press Ctrl+C twice)

Type / for the command list.

Optional: AGENTS.md in the repo

Put an AGENTS.md at the project root with stack notes, directory conventions, and "do not touch" rules. It helps Codex follow your project; you can skip it for a first try (Claude Code users: this is the equivalent of CLAUDE.md, and the content transfers directly).

5. Saving money and troubleshooting

You already connected Tiantian AI, which is usually cheaper than an official subscription. A few habits save more:

  1. Keep the model at auto; do not force the most expensive tier for small jobs
  2. Scope the task (which files, what not to change)
  3. For large changes, ask it to analyze only, no edits, then implement after you agree on the plan

Common issues:

  • codex not found: open a new terminal; make sure the npm global directory is on PATH; reinstall with npm install -g @openai/codex
  • Config error / wire_api not supported: you are on an old Codex or copied an old tutorial's wire_api = "chat". Change it to "responses"; if that still fails, upgrade: npm install -g @openai/codex@latest
  • Auth errors / 401: check the http_headers line in config.toml — one space after Bearer, and a complete sk-mt-... key; in the console, confirm the key still exists and you have quota
  • 404 / endpoint not found: check that base_url is exactly https://ai.ttshuli.com/v1 (no missing /v1, no extra path)
  • Still prompts ChatGPT login: check that the top-level model_provider = "tiantian" matches [model_providers.tiantian] exactly
  • Still asks for permission every time: approval_policy / sandbox_mode are in the wrong place. They must sit above [model_providers.tiantian]; inside that table they are ignored. Start a new session after moving them. The IDE panel also overrides the file — set Never + Full Access there too
  • Rotate a key: change the string after Bearer in http_headers, then restart Codex

Official links

First run: write ~/.codex/config.toml (the key goes in http_headers) → cd into the project → codex → ask "what does this project do?"; once that works, give it a small edit.