每次在技术群里看到有人晒 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 接 DeepSeek，Claude 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 Terminal
Git 在 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_url：API 地址。env_key：Codex 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-code
Claude 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，按Ctrl+Shift+P打开命令面板，输入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": [] } ] }配置好后按Ctrl+Shift+P搜索Run Task，选中Start Claude Code即可。
5.4 快捷键与工作流建议
最后说下我每天的实际工作流，参考意义可能比工具安装本身更大。
白天写代码时，我一般把 VSCode 分屏：左边是代码编辑区，右边是集成终端。终端里运行着claude或codex。遇到 bug，我先复制报错信息丢给终端里的 AI，拿到修改建议后在编辑区手动修改；如果改动范围比较大，我会让 AI 直接改文件，然后用<C-Z>或 Git diff 检查每个改动。确认没问题再提交。
合理使用快捷键能省非常多时间：Ctrl+`` 快速切换终端，Ctrl+Shift+P执行任何命令，Ctrl+Shift+V在 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-8 | Windows Terminal 设置中把默认编码改为 UTF-8，或在 bash 中执行export LANG=en_US.UTF-8 |
| AI 找不到文件 | 项目路径含中文、空格或深层嵌套 | 按第 2.5 节调整项目目录路径 |
| 登录授权时浏览器回调失败 | 本机端口受限或网络环境不稳定 | 改用 API Key 环境变量方式登录 |
| 切换模型后请求失败 | base_url或wire_api设置不对 | 检查配置里 model、model_provider 与 provider 名称是否一致，第三方服务确认是否走/chat/completions |
6.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，建议用一个终端跑一个工具，并按Ctrl+Shift+W关闭不再使用的终端面板。Windows 下同时跑两个工具偶尔会有端口抢占的情况，分开使用能避免无谓的冲突。配置好之后，这两个工具在 Windows 上可以成为每天都离不开的编程搭档。
