小白友好 · 中文版
✨ OpenAI 官方开源编程助手

Codex 小白教程

从零开始，手把手教你安装、配置和使用 OpenAI Codex。无需任何基础，跟着做就行。

自动写代码
自动改 Bug
理解整个项目
命令行操作

🤔 Codex 到底是啥？

简单说，Codex 就是 OpenAI 出的一个跑在你终端（命令行）里的 AI 编程助手。你用文字告诉它你想干什么，它就能帮你：

它和 ChatGPT 网页版最大的不同是：它直接在你电脑上操作文件、运行命令，而不只是在网页里聊天。你说"帮我把这 100 个文件重命名"，它真的会帮你改，而不只是告诉你怎么改。

如果你听说过 Claude Code、Cursor 这类工具，Codex 就是 OpenAI 家对标它们的产品，同样是开源、免费下载的命令行工具。

你（终端里打字）
→
Codex CLI
→
你的中转站
→
GPT 模型
✦

Codex 能帮你做什么？

很多人以为 Codex 只能写代码，其实不然。它是一个全能型的 AI 助手，几乎任何需要"操作文件 + 动脑"的任务它都能帮忙。下面是一些常见的办公场景：

📝 文档写作与编辑

无论是写周报、写方案、还是翻译文档，Codex 都能直接帮你创建和修改文件。

Terminal — codex
▌ 帮我写一份本周工作周报，内容包括：完成了用户系统重构、 修复了 3 个线上 Bug、参加了产品评审会议。保存为 weekly-report.md codex 好的，我来帮你生成周报。 📝 新建 weekly-report.md ✅ 周报已生成，包含工作概述、详细成果和下周计划。

类似的还可以：写会议纪要、写邮件草稿、写项目方案、翻译英文文档等。

📊 数据处理与分析

有 CSV 或 Excel 数据需要处理？Codex 可以直接帮你写脚本分析。

Terminal — codex
▌ 帮我分析 sales_data.csv 这个文件，统计每个月的销售额， 然后生成一个汇总表格保存为 summary.csv codex 让我先看看数据结构... 📝 新建 analyze.py (Python 分析脚本) 🔧 运行: python analyze.py 📝 新建 summary.csv ✅ 分析完成！共处理 2,847 条数据，按月汇总结果已保存。

📂 文件批量操作

需要批量重命名、整理、移动文件？用自然语言告诉 Codex 就行。

Terminal — codex
▌ 把 photos 文件夹里的所有图片按拍摄日期重命名，格式为 2024-01-15_001.jpg 这样的 codex 我来看看文件夹里有哪些图片... 找到 156 张图片，正在读取 EXIF 日期信息... ✅ 已完成！156 张图片全部按日期重命名。

🌐 快速制作网页

需要一个活动页面、个人简历网站、或者产品展示页？一句话搞定。

Terminal — codex
▌ 帮我做一个个人简历网页，暗黑主题，要好看，包含我的基本信息、 工作经历和技能展示，保存为 resume.html codex 好的，我来为你设计一个现代风格的简历网页。 📝 新建 resume.html ✅ 简历网页已创建！直接用浏览器打开 resume.html 即可预览。

🎓 辅助学习

想学编程但不知道从哪开始？Codex 就是最好的老师，边学边练。

Terminal — codex
▌ 我是 Python 初学者，帮我写一个猜数字小游戏，并且在代码里 加上详细的中文注释，让我能看懂每一行 codex 没问题！我来写一个带详细注释的猜数字游戏。 📝 新建 guess_number.py 每一行代码都加了中文注释，你可以运行 python guess_number.py 来玩。

总结一下：Codex 的核心能力就是"听你说话 → 操作你的文件"。所以只要是跟文件打交道的事情，都可以试试让它帮忙。你不需要会写代码，只要会说话就行。

0

命令行入门（完全小白必看）

Codex 是一个运行在命令行（也叫终端 / Terminal）里的工具。如果你从来没用过命令行，别慌，看完这一节就够了。

🤔 命令行是什么？

命令行就是一个用打字代替鼠标点击来操作电脑的工具。你在里面输入一条"命令"，按下回车，电脑就会执行。

比如：

  • 你想打开某个文件夹？在命令行里输 cd 文件夹名 就行（相当于双击文件夹）
  • 你想看文件夹里有什么？输 ls 就行（相当于打开文件夹看一眼）
  • 你想创建一个新文件夹？输 mkdir 文件夹名 就行（相当于右键→新建文件夹）

是不是没那么可怕？其实你只需要会打开它就行，剩下的都可以让 Codex 帮你做。

📖 怎么打开命令行？

方法一：用 Spotlight 搜索（最快）

