每次在技术群里看到有人晒 Codex CLI 和 Claude Code 的操作视频底下总有 Windows 用户哀嚎“又用不了”。其实这俩工具在 Windows 上没那么难搞只是默认会遇到几个坑Node 版本不对、PowerShell 执行策略挡脚本、终端编码乱掉、环境变量不生效……这些破事单独看都很小但叠在一起就劝退了一大半人。我这几年在 Windows 上把 Codex 和 Claude Code 都跑通了日常用它们写脚本、改 bug、做代码重构电脑就是一台普通的 Windows 笔记本没有特殊的网络环境也没有装第三方终端模拟器。这篇文章把我完整的安装配置流程和踩坑记录整理出来从零开始带你把这两个命令行 AI 编程工具装好再把 VSCode 集成起来。全程只讲 Windows 用户关心的细节适合刚接触命令行 AI 工具的新手也适合已经在 Mac 上用过、想在 Windows 里复刻同样体验的人。1. 动手之前先想清楚Codex 和 Claude Code 到底在解决什么问题1.1 两个工具的本质终端里的 AI 编程代理Codex CLI 是 OpenAI 出的开源命令行编程工具本质是一个跑在终端里的 AI 编程代理。你给它一句自然语言指令比如“帮我修复当前项目里的内存泄漏”它会自己去读文件、搜索代码、分析上下文然后给出修改方案经过你确认后直接改文件。它甚至可以执行 shell 命令来跑测试、查日志像一个坐在你旁边、能直接操作你电脑的实习生。Claude Code 是 Anthropic 推出的同类产品对应 Claude 等模型定位也是 AI coding agent。它同样支持读写代码、执行命令、多文件修改但它有一个很有用的设计项目根目录放一个CLAUDE.md文件Claude Code 每次启动都会自动读取这个文件把里面写的项目规范、编码约定、禁止事项都当成“工作手册”。你的项目越复杂、规范越多这个文件带来的提升越明显。Codex 那边对应的机制是AGENTS.md理念类似只是命名不同。这两个工具解决的是同一个核心问题从“人写代码、AI 补全”变成“人指挥、AI 干活”。它们不像 Cursor 那样只是一个编辑器插件而是深入到终端里可以操作整个项目文件系统。这也是为什么 VSCode 接入教程会成为热门需求——VSCode 强大的编辑器界面和它们俩的终端能力正好互补。1.2 为什么 Windows 上安装容易出岔子很多报错并不是你操作不对而是 Windows 的底层环境跟这些工具的预期不一致。最典型的三点。第一Node.js 版本太旧。Codex CLI 和 Claude Code 都基于 Node.js 开发官方最低要求通常是 Node 18但我建议直接装 20 LTS 或 22 LTS。Windows 上很多人装过旧版 Node 之后不会主动升级结果 npm 安装时直接报错让人误以为是网络问题。第二PowerShell 执行策略。Windows 默认会限制脚本执行npm安装出来的某些工具脚本无法正常运行控制台会冒出一大段“无法加载文件……因为在此系统上禁止运行脚本”的提示。第三终端和编码问题。Windows 传统的控制台窗口对 ANSI 颜色和 UTF-8 支持不完整Codex 和 Claude Code 又是重度依赖彩色高亮和 emoji 输出的工具在老的 cmd 里显示会花屏、乱码甚至布局错乱。再加上不少项目路径里带中文和空格配置不好会直接导致 AI 找不到文件。这些坑都不是什么高深问题只是需要提前做几项环境准备。我建议你在动手前先把下面第 2 节做完每一步都不白做。1.3 选型建议什么时候用 Codex什么时候用 Claude Code问得最多的问题是“这两个是不是二选一”。我的答案是都装上平时按任务选。我自己实测下来的体感差别大概是这样。Codex 更适合喜欢 OpenAI 模型、或者想通过配置接入第三方 OpenAI 兼容 API 的人。它的交互模式比较轻像是面对一个快速响应的结对工程师适合快速生成函数、解释报错、做小范围改动。Claude Code 在长对话、多文件跨模块改动时表现更稳配合CLAUDE.md的使用方式适合处理有一定架构背景的遗留项目你能把项目背景写清楚它就很少跑偏。但这里有一个重要提醒这俩工具的默认登录方式都需要官方账号如果你没有订阅或者没有 API key可以走“第三方模型接入”路线。这也是现在很流行的一种玩法——OpenAI 的 Codex CLI 接 DeepSeekClaude Code 也接 DeepSeek通过修改配置就能低成本体验。我会在下面把两种方式的配置都写出来你看情况选。2. 环境准备五件事做完后面就顺了2.1 安装 Node.js LTS 并验证版本先去 Node.js 官网下载 LTS 版本安装包。这里强调一下不要图新装 Current 最新版LTS 的稳定性在 Windows 上更重要因为一些原生模块在最新版上可能还没做好兼容。安装完成后打开任意终端建议直接用 Windows Terminal按顺序执行node -v npm -v能看到类似v20.18.0和10.8.2这样的输出就说明没问题。如果提示“node 不是内部或外部命令”说明安装时没有勾选“Add to PATH”或者安装后没重启终端。重新打开终端一般都能解决实在不行就重装一次安装向导里别忘了勾上环境变量。注意安装 Node 的路径尽量不要带空格。路径带空格会让后面很多工具在解析文件路径时出错尤其是当你用npm install -g装全局包的时候。2.2 安装 Git 和 Windows TerminalGit 在 Windows 上不只是拿来拉代码的更重要的是它自带的 Git Bash。很多 AI 编程工具在 Windows 上原生运行时会跟 PowerShell 的编码规范打架但放进 Git Bash 里就舒服很多特别是处理 shell 命令、解析字符串的场景。所以即使你平时用不惯命令行也建议装 Git for Windows一路默认下一步就完事。Windows Terminal 则是微软官方的新终端比老旧的 cmd 和传统 PowerShell 窗口好用太多。它的标签页、字体渲染、UTF-8 支持都很现代。Windows 11 通常自带Windows 10 可以在 Microsoft Store 里搜索安装。后面所有操作我都默认在这个终端里做。2.3 调整 PowerShell 执行策略在 PowerShell 里执行一句Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser弹提示时输入Y确认。这个命令的作用是允许运行本地脚本但限制从互联网下载的未签名脚本。这是两全其美的方案既不会破坏系统安全性又解决了 npm 全局工具无法启动的问题。如果你已经运行过这句命令还是报脚本错误那就检查一下是不是管理员权限问题或者项目路径下有没有奇怪的.ps1文件拦截。多数情况RemoteSigned就够了。2.4 配置 npm 镜像源Windows 下用 npm 装大包最容易遇到的就是网络波动导致的超时、文件下载不完整。这不是什么神秘问题就是跨国链路稳定性一般。稳妥的操作是给 npm 配置国内镜像源常用的方案是 npmmirror淘宝 npm 镜像的后续维护版本。在终端执行npm config set registry https://registry.npmmirror.com之后安装 npm 全局包的速度会明显提升。善用npm config get registry可以随时确认当前配置。如果你有多个镜像源需求也可以考虑用nrm这类工具做切换。不过我不建议频繁切换固定一个稳定的源能少踩很多坑。2.5 给项目目录定个规矩别用中文路径Windows 的路径分隔符和转义规则与 Linux/macOS 本来就不同中文路径更是把复杂度拉满。Codex 和 Claude Code 在解析路径时有时会正常工作但一旦项目里出现某些特殊字符或者深层嵌套目录很容易出玄学问题。我自己会固定建一个类似D:\dev的目录所有项目都放在里面路径里只用英文字母、数字、连字符。这是一个很简单但能避免大量后续麻烦的习惯强烈建议你也这样做。3. Codex CLI 安装配置全流程3.1 全局安装与版本验证环境准备好之后安装 Codex CLI 只需要一条命令npm install -g openai/codex如果你之前听说过工具叫codex现在官方 npm 包名是openai/codex安装出来的命令行程序是codex。安装完成后验证codex --version只要这条命令能输出版本号说明安装成功。如果提示找不到命令大概率是 npm 全局 bin 目录没有加入 PATH。用npm config get prefix查看全局目录把它下面的路径加到系统环境变量 PATH 里然后重开终端。3.2 登录鉴权两种方式都写明白Codex CLI 有两种认证方式选择哪条取决于你有没有 OpenAI 账号。第一种官方账号登录。在终端运行codex login它会拉起浏览器打开授权页面授权完成后终端会自动收到登录成功的反馈。登录后的凭证会保存在本地配置目录里之后使用就不需要重复登录了。第二种API Key 方式。如果你有 OpenAI 平台账号可以在 console 页面创建 API Key然后设置环境变量。Windows 上建议在系统设置里添加用户环境变量变量名OPENAI_API_KEY 变量值sk-xxxxxxxxxxxxx设置完记得重新打开终端让环境变量重新加载。Codex CLI 会优先读取这个变量。提示别在公开仓库或聊天截图里泄露你的 API Key。这东西和密码一样敏感泄露后可能被刷爆配额。3.3 config.toml 配置详解接入 DeepSeek 等兼容服务这是我觉得 Codex 最实用的能力——可以通过配置文件自由切换模型供应商。配置文件的路径在C:\Users\你的用户名\.codex\config.toml没有这个目录和文件的话首次运行codex时会自动创建也可以自己手动建。最常见的第三方接入方案是 DeepSeek因为它提供 OpenAI 兼容的 API 接口而且国内访问和充值都方便。一个能用的配置示例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解释几个关键字段model默认模型名称DeepSeek 对应的是deepseek-chat或deepseek-reasoner。model_provider指定走哪个 provider名字要和下方方括号里的deepseek对应。base_urlAPI 地址。env_keyCodex CLI 会从环境变量里读取 API Key所以你还得手动新建一个名为DEEPSEEK_API_KEY的环境变量。wire_api chat表示走/chat/completions接口而不是/responses很多第三方 OpenAI 兼容服务只实现了前者不设置这个字段会报接口不支持。配置好后进入项目目录运行codex它就会按这个配置去连接 DeepSeek 服务。类似的思路还可以接 Kimi、通义、OpenRouter 这些兼容服务原理完全一样只需要改 provider 的名称、base_url 和 env_key。这是 Codex 在官方模型之外最实用的扩展方式也是最近热搜里“codex 接入 deepseek”的核心做法。3.4 首次使用进入交互界面并熟悉几个高级用法在项目目录里输入codex回车就进入了交互模式。Codex 会读取当前目录的文件结构然后等待你输入任务描述。第一次建议从一个简单需求开始比如“帮我写一个 Python 脚本把当前目录下的 CSV 文件合并成一个”。它会给出方案并询问你是否确认执行确认后才开始写文件。Codex 提供一些非常实用的斜杠命令在交互界面输入/help可以看到全部列表其中我最高频使用三个/apply让 Codex 直接应用当前对话中产生的修改适合你审查过方案之后让它落盘。/examples让 Codex 展示若干个典型使用示例快速学习工具思维方式。/status查看当前会话的模型、上下文占用等信息。另外Codex 支持在项目目录下放AGENTS.md文件相当于给 AI 写一份项目说明书。它会在每次启动时自动读取里面可以写明技术栈、目录结构、编码规范、不许碰的文件等约束。如果你已经准备写CLAUDE.md给 Claude Code 用那 Codex 的AGENTS.md建议也顺手套一份两边都能规范不少。4. Claude Code 安装配置全流程4.1 安装 anthropic-ai/claude-codeClaude Code 的官方 npm 包名是anthropic-ai/claude-code全局安装照样是一条命令npm install -g anthropic-ai/claude-code安装完成后运行claude --version能输出版本号就是成功。如果你之前装过老版本建议先npm uninstall -g anthropic-ai/claude-code再重装避免版本残留互相干扰。4.2 登录鉴权账号登录和 API Key 方式和 Codex 一样Claude Code 也可以走两种认证路线。有 Anthropic 账号的直接运行claude首次启动过程中会引导你完成浏览器授权登录。这里有个细节授权链接会绑定本机回调端口如果你的网络环境对本地端口访问有限制登录时大概率会超时遇到这种情况果断切换到 API Key 方式。API Key 方式是很多非订阅用户的常用路线。到 Anthropic 控制台创建 API Key然后设置环境变量变量名ANTHROPIC_API_KEY 变量值sk-ant-xxxxxxxxxxxx设置好环境变量之后重新打开终端运行claude就不会再要求登录了。注意ANTHROPIC_API_KEY和 Codex 的OPENAI_API_KEY互不影响可以同时存在。这也是为什么我建议两个工具都装切换链路完全隔离不会互相污染。4.3 项目记忆文件 CLAUDE.md 的妙用Claude Code 最有吸引力的功能就是把项目背景写进CLAUDE.md。我的建议是项目一开始创建就建这个文件尽量让 AI 在第一时间了解项目规则。一个真实的示例# 项目XX 后台管理系统 ## 技术栈 - 后端Python FastAPI - 前端Vue3 Vite ## 编码规范 - 所有数据库操作必须走 SQLAlchemy 的 Session - 接口返回统一使用 { code: 0, data: ... } 格式 - 禁止直接修改 migrations 目录下已发布的文件 ## 注意事项 - 日志统一使用项目封装的 logger禁止 print - 新增配置项必须在 .env.example 中同步补充每次 Claude Code 进入项目目录会自动读取这个文件后续对话中它会像一个“看过项目文档的老同事”一样行事。比起每次都口头描述项目背景这个文件才是长期稳定的上下文来源。Codex 的AGENTS.md同理两个文件可以共享大部分内容但格式和字段建议各自独立写因为两个工具解析规则并不完全一致。4.4 让 Claude Code 使用第三方兼容模型Claude Code 也支持通过环境变量把模型请求转发到兼容接口。如果你希望 Claude Code 默认走第三方服务可以这样配置。最常见的做法是配置一个支持 Anthropic 兼容协议的 API 端点。比如说 DeepSeek 提供 Anthropic 兼容地址那就可以设置变量名ANTHROPIC_BASE_URL 变量值https://api.deepseek.com/anthropic 变量名ANTHROPIC_AUTH_TOKEN 变量值你的DeepSeek API Key 变量名ANTHROPIC_MODEL 变量值deepseek-chat重新启动claude它就会请求你配置的端点。这种连接方式的好处是用 Claude Code 的交互体验、记忆文件机制同时底层模型可以是性价比更高的第三方模型适合日常轻量任务。需要提醒的是第三方兼容层通常不能保证 100% 复刻官方模型的行为个别高级功能比如部分工具调用、子代理可能出现兼容问题。实测下来基础对话、代码修改、文件读写这些核心场景都很稳定但真要跑重活还是建议切回官方模型。5. VSCode 接入教程把终端和编辑器打通5.1 配置 VSCode 集成终端默认使用 Git Bash很多人的“VSCode 接入”其实只是把这两个工具放进 VSCode 集成终端里运行这样能一边看代码一边和 AI 对话。我用的就是这个思路最轻量也不容易坏。打开 VSCode按CtrlShiftP打开命令面板输入Preferences: Open User Settings (JSON)在settings.json里添上{ terminal.integrated.defaultProfile.windows: Git Bash, terminal.integrated.profiles.windows: { Git Bash: { path: C:\\Program Files\\Git\\bin\\bash.exe } } }如果你 Git 安装在默认路径上面的路径就是对的。保存后新建一个集成终端快捷键Ctrl默认就会是 Git Bash。用这个终端跑codex和claude能避开 PowerShell 下的编码和转义问题。5.2 让 AI 自动在当前项目目录启动我建议在 VSCode 里打开项目根目录然后用集成终端进入这个项目目录再启动 AI。因为 Codex 和 Claude Code 都是基于当前工作目录工作的它们的文件读写和目录扫描都依托于启动时所在的位置。操作流程很简单VSCode 打开项目文件夹后按 Ctrl 调出集成终端确认路径就是项目根目录直接输入codex或者claude这时候它们读取的上下文就是当前整个项目。不要从随意目录启动再cd进项目虽然也能用但偶尔会出现路径识别混乱的场面。养成“在项目根目录启动”的习惯能少踩很多坑。5.3 扩展插件和辅助设置除了把工具塞进集成终端VSCode 里还可以配合几个本地插件提升体验。第一个是 Codex 官方扩展。如果你安装了 OpenAI Codex 的 VS Code 扩展它会提供一个图形化面板你可以在编辑器里直接发起对话无需到终端敲命令。扩展通常会复用你已经登录好的codex凭证配置好之后用起来还挺顺手。第二个是 Claude Code 相关的社区扩展。这类扩展主要提供侧边栏面板、命令列表、会话管理等功能。无论用哪个本质都是调用本地的claude命令所以核心安装还是以第 4 节的 CLI 为主扩展只是外壳。第三类不是插件而是 VSCode 本身的设置项可以把codex、claude设置成任务task。在项目的.vscode/tasks.json里配置一个自定义任务按一个快捷键就能在当前目录唤起 AI操作路径非常顺手。这里给一个简化示例{ version: 2.0.0, tasks: [ { label: Start Claude Code, type: shell, command: claude, options: { cwd: ${workspaceFolder} }, problemMatcher: [] } ] }配置好后按CtrlShiftP搜索Run Task选中Start Claude Code即可。5.4 快捷键与工作流建议最后说下我每天的实际工作流参考意义可能比工具安装本身更大。白天写代码时我一般把 VSCode 分屏左边是代码编辑区右边是集成终端。终端里运行着claude或codex。遇到 bug我先复制报错信息丢给终端里的 AI拿到修改建议后在编辑区手动修改如果改动范围比较大我会让 AI 直接改文件然后用C-Z或 Git diff 检查每个改动。确认没问题再提交。合理使用快捷键能省非常多时间Ctrl 快速切换终端CtrlShiftP执行任何命令CtrlShiftV在 Markdown 里预览说明文档。无论是CLAUDE.md还是AGENTS.md都可以用 Markdown 预览实时检查格式。还有一个习惯值得养成项目里同时维护CLAUDE.md和AGENTS.md的模板每次开新项目复制一份再修改。这样不管切换哪个 AI 工具它们都能立刻理解项目背景不需要每晚重复解释自己的项目是干嘛的。6. 我踩过的坑与问题排查速查表6.1 常见故障与解决方案速查表我自己反复遇到过的问题整理成表格方便按图索骥。现象可能原因解决方案npm install -g报权限/路径错误Node 安装时未正确配置 PATH或目录带特殊字符重装 Node 并勾选 Add to PATH尽量用英文路径执行codex或claude提示“不是内部或外部命令”npm 全局 bin 目录不在 PATH 中npm config get prefix查到全局目录加入 PATH 后重开终端PowerShell 提示禁止运行脚本执行策略未调整按 2.3 节执行Set-ExecutionPolicy RemoteSigned终端出现彩色花屏或字符错位使用老式控制台窗口改用 Windows Terminal或把 VSCode 集成终端设为 Git Bash中文字符乱码控制台编码不是 UTF-8Windows Terminal 设置中把默认编码改为 UTF-8或在 bash 中执行export LANGen_US.UTF-8AI 找不到文件项目路径含中文、空格或深层嵌套按第 2.5 节调整项目目录路径登录授权时浏览器回调失败本机端口受限或网络环境不稳定改用 API Key 环境变量方式登录切换模型后请求失败base_url或wire_api设置不对检查配置里 model、model_provider 与 provider 名称是否一致第三方服务确认是否走/chat/completions6.2 “切换模型供应商时本地连接失败”的排查思路最近很多人在讨论一个典型报错在 Codex 或 Claude Code 里切换自定义模型供应商时提示本地连接失败卡在握手阶段。这个问题的迷惑性在于命令本身没问题配置看上去也对但它就是连不上。我的排查顺序是这样第一步确认环境变量真的被读取了。Windows 上设置完环境变量后必须重新打开终端这个老生常谈的问题能排除五成情况。第二步确认base_url拼写无误有没有加多余斜杠是不是https。第三步检查本机是否有程序占用了配置文件里指定的端口以及防火墙是否拦截了 Node.js 进程的出站请求。按这个顺序走下来绝大多数“本地连接失败”类问题都能定位到原因。另外劝你别急着把矛盾上升到工具本身。先用最简单的 curl 请求验证目标 API 地址是否响应正常很多时候是模型服务端欠费、限流或临时故障。排除了服务端问题再回来查本地配置思路才清晰。6.3 一些值得长期坚持的使用习惯说完了故障再分享几个我实际使用中觉得特别重要的习惯。第一凡是 AI 修改过的文件逐个 diff 后再确认。命令行 AI 工具的执行力越强越要养成审查的习惯。我见过它把某个配置文件里的注释删得干干净净也见过它“顺手”优化掉一个看似无用但实际影响着特殊逻辑的函数。AI 写的代码不是不能信但你必须做把关的那个人。第二重要任务前先给 AI 足够的背景信息。不要一上来就说“修这个 bug”而是把 bug 复现步骤、相关文件路径、你尝试过的方案都写清楚。上下文质量直接影响输出质量这点在 Claude Code 和 Codex 上体现得非常明显。写好了CLAUDE.md和AGENTS.md新项目的初始理解成本会低很多。第三用会话清理命令保持上下文精简。长对话越到后面AI 的响应越迟钝也越容易遗漏早期信息。Codex 和 Claude Code 都提供了精简上下文或清理会话的方式多峰使用时要主动清理。这就像写代码要及时重构一样上下文不整洁后面一定会还债。第四定期备份配置。~/.codex/config.toml和CLAUDE.md、AGENTS.md这些文件都值得放进一个专门配置仓库里管理。换新电脑时只需要重新安装 Node 和这两个全局包再把配置文件复制回去五分钟就能恢复到原来的工作环境不需要重新摸索一遍。最后再送一个小技巧如果你在 VSCode 的集成终端里同时启动了codex和claude建议用一个终端跑一个工具并按CtrlShiftW关闭不再使用的终端面板。Windows 下同时跑两个工具偶尔会有端口抢占的情况分开使用能避免无谓的冲突。配置好之后这两个工具在 Windows 上可以成为每天都离不开的编程搭档。