1. 为什么第一次装 ClaudeCode 总卡在环境这一步ClaudeCode 是 Anthropic 推出的终端智能编程工具简单说就是让你在命令行里用自然语言指挥它读代码、改文件、跑任务。它适合已经习惯终端工作流、又想让 AI 直接操作本地代码库的开发者。但很多人第一次装它卡住的地方往往不是工具本身而是 Node.js 版本不对、npm 全局路径没配好、settings.json 放错目录、或者 claude-code-router 的 config.json 字段写错。这篇就按“从零到跑通”的顺序把 ClaudeCode 安装、Node.js 与 npm 版本校验、settings.json 关键字段、claude-code-router 接入位置一次讲清楚每一步都给可复制命令和验证动作。我试过在一台干净的 WSL 和一台 Windows 上各装一遍发现最容易翻车的其实是版本和路径这两件事。Node.js 低于 18 会直接报引擎不兼容npm 全局目录没进 PATH 会导致claude命令找不到settings.json 少一个字段就会在启动时反复要求登录。所以下面每个环节我都会带上“怎么确认它真的生效了”而不是装完就完事。先明确整体流程校验 Node.js 与 npm → 全局安装 ClaudeCode → 写 settings.json 指向模型服务 → 安装并配置 claude-code-router → 用 ccr 启动验证。你按这个顺序走基本能一次跑通。如果你只是想先体验模型对话能力也可以先到模型对话页面感受一下接口返回再回来配本地环境这样对字段含义会更有感觉。需要提前说明的是本文所有第三方接口地址都以你实际申请到的为准配置里的sk-xxx要换成你自己的 Key。下面进入具体操作。2. Node.js 与 npm 版本校验及 ClaudeCode 全局安装2.1 校验 Node.js 与 npm 版本ClaudeCode 要求 Node.js 18.0 及以上。先开终端确认node -v npm -v正常会输出类似v20.11.1和10.2.4。如果node -v报 command not found说明没装或没进 PATH如果版本低于 18需要升级。Windows 和 Linux含 WSL都建议用 nvm 管理版本避免直接覆盖系统 Node。Linux/WSL 安装 nvm 并切到 20curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -vWindows 可以用 nvm-windows装完后同样nvm install 20再nvm use 20。切完再跑一次node -v确认输出 20.x。这一步别跳过版本不对后面全白搭。2.2 全局安装 ClaudeCode确认版本没问题后执行全局安装npm install -g anthropic-ai/claude-code安装完成后验证命令是否可用claude --version如果提示claude: command not found多半是 npm 全局 bin 目录没进 PATH。先查全局目录npm config get prefixLinux/macOS 一般输出/usr/local或~/.nvm/versions/node/v20.x.x对应的可执行文件在bin子目录。把这个bin路径加进~/.bashrc或~/.zshrcexport PATH$PATH:$(npm config get prefix)/bin source ~/.bashrcWindows 下npm config get prefix通常输出C:\Users\用户名\AppData\Roaming\npm把这个路径加到系统环境变量 Path 里重开终端再试claude --version。2.3 首次启动与目录确认安装成功后进入你的项目目录再启动cd your-project claude第一次启动会在用户目录下生成配置目录。Windows 是C:\Users\用户名\.claudeLinux/WSL 是~/.claude。这个目录就是后面放 settings.json 的地方先记住它。如果启动时提示登录先别急着登录下一步我们用 settings.json 直接指定模型服务跳过官方登录流程。3. settings.json 关键字段与 claude-code-router 接入配置3.1 settings.json 字段逐项说明在~/.claudeWindows 为C:\Users\用户名\.claude下创建settings.json。这个文件的作用是告诉 ClaudeCode用哪个接口、用哪个 Key、用哪个模型。模板如下{ env: { ANTHROPIC_AUTH_TOKEN: sk-xxx, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-sonnet-4-20250514 } }逐项解释ANTHROPIC_AUTH_TOKEN是你的 API Key把sk-xxx换成实际值ANTHROPIC_BASE_URL是接口地址注意结尾不要多加斜杠ANTHROPIC_MODEL是主模型 IDANTHROPIC_SMALL_FAST_MODEL是处理轻量任务时用的快速模型可以填同一个。这四个字段缺一个都可能在启动时报鉴权或模型不存在。写完后保存重新在项目目录执行claude。如果配置生效界面不会再要求登录而是直接进入对话。你可以输入一句“列出当前目录的文件”测试它是否能正常调用。3.2 安装 claude-code-routerclaude-code-router简称 ccr是一个中间层把 ClaudeCode 发出的 Anthropic 格式请求转成 OpenAI 格式再转发给兼容 OpenAI 接口的模型。它的价值在于模型选择更灵活、成本更可控。全局安装npm install -g musistudio/claude-code-router验证ccr -v3.3 config.json 配置模板ccr 的配置文件位置Windows 是C:\Users\用户名\.claude-code-router\config.jsonLinux/WSL 是~/.claude-code-router/config.json。模板{ Providers: [ { name: taotoken, api_base_url: https://taotoken.net/api/v1/chat/completions, api_key: sk-xxx, models: [ claude-sonnet-4-20250514 ] } ], Router: { default: taotoken,claude-sonnet-4-20250514 } }Providers里name是自定义标识api_base_url填兼容 OpenAI 的接口地址api_key换成你的 Keymodels列出可用模型。Router.default的格式是provider名,模型ID要和上面保持一致。字段写错最常见的表现是启动后请求 404 或模型不存在。3.4 ccr 常用指令配置好后ccr start启动路由服务。然后ccr code通过 ccr 启动 ClaudeCode。想可视化改配置可以用ccr ui。如果ccr start报端口占用检查是否有旧进程没退干净。4. 验证请求与确认安装成功4.1 直接验证 settings.json 路径先不经过 ccr直接跑claude输入帮我读取 package.json 并总结依赖如果它能返回文件内容摘要说明 settings.json 的 Base URL、Key、Model 三个字段都通了。这一步是基础验证别跳过。4.2 验证 ccr 路由先ccr start看到服务启动日志后另开终端ccr code。进入后同样输入一句测试指令。如果返回正常说明请求经过了 ccr 转换并成功拿到响应。此时你可以查看 ccr 的日志输出确认请求确实走了你配置的 provider。4.3 用 curl 单独验证接口想更直接地确认接口可用可以绕过 ClaudeCode 直接打接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回里有choices字段且内容正常说明 Key 和地址都没问题。如果这里就报 401那问题在 Key如果报模型不存在问题在模型 ID。把这两层分开验证排障会快很多。4.4 确认安装成功的三个标志第一claude --version有输出第二claude启动后不要求登录且能响应指令第三ccr code启动后请求能正常返回。三个都满足就算完整跑通了。此时你可以到 API Keys 页面管理你的 Key或到接入文档对照更多字段说明。5. 常见报错排查对照5.1 401 鉴权失败报错形如401 Unauthorized或invalid api key。原因通常是 Key 写错、Key 已失效、或ANTHROPIC_AUTH_TOKEN和 ccr 里的api_key不一致。排查先用上面 4.3 的 curl 单独测 Key通了再回头检查配置文件里有没有多余空格或引号。5.2 local proxy failedccr 启动后 ClaudeCode 报local proxy failed或连接被拒。多半是ccr start没真正跑起来或端口被占用。先确认ccr start的终端还在运行再检查端口。重启顺序也有讲究先ccr start等日志稳定后再ccr code。5.3 reading choices 报错返回里提示reading choices或choices is undefined说明响应格式不是预期的 OpenAI 结构。常见原因是api_base_url填成了不带/v1/chat/completions的根地址或者填了 Anthropic 格式的地址却用 OpenAI 解析。对照第 3.3 节模板确认路径完整。5.4 OAuth 相关报错如果启动时反复跳 OAuth 登录说明 settings.json 没被读到。检查文件是否真的在~/.claude/settings.json文件名是否拼错JSON 是否合法可以用python -m json.tool settings.json校验。JSON 里多一个逗号都会导致整个文件被忽略。5.5 模型不存在报model not found或类似提示。检查ANTHROPIC_MODEL和 ccr 里models列表、Router.default三处的模型 ID 是否完全一致。模型 ID 大小写和连字符都要对。5.6 命令找不到claude或ccr报 command not found回到 2.2 节检查 npm 全局 bin 是否进 PATH。改完环境变量一定要重开终端或source配置文件。6. 跑通之后怎么继续用环境搭好只是起点。日常使用中你可以把常用模型固定进 settings.json把多模型切换交给 ccr 的 Router 配置。如果长期做编码和 Agent 任务建议了解 Coding Plan它在持续调用场景下更省心。需要管理多个 Key 时API Keys 页面可以集中处理。字段含义拿不准就翻接入文档比反复试错快。最后留一个实用习惯每次改完 settings.json 或 config.json先用python -m json.tool校验一遍再启动能省掉一大半“配置没生效”的困惑。装一次跑通后面就是调模型和调工作流的事了。