ClaudeCode 安装指南：从 Node.js 到 settings.json 的完整配置流程

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 并切到 20：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v

Windows 可以用 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 prefix

Linux/macOS 一般输出/usr/local或~/.nvm/versions/node/v20.x.x，对应的可执行文件在bin子目录。把这个bin路径加进~/.bashrc或~/.zshrc：

export PATH="$PATH:$(npm config get prefix)/bin" source ~/.bashrc

Windows 下npm config get prefix通常输出C:\Users\用户名\AppData\Roaming\npm，把这个路径加到系统环境变量 Path 里，重开终端再试claude --version。

2.3 首次启动与目录确认

安装成功后，进入你的项目目录再启动：

cd your-project claude

第一次启动会在用户目录下生成配置目录。Windows 是C:\Users\用户名\.claude，Linux/WSL 是~/.claude。这个目录就是后面放 settings.json 的地方，先记住它。如果启动时提示登录，先别急着登录，下一步我们用 settings.json 直接指定模型服务，跳过官方登录流程。

3. settings.json 关键字段与 claude-code-router 接入配置

3.1 settings.json 字段逐项说明

在~/.claude（Windows 为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是主模型 ID；ANTHROPIC_SMALL_FAST_MODEL是处理轻量任务时用的快速模型，可以填同一个。这四个字段缺一个都可能在启动时报鉴权或模型不存在。

写完后保存，重新在项目目录执行claude。如果配置生效，界面不会再要求登录，而是直接进入对话。你可以输入一句“列出当前目录的文件”测试它是否能正常调用。

3.2 安装 claude-code-router

claude-code-router（简称 ccr）是一个中间层，把 ClaudeCode 发出的 Anthropic 格式请求转成 OpenAI 格式，再转发给兼容 OpenAI 接口的模型。它的价值在于模型选择更灵活、成本更可控。全局安装：

npm install -g @musistudio/claude-code-router

验证：

ccr -v

3.3 config.json 配置模板

ccr 的配置文件位置：Windows 是C:\Users\用户名\.claude-code-router\config.json，Linux/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换成你的 Key，models列出可用模型。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 failed

ccr 启动后 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校验一遍再启动，能省掉一大半“配置没生效”的困惑。装一次跑通，后面就是调模型和调工作流的事了。