按 Command + 空格，输入 Terminal（或"终端"），按回车即可打开。

方法二：从应用程序打开

打开 访达(Finder) → 应用程序 → 实用工具 → 双击 终端(Terminal)。

推荐：你也可以下载 iTerm2，它是 Mac 上更好用的终端工具，免费的。不过自带的 Terminal 完全够用。

推荐方式：安装 Git Bash

Codex 在 Windows 上推荐配合 WSL2 或 Git Bash 使用。先去 git-scm.com 下载安装 Git for Windows。

安装时一路点"Next"用默认设置就行。安装完后，在桌面或开始菜单找到 Git Bash 打开。

更佳方式：WSL2（适合进阶）

Codex 在 Windows 上对 WSL2（Windows 里的 Linux 子系统）支持最好。以管理员身份打开 PowerShell，运行 wsl --install 即可安装。

大部分 Linux 发行版按 Ctrl + Alt + T 就能打开终端。

或者在应用菜单中搜索 "Terminal"。

⌨️ 你只需要记住的 5 个命令

以下命令足够你使用 Codex 了，其他的都可以让 Codex 帮你执行。

命令作用举例
cd 目录名 进入某个文件夹 cd ~/Desktop 进入桌面
ls 查看当前文件夹里有什么 ls 列出所有文件和文件夹
pwd 显示你现在在哪个文件夹 pwd → /Users/zhangsan/Desktop
mkdir 名字 创建新文件夹 mkdir my-project 创建项目文件夹
codex 启动 Codex！ 安装好之后输入 codex 即可开始

🎬 命令行操作演示

下面演示一个典型的流程：打开终端 → 进入项目 → 启动 Codex

Terminal
# 第 1 步：看看自己在哪里 $ pwd /Users/zhangsan # 第 2 步：进入桌面 $ cd Desktop # 第 3 步：创建一个项目文件夹 $ mkdir my-project # 第 4 步：进入项目文件夹 $ cd my-project # 第 5 步：启动 Codex（安装好之后才能用） $ codex ╭────────────────────────────────╮ │ OpenAI Codex ready! │ ╰────────────────────────────────╯ ▌

看到 $ 或 % 符号是什么意思？

这是命令行的"提示符"，表示"我准备好了，你可以输入命令了"。你不需要自己打这个符号，直接输入命令就行。本教程中 $ 后面的内容才是你需要输入的。

小白贴心提示：如果你在命令行里输错了，不用怕！按 Ctrl + C 可以取消当前操作，再重新输入就行。命令行不会因为你输错而弄坏电脑。

1

准备工作

在安装之前，请确保你有以下东西：

📦 你需要准备的东西

项目说明怎么获得
电脑 macOS / Linux / Windows 都行 你正在用的就行
终端 就是命令行工具 Mac 自带 Terminal；Windows 用 Git Bash / WSL2
Node.js 18+ npm 安装方式需要（推荐方式） 见下方安装教程
中转站 API Key 用来调用 GPT 模型的密钥 你自己搭的中转站后台获取
中转站 API 地址 中转站的 Base URL（通常到 /v1） 你自己搭的中转站后台获取
CC Switch 管理中转站配置的图形化工具（推荐） 官网 ccswitch.io 免费下载

因为国内无法直接访问 OpenAI 官方服务，所以我们需要通过中转站来使用 GPT 模型。你需要从中转站后台拿到两样东西：

  • API Key（一串密钥字符串，类似 sk-xxxx...）
  • API Base URL（一个网址，本站为 http://159.223.78.34:28046/v1）

没有这两样东西，Codex 是无法工作的。拿到之后，用 CC Switch 填进去即可（见 配置章节）。

我有 ChatGPT Plus/Pro 账号，可以直接用吗？

可以！Codex 原生支持用 ChatGPT 账号登录（codex login），额度直接算在你的订阅里，无需中转站。但登录过程需要访问 OpenAI 官网，国内需要全程翻墙。本教程主要讲不用翻墙的 CC Switch + 中转站 方式，各方式详见 配置章节。

还不知道怎么打开终端？请先看上面的 命令行入门 章节，里面有详细的图文教程。

2

安装 Codex

这是最推荐、最通用的方式！配合国内 npm 镜像源，完全不需要翻墙，一条命令搞定。

先安装 Node.js（如果还没有的话）

npm 是 Node.js 自带的包管理器，所以需要先安装 Node.js（版本 18 以上）。

方法 A：用 Homebrew 安装（推荐）

bash
brew install node

方法 B：去 Node.js 中文官网 下载安装包，双击安装。

去 Node.js 中文官网 下载 Windows 安装包（.msi），双击安装即可。安装时记得勾选 "Add to PATH"。

