Codex Core Concepts
Before using Codex, it is very important to understand a few core concepts. These concepts form the foundation of how Codex works.
Prompt
You interact with Codex by sending prompts, describing the task you want it to accomplish.
Prompt working loop
After you submit a prompt, Codex works in the following loop:
- Call the language model to understand the task
- Execute the operations indicated by the model output (read files, edit code, run commands)
- Feed the operation results back to the model
- Repeat the loop until the task is completed or you cancel.
Codex usesAgent loopmode of operation — the model outputs instructions for actions, results are fed back to the model, and the cycle repeats until the task is complete.
Principles of effective prompts
| Principle | Description | Example |
|---|---|---|
| Include verification steps | Codex produces higher-quality output when it can verify its work | "Write a function, including test cases to verify it handles an empty list" |
| Break down complex tasks | Smaller tasks are easier to test and review | "Step 1: Create the model; after it's done, tell me before continuing to step 2" |
| Provide context | Reference relevant files and images | "Refer to the style of src/auth.py to implement similar functionality" |
Codex performs best when handling small, focused tasks. Large tasks should be broken down into small steps and executed incrementally.
Thread
A thread is a single task session: your prompts plus the resulting model outputs and tool calls.
Thread types
| Type | Runtime environment | Characteristics |
|---|---|---|
| Local thread | Your machine (inside the sandbox) | Can read/write files, use existing tools, and run commands |
| Cloud thread | Isolated cloud environment | Clone repository and run, suitable for parallel tasks, cross-device delegation |
Thread usage rules
Running threads can be concurrent, but note:
- Avoid two threads modifying the same file at the same time
- A thread can be resumed later by continuing with another prompt
- Long-running tasks may automatically compact the context
Context
When you submit a prompt, it includes context that Codex can use—references to relevant files and images.
Context sources
- IDE extension: Automatically includes the list of open files and selected text ranges
- Manual specification: Reference file paths in the prompt or attach images
- Conversation history: Previous conversation content in the thread
Context window
All information in a thread must fit within the model's context window.
Codex monitors and reports remaining space. You'll receive a prompt when approaching the limit.
Automatic Compact
For longer tasks, Codex may automatically compact the context.
The compaction mechanism summarizes relevant information, discards less important details, and frees up space to continue processing.
Managing context
/new
# View current context usage
/status
When Codex reports high context usage, consider starting a new session or reducing historical messages.
Sandbox
Sandbox is Codex's security isolation mechanism that prevents accidental modification of files outside the workspace.
Sandbox modes
| Mode | File Modification | Network Access | Use Cases |
|---|---|---|---|
| Read-only | Denied | Denied | Read-only analysis, code review |
| Workspace-write | Workspace only | Denied | Daily development (default) |
| Full-access | Allowed | Allowed | Fully trusted environment (use with caution) |
Approval mechanism
Certain operations require your confirmation before execution:
- Executing shell commands (especially rm, kill, etc.)
- Modifying or deleting files
- Accessing sensitive directories (e.g., ~/.ssh/, /etc/)
- Network requests
Setting sandbox mode
codex --sandbox workspace-write
# Or specify in the prompt
"Analyze this code, don't modify any files"
The sandbox is the first line of defense in Codex's security policy, ensuring that AI operations don't exceed the expected scope.
Approval Policy
The approval policy controls whether confirmation is needed before Codex executes operations.
Policy types
| Policy | Description | Behavior |
|---|---|---|
ask | Ask each time | Request confirmation before sensitive operations (default) |
approve | Auto-approve | Execute automatically, no confirmation needed (use with caution) |
deny | Auto-reject | Reject all operations that may have side effects |
Configure approval policy
approval_policy = "ask"
Summary
After understanding these core concepts, you can use Codex more effectively:
- Prompt: Clearly describe the task, including verification steps
- Thread: Manage task sessions, pay attention to concurrency rules
- Context: Provide relevant context, monitor window usage
- Sandbox: Understand security mechanisms, choose the appropriate mode
Frequently asked questions
Q: Should prompts be in Chinese or English?
Codex supports multiple languages, but English usually works best. When using Chinese, make sure the description is detailed and clear enough.
Q: How can I view the current thread status?
Use/statuscommand to view thread ID, context usage, and configuration information.
Q: What should I do if the context window is full?
Start a new session (/new), or let Codex automatically compact the history.
Q: Can sandbox mode be switched dynamically?
You can specify it at CLI startup, or set a default value in the configuration file.
Other Extensions