1. 先说清楚：Codex 和 Claude Code 到底是什么
先说结论：这两个东西不是聊天机器人，而是跑了终端里的 AI 编程助手。Codex 是 OpenAI 出的命令行工具，主打直接在你项目目录里执行任务、改代码、跑命令；Claude Code 是 Anthropic 出的同类工具，侧重点在长上下文理解、多文件修改和严谨的代码审查。两者都以 CLI（命令行界面）为核心交互方式，装好之后就能在 Windows 终端里用自然语言指挥 AI 干活。
很多刚接触的朋友容易把它们和网页版 ChatGPT、Claude 混淆，其实差别很大。网页版是对话，AI 给你一段代码你自己复制粘贴；这两个是“进场干活”，AI 自己遍历你的项目文件、自己跑测试、自己改代码，改完给你看 diff。用熟之后效率提升非常明显，尤其在处理重构、补测试、排查报错这类事情上。
那 Windows 用户为什么会“别折腾”？因为这两个工具官方主推的其实是 mac 和 Linux，Windows 上安装虽然能装，但会遇到几个典型问题：Node.js 版本不够新导致 npm 装不上、终端编码格式不对导致中文乱码、按官方文档装完了命令却找不到、装了 Codex 又发现没法正常登录。这些问题我在实际安装过程中全踩过一遍，所以这篇就是把能直接跑通的流程整理出来。
这篇文章适合谁？两类人。一类是已经在用 VSCode 但想试试 AI 编程助手的开发者，跟着步骤做完就能在编辑器里用上；另一类是已经装了但被各种报错卡住的用户，可以直接跳到文末的排查速查表找答案。
2. 先补齐两样基础环境：Node.js 与 Git
2.1 为什么非要先装这两个
Codex 和 Claude Code 的安装方式都是通过 npm 全局安装，而 npm 是 Node.js 自带的包管理器。也就是说你电脑上没有 Node.js，后面一切免谈。这里要特别提醒：官方要求 Node.js 版本不低于 18，推荐 20 LTS 或更高，版本太老会出现安装时报错或者运行时崩溃。
Git 则是因为这两个工具在做代码修改时需要读取仓库状态、生成 diff 对比。哪怕你的项目没有推到远程仓库，本地只要是一个 Git 仓库，AI 就能正确识别新增、删除、修改，它的工作质量会高很多。建议顺手把 Git 装上，后面很多项目操作都依赖它。
装 Node.js 的建议是去官方中文站下载 LTS 版本，不要下载 Current 版本。LTS 是长期维护版，稳定；Current 是最新版，问题多。下载之后一路 Next 安装即可，默认配置足够用。Git 同理，官方 Windows 版本默认安装一路 Next，足够用。
安装完成后打开 Windows Terminal（Win 11 自带，Win 10 可以装微软商店版本），输入下面三条命令验证：
node -v npm -v git --version能正常输出版本号就说明环境没问题。这里有个小细节：如果输入命令提示“无法识别”，大概率是安装时没有勾选加入 PATH，重装一次并确保勾选“Add to PATH”即可。如果 node 有版本但 npm 没有，可能是代理环境变量冲突，等下会专门说。
2.2 给 npm 换一个国内可用的镜像源
这一步不是必须的，但国内网络下默认源安装速度很慢，甚至直接超时。我的做法是一开始就直接指定国内镜像，省得装到一半卡住。命令行执行：
npm config set registry https://registry.npmmirror.com设置完之后可以用npm config get registry确认是否生效。这个操作只影响 npm 下载包的来源，不影响其他任何功能，可以放心设置。装完这些基础工具，后面才有条件谈 Codex 和 Claude Code 的安装。
3. 安装 Codex：一条命令的事，但有几个必踩的坑
3.1 全局安装与版本验证
安装方式很简单，终端里执行：
npm install -g @openai/codex这里的-g表示全局安装，安装完成后系统里就有了一个codex命令。装完后运行：
codex --version如果输出版本号就说明安装成功。我实测用的是 Windows 11 + Node 20 LTS，整个过程不到一分钟。如果在执行npm install -g时看到权限错误（比如 EPERM、EACCES），先在终端里执行npm config get prefix看全局目录，如果指向了系统盘 Program Files 是常见原因，建议用管理员身份打开终端再装。
装好之后先不急着登录官方账号，因为接下来要讨论一个国内用户最常见的拦截点：如何通过本地 API 网关接入不同模型服务。
3.2 用本地网关打通 Codex 的模型端点
Codex 默认会连接 OpenAI 官方的模型 API 端点，但国内网络环境下访问不畅。解决思路不是去折腾网络，而是用一个本地 API 网关工具，把不同来源的模型 API 封装成一个统一地址，Codex 只需要指向本地地址即可。
这里我用了一个开源工具叫 CALAO，它的作用是把 Anthropic 格式的请求转成 OpenAI 格式，或者反过来，同时支持多个后端模型服务。安装方式同样 npm 全局安装：
npm install -g @calao/cli装完后启动它，让它监听本机某个端口（比如 8787）。随后配置 Codex 指向这个本地端点：
codex switch local设置环境变量OPENAI_BASE_URL=http://127.0.0.1:8787/v1，再设置OPENAI_API_KEY为你用的后端服务提供的密钥。这里要理解一下原理：Codex 客户端本身只认识 OpenAI 兼容格式，CALAO 在本地充当了一个翻译和转发层。你只管给 Codex 一个本地地址和任意一个有效密钥，剩下的由 CALAO 拿这个密钥去请求真实后端。
这个过程有点绕，但拆开看其实不难：
- 启动 CALAO 网关，配置好后端接入信息。
- 设置 Codex 环境变量，让所有请求都打给
127.0.0.1:8787。 - Codex 发出 OpenAI 格式请求，CALAO 收到后转成对应格式发给后端，拿到结果再返回给 Codex。
这样配置的额外好处是，你不会在 Codex 的配置里暴露真实密钥，密钥只存在本地的 CALAO 配置中，安全性更高。如果你是自建服务或者使用各类模型平台的 API，都是同样的接入逻辑。
3.3 Codex 的模型选择与使用模式
安装配置完成后，在项目目录里运行codex就进入交互模式了。首次使用会让你选择模型，可以用方向键选择列表里的模型并按回车确认。平时启动也可以直接指定：
codex --model gpt-5这里用一个我习惯的工作流：在项目根目录启动 Codex，输入“帮我加上单元测试，覆盖率目标是 80%”这类指令。Codex 会自己读取项目文件结构、分析现有代码、动手写测试文件，然后运行测试命令给你看结果。整个过程它都会输出正在执行的命令和结果，相当于你有一个自动操作脚手架的同事。
更重要的是 Codex 有审批机制，默认情况下执行任何可能修改文件的命令前都会征得你的同意。如果你觉得反复确认太烦琐，可以启动时加--dangerously-skip-permissions跳过所有权限询问，但我强烈建议刚开始用的时候保留默认模式，看看 AI 会执行哪些命令，确认它能正确理解你的意图后再开跳过权限模式。
4. 安装 Claude Code：登录认证与第三方 API 接入
4.1 npm 安装与登录认证
Claude Code 的安装同样走得 npm：
npm install -g @anthropic-ai/claude-code装完后在终端运行claude就能进入初始化向导。这里和 Codex 最大的不同是认证方式。Claude Code 本身设计上是配合 Claude 订阅或 Anthropic API 使用的，官方登录流程是打开浏览器完成身份验证。如果你有对应订阅或者 API Key，直接按提示走即可。
如果你当前网络无法完成官方登录，也可以走 API Key 模式。设置环境变量：
set ANTHROPIC_API_KEY=你的密钥然后再运行claude，它会直接采用 API Key 认证方式。但我实测下来，新版 Claude Code 对 API Key 模式的请求频率限制比较严格，尤其是那种单轮对话任务量大、连续生成代码的场景，容易出现 429 限流报错。如果你确实有官方订阅，登录使用体验会好很多。
4.2 通过 ANTHROPIC_BASE_URL 接入第三方模型服务
很多人没有 Claude 官方订阅，但想用 Claude Code 这个工具本身的文件操作、长上下文管理、多文件编辑能力。这个时候不需要官方 Key，只需要一个兼容 Anthropic 协议的后端服务。
配置思路和 Codex 那边其实异曲同工：设置环境变量指向你的后端地址：
set ANTHROPIC_BASE_URL=http://127.0.0.1:8787 set ANTHROPIC_AUTH_TOKEN=任意可用token然后运行claude，它会通过这个地址发请求。这里要注意的是：不同的后端服务对协议兼容程度不一样，有的支持工具调用，有的只支持纯文本对话。Claude Code 强的就是工具调用能力，如果后端不支持的话，它能对话但不能操作文件，体验大打折扣。建议先跑一个简单任务测试工具调用是否正常，比如问“读取当前目录下有哪些文件”，如果它能正常列出文件列表，说明工具链路是通的。
我一直觉得 Claude Code 最精华的部分是对大项目的理解能力。它在项目里会自动维护一个上下文系统，能把多个文件的内容组织成结构化的记忆，后续对话直接引用，不需要重复读一遍。这也是为什么它比直接在网页上复制代码更高效——它真的像一个能记住整个项目状态的成员。
4.3 模型选择与工作模式设置
Claude Code 模型选择比 Codex 灵活一些。官方提供多个模型名称，启动时可以加参数指定：
claude --model claude-sonnet-4-20250514如果你接入的是第三方服务，模型名以服务商提供的为准。我第一次接入 deepseek 兼容 Claude 协议的模型时，直接用模型名deepseek-chat就能跑通，挺省心的。后来我发现很多兼容服务在模型名上有细微区别，有的要求带版本号，有的要求不带，这个只能看后端服务的文档。
工作模式上 Cloude Code 有三种：默认模式、自动接受模式、计划模式。默认模式会询问文件修改；自动接受模式通过--dangerously-skip-permissions开启；计划模式通过--plan开启，AI 只做分析和规划不执行任何修改。我遇到复杂需求时喜欢先开计划模式让它拆解任务，确认方案没问题再用默认模式逐步执行，相当于给 AI 装了一个“先想清楚再动手”的开关。
5. VSCode 接入：让两个 CLI 工具真正融进开发环境
5.1 在 VSCode 里启动 Codex 与 Claude Code
VSCode 接入这两个工具的方式比想象中简单，不需要装第三方插件，直接用 VSCode 集成的终端就行——当然前提是工具已经全局安装过。
打开 VSCode，按Ctrl+`打开终端，如果之前安装成功，此时直接输入codex或claude就能看到交互界面。这里有两个核心技巧：
- 建议为项目单独创建工作区，终端默认在项目根目录打开。如果项目不在当前目录，先用
cd 项目路径切换再启动工具，避免 AI 读错目录范围。 - VSCode 终端里支持富文本输出，工具打印的彩色 diff、日志、表格都能正常显示。如果发现显示异常，检查 VSCode 设置里的
terminal.integrated.defaultProfile.windows，确保默认终端是 PowerShell 7 或 Windows Terminal，老旧的 ConHost 会有限制。
我是把终端拆成左右两个 pane，左边跑 Codex 帮我看测试和重构，右边跑 Claude Code 帮我在长对话里追踪问题。用下来发现这种组合意外地顺手，Codex 适合那种“快速动手改”的场景，Claude Code 适合“翻遍整个项目找问题”的场景。
5.2 配置工作区文件提升使用体验
如果你希望 AI 每次启动时自动了解项目背景，可以在项目根目录创建CLAUDE.md文件（Claude Code 专用）或.codex/instructions.md（Codex 专用）。这样每次启动工具时它会把文件内容作为项目上下文加载，你不用反复口述背景。
我自己的CLAUDE.md大致长这样：
# 项目说明 这个项目是一个基于 Vue 3 + Vite 的中后台管理前端。 # 常用命令 - 安装依赖: npm install - 启动开发环境: npm run dev - 运行测试: npm test # 编码规范 - 组件命名使用 PascalCase - 样式优先使用 CSS Modules - 提交信息遵循 conventional commits 规范有了这个文件之后，Claude Code 在写新组件时能自动遵守项目约定，少了很多“你忘记加 loading 状态”“你没有按规范命名”这类反馈。Codex 那边同理，把.codex/instructions.md建好后，每次进入项目都会自动加载，等于给 AI 写了一份使用手册。
另外一个实用技巧是在 VSCode 的keybindings.json里加一个快捷键，快速让代码文件在终端中打开对应的 AI 工具。我个人习惯是在选中代码后按Ctrl+Shift+C复制文件路径，然后在终端里输入codex 文件路径直接定位，比一步步cd快不少。
5.3 终端显示中文乱码的根源与解法
Windows 终端最头疼的问题就是中文乱码，尤其是 AI 返回的内容里混有中文时，屏幕上经常出现各种乱码符号。原因在于 Windows 的代码页默认是 GBK，而 npm 装出来的工具输出的是 UTF-8。解决办法分两步：
- 在 VSCode 设置中把终端编码改为 UTF-8：搜索
terminal.integrated.defaultProfile.windows后，在同级设置里找files.encoding，设为utf8（默认就是）。如果输出仍然乱码，在终端执行：
chcp 65001这个命令把当前控制台代码页临时切换为 UTF-8。实测下来大部分乱码都能解决。
- 如果切换代码页后仍然乱码，检查 PowerShell 的
$PROFILE文件中是否设置了旧的系统默认编码，有的话一并清理掉。还有一种情况是，工具输出的特殊字符 Windows 终端字体不支持，可以在 VSCode 设置里把terminal.integrated.fontFamily设为Cascadia Mono或JetBrains Mono，这俩对 Unicode 符号的支持比较全。
我在知乎上看到不少朋友被乱码劝退了，其实就这一步的设置问题，调完终端显示就跟 mac 上一样好看。
6. 常见问题排查速查表与避坑指南
6.1 热里面出现频率最高的几个报错
我整理了一下这段时间在各平台看到的高频报错，直接做成表格方便对照：
| 报错现象 | 主要原因 | 解决办法 |
|---|---|---|
cc switch local proxy failed while handling codex endpoint /responses | 本地网关地址配置错误，或者网关没有正常启动 | 确认网关确实在监听 8787 端口；检查环境变量OPENAI_BASE_URL是否包含/v1后缀；换一个本地端口并同步修改两端配置 |
npm ERR! code EPERM | 全局安装目录权限不足 | 用管理员身份打开终端重新执行安装命令；或者手动修改 npm prefix 到用户目录 |
claude: 无法识别命令 | 环境变量 PATH 未包含 npm 全局目录 | 执行npm config get prefix查看全局目录，把那个路径加到系统 PATH |
| 中文乱码 | Windows 代码页不识别 UTF-8 | chcp 65001；VSCode 终端字体换成 Cascadia Mono |
| 模型请求超时 | 后端服务响应慢或网络问题 | 确认后端服务状态；检查ANTHROPIC_BASE_URL/OPENAI_BASE_URL是否写错协议；增大超时时间（如果有配置项） |
429 rate limit exceeded | 请求频率超出限制 | 降低任务密度，让工具多次对话而不是一次性塞大量内容；或者更换认证方式 |
| 选择模型时列表为空 | 后端网关没有正确返回模型列表 | 检查网关配置中后端模型的model_id是否填写正确；网关版本太旧可升级 |
6.2 一个真实的排查案例：本地代理报错
很多人遇到的cc switch local proxy failed while handling codex endpoint /responses这个报错，它写的是 “proxy failed”，但实际跑排查以后你会发现并不是本地网关失效，而是 Codex 在向本地网关发请求时，带了错误路径。
看报错里出现codex endpoint /responses，说明 Codex 是按 OpenAI 新版 Responses API 格式在请求。如果本地网关只实现了老版的 Chat Completions 接口，它会报路由错误。解决办法是升级网关版本，或者在后端服务的配置里看看有没有切换 API 格式的开关。我用的版本在升级之后这个问题就消失了，目前跑得很稳。
6.3 三条实测下来的避坑心得
第一，别在项目目录的路径里带中文或空格。虽然 Windows 默认支持，但 Codex 和 Claude Code 在解析文件路径时偶尔会出错。我的一个项目路径是D:\学习资料\project，结果 Claude Code 读文件时把中文路径转义乱了，后来我把所有 AI 项目的目录统一改成英文和短横线，再没出现过路径类问题。
第二，谨慎使用--dangerously-skip-permissions。我踩过一次坑：让 Codex 帮忙清理无用文件，开了跳过权限模式后它把一组看起来“好像没用但实际是配置备份”的 JSON 文件全删了。后来恢复起来非常麻烦。这个参数不是不能用，而是要在你确认项目已经提交到 Git、可以随时回滚的情况下才开。
第三，控制单次任务量，别让 AI 一次干太多事。我一开始习惯把一堆需求一次性丢给 Claude Code，结果它到后面就“忘了前面”——虽然它有指标上下文窗口，但实际执行时会陷入混乱。后来我的做法是拆成小任务：先让它分析现状、接着让它出方案、再让它动第一处代码、最后单独让它跑测试。每步都确认结果，稳定度明显提升。
6.4 进阶用法：用 CLAUDE.md 和项目记忆控制 AI 行为
Claude Code 的CLAUDE.md不仅能写项目信息，还能写团队规范和工具偏好。比如你有固定的代码风格，不希望 AI 改代码时引入新套路，可以直接在文件里写 “禁止引入新的 UI 组件库”、“所有错误处理必须使用 try-catch 并返回统一格式”。它每次对话都会读这个上下文，比你和它反复口头强调可靠得多。
Codex 那边对应的文件是.codex/instructions.md，一样的效果。某种程度上，这两个工具的水平上线不是模型本身，而是你写了多好的项目说明文件。AI 的知识停留在训练数据里，但你的项目说明能给它实时的、针对你项目的额外上下文——写清楚这个文件，工具的使用体验会翻倍。
最后补一个实操小技巧
每次打开终端输入codex或claude太繁琐。我加了个自定义命令：在 PowerShell 里用函数封装，直接用ai codex和ai claude就能进入对应的工具，并且自动读取当前目录。代码随手放这里：
function ai-codex { codex --model gpt-5 } function ai-claude { claude --model claude-sonnet-4-20250514 } Set-Alias cx ai-codex Set-Alias cc ai-claude把这个配置写进$PROFILE，重开终端就生效。仪式感少了，顺手程度大幅增加。希望在 Windows 上折腾这两个工具的朋友，看完这篇能少走几个弯路。