另外建议安装 Git for Windows 或启用 WSL2，Codex 在类 Unix 环境下体验最好。

bash — Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs

安装好后，验证一下版本：

bash
node -v # 应该显示 v18.x.x 或更高 npm -v # 应该显示 9.x.x 或更高

用 npm 安装 Codex

这是关键的一步。加上淘宝镜像源来安装，完全不需要翻墙：

bash — 一条命令搞定
npm install -g @openai/codex --registry=https://registry.npmmirror.com

这条命令做了什么？

  • npm install -g — 全局安装一个包
  • @openai/codex — Codex CLI 的 npm 包名
  • --registry=https://registry.npmmirror.com — 使用国内淘宝镜像源，不走国外服务器

想永久使用国内镜像？可以把镜像源设为默认，以后装任何 npm 包都走国内：

bash
npm config set registry https://registry.npmmirror.com # 设置好之后，以后就可以直接用： npm install -g @openai/codex

等待安装完成

安装过程可能需要 1-3 分钟（取决于你的网速）。看到类似下面的输出就表示安装成功了：

Terminal
$ npm install -g @openai/codex --registry=https://registry.npmmirror.com added 1 package in 40s $

如果你的 Mac 装了 Homebrew，可以直接用一条命令安装 Codex。

bash
brew install codex

Homebrew 下载有时会走国外服务器、速度较慢。如果卡住，建议改用 npm 国内镜像 方式安装。

Codex 是开源项目，你也可以直接去 GitHub 下载编译好的二进制文件。

前往 GitHub Releases 页面

在浏览器中打开：https://github.com/openai/codex/releases

找到最新版本，下载对应你系统的文件：

你的系统下载哪个文件（示例）
Mac (Apple 芯片 M1/M2/M3/M4)codex-aarch64-apple-darwin.tar.gz
Mac (Intel 芯片)codex-x86_64-apple-darwin.tar.gz
Linux (x64)codex-x86_64-unknown-linux-gnu.tar.gz
Windows (x64)codex-x86_64-pc-windows-msvc.zip

安装二进制文件（Mac/Linux）

bash
# 1. 解压下载的文件（文件名换成你实际下载的） tar -xzf codex-aarch64-apple-darwin.tar.gz # 2. 重命名并移动到系统路径 sudo mv codex-aarch64-apple-darwin /usr/local/bin/codex # 3. 确保可执行权限 chmod +x /usr/local/bin/codex

Windows 用户

解压 .zip 后，把 codex.exe 放到一个方便的位置（如 C:\Program Files\Codex\），然后将该目录添加到系统 PATH 环境变量中。

GitHub 访问慢？可以试试国内的 GitHub 镜像站来加速下载，或者让已经下载好的朋友直接把文件传给你。

验证安装成功

无论用哪种方式安装，安装完成后都运行以下命令验证：

检查版本号

bash
codex --version
Terminal
$ codex --version codex-cli 0.x.x ← 看到版本号就说明安装成功了！

查看帮助（可选）

bash
codex --help

这个命令会列出所有可用的子命令和参数。

安装遇到问题？

  • 提示 npm: command not found — 说明你还没装 Node.js，先装 Node.js 再来
  • 提示 permission denied — 在命令前面加 sudo 重试：sudo npm install -g @openai/codex
  • 下载速度很慢 — 确认你加了 --registry=https://registry.npmmirror.com 走国内镜像
  • codex --version 提示找不到命令 — 关闭终端重新打开试试，或者检查 npm 的全局 bin 路径是否在 PATH 中
3

配置第三方 API（最重要！）

这一步是整个教程最关键的一步！因为我们在国内不能直接登录 OpenAI 账号，所以需要把你的中转站配置给 Codex。如果这一步没搞对，后面什么都用不了。

Codex 的配置写在 ~/.codex/config.toml（TOML 格式）里，手动编辑容易出错。所以强烈推荐用 CC Switch 这个免费图形化工具来管理中转站——填一次、点一下就能启用，还能在多个中转站之间一键切换。

CC Switch 是什么？它是一个开源免费的桌面小工具，专门用来管理 Claude Code、Codex、Gemini 等 AI 工具的"供应商"。你把中转站的地址和密钥填进去，它会自动帮你写好 ~/.codex/config.toml，你完全不用碰配置文件。

下载安装 CC Switch

去官网 ccswitch.io 或 GitHub Releases 下载对应系统的安装包。

用 Homebrew 一条命令安装（推荐）：

bash
brew install --cask cc-switch

或直接从官网下载 .dmg 拖进"应用程序"（已做苹果签名与公证，可放心打开）。

