Codex / Getting Started
Codex Overview
Learn how Codex acts as a software engineering agent, completing tasks, modifying files, and delivering auditable results at every entry point you write.
What is codex
Codex is OpenAI's coding agent for software engineering that can read code, edit files, run commands, review differences, and deliver results as verifiable engineering output, both locally and in the cloud.
The official manual organizes Codex into multiple surfaces: CLI, IDE extension, Codex app, Codex web, GitHub, Slack, Linear, SDK, and automation. They share the same type of core capabilities, but have different operating locations, authority boundaries, and applicable tasks.
When learning Codex, you should not just learn "how to let it write code", but also master the execution model: clarify tasks, load project rules, let it plan, control permissions, run verification, review diff, and review.
Codex entrance
Different entrances correspond to different working methods. CLI is suitable for local repositories and real commands; IDE is suitable for in-editor review; App/Web is suitable for task management and cloud parallelism; SDK is suitable for embedding Codex into products or internal platforms.
| entrance | Suitable for the scene | Things to note |
|---|---|---|
| CLI | Fix bugs locally, run tests, and script execution. | Subject to sandbox and approval policy. |
| IDE extension | Quote files, view diffs, and make small changes in the editor. | Settings still share some configuration with the CLI. |
| App / Web | Manage tasks, review results, remote/cloud execution. | The local login state is different from the network environment. |
| GitHub / Slack / Linear | Initiate and track tasks from collaboration tools. | Manual review and CI need to be retained. |
| SDK | Build an internal agent platform or automation. | Permissions, logging, timeouts, and rollbacks must be designed. |
learning principles
Think of Codex as a collaborator that performs project actions. All tasks must have goals, scope, limits, verification mandates, and auditable results.
- Read the code first, then modify the file.
- Plan first, then execute.
- Verify first, then summarize.
- Review diffs before committing or deploying.
Complete usage points
Supplement the core concepts, operation sequences, permission boundaries and verification requirements that are easily compressed and missed in official documents, making it easier for English readers to learn completely by page.
Official structure supplement
The main line of the OpenAI Codex document is not a single product page, but a set of usage systems surrounding "software engineering agents". The recommended reading order starts with an overview, understanding how Codex works across CLI, IDE, Web, App, GitHub, Slack, Linear, and SDK, and then moves into sandboxing, permissions, configuration, AGENTS.md, MCP, Skills, and automation.
- Entrance layer: determines where the task is initiated and whether it can access the local repository, browser login state, remote cloud environment or team collaboration context.
- Permission layer: determines which paths Codex can read and write, whether it can be connected to the Internet, and when manual or automatic approval is required.
- Project rules layer: Turn team agreements into reusable context through AGENTS.md, configuration, skills, hooks, and MCP.
- Delivery layer: The final result must be verifiable by diff, test, build, screenshot, PR or release record.
So getting started with Codex shouldn’t stop at “making it code.” More reliable learning goals are: being able to explain the permission boundaries of the current entry, being able to write tasks into project cards, being able to read Codex plans and command output, and being able to review changes and risks before submission.
Study Checklist
Put the content on this page into real tasks and use the five dimensions of entry, context, permissions, verification and team rules to check whether you have truly mastered it.
Study Checklist
After reading this page, do not just remember the concept name. You should be able to place "Codex Overview" back into a real Codex engineering workflow: where the task starts, what context the system loads, which actions need approval, how the result is verified, and how to roll back when it fails.
If this is a concept page, be specific about how it affects the real task: does it change context, permissions, execution paths, validation methods, or changes the team collaboration process.
- Be able to describe in your own words the specific problem this page solves, rather than just reciting the title.
- Able to write a minimal example task with goals, scope, prohibitions, and acceptance criteria.
- Be able to determine which information should be put into the current prompt and which should be captured as project rules or configurations.
- Be able to explain which long-term rules should go into AGENTS.md, and which runtime behavior should be handled by config.toml, permission profile, skills and MCP.
- Ability to check diffs, command output, test results, screenshots or PR notes after a task is completed instead of just trusting the natural language summary.
If this page is used for team training, ask learners to complete a small task with Codex: read and explain first, submit a plan, make the smallest useful change, and close with real verification commands plus human diff review.
Codex practical notes
Fill in the most overlooked execution details of Codex usage around local environments, privilege escalation, remote entry, automation failures, and rollbacks.
Codex Practical Notes
This page belongs to the core concepts of Codex. When learning, connect concepts to real-world implementation: will it change context, permissions, task splitting, verification paths, or change the way teams collaborate.
When handling tasks related to "Codex Overview", always confirm the current Git status and working directory first. Codex can make changes quickly, but it does not automatically know which uncommitted edits came from the user, which files are off limits, or which commands may affect production.
- Prioritize using low-risk branches or working trees for local tasks, and review them with git diff after completion.
- When it comes to installation dependencies, networking, databases, deployment, push, deletion, and reset, Codex must first be asked to explain the impact before approval.
- Results generated by remote or collaborative portals must also be confirmed back to PR, CI, build logs and test evidence.
- Automated tasks must define failure output and exit conditions in advance to avoid Codex repeatedly trying in the wrong direction.
Think of Codex as an engineering teammate who can execute commands, rather than an assistant who can only write text. The closer you get to a real system, the greater the need for clear boundaries, evidence, and rollbacks.