From 45278ef6445f8b2a39ebc774d25166f69378a462 Mon Sep 17 00:00:00 2001 From: Mahdi Salmanzadeh Asl Date: Mon, 6 Jul 2026 19:53:29 +0400 Subject: [PATCH] Add English reader and language switcher --- CodexOrangeBook.en.md | 7208 ++++++++++++++++++++++++ README.en.md | 55 + README.md | 9 + en.html | 9933 +++++++++++++++++++++++++++++++++ index.html | 46 +- tools/build_english_reader.py | 343 ++ tools/test_reader_links.py | 16 + 7 files changed, 17608 insertions(+), 2 deletions(-) create mode 100644 CodexOrangeBook.en.md create mode 100644 README.en.md create mode 100644 en.html create mode 100644 tools/build_english_reader.py diff --git a/CodexOrangeBook.en.md b/CodexOrangeBook.en.md new file mode 100644 index 0000000..1cbdeb5 --- /dev/null +++ b/CodexOrangeBook.en.md @@ -0,0 +1,7208 @@ +# Codex Orange Book: A Practical Guide from Setup to Real-World Workflows + +> Unofficial open-source guide · Continuously updated edition +> A Codex handbook for developers, indie makers, and power users of AI tools. + +| Version | Last Verification | Data Nature | +| --- | --- | --- | +| v0.1.0 | 2026-06-22 | Unofficial guide, not OpenAI documentation or a product commitment | + +> This guide is based on Codex App, Codex CLI, Codex IDE Extension, and Codex Web/Cloud capabilities and observed UI available on 2026-06-22. Codex changes quickly, so installation paths, model names, quotas, entry points, and command parameters may change. For current features and pricing, rely on official OpenAI documentation, the current Codex version, and what your own account shows. +> Third-party tools and model access solutions such as CC Switch and DeepSeek are only recorded as extension methods and are not official OpenAI functions. + +> Translation note: this English edition is machine-assisted from the Chinese source and may lag behind future Chinese updates. Please verify product details against current OpenAI documentation and your own account UI. + +## Reading Entry + +- [Read online in English](./en.html) +- [English Markdown source](./CodexOrangeBook.en.md) +- [Original Chinese reader](./index.html) +- [Download the original Chinese PDF](https://raw.githubusercontent.com/bozhouDev/codex-orange-book/main/Codex%E6%A9%99%E7%9A%AE%E4%B9%A6.pdf) + +## Table of Contents + +- 0. Instructions for use +- Part 1: Understand what Codex is +- Part 2: Installation, configuration, and environment setup +- Part 3: Core functions +- Part 4: Standard workflow +- Part 5: Hands-on case library +- Appendix: Third-party model access + +## 0. Instructions for use + +### 0.1 Important Statement + +- This material is an unofficial guide and does not represent official OpenAI documentation. +- All functions are subject to the official OpenAI documentation and the actual version of Codex. +- This PDF will be continuously maintained with Codex updates. +- Readers are advised to check the latest version of the Markdown manuscript in the GitHub repository first. + +### 0.2 Who is this PDF suitable for? + +- People who have never used Codex but want to get started with the system. +- People who can write code but don't know how to connect Codex to real projects. +- People who have used Cursor, Claude Code, ChatGPT and want to compare Codex workflows. +- Independent developer, AI tool blogger, technical team leader. +- People who want to build AI programming workflows, knowledge bases and automated processes. + +### 0.3 Reading route + +- **Quick Start Route**: 0. Instructions → Part 1: Understand what Codex is first → Part 2: Installation, configuration and environment preparation → Part 4: Standard workflow → Part 5: Practical case library +- **Core Route for Developers**: Part 1: First understand what Codex is → Part 2: Installation, configuration and environment preparation → Part 3: Detailed explanation of core functions → Part 4: Standard workflow +- **Advanced expansion route**: Part 3: Detailed explanation of core functions → Part 4: Standard workflow → Appendix: Third-party model access + +--- + +## Article 1: First understand what Codex is + +### Basic knowledge of Codex + +#### What exactly is Codex? + +When many people hear Codex for the first time, they will subconsciously understand it as "another AI code writing tool." + +But if you only think of Codex as "ChatGPT that writes code for me", it's easy to underestimate it. + +What is really important about Codex is not whether it can write a function, add a piece of code, or explain an error, but that it represents a change in the role of AI programming tools: + +In the past, AI was the person sitting next to you to help you fill in the code. + +Later, AI is the person who changes the code with you in the editor. + +Now, Codex is more like a project executor that can be assigned tasks. + +It doesn't just answer "how to write this code", but can enter a project, read the file, understand the context, make a plan, modify the code, run the command, check the results, and finally organize the changes into results that can be reviewed. + +This is the biggest difference between Codex and ordinary AI chat tools. + +--- + +##### Changed four times in five years + +

+ AI编程工具的四次进化历程 +

+ +**Four evolutions of AI programming tools** + +In the past few years, AI programming tools have generally gone through four stages. + +**2021: The era of Copilot completion. ** +The first time the name Codex was heard by a large number of developers was because of GitHub Copilot. At that time, AI was mainly responsible for code completion: you wrote the beginning, and it completed the end; you wrote the function name, and it completed the function body. It is like a smarter input method that allows you to write faster, but how to dismantle the project, how to find the files, and how to run the test still mainly depends on people. + +**2022: ChatGPT conversation era. ** +After ChatGPT appears, AI programming moves from "completion" to "dialogue". You can directly ask it about the reason for the error, code optimization, interface writing, and project structure explanation. AI transforms from an input method into a question-and-answer companion. But it is usually not in a real project. You need to copy the code, paste the error report, manually fill in the context, and then move the answer back to the project. + +**2023-2024: Cursor Project Collaboration Era. ** +AI editors such as Cursor allow AI to truly enter the editor, where it can see files, modify functions, reconstruct across files, and complete some development tasks based on the project context. AI begins to shift from “answering questions” to “assisting in modifying projects.” But most of the time it is still attached to the IDE, and you still need to keep an eye on it to make changes, determine the next step, run tests, and organize submissions. + +**2025: Codex Engineering Agent Era. ** +After Codex reappeared, it was no longer just a model responsible for code completion, but a coding agent for real software engineering tasks. It can read projects, interpret code, fix bugs, add features, add tests, refactor modules, run commands, check diffs, organize PR notes, and even process multiple engineering tasks in parallel. + +This means that the focus of AI programming tools is shifting from "helping you write code" to "helping you deliver tasks." + +One sentence summary: + +**Copilot helps you make up the code, ChatGPT helps you think about the code, Cursor accompanies you to modify the project, and Codex starts to help you perform engineering tasks. ** + +--- + +#### What can Codex do? + +**What Codex Can Do** + +

+ Codex能做什么的内容 +

+ +Many people will ask directly when using Codex for the first time: + +- "Write a login page for me." +- "Help me fix this bug." +- "Help me with a project." + +These certainly work, but they are not accurate enough. + +What Codex is really good at is not generating a piece of code out of thin air, but completing a set of engineering tasks in a real project. + +It can read the project, find files, understand the context, make plans, modify code, run commands, check results, organize diffs, and finally advance the task to a state that can be reviewed. + +So, don’t think of Codex as a “code generation button”. + +More precisely: + +**Codex is an AI engineering assistant that can enter the project site. ** + +What it can do can be roughly divided into the following categories. + +--- + +##### Understand an unfamiliar project + +The first step in using Codex should not be to let it write code directly, but to let it read the project first. + +It can help you figure it out quickly: + +- What technology stack is used for the project. +- Where is the entry file. +- where the core module is. +- What are the test and build commands. +- Which files cannot be moved casually. + +Many Codex tasks fail, not because it cannot write code, but because it is asked to do it directly before it understands the project. + +--- + +##### Explain the code and sort out the logic + +Codex can help you explain the code you don't understand. + +For example: + +- What does this function do. +- Why is this component written like this. +- What is the interface call link. +- where the status comes from. +- Which files this bug may be related to. + +It not only explains a single function, but also combines the context to sort out module relationships, data flows and potential risks. + +This is especially useful for taking over old projects. + +--- + +##### Fix bugs and add features + +Codex is well suited for handling well-bounded development tasks. + +For example: + +- Fix a reproducible bug. +- Add a new settings page. +- Add a new form check. +- Add a new interface. +- Added an export button. +- Optimize a front-end page. + +But don't just throw a big project at it. + +A better way is to break the task into smaller pieces: + +1. Read the project first. +2. Come up with another plan. +3. Only change one module. +4. Run the test. +5. Look at the diff. +6. Confirm that there is no problem before continuing. + +Codex is better suited for completing small tasks in a row rather than swallowing large projects all at once. + +--- + +##### Write tests and do refactoring + +Codex can help you make up tests and refactor your code. + +It can do: + +- Supplementary unit tests. +- Supplementary boundary conditions. +- Fix abnormal scenes. +- Extract duplicate logic. +- Split too long function. +- Organize component structure. +- Encapsulates API requests. + +But such tasks must have boundaries: + +- Do not change the business logic. +- No changes to the public API. +- No extraneous dependencies are introduced. +- Not extensively refactored. +- Test must be run after modification. + +Codex can be refactored, but you have to control the scope. + +--- + +##### Write documents and organize PR + +Codex is very suitable for writing engineering documents. + +For example: + +- README。 +- Installation instructions. +- Startup instructions. +- Interface documentation. +- Environment variable description. +- Project structure description. +- PR description. +- commit message。 +- Change log. + +The document is not an accessory. + +In a Codex workflow, the document itself is the contextual infrastructure. + +The clearer the documentation, the easier it will be for subsequent people and AI to take over the project. + +But be reminded of Codex: + +**Do not make up non-existent commands, and uncertain information must be clearly marked. ** + +--- + +##### Run commands, read diff, and do review + +One of the biggest differences between Codex and ordinary chat tools is that it can run commands in the project environment. + +It can: + +- Run the test. +- run lint. +- Run typecheck. +- Run build. +- View git status. +- View git diff. +- Search code. +- Check the modification results. + +This allows Codex to not just "guess the answer" but to verify the result. + +But there are risks in command execution. + +If it can be verified, you can let it be verified. + +Risky and must be approved by you. + +Do not leave it to automatic execution for operations involving the production environment, database, and real user data. + +--- + +##### When is it appropriate to use Codex? + +is suitable for Codex tasks and generally has several characteristics: + +- clear goals. +- Range controllable. +- clear context. +- results can be verified. +- Can be rolled back on failure. +- Risk acceptable. + +For example: + +- Read item. +- bug fix. +- Added small functions. +- Supplementary test. +- Write documentation. +- Optimize the front-end page. +- Clean up PR. +- Review diff. +- Handles recurring tasks. + +--- + +##### When is it not appropriate to use Codex directly? + +It is not recommended to let Codex handle it directly: + +- Production database. +- Real user data. +- payment core logic. +- Permissions and security core module. +- Large-scale architecture migration. +- Important items not backed up. +- Core business not tested. +- A task that you yourself cannot accept. + +If you can't tell whether the result is correct or not, don't let Codex complete it independently. + +Codex can improve efficiency, but it cannot make judgments for you. + +--- + +##### One sentence summary + +Codex can do more than just write code. + +> Its really important capabilities are: + +**Promote a clear software engineering task from requirements to reviewable results. ** + +You don't let it just write some code. + +You are allowing it to complete a controllable engineering task according to your project rules, context, and acceptance criteria. + + +--- + +#### The difference between Codex and ChatGPT + +Many people will ask: + +Since ChatGPT can also write code, why use Codex? + +The core difference is: + +**ChatGPT is more like a consultant. If you have questions, ask GPT, get answers from it, and then execute it yourself. So now Codex is more like an intern. We can really let it help us work and complete the tasks assigned to it. ** + +ChatGPT is suitable for helping you think about problems. + +Codex is suitable to help you advance your mission. + +A more reasonable usage is: + +**Use ChatGPT to think clearly, and then use Codex to execute the project. ** + +

+ ChatGPT与Codex的区别对比表，分为核心定位、主要方式、适合场景、项目上下文、交付结果、使用重点六个方面 +

+ +#### The difference between Codex and Cursor + +Many people compare Codex and Cursor together, because they can both help you write code, change code, and understand projects. + +But their positioning is different. + +**Cursor is more like an AI editor, and Codex is more like an engineering agent. ** + +Reasonable usage is to use it in combination: + +**Use Cursor for daily coding and partial modification, and use Codex for task promotion and project delivery. ** + +Cursor is responsible for writing with you. + +Codex is responsible for helping you run the complete mission. + +One is for IDE collaboration and the other is for Agent execution. + +This is their biggest difference. + +

+ 图片以“Cursor与Codex的区别”为标题，对比了两者在核心定位、使用位置、主要方式、适合场景、工作粒度、交付结果及使用重点等方面的差异 +

+ +#### The difference between Codex and Claude Code + +Codex is very similar to Claude Code. + +are both **agentic coding tools,** but their focus is different. + +--- + +##### Claude Code prefers long-term collaboration in the terminal + +The experience of Claude Code is more like: + +You open the terminal, put it into the project, and then continue to collaborate with it around a development task. + +It is suitable for: + +- Long read item. +- Continuous tracking of a complex task. +- Discuss and modify in the terminal. +- Handles multi-step engineering problems. +- Extend workflow through hooks, subagents, MCP and other mechanisms. + +Therefore, Claude Code is more like an AI engineering partner that stays in your terminal for a long time. + +Its strengths lie in command line workflow, deep contextual collaboration, and continuous advancement of engineering tasks. + +--- + +##### Codex is more focused on multi-terminal task execution in the OpenAI ecosystem + +The advantage of Codex is not only in the CLI, but also in the multi-terminal linkage in the OpenAI ecosystem. + +It can be used through different entrances: + +Codex CLI。 + +Codex App。 + +Codex IDE Extension。 + +Codex Web。 + +ChatGPT account system. + +GitHub/PR workflow. + +Skills and Project Rules. + +According to OpenAI official documentation, Codex CLI is the coding agent in the local terminal; Codex App provides desktop multi-threading, worktree, automation and Git functions; Codex Skills can also be reused in CLI, IDE extension and Codex app. + +Therefore, Codex is more like an engineering task platform connected to the OpenAI ecosystem. + +It is not just "writing code in the terminal", but can be transferred between multiple portals such as App, CLI, IDE, Web, etc., allowing you to manage, execute and review engineering tasks in different ways. + +--- + +##### How to choose + +If you prefer terminal workflow and want AI to stay in the project for a long time and continuously collaborate with you on complex tasks, Claude Code is very suitable. + +If you are already using the ChatGPT and OpenAI ecosystem and want to switch between CLI, desktop App, IDE, and Web, and string together tasks, diff, PR, Skills, and GitHub workflows, Codex will be more convenient. + +But there is no absolute replacement between the two. + +The final choice depends on: + +- Model capabilities. +- Context handling. +- Toolchain. +- Price. +- Team Habits. +- Your own development process. + +One sentence summary: + +**Claude Code is more like a long-term engineering partner in the terminal, and Codex is more like a multi-terminal engineering agent in the OpenAI ecosystem. ** + +

+ Claude Code与Codex的区别对比表，从核心定位、主要入口、工作风格、适合场景、扩展能力、生态优势、选择关键等7方面进行对比 +

+ +#### One sentence summary Codex + +- Basic usage: let it help you write code. +- Intermediate usage: let it help you read projects, change functions, and run tests. +- Advanced usage: Make it your project execution agent, working with rules, context, automation and team processes. + +--- + +### Codex usage entrance + +

+ 图片标题为“Codex的4个入口怎么选”，介绍了Codex的4种使用入口：2.1 Codex App、2.2 Codex CLI、2.3 Codex IDE Extensio... +

+ +If you mainly do local projects, web page exercises and daily development, it is usually enough to start with Codex App first; after you are familiar with Git, terminal and team collaboration, you can gradually add CLI, IDE Extension and Web/Cloud. + +--- + +## Part 2: Installation, configuration and environment preparation + +### Preparation before installation + +#### Account preparation + +If you are an ordinary individual user, it is recommended to prepare: + +- ChatGPT account +- A network that can normally access ChatGPT / OpenAI services +- Select the ChatGPT package that currently includes Codex; the package name, quota and functional scope will change, please refer to the official page and the actual display in your account. + +#### System preparation + +Four major forms of Codex: + + +| Method | Who is suitable | Preparation required | +| --- | --- | --- | +| Codex App desktop version | Newbies, people who want a graphical interface | Windows or macOS | +| Codex CLI | People who know a little about terminals | Terminal, Git, project environment | +| Codex IDE Extension plugin | People who use VS Code / Cursor / Windsurf | Editor + plugin | +| Codex Web / Cloud | People who want Codex to work remotely on GitHub projects | GitHub repositories | + + +Codex App supports **macOS and Windows**; Codex CLI supports macOS, Windows and Linux. + +#### Software tool preparation + +Before installing Codex, it is recommended to prepare these basic tools: + + +| Tools | Function | Download/Registration Link | +| --- | --- | --- | +| Git | Allow Codex to view code changes, generate diff, and roll back modifications | Git official download | +| VS Code / Cursor | Convenient to view and edit code | VS Code download / Cursor download | +| Terminal | PowerShell for Windows; Terminal for Mac | No need to download, the system comes with it | +| Browser | Login ChatGPT / OpenAI / GitHub | Chrome Download | +| Node.js | Commonly used for web pages, front-end, Next.js, Vite projects | Node.js download | +| Python | Commonly used for scripting, automation, and data processing | Python download | +| GitHub account | If you want to use Codex Cloud or push code, you need to prepare | GitHub registration | +| Codex App | Codex desktop version, use graphical interface to manage tasks and projects | Codex App official page | +| Codex CLI | Use Codex in the terminal, suitable for real project development | Codex CLI official documentation | +| Codex web version | After connecting to GitHub, let Codex handle projects in the cloud | Codex Web | + + +> #### Project directory preparation + +Codex is not a simple chat tool, it requires entering a specific project directory to work. The official entry process is also: After logging in to Codex, select a folder or Git repository on your computer, and then start the first task. + +It is recommended that you create a special practice directory in advance, such as: + +```text +D:\AI-Codex-Projects +``` + +You can put: + +```text +hello-web +ai-tools-page +xiaohongshu-cover-tool +landing-page-demo +``` + +Don’t let Codex operate on your most important real projects right from the start. First use the practice project to familiarize yourself with how it changes files, runs commands, and generates results. + +> #### Permissions and Security Preparations + +Codex can read, modify files, and run commands in your project directory. The official description of the CLI is: it can read, modify code, and run commands in the directory of your choice. + +So please pay attention before installation: + + +| Notes | Suggestions | +| --- | --- | +| Do not put important files directly | Use test projects first | +| Do not write the password/API key in the code | Use .env files and avoid uploading | +| Git commit before operation | Convenient rollback | +| See clearly the commands to be executed by Codex | If you don’t understand the command, ask it for explanation first | +| Don't give it permissions to the entire C drive | Select only specific project folders | + + +It is recommended that each project initialize Git: + +```text +git init +git add . +git commit -m "initial commit" +``` + +In this way, if the Codex is changed, it can be rolled back. + +--- + +### Codex App installation and getting started (most recommended for novices and the most powerful one) + +> #### Download and Installation + +##### macOS installation + +If you are using a Mac, first confirm your chip type. + +Click the Apple icon in the upper left corner of your computer and select "About This Mac." + +If displayed: + +- Apple M1 / M2 / M3 / M4: Select Apple Silicon version +- Intel: Select Intel version + +After entering the Codex App official page, download the corresponding version according to your own chip. After the download is complete, open the installation package and drag Codex into the "Applications" folder. + +After the installation is complete, open Codex in "Applications". + +When opening it for the first time, the system may prompt: + +"This is an application downloaded from the Internet. Are you sure to open it?" + +Select "Open". + +###### The difference between Intel Mac and Apple Silicon + +Mac is mainly divided into two types of chips: + + +| Type | Common models | Should be downloaded | +| --- | --- | --- | +| Apple Silicon | M1 / M2 / M3 / M4 Mac | Apple Silicon version | +| Intel Mac | Old Intel chip Mac | Intel version | + + +The simplest way to judge: + +Open "About This Mac" to view the chip information. + +If you write about Apple M series, it is Apple Silicon. + +If it says Intel Core i5, Intel Core i7, Intel Core i9, it means Intel Mac. + +Don’t choose this place wrong. Selecting the wrong version may result in inability to install, inability to open, or unstable operation. + +##### Windows Installation + +If you are using Windows, enter the Codex App official page and select the Windows version. + +The Windows version will generally jump to the Microsoft Store for installation. + +Installation steps: + +1. Open [Codex App official page](https://openai.com/zh-Hans-CN/codex/) +2. Click on the Windows download portal + +

+ Codex App在Windows平台的下载页面 +

+ +3. Jump to Microsoft Store + +

+ Microsoft Store中Codex应用的页面 +

+ +4. Click "Get" or "Install" (I have already installed it here, so it shows open) +5. Open Codex App +6. Codex App has been installed here. + + +#### Open Codex App for the first time + +##### Select project directory + +After opening the Codex App for the first time, after logging in, the system will ask you to select a project directory. + +The "project directory" here can be understood as: + +Codex Which folder to enter to work. + +For example, if you want Codex to help you create a web page, you can create a new folder in advance: + +```text +hello-codex +``` + +Then select this folder in the Codex App. + +Newbies are advised to choose a clean exercise directory for the first time, not the C drive directly, and don’t select important work items right from the start. + +Recommended directory structure: + +```text +AI-Codex-Projects +└── hello-codex + └── index.html +``` + +After selecting the project directory, Codex knows which files it should read, which files it should change, and where it should run the command. + +

+ Codex App中选择项目目录的界面 +

+ +##### Understanding the project list + +After entering the Codex App, you will usually see a list of projects on the left. + +You can understand the project list as: + +Different code folders that you hand over to Codex. + +For example: + +```text +hello-codex +ai-first-page +``` + +Each project corresponds to a local folder on your computer, or a Git repository. + +If you have opened projects in Codex App, Codex CLI, or Codex IDE Extension before, these projects may also appear in the list. + +Newbies should remember one thing: + +The project list is not a chat record list, but a "code project list". + +When you click on different projects, the file range seen by Codex is also different. + +

+ Codex App的界面左侧菜单栏 +

+ +##### Understanding thread (dialogue) + +Thread can be understood as: + +A task dialogue in the same project. + +For example, in the project `hello-Codex`, you can open multiple threads: + +```text +Thread 1：做一个首页 +Thread 2：修复按钮点击无反应的问题 +Thread 3：优化移动端样式 +Thread 4：帮我写 README +``` + +

+ Codex App的菜单界面 +

+ +Each thread has its own context. + +In other words, if you ask Codex to be the home page in Thread 1, it will continue to understand and modify around this task. + +You tell it to fix bugs in Thread 2, and it will work around another task. + +Newbies can easily understand: + +- project = a company +- thread = employees in the company + +Don't cram everything into the same thread. + +A better approach is: + +A clear task, open a thread. + +For example: + +```text +请帮我做一个个人主页 +``` + +This is a thread. + +```text +请检查为什么移动端布局错位 +``` + +This is another thread. + +In this way, the project will not be messy, and the Codex will make it easier to understand the task boundaries. + +##### Understanding the task window + +The task window is where you talk to Codex and arrange work. + +You can enter the task here, such as: + +```text +请帮我做一个简单网页，黑色背景，中间显示 Hello, Codex。 +``` + +

+ Codex App中“做一个首页”任务的执行界面 +

+ +You can also continue to ask: + +```text +请把这个页面改得更像科技产品首页。 +``` + +These contents usually appear in the task window: + + +| Content | Function | +| --- | --- | +| Your task description | Tell Codex what to do | +| Codex’s plan | What it plans to do | +| Codex execution process | It is reading files, changing files, and running commands | +| Summary of Codex | What was changed in the end | +| Subsequent input box | You can continue to let it be modified | + + +When using it for the first time, do not write too complex tasks. + +Not recommended: + +```text +帮我做一个完整的 AI 工具平台，要有登录、支付、数据库、后台管理。 +``` + +Recommended: + +```text +请帮我做一个简单的产品介绍页，只用 HTML 和 CSS。 +``` + +The clearer the task, the easier it is to do the Codex well. + +##### Understanding review pane + +Review pane can be understood as: + +Check the Codex to see what has been changed. + +After modifying the file in Codex, you should not just read its text summary, but open the review pane to see the actual changes. + +

+ Codex App中“做一个首页”任务的review pane界面 +

+ +It will tell you: + +- which files were modified +- where new codes have been added +- where code was removed +- What changes are acceptable +- Which changes can be rolled back + +> Newbies can understand review pane as: + +Codex's "Operation Inspection Area". + +You don't just trust the Codex after it's written, but you have to check what homework it handed in here. + +If you are not satisfied with a certain line of code, you can leave a comment in the corresponding position and let Codex continue to modify it according to your comments. + +For example, you can comment: + +```text +这里的按钮颜色太亮了，改成更克制的深蓝色。 +``` + +or: + +```text +这段代码太复杂，请改成新手更容易理解的写法。 +``` + +##### Understanding diff + +Diff is a comparison of code changes. + +

+ Codex App界面，左侧为项目文件夹，中间是代码编辑区域，右侧是review pane +

+ +> Newbies can understand it this way: + +```text +绿色 = 新增内容 +红色 = 删除内容 +``` + +For example, Codex originally did not have a title, but later added a line: + +```html +

Hello, Codex

+``` + +This line will be displayed as new. + +If Codex deletes an old section of code, that section will appear as deleted. + +The function of Diff is to let you see clearly: + +What exactly has been changed in Codex. + +Don’t just look at the final page, and don’t just look at the summary of the Codex. + +What really matters is looking at the diff. + +Because Codex may sometimes: + +- I changed things that you didn’t ask for. +- Removed some code you still need +- Make simple code complex +- Modified multiple files but did not explain clearly + +So when you first start using it, you need to develop a habit: + +```text +每次 Codex 完成任务后，先看 diff，再决定要不要接受。 +``` + +##### Recommended operation process after opening for the first time + +When opening Codex App for the first time, you can follow this sequence: + +```text +1. 登录 ChatGPT +2. 选择一个练习项目目录 +3. 新建或选择一个 thread +4. 在任务窗口输入一个简单任务 +5. 等 Codex 修改文件 +6. 打开 review pane +7. 查看 diff +8. 确认没有问题后再继续修改 +``` + +Recommended first task: + +```text +请帮我做一个简单网页，要求： +1. 黑色背景 +2. 页面中间显示大字 Hello, Codex +3. 字体白色 +4. 页面整体水平和垂直居中 +5. 只使用 HTML 和 CSS +``` + +This task is simple enough and suitable for familiarizing yourself with the basic process of Codex App. + + +##### Several concepts that beginners need to remember + + +| Concept | Simple understanding | +| --- | --- | +| Project directory | Your company's address | +| Project list | Your company's project department | +| thread | An employee of a project department | +| Task window | A place to give instructions to employees | +| review pane | Check for changes | +| diff | Comparison of new and deleted codes | + + +#### Basic use of Codex App + +##### Basic layout + +You can see that the Codex App is a classic three-column layout + +On the left is the task list + +The middle is the dialogue window + +On the right is the multi-functional area + +

+ Codex App的基础布局 +

+ +##### New conversation + +###### Use Project + +We can open a new conversation to perform a new task + +After opening a new conversation, you need to select which project the new conversation belongs to. + +

+ Codex App的界面，左侧任务列表中“hello - Codex”项目被选中 +

+ +Of course, we can also directly click on the small button on the right side of the project to directly open a new conversation corresponding to the project. + +

+ Codex App的界面，左侧任务列表中“hello - Codex”项目被红色框突出显示 +

+ +###### Do not use the project + +Click on the unused project, and the corresponding conversation will be displayed in the conversation, which can be used as a question unrelated to the project. + +

+ Codex App的对话界面 +

+ +

+ Codex App的界面 +

+ +##### Search + +There are too many dialogues in later tasks, but I just remember that some key times cannot find the corresponding task dialogues. You can search here directly, search for keywords, and you will find the corresponding task dialogues. + +

+ Codex App的界面，左侧为任务列表，中间是对话窗口，右侧是多功能区域 +

+ +##### Plugin + +There are many functions, which will be discussed later. + +##### Automation + +There are many functions, which will be discussed later. + +> ##### Project + +###### Create project + +You can create a new project directly in Codex or use an existing project + +The created or selected project will appear in the project bar to facilitate subsequent management. + +

+ Codex App中“自动化”功能界面 +

+ +###### thread + +thread is a "single task conversation" in a project + +

+ Codex App中“自动化”页面 +

+ +For example, you have a project called: + +```text +hello-codex +``` + +You can open multiple threads in this project: + + +| Thread | Represented task | +| --- | --- | +| Thread 1 | Make a home page | +| Thread 2 | Fix button click does not respond | +| Thread 3 | Optimize mobile style | +| Thread 4 | Help me write README | +| Thread 5 | Check if there are any errors in the project | + + +You can understand it this way: + +```text +Project 项目 = 一个代码文件夹 +Thread = 这个项目里的一个具体任务 +``` + +For example: + +```text +项目：小红书封面生成器 +Thread 1：做首页 +Thread 2：修复上传图片失败 +Thread 3：优化手机端布局 +Thread 4：写项目说明文档 +``` + +> **Why is there a thread? ** + +Because different tasks are best done separately. + +If you cram "making the homepage, fixing bugs, changing styles, and writing documents" into one conversation, Codex will easily get confused in context, and it will be difficult for you to check what it has changed. + +A better usage is: + +```text +一个明确任务 = 一个 thread +``` + +For example, if you want to make a page: + +```text +请帮我做一个 AI 工具介绍页。 +``` + +This is a thread. + +If you find something wrong with the button later, open a new thread: + +```text +请检查为什么首页按钮点击后没有反应。 +``` + +One sentence summary: + +> **Thread is the task dialogue in Codex App. A thread is dedicated to processing a specific task. ** + + +###### Waiting for approval + +When we perform tasks in Codex, we often require users to approve permissions. + +and the tags waiting for approval will be prompted in the corresponding dialogue. + +After clicking on the corresponding conversation and then clicking on Allow, Codex will continue with the next work. + +

+ Codex App中“等待批准”界面 +

+ +###### Archive + +Archive Archive can be understood as putting away a thread that has been completed and does not need to be processed for the time being. + +Its function is not to delete code, nor to merge code, but to make your task list cleaner. + +

+ Codex App中“自动化”功能界面 +

+ +For example, if you complete these tasks: + +```text +Thread 1：优化移动端样式 +Thread 2：做一个首页 +Thread 3：做一个首页 + +``` + +Thread 2 and Thread 3 have been completed, and you don’t plan to use Thread 1 anymore, so you can archive them. + +After archiving, they will no longer occupy the position of the current task list, and your project interface will be cleaner. + +**Cancel the archive. Of course, you can also find the archived conversation in the settings and restore it** + +

+ Codex App中“已归档对话”界面 +

+ +##### Settings + +###### Remaining balance + +Here you can see the quota, rate limit or usage of the current account. + +Different packages, workspaces, models and versions may display different restrictions; the specific length of use, when to restore, and whether additional credits can be purchased are subject to the current Codex interface and official instructions. + +

+ Codex App中“剩余额度”页面 +

+ +##### Dialog window + +###### Permission Control + +###### Sandbox + +To know permission control, you must first know the concept of a sandbox (Sandbox) + +You can understand it as: + +> Codex You can work inside the fence, but you can't just go outside the fence and mess with your computer. + +Because Codex App is not an ordinary chat tool. It can read files, change files, and run commands, so there must be a "fence" to limit where it can touch, whether it can be connected to the Internet, and whether it can change files outside the project. According to the official documentation, Codex's sandbox mode includes `read-only`, `workspace-write`, and `danger-full-access`, which are used to control file system and network access boundaries. + +###### **Simply put** + +Assume your project folder is: + +```text +D:\AI-Codex-Projects\hello-codex +``` + +If the sandbox is turned on, Codex can only work within the scope of this project folder, for example: + +```text +可以看 index.html +可以改 style.css +可以运行 npm run dev +``` + +But if it wants to do these things, it may need your approval: + +```text +访问桌面文件 +读取下载文件夹 +修改项目外的文件 +联网下载东西 +运行高风险命令 +``` + +So: + +```text +Sandbox = 给 Codex 设置工作边界 +``` + +###### Three major permissions + +

+ Codex App的权限控制界面 +

+ + +```text +请求批准 +替我审批 +完全访问权限 +``` + +can be understood as follows: + + +| Options you see | Relationship with Sandbox | +| --- | --- | +| Request approval | There are sandbox restrictions, please ask you first for out-of-bounds operations | +| Approval for me | Let the system automatically determine part of the approval for you | +| Full access | Release the sandbox and can perform any operation on the computer, with the highest risk | + + +Beginners are advised to enable: + +**Request approval or automatic approval class options**. If you are new, prefer a mode that does not let go of project boundaries: let Codex work within the current project, but still stop and let you confirm when it encounters out-of-bounds, networked, or high-risk commands. The names of permission options may be different in different versions. The core principle is: don't enable full access at the beginning. + +###### One sentence summary + +> **Sandbox The sandbox is the safety fence of Codex. ** + +It determines whether the Codex can: + +```text +看文件 +改文件 +访问项目外目录 +联网 +运行命令 +``` + +###### Model model selection + +###### Inference strength + +You can see that the inference intensity is divided into 4 levels. The higher the intensity, the stronger the inference ability and the greater the time and token consumption. + +

+ Codex App中“做一个首页”任务的对话窗口界面 +

+ + +| Options | In simple terms | Fit for the task | +| --- | --- | --- | +| Low | Think less, be fast, save credit | Change copywriting, change colors, minor issues | +| Medium | Balance speed and quality | Ordinary web pages, simple bugs, daily development | +| High | Think deeper, more suitable for complex problems | Multiple file modifications, complex bugs, refactoring | +| Super high | The most serious, the slowest, the most time-consuming | Difficult questions, architecture analysis, bugs that cannot be fixed repeatedly | + + +###### Model selection + +Different models can be selected here. Model capabilities, available scope, and consumption vary with account packages, regions, versions, and model catalogs. For ordinary tasks, just use the default recommended model; for complex tasks, consider switching to a stronger model or increasing the inference intensity. + +

+ Codex App中“做一个首页”任务的界面 +

+ +###### Speed + +Some models or versions will provide service levels such as standard/fast. + +The speed increase, credit consumption and availability of fast mode are subject to the current interface display. You can consider turning it on when the task is urgent and the quota is sufficient; it does not need to be turned on by default for daily tasks. + +

+ Codex App中“做一个首页”任务的界面 +

+ +###### Boot + +Can interrupt the conversation midway + +When we find that the AI misunderstands what we mean during the execution of AI, we should not let it continue to execute. At this time, manual guidance should be provided in a timely manner + +If you do not choose to guide, it will be queued for execution. Only after the previous task is executed, the AI will execute the next task you send. + +

+ Codex App的界面，左侧为项目管理区域，显示“做一个首页”项目，有“你好”和“做一个首页”两个任务，其中“你好”任务已结束22小时 +

+ +###### Plan Mode + +After turning on the plan mode, Codex will not start working immediately. Instead, it will sort out a work plan first and confirm it with us before starting work. + +For all complex tasks, it is recommended to turn on the planning mode first, so that leaks can be checked and filled. + +

+ Codex App中“做一个首页”任务的对话窗口界面 +

+ +

+ Codex App中“极简动效增强计划”的对话窗口 +

+ +##### Multifunctional Area + +###### Comments + +Comments in the upper right corner area of the multi-function + +When we open the page using Codex’s built-in browser, we will find a comment function + +We can let AI help us modify only specific parts of the page + +

+ Codex App的界面 +

+ +

+ Codex App的界面，左侧为项目列表，右侧是“Hello, Codex.”的页面 +

+ +

+ Codex App的界面 +

+ + +--- + +### Codex CLI installation and getting started + +Codex CLI is the command line version of Codex. + +It is suitable for people who are willing to open a terminal, such as PowerShell, Terminal, iTerm, Windows Terminal. + +#### macOS / Linux installation + +There are two common installation methods for macOS. + +##### Method 1: Use npm to install + +First make sure Node.js is installed on your computer. + +Open Terminal and enter: + +```text +node -v +npm -v +``` + +If you can see the version number, it means that Node.js and npm are available. + +Then install the Codex CLI: + +```text +npm install -g @openai/codex +``` + +After the installation is completed, check whether the installation is successful: + +```text +codex --version +``` + +Or run directly: + +```text +codex +``` + +--- + +##### Method 2: Use Homebrew to install + +Mac users can also use Homebrew: + +```text +brew install --cask codex +``` + +After installation, run: + +```text +codex +``` + +> Xiaobai’s suggestion: + +- If you have installed Node.js, use npm. +- If you are used to Homebrew, just use brew. + +#### Windows Installation + +Windows users are advised to use PowerShell or Windows Terminal. + +The first step is to install Node.js. + +After the installation is complete, open PowerShell and enter: + +```text +node -v +npm -v +``` + +If you can see the version number, the installation is successful. + +The second step is to install the Codex CLI: + +```text +npm install -g @openai/codex +``` + +The third step is to check whether the installation is successful: + +```text +codex --version +``` + +Or run directly: + +```text +codex +``` + +For Windows users, it is recommended not to run Codex in the system directory when using it for the first time. + +Do not operate directly in these locations: + +```text +C:\ +系统目录 +桌面 +下载文件夹 +重要资料文件夹 +``` + +It is recommended to create a new exercise directory: + +```text +D:\AI-Codex-Projects\hello-codex +``` + +#### First run + +After the installation is complete, enter in the terminal: + +```text +codex +``` + +The first time you run Codex, you will be prompted to log in. + +There are two common login methods for Codex CLI: + +```text +1. 使用 ChatGPT 账号登录 +2. 使用 OpenAI API key 登录 +``` + +The first method is recommended for newbies: log in with a ChatGPT account. + +##### Method 1: Log in using ChatGPT account + +This is the most suitable method for ordinary users and novices. + +Enter in the terminal: + +```text +codex +``` + +Or: + +```text +codex login +``` + +Then select: + +```text +Sign in with ChatGPT +``` + +The login process is roughly as follows: + +```text +1. 终端输入 codex 或 codex login +2. 选择 Sign in with ChatGPT +3. 浏览器会自动打开登录页面 +4. 输入你的 ChatGPT 账号 +5. 登录成功后，浏览器会把登录结果传回终端 +6. 回到终端，Codex CLI 就可以使用了 +``` + +##### Method 2: Log in using API key + +Codex CLI also supports logging in using OpenAI API key. + +API key login is more suitable for developers, automated scripts, CI/CD, server tasks and other scenarios. + +> Newbies can understand it this way: + +```text +ChatGPT 登录 = 走 ChatGPT 账号和套餐额度 +API key 登录 = 走 OpenAI Platform API 计费 +``` + +If you want to log in with an API key, first go to OpenAI Platform to create an API key. + +Then set the environment variable in the terminal. + +macOS / Linux can be written like this: + +```text +export OPENAI_API_KEY="你的_API_Key" +printenv OPENAI_API_KEY | codex login --with-api-key +``` + +Windows PowerShell can be written like this: + +```text +$env:OPENAI_API_KEY="你的_API_Key" +$env:OPENAI_API_KEY | codex login --with-api-key +``` + +After successful login, Codex CLI will save the login information and run it again later: + +```text +codex +``` + +and you can continue to use it. + +--- + +##### What is the difference between ChatGPT login and API key login? + + +| Comparison | ChatGPT account login | API key login | +| --- | --- | --- | +| Suitable for people | Ordinary users, novices | Developers, automation, CI/CD | +| Usage quota | Related to ChatGPT package | Billed by OpenAI Platform API | +| Difficulty to get started | Easier | Slightly more complex | +| Do you recommend it for beginners | Recommended | Not recommended for the first time | +| Suitable for local practice | Suitable | OK, but not necessary | +| Suitable for automated scripts | General | More suitable | + + +##### API key Login Notes + +API key is very sensitive and cannot be leaked casually. + +Do not use API key: + +```text +写进代码里 +发给别人 +截图公开 +上传到 GitHub +放进 README +放进前端网页 +提交到 Git 仓库 +``` + +If the API key is accidentally leaked, go to OpenAI Platform immediately to delete or regenerate it. + +Although API key login is convenient for automation, it will be billed based on API usage, so novices should not run tasks for a long time without knowing the cost rules. + +--- + +##### View current login status + +You can use the following command to check whether you are currently logged in: + +```text +codex login status +``` + +If you need to log out, you can run: + +```text +codex logout +``` + +After exiting, you need to log in again the next time you run the Codex CLI. + +#### CLI basic commands + +Codex CLI commands can be divided into two categories: + + +| Type | Usage location | Function | +| --- | --- | --- | +| Terminal command | Enter in PowerShell / Terminal | Start, log in, update, diagnose, manage Codex | +| Slash command | Enter after entering Codex | Cut model, adjust permissions, view diff, generate rules, exit session | + + +##### CLI terminal command + +CLI terminal command is the command entered in PowerShell / Terminal / Windows Terminal. + +###### The most commonly used terminal commands for beginners + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| `codex` | Start Codex CLI | Open the terminal version of Codex | Use after entering the project | +| `codex --version` | View version | Check if the installation is successful | The first step after installation | +| `codex --help` | View help | View which commands are supported | Don’t know how to use the command | +| `codex login` | Log in to Codex | Log in with ChatGPT account or API key | First time use | +| `codex login status` | Check the login status | Check if there is currently a login | When the login is abnormal | +| `codex logout` | Log out | Clear local login status | Change account, public computer | +| `codex doctor` | Check environment problems | Automatically generate diagnostic reports | Startup failure, login failure, environment exception | +| `codex update` | Update Codex | Update CLI version | When upgrade is required | +| `codex app` | Open Codex App | Open the desktop version from the terminal | When you want to switch to the graphical interface | + + +--- + +###### Enter project related commands + + +| Command | Function | Example | In simple terms | +| --- | --- | --- | --- | +| `cd 项目目录` | Enter the project folder | `cd D:\\AI-Codex-Projects\\hello-Codex` | Go to the project first | +| `codex` | Start Codex in the current directory | `codex` | Let Codex work in the current project | +| `codex --cd 项目路径` | Specify directory to start | `codex --cd D:\\AI-Codex-Projects\\hello-Codex` | Specify the project directly without cd first | +| `codex -C 项目路径` | --abbreviation for cd | `codex -C ./hello-Codex` | Shorter notation | + + +The simplest way recommended by novices: + +```text +cd 项目目录 +codex +``` + +Do not run Codex directly in these places: + +```text +C:\ +桌面 +下载文件夹 +系统目录 +重要资料文件夹 +``` + +--- + +###### Login related commands + + +| Command | Function | Suitable for scenarios | +| --- | --- | --- | +| `codex login` | Open the browser by default and log in with a ChatGPT account | First choice for beginners | +| `codex login --device-auth` | Log in with device code | The remote server and browser cannot be opened | +| `printenv OPENAI_API_KEY \| codex login --with-api-key` | Login with API key | Developer, Automation, CI/CD | +| `codex login status` | Check the current login method and status | Not sure if you are logged in | +| `codex logout` | Delete the login credentials saved on this machine | Change account, public computer | + + +Windows PowerShell Login using API key: + +```text +$env:OPENAI_API_KEY | codex login --with-api-key +``` + +--- + +###### Send tasks directly at startup + + +| Command | Function | Example | +| --- | --- | --- | +| `codex "任务内容"` | Start Codex and send the first task directly | `codex "请解释这个项目结构"` | +| `codex -i 图片路径 "任务"` | Attached pictures for analysis | `codex -i __CODX_TOKEN_000__ "分析这个报错"` | +| `codex --image 图片路径 "任务"` | The complete writing method of `-i` | `codex --image __CODX_TOKEN_000__ "根据截图优化页面"` | +| `codex --search "任务"` | Allows search capabilities | `codex --search "查一下这个库的新用法"` | + + +Suitable for: + +```text +简单解释项目 +分析报错截图 +根据 UI 截图提修改建议 +查新版本文档 +``` + +Newbies are more recommended to run first: + +```text +codex +``` + +Enter the task after entering to make it easier to observe the execution process. + +--- + +###### Model, permissions, and sandbox related commands + + +| Command | Function | In simple terms | Newbie suggestions | +| --- | --- | --- | --- | +| `codex --model 模型名` | Specify model | Select AI brain | Default is enough, change it for complex tasks | +| `codex -m 模型名` | `--model` Abbreviation | Shorter writing | No need to force memorization | +| `codex --sandbox read-only` | Read-only mode | Can only be viewed, try not to change | Used only when analyzing the project | +| `codex --sandbox workspace-write` | The current project can be read and written | Able to work in the project | Daily recommendations | +| `codex --sandbox danger-full-access` | Completely loosen restrictions | Great permissions | Novices not allowed to use | +| `codex --ask-for-approval on-request` | Ask you first for sensitive operations | Request approval | Recommended for newbies | +| `codex -a on-request` | Approval mode abbreviation | Shorter writing | Recommended | + + +Recommended combination for novices: + +```text +codex --sandbox workspace-write --ask-for-approval on-request +``` + +means: + +```text +Codex 可以在当前项目里工作，但敏感操作要先问我。 +``` + +Don’t think of this as a trouble-saving mode: + +```text +codex --sandbox danger-full-access +``` + +--- + +###### Non-interactive task command + + +| Command | Function | In simple terms | Suitable for the scene | +| --- | --- | --- | --- | +| `codex exec "任务"` | One-time task execution | Don’t enter a long conversation, it will end after running | Automation, inspection, report generation | +| `codex e "任务"` | Abbreviation for `exec` | Same as above | Fast execution | +| `codex exec --cd 项目路径 "任务"` | Specify the directory to execute the task | Execute it once in a project | Automation script | +| `codex exec resume` | Resume the exec session | Continue with the last non-interactive task | After an automated task is interrupted | +| `codex exec resume --last` | Restore the most recent exec session | Continue with the most recent task | The most common recovery method | + + +Example: + +```text +codex exec "请检查当前项目有没有明显问题" +``` + +Priority is given to beginners: + +```text +codex +``` + +Use `codex exec` after you are familiar with it. + +--- + +###### Session management command + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| `codex resume` | Restore the previous session | Continue with the previous thread | Not finished last time | +| `codex resume --last` | Restore the most recent session | Continue with the most recent task | Most commonly used | +| `codex archive` | Archive session | Put away unused tasks | Task completed or no longer required | +| `codex unarchive` | Restore archived session | Retrieve archived tasks | Want to continue after archiving | +| `codex fork` | Copy the old session into a new thread | Keep the original task and try a new direction | Try multiple solutions | + + +In simple terms: + +```text +resume = 接着做 +archive = 收起来 +unarchive = 找回来 +fork = 复制一份去试新方案 +``` + +--- + +###### Diagnostic, update and maintenance commands + + +| Command | Function | When to use | +| --- | --- | --- | +| `codex doctor` | Generate diagnostic report | Codex startup exception, login exception, environment exception | +| `codex update` | Check and update the Codex CLI | When you want to upgrade the version | +| `codex completion` | Generate command completion script | People who often use terminal | +| `codex features list` | Check the function switch | Check whether the function is turned on | +| `codex features enable 功能名` | Turn on a function | Advanced configuration | +| `codex features disable 功能名` | Turn off a function | Advanced configuration | + + +Most commonly used by noobs: + +```text +codex doctor +codex update +``` + +Don’t remember anything else. + +--- + +###### Cloud, MCP, plugin related commands + + +| Command | Function | Does Newbie need it | +| --- | --- | --- | +| `codex cloud` | Browse or perform Codex Cloud tasks in the terminal | Not used for the time being | +| `codex apply` | Apply the diff generated by Codex Cloud to local | Learn after using Cloud | +| `codex mcp list` | View MCP Tools | Not used yet | +| `codex mcp add` | Add MCP server | Advanced | +| `codex mcp remove` | Delete MCP server | Advanced | +| `codex plugin list` | View plugin | Not used at the moment | +| `codex plugin add` | Install plugin | Advanced | +| `codex plugin remove` | Delete plugin | Advanced | + + +Don't worry about these at the novice stage. + +Waiting for you to start using: + +```text +Codex Cloud +外部工具 +数据库 +Figma +项目管理工具 +MCP +插件 +``` + +Learn this type of command again. + +--- + +###### Sandbox test command + + +| Command | Function | Who it is suitable for | +| --- | --- | --- | +| `codex sandbox` | Run commands under Codex's sandbox rules | Advanced users | +| `codex sandbox --cd 项目目录 -- 命令` | Specify the directory to run the sandbox command | Debugging permission issues | +| `codex execpolicy` | Check whether a command will be allowed, asked, or blocked | Advanced security configuration | + + +There is no need to learn it at the beginner level. + +Just remember: + +```text +默认用 workspace-write + on-request。 +不要随便 full access。 +``` + +--- + +###### Dangerous commands and dangerous parameters + + +| Commands/Parameters | Why it’s dangerous | Newbie advice | +| --- | --- | --- | +| --sandbox danger-full-access | Release file and network restrictions | Do not use | +| --dangerously-bypass-approvals-and-sandbox | Skip approval and sandbox | Do not use | +| --yolo | Alias for the dangerous parameter above | Do not use | +| --ask-for-approval never | Don’t ask you again when operating Codex | Don’t use it if you are new to it | +| sudo | System-level content may be modified | Don’t allow it if you don’t understand | +| rm -rf | May delete a large number of files | High risk | +| git reset --hard | Unsaved changes may be lost | Confirm first | +| git clean -fd | Untracked files may be deleted | Confirm first | +| curl xxx \| sh | Download the script and execute it directly | High risk | + + +After seeing these contents, ask Codex first: + +```text +请解释这条命令的作用、风险，以及有没有更安全的替代方案。 +``` + +--- + +###### The most recommended command for beginners to remember + + +| Ranking | Commands | Why it matters | +| --- | --- | --- | +| 1 | Codex | Start Codex CLI | +| 2 | `codex login` | Login account | +| 3 | `codex login status` | Check login status | +| 4 | `codex doctor` | Troubleshoot environmental issues | +| 5 | `codex --version` | View version | +| 6 | `codex resume --last` | Continue from the last task | +| 7 | `codex archive` | Archive unused tasks | +| 8 | `codex update` | Update Codex | +| 9 | `codex exec "任务"` | One-time execution task | +| 10 | `codex logout` | Log out | + + +--- + +###### Recommended workflow for novices + + +| Steps | Commands | Purpose | +| --- | --- | --- | +| 1 | cd project directory | enter the project folder | +| 2 | git status | View the current project status | +| 3 | Codex | Start Codex CLI | +| 4 | Enter the task | Let Codex start working | +| 5 | /diff | View changes in Codex | +| 6 | git diff | Check again in Git | +| 7 | git add . | Temporarily store satisfactory modifications | +| 8 | git commit -m "Description" | Save a version | +| 9 | `codex archive` or `/quit` | Archive task or exit | + + +##### CLI slash command + +It is not entered in the external PowerShell / Terminal, but after entering the Codex, enter `/` in the Codex input box. + +###### The most commonly used commands for beginners + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| /model | Switch model and reasoning strength | Change AI brain and thinking depth | When the task is too difficult, too slow or you want to save credits | +| /permissions | Adjust permissions | Control whether Codex can change files, connect to the Internet, and run commands | When you want to tighten or relax permissions | +| /diff | View code changes | See what has been changed in Codex | Must read after modifying files in Codex | +| /plan | Enter planning mode | Let Codex give you the plan first, don’t rush to change the code | Complex tasks, bug fixes, before refactoring | +| /init | Generate AGENTS.md | Create project rules file | The first time a new project uses Codex | +| /status | View the current status | View model, permissions, context, token and other information | When not sure about the current configuration | +| /quit | Exit Codex CLI | End current session | Exit after task is completed | +| /exit | Exit the Codex CLI | Similar to /quit | Exit after task completion | + + +--- + +###### Model is related to speed + + +| Command | Function | When to use | +| --- | --- | --- | +| /model | Select model and inference strength | When you want to switch GPT-5.5, mini, low/medium/high inference | +| /fast | Turn on or off Fast mode | When you want the supported models to respond faster | +| /personality | Adjust your answer style | When you want to make your Codex more concise, explanatory, or collaborative | +| /status | Check the current model and context status | When you want to confirm what model is being used | + + +Newbie suggestions: + +```text +普通任务：默认模型 + 中推理 +复杂 bug：高推理 +简单改文案：低推理 +不要所有任务都开最高推理 +``` + +--- + +###### Permissions related to security + + +| Command | Function | In simple terms | Suggestion | +| --- | --- | --- | --- | +| /permissions | Modify permissions policy | Control what Codex can do | Keep "Request Approval" for newbies | +| /approve | Approve an automatically rejected operation | Let the blocked operation retry | Understand the risks before using | +| /sandbox-add-read-dir | Additional permission to read a certain directory | Allow Codex to read the specified directory outside the project | Windows-specific scenarios, rarely used | +| /status | View permissions and writable directories | Confirm the current permission range of Codex | Check after changing permissions | + + +> Newbie suggestions: + +```text +默认用 /permissions 保持请求批准。 +不要随便放开完全访问权限。 +看不懂的操作，不要用 /approve。 +``` + +--- + +###### Code inspection is related to Review + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| /diff | View the current Git diff | See what is added and what is deleted | Must read after modification | +| /review | Let Codex review the current changes | Let it check the code for problems | Check before submission | +| /copy | Copy the latest Codex output | Quickly copy the results | Copy plan, summary, command description | +| /raw | Switch raw output mode | Convenient for copying long logs or terminal output | When the log is very long | + + +Recommended process: + +```text +Codex 修改完成 +→ /diff 查看改动 +→ /review 检查问题 +→ 没问题再 git commit +``` + +--- + +###### Session management related + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| /new | Start a new conversation | Change to a new task in the current CLI | The current task is over and you want to start a new one | +| /clear | Clear the terminal and start a new chat | Clear the current display and context | The interface is too messy and want to start over | +| /resume | Resume the previous session | Continue with the previous task | The last task was not completed | +| /archive | Archive the current session and exit | Put away unused tasks | The task is completed or the plan is no longer needed | +| /fork | Copy the current session into a new thread | Keep the original idea and try another branch | Want to try another solution | +| /side | Open a temporary side conversation | Ask a small question without affecting the main task | Want to temporarily confirm a point | +| /quit | Exit CLI | End current use | Task completed | +| /exit | Exit CLI | Same as /quit | Task completed | + + +> Differences for beginners: + +```text +/new = 开新任务 +/clear = 清理并重新开始 +/archive = 收起当前任务 +/fork = 复制当前任务去试新方案 +/side = 临时问个小问题 +``` + +--- + +###### The context is related to long conversations + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| /compact | Compress the current conversation | Summarize long conversations into key points | When the conversation is very long and the context is almost full | +| /status | View context usage | See how much context space is left | After the task has been completed for many rounds | +| /mention | Attached files or folders | Specify Codex to focus on a certain file | Want it to only view certain files | +| /ide | Introduce the current context of the IDE | Bring in the files opened by the editor | Use with VS Code / Cursor | + + +Newbie suggestions: + +```text +对话长了用 /compact。 +想让 Codex 看特定文件，用 /mention。 +不想让它乱扫整个项目，就明确指定文件。 +``` + +--- + +###### Project rules are related to capabilities + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| /init | Generate AGENTS.md | Create project rules file | Use Codex for the first time in a new project | +| /skills | Browse and use Skills | Select special skills | Do UI, write documents, review and other special tasks | +| /memories | Configuration memories | Control whether Codex uses or generates memories | When you want to manage long-term preferences | +| /goal | Set task goals | Give Codex a continuous goal | Large tasks, long tasks | +| /apps | Browse connectable apps | Let Codex use external apps | When connecting to external tools | +| /plugins | Manage plugins | View or enable plugin capabilities | When plugin tools are needed | +| /mcp | View MCP tools | See what external tools Codex can call | Check after configuring MCP | + + +Newbies are given priority to master: + +```text +/init +/skills +``` + +Other commands can be learned later. + +--- + +###### Terminal and background tasks related + + +| Command | Function | In simple terms | Usage scenarios | +| --- | --- | --- | --- | +| /ps | View background terminal tasks | See which commands are still running | npm dev, test, and build are still running | +| /stop | Stop the background terminal task | Terminate the command running in the background | The command is stuck or does not want to continue running | +| /raw | Raw output mode | Convenient for copying terminal logs | When the log is very long | + + +Common scenarios: + +```text +Codex 跑了 npm run dev +你想看它还在不在跑 +→ 用 /ps + +命令卡住了 +→ 用 /stop +``` + +--- + +###### The interface is related to shortcut keys + + +| Command | Function | In simple terms | Is it commonly used | +| --- | --- | --- | --- | +| /theme | Switch code highlighting theme | Change terminal display style | General | +| /statusline | Configure the bottom status bar | Display models, tokens, Git branches, etc. | Advanced | +| /title | Configure the terminal title | Let the window title display project information | Advanced | +| /keymap | Modify shortcut keys | Customize operation keys | Advanced | +| /vim | Switch Vim editing mode | Use Vim to edit the input box | For people who know Vim | +| /debug-config | View the configuration level | Check why the configuration does not take effect | Advanced troubleshooting | + + +You don’t need to use these at the novice stage. + +--- + +> ###### Developers and Premium Features + + +| Command | Function | Who it is suitable for | +| --- | --- | --- | +| /experimental | Turn on the experimental function | Users who like to try new things | +| /hooks | View and manage lifecycle hooks | Advanced users, team projects | +| /feedback | Send logs or feedback | When you encounter a problem and need feedback | +| /agent | Switch active agent thread | People using subagent workflow | + + +These are not required for beginners. + +Novices only need to know it, and there is no need to master it at the beginning. + +--- + +###### The 8 most recommended tips for beginners to remember + + +| Ranking | Commands | Why it matters | +| --- | --- | --- | +| 1 | /diff | See what was actually changed in Codex | +| 2 | /plan | For complex tasks, let them be planned first | +| 3 | /permissions | Control permissions to avoid arbitrary changes | +| 4 | /model | Switch model and inference strength | +| 5 | /status | View current model, permissions, context | +| 6 | /init | Generate project rules | +| 7 | /compact | Key points of long dialogue compression | +| 8 | /quit | Exit Codex | + + +--- + +###### Recommended usage process for novices + + +| Steps | Commands | Purpose | +| --- | --- | --- | +| 1 | /init | Generate project rules | +| 2 | /permissions | Make sure the permissions are not too large | +| 3 | /model | Confirm model and inference strength | +| 4 | /plan | Plan complex tasks first | +| 5 | Enter the task | Let Codex start working | +| 6 | /diff | Check for code changes | +| 7 | /review | Let Codex check again | +| 8 | /status | View current status and context | +| 9 | /compact | Compress when the conversation is too long | +| 10 | /quit | Exit Codex | + + +--- + +###### One sentence summary + +Slash Commands are shortcut control commands in Codex CLI. + +Novices don’t need to memorize them all, just remember these few first: + +```text +/diff 看改动 +/plan 先规划 +/permissions 控权限 +/model 换模型 +/status 看状态 +/init 建规则 +/compact 压缩长对话 +/quit 退出 +``` + +#### How the CLI works + +The working method of Codex CLI can be understood as a complete process: + +```text +读取项目 +→ 理解任务 +→ 提出计划 +→ 修改文件 +→ 运行命令 +→ 等待批准 +→ 展示 diff +→ 处理失败 +``` + +Newbies don’t need to understand all the technical details at the beginning, as long as they know: + +Codex CLI will not only chat, it will actually enter the current project directory, read files, modify files, run commands, and then show you the results for inspection. + +--- + +###### Codex How to read items + +When you run in the project directory: + +```text +codex +``` + +Codex will treat the current directory as the workspace. + +For example, if you start in this directory: + +```text +D:\AI-Codex-Projects\hello-codex +``` + +Codex will work around the contents of this folder. + +It may read: + + +| Content | Function | +| --- | --- | +| Project files | Understanding the current code | +| Folder structure | Determine whether the project is a front-end, back-end or script project | +| package.json | Determine startup command, dependencies, project type | +| README.md | Understand the project description | +| AGENTS.md | Read the work rules you wrote for Codex | +| Error log | Analyze the cause of the problem | +| Git status | Determine which files have been modified | + + +In simple terms: + +```text +你在哪个文件夹启动 Codex， +Codex 就默认把哪个文件夹当成当前项目。 +``` + +So don’t start randomly in these places: + +```text +C:\ +桌面 +下载文件夹 +系统目录 +重要资料文件夹 +``` + +Recommended practices: + +```text +cd 项目目录 +codex +``` + +--- + +###### How Codex understands tasks + +After you enter the task, Codex will first determine what you want it to do. + +For example, if you enter: + +```text +请帮我做一个简单网页，黑色背景，中间显示 Hello Codex。 +``` + +Codex will determine: + + +| What it will understand | Example | +| --- | --- | +| Task Type | New Web Page | +| Modification scope | Current project file | +| May require files | index.html, style.css | +| Whether you need to run the command | Simple HTML Not necessarily required | +| Is there any risk | Low risk | + + +If you enter: + +```text +请检查为什么 npm run build 失败。 +``` + +Codex will determine: + + +| What it will understand | Example | +| --- | --- | +| Task type | Troubleshoot build failure | +| You may want to run the command | npm run build | +| May need to read files | package.json, error related files | +| Do you need to modify the code? | May be required | +| Whether your approval is required | Depends on permission settings | + + +> Tips for beginners: + +The clearer the task, the more stable the Codex. + +Recommended writing method: + +```text +请帮我完成【具体任务】。 + +要求： +1. +2. +3. + +限制： +1. 不要修改无关文件 +2. 不要删除已有功能 +3. 完成后告诉我改了哪些文件 +``` + +--- + +###### How Codex proposes a plan + +Before starting a complex task, Codex usually analyzes the problem and then proposes a plan. + +You can also actively ask it to plan first: + +```text +请先给我计划，不要直接修改文件。 +``` + +Or use: + +```text +/plan +``` + +Plans typically include: + + +| Content | Function | +| --- | --- | +| Which files it is going to check | Prevent spam items | +| How to modify it | Let you know the direction first | +| What commands it might run | Know the risks ahead of time | +| Where it is expected to affect | To help you decide whether to accept it | + + +For example: + +```text +计划： +1. 先查看 package.json，确认启动命令 +2. 运行 npm run build 复现报错 +3. 根据报错定位相关文件 +4. 最小范围修复问题 +5. 再次运行 build 验证 +``` + +> Xiaobai’s suggestion: + +```text +简单任务可以直接让它做。 +复杂任务先让它 /plan。 +``` + +Especially for these tasks, it is recommended to plan first: + +```text +修复复杂 bug +多文件修改 +项目重构 +新增功能 +构建失败 +涉及依赖升级 +``` + +--- + +###### How to modify files in Codex + +When Codex confirms that the file needs to be modified, it will edit it in the current project. + +It may: + + +| Operations | Examples | +| --- | --- | +| New file | New index.html | +| Modify file | Modify style.css | +| Delete code | Delete useless code | +| Rename file | Adjust file name | +| Split files | Split the code into multiple modules | + + +Newbies should note: + +The Codex may be changed to the right or more. + +So you have to develop a habit: + +```text +它改完之后，不要直接相信。 +一定要看 diff。 +``` + +You can add restrictions in advance: + +```text +请只修改 index.html 和 style.css，不要修改其他文件。 +``` + +Or: + +```text +请用最小改动修复问题，不要重构整个项目。 +``` + +This can reduce the problem of excessive scope of Codex changes. + +--- + +###### Codex How to run commands + +Codex can not only modify files, but also run terminal commands. + +Common commands include: + + +| Command | Function | +| --- | --- | +| npm install | Install dependencies | +| npm run dev | Start development project | +| npm run build | Check whether the project can be built | +| npm test | Run test | +| git status | View Git status | +| git diff | View code changes | + + +For example, if you let it fail to build, it may run: + +```text +npm run build +``` + +Then continue to modify according to the error report. + +Xiaobai, don’t be afraid of orders, but you must understand them before giving permission. + +If you don’t understand, you can ask it to explain first: + +```text +请先解释你准备运行的命令，每条命令是干什么的，不要直接执行。 +``` + +Be cautious when seeing these commands: + +```text +rm -rf +sudo +curl xxx | sh +git reset --hard +git clean -fd +``` + +These commands may delete files, modify the system, reset code, or execute remote scripts. + +--- + +###### How does Codex wait for user approval? + +Codex CLI has permission control, and not all operations can be performed directly. + +If Codex wants to do a sensitive operation, it may stop and ask you. + +For example: + + +| Actions | Why approval may be required | +| --- | --- | +| Internet installation dependencies | May download external code | +| Accessing files outside the project | Beyond the current workspace | +| Modify external files | May affect other projects | +| Runs high-risk commands | May delete or overwrite content | +| Use higher permissions | Greater risk | + + +In simple terms: + +```text +批准 = 你允许 Codex 继续做这一步。 +拒绝 = 这一步不要做。 +``` + +If you don't understand what it is trying to do, don't just click Allow. + +You can ask first: + +```text +请解释这个操作的作用、风险，以及有没有更安全的替代方案。 +``` + +Suggested permissions for newbies: + +```text +保持请求批准。 +不要随便开启完全访问权限。 +``` + +--- + +###### How does Codex display diff? + +Diff is the code comparison before and after the Codex modification. + +You can enter in the Codex CLI: + +```text +/diff +``` + +It will show the current changes. + +In simple terms: + +```text +绿色 = 新增内容 +红色 = 删除内容 +``` + +diff can help you confirm: + + +| Checkpoint | What do you want to see | +| --- | --- | +| Have the correct files been changed | Have irrelevant files been changed | +| Whether to delete important code | Pay attention to the red deleted part | +| Whether to add complex dependencies | Whether to install unnecessary packages | +| Are the changes too big | Don’t turn small tasks into big refactorings | +| Does it meet the requirements | Does it achieve the effect you requested | + + +Recommended process: + +```text +Codex 完成修改 +→ 输入 /diff +→ 查看改动 +→ 不满意就让它继续改或撤回 +→ 满意后再 git commit +``` + +Don’t just look at the Codex summary. + +What really matters is: + +```text +它实际改了什么。 +``` + +--- + +###### How does Codex handle failures? + +It is normal for Codex to fail to execute tasks. + +Common failures include: + + +| Failure type | Example | +| --- | --- | +| Command failed | npm run build error | +| Missing dependencies | A package is not installed | +| Code error | Blank page, function error | +| Insufficient permissions | No network or file access | +| Wrong understanding of requirements | What you changed is not what you want | +| The scope of modification is too large | I accidentally changed irrelevant files | + + +Codex will normally continue analysis based on failure results. + +For example: + +```text +运行 npm run build 失败 +→ 读取报错信息 +→ 定位相关文件 +→ 修改代码 +→ 再次运行 build +``` + +But you should pay attention to: + +Don't let it try endlessly. + +If it fails continuously, you can pause it and let it reanalyze: + +```text +先停一下。请总结目前失败原因，不要继续修改文件。 +``` + +Or: + +```text +请列出你已经尝试过的方法、失败原因，以及下一步最小改动方案。 +``` + +If it is messed up, you can say: + +```text +请撤回刚才的修改，恢复到修改前状态。 +``` + +Or use Git to view it yourself: + +```text +git status +git diff +``` + +Then decide whether to keep it. + +--- + +###### Recommended workflow for novices + + +| Steps | Actions | Purpose | +| --- | --- | --- | +| 1 | cd project directory | Enter the correct project | +| 2 | Codex | Start Codex CLI | +| 3 | Enter the task | Tell Codex what to do | +| 4 | Complex tasks first /plan | Look at the plan first | +| 5 | Wait for Codex to read the item | Let it understand the context | +| 6 | Approval of sensitive operations | Understand before allowing | +| 7 | Wait for it to modify the file | Execute the task | +| 8 | Run command check | Verify results | +| 9 | /diff | View changes | +| 10 | If not satisfied, continue to modify | Iterative optimization | +| 11 | When satisfied, git commit | Save version | + + +--- + +###### One sentence summary + +The working method of Codex CLI is not "ask and answer", but a complete programming process: + +```text +读项目 +→ 想方案 +→ 改文件 +→ 跑命令 +→ 等批准 +→ 看 diff +→ 修失败 +→ 交结果 +``` + +#### CLI FAQ + +Codex CLI common problems, most of them are not broken by Codex itself, but in these places: + +##### The most frequently asked questions for beginners + + +| Problems | Common Causes | Solutions | +| --- | --- | --- | +| Enter `codex` but no response | Codex is not installed, or the environment variable is not added to the command | Run `codex --version` first to check | +| Prompt command not found | The terminal cannot find the Codex command | Reinstall the Codex CLI or restart the terminal | +| Don’t know where to run Codex | Did not enter the project directory | First cd the project directory, then run Codex | +| Codex read the wrong project | Started in the wrong folder | After exiting, enter the correct project directory and restart | +| Login failed | The browser is not open, the network is abnormal, the account is not logged in | Use `codex login` to log in again | +| API key login failed | Key is not set, Key is wrong, environment variables are not effective | Reset the environment variables and log in again | +| Codex has been waiting | Maybe waiting for you to approve permissions | Check if there is an approval prompt on the terminal | +| Codex cannot connect to the Internet | Sandbox or permission restrictions | Manual approval when connected to the Internet | +| Don’t know what was changed after the change | Didn’t read diff | Enter /diff in Codex | +| What to do if it is changed | Did not save with Git in advance | Use git diff to check and revert if necessary | + + +--- + +##### Installation issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| `codex --version` No output | Codex was not installed successfully | Reinstall Codex CLI | +| `codex: command not found` | The command is not added to PATH | Restart the terminal or reinstall | +| npm installation failed | Node.js / npm is not installed | Run node -v and npm -v first | +| Command not found after Windows installation | PowerShell did not refresh environment variables | Close the terminal and reopen it | +| The version is too old | Codex CLI is not updated | Run `codex update` or reinstall | + + +Troubleshooting command: + +```text +codex --version +node -v +npm -v +codex doctor +``` + +> Xiaobai’s suggestion: + +```text +安装后第一件事，不是直接用，而是先运行 codex --version。 +能看到版本号，说明基础安装正常。 +``` + +--- + +##### Login issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| Don’t know if you are logged in | Did not check login status | Run `codex login status` | +| The browser does not open automatically | The default browser is abnormal or the remote environment | Use `codex login --device-auth` | +| ChatGPT login failure | Network, account, browser cache issues | Re-run `codex login` | +| API key login failed | Environment variable not set properly | Check OPENAI_API_KEY | +| Want to change account | This machine has saved the old account | First `codex logout`, then log in again | + + +Common commands: + +```text +codex login +codex login status +codex logout +codex login --device-auth +``` + +> Newbie suggestions: + +```text +本地学习优先用 ChatGPT 账号登录。 +API key 登录更适合开发者、自动化和服务器场景。 +``` + +--- + +##### Project directory issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| Codex cannot see the project file | Did not enter the project directory | cd the project directory first | +| Codex read the wrong file | Started in the wrong directory | Exit and then re-enter the correct directory | +| Codex scanned too many things | Start on desktop, download directory or C drive | Only start in specific project folder | +| Don’t know where you are now | Don’t know the path to the terminal | Use cd for Windows, pwd for Mac | +| File not found | The file is not in the current project | Use /mention to specify the file, or enter the correct directory | + + +Recommended method: + +```text +cd D:\AI-Codex-Projects\hello-codex +codex +``` + +Not recommended: + +```text +在 C 盘根目录运行 +在桌面运行 +在下载文件夹运行 +在重要资料文件夹运行 +``` + +In one sentence: + +```text +你在哪个目录运行 codex，它就默认把哪个目录当成项目。 +``` + +--- + +##### Permissions and sandbox issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| Codex prompts that approval is required | It needs to perform sensitive operations | Understand before allowing | +| Codex cannot access the network | The sandbox limits the Internet by default | Manual approval if needed | +| Codex cannot read files outside the project | Beyond the scope of the workspace | It is not recommended to release it casually | +| Codex cannot modify some files | Insufficient permissions or in read-only mode | Check /permissions | +| Codex requests full access | The task requires greater permissions | Novices, please do not agree | + + +Recommended settings: + +```text +sandbox：workspace-write +approval：on-request +``` + +In simple terms: + +```text +workspace-write = 允许在当前项目里工作 +on-request = 敏感操作先问你 +``` + +Do not use casually: + +```text +danger-full-access +--yolo +--dangerously-bypass-approvals-and-sandbox +``` + +If you see a permission request that you don’t understand, you can ask: + +```text +请解释这个操作为什么需要权限，会影响哪些文件，有没有更安全的替代方案。 +``` + +--- + +##### Command running issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| npm run dev failed | The dependency is not installed or the script does not exist | Look at package.json first | +| npm install failed | Network, source, permissions, or dependency conflicts | Let Codex analyze the error first | +| npm run build failed | The project code itself reported an error | Let Codex reproduce and minimally repair | +| The command is stuck | The development server keeps running | Use /ps to view background tasks | +| Want to stop the command | The command keeps occupying the terminal | Use /stop to stop the background task | + + +Common command meanings: + + +| Command | Meaning | +| --- | --- | +| npm install | Install project dependencies | +| npm run dev | Start the development environment | +| npm run build | Check whether the project can be officially built | +| npm test | Run test | +| git status | View project change status | +| git diff | View specific changes | + + +When you don’t understand the command, let Codex explain it first: + +```text +请先解释你准备运行的命令，每条命令是干什么的，不要直接执行。 +``` + +--- + +##### Diff and modification issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| Don’t know what has been changed in Codex | Didn’t read diff | Enter /diff | +| Too many changes in diff | Codex modification scope is too large | Require minimum changes | +| Changed irrelevant files | Unclear task restrictions | Let it undo irrelevant changes | +| Deleted important code | Did not check the red deleted part | Use Git to restore or let it revert | +| /diff Nothing | No file changes, or changes have been saved | Use git status to check again | + + +Recommended inspection process: + +```text +Codex 完成任务 +→ 输入 /diff +→ 看改了哪些文件 +→ 看红色删除部分 +→ 看是否改了无关文件 +→ 满意后再 git commit +``` + +The prompt word can be written like this: + +```text +请只修改当前任务相关文件。 +不要重构整个项目。 +完成后列出修改了哪些文件。 +``` + +--- + +##### Git related issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| I changed it and don’t know how to restore it | I don’t use Git to save the version | I will git init and commit in the future | +| git status shows many files | Codex or you have changed a lot of content | Use git diff to check one by one | +| Don’t know which changes to keep | Haven’t looked at the diff | Don’t commit yet | +| Want to rollback after committing | Not familiar with Git basics | Let Codex explain the rollback plan first | +| Codex changed a file that should not be changed | The scope of the task is too large | Ask it to revert irrelevant files | + + +It is recommended for novices to do the following for their first project: + +```text +git init +git add . +git commit -m "initial commit" +``` + +After each change of Codex: + +```text +git status +git diff +``` + +In simple terms: + +```text +git status = 看哪些文件变了 +git diff = 看具体变了什么 +commit = 保存一个版本 +``` + +--- + +##### Model and quota issues + + +| Problem | Cause | Solution | +| --- | --- | --- | +| A certain model cannot be seen | Different packages, regions or permissions | Use the currently available model | +| Task slows down | Strong model, high inference, large project | Reduce inference or reduce task scope | +| Credit consumption is too fast | High reasoning, multiple rounds of modifications, reading large projects | Use low/medium reasoning for small tasks | +| Prompt that the limit has been reached | The current plan quota has been exhausted | Wait for the quota to be restored or purchase additional quota | +| API key consumption fee | API login is billed based on API usage | Newbies are given priority to log in with ChatGPT | + + +Suggestions for saving quota: + +```text +小任务不要开最高推理。 +不要一次让 Codex 扫整个项目。 +不要反复让它大范围重构。 +能指定文件就指定文件。 +复杂任务先 /plan，再修改。 +``` + +Recommended configuration: + +```text +普通任务：默认模型 + 中推理 +复杂 bug：高推理 +小改动：低推理 +``` + +--- + +##### Codex stuck or wrong result + + +| Problem | Cause | Solution | +| --- | --- | --- | +| Codex stays still | Waiting for permission, command stuck, task too big | Check if there is approval or /ps | +| Codex cannot be repaired repeatedly | No root cause found | Let it summarize the reasons for failure first | +| Codex becomes more and more chaotic as it changes | No limit on modification scope | Paused, minimum changes required | +| Codex misunderstood the requirements | The task description is too vague | Rewrite the goals, requirements, and limitations clearly | +| Output too long and garbled | Conversation context too long | Use /compact | + + +You can stop it like this: + +```text +先停一下，不要继续修改文件。 +请总结目前做了什么、失败在哪里、下一步最小修改方案是什么。 +``` + +If it changes direction, you can say: + +```text +这次方向不对。请撤回刚才的无关修改，只保留和首页样式相关的改动。 +``` + +--- + +##### Windows FAQ + + +| Problem | Cause | Solution | +| --- | --- | --- | +| PowerShell does not recognize Codex | Environment variables are not refreshed | Close the terminal and reopen it | +| The path contains spaces and an error is reported | The path is not quoted | Use English path or add quotes | +| API key command is not applicable | Windows and Mac commands are different | Written in PowerShell | +| Frequent permission pop-ups | Windows security restrictions or sandbox approval | Just keep requesting approval | +| Chinese path exception | Some tools are not compatible with Chinese paths | Try to use English for project paths | + + +Recommended Windows project path: + +```text +D:\AI-Codex-Projects\hello-codex +``` + +Not recommended: + +```text +C:\Users\你的名字\桌面\新建文件夹 +``` + +Reason: + +```text +中文路径、空格、桌面目录，有时更容易出问题。 +``` + +--- + +##### macOS FAQ + + +| Problem | Cause | Solution | +| --- | --- | --- | +| Insufficient permissions | Folder permission restrictions | Change to the project folder in the user directory | +| Command not found | PATH does not take effect | Reopen Terminal | +| npm permission issues | Global installation permission issues | Prioritize the official recommended installation method | +| Browser login does not jump back to the terminal | Browser blocking or network problem | Use device auth | +| The terminal is not familiar with the path | Does not know the current directory | Use pwd and ls | + + +Recommended project path: + +```text +~/AI-Codex-Projects/hello-codex +``` + +Common inspection commands: + +```text +pwd +ls +codex --version +codex doctor +``` + +--- + +##### Run `codex doctor` troubleshooting + +If you don’t know where the problem is, you can run: + +```text +codex doctor +``` + +It is suitable for troubleshooting: + +```text +安装异常 +登录异常 +配置异常 +终端环境异常 +权限问题 +系统环境问题 +``` + +In simple terms: + +```text +codex doctor = Codex 的体检命令。 +``` + +When you encounter complex problems, you can send the doctor results to Codex and let it help you analyze: + +```text +请根据 codex doctor 的输出，帮我判断 CLI 哪里有问题。 +``` + +--- + +##### General troubleshooting process for novices + + +| Steps | Commands/Actions | Purpose | +| --- | --- | --- | +| 1 | `codex --version` | Check whether the installation is successful | +| 2 | `codex login status` | Check if you are logged in | +| 3 | pwd / cd | Confirm current project directory | +| 4 | git status | View project status | +| 5 | `codex doctor` | Check environment issues | +| 6 | /permissions | Check permission settings | +| 7 | /diff | View file changes | +| 8 | /ps | View background tasks | +| 9 | /stop | Stop stuck command | +| 10 | /compact | Compact context when conversation is too long | + + +--- + +### Codex IDE Extension + +Load Codex directly into your code editor. + +You don’t need to open the Codex App separately, nor do you need to switch to the terminal. Instead, you can use Codex directly in the sidebar of editors such as VS Code, Cursor, and Windsurf. + + +#### How to understand Codex IDE Extension + + +| Concept | In simple terms | +| --- | --- | +| IDE | Software for writing code, such as VS Code, Cursor, Windsurf | +| Codex IDE Extension | Codex installed in the editor | +| Sidebar | Where Codex appears, like a chat panel | +| Current file | The file you are opening in the editor | +| Selected code | The piece of code selected by your mouse | +| Context | Files, codes, error reports and task descriptions that can be referenced by Codex | + + +Simply put: + +```text +Codex IDE = 在写代码软件里直接叫 Codex 帮你干活 +``` + +#### Who is Codex IDE Extension suitable for? + + +| Crowd | Suitability | +| --- | --- | +| People who use VS Code | Suitable | +| People who use Cursor | Suitable | +| People using Windsurf | Suitable | +| People who want to modify while reading the code | Suitable | +| People who want Codex to only see the current file | Suitable for | +| People who don’t want to touch the editor at all | Not suitable | +| People who prefer graphical task management | More suitable for Codex App | +| People who prefer terminal | More suitable for Codex CLI | + + +#### Which editors does Codex IDE Extension support? + + +| Editor | Description | +| --- | --- | +| VS Code | The most common code editor for beginners | +| VS Code Insiders | Beta version of VS Code | +| Cursor | AI editor, based on VS Code | +| Windsurf | AI editor, also compatible with VS Code plugin system | +| JetBrains IDE | Such as IntelliJ, PyCharm, WebStorm, Rider | + + +Newbies are recommended first: + +```text +VS Code 或 Cursor +``` + +#### How to install Codex IDE Extension + + +| Steps | Actions | +| --- | --- | +| 1 | Open VS Code / Cursor / Windsurf | +| 2 | Enter the extension market Extensions | +| 3 | Search Codex | +| 4 | Install OpenAI’s Codex extension | +| 5 | Restart the editor after the installation is complete | +| 6 | Find the Codex icon in the sidebar | +| 7 | Click Codex to log in to your account | +| 8 | Open the project folder and start using | + + +If you can't find the Codex icon in Cursor, the sidebar icon may be collapsed. You can first check the left or right active bar to pin the Codex. + +--- + +#### First time login + +After the installation is complete, the Codex IDE Extension will prompt you to log in. + +There are two common login methods: + + +| Login method | Who is it suitable for | Newbie suggestions | +| --- | --- | --- | +| ChatGPT account login | Ordinary users, novices | Recommended | +| API key login | Developers, automation, special scenarios | Not recommended for use at the beginning | + + +> Newbies’ first choice: + +```text +Sign in with ChatGPT +``` + +That is, log in with your ChatGPT account. + +API key login is more suitable for developers who understand API billing and environment variables. + +--- + +#### Where to open Codex IDE Extension + +After successful installation, Codex will usually appear in the editor sidebar. + +Common locations: + + +| Editor | Possible Locations | +| --- | --- | +| VS Code | By default in the right sidebar or left active bar | +| Cursor | May be on the left/right, or may be collapsed | +| Windsurf | Usually in the extension sidebar | +| JetBrains | In the plugin panel or tool window | + + +If you can't find it, you can try: + +```text +1. 重启编辑器 +2. 打开 Extensions，确认 Codex 已安装 +3. 查看左侧活动栏是否有 Codex 图标 +4. 查看右侧边栏是否有 Codex 面板 +5. 在命令面板里搜索 Codex +``` + +--- + +#### What can Codex IDE Extension do? + + +| Function | In simple terms | Example | +| --- | --- | --- | +| Read the current file | View the code you are opening | Interpret this file | +| Read the selected code | Only see the part you selected | Explain this function | +| Modify the code | Help you directly modify the file | Change the button to blue | +| Run command | Execute command in project | npm run build | +| Fix error report | Modify according to error message | Fix build failure | +| Generate documentation | Write README or comments | Write README according to the project | +| Switch model | Change to a stronger or faster model | GPT-5.5 / mini | +| Adjust reasoning | Control depth of thinking | Low / Medium / High | +| Control permissions | Control whether files can be changed and connected to the Internet | Chat / Agent / Full Access | +| Entrust the cloud | Give big tasks to the Cloud | Run in the cloud | + + +### Codex Web + +Cloud Codex used in web pages. + +It does not require you to keep your local computer on or operate in a terminal. Instead, you can connect to the GitHub repository and let Codex read code, execute tasks, modify files, and generate reviewable results in the cloud environment. + +#### How to understand Codex Web + + +| Concept | In simple terms | +| --- | --- | +| Codex Web | Web version Codex | +| Cloud Task | Cloud task, not necessarily run on your computer | +| Repository | Code repository on GitHub | +| Branch | Code branch, like an independently modified version | +| Pull Request | Submit the code modified by Codex to you for review | +| Environment | Codex The environment required to run projects in the cloud | +| Setup Script | Installation command to be executed before starting the cloud environment | +| Maintenance Script | Optional maintenance script, such as updating dependencies or preparing data | + + +In one sentence: + +```text +Codex Web = 让 Codex 在云端帮你处理 GitHub 项目。 +``` + +--- + +#### Who is Codex Web suitable for? + + +| Crowd | Suitability | +| --- | --- | +| People with GitHub repositories | Suitable | +| People who want Codex to handle tasks in the cloud | Suitable for | +| People who want Codex to create a PR | Suitable | +| Team Project Developer | Suitable | +| People who don’t want to occupy the local computer all the time | Suitable | +| Novice with no knowledge of GitHub | Not very suitable | +| People who are just doing local HTML exercises | More suitable for Codex App | +| People who don’t know Git / GitHub | It is recommended to learn the basics first | + + +> Xiaobai’s suggestion: + +```text +刚开始做本地练习，用 Codex App。 +项目已经放到 GitHub 后，再学 Codex Web。 +``` + +--- + +#### Where is the Codex Web entrance? + +> The entrance to Codex Web is: + +```text +chatgpt.com/codex +``` + +After opening, you need: + + +| Steps | Actions | +| --- | --- | +| 1 | Log in to ChatGPT account | +| 2 | Enter the Codex page | +| 3 | Connect to GitHub account | +| 4 | Select the repository to process | +| 5 | Create a cloud task | +| 6 | Wait for Codex to run in the cloud | +| 7 | View results and diff | +| 8 | Create Pull Request after satisfaction | + + +--- + +#### What is the difference between Codex Web and local Codex + + +| Comparison | Codex Web | Codex App / CLI / IDE | +| --- | --- | --- | +| Running location | Cloud | Local computer | +| Project source | GitHub repository | Local folder or Git repository | +| Do you need the computer to be turned on all the time | Not necessarily | Usually required | +| Is it suitable for the PR process | Very suitable | Yes, but more local | +| Is it suitable for beginners to practice | General | App is more suitable | +| Whether to rely on GitHub | Usually required | Not necessarily | +| Suitable for tasks | Repository tasks, PR, team collaboration | Local development, rapid modification, debugging | + + +Simple understanding: + +```text +本地 Codex = 在你电脑上干活 +Codex Web = 在云端帮 GitHub 仓库干活 +``` + +--- + +#### The process of using Codex Web for the first time + + +| Steps | Operations | In simple terms | +| --- | --- | --- | +| 1 | Open Codex Web | Enter the web version of Codex | +| 2 | Log in to ChatGPT | Confirm your account | +| 3 | Connect to GitHub | Allow Codex to access your code repository | +| 4 | Select repository | Select an item to process | +| 5 | Select branch | Select which version to start from | +| 6 | Enter the task | Tell Codex what to do | +| 7 | Waiting to run | Codex processed in the cloud | +| 8 | View results | See which files have been changed | +| 9 | Review diff | Check for new and deleted content | +| 10 | Create PR | Submit to yourself or the team after you are satisfied review | + + +--- + +#### What does it mean to connect to GitHub? + +Connecting to GitHub means: + +Allow Codex Web to have access to your specified GitHub repository. + +It needs to read the repository code to complete the task. + +For example, if you ask Codex Web to do: + +```text +请帮我修复首页按钮点击无反应的问题。 +``` + +It needs to read your project code first, then determine where the button logic is, and then modify the relevant files. + +In simple terms: + +```text +GitHub = 放代码的云盘 +Codex Web = 进入这个代码云盘帮你改项目 +``` + +Note: + +```text +不要随便授权不信任的账号或组织。 +不要一上来让 Codex 访问所有仓库。 +能只授权某几个仓库，就只授权需要的仓库。 +``` + +--- + +#### Repository What is the repository? + +Repository is referred to as repo, which can be understood as: + +A complete code project. + +For example: + +```text +my-landing-page +ai-tools-site +xiaohongshu-cover-generator +my-react-app +``` + +These can be repositories on GitHub. + +Codex Web typically creates tasks around a repository. + +In simple terms: + +```text +仓库 = 一个放在 GitHub 上的项目文件夹 +``` + +--- + +#### What is Branch? + +Branch can be understood as: + +A standalone version of the code. + +For example: + +```text +main = 正式版本 +feature/homepage = 首页修改版本 +fix/button-bug = 修复按钮 bug 的版本 +``` + +Codex Web usually does not directly modify the official branch, but does tasks based on a certain branch, and finally generates checkable modifications. + +In simple terms: + +```text +main = 原稿 +新分支 = 复制一份出来修改 +PR = 把修改后的版本提交给你检查 +``` + +--- + +#### What is Pull Request? + +Pull Request, referred to as PR. + +Xiaobai can understand it as: + +Codex After modifying the code, instead of directly integrating the code into the formal project, a "modification application" must be submitted first. + +You can see in the PR: + +```text +改了哪些文件 +新增了哪些代码 +删除了哪些代码 +有没有测试通过 +Codex 的总结说明 +是否可以合并 +``` + +> The benefits of PR are: + +```text +先检查，再合并。 +``` + +So Codex Web is very suitable for real projects and team projects. + +--- + +#### How to create a task in Codex Web + +When creating a task, it is best to write clearly: + +```text +目标：让 Codex 做什么 +范围：只改哪些地方 +限制：哪些地方不能动 +验证：完成后怎么检查 +``` + +Example: + +```text +请修复首页按钮点击无反应的问题。 + +要求： +1. 先分析按钮点击逻辑在哪里 +2. 只修改和按钮相关的文件 +3. 不要重构整个项目 +4. 不要删除现有功能 +5. 修复后运行构建或测试命令验证 +6. 完成后说明修改了哪些文件 +``` + +It is not recommended to write: + +```text +帮我优化一下项目。 +``` + +The Codex is too vague, and it is easy to not know where to start. + +--- + +#### Codex Web How to run the project + +Codex Web will create a runtime environment in the cloud. + +It will usually: + +```text +1. 拉取 GitHub 仓库代码 +2. 切到指定分支或提交 +3. 执行 setup script 安装依赖 +4. 根据你的任务读取文件 +5. 修改代码 +6. 运行测试或构建命令 +7. 生成 diff 和总结 +``` + +If the project needs to install dependencies, the setup script must be configured. + +For example, front-end projects may require: + +```text +npm install +``` + +Or: + +```text +pnpm install +``` + +If the environment is not configured correctly, Codex may fail due to missing dependencies. + +--- + +#### Environment What is the environment? + +Environment can be understood as: + +Computer configuration for Codex Web to run projects in the cloud. + +It needs to know: + +```text +用什么语言 +怎么安装依赖 +怎么启动项目 +怎么运行测试 +需要哪些环境变量 +是否需要特殊工具 +``` + +For example, a front-end project may require: + +```text +Node.js +npm / pnpm +package.json +npm run build +``` + +A Python project may require: + +```text +Python +pip +requirements.txt +pytest +``` + +In simple terms: + +```text +Environment = Codex 在云端跑项目时需要的工具箱。 +``` + +--- + +#### What is Setup Script? + +Setup Script can be understood as: + +Codex Web is an installation command that is executed first every time when preparing a cloud environment. + +For example: + +```text +npm install +``` + +or: + +```text +pip install -r requirements.txt +``` + +> Its function is: + +```text +把项目需要的依赖先装好。 +``` + +If the setup script is written incorrectly, Codex may not be able to run the project. + +> Xiaobai’s suggestion: + +```text +先用最简单的安装命令。 +不要在 setup script 里写危险命令。 +不要把密码和 API key 写进去。 +``` + +--- + +#### Network access to Codex Web + +Codex Web's cloud environment does not mean completely free networking. + +Typically: + +```text +安装依赖阶段可能允许联网 +真正执行 agent 任务阶段可能默认限制联网 +``` + +In simple terms: + +```text +安装依赖可以联网，干活时不一定能随便联网。 +``` + +This is done for security and to avoid random access to external networks during the mission. + +If your task must be connected to the Internet, it depends on whether the workspace and environment settings allow it. + +--- + +#### What should you pay attention to about the permissions of Codex Web? + +Codex Web mainly involves these permissions: + + +| Permissions | Notes | +| --- | --- | +| GitHub repository permissions | Which repositories it can read | +| Branch permissions | Can it create branches | +| PR permissions | Can it create a Pull Request | +| Cloud permissions | Whether the workspace is allowed to use Codex Cloud | +| Environment variables | Do not disclose API key, token, password | +| External network | Whether to allow cloud tasks to network | + + +Safety advice for newbies: + +```text +只授权需要的仓库。 +不要授权全部仓库。 +不要把 .env、API key、密码、token 写进任务。 +不要让 Codex 自动合并 PR。 +先 review，再合并。 +``` + +--- + +#### What is Codex Web suitable for? + + +| Scenario | Example | +| --- | --- | +| Fix bugs in GitHub repository | Fix buttons, fix build failures, fix test failures | +| Make small functions | Add a page, add a form | +| Write documentation | README, usage instructions, deployment instructions | +| Code review | Check current PR or diff | +| Fix CI error | Fix the problem according to the build log | +| Multi-task background processing | Let Codex run in the cloud without occupying the local computer | +| Team collaboration | Let the team review through PR | + + +Especially suitable for: + +```text +GitHub 项目 +团队项目 +需要 PR 流程的项目 +不想本地一直开着电脑的任务 +``` + +--- + +#### What Codex Web is not suitable for + +Newbies are not recommended to use Codex Web at the beginning: + +```text +没有 GitHub 的本地小练习 +完全不会 Git 的项目 +真实生产环境部署 +数据库迁移 +支付系统修改 +自动合并 PR +删除大量文件 +处理敏感密钥 +``` + +It’s not that these cannot be done, but the risks are higher. + +> Xiaobai’s suggestion: + +```text +先用 Codex App 做本地练习。 +会 GitHub 后，再用 Codex Web 处理仓库任务。 +``` + +--- + +#### Are Codex Web and Codex Cloud the same thing? + +can be understood like this: + +```text +Codex Web = 你在网页上操作的界面 +Codex Cloud = 背后帮你跑任务的云端能力 +``` + +That is to say: + +```text +你在 Codex Web 上输入任务， +Codex Cloud 在云端环境里帮你执行。 +``` + +Novices don’t have to worry about these two words. + +Daily understanding is: + +```text +Codex Web = 网页入口 +Cloud task = 云端任务 +``` + +--- + +#### First Codex Web Mission Suggestion + +Novices should not choose complex projects for the first time. + +It is recommended to choose a simple GitHub repository, such as: + +```text +简单 HTML 页面 +React 小项目 +个人主页 +README 项目 +小工具页面 +``` + +The task can be written: + +```text +请帮我检查这个项目的 README 是否清楚。 + +要求： +1. 阅读当前项目结构 +2. 说明 README 缺少哪些内容 +3. 补充安装步骤、启动命令和项目结构说明 +4. 不要修改代码逻辑 +5. 完成后创建一个 PR +``` + +This task is low risk and suitable for those familiar with Codex Web processes. + +--- + +#### Frequently Asked Questions + + +| Problem | Possible Cause | Solution | +| --- | --- | --- | +| Repository not found | GitHub does not have authorization, or does not give permission to the repository | Recheck GitHub authorization | +| Codex cannot create PR | No branch or PR permissions | Check GitHub permissions | +| Task operation failed | setup script error or dependency installation failure | Check environment configuration | +| Codex does not know how to start the project | README or package.json is not clear | Supplementary project description | +| Failed to run the test | The project itself has bugs or incomplete dependencies | Let Codex analyze the cause of the failure first | +| The credit is consumed quickly | The task is large, the model is strong, and it is run repeatedly | Reduce the scope of the task and let it be planned first | +| Too many changes | The task is too vague | Clearly limit which files can only be changed | +| Unsatisfactory results | Unclear requirements or failed environment | Add comments to let Codex modify | + + +--- + +#### Safety rules for newbies + +```text +1. 不要一上来授权所有 GitHub 仓库。 +2. 不要让 Codex 自动合并 PR。 +3. 不要把 API key、密码、token 写进任务。 +4. 不要把 .env 文件提交到仓库。 +5. 复杂任务先让 Codex 给计划。 +6. PR 里一定要看 diff。 +7. 看不懂的改动不要合并。 +8. 生产项目不要直接让 Codex 自动部署。 +9. 先用简单仓库练习。 +10. 满意后再 merge。 +``` + +--- + +--- + +## Part 3: Detailed explanation of core functions + +> ### Automation + +> #### What is automation + +> **Codex Automation = Let Codex not only "listen to your instructions", but also help you regularly inspect the project, discover problems, and solve problems according to the rules. ** + +It’s like you hired an “AI duty engineer” for the project: + +> Usually it doesn’t bother you, +> It will remind you if there is a problem. +> For simple problems, try to fix them first. +> Finally let you review the decision. + + +#### How to use automation + +You can use "weekly Codex session automatic review" as an example to make Codex more and more useful. + +You can let Codex regularly check the recent session records, task results and common problems, and compile them into a reusable workflow file. + +Example prompt words can be written like this: + +```text +请检索并复盘最近一周的 Codex 会话记录与执行日志，维护一份“Codex 会话复盘与个人风格档案”。 + +要求： +1. 优先使用可用的会话历史检索能力；如果需要读取日志，只做搜索、元数据提取和相关片段抽取，不要整文件载入大型 session 文件。 +2. 不要复现原始日志、隐私内容、密钥、内部 reasoning 或长对话原文。 +3. 总结执行经验：哪些做法导致了问题，最终正确做法是什么，适合什么场景复用。 +4. 总结我的偏好：UI 设计偏好、产品理念、交互原则、内容系统偏好和工作流偏好。 +5. 整理可复用规则清单：把复盘结论改写成后续 Codex 会话可以遵循的简洁规则。 +6. 更新文档时去重、合并相近规则，保留日期范围或任务类型作为来源线索。 +7. 如有适合长期复用的规则，请建议是否加入项目级或用户级 AGENTS.md。 +``` + +

+ Codex平台的自动化页面 +

+ +

+ Codex桌面端界面，左侧为功能导航栏，其中“自动化”选项被选中 +

+ +> ### Plugin + +Additional "capability package" installed for Codex + +#### What is a plugin? + +Codex itself can already read code, change code, and run commands; plugins are based on this, allowing it to connect to more tools, use fixed processes, or obtain certain special capabilities. + +For example: + + +| Plugin type | What can Codex do | +| --- | --- | +| Chrome plugin | Open web pages, check pages, and cooperate with browser debugging | +| Gmail plugin | Summarize emails, draft replies | +| Google Drive plugin | Read documents, tables, slides | +| Slack plugin | Summarize channel messages and draft team responses | +| Security plugin | Check code security issues | +| Computer Use plugin | Operate applications on the computer | + + +#### The relationship between plugin, Skill and MCP (look at this table first) + +Plugins, Skills, and MCP are the three most confusing concepts in this article. They are not substitutes for each other, but each has its own layer. Please remember the following general list first, and the comparison will not be repeated in subsequent sections. + +| Comparison | Plugin | Skill | MCP | +| --- | --- | --- | --- | +| One sentence | Capability installation package | A set of fixed working methods | Interface to connect external tools | +| What problem to solve | Installation, packaging, distribution capabilities | "How to do" similar tasks | "What tools or data to connect to" | +| Scope | Largest, can package Skill, MCP, etc. | Smaller, process for a single type of task | Connection to a single external tool or data source | +| Analogy | Toolbox | Instructions in the toolbox | Socket for powering the toolbox | +| Who will use it | Ordinary users can also install it with one click | Ordinary users can also use it | More for developers and team configuration | +| Examples | GitHub plugin, Figma plugin | README Skill, Code Review Skill | Database MCP, Documentation MCP | + +One sentence to remember: **Plugins can package Skill and MCP into capability packages that are easier to install; Skill manages "how to do it", and MCP manages "what tools to connect". ** + +#### How to install plugins in Codex App + +##### Open Codex App + +

+ Codex App中插件页面 +

+ +##### Search or browse plugins + +You can also search for the corresponding plugin + +

+ Codex App中插件页面 +

+ +##### Click to open the plugin details + +

+ Codex App中GitHub插件的详情页面 +

+ +##### Click Add to Codex or Add button + +

+ 在Codex App中插件详情页面的界面 +

+ +##### After the installation is completed, open a new thread for use + +

+ Codex App中“hello - Codex”项目页面 +

+ +#### How to install plugins in Codex CLI + +After entering the project directory, start Codex first: + +```text +codex +``` + +Then enter in Codex CLI: + +```text +/plugins +``` + +After opening the plugin list, you can: + + +| Operation | Description | +| --- | --- | +| Search plugins | Find the plugins you need | +| View details | See what the plugin can do and what permissions are required | +| Install plugin | Install plugin | +| Uninstall plugin | Uninstall plugin | +| Space | Enable or disable installed plugins | + + +#### Common plugins and capability directions + +> The plugin directory will change with the Codex version, workspace and account permissions. The following is not a fixed ranking, but a common capability direction. The actual installable content is subject to what is displayed on your current Codex plugin page. + +| Type | Contains plugins | What to do | +| --- | --- | --- | +| Browser and computer operation | Chrome, Computer Use | Web page testing, automatic clicks, software operation | +| Code and project collaboration | GitHub | Manage repository, fix bugs, create PR | +| Front-end and design | Build Web Apps, Figma | Generate web pages, convert design drafts to code | +| Office Delivery | Documents, Presentations, Spreadsheets | Documents, PPT, spreadsheet analysis | +| Video generation | HyperFrames, Remotion | Generate videos with code or HTML | + + +| Serial number | Plugin/Capability | Main function | In simple terms | +| --- | --- | --- | --- | +| 1 | Chrome | Let Codex directly operate the browser | You can open web pages, click buttons, check page effects, and test web page functions | +| 2 | GitHub | Code repository management and collaboration | Let Codex read the repository, handle issues, change code, and create PR | +| 3 | Computer Use | Let Codex operate the computer | Look at the screen, click buttons, and operate software like a human, with relatively high permissions | +| 4 | Build Web Apps | Generate front-end web applications in one sentence | Enter requirements and generate web pages, gadgets, landing pages, and demos | +| 5 | Figma | Design draft to code and prototype design | Turn Figma design draft into front-end page, suitable for UI development | +| 6 | Documents | AI helps you deliver formal documents | Generate README, project descriptions, tutorial documents, product documents | +| 7 | Presentations | AI generates high-quality PPT | Generate reports, courses, product introductions, and solution-based PPT based on content | +| 8 | Spreadsheets | AI data analysis and table processing | Help you organize Excel, analyze data, and generate table conclusions | +| 9 | HyperFrames | HTML directly generates video | Use web page/HTML structure to generate video content | +| 10 | Remotion | Use code to generate high-quality videos | Use React/code to generate more professional videos | + + +### Skill + +A set of "fixed working methods" prepared for Codex. + +Codex itself can read code, change code, and run commands. + +But if you often ask it to do the same type of tasks, such as writing README, doing code review, generating web pages, and organizing documents, you can make this process into a Skill. + +#### What is Skill + + +| Concept | In simple terms | +| --- | --- | +| Skill | A set of fixed working methods | +| Prompt | Prompt word for this mission | +| Workflow | Work process | +| Template | Fixed template | +| Instruction | Long-term rules for Codex | +| Resource | Reference materials included with the Skill | +| Script | Optional automation script in Skill | + + +For example, if you want Codex to write a README every time, the README must contain: + +```text +项目介绍 +安装步骤 +启动命令 +文件结构 +常见问题 +``` + +Then you can make a README Skill. + +In the future, you don’t need to reinterpret the rules every time. As long as you call this Skill, the Codex will be written according to this set of procedures. + + +--- + +#### Skill or MCP? When to use which + +For the overall difference between plugins, Skills, and MCPs, see the previous summary table of "Relationships between plugins, Skills, and MCPs." Here we only solve the most common dilemma: whether to use Skill or MCP for a requirement. + +Remember one sentence: **For questions about "how to do it" use Skill, and for questions about "what tool to connect" use MCP. ** + +| Your needs | Use Skill or MCP | +| --- | --- | +| Write README, fixed document output format | Skill | +| Code Review, UI Review | Skill | +| Generate landing page and standardize bug fixing process | Skill | +| Check the latest development documents and new version API | MCP | +| Connect to database | MCP | +| Read Figma design draft | MCP | +| Read GitHub issue/PR | MCP | +| Connect to Notion, internal knowledge base, internal company tools | MCP | + +#### What is the difference between Skill and ordinary prompt words? + +Tasks that are only done once = write the prompt word directly Tasks that are often repeated = suitable for Skill + + +| Comparison dimensions | Common prompt words | Skill | +| --- | --- | --- | +| Usage | Manual input each time | Save as fixed capability | +| Stability | Easy to miss requirements | More stable | +| Suitable for scenarios | Temporary tasks | Repeating tasks | +| Reusability | Low | High | +| Content structure | A prompt word | Instructions, templates, materials, scripts | +| Who is it suitable for | Everyone | People who often do the same tasks repeatedly | + + +#### When is Skill suitable for use? + + +| Situation | Is it suitable to be a Skill | +| --- | --- | +| The same type of tasks are often repeated | Suitable | +| Write a bunch of rules every time | Suitable | +| Want to make Codex output more stable | Suitable | +| Multiple people in the team need to use the same process | Suitable | +| One-time small task | Not necessarily required | +| Temporarily change a sentence of copywriting | Not required | +| Just asking for a concept | No need | + + +> #### What does Skill usually contain? + + +| Content | Function | +| --- | --- | +| instructions | Tell Codex what to do | +| resources | put reference materials, templates, standards | +| scripts | Optional scripts to automate tasks | +| examples | Example input and example output | +| checklist | Check list to prevent missing steps | + + +#### Basic structure of Skill + +A simple Skill can be written like this: + +```text +# Skill 名称 + +## 适用场景 +这个 Skill 适合用来做什么。 + +## 工作目标 +Codex 最终要交付什么结果。 + +## 工作流程 +1. 先分析输入内容 +2. 再确认任务类型 +3. 然后按固定步骤处理 +4. 最后输出结果和检查清单 + +## 输出格式 +规定 Codex 最后应该怎么输出。 + +## 注意事项 +哪些事情不能做，哪些风险要提醒。 +``` + +For example README Skill: + +```text +# README 生成 Skill + +## 适用场景 +用于根据当前项目生成 README 文档。 + +## 工作目标 +输出一份结构清晰、适合新手阅读的 README。 + +## 工作流程 +1. 阅读项目结构 +2. 查看 package.json 或主要入口文件 +3. 判断项目类型 +4. 生成项目介绍 +5. 补充安装步骤和启动命令 +6. 说明文件结构 +7. 输出常见问题 + +## 输出格式 +使用 Markdown 格式。 + +## 注意事项 +不要编造不存在的功能。 +不确定的地方要明确标注。 +``` + +#### How to add Skill in Codex App + +Adding Skill in Codex App can be divided into two situations: + +```text +1. 使用已有 Skill +2. 创建自己的 Skill +``` + +##### Use existing Skill + +In the skills in the plugin, you can see some skills recommended by the system. + +

+ Codex App中技能相关界面 +

+ +##### Create your own Skill + +If you want to create a Skill yourself, you can use it in the thread of Codex App: + +```text +$skill-creator +``` + +It is equivalent to a Skill creation assistant, which will help you organize a set of repetitive processes into Skills. + +Operation steps: + + +| Steps | Actions | +| --- | --- | +| 1 | Open Codex App | +| 2 | Select a project | +| 3 | Create a new thread | +| 4 | Enter `$skill-creator` | +| 5 | Tell it what Skill you want to create | +| 6 | Provide usage scenarios, rules, and sample output | +| 7 | Let Codex generate Skill files | +| 8 | Check the generated results | +| 9 | Use this Skill in a new thread later | + + +Example prompt words: + +```text +$skill-creator + +请帮我创建一个 README Skill。 + +这个 Skill 的作用： +根据当前项目自动生成适合小白阅读的 README。 + +触发场景： +当我说“生成 README”“写项目说明”“整理项目文档”时使用。 + +工作流程： +1. 先阅读项目结构 +2. 查看 package.json、README、入口文件 +3. 判断项目类型 +4. 生成项目简介 +5. 写安装步骤 +6. 写启动命令 +7. 说明主要文件夹作用 +8. 补充常见问题 +9. 不确定的地方不要编造 + +输出格式： +使用 Markdown。 + +必须包含： +- 项目简介 +- 功能特点 +- 安装步骤 +- 启动命令 +- 文件结构 +- 常见问题 +- 后续优化方向 +``` + + +##### Recommended Skill to install + + +| Skill/Project | Main function | GitHub address | +| --- | --- | --- | +| Superpowers | Add a complete set of "software development methodology" to Coding Agent: first clarify requirements, write specifications, make implementation plans, and then promote development according to TDD/task splitting. Suitable for engineering agents such as Codex, Claude Code, Cursor, Gemini CLI, etc. | https://github.com/obra/superpowers | +| skill-creator | Auxiliary Skill to create Skill. The built-in or available Skills in Codex are subject to your current environment; Skills with the same name from different sources may be implemented differently. | Based on the current Codex Skill list | +| baoyu-skills | A set of practical Skills compiled by Baoyu, focusing on content creation and daily efficiency: Xiaohongshu pictures and texts, article illustrations, comics, public account publishing, X/Weibo publishing, webpage conversion to Markdown, YouTube subtitles, AI generated pictures, etc. The description of the repository is to improve the effectiveness of AI Agents such as Claude Code and Codex, and it is recommended to install them on demand. | https://github.com/JimLiu/baoyu-skills | +| Agent Reach | Equip Agent with "networking capabilities": read web pages, YouTube, RSS, GitHub, Twitter/X, Bilibili, Reddit, Xiaohongshu, LinkedIn, etc. It also comes with diagnostics and multi-backend routing. Simply put, it allows the local Agent to search the Internet and read platform content more conveniently. | https://github.com/Panniantong/Agent-Reach | +| find-skills | "Find the Skill of Skill". When you ask "Is there a Skill with such and such function?", it will help you search, discover, and install Agent Skills; the bottom layer is used with npx skills find / add / check / update. | https://github.com/vercel-labs/skills/tree/main/skills/find-skills | + + +#### How to add Skill in Codex CLI + +There are three main ways to add Skills in Codex CLI: + +```text +1. 使用已有 Skill +2. 用 $skill-creator 创建 Skill +3. 手动创建 SKILL.md 文件 +``` + +##### 3 ways to add Skills + + +| Method | Who is suitable for | In simple terms | Recommendation level | +| --- | --- | --- | --- | +| Use existing Skills | New users | Directly call ready-made skills | Recommended | +| `$skill-creator` created | People who want to turn prompt words into Skills | Let Codex help you organize Skills | Most recommended | +| Manually create `SKILL.md` | People familiar with file structure | Write Skill files by yourself | Advanced | + + +--- + +###### Method 1: Use existing Skill + +After entering the project directory, first start the Codex CLI: + +```text +cd 项目目录 +codex +``` + +After entering the Codex CLI, you can enter: + +```text +/skills +``` + +Or enter directly: + +```text +$ +``` + +The Codex will display the currently available Skills. + +If you already know the Skill name, you can also name it directly in the task: + +```text +请使用 $readme-skill，根据当前项目生成 README。 +``` + +or: + +```text +$ui-review-skill 请检查当前首页的视觉问题，并给出修改建议。 +``` + +--- + +###### How to use existing Skills + + +| Usage | Examples | Suitable scenarios | +| --- | --- | --- | +| /skills | Open the Skill list | When you don’t know which Skills there are | +| Enter $ | Quickly select Skill | When you want to call it quickly | +| `$skill-name` | `$readme-skill` | When the Skill name is known | +| Natural language description | Please use README Skill to write a project description | When you are not sure of the specific name | + + +--- + +###### Method 2: Create Skill with `$skill-creator` + +If you want to save a set of repeated processes as a Skill, you can use: + +```text +$skill-creator +``` + +It is equivalent to a Skill creation assistant and will ask you: + + +| Question | Purpose | +| --- | --- | +| What does this Skill do | Clarify the purpose | +| When to trigger | Write down applicable scenarios | +| Whether to include scripts | Determine whether it is only a command-type Skill | +| What is the output format | Ensure stable results | +| What are the restrictions | Avoid random modification, random compilation, and random execution | + + +--- + +###### `$skill-creator` Usage process + + +| Steps | Actions | Purpose | +| --- | --- | --- | +| 1 | Enter the project directory | Make sure the Skill is generated in the correct project | +| 2 | Run `codex` | Open Codex CLI | +| 3 | Enter `$skill-creator` | Start Skill Creation Assistant | +| 4 | Describe the Skill purpose | Tell it what to do | +| 5 | Supplementary trigger scenarios | Tell it when to use | +| 6 | Supplementary workflow | Fixed Codex execution steps | +| 7 | Supplementary output format | Ensure stable results | +| 8 | Check the generated results | Confirm whether `SKILL.md` is reasonable | +| 9 | Reopen or continue to use | Test whether the Skill is effective | + + +--- + +###### `$skill-creator` Example prompt word + +```text +$skill-creator + +请帮我创建一个 README Skill。 + +这个 Skill 的作用： +根据当前项目自动生成一份适合小白阅读的 README。 + +触发场景： +当我说“生成 README”“写项目说明”“整理项目文档”“写安装教程”时使用。 + +工作流程： +1. 先阅读项目结构 +2. 查看 package.json、README、入口文件 +3. 判断项目类型 +4. 生成项目简介 +5. 写安装步骤 +6. 写启动命令 +7. 说明主要文件夹作用 +8. 补充常见问题 +9. 不确定的地方不要编造 + +输出格式： +使用 Markdown。 + +必须包含： +- 项目简介 +- 功能特点 +- 安装步骤 +- 启动命令 +- 文件结构 +- 常见问题 +- 后续优化方向 + +注意事项： +不要编造不存在的功能。 +不要读取或输出 API key、密码、token、私钥。 +``` + +--- + +###### Method 3: Manually create Skill files + +Skill is essentially a folder, which must contain one of: + +```text +SKILL.md +``` + +The simplest structure is: + +```text +.agents +└── skills + └── readme-skill + └── SKILL.md +``` + +You can also put scripts, reference materials and resource files: + +```text +.agents +└── skills + └── readme-skill + ├── SKILL.md + ├── scripts + ├── references + └── assets +``` + +--- + +###### Skill file structure description + + +| File/Folder | Is it necessary | Function | +| --- | --- | --- | +| `SKILL.md` | Required | Write the name, description and specific instructions of the Skill | +| scripts/ | Optional | Put executable scripts | +| references/ | Optional | Put reference documents, standards, instructions | +| assets/ | Optional | Put templates, pictures, resource files | + + +--- + +###### The simplest `SKILL.md` example + +```text +--- +name: readme-skill +description: 当用户需要生成 README、项目说明、安装教程、启动步骤时使用。 +--- + +你是一个 README 文档生成助手。 + +任务： +根据当前项目生成一份适合新手阅读的 README。 + +工作流程： +1. 阅读项目结构 +2. 查看 package.json、README、入口文件 +3. 判断项目类型 +4. 生成项目介绍 +5. 写安装步骤 +6. 写启动命令 +7. 说明文件结构 +8. 补充常见问题 +9. 不确定的地方不要编造 + +输出格式： +使用 Markdown。 + +必须包含： +- 项目简介 +- 功能特点 +- 安装步骤 +- 启动命令 +- 文件结构 +- 常见问题 +- 后续优化方向 +``` + +#### How to use Skill after adding it + +After adding Skill, there are two common usages: + + +| Usage | Example | +| --- | --- | +| Explicitly specify Skill | Please use `$readme-skill` to generate README | +| Let Codex automatically determine | Help me write a project README | + + +If the Skill description is written clearly, it will be easier for Codex to automatically determine when to use it. + +For example: + +```text +description: 当用户需要生成 README、项目说明、安装教程、启动步骤时使用。 +``` + +This description is very clear. + +It is not recommended to write too vaguely: + +```text +description: 帮我写东西。 +``` + +This way Codex doesn't know when to call it. + +#### Where is the skill more suitable? + + +| Placement | Suitable for the scene | In simple terms | +| --- | --- | --- | +| .agents/skills in the project | Only for the current project | Project-specific Skills | +| User-level Skill directory | Want to use it for multiple projects | Personal general Skill | +| Team/Administrator configuration | Uniform use by team members | Team sharing Skill | +| In the plugin | Want to package and distribute to others for installation | Formal capability package | + + +### MCP + +**Only advanced AI programming needs to be understood, ordinary people can skip it directly** + +Allows Codex to connect to the interface of external tools. + +Codex itself can read code, change code, and run commands. + +The role of MCP is to allow Codex to connect to more external tools, data sources or services. + +#### What is MCP + + +| Concept | In simple terms | +| --- | --- | +| MCP | Standard interface for connecting external tools | +| MCP Server | Services that provide tool capabilities | +| Tool | Specific functions that can be called by Codex | +| Config | MCP configuration file | +| STDIO Server | MCP service started by local command | +| HTTP Server | MCP service connected via URL | +| Context | Contextual information provided to Codex by external tools | + + +Daily understanding: + +```text +Codex = 一个会干活的人 +MCP = 给他接上不同工具的插座 +MCP Server = 插在插座上的工具箱 +Tool = 工具箱里的具体工具 +``` + +For example, a document MCP allows Codex to read the document. + +A database MCP that allows Codex to query the database. + +A design tool MCP that allows Codex to obtain design draft information. + + +--- + +#### What is MCP suitable for? + + +| Scenario | How to use MCP | +| --- | --- | +| Check development documentation | Connect the documentation MCP and let Codex check the new version API | +| Connect to the database | Let Codex query the database structure or test data | +| Connect design tools | Let Codex read design drafts and component information | +| Connect to project management tools | Read issues, tasks, and requirements descriptions | +| Connect to internal systems | Call the company's internal tools or data sources | +| Connect to the knowledge base | Make Codex work based on team documentation | +| Connect to automation tools | Let Codex call additional scripts or services | + + +> Xiaobai can judge this way: + +```text +普通写代码，不一定需要 MCP。 +需要 Codex 访问外部工具或外部数据时，才考虑 MCP。 +``` + +#### What is MCP Server? + +> MCP Server can be understood as: + +Provide tool capabilities to Codex. + +For example: + + +| MCP Server type | What can be provided | +| --- | --- | +| Document MCP | Query development documents, API documents | +| Database MCP | Query table structure, read test data | +| GitHub MCP | Read issue, PR, repository information | +| Figma MCP | Read design draft information | +| Notion MCP | Read knowledge base page | +| Browser MCP | Access web pages and obtain page information | +| Internal tool MCP | Connect to company's own systems | + + +In simple terms: + +```text +MCP Server = Codex 可以调用的外部工具服务。 +``` + +#### How to use MCP in Codex App + +##### Basic process of using Codex App MCP + + +| Steps | Operations | In simple terms | +| --- | --- | --- | +| 1 | Open Codex App | Enter the desktop version of Codex | +| 2 | Enter Settings | Open Settings | +| 3 | Find MCP servers | Enter the MCP tool management area | +| 4 | View recommended servers | View official or system recommended MCP | +| 5 | Add custom server | Add your own MCP server | +| 6 | Follow the prompts to complete the authorization | Some MCPs need to log in to an external account | +| 7 | Return to project thread | Call MCP in task | +| 8 | View results and permission requests | Confirm what tools were called by Codex | + + +

+ Codex App中MCP Server的设置界面 +

+ +##### What usually needs to be filled in when adding MCP + + +| Configuration items | Function | In simple terms | +| --- | --- | --- | +| Name | MCP name | Name this tool | +| Command / URL | Launch command or service address | Codex through which to connect tools | +| Type | MCP type | Local command type or remote HTTP type | +| Env | Environment variables | Put tokens, configuration items, etc. | +| Auth | Authorization method | Do you need to log in to an external account | +| Enabled tools | Which tools are enabled | Only the functions you need are enabled | + + +

+ Codex App中添加MCP时的设置界面 +

+ +##### How to use MCP after adding it + +After the addition is completed, return to the thread of Codex App and describe the task directly. + + +| Usage | Example | +| --- | --- | +| Directly describe the requirements | Please check the latest usage of Next.js App Router | +| Explicitly request the use of MCP | Please query the documentation for this library using the available MCP tools | +| Specify an MCP | Please use context7 to query the latest documentation of Next.js | +| Check available tools first | What MCP tools are currently available? | + + +Example prompt words: + +```text +请使用可用的 MCP 文档工具， +查询 Next.js App Router 的最新用法， +然后告诉我当前项目应该怎么修改。 +``` + +Or: + +```text +请用 Figma MCP 读取这个设计稿， +分析页面结构，并给我生成前端实现计划。 +``` + +#### How to use MCP in Codex CLI + +Using MCP in Codex CLI can be understood as: + +Connect external tools to the terminal version of Codex. + +For example: + +```text +文档 MCP：让 Codex 查询开发文档 +GitHub MCP：让 Codex 读取 issue、PR、仓库信息 +Figma MCP：让 Codex 读取设计稿 +数据库 MCP：让 Codex 查询数据库结构 +``` + +> Xiaobai can understand it this way: + +```text +Codex CLI = 终端里的 AI 编程助手 +MCP = 给 Codex CLI 接外部工具的接口 +``` + +--- + +##### Basic process of using MCP with CLI + + +| Steps | Operations | In simple terms | +| --- | --- | --- | +| 1 | Open Terminal | PowerShell / Terminal | +| 2 | Enter the project directory | Let Codex know the current project | +| 3 | Add MCP server | Connect external tools to Codex | +| 4 | Check whether the MCP is added successfully | Confirm that the tool is available | +| 5 | Start Codex CLI | Enter the Codex dialog interface | +| 6 | Use /mcp to view tools | See which MCPs are currently available | +| 7 | Call MCP in a task | Let Codex use external tools | +| 8 | View results and permission prompts | Confirm whether it is safe | + + +--- + +##### Commonly used MCP terminal commands + + +| Command | Function | In simple terms | +| --- | --- | --- | +| `codex mcp --help` | View MCP command help | Read first if you don’t know how to use it | +| `codex mcp list` | View the configured MCP server | See which external tools are connected now | +| `codex mcp add` | Add MCP server | Add an external tool to Codex | +| `codex mcp remove` | Delete MCP server | Remove if no longer needed | +| `codex mcp get` | View details of an MCP server | See specific configuration | +| `codex mcp login` | Log in to an MCP that requires authorization | Authorize some remote MCPs | +| `codex mcp logout` | Exit an MCP authorization | Cancel the connection status | +| /mcp | View the MCP in the Codex session | See which tools can be called in the current session | + + +--- + +##### Add the basic format of MCP + +The basic command to add an MCP is usually: + +```text +codex mcp add 名称 -- 启动命令 +``` + +In simple terms: + +```text +名称 = 你给这个 MCP 起的名字 +启动命令 = 这个 MCP 怎么启动 +``` + +Example: + +```text +codex mcp add context7 -- npx -y @upstash/context7-mcp +``` + +This command can be understood as: + +```text +给 Codex 添加一个叫 context7 的 MCP。 +它通过 npx 启动 @upstash/context7-mcp 这个工具。 +``` + +--- + +> ##### View the added MCP + +You can run it after adding: + +```text +codex mcp list +``` + +Function: + +```text +查看当前 Codex CLI 已经配置了哪些 MCP server。 +``` + +If you can see the name you just added, it means that the configuration has been written. + +--- + +##### View MCP after entering Codex + +First enter the project directory: + +```text +cd 项目目录 +``` + +Then start Codex: + +```text +codex +``` + +After entering the Codex CLI, enter: + +```text +/mcp +``` + +Function: + +```text +查看当前会话里可用的 MCP 工具。 +``` + +If the MCP is not displayed, it may be: + + +| Problem | Possible Causes | +| --- | --- | +| Failed to add successfully | `codex mcp add` command failed | +| MCP startup failed | Dependencies not installed or command error | +| Wrong name | Wrong server name when calling | +| Authorization required | Not logged in to external service yet | +| Configuration is not refreshed | Need to restart Codex CLI | + + +--- + +##### Call MCP in task + +After configuring MCP, it is not necessary to memorize complex commands. + +You can say directly in the Codex CLI: + +```text +请使用可用的 MCP 工具，查询 Next.js App Router 的最新文档。 +``` + +You can also specify an MCP: + +```text +请用 context7 查询 Next.js App Router 的最新用法， +然后告诉我当前项目应该怎么修改。 +``` + +If it is a Figma-like MCP, you can say this: + +```text +请用 Figma MCP 读取这个设计稿， +分析页面结构，并给我生成前端实现计划。 +``` + +If it is a GitHub-like MCP, you can say this: + +```text +请用 GitHub MCP 查看这个仓库最近的 open issue， +帮我整理出优先级最高的 3 个问题。 +``` + +--- + +##### Where is the MCP configuration file? + +Codex's MCP configuration will be written into the configuration file. + +Common locations are: + +```text +~/.codex/config.toml +``` + +In simple terms: + +```text +config.toml = Codex 的配置文件 +``` + +There may be configuration similar to this: + +```text +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp"] +``` + +This means: + +```text +有一个 MCP server 叫 context7。 +启动命令是 npx -y @upstash/context7-mcp。 +``` + +If you are not familiar with the configuration file, do not change it manually in the early stage. + +Priority: + +```text +codex mcp add +codex mcp list +codex mcp remove +``` + +--- + +##### Add remote MCP + +Some MCPs are not started by local commands, but connected through a URL. + +This type is generally called remote MCP / HTTP MCP. + +May require: + + +| Configuration items | In simple terms | +| --- | --- | +| URL | Remote MCP service address | +| Auth | Do you need to log in | +| Token | Access Credentials | +| OAuth | Browser authorization login | + + +If you need to log in, you can use: + +```text +codex mcp login MCP名称 +``` + +No need: + +```text +codex mcp logout MCP名称 +``` + +> Newbie suggestions: + +```text +先用不需要复杂授权的文档类 MCP。 +后面再尝试需要登录的远程 MCP。 +``` + +--- + +##### Delete unused MCP + +If an MCP is no longer used, it can be deleted: + +```text +codex mcp remove 名称 +``` + +For example: + +```text +codex mcp remove context7 +``` + +Delete and check again: + +```text +codex mcp list +``` + +Make sure it is no longer in the list. + +### Code management (Git and GitHub workflow) + +When using Codex to do real projects, you must know a little bit about Git and GitHub. + +> Newbies can first understand it like this: + +```text +Git = 本地代码版本管理工具 +GitHub = 把代码放到网上协作的平台 +Codex = 帮你读代码、改代码、跑命令的 AI 编程助手 +``` + +In one sentence: + +```text +Git 负责记录代码变化。 +GitHub 负责远程保存和协作。 +Codex 负责帮你完成具体编程任务。 +``` + +#### What is the difference between Git and GitHub + + +| Comparison | Git | GitHub | +| --- | --- | --- | +| In simple terms | Local version management tool | Code cloud disk + collaboration platform | +| Main functions | Record what has been changed every time the code is changed | Remotely save code and team collaboration | +| Location | Your computer | Browser / Cloud | +| Core capabilities | commit, branch, diff, merge | repository, issue, pull request | +| Is it necessary to connect to the Internet? | No need | Required | +| Relationship with Codex | After changing the code in Codex, use Git to check and save | Codex Web/Cloud often cooperates with GitHub | + + +##### Git concepts that beginners must understand first + + +| Concept | In simple terms | Function | +| --- | --- | --- | +| Repository | A code repository | Store the entire project | +| Commit | A code archive | Record what was changed this time | +| Branch | Branch | Change the code without affecting the main line | +| Diff | Change comparison | See what is added, deleted, and modified | +| Stage | Temporary storage area | What changes are going to be saved into commit | +| Merge | Merge | Merge changes from one branch to another branch | +| Conflict | Conflict | The same code has been changed on both sides and needs to be selected manually | +| Push | Push | Upload local code to GitHub | +| Pull | Pull | Sync new code on GitHub to local | +| Clone | Clone | Download a project from GitHub to local | + + +--- + +##### GitHub concepts that beginners must understand first + + +| Concept | In simple terms | Function | +| --- | --- | --- | +| Repository | Project repository on GitHub | Store code | +| Issue | Problem/Requirement Record | Record bugs, requirements, tasks | +| Pull Request / PR | Code Merger Application | Apply for merging after changing the code | +| Main Branch | Main branch | Stable version of the project | +| Feature Branch | Function branch | Used to develop new features | +| Review | Code inspection | Check code before merging | +| Actions | Automated process | Automatic testing, building, deployment | +| README | Project Description | Tell others how to use the project | +| .gitignore | Ignore file list | Prevent irrelevant or sensitive files from being uploaded | + + +--- + +#### Why Git is more needed when using Codex + + +| Scenario | Why Git is needed | +| --- | --- | +| Codex has changed a lot of code | You can check the specific changes | +| Codex has been corrected | You can roll back to the previous version | +| Codex deleted content that should not be deleted | You can use Git to retrieve it | +| Let Codex be modified multiple times | Save one stage for each commit | +| Want Codex to boldly try solutions | Use branch or worktree to isolate risks | +| To put the project on GitHub | Need to push to the remote repository | +| Team collaboration | PR, review, merge required | + + +In one sentence: + +```text +没有 Git，Codex 改错了你很难回退。 +有了 Git，Codex 可以放心试，你可以随时检查和恢复。 +``` + +--- + +#### How to use Git in Codex + + +| Steps | Actions | Purpose | +| --- | --- | --- | +| 1 | Initialize Git | Let the project start to be managed by Git | +| 2 | Write .gitignore | Prevent junk files and keys from being uploaded | +| 3 | Commit once | Save the clean version | +| 4 | Create a new branch | Give Codex a safe experimental area | +| 5 | Let Codex modify the code | Complete specific tasks | +| 6 | View diff | Check what has been changed in Codex | +| 7 | Run the project / Build | Confirm that there are no errors | +| 8 | Commit when satisfied | Save this modification | +| 9 | push to GitHub | upload remote repository | +| 10 | Create PR | Check again before merging | + + +##### Enter in the Codex dialog box: Initialize the project into a Git project and exclude unnecessary files + +

+ 在Codex中使用Git的界面 +

+ + +--- + +##### Codex will help us write the .gitignore file directly + +

+ 在Codex中使用Git的界面 +

+ +#### How to use GitHub in Codex + +> ##### What to prepare before use + + +| Preparation items | Function | In simple terms | +| --- | --- | --- | +| GitHub account | Save remote code | Code cloud disk account | +| Git | Local version management | Record code changes | +| GitHub repository | Put project code | A remote project folder | +| Local project | Codex code to be modified | Project folder on computer | +| GitHub login permissions | Allow push / PR | Prove this is your repository | +| .gitignore | Prevent irrelevant files from being uploaded | Do not upload junk files and keys | + + +##### Standard upload process + + +| Steps | Actions | Purpose | +| --- | --- | --- | +| 1 | Create a new repository on GitHub | Create a remote project space | +| 2 | Copy the repository address | You will need to connect the local project later | +| 3 | Copy the address to Codex | Let Codex know which repository to upload to | +| 4 | Push to GitHub | Officially upload code | + + +###### Create a GitHub repository + +

+ GitHub创建仓库页面 +

+ +###### Copy repository address + +

+ 在GitHub上创建仓库时复制仓库地址的操作界面 +

+ +###### Copy the address to Codex + +

+ Codex平台中“做一个首页”项目的页面 +

+ +###### Push to GitHub + +#### Code rollback + +##### Modify code + +Let AI modify the code first + +

+ Codex平台中“做一个首页”项目的界面 +

+ +##### Submit to Git and save the current version + +

+ Codex平台中使用Git进行代码管理的操作界面 +

+ +##### Continue to modify the code + +

+ 在Codex中使用Git的代码回滚操作界面 +

+ +##### Open the IDE to view the code and roll back the code + +First open the IDE to view the code + +

+ 在Codex中使用Git的界面 +

+ +##### Copy version number + +

+ 在VS Code中使用Codex进行代码回滚的操作界面 +

+ +##### Copy to Codex and let it roll back the code to the specified version + +

+ 在Codex中使用Git进行代码回滚的操作界面 +

+ +#### Git Worktree + +Create an additional independent working copy for the same Git project. + +It is equivalent to a draft. It will be merged back into the official project after the effect is satisfactory. + +##### Why Worktree is needed + +Although ordinary Git branches can be switched, only one branch can be operated in one folder at a time. + +The benefits of Worktree are: + + +| Scenario | The role of Worktree | +| --- | --- | +| I want Codex to boldly change the code | Open a separate copy for it | +| Do not want to affect the current project | The main project remains unchanged | +| Want to do multiple tasks at the same time | One worktree for each task | +| Want to compare multiple plans | Plans A / B / C are available separately | +| Changed and don’t want it | Just throw away the worktree | +| Make big changes/refactoring | Reduce the risk of polluting the main project | + + +##### Create Worktree + +

+ Codex移动版界面中“hello - Codex”项目的操作菜单 +

+ +

+ Codex平台界面，左侧为项目列表，其中“hello - codex_2”项目被红色框突出显示 +

+ +##### Use branches to perform tasks + +

+ Gitpod界面中“hello - codex_2”分支的代码编辑区域 +

+ +##### Merge back to trunk + +After the check result is satisfactory, you can merge it back to the trunk and delete this branch. + +

+ 在GitHub上使用Worktree进行代码管理的操作界面 +

+ +### Cloud operation + +Codex's cloud tasks are suitable for you to continue processing work when it is inconvenient for you to keep your local computer on all the time; if your account and client support mobile portal, you can also view or advance some tasks when you are out. + +```text +把代码任务交给 Codex，让它在云端环境里自己跑。 +``` + +Newbies can understand it this way: + + +| Mode | Running Position | In Simple Terms | +| --- | --- | --- | +| Local | Your computer’s local project | Codex directly changes the code in your computer | +| Worktree | Your computer's local copy | Codex Change code in a safe copy | +| Cloud | OpenAI cloud environment | Codex pulls the GitHub repository in the cloud and processes tasks | + + +#### What is Codex cloud operation? + +Codex runs in the cloud, essentially: + + +| Content | Description | +| --- | --- | +| Running environment | Cloud container | +| Code source | GitHub repository | +| How it works | Codex reads, modifies, runs, and verifies code in the cloud | +| Final result | Generate modification results, diff, and create PR if necessary | +| Suitable for tasks | Fix bugs, change functions, write documents, code review, handle issues | +| Not suitable for the task | Local private files, projects not uploaded to GitHub, high-risk production operations | + + +--- + +#### The difference between cloud operation and local operation + + +| Comparison | Local running Local / Worktree | Cloud running Cloud | +| --- | --- | --- | +| Code location | On your computer | GitHub repository | +| Running location | Your computer | Cloud container | +| Whether to occupy the computer | Yes | Basically not occupied | +| Do you need GitHub | Not necessarily | Usually required | +| Is it suitable for background tasks | General | Very suitable | +| Is it suitable for parallel tasks | General | Very suitable | +| Permission risks | Mainly local file permissions | Mainly repository, environment variables, network permissions | +| Is it suitable for novices | More suitable for learning first | Learn GitHub before using it | + + +#### Cloud operation steps + +##### Push the code to GitHub + +

+ 在GitHub上推送代码到仓库的操作界面 +

+ +##### Open Codex Web + +

+ Codex操作界面，在界面某处的下拉菜单中，“打开Codex web”选项被红色框线突出显示 +

+ +

+ Codex云端界面 +

+ +##### Select the repository we want to modify + +After selecting, just let Codex do the work for us. + +

+ Codex云端运行操作步骤中选择我们要修改的仓库界面 +

+ +##### Upload to GitHub repository after modification is completed + +

+ Codex云端运行操作步骤中修改完成后上传到GitHub仓库的界面 +

+ +

+ 一个GitHub仓库页面，显示了用户Vink567在“Polish landing page design #2”仓库的代码提交记录 +

+ +##### Synchronize the latest code in the GitHub repository before making local modifications + +If the cloud task has pushed the modification back to GitHub, the latest code must be synchronized before continuing local development to avoid conflicts caused by continued modification on the old version. Specifically, whether Codex automatically applies the changes for you, or you manually apply `git pull` / `codex apply`, depends on the current entry and task type. + +

+ Codex云端运行操作界面 +

+ +### Memory system + +Let Codex remember some long-term useful information to facilitate future work. + +#### Project-level AGENTS.md + +```text +写给 Codex 看的项目规则说明书。 +``` + +Newbies can understand it this way: + + +| Documentation | Main Reader | Role | +| --- | --- | --- | +| README.md | People | Tell people what this project is, how to install it, and how to use it | +| AGENTS.md | Codex / AI Agent | Tell the AI how it should work in this project | +| .gitignore | Git | Tell Git which files not to upload | + + +##### Where to put AGENTS.md + + +| Placement | Scope | In simple terms | +| --- | --- | --- | +| Project root directory AGENTS.md | Entire project | General rules of the current project | +| AGENTS.md in the subdirectory | Current subdirectory and related tasks | Exclusive rules for a module | +| User level `~/.codex/AGENTS.md` | All your projects | Personal general rules | +| Project-level AGENTS.md + User-level AGENTS.md | Overlay takes effect | Personal habits + current project rules | + + +##### How to write AGENTS.md + +You can directly hand it over to AI to write, and let AI summarize the core content of this project and create AGENTS.md + +###### Front-end project AGENTS.md template + +```text +# AGENTS.md + +## 项目说明 + +这是一个前端网页项目，用于构建产品页面、工具页面或个人作品展示页面。 + +## 技术栈 + +- React +- Vite +- Tailwind CSS +- JavaScript / TypeScript + +## 常用命令 + +- 安装依赖：`npm install` +- 启动项目：`npm run dev` +- 构建项目：`npm run build` + +## 项目结构 + +- `src/`：主要源代码 +- `src/components/`：通用组件 +- `src/pages/`：页面文件 +- `src/assets/`：图片、图标等静态资源 +- `public/`：公开静态文件 + +## 代码规范 + +- 优先使用 React 函数组件 +- 优先使用 Tailwind CSS 写样式 +- 不要引入 Bootstrap +- 不要大范围重构无关代码 +- 修改时保持文件结构清晰 +- 中文文案要自然、简洁、适合普通用户阅读 + +## UI 规则 + +- 页面要有清晰的信息层级 +- 按钮、卡片、标题、留白要统一 +- 移动端要基本可用 +- 不要过度渐变、阴影和 AI 模板感 +- 优先做真实产品感，而不是 Demo 感 + +## 禁止事项 + +- 不要修改 `.env`、`.env.local` +- 不要输出 API key、token、密码 +- 不要删除已有核心功能 +- 不要随意新增大型依赖 +- 不要直接改动和当前任务无关的文件 + +## 完成任务后 + +每次修改完成后，请输出： + +1. 修改了哪些文件 +2. 每个文件改了什么 +3. 为什么这样改 +4. 是否需要运行 `npm run build` +5. 提醒我检查 diff +``` + +###### What are the characteristics of a good AGENTS.md + + +| Features | Description | +| --- | --- | +| Specific | Write clearly the technology stack, commands, and directories | +| Be concise | Don’t write long nonsense | +| Executable | Codex shows how to do it | +| Restricted | Specify which files cannot be touched | +| Verified | Write clearly what command to run to check | +| Have completion standards | Let Codex know what to deliver | +| Maintainable | Timely updated after project changes | + + +#### Global level AGENTS.md + +##### Open Codex settings and find Personalization + +

+ Codex的个性化设置界面 +

+ +##### Enter the command. The command here will affect subsequent Codex sessions as your personal general preference. + +When using AI programming, you are most afraid of AI deleting things randomly. You can use the following command + +Batch deletion of files or directories is prohibited. + +Do not use: + +- `del /s` +- `rd /s` +- `rmdir /s` +- `Remove-Item -Recurse` +- `rm -rf` + +When you need to delete a file, you can only delete a file with a clear path at a time. + +Correct example: + +```powershell +Remove-Item "C:\path\to\file.txt" +``` + +If you need to delete files in batches, you should stop the operation and request the user to delete them manually. + +#### The best way to use Codex memory + +

+ Codex记忆的最佳使用方法封面图 +

+ +The biggest problem that many people have with Codex is that they don’t know how to ask questions. + +

+ 很多人用Codex不是不会提问 +

+ +Instead, it starts from scratch every time: + +"How to run tests on my project" +"What output style do I like" +"What are the pitfalls of this repository?" +> "Which step did this process last?" +> "Where is this information?" + +This is actually using the "memory system" as a chat record. + +A better way is to put different types of information into different context layers and let Codex read the appropriate information at the appropriate time. + +Let’s look at a general table first: + +

+ Codex记忆系统应该放在哪里的总结图 +

+ +| What do you want Codex to remember | Recommended place | Not recommended place | Reason | +| --- | --- | --- | --- | +| Temporary requirements for the current task | Current prompt / current session | AGENTS.md | Use only once, do not pollute long-term rules | +| Personal preferences, common habits | Memories / Global AGENTS.md | Re-say every time | Stable but not necessarily entered into the project repository | +| Repository rules, test commands, directory conventions | AGENTS.md of repo | Memories | This is a hard rule and should be followed by the project | +| Reusable workflow | Skill | AGENTS.md | Skill can hold reference files, scripts, templates | +| Regular review, follow-up, monitoring | Automations | Keep in mind | Need to wake up according to time, not static rules | +| Real-time information in Slack / GitHub / Docs | MCP / Connector | Manual copy and paste | External information will change and should be used immediately | + +##### Current session/prompt: most suitable for placing the requirements of "this mission" + +The current session is the shortest term memory, which is only used for this task and will rarely be reused. + +For example: + +

+ 当前会话适合放本次任务要求的示例图 +

+ +"This time the background of the web page is changed to blue and white" +> "Add a login button in the upper right corner of the web page" +"This solution only considers Windows" +"Don't submit a PR yet" + +This type of information is only useful for the current task and should not be precipitated into long-term rules. + +If you write temporary requirements into AGENTS.md, every time you open the project later, Codex may mistakenly think that this is a long-term rule, which will pollute the context. + +##### Memories: suitable for "stable preferences" and "common backgrounds" + +Memories are suitable for saving information that is often useful across sessions and projects. + +Simply put, Memories are: + +> Codex's soft memory of your personal work habits. + +For example: + +- You prefer Chinese answers. +- You want the explanation to be as simple as possible and not jargon-heavy. +- When working on a project, you like to read the plan first, and then modify the code. +- You commonly use Windows, PowerShell, some fixed directories or tool chains. +- You often ask for modified clarification of diffs, verified commands, and unverified items. + +Operation steps: + +

+ Codex设置里开启Memories的界面 +

+ +1. Enable Memories in Codex settings. +2. Use several real tasks to let Codex form stable preferences. +3. You can view the corresponding memory file in the following directory: + +```text +~/.codex/memories/ +``` + +

+ Codex memories目录文件示例 +

+ +Common files and directories can be roughly understood as follows: + +| Name | Function | In simple terms | +| --- | --- | --- | +| MEMORY.md | Codex is the most important long-term memory file, usually containing stable preferences, common workflows, technology stacks, project habits, etc. | Official memory book | +| memory_summary.md | Compress and summarize the memory content to allow Codex to read core information faster | Memory summary | +| raw_memories.md | More raw memory entries, may contain uncompressed records extracted from historical threads | Raw logbook | +| rollout_summaries/ | Stores summaries of certain tasks, sessions or running processes to support subsequent memory generation | Past task summary library | +| extensions/ | Memory directory for extended functions | Extension memory area | + +It is recommended to check Memories regularly: + +- Have you recorded one-time temporary requests? +- Have you recorded the private information, keys, and account information? +- Have expired or wrong preferences been recorded? +- Are there any important rules that only exist in Memories but are not synced to AGENTS.md or Skills? + +One sentence summary: + +> Memories are memories that Codex uses to record your long-term preferences and common backgrounds. + +##### AGENTS.md: Best for "project rules that must be followed" + +AGENTS.md is the first layer I recommend for beginners. + +It works much like a statement of work for the Codex. Codex will read AGENTS.md before starting work, and regard the rules in it as work constraints for the current project or current user. + +It is worth noting that AGENTS.md can be divided into global level and project level. + +The global AGENTS.md affects most of your projects and sessions in Codex and is suitable for personal long-term rules. + +The file location is usually: + +```text +~/.codex/AGENTS.md +``` + +Operation steps: + +

+ Codex个性化设置写入全局AGENTS规则 +

+ +1. Write the rules directly in the personalization area in the Codex settings. +2. Write only a few of the most important and stable rules. +3. Do not write in the temporary requirements of a certain task. + +For example: + +> "Use Markdown format for every text output." +> "When you are unsure of your needs, point out the uncertain points first and then recommend a solution." +> "Do not delete files, rename core directories, or extensively refactor." + +Project-level AGENTS.md only affects the current project and is suitable for storing repository rules, test commands, directory conventions and delivery standards. + +The file location is usually: + +```text +~/xxx项目/AGENTS.md +``` + +Operation steps: + +

+ 在项目根目录创建AGENTS文件 +

+ +1. Create AGENTS.md in the root directory of the corresponding project folder. +2. Only write the rules that this project must follow. +3. If you are not sure how to write it, you can ask Codex to read the project first and then generate the first version for you. + +For example: + +> "Use the existing technology stack of the project and do not change the framework without authorization." +> "Do not delete or rename the core directory without authorization." +> "When fixing bugs, give priority to finding the root cause, don't just do superficial compatibility." + +The simplest template: + +```text +# AGENTS.md + +## Project overview + +这是一个前端项目，主要用于构建网页、交互页面、小游戏或内容展示页。 + +## Tech stack + +- 使用项目现有技术栈，不要擅自更换框架。 +- 如果是 Vite / React / Vue / Next.js 项目，先确认 `package.json` 再判断运行方式。 +- 不要随意引入新的生产依赖。 +- 如确实需要新增依赖，先说明原因、用途和替代方案，等待确认。 + +## Project structure + +- `src/`：主要源码目录。 +- `public/`：静态资源目录。 +- `components/`：组件目录，如果项目中存在则优先复用。 +- `assets/`：图片、图标、样式资源。 +- 不要擅自删除、重命名核心目录。 +- 修改前先阅读相关文件，不要只凭文件名猜测。 + +## Working rules + +- 开始修改前，先简单说明计划。 +- 优先小步修改，不要一次性大范围重构。 +- 保持原项目代码风格、命名风格和目录结构。 +- 修 bug 时，优先找到根因，不要只做表面兼容。 +- 改 UI 时，注意中文排版、信息层级、间距、按钮状态和移动端适配。 +- 不要覆盖用户已有改动。 + +## Commands + +请根据 `package.json` 判断实际命令。常见命令如下： + +npm install +npm run dev +npm run build +npm run lint +``` + +##### Skills: suitable for "reusable workflow" + +If AGENTS.md is a project specification, Skill is more like a reusable workflow package. + +Skills can contain SKILL.md, reference files, scripts, and resources; they are suitable for recurring tasks that require assistance with steps, examples, or tools. + +For example: + +| Scene | Should it be made into Skill | +| --- | --- | +| Write the same X Article every time | Should | +| PR review must be done according to the fixed process every time | Should | +| Just want to remind Codex to use pnpm | No, put AGENTS.md | +| Tone requirements that are only valid for the current task | No, put prompt | + +The Skill used for writing is not just to remember "Write a tweet for me". + +What it should really settle is: + +- Writing style. +- Output structure. +- Markdown format. +- Picture placeholder. +- Tutorial steps. +- Recommended rules. +- Quality check. + +Operation steps: + +1. First list the tasks you do repeatedly. +2. If a task appears more than 3 times, consider making it a Skill. +3. SKILL.md only contains core rules. +4. Long templates, style cards, and checklists are placed in references/. +5. Put scripts in the parts that can be automated. + +> ##### Final summary + +If the front seems a bit convoluted, you can understand it like this: + +| Hierarchy | Metaphor | What to put | +| --- | --- | --- | +| Current session / prompt | Temporary note | One-time requirement for this mission | +| Memories | Personal habit files | Stable preferences, common backgrounds, long-term habits | +| Global AGENTS.md | Personal work rules | Hard rules that must be followed in all projects | +| Project-level AGENTS.md | Project work instructions | Technology stack, commands, directories and restricted areas of the current repository | +| Skill | Reusable process package | Frequently repeated tasks that require steps and templates | +| Automations | Regular reminders and monitoring | Regular review, follow-up, inspection, and monitoring | +| MCP / Connector | Real-time data portal | Changing external information such as Slack, GitHub, Docs, etc. | + +

+ Codex记忆系统各层级总结图 +

+ +One final sentence: + +> The memory and context of Codex can be understood as "the more temporary, more specific, and closer to the current task, the higher the priority". + +## Part 4: Standard Workflow + +### Complete link from requirement to delivery + +Many people just start using Codex and will throw one sentence at it: + +> Help me make a website. +> Help me change this function. +> Help me optimize this project. + +This is not impossible, but it is easy to cause a problem: +**AI changes very quickly, but you don’t know what it has changed, and you don’t know whether it can be delivered with confidence. ** + +Therefore, the truly stable way is not to make random changes to Codex in one go, but to advance according to a set of fixed workflows. + +You can understand it as: + +> Requirements are not directly transformed into deliverables. They must go through the steps of "understanding, planning, modification, verification, inspection, and acceptance". + +#### Standard six-step method + + +| Steps | Name | In simple terms | Purpose | +| --- | --- | --- | --- | +| 1 | Requirement dismantling | Let Codex know what the project is to be done first | Avoid making random changes without understanding the structure | +| 2 | Make a plan | List what you want to do first, and then start after confirming | Avoid changing too many steps in one step and going off track | +| 3 | Implementation in small steps | Only change a small piece at a time | Reduce the probability of errors and facilitate rollback | +| 4 | Test | After the modification, run the check and manually verify | Confirm that the code does not report obvious errors | +| 5 | Code review | Look at the diff to check whether the changes are correct and whether there are risks | Prevent AI from changing to places that should not be changed | +| 6 | Submit and review | Submit code and accumulate experience | AI is responsible for execution, people are responsible for making decisions | + + +##### Step 1: Requirements dismantling + +Before letting Codex modify the project, the first thing is not to write the code, but to break down the requirements. + +Many people are prone to overturning when using Codex, not because Codex doesn’t know how to write code, but because the requirements are not clearly stated at the beginning. + +For example, if you just say: + +> Help me optimize the homepage. + +Codex may be understood as: + +- Change UI +- Change the copy +- Change layout +- Change component structure +- Change routing +- even deleted some code that it felt was "useless" + +Therefore, before starting the formal work, the requirements should be broken down into several key issues. + +###### What is the background? + +First explain why this task is required. + + +| Questions | Examples | +| --- | --- | +| What stage is the project at now | This is an official website page that has been launched | +| What situation are you encountering now | The conversion rate on the homepage is low and users don’t know the selling points of the product | +| Why should we change now | In preparation for releasing a new version, we need to optimize the first screen expression | +| What type does this requirement belong to | UI optimization / Bug fix / New features / Refactoring | + + +###### What problem should be solved? + +The requirements should be as specific as possible. Don't just write "optimize", "beautify" or "make it better". + + +| Vague statement | Clearer statement | +| --- | --- | +| Optimize home page | Optimize home page title, subtitle and CTA button | +| The page does not look good | Adjust card spacing, font level and button style | +| There is a problem with logging in | Fix the problem that there is no jump after clicking the login button | +| Make a backend | Add a new user list page, including search, filtering and paging | + + +A good request should be able to answer: + +> Which specific problem should be solved this time? + +Example: + +```text +这次主要解决三个问题： +1. 首屏标题表达不清楚 +2. CTA 按钮不明显 +3. 移动端首屏内容太拥挤 +``` + +###### Which files may be relevant + +If you know the approximate file location, it is best to tell Codex in advance. + +This can reduce the probability of random searching and modification throughout the project. + + +| Scenario | Possibly related files | +| --- | --- | +| Change homepage | app/page.tsx, pages/index.tsx, components/Hero.tsx | +| Change style | globals.css, tailwind.config.js, related component files | +| Change login | login/page.tsx, auth.ts, middleware.ts | +| Change interface | api directory, server directory, lib directory | +| Change copy | Page components, configuration files, i18n files | + + +###### Which functions cannot be moved + +This is very important. + +Codex It is easy to change other places in order to complete the current task. + +So tell it in advance: + + +| Immovable content | Description | +| --- | --- | +| Login logic | Only change the UI, not the authentication process | +| Interface address | Do not change the API request path | +| Data structure | Do not change database fields | +| Routing structure | Do not change the existing page path | +| Existing components | Do not refactor on a large scale unless necessary | +| Dependency version | Do not upgrade or add dependencies casually | + + +The core of this step is to draw the boundary for the Codex. + +--- + + +###### What result is considered complete? + +Don’t just say “just do it”, tell Codex what completion means. + + +| Requirement Type | Completion Criteria | +| --- | --- | +| UI optimization | The page visuals are significantly improved, and the mobile terminal is not messy | +| Bug repair | The original error report disappears and related functions can be used normally | +| New features | Users can complete the operation process | +| Performance optimization | The build is normal and the page loading is not significantly slower | +| Copywriting optimization | Title, subtitle, and button copywriting are clearer | + + +Example: + +```text +完成标准： +1. 首页首屏能清楚表达产品用途 +2. CTA 按钮更明显 +3. 移动端显示正常 +4. 不影响其他页面 +5. 项目可以正常运行和构建 +``` + +###### What tests are required? + +After the modification is completed, you cannot just look at the Codex and say "completed", but you must also explain in advance how to verify it. + + +| Test type | Applicable scenarios | +| --- | --- | +| Page preview | UI modification, page layout adjustment | +| Console inspection | Front-end page, interactive functions | +| Build Test | Next.js, React, Vue Project | +| Unit testing | Projects with test files | +| Manual process testing | Login, payment, form, upload and other processes | +| Mobile terminal test | Responsive page, Xiaohongshu first picture, mobile web page | + + +--- + + +###### What are the risks? + +When dismantling requirements, Codex must be asked to determine the risks in advance. + +This way it won't try randomly while changing. + + +| Risk | Description | +| --- | --- | +| The scope of influence is too large | Small requirements are changed into major refactoring | +| Style pollution | Changed global CSS, affecting other pages | +| Dependency risk | Adding unnecessary dependencies makes the project more complicated | +| Logical risk | In order to fix one problem, change other processes | +| Data risk | Change interface, fields, database related content | +| Compatibility risk | The desktop version is normal, but the mobile version has problems | + + +###### Requirement disassembly prompt word template + +When actually using Codex, you can copy this section directly: + +```text +请先帮我做需求拆解，不要立刻修改代码。 + +需求： +【这里写你的需求】 + +请按下面结构分析： + +1. 背景是什么 +- 当前项目大概是什么 +- 为什么要做这个需求 +- 这个需求属于新功能、Bug 修复、UI 优化，还是重构 + +2. 要解决什么问题 +- 当前具体问题是什么 +- 本次要解决到什么程度 +- 哪些内容不是本次范围 + +3. 哪些文件可能相关 +- 请根据项目结构判断可能涉及哪些文件 +- 先列出来，不要直接修改 + +4. 哪些功能不能动 +- 不要改哪些逻辑 +- 不要动哪些接口 +- 不要影响哪些页面或组件 + +5. 什么结果算完成 +- 功能完成标准 +- 页面完成标准 +- 代码完成标准 + +6. 需要哪些测试 +- 需要运行什么命令 +- 需要手动检查哪些页面 +- 需要重点验证哪些流程 + +7. 有哪些风险 +- 可能影响哪些功能 +- 是否有样式污染风险 +- 是否有重构过度风险 +- 是否有新增依赖风险 + +最后，请给我一个简短的执行建议： +- 建议先做哪一步 +- 是否需要我确认后再修改 +``` + +##### Step 2: Let Codex make a plan + +After the requirements are disassembled, do not let Codex write code immediately. + +This step requires Codex to make a plan first. + +You can understand it as: + +> Let the AI explain what it is going to do first, and then decide whether to let it take action. + +Many projects have overturned, not because Codex will not change, but because it starts to change as soon as it comes up. + +By the time you find that the direction is wrong, it may have changed many files, and it will be troublesome to check and roll back. + +So the core of the second step is: + +> > Plan first, then execute. +> > Confirm first, then modify. + +###### Don’t write code yet + +This should be written at the beginning of the prompt word. + +Because the default tendency of Codex is to start solving the problem directly after seeing the demand. + +But in a real project, directly changing the code is very risky. + + +| Problems with writing code directly | Possible consequences | +| --- | --- | +| Didn't understand the project structure | Correct the error file | +| Failure to confirm the requirement boundary | Performing functions that should not be performed | +| Unable to determine the scope of impact | Inadvertent damage to old functions | +| No test method listed | I don’t know how to accept the changes | +| Too many changes at once | It is difficult to roll back after an error | + + +Example prompt words: + +```text +先不要写代码，也不要修改任何文件。 +请先根据当前需求和项目结构，制定一个修改计划。 +等我确认后，再开始执行。 +``` + +###### Turn on plan mode + +You can refer to the "Planning Mode" section in the basic use of Codex App. In actual use, you can also directly enter `/plan` in the Codex CLI or App, and let Codex output the plan first, and then decide whether to execute it. + + +##### Step 3: Implementation in small steps + +Only after the plan is confirmed can the actual code modification phase be entered. + +But there is a very important principle here: + +> Don't let Codex change everything at once. + +Many people use Codex to overturn it, just because it "achieves everything" as soon as they come up. + +As a result, it may change the page, components, styles, interfaces, and configurations at the same time. Although the project looks changed in the end, it is difficult for you to determine what went wrong. + +So the more stable way is: + +> Only change one function point at a time. +> After changing a small step, check the small step. + +###### Only change one function point at a time + +The core of small step implementation is to control the scope of modification. + +For example, if you want to optimize the homepage, don’t say it all at once: + +```text +请帮我优化整个首页。 +``` + +It is more recommended to split it into this: + + +| Steps | Modify content | +| --- | --- | +| Step 1 | Optimize only the first screen title and subtitle | +| Step 2 | Adjust only the CTA button | +| Step 3 | Optimize mobile layout only | +| Step 4 | Only add product selling point cards | +| Step 5 | Only deal with final style details | + + +This way every step is clear and problems can be easily located. + +###### Don’t let Codex easily refactor irrelevant code + +Codex sometimes feels that some code is "not elegant enough", and then helps you refactor it. + +But in real projects, it is very dangerous to refactor easily. + + +| Smooth operation of Codex | Possible problems | +| --- | --- | +| Rename component | Cause reference path error | +| Split files | Increase maintenance costs | +| Change global style | Affect other pages | +| Optimize old logic | Destroy originally available functions | +| Upgrade dependencies | Cause compatibility issues | +| Remove code it considers useless | It may actually be business logic | + + +Therefore, when implementing in small steps, the restrictions must be clear: + +```text +本次只实现当前功能点。 +不要顺手重构无关代码。 +不要修改命名、目录结构、依赖版本和全局配置。 +如果你发现代码可以优化，请先记录为建议，不要直接修改。 +``` + +This sentence is very important. + +Codex can make suggestions, but cannot expand the scope of changes without permission. + +--- + +###### Do not accept large-scale modifications without explanation + +If Codex changes many files at once and the reasons are not clearly explained, it will be suspended. + +Especially when you see these situations, be vigilant: + + +| Situation | Processing | +| --- | --- | +| The number of changed files suddenly became large | Asking for an explanation as to why each file was changed | +| Deleted a large amount of code | Requested explanation of the reason for deletion | +| Added an unknown dependency | Request explanation of necessity | +| Modified the configuration file | Request a description of the scope of impact | +| Changes to pages unrelated to requirements | Request to roll back irrelevant modifications | +| Big change in code style | Request to maintain the original project style | + + +###### If you are unsure, stop and ask first. + +The small step implementation is not to let Codex ask everything, but to stop when encountering key uncertainties. + +For example: + + +| Uncertain situation | Why stop | +| --- | --- | +| Not sure which file to change | Prevent the wrong location from being changed | +| Uncertain business rules | Prevent logic errors | +| Not sure if old code can be deleted | Function to prevent accidental deletion | +| Not sure whether to add dependencies | Prevent project complexity | +| Unsure of interface meaning | Prevent data from being affected | +| Not sure why the test failed | Prevent repairs from getting messy | + + +You can add this rule to Codex in advance: + +```text +如果你遇到以下情况，请先停下来问我，不要自行决定： + +1. 不确定该改哪个文件 +2. 不确定是否要删除旧代码 +3. 不确定是否要新增依赖 +4. 不确定业务逻辑应该怎么处理 +5. 不确定测试失败原因 +6. 发现需要超出原计划的修改 +``` + +###### Implement prompt word template in small steps + +For actual use, you can directly copy the following paragraph: + +```text +请开始小步实现。 + +当前只执行第【1】步： +【这里写本次只做的一个功能点】 + +要求： +1. 一次只改这个功能点 +2. 只修改和当前功能直接相关的文件 +3. 不要顺手重构无关代码 +4. 不要修改目录结构 +5. 不要新增不必要依赖 +6. 不要删除已有功能 +7. 不要改计划外的文件 + +修改完成后请停止，并输出： + +1. 本次修改了哪些文件 +2. 每个文件改了什么 +3. 为什么这些修改是必要的 +4. 有没有改到计划外内容 +5. 有没有潜在风险 +6. 下一步建议做什么 + +注意： +如果遇到不确定的地方，请先停下来问我，不要自行决定。 +``` + + +##### Step 4: Test + +After completing the small step modifications in Codex, you cannot proceed to the next step immediately and must be tested first. + +The biggest problem that many people have with Codex is: + +> AI said it was completed, but the project actually did not go through. +> > The page looks normal, but some functionality is broken. +> > The current function has been fixed, but the old function has been affected. + +So the core of the test is: **not to believe that Codex says "complete", but to use the results to prove that it is really completed. ** + +> The following table covers what needs to be done for a complete test. Just execute it in order from fastest to slowest: + +| Test type | Function | Common commands | Key points | +| --- | --- | --- | --- | +| Unit test | Check whether functions, components, and modules are normal | `npm test` / `pnpm test` / `yarn test` | If it fails, explain the reason first, do not change the code directly | +| Type checking | TypeScript projects catch type errors early | `npm run typecheck` / `tsc --noEmit` | Explicitly state without this command | +| lint | Check code specification issues (unused variables, import order, Hook usage, etc.) | `npm run lint` | Distinguish between this new issue and the original issue of the project | +| Build | Being able to open locally does not mean that it can be online. Building only means that it can be packaged | `npm run build` / `pnpm build` | If it fails, summarize the error report and scope of impact first | +| Manual testing | UI, form, login, payment, upload must be clicked manually | —— | Step by step verification according to user operation path | +| Browser test | Page/console/interface problems that cannot be seen on the terminal | —— | See page display, Console error, Network, mobile terminal | +| Regression testing | Not only test new functions, but also test whether old functions have been changed | —— | List old pages and components that may be affected by this modification | + +> Two reminders: Many old projects have lint or type issues themselves. Don’t let Codex refactor all historical issues; regression testing is the most easily overlooked step by novices - changing the homepage button may also affect other pages that reuse the same component. + +When testing manually, you can ask Codex to list the verification steps into an "Operation-Expected Result" table, for example: + +| Steps | Actions | Expected results | +| --- | --- | --- | +| 1 | Open the home page | The page loads normally | +| 2 | Click the CTA button | Jump to the registration page | +| 3 | Shrink to mobile phone width | The page will not be deformed | +| 4 | Open the console | No obvious red error | + +###### Test phase prompt word template + +For actual use, you can copy this section directly: + +```text +请对本次修改进行测试，不要继续新增功能。 + +请按下面顺序执行或说明： + +1. 单元测试 +- 项目是否有单元测试 +- 如果有，请运行测试命令 +- 如果失败，请说明失败原因 + +2. 类型检查 +- 项目是否有 typecheck 命令 +- 如果有，请运行 +- 如果没有，请说明 + +3. lint +- 运行 lint 检查 +- 区分本次新增问题和项目原有问题 + +4. 构建 +- 运行 build 命令 +- 如果失败，请说明报错原因和影响范围 + +5. 手动测试 +- 列出需要手动测试的页面 +- 列出用户操作步骤 +- 列出每一步预期结果 + +6. 浏览器测试 +- 检查页面显示 +- 检查控制台报错 +- 检查移动端布局 +- 检查关键按钮和交互 + +7. 回归测试 +- 检查本次修改是否影响旧功能 +- 列出可能受影响的页面、组件和流程 + +最后请输出测试总结： +- 哪些测试通过了 +- 哪些测试失败了 +- 失败原因是什么 +- 是否可以进入下一步 +- 是否需要先修复问题 +``` + +##### Step 5: Code Review + +After passing the test, it does not mean that the modification can be delivered directly. + +Code review is also required. + +Code review can be understood as: + +> It’s not just about whether the code can run, but also about whether the code changes are correct, whether it is stable, and whether there are risks. + +Codex is fast to write code, but it may also have these problems: + + +| FAQ | Instructions | +| --- | --- | +| The function can run, but the logic is wrong | It looks normal on the surface, but there is a problem with the real business process | +| The changes are too big | For a small requirement, a lot of irrelevant code has been changed | +| Accidentally deleted old logic | Deleted seemingly useless but actually useful code | +| Ignore boundary conditions | Normal input can be used, abnormal input will crash | +| Security issues | Exposed keys, incorrect permission judgment, unverified input | +| Inconsistent style | The new code is inconsistent with the original project writing method | +| Poor maintainability | Temporarily programmed, hard-coded, difficult to change later | + + +So code review is not optional, but a key step in the Codex workflow. + +--- + +###### Two rounds of review: Codex self-review + manual review + +In the first round, let Codex self-examine the modifications just now (the purpose is not to completely believe it, but to let it expose obvious problems first). It is best to let it output into a table: + +| Check items | Results | Description | +| --- | --- | --- | +| Whether to change to unplanned files | No | Only the homepage related components have been modified | +| Whether to add new dependencies | No | No modifications to package.json | +| Whether to delete the old logic | No | Keep the original button jump logic | +| Is there a risk | Yes | The distance between the buttons on the mobile terminal needs to be manually confirmed | + +> Second round of manual review. The final deliverer is you, not Codex. It is not required to understand every line, but you should focus on these parts of diff: + +| Review highlights | What to see | +| --- | --- | +| File range | Whether only the files that should be changed | +| Modify/delete content | Whether it complies with the plan and whether old functions have been deleted | +| Naming and structure | Whether it is consistent with the original project style | +| Business logic | Whether it meets the real needs (can run ≠ logical pair) | +| Test results | Whether the test was actually run | + +Involving important codes such as login, payment, permissions, database, authentication, etc., it is recommended to use a second model for cross-examination - one model is written, and the other model is specially used to find errors (it is generally not necessary to only change the copywriting and minor styles). But the suggestions of the second model cannot be accepted in full. It helps you find problems but does not make the final decision for you. + +###### Focus on four types of high-risk issues + +The following four categories are the areas where Codex is most likely to cause problems and should be reviewed most: + +| Category | FAQ | Review Points | +| --- | --- | --- | +| Boundary conditions | Normal input can be used, abnormal input will crash | Empty data, interface failure, not logged in, insufficient permissions, mobile terminal size, repeated clicks | +| Security issues | When involving user/interface/permission/payment/upload/database | Whether the key token is exposed, whether the authority judgment is missing, whether the input is verified, whether sensitive information is leaked, whether the interface is authenticated | +| Whether it was deleted by mistake | Code that seems useless but is actually useful has been deleted | Focus on the deleted content of diff; old components, comments, compatible code, fallbacks, and configuration items may still be relied on | +| Business logic | The code can run but the logic is wrong (jumping to the wrong page, wrong price calculation, override of authority) | Normal path, abnormal path, permission judgment, whether the old business rules are overwritten | + +If you see a large section deleted but the Codex does not explain it clearly, don’t accept it directly. + +###### Code review prompt word template + +For actual use, you can directly copy this paragraph: + +```text +请对本次修改做代码审查，不要继续写代码。 + +请按下面结构审查： + +1. Codex 自审 +- 本次是否只改了计划内文件 +- 是否有无关重构 +- 是否有新增依赖 +- 是否有硬编码 +- 是否有误删旧逻辑 + +2. 修改范围审查 +- 修改了哪些文件 +- 每个文件为什么要改 +- 是否存在计划外修改 +- 是否有大面积无解释修改 + +3. 边界条件审查 +- 空数据如何处理 +- 接口失败如何处理 +- 用户未登录如何处理 +- 权限不足如何处理 +- 重复点击如何处理 +- 移动端是否可能异常 + +4. 安全问题审查 +- 是否暴露密钥、token、账号密码 +- 是否影响权限判断 +- 是否缺少输入校验 +- 是否可能泄露敏感信息 +- 是否修改了接口鉴权逻辑 + +5. 删除内容审查 +- 删除了哪些代码 +- 删除原因是什么 +- 是否确认没有其他地方依赖 +- 是否可能影响旧功能 + +6. 业务逻辑审查 +- 是否符合需求 +- 正常流程是否正确 +- 异常流程是否正确 +- 是否影响旧业务规则 +- 是否有不确定的业务假设 + +7. 审查结论 +请最后给出结论： +- 可以继续 +- 需要小修 +- 需要回退部分修改 +- 需要重新制定计划 + +注意： +只审查，不要继续修改代码。 +如果发现问题，请先说明问题和建议，等我确认后再改。 +``` + +##### Step 6: Submission and Review + +After the code test passes and the review is completed, the last step is not to simply say "done". + +For a truly complete Codex workflow, two more things need to be done: + +> > First, formally submit this modification. +> Second, accumulate this experience. + +Many people use Codex only to achieve "the code can run", but there are no submission instructions, no PR description, no problem recording, and no updated documentation. + +This may not be a problem in the short term, but there will be a problem in the long term: + +> It’s like doing it for the first time every time. +> Reinterpret every time. +> Repeat the trap every time. + +So the core of the sixth step is: + +> > Delivery is not the end, review is the beginning of the next efficiency improvement. + +###### Generate commit + +When this modification has passed testing and review, you can let Codex generate a commit for you. + +Commit is not just about writing "update", but it is about explaining what has been changed this time. + +A good commit should be able to answer: + + +| Question | Description | +| --- | --- | +| What has been changed | The main content of this submission | +| Why the change | What needs or problems does it correspond to | +| Where is affected | Which modules, pages or functions are involved | +| Whether to pass the test | Whether to build, lint, test passed | + + +Common commit message format: + +```text +feat: add user profile page +fix: resolve login redirect issue +style: improve homepage responsive layout +refactor: simplify product card component +docs: update setup guide +``` + +If it is a Chinese project, it can also be written as: + +```text +feat: 新增用户资料页 +fix: 修复登录后跳转异常 +style: 优化首页移动端布局 +docs: 更新项目使用说明 +``` + +###### Write PR + +If the project uses GitHub, GitLab or team collaboration process, a PR is usually written after submission. + +The role of PR is not to "just go through the motions", but to let others know quickly: + + +| What PR should explain | Function | +| --- | --- | +| What did you do this time | Convenient for reviewers to quickly understand | +| Why do it | Explain the background of the requirement | +| What has been changed | Reduce review costs | +| How to test | Prove that it is not changed casually | +| What are the risks | Expose uncertainties in advance | +| What to focus on | Guide reviewer review focus | + + +A good PR description can be written like this: + +```text +## 本次修改 + +- 优化首页首屏标题、副标题和 CTA 按钮 +- 调整移动端首屏布局 +- 保留原有跳转逻辑，没有修改接口和路由 + +## 测试结果 + +- npm run lint 通过 +- npm run build 通过 +- 手动检查首页桌面端和移动端显示正常 +- 点击 CTA 按钮跳转正常 + +## 风险说明 + +- 本次涉及首页样式调整，需要重点确认移动端显示 +- 没有新增依赖 +- 没有修改登录、接口、数据库逻辑 +``` + +###### Record the problem + +When reviewing, the problems encountered during this process should be recorded. + +This step is very important. + +Because in the Codex workflow, the real value is not "done this time", but: + +> If you encounter similar problems next time, you can avoid taking detours. + +Problems that need to be recorded include: + + +| Question Type | Example | +| --- | --- | +| Requirement issues | The requirements description was not clear enough at the beginning | +| Planning issues | The mobile version is missing from the Codex plan | +| Modify the problem | Codex changed irrelevant components smoothly | +| Test problem | Project does not have typecheck command | +| Review issue | Found that it deleted the fallback logic by mistake | +| Communication problem | The prompt word is not clear "Do not add dependencies" | + + +The record format can be very simple: + +```text +本次问题记录： + +1. 问题：Codex 一开始想修改全局样式 + 原因：需求里没有明确限制“只改首页” + 解决：补充提示词，要求只修改首页相关文件 + +2. 问题：移动端测试遗漏 + 原因：计划阶段没有列移动端验收标准 + 解决：以后在测试清单里固定加入移动端检查 + +3. 问题：PR 描述不够清楚 + 原因：没有提前记录测试结果 + 解决：每次测试后直接生成测试总结 +``` + +###### Summary Prompt + +If the prompt word used this time is effective, it should be settled. + +The purpose of this step is simple: + +> > Useful prompt, don’t rewrite it every time. + +For example, this time you find the following sentence useful: + +```text +不要顺手重构无关代码。 +如果发现需要超出计划的修改，请先停下来问我。 +``` + +Then it should be recorded and used as a fixed rule in the future. + +can be organized into a table: + + +| Valid Prompt | Applicable scenarios | Why it is valid | +| --- | --- | --- | +| Don’t write code first, make a plan first | All complex requirements | Prevent Codex from being directly modified | +| Change only one function point at a time | Multi-step tasks | Reduce errors and rollback costs | +| Do not refactor irrelevant code | Maintain old projects | Prevent the scope of changes from expanding | +| Summary after modification | diff | after each modification | to facilitate manual review | +| If you are not sure, stop and ask first | When the business logic is unclear | Prevent AI from making its own decisions | + + +###### Update AGENTS.md + +If certain rules must be followed every time in the future, don't just write them in the chat. It is best to update them to the project level `AGENTS.md`. + +> `AGENTS.md` can be understood as: + +> Project rules statement written to Codex. + +It tells Codex: + + +| Content | Function | +| --- | --- | +| How to run the project | Let Codex know the startup, test, and build commands | +| What is the coding style | Avoid generating code that does not conform to the project style | +| Which directories cannot be moved | Prevent core files from being accidentally changed | +| What to do before modification | Fixed "plan first and then execute" | +| What are the testing requirements | What checks must be run after the modification | +| What are the submission requirements | How to write commit and PR | + + +Example content: + +```text +# AGENTS.md + +## 工作规则 + +- 修改前必须先阅读项目结构。 +- 修改前必须先制定计划，不要直接写代码。 +- 一次只实现一个功能点。 +- 不要顺手重构无关代码。 +- 不要新增不必要依赖。 +- 不确定业务逻辑时，先提问，不要自行决定。 + +## 测试要求 + +每次修改后至少检查： + +- npm run lint +- npm run build +- 相关页面手动测试 +- 浏览器控制台是否有报错 +- 移动端布局是否正常 + +## 提交要求 + +提交前需要说明： + +- 修改了哪些文件 +- 每个文件改了什么 +- 测试是否通过 +- 是否有风险或未完成事项 +``` + +###### Update project documentation + +In addition to `AGENTS.md`, if this modification affects the way the project is used, the project document must also be updated. + +For example: + + +| Modified content | Documents that need to be updated | +| --- | --- | +| New features | README, function description | +| Add environment variable | .env.example, deployment document | +| New command | README, development guide | +| Modify interface | API documentation | +| Modify deployment process | Deployment instructions | +| Modify configuration | Configuration description | +| New component | Component usage instructions | + + +The document is updated not to look good, but to avoid forgetting it in the future. + +Common documents include: + + +| File | Function | +| --- | --- | +| README.md | Project introduction, startup method, common commands | +| .env.example | Environment variable example | +| docs/ | Detailed project documentation | +| CHANGELOG.md | Version update record | +| AGENTS.md | Codex work rules | +| CONTRIBUTING.md | Team collaboration specifications | + + +###### Submission and review prompt word template + +For actual use, you can directly copy the following paragraph: + +```text +请进入提交与复盘阶段，不要继续新增功能。 + +请按下面结构输出： + +1. Commit 建议 +- 生成一个合适的 commit message +- 使用 conventional commit 格式 +- 不要夸大本次修改范围 + +2. PR 描述 +请生成 PR 内容，包括： +- 本次修改 +- 修改原因 +- 涉及文件 +- 测试结果 +- 风险说明 +- reviewer 需要重点看的地方 + +3. 问题记录 +请复盘本次过程： +- 遇到了哪些问题 +- 原因是什么 +- 如何解决 +- 下次如何避免 + +4. Prompt 总结 +请总结： +- 哪些 Prompt 有效 +- 为什么有效 +- 适合什么场景复用 +- 是否建议加入 AGENTS.md + +5. AGENTS.md 更新建议 +请输出适合加入 AGENTS.md 的长期规则： +- 修改前规则 +- 修改中规则 +- 测试规则 +- 提交规则 + +6. 项目文档更新建议 +请判断是否需要更新： +- README.md +- .env.example +- docs/ +- CHANGELOG.md +- 其他项目文档 + +最后请给出交付结论： +- 是否可以提交 +- 是否可以发 PR +- 是否还有未完成事项 +- 是否有需要人工确认的风险 +``` + +### Codex task template library + +What we talked about earlier is the standard workflow of Codex. + +This section directly places some commonly used templates for easy copying and use in the future. + +The purpose of these templates is to: + +> > There is no need to rethink Prompt every time, just copy it according to the scene, and then fill in your own needs. + +#### Read project template + +This template is suitable for use when just opening a new project. + +Especially when it is your first time to let Codex come into contact with a project, do not let it change the code right away. + +A more stable way is to let it read the project first and output a project understanding report. + +This way you can judge first: + + +| Checkpoint | Function | +| --- | --- | +| Does Codex understand the project | Prevent correcting wrong files at first | +| Is the technology stack judged correctly | Make sure it knows what framework the project uses | +| Is the startup method clear | The subsequent testing and operation will be smoother | +| Whether the core module is found correctly | Subsequent modifications will not cause confusion | +| Whether risks are exposed in advance | Avoid changing core logic by mistake | + + +##### Read project template (can be copied directly) + +```text +请先不要修改任何代码。 + +请阅读当前项目，并输出一份项目理解报告，包括： + +1. 技术栈 +- 项目使用了哪些主要技术 +- 前端/后端/数据库/构建工具分别是什么 +- 是否使用 TypeScript、Tailwind、框架或组件库 + +2. 目录结构 +- 主要目录分别负责什么 +- 页面、组件、工具函数、接口、配置文件分别在哪里 +- 哪些目录是核心目录，哪些目录不建议随便改 + +3. 启动方式 +- 项目如何安装依赖 +- 项目如何本地启动 +- 是否需要环境变量 +- 如果 README 里有说明，请优先参考 README + +4. 测试命令 +- 项目是否有 test 命令 +- 是否有 lint 命令 +- 是否有 typecheck 命令 +- 是否有 build 命令 +- 如果没有相关命令，请明确说明 + +5. 核心模块 +- 项目的核心功能模块有哪些 +- 每个模块大概负责什么 +- 如果后续要修改功能，应该优先查看哪些文件 + +6. 后续修改风险 +- 哪些文件或目录改动风险较高 +- 哪些逻辑不能随便改 +- 是否存在全局样式、全局配置、鉴权、接口、数据库等高风险区域 +- 后续修改时需要特别注意什么 + +请只输出项目理解报告，不要修改代码。 +输出完成后等待我确认。 +``` + +#### Bug fix template + +I encountered a bug: + +- [Phenomena] +- [Reproduction Steps] +- [Expected results] +- [Actual results] +- [Related files/pages] + +Please locate the cause first and do not modify it directly. + +First give: + +1. Possible reasons +2. Files to be viewed +3. Repair plan +4. Risk points +Wait for my confirmation before changing the code. + +#### Add function template + +I want to add a new function: + +- [Function Description] +- [Entrance Location] +- [Interaction process] +- [Visual requirements] +- [Data source] +- [Acceptance Criteria] + +Please read the relevant code first and give an implementation plan. + +Do not change irrelevant files. + +Please run the test and summarize the diff after implementation. + +#### Front-end page template + +Please implement a page according to the following requirements: + +- [Page Purpose] +- [Target Users] +- [Visual style] +- [Module Structure] +- [Chinese copywriting] +- [Responsive request] +- [Unwanted problem] + +Please provide a component splitting plan before starting to implement it. + +#### Code review template + +Please review the diff of the current branch relative to main. + +Key inspections: + +1. Potential bugs +2. Boundary conditions +3. Security risks +4. Type issue +5. Performance issues +6. Are there any irrelevant modifications? +7. Is the test sufficient? +Please do not modify the code directly, output the review report first. + +> #### Reconstruction template + +Please refactor the following modules: + +[Module path] + +The goal is: + +1. Improve readability +2. Reduce duplicate code +3. Keep existing behavior unchanged +4. No changes to the public API +5. No new dependencies are introduced +Please write a refactoring plan first and explain how to verify consistent behavior. + +#### Write test template + +Please add tests for the following functions: + +- [Function Description] +- [Related documents] +- [Border Case] + +Requirements: + +1. Do not change the business logic +2. Cover the normal path +3. Cover the abnormal path +4. Override boundary conditions +5. Run the test and report the results. + +#### Write document template + +Please generate documents based on the current project: + +1. Project Introduction +2. Installation method +3. Startup method +4. Environment variable description +5. Common commands +6. Directory structure +7. Development considerations +8. Frequently Asked Questions +Please do not make up non-existent commands. You must judge based on the project file. + +--- + +## Part 5: Practical Case Library + +### Practical Case 1: Create a front-end page website for selling pet snacks + +Create a front-end web page from scratch that can be published on the Internet + +#### Create a folder locally and name it Pet treats + +Select the created folder + +

+ Codex移动版界面，左侧为导航栏，有搜索、插件、项目等选项 +

+ +#### Turn on plan mode + +Generate a preliminary project plan and execute it directly after checking that there are no problems + +

+ 一个宠物零食售卖网站的项目计划界面 +

+ +#### Open the index.html file for preview + +

+ 在本地打开index.html文件进行预览的界面 +

+ +#### Create Git repository + +Create a Git repository for code management to facilitate subsequent updates and maintenance + +

+ 在本地创建的“Pet treats”文件夹中，使用Codex生成的初步项目计划 +

+ +#### Optimization details changes + +Directly use comments to make detailed modifications on the page + +

+ 一个宠物零食售卖前端页面网站中的一款商品“草本洁齿咀嚼棒” +

+ +Increase monthly sales + +

+ 在GitHub上对“制作宠物零食售卖网站”项目的操作界面 +

+ +#### New features + +Added hot-selling list + +

+ 一个宠物零食售卖前端页面网站的热销榜页面 +

+ +> #### Push updated code + +Push the updated code after checking that there are no problems + +

+ 在GitHub上对“Pet treats”仓库代码进行推送更新的操作界面 +

+ +#### Upload to GitHub repository + +##### Create a new repository + +

+ Codex平台的界面，左侧为项目列表，右侧是项目详情区域 +

+ +

+ GitHub新建仓库页面 +

+ + +--- + +##### Copy the corresponding repository link + +

+ GitHub仓库创建页面中“快速安装”部分的内容 +

+ +##### Let Codex upload the code to the GitHub repository + +

+ 在GitHub上上传代码后的信息界面 +

+ +

+ Codex平台的仓库页面 +

+ +##### Publish web pages through GitHub Pages so that others can access them + +Find pages in settings and click Save + +Wait a few minutes + +

+ GitHub Pages的相关设置界面 +

+ +Wait a few minutes and a link will appear. This link allows others to visit your web page. + +It should be noted that GitHub Pages is suitable for hosting static websites, such as HTML, CSS, JavaScript and static resources; it is not suitable for running business logic that requires back-end servers, databases or sensitive transactions. + +

+ GitHub Pages的相关设置界面 +

+ +##### Open the web page to view the completed project + +The stability of accessing GitHub Pages may vary in different regions and network environments. If it cannot be opened, you can change the network first or wait for the deployment to complete and try again. + +https://vink567.github.io/Pet-treats/ + +

+ 在浏览器中打开的“Pet treats”网页 +

+ +### Practical Case 2: Adding functions and optimizing pages to the pet snack website + +#### Create a new user login registration page + +Users need to fill in their own address information when purchasing. At this time, a personal login account is needed to save this information. + +

+ 宠物零食管理系统的登录页面 +

+ +#### Create different pet categories and classify food under pet categories + +Still use the planning mode first to see if the AI understands your needs + +

+ 宠物零食网站的页面及后台内容 +

+ +#### Use the comment function to optimize details + +

+ 宠物零食网站的页面及后台管理界面 +

+ +

+ 宠物零食管理后台的界面 +

+ +#### After selecting food and adding it to the shopping cart, you will be prompted to confirm your address when you click to purchase. + +

+ 宠物零食管理系统的界面 +

+ +#### Submit to Git and save the code + +

+ 宠物零食网站的管理后台界面 +

+ +### Practical Case 3: Management Backend for Making Pet Snacks + +#### Still use the plan mode first + +

+ 宠物零食网站的管理后台界面 +

+ +

+ 宠物零食管理后台计划的相关内容 +

+ +#### Check the effect + +

+ 宠物零食管理售卖网站的界面 +

+ +#### Submit to Git and save the code + +

+ 宠物零食管理后台的界面 +

+ +### Practical case four: Making pet snack brand investment PPT + +#### Install PPT Skill + +What I installed here is a PPT Skill that I have evaluated before. Just send the corresponding Skill address on GitHub to Codex and let it be installed. + +

+ Codex平台界面，左侧为项目列表，当前选中“Pet treats - 制作宠物零食销售网站”项目 +

+ +#### Use "/" to select the corresponding Skill + +

+ Codex平台中安装PPT Skill的界面 +

+ +> #### Check the final result + +Codex finally generated a complete investment promotion PPT. The finished product has been uploaded to the cloud. Click the link below to download and view: + +[⬇Download investment promotion PPT](https://r2notes.bozhouai.com/images/codex-orange-book/pet-treats-investment-deck.pptx) + + +

+ Codex 生成的宠物零食品牌招商 PPT 预览界面 +

+ +### Practical case 5: Making a promotional video for pet snacks + +#### Install video plugin + +The HyperFrames plugin is used here + +

+ HyperFrames by HeyGen的界面 +

+ + +--- + +#### Plan to generate video + +

+ 一个文档界面，标题为“重做《炭禾小食》BGM 版电影级生产过程宣传片” +

+ +#### Effect preview + +The finished product is a promotional video for pet snacks. The complete video has been uploaded to the cloud. Click the link below to play it directly in the browser: + +[▶ Watch the demo video online](https://r2notes.bozhouai.com/images/codex-orange-book/pet-treats-promo.mp4) + + +## Appendix + +> ### Appendix A: Third-party model access + +> This section introduces the unofficial ideas for third-party model access, taking CC Switch + DeepSeek as an example. It is not an official function of OpenAI. Model compatibility, stability, privacy and cost rules are subject to the corresponding third-party tools and model service providers. + +#### What is CC Switch + +It is not the Claude Code ontology, nor the Codex ontology, but a third-party open source desktop tool used to uniformly manage different Agent tools. + +Simply put: + +> > **In the past, you had to manually change the configuration files of Claude Code, Codex, and Gemini CLI. ** +> **Now CC Switch makes a visual panel for you, switching with one click. ** + +It has three core uses: + + +| Function | In simple terms | +| --- | --- | +| Provider switching | For example, switching from the official Claude API to a transit API, or switching to another model service | +| MCP unified management | No need to configure MCP for Claude Code, Codex, and Gemini separately | +| Skills management | Skills can be installed from GitHub or ZIP and synchronized to different AI programming tools | + + +**If you need to switch between multiple Agent tools and models, CC Switch can be used as an advanced option. ** + +#### Download CC Switch + +First enter the official website: https://ccswitch.io/zh/ + +After clicking download, you will jump to the corresponding download page. Scroll down to find the corresponding version and click to download. + +

+ CC Switch官网的下载页面 +

+ +#### Connect to the third-party model + +##### Here we take DeepSeek as an example + +###### First find the official website of DeepSeek and create an API key + +

+ 文档配图 +

+ +###### Turn on cc switch + +Click to add model + +

+ CC Switch的界面 +

+ +Copy the API key you just created here + +

+ CC Switch中添加新供应商界面 +

+ +Enable local route mapping + +

+ 接入三方模型时在CC Switch中添加模型的设置界面 +

+ +Then click Add + +

+ CC Switch添加新供应商界面 +

+ +Enter settings and turn on all routes + +

+ CC Switch设置中的路由页面 +

+ +Click to enable + +

+ CC Switch的界面，其中“DeepSeek”模型被选中，其右侧有“启用”按钮，该按钮被红色框突出显示 +

+ +If CC Switch's routing, model service, and Codex side configuration are all compatible, and then open Codex, it will be possible to use third-party models such as DeepSeek through this set of unofficial routing. + +This type of method is not an official function of OpenAI. Whether it can be used normally, model capabilities, context length, tool call compatibility, fees and privacy rules are all subject to CC Switch, the model service provider and your own configuration. For important projects, it is recommended to use the test repository to verify it first, and do not try it directly in the production project. diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..19c48bf --- /dev/null +++ b/README.en.md @@ -0,0 +1,55 @@ +# Codex Orange Book + +> An unofficial open-source Codex guide for developers, indie makers, and heavy users of AI tools. + +Authors on X/Twitter: + +- [@Vinkyu567](https://x.com/Vinkyu567) +- [@bozhou_ai](https://x.com/bozhou_ai) + +## Language + +- [中文 README](./README.md) +- [English reader](./en.html) +- [English Markdown source](./CodexOrangeBook.en.md) +- [Original Chinese PDF](./Codex橙皮书.pdf) + +## What This Is + +The Codex Orange Book is a practical guide to using Codex in real projects. It explains the major Codex entry points, setup paths, workflow patterns, and hands-on examples that move a reader from "I have heard of Codex" to "I can use Codex inside a real project." + +This is not official OpenAI documentation and does not represent product commitments. The content is based on publicly available capabilities, observed interfaces, and practical examples. For fast-changing details such as model names, account limits, pricing, and current UI, always check official OpenAI documentation and what your own account shows. + +The English edition is machine-assisted from the Chinese source and may need human review as the project evolves. + +## Reading Links + +- [Read online in English](https://vink567.github.io/codex-orange-book/en.html) +- [Full English Markdown source](./CodexOrangeBook.en.md) +- [Chinese online reader](https://vink567.github.io/codex-orange-book/) +- [Download the original Chinese PDF](https://raw.githubusercontent.com/Vink567/codex-orange-book/main/Codex%E6%A9%99%E7%9A%AE%E4%B9%A6.pdf) + +## Contents + +- Codex basics: how Codex differs from ChatGPT, Cursor, Claude Code, and similar tools. +- Setup and environment preparation: Codex App, CLI, IDE Extension, and Web / Cloud entry points. +- Core capabilities: automation, plugins, Skills, MCP, Git / GitHub workflows, cloud execution, and memory. +- Standard workflows: requirement breakdown, planning, implementation, testing, review, and delivery. +- Hands-on examples: building and improving front-end pages, creating an admin dashboard, generating slides, and preparing a promotional video. +- Appendix: third-party model connection notes and other unofficial extensions. + +## Repository Structure + +```text +. +├── Codex橙皮书.md # Original Chinese Markdown source +├── CodexOrangeBook.en.md # English Markdown edition +├── Codex橙皮书.pdf # Original Chinese PDF +├── Codex橙皮书.preview.pdf # Lightweight Chinese PDF preview +├── index.html # Chinese online reader +├── en.html # English online reader +├── book.html # Generated Chinese book HTML +├── cover.html # Chinese PDF cover +├── assets/images/ # Book images +└── tools/ # Build and validation scripts +``` diff --git a/README.md b/README.md index c839c43..1094d06 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ > 一本写给开发者、独立开发者和 AI 工具重度用户的 Codex 非官方开源指南。 +## 语言 / Language + +- [中文](./README.md) +- [English](./README.en.md) + 作者 X/Twitter： - [@Vinkyu567](https://x.com/Vinkyu567) @@ -16,7 +21,9 @@ ## 阅读入口 - [在线阅读](https://vink567.github.io/codex-orange-book/) +- [English reader](https://vink567.github.io/codex-orange-book/en.html) - [完整 Markdown 原稿](./Codex橙皮书.md) +- [English Markdown](./CodexOrangeBook.en.md) - [下载 PDF](https://raw.githubusercontent.com/Vink567/codex-orange-book/main/Codex%E6%A9%99%E7%9A%AE%E4%B9%A6.pdf) - [预览 PDF](./Codex橙皮书.preview.pdf) @@ -34,9 +41,11 @@ ```text . ├── Codex橙皮书.md # 完整 Markdown 正文 +├── CodexOrangeBook.en.md # 英文 Markdown 版本 ├── Codex橙皮书.pdf # 完整 PDF ├── Codex橙皮书.preview.pdf # 便于 GitHub 预览的 PDF ├── index.html # 在线阅读入口 +├── en.html # 英文在线阅读入口 ├── book.html # 在线阅读正文页面 ├── cover.html # 封面页面 ├── assets/images/ # 正文配图 diff --git a/en.html b/en.html new file mode 100644 index 0000000..c8b6107 --- /dev/null +++ b/en.html @@ -0,0 +1,9933 @@ + + + + + + Codex Orange Book + + + +
+
+

Unofficial Codex Guide

+

Codex Orange Book

+

A practical guide from setup to real-world Codex workflows.

+

Machine-assisted English edition. Verify fast-changing product details against official docs and your account UI.

+
+ +
+ +
+
+

Codex Orange Book: A Practical Guide from Setup to Real-World Workflows

+
+

Unofficial open-source guide · Continuously updated edition
+A Codex handbook for developers, indie makers, and power users of AI tools.

+
+ + + + + + + + + + + + + + + +
VersionLast VerificationData Nature
v0.1.02026-06-22Unofficial guide, not OpenAI documentation or a product commitment
+
+

This guide is based on Codex App, Codex CLI, Codex IDE Extension, and Codex Web/Cloud capabilities and observed UI available on 2026-06-22. Codex changes quickly, so installation paths, model names, quotas, entry points, and command parameters may change. For current features and pricing, rely on official OpenAI documentation, the current Codex version, and what your own account shows. +Third-party tools and model access solutions such as CC Switch and DeepSeek are only recorded as extension methods and are not official OpenAI functions.

+

Translation note: this English edition is machine-assisted from the Chinese source and may lag behind future Chinese updates. Please verify product details against current OpenAI documentation and your own account UI.

+
+

Reading Entry

+ +

Table of Contents

+
    +
  • +
      +
    1. Instructions for use
      2. +
    +
    • +
  • Part 1: Understand what Codex is
    • +
  • Part 2: Installation, configuration, and environment setup
    • +
  • Part 3: Core functions
    • +
  • Part 4: Standard workflow
    • +
  • Part 5: Hands-on case library
    • +
  • Appendix: Third-party model access
    • +
+

0. Instructions for use

+

0.1 Important Statement

+
    +
  • This material is an unofficial guide and does not represent official OpenAI documentation.
    • +
  • All functions are subject to the official OpenAI documentation and the actual version of Codex.
    • +
  • This PDF will be continuously maintained with Codex updates.
    • +
  • Readers are advised to check the latest version of the Markdown manuscript in the GitHub repository first.
    • +
+

0.2 Who is this PDF suitable for?

+
    +
  • People who have never used Codex but want to get started with the system.
    • +
  • People who can write code but don't know how to connect Codex to real projects.
    • +
  • People who have used Cursor, Claude Code, ChatGPT and want to compare Codex workflows.
    • +
  • Independent developer, AI tool blogger, technical team leader.
    • +
  • People who want to build AI programming workflows, knowledge bases and automated processes.
    • +
+

0.3 Reading route

+
    +
  • Quick Start Route: 0. Instructions → Part 1: Understand what Codex is first → Part 2: Installation, configuration and environment preparation → Part 4: Standard workflow → Part 5: Practical case library
    • +
  • Core Route for Developers: Part 1: First understand what Codex is → Part 2: Installation, configuration and environment preparation → Part 3: Detailed explanation of core functions → Part 4: Standard workflow
    • +
  • Advanced expansion route: Part 3: Detailed explanation of core functions → Part 4: Standard workflow → Appendix: Third-party model access
    • +
+
+

Article 1: First understand what Codex is

+

Basic knowledge of Codex

+

What exactly is Codex?

+

When many people hear Codex for the first time, they will subconsciously understand it as "another AI code writing tool."

+

But if you only think of Codex as "ChatGPT that writes code for me", it's easy to underestimate it.

+

What is really important about Codex is not whether it can write a function, add a piece of code, or explain an error, but that it represents a change in the role of AI programming tools:

+

In the past, AI was the person sitting next to you to help you fill in the code.

+

Later, AI is the person who changes the code with you in the editor.

+

Now, Codex is more like a project executor that can be assigned tasks.

+

It doesn't just answer "how to write this code", but can enter a project, read the file, understand the context, make a plan, modify the code, run the command, check the results, and finally organize the changes into results that can be reviewed.

+

This is the biggest difference between Codex and ordinary AI chat tools.

+
+
Changed four times in five years
+

+ AI编程工具的四次进化历程 +

+ +

Four evolutions of AI programming tools

+

In the past few years, AI programming tools have generally gone through four stages.

+

**2021: The era of Copilot completion. ** +The first time the name Codex was heard by a large number of developers was because of GitHub Copilot. At that time, AI was mainly responsible for code completion: you wrote the beginning, and it completed the end; you wrote the function name, and it completed the function body. It is like a smarter input method that allows you to write faster, but how to dismantle the project, how to find the files, and how to run the test still mainly depends on people.

+

**2022: ChatGPT conversation era. ** +After ChatGPT appears, AI programming moves from "completion" to "dialogue". You can directly ask it about the reason for the error, code optimization, interface writing, and project structure explanation. AI transforms from an input method into a question-and-answer companion. But it is usually not in a real project. You need to copy the code, paste the error report, manually fill in the context, and then move the answer back to the project.

+

**2023-2024: Cursor Project Collaboration Era. ** +AI editors such as Cursor allow AI to truly enter the editor, where it can see files, modify functions, reconstruct across files, and complete some development tasks based on the project context. AI begins to shift from “answering questions” to “assisting in modifying projects.” But most of the time it is still attached to the IDE, and you still need to keep an eye on it to make changes, determine the next step, run tests, and organize submissions.

+

**2025: Codex Engineering Agent Era. ** +After Codex reappeared, it was no longer just a model responsible for code completion, but a coding agent for real software engineering tasks. It can read projects, interpret code, fix bugs, add features, add tests, refactor modules, run commands, check diffs, organize PR notes, and even process multiple engineering tasks in parallel.

+

This means that the focus of AI programming tools is shifting from "helping you write code" to "helping you deliver tasks."

+

One sentence summary:

+

**Copilot helps you make up the code, ChatGPT helps you think about the code, Cursor accompanies you to modify the project, and Codex starts to help you perform engineering tasks. **

+
+

What can Codex do?

+

What Codex Can Do

+

+ Codex能做什么的内容 +

+ +

Many people will ask directly when using Codex for the first time:

+
    +
  • "Write a login page for me."
    • +
  • "Help me fix this bug."
    • +
  • "Help me with a project."
    • +
+

These certainly work, but they are not accurate enough.

+

What Codex is really good at is not generating a piece of code out of thin air, but completing a set of engineering tasks in a real project.

+

It can read the project, find files, understand the context, make plans, modify code, run commands, check results, organize diffs, and finally advance the task to a state that can be reviewed.

+

So, don’t think of Codex as a “code generation button”.

+

More precisely:

+

**Codex is an AI engineering assistant that can enter the project site. **

+

What it can do can be roughly divided into the following categories.

+
+
Understand an unfamiliar project
+

The first step in using Codex should not be to let it write code directly, but to let it read the project first.

+

It can help you figure it out quickly:

+
    +
  • What technology stack is used for the project.
    • +
  • Where is the entry file.
    • +
  • where the core module is.
    • +
  • What are the test and build commands.
    • +
  • Which files cannot be moved casually.
    • +
+

Many Codex tasks fail, not because it cannot write code, but because it is asked to do it directly before it understands the project.

+
+
Explain the code and sort out the logic
+

Codex can help you explain the code you don't understand.

+

For example:

+
    +
  • What does this function do.
    • +
  • Why is this component written like this.
    • +
  • What is the interface call link.
    • +
  • where the status comes from.
    • +
  • Which files this bug may be related to.
    • +
+

It not only explains a single function, but also combines the context to sort out module relationships, data flows and potential risks.

+

This is especially useful for taking over old projects.

+
+
Fix bugs and add features
+

Codex is well suited for handling well-bounded development tasks.

+

For example:

+
    +
  • Fix a reproducible bug.
    • +
  • Add a new settings page.
    • +
  • Add a new form check.
    • +
  • Add a new interface.
    • +
  • Added an export button.
    • +
  • Optimize a front-end page.
    • +
+

But don't just throw a big project at it.

+

A better way is to break the task into smaller pieces:

+
    +
  1. Read the project first.
    2. +
  2. Come up with another plan.
    3. +
  3. Only change one module.
    4. +
  4. Run the test.
    5. +
  5. Look at the diff.
    6. +
  6. Confirm that there is no problem before continuing.
    7. +
+

Codex is better suited for completing small tasks in a row rather than swallowing large projects all at once.

+
+
Write tests and do refactoring
+

Codex can help you make up tests and refactor your code.

+

It can do:

+
    +
  • Supplementary unit tests.
    • +
  • Supplementary boundary conditions.
    • +
  • Fix abnormal scenes.
    • +
  • Extract duplicate logic.
    • +
  • Split too long function.
    • +
  • Organize component structure.
    • +
  • Encapsulates API requests.
    • +
+

But such tasks must have boundaries:

+
    +
  • Do not change the business logic.
    • +
  • No changes to the public API.
    • +
  • No extraneous dependencies are introduced.
    • +
  • Not extensively refactored.
    • +
  • Test must be run after modification.
    • +
+

Codex can be refactored, but you have to control the scope.

+
+
Write documents and organize PR
+

Codex is very suitable for writing engineering documents.

+

For example:

+
    +
  • README。
    • +
  • Installation instructions.
    • +
  • Startup instructions.
    • +
  • Interface documentation.
    • +
  • Environment variable description.
    • +
  • Project structure description.
    • +
  • PR description.
    • +
  • commit message。
    • +
  • Change log.
    • +
+

The document is not an accessory.

+

In a Codex workflow, the document itself is the contextual infrastructure.

+

The clearer the documentation, the easier it will be for subsequent people and AI to take over the project.

+

But be reminded of Codex:

+

**Do not make up non-existent commands, and uncertain information must be clearly marked. **

+
+
Run commands, read diff, and do review
+

One of the biggest differences between Codex and ordinary chat tools is that it can run commands in the project environment.

+

It can:

+
    +
  • Run the test.
    • +
  • run lint.
    • +
  • Run typecheck.
    • +
  • Run build.
    • +
  • View git status.
    • +
  • View git diff.
    • +
  • Search code.
    • +
  • Check the modification results.
    • +
+

This allows Codex to not just "guess the answer" but to verify the result.

+

But there are risks in command execution.

+

If it can be verified, you can let it be verified.

+

Risky and must be approved by you.

+

Do not leave it to automatic execution for operations involving the production environment, database, and real user data.

+
+
When is it appropriate to use Codex?
+

is suitable for Codex tasks and generally has several characteristics:

+
    +
  • clear goals.
    • +
  • Range controllable.
    • +
  • clear context.
    • +
  • results can be verified.
    • +
  • Can be rolled back on failure.
    • +
  • Risk acceptable.
    • +
+

For example:

+
    +
  • Read item.
    • +
  • bug fix.
    • +
  • Added small functions.
    • +
  • Supplementary test.
    • +
  • Write documentation.
    • +
  • Optimize the front-end page.
    • +
  • Clean up PR.
    • +
  • Review diff.
    • +
  • Handles recurring tasks.
    • +
+
+
When is it not appropriate to use Codex directly?
+

It is not recommended to let Codex handle it directly:

+
    +
  • Production database.
    • +
  • Real user data.
    • +
  • payment core logic.
    • +
  • Permissions and security core module.
    • +
  • Large-scale architecture migration.
    • +
  • Important items not backed up.
    • +
  • Core business not tested.
    • +
  • A task that you yourself cannot accept.
    • +
+

If you can't tell whether the result is correct or not, don't let Codex complete it independently.

+

Codex can improve efficiency, but it cannot make judgments for you.

+
+
One sentence summary
+

Codex can do more than just write code.

+
+

Its really important capabilities are:

+
+

**Promote a clear software engineering task from requirements to reviewable results. **

+

You don't let it just write some code.

+

You are allowing it to complete a controllable engineering task according to your project rules, context, and acceptance criteria.

+
+

The difference between Codex and ChatGPT

+

Many people will ask:

+

Since ChatGPT can also write code, why use Codex?

+

The core difference is:

+

**ChatGPT is more like a consultant. If you have questions, ask GPT, get answers from it, and then execute it yourself. So now Codex is more like an intern. We can really let it help us work and complete the tasks assigned to it. **

+

ChatGPT is suitable for helping you think about problems.

+

Codex is suitable to help you advance your mission.

+

A more reasonable usage is:

+

**Use ChatGPT to think clearly, and then use Codex to execute the project. **

+

+ ChatGPT与Codex的区别对比表，分为核心定位、主要方式、适合场景、项目上下文、交付结果、使用重点六个方面 +

+ +

The difference between Codex and Cursor

+

Many people compare Codex and Cursor together, because they can both help you write code, change code, and understand projects.

+

But their positioning is different.

+

**Cursor is more like an AI editor, and Codex is more like an engineering agent. **

+

Reasonable usage is to use it in combination:

+

**Use Cursor for daily coding and partial modification, and use Codex for task promotion and project delivery. **

+

Cursor is responsible for writing with you.

+

Codex is responsible for helping you run the complete mission.

+

One is for IDE collaboration and the other is for Agent execution.

+

This is their biggest difference.

+

+ 图片以“Cursor与Codex的区别”为标题，对比了两者在核心定位、使用位置、主要方式、适合场景、工作粒度、交付结果及使用重点等方面的差异 +

+ +

The difference between Codex and Claude Code

+

Codex is very similar to Claude Code.

+

are both agentic coding tools, but their focus is different.

+
+
Claude Code prefers long-term collaboration in the terminal
+

The experience of Claude Code is more like:

+

You open the terminal, put it into the project, and then continue to collaborate with it around a development task.

+

It is suitable for:

+
    +
  • Long read item.
    • +
  • Continuous tracking of a complex task.
    • +
  • Discuss and modify in the terminal.
    • +
  • Handles multi-step engineering problems.
    • +
  • Extend workflow through hooks, subagents, MCP and other mechanisms.
    • +
+

Therefore, Claude Code is more like an AI engineering partner that stays in your terminal for a long time.

+

Its strengths lie in command line workflow, deep contextual collaboration, and continuous advancement of engineering tasks.

+
+
Codex is more focused on multi-terminal task execution in the OpenAI ecosystem
+

The advantage of Codex is not only in the CLI, but also in the multi-terminal linkage in the OpenAI ecosystem.

+

It can be used through different entrances:

+

Codex CLI。

+

Codex App。

+

Codex IDE Extension。

+

Codex Web。

+

ChatGPT account system.

+

GitHub/PR workflow.

+

Skills and Project Rules.

+

According to OpenAI official documentation, Codex CLI is the coding agent in the local terminal; Codex App provides desktop multi-threading, worktree, automation and Git functions; Codex Skills can also be reused in CLI, IDE extension and Codex app.

+

Therefore, Codex is more like an engineering task platform connected to the OpenAI ecosystem.

+

It is not just "writing code in the terminal", but can be transferred between multiple portals such as App, CLI, IDE, Web, etc., allowing you to manage, execute and review engineering tasks in different ways.

+
+
How to choose
+

If you prefer terminal workflow and want AI to stay in the project for a long time and continuously collaborate with you on complex tasks, Claude Code is very suitable.

+

If you are already using the ChatGPT and OpenAI ecosystem and want to switch between CLI, desktop App, IDE, and Web, and string together tasks, diff, PR, Skills, and GitHub workflows, Codex will be more convenient.

+

But there is no absolute replacement between the two.

+

The final choice depends on:

+
    +
  • Model capabilities.
    • +
  • Context handling.
    • +
  • Toolchain.
    • +
  • Price.
    • +
  • Team Habits.
    • +
  • Your own development process.
    • +
+

One sentence summary:

+

**Claude Code is more like a long-term engineering partner in the terminal, and Codex is more like a multi-terminal engineering agent in the OpenAI ecosystem. **

+

+ Claude Code与Codex的区别对比表，从核心定位、主要入口、工作风格、适合场景、扩展能力、生态优势、选择关键等7方面进行对比 +

+ +

One sentence summary Codex

+
    +
  • Basic usage: let it help you write code.
    • +
  • Intermediate usage: let it help you read projects, change functions, and run tests.
    • +
  • Advanced usage: Make it your project execution agent, working with rules, context, automation and team processes.
    • +
+
+

Codex usage entrance

+

+ 图片标题为“Codex的4个入口怎么选”，介绍了Codex的4种使用入口：2.1 Codex App、2.2 Codex CLI、2.3 Codex IDE Extensio... +

+ +

If you mainly do local projects, web page exercises and daily development, it is usually enough to start with Codex App first; after you are familiar with Git, terminal and team collaboration, you can gradually add CLI, IDE Extension and Web/Cloud.

+
+

Part 2: Installation, configuration and environment preparation

+

Preparation before installation

+

Account preparation

+

If you are an ordinary individual user, it is recommended to prepare:

+
    +
  • ChatGPT account
    • +
  • A network that can normally access ChatGPT / OpenAI services
    • +
  • Select the ChatGPT package that currently includes Codex; the package name, quota and functional scope will change, please refer to the official page and the actual display in your account.
    • +
+

System preparation

+

Four major forms of Codex:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodWho is suitablePreparation required
Codex App desktop versionNewbies, people who want a graphical interfaceWindows or macOS
Codex CLIPeople who know a little about terminalsTerminal, Git, project environment
Codex IDE Extension pluginPeople who use VS Code / Cursor / WindsurfEditor + plugin
Codex Web / CloudPeople who want Codex to work remotely on GitHub projectsGitHub repositories
+

Codex App supports macOS and Windows; Codex CLI supports macOS, Windows and Linux.

+

Software tool preparation

+

Before installing Codex, it is recommended to prepare these basic tools:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolsFunctionDownload/Registration Link
GitAllow Codex to view code changes, generate diff, and roll back modificationsGit official download
VS Code / CursorConvenient to view and edit codeVS Code download / Cursor download
TerminalPowerShell for Windows; Terminal for MacNo need to download, the system comes with it
BrowserLogin ChatGPT / OpenAI / GitHubChrome Download
Node.jsCommonly used for web pages, front-end, Next.js, Vite projectsNode.js download
PythonCommonly used for scripting, automation, and data processingPython download
GitHub accountIf you want to use Codex Cloud or push code, you need to prepareGitHub registration
Codex AppCodex desktop version, use graphical interface to manage tasks and projectsCodex App official page
Codex CLIUse Codex in the terminal, suitable for real project developmentCodex CLI official documentation
Codex web versionAfter connecting to GitHub, let Codex handle projects in the cloudCodex Web
+
+

Project directory preparation

+
+

Codex is not a simple chat tool, it requires entering a specific project directory to work. The official entry process is also: After logging in to Codex, select a folder or Git repository on your computer, and then start the first task.

+

It is recommended that you create a special practice directory in advance, such as:

+
D:\AI-Codex-Projects
+
+

You can put:

+
hello-web
+ai-tools-page
+xiaohongshu-cover-tool
+landing-page-demo
+
+

Don’t let Codex operate on your most important real projects right from the start. First use the practice project to familiarize yourself with how it changes files, runs commands, and generates results.

+
+

Permissions and Security Preparations

+
+

Codex can read, modify files, and run commands in your project directory. The official description of the CLI is: it can read, modify code, and run commands in the directory of your choice.

+

So please pay attention before installation:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NotesSuggestions
Do not put important files directlyUse test projects first
Do not write the password/API key in the codeUse .env files and avoid uploading
Git commit before operationConvenient rollback
See clearly the commands to be executed by CodexIf you don’t understand the command, ask it for explanation first
Don't give it permissions to the entire C driveSelect only specific project folders
+

It is recommended that each project initialize Git:

+
git init
+git add .
+git commit -m "initial commit"
+
+

In this way, if the Codex is changed, it can be rolled back.

+
+

Codex App installation and getting started (most recommended for novices and the most powerful one)

+
+

Download and Installation

+
+
macOS installation
+

If you are using a Mac, first confirm your chip type.

+

Click the Apple icon in the upper left corner of your computer and select "About This Mac."

+

If displayed:

+
    +
  • Apple M1 / M2 / M3 / M4: Select Apple Silicon version
    • +
  • Intel: Select Intel version
    • +
+

After entering the Codex App official page, download the corresponding version according to your own chip. After the download is complete, open the installation package and drag Codex into the "Applications" folder.

+

After the installation is complete, open Codex in "Applications".

+

When opening it for the first time, the system may prompt:

+

"This is an application downloaded from the Internet. Are you sure to open it?"

+

Select "Open".

+
The difference between Intel Mac and Apple Silicon
+

Mac is mainly divided into two types of chips:

+ + + + + + + + + + + + + + + + + + + + +
TypeCommon modelsShould be downloaded
Apple SiliconM1 / M2 / M3 / M4 MacApple Silicon version
Intel MacOld Intel chip MacIntel version
+

The simplest way to judge:

+

Open "About This Mac" to view the chip information.

+

If you write about Apple M series, it is Apple Silicon.

+

If it says Intel Core i5, Intel Core i7, Intel Core i9, it means Intel Mac.

+

Don’t choose this place wrong. Selecting the wrong version may result in inability to install, inability to open, or unstable operation.

+
Windows Installation
+

If you are using Windows, enter the Codex App official page and select the Windows version.

+

The Windows version will generally jump to the Microsoft Store for installation.

+

Installation steps:

+
    +
  1. Open Codex App official page
    2. +
  2. Click on the Windows download portal
    3. +
+

+ Codex App在Windows平台的下载页面 +

+ +
    +
  1. Jump to Microsoft Store
    2. +
+

+ Microsoft Store中Codex应用的页面 +

+ +
    +
  1. Click "Get" or "Install" (I have already installed it here, so it shows open)
    2. +
  2. Open Codex App
    3. +
  3. Codex App has been installed here.
    4. +
+

Open Codex App for the first time

+
Select project directory
+

After opening the Codex App for the first time, after logging in, the system will ask you to select a project directory.

+

The "project directory" here can be understood as:

+

Codex Which folder to enter to work.

+

For example, if you want Codex to help you create a web page, you can create a new folder in advance:

+
hello-codex
+
+

Then select this folder in the Codex App.

+

Newbies are advised to choose a clean exercise directory for the first time, not the C drive directly, and don’t select important work items right from the start.

+

Recommended directory structure:

+
AI-Codex-Projects
+└── hello-codex
+    └── index.html
+
+

After selecting the project directory, Codex knows which files it should read, which files it should change, and where it should run the command.

+

+ Codex App中选择项目目录的界面 +

+ +
Understanding the project list
+

After entering the Codex App, you will usually see a list of projects on the left.

+

You can understand the project list as:

+

Different code folders that you hand over to Codex.

+

For example:

+
hello-codex
+ai-first-page
+
+

Each project corresponds to a local folder on your computer, or a Git repository.

+

If you have opened projects in Codex App, Codex CLI, or Codex IDE Extension before, these projects may also appear in the list.

+

Newbies should remember one thing:

+

The project list is not a chat record list, but a "code project list".

+

When you click on different projects, the file range seen by Codex is also different.

+

+ Codex App的界面左侧菜单栏 +

+ +
Understanding thread (dialogue)
+

Thread can be understood as:

+

A task dialogue in the same project.

+

For example, in the project hello-Codex, you can open multiple threads:

+
Thread 1：做一个首页
+Thread 2：修复按钮点击无反应的问题
+Thread 3：优化移动端样式
+Thread 4：帮我写 README
+
+

+ Codex App的菜单界面 +

+ +

Each thread has its own context.

+

In other words, if you ask Codex to be the home page in Thread 1, it will continue to understand and modify around this task.

+

You tell it to fix bugs in Thread 2, and it will work around another task.

+

Newbies can easily understand:

+
    +
  • project = a company
    • +
  • thread = employees in the company
    • +
+

Don't cram everything into the same thread.

+

A better approach is:

+

A clear task, open a thread.

+

For example:

+
请帮我做一个个人主页
+
+

This is a thread.

+
请检查为什么移动端布局错位
+
+

This is another thread.

+

In this way, the project will not be messy, and the Codex will make it easier to understand the task boundaries.

+
Understanding the task window
+

The task window is where you talk to Codex and arrange work.

+

You can enter the task here, such as:

+
请帮我做一个简单网页，黑色背景，中间显示 Hello, Codex。
+
+

+ Codex App中“做一个首页”任务的执行界面 +

+ +

You can also continue to ask:

+
请把这个页面改得更像科技产品首页。
+
+

These contents usually appear in the task window:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ContentFunction
Your task descriptionTell Codex what to do
Codex’s planWhat it plans to do
Codex execution processIt is reading files, changing files, and running commands
Summary of CodexWhat was changed in the end
Subsequent input boxYou can continue to let it be modified
+

When using it for the first time, do not write too complex tasks.

+

Not recommended:

+
帮我做一个完整的 AI 工具平台，要有登录、支付、数据库、后台管理。
+
+

Recommended:

+
请帮我做一个简单的产品介绍页，只用 HTML 和 CSS。
+
+

The clearer the task, the easier it is to do the Codex well.

+
Understanding review pane
+

Review pane can be understood as:

+

Check the Codex to see what has been changed.

+

After modifying the file in Codex, you should not just read its text summary, but open the review pane to see the actual changes.

+

+ Codex App中“做一个首页”任务的review pane界面 +

+ +

It will tell you:

+
    +
  • which files were modified
    • +
  • where new codes have been added
    • +
  • where code was removed
    • +
  • What changes are acceptable
    • +
  • Which changes can be rolled back
    • +
+
+

Newbies can understand review pane as:

+
+

Codex's "Operation Inspection Area".

+

You don't just trust the Codex after it's written, but you have to check what homework it handed in here.

+

If you are not satisfied with a certain line of code, you can leave a comment in the corresponding position and let Codex continue to modify it according to your comments.

+

For example, you can comment:

+
这里的按钮颜色太亮了，改成更克制的深蓝色。
+
+

or:

+
这段代码太复杂，请改成新手更容易理解的写法。
+
+
Understanding diff
+

Diff is a comparison of code changes.

+

+ Codex App界面，左侧为项目文件夹，中间是代码编辑区域，右侧是review pane +

+ +
+

Newbies can understand it this way:

+
+
绿色 = 新增内容
+红色 = 删除内容
+
+

For example, Codex originally did not have a title, but later added a line:

+
<h1>Hello, Codex</h1>
+
+

This line will be displayed as new.

+

If Codex deletes an old section of code, that section will appear as deleted.

+

The function of Diff is to let you see clearly:

+

What exactly has been changed in Codex.

+

Don’t just look at the final page, and don’t just look at the summary of the Codex.

+

What really matters is looking at the diff.

+

Because Codex may sometimes:

+
    +
  • I changed things that you didn’t ask for.
    • +
  • Removed some code you still need
    • +
  • Make simple code complex
    • +
  • Modified multiple files but did not explain clearly
    • +
+

So when you first start using it, you need to develop a habit:

+
每次 Codex 完成任务后，先看 diff，再决定要不要接受。
+
+
Recommended operation process after opening for the first time
+

When opening Codex App for the first time, you can follow this sequence:

+
1. 登录 ChatGPT
+2. 选择一个练习项目目录
+3. 新建或选择一个 thread
+4. 在任务窗口输入一个简单任务
+5. 等 Codex 修改文件
+6. 打开 review pane
+7. 查看 diff
+8. 确认没有问题后再继续修改
+
+

Recommended first task:

+
请帮我做一个简单网页，要求：
+1. 黑色背景
+2. 页面中间显示大字 Hello, Codex
+3. 字体白色
+4. 页面整体水平和垂直居中
+5. 只使用 HTML 和 CSS
+
+

This task is simple enough and suitable for familiarizing yourself with the basic process of Codex App.

+
Several concepts that beginners need to remember
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptSimple understanding
Project directoryYour company's address
Project listYour company's project department
threadAn employee of a project department
Task windowA place to give instructions to employees
review paneCheck for changes
diffComparison of new and deleted codes
+

Basic use of Codex App

+
Basic layout
+

You can see that the Codex App is a classic three-column layout

+

On the left is the task list

+

The middle is the dialogue window

+

On the right is the multi-functional area

+

+ Codex App的基础布局 +

+ +
New conversation
+
Use Project
+

We can open a new conversation to perform a new task

+

After opening a new conversation, you need to select which project the new conversation belongs to.

+

+ Codex App的界面，左侧任务列表中“hello - Codex”项目被选中 +

+ +

Of course, we can also directly click on the small button on the right side of the project to directly open a new conversation corresponding to the project.

+

+ Codex App的界面，左侧任务列表中“hello - Codex”项目被红色框突出显示 +

+ +
Do not use the project
+

Click on the unused project, and the corresponding conversation will be displayed in the conversation, which can be used as a question unrelated to the project.

+

+ Codex App的对话界面 +

+ +

+ Codex App的界面 +

+ +
Search
+

There are too many dialogues in later tasks, but I just remember that some key times cannot find the corresponding task dialogues. You can search here directly, search for keywords, and you will find the corresponding task dialogues.

+

+ Codex App的界面，左侧为任务列表，中间是对话窗口，右侧是多功能区域 +

+ +
Plugin
+

There are many functions, which will be discussed later.

+
Automation
+

There are many functions, which will be discussed later.

+
+
Project
+
+
Create project
+

You can create a new project directly in Codex or use an existing project

+

The created or selected project will appear in the project bar to facilitate subsequent management.

+

+ Codex App中“自动化”功能界面 +

+ +
thread
+

thread is a "single task conversation" in a project

+

+ Codex App中“自动化”页面 +

+ +

For example, you have a project called:

+
hello-codex
+
+

You can open multiple threads in this project:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ThreadRepresented task
Thread 1Make a home page
Thread 2Fix button click does not respond
Thread 3Optimize mobile style
Thread 4Help me write README
Thread 5Check if there are any errors in the project
+

You can understand it this way:

+
Project 项目 = 一个代码文件夹
+Thread = 这个项目里的一个具体任务
+
+

For example:

+
项目：小红书封面生成器
+Thread 1：做首页
+Thread 2：修复上传图片失败
+Thread 3：优化手机端布局
+Thread 4：写项目说明文档
+
+
+

**Why is there a thread? **

+
+

Because different tasks are best done separately.

+

If you cram "making the homepage, fixing bugs, changing styles, and writing documents" into one conversation, Codex will easily get confused in context, and it will be difficult for you to check what it has changed.

+

A better usage is:

+
一个明确任务 = 一个 thread
+
+

For example, if you want to make a page:

+
请帮我做一个 AI 工具介绍页。
+
+

This is a thread.

+

If you find something wrong with the button later, open a new thread:

+
请检查为什么首页按钮点击后没有反应。
+
+

One sentence summary:

+
+

**Thread is the task dialogue in Codex App. A thread is dedicated to processing a specific task. **

+
+
Waiting for approval
+

When we perform tasks in Codex, we often require users to approve permissions.

+

and the tags waiting for approval will be prompted in the corresponding dialogue.

+

After clicking on the corresponding conversation and then clicking on Allow, Codex will continue with the next work.

+

+ Codex App中“等待批准”界面 +

+ +
Archive
+

Archive Archive can be understood as putting away a thread that has been completed and does not need to be processed for the time being.

+

Its function is not to delete code, nor to merge code, but to make your task list cleaner.

+

+ Codex App中“自动化”功能界面 +

+ +

For example, if you complete these tasks:

+
Thread 1：优化移动端样式
+Thread 2：做一个首页
+Thread 3：做一个首页
+
+
+

Thread 2 and Thread 3 have been completed, and you don’t plan to use Thread 1 anymore, so you can archive them.

+

After archiving, they will no longer occupy the position of the current task list, and your project interface will be cleaner.

+

Cancel the archive. Of course, you can also find the archived conversation in the settings and restore it

+

+ Codex App中“已归档对话”界面 +

+ +
Settings
+
Remaining balance
+

Here you can see the quota, rate limit or usage of the current account.

+

Different packages, workspaces, models and versions may display different restrictions; the specific length of use, when to restore, and whether additional credits can be purchased are subject to the current Codex interface and official instructions.

+

+ Codex App中“剩余额度”页面 +

+ +
Dialog window
+
Permission Control
+
Sandbox
+

To know permission control, you must first know the concept of a sandbox (Sandbox)

+

You can understand it as:

+
+

Codex You can work inside the fence, but you can't just go outside the fence and mess with your computer.

+
+

Because Codex App is not an ordinary chat tool. It can read files, change files, and run commands, so there must be a "fence" to limit where it can touch, whether it can be connected to the Internet, and whether it can change files outside the project. According to the official documentation, Codex's sandbox mode includes read-only, workspace-write, and danger-full-access, which are used to control file system and network access boundaries.

+
Simply put
+

Assume your project folder is:

+
D:\AI-Codex-Projects\hello-codex
+
+

If the sandbox is turned on, Codex can only work within the scope of this project folder, for example:

+
可以看 index.html
+可以改 style.css
+可以运行 npm run dev
+
+

But if it wants to do these things, it may need your approval:

+
访问桌面文件
+读取下载文件夹
+修改项目外的文件
+联网下载东西
+运行高风险命令
+
+

So:

+
Sandbox = 给 Codex 设置工作边界
+
+
Three major permissions
+

+ Codex App的权限控制界面 +

+ +
请求批准
+替我审批
+完全访问权限
+
+

can be understood as follows:

+ + + + + + + + + + + + + + + + + + + + + +
Options you seeRelationship with Sandbox
Request approvalThere are sandbox restrictions, please ask you first for out-of-bounds operations
Approval for meLet the system automatically determine part of the approval for you
Full accessRelease the sandbox and can perform any operation on the computer, with the highest risk
+

Beginners are advised to enable:

+

Request approval or automatic approval class options. If you are new, prefer a mode that does not let go of project boundaries: let Codex work within the current project, but still stop and let you confirm when it encounters out-of-bounds, networked, or high-risk commands. The names of permission options may be different in different versions. The core principle is: don't enable full access at the beginning.

+
One sentence summary
+
+

**Sandbox The sandbox is the safety fence of Codex. **

+
+

It determines whether the Codex can:

+
看文件
+改文件
+访问项目外目录
+联网
+运行命令
+
+
Model model selection
+
Inference strength
+

You can see that the inference intensity is divided into 4 levels. The higher the intensity, the stronger the inference ability and the greater the time and token consumption.

+

+ Codex App中“做一个首页”任务的对话窗口界面 +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionsIn simple termsFit for the task
LowThink less, be fast, save creditChange copywriting, change colors, minor issues
MediumBalance speed and qualityOrdinary web pages, simple bugs, daily development
HighThink deeper, more suitable for complex problemsMultiple file modifications, complex bugs, refactoring
Super highThe most serious, the slowest, the most time-consumingDifficult questions, architecture analysis, bugs that cannot be fixed repeatedly
+
Model selection
+

Different models can be selected here. Model capabilities, available scope, and consumption vary with account packages, regions, versions, and model catalogs. For ordinary tasks, just use the default recommended model; for complex tasks, consider switching to a stronger model or increasing the inference intensity.

+

+ Codex App中“做一个首页”任务的界面 +

+ +
Speed
+

Some models or versions will provide service levels such as standard/fast.

+

The speed increase, credit consumption and availability of fast mode are subject to the current interface display. You can consider turning it on when the task is urgent and the quota is sufficient; it does not need to be turned on by default for daily tasks.

+

+ Codex App中“做一个首页”任务的界面 +

+ +
Boot
+

Can interrupt the conversation midway

+

When we find that the AI misunderstands what we mean during the execution of AI, we should not let it continue to execute. At this time, manual guidance should be provided in a timely manner

+

If you do not choose to guide, it will be queued for execution. Only after the previous task is executed, the AI will execute the next task you send.

+

+ Codex App的界面，左侧为项目管理区域，显示“做一个首页”项目，有“你好”和“做一个首页”两个任务，其中“你好”任务已结束22小时 +

+ +
Plan Mode
+

After turning on the plan mode, Codex will not start working immediately. Instead, it will sort out a work plan first and confirm it with us before starting work.

+

For all complex tasks, it is recommended to turn on the planning mode first, so that leaks can be checked and filled.

+

+ Codex App中“做一个首页”任务的对话窗口界面 +

+ +

+ Codex App中“极简动效增强计划”的对话窗口 +

+ +
Multifunctional Area
+
Comments
+

Comments in the upper right corner area of the multi-function

+

When we open the page using Codex’s built-in browser, we will find a comment function

+

We can let AI help us modify only specific parts of the page

+

+ Codex App的界面 +

+ +

+ Codex App的界面，左侧为项目列表，右侧是“Hello, Codex.”的页面 +

+ +

+ Codex App的界面 +

+ +
+

Codex CLI installation and getting started

+

Codex CLI is the command line version of Codex.

+

It is suitable for people who are willing to open a terminal, such as PowerShell, Terminal, iTerm, Windows Terminal.

+

macOS / Linux installation

+

There are two common installation methods for macOS.

+
Method 1: Use npm to install
+

First make sure Node.js is installed on your computer.

+

Open Terminal and enter:

+
node -v
+npm -v
+
+

If you can see the version number, it means that Node.js and npm are available.

+

Then install the Codex CLI:

+
npm install -g @openai/codex
+
+

After the installation is completed, check whether the installation is successful:

+
codex --version
+
+

Or run directly:

+
codex
+
+
+
Method 2: Use Homebrew to install
+

Mac users can also use Homebrew:

+
brew install --cask codex
+
+

After installation, run:

+
codex
+
+
+

Xiaobai’s suggestion:

+
+
    +
  • If you have installed Node.js, use npm.
    • +
  • If you are used to Homebrew, just use brew.
    • +
+

Windows Installation

+

Windows users are advised to use PowerShell or Windows Terminal.

+

The first step is to install Node.js.

+

After the installation is complete, open PowerShell and enter:

+
node -v
+npm -v
+
+

If you can see the version number, the installation is successful.

+

The second step is to install the Codex CLI:

+
npm install -g @openai/codex
+
+

The third step is to check whether the installation is successful:

+
codex --version
+
+

Or run directly:

+
codex
+
+

For Windows users, it is recommended not to run Codex in the system directory when using it for the first time.

+

Do not operate directly in these locations:

+
C:\
+系统目录
+桌面
+下载文件夹
+重要资料文件夹
+
+

It is recommended to create a new exercise directory:

+
D:\AI-Codex-Projects\hello-codex
+
+

First run

+

After the installation is complete, enter in the terminal:

+
codex
+
+

The first time you run Codex, you will be prompted to log in.

+

There are two common login methods for Codex CLI:

+
1. 使用 ChatGPT 账号登录
+2. 使用 OpenAI API key 登录
+
+

The first method is recommended for newbies: log in with a ChatGPT account.

+
Method 1: Log in using ChatGPT account
+

This is the most suitable method for ordinary users and novices.

+

Enter in the terminal:

+
codex
+
+

Or:

+
codex login
+
+

Then select:

+
Sign in with ChatGPT
+
+

The login process is roughly as follows:

+
1. 终端输入 codex 或 codex login
+2. 选择 Sign in with ChatGPT
+3. 浏览器会自动打开登录页面
+4. 输入你的 ChatGPT 账号
+5. 登录成功后，浏览器会把登录结果传回终端
+6. 回到终端，Codex CLI 就可以使用了
+
+
Method 2: Log in using API key
+

Codex CLI also supports logging in using OpenAI API key.

+

API key login is more suitable for developers, automated scripts, CI/CD, server tasks and other scenarios.

+
+

Newbies can understand it this way:

+
+
ChatGPT 登录 = 走 ChatGPT 账号和套餐额度
+API key 登录 = 走 OpenAI Platform API 计费
+
+

If you want to log in with an API key, first go to OpenAI Platform to create an API key.

+

Then set the environment variable in the terminal.

+

macOS / Linux can be written like this:

+
export OPENAI_API_KEY="你的_API_Key"
+printenv OPENAI_API_KEY | codex login --with-api-key
+
+

Windows PowerShell can be written like this:

+
$env:OPENAI_API_KEY="你的_API_Key"
+$env:OPENAI_API_KEY | codex login --with-api-key
+
+

After successful login, Codex CLI will save the login information and run it again later:

+
codex
+
+

and you can continue to use it.

+
+
What is the difference between ChatGPT login and API key login?
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComparisonChatGPT account loginAPI key login
Suitable for peopleOrdinary users, novicesDevelopers, automation, CI/CD
Usage quotaRelated to ChatGPT packageBilled by OpenAI Platform API
Difficulty to get startedEasierSlightly more complex
Do you recommend it for beginnersRecommendedNot recommended for the first time
Suitable for local practiceSuitableOK, but not necessary
Suitable for automated scriptsGeneralMore suitable
+
API key Login Notes
+

API key is very sensitive and cannot be leaked casually.

+

Do not use API key:

+
写进代码里
+发给别人
+截图公开
+上传到 GitHub
+放进 README
+放进前端网页
+提交到 Git 仓库
+
+

If the API key is accidentally leaked, go to OpenAI Platform immediately to delete or regenerate it.

+

Although API key login is convenient for automation, it will be billed based on API usage, so novices should not run tasks for a long time without knowing the cost rules.

+
+
View current login status
+

You can use the following command to check whether you are currently logged in:

+
codex login status
+
+

If you need to log out, you can run:

+
codex logout
+
+

After exiting, you need to log in again the next time you run the Codex CLI.

+

CLI basic commands

+

Codex CLI commands can be divided into two categories:

+ + + + + + + + + + + + + + + + + + + + +
TypeUsage locationFunction
Terminal commandEnter in PowerShell / TerminalStart, log in, update, diagnose, manage Codex
Slash commandEnter after entering CodexCut model, adjust permissions, view diff, generate rules, exit session
+
CLI terminal command
+

CLI terminal command is the command entered in PowerShell / Terminal / Windows Terminal.

+
The most commonly used terminal commands for beginners
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
codexStart Codex CLIOpen the terminal version of CodexUse after entering the project
codex --versionView versionCheck if the installation is successfulThe first step after installation
codex --helpView helpView which commands are supportedDon’t know how to use the command
codex loginLog in to CodexLog in with ChatGPT account or API keyFirst time use
codex login statusCheck the login statusCheck if there is currently a loginWhen the login is abnormal
codex logoutLog outClear local login statusChange account, public computer
codex doctorCheck environment problemsAutomatically generate diagnostic reportsStartup failure, login failure, environment exception
codex updateUpdate CodexUpdate CLI versionWhen upgrade is required
codex appOpen Codex AppOpen the desktop version from the terminalWhen you want to switch to the graphical interface
+
+
Enter project related commands
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionExampleIn simple terms
cd 项目目录Enter the project foldercd D:\\AI-Codex-Projects\\hello-CodexGo to the project first
codexStart Codex in the current directorycodexLet Codex work in the current project
codex --cd 项目路径Specify directory to startcodex --cd D:\\AI-Codex-Projects\\hello-CodexSpecify the project directly without cd first
codex -C 项目路径--abbreviation for cdcodex -C ./hello-CodexShorter notation
+

The simplest way recommended by novices:

+
cd 项目目录
+codex
+
+

Do not run Codex directly in these places:

+
C:\
+桌面
+下载文件夹
+系统目录
+重要资料文件夹
+
+
+
Login related commands
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionSuitable for scenarios
codex loginOpen the browser by default and log in with a ChatGPT accountFirst choice for beginners
codex login --device-authLog in with device codeThe remote server and browser cannot be opened
printenv OPENAI_API_KEY \| codex login --with-api-keyLogin with API keyDeveloper, Automation, CI/CD
codex login statusCheck the current login method and statusNot sure if you are logged in
codex logoutDelete the login credentials saved on this machineChange account, public computer
+

Windows PowerShell Login using API key:

+
$env:OPENAI_API_KEY | codex login --with-api-key
+
+
+
Send tasks directly at startup
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionExample
codex "任务内容"Start Codex and send the first task directlycodex "请解释这个项目结构"
codex -i 图片路径 "任务"Attached pictures for analysiscodex -i __CODX_TOKEN_000__ "分析这个报错"
codex --image 图片路径 "任务"The complete writing method of -icodex --image __CODX_TOKEN_000__ "根据截图优化页面"
codex --search "任务"Allows search capabilitiescodex --search "查一下这个库的新用法"
+

Suitable for:

+
简单解释项目
+分析报错截图
+根据 UI 截图提修改建议
+查新版本文档
+
+

Newbies are more recommended to run first:

+
codex
+
+

Enter the task after entering to make it easier to observe the execution process.

+
+
Model, permissions, and sandbox related commands
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsNewbie suggestions
codex --model 模型名Specify modelSelect AI brainDefault is enough, change it for complex tasks
codex -m 模型名--model AbbreviationShorter writingNo need to force memorization
codex --sandbox read-onlyRead-only modeCan only be viewed, try not to changeUsed only when analyzing the project
codex --sandbox workspace-writeThe current project can be read and writtenAble to work in the projectDaily recommendations
codex --sandbox danger-full-accessCompletely loosen restrictionsGreat permissionsNovices not allowed to use
codex --ask-for-approval on-requestAsk you first for sensitive operationsRequest approvalRecommended for newbies
codex -a on-requestApproval mode abbreviationShorter writingRecommended
+

Recommended combination for novices:

+
codex --sandbox workspace-write --ask-for-approval on-request
+
+

means:

+
Codex 可以在当前项目里工作，但敏感操作要先问我。
+
+

Don’t think of this as a trouble-saving mode:

+
codex --sandbox danger-full-access
+
+
+
Non-interactive task command
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsSuitable for the scene
codex exec "任务"One-time task executionDon’t enter a long conversation, it will end after runningAutomation, inspection, report generation
codex e "任务"Abbreviation for execSame as aboveFast execution
codex exec --cd 项目路径 "任务"Specify the directory to execute the taskExecute it once in a projectAutomation script
codex exec resumeResume the exec sessionContinue with the last non-interactive taskAfter an automated task is interrupted
codex exec resume --lastRestore the most recent exec sessionContinue with the most recent taskThe most common recovery method
+

Example:

+
codex exec "请检查当前项目有没有明显问题"
+
+

Priority is given to beginners:

+
codex
+
+

Use codex exec after you are familiar with it.

+
+
Session management command
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
codex resumeRestore the previous sessionContinue with the previous threadNot finished last time
codex resume --lastRestore the most recent sessionContinue with the most recent taskMost commonly used
codex archiveArchive sessionPut away unused tasksTask completed or no longer required
codex unarchiveRestore archived sessionRetrieve archived tasksWant to continue after archiving
codex forkCopy the old session into a new threadKeep the original task and try a new directionTry multiple solutions
+

In simple terms:

+
resume = 接着做
+archive = 收起来
+unarchive = 找回来
+fork = 复制一份去试新方案
+
+
+
Diagnostic, update and maintenance commands
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionWhen to use
codex doctorGenerate diagnostic reportCodex startup exception, login exception, environment exception
codex updateCheck and update the Codex CLIWhen you want to upgrade the version
codex completionGenerate command completion scriptPeople who often use terminal
codex features listCheck the function switchCheck whether the function is turned on
codex features enable 功能名Turn on a functionAdvanced configuration
codex features disable 功能名Turn off a functionAdvanced configuration
+

Most commonly used by noobs:

+
codex doctor
+codex update
+
+

Don’t remember anything else.

+
+
Cloud, MCP, plugin related commands
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionDoes Newbie need it
codex cloudBrowse or perform Codex Cloud tasks in the terminalNot used for the time being
codex applyApply the diff generated by Codex Cloud to localLearn after using Cloud
codex mcp listView MCP ToolsNot used yet
codex mcp addAdd MCP serverAdvanced
codex mcp removeDelete MCP serverAdvanced
codex plugin listView pluginNot used at the moment
codex plugin addInstall pluginAdvanced
codex plugin removeDelete pluginAdvanced
+

Don't worry about these at the novice stage.

+

Waiting for you to start using:

+
Codex Cloud
+外部工具
+数据库
+Figma
+项目管理工具
+MCP
+插件
+
+

Learn this type of command again.

+
+
Sandbox test command
+ + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionWho it is suitable for
codex sandboxRun commands under Codex's sandbox rulesAdvanced users
codex sandbox --cd 项目目录 -- 命令Specify the directory to run the sandbox commandDebugging permission issues
codex execpolicyCheck whether a command will be allowed, asked, or blockedAdvanced security configuration
+

There is no need to learn it at the beginner level.

+

Just remember:

+
默认用 workspace-write + on-request。
+不要随便 full access。
+
+
+
Dangerous commands and dangerous parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Commands/ParametersWhy it’s dangerousNewbie advice
--sandbox danger-full-accessRelease file and network restrictionsDo not use
--dangerously-bypass-approvals-and-sandboxSkip approval and sandboxDo not use
--yoloAlias for the dangerous parameter aboveDo not use
--ask-for-approval neverDon’t ask you again when operating CodexDon’t use it if you are new to it
sudoSystem-level content may be modifiedDon’t allow it if you don’t understand
rm -rfMay delete a large number of filesHigh risk
git reset --hardUnsaved changes may be lostConfirm first
git clean -fdUntracked files may be deletedConfirm first
curl xxx | shDownload the script and execute it directlyHigh risk
+

After seeing these contents, ask Codex first:

+
请解释这条命令的作用、风险，以及有没有更安全的替代方案。
+
+
+
The most recommended command for beginners to remember
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RankingCommandsWhy it matters
1CodexStart Codex CLI
2codex loginLogin account
3codex login statusCheck login status
4codex doctorTroubleshoot environmental issues
5codex --versionView version
6codex resume --lastContinue from the last task
7codex archiveArchive unused tasks
8codex updateUpdate Codex
9codex exec "任务"One-time execution task
10codex logoutLog out
+
+
Recommended workflow for novices
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsCommandsPurpose
1cd project directoryenter the project folder
2git statusView the current project status
3CodexStart Codex CLI
4Enter the taskLet Codex start working
5/diffView changes in Codex
6git diffCheck again in Git
7git add .Temporarily store satisfactory modifications
8git commit -m "Description"Save a version
9codex archive or /quitArchive task or exit
+
CLI slash command
+

It is not entered in the external PowerShell / Terminal, but after entering the Codex, enter / in the Codex input box.

+
The most commonly used commands for beginners
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
/modelSwitch model and reasoning strengthChange AI brain and thinking depthWhen the task is too difficult, too slow or you want to save credits
/permissionsAdjust permissionsControl whether Codex can change files, connect to the Internet, and run commandsWhen you want to tighten or relax permissions
/diffView code changesSee what has been changed in CodexMust read after modifying files in Codex
/planEnter planning modeLet Codex give you the plan first, don’t rush to change the codeComplex tasks, bug fixes, before refactoring
/initGenerate AGENTS.mdCreate project rules fileThe first time a new project uses Codex
/statusView the current statusView model, permissions, context, token and other informationWhen not sure about the current configuration
/quitExit Codex CLIEnd current sessionExit after task is completed
/exitExit the Codex CLISimilar to /quitExit after task completion
+
+
Model is related to speed
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionWhen to use
/modelSelect model and inference strengthWhen you want to switch GPT-5.5, mini, low/medium/high inference
/fastTurn on or off Fast modeWhen you want the supported models to respond faster
/personalityAdjust your answer styleWhen you want to make your Codex more concise, explanatory, or collaborative
/statusCheck the current model and context statusWhen you want to confirm what model is being used
+

Newbie suggestions:

+
普通任务：默认模型 + 中推理
+复杂 bug：高推理
+简单改文案：低推理
+不要所有任务都开最高推理
+
+
+
Permissions related to security
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsSuggestion
/permissionsModify permissions policyControl what Codex can doKeep "Request Approval" for newbies
/approveApprove an automatically rejected operationLet the blocked operation retryUnderstand the risks before using
/sandbox-add-read-dirAdditional permission to read a certain directoryAllow Codex to read the specified directory outside the projectWindows-specific scenarios, rarely used
/statusView permissions and writable directoriesConfirm the current permission range of CodexCheck after changing permissions
+
+

Newbie suggestions:

+
+
默认用 /permissions 保持请求批准。
+不要随便放开完全访问权限。
+看不懂的操作，不要用 /approve。
+
+
+
Code inspection is related to Review
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
/diffView the current Git diffSee what is added and what is deletedMust read after modification
/reviewLet Codex review the current changesLet it check the code for problemsCheck before submission
/copyCopy the latest Codex outputQuickly copy the resultsCopy plan, summary, command description
/rawSwitch raw output modeConvenient for copying long logs or terminal outputWhen the log is very long
+

Recommended process:

+
Codex 修改完成
+→ /diff 查看改动
+→ /review 检查问题
+→ 没问题再 git commit
+
+
+
Session management related
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
/newStart a new conversationChange to a new task in the current CLIThe current task is over and you want to start a new one
/clearClear the terminal and start a new chatClear the current display and contextThe interface is too messy and want to start over
/resumeResume the previous sessionContinue with the previous taskThe last task was not completed
/archiveArchive the current session and exitPut away unused tasksThe task is completed or the plan is no longer needed
/forkCopy the current session into a new threadKeep the original idea and try another branchWant to try another solution
/sideOpen a temporary side conversationAsk a small question without affecting the main taskWant to temporarily confirm a point
/quitExit CLIEnd current useTask completed
/exitExit CLISame as /quitTask completed
+
+

Differences for beginners:

+
+
/new = 开新任务
+/clear = 清理并重新开始
+/archive = 收起当前任务
+/fork = 复制当前任务去试新方案
+/side = 临时问个小问题
+
+
+
The context is related to long conversations
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
/compactCompress the current conversationSummarize long conversations into key pointsWhen the conversation is very long and the context is almost full
/statusView context usageSee how much context space is leftAfter the task has been completed for many rounds
/mentionAttached files or foldersSpecify Codex to focus on a certain fileWant it to only view certain files
/ideIntroduce the current context of the IDEBring in the files opened by the editorUse with VS Code / Cursor
+

Newbie suggestions:

+
对话长了用 /compact。
+想让 Codex 看特定文件，用 /mention。
+不想让它乱扫整个项目，就明确指定文件。
+
+
+
Project rules are related to capabilities
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
/initGenerate AGENTS.mdCreate project rules fileUse Codex for the first time in a new project
/skillsBrowse and use SkillsSelect special skillsDo UI, write documents, review and other special tasks
/memoriesConfiguration memoriesControl whether Codex uses or generates memoriesWhen you want to manage long-term preferences
/goalSet task goalsGive Codex a continuous goalLarge tasks, long tasks
/appsBrowse connectable appsLet Codex use external appsWhen connecting to external tools
/pluginsManage pluginsView or enable plugin capabilitiesWhen plugin tools are needed
/mcpView MCP toolsSee what external tools Codex can callCheck after configuring MCP
+

Newbies are given priority to master:

+
/init
+/skills
+
+

Other commands can be learned later.

+
+
Terminal and background tasks related
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsUsage scenarios
/psView background terminal tasksSee which commands are still runningnpm dev, test, and build are still running
/stopStop the background terminal taskTerminate the command running in the backgroundThe command is stuck or does not want to continue running
/rawRaw output modeConvenient for copying terminal logsWhen the log is very long
+

Common scenarios:

+
Codex 跑了 npm run dev
+你想看它还在不在跑
+→ 用 /ps
+
+命令卡住了
+→ 用 /stop
+
+
+
The interface is related to shortcut keys
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple termsIs it commonly used
/themeSwitch code highlighting themeChange terminal display styleGeneral
/statuslineConfigure the bottom status barDisplay models, tokens, Git branches, etc.Advanced
/titleConfigure the terminal titleLet the window title display project informationAdvanced
/keymapModify shortcut keysCustomize operation keysAdvanced
/vimSwitch Vim editing modeUse Vim to edit the input boxFor people who know Vim
/debug-configView the configuration levelCheck why the configuration does not take effectAdvanced troubleshooting
+

You don’t need to use these at the novice stage.

+
+
+
Developers and Premium Features
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionWho it is suitable for
/experimentalTurn on the experimental functionUsers who like to try new things
/hooksView and manage lifecycle hooksAdvanced users, team projects
/feedbackSend logs or feedbackWhen you encounter a problem and need feedback
/agentSwitch active agent threadPeople using subagent workflow
+

These are not required for beginners.

+

Novices only need to know it, and there is no need to master it at the beginning.

+
+
The 8 most recommended tips for beginners to remember
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RankingCommandsWhy it matters
1/diffSee what was actually changed in Codex
2/planFor complex tasks, let them be planned first
3/permissionsControl permissions to avoid arbitrary changes
4/modelSwitch model and inference strength
5/statusView current model, permissions, context
6/initGenerate project rules
7/compactKey points of long dialogue compression
8/quitExit Codex
+
+
Recommended usage process for novices
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsCommandsPurpose
1/initGenerate project rules
2/permissionsMake sure the permissions are not too large
3/modelConfirm model and inference strength
4/planPlan complex tasks first
5Enter the taskLet Codex start working
6/diffCheck for code changes
7/reviewLet Codex check again
8/statusView current status and context
9/compactCompress when the conversation is too long
10/quitExit Codex
+
+
One sentence summary
+

Slash Commands are shortcut control commands in Codex CLI.

+

Novices don’t need to memorize them all, just remember these few first:

+
/diff       看改动
+/plan       先规划
+/permissions 控权限
+/model      换模型
+/status     看状态
+/init       建规则
+/compact    压缩长对话
+/quit       退出
+
+

How the CLI works

+

The working method of Codex CLI can be understood as a complete process:

+
读取项目
+→ 理解任务
+→ 提出计划
+→ 修改文件
+→ 运行命令
+→ 等待批准
+→ 展示 diff
+→ 处理失败
+
+

Newbies don’t need to understand all the technical details at the beginning, as long as they know:

+

Codex CLI will not only chat, it will actually enter the current project directory, read files, modify files, run commands, and then show you the results for inspection.

+
+
Codex How to read items
+

When you run in the project directory:

+
codex
+
+

Codex will treat the current directory as the workspace.

+

For example, if you start in this directory:

+
D:\AI-Codex-Projects\hello-codex
+
+

Codex will work around the contents of this folder.

+

It may read:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ContentFunction
Project filesUnderstanding the current code
Folder structureDetermine whether the project is a front-end, back-end or script project
package.jsonDetermine startup command, dependencies, project type
README.mdUnderstand the project description
AGENTS.mdRead the work rules you wrote for Codex
Error logAnalyze the cause of the problem
Git statusDetermine which files have been modified
+

In simple terms:

+
你在哪个文件夹启动 Codex，
+Codex 就默认把哪个文件夹当成当前项目。
+
+

So don’t start randomly in these places:

+
C:\
+桌面
+下载文件夹
+系统目录
+重要资料文件夹
+
+

Recommended practices:

+
cd 项目目录
+codex
+
+
+
How Codex understands tasks
+

After you enter the task, Codex will first determine what you want it to do.

+

For example, if you enter:

+
请帮我做一个简单网页，黑色背景，中间显示 Hello Codex。
+
+

Codex will determine:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
What it will understandExample
Task TypeNew Web Page
Modification scopeCurrent project file
May require filesindex.html, style.css
Whether you need to run the commandSimple HTML Not necessarily required
Is there any riskLow risk
+

If you enter:

+
请检查为什么 npm run build 失败。
+
+

Codex will determine:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
What it will understandExample
Task typeTroubleshoot build failure
You may want to run the commandnpm run build
May need to read filespackage.json, error related files
Do you need to modify the code?May be required
Whether your approval is requiredDepends on permission settings
+
+

Tips for beginners:

+
+

The clearer the task, the more stable the Codex.

+

Recommended writing method:

+
请帮我完成【具体任务】。
+
+要求：
+1.
+2.
+3.
+
+限制：
+1. 不要修改无关文件
+2. 不要删除已有功能
+3. 完成后告诉我改了哪些文件
+
+
+
How Codex proposes a plan
+

Before starting a complex task, Codex usually analyzes the problem and then proposes a plan.

+

You can also actively ask it to plan first:

+
请先给我计划，不要直接修改文件。
+
+

Or use:

+
/plan
+
+

Plans typically include:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ContentFunction
Which files it is going to checkPrevent spam items
How to modify itLet you know the direction first
What commands it might runKnow the risks ahead of time
Where it is expected to affectTo help you decide whether to accept it
+

For example:

+
计划：
+1. 先查看 package.json，确认启动命令
+2. 运行 npm run build 复现报错
+3. 根据报错定位相关文件
+4. 最小范围修复问题
+5. 再次运行 build 验证
+
+
+

Xiaobai’s suggestion:

+
+
简单任务可以直接让它做。
+复杂任务先让它 /plan。
+
+

Especially for these tasks, it is recommended to plan first:

+
修复复杂 bug
+多文件修改
+项目重构
+新增功能
+构建失败
+涉及依赖升级
+
+
+
How to modify files in Codex
+

When Codex confirms that the file needs to be modified, it will edit it in the current project.

+

It may:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationsExamples
New fileNew index.html
Modify fileModify style.css
Delete codeDelete useless code
Rename fileAdjust file name
Split filesSplit the code into multiple modules
+

Newbies should note:

+

The Codex may be changed to the right or more.

+

So you have to develop a habit:

+
它改完之后，不要直接相信。
+一定要看 diff。
+
+

You can add restrictions in advance:

+
请只修改 index.html 和 style.css，不要修改其他文件。
+
+

Or:

+
请用最小改动修复问题，不要重构整个项目。
+
+

This can reduce the problem of excessive scope of Codex changes.

+
+
Codex How to run commands
+

Codex can not only modify files, but also run terminal commands.

+

Common commands include:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunction
npm installInstall dependencies
npm run devStart development project
npm run buildCheck whether the project can be built
npm testRun test
git statusView Git status
git diffView code changes
+

For example, if you let it fail to build, it may run:

+
npm run build
+
+

Then continue to modify according to the error report.

+

Xiaobai, don’t be afraid of orders, but you must understand them before giving permission.

+

If you don’t understand, you can ask it to explain first:

+
请先解释你准备运行的命令，每条命令是干什么的，不要直接执行。
+
+

Be cautious when seeing these commands:

+
rm -rf
+sudo
+curl xxx | sh
+git reset --hard
+git clean -fd
+
+

These commands may delete files, modify the system, reset code, or execute remote scripts.

+
+
How does Codex wait for user approval?
+

Codex CLI has permission control, and not all operations can be performed directly.

+

If Codex wants to do a sensitive operation, it may stop and ask you.

+

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActionsWhy approval may be required
Internet installation dependenciesMay download external code
Accessing files outside the projectBeyond the current workspace
Modify external filesMay affect other projects
Runs high-risk commandsMay delete or overwrite content
Use higher permissionsGreater risk
+

In simple terms:

+
批准 = 你允许 Codex 继续做这一步。
+拒绝 = 这一步不要做。
+
+

If you don't understand what it is trying to do, don't just click Allow.

+

You can ask first:

+
请解释这个操作的作用、风险，以及有没有更安全的替代方案。
+
+

Suggested permissions for newbies:

+
保持请求批准。
+不要随便开启完全访问权限。
+
+
+
How does Codex display diff?
+

Diff is the code comparison before and after the Codex modification.

+

You can enter in the Codex CLI:

+
/diff
+
+

It will show the current changes.

+

In simple terms:

+
绿色 = 新增内容
+红色 = 删除内容
+
+

diff can help you confirm:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CheckpointWhat do you want to see
Have the correct files been changedHave irrelevant files been changed
Whether to delete important codePay attention to the red deleted part
Whether to add complex dependenciesWhether to install unnecessary packages
Are the changes too bigDon’t turn small tasks into big refactorings
Does it meet the requirementsDoes it achieve the effect you requested
+

Recommended process:

+
Codex 完成修改
+→ 输入 /diff
+→ 查看改动
+→ 不满意就让它继续改或撤回
+→ 满意后再 git commit
+
+

Don’t just look at the Codex summary.

+

What really matters is:

+
它实际改了什么。
+
+
+
How does Codex handle failures?
+

It is normal for Codex to fail to execute tasks.

+

Common failures include:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Failure typeExample
Command failednpm run build error
Missing dependenciesA package is not installed
Code errorBlank page, function error
Insufficient permissionsNo network or file access
Wrong understanding of requirementsWhat you changed is not what you want
The scope of modification is too largeI accidentally changed irrelevant files
+

Codex will normally continue analysis based on failure results.

+

For example:

+
运行 npm run build 失败
+→ 读取报错信息
+→ 定位相关文件
+→ 修改代码
+→ 再次运行 build
+
+

But you should pay attention to:

+

Don't let it try endlessly.

+

If it fails continuously, you can pause it and let it reanalyze:

+
先停一下。请总结目前失败原因，不要继续修改文件。
+
+

Or:

+
请列出你已经尝试过的方法、失败原因，以及下一步最小改动方案。
+
+

If it is messed up, you can say:

+
请撤回刚才的修改，恢复到修改前状态。
+
+

Or use Git to view it yourself:

+
git status
+git diff
+
+

Then decide whether to keep it.

+
+
Recommended workflow for novices
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActionsPurpose
1cd project directoryEnter the correct project
2CodexStart Codex CLI
3Enter the taskTell Codex what to do
4Complex tasks first /planLook at the plan first
5Wait for Codex to read the itemLet it understand the context
6Approval of sensitive operationsUnderstand before allowing
7Wait for it to modify the fileExecute the task
8Run command checkVerify results
9/diffView changes
10If not satisfied, continue to modifyIterative optimization
11When satisfied, git commitSave version
+
+
One sentence summary
+

The working method of Codex CLI is not "ask and answer", but a complete programming process:

+
读项目
+→ 想方案
+→ 改文件
+→ 跑命令
+→ 等批准
+→ 看 diff
+→ 修失败
+→ 交结果
+
+

CLI FAQ

+

Codex CLI common problems, most of them are not broken by Codex itself, but in these places:

+
The most frequently asked questions for beginners
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemsCommon CausesSolutions
Enter codex but no responseCodex is not installed, or the environment variable is not added to the commandRun codex --version first to check
Prompt command not foundThe terminal cannot find the Codex commandReinstall the Codex CLI or restart the terminal
Don’t know where to run CodexDid not enter the project directoryFirst cd the project directory, then run Codex
Codex read the wrong projectStarted in the wrong folderAfter exiting, enter the correct project directory and restart
Login failedThe browser is not open, the network is abnormal, the account is not logged inUse codex login to log in again
API key login failedKey is not set, Key is wrong, environment variables are not effectiveReset the environment variables and log in again
Codex has been waitingMaybe waiting for you to approve permissionsCheck if there is an approval prompt on the terminal
Codex cannot connect to the InternetSandbox or permission restrictionsManual approval when connected to the Internet
Don’t know what was changed after the changeDidn’t read diffEnter /diff in Codex
What to do if it is changedDid not save with Git in advanceUse git diff to check and revert if necessary
+
+
Installation issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
codex --version No outputCodex was not installed successfullyReinstall Codex CLI
codex: command not foundThe command is not added to PATHRestart the terminal or reinstall
npm installation failedNode.js / npm is not installedRun node -v and npm -v first
Command not found after Windows installationPowerShell did not refresh environment variablesClose the terminal and reopen it
The version is too oldCodex CLI is not updatedRun codex update or reinstall
+

Troubleshooting command:

+
codex --version
+node -v
+npm -v
+codex doctor
+
+
+

Xiaobai’s suggestion:

+
+
安装后第一件事，不是直接用，而是先运行 codex --version。
+能看到版本号，说明基础安装正常。
+
+
+
Login issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
Don’t know if you are logged inDid not check login statusRun codex login status
The browser does not open automaticallyThe default browser is abnormal or the remote environmentUse codex login --device-auth
ChatGPT login failureNetwork, account, browser cache issuesRe-run codex login
API key login failedEnvironment variable not set properlyCheck OPENAI_API_KEY
Want to change accountThis machine has saved the old accountFirst codex logout, then log in again
+

Common commands:

+
codex login
+codex login status
+codex logout
+codex login --device-auth
+
+
+

Newbie suggestions:

+
+
本地学习优先用 ChatGPT 账号登录。
+API key 登录更适合开发者、自动化和服务器场景。
+
+
+
Project directory issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
Codex cannot see the project fileDid not enter the project directorycd the project directory first
Codex read the wrong fileStarted in the wrong directoryExit and then re-enter the correct directory
Codex scanned too many thingsStart on desktop, download directory or C driveOnly start in specific project folder
Don’t know where you are nowDon’t know the path to the terminalUse cd for Windows, pwd for Mac
File not foundThe file is not in the current projectUse /mention to specify the file, or enter the correct directory
+

Recommended method:

+
cd D:\AI-Codex-Projects\hello-codex
+codex
+
+

Not recommended:

+
在 C 盘根目录运行
+在桌面运行
+在下载文件夹运行
+在重要资料文件夹运行
+
+

In one sentence:

+
你在哪个目录运行 codex，它就默认把哪个目录当成项目。
+
+
+
Permissions and sandbox issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
Codex prompts that approval is requiredIt needs to perform sensitive operationsUnderstand before allowing
Codex cannot access the networkThe sandbox limits the Internet by defaultManual approval if needed
Codex cannot read files outside the projectBeyond the scope of the workspaceIt is not recommended to release it casually
Codex cannot modify some filesInsufficient permissions or in read-only modeCheck /permissions
Codex requests full accessThe task requires greater permissionsNovices, please do not agree
+

Recommended settings:

+
sandbox：workspace-write
+approval：on-request
+
+

In simple terms:

+
workspace-write = 允许在当前项目里工作
+on-request = 敏感操作先问你
+
+

Do not use casually:

+
danger-full-access
+--yolo
+--dangerously-bypass-approvals-and-sandbox
+
+

If you see a permission request that you don’t understand, you can ask:

+
请解释这个操作为什么需要权限，会影响哪些文件，有没有更安全的替代方案。
+
+
+
Command running issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
npm run dev failedThe dependency is not installed or the script does not existLook at package.json first
npm install failedNetwork, source, permissions, or dependency conflictsLet Codex analyze the error first
npm run build failedThe project code itself reported an errorLet Codex reproduce and minimally repair
The command is stuckThe development server keeps runningUse /ps to view background tasks
Want to stop the commandThe command keeps occupying the terminalUse /stop to stop the background task
+

Common command meanings:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandMeaning
npm installInstall project dependencies
npm run devStart the development environment
npm run buildCheck whether the project can be officially built
npm testRun test
git statusView project change status
git diffView specific changes
+

When you don’t understand the command, let Codex explain it first:

+
请先解释你准备运行的命令，每条命令是干什么的，不要直接执行。
+
+
+
Diff and modification issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
Don’t know what has been changed in CodexDidn’t read diffEnter /diff
Too many changes in diffCodex modification scope is too largeRequire minimum changes
Changed irrelevant filesUnclear task restrictionsLet it undo irrelevant changes
Deleted important codeDid not check the red deleted partUse Git to restore or let it revert
/diff NothingNo file changes, or changes have been savedUse git status to check again
+

Recommended inspection process:

+
Codex 完成任务
+→ 输入 /diff
+→ 看改了哪些文件
+→ 看红色删除部分
+→ 看是否改了无关文件
+→ 满意后再 git commit
+
+

The prompt word can be written like this:

+
请只修改当前任务相关文件。
+不要重构整个项目。
+完成后列出修改了哪些文件。
+
+
+
Git related issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
I changed it and don’t know how to restore itI don’t use Git to save the versionI will git init and commit in the future
git status shows many filesCodex or you have changed a lot of contentUse git diff to check one by one
Don’t know which changes to keepHaven’t looked at the diffDon’t commit yet
Want to rollback after committingNot familiar with Git basicsLet Codex explain the rollback plan first
Codex changed a file that should not be changedThe scope of the task is too largeAsk it to revert irrelevant files
+

It is recommended for novices to do the following for their first project:

+
git init
+git add .
+git commit -m "initial commit"
+
+

After each change of Codex:

+
git status
+git diff
+
+

In simple terms:

+
git status = 看哪些文件变了
+git diff = 看具体变了什么
+commit = 保存一个版本
+
+
+
Model and quota issues
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
A certain model cannot be seenDifferent packages, regions or permissionsUse the currently available model
Task slows downStrong model, high inference, large projectReduce inference or reduce task scope
Credit consumption is too fastHigh reasoning, multiple rounds of modifications, reading large projectsUse low/medium reasoning for small tasks
Prompt that the limit has been reachedThe current plan quota has been exhaustedWait for the quota to be restored or purchase additional quota
API key consumption feeAPI login is billed based on API usageNewbies are given priority to log in with ChatGPT
+

Suggestions for saving quota:

+
小任务不要开最高推理。
+不要一次让 Codex 扫整个项目。
+不要反复让它大范围重构。
+能指定文件就指定文件。
+复杂任务先 /plan，再修改。
+
+

Recommended configuration:

+
普通任务：默认模型 + 中推理
+复杂 bug：高推理
+小改动：低推理
+
+
+
Codex stuck or wrong result
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
Codex stays stillWaiting for permission, command stuck, task too bigCheck if there is approval or /ps
Codex cannot be repaired repeatedlyNo root cause foundLet it summarize the reasons for failure first
Codex becomes more and more chaotic as it changesNo limit on modification scopePaused, minimum changes required
Codex misunderstood the requirementsThe task description is too vagueRewrite the goals, requirements, and limitations clearly
Output too long and garbledConversation context too longUse /compact
+

You can stop it like this:

+
先停一下，不要继续修改文件。
+请总结目前做了什么、失败在哪里、下一步最小修改方案是什么。
+
+

If it changes direction, you can say:

+
这次方向不对。请撤回刚才的无关修改，只保留和首页样式相关的改动。
+
+
+
Windows FAQ
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
PowerShell does not recognize CodexEnvironment variables are not refreshedClose the terminal and reopen it
The path contains spaces and an error is reportedThe path is not quotedUse English path or add quotes
API key command is not applicableWindows and Mac commands are differentWritten in PowerShell
Frequent permission pop-upsWindows security restrictions or sandbox approvalJust keep requesting approval
Chinese path exceptionSome tools are not compatible with Chinese pathsTry to use English for project paths
+

Recommended Windows project path:

+
D:\AI-Codex-Projects\hello-codex
+
+

Not recommended:

+
C:\Users\你的名字\桌面\新建文件夹
+
+

Reason:

+
中文路径、空格、桌面目录，有时更容易出问题。
+
+
+
macOS FAQ
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemCauseSolution
Insufficient permissionsFolder permission restrictionsChange to the project folder in the user directory
Command not foundPATH does not take effectReopen Terminal
npm permission issuesGlobal installation permission issuesPrioritize the official recommended installation method
Browser login does not jump back to the terminalBrowser blocking or network problemUse device auth
The terminal is not familiar with the pathDoes not know the current directoryUse pwd and ls
+

Recommended project path:

+
~/AI-Codex-Projects/hello-codex
+
+

Common inspection commands:

+
pwd
+ls
+codex --version
+codex doctor
+
+
+
Run codex doctor troubleshooting
+

If you don’t know where the problem is, you can run:

+
codex doctor
+
+

It is suitable for troubleshooting:

+
安装异常
+登录异常
+配置异常
+终端环境异常
+权限问题
+系统环境问题
+
+

In simple terms:

+
codex doctor = Codex 的体检命令。
+
+

When you encounter complex problems, you can send the doctor results to Codex and let it help you analyze:

+
请根据 codex doctor 的输出，帮我判断 CLI 哪里有问题。
+
+
+
General troubleshooting process for novices
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsCommands/ActionsPurpose
1codex --versionCheck whether the installation is successful
2codex login statusCheck if you are logged in
3pwd / cdConfirm current project directory
4git statusView project status
5codex doctorCheck environment issues
6/permissionsCheck permission settings
7/diffView file changes
8/psView background tasks
9/stopStop stuck command
10/compactCompact context when conversation is too long
+
+

Codex IDE Extension

+

Load Codex directly into your code editor.

+

You don’t need to open the Codex App separately, nor do you need to switch to the terminal. Instead, you can use Codex directly in the sidebar of editors such as VS Code, Cursor, and Windsurf.

+

How to understand Codex IDE Extension

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptIn simple terms
IDESoftware for writing code, such as VS Code, Cursor, Windsurf
Codex IDE ExtensionCodex installed in the editor
SidebarWhere Codex appears, like a chat panel
Current fileThe file you are opening in the editor
Selected codeThe piece of code selected by your mouse
ContextFiles, codes, error reports and task descriptions that can be referenced by Codex
+

Simply put:

+
Codex IDE = 在写代码软件里直接叫 Codex 帮你干活
+
+

Who is Codex IDE Extension suitable for?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CrowdSuitability
People who use VS CodeSuitable
People who use CursorSuitable
People using WindsurfSuitable
People who want to modify while reading the codeSuitable
People who want Codex to only see the current fileSuitable for
People who don’t want to touch the editor at allNot suitable
People who prefer graphical task managementMore suitable for Codex App
People who prefer terminalMore suitable for Codex CLI
+

Which editors does Codex IDE Extension support?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EditorDescription
VS CodeThe most common code editor for beginners
VS Code InsidersBeta version of VS Code
CursorAI editor, based on VS Code
WindsurfAI editor, also compatible with VS Code plugin system
JetBrains IDESuch as IntelliJ, PyCharm, WebStorm, Rider
+

Newbies are recommended first:

+
VS Code 或 Cursor
+
+

How to install Codex IDE Extension

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActions
1Open VS Code / Cursor / Windsurf
2Enter the extension market Extensions
3Search Codex
4Install OpenAI’s Codex extension
5Restart the editor after the installation is complete
6Find the Codex icon in the sidebar
7Click Codex to log in to your account
8Open the project folder and start using
+

If you can't find the Codex icon in Cursor, the sidebar icon may be collapsed. You can first check the left or right active bar to pin the Codex.

+
+

First time login

+

After the installation is complete, the Codex IDE Extension will prompt you to log in.

+

There are two common login methods:

+ + + + + + + + + + + + + + + + + + + + +
Login methodWho is it suitable forNewbie suggestions
ChatGPT account loginOrdinary users, novicesRecommended
API key loginDevelopers, automation, special scenariosNot recommended for use at the beginning
+
+

Newbies’ first choice:

+
+
Sign in with ChatGPT
+
+

That is, log in with your ChatGPT account.

+

API key login is more suitable for developers who understand API billing and environment variables.

+
+

Where to open Codex IDE Extension

+

After successful installation, Codex will usually appear in the editor sidebar.

+

Common locations:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
EditorPossible Locations
VS CodeBy default in the right sidebar or left active bar
CursorMay be on the left/right, or may be collapsed
WindsurfUsually in the extension sidebar
JetBrainsIn the plugin panel or tool window
+

If you can't find it, you can try:

+
1. 重启编辑器
+2. 打开 Extensions，确认 Codex 已安装
+3. 查看左侧活动栏是否有 Codex 图标
+4. 查看右侧边栏是否有 Codex 面板
+5. 在命令面板里搜索 Codex
+
+
+

What can Codex IDE Extension do?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionIn simple termsExample
Read the current fileView the code you are openingInterpret this file
Read the selected codeOnly see the part you selectedExplain this function
Modify the codeHelp you directly modify the fileChange the button to blue
Run commandExecute command in projectnpm run build
Fix error reportModify according to error messageFix build failure
Generate documentationWrite README or commentsWrite README according to the project
Switch modelChange to a stronger or faster modelGPT-5.5 / mini
Adjust reasoningControl depth of thinkingLow / Medium / High
Control permissionsControl whether files can be changed and connected to the InternetChat / Agent / Full Access
Entrust the cloudGive big tasks to the CloudRun in the cloud
+

Codex Web

+

Cloud Codex used in web pages.

+

It does not require you to keep your local computer on or operate in a terminal. Instead, you can connect to the GitHub repository and let Codex read code, execute tasks, modify files, and generate reviewable results in the cloud environment.

+

How to understand Codex Web

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptIn simple terms
Codex WebWeb version Codex
Cloud TaskCloud task, not necessarily run on your computer
RepositoryCode repository on GitHub
BranchCode branch, like an independently modified version
Pull RequestSubmit the code modified by Codex to you for review
EnvironmentCodex The environment required to run projects in the cloud
Setup ScriptInstallation command to be executed before starting the cloud environment
Maintenance ScriptOptional maintenance script, such as updating dependencies or preparing data
+

In one sentence:

+
Codex Web = 让 Codex 在云端帮你处理 GitHub 项目。
+
+
+

Who is Codex Web suitable for?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CrowdSuitability
People with GitHub repositoriesSuitable
People who want Codex to handle tasks in the cloudSuitable for
People who want Codex to create a PRSuitable
Team Project DeveloperSuitable
People who don’t want to occupy the local computer all the timeSuitable
Novice with no knowledge of GitHubNot very suitable
People who are just doing local HTML exercisesMore suitable for Codex App
People who don’t know Git / GitHubIt is recommended to learn the basics first
+
+

Xiaobai’s suggestion:

+
+
刚开始做本地练习，用 Codex App。
+项目已经放到 GitHub 后，再学 Codex Web。
+
+
+

Where is the Codex Web entrance?

+
+

The entrance to Codex Web is:

+
+
chatgpt.com/codex
+
+

After opening, you need:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActions
1Log in to ChatGPT account
2Enter the Codex page
3Connect to GitHub account
4Select the repository to process
5Create a cloud task
6Wait for Codex to run in the cloud
7View results and diff
8Create Pull Request after satisfaction
+
+

What is the difference between Codex Web and local Codex

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComparisonCodex WebCodex App / CLI / IDE
Running locationCloudLocal computer
Project sourceGitHub repositoryLocal folder or Git repository
Do you need the computer to be turned on all the timeNot necessarilyUsually required
Is it suitable for the PR processVery suitableYes, but more local
Is it suitable for beginners to practiceGeneralApp is more suitable
Whether to rely on GitHubUsually requiredNot necessarily
Suitable for tasksRepository tasks, PR, team collaborationLocal development, rapid modification, debugging
+

Simple understanding:

+
本地 Codex = 在你电脑上干活
+Codex Web = 在云端帮 GitHub 仓库干活
+
+
+

The process of using Codex Web for the first time

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsOperationsIn simple terms
1Open Codex WebEnter the web version of Codex
2Log in to ChatGPTConfirm your account
3Connect to GitHubAllow Codex to access your code repository
4Select repositorySelect an item to process
5Select branchSelect which version to start from
6Enter the taskTell Codex what to do
7Waiting to runCodex processed in the cloud
8View resultsSee which files have been changed
9Review diffCheck for new and deleted content
10Create PRSubmit to yourself or the team after you are satisfied review
+
+

What does it mean to connect to GitHub?

+

Connecting to GitHub means:

+

Allow Codex Web to have access to your specified GitHub repository.

+

It needs to read the repository code to complete the task.

+

For example, if you ask Codex Web to do:

+
请帮我修复首页按钮点击无反应的问题。
+
+

It needs to read your project code first, then determine where the button logic is, and then modify the relevant files.

+

In simple terms:

+
GitHub = 放代码的云盘
+Codex Web = 进入这个代码云盘帮你改项目
+
+

Note:

+
不要随便授权不信任的账号或组织。
+不要一上来让 Codex 访问所有仓库。
+能只授权某几个仓库，就只授权需要的仓库。
+
+
+

Repository What is the repository?

+

Repository is referred to as repo, which can be understood as:

+

A complete code project.

+

For example:

+
my-landing-page
+ai-tools-site
+xiaohongshu-cover-generator
+my-react-app
+
+

These can be repositories on GitHub.

+

Codex Web typically creates tasks around a repository.

+

In simple terms:

+
仓库 = 一个放在 GitHub 上的项目文件夹
+
+
+

What is Branch?

+

Branch can be understood as:

+

A standalone version of the code.

+

For example:

+
main = 正式版本
+feature/homepage = 首页修改版本
+fix/button-bug = 修复按钮 bug 的版本
+
+

Codex Web usually does not directly modify the official branch, but does tasks based on a certain branch, and finally generates checkable modifications.

+

In simple terms:

+
main = 原稿
+新分支 = 复制一份出来修改
+PR = 把修改后的版本提交给你检查
+
+
+

What is Pull Request?

+

Pull Request, referred to as PR.

+

Xiaobai can understand it as:

+

Codex After modifying the code, instead of directly integrating the code into the formal project, a "modification application" must be submitted first.

+

You can see in the PR:

+
改了哪些文件
+新增了哪些代码
+删除了哪些代码
+有没有测试通过
+Codex 的总结说明
+是否可以合并
+
+
+

The benefits of PR are:

+
+
先检查，再合并。
+
+

So Codex Web is very suitable for real projects and team projects.

+
+

How to create a task in Codex Web

+

When creating a task, it is best to write clearly:

+
目标：让 Codex 做什么
+范围：只改哪些地方
+限制：哪些地方不能动
+验证：完成后怎么检查
+
+

Example:

+
请修复首页按钮点击无反应的问题。
+
+要求：
+1. 先分析按钮点击逻辑在哪里
+2. 只修改和按钮相关的文件
+3. 不要重构整个项目
+4. 不要删除现有功能
+5. 修复后运行构建或测试命令验证
+6. 完成后说明修改了哪些文件
+
+

It is not recommended to write:

+
帮我优化一下项目。
+
+

The Codex is too vague, and it is easy to not know where to start.

+
+

Codex Web How to run the project

+

Codex Web will create a runtime environment in the cloud.

+

It will usually:

+
1. 拉取 GitHub 仓库代码
+2. 切到指定分支或提交
+3. 执行 setup script 安装依赖
+4. 根据你的任务读取文件
+5. 修改代码
+6. 运行测试或构建命令
+7. 生成 diff 和总结
+
+

If the project needs to install dependencies, the setup script must be configured.

+

For example, front-end projects may require:

+
npm install
+
+

Or:

+
pnpm install
+
+

If the environment is not configured correctly, Codex may fail due to missing dependencies.

+
+

Environment What is the environment?

+

Environment can be understood as:

+

Computer configuration for Codex Web to run projects in the cloud.

+

It needs to know:

+
用什么语言
+怎么安装依赖
+怎么启动项目
+怎么运行测试
+需要哪些环境变量
+是否需要特殊工具
+
+

For example, a front-end project may require:

+
Node.js
+npm / pnpm
+package.json
+npm run build
+
+

A Python project may require:

+
Python
+pip
+requirements.txt
+pytest
+
+

In simple terms:

+
Environment = Codex 在云端跑项目时需要的工具箱。
+
+
+

What is Setup Script?

+

Setup Script can be understood as:

+

Codex Web is an installation command that is executed first every time when preparing a cloud environment.

+

For example:

+
npm install
+
+

or:

+
pip install -r requirements.txt
+
+
+

Its function is:

+
+
把项目需要的依赖先装好。
+
+

If the setup script is written incorrectly, Codex may not be able to run the project.

+
+

Xiaobai’s suggestion:

+
+
先用最简单的安装命令。
+不要在 setup script 里写危险命令。
+不要把密码和 API key 写进去。
+
+
+

Network access to Codex Web

+

Codex Web's cloud environment does not mean completely free networking.

+

Typically:

+
安装依赖阶段可能允许联网
+真正执行 agent 任务阶段可能默认限制联网
+
+

In simple terms:

+
安装依赖可以联网，干活时不一定能随便联网。
+
+

This is done for security and to avoid random access to external networks during the mission.

+

If your task must be connected to the Internet, it depends on whether the workspace and environment settings allow it.

+
+

What should you pay attention to about the permissions of Codex Web?

+

Codex Web mainly involves these permissions:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PermissionsNotes
GitHub repository permissionsWhich repositories it can read
Branch permissionsCan it create branches
PR permissionsCan it create a Pull Request
Cloud permissionsWhether the workspace is allowed to use Codex Cloud
Environment variablesDo not disclose API key, token, password
External networkWhether to allow cloud tasks to network
+

Safety advice for newbies:

+
只授权需要的仓库。
+不要授权全部仓库。
+不要把 .env、API key、密码、token 写进任务。
+不要让 Codex 自动合并 PR。
+先 review，再合并。
+
+
+

What is Codex Web suitable for?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioExample
Fix bugs in GitHub repositoryFix buttons, fix build failures, fix test failures
Make small functionsAdd a page, add a form
Write documentationREADME, usage instructions, deployment instructions
Code reviewCheck current PR or diff
Fix CI errorFix the problem according to the build log
Multi-task background processingLet Codex run in the cloud without occupying the local computer
Team collaborationLet the team review through PR
+

Especially suitable for:

+
GitHub 项目
+团队项目
+需要 PR 流程的项目
+不想本地一直开着电脑的任务
+
+
+

What Codex Web is not suitable for

+

Newbies are not recommended to use Codex Web at the beginning:

+
没有 GitHub 的本地小练习
+完全不会 Git 的项目
+真实生产环境部署
+数据库迁移
+支付系统修改
+自动合并 PR
+删除大量文件
+处理敏感密钥
+
+

It’s not that these cannot be done, but the risks are higher.

+
+

Xiaobai’s suggestion:

+
+
先用 Codex App 做本地练习。
+会 GitHub 后，再用 Codex Web 处理仓库任务。
+
+
+

Are Codex Web and Codex Cloud the same thing?

+

can be understood like this:

+
Codex Web = 你在网页上操作的界面
+Codex Cloud = 背后帮你跑任务的云端能力
+
+

That is to say:

+
你在 Codex Web 上输入任务，
+Codex Cloud 在云端环境里帮你执行。
+
+

Novices don’t have to worry about these two words.

+

Daily understanding is:

+
Codex Web = 网页入口
+Cloud task = 云端任务
+
+
+

First Codex Web Mission Suggestion

+

Novices should not choose complex projects for the first time.

+

It is recommended to choose a simple GitHub repository, such as:

+
简单 HTML 页面
+React 小项目
+个人主页
+README 项目
+小工具页面
+
+

The task can be written:

+
请帮我检查这个项目的 README 是否清楚。
+
+要求：
+1. 阅读当前项目结构
+2. 说明 README 缺少哪些内容
+3. 补充安装步骤、启动命令和项目结构说明
+4. 不要修改代码逻辑
+5. 完成后创建一个 PR
+
+

This task is low risk and suitable for those familiar with Codex Web processes.

+
+

Frequently Asked Questions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemPossible CauseSolution
Repository not foundGitHub does not have authorization, or does not give permission to the repositoryRecheck GitHub authorization
Codex cannot create PRNo branch or PR permissionsCheck GitHub permissions
Task operation failedsetup script error or dependency installation failureCheck environment configuration
Codex does not know how to start the projectREADME or package.json is not clearSupplementary project description
Failed to run the testThe project itself has bugs or incomplete dependenciesLet Codex analyze the cause of the failure first
The credit is consumed quicklyThe task is large, the model is strong, and it is run repeatedlyReduce the scope of the task and let it be planned first
Too many changesThe task is too vagueClearly limit which files can only be changed
Unsatisfactory resultsUnclear requirements or failed environmentAdd comments to let Codex modify
+
+

Safety rules for newbies

+
1. 不要一上来授权所有 GitHub 仓库。
+2. 不要让 Codex 自动合并 PR。
+3. 不要把 API key、密码、token 写进任务。
+4. 不要把 .env 文件提交到仓库。
+5. 复杂任务先让 Codex 给计划。
+6. PR 里一定要看 diff。
+7. 看不懂的改动不要合并。
+8. 生产项目不要直接让 Codex 自动部署。
+9. 先用简单仓库练习。
+10. 满意后再 merge。
+
+
+
+

Part 3: Detailed explanation of core functions

+
+

Automation

+

What is automation

+

**Codex Automation = Let Codex not only "listen to your instructions", but also help you regularly inspect the project, discover problems, and solve problems according to the rules. **

+
+

It’s like you hired an “AI duty engineer” for the project:

+
+

Usually it doesn’t bother you, +It will remind you if there is a problem. +For simple problems, try to fix them first. +Finally let you review the decision.

+
+

How to use automation

+

You can use "weekly Codex session automatic review" as an example to make Codex more and more useful.

+

You can let Codex regularly check the recent session records, task results and common problems, and compile them into a reusable workflow file.

+

Example prompt words can be written like this:

+
请检索并复盘最近一周的 Codex 会话记录与执行日志，维护一份“Codex 会话复盘与个人风格档案”。
+
+要求：
+1. 优先使用可用的会话历史检索能力；如果需要读取日志，只做搜索、元数据提取和相关片段抽取，不要整文件载入大型 session 文件。
+2. 不要复现原始日志、隐私内容、密钥、内部 reasoning 或长对话原文。
+3. 总结执行经验：哪些做法导致了问题，最终正确做法是什么，适合什么场景复用。
+4. 总结我的偏好：UI 设计偏好、产品理念、交互原则、内容系统偏好和工作流偏好。
+5. 整理可复用规则清单：把复盘结论改写成后续 Codex 会话可以遵循的简洁规则。
+6. 更新文档时去重、合并相近规则，保留日期范围或任务类型作为来源线索。
+7. 如有适合长期复用的规则，请建议是否加入项目级或用户级 AGENTS.md。
+
+

+ Codex平台的自动化页面 +

+ +

+ Codex桌面端界面，左侧为功能导航栏，其中“自动化”选项被选中 +

+ +
+

Plugin

+
+

Additional "capability package" installed for Codex

+

What is a plugin?

+

Codex itself can already read code, change code, and run commands; plugins are based on this, allowing it to connect to more tools, use fixed processes, or obtain certain special capabilities.

+

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Plugin typeWhat can Codex do
Chrome pluginOpen web pages, check pages, and cooperate with browser debugging
Gmail pluginSummarize emails, draft replies
Google Drive pluginRead documents, tables, slides
Slack pluginSummarize channel messages and draft team responses
Security pluginCheck code security issues
Computer Use pluginOperate applications on the computer
+

The relationship between plugin, Skill and MCP (look at this table first)

+

Plugins, Skills, and MCP are the three most confusing concepts in this article. They are not substitutes for each other, but each has its own layer. Please remember the following general list first, and the comparison will not be repeated in subsequent sections.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComparisonPluginSkillMCP
One sentenceCapability installation packageA set of fixed working methodsInterface to connect external tools
What problem to solveInstallation, packaging, distribution capabilities"How to do" similar tasks"What tools or data to connect to"
ScopeLargest, can package Skill, MCP, etc.Smaller, process for a single type of taskConnection to a single external tool or data source
AnalogyToolboxInstructions in the toolboxSocket for powering the toolbox
Who will use itOrdinary users can also install it with one clickOrdinary users can also use itMore for developers and team configuration
ExamplesGitHub plugin, Figma pluginREADME Skill, Code Review SkillDatabase MCP, Documentation MCP
+

One sentence to remember: **Plugins can package Skill and MCP into capability packages that are easier to install; Skill manages "how to do it", and MCP manages "what tools to connect". **

+

How to install plugins in Codex App

+
Open Codex App
+

+ Codex App中插件页面 +

+ +
Search or browse plugins
+

You can also search for the corresponding plugin

+

+ Codex App中插件页面 +

+ +
Click to open the plugin details
+

+ Codex App中GitHub插件的详情页面 +

+ +
Click Add to Codex or Add button
+

+ 在Codex App中插件详情页面的界面 +

+ +
After the installation is completed, open a new thread for use
+

+ Codex App中“hello - Codex”项目页面 +

+ +

How to install plugins in Codex CLI

+

After entering the project directory, start Codex first:

+
codex
+
+

Then enter in Codex CLI:

+
/plugins
+
+

After opening the plugin list, you can:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationDescription
Search pluginsFind the plugins you need
View detailsSee what the plugin can do and what permissions are required
Install pluginInstall plugin
Uninstall pluginUninstall plugin
SpaceEnable or disable installed plugins
+

Common plugins and capability directions

+
+

The plugin directory will change with the Codex version, workspace and account permissions. The following is not a fixed ranking, but a common capability direction. The actual installable content is subject to what is displayed on your current Codex plugin page.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeContains pluginsWhat to do
Browser and computer operationChrome, Computer UseWeb page testing, automatic clicks, software operation
Code and project collaborationGitHubManage repository, fix bugs, create PR
Front-end and designBuild Web Apps, FigmaGenerate web pages, convert design drafts to code
Office DeliveryDocuments, Presentations, SpreadsheetsDocuments, PPT, spreadsheet analysis
Video generationHyperFrames, RemotionGenerate videos with code or HTML
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Serial numberPlugin/CapabilityMain functionIn simple terms
1ChromeLet Codex directly operate the browserYou can open web pages, click buttons, check page effects, and test web page functions
2GitHubCode repository management and collaborationLet Codex read the repository, handle issues, change code, and create PR
3Computer UseLet Codex operate the computerLook at the screen, click buttons, and operate software like a human, with relatively high permissions
4Build Web AppsGenerate front-end web applications in one sentenceEnter requirements and generate web pages, gadgets, landing pages, and demos
5FigmaDesign draft to code and prototype designTurn Figma design draft into front-end page, suitable for UI development
6DocumentsAI helps you deliver formal documentsGenerate README, project descriptions, tutorial documents, product documents
7PresentationsAI generates high-quality PPTGenerate reports, courses, product introductions, and solution-based PPT based on content
8SpreadsheetsAI data analysis and table processingHelp you organize Excel, analyze data, and generate table conclusions
9HyperFramesHTML directly generates videoUse web page/HTML structure to generate video content
10RemotionUse code to generate high-quality videosUse React/code to generate more professional videos
+

Skill

+

A set of "fixed working methods" prepared for Codex.

+

Codex itself can read code, change code, and run commands.

+

But if you often ask it to do the same type of tasks, such as writing README, doing code review, generating web pages, and organizing documents, you can make this process into a Skill.

+

What is Skill

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptIn simple terms
SkillA set of fixed working methods
PromptPrompt word for this mission
WorkflowWork process
TemplateFixed template
InstructionLong-term rules for Codex
ResourceReference materials included with the Skill
ScriptOptional automation script in Skill
+

For example, if you want Codex to write a README every time, the README must contain:

+
项目介绍
+安装步骤
+启动命令
+文件结构
+常见问题
+
+

Then you can make a README Skill.

+

In the future, you don’t need to reinterpret the rules every time. As long as you call this Skill, the Codex will be written according to this set of procedures.

+
+

Skill or MCP? When to use which

+

For the overall difference between plugins, Skills, and MCPs, see the previous summary table of "Relationships between plugins, Skills, and MCPs." Here we only solve the most common dilemma: whether to use Skill or MCP for a requirement.

+

Remember one sentence: **For questions about "how to do it" use Skill, and for questions about "what tool to connect" use MCP. **

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Your needsUse Skill or MCP
Write README, fixed document output formatSkill
Code Review, UI ReviewSkill
Generate landing page and standardize bug fixing processSkill
Check the latest development documents and new version APIMCP
Connect to databaseMCP
Read Figma design draftMCP
Read GitHub issue/PRMCP
Connect to Notion, internal knowledge base, internal company toolsMCP
+

What is the difference between Skill and ordinary prompt words?

+

Tasks that are only done once = write the prompt word directly Tasks that are often repeated = suitable for Skill

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Comparison dimensionsCommon prompt wordsSkill
UsageManual input each timeSave as fixed capability
StabilityEasy to miss requirementsMore stable
Suitable for scenariosTemporary tasksRepeating tasks
ReusabilityLowHigh
Content structureA prompt wordInstructions, templates, materials, scripts
Who is it suitable forEveryonePeople who often do the same tasks repeatedly
+

When is Skill suitable for use?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SituationIs it suitable to be a Skill
The same type of tasks are often repeatedSuitable
Write a bunch of rules every timeSuitable
Want to make Codex output more stableSuitable
Multiple people in the team need to use the same processSuitable
One-time small taskNot necessarily required
Temporarily change a sentence of copywritingNot required
Just asking for a conceptNo need
+
+

What does Skill usually contain?

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ContentFunction
instructionsTell Codex what to do
resourcesput reference materials, templates, standards
scriptsOptional scripts to automate tasks
examplesExample input and example output
checklistCheck list to prevent missing steps
+

Basic structure of Skill

+

A simple Skill can be written like this:

+
# Skill 名称
+
+## 适用场景
+这个 Skill 适合用来做什么。
+
+## 工作目标
+Codex 最终要交付什么结果。
+
+## 工作流程
+1. 先分析输入内容
+2. 再确认任务类型
+3. 然后按固定步骤处理
+4. 最后输出结果和检查清单
+
+## 输出格式
+规定 Codex 最后应该怎么输出。
+
+## 注意事项
+哪些事情不能做，哪些风险要提醒。
+
+

For example README Skill:

+
# README 生成 Skill
+
+## 适用场景
+用于根据当前项目生成 README 文档。
+
+## 工作目标
+输出一份结构清晰、适合新手阅读的 README。
+
+## 工作流程
+1. 阅读项目结构
+2. 查看 package.json 或主要入口文件
+3. 判断项目类型
+4. 生成项目介绍
+5. 补充安装步骤和启动命令
+6. 说明文件结构
+7. 输出常见问题
+
+## 输出格式
+使用 Markdown 格式。
+
+## 注意事项
+不要编造不存在的功能。
+不确定的地方要明确标注。
+
+

How to add Skill in Codex App

+

Adding Skill in Codex App can be divided into two situations:

+
1. 使用已有 Skill
+2. 创建自己的 Skill
+
+
Use existing Skill
+

In the skills in the plugin, you can see some skills recommended by the system.

+

+ Codex App中技能相关界面 +

+ +
Create your own Skill
+

If you want to create a Skill yourself, you can use it in the thread of Codex App:

+
$skill-creator
+
+

It is equivalent to a Skill creation assistant, which will help you organize a set of repetitive processes into Skills.

+

Operation steps:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActions
1Open Codex App
2Select a project
3Create a new thread
4Enter $skill-creator
5Tell it what Skill you want to create
6Provide usage scenarios, rules, and sample output
7Let Codex generate Skill files
8Check the generated results
9Use this Skill in a new thread later
+

Example prompt words:

+
$skill-creator
+
+请帮我创建一个 README Skill。
+
+这个 Skill 的作用：
+根据当前项目自动生成适合小白阅读的 README。
+
+触发场景：
+当我说“生成 README”“写项目说明”“整理项目文档”时使用。
+
+工作流程：
+1. 先阅读项目结构
+2. 查看 package.json、README、入口文件
+3. 判断项目类型
+4. 生成项目简介
+5. 写安装步骤
+6. 写启动命令
+7. 说明主要文件夹作用
+8. 补充常见问题
+9. 不确定的地方不要编造
+
+输出格式：
+使用 Markdown。
+
+必须包含：
+- 项目简介
+- 功能特点
+- 安装步骤
+- 启动命令
+- 文件结构
+- 常见问题
+- 后续优化方向
+
+
Recommended Skill to install
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Skill/ProjectMain functionGitHub address
SuperpowersAdd a complete set of "software development methodology" to Coding Agent: first clarify requirements, write specifications, make implementation plans, and then promote development according to TDD/task splitting. Suitable for engineering agents such as Codex, Claude Code, Cursor, Gemini CLI, etc.https://github.com/obra/superpowers
skill-creatorAuxiliary Skill to create Skill. The built-in or available Skills in Codex are subject to your current environment; Skills with the same name from different sources may be implemented differently.Based on the current Codex Skill list
baoyu-skillsA set of practical Skills compiled by Baoyu, focusing on content creation and daily efficiency: Xiaohongshu pictures and texts, article illustrations, comics, public account publishing, X/Weibo publishing, webpage conversion to Markdown, YouTube subtitles, AI generated pictures, etc. The description of the repository is to improve the effectiveness of AI Agents such as Claude Code and Codex, and it is recommended to install them on demand.https://github.com/JimLiu/baoyu-skills
Agent ReachEquip Agent with "networking capabilities": read web pages, YouTube, RSS, GitHub, Twitter/X, Bilibili, Reddit, Xiaohongshu, LinkedIn, etc. It also comes with diagnostics and multi-backend routing. Simply put, it allows the local Agent to search the Internet and read platform content more conveniently.https://github.com/Panniantong/Agent-Reach
find-skills"Find the Skill of Skill". When you ask "Is there a Skill with such and such function?", it will help you search, discover, and install Agent Skills; the bottom layer is used with npx skills find / add / check / update.https://github.com/vercel-labs/skills/tree/main/skills/find-skills
+

How to add Skill in Codex CLI

+

There are three main ways to add Skills in Codex CLI:

+
1. 使用已有 Skill
+2. 用 $skill-creator 创建 Skill
+3. 手动创建 SKILL.md 文件
+
+
3 ways to add Skills
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodWho is suitable forIn simple termsRecommendation level
Use existing SkillsNew usersDirectly call ready-made skillsRecommended
$skill-creator createdPeople who want to turn prompt words into SkillsLet Codex help you organize SkillsMost recommended
Manually create SKILL.mdPeople familiar with file structureWrite Skill files by yourselfAdvanced
+
+
Method 1: Use existing Skill
+

After entering the project directory, first start the Codex CLI:

+
cd 项目目录
+codex
+
+

After entering the Codex CLI, you can enter:

+
/skills
+
+

Or enter directly:

+
$
+
+

The Codex will display the currently available Skills.

+

If you already know the Skill name, you can also name it directly in the task:

+
请使用 $readme-skill，根据当前项目生成 README。
+
+

or:

+
$ui-review-skill 请检查当前首页的视觉问题，并给出修改建议。
+
+
+
How to use existing Skills
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
UsageExamplesSuitable scenarios
/skillsOpen the Skill listWhen you don’t know which Skills there are
Enter $Quickly select SkillWhen you want to call it quickly
$skill-name$readme-skillWhen the Skill name is known
Natural language descriptionPlease use README Skill to write a project descriptionWhen you are not sure of the specific name
+
+
Method 2: Create Skill with $skill-creator
+

If you want to save a set of repeated processes as a Skill, you can use:

+
$skill-creator
+
+

It is equivalent to a Skill creation assistant and will ask you:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
QuestionPurpose
What does this Skill doClarify the purpose
When to triggerWrite down applicable scenarios
Whether to include scriptsDetermine whether it is only a command-type Skill
What is the output formatEnsure stable results
What are the restrictionsAvoid random modification, random compilation, and random execution
+
+
$skill-creator Usage process
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActionsPurpose
1Enter the project directoryMake sure the Skill is generated in the correct project
2Run codexOpen Codex CLI
3Enter $skill-creatorStart Skill Creation Assistant
4Describe the Skill purposeTell it what to do
5Supplementary trigger scenariosTell it when to use
6Supplementary workflowFixed Codex execution steps
7Supplementary output formatEnsure stable results
8Check the generated resultsConfirm whether SKILL.md is reasonable
9Reopen or continue to useTest whether the Skill is effective
+
+
$skill-creator Example prompt word
+
$skill-creator
+
+请帮我创建一个 README Skill。
+
+这个 Skill 的作用：
+根据当前项目自动生成一份适合小白阅读的 README。
+
+触发场景：
+当我说“生成 README”“写项目说明”“整理项目文档”“写安装教程”时使用。
+
+工作流程：
+1. 先阅读项目结构
+2. 查看 package.json、README、入口文件
+3. 判断项目类型
+4. 生成项目简介
+5. 写安装步骤
+6. 写启动命令
+7. 说明主要文件夹作用
+8. 补充常见问题
+9. 不确定的地方不要编造
+
+输出格式：
+使用 Markdown。
+
+必须包含：
+- 项目简介
+- 功能特点
+- 安装步骤
+- 启动命令
+- 文件结构
+- 常见问题
+- 后续优化方向
+
+注意事项：
+不要编造不存在的功能。
+不要读取或输出 API key、密码、token、私钥。
+
+
+
Method 3: Manually create Skill files
+

Skill is essentially a folder, which must contain one of:

+
SKILL.md
+
+

The simplest structure is:

+
.agents
+└── skills
+    └── readme-skill
+        └── SKILL.md
+
+

You can also put scripts, reference materials and resource files:

+
.agents
+└── skills
+    └── readme-skill
+        ├── SKILL.md
+        ├── scripts
+        ├── references
+        └── assets
+
+
+
Skill file structure description
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
File/FolderIs it necessaryFunction
SKILL.mdRequiredWrite the name, description and specific instructions of the Skill
scripts/OptionalPut executable scripts
references/OptionalPut reference documents, standards, instructions
assets/OptionalPut templates, pictures, resource files
+
+
The simplest SKILL.md example
+
---
+name: readme-skill
+description: 当用户需要生成 README、项目说明、安装教程、启动步骤时使用。
+---
+
+你是一个 README 文档生成助手。
+
+任务：
+根据当前项目生成一份适合新手阅读的 README。
+
+工作流程：
+1. 阅读项目结构
+2. 查看 package.json、README、入口文件
+3. 判断项目类型
+4. 生成项目介绍
+5. 写安装步骤
+6. 写启动命令
+7. 说明文件结构
+8. 补充常见问题
+9. 不确定的地方不要编造
+
+输出格式：
+使用 Markdown。
+
+必须包含：
+- 项目简介
+- 功能特点
+- 安装步骤
+- 启动命令
+- 文件结构
+- 常见问题
+- 后续优化方向
+
+

How to use Skill after adding it

+

After adding Skill, there are two common usages:

+ + + + + + + + + + + + + + + + + +
UsageExample
Explicitly specify SkillPlease use $readme-skill to generate README
Let Codex automatically determineHelp me write a project README
+

If the Skill description is written clearly, it will be easier for Codex to automatically determine when to use it.

+

For example:

+
description: 当用户需要生成 README、项目说明、安装教程、启动步骤时使用。
+
+

This description is very clear.

+

It is not recommended to write too vaguely:

+
description: 帮我写东西。
+
+

This way Codex doesn't know when to call it.

+

Where is the skill more suitable?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlacementSuitable for the sceneIn simple terms
.agents/skills in the projectOnly for the current projectProject-specific Skills
User-level Skill directoryWant to use it for multiple projectsPersonal general Skill
Team/Administrator configurationUniform use by team membersTeam sharing Skill
In the pluginWant to package and distribute to others for installationFormal capability package
+

MCP

+

Only advanced AI programming needs to be understood, ordinary people can skip it directly

+

Allows Codex to connect to the interface of external tools.

+

Codex itself can read code, change code, and run commands.

+

The role of MCP is to allow Codex to connect to more external tools, data sources or services.

+

What is MCP

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptIn simple terms
MCPStandard interface for connecting external tools
MCP ServerServices that provide tool capabilities
ToolSpecific functions that can be called by Codex
ConfigMCP configuration file
STDIO ServerMCP service started by local command
HTTP ServerMCP service connected via URL
ContextContextual information provided to Codex by external tools
+

Daily understanding:

+
Codex = 一个会干活的人
+MCP = 给他接上不同工具的插座
+MCP Server = 插在插座上的工具箱
+Tool = 工具箱里的具体工具
+
+

For example, a document MCP allows Codex to read the document.

+

A database MCP that allows Codex to query the database.

+

A design tool MCP that allows Codex to obtain design draft information.

+
+

What is MCP suitable for?

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioHow to use MCP
Check development documentationConnect the documentation MCP and let Codex check the new version API
Connect to the databaseLet Codex query the database structure or test data
Connect design toolsLet Codex read design drafts and component information
Connect to project management toolsRead issues, tasks, and requirements descriptions
Connect to internal systemsCall the company's internal tools or data sources
Connect to the knowledge baseMake Codex work based on team documentation
Connect to automation toolsLet Codex call additional scripts or services
+
+

Xiaobai can judge this way:

+
+
普通写代码，不一定需要 MCP。
+需要 Codex 访问外部工具或外部数据时，才考虑 MCP。
+
+

What is MCP Server?

+
+

MCP Server can be understood as:

+
+

Provide tool capabilities to Codex.

+

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MCP Server typeWhat can be provided
Document MCPQuery development documents, API documents
Database MCPQuery table structure, read test data
GitHub MCPRead issue, PR, repository information
Figma MCPRead design draft information
Notion MCPRead knowledge base page
Browser MCPAccess web pages and obtain page information
Internal tool MCPConnect to company's own systems
+

In simple terms:

+
MCP Server = Codex 可以调用的外部工具服务。
+
+

How to use MCP in Codex App

+
Basic process of using Codex App MCP
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsOperationsIn simple terms
1Open Codex AppEnter the desktop version of Codex
2Enter SettingsOpen Settings
3Find MCP serversEnter the MCP tool management area
4View recommended serversView official or system recommended MCP
5Add custom serverAdd your own MCP server
6Follow the prompts to complete the authorizationSome MCPs need to log in to an external account
7Return to project threadCall MCP in task
8View results and permission requestsConfirm what tools were called by Codex
+

+ Codex App中MCP Server的设置界面 +

+ +
What usually needs to be filled in when adding MCP
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Configuration itemsFunctionIn simple terms
NameMCP nameName this tool
Command / URLLaunch command or service addressCodex through which to connect tools
TypeMCP typeLocal command type or remote HTTP type
EnvEnvironment variablesPut tokens, configuration items, etc.
AuthAuthorization methodDo you need to log in to an external account
Enabled toolsWhich tools are enabledOnly the functions you need are enabled
+

+ Codex App中添加MCP时的设置界面 +

+ +
How to use MCP after adding it
+

After the addition is completed, return to the thread of Codex App and describe the task directly.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
UsageExample
Directly describe the requirementsPlease check the latest usage of Next.js App Router
Explicitly request the use of MCPPlease query the documentation for this library using the available MCP tools
Specify an MCPPlease use context7 to query the latest documentation of Next.js
Check available tools firstWhat MCP tools are currently available?
+

Example prompt words:

+
请使用可用的 MCP 文档工具，
+查询 Next.js App Router 的最新用法，
+然后告诉我当前项目应该怎么修改。
+
+

Or:

+
请用 Figma MCP 读取这个设计稿，
+分析页面结构，并给我生成前端实现计划。
+
+

How to use MCP in Codex CLI

+

Using MCP in Codex CLI can be understood as:

+

Connect external tools to the terminal version of Codex.

+

For example:

+
文档 MCP：让 Codex 查询开发文档
+GitHub MCP：让 Codex 读取 issue、PR、仓库信息
+Figma MCP：让 Codex 读取设计稿
+数据库 MCP：让 Codex 查询数据库结构
+
+
+

Xiaobai can understand it this way:

+
+
Codex CLI = 终端里的 AI 编程助手
+MCP = 给 Codex CLI 接外部工具的接口
+
+
+
Basic process of using MCP with CLI
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsOperationsIn simple terms
1Open TerminalPowerShell / Terminal
2Enter the project directoryLet Codex know the current project
3Add MCP serverConnect external tools to Codex
4Check whether the MCP is added successfullyConfirm that the tool is available
5Start Codex CLIEnter the Codex dialog interface
6Use /mcp to view toolsSee which MCPs are currently available
7Call MCP in a taskLet Codex use external tools
8View results and permission promptsConfirm whether it is safe
+
+
Commonly used MCP terminal commands
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFunctionIn simple terms
codex mcp --helpView MCP command helpRead first if you don’t know how to use it
codex mcp listView the configured MCP serverSee which external tools are connected now
codex mcp addAdd MCP serverAdd an external tool to Codex
codex mcp removeDelete MCP serverRemove if no longer needed
codex mcp getView details of an MCP serverSee specific configuration
codex mcp loginLog in to an MCP that requires authorizationAuthorize some remote MCPs
codex mcp logoutExit an MCP authorizationCancel the connection status
/mcpView the MCP in the Codex sessionSee which tools can be called in the current session
+
+
Add the basic format of MCP
+

The basic command to add an MCP is usually:

+
codex mcp add 名称 -- 启动命令
+
+

In simple terms:

+
名称 = 你给这个 MCP 起的名字
+启动命令 = 这个 MCP 怎么启动
+
+

Example:

+
codex mcp add context7 -- npx -y @upstash/context7-mcp
+
+

This command can be understood as:

+
给 Codex 添加一个叫 context7 的 MCP。
+它通过 npx 启动 @upstash/context7-mcp 这个工具。
+
+
+
+
View the added MCP
+
+

You can run it after adding:

+
codex mcp list
+
+

Function:

+
查看当前 Codex CLI 已经配置了哪些 MCP server。
+
+

If you can see the name you just added, it means that the configuration has been written.

+
+
View MCP after entering Codex
+

First enter the project directory:

+
cd 项目目录
+
+

Then start Codex:

+
codex
+
+

After entering the Codex CLI, enter:

+
/mcp
+
+

Function:

+
查看当前会话里可用的 MCP 工具。
+
+

If the MCP is not displayed, it may be:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemPossible Causes
Failed to add successfullycodex mcp add command failed
MCP startup failedDependencies not installed or command error
Wrong nameWrong server name when calling
Authorization requiredNot logged in to external service yet
Configuration is not refreshedNeed to restart Codex CLI
+
+
Call MCP in task
+

After configuring MCP, it is not necessary to memorize complex commands.

+

You can say directly in the Codex CLI:

+
请使用可用的 MCP 工具，查询 Next.js App Router 的最新文档。
+
+

You can also specify an MCP:

+
请用 context7 查询 Next.js App Router 的最新用法，
+然后告诉我当前项目应该怎么修改。
+
+

If it is a Figma-like MCP, you can say this:

+
请用 Figma MCP 读取这个设计稿，
+分析页面结构，并给我生成前端实现计划。
+
+

If it is a GitHub-like MCP, you can say this:

+
请用 GitHub MCP 查看这个仓库最近的 open issue，
+帮我整理出优先级最高的 3 个问题。
+
+
+
Where is the MCP configuration file?
+

Codex's MCP configuration will be written into the configuration file.

+

Common locations are:

+
~/.codex/config.toml
+
+

In simple terms:

+
config.toml = Codex 的配置文件
+
+

There may be configuration similar to this:

+
[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+
+

This means:

+
有一个 MCP server 叫 context7。
+启动命令是 npx -y @upstash/context7-mcp。
+
+

If you are not familiar with the configuration file, do not change it manually in the early stage.

+

Priority:

+
codex mcp add
+codex mcp list
+codex mcp remove
+
+
+
Add remote MCP
+

Some MCPs are not started by local commands, but connected through a URL.

+

This type is generally called remote MCP / HTTP MCP.

+

May require:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Configuration itemsIn simple terms
URLRemote MCP service address
AuthDo you need to log in
TokenAccess Credentials
OAuthBrowser authorization login
+

If you need to log in, you can use:

+
codex mcp login MCP名称
+
+

No need:

+
codex mcp logout MCP名称
+
+
+

Newbie suggestions:

+
+
先用不需要复杂授权的文档类 MCP。
+后面再尝试需要登录的远程 MCP。
+
+
+
Delete unused MCP
+

If an MCP is no longer used, it can be deleted:

+
codex mcp remove 名称
+
+

For example:

+
codex mcp remove context7
+
+

Delete and check again:

+
codex mcp list
+
+

Make sure it is no longer in the list.

+

Code management (Git and GitHub workflow)

+

When using Codex to do real projects, you must know a little bit about Git and GitHub.

+
+

Newbies can first understand it like this:

+
+
Git = 本地代码版本管理工具
+GitHub = 把代码放到网上协作的平台
+Codex = 帮你读代码、改代码、跑命令的 AI 编程助手
+
+

In one sentence:

+
Git 负责记录代码变化。
+GitHub 负责远程保存和协作。
+Codex 负责帮你完成具体编程任务。
+
+

What is the difference between Git and GitHub

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComparisonGitGitHub
In simple termsLocal version management toolCode cloud disk + collaboration platform
Main functionsRecord what has been changed every time the code is changedRemotely save code and team collaboration
LocationYour computerBrowser / Cloud
Core capabilitiescommit, branch, diff, mergerepository, issue, pull request
Is it necessary to connect to the Internet?No needRequired
Relationship with CodexAfter changing the code in Codex, use Git to check and saveCodex Web/Cloud often cooperates with GitHub
+
Git concepts that beginners must understand first
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptIn simple termsFunction
RepositoryA code repositoryStore the entire project
CommitA code archiveRecord what was changed this time
BranchBranchChange the code without affecting the main line
DiffChange comparisonSee what is added, deleted, and modified
StageTemporary storage areaWhat changes are going to be saved into commit
MergeMergeMerge changes from one branch to another branch
ConflictConflictThe same code has been changed on both sides and needs to be selected manually
PushPushUpload local code to GitHub
PullPullSync new code on GitHub to local
CloneCloneDownload a project from GitHub to local
+
+
GitHub concepts that beginners must understand first
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptIn simple termsFunction
RepositoryProject repository on GitHubStore code
IssueProblem/Requirement RecordRecord bugs, requirements, tasks
Pull Request / PRCode Merger ApplicationApply for merging after changing the code
Main BranchMain branchStable version of the project
Feature BranchFunction branchUsed to develop new features
ReviewCode inspectionCheck code before merging
ActionsAutomated processAutomatic testing, building, deployment
READMEProject DescriptionTell others how to use the project
.gitignoreIgnore file listPrevent irrelevant or sensitive files from being uploaded
+
+

Why Git is more needed when using Codex

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioWhy Git is needed
Codex has changed a lot of codeYou can check the specific changes
Codex has been correctedYou can roll back to the previous version
Codex deleted content that should not be deletedYou can use Git to retrieve it
Let Codex be modified multiple timesSave one stage for each commit
Want Codex to boldly try solutionsUse branch or worktree to isolate risks
To put the project on GitHubNeed to push to the remote repository
Team collaborationPR, review, merge required
+

In one sentence:

+
没有 Git，Codex 改错了你很难回退。
+有了 Git，Codex 可以放心试，你可以随时检查和恢复。
+
+
+

How to use Git in Codex

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActionsPurpose
1Initialize GitLet the project start to be managed by Git
2Write .gitignorePrevent junk files and keys from being uploaded
3Commit onceSave the clean version
4Create a new branchGive Codex a safe experimental area
5Let Codex modify the codeComplete specific tasks
6View diffCheck what has been changed in Codex
7Run the project / BuildConfirm that there are no errors
8Commit when satisfiedSave this modification
9push to GitHubupload remote repository
10Create PRCheck again before merging
+
Enter in the Codex dialog box: Initialize the project into a Git project and exclude unnecessary files
+

+ 在Codex中使用Git的界面 +

+ +
+
Codex will help us write the .gitignore file directly
+

+ 在Codex中使用Git的界面 +

+ +

How to use GitHub in Codex

+
+
What to prepare before use
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Preparation itemsFunctionIn simple terms
GitHub accountSave remote codeCode cloud disk account
GitLocal version managementRecord code changes
GitHub repositoryPut project codeA remote project folder
Local projectCodex code to be modifiedProject folder on computer
GitHub login permissionsAllow push / PRProve this is your repository
.gitignorePrevent irrelevant files from being uploadedDo not upload junk files and keys
+
Standard upload process
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActionsPurpose
1Create a new repository on GitHubCreate a remote project space
2Copy the repository addressYou will need to connect the local project later
3Copy the address to CodexLet Codex know which repository to upload to
4Push to GitHubOfficially upload code
+
Create a GitHub repository
+

+ GitHub创建仓库页面 +

+ +
Copy repository address
+

+ 在GitHub上创建仓库时复制仓库地址的操作界面 +

+ +
Copy the address to Codex
+

+ Codex平台中“做一个首页”项目的页面 +

+ +
Push to GitHub
+

Code rollback

+
Modify code
+

Let AI modify the code first

+

+ Codex平台中“做一个首页”项目的界面 +

+ +
Submit to Git and save the current version
+

+ Codex平台中使用Git进行代码管理的操作界面 +

+ +
Continue to modify the code
+

+ 在Codex中使用Git的代码回滚操作界面 +

+ +
Open the IDE to view the code and roll back the code
+

First open the IDE to view the code

+

+ 在Codex中使用Git的界面 +

+ +
Copy version number
+

+ 在VS Code中使用Codex进行代码回滚的操作界面 +

+ +
Copy to Codex and let it roll back the code to the specified version
+

+ 在Codex中使用Git进行代码回滚的操作界面 +

+ +

Git Worktree

+

Create an additional independent working copy for the same Git project.

+

It is equivalent to a draft. It will be merged back into the official project after the effect is satisfactory.

+
Why Worktree is needed
+

Although ordinary Git branches can be switched, only one branch can be operated in one folder at a time.

+

The benefits of Worktree are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioThe role of Worktree
I want Codex to boldly change the codeOpen a separate copy for it
Do not want to affect the current projectThe main project remains unchanged
Want to do multiple tasks at the same timeOne worktree for each task
Want to compare multiple plansPlans A / B / C are available separately
Changed and don’t want itJust throw away the worktree
Make big changes/refactoringReduce the risk of polluting the main project
+
Create Worktree
+

+ Codex移动版界面中“hello - Codex”项目的操作菜单 +

+ +

+ Codex平台界面，左侧为项目列表，其中“hello - codex_2”项目被红色框突出显示 +

+ +
Use branches to perform tasks
+

+ Gitpod界面中“hello - codex_2”分支的代码编辑区域 +

+ +
Merge back to trunk
+

After the check result is satisfactory, you can merge it back to the trunk and delete this branch.

+

+ 在GitHub上使用Worktree进行代码管理的操作界面 +

+ +

Cloud operation

+

Codex's cloud tasks are suitable for you to continue processing work when it is inconvenient for you to keep your local computer on all the time; if your account and client support mobile portal, you can also view or advance some tasks when you are out.

+
把代码任务交给 Codex，让它在云端环境里自己跑。
+
+

Newbies can understand it this way:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ModeRunning PositionIn Simple Terms
LocalYour computer’s local projectCodex directly changes the code in your computer
WorktreeYour computer's local copyCodex Change code in a safe copy
CloudOpenAI cloud environmentCodex pulls the GitHub repository in the cloud and processes tasks
+

What is Codex cloud operation?

+

Codex runs in the cloud, essentially:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ContentDescription
Running environmentCloud container
Code sourceGitHub repository
How it worksCodex reads, modifies, runs, and verifies code in the cloud
Final resultGenerate modification results, diff, and create PR if necessary
Suitable for tasksFix bugs, change functions, write documents, code review, handle issues
Not suitable for the taskLocal private files, projects not uploaded to GitHub, high-risk production operations
+
+

The difference between cloud operation and local operation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComparisonLocal running Local / WorktreeCloud running Cloud
Code locationOn your computerGitHub repository
Running locationYour computerCloud container
Whether to occupy the computerYesBasically not occupied
Do you need GitHubNot necessarilyUsually required
Is it suitable for background tasksGeneralVery suitable
Is it suitable for parallel tasksGeneralVery suitable
Permission risksMainly local file permissionsMainly repository, environment variables, network permissions
Is it suitable for novicesMore suitable for learning firstLearn GitHub before using it
+

Cloud operation steps

+
Push the code to GitHub
+

+ 在GitHub上推送代码到仓库的操作界面 +

+ +
Open Codex Web
+

+ Codex操作界面，在界面某处的下拉菜单中，“打开Codex web”选项被红色框线突出显示 +

+ +

+ Codex云端界面 +

+ +
Select the repository we want to modify
+

After selecting, just let Codex do the work for us.

+

+ Codex云端运行操作步骤中选择我们要修改的仓库界面 +

+ +
Upload to GitHub repository after modification is completed
+

+ Codex云端运行操作步骤中修改完成后上传到GitHub仓库的界面 +

+ +

+ 一个GitHub仓库页面，显示了用户Vink567在“Polish landing page design #2”仓库的代码提交记录 +

+ +
Synchronize the latest code in the GitHub repository before making local modifications
+

If the cloud task has pushed the modification back to GitHub, the latest code must be synchronized before continuing local development to avoid conflicts caused by continued modification on the old version. Specifically, whether Codex automatically applies the changes for you, or you manually apply git pull / codex apply, depends on the current entry and task type.

+

+ Codex云端运行操作界面 +

+ +

Memory system

+

Let Codex remember some long-term useful information to facilitate future work.

+

Project-level AGENTS.md

+
写给 Codex 看的项目规则说明书。
+
+

Newbies can understand it this way:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
DocumentationMain ReaderRole
README.mdPeopleTell people what this project is, how to install it, and how to use it
AGENTS.mdCodex / AI AgentTell the AI how it should work in this project
.gitignoreGitTell Git which files not to upload
+
Where to put AGENTS.md
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlacementScopeIn simple terms
Project root directory AGENTS.mdEntire projectGeneral rules of the current project
AGENTS.md in the subdirectoryCurrent subdirectory and related tasksExclusive rules for a module
User level ~/.codex/AGENTS.mdAll your projectsPersonal general rules
Project-level AGENTS.md + User-level AGENTS.mdOverlay takes effectPersonal habits + current project rules
+
How to write AGENTS.md
+

You can directly hand it over to AI to write, and let AI summarize the core content of this project and create AGENTS.md

+
Front-end project AGENTS.md template
+
# AGENTS.md
+
+## 项目说明
+
+这是一个前端网页项目，用于构建产品页面、工具页面或个人作品展示页面。
+
+## 技术栈
+
+- React
+- Vite
+- Tailwind CSS
+- JavaScript / TypeScript
+
+## 常用命令
+
+- 安装依赖：`npm install`
+- 启动项目：`npm run dev`
+- 构建项目：`npm run build`
+
+## 项目结构
+
+- `src/`：主要源代码
+- `src/components/`：通用组件
+- `src/pages/`：页面文件
+- `src/assets/`：图片、图标等静态资源
+- `public/`：公开静态文件
+
+## 代码规范
+
+- 优先使用 React 函数组件
+- 优先使用 Tailwind CSS 写样式
+- 不要引入 Bootstrap
+- 不要大范围重构无关代码
+- 修改时保持文件结构清晰
+- 中文文案要自然、简洁、适合普通用户阅读
+
+## UI 规则
+
+- 页面要有清晰的信息层级
+- 按钮、卡片、标题、留白要统一
+- 移动端要基本可用
+- 不要过度渐变、阴影和 AI 模板感
+- 优先做真实产品感，而不是 Demo 感
+
+## 禁止事项
+
+- 不要修改 `.env`、`.env.local`
+- 不要输出 API key、token、密码
+- 不要删除已有核心功能
+- 不要随意新增大型依赖
+- 不要直接改动和当前任务无关的文件
+
+## 完成任务后
+
+每次修改完成后，请输出：
+
+1. 修改了哪些文件
+2. 每个文件改了什么
+3. 为什么这样改
+4. 是否需要运行 `npm run build`
+5. 提醒我检查 diff
+
+
What are the characteristics of a good AGENTS.md
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeaturesDescription
SpecificWrite clearly the technology stack, commands, and directories
Be conciseDon’t write long nonsense
ExecutableCodex shows how to do it
RestrictedSpecify which files cannot be touched
VerifiedWrite clearly what command to run to check
Have completion standardsLet Codex know what to deliver
MaintainableTimely updated after project changes
+

Global level AGENTS.md

+
Open Codex settings and find Personalization
+

+ Codex的个性化设置界面 +

+ +
Enter the command. The command here will affect subsequent Codex sessions as your personal general preference.
+

When using AI programming, you are most afraid of AI deleting things randomly. You can use the following command

+

Batch deletion of files or directories is prohibited.

+

Do not use:

+
    +
  • del /s
    • +
  • rd /s
    • +
  • rmdir /s
    • +
  • Remove-Item -Recurse
    • +
  • rm -rf
    • +
+

When you need to delete a file, you can only delete a file with a clear path at a time.

+

Correct example:

+
Remove-Item "C:\path\to\file.txt"
+
+

If you need to delete files in batches, you should stop the operation and request the user to delete them manually.

+

The best way to use Codex memory

+

+ Codex记忆的最佳使用方法封面图 +

+ +

The biggest problem that many people have with Codex is that they don’t know how to ask questions.

+

+ 很多人用Codex不是不会提问 +

+ +

Instead, it starts from scratch every time:

+

"How to run tests on my project" +"What output style do I like" +"What are the pitfalls of this repository?"

+
+

"Which step did this process last?" +"Where is this information?"

+
+

This is actually using the "memory system" as a chat record.

+

A better way is to put different types of information into different context layers and let Codex read the appropriate information at the appropriate time.

+

Let’s look at a general table first:

+

+ Codex记忆系统应该放在哪里的总结图 +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
What do you want Codex to rememberRecommended placeNot recommended placeReason
Temporary requirements for the current taskCurrent prompt / current sessionAGENTS.mdUse only once, do not pollute long-term rules
Personal preferences, common habitsMemories / Global AGENTS.mdRe-say every timeStable but not necessarily entered into the project repository
Repository rules, test commands, directory conventionsAGENTS.md of repoMemoriesThis is a hard rule and should be followed by the project
Reusable workflowSkillAGENTS.mdSkill can hold reference files, scripts, templates
Regular review, follow-up, monitoringAutomationsKeep in mindNeed to wake up according to time, not static rules
Real-time information in Slack / GitHub / DocsMCP / ConnectorManual copy and pasteExternal information will change and should be used immediately
+
Current session/prompt: most suitable for placing the requirements of "this mission"
+

The current session is the shortest term memory, which is only used for this task and will rarely be reused.

+

For example:

+

+ 当前会话适合放本次任务要求的示例图 +

+ +

"This time the background of the web page is changed to blue and white"

+
+

"Add a login button in the upper right corner of the web page" +"This solution only considers Windows" +"Don't submit a PR yet"

+
+

This type of information is only useful for the current task and should not be precipitated into long-term rules.

+

If you write temporary requirements into AGENTS.md, every time you open the project later, Codex may mistakenly think that this is a long-term rule, which will pollute the context.

+
Memories: suitable for "stable preferences" and "common backgrounds"
+

Memories are suitable for saving information that is often useful across sessions and projects.

+

Simply put, Memories are:

+
+

Codex's soft memory of your personal work habits.

+
+

For example:

+
    +
  • You prefer Chinese answers.
    • +
  • You want the explanation to be as simple as possible and not jargon-heavy.
    • +
  • When working on a project, you like to read the plan first, and then modify the code.
    • +
  • You commonly use Windows, PowerShell, some fixed directories or tool chains.
    • +
  • You often ask for modified clarification of diffs, verified commands, and unverified items.
    • +
+

Operation steps:

+

+ Codex设置里开启Memories的界面 +

+ +
    +
  1. Enable Memories in Codex settings.
    2. +
  2. Use several real tasks to let Codex form stable preferences.
    3. +
  3. You can view the corresponding memory file in the following directory:
    4. +
+
~/.codex/memories/
+
+

+ Codex memories目录文件示例 +

+ +

Common files and directories can be roughly understood as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameFunctionIn simple terms
MEMORY.mdCodex is the most important long-term memory file, usually containing stable preferences, common workflows, technology stacks, project habits, etc.Official memory book
memory_summary.mdCompress and summarize the memory content to allow Codex to read core information fasterMemory summary
raw_memories.mdMore raw memory entries, may contain uncompressed records extracted from historical threadsRaw logbook
rollout_summaries/Stores summaries of certain tasks, sessions or running processes to support subsequent memory generationPast task summary library
extensions/Memory directory for extended functionsExtension memory area
+

It is recommended to check Memories regularly:

+
    +
  • Have you recorded one-time temporary requests?
    • +
  • Have you recorded the private information, keys, and account information?
    • +
  • Have expired or wrong preferences been recorded?
    • +
  • Are there any important rules that only exist in Memories but are not synced to AGENTS.md or Skills?
    • +
+

One sentence summary:

+
+

Memories are memories that Codex uses to record your long-term preferences and common backgrounds.

+
+
AGENTS.md: Best for "project rules that must be followed"
+

AGENTS.md is the first layer I recommend for beginners.

+

It works much like a statement of work for the Codex. Codex will read AGENTS.md before starting work, and regard the rules in it as work constraints for the current project or current user.

+

It is worth noting that AGENTS.md can be divided into global level and project level.

+

The global AGENTS.md affects most of your projects and sessions in Codex and is suitable for personal long-term rules.

+

The file location is usually:

+
~/.codex/AGENTS.md
+
+

Operation steps:

+

+ Codex个性化设置写入全局AGENTS规则 +

+ +
    +
  1. Write the rules directly in the personalization area in the Codex settings.
    2. +
  2. Write only a few of the most important and stable rules.
    3. +
  3. Do not write in the temporary requirements of a certain task.
    4. +
+

For example:

+
+

"Use Markdown format for every text output." +"When you are unsure of your needs, point out the uncertain points first and then recommend a solution." +"Do not delete files, rename core directories, or extensively refactor."

+
+

Project-level AGENTS.md only affects the current project and is suitable for storing repository rules, test commands, directory conventions and delivery standards.

+

The file location is usually:

+
~/xxx项目/AGENTS.md
+
+

Operation steps:

+

+ 在项目根目录创建AGENTS文件 +

+ +
    +
  1. Create AGENTS.md in the root directory of the corresponding project folder.
    2. +
  2. Only write the rules that this project must follow.
    3. +
  3. If you are not sure how to write it, you can ask Codex to read the project first and then generate the first version for you.
    4. +
+

For example:

+
+

"Use the existing technology stack of the project and do not change the framework without authorization." +"Do not delete or rename the core directory without authorization." +"When fixing bugs, give priority to finding the root cause, don't just do superficial compatibility."

+
+

The simplest template:

+
# AGENTS.md
+
+## Project overview
+
+这是一个前端项目，主要用于构建网页、交互页面、小游戏或内容展示页。
+
+## Tech stack
+
+- 使用项目现有技术栈，不要擅自更换框架。
+- 如果是 Vite / React / Vue / Next.js 项目，先确认 `package.json` 再判断运行方式。
+- 不要随意引入新的生产依赖。
+- 如确实需要新增依赖，先说明原因、用途和替代方案，等待确认。
+
+## Project structure
+
+- `src/`：主要源码目录。
+- `public/`：静态资源目录。
+- `components/`：组件目录，如果项目中存在则优先复用。
+- `assets/`：图片、图标、样式资源。
+- 不要擅自删除、重命名核心目录。
+- 修改前先阅读相关文件，不要只凭文件名猜测。
+
+## Working rules
+
+- 开始修改前，先简单说明计划。
+- 优先小步修改，不要一次性大范围重构。
+- 保持原项目代码风格、命名风格和目录结构。
+- 修 bug 时，优先找到根因，不要只做表面兼容。
+- 改 UI 时，注意中文排版、信息层级、间距、按钮状态和移动端适配。
+- 不要覆盖用户已有改动。
+
+## Commands
+
+请根据 `package.json` 判断实际命令。常见命令如下：
+
+npm install
+npm run dev
+npm run build
+npm run lint
+
+
Skills: suitable for "reusable workflow"
+

If AGENTS.md is a project specification, Skill is more like a reusable workflow package.

+

Skills can contain SKILL.md, reference files, scripts, and resources; they are suitable for recurring tasks that require assistance with steps, examples, or tools.

+

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
SceneShould it be made into Skill
Write the same X Article every timeShould
PR review must be done according to the fixed process every timeShould
Just want to remind Codex to use pnpmNo, put AGENTS.md
Tone requirements that are only valid for the current taskNo, put prompt
+

The Skill used for writing is not just to remember "Write a tweet for me".

+

What it should really settle is:

+
    +
  • Writing style.
    • +
  • Output structure.
    • +
  • Markdown format.
    • +
  • Picture placeholder.
    • +
  • Tutorial steps.
    • +
  • Recommended rules.
    • +
  • Quality check.
    • +
+

Operation steps:

+
    +
  1. First list the tasks you do repeatedly.
    2. +
  2. If a task appears more than 3 times, consider making it a Skill.
    3. +
  3. SKILL.md only contains core rules.
    4. +
  4. Long templates, style cards, and checklists are placed in references/.
    5. +
  5. Put scripts in the parts that can be automated.
    6. +
+
+
Final summary
+
+

If the front seems a bit convoluted, you can understand it like this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HierarchyMetaphorWhat to put
Current session / promptTemporary noteOne-time requirement for this mission
MemoriesPersonal habit filesStable preferences, common backgrounds, long-term habits
Global AGENTS.mdPersonal work rulesHard rules that must be followed in all projects
Project-level AGENTS.mdProject work instructionsTechnology stack, commands, directories and restricted areas of the current repository
SkillReusable process packageFrequently repeated tasks that require steps and templates
AutomationsRegular reminders and monitoringRegular review, follow-up, inspection, and monitoring
MCP / ConnectorReal-time data portalChanging external information such as Slack, GitHub, Docs, etc.
+

+ Codex记忆系统各层级总结图 +

+ +

One final sentence:

+
+

The memory and context of Codex can be understood as "the more temporary, more specific, and closer to the current task, the higher the priority".

+
+

Part 4: Standard Workflow

+

Complete link from requirement to delivery

+

Many people just start using Codex and will throw one sentence at it:

+
+

Help me make a website. +Help me change this function. +Help me optimize this project.

+
+

This is not impossible, but it is easy to cause a problem: +**AI changes very quickly, but you don’t know what it has changed, and you don’t know whether it can be delivered with confidence. **

+

Therefore, the truly stable way is not to make random changes to Codex in one go, but to advance according to a set of fixed workflows.

+

You can understand it as:

+
+

Requirements are not directly transformed into deliverables. They must go through the steps of "understanding, planning, modification, verification, inspection, and acceptance".

+
+

Standard six-step method

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsNameIn simple termsPurpose
1Requirement dismantlingLet Codex know what the project is to be done firstAvoid making random changes without understanding the structure
2Make a planList what you want to do first, and then start after confirmingAvoid changing too many steps in one step and going off track
3Implementation in small stepsOnly change a small piece at a timeReduce the probability of errors and facilitate rollback
4TestAfter the modification, run the check and manually verifyConfirm that the code does not report obvious errors
5Code reviewLook at the diff to check whether the changes are correct and whether there are risksPrevent AI from changing to places that should not be changed
6Submit and reviewSubmit code and accumulate experienceAI is responsible for execution, people are responsible for making decisions
+
Step 1: Requirements dismantling
+

Before letting Codex modify the project, the first thing is not to write the code, but to break down the requirements.

+

Many people are prone to overturning when using Codex, not because Codex doesn’t know how to write code, but because the requirements are not clearly stated at the beginning.

+

For example, if you just say:

+
+

Help me optimize the homepage.

+
+

Codex may be understood as:

+
    +
  • Change UI
    • +
  • Change the copy
    • +
  • Change layout
    • +
  • Change component structure
    • +
  • Change routing
    • +
  • even deleted some code that it felt was "useless"
    • +
+

Therefore, before starting the formal work, the requirements should be broken down into several key issues.

+
What is the background?
+

First explain why this task is required.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
QuestionsExamples
What stage is the project at nowThis is an official website page that has been launched
What situation are you encountering nowThe conversion rate on the homepage is low and users don’t know the selling points of the product
Why should we change nowIn preparation for releasing a new version, we need to optimize the first screen expression
What type does this requirement belong toUI optimization / Bug fix / New features / Refactoring
+
What problem should be solved?
+

The requirements should be as specific as possible. Don't just write "optimize", "beautify" or "make it better".

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Vague statementClearer statement
Optimize home pageOptimize home page title, subtitle and CTA button
The page does not look goodAdjust card spacing, font level and button style
There is a problem with logging inFix the problem that there is no jump after clicking the login button
Make a backendAdd a new user list page, including search, filtering and paging
+

A good request should be able to answer:

+
+

Which specific problem should be solved this time?

+
+

Example:

+
这次主要解决三个问题：
+1. 首屏标题表达不清楚
+2. CTA 按钮不明显
+3. 移动端首屏内容太拥挤
+
+
Which files may be relevant
+

If you know the approximate file location, it is best to tell Codex in advance.

+

This can reduce the probability of random searching and modification throughout the project.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioPossibly related files
Change homepageapp/page.tsx, pages/index.tsx, components/Hero.tsx
Change styleglobals.css, tailwind.config.js, related component files
Change loginlogin/page.tsx, auth.ts, middleware.ts
Change interfaceapi directory, server directory, lib directory
Change copyPage components, configuration files, i18n files
+
Which functions cannot be moved
+

This is very important.

+

Codex It is easy to change other places in order to complete the current task.

+

So tell it in advance:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Immovable contentDescription
Login logicOnly change the UI, not the authentication process
Interface addressDo not change the API request path
Data structureDo not change database fields
Routing structureDo not change the existing page path
Existing componentsDo not refactor on a large scale unless necessary
Dependency versionDo not upgrade or add dependencies casually
+

The core of this step is to draw the boundary for the Codex.

+
+
What result is considered complete?
+

Don’t just say “just do it”, tell Codex what completion means.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Requirement TypeCompletion Criteria
UI optimizationThe page visuals are significantly improved, and the mobile terminal is not messy
Bug repairThe original error report disappears and related functions can be used normally
New featuresUsers can complete the operation process
Performance optimizationThe build is normal and the page loading is not significantly slower
Copywriting optimizationTitle, subtitle, and button copywriting are clearer
+

Example:

+
完成标准：
+1. 首页首屏能清楚表达产品用途
+2. CTA 按钮更明显
+3. 移动端显示正常
+4. 不影响其他页面
+5. 项目可以正常运行和构建
+
+
What tests are required?
+

After the modification is completed, you cannot just look at the Codex and say "completed", but you must also explain in advance how to verify it.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Test typeApplicable scenarios
Page previewUI modification, page layout adjustment
Console inspectionFront-end page, interactive functions
Build TestNext.js, React, Vue Project
Unit testingProjects with test files
Manual process testingLogin, payment, form, upload and other processes
Mobile terminal testResponsive page, Xiaohongshu first picture, mobile web page
+
+
What are the risks?
+

When dismantling requirements, Codex must be asked to determine the risks in advance.

+

This way it won't try randomly while changing.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RiskDescription
The scope of influence is too largeSmall requirements are changed into major refactoring
Style pollutionChanged global CSS, affecting other pages
Dependency riskAdding unnecessary dependencies makes the project more complicated
Logical riskIn order to fix one problem, change other processes
Data riskChange interface, fields, database related content
Compatibility riskThe desktop version is normal, but the mobile version has problems
+
Requirement disassembly prompt word template
+

When actually using Codex, you can copy this section directly:

+
请先帮我做需求拆解，不要立刻修改代码。
+
+需求：
+【这里写你的需求】
+
+请按下面结构分析：
+
+1. 背景是什么
+- 当前项目大概是什么
+- 为什么要做这个需求
+- 这个需求属于新功能、Bug 修复、UI 优化，还是重构
+
+2. 要解决什么问题
+- 当前具体问题是什么
+- 本次要解决到什么程度
+- 哪些内容不是本次范围
+
+3. 哪些文件可能相关
+- 请根据项目结构判断可能涉及哪些文件
+- 先列出来，不要直接修改
+
+4. 哪些功能不能动
+- 不要改哪些逻辑
+- 不要动哪些接口
+- 不要影响哪些页面或组件
+
+5. 什么结果算完成
+- 功能完成标准
+- 页面完成标准
+- 代码完成标准
+
+6. 需要哪些测试
+- 需要运行什么命令
+- 需要手动检查哪些页面
+- 需要重点验证哪些流程
+
+7. 有哪些风险
+- 可能影响哪些功能
+- 是否有样式污染风险
+- 是否有重构过度风险
+- 是否有新增依赖风险
+
+最后，请给我一个简短的执行建议：
+- 建议先做哪一步
+- 是否需要我确认后再修改
+
+
Step 2: Let Codex make a plan
+

After the requirements are disassembled, do not let Codex write code immediately.

+

This step requires Codex to make a plan first.

+

You can understand it as:

+
+

Let the AI explain what it is going to do first, and then decide whether to let it take action.

+
+

Many projects have overturned, not because Codex will not change, but because it starts to change as soon as it comes up.

+

By the time you find that the direction is wrong, it may have changed many files, and it will be troublesome to check and roll back.

+

So the core of the second step is:

+
+
+

Plan first, then execute. +Confirm first, then modify.

+
+
+
Don’t write code yet
+

This should be written at the beginning of the prompt word.

+

Because the default tendency of Codex is to start solving the problem directly after seeing the demand.

+

But in a real project, directly changing the code is very risky.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Problems with writing code directlyPossible consequences
Didn't understand the project structureCorrect the error file
Failure to confirm the requirement boundaryPerforming functions that should not be performed
Unable to determine the scope of impactInadvertent damage to old functions
No test method listedI don’t know how to accept the changes
Too many changes at onceIt is difficult to roll back after an error
+

Example prompt words:

+
先不要写代码，也不要修改任何文件。
+请先根据当前需求和项目结构，制定一个修改计划。
+等我确认后，再开始执行。
+
+
Turn on plan mode
+

You can refer to the "Planning Mode" section in the basic use of Codex App. In actual use, you can also directly enter /plan in the Codex CLI or App, and let Codex output the plan first, and then decide whether to execute it.

+
Step 3: Implementation in small steps
+

Only after the plan is confirmed can the actual code modification phase be entered.

+

But there is a very important principle here:

+
+

Don't let Codex change everything at once.

+
+

Many people use Codex to overturn it, just because it "achieves everything" as soon as they come up.

+

As a result, it may change the page, components, styles, interfaces, and configurations at the same time. Although the project looks changed in the end, it is difficult for you to determine what went wrong.

+

So the more stable way is:

+
+

Only change one function point at a time. +After changing a small step, check the small step.

+
+
Only change one function point at a time
+

The core of small step implementation is to control the scope of modification.

+

For example, if you want to optimize the homepage, don’t say it all at once:

+
请帮我优化整个首页。
+
+

It is more recommended to split it into this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsModify content
Step 1Optimize only the first screen title and subtitle
Step 2Adjust only the CTA button
Step 3Optimize mobile layout only
Step 4Only add product selling point cards
Step 5Only deal with final style details
+

This way every step is clear and problems can be easily located.

+
Don’t let Codex easily refactor irrelevant code
+

Codex sometimes feels that some code is "not elegant enough", and then helps you refactor it.

+

But in real projects, it is very dangerous to refactor easily.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Smooth operation of CodexPossible problems
Rename componentCause reference path error
Split filesIncrease maintenance costs
Change global styleAffect other pages
Optimize old logicDestroy originally available functions
Upgrade dependenciesCause compatibility issues
Remove code it considers uselessIt may actually be business logic
+

Therefore, when implementing in small steps, the restrictions must be clear:

+
本次只实现当前功能点。
+不要顺手重构无关代码。
+不要修改命名、目录结构、依赖版本和全局配置。
+如果你发现代码可以优化，请先记录为建议，不要直接修改。
+
+

This sentence is very important.

+

Codex can make suggestions, but cannot expand the scope of changes without permission.

+
+
Do not accept large-scale modifications without explanation
+

If Codex changes many files at once and the reasons are not clearly explained, it will be suspended.

+

Especially when you see these situations, be vigilant:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SituationProcessing
The number of changed files suddenly became largeAsking for an explanation as to why each file was changed
Deleted a large amount of codeRequested explanation of the reason for deletion
Added an unknown dependencyRequest explanation of necessity
Modified the configuration fileRequest a description of the scope of impact
Changes to pages unrelated to requirementsRequest to roll back irrelevant modifications
Big change in code styleRequest to maintain the original project style
+
If you are unsure, stop and ask first.
+

The small step implementation is not to let Codex ask everything, but to stop when encountering key uncertainties.

+

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Uncertain situationWhy stop
Not sure which file to changePrevent the wrong location from being changed
Uncertain business rulesPrevent logic errors
Not sure if old code can be deletedFunction to prevent accidental deletion
Not sure whether to add dependenciesPrevent project complexity
Unsure of interface meaningPrevent data from being affected
Not sure why the test failedPrevent repairs from getting messy
+

You can add this rule to Codex in advance:

+
如果你遇到以下情况，请先停下来问我，不要自行决定：
+
+1. 不确定该改哪个文件
+2. 不确定是否要删除旧代码
+3. 不确定是否要新增依赖
+4. 不确定业务逻辑应该怎么处理
+5. 不确定测试失败原因
+6. 发现需要超出原计划的修改
+
+
Implement prompt word template in small steps
+

For actual use, you can directly copy the following paragraph:

+
请开始小步实现。
+
+当前只执行第【1】步：
+【这里写本次只做的一个功能点】
+
+要求：
+1. 一次只改这个功能点
+2. 只修改和当前功能直接相关的文件
+3. 不要顺手重构无关代码
+4. 不要修改目录结构
+5. 不要新增不必要依赖
+6. 不要删除已有功能
+7. 不要改计划外的文件
+
+修改完成后请停止，并输出：
+
+1. 本次修改了哪些文件
+2. 每个文件改了什么
+3. 为什么这些修改是必要的
+4. 有没有改到计划外内容
+5. 有没有潜在风险
+6. 下一步建议做什么
+
+注意：
+如果遇到不确定的地方，请先停下来问我，不要自行决定。
+
+
Step 4: Test
+

After completing the small step modifications in Codex, you cannot proceed to the next step immediately and must be tested first.

+

The biggest problem that many people have with Codex is:

+
+

AI said it was completed, but the project actually did not go through.

+
+

The page looks normal, but some functionality is broken. +The current function has been fixed, but the old function has been affected.

+
+
+

So the core of the test is: **not to believe that Codex says "complete", but to use the results to prove that it is really completed. **

+
+

The following table covers what needs to be done for a complete test. Just execute it in order from fastest to slowest:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Test typeFunctionCommon commandsKey points
Unit testCheck whether functions, components, and modules are normalnpm test / pnpm test / yarn testIf it fails, explain the reason first, do not change the code directly
Type checkingTypeScript projects catch type errors earlynpm run typecheck / tsc --noEmitExplicitly state without this command
lintCheck code specification issues (unused variables, import order, Hook usage, etc.)npm run lintDistinguish between this new issue and the original issue of the project
BuildBeing able to open locally does not mean that it can be online. Building only means that it can be packagednpm run build / pnpm buildIf it fails, summarize the error report and scope of impact first
Manual testingUI, form, login, payment, upload must be clicked manually——Step by step verification according to user operation path
Browser testPage/console/interface problems that cannot be seen on the terminal——See page display, Console error, Network, mobile terminal
Regression testingNot only test new functions, but also test whether old functions have been changed——List old pages and components that may be affected by this modification
+
+

Two reminders: Many old projects have lint or type issues themselves. Don’t let Codex refactor all historical issues; regression testing is the most easily overlooked step by novices - changing the homepage button may also affect other pages that reuse the same component.

+
+

When testing manually, you can ask Codex to list the verification steps into an "Operation-Expected Result" table, for example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepsActionsExpected results
1Open the home pageThe page loads normally
2Click the CTA buttonJump to the registration page
3Shrink to mobile phone widthThe page will not be deformed
4Open the consoleNo obvious red error
+
Test phase prompt word template
+

For actual use, you can copy this section directly:

+
请对本次修改进行测试，不要继续新增功能。
+
+请按下面顺序执行或说明：
+
+1. 单元测试
+- 项目是否有单元测试
+- 如果有，请运行测试命令
+- 如果失败，请说明失败原因
+
+2. 类型检查
+- 项目是否有 typecheck 命令
+- 如果有，请运行
+- 如果没有，请说明
+
+3. lint
+- 运行 lint 检查
+- 区分本次新增问题和项目原有问题
+
+4. 构建
+- 运行 build 命令
+- 如果失败，请说明报错原因和影响范围
+
+5. 手动测试
+- 列出需要手动测试的页面
+- 列出用户操作步骤
+- 列出每一步预期结果
+
+6. 浏览器测试
+- 检查页面显示
+- 检查控制台报错
+- 检查移动端布局
+- 检查关键按钮和交互
+
+7. 回归测试
+- 检查本次修改是否影响旧功能
+- 列出可能受影响的页面、组件和流程
+
+最后请输出测试总结：
+- 哪些测试通过了
+- 哪些测试失败了
+- 失败原因是什么
+- 是否可以进入下一步
+- 是否需要先修复问题
+
+
Step 5: Code Review
+

After passing the test, it does not mean that the modification can be delivered directly.

+

Code review is also required.

+

Code review can be understood as:

+
+

It’s not just about whether the code can run, but also about whether the code changes are correct, whether it is stable, and whether there are risks.

+
+

Codex is fast to write code, but it may also have these problems:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FAQInstructions
The function can run, but the logic is wrongIt looks normal on the surface, but there is a problem with the real business process
The changes are too bigFor a small requirement, a lot of irrelevant code has been changed
Accidentally deleted old logicDeleted seemingly useless but actually useful code
Ignore boundary conditionsNormal input can be used, abnormal input will crash
Security issuesExposed keys, incorrect permission judgment, unverified input
Inconsistent styleThe new code is inconsistent with the original project writing method
Poor maintainabilityTemporarily programmed, hard-coded, difficult to change later
+

So code review is not optional, but a key step in the Codex workflow.

+
+
Two rounds of review: Codex self-review + manual review
+

In the first round, let Codex self-examine the modifications just now (the purpose is not to completely believe it, but to let it expose obvious problems first). It is best to let it output into a table:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Check itemsResultsDescription
Whether to change to unplanned filesNoOnly the homepage related components have been modified
Whether to add new dependenciesNoNo modifications to package.json
Whether to delete the old logicNoKeep the original button jump logic
Is there a riskYesThe distance between the buttons on the mobile terminal needs to be manually confirmed
+
+

Second round of manual review. The final deliverer is you, not Codex. It is not required to understand every line, but you should focus on these parts of diff:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Review highlightsWhat to see
File rangeWhether only the files that should be changed
Modify/delete contentWhether it complies with the plan and whether old functions have been deleted
Naming and structureWhether it is consistent with the original project style
Business logicWhether it meets the real needs (can run ≠ logical pair)
Test resultsWhether the test was actually run
+

Involving important codes such as login, payment, permissions, database, authentication, etc., it is recommended to use a second model for cross-examination - one model is written, and the other model is specially used to find errors (it is generally not necessary to only change the copywriting and minor styles). But the suggestions of the second model cannot be accepted in full. It helps you find problems but does not make the final decision for you.

+
Focus on four types of high-risk issues
+

The following four categories are the areas where Codex is most likely to cause problems and should be reviewed most:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryFAQReview Points
Boundary conditionsNormal input can be used, abnormal input will crashEmpty data, interface failure, not logged in, insufficient permissions, mobile terminal size, repeated clicks
Security issuesWhen involving user/interface/permission/payment/upload/databaseWhether the key token is exposed, whether the authority judgment is missing, whether the input is verified, whether sensitive information is leaked, whether the interface is authenticated
Whether it was deleted by mistakeCode that seems useless but is actually useful has been deletedFocus on the deleted content of diff; old components, comments, compatible code, fallbacks, and configuration items may still be relied on
Business logicThe code can run but the logic is wrong (jumping to the wrong page, wrong price calculation, override of authority)Normal path, abnormal path, permission judgment, whether the old business rules are overwritten
+

If you see a large section deleted but the Codex does not explain it clearly, don’t accept it directly.

+
Code review prompt word template
+

For actual use, you can directly copy this paragraph:

+
请对本次修改做代码审查，不要继续写代码。
+
+请按下面结构审查：
+
+1. Codex 自审
+- 本次是否只改了计划内文件
+- 是否有无关重构
+- 是否有新增依赖
+- 是否有硬编码
+- 是否有误删旧逻辑
+
+2. 修改范围审查
+- 修改了哪些文件
+- 每个文件为什么要改
+- 是否存在计划外修改
+- 是否有大面积无解释修改
+
+3. 边界条件审查
+- 空数据如何处理
+- 接口失败如何处理
+- 用户未登录如何处理
+- 权限不足如何处理
+- 重复点击如何处理
+- 移动端是否可能异常
+
+4. 安全问题审查
+- 是否暴露密钥、token、账号密码
+- 是否影响权限判断
+- 是否缺少输入校验
+- 是否可能泄露敏感信息
+- 是否修改了接口鉴权逻辑
+
+5. 删除内容审查
+- 删除了哪些代码
+- 删除原因是什么
+- 是否确认没有其他地方依赖
+- 是否可能影响旧功能
+
+6. 业务逻辑审查
+- 是否符合需求
+- 正常流程是否正确
+- 异常流程是否正确
+- 是否影响旧业务规则
+- 是否有不确定的业务假设
+
+7. 审查结论
+请最后给出结论：
+- 可以继续
+- 需要小修
+- 需要回退部分修改
+- 需要重新制定计划
+
+注意：
+只审查，不要继续修改代码。
+如果发现问题，请先说明问题和建议，等我确认后再改。
+
+
Step 6: Submission and Review
+

After the code test passes and the review is completed, the last step is not to simply say "done".

+

For a truly complete Codex workflow, two more things need to be done:

+
+
+

First, formally submit this modification. +Second, accumulate this experience.

+
+
+

Many people use Codex only to achieve "the code can run", but there are no submission instructions, no PR description, no problem recording, and no updated documentation.

+

This may not be a problem in the short term, but there will be a problem in the long term:

+
+

It’s like doing it for the first time every time. +Reinterpret every time. +Repeat the trap every time.

+
+

So the core of the sixth step is:

+
+
+

Delivery is not the end, review is the beginning of the next efficiency improvement.

+
+
+
Generate commit
+

When this modification has passed testing and review, you can let Codex generate a commit for you.

+

Commit is not just about writing "update", but it is about explaining what has been changed this time.

+

A good commit should be able to answer:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
QuestionDescription
What has been changedThe main content of this submission
Why the changeWhat needs or problems does it correspond to
Where is affectedWhich modules, pages or functions are involved
Whether to pass the testWhether to build, lint, test passed
+

Common commit message format:

+
feat: add user profile page
+fix: resolve login redirect issue
+style: improve homepage responsive layout
+refactor: simplify product card component
+docs: update setup guide
+
+

If it is a Chinese project, it can also be written as:

+
feat: 新增用户资料页
+fix: 修复登录后跳转异常
+style: 优化首页移动端布局
+docs: 更新项目使用说明
+
+
Write PR
+

If the project uses GitHub, GitLab or team collaboration process, a PR is usually written after submission.

+

The role of PR is not to "just go through the motions", but to let others know quickly:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
What PR should explainFunction
What did you do this timeConvenient for reviewers to quickly understand
Why do itExplain the background of the requirement
What has been changedReduce review costs
How to testProve that it is not changed casually
What are the risksExpose uncertainties in advance
What to focus onGuide reviewer review focus
+

A good PR description can be written like this:

+
## 本次修改
+
+- 优化首页首屏标题、副标题和 CTA 按钮
+- 调整移动端首屏布局
+- 保留原有跳转逻辑，没有修改接口和路由
+
+## 测试结果
+
+- npm run lint 通过
+- npm run build 通过
+- 手动检查首页桌面端和移动端显示正常
+- 点击 CTA 按钮跳转正常
+
+## 风险说明
+
+- 本次涉及首页样式调整，需要重点确认移动端显示
+- 没有新增依赖
+- 没有修改登录、接口、数据库逻辑
+
+
Record the problem
+

When reviewing, the problems encountered during this process should be recorded.

+

This step is very important.

+

Because in the Codex workflow, the real value is not "done this time", but:

+
+

If you encounter similar problems next time, you can avoid taking detours.

+
+

Problems that need to be recorded include:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Question TypeExample
Requirement issuesThe requirements description was not clear enough at the beginning
Planning issuesThe mobile version is missing from the Codex plan
Modify the problemCodex changed irrelevant components smoothly
Test problemProject does not have typecheck command
Review issueFound that it deleted the fallback logic by mistake
Communication problemThe prompt word is not clear "Do not add dependencies"
+

The record format can be very simple:

+
本次问题记录：
+
+1. 问题：Codex 一开始想修改全局样式
+   原因：需求里没有明确限制“只改首页”
+   解决：补充提示词，要求只修改首页相关文件
+
+2. 问题：移动端测试遗漏
+   原因：计划阶段没有列移动端验收标准
+   解决：以后在测试清单里固定加入移动端检查
+
+3. 问题：PR 描述不够清楚
+   原因：没有提前记录测试结果
+   解决：每次测试后直接生成测试总结
+
+
Summary Prompt
+

If the prompt word used this time is effective, it should be settled.

+

The purpose of this step is simple:

+
+
+

Useful prompt, don’t rewrite it every time.

+
+
+

For example, this time you find the following sentence useful:

+
不要顺手重构无关代码。
+如果发现需要超出计划的修改，请先停下来问我。
+
+

Then it should be recorded and used as a fixed rule in the future.

+

can be organized into a table:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Valid PromptApplicable scenariosWhy it is valid
Don’t write code first, make a plan firstAll complex requirementsPrevent Codex from being directly modified
Change only one function point at a timeMulti-step tasksReduce errors and rollback costs
Do not refactor irrelevant codeMaintain old projectsPrevent the scope of changes from expanding
Summary after modificationdiffafter each modification
If you are not sure, stop and ask firstWhen the business logic is unclearPrevent AI from making its own decisions
+
Update AGENTS.md
+

If certain rules must be followed every time in the future, don't just write them in the chat. It is best to update them to the project level AGENTS.md.

+
+

AGENTS.md can be understood as:

+

Project rules statement written to Codex.

+
+

It tells Codex:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ContentFunction
How to run the projectLet Codex know the startup, test, and build commands
What is the coding styleAvoid generating code that does not conform to the project style
Which directories cannot be movedPrevent core files from being accidentally changed
What to do before modificationFixed "plan first and then execute"
What are the testing requirementsWhat checks must be run after the modification
What are the submission requirementsHow to write commit and PR
+

Example content:

+
# AGENTS.md
+
+## 工作规则
+
+- 修改前必须先阅读项目结构。
+- 修改前必须先制定计划，不要直接写代码。
+- 一次只实现一个功能点。
+- 不要顺手重构无关代码。
+- 不要新增不必要依赖。
+- 不确定业务逻辑时，先提问，不要自行决定。
+
+## 测试要求
+
+每次修改后至少检查：
+
+- npm run lint
+- npm run build
+- 相关页面手动测试
+- 浏览器控制台是否有报错
+- 移动端布局是否正常
+
+## 提交要求
+
+提交前需要说明：
+
+- 修改了哪些文件
+- 每个文件改了什么
+- 测试是否通过
+- 是否有风险或未完成事项
+
+
Update project documentation
+

In addition to AGENTS.md, if this modification affects the way the project is used, the project document must also be updated.

+

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Modified contentDocuments that need to be updated
New featuresREADME, function description
Add environment variable.env.example, deployment document
New commandREADME, development guide
Modify interfaceAPI documentation
Modify deployment processDeployment instructions
Modify configurationConfiguration description
New componentComponent usage instructions
+

The document is updated not to look good, but to avoid forgetting it in the future.

+

Common documents include:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FileFunction
README.mdProject introduction, startup method, common commands
.env.exampleEnvironment variable example
docs/Detailed project documentation
CHANGELOG.mdVersion update record
AGENTS.mdCodex work rules
CONTRIBUTING.mdTeam collaboration specifications
+
Submission and review prompt word template
+

For actual use, you can directly copy the following paragraph:

+
请进入提交与复盘阶段，不要继续新增功能。
+
+请按下面结构输出：
+
+1. Commit 建议
+- 生成一个合适的 commit message
+- 使用 conventional commit 格式
+- 不要夸大本次修改范围
+
+2. PR 描述
+请生成 PR 内容，包括：
+- 本次修改
+- 修改原因
+- 涉及文件
+- 测试结果
+- 风险说明
+- reviewer 需要重点看的地方
+
+3. 问题记录
+请复盘本次过程：
+- 遇到了哪些问题
+- 原因是什么
+- 如何解决
+- 下次如何避免
+
+4. Prompt 总结
+请总结：
+- 哪些 Prompt 有效
+- 为什么有效
+- 适合什么场景复用
+- 是否建议加入 AGENTS.md
+
+5. AGENTS.md 更新建议
+请输出适合加入 AGENTS.md 的长期规则：
+- 修改前规则
+- 修改中规则
+- 测试规则
+- 提交规则
+
+6. 项目文档更新建议
+请判断是否需要更新：
+- README.md
+- .env.example
+- docs/
+- CHANGELOG.md
+- 其他项目文档
+
+最后请给出交付结论：
+- 是否可以提交
+- 是否可以发 PR
+- 是否还有未完成事项
+- 是否有需要人工确认的风险
+
+

Codex task template library

+

What we talked about earlier is the standard workflow of Codex.

+

This section directly places some commonly used templates for easy copying and use in the future.

+

The purpose of these templates is to:

+
+
+

There is no need to rethink Prompt every time, just copy it according to the scene, and then fill in your own needs.

+
+
+

Read project template

+

This template is suitable for use when just opening a new project.

+

Especially when it is your first time to let Codex come into contact with a project, do not let it change the code right away.

+

A more stable way is to let it read the project first and output a project understanding report.

+

This way you can judge first:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CheckpointFunction
Does Codex understand the projectPrevent correcting wrong files at first
Is the technology stack judged correctlyMake sure it knows what framework the project uses
Is the startup method clearThe subsequent testing and operation will be smoother
Whether the core module is found correctlySubsequent modifications will not cause confusion
Whether risks are exposed in advanceAvoid changing core logic by mistake
+
Read project template (can be copied directly)
+
请先不要修改任何代码。
+
+请阅读当前项目，并输出一份项目理解报告，包括：
+
+1. 技术栈
+- 项目使用了哪些主要技术
+- 前端/后端/数据库/构建工具分别是什么
+- 是否使用 TypeScript、Tailwind、框架或组件库
+
+2. 目录结构
+- 主要目录分别负责什么
+- 页面、组件、工具函数、接口、配置文件分别在哪里
+- 哪些目录是核心目录，哪些目录不建议随便改
+
+3. 启动方式
+- 项目如何安装依赖
+- 项目如何本地启动
+- 是否需要环境变量
+- 如果 README 里有说明，请优先参考 README
+
+4. 测试命令
+- 项目是否有 test 命令
+- 是否有 lint 命令
+- 是否有 typecheck 命令
+- 是否有 build 命令
+- 如果没有相关命令，请明确说明
+
+5. 核心模块
+- 项目的核心功能模块有哪些
+- 每个模块大概负责什么
+- 如果后续要修改功能，应该优先查看哪些文件
+
+6. 后续修改风险
+- 哪些文件或目录改动风险较高
+- 哪些逻辑不能随便改
+- 是否存在全局样式、全局配置、鉴权、接口、数据库等高风险区域
+- 后续修改时需要特别注意什么
+
+请只输出项目理解报告，不要修改代码。
+输出完成后等待我确认。
+
+

Bug fix template

+

I encountered a bug:

+
    +
  • [Phenomena]
    • +
  • [Reproduction Steps]
    • +
  • [Expected results]
    • +
  • [Actual results]
    • +
  • [Related files/pages]
    • +
+

Please locate the cause first and do not modify it directly.

+

First give:

+
    +
  1. Possible reasons
    2. +
  2. Files to be viewed
    3. +
  3. Repair plan
    4. +
  4. Risk points +Wait for my confirmation before changing the code.
    5. +
+

Add function template

+

I want to add a new function:

+
    +
  • [Function Description]
    • +
  • [Entrance Location]
    • +
  • [Interaction process]
    • +
  • [Visual requirements]
    • +
  • [Data source]
    • +
  • [Acceptance Criteria]
    • +
+

Please read the relevant code first and give an implementation plan.

+

Do not change irrelevant files.

+

Please run the test and summarize the diff after implementation.

+

Front-end page template

+

Please implement a page according to the following requirements:

+
    +
  • [Page Purpose]
    • +
  • [Target Users]
    • +
  • [Visual style]
    • +
  • [Module Structure]
    • +
  • [Chinese copywriting]
    • +
  • [Responsive request]
    • +
  • [Unwanted problem]
    • +
+

Please provide a component splitting plan before starting to implement it.

+

Code review template

+

Please review the diff of the current branch relative to main.

+

Key inspections:

+
    +
  1. Potential bugs
    2. +
  2. Boundary conditions
    3. +
  3. Security risks
    4. +
  4. Type issue
    5. +
  5. Performance issues
    6. +
  6. Are there any irrelevant modifications?
    7. +
  7. Is the test sufficient? +Please do not modify the code directly, output the review report first.
    8. +
+
+

Reconstruction template

+
+

Please refactor the following modules:

+

[Module path]

+

The goal is:

+
    +
  1. Improve readability
    2. +
  2. Reduce duplicate code
    3. +
  3. Keep existing behavior unchanged
    4. +
  4. No changes to the public API
    5. +
  5. No new dependencies are introduced +Please write a refactoring plan first and explain how to verify consistent behavior.
    6. +
+

Write test template

+

Please add tests for the following functions:

+
    +
  • [Function Description]
    • +
  • [Related documents]
    • +
  • [Border Case]
    • +
+

Requirements:

+
    +
  1. Do not change the business logic
    2. +
  2. Cover the normal path
    3. +
  3. Cover the abnormal path
    4. +
  4. Override boundary conditions
    5. +
  5. Run the test and report the results.
    6. +
+

Write document template

+

Please generate documents based on the current project:

+
    +
  1. Project Introduction
    2. +
  2. Installation method
    3. +
  3. Startup method
    4. +
  4. Environment variable description
    5. +
  5. Common commands
    6. +
  6. Directory structure
    7. +
  7. Development considerations
    8. +
  8. Frequently Asked Questions +Please do not make up non-existent commands. You must judge based on the project file.
    9. +
+
+

Part 5: Practical Case Library

+

Practical Case 1: Create a front-end page website for selling pet snacks

+

Create a front-end web page from scratch that can be published on the Internet

+

Create a folder locally and name it Pet treats

+

Select the created folder

+

+ Codex移动版界面，左侧为导航栏，有搜索、插件、项目等选项 +

+ +

Turn on plan mode

+

Generate a preliminary project plan and execute it directly after checking that there are no problems

+

+ 一个宠物零食售卖网站的项目计划界面 +

+ +

Open the index.html file for preview

+

+ 在本地打开index.html文件进行预览的界面 +

+ +

Create Git repository

+

Create a Git repository for code management to facilitate subsequent updates and maintenance

+

+ 在本地创建的“Pet treats”文件夹中，使用Codex生成的初步项目计划 +

+ +

Optimization details changes

+

Directly use comments to make detailed modifications on the page

+

+ 一个宠物零食售卖前端页面网站中的一款商品“草本洁齿咀嚼棒” +

+ +

Increase monthly sales

+

+ 在GitHub上对“制作宠物零食售卖网站”项目的操作界面 +

+ +

New features

+

Added hot-selling list

+

+ 一个宠物零食售卖前端页面网站的热销榜页面 +

+ +
+

Push updated code

+
+

Push the updated code after checking that there are no problems

+

+ 在GitHub上对“Pet treats”仓库代码进行推送更新的操作界面 +

+ +

Upload to GitHub repository

+
Create a new repository
+

+ Codex平台的界面，左侧为项目列表，右侧是项目详情区域 +

+ +

+ GitHub新建仓库页面 +

+ +
+
Copy the corresponding repository link
+

+ GitHub仓库创建页面中“快速安装”部分的内容 +

+ +
Let Codex upload the code to the GitHub repository
+

+ 在GitHub上上传代码后的信息界面 +

+ +

+ Codex平台的仓库页面 +

+ +
Publish web pages through GitHub Pages so that others can access them
+

Find pages in settings and click Save

+

Wait a few minutes

+

+ GitHub Pages的相关设置界面 +

+ +

Wait a few minutes and a link will appear. This link allows others to visit your web page.

+

It should be noted that GitHub Pages is suitable for hosting static websites, such as HTML, CSS, JavaScript and static resources; it is not suitable for running business logic that requires back-end servers, databases or sensitive transactions.

+

+ GitHub Pages的相关设置界面 +

+ +
Open the web page to view the completed project
+

The stability of accessing GitHub Pages may vary in different regions and network environments. If it cannot be opened, you can change the network first or wait for the deployment to complete and try again.

+

https://vink567.github.io/Pet-treats/

+

+ 在浏览器中打开的“Pet treats”网页 +

+ +

Practical Case 2: Adding functions and optimizing pages to the pet snack website

+

Create a new user login registration page

+

Users need to fill in their own address information when purchasing. At this time, a personal login account is needed to save this information.

+

+ 宠物零食管理系统的登录页面 +

+ +

Create different pet categories and classify food under pet categories

+

Still use the planning mode first to see if the AI understands your needs

+

+ 宠物零食网站的页面及后台内容 +

+ +

Use the comment function to optimize details

+

+ 宠物零食网站的页面及后台管理界面 +

+ +

+ 宠物零食管理后台的界面 +

+ +

After selecting food and adding it to the shopping cart, you will be prompted to confirm your address when you click to purchase.

+

+ 宠物零食管理系统的界面 +

+ +

Submit to Git and save the code

+

+ 宠物零食网站的管理后台界面 +

+ +

Practical Case 3: Management Backend for Making Pet Snacks

+

Still use the plan mode first

+

+ 宠物零食网站的管理后台界面 +

+ +

+ 宠物零食管理后台计划的相关内容 +

+ +

Check the effect

+

+ 宠物零食管理售卖网站的界面 +

+ +

Submit to Git and save the code

+

+ 宠物零食管理后台的界面 +

+ +

Practical case four: Making pet snack brand investment PPT

+

Install PPT Skill

+

What I installed here is a PPT Skill that I have evaluated before. Just send the corresponding Skill address on GitHub to Codex and let it be installed.

+

+ Codex平台界面，左侧为项目列表，当前选中“Pet treats - 制作宠物零食销售网站”项目 +

+ +

Use "/" to select the corresponding Skill

+

+ Codex平台中安装PPT Skill的界面 +

+ +
+

Check the final result

+
+

Codex finally generated a complete investment promotion PPT. The finished product has been uploaded to the cloud. Click the link below to download and view:

+

⬇Download investment promotion PPT

+

+ Codex 生成的宠物零食品牌招商 PPT 预览界面 +

+ +

Practical case 5: Making a promotional video for pet snacks

+

Install video plugin

+

The HyperFrames plugin is used here

+

+ HyperFrames by HeyGen的界面 +

+ +
+

Plan to generate video

+

+ 一个文档界面，标题为“重做《炭禾小食》BGM 版电影级生产过程宣传片” +

+ +

Effect preview

+

The finished product is a promotional video for pet snacks. The complete video has been uploaded to the cloud. Click the link below to play it directly in the browser:

+

▶ Watch the demo video online

+

Appendix

+
+

Appendix A: Third-party model access

+

This section introduces the unofficial ideas for third-party model access, taking CC Switch + DeepSeek as an example. It is not an official function of OpenAI. Model compatibility, stability, privacy and cost rules are subject to the corresponding third-party tools and model service providers.

+
+

What is CC Switch

+

It is not the Claude Code ontology, nor the Codex ontology, but a third-party open source desktop tool used to uniformly manage different Agent tools.

+

Simply put:

+
+
+

In the past, you had to manually change the configuration files of Claude Code, Codex, and Gemini CLI. ** +Now CC Switch makes a visual panel for you, switching with one click. **

+
+
+

It has three core uses:

+ + + + + + + + + + + + + + + + + + + + + +
FunctionIn simple terms
Provider switchingFor example, switching from the official Claude API to a transit API, or switching to another model service
MCP unified managementNo need to configure MCP for Claude Code, Codex, and Gemini separately
Skills managementSkills can be installed from GitHub or ZIP and synchronized to different AI programming tools
+

**If you need to switch between multiple Agent tools and models, CC Switch can be used as an advanced option. **

+

Download CC Switch

+

First enter the official website: https://ccswitch.io/zh/

+

After clicking download, you will jump to the corresponding download page. Scroll down to find the corresponding version and click to download.

+

+ CC Switch官网的下载页面 +

+ +

Connect to the third-party model

+
Here we take DeepSeek as an example
+
First find the official website of DeepSeek and create an API key
+

+ 文档配图 +

+ +
Turn on cc switch
+

Click to add model

+

+ CC Switch的界面 +

+ +

Copy the API key you just created here

+

+ CC Switch中添加新供应商界面 +

+ +

Enable local route mapping

+

+ 接入三方模型时在CC Switch中添加模型的设置界面 +

+ +

Then click Add

+

+ CC Switch添加新供应商界面 +

+ +

Enter settings and turn on all routes

+

+ CC Switch设置中的路由页面 +

+ +

Click to enable

+

+ CC Switch的界面，其中“DeepSeek”模型被选中，其右侧有“启用”按钮，该按钮被红色框突出显示 +

+ +

If CC Switch's routing, model service, and Codex side configuration are all compatible, and then open Codex, it will be possible to use third-party models such as DeepSeek through this set of unofficial routing.

+

This type of method is not an official function of OpenAI. Whether it can be used normally, model capabilities, context length, tool call compatibility, fees and privacy rules are all subject to CC Switch, the model service provider and your own configuration. For important projects, it is recommended to use the test repository to verify it first, and do not try it directly in the production project.

+
+
+ + diff --git a/index.html b/index.html index 161d34d..8796789 100644 --- a/index.html +++ b/index.html @@ -87,6 +87,38 @@ flex: none; } + .language-switcher { + display: inline-flex; + overflow: hidden; + border: 1px solid var(--line); + border-radius: 6px; + background: var(--panel); + } + + .language-switcher a, + .language-switcher span { + display: inline-flex; + align-items: center; + justify-content: center; + min-height: 38px; + padding: 0 12px; + color: var(--ink); + font-size: 14px; + font-weight: 650; + text-decoration: none; + white-space: nowrap; + } + + .language-switcher span + a, + .language-switcher a + span { + border-left: 1px solid var(--line); + } + + .language-switcher [aria-current="page"] { + background: var(--orange); + color: #fff; + } + .button { display: inline-flex; align-items: center; @@ -110,7 +142,9 @@ } .button:hover, - .button:focus-visible { + .button:focus-visible, + .language-switcher a:hover, + .language-switcher a:focus-visible { border-color: var(--blue); outline: none; } @@ -162,6 +196,10 @@ padding-inline: 10px; } + .language-switcher { + grid-column: 1 / -1; + } + .viewer { padding: 10px; } @@ -181,7 +219,11 @@

Codex 橙皮书

从安装到实战案例的全链路使用指南

下方为轻量预览；打开或下载按钮会使用高清原版 PDF。

-