从官网或 GitHub 下载 .msi 安装包双击安装；也有免安装的 .zip 绿色版，解压后直接运行。

  • Debian / Ubuntu：下载 .deb 安装
  • Fedora / RHEL：下载 .rpm 安装
  • Arch：paru -S cc-switch-bin
  • 通用：下载 .AppImage，加可执行权限后运行

切换到 Codex 标签页

打开 CC Switch，顶部有 Claude Code、Codex、Gemini 等几个标签页。点进 Codex 标签页。

新建一个中转站供应商

点击右上角橙色的 「+」 按钮，配置类型选择 「自定义配置 / OpenAI 兼容」。

填写你的中转站信息

按下表填写（这些信息来自你自己搭的中转站）：

字段填什么
名称随便起个好认的名字，如 我的中转-Codex
Base URL本站填 http://159.223.78.34:28046/v1（OpenAI 兼容接口填到 /v1 为止）
API Key中转站给你的密钥（形如 sk-xxxx）
模型（可留空）本站转发 Codex 官方模型，可以不填，Codex 会用默认官方模型；想锁定某个模型再填真实模型名，如 gpt-5.1-codex
推理强度（可选）可设为 high，回答更稳更聪明

最容易踩的坑是 Base URL：结尾要不要 /v1 按中转站要求来，填错就连不上。模型可以留空（本站是官方模型，Codex 会用默认值）；如果你手动填了模型名，一定要是真实存在的，否则会报 model not found。

点「启用」，然后重启终端

填好后保存并点 启用。CC Switch 会自动把配置写进 ~/.codex/config.toml。

关键：切换供应商后必须重启终端（关掉再重开，或退出 codex 重进），配置才会生效。Codex 不像 Claude Code 那样支持热切换。

验证一下

新开一个终端窗口，进入任意项目目录运行 codex，启动画面里的 Model 应该就是你填的模型。也可以在 Codex 里输入 /status 查看当前连接的供应商和模型。

一份中转站，多个工具通用。CC Switch 也能管 Claude Code、Gemini 等。如果你也在用 Claude Code，在对应标签页把同一个中转站再填一次即可（或用"通用供应商"一份配置同步多个工具），以后想切哪个中转站，点一下就行。

CC Switch 采用"最小侵入"设计：它只会帮你改 ~/.codex/config.toml 和 ~/.codex/auth.json 这两个 Codex 原生文件，自己的数据放在 ~/.cc-switch/ 目录，并会自动备份，卸载也不影响 Codex。

如果你不想装图形工具、喜欢直接改文件，也可以手动编辑 ~/.codex/config.toml。原理和 CC Switch 帮你写的内容是一样的。

创建配置文件 config.toml

用终端命令直接创建 ~/.codex/config.toml（把地址和密钥换成你中转站的）：

bash
mkdir -p ~/.codex cat > ~/.codex/config.toml << 'EOF' # 模型可留空：中转转发官方模型时，Codex 会用默认官方模型 # model = "gpt-5.1-codex" # 想锁定某个模型时再取消注释 model_reasoning_effort = "high" # 使用下面自定义的中转站 model_provider = "relay" [model_providers.relay] name = "我的中转站" # 中转站地址，OpenAI 兼容接口填到 /v1 base_url = "http://159.223.78.34:28046/v1" # 从哪个环境变量读取 API Key env_key = "OPENAI_API_KEY" # 接口协议：中转站一般用 chat；OpenAI 官方用 responses wire_api = "chat" EOF

设置 API Key（环境变量）

上面 env_key 写的是 OPENAI_API_KEY，把密钥存到这个环境变量里，一次设置永久生效：

bash — Mac 默认 Zsh；Bash 改成 ~/.bashrc
echo 'export OPENAI_API_KEY="把这里替换成你的中转站密钥"' >> ~/.zshrc source ~/.zshrc

验证配置

bash
cat ~/.codex/config.toml # 看看配置对不对 echo $OPENAI_API_KEY # 看看密钥有没有设进去

🔑 各配置项含义

配置项含义示例值
model（可选）指定模型名；留空则用 Codex 默认官方模型gpt-5.1-codex
model_reasoning_effort推理强度，越高越聪明越慢high
model_provider使用哪个供应商（对应下面的定义）relay
base_url中转站的 API 地址http://159.223.78.34:28046/v1
env_key去哪个环境变量读取 API KeyOPENAI_API_KEY
wire_api接口协议，中转多用 chat，官方用 responseschat / responses

如果你有 ChatGPT Plus / Pro / Team 订阅，可以直接用账号登录，用量算在订阅里、无需 API Key。但登录要访问 OpenAI 官网，国内需要全程翻墙，日常使用也依赖能访问官网。用中转站的话不需要这一步。

运行登录命令

bash
codex login

