Codex Core Concepts at a Glance
📚 Series Navigation: The previous article 01 · Understanding Codex and Its Four Entries introduced the four faces of Codex—Desktop App, CLI, IDE extension, and Cloud. This article takes a step deeper to explain several core concepts that will be repeatedly used in all subsequent chapters. The next article 03 · Installation and Login will walk you through the actual installation.
Let me start with a stupid thing I did when I first started using Codex. I asked it to "rename these three files in bulk." It modified them in a flash, but when I looked closer, I was dumbfounded—it only changed the ones in the current project directory; the two on my desktop were completely untouched. I was wondering: they said it could run commands, so why is it a picky eater? Later, I looked through the documentation and realized: that was the sandbox (Sandbox) stopping it. By default, it can only modify things inside your specified workspace, and it must ask you before stepping out of this boundary.
At that moment, I realized: if you don't understand these concepts before using Codex, you will always feel it is "sometimes works, sometimes doesn't"—in fact, it isn't acting up; you just didn't know it was wearing a few tight golden hoops on its head.
This article will break down these golden hoops, along with its unique configuration options, in detail.
After reading this article, you will get:
- A single sentence to explain what a Codex "agent (Agent)" is, and how it differs from a chatbot
- A thorough understanding of the sibling concepts sandbox and approval—why my renaming failed that time, and how to relax them
- An introduction to
AGENTS.md: the "onboarding handbook" that makes Codex remember your project rules - An understanding of what Memory and Chronicle are, whether they are enabled by default, and how to use them
- A hands-on experiment you can run to see the sandbox block you in action
⚠️ All specific commands, configuration items, and default behaviors mentioned below are based on the Codex official documentation; model names, subscription plans, and other version-dependent items are subject to what is actually displayed on your local system.
01 Agent: It Gets Hands-on, Not Just Chatting
First, the conclusion in one sentence: Codex is OpenAI's "programming agent (coding agent)" that can read code, edit files, and run commands itself, rather than just returning a piece of text. The official phrasing is "OpenAI's coding agent that can read, edit, and run code."
The word "agent (Agent)" is the key term here, which needs some explanation: Agent = an AI that can break down tasks, invoke tools, inspect results, and decide on the next step by itself, rather than a Q&A chat box.
The official documentation describes the way Codex works: "The agent runs terminal commands in a loop. It edits code, runs checks, and tries to validate its work."
In plain English, it boils down to three actions—Think → Do → See:
- Think: Read relevant files, check error messages, and understand the situation.
- Do: Modify code, create files, and run commands.
- See: Run tests, check outputs, and if something is wrong, go back and do another loop.
Analogy: A personal shopper who actually runs errands. A normal chatbot is like a customer service rep who only looks up prices—you ask "how much is this jacket," they tell you, and that's it. Codex is like a personal shopper: you say "help me buy a black hoodie in medium size," and they search for the item, compare prices, place the order, receive the item, and even unbox it to check if the size is correct, returning or exchanging it if it is wrong. "Running the entire process itself" is the essential difference between an agent and a chat box.
Here are some real scenarios you will encounter:
- You ask "why did this test fail," and it runs the test itself → reads the error → finds the bug → modifies the code → runs it again to confirm, while you just watch.
- You throw a legacy project with no documentation to it and say "map out the structure," and it inspects the files in the directory, searches for keywords, reads files, and finally draws a diagram for you—without you specifying a single file.
- You say "add caching to this function," and it modifies it and automatically cleans up the calling sites in other files because it can see the project globally across files.
💡 Summary in one sentence: Codex is an "agent," not a "chat box"—it gets the job done in a "Think → Do → See" loop, a mechanism identical to Claude Code, just under a different hood.
02 Sandbox (Sandbox): Where Is the Boundary Drawn?
Here comes the important part. The sandbox was the culprit behind my renaming failure at the beginning.
Sandbox: The official definition is "the boundary that allows Codex to act autonomously without granting unlimited permissions to your entire machine." Simply put, it is a boundary circle drawn for Codex—it does whatever it wants inside, but must ask you before stepping out.
Analogy: The play area in a mall. When you put a child in a fenced play area, they can play with the slides and ball pits as they please without you watching every move; but if they try to climb over the fence to run to the parking lot, the alarm goes off, and they need your nod. The sandbox is this fence: free movement inside the fence without interruption, and blocked only when stepping out—saving you from constantly worrying while preventing it from causing trouble.
This fence controls two things: what files it can modify and whether it can connect to the network. The official documentation lists three common sandbox modes:
| Sandbox Mode | Can Modify Files? | Can Connect to Network? | When to Use |
|---|---|---|---|
read-only | ❌ No (must approve changes first) | ❌ | When you only want it to read code, perform reviews, or draft solutions without modifying your files |
workspace-write | ✅ Only inside the workspace | ❌ No by default | Most common for daily development; Codex recommends this by default for version-controlled directories, while non-version-controlled directories default to read-only |
danger-full-access | ✅ Entire machine | ✅ | Fully trusted environments; the word "danger" is not a joke, use with caution |
See the "Only inside the workspace" in the workspace-write row? That is why my desktop files were not modified—they were not in the project directory where I started Codex, and were not inside the fence. Codex wasn't being lazy; it literally couldn't reach them.
There is another detail the official docs emphasize: the sandbox controls not only Codex's own read/write access, but also the commands it spawns. That means even if it invokes git, package managers, or test scripts, these commands are locked in the same circle—there is no loophole where the parent process is locked but child commands escape.
Implementation varies across platforms, which you will encounter during installation (details left for 03 Installation and Login):
- macOS: Uses the built-in Seatbelt framework, working out of the box without any configuration.
- Windows: Runs directly in the native Windows environment, using native Windows Sandboxes (divided into
elevatedandunelevatedmodes); if using WSL2, it follows the Linux implementation. - Linux / WSL2: You must manually install a tool called
bubblewrapfor the sandbox to function properly (this is an explicit prerequisite from the official docs).
💡 Summary in one sentence: The sandbox is the first golden hoop on Codex's head—by default (
workspace-write), it only allows Codex to modify files inside your workspace and blocks network access; if you want it to manage more, you must draw a larger circle yourself.
03 Approval (Approval): Who Nods at the Boundary?
Once the sandbox circle is drawn, "who to ask for approval when stepping out" is another matter, called Approval.
Many people (including my former self) confuse the two. The official documentation specifically notes: the sandbox defines the technical boundary, while the approval policy determines when Codex must stop and ask you before crossing that boundary.
Analogy: Access Card + Guard. The sandbox is the access gate (physically blocking you from going out), while the approval policy is the guard's temperament at the gate—some guards let everyone pass (never), some only block strangers (untrusted), and some require you to shout and ask every time you want to go out (on-request). The gate is fixed, but you can adjust the guard's strictness.
The three common approval policies in the official documentation:
| Approval Policy | Codex Behavior | Plain English |
|---|---|---|
untrusted | Asks before running commands that are not in the "trusted set" | Only prevents unfamiliar commands |
on-request | Runs inside the sandbox by default, stops and asks only when stepping out | The most common balanced setting |
never | Never prompts for approval, works silently | Commonly used in automation; permissions are still restricted by the sandbox, and this only makes sense when combined with full access |
Note: untrusted / on-request / never are three approval policies in the official docs—they are independent dimensions from the sandbox modes, configured and understood separately.
How to pair them? The official docs provide two ready-made combinations, which are enough to remember:
- Low-Risk Local Automation (Recommended for daily use):
sandbox_mode = "workspace-write"paired withapproval_policy = "on-request". The fence is locked, and it only asks when stepping out—secure and not annoying. - Fully Relaxed (Use with caution):
sandbox_mode = "danger-full-access"paired withapproval_policy = "never". This is like removing the gate and letting the guard go on vacation—use only in environments you trust 100%.
My habit is: for new projects and unfamiliar codebases, always start with read-only to let it read and analyze first. Once I review its plan and feel confident, I switch to workspace-write to let it do the work. I once directly used danger-full-access to run a bulk script out of laziness, and watched it flip through files across half of my home directory with sweaty palms—since then, I have never enabled full access in places where it shouldn't be.
How to switch? You don't need to touch the configuration file during daily use; a single /permissions command in the CLI session will switch modes on the spot (in the Desktop App and IDE, it is the permission selector next to the input box). If you want it to use the same settings every time it starts, you write it in the config file—that's the job of 18 config.toml Configuration in Detail, for now just know there is such a switch.
The diagram below maps out the relationship between sandbox and approval:
What this diagram does: it explains one thing—for every step Codex takes, it first checks "is it inside the sandbox circle" (sandbox decides), and if it steps out, it checks "should it ask you" (approval decides). Two gates, each managing its own part.
💡 Summary in one sentence: The sandbox handles "can it," while approval handles "does it ask," two dials adjusted separately; the daily combo of
workspace-write+on-requestbalances safety and convenience.
04 AGENTS.md: The Project Onboarding Handbook for Codex
The first three sections talked about "permissions." This section switches to a different topic: how to make Codex remember the rules of your project, so you don't have to explain them every single time.
The answer is a file called AGENTS.md.
Analogy: An onboarding handbook for a new employee. When a new person joins the company, you don't follow them around every day nagging "we use pnpm instead of npm" or "commit messages must be in Chinese"—you hand them a handbook and let them read it. AGENTS.md is this handbook for Codex: place it in the project, and Codex will read it before starting work and follow the rules inside.
The official definition for it is "durable project guidance"—persistent guidance that lives with the repository and takes effect before the agent starts working. One piece of advice: Keep it small, don't write it as a long-winded document.
It typically contains (examples from the official docs):
- Build and test commands (e.g., "use
pytest -qfor testing") - Code review expectations (e.g., "must run lint after editing")
- Repository-specific conventions (e.g., directory structures, naming conventions)
It can be placed at two levels, with the one closer to the working directory taking precedence (this priority judgment is critical):
| Level | Where to Put | What It Controls |
|---|---|---|
| Global | ~/.codex/AGENTS.md | Your personal preferences (e.g., "keep responses concise"), taking effect across all projects |
| Project | AGENTS.md in the repository root or subdirectory | The rules of this project/team, which can be committed to Git to be shared by the team |
The most brilliant use case highlighted by the official docs, and my personal favorite—using it as a feedback loop: when Codex makes a wrong assumption about your codebase, instead of just correcting it in the conversation (which is one-off, and it will forget next time), directly have it write this correction into AGENTS.md so that new sessions will automatically inherit it. I spent two weeks tuning a Python project, and AGENTS.md grew from blank to about twenty lines, capturing all the traps it fell into and got caught by me—now new sessions rarely repeat those mistakes.
AGENTS.mdis to Codex whatCLAUDE.mdis to Claude Code—same concept, different filename.
💡 Summary in one sentence:
AGENTS.mdis Codex's project onboarding handbook—write down your project rules, and it reads them before starting work; use it as a feedback loop to record traps it falls into, making it run smoother the more you use it.
05 Memory and Chronicle: Can It "Remember" You?
This final set of concepts is relatively new to Codex and easily misunderstood—can it actually remember what you chatted about in the past?
First, let's distinguish between the two terms:
Memory: Allows Codex to carry useful information learned in earlier sessions into subsequent work—such as your tech stack, project conventions, and traps you fell into, saving you from explaining them every time you start a session.
Analogy: A long-time partner. You have to repeatedly teach a new assistant that "we use TypeScript and don't write semicolons," but a partner of three years gets it with a glance—because they remember your habits. Memory is about turning Codex from a "newcomer" into a "long-time partner."
However, there are several critical facts you must know, otherwise you will feel it "sometimes works, sometimes doesn't":
- Off by default. If you don't turn it on, it won't remember anything. How to enable: turn it on in the Codex App settings, or write
memories = truein the[features]section of~/.codex/config.toml. - Regional restrictions. The official docs explicitly state: currently unavailable in the European Economic Area (EEA), the UK, and Switzerland.
- Not updated in real time. It waits until a session has been "idle long enough" to confirm you are not still working, then quietly summarizes it into memories in the background—so memories might not be written immediately after you close a session.
- Stored locally: Default path is under
~/.codex/memories/as a set of generated markdown files. - Session-level control: Use
/memoriesin the App and CLI to decide "whether the current session should use existing memories or be used to generate new memories."
The official docs also add an important note: for team rules that must take effect every single time, write them in AGENTS.md and do not rely on Memory—Memory is an "icing-on-the-cake local recall layer," not the single source of truth for rules. I have felt this deeply: memory is probabilistic, and relying on it to safeguard critical rules will eventually lead to failure.
💡 Summary in one sentence: Memory is the "long-time partner" mode, but it is off by default, has regional restrictions, and shouldn't replace
AGENTS.md—it is only for icing on the cake.
Now about Chronicle, let's label it clearly first:
⚠️ Experimental, subject to change. Chronicle is currently an "opt-in research preview," only available to ChatGPT Pro users, and only on macOS; also not available in the EU, UK, and Switzerland.
Chronicle "feeds the screen" to Memory. Normal memory learns from your conversations with Codex; Chronicle goes a step further, using contents on your screen to help Codex understand what you have been busy with lately—which file, which PR, or which documentation page you are looking at, so it can pick up the context without you explaining from scratch.
Analogy: A partner who can see your screen. A normal partner can only listen to what you say; a Chronicle partner can also glance at your monitor: "Ah, you are looking at this error," so you don't have to repeat it. It sounds great, but the cost is also practical—the official docs explicitly warn about three things: it consumes quota quickly, increases the risk of prompt injection, and memories are stored unencrypted on your local machine. In other words, convenience and risks are both on the table, weigh them yourself. My personal attitude: try it if you want, but remember to use the "Pause Chronicle" option in the menu bar in front of sensitive screen contents (passwords, private messages, customer data).
| Dimension | Memory | Chronicle |
|---|---|---|
| Information Source | Previous conversations | Your screen content |
| Maturity | Formal feature (off by default) | Research Preview (experimental) |
| Platform | Follows App / CLI | macOS only, Pro only |
| My Advice | Enable if you want convenience | Try it out, but remember to pause in sensitive scenarios |
💡 Summary in one sentence: Memory turns Codex from a "newcomer" into a "long-time partner," but it is off by default, has regional restrictions, and shouldn't replace
AGENTS.md; Chronicle is an experimental "screen-viewing" enhancement that is convenient but has clear risks.
06 Hands-on: See the Sandbox Block You with Your Own Eyes
Just reading concepts won't make them stick. Let's run a one-minute experiment to see how the sandbox blocks a write operation in read-only mode—this is where you should get a physical feel for it. The experiment doesn't rely on any existing project; just create a new empty folder.
Step 1: Create an empty directory, enter it, and start Codex.
Run in the terminal (Mac/Linux; on Windows PowerShell, replace mkdir -p with mkdir):
mkdir -p ~/codex-demo && cd ~/codex-demo
codexHaven't installed Codex yet? No problem, establish the concepts first. 03 Installation and Login will guide you through installing it, and then you can come back to run this.
Step 2: Switch to read-only mode.
Enter the slash command in the Codex session to adjust permissions to read-only:
/permissionsSelect read-only (Read Only / read-only) in the menu. Expected result: the interface prompts that you have entered read-only mode, similar to:
Permissions updated: read-only⚠️ New menu options might differ: Starting from codex-cli 0.142, the official release introduced permission profiles (marked Beta, may change) to replace the old "Read Only / Auto / Full Access" presets—your
/permissionsmenu might have changed to approval policies likeAsk for approval/Approval for me/Full access(without a directRead Onlyoption).If you don't see the
Read Onlyoption, using the old sandbox mode is the most stable approach (retained by official compatibility): exit the session, and re-enter withcodex --sandbox read-only; or writesandbox_mode = "read-only"in~/.codex/config.tomlto make it permanent. The subsequent experiment in this section will run successfully using this fallback.This part is "experimental, subject to change"; all subsequent mentions of switching to read-only via
/permissionsin this tutorial follow this note without repetition.
Step 3: Ask it to do something that requires writing a file, and watch it get blocked.
Tell it:
Help me create a new file hello.txt with the text "hello codex" inside.Expected result: It will not silently create the file, but will stop and request your approval—because "writing a file" breaks the boundary of read-only, and according to the approval policy, it must ask you first. It will look like:
I need to create the file hello.txt, which exceeds the permissions of the current read-only mode.
Do you allow this? (y/n)The moment you see this "stop and ask," you are witnessing the sandbox and approval working together: the sandbox determines "this step goes out of bounds," and approval then pops up to seek your nod. These are the two gates we talked about in Sections 02 and 03, running live on your screen.
Step 4: Compare what it looks like when allowed.
Go back to /permissions, switch to workspace-writable (workspace-write), and ask it to create hello.txt again. This time expected result: it creates it directly without asking—because writing files inside the workspace is within the sandbox circle, so no approval is needed.
Created hello.txtAfter running, check the current session's model, approval policy, and other info with /status:
/statusThe same file creation request is blocked in read-only and allowed in writable—this is the very real difference of sandbox modes. Instead of reading "sandbox is a security boundary" ten times, watching it stop and ask you in read-only mode makes it much easier to understand.
💡 Summary in one sentence: Run this minimal experiment, and you will see—the same file creation request is blocked and asked in
read-onlybut allowed directly inworkspace-write; that is how the sandbox and approval join forces.
07 Summary
This article has laid out the core concepts you will use in all subsequent chapters of Codex:
| Concept | Remember in One Sentence | Corresponding Claude Code |
|---|---|---|
| Agent (Agent) | AI that can Think → Do → See, not a chat box | Agent loop, identical |
| Sandbox (Sandbox) | The circle drawn for it, managing "where to modify, can connect to network" | Similar permission boundary, but more explicit |
| Approval (Approval) | Whether it asks you when stepping out, a separate dial from sandbox | Similar permission mode |
| AGENTS.md | Project onboarding handbook, reads rules before starting | CLAUDE.md with a different name |
| Memory / Chronicle | Remembers your preferences; Chronicle looks at screen, experimental | Similar to memory, Chronicle is new |
You should now understand: why Codex sometimes "refuses" to modify a file (outside the sandbox), why it suddenly stops to ask you (stepping out of bounds, approval blocks it), how to use AGENTS.md to make it remember project rules, and how to adjust strictness via /permissions.
The single most important takeaway: Codex is not a wishing well, but a capable partner wearing a golden hoop—your job is to set the direction, draw the circle it can work in, and pull it back when it wanders off. Master these concepts, and you will be building on a solid foundation as you learn about various entries, configurations, and extensions.
Next article 03 · Installation and Login: Now that we understand the concepts, it's time to actually install Codex on your machine. The next article will guide you through installing Codex, logging in, and running your first prompt on Mac / Windows / Linux—especially for Linux users, remember the bubblewrap mentioned in this article? You'll see what it does during installation.