跪拜 Guibai
← Back to the summary

Codex Isn't a Chatbot — It's a Seven-Layer Configurable Workbench

Codex Beginner's Guide: From Installation to Plugins, MCP, and Skills — A Complete Configuration Walkthrough

Recently, many people in the old fan group have been urging me: can you write a basic tutorial on Codex? Don't just say "it's powerful" or "it's easy to use," but explain installation, configuration, plugins, Skills, MCP, memory, and connecting Apps clearly in one go. I understand this need.

I also have some AI Coding (SDD Agent AI tools, etc.) and Node tech exchange groups. If you're interested, you can add me on WeChat ikoala520 to join the group, learn together, and make progress together.

Because the biggest problem for beginners using Codex is often not knowing how to ask questions, but not understanding what Codex's "layers of configuration" each manage. You might have already installed Codex and can make it modify code, write articles, and explain errors, but as soon as you see config.toml, AGENTS.md, MCP, Plugins, Skills, Memory, your mind immediately becomes a tangled mess. This article solves that problem.

I won't write it as a translation of the official documentation, nor will I pile up a bunch of parameters right from the start. We'll follow the order a beginner actually gets started: install it first, then let Codex understand your project, and then gradually connect plugins, MCP, Skills, memory, and Apps.

image.png

A quick note: Codex updates very quickly. At the time of writing, the CLI version I verified locally is codex-cli 0.140.0-alpha.2, dated June 14, 2026. Specific commands should be based on your local codex --help and the official documentation. This article focuses on methods and configuration thinking; the commands are just to help you build your first runnable skeleton.

Remember One Thing First

Codex is not just a single chat window.

More precisely, it's like a workbench that you can configure:

Problem You Want to Solve Where It Should Go
Requirements for this specific task Current conversation / prompt
Rules this project follows long-term AGENTS.md
Your global default settings ~/.codex/config.toml
Standard process for a certain type of task Skills
A packaged set of capabilities Plugins
External system and tool interfaces MCP servers
Your long-term preferences Memory
Real applications like Gmail, GitHub, Chrome Apps / Connectors

image.png

A common mistake many beginners make at first is stuffing everything into the prompt.

For example, you tell Codex every time: "Please first read the project structure, follow our coding standards, run tests, don't modify files recklessly, and give me a summary after writing."

This certainly works, but it's tiring. A better way is to solidify long-term rules into AGENTS.md, put default behaviors into config.toml, write repetitive workflows as Skills, and hand off external capabilities to MCP and plugins.

This way, Codex transforms from "a window that answers questions" into "an assistant that fits your workflow."

Step 1: Install Codex First

Codex currently has several common ways to use it.

Entry Point Better Suited For How You Can Understand It
Codex CLI Programmers, people who often work in the terminal Directly let Codex read code, modify code, and run commands in the project directory
Codex Desktop App People who want a graphical interface, plugins, and to connect Apps More like a complete workbench
IDE Extension People who spend long hours in the editor Brings Codex close to your code editing environment
Cloud / Web Tasks People who want to hand off tasks to the cloud to run Suitable for parallel processing or long tasks

If you are a beginner, I suggest starting with the Codex Desktop App + CLI combination. The Desktop App is good for viewing plugins, connecting Apps, and managing threads; the CLI is good for diving into specific projects to work.

1. How to Install Codex Desktop App

The official entry point for the Desktop App is:

https://developers.openai.com/codex/app

If you want to download the installation package directly, you can also choose by system:

The corresponding direct links are as follows:

macOS Apple Silicon:
https://persistent.oaistatic.com/codex-app-prod/Codex.dmg

macOS Intel:
https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg

Windows:
https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi

The macOS installation steps are simple:

  1. First, confirm your chip type. Click the Apple icon in the top left corner, select "About This Mac," and see if the chip is Apple Silicon or Intel.
  2. Download the corresponding .dmg file.
  3. Double-click to open the installation package, and drag Codex to Applications.
  4. Open the Codex App and follow the prompts to log in with your OpenAI account.
  5. If macOS prompts for security confirmation, allow it to open in System Settings.

The Windows installation steps are similar:

  1. Open the Windows download link.
  2. Follow the prompts from Microsoft Store / App Installer to install.
  3. Launch Codex after installation is complete.
  4. Log in with your OpenAI account.
  5. Check plugins, connectors, and local workspace permissions within the App.

If you have already installed the CLI, you can also run this in the terminal:

codex app

This command will launch the Codex Desktop App. If the App is not yet installed locally, it will guide you to install it.

2. How to Install Codex CLI

The official entry point for the CLI is:

https://developers.openai.com/codex/cli

It is now more recommended to use the official standalone installer. For macOS / Linux, you can install it like this:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

For Windows PowerShell, you can install it like this:

irm https://chatgpt.com/codex/install.ps1 | iex

If you are used to using a package manager, you can also choose the following methods:

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

If you want to download the binary manually, you can go to GitHub Releases:

https://github.com/openai/codex/releases

After installing the CLI, run these commands first:

codex --version
codex login
codex doctor

codex login is used to log into your account.

codex doctor is used to check the local installation, configuration, authentication, and runtime health status. When beginners encounter "why doesn't it work," "why aren't tools taking effect," or "why can't MCP connect," run this first; it's more reliable than guessing the reason directly.

You can also view the full command list:

codex --help

The common commands I see on my local machine include:

Command Purpose
codex Start interactive CLI
codex exec Execute a task non-interactively
codex review Perform code review
codex login / logout Manage login
codex doctor Diagnose environment
codex mcp Manage MCP server
codex plugin Manage plugins
codex app Launch Desktop App
codex update Update Codex

You don't need to memorize them all at the start. For the beginner stage, just remember:

codex
codex login
codex doctor
codex --help

That's enough.

Step 2: Understand AGENTS.md

If you can only learn one configuration file first, I suggest starting with AGENTS.md.

Its role is simple: tell Codex how this project should work.

For example, how to start the project, how to test it, what the code style is, which directories not to touch, what commands to run before committing, and what to pay attention to when answering. You can understand it as a "project manual written for an AI colleague."

A minimal version can be written like this:

# AGENTS.md

## Project overview

This is a Next.js project. The main app is in `apps/web`.

## Common commands

- Install dependencies: `pnpm install`
- Start dev server: `pnpm dev`
- Run typecheck: `pnpm typecheck`
- Run tests: `pnpm test`

## Coding rules

- Follow existing file structure and naming style.
- Prefer small, focused changes.
- Do not rewrite unrelated files.
- Do not add new dependencies unless necessary.

## Verification

Before saying the task is complete, run the relevant check:

- UI changes: run `pnpm typecheck`
- Logic changes: run related tests
- Large changes: run `pnpm test`

If a command was not run, say it clearly.

The key here is not writing a lot, but writing accurately.

I suggest you prioritize four types of content in AGENTS.md:

Content Example
Project Structure Where the frontend is, where the backend is, where the configuration is
Common Commands Install, start, test, build
Coding Constraints Which files not to change, what style to use, how to name things
Verification Method When to run type checking, when to run tests

Some friends might ask: why not just write these things directly in the prompt?

Because the prompt is temporary, while AGENTS.md is long-term. You might ask Codex to modify the login today, the list tomorrow, and write tests the day after. All these tasks should follow the same set of project rules. By writing the rules into AGENTS.md, you don't have to repeat them every time afterward.

Step 3: Understand config.toml

AGENTS.md manages "project rules," while config.toml manages "how Codex itself runs."

The most common location is:

~/.codex/config.toml

It is typically used to configure the model, sandbox, approval strategy, MCP, profiles, environment variable policies, and other content.

You can also temporarily override the configuration. For example, the CLI help might show this kind of syntax:

codex -c model=\"o3\"
codex -c 'sandbox_permissions=[\"disk-full-read-access\"]'
codex -c shell_environment_policy.inherit=all

This illustrates an important concept: config.toml is for long-term defaults, and -c is for a temporary override this time.

At the beginner stage, I don't recommend changing a lot right away. You can first understand these configuration directions:

Configuration Direction How You Should Understand It
model Which model to use by default
sandbox Which files Codex can access when running commands
approval Which operations require your confirmation
MCP How to connect external tools
profiles Prepare different configurations for different scenarios
features Enable or disable certain experimental capabilities

Here's an example of a more conservative understanding:

# ~/.codex/config.toml

# Example: Adjust based on your account and the models available in the current Codex version
model = "o3"

# Beginners are advised not to rush to open the highest permissions.
# When you truly need full permissions, enable them separately in trusted projects.
sandbox_mode = "workspace-write"

# Whether manual confirmation is needed depends on your usage scenario.
# For daily interaction, you can be more conservative; for automation scripts, you can set more explicit limits.
approval_policy = "on-request"