它会自动打开浏览器，让你登录 ChatGPT 账号并授权。授权成功后终端会提示登录完成，信息保存在 ~/.codex/auth.json。

用 API Key 登录（也需翻墙）

如果你有 OpenAI 官方 API Key，也可以直接用它登录：

bash
codex login --api-key "sk-你的官方密钥"
4

第一次运行

进入你的项目目录

Codex 需要在一个项目目录中运行，这样它才能看到你的代码文件。

bash
# 进入你的项目文件夹（换成你自己的路径） cd ~/my-project # 如果你还没有项目，可以先创建一个测试目录 mkdir ~/test-project && cd ~/test-project

启动 Codex

bash
codex

看到这个画面说明成功了

Terminal — codex
╭────────────────────────────────────────╮ │ OpenAI Codex v0.x.x │ │ │ │ Model: gpt-5.1-codex │ │ 目录: ~/test-project │ ╰────────────────────────────────────────╯ 输入 / 查看可用命令 ▌

出现 ▌ 输入框就表示 Codex 已经准备好了，可以开始对话了！

试着说句话

在输入框里输入你想问的问题，按回车发送：

Terminal — codex
▌ 你好，请用中文介绍一下你自己 codex 你好！我是 Codex，一个运行在终端里的 AI 编程助手。 我可以帮你： • 阅读和理解你的代码 • 编写新的代码文件 • 修复代码中的 Bug • 执行终端命令 • 管理 Git 版本控制 有什么我可以帮你的吗？ ▌

如果启动后报错，请检查：

  • API Key 是否正确（有没有多余的空格或引号）
  • base_url 是否正确（注意 https:// 和结尾的 /v1）
  • 模型名称你的中转站是否支持（在 CC Switch 里核对）
  • 网络是否正常（能否访问你的中转站地址）
  • 在 CC Switch 里改完配置后，有没有重启终端
5

基本对话用法

Codex 的核心用法非常简单：你打字说话，它来干活。下面是一些最常用的场景。

📖 场景一：让它看懂你的项目

Terminal — codex
▌ 帮我分析一下这个项目的整体结构和功能 codex 我来看一下项目结构... 📁 项目结构分析： ├── src/ — 源代码目录 │ ├── App.tsx — 主入口组件（React） │ ├── api/ — 后端 API 接口 │ └── utils/ — 工具函数 ├── package.json — 项目依赖配置 └── README.md — 项目说明文档 这是一个 React + TypeScript 的前端项目，主要功能是...

🔍 场景二：问具体的代码问题

Terminal — codex
▌ src/api/user.ts 这个文件里的 getUserProfile 函数是干嘛的？ codex 我来读一下这个文件... `getUserProfile` 函数的作用是根据用户 ID 从后端获取 用户的个人资料信息。它接收一个 `userId` 参数，然后向 `/api/users/:id` 发送 GET 请求，返回包含用户名、邮箱、 头像等信息的对象。

你可以用 @ 符号直接引用文件，例如输入 解释一下 @src/api/user.ts，Codex 会自动读取这个文件（输入 @ 时通常还有文件名自动补全）。

🐛 场景三：让它修 Bug

Terminal — codex
▌ 登录页面点击登录按钮后没有反应，帮我找一下 Bug codex 让我检查一下登录相关的代码... 找到问题了！在 `src/pages/Login.tsx` 第 42 行： ```tsx // 问题：handleSubmit 函数没有 await 异步调用 const handleSubmit = (e) => { e.preventDefault(); loginAPI(username, password); // ← 缺少 await }; ``` 应该改为： ```tsx const handleSubmit = async (e) => { e.preventDefault(); await loginAPI(username, password); // ← 加上 await }; ``` 要我帮你直接修改这个文件吗？

当 Codex 要修改你的文件时，它会先弹出一个审批框问你同意不同意。用方向键选择、回车确认即可。

6

让 AI 帮你写代码（实战演示）

下面是几个完整的实战例子，展示 Codex 有多强大。

🌟 实战一：从零创建一个 TODO 应用

Terminal — codex
▌ 帮我用 HTML + CSS + JavaScript 创建一个漂亮的 TODO 待办事项应用， 要支持添加、删除、标记完成功能，界面要好看一点 codex 好的，我来为你创建一个完整的 TODO 应用。 📝 新建 index.html 📝 新建 style.css 📝 新建 app.js ✅ 已经创建了 3 个文件： • index.html — 页面结构 • style.css — 样式（渐变背景 + 卡片设计） • app.js — 交互逻辑（增删改查 + 本地存储） 你可以用浏览器直接打开 index.html 查看效果。

🌟 实战二：给现有项目加新功能

