全网最全Codex CLI 使用教程:从安装到精通的实战指南

你有没有过这种感觉——写代码写到一半，突然想不起某个API怎么用了？或者调试了半天，就是找不到bug在哪？

以前你可能得打开浏览器、搜索文档、翻Stack Overflow，一套流程下来十几分钟没了。现在不一样了，Codex CLI 了解一下。

这是OpenAI官方出的命令行编程助手，装在终端里，直接跟你对话，让它帮你读代码、写代码、调试代码。最骚的是，它真的能动手改你的文件——不是只会说"你应该这样写"，而是直接帮你把活干了。

我用了大半年，真心觉得这玩意儿是程序员必备神器。今天这篇，全网最全的Codex CLI使用教程，从安装到进阶，一条龙给你讲清楚。

一、先搞懂这玩意是什么

说白了，Codex CLI就是一个跑在终端里的AI编程搭档。它能干的事情特别多：

代码生成——你描述需求，它帮你写代码；代码解释——丢一段看不懂的代码进去，它给你讲得明明白白；Bug修复——把错误信息扔给它，它直接定位问题并修复；项目重构——让它分析代码结构，给出改进建议；命令生成——"帮我写个shell脚本处理这些文件"，一句话的事。

跟普通的ChatGPT聊天不一样，Codex CLI能直接操作你的项目文件。它会读取代码、修改代码、执行命令——你批准了它才动，完全受你控制。

支持的系统有macOS、Linux，Windows的话建议用WSL。官方说Windows原生也能跑，但稳定性嘛……你懂的。

二、安装前必看：Node.js环境

Codex CLI是基于Node.js开发的，所以装之前得先把Node.js安排好。最低要求是Node.js 20以上，低于这个版本直接报错。

检查一下你机器上有没有装、装的什么版本：

node -v
npm -v

如果输出了版本号（比如v20.x.x），说明Node.js已经就位。如果提示"command not found"，或者版本低于20，就得先装一下。

各系统安装Node.js

macOS用户——两种方式：

方式一，去官网下载macOS安装包，双击安装，全程无脑下一步；

方式二，如果你用Homebrew（强烈推荐程序员装一个），一条命令搞定：

brew install node

Linux用户——以Ubuntu/Debian为例：

sudo apt update
sudo apt install -y nodejs npm

不过系统自带的版本可能比较老，建议用nvm（Node Version Manager）来管理多版本，会灵活很多：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install --lts
nvm use --lts

Windows用户——直接去官网下载Windows安装包，勾选"Add to PATH"这个选项，装完验证一下版本号对不对就行。

三、安装Codex CLI：三秒搞定

Node.js搞定之后，安装Codex CLI就是一条命令的事。

npm安装（跨平台通用）：

npm install -g @openai/codex

Homebrew安装（macOS/Linux推荐）：

brew install codex

安装完成，验证一下：

codex --version

能看到版本号输出，就说明装好了。如果提示找不到命令，可能需要重启一下终端，或者检查npm的全局路径有没有加到PATH里。

还有一个更骚的方式——直接从GitHub下载二进制文件。适合那些不想装npm的朋友：

# macOS Apple Silicon
curl -L https://github.com/openai/codex/releases/latest/download/codex-aarch64-apple-darwin.tar.gz | tar xz
mv codex-aarch64-apple-darwin /usr/local/bin/codex

# Linux x86_64
curl -L https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz | tar xz
mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

四、认证登录：两种方式任选

装好之后，第一次运行codex会提示你登录。有两种方式，看你适合哪种：

方式一：用ChatGPT账号（推荐）

如果你有ChatGPT Plus/Pro/Business/Edu/Enterprise订阅，直接OAuth登录就行。运行：

codex

然后选择"Sign in with ChatGPT"，它会打开浏览器让你授权。这种方式最省心，而且能用到OpenAI最新的模型。

方式二：用API Key

没有ChatGPT订阅？没关系，准备一个OpenAI API Key也能用。

首先创建一个配置文件：

mkdir -p ~/.codex
touch ~/.codex/auth.json

编辑auth.json，把你的API Key填进去：

{"OPENAI_API_KEY": "sk-your-api-key-here"}

然后在~/.codex/config.toml里指定认证方式：

preferred_auth_method = "apikey"

改完记得重启终端，让配置生效。

这里提一嘴，用API Key是按量计费的，适合轻度使用或者自己有OpenAI账号的朋友。如果你是ChatGPT订阅用户，用OAuth登录明显更划算——Plus会员每个月送的Usage基本够用。

五、核心命令详解

这是重点部分，码住慢慢看。

1. codex：交互模式（最常用）

