Core Concepts

02 · Codex Core Concepts at a Glance

📚 Series navigation: The previous chapter, 01 · 认识 Codex 与四种入口, introduced the four faces of Codex—the desktop App, command line, IDE extension, and cloud. This chapter goes one level deeper, explaining in one go the core concepts that will recur throughout every later chapter. In the next chapter, 03 · 安装与登录, we will get hands-on and install it.

First, a silly mistake I made. When I first started using Codex, I asked it, ‘Help me rename these three files in bulk.’ It rattled through the changes, but when I looked, I was dumbfounded—it had only touched the files in the current project directory; the two on my desktop had not moved an inch. I wondered: isn't it supposed to be able to run commands, so why was it being picky? Only after reading the documentation did I realise that the sandbox was stopping it. By default, it can act only within the workspace you specify; it has to ask you before stepping outside that boundary.

That was when I understood: if you do not grasp these concepts before using Codex, you will keep thinking it ‘works sometimes and not others’. In fact, its behaviour is perfectly consistent; you simply do not know about the constraints it is operating under.

This chapter unpacks those constraints, along with several of Codex's distinctive configuration mechanisms, and explains them clearly.

By the end of this chapter, you will have:

• A one-sentence explanation of what a Codex ‘Agent’ is and how it differs from a chatbot
• A thorough understanding of the closely related concepts of sandboxing and approvals—why my rename attempt failed and how to relax the restrictions
• An introduction to AGENTS.md, the ‘onboarding handbook’ that helps Codex remember your project's rules
• An understanding of what Memory and Chronicle are, whether they are enabled by default, and whether you can use them
• A small experiment you can follow to see the sandbox stop an operation for yourself

⚠️ For all specific commands, configuration options, and default behaviours below, treat the Codex 官方文档 as authoritative. Model names, plans, and similar details can change between versions, so rely on what your local installation actually displays.

01 Agent: It Takes Action, Not Just Replies

Here is the conclusion in one sentence: Codex is OpenAI's ‘coding agent’: it can read code, edit files, and run commands itself, rather than merely replying with text. The official wording is "OpenAI's coding agent that can read, edit, and run code".

‘Agent’ is the key term here, so it deserves a quick explanation the first time you encounter it: an agent is an AI that can break down a task, invoke tools, inspect the results, and then decide what to do next; it is not a one-question, one-answer chat box.

The official description of how Codex works is: ‘The agent runs terminal commands in a loop. It edits code, runs checks, and tries to validate its work’ (original: The agent runs terminal commands in a loop. It edits code, runs checks, and tries to validate its work).

In plain English, that is still the same three actions—think → do → inspect:

• Think: read relevant files, examine errors, and understand the situation
• Do: edit code, create files, and run commands
• Inspect: run tests and examine output; if something is wrong, go back and try another round

Analogy: a personal shopper willing to do the legwork. An ordinary chatbot is like customer service that can only look up a price—you ask, ‘How much is this item of clothing?’, it tells you, and that is the end of it. Codex is like a personal shopper: you say, ‘Buy me a one-size black hoodie’, and it searches the stock, compares prices, places the order, opens the parcel when it arrives to check the size, and returns or exchanges it if it is wrong. Running the entire process itself is the fundamental difference between an agent and a chat box.

Some situations you will genuinely encounter:

• You say, ‘Why is this test failing?’, and it runs the test → reads the error → finds the bug → fixes it → runs the test again to confirm, while you simply watch.
• You give it an old, undocumented project and say, ‘Make sense of the structure.’ It lists the files in the current directory, searches for keywords, reads a collection of files, and finally draws you a diagram—without you specifying a single file.
• You say, ‘Add caching to this function.’ Once it has made the change, it also checks the related call sites because it can see the broader picture across files.

💡 In one sentence: Codex is an ‘agent’, not a ‘chat box’—it completes the work itself in a ‘think → do → inspect’ loop, and this mechanism is exactly the same as Claude Code's, just in a different shell.

02 Sandbox: Where the Boundary Around Its Actions Is Drawn

Now for the important part. The sandbox was responsible for the failed rename at the beginning.

