Codex 入门安装配置使用详细手册：从桌面应用、CLI 到权限模式一次跑通
写在前面
AI 编程工具这两年变化很快。以前大家说“AI 写代码”，许多时候指的是编辑器里补几行、解释一段函数；目前的主流方向已经变成 Agent 工作流：它不只是回答问题，还会读项目、改文件、运行命令、分析报错，甚至接手一整段开发任务。
Codex 就是这类工具里超级典型的一种。它既有桌面应用，也有 CLI，还能接进 IDE。对开发者来说，真正要搞清楚的不是“它会不会写代码”，而是这几个问题：
- • 应该用 Codex 应用、Codex CLI，还是 IDE 插件？
- • 第一次安装到底怎么装？Mac、Linux、Windows 有什么区别？
- • ChatGPT 登录、API Key、auth.json 这几种认证方式怎么选？
- • ask、auto-edit、full-auto 这些审批模式到底有什么差别？
- • 图片、设计稿、报错截图能不能直接丢给 Codex？
- • AI Agent 越来越能干之后，权限和安全该怎么控制？
这篇手册就按“从零到能用”的顺序，把安装、配置、启动和日常使用一次讲清楚。
一、先理解：Codex 可以通过哪些方式使用？
Codex 可以通过多种方式使用。按开发者的使用习惯，大致可以分成五类：
|
安装/使用方式 |
使用场景 |
推荐程度 |
|
Codex 应用 |
直接下载 Codex 应用 |
⭐⭐⭐⭐ |
|
Codex CLI |
在终端使用 |
⭐⭐⭐⭐⭐ |
|
IDE 插件 |
在 VS Code / Cursor 使用 |
⭐⭐⭐⭐ |
|
Homebrew 安装 |
Mac 用户 |
⭐⭐⭐⭐ |
|
GitHub Release 二进制 |
手动安装 |
⭐⭐⭐ |
如果你还没决定怎么用，可以先这样选：
- • 只想快速体验：先用 Codex 应用。
- • 主要写代码、改项目、跑命令：优先用 Codex CLI。
- • 习惯在 VS Code / Cursor / Windsurf 里开发：装 IDE 插件。
- • Mac 用户想省事安装：用 Homebrew。
- • 不想依赖 npm 或包管理器：下载 GitHub Release 二进制。
说白了，Codex CLI 是开发者最常用、也最接近“AI 编程 Agent”的形态。桌面应用适合管理和查看任务，CLI 适合真正进入项目目录干活。
二、方式一：Codex 应用，最简单的入门路线
最简单的方式就是直接使用 Codex 应用。它适合刚上手的用户，也适合你先熟悉 Codex 的界面和基本交互。
访问入口：https://chatgpt.com/codex
进入页面后下载应用：
下载完成后，登录 ChatGPT 账号即可使用。
Codex 应用的界面大体是三栏结构：左侧是任务列表，中间是对话窗口，右侧是多功能区域。
打开应用后，你可以在输入框里直接描述需求：
列如可以这样问：
帮我分析这个项目的结构，并指出主要模块的职责。或者：
我想给这个项目加一个用户注册接口，请先阅读代码，再给出实现方案。如果你只是想熟悉 Codex 的能力，桌面应用就够了；但如果你要让它直接读写本地项目文件、执行命令、跑测试，CLI 会更顺手。
原文提到：如果 Codex 访问和使用有障碍，国内阿里 Qoder Quest 与字节 Trae Solo 也是类似的 AI 开发环境。这里把它作为替代路线参考，不展开做营销推荐。
三、方式二：Codex CLI，开发者最常用的形态
Codex CLI 是一个运行在终端中的 AI 编程代理。它可以做的事情包括：
- • 阅读代码
- • 修改代码
- • 执行 shell 命令
- • 自动修复 bug
- • 分析项目结构
- • 根据设计图或截图生成代码
Codex CLI 在本地运行，因此代码不会被整体上传到云端；一般发送给模型的是 prompt 和必要上下文。对开发者来说，这一点很关键：它既能看本地项目，又不是简单把整个仓库一股脑丢出去。
如果你走 API Key 路线，后面真正影响体验的一般不是 CLI 本身，而是账号、额度和网络稳定性。国内用户不想在这些地方反复折腾的话，可以把 Code80 当成一个更省事的接入入口：CLI 还是原来的 CLI，只是把模型服务换成更容易连上的渠道。
3.1 安装前准备：先确认 Node.js 和 npm
如果你准备用 npm 安装 Codex CLI，需要先有 Node.js，由于 npm 已经包含在 Node.js 里。
Windows：用 Chocolatey 安装 Node.js
先安装 Chocolatey：
# 安装 Chocolatey
powershell -c "irm https://community.chocolatey.org/install.ps1 | iex"安装完成后，重新打开终端，再安装 Node.js：
# 安装 Node.js 24.15.0（已包含 npm）
choco install nodejs --version="24.15.0"验证安装：
node -v
npm -vLinux：推荐用 nvm 管理 Node.js
安装 nvm：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash无需重启终端，直接加载配置：
source ~/.nvm/nvm.sh安装 Node.js 24：
nvm install 24设置为默认版本：
nvm alias default 24验证安装：
node -v
npm -v安装成功后，你应该能看到类似输出：
v24.x.x
11.x.x3.2 使用 npm 安装 Codex CLI
最常见的安装方式是 npm 全局安装：
sudo npm install -g @openai/codex
# 使用国内镜像安装更快
sudo npm install -g @openai/codex --registry=https://registry.npmmirror.com安装完成后运行：
codex如果能进入交互界面，说明安装已经成功。
四、登录 Codex：三种认证方式
首次运行 Codex 需要登录。原文给了三种方式：ChatGPT 登录、API Key 登录、auth.json 文件配置。
4.1 方法一：ChatGPT 登录（推荐）
在终端运行：
codex选择：
Sign in with ChatGPT随后浏览器会打开登录页面。登录完成后，回到终端就能继续使用。
这条路线适合大多数普通用户：不用手动管理 API Key，也不用写配置文件。
4.2 方法二：API Key 登录
如果你是开发者模式，或者希望用 API Key 控制调用，可以配置环境变量。
macOS / Linux 临时设置，只对当前终端会话有效：
export OPENAI_API_KEY="sk-你的API密钥"永久配置可以写入 ~/.bashrc 或 ~/.zshrc：
echo 'export OPENAI_API_KEY="sk-你的API密钥"' >> ~/.zshrc
source ~/.zshrcWindows PowerShell：
$env:OPENAI_API_KEY="sk-你的API密钥"配置后启动，并指定模型：
codex --model gpt-5-codex然后运行：
codex4.3 方法三：auth.json 文件配置
也可以手动编辑认证文件。先创建目录：
mkdir -p ~/.codex写入 API Key：
cat > ~/.codex/auth.json << 'EOF'
{
"OPENAI_API_KEY": "sk-你的API密钥"
}
EOF这种方式适合你希望把 Codex 的认证信息聚焦放在固定目录里，或者需要在脚本、服务器环境里统一管理配置。
不过说实话，官方账号和 API Key 对国内用户不算太友善：账号、支付、网络环境都可能卡住。如果你只是想把 Codex CLI 稳定接进日常开发，也可以看看 Code80，真实订阅帐号转 API，换个 endpoint 就能用，省掉不少环境和账号层面的折腾。
五、第一次运行 Codex：从一个测试项目开始
安装和登录都完成后，提议先建一个小目录测试，不要一上来就扔进大型生产项目。
进入项目目录：
cd my-project启动 Codex：
codex然后输入：
分析下当前的项目结构Codex 会自动做三件事：
- • 扫描代码库
- • 分析项目结构
- • 输出系统架构说明
可以用一个完整测试流程先跑通。先创建目录：
mkdir codex-runoob-test进入目录：
cd codex-runoob-test新建 test.py 文件，代码如下：
print("Hello Runoob!")启动 Codex：
codex第一次启动时，选择第一个 Yes, continue，回车后就可以开始使用 Codex CLI 写代码。
六、启动 Codex：应用和 CLI 的基础操作
6.1 启动 Codex 应用
Codex 的界面是标准三栏结构：左侧任务列表，中间对话窗口，右侧多功能区域。
启动 Codex 应用后，可以在左侧菜单添加项目，中间输入框输入需求：
也可以设置模型或上传文件：
6.2 启动 Codex CLI
安装并配置好账号后，在项目目录下打开终端，输入 codex 即可启动交互式界面：
# 进入你的项目目录
cd ~/my-project
# 启动 Codex 交互界面
codex
# 带初始提示词直接启动
codex "帮我分析这个项目的结构"
# 启动时指定模型
codex --model gpt-5提议在项目根目录下启动 Codex，这样它能完整读取项目文件结构。
Codex 界面很简洁，光标所在处就是输入框，直接输入你的需求即可。
例如进入 codex-runoob-test 目录后启动：
cd codex-runoob-test
# 启动 Codex 交互界面
codex进入交互界面后，可以直接输入需求，列如让它解释 test.py 文件的代码。这些记录也会显示在 Codex App 中：
七、审批模式：必定要搞懂权限边界
Codex 这类工具能读文件、改文件、跑命令，所以权限模式超级重大。实际使用里常常会遇到两套说法：一套是 CLI 的 Approval Mode，另一套是运行模式。可以合并理解为：从“只提议”到“自动执行”，权限越来越大，风险也越来越高。
7.1 Approval Mode：ask、auto-edit、full-auto
|
模式 |
说明 |
适用场景 |
|
ask（默认） |
只读模式：可以读取文件、制定方案，但执行任何操作前都需要你确认 |
陌生代码库探索、风险评估 |
|
auto-edit |
自动编辑：可以读取和修改当前目录文件，但网络操作仍需确认 |
日常代码开发、重构任务 |
|
full-auto |
完全自动：在禁用网络的沙箱中全自动运行，无需确认 |
批量任务、CI/CD 自动化 |
启动时指定审批模式：
# 指定审批模式启动
codex --approval-mode ask # 默认只读模式
codex --approval-mode auto-edit # 自动编辑模式（缩写 -a auto-edit）
codex --approval-mode full-auto # 完全自动模式
# 在交互界面中切换
/approvals # 输入此命令切换审批模式7.2 另一组运行模式：Suggest、Auto Edit、Full Auto
|
模式 |
功能 |
|
Suggest |
只提议修改 |
|
Auto Edit |
自动修改文件 |
|
Full Auto |
自动执行所有操作 |
默认模式：
Suggest切换到自动编辑：
codex --auto-edit切换到完全自动：
codex --full-autoFull Auto 模式可以自动执行代码修复和任务，但我提议新手先不要急着开。更稳的做法是：
- 1. 新项目或陌生代码库，用 ask / Suggest。
- 2. 熟悉项目后，日常开发用 auto-edit / Auto Edit。
- 3. 批量、可回滚、有测试兜底的任务，再思考 full-auto / Full Auto。
八、你的第一次对话：三个实用示例
8.1 示例 1：分析项目结构
codex "分析这个项目的目录结构，告知我主要文件的作用"
# Codex 会自动读取文件，输出类似：
# ✓ 读取 package.json
# ✓ 扫描 src/ 目录（23 个文件）
# 项目结构分析：
# - src/index.ts：应用入口，初始化 Express 服务器
# - src/routes/：API 路由定义（共 5 个端点）
# ...这个场景特别适合接手新项目。你不用先人工翻一遍目录，让 Codex 先扫一遍，再追问重点模块就行。
8.2 示例 2：修复 Bug
codex "我的 login 函数有 bug，用户登录后 token 没有正确保存，帮我找出问题并修复"
# Codex 会：
# 1. 读取相关文件
# 2. 分析代码逻辑
# 3. 提出修改方案
# 4. 等待你确认后执行修改如果你在 ask 模式下，它会先给方案，等你确认再改。这个流程比较适合线上项目，由于不会莫名其妙动文件。
8.3 示例 3：生成新功能
codex "给我的 Express 应用添加一个用户注册接口，需要验证邮箱格式，密码至少8位，并把用户信息存入数据库"
# 传入图片上下文
codex -i design.png "按照这个设计图，实现对应的 React 组件"写新功能时，提议你把约束说清楚，列如接口路径、字段、校验规则、数据库表、测试要求。Codex 能做许多事，但前提是你给它一个明确边界。
九、图片输入：报错截图、设计图、架构图都能用
Codex CLI 支持将图片作为上下文输入，这在下面几个场景特别有用：
- • 分析报错截图
- • 根据 UI 设计图生成前端代码
- • 解读架构图并据此实现功能
常见用法如下：
# 方法一：命令行传入图片路径
codex -i screenshot.png "解释这个报错信息，并告知我如何修复"
# 方法二：传入多张图片
codex --image img1.png,img2.jpg "对比这两个界面的区别，实现图一的设计"
# 方法三：在交互界面中粘贴图片（macOS）
# 复制图片后，在 Codex 输入框中直接按 Cmd+V 粘贴
# 方法四：Shift + 拖拽图片到终端窗口这部分对前端开发尤其有用。你可以把 UI 截图、设计稿、报错弹窗一起丢进去，让 Codex 结合代码分析。
十、方式三：Homebrew 安装（Mac 推荐）
Mac 用户可以使用 Homebrew 安装：
brew install --cask codex安装完成后运行：
codex即可启动。
这种方式适合：
- • Mac 开发者
- • 不想安装 Node.js 的用户
如果你的 Mac 开发环境本来就靠 Homebrew 管理，这条路线会比较省事。
十一、方式四：GitHub Release 二进制安装
如果不想使用 npm，也可以直接下载二进制版本。
下载地址：
https://github.com/openai/codex/releases
常见版本：
Mac Apple Silicon：
codex-aarch64-apple-darwin.tar.gzMac Intel：
codex-x86_64-apple-darwin.tar.gzLinux：
codex-x86_64-unknown-linux-musl.tar.gz下载后解压：
tar -xzf codex-xxx.tar.gz重命名：
mv codex-x86_64-unknown-linux-musl codex加入 PATH：
sudo mv codex /usr/local/bin然后运行：
codex即可使用。
十二、方式五：IDE 插件安装
Codex 还可以在 IDE 中使用，例如：
- • VS Code
- • Cursor
- • Windsurf
- • VS Code forks
安装方式：
- 1. 打开 IDE 插件市场
- 2. 搜索 Codex
- 3. 安装插件
- 4. 登录 ChatGPT 账号
这样就可以在 IDE 内直接使用 Codex，列如：
- • 自动修复代码
- • 自动生成函数
- • 自动重构代码
如果你不想离开编辑器，IDE 插件是最自然的入口；如果你想让它跑命令、跨文件处理复杂任务，CLI 更适合。
十三、更新与卸载
Codex CLI 更新很简单：
codex --upgrade或者：
npm update -g @openai/codex查看版本：
codex --version也可以用 npm 强制重装最新版：
npm install -g @openai/codex@latest卸载：
npm uninstall -g @openai/codexHomebrew 卸载：
brew uninstall --cask codexCodex CLI 目前支持情况：
|
系统 |
支持情况 |
|
macOS |
完整支持 |
|
Linux |
完整支持 |
|
Windows |
实验支持（提议 WSL） |
Windows 用户如果要长期使用 CLI，提议优先走 WSL。这样更接近 Linux 开发环境，许多命令和路径问题会少许多。
十四、安全背景：为什么审批模式很重大？
聊 Codex 这类编程 Agent，绕不开安全问题。它越能干，越需要明确权限边界。腾讯新闻这篇关于 Claude Fable 5 的文章，虽然主角不是 Codex，但它提醒了一个超级现实的问题：强模型不是越自由越好，也不是越保守越好，真正关键的是“可解释、可控制、不过度误伤”。
原文提到，Claude Fable 5 被称为「Mythos 级能力、第一个对公众安全开放的版本」。但上线后，许多普通科学问题也触发拒绝，甚至只是涉及癌症、生命科学、模型研究，就被安全机制拦掉。
列如问“关于癌症的错误信息是怎么在网上传播的”，模型拒绝：
再问癌症有哪些类型，也拒绝：
这类一刀切会带来一个问题：安全本来是为了防止危险使用，但如果分类器太粗糙，正常学习、科研和开发也会被误伤。
原文对 Fable 5 的机制做了一个解释：它与 Mythos 5 共享底层模型，区别是 Fable 外面套了一层“分类器”。分类器不参与回答，只负责检查请求。只要判定触及高风险领域，就强制 fallback 到另一个模型。
这跟 Codex 的权限模式有什么关系？关系很直接：
- • 对模型公司来说，要控制模型能力边界。
- • 对开发者来说，要控制 Agent 在本地项目里的操作边界。
- • 对团队来说，要知道什么时候允许自动编辑，什么时候必须人工确认。
Codex 的 ask、auto-edit、full-auto 本质上就是一套本地开发场景里的安全阀。新手最容易犯的错，是一上来就把权限开满，然后让 AI 在不熟悉的项目里自动改一堆文件。更稳的方式是先让它读、让它解释、让它给方案，再逐步放开编辑权限。
原文还提到，某些模型在前沿 AI 研发、模型蒸馏等请求上，可能不是透明回退，而是“不提示地变笨”。
被抓包后，厂商出来道歉并表明会整改：
这件事对开发者的启发是：AI Agent 的行为必须尽量透明。 它读了什么、准备改什么、为什么要执行命令、是否切换模型或降级能力，都应该让用户知道。
所以，在 Codex 里使用审批模式时，提议记住这几条：
- 1. 陌生项目先只读：先用 ask 分析结构和风险。
- 2. 修改前看 diff：让 Codex 解释它准备改哪些文件。
- 3. 自动模式只给可回滚任务：列如格式化、批量替换、补测试。
- 4. full-auto 要配合测试和版本控制：最好在 git clean 的状态下操作。
- 5. 不要把敏感信息直接塞进 prompt：API Key、私钥、账号密码都不该暴露。
十五、新手推荐工作流：从保守到自动化
如果你是第一次用 Codex，可以按这个顺序来：
第一步：安装并登录
优先选一种你最顺手的方式：
- • 普通用户：Codex 应用 + ChatGPT 登录
- • 开发者：npm 安装 Codex CLI + ChatGPT 登录
- • Mac 用户：Homebrew 安装
- • 服务器或手动环境：GitHub Release 二进制
如果你已经决定长期用 CLI，提议一开始就把“稳定接入”这件事想清楚。官方账号能跑当然最好；如果卡在支付、风控或网络上，用 Code80 这类 API 接入方式会更省心，后面的学习和工作流练习也不容易被环境问题打断。
第二步：用小项目测试
不要直接丢生产仓库。先建一个 codex-runoob-test：
mkdir codex-runoob-test
cd codex-runoob-test创建 test.py：
print("Hello Runoob!")启动：
codex让它解释代码：
解释这个 test.py 文件在做什么，并给我一个改成函数形式的提议。第三步：进入真实项目，先分析不修改
codex --approval-mode ask "分析这个项目结构，列出主要模块、入口文件和潜在风险点"这一步只让它读和分析，不让它动手。
第四步：小范围自动编辑
确认它理解项目后，再让它做小改动：
codex --approval-mode auto-edit "给登录模块补充缺失的单元测试，不要修改业务逻辑"第五步：复杂任务拆小
不要一次说“帮我重构整个系统”。更好的方式是拆成：
- 1. 先分析现状。
- 2. 给重构方案。
- 3. 只改一个模块。
- 4. 跑测试。
- 5. 再继续下一个模块。
这样 Codex 更稳定，你也更容易控制结果。
常见问题
Q: 新手到底应该先用 Codex App 还是 CLI？
A: 如果只是体验功能，先用 Codex App；如果你是开发者，最终必定要熟悉 CLI。CLI 才能在项目目录里读文件、改代码、跑命令。
Q: Windows 能不能用 Codex CLI？
A: 可以，但原文标注 Windows 是实验支持，提议走 WSL。WSL 的路径、shell、包管理和 Linux 更接近，长期使用会更省心。
Q: ask、auto-edit、full-auto 怎么选？
A: 陌生项目用 ask，日常开发用 auto-edit，批量可回滚任务再思考 full-auto。不要一上来就全自动。
Q: API Key 和 ChatGPT 登录哪个更推荐？
A: 普通用户优先 ChatGPT 登录，少折腾；开发者、团队或脚本环境可以思考 API Key 或 auth.json。如果国内环境下官方账号和支付不方便，也可以通过 Code80 这类渠道更省事地接入。
Q: Codex 能看图片吗？
A: 可以。可以用 codex -i screenshot.png “解释这个报错”，也可以传多张图片，或在交互界面里粘贴、拖拽图片。
Q: Codex 会不会直接乱改文件？
A: 取决于你的权限模式。ask 模式会更保守，执行操作前需要确认；auto-edit 可以自动改当前目录文件；full-auto 权限最大，必须谨慎。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
相关文章
暂无评论...