Terminal — codex
▌ 给项目加一个暗黑模式切换功能，点击按钮可以在亮色和暗色主题之间切换 codex 我来看看项目现有的样式结构... ✏️ 修改 src/App.tsx (添加了主题切换按钮和逻辑) ✏️ 修改 src/styles/main.css (添加了暗色主题 CSS 变量) ✏️ 修改 src/hooks/index.ts (新增 useTheme Hook) ✅ 暗黑模式功能已添加！ • 页面右上角新增了🌙/☀️切换按钮 • 主题偏好会保存到 localStorage • 默认跟随系统主题设置

🌟 实战三：用自然语言跑命令

Terminal — codex
▌ 帮我安装项目依赖，然后启动开发服务器 codex 我来执行安装和启动命令。 🔧 建议运行: npm install 是否允许？ (方向键选择 → 允许 / 拒绝) added 1247 packages in 32s 🔧 建议运行: npm run dev 是否允许？ → 允许 VITE v5.x.x ready in 420 ms ➜ Local: http://localhost:5173/

注意：在默认审批模式下，执行命令之前 Codex 会征求你的同意，你能看到它要执行什么命令再决定是否允许。

7

常用命令大全

在 Codex 的对话框中，以 / 开头的是内置命令，用来控制 Codex 本身的行为。输入 / 会弹出命令列表。

命令功能使用场景
/init 为当前项目生成 AGENTS.md 让 Codex 更了解你的项目
/model 切换模型和推理强度 想换用更快或更强的模型
/approvals 切换审批 / 沙箱模式 控制 Codex 能自动做多少事
/new 开始一段全新的对话 想开始新的话题
/compact 压缩对话历史 对话太长、token 用太多时
/diff 查看本次改动的 Git diff 想看看 Codex 改了哪些内容
/status 查看当前会话状态、模型、用量 检查配置是否正常
/mcp 查看已连接的 MCP 工具 接入外部工具（GitHub、数据库等）
/mention 引用某个文件（也可直接打 @） 让 Codex 读取指定文件
/quit 退出 Codex 用完了想退出（也可以按 Ctrl+D）

启动时直接带上任务：你可以在启动时就把需求作为参数传进去，Codex 会直接开始干活：

bash
# 启动并直接下达任务 codex "帮我给这个项目写一个 README" # 恢复上一次的会话继续聊 codex resume --last
8

项目记忆：AGENTS.md

AGENTS.md 是一个特殊的文件，相当于给 Codex 的"项目说明书"。把它放在项目根目录，Codex 每次启动时都会自动读取。

小知识：AGENTS.md 是一个通用约定，不止 Codex，很多 AI 编程工具都会读取它。所以写一份，多个工具通用。（Claude Code 用的是 CLAUDE.md，作用类似。）

📝 怎么创建 AGENTS.md？

最简单的方式 — 让 Codex 帮你创建：

在 Codex 中输入
/init

Codex 会自动扫描你的项目，然后生成一个合适的 AGENTS.md。

📄 AGENTS.md 写什么内容？

下面是一个示例模板：

markdown — AGENTS.md 示例
# 我的电商项目 ## 项目概述 这是一个基于 React + Node.js 的电商网站 ## 技术栈 - 前端：React 18 + TypeScript + Tailwind CSS - 后端：Node.js + Express + PostgreSQL - 测试：Jest + React Testing Library ## 常用命令 - npm run dev — 启动前端开发服务器 - npm run server — 启动后端服务器 - npm test — 运行测试 - npm run build — 构建生产版本 ## 目录结构 - src/components/ — React 组件 - src/pages/ — 页面组件 - src/api/ — API 调用函数 - server/routes/ — 后端路由 - server/models/ — 数据库模型 ## 编码规范 - 使用 TypeScript 严格模式 - 组件使用函数式写法 - CSS 使用 Tailwind 类名 - 变量命名用 camelCase - 所有回复请使用中文

记忆层级（从高到低，越靠近项目越优先）：

  • 子目录级 子目录/AGENTS.md — 只对该子目录内的代码生效
  • 项目级 ./AGENTS.md — 整个项目共享的说明（放项目根目录）
  • 全局级 ~/.codex/AGENTS.md — 你个人的偏好（适用于所有项目）
9

切换 AI 模型

Codex 可以使用多个模型，还能调节"推理强度"（想得多不多）。在对话中输入 /model 即可选择。

模型特点适用场景
gpt-5.1-codex 旗舰编码模型，最聪明 复杂问题、架构设计、困难 Bug
gpt-5.1-codex-mini 更快更省，能力略弱 日常小任务、快速查询
其它 GPT 模型 取决于你中转站支持哪些 按需选择

什么是"推理强度"（reasoning effort）？