直接输入codex启动，它会进入一个全屏的终端界面，你可以在里面跟AI对话、让它帮你写代码、改文件。

codex

也可以直接加初始任务：

codex "解释一下这个项目的架构"
codex "修复登录页面的bug"
codex "帮我在auth目录下加个JWT验证"

2. codex exec：非交互模式（自动化必备）

不想进交互界面？想把它集成到CI/CD流程里？用exec：

codex exec "解释utils.ts里的正则表达式"

exec模式会直接输出结果，不会有TUI界面。进度信息输出到stderr，最终结果输出到stdout，方便你用管道传给其他工具。

如果你想输出JSON格式（方便程序处理）：

codex exec --json "分析代码库的架构" | jq

还可以输出到文件：

codex exec --output-last-message result.txt "生成release notes"

3. codex resume：恢复会话

跟Codex聊了一半要去开会？下次回来继续：

# 恢复最近一次会话
codex resume --last

# 或者指定session ID
codex resume 7f9f9a2e-1b3c-4c7a-9b0e-123456789abc

Session ID可以从/status命令或者~/.codex/sessions/目录里找到。

4. codex completion：Shell自动补全

装了这个，敲命令的时候按Tab能自动补全，体验会好很多：

codex completion bash    # 生成Bash补全脚本
codex completion zsh     # 生成Zsh补全脚本
codex completion fish    # 生成Fish补全脚本

把生成的脚本加到你的shell配置文件里就可以了，比如：

# ~/.zshrc 里加一行
source <(codex completion zsh)

六、常用参数：让你的效率翻倍

参数用得好，效率嘎嘎高。

指定模型 -m/--model：

codex -m gpt-5-codex "重构这个组件"

默认会用官方推荐的模型，但你也可以手动指定，比如用GPT-4或者最新的GPT-5。

审批模式 -a/--ask-for-approval：

codex -a "修改数据库连接配置"

这个参数控制Codex什么时候需要你确认。可选值有：

• • untrusted：每次操作都确认
• • on-failure：失败了才确认
• • on-request：只有你明确要求才确认
• • never：完全放权，不确认

全自动模式 --full-auto：

codex --full-auto "创建一个todo-list应用"

开启这个模式，Codex会自己生成代码、安装依赖、运行测试、提交代码，全程不需要你盯着——适合那种明确知道要什么、只是想让它快速搞定场景。

图片输入 -i/--image：

codex -i screenshot.png "修复这个UI问题"
codex --image img1.png,img2.png "分析这两个截图"

上传截图给Codex看，特别适合UI调试、报错截图分析这些场景。

指定工作目录 -C/--cd：

codex -C ./backend "重构认证服务"

不用先cd过去，直接用这个参数指定工作目录。它会把这个目录作为"工作根目录"，Codex只会在这个目录范围内操作，不会乱跑。

沙箱模式 --sandbox：

codex --sandbox read-only "分析这个项目"
codex --sandbox workspace-write "写代码"
codex --sandbox danger-full-access "随便搞"

控制Codex的权限范围。read-only只读不写，workspace-write默认模式只动工作目录里的文件，danger-full-access是完全放权——这个参数主要是为了安全，生产环境慎用。

添加额外目录 --add-dir：

codex --add-dir /path/to/shared-libs "用这些库重构"

有时候你的项目依赖其他目录的文件，用这个参数给它们加权限。

七、配置文件：让你的Codex更懂你

Codex的配置文件有两个：config.toml和AGENTS.md。

config.toml：全局配置

路径是~/.codex/config.toml，控制Codex的行为：

# 指定默认模型
model = "gpt-5-codex"

# 指定审批模式
approval_mode = "auto-edit"

# 禁用遥测
disable_telemetry = true

# MCP服务器配置（后面会讲）
[mcp_servers.database]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sqlite"]

你还可以创建多个配置profile，用--profile切换：

codex --profile work "处理工作项目"
codex --profile personal "搞自己的side project"

AGENTS.md：给Codex的指令文件

这个文件厉害了——你可以写一些项目规范、技术栈说明、工作流程偏好，Codex每次启动都会自动读取这些内容。

Codex会从上到下合并多个AGENTS.md文件，优先级是：

1. 1. ~/.codex/AGENTS.override.md（最高优先级）
2. 2. ~/.codex/AGENTS.md（全局配置）
3. 3. 项目目录/.codex/AGENTS.md（项目级配置）
4. 4. 项目目录/AGENTS.md（项目根目录）

举个例子，在你的项目根目录创建一个AGENTS.md：

# 项目说明

这是一个React + TypeScript项目，使用Vite构建。

## 代码规范

