Codex 入门安装配置使用详细手册：从桌面应用、CLI 到权限模式一次跑通 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这些审批模式到底有什么差别图片、设计稿、报错截图能不能直接丢给 CodexAI 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# 安装 Chocolateypowershell-cirm https://community.chocolatey.org/install.ps1 | iex安装完成后重新打开终端再安装 Node.js# 安装 Node.js 24.15.0已包含 npmchoco install nodejs--version24.15.0验证安装node-vnpm-vLinux推荐用 nvm 管理 Node.js安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh|bash无需重启终端直接加载配置source~/.nvm/nvm.sh安装 Node.js 24nvminstall24设置为默认版本nvmaliasdefault24验证安装node-vnpm-v安装成功后你应该能看到类似输出v24.x.x 11.x.x3.2 使用 npm 安装 Codex CLI最常见的安装方式是 npm 全局安装sudonpminstall-gopenai/codex# 使用国内镜像安装更快sudonpminstall-gopenai/codex--registryhttps://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 临时设置只对当前终端会话有效exportOPENAI_API_KEYsk-你的API密钥永久配置可以写入~/.bashrc或~/.zshrcechoexport OPENAI_API_KEYsk-你的API密钥~/.zshrcsource~/.zshrcWindows PowerShell$env:OPENAI_API_KEYsk-你的API密钥配置后启动并指定模型codex--modelgpt-5-codex然后运行codex4.3 方法三auth.json 文件配置也可以手动编辑认证文件。先创建目录mkdir-p~/.codex写入 API Keycat~/.codex/auth.jsonEOF { OPENAI_API_KEY: sk-你的API密钥 } EOF这种方式适合你希望把 Codex 的认证信息集中放在固定目录里或者需要在脚本、服务器环境里统一管理配置。不过说实话官方账号和 API Key 对国内用户不算太友好账号、支付、网络环境都可能卡住。如果你只是想把 Codex CLI 稳定接进日常开发也可以看看 Code80真实订阅帐号转 API换个 endpoint 就能用省掉不少环境和账号层面的折腾。五、第一次运行 Codex从一个测试项目开始安装和登录都完成后建议先建一个小目录测试不要一上来就扔进大型生产项目。进入项目目录cdmy-project启动 Codexcodex然后输入分析下当前的项目结构Codex 会自动做三件事扫描代码库分析项目结构输出系统架构说明可以用一个完整测试流程先跑通。先创建目录mkdircodex-runoob-test进入目录cdcodex-runoob-test新建test.py文件代码如下print(Hello Runoob!)启动 Codexcodex第一次启动时选择第一个Yes, continue回车后就可以开始使用 Codex CLI 写代码。六、启动 Codex应用和 CLI 的基础操作6.1 启动 Codex 应用Codex 的界面是标准三栏结构左侧任务列表中间对话窗口右侧多功能区域。启动 Codex 应用后可以在左侧菜单添加项目中间输入框输入需求也可以设置模型或上传文件6.2 启动 Codex CLI安装并配置好账号后在项目目录下打开终端输入codex即可启动交互式界面# 进入你的项目目录cd~/my-project# 启动 Codex 交互界面codex# 带初始提示词直接启动codex帮我分析这个项目的结构# 启动时指定模型codex--modelgpt-5建议在项目根目录下启动 Codex这样它能完整读取项目文件结构。Codex 界面很简洁光标所在处就是输入框直接输入你的需求即可。例如进入codex-runoob-test目录后启动cdcodex-runoob-test# 启动 Codex 交互界面codex进入交互界面后可以直接输入需求比如让它解释test.py文件的代码。这些记录也会显示在 Codex App 中七、审批模式一定要搞懂权限边界Codex 这类工具能读文件、改文件、跑命令所以权限模式非常重要。实际使用里经常会遇到两套说法一套是 CLI 的 Approval Mode另一套是运行模式。可以合并理解为从“只建议”到“自动执行”权限越来越大风险也越来越高。7.1 Approval Modeask、auto-edit、full-auto模式说明适用场景ask默认只读模式可以读取文件、制定方案但执行任何操作前都需要你确认陌生代码库探索、风险评估auto-edit自动编辑可以读取和修改当前目录文件但网络操作仍需确认日常代码开发、重构任务full-auto完全自动在禁用网络的沙箱中全自动运行无需确认批量任务、CI/CD 自动化启动时指定审批模式# 指定审批模式启动codex --approval-mode ask# 默认只读模式codex --approval-mode auto-edit# 自动编辑模式缩写 -a auto-editcodex --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 模式可以自动执行代码修复和任务但我建议新手先不要急着开。更稳的做法是新项目或陌生代码库用ask/Suggest。熟悉项目后日常开发用auto-edit/Auto Edit。批量、可回滚、有测试兜底的任务再考虑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修复 Bugcodex我的 login 函数有 bug用户登录后 token 没有正确保存帮我找出问题并修复# Codex 会# 1. 读取相关文件# 2. 分析代码逻辑# 3. 提出修改方案# 4. 等待你确认后执行修改如果你在ask模式下它会先给方案等你确认再改。这个流程比较适合线上项目因为不会莫名其妙动文件。8.3 示例 3生成新功能codex给我的 Express 应用添加一个用户注册接口需要验证邮箱格式密码至少8位并把用户信息存入数据库# 传入图片上下文codex-idesign.png按照这个设计图实现对应的 React 组件写新功能时建议你把约束说清楚比如接口路径、字段、校验规则、数据库表、测试要求。Codex 能做很多事但前提是你给它一个明确边界。九、图片输入报错截图、设计图、架构图都能用Codex CLI 支持将图片作为上下文输入这在下面几个场景特别有用分析报错截图根据 UI 设计图生成前端代码解读架构图并据此实现功能常见用法如下# 方法一命令行传入图片路径codex-iscreenshot.png解释这个报错信息并告诉我如何修复# 方法二传入多张图片codex--imageimg1.png,img2.jpg对比这两个界面的区别实现图一的设计# 方法三在交互界面中粘贴图片macOS# 复制图片后在 Codex 输入框中直接按 CmdV 粘贴# 方法四Shift 拖拽图片到终端窗口这部分对前端开发尤其有用。你可以把 UI 截图、设计稿、报错弹窗一起丢进去让 Codex 结合代码分析。十、方式三Homebrew 安装Mac 推荐Mac 用户可以使用 Homebrew 安装brewinstall--caskcodex安装完成后运行codex即可启动。这种方式适合Mac 开发者不想安装 Node.js 的用户如果你的 Mac 开发环境本来就靠 Homebrew 管理这条路线会比较省事。十一、方式四GitHub Release 二进制安装如果不想使用 npm也可以直接下载二进制版本。下载地址https://github.com/openai/codex/releases常见版本Mac Apple Siliconcodex-aarch64-apple-darwin.tar.gzMac Intelcodex-x86_64-apple-darwin.tar.gzLinuxcodex-x86_64-unknown-linux-musl.tar.gz下载后解压tar-xzfcodex-xxx.tar.gz重命名mvcodex-x86_64-unknown-linux-musl codex加入 PATHsudomvcodex /usr/local/bin然后运行codex即可使用。十二、方式五IDE 插件安装Codex 还可以在 IDE 中使用例如VS CodeCursorWindsurfVS Code forks安装方式打开 IDE 插件市场搜索Codex安装插件登录 ChatGPT 账号这样就可以在 IDE 内直接使用 Codex比如自动修复代码自动生成函数自动重构代码如果你不想离开编辑器IDE 插件是最自然的入口如果你想让它跑命令、跨文件处理复杂任务CLI 更适合。十三、更新与卸载Codex CLI 更新很简单codex--upgrade或者npmupdate-gopenai/codex查看版本codex--version也可以用 npm 强制重装最新版npminstall-gopenai/codexlatest卸载npmuninstall-gopenai/codexHomebrew 卸载brew uninstall--caskcodexCodex CLI 目前支持情况系统支持情况macOS完整支持Linux完整支持Windows实验支持建议 WSLWindows 用户如果要长期使用 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 里使用审批模式时建议记住这几条陌生项目先只读先用ask分析结构和风险。修改前看 diff让 Codex 解释它准备改哪些文件。自动模式只给可回滚任务比如格式化、批量替换、补测试。full-auto 要配合测试和版本控制最好在 git clean 的状态下操作。不要把敏感信息直接塞进 promptAPI Key、私钥、账号密码都不该暴露。十五、新手推荐工作流从保守到自动化如果你是第一次用 Codex可以按这个顺序来第一步安装并登录优先选一种你最顺手的方式普通用户Codex 应用 ChatGPT 登录开发者npm 安装 Codex CLI ChatGPT 登录Mac 用户Homebrew 安装服务器或手动环境GitHub Release 二进制如果你已经决定长期用 CLI建议一开始就把“稳定接入”这件事想清楚。官方账号能跑当然最好如果卡在支付、风控或网络上用 Code80 这类 API 接入方式会更省心后面的学习和工作流练习也不容易被环境问题打断。第二步用小项目测试不要直接丢生产仓库。先建一个codex-runoob-testmkdircodex-runoob-testcdcodex-runoob-test创建test.pyprint(Hello Runoob!)启动codex让它解释代码解释这个 test.py 文件在做什么并给我一个改成函数形式的建议。第三步进入真实项目先分析不修改codex --approval-mode ask分析这个项目结构列出主要模块、入口文件和潜在风险点这一步只让它读和分析不让它动手。第四步小范围自动编辑确认它理解项目后再让它做小改动codex --approval-mode auto-edit给登录模块补充缺失的单元测试不要修改业务逻辑第五步复杂任务拆小不要一次说“帮我重构整个系统”。更好的方式是拆成先分析现状。给重构方案。只改一个模块。跑测试。再继续下一个模块。这样 Codex 更稳定你也更容易控制结果。常见问题Q: 新手到底应该先用 Codex App 还是 CLIA: 如果只是体验功能先用 Codex App如果你是开发者最终一定要熟悉 CLI。CLI 才能在项目目录里读文件、改代码、跑命令。Q: Windows 能不能用 Codex CLIA: 可以但原文标注 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权限最大必须谨慎。