Field names may change between versions. If you open it and find the field names are different, don't panic; check first:

codex --help
codex doctor

And the official documentation corresponding to your current Codex version.

Here's a very practical piece of experience: Don't start beginners with danger-full-access.

danger-full-access is very powerful, but it also means Codex has very broad file system permissions when executing commands. It's suitable for scenarios where you trust the current workspace very much and know what you're doing. When you first start using it, use a more conservative sandbox and approval strategy first, and gradually loosen them after you become familiar.

Step 4: What Are Plugins

Many people hear "plugin" and think it just means "one more button."

In Codex, a plugin is more like a capability pack. A plugin might contain:

You can use commands to view plugin-related capabilities:

codex plugin --help

Common subcommands include:

codex plugin list
codex plugin add <plugin>
codex plugin remove <plugin>
codex plugin marketplace list

When installing a plugin, the command form is roughly:

codex plugin add sample@debug
codex plugin add sample --marketplace debug

If you use the Desktop App, you can also search, install, and enable plugins in the plugin entry.

image.png

At the beginner stage, I don't recommend installing a bunch of plugins all at once. You can choose based on your workflow:

Your Scenario Prioritize
Writing code, reviewing PRs GitHub, Browser, Chrome
Writing articles, reports Documents, Browser, Data Analytics
Making PPTs Presentations
Handling spreadsheets Spreadsheets
Doing product and UI design Product Design, Figma, Browser
Operating web pages or desktop Chrome, Computer Use

The value of a plugin is not "looking advanced," but enabling Codex to access real materials, call real tools, and deliver real files.

For example, after you install a GitHub-related plugin, it doesn't just tell you "how you should review"; it can read PRs, view comments, check CI, and give modification suggestions. If you install Presentations, it doesn't just write PPT copy; it can generate a real presentation file.

This is the difference between plugins and ordinary prompts.

Step 5: What Are Skills

Skills are very suitable for beginners to understand as: writing a fixed way of doing things into a file.

For example, you often write public account articles, and each time you go through:

  1. Decide on a topic
  2. Research materials
  3. Build an outline
  4. Write the first draft
  5. Create illustrations
  6. Preview
  7. Adjust the rhythm

If you have to say it in the prompt every time, it's very troublesome. You can write this set of processes into a SKILL.md, and in the future, whenever a task matches, Codex can follow this method.

The location for Codex Skills is here ~/.codex/skills

image.png

A Skill usually looks like this:

---
name: ai-article-writer
description: Use when writing long-form AI technical articles.
---

# AI Article Writer

## Workflow

1. Clarify the target reader and article angle.
2. Collect reliable references.
3. Propose title options and outline.
4. Draft the article in Markdown.
5. Add diagrams when useful.
6. Render a local preview.
7. Review readability before final delivery.

Note that a Skill is not just a prompt template.

It's more like a set of "operating procedures." A good Skill tells Codex:

Element Explanation
When to use The description clearly states the trigger scenario
How to do it Clear steps
What materials to use Reference related reference files
What scripts to use Reuse existing scripts, rather than rewriting each time
How to verify What to check at the end

So what's the difference between Skill and AGENTS.md?

It's simple:

File Suitable for what
AGENTS.md Rules this project follows long-term
SKILL.md The standard way to do a certain type of task

For example, "this project uses pnpm, don't use npm" should go in AGENTS.md.

For example, "before writing a public account article, you must first do topic positioning, then write an outline" should go in a Skill.

Step 6: What Is MCP

MCP stands for Model Context Protocol. You don't need to memorize the English for now, just remember the problem it solves:

Let Codex connect to external tools and data sources through a standard protocol.

For example:

What MCP can connect to Typical Use
GitHub Read PRs, Issues, files, CI
Database Query business data
Documentation System Read team knowledge base
Browser Open pages, inspect UI
Search Service Find external materials
Internal System Call your own tools

In the CLI, you can use:

codex mcp --help

The common subcommands I see on my local machine include:

codex mcp list
codex mcp get <name>
codex mcp add <name> --url <url>
codex mcp add <name> -- <command>
codex mcp remove <name>
codex mcp login <name>
codex mcp logout <name>

There are two common ways to add an MCP server.

The first is the HTTP method:

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

The second is the local command method:

codex mcp add my-tool -- node server.js

If environment variables are needed, you might also see a form like this:

codex mcp add my-tool --env API_KEY=$MY_TOOL_API_KEY -- node server.js

In actual use, it's not recommended to write real keys directly in the command. A better way is to put them in environment variables, or use the secure configuration methods supported by Codex / MCP.

If you don't like the CLI above, you can also install and use MCP through the Codex desktop client.

image.png

For beginners to understand MCP, you can grasp one judgment criterion:

Whenever Codex needs to read external systems, call external tools, or access real-time data, prioritize thinking about MCP or App Connector.

Don't let the model answer your private data from memory.

For example, you ask: "Which PR in our project recently failed CI?"

This kind of question shouldn't let Codex guess, nor should it require you to copy and paste a bunch of webpage content. A more reasonable way is to connect GitHub, and then let Codex directly read the real PR and check results.

Step 7: How to Use the Memory Feature

Memory is easily misunderstood.

image.png

It's not for Codex to remember all facts, nor is it your private database. It's more suitable for remembering long-term preferences and stable habits.

Content suitable for Memory:

Suitable to Remember Example
Writing preferences I like Chinese technical articles, practical style, less empty talk
Common working methods Run typecheck after modifying code
Long-term address preferences Answer me in Chinese
Stable background I often write AI tool articles for public accounts

Content not suitable for Memory:

Not Suitable to Remember Reason
Passwords, tokens, keys Security risk is too high
Today's news Expires quickly
Current status of a certain PR Should be read from GitHub in real-time
Temporary task requirements Putting them in the current conversation is enough

In one sentence: Memory remembers preferences, not facts; remembers habits, not secrets.

If you want Codex to long-term remember "I like a practical style when writing articles," putting it in Memory is very suitable.

If you want Codex to know "how to start this project," putting it in AGENTS.md is more suitable.

If you want Codex to know "whether this PR on GitHub currently passes CI," then you should connect the GitHub App or MCP.

Step 8: How to Connect Apps, Letting Codex Truly Operate

Codex's power is not just being able to write answers, but being able to connect to real tools.

Common Apps / Connectors include:

App / Connector What It Can Do
GitHub Read repos, view PRs, check Issues, handle reviews
Gmail Search emails, summarize threads, extract to-dos, draft replies
Google Drive / Docs Read documents, organize materials
Figma Read design drafts, assist design-to-code
Browser Open web pages, test local pages, screenshot verification
Chrome Use your Chrome login state to operate web pages
Computer Use Operate local desktop applications

Here we need to distinguish two concepts:

Type More Like What
MCP Standard protocol interface, suitable for tools and data sources
App / Connector Authorized real application connection

For example, if you want Codex to look at a GitHub PR, there are several possibilities:

They are not mutually exclusive. In actual work, Codex will often prioritize the entry point that is already available in the current environment, has suitable permissions, and is the most stable.

At the beginner stage, you just need to remember one security principle: Reading can be more automatic, writing must be cautious. For example, reading PRs, summarizing emails, opening web pages generally have lower risk.

But sending emails, submitting forms, deleting files, publishing articles, changing permissions, making payments, sending messages—these actions must let Codex stop and ask for your confirmation first. Treat AI as a supervised assistant, not a completely unleashed robot.

Beginner's First Configuration, Follow This Order

Don't pursue "fully configured" right from the start.

A better order is:

image.png

You can follow this route:

  1. Install Codex, complete login.
  2. Run codex doctor, confirm the environment is normal.
  3. Write a simple AGENTS.md in the project root directory.
  4. Only change the necessary config.toml, don't open too many high permissions yet.
  5. Connect one most commonly used plugin first, like GitHub or Browser.
  6. If you often repeat a certain type of task, then write a Skill.
  7. When you need external data, then configure MCP.
  8. Finally, consider putting long-term preferences into Memory.

The advantage of this order is that you can verify at each step.

Many people install a dozen plugins, configure five or six MCPs, and write a bunch of global rules right from the start. When problems arise, they don't even know which layer is broken. The most important thing at the beginner stage is not showing off skills, but being able to locate problems.

A Set of Basic Configuration Templates for You

The following set of templates can serve as a starting point. It's not recommended to copy them blindly into all projects, but you can modify them according to your own project.

1. Project Root Directory AGENTS.md

# AGENTS.md

## Project overview

Briefly describe what this project does and where the main code lives.

## Common commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
- Build: `pnpm build`

## Working rules