Sandbox: the official definition is the boundary that allows Codex to act autonomously without giving it unlimited access to your entire machine. Put simply, it draws a circle around Codex—it handles matters inside the circle itself, but must ask you before leaving it.

Analogy: a children's play area in a shopping centre. You put a child inside the fence, where they can use the slides and ball pit freely without you watching every movement. If they try to climb over the fence and run into the car park, however, an alarm goes off and you must give permission. The sandbox is that fence: freedom inside the boundary without interruptions, and intervention only when it tries to leave—saving you constant worry without letting it run amok.

This fence governs two things: which files it can modify and whether it can access the network. The official documentation describes three common sandbox modes:

| Sandbox mode | Can it modify files? | Can it access the network? | When to use it |
|---|---|---|---|
| `read-only` | ❌ No (changes require approval first) | ❌ | When you only want it to read code, review it, and propose a solution without touching anything |
| `workspace-write` | ✅ Only within the workspace | ❌ Not by default | **The most common choice for day-to-day development**; Codex recommends this by default in version-controlled directories, while non-version-controlled directories default to `read-only` |
| `danger-full-access` | ✅ Across the entire machine | ✅ | Fully trusted environments; **the word danger is not there merely to frighten you—use it cautiously** |

Notice ‘Only within the workspace’ in the workspace-write row? That is why the files on my desktop were not changed—they were outside the project directory from which I launched Codex and therefore outside the fence. Codex was not being lazy; it genuinely could not reach them.

The official documentation also stresses another detail: the sandbox restricts not only Codex's own reads and writes, but also the commands it spawns. In other words, even when it invokes git, a package manager, or a test script, those commands remain inside the same boundary—there is no loophole where the main process is confined but a child command escapes.

Each platform implements this differently, as you will discover during installation (details are reserved for 03 安装与登录):

• macOS: uses the built-in Seatbelt framework and works out of the box, with no configuration required.
• Windows: runs directly in the native Windows environment and uses the native Windows sandbox, with elevated and unelevated modes; WSL2 uses the Linux implementation.
• Linux / WSL2: you must first install bubblewrap for the sandbox to work correctly (an explicit official prerequisite).

💡 In one sentence: The sandbox is Codex's first major constraint—by default (`workspace-write`), it may modify files only in your workspace and may not access the network; if you want it to cover more, you must enlarge the boundary yourself.

03 Approval: Who Gives Permission at the Fence

The sandbox draws the boundary, but ‘who approves crossing it?’ is a separate matter called Approval.

Many people, myself included at first, confuse the two. The official documentation makes a distinction worth remembering: the sandbox defines the technical boundary, while the approval policy determines when Codex must stop and ask you before crossing it.

Analogy: an access-control door plus a security guard. The sandbox is the locked door physically preventing you from leaving, while approval is the security guard's disposition—some guards let everyone through (never), some stop only strangers (untrusted), and some ask whenever you want to leave (on-request). The door is fixed; you can adjust how strict the guard is.

The official documentation lists three common approval policies:

| Approval policy | Codex behaviour | In plain English |
|---|---|---|
| `untrusted` | Asks before running commands outside the ‘trusted set’ | Stops only unfamiliar commands |
| `on-request` | Works in the sandbox by default and **stops to ask only when it needs to leave** | The most common balanced setting |
| `never` | Does not display approval prompts and carries on | Common for automation; permissions are still determined by the sandbox, so this is meaningful with full access |

Note that untrusted / on-request / never are the three approval policies in the official documentation. They and the sandbox modes are two independent dimensions, configured and understood separately.

How should you combine them? The official documentation provides two ready-made combinations; remembering these two is enough:

• Low-risk local automation (recommended for everyday use): sandbox_mode = "workspace-write" with approval_policy = "on-request". The fence stays locked and Codex asks only when it needs to leave, keeping things safe without becoming irritating.
• Fully open (use cautiously): sandbox_mode = "danger-full-access" with approval_policy = "never". This is equivalent to removing the door and giving the security guard the day off—use it only in an environment you trust 100%.

