Codex CLI 完全指南：终端AI编程代理的安装配置与实战手册

最近把日常编码场景基本都迁到了终端里的 Codex CLI 上，越用越觉得这东西值得写一份完整的参考笔记。Codex CLI 是 OpenAI 官方出品的命令行编程代理——在终端敲一句话，它就能读项目、改代码、跑命令、看报错、再迭代修正，整个过程你只需要做 review。这份笔记不是官方文档的翻译，而是我从安装到日常使用、从默认配置到接入第三方模型、从踩坑到排查的完整记录，重点解决“装好了但不知道怎么写配置”“遇到报错不知道怎么查”这两个高频痛点。适合三类人：第一次听说 Codex CLI 的开发者、装完但只会用默认参数的新手，以及想把它接到更便宜或私有模型上的技术负责人。

1. 从“welcome to codex”说起：终端里的 AI 编程代理到底是什么

1.1 Codex CLI 是什么，为什么选择终端

第一次在终端敲下codex，看到那行Welcome to Codex, OpenAI's command-line coding agent，我就意识到这次思路完全不一样了。它不是在 IDE 里给你补全代码的插件，而是一个能直接操作你电脑的智能体：读文件、改代码、跑测试、装依赖、看报错，全都在当前这台机器的真实环境里完成。

为什么是终端？因为终端对开发者来说是最不需要额外信任成本的地方。VSCode 插件要适配编辑器版本，桌面应用要开 GUI，而终端是每一种操作系统都有的通用入口；更关键的是，不管你是在本地开发、SSH 到服务器、还是写一次性运维脚本，终端都会有。Codex CLI 直接长在这个通用入口上，意味着它天然具备“操作真实环境”的能力，不需要通过编辑器那层间接接口。

1.2 它能做什么、不能做什么

先说能做的。Codex CLI 的核心能力是理解现存代码库，然后直接修改它。你可以让它“给 main.py 加上 argparse 参数”，它会先通读你的文件，判断改动位置，再给出待应用的变更；确认后它真的会写文件。它还能执行 shell 命令，跑pytest或者npm test，看到测试失败输出之后自己分析、自己修，修完再跑一遍验证。

不能做的事情也需要讲清楚。它不是万能的模型本体，而是模型的一个客户端——最终回答质量取决于你配置了哪个模型，以及这个模型对工具调用的支持程度。上下文窗口也有限，一个巨大仓库不可能全部喂进去，它依赖你通过指令文件、会话管理和精准提问把“最重要”的信息暴露给它。最后，如果给的指令太模糊，它一样会写出让 maintainer 生气的代码。本质上它像一个上手速度非常快的远程实习生，方向感需要你把控。

1.3 和 Claude Code 这类工具比，差异在哪

不少朋友问我它和 Claude Code 有什么区别。两者理念几乎同源：都认为未来编程入口是“自然语言 + 终端代理”，而不是又一层 IDE 面板。差异主要在三处：默认模型体系不同（Codex 走 OpenAI 系列，Claude Code 走 Anthropic 系列）；审批与权限机制的成熟度不同，Codex 对“文件写入、命令执行、MCP 调用”三类权限是分开管控的；生态上 Claude Code 社区插件多，Codex 官方迭代速度快。

如果你只打算长期用其中一款，我的建议是别纠结“哪个强”，先看你日常用的 API 是哪个体系。如果你本来就在用 OpenAI 系的模型，或者打算接入各类兼容服务，Codex CLI 的自然语言交互和沙箱机制足够稳。本文后续所有操作都是以 Codex CLI 为基准展开的。

2. 环境准备与安装：先把环境跑起来

2.1 前置依赖：Node.js 与 npm

Codex CLI 是基于 Node.js 构建的，所以第一件事是把 Node 装好。官方要求 Node 18 以上，我的建议是直接用当前 LTS 版本（20 或更新），省得以后遇到兼容性问题。先确认环境：

node -v npm -v

两条命令都能输出版本号，说明基础环境没问题。没有 Node 的话，去官网下载 LTS 安装包即可，macOS 也可以用 Homebrew 装，装完顺手把全局bin路径写进 shell 配置。

为什么这个工具用 Node 而不是 Go、Rust？说白了是生态原因：OpenAI 的 CLI 最开始就是 TypeScript 技术栈，npm 上现成的包多，后续插件的扩展路径也顺。普通用户不需要关心这一点，只要知道“缺 Node 就装不上”就行。