- Read existing code before editing.
- Keep changes focused on the requested task.
- Do not rewrite unrelated files.
- Follow existing naming and style.
- Ask before adding new dependencies.

## Verification

Before marking work complete:

- Run the most relevant check.
- If checks cannot run, explain why.
- Do not claim tests passed unless they were actually run.

2. Global config.toml

# ~/.codex/config.toml

# Pick the model you normally want Codex to use.
# Example: Adjust based on your account and the models available in the current Codex version
model = "o3"

# Conservative default for local coding work.
sandbox_mode = "workspace-write"

# Let Codex ask when it needs permission for sensitive operations.
approval_policy = "on-request"

# You can add MCP servers below when needed.
# [mcp_servers.example]
# command = "node"
# args = ["server.js"]

If your Codex version prompts that fields are not recognized, don't force changes; run:

codex doctor
codex --help

Then adjust according to the current version.

3. A Minimal Skill Template

---
name: project-review
description: Use when reviewing a feature implementation before merge.
---

# Project Review

## Workflow

1. Read the requirement or issue.
2. Inspect changed files.
3. Look for bugs, regressions, missing tests, and risky assumptions.
4. Run or recommend relevant verification commands.
5. Report findings first, then summarize.

## Output

- Findings with file references.
- Test gaps.
- Suggested next steps.

4. MCP Add Command Template

# HTTP MCP server
codex mcp add <name> --url <server-url>

# Local stdio MCP server
codex mcp add <name> -- <command> <args>

# Check configured MCP servers
codex mcp list

The most important thing here is that <name> should be clear, like github, docs, postgres-readonly, not test1, abc. When troubleshooting later, clear names will save your life.

Common Pitfalls

1. Writing AGENTS.md Like Prose

AGENTS.md is not a project promotional draft for people to read, but an operational manual for Codex to use when executing tasks. Write less vision, more commands, constraints, and verification methods.

2. Opening Maximum Permissions Right From the Start

Beginners should not pursue "fully automatic execution without confirmation" at the beginning. The more an AI tool can operate real systems, the more boundaries it needs. First, get the workflow running with conservative permissions, then loosen them as needed.

3. MCP Configured But Forgot to Verify

After configuring MCP, run first:

codex mcp list
codex doctor

Being able to list it is only the first step. Whether it can be called in a real task depends on authentication, network, permissions, and whether the server itself is normal.

4. Installing Too Many Plugins

More plugins are not necessarily better. What you really need is a workflow.

If you write code every day, connect things like GitHub and Browser first. If you write articles every day, get the Documents, Browser, image generation, or preview workflow running first. Installing a bunch of unused plugins will only confuse you more.

5. Treating Memory as a Fact Database

Memory is suitable for remembering preferences, not real-time facts. Project status, PR status, database data, news changes—these should all be read from real sources.

6. Not Distinguishing "Read" from "Write"

Letting Codex read materials, summarize content, check pages usually carries lower risk.

Letting Codex send emails, publish articles, delete files, submit forms, change permissions carries much higher risk. For actions involving external side effects, it's best to let it stop and ask for confirmation first.

My Own Suggestions

If you are just starting to use Codex, I suggest not rushing to study all the advanced configurations.

In the first week, just do three things:

  1. Add an AGENTS.md for each project.
  2. Learn to use codex doctor to troubleshoot problems.
  3. Connect only one plugin or App you need most.

When you discover a task you repeat every week, like writing articles, reviewing PRs, organizing weekly reports, making PPTs, querying data, then solidify it into a Skill or plugin workflow.

What's truly powerful about Codex is not how fancy your one-time prompt is, but that you can gradually solidify your own way of working. The project rules written into AGENTS.md today, the GitHub connected tomorrow, the writing process solidified into a Skill the day after—all of these will make it more and more like your workbench.

For beginners, the best entry route is not "learn all the concepts before starting to use it," but to get it running first, and then put recurring problems in the right places.

If you only remember one diagram from this article, remember the seven-layer configuration map above:

Temporary needs go in the conversation, project rules in AGENTS.md, runtime defaults in config.toml, repetitive processes in Skills, external capabilities to Plugins, MCP, and Apps, and personal preferences then into Memory.

Once you clearly distinguish these layers, Codex is no longer a pile of unfamiliar terms, but an AI working system you can slowly build up.

I also have some AI Coding (SDD Agent AI tools, etc.) and Node tech exchange groups. If you're interested, you can add me on WeChat ikoala520 to join the group, learn together, and make progress together.

References