10 Minutes to Codex

中文版本

Codex is different from a normal chat assistant.

It can read your repository, edit files, run commands, inspect errors, and then show you the result.

So learning Codex is not mainly about memorizing prompt tricks.

The important parts are:

Describe the task clearly.
Keep the edit scope small.
Review what changed before you trust it.

This guide only covers the first real pass.

1. Install

One official setup path for the CLI is npm:

npm i -g @openai/codex

Run it:

codex

The first time you run Codex, it prompts you to sign in. You can authenticate with an OpenAI account that includes Codex access, or follow the API key flow.

Upgrade later with:

npm i -g @openai/codex@latest

On Windows, Codex can run natively in PowerShell. If your project depends on a Linux-native toolchain, WSL2 may still be the better environment.

2. Open a Real Project

Do not start in an empty folder.

Use a small project you already understand, ideally one with a build or test command:

cd ~/projects/my-app
codex

Do not ask it to edit files immediately.

Start with:

Read this project first. Do not edit files. Tell me the entry point, main folders, dev command, build command, and test command.

This is a good first request because you can observe how Codex reads files and summarizes the project without creating a large diff.

3. Give It a Small Task

Once it understands the project, give it a narrow task:

Fix the button text overflow on the homepage. Only change files related to that button. After editing, tell me which files changed. Do not commit.

This prompt has useful boundaries:

The bug is specific.
The edit scope is limited.
It should not commit before review.

For tests:

Add 3 tests for formatPrice in src/lib/price.ts. Cover normal amount, zero, and negative values. Do not change the implementation first.

Coding agents struggle when the task boundary is vague.

Not because they cannot do the work, but because a small request can easily expand into a much larger rewrite.

4. Review the Diff

Build this habit early:

After Codex edits, review the diff.

Inside the interactive session:

/diff

Or in your terminal:

git diff

Check three things:

Did it touch unrelated files?
Did it make a simple problem too complex?
Did it run the right verification?

If you dislike the result, say so directly:

This edit is too broad. Keep only the button style change and revert the unrelated files.

Or:

Stop writing new code. Explain why these two files need to change.

This is not being difficult.

This is your job as the project owner.

5. Useful Slash Commands

These are enough for the first week:

| Command | Purpose |

| --- | --- |

| /diff | Show current changes |

| /status | Show session and environment status |

| /permissions | Adjust what Codex can do without asking |

| /model | Switch model |

| /clear | Clear the conversation and start fresh |

| /compact | Summarize a long conversation to free context |

| /mention | Point Codex at a file or folder |

| /init | Generate an AGENTS.md file for the project |

| /exit | Exit |

If you forget the commands, type / and read the menu.

6. Run One-Off Tasks

Sometimes you do not need the full interactive session.

Ask one question directly:

codex "Explain the main modules of this project"

Set the working directory:

codex --cd ~/projects/my-app "Find why pnpm build fails. Do not edit code yet."

Attach an image:

codex --image screenshot.png "Compare this screenshot with the current page and find layout issues"

These are good for quick analysis.

For real edits, I prefer interactive mode because I can review the plan and diff as it works.

7. Start With Conservative Permissions

Codex can run commands and edit files, so permissions matter.

At the beginning, stay conservative:

codex --ask-for-approval on-request

If you only want it to inspect the project:

codex --sandbox read-only

Only use wide-open permissions in an isolated environment.

The stronger the agent gets, the more important it is to know when it is touching your real files.

8. A Beginner Prompt Template

You can start with this:

Read this project first. Do not edit files yet.

The problem I want to solve:
[describe the problem]

Constraints:
- Only change [file or folder]
- Do not touch [unrelated module]
- After editing, summarize the diff
- Do not commit

Verification:
- Prefer running [test or build command]
- If the command cannot run, explain why

This is much better than "optimize this project".

Clear boundaries make Codex feel like a useful collaborator instead of a roaming autocomplete engine.

9. When Codex Is a Good Fit

| Task | Fit |

| --- | --- |

| Understanding an unfamiliar codebase | Great |

| Fixing a clear bug | Great |

| Writing tests | Great |

| Small refactors | Good |

| Large architecture migrations | Be careful |

| Unclear product direction | Think first |

Codex works best when you can already describe the problem.

Start with build errors, UI bugs, missing tests, confusing functions, and small refactors.

Then move toward larger tasks after you understand its rhythm.