1. 为什么第一次装 Claude Code 总卡在环境这一步
Claude Code 是 Anthropic 推出的终端 AI 编程工具，能直接在命令行里读写项目文件、跑测试、改代码。它适合已经习惯终端操作的开发者，尤其是想让 AI 帮忙处理多文件重构、批量改配置、写脚本这类活儿的人。但它不像普通 npm 包那样装完就能用，第一次上手最容易卡在三个地方：Node.js 版本不对、npm 全局安装权限报错、以及启动后连不上服务。
我见过太多人在这三步里反复折腾。有人 node -v 显示 v14，装完 claude 直接报语法错误；有人在 Windows 的 system32 目录下跑 claude，被提示信任文件夹时手一抖点了 yes，结果 AI 差点去改系统文件；还有人装完启动，屏幕上跳出Unable to connect to Anthropic services，然后就不知道下一步该干嘛了。
这篇教程就按真实操作顺序走一遍：先把 Node.js 和 npm 环境弄干净，再装 Claude Code 本体，然后用 cc-switch 这个配置管理工具把 API Key 管起来，最后用 taotoken.net 的统一 Key 通道发一次对话请求，确认整条链路通了。全程命令可复制，配置文件给完整片段，报错对照着排查。
cc-switch 在这里的角色很关键。它是一款跨平台的 Claude Code 配置切换器，你可以把它理解成 AI 编程工具的“遥控器”——不用手动去改.claude.json或者环境变量，点几下就能在不同模型服务商之间切换。对于需要同时用多个模型、或者想统一管理 Key 的开发者来说，它省掉了大量手改配置的麻烦。
下面从环境准备开始，一步步来。
2. Node.js 与 npm 环境准备：版本、镜像与全局安装权限
Claude Code 对 Node.js 版本有要求，官方建议 18 以上。我实测下来，Node 20 LTS 最稳，Node 22 也能跑。先去 nodejs.org 下载对应系统的安装包，Windows 选.msi，macOS 选.pkg，装完打开终端验证。
node -v npm -v如果输出类似v20.11.1和10.2.4，说明基础环境 OK。如果 node 命令找不到，检查安装时有没有勾选“Add to PATH”。
接下来处理 npm 下载源。默认的registry.npmjs.org在国内访问经常超时，装全局包时容易卡住。切换成 npmmirror 镜像：
npm config set registry https://registry.npmmirror.com npm config get registry第二条命令应该返回https://registry.npmmirror.com/，确认生效。
然后是全局安装权限问题。Linux 和 macOS 下直接npm install -g可能报EACCES权限错误。两种解法：一是用 nvm 管理 Node，全局包会装到用户目录下，不碰系统目录；二是改 npm 全局目录：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATHWindows 下如果用管理员 CMD 装全局包，一般不会报权限错，但要注意别在C:\Windows\system32里操作。装完 Claude Code 后，第一次启动会让你选一个工作目录，这时候一定要切到自己的项目文件夹，比如D:\projects\test-claude，别在系统目录里点信任。
环境准备好之后，装 Claude Code 本体：
npm install -g @anthropic-ai/claude-code claude -vclaude -v能输出版本号就说明安装成功。如果报command not found，检查 npm 全局 bin 目录有没有加到 PATH 里。
这一步做完，Node.js、npm、Claude Code 三件套就齐了。接下来是配置管理，也是很多人第一次启动后卡住的地方。
3. cc-switch 配置 API Key：完整 settings 片段与三件套写法
Claude Code 第一次启动会走一个引导流程，要求登录 Anthropic 账号。如果你没有官方账号，或者想用其他模型服务，就会卡在登录页。这时候有两个选择：一是手动改.claude.json跳过引导，二是用 cc-switch 来管理配置。
手动改.claude.json的方式是在用户目录下找到这个文件（Windows 是C:\Users\你的用户名\.claude.json，macOS/Linux 是~/.claude.json），加上：
{ "hasCompletedOnboarding": true }这个字段的作用是标记首次引导已完成，下次启动直接进主界面。但光跳过引导还不够，你还得告诉 Claude Code 用哪个 API 端点、哪个 Key、哪个模型。这些信息如果全塞在.claude.json里，切换服务商时就得反复手改，很容易出错。
cc-switch 就是来解决这个问题的。去 GitHub 的 releases 页面下载对应系统的安装包，Windows 推荐.msi安装版，macOS 用.dmg，Linux 有.deb和.AppImage。装完之后打开，界面里可以添加多个供应商配置。
这里以 taotoken.net 的统一 Key 通道为例，写一份完整的配置。在 cc-switch 里添加新供应商时，需要填三件套：Base URL、API Key、Model ID。
{ "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的taotoken密钥", "model": "claude-sonnet-4-20250514", "settings": { "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的taotoken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } } }如果你习惯直接改 Claude Code 的 settings 文件，路径在~/.claude/settings.json，内容写成：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的taotoken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }注意 Base URL 这里写的是https://taotoken.net/api，不要多加路径后缀。API Key 去 taotoken.net 的 console 里生成，模型 ID 按你实际要用的填。cc-switch 的好处是这些配置可以在界面里保存成多个方案，点一下就能切换，不用每次手改 JSON。
配置保存后，回到终端启动 claude，它就不会再要求登录，而是直接读取环境变量里的 Base URL 和 Key。你可以用/model命令查看当前生效的模型，确认是不是你配置的那个。
这一步的关键是三件套必须写全：Base URL 指向 taotoken.net/api，API Key 用 taotoken 生成的，Model ID 写清楚。少任何一个，启动后都会报连接错误。
4. 验证请求：用一次对话确认环境可用
配置写完，启动 claude 进到交互界面，先别急着让它改代码。用最简单的对话测试一下链路通不通。
启动命令：
claude进去之后，输入一句测试：
你好，请用一句话说明你当前使用的模型名称。如果配置正确，它会正常回复。如果报错，对照下一节的排查表处理。
更严谨的验证方式是直接用 curl 打一次 API，确认 Key 和端点都没问题：
curl https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的taotoken密钥" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": [ {"role": "user", "content": "回复 OK 两个字母即可"} ] }'如果返回 JSON 里content字段有内容，说明 Key 和端点都正常。这一步能排除掉 Claude Code 客户端本身的问题，把故障范围缩小到配置层。
在 Claude Code 里还可以用/model命令确认当前模型：
/model它会列出当前生效的模型 ID。如果显示的不是你配置的那个，说明环境变量没被正确读取，检查 settings.json 的路径和 JSON 格式。
实测下来，只要 Base URL、Key、Model 三件套写对，第一次对话基本都能通。如果卡住，大概率是下面几种报错之一。
5. 常见报错排查：401、local proxy failed 与 OAuth 问题
这一节按真实报错来对照。你遇到哪个，直接找对应条目。
报错一：401 Unauthorized
API Error: 401 - {"error":{"type":"authentication_error","message":"invalid x-api-key"}}原因通常是 Key 写错、Key 过期、或者 Base URL 和 Key 不匹配。排查步骤：先去 taotoken.net 的 console 确认 Key 还在有效期内，然后检查 settings.json 里ANTHROPIC_API_KEY的值有没有多余空格或换行。如果 Key 是从网页复制的，注意别把前后空白带进去。
报错二：local proxy failed
Error: local proxy failed to start这个多半是端口被占用，或者 cc-switch 的代理进程没起来。先检查有没有其他程序占了 Claude Code 默认的本地端口，关掉冲突进程再试。如果用 cc-switch 切换供应商后出现这个错，重启一下 cc-switch，让它重新写入配置。
报错三：reading choices 相关错误
TypeError: Cannot read properties of undefined (reading 'choices')这是响应格式不匹配导致的。常见于 Base URL 写成了 OpenAI 兼容格式的端点，但 Claude Code 期望的是 Anthropic 格式的响应。确认 Base URL 是https://taotoken.net/api，不要自己加/v1/chat/completions这类后缀。taotoken 的 API 端点已经做了格式适配，按文档给的地址写就行。
报错四：OAuth 登录循环
启动后一直跳登录页，或者提示OAuth token expired。这是因为.claude.json里的hasCompletedOnboarding没生效，或者环境变量没覆盖掉默认的登录逻辑。检查两点：一是.claude.json里确实有"hasCompletedOnboarding": true；二是 settings.json 里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY都写对了。两个都确认后重启终端。
报错五：Unable to connect to Anthropic services
这个在原文里也出现过。本质是客户端尝试连默认的 Anthropic 端点失败。如果你已经配了 taotoken 的 Base URL，还报这个错，说明环境变量没被读取。检查 settings.json 的路径是不是~/.claude/settings.json，Windows 下是C:\Users\你的用户名\.claude\settings.json。路径不对，配置就不生效。
排查顺序建议：先 curl 测 API 通不通，再检查 settings.json 格式，最后看 cc-switch 有没有正确写入。三步走完，基本能定位到问题。
6. 配置完成后怎么用：模型切换与长期使用建议
环境通了之后，日常使用就简单了。在 Claude Code 里用/model切换模型，cc-switch 里保存的多个供应商方案可以随时切换。如果你需要长期跑编码任务或者 Agent 流程，建议把常用配置固定下来，别每次临时改。
taotoken.net 的 API Key 可以在 console 里管理，生成多个 Key 分配给不同项目，方便追踪用量。接入文档里有完整的端点说明和参数列表，遇到格式问题先翻文档。
对于需要频繁切换模型的场景，cc-switch 的方案管理比手改 JSON 高效得多。你可以给每个项目建一个配置方案，点一下切换，不用记那些环境变量名。
最后提醒一点：Claude Code 第一次启动时选工作目录，一定选自己的项目文件夹，别在系统目录里点信任。这个坑我踩过，AI 拿到系统目录的写权限后，改起文件来是真的不客气。