2.2 安装、登录与版本管理

安装就是一条命令：

npm install -g @openai/codex@latest

装完先验证版本：

codex --version

第一次运行codex会引导登录。执行codex login会弹出浏览器窗口，用 ChatGPT 账号完成授权，授权凭证会存到本地。如果你更习惯 API Key 方式，可以在当前 shell 里设置环境变量OPENAI_API_KEY，Codex 会自动读取并使用这个凭证。

登录凭证的位置在~/.codex/auth.json（macOS/Linux）或用户目录下的.codex/auth.json（Windows）。这个文件以后排查登录问题会用到——当授权状态异常时，删掉它重新codex login往往比在网页端折腾更快。

升级和卸载也很简单：

npm update -g @openai/codex npm uninstall -g @openai/codex

现在 Codex 也有桌面版了，习惯 GUI 的朋友可以下载桌面版；但 CLI 在脚本化、自动化和服务器场景里仍然不可替代，这篇笔记聚焦 CLI 方向。

2.3 Windows 环境两个经典坑

Windows 用户最容易栽的第一个坑是 PowerShell 执行策略。很多人执行npm install -g时没问题，一运行codex就报类似 “npm: 无法加载文件 ...npm.ps1，因为在此系统上禁止运行脚本” 的错。这不是 Codex 的问题，而是 Windows 默认禁止执行本地脚本。处理方式：用管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy RemoteSigned

原理是：RemoteSigned允许本机创建的脚本运行，只有从远程下载的脚本才要求签名，对个人开发者来说足够安全又省心。

第二个坑是codex命令找不到。npm 全局包的 bin 目录通常不在 PATH 里，可以执行npm config get prefix查看全局路径，再把<prefix>目录加入系统 PATH。装了 nvm 的同学一般不会有这个问题，因为 nvm 会自动把全局 bin 配好。如果这两个坑都没有，但启动时仍然提示找不到组件，参考第 6 章的排查清单。

3. 配置文件细读：每个参数背后的为什么

3.1 config.toml 的位置与整体结构

Codex CLI 的配置主文件是config.toml，位于~/.codex/config.toml。没有这个文件，Codex 也会用默认值跑起来；但想真正把它调到好用，还是得手动建这个文件。

整体结构分三层。顶层是一堆常规选项，比如默认模型、权限策略、安静模式；接下来是[model_providers.*]表格，每一张表定义一个模型提供方（provider），你可以定义多个；再往下是审批策略、沙箱工作区等更细粒度的权限设置。这个分层的设计思路很清楚：把“选择哪个模型”和“模型从哪里来”解耦，把“能不能做”和“怎么做”分开，这样日常切换模型不会影响权限规则。

强烈建议每一次改完配置都执行codex --help或codex /status确认当前生效的参数，不同版本之间字段名会有细微差异。

3.2 模型与模型提供方配置

默认情况下，Codex 会请求 OpenAI 官方服务。但真正让它变得灵活的是自定义 provider。下面这个配置把 DeepSeek 加进来：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

然后设置环境变量DEEPSEEK_API_KEY，Codex 就会通过base_url指向的兼容端点发请求。

这里有几个参数你必须理解，因为绝大多数对接报错都出在它们身上。

base_url是请求的根地址。Codex 会把对话补全的请求路径拼在后面，所以如果base_url写错了，最常见的错误就是 404 或者连接失败。env_key告诉 Codex 从哪个环境变量读取 API Key，写错了就会一直 401。wire_api则决定用 OpenAI 的哪种协议格式：官方新模型用responses，很多第三方兼容端点只实现了chat（也就是 chat/completions 协议）。如果你的后端只支持chat，你却配成responses，报错就会非常隐晦。切换任何 provider 之后，先用一个最简单的对话验证连通性，再投入真实任务。

3.3 权限与沙箱：把 AI 锁在笼子里

让 AI 在终端里执行命令，信任问题比能力问题更关键。Codex 提供了几个权限档位：

approval_policy = "on-request" # 默认，写文件/执行命令前都会询问 approval_policy = "never" # 不询问，完全自动 approval_policy = "on-failure" # 只在命令执行失败时询问 approval_policy = "unrestricted" # 完全放开，不推荐日常用

