最近命令行里的AI编程工具是真的火，Anthropic的Claude Code和OpenAI的Codex CLI这两个名字几乎天天挂在社区热榜上。身边不少做后端、前端、运维的朋友都开始尝试在终端里让AI直接写代码、跑测试、改bug，安装和配置问题也随之爆发：有人npm装完发现claude命令根本不存在，有人Windows桌面版装到一半提示未完成，有人登录时反复遇到token不可用，还有人同时用两个工具，在切换配置时被cc-switch的local proxy报错整到怀疑人生。
我前前后后把这两个工具从安装到卸载折腾了好几遍，踩过不少坑，也顺手记录了各种报错的完整排查链路。这篇就用偏实战的笔记形式，从环境准备、安装登录、VSCode集成，到双工具切换、第三方模型接入、常见报错定位，最后一直写到卸载清理残留，一条龙说清楚。适合所有想在本地终端里正经用AI编程工具的开发者，不管你是Mac、Windows还是Linux，也不管你是新手还是已经装了但被各种问题卡住的老手。
1. 装之前先搞定环境：Node.js版本与终端状态检查
1.1 为什么这两个工具都依赖Node.js
Claude Code和Codex CLI本质上都是Node.js写的命令行程序，通过npm全局安装分发。这不是个小细节，很多人安装失败的第一道坎就出在Node版本上。
两个工具对Node版本的要求是这样的：
| 工具 | npm包名 | Node.js版本要求 |
|---|---|---|
| Claude Code | @anthropic-ai/claude-code | 官方要求18+，推荐20+ |
| Codex CLI | @openai/codex | 官方要求18+，新版建议直接20+ |
安装命令本身不复杂：
npm install -g @anthropic-ai/claude-code npm install -g @openai/codex但如果你机器上的Node还停留在v14甚至v12，千万别直接装最新版CLI。这两个工具用了大量最新的JavaScript语言特性，老版本Node大概率启动就崩，报各种莫名其妙的语法错误，看起来像是工具本身坏了，其实是运行时太老。
提示：先用
node -v看版本。如果低于18，直接装Node 22 LTS，这是目前最稳妥的选择，两个CLI跑起来都没问题。Windows用户去官网下载安装包，macOS用户用brew install node，Linux用户用apt或直接下载二进制包都行。
1.2 npm镜像与全局bin路径
如果你在国内直接用官方npm源，装这两个包的速度会让人抓狂，经常卡在下载阶段十几分钟没动静。配置npmmirror镜像能快很多：
npm config set registry https://registry.npmmirror.com配完之后再装包，速度不是一个量级。但这里要先打个预防针：npm镜像只解决"下载安装包"这件事，解决不了"登录和调用API"这件事。这两个CLI装完后，登录Anthropic或OpenAI的服务，以及后续每次请求模型，都需要你的网络环境能正常到达对应服务。这是工具本身的地域限制，镜像帮不上忙。
确定安装成功，不是看npm输出那几行绿色提示就完事了，关键要实际执行一下：
claude --version codex --version如果提示"不是内部或外部命令"或"command not found"，不是你操作有问题，而是npm的全局bin目录没在PATH里。Windows上通常在%APPDATA%\npm或C:\Program Files\nodejs\，macOS和Linux上通常在/usr/local/bin或/opt/homebrew/bin。把对应目录加进PATH，重新打开终端再试。
1.3 Windows用户建议用PowerShell
在Windows上跑这些CLI工具，强烈建议用PowerShell或Windows Terminal，别用老旧的cmd窗口。Codex的交互式会话、方向键操作、多行输入，在cmd里容易出现各种显示异常和输入错位。Win11自带的Windows Terminal可以直接用，Win10去应用商店装一个就行，这步不是必须，但能省掉一堆终端渲染的奇怪问题。
另外，如果你打算长期做AI编程工具的配置和调试，给自己养成一个习惯：所有环境相关的改动，都在同一个终端窗口里验证，不要一会儿用PowerShell、一会儿用cmd、一会儿用VSCode内置终端，PATH不一致会导致"明明装了却找不到命令"的假象。
2. Claude Code：安装、登录与VSCode集成
2.1 安装与版本验证
Claude Code的安装是最标准的npm全局安装流程：
npm install -g @anthropic-ai/claude-code装完先跑一次claude --version确认版本号正常输出。这里有个很多人忽略的点：首次在某个目录下运行claude时，它会做一次初始化，问你是否尊重该目录下已存在的.git目录、是否允许它读取特定文件等，按提示选即可。
注意Claude Code在Windows上没有独立的"桌面版客户端"这个东西。社区里传的"Claude Code桌面版"，其实指的是Anthropic官方桌面应用里内置的Claude Code入口，本质上调用的还是同一个CLI。如果你想要的是一个图形界面窗口，大概率会失望，它主打的场景就是终端。
2.2 登录：账号登录与API Key两种方式
登录是这个工具最容易出问题的环节，这里多说几句。Claude Code的登录本质，是在本机存一份认证凭据，后续每次请求都带着它。
方式一，官方账号登录：
claude /login运行后会打印一个URL，浏览器打开授权，授权完回到终端继续。这种方式的约束是：网络环境必须能正常访问Anthropic服务，而且账号有配额限制。
方式二，用API Key：
export ANTHROPIC_API_KEY="sk-ant-..."Windows PowerShell里这样设：
$env:ANTHROPIC_API_KEY = "sk-ant-..."这里有个很容易踩的坑：如果环境变量和账号登录同时存在，系统会优先读ANTHROPIC_API_KEY。有时候你明明账号登录成功了，跑项目却一直401报错，十有八九是环境变量里残留了一个过期或没权限的API Key，把环境变量清掉就好。
2.3 VSCode配置Claude Code
这就是搜索量很高的"vscode配置claude code"场景。早期大家只能在终端里用Claude Code，现在官方出了VSCode扩展，体验好不少。
配置步骤很简单：
- VSCode扩展市场搜"Claude Code"，认准官方扩展，安装。
- 扩展的运行依赖CLI本体的登录状态，所以先确保命令行里
claude能正常进入对话。 - 打开任意项目，快捷命令唤起Claude面板，或者点侧边栏的Claude图标。
有一个常见认知误区：以为VSCode扩展是一个独立程序，不需要装CLI。不对，扩展只是个壳，它要调用你本机的claude命令行。所以如果你之前没全局安装过CLI，扩展装完依然用不了，还得回到npm装一遍。
2.4 权限模型与常用配置
"claude code权限"这个关键词也经常被搜，因为Claude Code默认会做权限控制。它执行文件修改、跑终端命令之前，会弹确认请求，避免AI乱动项目文件。如果你觉得频繁确认太打断思路，可以在~/.claude/settings.json里做一层规则配置，比如允许执行npm开头的命令、禁止rm -rf这类危险操作，配好之后该放行的自动放行，该拦截的坚决拦截。
界面语言方面，Claude Code的界面文案会跟随系统语言，如果你希望AI默认用中文回答，直接在对话里说"请用中文回复"即可，不用改任何配置。
3. Codex CLI：桌面版与命令行版的安装细节
3.1 两条主要安装路线
Codex CLI来自OpenAI，安装方式比Anthropic那边多，也更容易绕晕。
路线A，npm安装命令行版：
npm install -g @openai/codex路线B，官方桌面版：OpenAI官网提供了Codex桌面应用，分Windows和macOS两个版本。桌面版内部其实也是包了一层CLI，对平时不爱碰终端的开发者友好很多，很多人搜的"codex官网下载""codex安装包""codex安装windows桌面版"指的都是这条。
macOS还有一个路线C，brew install codex。这里提醒一句：如果你之前已经用npm装过，再brew install会面临bin指向冲突，两个包管理器各装了一份，命令行实际调用的可能是旧的那个。个人建议二选一，以npm为主，因为版本更新最及时。
3.2 Windows桌面版安装失败排查链路
"codex windows安装未完成"是Windows用户最常搜的一个报错，完整提示可能是"Something went wrong with your install"或类似内容。这个问题原因很多，我按排查顺序列一下：
第一步，确认安装包完整性。浏览器下载中途断流，安装包文件残缺的情况特别常见，而且浏览器不一定报错。拿到安装包后先看体积和官网标注是否一致，如果不一致，重下一遍。
第二步，看杀毒软件有没有拦截。Windows Defender或第三方安全软件对这类新工具的安装程序常有误报。如果你遇到双击安装包没反应、装了之后找不到程序文件，先去Defender的"保护历史记录"里看有没有被隔离，再把安装目录加进排除项重新安装。
第三步，用管理员权限运行安装程序。安装器需要往Program Files写入文件并注册PATH，普通权限在某些企业版Windows上会静默失败，表面看安装流程走完了，实际什么都没写进去。
第四步，装完后如果codex命令仍然找不到，去检查安装目录是否在PATH里。桌面版通常把可执行文件放在%LOCALAPPDATA%\Programs\codex这类位置并自动配置PATH，没生效的话手动加一遍，然后重启终端。
另外有一种特殊情况：安装进程一直卡在"正在连接""connecting"这类状态，基本可以确定是网络到达不了下载端。这时候不要反复点安装，大部分安装器不支持断点续传也没有幂等保护，重复运行会留下很多残留进程和半成品文件，正确的做法是换个网络环境重试。
3.3 登录与auth token is unavailable处理
Codex的登录流程：
codex login浏览器授权完成后，凭据以JSON格式存在~/.codex/auth.json里。
运行时报"codex auth token is unavailable"或类似提示，意思是本地没有找到合法token。常见就四种情况：
- 登录过但token过期，重新
codex login。 - 刚装完还没登录，直接登录。
- 设置了
OPENAI_API_KEY环境变量，但那个Key本身没权限或格式错误。 - 之前切换过账号，新登录覆盖了旧token，但某个旧进程还在读旧缓存。
提示：如果你是在准生产环境或CI/CD流程里用Codex，建议用API Key而不是ChatGPT账号登录。账号登录受订阅配额限制，API Key按量付费，行为更可控，也方便在自动化脚本里复用。
3.4 Codex的初始化配置
第一次运行codex可能会提示你选择默认模型、默认供应商，这些设置会写进~/.codex/config.toml。这个文件很关键，后面接第三方模型、配置各种供应商，全靠改它。即使你打算用cc-switch这类图形管理工具，也需要先理解config.toml的结构逻辑，否则切换配置时出了问题，都不知道改的是哪一层。
4. 双工具切换与cc-switch的本地代理报错排查
4.1 cc-switch在双工具工作流里的作用
cc-switch是一个开源的配置管理小工具，用来管理多个AI编程CLI的供应商配置。一句话解释它的定位：一个"配置文件图形管理器"。
它解决的痛点是：当你又用Claude Code、又用Codex CLI，并且每个工具都配了多个供应商环境（官方账号、第三方转发、公司网关等）时，手动改config.toml和settings.json不仅麻烦，还容易改错格式。cc-switch把每套配置存成profile，图形界面里一键切换，同时负责把请求通过本地代理转发到目标供应商。
4.2 在cc-switch里配置Codex接入自定义provider
cc-switch的新版本支持直接管理Codex的provider。添加provider时一般要填这几项：
- Provider名称（自定义，比如DeepSeek）
- Base URL（比如
https://api.deepseek.com/v1） - API Key
- 模型名
保存后，cc-switch会把信息写进~/.codex/config.toml。这里有一个容易忽略的坑：如果你之后手动改过config.toml，cc-switch界面里的信息和实际文件可能不一致，切换前先在cc-switch里刷新一下，避免用旧配置覆盖新文件。
4.3 核心报错拆解：cc switch local proxy failed while handling codex endpoint /responses
现在聊这个高频报错。完整信息一般是：
cc switch local proxy failed while handling codex endpoint /responses. provider ...第一次看到这行报错的人很容易慌，其实拆开来看就三条关键信息：
- "local proxy"，cc-switch在本地监听了一个端口作为代理，Codex把请求发到本地，本地再转发给真实供应商。
- "codex endpoint /responses"，Codex默认请求的是OpenAI的Responses API端点
/responses，不是更老的/chat/completions。 - "provider failed"，目标供应商在处理这个请求时返回了错误。
最常见的根因是：目标供应商不支持/responses端点。市面上大量宣称"OpenAI兼容"的服务，实际只实现了/v1/chat/completions，还没跟上游的Responses API。cc-switch把这个请求原样转发过去，对方返回4xx或5xx，本地代理把错误抛给Codex，于是你看到这条报错。
解决方案按优先级排：
- 如果cc-switch的provider配置里能设置"接口风格"，把responses改成chat，让它用
/chat/completions路径转发，兼容性高得多。 - 手动改
~/.codex/config.toml，在对应provider里显式加一行wire_api = "chat"，比如：
[model_providers.myprovider] name = "My Provider" base_url = "http://127.0.0.1:3000/v1" env_key = "MY_PROVIDER_API_KEY" wire_api = "chat"- 如果确认供应商确实支持
/responses端点，那问题多半出在Base URL上。很多服务商的Responses端点在/v1/responses路径下，base_url漏掉末尾的/v1就会404。检查Base URL是不是填成了裸域名。 - 再排除cc-switch自身的问题。本地代理如果端口被别的程序占用，Codex会一直"正在重新连接"或直接报代理错误。换一个端口、重启cc-switch、确认代理进程起来，就正常了。
排查这个报错有个很实用的思路：绕开cc-switch，直接用curl测试目标供应商的/chat/completions和/responses两个端点，看它们分别返回什么：
curl -X POST https://api.example.com/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"your-model","messages":[{"role":"user","content":"hi"}]}'哪个端点通、哪个端点不通，问题出在哪一层，一比划就清楚了。这个方法不仅能排查cc-switch，排查任何代理转发类工具的报错都通用。
4.4 与"codex正在重新连接"的关系
顺带说下另一个热词"codex正在重新连接"。这个提示一般出现在网络波动或代理不稳定时，Codex没有收到上游响应，进入了退避重连状态。通常等几秒它会自动恢复。如果一直卡着不动，优先检查当前网络到目标供应商的连通性；如果是cc-switch转发路径，就回去看代理日志里有没有持续4xx或5xx。
遇到"正在重新连接"不要急着杀掉进程重启，先观察十几秒。CLI有自动重试机制，频繁手动重启反而会让token状态和会话上下文乱掉。
5. 装完就能用的进阶配置：第三方模型、Skills与常用命令
5.1 Codex接入DeepSeek等第三方模型
"codex接入deepseek"是最近很火的需求，操作本质就是改~/.codex/config.toml。在文件里声明一个model_provider，设为默认即可。以DeepSeek为例：
model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"然后把DEEPSEEK_API_KEY加进系统环境变量，重新打开终端，跑codex时就会走DeepSeek。
这里最关键的参数是wire_api：
- 设为
"chat"，走/chat/completions端点。 - 不写或写成
"responses"，走/responses端点。
DeepSeek官方API目前主要兼容OpenAI的chat completions格式，所以接入codex时要显式写wire_api = "chat"。如果你漏了这行，大概率会撞上上一节那个/responses报错。反过来，如果你接的是OpenAI官方模型，wire_api别改成chat，官方两个端点都支持，保持responses反而能用上更新的功能。
5.2 Claude Code Skills安装
Claude Code的Skills机制是它的扩展能力，可以给Claude Code装"技能包"，比如专项Code Review、接口文档生成这类。安装方式一般是在对话里输入/install-skills，或者把下载好的技能包目录手动放到项目的.claude/skills下。
对新手来说最省事的操作是：拿到skill包后看它的目录结构，如果是文件夹形式的，直接放进.claude/skills，然后重启Claude Code会话让它重新加载。有个小提醒：skill装多了以后，注意同名冲突，两个包用了同一个技能名，后加载的会覆盖先加载的，排查起来很难受。
5.3 常用命令速查表
收藏这张表，日常使用基本够用：
| 操作 | Claude Code | Codex CLI |
|---|---|---|
| 安装 | npm install -g @anthropic-ai/claude-code | npm install -g @openai/codex |
| 版本验证 | claude --version | codex --version |
| 登录 | claude /login | codex login |
| 进入交互模式 | claude | codex |
| 非交互执行 | claude -p "生成一个排序算法" | codex exec "生成一个排序算法" |
| 会话控制 | /clear清空上下文 | 重开会话 |
| 配置目录 | ~/.claude | ~/.codex/config.toml |
| 卸载 | npm uninstall -g @anthropic-ai/claude-code | npm uninstall -g @openai/codex |
两个工具的对话语言都直接跟着你的输入走，你发中文它回中文，发英文它回英文，不用单独做"中文设置"。如果你希望它默认用中文，最简单的方法是在项目根目录放一个CLAUDE.md或AGENTS.md说明文件，在里面写一句"请始终用中文回答"，它每次启动都会读到。
5.4 一点进阶：二开与脚本集成
"claude code二开"对应的是Claude Code的脚本化集成能力，你可以通过SDK或子进程方式调用CLI，解析JSON输出，把它嵌入自己的工具链。Codex这边也差不多，codex exec --json可以输出结构化结果，方便脚本消费。这部分不是安装卸载的必修课，但如果你有把AI编程工具接入内部系统的需求，知道有这条路就行，具体往下做的时候再深入研究。
6. 卸载与残留清理：两个工具各留了什么
6.1 Claude Code的卸载与清理
很多人以为卸载就是跑一句npm uninstall，实际上这么干完，电脑里残留的东西比想象中多。
npm uninstall -g @anthropic-ai/claude-code这一步只移除可执行文件，但以下几个位置的配置和会话数据不会被自动删除：
~/.claude/：项目配置、会话记录、skills包等。~/.claude.json：全局设置文件。~/.anthropic/：相关的缓存数据。
确认这些数据不再需要后，手动删除。macOS和Linux：
rm -rf ~/.claude ~/.claude.json ~/.anthropicWindows上打开资源管理器，删除C:\Users\你的用户名\.claude等对应目录即可。
还有一个很容易漏掉的地方：VSCode扩展。如果你装过Claude Code扩展而不卸载，CLI本体虽然没了，但VSCode侧边栏那个Claude图标还在，点开会报"找不到claude命令"，非常误导人。在扩展面板里搜Claude Code，手动卸载。
6.2 Codex的卸载与清理
Codex的npm版卸载：
npm uninstall -g @openai/codex如果当初用的是brew安装的：
brew uninstall codex桌面版的话，直接在系统设置的应用列表里卸载。
配置目录的清理重点是这两处：
~/.codex/：含config.toml、auth.json、历史会话，全在这。~/.chatgpt/：旧版本Codex CLI的配置目录，如果存在一并删除。
删除后有个直接影响：token也没了，下次重装需要重新codex login。如果你打算直接重装并继续用，可以把config.toml先备份出来，装完拷回去，省去重新配置的时间。
6.3 环境变量残留与PATH检查
卸载完成后，如果你执行claude或codex居然还能"出结果"，大概率不是没卸载干净，而是存在环境变量和PATH残留。
需要检查的位置：
~/.bashrc、~/.zshrc、Windows的系统环境变量里，有没有ANTHROPIC_API_KEY、OPENAI_API_KEY、DEEPSEEK_API_KEY这类Key。- PATH里有没有指向老安装目录的条目。
- 有没有用pnpm或yarn等其他包管理器也全局装过一份，或者用独立安装器装过第二个副本。
确认没有残留后，重启终端再验证一遍。有时候从旧终端窗口看、从新终端窗口看，PATH都不一样，容易误判。
6.4 重装前的配置备份建议
如果你卸载是为了重装升级，别急着删配置目录。先把真正自己改过的文件备份出来：
- Codex：
~/.codex/config.toml - Claude Code：
~/.claude/settings.json
重装完，把备份拷回原位，能省掉重新配置的大量时间。但像auth.json这类认证文件，建议删除重新登录，因为换过环境或token过期后，旧认证大概率失效，留着反而可能干扰新登录。
这套流程我前前后后折腾了三四遍，最大的感受是：这两个工具安装本身都不难，难的是搞清楚它们背后那套配置文件逻辑。遇到报错，先拆解报错里的关键词，回到config.toml和settings.json看对应设置，十有八九能定位到问题。最后一条个人经验：如果你两个工具都要用，给它们分别建独立的工作目录，别在同一个项目里同时混用~/.claude和~/.codex的配置，否则切换供应商时，很容易被一份旧配置里的残留provider带偏。