- 组件用函数式组件 + Hooks
- 样式用CSS Modules
- 所有API调用封装到`/src/api/`目录

## 提交规范

- 提交前必须运行`npm run lint`和`npm test`
- commit message用Conventional Commits格式

这样Codex每次处理这个项目，都会自动遵循这些规范，不用每次都重复交代。

八、MCP集成：让Codex连接一切

MCP（Model Context Protocol）是Codex的扩展接口，可以让Codex连接各种外部工具和服务。

查看已配置的MCP服务器：

codex mcp list

添加一个新的MCP服务器：

codex mcp add sqlite "npx" "-y" "@modelcontextprotocol/server-sqlite"

这样Codex就能直接操作SQLite数据库了，比如：

codex "在SQLite里创建一个users表"

社区里有很多现成的MCP服务器，比如GitHub、文件系统、数据库、API调用等，需要什么功能直接搜一下就行。

九、实战案例：这些场景用Codex超爽

说几个我日常高频使用的场景，你感受一下：

场景1：接手遗留项目

刚入职或者接了一个新项目，一脸懵。丢给Codex：

codex "详细分析这个代码库的结构、用的技术栈、主要模块，以及数据流向"

它会帮你梳理整个项目，比你自己啃快10倍。

场景2：写单元测试

写了业务代码，不想手写测试：

codex "为auth目录下所有模块生成单元测试"

Codex会自动推断测试框架，生成测试用例，还会运行验证。

场景3：代码重构

要升级技术栈或者改架构：

codex "把这个类组件改成函数组件 + Hooks，然后用React 18的新特性重构"

Codex会帮你改代码、改引用、改测试，一步到位。

场景4：Bug修复

遇到报错，截图或者贴错误信息给它：

codex -i error-screenshot.png "修复这个报错"
codex "Cannot read property 'map' of undefined这个错误怎么修"

场景5：生成脚手架

想快速验证一个想法：

codex --full-auto "用Express + TypeScript创建一个REST API，包含用户CRUD接口"

全自动模式，代码生成、依赖安装、代码运行，一条命令全搞定。

场景6：安全审计

codex "审查这个代码库的安全漏洞，输出报告"

Codex会扫描常见的安全问题，比如SQL注入、XSS、敏感信息泄露等。

十、常见问题：避坑指南

Q1：codex command not found？

先确认安装成功了：npm list -g @openai/codex。如果装了但找不到，可能是npm全局路径没加到PATH里。检查一下：

npm config get prefix

把这个路径下的bin目录加到PATH里就好了。

Q2：一直连不上/超时？

国内直连OpenAI可能会遇到网络问题。可以试试配置代理，或者用API中转服务。确保base_url配置正确，而且改完配置要重启终端。

Q3：权限报错 EACCES？

Linux/macOS上npm全局安装需要权限。用sudo：

sudo npm install -g @openai/codex

或者配置npm使用用户目录，避免权限问题：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Q4：配置了API Key但还是401未授权？

两个检查点：

1. 1. auth.json格式要对：{"OPENAI_API_KEY": "sk-xxx"}
2. 2. config.toml里要设置preferred_auth_method = "apikey"

改完一定要重启终端，光关掉窗口不算重启。

Q5：怎么升级Codex CLI？

npm update -g @openai/codex
# 或者指定最新版本
npm i -g @openai/codex@latest

Q6：Windows上找不到.codex文件夹？

Windows上要显示隐藏文件夹：在资源管理器里点"查看" → 勾选"隐藏的项目"。或者直接Win+R，输入%USERPROFILE%回车，就能看到.codex目录。

十一、进阶玩法：Git工作流

强烈建议在用Codex之前先打一个Git checkpoint，方便回滚：

git add -A && git commit -m "codex before task"

让Codex干完活，如果效果不对：

git checkout .
git reset --soft HEAD^

直接回到任务前的状态。这种"Codex + Git"的组合拳，用起来特别踏实。

十二、总结

来，帮你划个重点：

安装：一条npm命令，三秒钟搞定
认证：ChatGPT订阅用户推荐OAuth，API Key适合轻度使用
核心命令：codex（交互）、codex exec（自动化）、codex resume（恢复会话）
效率参数：--full-auto（全自动）、-a（审批模式）、-C（指定目录）
配置文件：config.toml控制行为，AGENTS.md注入项目规范
安全习惯：用Git checkpoint，随时可回滚

Codex CLI不是那种"装完就吃灰"的工具，它是真正能融入日常开发流的效率利器。我现在每天敲代码都开着它，写测试、调Bug、做重构，能省的力气绝不多花。

现在就去装一个试试吧，三分钟装完，用它解决你现在最头疼的那个问题。相信我，用一次你就回不去了。