cqbase.net · English & Chinese

CQBase

Context & Query Base

Workflows

OpenAI Codex CLI

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.

This page is a guide, not the original text.

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 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. On macOS or Linux:

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

On Windows 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:

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 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 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 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 repository is licensed under Apache-2.0. This page is a paraphrase, for CQBase — Context & Query Base, of the README, CLI docs, Authentication, the Help Center article, and the supported-countries list, all checked on 2026-11-15. If install commands, plan coverage, or regional policy change, the official pages win.

Subscribe to CQBase Weekly

One email a week with newly catalogued public AI skills, prompts, MCP servers, and methods. Unsubscribe at any time. We will not hand your address to a third party for their marketing.