Windows下Claude Code、Codex与OpenCode三款CLI编码智能体统一部署指南

1. 为什么要把三款 CLI 编码智能体凑到同一块 Windows 上先说我为什么这么干。我日常大部分工作在 Windows 机器上完成最近半年开始重度使用 AI 编码工具先后试了 Claude Code、Codex 和 OpenCode。它们各有脾气Claude Code 对上下文的理解最细Codex 在代码修复上干脆利落OpenCode 又轻又开放接什么模型都方便。用一段时间后我意识到与其只留一个不如把三个都装上按任务类型换着用。这个思路听起来简单真正落到 Windows 上却有一堆零碎问题全局路径、PowerShell 执行策略、终端编码、Node 版本、配置目录、本地模型端点不能通用……我在一个周末下午把这些问题挨个趟了一遍最后整理出一套可以复用的“Windows 工作台”方案。这篇文章就是这个过程的完整记录包含安装步骤、配置文件写法、每个工具的定位以及几个高频报错的排查过程。如果你符合下面任何一种情况这篇内容应该对你有用想在 Windows 上装 Claude Code 但怕遇到 shell 配合问题已经装了 Codex 但用不顺手想搞清楚 config 怎么改想用 OpenCode 接免费的模型或本地 Ollama 做测试或者单纯想把几个 CLI 工具统一管理在项目里来回切换不折腾。我会尽量按实操顺序讲能贴命令的直接给命令能上配置的直接上配置不搞云里雾里的原则。1.1 三个工具到底是什么定位在动手安装之前先把三者的区别说清楚因为“三个都装”并不等于“三个都用一样的方式”。它们的定位差异很大理解这个差异才能决定什么时候用谁。Claude Code 是 Anthropic 出品的终端 Agent主打“长期共事”。它会在当前目录维护一个隐式的项目上下文支持通过 CLAUDE.md 写入项目规范还能通过 MCP 接入大量外部工具。对我这种需要理解历史代码、做跨文件重构的场景它是三个里面最“懂脑子”的。Codex 是 OpenAI 官方的 CLI 编码智能体模型迭代快对大仓库的错误定位和补丁生成能力很强。它的配置体系是三个里最完整的支持自定义 model_provider、API base、多环境密钥适合把不同供应商的模型接到同一个外壳里用。缺点也很明显默认依赖 OpenAI 的专用接口想换模型要折腾 config。OpenCode 则是完全相反的风格。它是开源项目主打轻量、中立、可插拔本身不绑定任何厂商模型配置全部由用户决定。包里默认就支持几十种提供方从 OpenAI、Anthropic 到本地模型都能接。不挑食这一点让它在快速验证、基准对比和离线场景里非常好用。三个工具不是替代关系而是互补关系。Claude Code 适合复杂架构任务Codex 适合精准打补丁OpenCode 适合当“万能遥控器”。1.2 为什么我不直接切到 WSL 或 Linux很多技术贴会告诉你搞开发就上 WSL 或者干脆换 LinuxWindows 原生跑 AI CLI 会有一堆兼容性问题。这话有一半是对的但也有一半是偷懒。我不切 WSL 的原因很现实项目里有大量 Windows 专属脚本同事交付的代码默认在 Windows 环境运行本地还挂着几个数据库服务和客户端工具。如果我整天泡在 WSL 里跟团队协作反而是多了一层翻译成本。另一个原因是这三款工具目前对 Windows 原生的支持都已经到了可用程度。Claude Code 官方推荐了针对 Windows 的安装方式Codex CLI 提供全平台可用的 npm 包OpenCode 更是直接用 Go 编译的跨平台二进制。真正需要关注的只是 terminal 环境、bash 解释器和路径这些小细节。把这些小细节处理好Windows 原生开发体验并不差而且省去了 WSL 文件系统跨盘读写带来的额外心智负担。这套方案的适用人群我理解得很清楚主力机是 Windows项目交付目标也是 Windows希望用比较小的成本把 AI 编码工具纳入日常工作流的人。如果你本来就是 Linux 用户或者极度依赖 Linux 命令生态那对你的参考价值会打折扣但核心配置逻辑是通用的。2. 环境准备给 Windows 补齐基础设施三个工具都是命令行应用所以环境准备的第一步不是装它们而是把地基打平。我在踩坑过程中发现很多所谓的“安装失败”其实都出在 Node、终端、PATH 和脚本执行策略上而不是工具本身。2.1 Node.js 和版本管理工具Claude Code 和 Codex 的官方安装方式默认走 npm 全局包OpenCode 也可以用 npm 安装所以要先把 Node.js 环境弄好。这三个工具目前普遍要求 Node 18 以上我建议直接装 LTS 版本不要追最新版省得某些原生模块编译出幺蛾子。最推荐的方式是用 nvm-windows 来管理 Node 版本。Windows 上没有 Linux 原生 nvm但 nvm-windows 已经足够稳定。装好之后安装并切换到某个 LTS 版本只需要两条命令nvm install 22 nvm use 22装完 Node 后顺手确认一下 npm 全局目录在不在 PATH 里这一步极其关键后面排查“命令不存在”时十有八九要回到这里npm config get prefix在 Windows 上npm 全局目录通常是C:\Users\你的用户名\AppData\Roaming\npm。如果这个路径不在环境变量 PATH 里你后续安装的任何 CLI 工具都无法在终端里直接调用。可以在 Windows 设置的“环境变量”里手动加也可以在 PowerShell 里用下面这条命令临时验证$env:Path ;$env:APPDATA\npm2.2 终端环境Windows Terminal、PowerShell 7 和 Git Bash装好 Node 之后接下来要解决的是“这个终端的壳到底像不像样”。Windows 自带的 CMD 已经不适合用来跑 AI 编码工具我实际使用的是三件套组合Windows Terminal 负责多标签管理颜色和字体渲染都更现代PowerShell 7 取代系统自带的 Windows PowerShell 5.1对 ANSI 颜色、UTF-8 编码和管道处理的支持更好Git Bash 作为 Claude Code 执行 shell 命令的底层解释器。后者的作用很多人会忽略我单独解释一下。Claude Code 在 Windows 上工作时运行命令会去找系统里的 bash。如果找不到合适的 bash你会在终端里看到类似“error: bash not found”或者“spawn bash ENOENT”的报错。我自己没有启用 WSL所以这个 bash 就是 Git Bash 提供的。装 Git for Windows 时把“将 Git Bash 加入 PATH”选上就能顺便解决。PowerShell 安装命令也很简单winget install Microsoft.PowerShell装好之后打开 Windows Terminal默认 shell 可以设置成 PowerShell 7。另外做一件事允许本地脚本执行否则后面安装或运行某些 CLI 脚本时会被执行策略拦住Set-ExecutionPolicy -Scope CurrentUser RemoteSigned2.3 顺手准备的服务类工具Docker、Redis、Elasticsearch这个不是必装项但我发现很多人在用 AI 编码工具做项目验证时卡点往往不在代码生成而在“生成的代码跑不起来”。如果你的日常任务里经常要启动 Redis、Elasticsearch 这类基础组件建议直接在 Windows 上装好 Docker Desktop用容器跑这些依赖。Docker Desktop 默认使用 WSL2 后端装上之后不需要单独装 WSL不冲突。我在工作台上放了 Redis 和 Elasticsearch 两个容器配置测试 AI 生成的接口时直接docker compose up -d把环境拉起来比裸装在 Windows 服务里干净得多。关于内存占用只需要在 WSL2 的.wslconfig里限制一下别让它把整台机器吃光。这个阶段看起来和三个 CLI 工具没关系但实际影响很大。地基建好了后面遇到的每一个“奇怪报错”都能用排除法快速定位而不是把锅全甩给某个 AI 工具。3. 安装三个核心工具命令、配置和不顺眼的地方环境准备好之后安装阶段其实非常快真正的沟都在配置和调用上。这一节我会按照 Claude Code、Codex、OpenCode 的顺序逐个把安装命令、初始化方式和 Windows 专属注意点写清楚。3.1 Claude Code从安装到跑通项目级上下文Claude Code 的 npm 安装过程很简单npm install -g anthropic-ai/claude-code安装完成后执行claude --version确认版本。首次启动时它会要求你登录你可以选择用浏览器走 Claude 账号的授权流程也可以设置环境变量ANTHROPIC_API_KEY来免登录。对于长期自动化使用我个人更喜欢直接用 API Key因为这样不怕浏览器登录态过期。$env:ANTHROPIC_API_KEY 你的密钥 claude启动后进入交互式终端直接用自然语言描述任务它会自行分析项目、读取文件、执行命令。建议每个项目根目录放一个CLAUDE.md文件把你对这个项目的约定写进去比如“后端使用 Python 3.11测试命令是 pytest提交时遵守 Conventional Commits”。Claude Code 每次启动都会参考这个文件这是它表现是否智能的分水岭。Windows 上最容易出错的地方是 bash 解释器。如果你已经按上一节装好 Git for Windows一般不用额外处理但如果你用的是企业定制终端或者某些 IDE 内置的终端Claude Code 可能找不到 bash。可以先检查一下where.exe bash如果bash不在结果里把 Git 安装目录下的usr\bin加到 PATH。还有一个小技巧在 PowerShell 里手动设置一下输出编码避免中文乱码[Console]::OutputEncoding [System.Text.Encoding]::UTF83.2 Codex CLIconfig.toml 是你的核心控制台Codex CLI 的安装同样走 npmnpm install -g openai/codex装完后首次运行codex它会引导你通过 ChatGPT 账号登录或者直接设置OPENAI_API_KEY。这里我想强调一个很多人不重视的点Codex 的配置文件config.toml才是它的灵魂位置在%USERPROFILE%\.codex\config.toml。默认配置很简洁但扩展性极强。如果希望把 Codex 接到某个兼容的模型服务商或者用企业内部的 OpenAI 兼容网关就需要在config.toml里定义一个model_provider。下面是一份我实际在用的配置示例model 你的模型名 model_provider custom [model_providers.custom] name custom base_url https://你的服务地址/v1 env_key CUSTOM_API_KEY设置好之后再在系统环境变量中定义CUSTOM_API_KEYCodex 启动时就会读取这个密钥并连接到对应服务。注意 Codex 默认会调用POST /responses这个接口而不是常见 OpenAI 兼容服务的/chat/completions这一点在接第三方服务时非常重要我会在后面的报错排查里再展开。日常交互使用codex进入对话模式非交互式批量执行可以这样用codex exec 修复 src/index.ts 中的类型错误这在 CI 或者批量处理场景下很实用。Codex 的日志文件也在%USERPROFILE%\.codex\logs下如果遇到“看不到输出”或者“窗口打不开”先翻日志基本能定位 80% 的问题。3.3 OpenCode轻量但扩展能力很强OpenCode 给我的感觉就是“清爽”。它不像前两者那样有厂商绑定色彩配置文件简单直观官方文档把各种模型的接入方式都列得很清楚。安装方式有三种我推荐用 npmnpm install -g opencode-ai如果你系统里装了 Go也可以用go install github.com/opencode-ai/opencodelatest运行opencode --version验证安装。首次启动进入交互界面后它会要求选择模型提供商。OpenCode 默认支持的 provider 列表非常长包括 OpenAI、Anthropic、Google、本地 Ollama 等几乎不需要额外配置选完就能用。配置文件位于~/.config/opencode/opencode.json可以通过它覆盖模型列表、默认 provider 和参数。举个例子我想默认使用本地 Ollama同时保留远程模型作为备选配置可以写成这样{ provider: { ollama: { models: { qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B } } } } }OpenCode 另一个抢眼的功能是 skills。它和 Claude Code 的 CLAUDE.md 有点类似但更强调场景化。你可以在项目里建.opencode/skills/目录每个 skill 放一个SKILL.md里面写清楚这个 skill 的用途、输入、输出规范和调用方法OpenCode 会在对应场景自动加载。实际用下来这个机制对团队统一 AI 编码规范很有帮助。非交互模式用opencode run 你的任务描述一样可以进 CI 流程。3.4 三个工具安装后的自检清单每次装完工具我都会花一分钟做一套自检确认基础环境没毛病分别执行claude --version、codex --version、opencode --version能打印版本号说明主程序没问题。进入一个测试项目分别执行claude、codex、opencode确认能进入交互界面且不会秒退。检查 PATH 和密钥where.exe claude、where.exe codex、where.exe opencode都能找到对应文件API Key 相关的环境变量也已配置到位。在 PowerShell 和 Git Bash 两种终端里都试一遍因为有些项目会指定 shell提前了解兼容性。这套自检最多五分钟做完之后基本不会再被“为什么命令找不到”这种基础问题卡住。4. 统一工作台把三个工具装进同一套工作流三个工具各自都能跑了接下来才是重头戏怎么让它们在同一台 Windows 工作台上成为一个整体。我花了很多时间折腾这部分核心目标只有一个切换成本足够低低到我不用去想“这次该用哪个”。4.1 项目目录里的配置规约三个工具都有自己的隐藏目录和配置文件在同一个项目里并存完全没问题只要做好目录隔离。我当前的约定是.claude/目录放 Claude Code 的项目级配置包括settings.json和 MCP 服务器配置。.codex/目录放 Codex 的项目级配置主要是针对不同仓库的提示词。.opencode/目录放 OpenCode 的技能配置。项目根目录的CLAUDE.md是 Claude Code 的记忆文件而 OpenCode 会读取.opencode/skills/。这些目录建议全部加入.gitignore避免把密钥或机器相关的配置提交到仓库。密钥类的环境变量可以放在项目根目录的.env里由工具自行读取不要硬编码到任何配置文件中。每次新增项目时我使用同一个模板把三个目录初始化好这样一个仓库里三套工具各拿各的配置互不干扰。4.2 用 cc-switch 管理多套配置和本地模型装三个工具之后很快会遇到一个新的痛点同一个工具可能要面对不同的模型服务商。早上用官方 API下午想切到本地的 Ollama 测试每次都要改环境变量和配置文件改来改去很容易出错。cc-switch 就是为这个痛点做的桌面小工具。它的定位很明确把你常用的模型服务配置保存成多套预设在图形界面里一键切换。说人话就是你不需要每次手动改config.toml或者环境变量鼠标点一下就完成切换。我实际使用的配置集有两个一个是“远程模型”走各家官方 API另一个是“本地模型”走http://127.0.0.1:11434也就是 Ollama 的默认地址。这样我可以随时在远程和离线之间来回切。不过这里有一个非常重要的坑值得单独说明Codex 默认请求的是/responses接口而 Ollama 兼容 OpenAI 协议时通常只实现了/v1/chat/completions。如果 cc-switch 只是简单地把 Codex 的 base_url 指向 Ollama就会出现类似“cc switch local proxy failed while handling codex endpoint /responses”的报错。这个问题的本质是路由不匹配不是工具不好用。我当时的处理方案是Claude Code 和 OpenCode 都允许直连 Ollama 用本地模型Codex 则单独配置一个能兼容/responses的转换层服务或者干脆继续走远程模型。把不同工具的适配边界理解清楚再用 cc-switch 做一批合理预设虽然还不能做到零配置但已经比手动改半天强太多了。4.3 在 VS Code 里把三个 CLI 变成可调用任务在终端里手动输入claude、codex、opencode当然没问题但更好的方式是把它们固化到编辑器的任务系统里。VS Code 支持自定义任务我配置了三个任务一个启动 Claude Code 会话一个运行 Codex 修复命令一个用 OpenCode 跑代码审查。这样在编辑器里按快捷键就能调用不需要靠记忆敲命令。.vscode/tasks.json大概长这样{ version: 2.0.0, tasks: [ { label: AI: Claude Code, type: shell, command: claude, options: { cwd: ${workspaceFolder} } }, { label: AI: Codex Fix, type: shell, command: codex exec \修复当前项目的所有 TODO 并提交\, options: { cwd: ${workspaceFolder} } }, { label: AI: OpenCode Review, type: shell, command: opencode run \审查当前分支的代码差异指出潜在问题\, options: { cwd: ${workspaceFolder} } } ] }配合 Windows Terminal 的多标签页一个标签跑 Claude Code一个标签跑 Codex再留一个普通 PowerShell 跑命令整个工作流非常流畅。这些都是基础设施层面的东西不直接提升模型能力但能极大降低切换的心理成本。4.4 我的日常分流习惯什么场景用哪个工具都在手边真正的问题就变成什么时候用谁。我给自己的分流规则经过一段时间实践已经比较稳定这里分享给你代码重构、跨文件改逻辑、需要理解项目背景的任务优先用 Claude Code。它的项目记忆和上下文能力在三个里面最能扛住大场面。定点修 bug、根据报错信息精准补丁优先用 Codex。它的输出更“代码化”模型对错误堆栈的敏感度非常高。快速跑通不同模型的方案对比、临时验证某个模型的效果优先用 OpenCode。配置轻、换模型快不会像前两个那样绑定某个生态。完全离线或者只想用本地模型的时候OpenCode 接 Ollama 是最省事的路径。如果项目已经形成了良好的自动化测试体系我会让三个工具分别负责不同模块并行跑再人工汇总这个用法确实能省很多时间。规则不代表死板我也会根据项目实际情况调整但有了这个初步分工至少每天打开电脑不需要纠结“该用哪个 AI”。5. 高频报错与排查实录这一节是我最想写的内容。安装文档到处都是但真正让你半夜崩溃的都是文档外的报错。我把最近实际踩过的几个问题记在这里按出现频率排序每个都附带了排查思路和最终解法。5.1 opencode 无法识别PATH 和环境变量的问题这个报错原文是类似“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。很多人第一反应是自己没装成功但我遇到时其实 npm 安装流程完全正常。最常见的原因有两个一个是 Node.js 的 npm 全局路径没有加入PATH另一个是装完新版本 Node 后之前 npm 全局安装的包没有被迁移过来。排查思路按顺序来where.exe opencode npm ls -g opencode-ai npm config get prefix如果where.exe opencode找不到任何东西但npm ls -g opencode-ai显示已安装那基本就是 PATH 的问题按前面第二节的方法把%APPDATA%\npm加入 PATH 即可。如果连 npm 全局列表里都没有说明安装时出了岔子最简单的方法是卸载重装npm uninstall -g opencode-ai npm install -g opencode-ai还有一个容易忽略的点如果你在 nvm-windows 里切换了 Node 版本不同版本对应的 npm 全局目录是分开的。切回老版本后新版本的全局包自然不可用这时候要么重新装要么固定一个长期使用的 Node 版本别来回切。5.2 cc-switch local proxy 报错Codex 和本地模型端点不匹配这个就是 4.2 节提过的坑我单独拿出来详细说。报错信息一般长这样cc switch local proxy failed while handling codex endpoint /responses。这个错误有一个非常直观的原因Codex 对模型的请求路径是/responses而本地代理无论是 Ollama 还是其他只实现了/chat/completions的工具只认/v1/chat/completions两边对不上所以请求失败。解决思路有三条按复杂程度从低到高排列第一如果只是想在本地跑模型别用 Codex改用 OpenCode 或 Claude Code 接 Ollama这两个工具对/chat/completions的兼容性更好。第二让 Codex 直连支持/responses接口的后端模型服务但这需要后端本身做适配。第三加一层转换代理把/responses的请求转成/chat/completions再发给本地模型。目前有一些开源网关工具可以做这件事但配置复杂度会上升我建议除非团队必须统一用 Codex否则优先采纳第一种方案。这个报错也提醒了我类似的问题不同工具对 API 协议的假设差异很大不要因为界面长得像就觉得底层逻辑一样。5.3 Codex 打不开或桌面版窗口不出现搜索“Codex 打不开”能搜到很多帖子我也遇到过。Codex 在 macOS 上有原生的桌面客户端体验但在 Windows 上官方提供的桌面版支持目前远不如 CLI 完整。如果你在 Windows 上双击桌面版图标之后没有任何窗口出现多半是它的渲染进程出了问题或者短暂的启动失败被 windows 静默吞了。我的建议很简单在 Windows 上把 Codex 桌面版当额外的预览体验主力使用 CLI。CLI 的功能反而更可靠会话状态、配置管理、日志输出都在自己的掌控内。如果确实需要在图形环境里查看任务我一般直接在 VS Code 终端里运行codex然后在 Windows Terminal 的标签页里盯着输出PDF 显示效果不会比桌面版差多少。如果命令行也打不开去%USERPROFILE%\.codex\logs目录下看日志通常能看到具体的报错原因比如 API Key 无效、网络请求超时或者配置文件解析错误。5.4 Claude Code 在 Windows 终端里的中文乱码这个问题比较细但遇到的概率很高尤其是企业 Windows 默认使用 GBK 代码页时。现象是 Claude Code 输出的中文全部变成乱码但英文、代码都正常。定位后发现是终端编码问题不是 Claude Code 的问题。临时解法是在 PowerShell 里设置 UTF-8 输出编码[Console]::OutputEncoding [System.Text.Encoding]::UTF8如果你想永久解决可以在 Windows Terminal 的配置文件里把默认编码设为 UTF-8同时把 PowerShell 的启动参数里加上-NoExit -Command [Console]::OutputEncoding[System.Text.Encoding]::UTF8。另外我建议把终端字体调成支持中文等宽字形的字体比如 Cascadia Code 或 JetBrains Mono中英文混排看起来舒服很多。5.5 npm 全局包更新后出现版本错乱最后一个问题是我自己折腾出来的为了升级 Codex我直接执行了npm update -g openai/codex结果codex --version还是旧版本。原因是 npm 全局包更新时偶尔会留下缓存或二进制链接没有被替换干净。遇到这种情况最干脆的做法是卸载再装而不是反复 updatenpm uninstall -g openai/codex npm install -g openai/codex如果你有多个 Node 版本顺便检查一下当前用的版本是不是当初安装 Codex 的那个。版本错乱的坑经常和不稳定的 PATH 混在一起多确认一步能省很多时间。6. 我的真实使用体会和最后几条建议这套工作台我实际用了一个多月最大的变化不是某一个工具让我效率翻倍而是三个工具放在一起后我敢于把更多任务交给 AI 去做了。以前遇到“让 AI 干活不如自己干”的情况往往是因为手边只有一个工具模型和任务的匹配度不够。现在有了切换的余地我会更愿意先让合适的工具处理再人工检查和补刀。有个很典型的场景一个老项目准备从旧接口迁移到新接口CLI 工具需要读大量历史代码理解业务分布然后生成一整套迁移方案。这种任务我用 Claude Code 从项目背景开始聊让它把方案拆成小步骤再让 Codex 逐个步骤去实现和验证OpenCode 则拿一个小模块做模型对比看看哪个模型的迁移代码更稳。三个工具各负责一段最后我只需要 review 落地结果。这种配合方式比单独用任何一款都要可靠。我也慢慢总结出了一些底层的工作习惯比如每次开始任务前先明确“这次项目级上下文应该给多少”比如无论用哪个工具密钥永远走环境变量而不是写进配置库再比如每次安装完新版本工具一定花一分钟跑一遍 3.4 节里的自检清单。这些小习惯听上去普通但它们才是这套工作台稳定运行的关键。如果你也想在 Windows 上搭建类似的环境我的建议是不要一步到位。先只装一个工具跑通一个真实项目再慢慢加入第二个、第三个。一次性把三个都装齐碰到问题容易归因混乱反而打击信心。从一个能稳定跑通任务的最小组合开始等熟悉了配置文件和工作流之后再按这个文章里的分工扩展体感会好很多。最后说一个小技巧给每个项目写CLAUDE.md的时候不要只写技术栈把团队协作方式、常见误区和最容易犯错的地方也写进去。这个文件不光是给 Claude Code 看的也是给未来接手项目的同事看的。语义清晰的说明文档在任何 AI 工具面前都是最高级的提示词。