1. Claude Code 安装与排障从 npm 到 cc-switch 的完整骨架Claude Code 是 Anthropic 推出的命令行 AI 编码工具能直接在终端里读写项目文件、跑命令、改代码适合习惯在 shell 里干活的后端、运维和全栈开发者。它的安装方式主要是 npm 全局包但真正让人卡住的往往不是安装本身而是装完之后报not be available、配置不生效、切换模型后请求 500 这几类问题。这篇就把我踩过的坑按顺序串一遍先用 npm 装好 Claude Code再用 cc-switch 管理多套配置最后把 settings.json 骨架和 TaoToken 的统一 Key/API 通道接进去并给出验证命令和排障清单。全程命令可直接复制Windows 和 macOS 都覆盖。2. 前置准备Node.js、npm prefix 与 TaoToken 通道2.1 确认 Node.js 与 npm 环境Claude Code 依赖 Node.js 18 以上版本先确认node -v npm -v如果node -v报找不到命令先去 Node.js 官网装 LTS 版本。装完重开终端再验证别在旧终端里反复试。2.2 理解 npm 全局安装路径这是 Windows 上最容易翻车的地方。npm install -g的安装位置取决于 npm 的全局 prefix而不是你当前所在的盘符。很多人改了 prefix 之后命令装成功了但终端里敲claude提示找不到就是因为那个 prefix 目录没进 PATH。# 查看全局安装根目录 npm root -g # 查看全局 prefix完整配置 npm config get prefix # 查看 npm 配置详情 npm config list拿到 prefix 路径后去系统环境变量 PATH 里把它加进去。Windows 在「此电脑 → 属性 → 高级系统设置 → 环境变量」里改macOS 在~/.zshrc或~/.bash_profile里加export PATH$PATH:你的prefix/bin。改完必须重开终端。2.3 TaoToken 统一 Key 与 API 通道Claude Code 默认走 Anthropic 官方端点但你可以把请求指向兼容的 API 通道用一个统一 Key 管理。TaoToken 提供的就是这种统一入口官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先去控制台建一个 Key后面 settings.json 里会用到。注意Key 只存在本地配置文件里别提交到 Git 仓库。建议把~/.claude/加进全局.gitignore。3. 可复制配置安装、cc-switch 与 settings.json 骨架3.1 安装 Claude CodeWindows 和 macOS 命令一致npm install -g anthropic-ai/claude-code装完验证claude --version如果提示claude: command not found或 Windows 上弹not be available回到 2.2 检查 prefix 是否进了 PATH。这一步 90% 的失败都是 PATH 问题不是安装失败。3.2 跳过首次引导可选首次运行会走 onboarding 流程如果你在脚本化环境里想跳过可以手动写标记位。Windows PowerShellpowershell -Command $f%USERPROFILE%\.claude.json;$jGet-Content $f|ConvertFrom-Json;$j|Add-Member -NotePropertyName hasCompletedOnboarding -NotePropertyValue $true -Force;$j|ConvertTo-Json|Set-Content $fmacOS 对应文件在~/.claude.json用jq或编辑器手动加hasCompletedOnboarding: true即可。3.3 用 cc-switch 管理多套配置cc-switch 是一个配置切换工具适合在官方端点和自建通道之间来回切。去它的 release 页下载对应平台版本安装后注册/配置把不同供应商的 Key 和 Base URL 存成 profile一键切换。这样你调试时不用手改 settings.json降低改错概率。3.4 settings.json 骨架Claude Code 的配置放在~/.claude/settings.jsonWindows 是%USERPROFILE%\.claude\settings.json。下面是一份可直接改的骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_Key, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 }, permissions: { allow: [], deny: [] }, hasCompletedOnboarding: true }几个关键点ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点注意不要带 UTM 参数ANTHROPIC_AUTH_TOKEN填你在控制台建的 KeyANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL分别是大模型和快速小模型按你账号可用的模型名填。改完保存重开终端。4. 验证请求与成功结果4.1 基础连通性验证先确认配置被读到claude --version claude config list然后跑一个最小请求看通道是否通claude -p 用一句话说明当前配置的模型名如果返回正常文本说明 Key、Base URL、模型名三者都对上了。4.2 在项目里实测进一个测试目录让 Claude Code 读文件cd ~/test-project claude -p 列出当前目录下的文件并说明每个文件的作用成功时它会调用工具读目录并给出结构化回答。这一步能同时验证模型通道和工具调用权限。4.3 成功结果长什么样正常返回是纯文本或带工具调用记录的输出没有error字段。如果返回体里出现type:error直接进下一节排查。5. 本篇常见错排查清单5.1 安装后命令找不到 / not be available症状npm install -g显示成功但敲claude提示找不到命令或 Windows 弹not be available。排查顺序先npm config get prefix拿到路径确认该路径下的binWindows 是根目录里有claude可执行文件再检查这个路径是否在 PATH 里最后重开终端。三步走完基本能解决。5.2 配置不生效症状改了 settings.json 但模型没变、还是走旧端点。排查确认文件路径是~/.claude/settings.json而不是项目目录下的确认 JSON 没有语法错误多余逗号最常见确认改完重开了终端。可以用claude config list看实际生效值。5.3 请求返回 500 insufficient balance症状{type:error,error:{type:api_error,message:insufficient balance (1008)},request_id:...}这是账户余额不足不是配置错误。去 TaoToken 控制台确认余额和 Key 状态充值或换一个有余额的 Key 即可。别在这个报错上反复改 settings.json方向错了。5.4 模型名不被识别症状返回模型不存在或 404。排查ANTHROPIC_MODEL填的模型名必须是账号可用的。不同通道支持的模型名可能不同去控制台或文档确认准确名称别凭记忆填。5.5 cc-switch 切换后没反应症状在 cc-switch 里切了 profile但 Claude Code 行为没变。排查cc-switch 本质是改 settings.json切完确认文件内容真的变了有些版本需要重启终端或重跑 Claude Code 才生效。如果 cc-switch 和手改冲突以最后一次写入为准。6. 后续接入与工具入口配置跑通之后日常最常用的几个入口需要新建或轮换 Key 时去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节和参数说明看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 想先在网页里验证模型对话效果用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 如果你要长期跑编码任务或 Agent 工作流Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 更划算控制台总入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后补一个实用习惯把 settings.json 备份一份到~/.claude/settings.json.bak每次大改前先备份。我试过在 cc-switch 和手改之间来回折腾有一次 JSON 少了个括号导致 Claude Code 直接起不来靠备份两分钟恢复。排障时优先看报错原文insufficient balance就去查余额command not found就去查 PATH别一上来就重装。