1. 先说清楚Codex 和 Claude Code 到底是什么先说结论这两个东西不是聊天机器人而是跑了终端里的 AI 编程助手。Codex 是 OpenAI 出的命令行工具主打直接在你项目目录里执行任务、改代码、跑命令Claude Code 是 Anthropic 出的同类工具侧重点在长上下文理解、多文件修改和严谨的代码审查。两者都以 CLI命令行界面为核心交互方式装好之后就能在 Windows 终端里用自然语言指挥 AI 干活。很多刚接触的朋友容易把它们和网页版 ChatGPT、Claude 混淆其实差别很大。网页版是对话AI 给你一段代码你自己复制粘贴这两个是“进场干活”AI 自己遍历你的项目文件、自己跑测试、自己改代码改完给你看 diff。用熟之后效率提升非常明显尤其在处理重构、补测试、排查报错这类事情上。那 Windows 用户为什么会“别折腾”因为这两个工具官方主推的其实是 mac 和 LinuxWindows 上安装虽然能装但会遇到几个典型问题Node.js 版本不够新导致 npm 装不上、终端编码格式不对导致中文乱码、按官方文档装完了命令却找不到、装了 Codex 又发现没法正常登录。这些问题我在实际安装过程中全踩过一遍所以这篇就是把能直接跑通的流程整理出来。这篇文章适合谁两类人。一类是已经在用 VSCode 但想试试 AI 编程助手的开发者跟着步骤做完就能在编辑器里用上另一类是已经装了但被各种报错卡住的用户可以直接跳到文末的排查速查表找答案。2. 先补齐两样基础环境Node.js 与 Git2.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 TerminalWin 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_URLhttp://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 的安装同样走得 npmnpm 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_URLhttp://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 CodeVSCode 接入这两个工具的方式比想象中简单不需要装第三方插件直接用 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.mdCodex 专用。这样每次启动工具时它会把文件内容作为项目上下文加载你不用反复口述背景。我自己的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 工具。我个人习惯是在选中代码后按CtrlShiftC复制文件路径然后在终端里输入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-8chcp 65001VSCode 终端字体换成 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 上折腾这两个工具的朋友看完这篇能少走几个弯路。