我的实际建议是：日常开发锁在on-request，让 AI 每次改文件、跑命令前都先汇报；当你把工作区限定到某个独立实验项目里，再考虑放宽到never。AI 生成的命令有时候看起来合理，实际跑出来的副作用完全不可控，宁可多看一次确认。

同时配合沙箱模式使用。sandbox-mode可以设为read-only（AI 只能读不能写）、workspace-write（只能写当前工作区）、danger-full-access（无限制）。这个机制的价值在于，即使 AI 在会话中产生了“出格”的意图，物理上也动不了工作区以外的文件。

提示：权限和沙箱是 Codex 使用里面最值得花时间理解的部分。把它当成你给实习生开账号时的权限矩阵——开局可以限制得严一点，摸清脾气之后再慢慢放开。

3.4 那些容易被忽略的实用配置

有几个选项平时不起眼，但实际体验差别很大。

quiet可以减少日志输出，适合在自动化脚本里调用 Codex 时使用。autoupdate决定要不要自动更新 CLI 版本，介意新版本行为变化的人可以关掉手动更新。skip_git_repo_check用于允许在非 Git 目录中运行，不过我个人不建议关掉这个检查——Git 仓库是回溯所有 AI 改动的安全网，没有它你很难 diff 看出 AI 动了什么。

还有一个我很看重的机制：项目指令文件。Codex 支持读取项目根目录下的AGENTS.md或CODEX.md作为“项目说明书”，你可以在里面写清构建命令、测试命令、目录结构、代码规范、绝对不做的事。AI 每次开工前会先读它，相当于给 AI 注入项目的背景知识。这一条强烈推荐每个人用起来，收益比想象中大得多。

4. 日常使用全流程：从一句话到一段代码落地

4.1 第一次启动会话与编写第一个任务

在项目目录下直接输入codex，进入交互式会话。界面会提示当前你处于哪个目录、Git 状态如何。

举个例子。假设你有一个 Python 项目，想给main.py增加命令行参数处理，可以这样输入：

给 main.py 加上 argparse 支持，提供 --input 和 --output 两个参数， 默认值分别是 data/in.txt 和 data/out.txt，不要改动其他函数。

Codex 会先读main.py，可能还会看一眼同目录的文件，然后给出它准备做的修改计划，并且因为权限策略是默认的on-request，它会等你确认才真正写文件。这个流程非常关键：AI 在写文件之前，已经先经过“读取-理解-规划-申请”四个阶段。

如果不想进入交互式会话，也可以一次性执行：

codex "给 main.py 加上 argparse，支持 --input 和 --output 参数"

它会直接处理这个请求，但同样会在写文件前等待你确认。

4.2 常用内置命令与会话管理

进入会话后，有几个斜杠命令必须知道：

• /init：让 Codex 扫描当前目录并生成/建议项目的初始配置，适合新项目首次接入。
• /status：查看当前会话状态、已用 token 量、当前模型与工作区范围。
• /model：在会话里临时切换模型，方便对比不同模型的输出质量。
• /help：随时查看内置命令帮助。
• /quit或/exit：退出会话。

会话管理是我非常喜欢的部分。Codex 支持断点续聊：用--resume接续某个历史会话，用--session开启新会话。实际迭代一个功能时，我往往上午让 AI 实现第一版，下午回来--resume让它继续优化，上下文还都保留着，不需要重新交代背景。用codex --list之类的命令可以回看历史会话列表，这一点在长时间项目里非常实用。

4.3 一次完整的“报错→修复”闭环

看一个完整的实操闭环，比零散命令更有参考价值。

第一步，我故意在测试文件里留下一个 bug，然后对 Codex 说“跑一下测试，看哪里挂了”。Codex 执行pytest，终端里出现失败堆栈，它会主动把报错信息读进自己的上下文，然后分析根因。第二步，我说“修好它，但不要改公共接口”，它提出一个修改方案：定位到具体的函数，给出 diff。第三步，我确认后它写入文件，然后我会补一句“再跑一遍测试验证”，它会重新执行测试命令，直到确认通过。

这里重点不在于 AI 一次成功，而在于整个链路是闭环的：发现问题、定位原因、修改代码、运行验证，全部由 AI 在真实环境里完成，你只需要在每个环节做判断。相比“从 IDE 复制报错到网页里问再粘回来”，效率差别非常大。

