Understanding Codex and Its Four Entries
📚 Series Navigation: This is the opening article of the "Codex Beginner Tutorial". No prior knowledge is required; we'll start with "what Codex actually is." In the next article, "02 Core Concepts Overview," we will clarify all the terminology at once.
What Codex is, what the four entries do, and how it differs from ChatGPT and Claude Code
Hey guys, in this tutorial we are going to talk about OpenAI's Codex.
Codex—does the name sound familiar? OpenAI had an older model named Codex a few years ago, and looking at the official website makes you even more confused: why is there a Desktop App, a CLI, a browser extension, and a cloud web version? Which one is the actual "Codex itself"? Which one should I install?
To be honest, this is exactly where Codex is most likely to confuse beginners: it is not "a single software," but the same AI coding agent (Agent) with four different faces. If you don't understand this, you will get stuck for a long time trying to decide "which one to download."
This article won't teach installation or run commands (that's for Article 03). It does only one thing: thoroughly explain to you what Codex is, what its four faces manage, and how it differs from ChatGPT and Claude Code, giving you a map in your mind first. Once you have the map, you can decide for yourself which one to install and use.
After reading this article, you will get:
- A single sentence to clearly explain to others "what Codex is," without being misled by the name
- A comparison table of the four entries (Desktop App / CLI / IDE extension / Cloud Web), so you know where to start
- A set of criteria: how Codex differs from ChatGPT and how it differs from Claude Code, so they are no longer lumped together
- A zero-cost quick action to confirm in 30 seconds whether your computer recognizes it
This diagram shows the core of the whole article at a glance: Desktop App, CLI, IDE extension, and Cloud Web are the four faces of Codex—with different appearances and landing places, but connected behind the same account and the same Codex agent.
01 What Codex Actually Is
First, the conclusion: Codex is the official "AI coding agent" released by OpenAI—you give it a goal, and it can read your entire project, directly modify files, run commands, and run tests to finish the job for your acceptance, rather than just returning a piece of code in a chat box.
You are certainly not unfamiliar with OpenAI, the company that made ChatGPT. Codex is a tool it specifically built for the "coding" scenario. According to the official documentation, the work it does mainly falls into the following categories (these serve as its "capability list," just to get familiar with them, and we will expand on them in Article 02):
- Writing Code: You describe what you want, and it generates code following the existing structure and style of your project, instead of tossing you an isolated snippet.
- Understanding Unfamiliar Codebases: When taking over a legacy project with no documentation, asking it to "explain this project architecture" first is much faster than struggling through it yourself.
- Code Review: Helping you find potential bugs, missing boundary conditions, and logical errors.
- Debugging & Fixing: Tossing errors to it, it follows the code to find the root cause, locate it, and provide a fix patch.
- Automating Tedious Tasks: Offloading repetitive labor like refactoring, writing tests, migrations, and configuring environments with a single sentence.
Here is a critical difference where beginners are most likely to fail, singled out below:
Analogy: Looking up recipes (ChatGPT) vs. hiring a private chef to cook at home (Codex). When you normally use ChatGPT to write code, it is like looking up a recipe—it tells you to "add salt, add sugar, and stir-fry for three minutes," but you still have to handle the pan yourself: copying code, switching to the editor, pasting, and fixing errors are all manual tasks. Codex is different; it is like a chef who directly enters your kitchen—you say "I want to eat this," and it opens the fridge (reads files), turns on the stove (runs commands), cooks it, and serves it on the table (modifies the code and runs the tests), leaving you only to taste and accept it.
This difference translates into a world of difference in actual experience.
Take my own example. In March this year, I picked up a small Python crawler that had been shelved for over six months. The dependencies had long expired, and running it threw a bunch of errors. In the past, I would have had to copy the errors one by one into ChatGPT, have it tell me "it might be a library version issue," switch back to check, modify, run again... spending the whole afternoon switching windows back and forth. This time, I opened Codex directly in the project directory and said, "This project won't run anymore, find the root cause and fix it so it runs." It went through requirements.txt and the error stack itself, located two incompatible dependencies, updated the version numbers, and ran it again to confirm. I went to get a cup of coffee, and when I came back, it was already waiting for me to review the diff.
This immediately gives you a sense of the weight of the word "agent (Agent, an AI that can execute tasks autonomously)"—it doesn't just offer suggestions; it gets its hands dirty and gets the job done for you.
💡 Summary in one sentence: Codex = OpenAI's official AI coding agent, you give the goal and it does the work, not a "chat box that can write code."
02 Four Faces: Same Codex, Four Entries
This is where Codex is most different from many tools and most likely to confuse people, so we will focus on it.
When "command line" and "terminal" are mentioned, many beginners immediately picture a dark window and are instantly discouraged. Don't panic—Codex is actually one of the most friendly tools for "people who don't want to touch the command line" among major AI coding tools, because it specifically made a desktop App with a graphical interface.
According to the official documentation, Codex has four entries in total, and you can start from any of them:
| Entry | What it looks like | Where it runs | Suitable for / Scenario |
|---|---|---|---|
| Desktop App (Codex app) | Independent application, graphical interface, visual diff viewing, multi-tasking side-by-side | Your local machine | People who don't want to touch the command line, prefer clicking interfaces, and need to monitor multiple tasks simultaneously |
| CLI (Codex CLI) | Command-line tool running codex in the terminal | Your local machine | People used to terminals, needing to write scripts for automation, or working in servers / SSH |
| IDE extension | Sidebar plugin in VS Code / Cursor / Windsurf / JetBrains | Your local machine | People who spend their time coding inside editors |
| Cloud Web (Codex cloud) | Open chatgpt.com/codex in a browser, tasks run in OpenAI's cloud environment | Cloud | Offloading long tasks to the background, running multiple in parallel without consuming local resources |
Among the four, the first three (Desktop App, CLI, IDE extension) all work on your own computer—reading your local files and running your local commands. Only the fourth one, Cloud Web, is different:
Analogy: Outsourcing the work. The first three entries are like hiring an assistant to sit at your desk, using your computer and your files to work, while you watch the whole time. Cloud Web is like outsourcing the task to a remote team—you place an order in the browser, OpenAI starts an isolated environment in its own cloud, pulls your repository from GitHub, modifies it behind closed doors, and hands you a diff or even directly creates a PR (Pull Request) for you. It runs even if your computer is turned off.
This "outsourcing" model has two practical benefits: one is parallelism—you can throw out three to five tasks to run at the same time without blocking each other; the other is isolation—it plays around in its own sandbox, not touching your local system, so even if it breaks things, it won't affect you. My own most common combination is: using the Desktop App or CLI on the spot for minor fixes, and throwing slow and long tasks like "run the full test suite and fix the failing test cases" to the cloud to run in the background, checking back later.
Here is a particularly critical point that is worth highlighting and keeping in mind:
These four entries run the same Codex behind the scenes, and their configurations can be shared to a large extent. For example, the AGENTS.md (project instruction file, discussed in a dedicated article later) you write and the Skills (reusable instructions and workflows) you define—the official documentation explicitly states they can be reused across the Desktop App, CLI, and IDE extension. Configure once, use everywhere. If you have used any of them before, opening another one will still display your past project history.
A friendly tip: Beginners shouldn't obsess over "which one to learn first". My recommendation is—if you are afraid of the command line, start with the Desktop App (graphical interface, visual diff, most stable); if you already love the terminal, go straight to the CLI. The rest of this series will cover the four entries in detail in dedicated articles (Articles 07–10), so for now you just need to remember "the same Codex, four faces."
💡 Summary in one sentence: Codex has four entries: Desktop App / CLI / IDE extension / Cloud Web. The first three work locally, while Cloud Web outsources the work to the cloud, but they all run the same Codex under the hood and share configurations.
03 What It Can and Cannot Do
The capability list was outlined in Section 01, and here we add the other half that you must recognize—what it cannot do. This is even more valuable than "what it can do," because most beginner failures happen here.
| ❌ What not to expect it to do | Why |
|---|---|
| Make technical decisions for you | Choosing which architecture to use, whether it's worth refactoring, how to balance requirements—judgment and decision-making are your job; it is not good at global system design |
| Guarantee 100% bug-free code | It provides high-quality candidates, not absolute correct answers; you must review it after modifications |
| Guess unclear requirements | For business logic you haven't explained clearly, it can only guess, and the more autonomous it is, the easier it is to go off track |
| Run fully automated without you understanding | If you don't understand what it modified, you can't judge right from wrong, which is like driving with your eyes closed |
The second one is the easiest to fall into. I did something stupid before: I asked Codex to add error handling to a project in bulk, and it modified over a dozen files in a flash. To save trouble, I committed it directly. As it turned out, it "took the initiative" to change the original logic in two places, and it was only days later that I noticed an API behavior had changed. Since then, I set a strict rule: always review the diff for every single line it changes before committing. By the way, the official Codex quickstart also specifically mentions—using Git to make a checkpoint (which can be understood as "saving" the project) before and after work, so you can roll back with one click if things go wrong. Beginners should form this habit as early as possible.
The mindset for using Codex well is really just one sentence:
Let Codex provide high-quality candidate solutions, not absolute correct answers.
Simply put—humans set the direction, guard, and make judgments; AI is responsible for execution, analysis, and repetitive labor. This is its design philosophy: collaboration, not replacement.
💡 Summary in one sentence: It can read projects, modify files, run commands, and do tedious tasks, but making decisions and guarding the gates are always your job—it is a partner, not a hands-off successor.
04 Codex vs. ChatGPT vs. Claude Code
The two questions beginners ask most: "Aren't Codex and ChatGPT from the same company? What's the difference?" "How does it differ from Claude Code?" Let's clear it up at once.
The Difference Between Codex and ChatGPT
They both belong to OpenAI, but they are not on the same dimension at all.
Analogy: Advisor vs. Special Forces. ChatGPT is like an advisor sitting at headquarters—you describe the situation to him, and he gives you advice and drafts plans, but he doesn't go to the field; execution is still up to you. Codex is like a special forces soldier who can parachute directly onto the field—you give a goal, and he sneaks into your project (reads files, runs commands, modifies code), finishes the task, and returns to report.
Simply put: ChatGPT is Q&A, Codex is command-and-execute. Interestingly, Codex is included in the ChatGPT subscription (according to the official documentation, every ChatGPT account—including the free tier—includes Codex usage, with higher quotas for paid tiers like Plus / Pro / Business / Edu / Enterprise). It can also be accessed via OpenAI's API key on a pay-as-you-go basis. For how much quota each tier gives and whether functions differ across login methods, things change rapidly; always refer to the official pricing page (this will be covered in Article 04).
The Difference Between Codex and Claude Code
These two are often compared. Let me throw cold water on this: don't ask "which one is stronger"; their positioning is too similar, and strength depends on your specific usage. The real difference lies in the "focus of the workflow":
| Dimension | Codex (OpenAI) | Claude Code (Anthropic) |
|---|---|---|
| Origin | OpenAI, using the GPT series models under the hood | Anthropic, using the Claude series models under the hood |
| Most Convenient Entry | Officially built a graphical desktop App, friendly to those who don't touch the command line | Terminal (CLI) native, most complete features and best at explaining principles |
| Project Instruction File | AGENTS.md | CLAUDE.md |
| Four Entries | Desktop App / CLI / IDE extension / Cloud Web | Terminal / Editor plugins / Desktop App / Web & Mobile |
| Can Modify Files/Run Commands | Yes, a true agent | Yes, a true agent |
See that? The structure of the two is almost identical: both are programming agents that "can read projects and do hands-on work," both have local + cloud entries, and both use a project instruction file to "configure" them. The most intuitive differences are two: first, different bloodlines (GPT vs. Claude, different underlying models); second, different default temperaments—Codex officially promotes the graphical desktop App, clearly trying to attract people who "don't want to touch the command line," while Claude Code is terminal-native with a stronger command-line flavor.
I use both, and my division of labor is roughly: tasks that need a graphical interface, visual diff monitoring, or running multiple lines in parallel in a project go to Codex's Desktop App; tasks inside the terminal that connect to a bunch of custom scripts and hooks go to Claude Code. One complements rather than replaces the other.
Note: Which model is smarter, which price is more cost-effective, and what features are open to each change extremely fast. Today's conclusion might be outdated next week. Therefore, this article deliberately avoids writing down any hard test scores or price figures—to compare these, please check the respective official pages of the two companies.
💡 Summary in one sentence: ChatGPT is an advisor who gives ideas; Codex is OpenAI's special forces soldier who can do hands-on work. Codex and Claude Code are "two of a kind from different families," with similar structures but different bloodlines and default temperaments—don't choose one over the other; assign them based on the task.
05 Hands-on: 30 Seconds to Confirm If Your Computer Recognizes It
We agreed not to teach installation in this article, but let's do a zero-cost quick action to check your environment (whether installed or not, this command can run and won't break anything).
Open your terminal (Terminal App on Mac, PowerShell on Windows) and type this line followed by Enter:
codex --versionTwo expected results, both normal:
- Case 1: A version number pops up—congratulations, you installed the CLI before, and you can skip directly to "Get using it" in Article 03.
- Case 2: Error
command not found: codex(on Windows it might be'codex' is not recognized as an internal or external command)—also completely normal, meaning the CLI is not installed yet, which is the very first task to solve in Article 03.
Here is a sneak peek at the CLI installation commands (no need to run them now, just get familiar with them), the official originals look like this:
# macOS / Linux: Standard installation script
curl -fsSL https://chatgpt.com/codex/install.sh | sh# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"Once installed, type codex in the terminal, and it will guide you to log in (using your ChatGPT account or OpenAI API key), and then you can start working in the current directory.
Note 1: The above is the installation method for the command-line CLI. If you are afraid of the command line, the Desktop App follows a graphical interface path of "download installer package, double-click to install" (available for macOS / Windows, Linux is currently waiting in line), which is no different from installing normal software—Article 03 will cover the four entries separately, leaving no step behind.
Note 2: Codex relies on the OpenAI / ChatGPT account system. Domestic users usually need a VPN to install and log in. How to set it up and how to log in will be specifically covered in Article 03, so we won't expand here.
The diagram below clarifies the "local / cloud" relationship of the four entries. Even if you can't see the diagram, it won't affect your understanding; just remember the table above:
What this diagram wants to convey is: the four entries are all "doors" for you to submit goals to Codex. The first three doors lead to your local machine, and the last door leads to OpenAI's cloud, but behind the doors is the same Codex.
💡 Summary in one sentence: A single
codex --versioncommand can confirm if your computer recognizes it—don't panic if it errors, that's the opening task of Article 03; if you're afraid of the command line, remember there is also a graphical desktop App available.
06 Summary
We didn't run many commands in this article, but we cleared up the most important things you should think about first:
- What it is: OpenAI's official AI coding agent. You give the goal, it reads the project, modifies files, runs commands, and gets the job done—not a "chat box that can write code."
- Four faces: Desktop App, CLI, IDE extension, and Cloud Web. The first three work on your machine, while Cloud Web outsources the work to the cloud, but they run the same Codex under the hood and share configurations.
- Can / Cannot: Can read code, modify files, fix bugs, and do tedious tasks; but making decisions, guarding the gates, and adding requirements are always your job—always review the diff.
- Comparison: ChatGPT is an advisor, Codex is a hands-on special forces soldier; Codex and Claude Code are similar tools from different families with different bloodlines and temperaments—assign tasks based on need, don't choose one over the other.
Now you should be able to: explain what Codex is to a colleague in a single sentence, and judge which entry you should use and what tasks to assign to it. This is the "sense of map" you need first—all subsequent features will build upon this map.
In the next article, 〈02 Core Concepts Overview〉: we will clear up the terminology in the Codex world all at once—agent loop, context, AGENTS.md, approval mode, sandbox, Skills, MCP... all terms you will deal with daily. Go run codex --version now to see if you belong to "Case 1" or "Case 2," so Article 03 can address it.