Codex 的模型可以设置想问题时"用多大脑力"，一般有 low / medium / high 等档位。越高越聪明但越慢越贵，简单任务用低档、难题用高档即可。/model 里可以同时选模型和这个强度。

你也可以在启动时或配置文件里指定：

bash
# 启动时指定模型 codex --model gpt-5.1-codex # 临时覆盖某个配置项（-c 后面跟 key=value） codex -c model_reasoning_effort="high"

或者写进 ~/.codex/config.toml 永久生效：

toml — config.toml
model = "gpt-5.1-codex" model_reasoning_effort = "high"

请确认你的中转站支持哪些模型，不是所有中转站都支持全部模型。如果切换后报错 model not found，八成是中转站不支持该模型名，在 CC Switch 里换一个即可。

10

审批与沙箱（权限管理）

Codex 有一套完善的"审批 + 沙箱"安全机制，可以控制它能自动做什么、什么操作需要先问你。

🔒 它是怎么工作的？

当 Codex 想要执行某个"有风险"的操作（比如修改文件外的内容、联网、跑命令）时，它会先弹出审批框问你：

Terminal — codex
🔧 Codex 想运行: npm install axios 是否允许？ ❯ 允许这一次 本次会话都允许 拒绝并说明原因 ▌

用方向键选择、回车确认。你可以先看清楚它要执行什么命令，再决定放不放行。

⚡ 三种常用模式

在对话中输入 /approvals 可以随时切换模式：

模式说明
只读 (Read Only)Codex 只能读文件、回答问题，任何改动和命令都要你批准。最安全
自动 (Auto)在当前项目目录内可自动读写文件、跑命令；越界操作（联网、动目录外文件）才会询问。日常推荐
完全访问 (Full Access)可读写、可联网、几乎不询问。方便但有风险，谨慎使用

你也可以在 ~/.codex/config.toml 中预设默认模式（approval_policy 控制何时询问，sandbox_mode 控制文件读写范围）：

toml — config.toml
# 何时需要你审批：untrusted / on-failure / on-request / never approval_policy = "on-request" # 文件沙箱范围：read-only / workspace-write / danger-full-access sandbox_mode = "workspace-write"

命令行也能快速切换：codex --full-auto 让它在沙箱内全自动跑（少打扰）；生产环境或不信任的代码请优先用只读或自动模式，别一上来就开完全访问。

11

非交互模式（脚本化使用）

Codex 还可以不进入对话界面，直接用 codex exec 一次性完成任务，适合集成到脚本或自动化流程中。

bash — 一次性执行
# exec 子命令：执行完就退出，不进入交互界面 codex exec "这个项目用了什么技术栈？" # 管道输入：把文件内容传给 Codex 分析 cat error.log | codex exec "帮我分析这些错误日志" # 让它在沙箱内全自动完成（不逐个询问） codex exec --full-auto "给所有函数补上类型注解" # 以 JSON 格式输出，方便脚本解析 codex exec --json "列出所有 API 接口"

codex exec 常用于 CI/CD 或批处理脚本。因为是自动运行、没人盯着审批，建议配合明确的沙箱设置使用，并只在可信代码上运行。

12

IDE 集成（VS Code）

如果你使用 VS Code（或 Cursor、Windsurf 等兼容编辑器），可以安装 Codex 插件，在编辑器内直接使用。

安装 VS Code 插件

打开 VS Code，按 Cmd+Shift+X（Mac）或 Ctrl+Shift+X（Windows），搜索 "OpenAI Codex"，点击安装。

打开 Codex 面板

安装后在 VS Code 侧边栏会出现 Codex 的图标，点击即可打开对话面板。

享受图形化体验

在 VS Code 中使用 Codex 有几个额外好处：

  • 文件修改可以用 并排对比视图 查看
  • 可以直接选中代码片段发给 Codex 提问
  • 终端版和插件版共享同一份配置和会话

VS Code 插件底层还是使用你配置好的 config.toml 和 API Key，所以确保之前的配置已经完成。

13

快捷键速查表

快捷键功能
Esc打断 Codex 正在进行的操作
Ctrl+C取消当前输入 / 中止
Ctrl+D退出 Codex
/唤出内置命令菜单
@引用文件（带自动补全）
↑ / ↓翻看历史输入
Shift+Enter输入换行（多行输入）

不同版本的快捷键可能略有差别。在对话中输入 / 或查看界面底部的提示，能看到当前版本支持的操作。

14

常见问题

Q：启动后提示 "Unauthorized" 或 "Invalid API Key" 怎么办？ ▼