因为这个流程有实时行为，安全网很重要。我每次开始这类任务前都会确认当前在 Git 仓库内，并且在工作区沙箱限制下运行。即使 AI 做出了不可控的修改，git diff和git checkout能让我一分钟内回滚。

4.4 结合 Git 工作流的协作技巧

Codex 和 Git 结合得好，才算真正融入开发流。

最常见的一个用法是提交信息生成：写完代码后，对 Codex 说“git diff 看一下，帮我生成 commit message，按 conventional commits 风格”。它会先git diff，分析改动内容，再给出几条 commit message 候选。这比手动敲 message 省时间，而且它确实会认真看你到底改了哪些行。

第二个用法是变更自查：对 Codex 说“帮我 review 这次 diff，找出潜在的 bug 或遗漏”。它会把 diff 从头看一遍，指出哪些地方不安全或者逻辑不完整。这种“AI review 自己写的代码”的过程，能在提交前拦截掉很多低级错误。

第三，如果你有远端 issue 文本，直接把 issue 内容粘贴给 Codex，让它“按这个需求实现，然后提交”。它在看 issue 之后开工，产出的代码往往更贴近需求描述。注意它不会自动 push，推送前建议你自己看一下git log和git diff。

5. 第三方模型接入：把 Codex CLI 接到 DeepSeek 等兼容服务

5.1 为什么要换模型，什么时候值得换

Codex CLI 用户里，很大比例都在折腾接入第三方模型，核心驱动力无非三个：成本、速率、可用性。OpenAI 官方模型能力强，但计费对高频入门用户不太友好；第三方兼容服务在 API 价格和并发速率上有明显优势；另外不少团队有内网私有化模型需求，希望把 Codex 的交互层接在自己内部的模型服务上。

Codex CLI 在这件事上做得聪明的地方是：它把“模型提供方”做成了可配置层，只要对方实现了 OpenAI 的chat/completions或responses协议，就能接进来。这不是破解，也不是绕过，而是官方支持的扩展能力。什么时候值得换？如果你每天跑大量类似“生成测试、批量重构”这类任务、对推理能力要求不那么极限，完全可以把高频琐碎任务放在低成本模型上，有硬骨头再切回强力模型。

5.2 DeepSeek 接入配置实战

以 DeepSeek 为例，完整操作如下。

先确认环境变量：

export DEEPSEEK_API_KEY="你的key"

然后修改~/.codex/config.toml：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

保存后，在项目目录跑一次最简单的验证：

codex "1+1等于几？"

能正常回答，说明连接通了；如果报 401，查env_key是否和实际环境变量一致；如果报 404，查base_url是否正确，尤其注意不要多写/v1之类的路径；如果是 400 或协议错误，查wire_api是否匹配。

一个容易被忽略的点：Codex 的很多高级功能，比如“AI 自己运行命令并读取结果”，依赖模型对工具调用（tool calling）的支持程度。第三方模型如果只支持纯文本对话，Codex 就退化成“能改文件但不会自主执行命令”的弱化形态。DeepSeek 这类模型在常见任务上可用，但如果你发现 AI 经常在“我无法直接运行命令”这类回答里打转，大概率就是模型工具调用兼容性不足，这时候要么换模型，要么明确告诉它你手动执行命令后把结果贴给它。

5.3 用 cc switch 管理多套配置

当我有“官方模型”“低成本模型”“团队内网模型”几套不同配置之后，手动改config.toml就会变得很痛苦。社区里有个开源工具叫 cc switch，专门做 Codex（以及 Claude Code）的多配置管理，核心功能是保存多份配置和凭证，一键切换，并验证新配置能否连通。

cc switch 的原理不复杂：它会在你的~/.codex目录下维护多套配置模板，切换时替换config.toml和相关鉴权文件，并检测当前环境变量。但它不会碰你的代码，也不会上传任何东西。实际使用中，我遇到最多的问题反而是切换之后忘了刷新环境变量——shell 里还保留着旧 provider 的 key，新 provider 根本读不到。切换完先执行env | grep -i api看一眼环境变量，再跑一条测试命令，能少踩很多坑。

注意：第三方的配置管理工具更新节奏不一，如果切换后出现类似“handling codex endpoint /responses failed”的报错，优先检查新配置的 base_url、api key、wire_api 三者是否匹配，不要第一时间怀疑工具坏了。

