Codex CLI 是 OpenAI 推出的终端编程智能体(agent):你给它一个目标,它会自己读代码、改文件、跑命令并验证结果,而不只是陪你聊天。读完本文你就能在 Windows / macOS / Linux 上装好、登录、用自然语言派活,并用审批模式守住安全边界。
一、Codex CLI 到底是什么
简单说,它是一个直接住在你终端里的编程搭档。和只会给建议的聊天机器人不同,Codex CLI 能读取整个代码仓库、自己编辑文件、运行命令、跑测试修复问题。它也不是只有命令行这一种形态——同一套能力还覆盖 VS Code / Cursor 插件、桌面端应用、以及云端版 Codex Web,你可以在它们之间无缝切换。本篇聚焦最核心也最常用的命令行版本 Codex CLI。
二、先选接入方式(两种,先想清楚)
动手安装前,先决定你走哪条路——这决定了后面「登录」那一步怎么填。
方式一:用 ChatGPT 账号登录(官方,推荐有额度的用户)
Codex 底层能力包含在 OpenAI 的订阅里。如果你已经是 ChatGPT Plus / Pro / Team / Enterprise 用户,订阅里已经包含了 Codex 的使用额度,无需额外付费。第一次启动选「用 ChatGPT 账号登录」即可,最省事。中途环境或登录异常时,运行 codex doctor 会自动检查并给出提示。
方式二:国内用 API 接入(适合无 OpenAI 账号 / 国内网络)
如果官方登录不便,也可以单独配置 API 密钥。国内有不少中转/接入服务把链路整理好了,例如 LetAiCode:在其「接口密钥」页面创建新密钥,密钥类型务必选 codex 分组(选错分组会无法调用),再把密钥和配置写进本地文件即可。下文安装完成后会给出完整配置文件。
三、安装 Codex CLI(Windows / macOS / Linux)
三平台前置都一样:Node.js 22+ 与 npm 10+。任选一种安装方式,通常几十秒装完。
Windows
- 前置:装 Git Bash(从 git-scm.com 下载,一路下一步)。很多人后续命令行不顺,往往是这一步环境没补齐。
- 装 Node.js:去 nodejs.org 下最新 LTS 版。
- 打开 CMD 或 PowerShell 运行:
npm install -g @openai/codex
- 验证:
codex --version 能输出版本号即成功。
macOS
推荐 Homebrew:brew install node,再 npm install -g @openai/codex;或直接去 Node.js 官网下 LTS 版。验证同样用 codex --version。
Linux(Ubuntu / Debian / CentOS / Arch)
Ubuntu/Debian:sudo apt update && curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs;
CentOS/RHEL/Fedora 用 sudo dnf install nodejs npm;
Arch 用 sudo pacman -S nodejs npm。
随后 sudo npm install -g @openai/codex。
四、登录与配置
官方账号登录
终端输入 codex 启动,首次会让你登录,选「ChatGPT 账号登录」走完授权即可进入交互界面。
国内 API 配置(写两个文件)
如果用方式二(API 密钥),在项目用户目录下建 .codex 文件夹,写入两个文件(已有内容直接覆盖):
auth.json
config.toml
说明:model_reasoning_effort 可选 high / medium / low(思考努力程度);想用更新模型把 model 改成 gpt-5.4 即可。改完配置记得重启终端再启动。
五、第一次真正使用它
进入交互模式后,Codex 就站在你的项目根目录里待命。你像和同事说话一样用自然语言提需求即可:
- 先让它熟悉项目:「解释一下这个代码库」——它会自动浏览相关文件,返回清晰的结构说明。
- 重点看某个文件:输入 @ 符号直接引用具体文件或目录。
它真正强大的地方在于会动手:「帮我修复登录页的报错」、「给这个函数补一组单元测试」——Codex 会自己定位文件、写出改动、再跑命令验证。整个过程你都能在终端里实时看到它在想什么、做什么。
六、三种审批模式:守住安全边界
既然它能改文件、能跑命令,安全就格外重要。Codex 提供三种审批模式:
| | |
|---|
| 可在项目目录内读写文件、运行命令;遇到联网等高风险操作先停下来征求同意 | |
| | |
| | |
任何时候,在对话里输入 /permissions 就能随时切换。建议新手保持默认自动模式,遇到敏感操作再手动放行。
七、让效率翻倍的 6 个技巧
/model:随时切换模型,日常推荐用最新 GPT 模型。
/review:写完代码让它像审查者一样通读改动、挑出问题。
-i:把设计稿或报错截图直接喂给它(如 codex -i bug.png "按这个报错修一下"),让它看着图改。
codex resume:关掉终端也不怕,下次接着上一次对话继续。
codex exec "任务":非交互方式跑完直接输出结果,适合写进脚本和 CI 持续集成。
- AGENTS 说明文件:在项目根目录放一个
AGENTS.md 写清项目规范,Codex 每次都会自动参考。
八、VS Code 插件与桌面客户端
配置好 CLI 后,还能在 VS Code 扩展商店搜 codex 安装插件,它会出现在侧边栏,并复用同一套配置。桌面客户端(Codex Desktop)配置方式与 CLI 一致;若桌面端不读取配置,通常是路径没指对——在「设置 → 配置 → Custom config.toml settings」里把 user config 指向你配置的文件路径即可。
九、常见问题排查
| |
|---|
| 密钥是否选对 codex 分组;额度是否够;国内网络优先用已整理好链路的接入服务 |
| Windows 下文件是否放在当前用户目录的 .codex;目录是否被系统隐藏;auth.json 与 config.toml 是否真的创建成功且覆盖了旧内容 |
| |
| 模型名是否写对(如 gpt-5.3-codex / gpt-5.4),复制时是否多了空格、少了引号 |
常见问题 FAQ
Q1 · Codex CLI 收费吗?
A:用 ChatGPT 账号登录时,Plus / Pro / Team / Enterprise 订阅已含额度,不额外收费;走 API 密钥则按所用模型计费。
Q2 · 国内没有 OpenAI 账号能用吗?
A:可以,单独配置 API 密钥(如国内接入服务 LetAiCode),按上文写两个配置文件即可。
Q3 · 只读模式和自动模式差别大吗?
A:只读模式完全不改动你的项目,只做分析与建议;自动模式默认即可读写运行,遇到高风险操作再征求同意。新手建议先用自动模式。
Q4 · 手机上能用吗?
A:Codex CLI 是命令行工具,需在桌面系统(Windows / macOS / Linux)的终端里运行;移动端可用云端版 Codex Web。
Q5 · AGENTS.md 必须写吗?
A:非必须,但强烈推荐——写上项目规范后,Codex 每次都会自动参考,输出更贴合你的工程约定。
Q6 · 关掉终端对话会丢吗?
A:不会,下次运行 codex resume 可续接上一次对话。