这说明你的 API Key 配置有问题。请检查：

  • API Key 是否完整复制（前后没有多余的空格或换行）
  • 环境变量名要和 config.toml 里的 env_key 一致（默认 OPENAI_API_KEY）
  • 设置完环境变量后有没有 source 或重开终端让它生效
  • API Key 是否还有效（没有过期或欠费）

运行以下命令检查：

bash
echo $OPENAI_API_KEY cat ~/.codex/config.toml
Q：提示 "Connection refused" 或 "404 / Not Found" 怎么办？ ▼

这通常是中转站地址或接口协议不对。请在 CC Switch 的 Codex 供应商里检查：

  • Base URL 是否正确（注意 http/https、结尾要不要 /v1）
  • 模型名你的中转站是否真的支持（写错会报 model not found）
  • 改完记得重启终端再试（Codex 不支持热切换）
  • 中转站是否正常运行，用 curl 你的中转站地址 测一下
  • 手动配置的用户可试试把 wire_api 在 chat 和 responses 之间切换
Q：怎么减少 Token 消耗（省钱）？ ▼
  • 使用 /compact 命令定期压缩对话历史
  • 换个话题时用 /new 开始全新对话，不带旧上下文
  • 简单任务把推理强度调到 low，或换用 mini 模型
  • 用 /status 查看当前会话的用量
  • 尽量一次把需求说清楚，减少来回对话次数
Q：Codex 修改了我的文件，怎么撤回？ ▼
  • 用 /diff 先看看它到底改了什么
  • 如果你的项目用了 Git，可以用 git checkout -- 文件名 恢复单个文件，或 git restore . 撤销全部改动
  • 也可以直接告诉 Codex "撤回你刚才的修改"

强烈建议在 Git 项目里使用 Codex，这样任何改动都能一键回退，最安全。

Q：一定要翻墙才能用吗？ ▼

不一定。如果你用 CC Switch + 中转站（本教程方式一），日常使用连接的是你中转站的地址，通常不需要翻墙。只有当你选择用 ChatGPT 账号登录（方式三）时，才需要全程翻墙访问 OpenAI 官网。

Q：如何让 Codex 用中文回复？ ▼

Codex 会自动根据你的输入语言来回复。如果你用中文提问，它通常会用中文回答。你也可以在 AGENTS.md 中加一行规则：

AGENTS.md
## 语言偏好 - 所有回复请使用中文
Q：如何更新 Codex？ ▼

用哪种方式装的就用对应方式更新：

bash
# npm 安装的： npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com # Homebrew 安装的： brew upgrade codex
Q：Codex 和 Claude Code 有什么区别？ ▼

两者都是命令行 AI 编程助手，用法非常相似。主要区别：Codex 是 OpenAI 出的、用 GPT 模型、配置文件是 ~/.codex/config.toml、项目记忆用 AGENTS.md；Claude Code 是 Anthropic 出的、用 Claude 模型、配置是 settings.json、记忆用 CLAUDE.md。会用一个，另一个上手很快。

15

术语表（看不懂的词看这里）

术语白话解释
终端 / Terminal就是那个黑色的命令行窗口，用来打字执行命令的地方
APIApplication Programming Interface，程序之间沟通的"接口"。这里指调用 GPT 模型的通道
API Key一串密码字符串，证明"你有权使用这个 API"
Base URLAPI 的服务器地址，就像网站的网址一样
TOML一种简单易读的配置文件格式，Codex 的 config.toml 就用它
TokenAI 处理文本的单位。大约 1 个中文字 ≈ 2-3 个 Token。Token 越多，费用越高
模型 / ModelAI 的"大脑"。不同模型有不同的能力和速度
推理强度 / Reasoning Effort模型"想问题用多大脑力"的档位，越高越聪明但越慢越贵
沙箱 / Sandbox一个受限的安全环境，限制 Codex 只能在允许的范围内改文件、跑命令
审批 / ApprovalCodex 做有风险的操作前先问你同不同意的机制
中转站 / 代理 / Proxy中间人服务，帮你转发请求到 OpenAI 的服务器（因为国内直接访问不了）。三个词基本是一个意思
CC Switch一个图形化小工具，用来管理各家中转站配置，一键切换供应商，免去手动改配置文件
环境变量操作系统里的一种全局设置，程序可以读取它（如 OPENAI_API_KEY）
AGENTS.md项目的"说明书"文件，让 Codex 了解你的项目
MCPModel Context Protocol，让 Codex 可以连接外部工具（如 GitHub、数据库等）
Git代码版本管理工具，记录代码的每一次修改，可随时回退
npmNode.js 的包管理器，用来安装 JavaScript 项目的依赖

Codex 小白教程 · 从零到一 · 中文版

本教程内容基于 OpenAI Codex 官方文档整理，仅供学习参考