1. 为什么国内开发者第一次跑 Claude Code 总卡在配置这一步Claude Code 是 Anthropic 推出的终端 AI 编程助手能直接在命令行里读项目、改代码、跑测试对习惯终端工作流的开发者来说体验很顺。但国内开发者第一次上手真正卡住的往往不是工具本身而是配置环节Node.js 版本不对、npm 全局安装权限报错、环境变量写错位置、settings.json 骨架不知道长什么样、填完 Key 之后请求到底通没通也没法确认。我见过太多人装完anthropic-ai/claude-code敲claude之后要么提示认证失败要么一直转圈最后怀疑是工具问题其实是环境变量没生效或者 Base URL 拼错了。这篇就聚焦「本地首次跑通」这一段把 Node.js/npm 安装后的环境变量配置、settings.json 骨架、统一 Key 的填入位置以及一条 curl 验证命令讲清楚让你能自查配置是否真的生效。适合人群已经装好 Node.js、准备在本地项目里第一次启动 Claude Code 的开发者或者之前配过但不确定是否生效、想系统核对一遍的人。下面所有命令和配置都可以直接复制改掉 Key 就能用。2. TaoToken 统一 Key 的前置准备TaoToken 在这里扮演的角色是「统一入口」你不需要在多个模型服务之间来回切换 Key 和地址用一个 Key 就能走通 Claude Code 的请求。对国内开发者来说省掉的是反复改环境变量、反复确认地址的麻烦。你需要先拿到两样东西一是 API Key。登录 TaoToken 控制台后在 API Keys 页面创建一个新 Key复制保存好后面填环境变量和 settings.json 都要用。创建入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup二是确认 Base URL。Claude Code 走的是 Anthropic 兼容协议统一入口地址是https://taotoken.net/api注意这个地址后面不加 UTM 参数直接作为ANTHROPIC_BASE_URL的值使用。如果你在文档里看到别的路径拼接方式以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup提示Key 只在创建时完整显示一次建议创建后立刻存到密码管理器里。如果丢了就重新建一个不要试图找回。前置准备做完接下来就是真正容易出错的环节环境变量和 settings.json。3. 可复制的环境变量与 settings.json 配置3.1 先确认 Node.js 和 npm 版本Claude Code 要求 Node.js ≥ 18。先跑一遍node --version npm --version如果 node 版本低于 18用 nvm 升级最省事nvm install 20 nvm use 20 node --versionWindows 用户如果用官方 msi 安装直接在 PowerShell 里验证即可。版本没问题再往下走。3.2 安装 Claude Codenpm install -g anthropic-ai/claude-code claude --version如果npm install -g报权限错误EACCES不要用 sudo 硬装改成配置 npm 全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH npm install -g anthropic-ai/claude-code这样装完claude命令就能在当前用户下正常调用。3.3 环境变量写入配置文件临时生效的方式是在当前终端 export但关掉就没了。推荐写进 shell 配置文件一劳永逸。macOS / Linuxzsh 用户echo ~/.zshrc echo export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey ~/.zshrc echo export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.zshrc source ~/.zshrcbash 用户把~/.zshrc换成~/.bash_profile或~/.bashrc即可。Windows PowerShell 用户用[Environment]::SetEnvironmentVariable(ANTHROPIC_AUTH_TOKEN,sk-你的TaoTokenKey,User) [Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL,https://taotoken.net/api,User)设置完重开一个终端验证是否写入成功echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN两个值都能正确打印出来说明环境变量这一层没问题。3.4 settings.json 骨架Claude Code 支持在项目或用户目录下放settings.json来做更细的配置。用户级配置放在~/.claude/settings.json项目级放在项目根目录的.claude/settings.json。一个最小可用骨架如下{ env: { ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_BASE_URL: https://taotoken.net/api }, permissions: { allow: [], deny: [] } }这里env字段里的两个键就是统一 Key 的填入位置。如果你已经在 shell 里配了环境变量settings.json 里的env可以留空或者不写两者取其一即可避免重复配置导致排查困难。我一般建议新手先用环境变量跑通再迁移到 settings.json这样出问题容易定位。注意settings.json 必须是合法 JSON不能有注释、不能有多余逗号。改完可以用python -m json.tool ~/.claude/settings.json校验一下格式。4. 验证请求是否真的走通了配置写完不代表生效必须验证。最直接的方式是用 curl 打一次接口确认请求经https://taotoken.net/api正常返回。curl -sS https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [ {role: user, content: 只回复两个字通了} ] }如果配置正确你会看到一段 JSON 返回里面content字段包含模型回复的文本。如果返回 401说明 Key 没读到或者写错了返回 404多半是 Base URL 拼错连接超时则检查网络和地址是否可达。curl 通了之后再进项目目录启动 Claude Codecd your-project-folder claude首次启动会依次让你选主题、确认安全须知、选终端配置、信任工作目录按提示回车即可。进入交互界面后随便问一句「这个项目是做什么的」如果模型能正常读文件并回答说明整条链路已经打通。想更直观地对比不同模型在同样配置下的表现可以到模型对话页面手动发几条请求做对照https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup5. 本篇常见错误与排查清单配置环节的报错大多集中在几个固定位置对照下面这张表基本能自查。现象可能原因处理方式claude: command not foundnpm 全局 bin 不在 PATH配置 npm prefix 并把 bin 加入 PATH401 UnauthorizedKey 未生效或写错echo $ANTHROPIC_AUTH_TOKEN核对检查 settings.json404 Not FoundBase URL 拼错确认值为https://taotoken.net/api不要多加路径一直转圈无响应环境变量未 source重开终端或source ~/.zshrcsettings.json 报解析错误JSON 格式非法用python -m json.tool校验改了配置但没变化环境变量与 settings.json 冲突只保留一处配置删掉重复项几个容易忽略的点一是ANTHROPIC_BASE_URL结尾不要带斜杠带了可能拼出双斜杠导致 404二是 Windows 下环境变量设置后必须重开终端才生效三是如果你同时装了多个版本的 Nodenpm install -g装到了另一个版本下claude命令自然找不到用which node和which npm确认路径一致。排障过程中如果反复卡在认证或地址上直接对照接入文档里的字段说明逐项核对最快https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup6. 长期使用与 Agent 场景的配置建议如果你只是偶尔在终端里问几句环境变量加 settings.json 就够了。但如果你打算把 Claude Code 当成日常主力或者要跑长时间、多轮的 Agent 任务建议把 Key 管理单独拎出来。一个实用做法是在项目里用.env存 Key通过 direnv 之类的工具按目录自动加载这样不同项目可以用不同 Key互不干扰。另一个做法是把长期任务和临时调试分开长期任务用专门的 Key方便在控制台里单独看用量。对于需要持续跑、调用量较大的场景Coding Plan 会比按次调用更省心配置方式也更适合固定下来https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup最后提醒一句配置这东西跑通一次之后把 settings.json 和环境变量文件备份一份换机器或者重装系统时直接复制能省掉大量重复排查的时间。真正麻烦的从来不是工具本身而是那些看起来不起眼、但错一个字符就全盘不通的配置项。