在 Windows 上折腾 Codex 和 Claude Code最难受的不是工具本身而是安装配置链路太长Node.js、npm、命令行、密钥认证、编辑器集成每一步都有概率出岔子。我前后花了一个周末把这条路彻底走通中途踩过命令找不到、接口地址配置错误、VSCode 终端识别不了命令这些坑。这篇就把完整流程整理出来从环境准备讲到两个 CLI 的安装配置最后落到 VSCode 接入适合想在 Windows 上把这些命令行 AI 编程工具真正用起来的开发者。如果你已经卡在某一步很久直接对照后面的排查链路走会比翻各种零散帖子省心很多。1. Windows 上为什么要装这两个命令行 AI 工具先搞清楚它们分别解决什么问题1.1 Codex 和 Claude Code 到底是什么适合谁用Codex CLI 是 OpenAI 推出的终端编程助手它和网页版 ChatGPT 最大的区别是它运行在你本机能直接看到你仓库里的文件、Git 状态和错误日志。你不用把代码复制粘贴过去直接在项目目录里说需求它就能基于当前代码上下文给出修改建议甚至生成 diff 供你审阅。实际用下来我一般拿它处理这段代码哪里有问题帮我补一个工具函数这个报错可能的原因是什么这类快速任务交互节奏比网页版爽快很多因为它不用反复上传文件。Claude Code 是 Anthropic 推出的同类命令行工具核心优势在于长上下文和跨多文件分析。同样是打开一个项目目录它能把登录模块、权限校验、数据库查询这几块串起来看适合把整个模块的重构方案想清楚然后一次性实施这种偏重活的任务。和 Codex 一样它也跑在终端里不绑定某个具体 IDE所以和 VSCode 配合非常自然。这两个工具适合已经习惯 VSCode 终端工作流的人尤其是需要让 AI 参与 Code Review、批量重构、测试修复的开发者。如果只是偶尔想问问代码什么意思网页版聊天就够了没必要装 CLI。但如果你每天都跟项目代码打交道把这两个工具放进终端相当于在同一个界面里多了一个能通读项目背景的协作者。1.2 在 Windows 上选型的一些现实考虑Windows 和 mac/Linux 最大的不同在于环境默认值。npm 全局包默认装到用户目录而不是系统目录PowerShell 执行策略默认可能拦截脚本环境变量修改后终端不会自动重载路径里反斜杠、中文、空格都会引发解析问题。这些不是 Codex 和 Claude Code 自身的问题而是 Windows 生态自带的附加题。所以我的建议是不要一上来就纠结到底装哪个而是先把基础环境理顺。基础环境整理好之后两个工具完全可以共存。我实际使用中的分工是Codex 负责快速响应和小范围改动Claude Code 负责需要全局理解的重构和长任务。两个都装在同一个 VSCode 里切换比来回换工具高效得多。另外要提醒一句Windows 上安装这类工具尽量用 PowerShell 或 Windows Terminal不要用 CMD。不是 CMD 跑不了而是交互式 CLI 对 ANSI 颜色、自动补全、长输出的支持都比较依赖现代终端CMD 里经常出现显示错位和中文乱码排查起来非常浪费时间。2. 安装前的环境准备Node.js、Git、终端工具一个都不能少2.1 Node.js 版本选择与安装细节Codex 和 Claude Code 都是 npm 包所以 Node.js 是前置条件。版本选择上不要追求最新用 LTS 版本就行18、20、22 都可以。很多人在 Windows 上装完最新版 Node.js结果某个 CLI 依赖的模块还没有跟上跑起来报一堆语法错误最后还得降级得不偿失。从官网下载 Windows Installer 也就是 .msi 安装包时注意安装向导里有一步 Add to PATH一定要勾上。这一步如果漏了装完 Node.js 后在终端里执行node -v会提示找不到命令。装完之后不要直接在已经开着的终端里验证必须重开一个新的 PowerShell 窗口因为环境变量的刷新不是即时的。验证命令很简单node -v npm -v如果你电脑里装了 nvm-windows 这类多版本管理工具先切换到 LTS 版本再安装免得 npm 全局包装到了某个旧版本目录下后面切版本之后命令又消失了。2.2 Git 与 Windows Terminal 的准备工作两个 CLI 都会读取 Git 状态判断当前分支、有没有未提交的改动、最近提交历史。没有装 Git 的话很多依赖仓库上下文的功能会直接不可用。安装 Git for Windows 时在 Adjusting your PATH 那一步选 Git from the command line and also from 3rd-party software这样 VSCode 集成终端和 PowerShell 内部都能找到 git 命令。Windows Terminal 不是必须项但我建议装一个。原因有三个一是支持多标签页可以一个窗口跑 Codex另一个窗口跑 Claude Code互不干扰二是它对 ANSI 彩色输出的渲染更好这两个 CLI 的交互界面都大量使用颜色在旧版控制台里会很糊三是可以单独为每个标签设置启动目录和命令省去每次手动 cd 的麻烦。PowerShell 执行策略也建议提前放宽到当前用户。默认情况下 Windows 的 Restricted 策略会阻止 .ps1 脚本运行npm 安装的 CLI 很多都是通过脚本来启动的。执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这一步不需要管理员权限但如果有权限限制可以换用Set-ExecutionPolicy -Scope Process Bypass不过那只对当前终端窗口生效重开之后还要再执行一次。2.3 检查环境变量的方法与常见问题安装时最常出问题的不是软件本身而是 PATH 和用户环境变量。打开 PowerShell 执行echo $env:Path确认里面包含C:\Users\你的用户名\AppData\Roaming\npm。如果不在去系统属性 环境变量里把它加到用户 PATH 中。npm 全局安装的命令行工具默认都装在这里不加进去就会出现明明装成功了但 shell 找不到命令的情况。密钥类环境变量我建议放在用户变量里不要放系统变量。用户变量只影响当前用户系统变量会影响这台电脑上的所有账户没必要把密钥暴露给同一个机器的其他使用者。设置方式有两种。一是图形界面操作在环境变量 用户变量里新建二是在 PowerShell 里执行[Environment]::SetEnvironmentVariable(OPENAI_API_KEY, sk-你的密钥, User)这个方法比setx更可靠因为setx会把整条变量读出来再写回去一旦变量里包含百分号或特别长的文本很容易破坏原有路径结构。设置完后必须重开终端环境变量才会加载到当前会话。3. Codex CLI 的安装配置从命令行到 API Key 认证3.1 直接用 npm 安装 Codex 并验证版本Codex CLI 的官方包名是openai/codex在 PowerShell 里执行npm install -g openai/codex等安装完成再执行codex --version能正常输出版本号说明安装路径没有问题。如果在 mac/Linux 教程里见过brew install codex在 Windows 上不用管npm 是统一入口。装完如果提示codex不是命令回到第 2 章检查%APPDATA%\npm是否在 PATH 里。有时候 npm 全局根目录被改到了别的位置可以用npm prefix -g查看全局根目录再把对应的 bin 目录加入 PATH。验证不一定要等到登录之后可以执行一次最小命令codex exec 用一句话说明当前目录里有什么这个命令会调用模型并打印分析结果同时能确认 Codex 是否成功读取到了本地目录内容。如果这一步能跑通主流程基本就通了。3.2 登录认证ChatGPT 账号登录与 API Key 两种方式Codex 的认证方式有两种用途不一样。第一种是codex login在浏览器里完成授权适合持有 ChatGPT 付费订阅的用户。执行后终端会显示一个验证码或自动打开浏览器授权成功后本地会保存会话凭据之后直接运行codex就能进入交互模式。这种方式的好处是个人使用方便不需要单独管理 API 预算。第二种是使用 OpenAI API Key。如果你走的是 API 计费或者想在公司环境里统一管理密钥就把OPENAI_API_KEY设置成用户环境变量[Environment]::SetEnvironmentVariable(OPENAI_API_KEY, sk-你的密钥, User)重开终端后Codex 会自动使用 API Key。两种方式选哪个我个人的经验是个人日常写代码用登录方式最省心因为 API Key 涉及按量计费还得盯着用量如果是要写自动化脚本、接 CI/CD那就用 API Key方便在流水线里注入。需要提醒的是无论哪种方式不要在共享电脑上长期保存登录状态尤其是公司公用机器用完最好退出登录。3.3 初次运行时容易遇到的报错与处置经验新手第一次跑 Codex碰到最多的不是登录问题而是请求接口报错。我自己就遇到过codex endpoint /responses请求失败的场景当时在切换模型供应商Codex 已经把请求发出了但接口地址和模型名对不上导致每次都失败。这个报错看着复杂其实排查链路很清晰。第一步先看环境变量是否加载成功。执行echo $env:OPENAI_API_KEY如果为空说明密钥没有生效重开终端再看。很多人设置完环境变量后不重开终端就直接跑这是最常见的误操作。第二步检查 Codex 的配置文件。配置文件一般在%USERPROFILE%\.codex\config.toml里面记录了当前使用的模型、模型供应商和接口地址。确认这些字段和你当前使用的服务一致。Codex 支持 OpenAI 兼容协议如果接了第三方服务接口地址必须指向支持该协议的服务端模型名也要改成目标服务支持的名称。第三步改完配置之后不要在一个旧终端里直接重试必须新开一个终端窗口。Codex 启动时会读取环境变量和配置文件旧终端里的环境变量还是改之前的版本。第四步如果一直报同样的错误检查有没有其他环境变量覆盖了配置文件。这类问题最隐蔽我见过有人在系统变量里写了一个旧地址用户配置里的正确地址被它顶掉了导致怎么改都没用。记住一个优先级关系环境变量高于配置文件。排查的时候把OPENAI_API_KEY、ANTHROPIC_API_KEY这类的会话值都打出来看看能避免很多无效操作。Windows 上还有一个高发问题就是执行codex时提示 .ps1 脚本无法加载。这不是 Codex 的问题是 PowerShell 执行策略拦截。解决办法就是第 2 章里提过的Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行完重开终端。如果是公司电脑策略被域设置锁死可以尝试在当前会话临时绕过Set-ExecutionPolicy -Scope Process Bypass但这个方法只对当前窗口有效治标不治本。4. Claude Code 的安装配置初始化、模型接入与 .claude 目录的作用4.1 安装 Claude Code 与首次初始化Claude Code 的安装方式和 Codex 几乎一样npm install -g anthropic-ai/claude-code装完验证版本claude --version第一次运行claude如果已经设置了ANTHROPIC_API_KEY环境变量它会直接进入交互模式没有设置的话会引导你完成登录或填写密钥。Windows 上我建议直接把密钥维护到用户环境变量里[Environment]::SetEnvironmentVariable(ANTHROPIC_API_KEY, sk-ant-你的密钥, User)设置完成后重开终端在项目目录里运行claude。它会自动扫描当前目录并在目录下生成.claude文件夹。这个文件夹非常重要其中CLAUDE.md文件会被 Claude Code 每次会话自动读取相当于给 AI 的项目入职手册。你可以在里面写清楚项目结构、常用命令、编码规范这样 Claude Code 就不会反复犯用错了测试命令改了 A 文件却忘了 B 文件这类低级错误。我自己的习惯是每个项目第一次跑 Claude Code 时先花十分钟把CLAUDE.md写好。内容包括项目用的语言和框架、启动和测试命令、目录结构说明、禁止改动哪些文件。这十分钟后面能省很多事。4.2 把模型请求地址指向 DeepSeek 或其他兼容服务的配置思路Claude Code 默认走 Anthropic 官方接口但官方密钥额度有限或者你需要更大灵活性时可以通过环境变量把请求地址指向其他兼容 Anthropic 协议的服务。比如接 DeepSeek 的做法是这样的$env:ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic $env:ANTHROPIC_API_KEY sk-你的DeepSeek密钥 claude这里有个关键点ANTHROPIC_BASE_URL指向的接口必须兼容 Anthropic 的消息协议不是随便填一个 OpenAI 兼容地址就能用。DeepSeek 官方提供的就是/anthropic路径正好让 Claude Code 直接识别。如果你接的是其他服务一定要先确认对方有没有提供 Anthropic 兼容接口再去改地址。接入第三方服务时最容易踩的坑是模型名没改。很多人改完接口地址之后模型名还保留着claude-3-5-sonnet目标服务端不认识这个模型名就会一直报模型不存在。正确做法是改成目标供应商支持的模型名比如 DeepSeek 上就写deepseek-chat。这个参数可以通过claude config set model 模型名或者修改配置文件来设置。要记住改了接口地址不代表模型名会自动跟着变这是两件事。Codex 要接入 DeepSeek 也是类似思路。Codex 走的是 OpenAI 兼容协议通常需要在config.toml里新增一个模型供应商配置把请求地址指向https://api.deepseek.com/v1模型名写成deepseek-chat并在环境变量里配置 DeepSeek 的 API Key。配置完成后可以先用codex exec跑一条简单命令验证接口通不通再接交互式会话。4.3 Claude 配置文件和环境变量的实战建议实际使用中我习惯把 Codex 和 Claude Code 的配置彻底分开。Codex 认OPENAI_API_KEY和~/.codex/Claude Code 认ANTHROPIC_API_KEY和~/.claude/两边互不干扰。默认情况下两个环境变量都设好两个工具都能直接跑不需要反复切换。我的建议是官方密钥作为默认配置放在用户环境变量里接第三方服务时再用$env:方式在当前会话临时覆盖。这样不会污染全局配置也不会出现前几天还能跑今天突然走了第三方服务的尴尬情况。临时覆盖只对当前终端有效重开窗口后恢复默认。Claude Code 的权限配置建议单独设置。默认情况下它会询问你允许执行哪些命令比如读取文件、运行测试、执行 git 操作。如果觉得每次弹窗很烦可以在项目的.claude/settings.json里维护白名单和黑名单。比如允许读取文件和执行npm test禁止执行git push{ permissions: { allow: [ Read, Glob, Bash(npm test) ], deny: [ Bash(git push) ] } }这个文件是项目级生效的团队协作时可以提交到仓库让所有成员有一致的 AI 行为边界。不要小看这一步没有权限约束的 AI 辅助工具真的可能在你没注意的时候执行了不太合适的命令。5. VSCode 接入终端、任务面板、快捷键三条路让两个工具真正用起来5.1 在 VSCode 集成终端里直接调用VSCode 接入这件事其实不用装什么复杂插件最直接的方式就是打开项目文件夹按Ctrl ~打开集成终端。VSCode 默认会把当前工作区目录作为终端的启动目录所以直接在命令行里执行codex或者claude它就能自动拿到当前项目的上下文。这也是命令行工具比 IDE 插件方式更灵活的地方你打开哪个项目它就分析哪个项目不用手动指定路径也不用担心插件读取不到项目文件。如果你希望 VSCode 的集成终端默认使用 PowerShell 7 或 Windows Terminal可以在设置里搜索terminal.integrated.defaultProfile.windows选好之后重开终端。这一步不强制但能让颜色渲染和补全体验更好。有一点要注意不要在同一个终端面板里同时跑 Codex 和 Claude Code。这两个都是全屏交互式工具两个进程会竞争同一个终端的输入输出画面会非常混乱。我的做法是在 VSCode 里开两个终端标签一个标题写成 Codex一个标题写成 Claude Code需要哪边就切到哪边。5.2 配置 tasks.json 把 Codex/Claude 变成可视化任务按钮对不习惯敲命令的 VSCode 用户可以把它配置成任务。在项目根目录的.vscode/tasks.json里写上{ version: 2.0.0, tasks: [ { label: Run Codex, type: shell, command: codex, options: { cwd: ${workspaceFolder} }, problemMatcher: [] }, { label: Run Claude Code, type: shell, command: claude, options: { cwd: ${workspaceFolder} }, problemMatcher: [] } ] }保存后按CtrlShiftP输入Run Task就能看到这两个任务。如果你希望用一个快捷键直接进入 AI 对话可以只给其中一个任务加构建组标记比如把 Claude Code 设为默认构建任务{ label: Run Claude Code, type: shell, command: claude, options: { cwd: ${workspaceFolder} }, group: { kind: build, isDefault: true }, problemMatcher: [] }这样按CtrlShiftB就直接打开 Claude Code 的交互界面相当于把打开终端、输入 claude、回车压缩成一个快捷键。这里要提醒一个前提tasks.json 里的command必须能在当前 PATH 中找到也就是第 2 章里反复强调的 npm 全局路径问题。如果 PATH 没配好VSCode 任务执行时会报无法识别不是任务配置写错了而是环境没对齐。5.3 主题色、文件上下文与工作区权限的细节处理这部分容易被忽略但对实际体验影响很大。第一是终端颜色。Codex 和 Claude Code 的输出大量使用 ANSI 颜色在 VSCode 默认深色主题下通常没问题但如果你用了自定义主题且对比度较低终端文字可能会糊成一团。建议在设置里搜索terminal.integrated.minimumContrast或直接换一个高对比度主题观察交互界面是否清晰。这种问题不大但很影响长时间使用的舒适度。第二是文件上下文。CLI 读取的是当前工作目录。如果你在 VSCode 里打开的是上一级目录而不是项目根目录Claude Code 会去扫描大量无关文件夹既浪费上下文空间又容易在读代码时分心。正确做法是每个项目单独用 VSCode 打开把项目根目录作为工作区不要让模型在一堆无关代码里找重点。这也解释了为什么 tasks.json 里要写cwd: ${workspaceFolder}就是为了确保无论从哪里启动任务工作目录都锁定在项目根。第三是工作区信任机制。VSCode 对不受信任的文件夹会限制任务和终端的部分能力。第一次打开外部项目时左下角会出现信任此文件夹的提示如果不信任Codex 和 Claude Code 的运行结果可能不完整执行命令也可能被拦。点一下信任后面就顺畅了。如果是自己长期维护的项目建议在信任对话框里选信任文件夹及其父项省得每次打开子目录都提醒一次。还有一个实用细节项目路径里如果包含中文或空格VSCode 集成终端一般还能处理但 tasks.json 里的cwd如果转义不正确就可能出现问题。能避免就避免新项目目录尽量用纯英文、无空格。这不是玄学是 Windows 下路径解析的老问题尤其是涉及 npm 脚本时空格路径经常导致引号匹配错误。6. 我在 Windows 上折腾完之后的经验清单6.1 几个坑的排查链路复盘把常见的几个问题集中列出来方便日后检索。现象可能原因处理方式codex/claude 命令找不到npm 全局 bin 不在 PATH添加%APPDATA%\npm到用户 PATHPowerShell 提示禁止运行脚本执行策略默认 Restricted设置 CurrentUser RemoteSigned启动后读取不到密钥环境变量未生效重启终端检查用户变量请求接口报错地址或模型名与目标服务不一致统一配置源确认服务兼容性中文项目路径出现异常路径转义问题项目根目录尽量用英文、无空格逐条展开说一下。codex: 无法识别是新手最常见的问题。安装包本身没坏只是 npm 全局目录不在 PATH 里。这种人一般伴随一个特征node -v正常npm -v也正常但where codex什么都查不到。解决办法就是把%APPDATA%\npm加进用户 PATH然后重开终端。没有什么高深原理就是 Windows 不知道去哪里找这个命令。PowerShell 执行策略的问题前面已经反复提到。这里补充一个识别技巧如果报错信息里带File D:\xxx\codex.ps1 cannot be loaded那就是执行策略拦截不是命令本身坏了。遇到这种提示先执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned再重开终端。密钥读取不到的问题大多数人其实没设置错只是没重启终端。Windows 环境变量是进程启动时加载的已经开着的终端不会自动感知新的环境变量。所以无论什么时候改了环境变量第一件事永远是重开终端。这个习惯建立起来之后能少踩很多坑。接口报错的问题第 3 章已经复盘过一条完整链路。核心只有一句话确认请求地址、模型名、密钥三者指向同一个服务。排查时先在 PowerShell 里把两个关键环境变量都打出来echo $env:OPENAI_API_KEY echo $env:ANTHROPIC_API_KEY确保它们在同一个会话里都存在且没有被写乱。接着确认配置文件里的接口地址和模型名最后重启终端再试。6.2 让日常使用更顺手的习惯最后分享几个我用下来一直保留的习惯。第一在两个 CLI 对应的项目根目录里分别维护AGENTS.md和CLAUDE.md。Codex 会读AGENTS.mdClaude Code 会读CLAUDE.md。这两个文件的作用类似项目的 AI 说明手册里面放三样东西项目用到的语言和框架、常用的构建测试命令、整体目录结构说明。模型每次会话都会自动读取你就不需要反复在提示词里解释背景了。第二VSCode 任务面板一定要配好。把常用命令绑成CtrlShiftB之后我基本不会手动敲claude了。敲命令本身不难但每次敲完还要确认当前目录对不对、有没有切成别的分支这些干扰会打断思路。任务面板把工作目录固定好一键进入交互界面专注力能保持得更久。第三维护环境变量时始终用用户级变量不把密钥写进项目代码。如果团队协作密钥放到各自的用户环境变量里不要提交到仓库。.claude和.codex目录里如果保存了登录态也不要加到 Git 里。这是安全问题不只是配置问题。我个人的体会是工具链越折腾越能理解配置一致性这四个字。Codex 和 Claude Code 本身写得都挺完善大部分问题都出在 Windows 的环境变量、PATH 和执行策略上。把这些前置问题解决掉后面的使用体验其实和 mac/Linux 差距很小。如果你也在 Windows 上卡在哪一步对照前面的链路走一遍应该能省不少时间。
 技术理解：从 JSON-RPC 到 Agentic AI 的配置骨架)