My own habit is to start every new project or unfamiliar repository in read-only, so Codex can only read and analyse. Once I have reviewed its proposal and know what to expect, I switch to workspace-write and let it act. Once, for convenience, I ran a batch script with danger-full-access; it searched through half my home directory, leaving me with sweaty palms. Since then, I have never enabled full access where it was not appropriate.

How do you switch? For everyday use, there is no need to touch the configuration file: enter /permissions in a CLI session to change modes immediately (in the desktop App and IDE, use the permission selector beside the input box). If you want the same settings on every launch, then edit the configuration file—that is covered in 18 config.toml 配置详解; for now, simply know that this switch exists.

The following diagram summarises the relationship between sandboxing and approvals:

What the diagram shows is straightforward: before every action, Codex first checks whether it is inside the sandbox boundary (the sandbox decides); if it is outside, Codex then checks whether it must ask you (the approval policy decides). These are two separate gates with separate responsibilities.

💡 In one sentence: The sandbox governs ‘whether it can’, while approval governs ‘whether it asks’; the two controls are adjusted separately. For everyday use, workspace-write + on-request balances safety with convenience.

04 AGENTS.md: The Project Onboarding Handbook for Codex

The first three sections covered permissions. This section changes topic: how to make Codex remember the rules of your project, so you do not have to repeat them every time.

The answer is a file named AGENTS.md.

Analogy: an onboarding handbook for a new employee. When someone joins a company, you do not follow them around every day saying, ‘We use pnpm, not npm’ and ‘Write commit messages in Chinese.’ You give them a handbook to read. AGENTS.md is that handbook for Codex: put it in the project, and Codex reads it before starting work and follows the rules inside.

The official term for it is ‘durable project guidance’: persistent instructions that travel with the repository and take effect before the agent begins working. The one-line recommendation is: Keep it small; do not turn it into an essay.

It usually contains items such as these (from the official examples):

• Build and test commands (for example, ‘Run tests with pytest -q’)
• Code-review expectations (for example, ‘Always run lint after making changes’)
• Repository-specific conventions (such as directory layout and naming rules)

It can exist at two levels, and the file closest to the working directory takes precedence (an important priority rule):

| Level | Location | Scope |
|---|---|---|
| Global | `~/.codex/AGENTS.md` | Your personal preferences (for example, ‘Keep replies concise’), applied across all projects |
| Project | `AGENTS.md` in the repository root or a subdirectory | Project or team rules; it can be committed to Git and shared with the whole team |

The official documentation highlights its best use, and it is my favourite too: treat it as a feedback loop. When Codex makes an incorrect assumption about your repository, do not merely correct it in the conversation—that correction is temporary and will be forgotten next time. Instead, ask it to write the correction into `AGENTS.md`, so a new session inherits it automatically. Over two weeks on one Python project, my AGENTS.md grew from empty to about twenty lines, all recording pitfalls Codex had encountered, I had caught, and it had then documented. New sessions now rarely repeat the same mistakes.

AGENTS.md is to Codex roughly what CLAUDE.md is to Claude Code—the same concept with a different filename.

💡 In one sentence: AGENTS.md is Codex's project onboarding handbook—write down your project's rules and it reads them before each job. Treat it as a feedback loop: record each mistake once, and Codex becomes smoother to use over time.

05 Memory and Chronicle: Can It ‘Remember’ You?

This final group of concepts is relatively new in Codex and easy to misunderstand—can it actually remember things you discussed before?

First, distinguish the two terms:

Memory lets Codex carry useful information learned in earlier sessions into later work—for example, your technology stack, project conventions, and previous pitfalls—so you do not have to explain everything again in every new session.

Analogy: a long-standing colleague. You must repeatedly teach a new assistant, ‘We use TypeScript and omit semicolons.’ A colleague who has worked with you for three years understands from a glance because they remember your habits. Memory moves Codex from ‘new arrival’ towards ‘long-standing colleague’.

However, there are several key facts you must know, or it will once again appear to ‘work sometimes and not others’:

• It is off by default. Unless you enable it, Codex remembers nothing. Enable it in the Codex App settings, or add ~/.codex/config.toml under [features] in memories = true.
• Regional restrictions apply. The official documentation states explicitly that, at launch, it is not available in the European Economic Area, the United Kingdom, or Switzerland.
• It is not updated in real time. Codex waits until a session has been ‘idle long enough’ and determines that you are no longer working before quietly summarising it into memories in the background. Consequently, a memory may not yet have been written immediately after you finish a session.
• It is stored locally: by default, under ~/.codex/memories/, as a collection of generated markdown files.
• It can be controlled per session: in the App and CLI, use /memories to decide whether the current session uses existing memories and whether it can generate new ones.

The official documentation adds an important point: team rules that truly must apply every time belong in `AGENTS.md`. Do not rely on Memory—Memory is ‘a helpful local recollection layer’, not the sole source of rules. This matches my own experience: Memory is probabilistic, and relying on it to enforce critical rules will eventually go wrong.

💡 In one sentence: Memory is the ‘long-standing colleague’ mode, but it is disabled by default and subject to regional restrictions. Important rules still belong in AGENTS.md; Memory is only an additional convenience.

Now for Chronicle, with a clear warning first:

⚠️ Experimental and subject to change. Chronicle is currently an ‘opt-in research preview’, available only to ChatGPT Pro users and only on macOS; it is likewise unavailable in the EU, United Kingdom, and Switzerland.

Chronicle ‘feeds the screen’ to Memory. Ordinary Memory learns from your conversations with Codex. Chronicle goes further, using content on your screen to help Codex understand what you have been working on—which file, PR, or document you are viewing—so it can pick up from there without requiring you to explain everything from the beginning.

Analogy: a colleague who can see your screen. An ordinary colleague can only listen to you; Chronicle can also glance at your monitor and say, ‘Oh, you're looking at this error’, saving you from repeating it. That sounds excellent, but the costs are real. The official documentation gives three explicit warnings: it consumes quota quickly, increases the risk of prompt injection, and stores memories locally without encryption. In other words, both the convenience and the risks are plain to see, so make your own judgement. My view: it is fine to try, but when sensitive content is on screen—passwords, private messages, or customer data—remember to use ‘Pause Chronicle’ in the menu bar.

| Dimension | Memory | Chronicle |
|---|---|---|
| Information source | Previous **conversation** sessions | Content on your **screen** |
| Maturity | General feature (off by default) | **Research preview (experimental)** |
| Platform | Follows App / CLI availability | **macOS only, Pro only** |
| My recommendation | Enable it if you want the convenience | Fine to try; remember to pause it in sensitive situations |

💡 In one sentence: Memory turns Codex from a ‘new arrival’ into a ‘long-standing colleague’, but it is disabled by default, subject to regional restrictions, and no replacement for `AGENTS.md`. Chronicle is an experimental ‘screen-reading’ enhancement: convenient, but with clear risks.

Having covered the five concepts individually, let us connect them in one diagram before moving to the practical section. Understanding each concept on its own is easy; the key is how they work together:

What the diagram shows: the ‘Agent’ in the middle is the main character, working within the circle of the ‘Sandbox’. To leave that circle for the outside world—your whole machine or the network—it must first pass the ‘Approval’ gate. On the left, AGENTS.md supplies the project's rules before it begins work. At the bottom, ‘Memory / Chronicle’ accumulates experience across sessions for reuse next time—all five concepts revolve around the agent in the centre.

06 Hands-on: Watch the Sandbox Stop You

Concepts alone are hard to remember. Run this one-minute experiment to see the sandbox stop a write operation in `read-only` mode—this is the part of the chapter you most need to experience directly. The experiment does not depend on an existing project; an empty new folder is enough.

Step one: create an empty directory, enter it, and start Codex.

Run this in a terminal (Mac / Linux; on Windows, use PowerShell and replace mkdir -p with mkdir):

mkdir -p ~/codex-demo && cd ~/codex-demo
codex

Have you not installed Codex yet? That is fine. This chapter establishes the concepts first; 03 安装与登录 will guide you through installation before you return to run the experiment.

Step two: switch to read-only mode.