6. 常见问题速查与避坑实录

6.1 安装与启动问题

codex命令找不到。npm 全局包的 bin 目录不在 PATH 里。执行npm config get prefix，把输出目录加入系统 PATH。注意改完要重新开终端才会生效。

PowerShell 提示无法加载脚本。如 2.3 节所述，用管理员权限执行Set-ExecutionPolicy RemoteSigned。

提示 unable to locate the codex cli binary or required runtime components。这个报错通常说明安装不完整或运行时组件缺失。第一优先做法：卸载后重新安装最新版：

npm uninstall -g @openai/codex npm install -g @openai/codex@latest

然后再codex --version验证。如果还不行，检查是否用了比较老的 Node 版本，尽量升级到 20+ 再试。

npm 安装太慢或反复失败。把 npm registry 切换为国内镜像服务，然后重新安装。装完之后再跑一次codex --version确认。

6.2 登录与鉴权问题

codex login无法完成授权。先看浏览器是否能正常打开授权页；如果授权页打不开，大概率是网络环境问题。也可以删掉~/.codex/auth.json后重新登录，清掉可能损坏的本地凭证。

一直 401 unauthorized。检查环境变量是否真的设置成功：echo $OPENAI_API_KEY（macOS/Linux）或echo $env:OPENAI_API_KEY（Windows PowerShell）。如果用了自定义 provider，检查env_key配置的变量名是否和实际一致。

403 forbidden。通常是 API Key 没有访问指定模型的权限，或者该模型在你当前网络环境中不可用。换一个模型名试试，或者确认 Key 对应的账号是否有该模型访问权。

6.3 请求与连接问题

切换配置后报错 handling codex endpoint /responses failed。这是很常见的对接类报错。按顺序排查：先确认base_url是否可达，用curl探一下端点；再确认wire_api和你所用的后端是否匹配；接着看环境变量里 key 是否被正确读取；最后用最简 prompt 跑一遍连通测试。如果自定义配置没问题，再考虑是不是 cc switch 这类切换工具没把旧环境变量清理干净。

请求返回乱码或中英文错乱。终端编码问题。Windows 下使用 Windows Terminal 并设置 UTF-8 编码，macOS/Linux 一般不会出现。

返回内容经常被截断。上下文窗口不够用。要么精简项目说明，把无关文件排除；要么用--model切换上下文更大的模型；也可以把一个大任务拆成多个小会话，每个会话聚焦一个文件或一个功能。

6.4 功能行为问题与排查思路

AI 尝试修改我不想动的文件。权限策略没有限制住工作区。建议开启沙箱read-only或workspace-write，同时用自然语言明确告诉它“只允许改动 src 目录下的文件，其他地方一律不要碰”。

每次写文件都询问太多，效率低。如果你已经在一个实验性项目里摸清了 AI 的行为规律，可以临时把approval_policy调整为on-failure甚至never；但切回正式项目时记得调回来。反复在多个项目间切换时，推荐维护两份配置或借助 cc switch 快速切换。

终端卡住，敲不出字母。大多数情况是会话中有命令在等待输入。先尝试Ctrl+C中断当前操作，不行就Ctrl+D退出会话重新进入。Windows 下尽量用 Windows Terminal，而不是老旧控制台，输入和编码体验会好很多。

AI 的改动在 git 中无法追踪。这通常是因为你在非 Git 目录运行了 Codex。建议要么把项目初始化成 Git 仓库，要么至少备份一份目录快照再去跑自动化修改任务。没有版本管理兜底的 AI 改代码，风险等级直接上一个台阶。

把上面这些整理成一个速查表：

最后分享几点我个人在实际使用中的体会。Codex CLI 用得好不好，和三件事强相关：权限设置要在开工前想清楚，项目指令文件要写清楚，每次让 AI 改动前先说明可验收的边界条件。我长期只在on-request模式下让它自动改文件，验证过多轮之后才敢在特定项目里放开权限，这个流程别嫌麻烦。另外，强烈建议在项目里维护一份AGENTS.md——把构建命令、测试命令、格式化规范、绝对禁忌写进去，AI 每次开工前先读一遍，整个体验会提升一个量级。这一条不在官方入门文档的显眼位置，但实测收益最大。先写到这，等踩到新坑再回来补。