# OpenAI Codex CLI

Canonical: https://cqbase.net/en/entry/openai-codex
Chinese: https://cqbase.net/zh/entry/openai-codex
English: https://cqbase.net/en/entry/openai-codex

> OpenAI’s lightweight terminal coding agent, Apache-2.0.

openai/codex is OpenAI’s terminal coding agent, Apache-2.0. The repository describes a lightweight coding agent that runs in the terminal. It sits in the same category as Claude Code and Gemini CLI: you give instructions in a repo, and it changes code.

Read the permission and sandbox notes in the repo before trying it on a small change. “Auto-approve commands” does not mean the same thing in every product. Do not carry the habit over unchanged.

## What problem it solves

Codex CLI is OpenAI’s terminal coding agent. In a local project directory it can read files, edit code, and run commands. It sits in the same category as Claude Code and Gemini CLI, but sign-in and usage are tied to ChatGPT or the OpenAI API. The same product family also includes IDE extensions, a desktop app, and Codex on the web. This page covers only the CLI getting-started path.

The repository is licensed under Apache-2.0. Official docs also describe `codex exec` for non-interactive scripts, plus slash commands such as `/permissions`, `/init` (which creates `AGENTS.md`), skills, plugins, and MCP via `codex mcp`. This page is not a feature catalog.

## Who it is for

It is for people who already open a repository in a terminal and want an agent that can work in that tree. The official Help Center article states that Codex is included across ChatGPT plans, including Free and Go, with usage limits that vary by plan. Codex Cloud is available to eligible Plus, Pro, Business, Enterprise, Healthcare, and Education accounts, and is not included with Free or Go. The repository README instead recommends signing in with Plus, Pro, Business, Edu, or Enterprise. Treat both statements as official and current as of the source dates below; this page does not invent numeric message caps. You can also sign in with an API key, which is billed at standard OpenAI API rates. Some ChatGPT-workspace or cloud features are limited or unavailable when you use a key.

OpenAI’s [supported countries list](https://developers.openai.com/api/docs/supported-countries) states that accessing or providing access from a place that is not listed can result in the account being blocked or suspended. That list includes Taiwan and does not include mainland China, Hong Kong, or Macau. The Help Center likewise treats unlisted locations as unsupported. The lists can change; use the official pages as the source of truth. This guide does not discuss ways to bypass the restriction.

## How to install it

Verified on 2026-11-15 (Asia/Shanghai). The commands below come from the repository README and the [Codex CLI docs](https://learn.chatgpt.com/docs/codex/cli). On macOS or Linux:

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

On Windows PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

You can also run `npm install -g @openai/codex` or `brew install --cask codex`. After install, change into a project directory and run `codex`. The first time, choose Sign in with ChatGPT and finish the flow in the browser. You can also run `codex login`. To use an API key, the official pattern is to pipe the key into the login command:

```bash
printenv OPENAI_API_KEY | codex login --with-api-key
```

Do not paste the key into the chat. Use `codex login status` to see the current method and `codex logout` to sign out. On a machine without a browser, the official device-code path is `codex login --device-auth`.

Inside a session, `/permissions` shows the sandbox and approval scope, and `/init` creates `AGENTS.md` for project conventions. Read the official permission docs before widening access. Do not carry over an “auto-approve everything” habit from another tool.

## A worked example

The official first-task prompt is: `Tell me about this project`. This guide did not run the command on a real repo, so it does not invent a project summary or a list of edited files.

1. Run `codex` in your own repository and finish ChatGPT or API-key sign-in.
2. Send: `Tell me about this project`. Official docs say the agent should inspect the local repo and describe it. You do not need to paste the directory tree first.
3. For a small change, use a narrow task of your own. Official guidance is to make a Git checkpoint before and after so you can roll back.
4. Use `/permissions` to confirm which files and commands are in scope. Review the diff yourself, then use your usual tests and Git workflow.

## Common pitfalls

- Sign-in fails, or you are in an unsupported region. Check OpenAI’s supported-countries list and the Help Center note on unsupported countries first. On a headless host, use device-code auth instead of waiting for a browser window. [Issue #39162](https://github.com/openai/codex/issues/39162) also reports ChatGPT auth becoming invalid after opening an older session on macOS.
- Permissions and the sandbox. Start with `/permissions` and do not allow every command by default. [Issue #47345](https://github.com/openai/codex/issues/47345) reported a Linux sandbox failure after an update (now closed); trust the current docs and the error in front of you.
- Putting an API key in the repo or in chat. Official docs want the key passed through `codex login --with-api-key` or a safe environment variable. Cached credentials may land in `~/.codex/auth.json`; watch the file permissions.
- Hitting a usage limit, or missing a feature. Free and Go, paid ChatGPT plans, and API-key sign-in include different features and billing. Codex Cloud is not part of Free or Go. Exact caps belong on [ChatGPT pricing](https://chatgpt.com/codex/pricing/) and the Help Center; this page does not invent numbers.

## FAQ

### Can I use Codex CLI on the free ChatGPT plan?

The official Help Center says Codex is included on Free and Go, with limited usage. The repository README more strongly recommends Plus or a higher plan. Codex Cloud is not included with Free or Go. Use the current official wording as the source of truth.

### Do I have to use an API key?

No. The recommended path is to sign in with a ChatGPT account in the browser. An API key is better for scripts or CI and is billed at API rates.

### What is AGENTS.md?

The official CLI can create `AGENTS.md` with `/init`. It holds project instructions for Codex, similar to convention files in other coding agents. Read what it generated before you edit it.

### Can I use it from mainland China?

OpenAI’s official supported-countries list does not include mainland China, Hong Kong, or Macau, and warns that access from an unlisted location can lead to a blocked or suspended account. Whether it works for you depends on the current official list. This page does not provide a workaround.

### Is the CLI the same as Codex on the web?

No. The CLI runs against your local repository. Codex on the web is the cloud agent at chatgpt.com/codex. There are also IDE extensions and `codex app`. This page covers only the CLI getting-started path.

## Sources and license

The [openai/codex](https://github.com/openai/codex) repository is licensed under Apache-2.0. This page is a paraphrase, for CQBase — Context & Query Base, of the README, [CLI docs](https://learn.chatgpt.com/docs/codex/cli), [Authentication](https://learn.chatgpt.com/docs/auth.md), the [Help Center article](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan), and the [supported-countries list](https://developers.openai.com/api/docs/supported-countries), all checked on 2026-11-15. If install commands, plan coverage, or regional policy change, the official pages win.

## Catalog record

- Author: openai
- License: Apache-2.0
- Source: https://github.com/openai/codex
- Added: 2026-11-15
- GitHub stars: 135344 (captured 2026-11-15)