Enter the slash command in the Codex session to set permissions to read-only:

/permissions

Then select the read-only option (Read Only / read-only) from the menu. Expected result: the interface indicates that the session is now in read-only mode, similar to:

Permissions updated: read-only

⚠️ The menu may differ in newer versions: from codex-cli 0.142, the official permission profiles (marked Beta，may change) replace the old ‘Read Only / Auto / Full Access’ presets. Your /permissions menu may instead show approval-policy choices such as Ask for approval / Approval for me / Full access, with no direct Read Only option.

If you cannot see Read Only, the old sandbox mode is the most reliable fallback and remains officially supported for compatibility: exit the session and re-enter with codex --sandbox read-only, or add ~/.codex/config.toml to sandbox_mode = "read-only" to make it permanent. The rest of this experiment works with that fallback.

This area is ‘experimental and subject to change’. The same note applies wherever the rest of this tutorial uses /permissions to switch to read-only mode, and it will not be repeated.

Step three: ask it to do something that requires writing a file, and watch it get stopped.

Give it this instruction:

帮我新建一个文件 hello.txt，里面写一行字 "hello codex"。

Expected result: it will not silently create the file. Instead, it stops and requests your approval because writing a file crosses the read-only boundary, and the approval policy requires it to ask you first. The message will mean something like:

我需要创建文件 hello.txt，这超出了当前只读模式的权限，
是否允许？(y/n)

The moment you see it stop and ask, you have witnessed sandboxing and approvals working together: the sandbox determines that the step crosses the boundary, then the approval mechanism prompts you for permission. The two gates described in Sections 02 and 03 have just run before your eyes.

Step four: compare what happens after relaxing the restriction.

Return to /permissions, switch to workspace write access (workspace-write), and ask it to create hello.txt again. This time, you should expect it to create the file directly without asking, because writing within the workspace is already inside the sandbox boundary and needs no approval.

已创建 hello.txt

Afterwards, use /status to inspect the current session's model, approval policy, and related information, giving you a clearer picture:

/status

The same request to create a file is stopped in read-only mode and allowed in write mode—that is the concrete difference between sandbox modes. Rather than reading ‘the sandbox is a security boundary’ ten times, seeing it stop and ask you in read-only mode makes the concept much quicker to understand.

💡 In one sentence: Run this minimal experiment and you will see for yourself that the same file-write request is stopped for approval under `read-only` and proceeds directly under `workspace-write`. That is how sandboxing and approvals work together.

07 Summary

This chapter has laid out, in one pass, the core concepts used throughout the later Codex chapters:

| Concept | Remember it in one sentence | Claude Code equivalent |
|---|---|---|
| **Agent** | An AI that can think → do → inspect on its own, not a chat box | The agent loop; exactly the same |
| **Sandbox** | The circle drawn around it, governing ‘what it can modify and whether it can access the network’ | Similar to a permission boundary, but more explicit |
| **Approval** | Whether it asks you when leaving the circle; a separate control from the sandbox | Similar to permission modes |
| **AGENTS.md** | A project onboarding handbook whose rules it reads first every time | `CLAUDE.md` under a different name |
| **Memory / Chronicle** | Helps it remember your preferences; Chronicle sees the screen and is experimental | Similar to memory; Chronicle is new |

You should now understand why Codex sometimes ‘refuses’ to modify a file (it is outside the sandbox boundary), why it suddenly stops to ask you (it needs to leave the boundary and the approval policy intervenes), how to use AGENTS.md to make it remember your rules, and how to adjust permissions immediately with /permissions.

The one sentence to take away: Codex is not a wishing well, but a capable colleague operating under constraints. Your job is to provide direction, draw an appropriate boundary around what it may do, and correct it if it strays. Once you understand these concepts, learning the various interfaces, configurations, and extensions simply builds on this foundation.

Next: 03 · Installation and Login. With the concepts understood, it is time to install Codex on your machine for real. The next chapter guides you through installing Codex on Mac / Windows / Linux, logging in, and running your first instruction. Linux users in particular: remember the bubblewrap mentioned in this chapter? During installation, you will see what it is for.