最近命令行里的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.jsClaude Code和Codex CLI本质上都是Node.js写的命令行程序通过npm全局安装分发。这不是个小细节很多人安装失败的第一道坎就出在Node版本上。两个工具对Node版本的要求是这样的工具npm包名Node.js版本要求Claude Codeanthropic-ai/claude-code官方要求18推荐20Codex CLIopenai/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 nodeLinux用户用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 Keyexport ANTHROPIC_API_KEYsk-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那边多也更容易绕晕。路线Anpm安装命令行版npm install -g openai/codex路线B官方桌面版OpenAI官网提供了Codex桌面应用分Windows和macOS两个版本。桌面版内部其实也是包了一层CLI对平时不爱碰终端的开发者友好很多很多人搜的codex官网下载codex安装包codex安装windows桌面版指的都是这条。macOS还有一个路线Cbrew 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接入自定义providercc-switch的新版本支持直接管理Codex的provider。添加provider时一般要填这几项Provider名称自定义比如DeepSeekBase URL比如https://api.deepseek.com/v1API Key模型名保存后cc-switch会把信息写进~/.codex/config.toml。这里有一个容易忽略的坑如果你之后手动改过config.tomlcc-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 proxycc-switch在本地监听了一个端口作为代理Codex把请求发到本地本地再转发给真实供应商。codex endpoint /responsesCodex默认请求的是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 CodeCodex CLI安装npm install -g anthropic-ai/claude-codenpm install -g openai/codex版本验证claude --versioncodex --version登录claude /logincodex login进入交互模式claudecodex非交互执行claude -p 生成一个排序算法codex exec 生成一个排序算法会话控制/clear清空上下文重开会话配置目录~/.claude~/.codex/config.toml卸载npm uninstall -g anthropic-ai/claude-codenpm 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和Linuxrm -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.tomlClaude Code~/.claude/settings.json重装完把备份拷回原位能省掉重新配置的大量时间。但像auth.json这类认证文件建议删除重新登录因为换过环境或token过期后旧认证大概率失效留着反而可能干扰新登录。这套流程我前前后后折腾了三四遍最大的感受是这两个工具安装本身都不难难的是搞清楚它们背后那套配置文件逻辑。遇到报错先拆解报错里的关键词回到config.toml和settings.json看对应设置十有八九能定位到问题。最后一条个人经验如果你两个工具都要用给它们分别建独立的工作目录别在同一个项目里同时混用~/.claude和~/.codex的配置否则切换供应商时很容易被一份旧配置里的残留provider带偏。
