1. Claude Code 安装前必须搞定的 Node.js 与 Git 环境Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手你可以把它理解成一个「能直接读写你仓库的 AI 同事」——在终端里让它读代码、改文件、跑测试、生成 Git 提交信息。它适合谁适合已经习惯在终端里干活、希望把 AI 能力嵌进现有工作流的开发者。但很多人第一次装就卡在环境上所以这一节先把地基打牢。先说结论Claude Code 对运行环境的要求其实不复杂核心就两样——Node.js 和 Git。Node.js 是它的运行时底座Git 则是它理解项目历史、生成 diff、管理分支的「眼睛」。缺了 Node.js 直接跑不起来缺了 Git 虽然能启动但涉及版本控制的功能会残废。1.1 Node.js 版本要求与安装Claude Code 要求 Node.js 18 及以上我实测下来推荐直接上 LTS 20稳定性和兼容性都更好。先验证你机器上有没有node -v npm -v如果输出类似v20.11.1和10.2.4说明已经就绪。如果提示「不是内部或外部命令」那就得装。Windows 用户最省事的方式是用 wingetwinget install --id OpenJS.NodeJS.LTS -e --source wingetmacOS 用户如果装了 Homebrewbrew install node20Linux 用户可以用 nvm 管理多版本避免污染系统 Nodecurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完记得重开一个终端窗口让 PATH 生效再跑一次node -v确认。这一步踩过的坑是Windows 上装完不重启终端node命令死活找不到其实只是环境变量没刷新。1.2 Git 依赖为什么不能省很多人觉得「我就让 AI 改个文件要 Git 干嘛」。实际上 Claude Code 生成 diff、读取提交历史、按最佳实践建 feature 分支全靠 Git。没有 Git它连「你改了什么」都判断不准。Windows 安装winget install --id Git.Git -e --source wingetmacOSbrew install gitLinuxDebian/Ubuntusudo apt update sudo apt install git -y验证git --version输出git version 2.43.0之类即可。另外建议顺手配一下身份否则后续提交会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱1.3 环境自检清单在正式装 Claude Code 之前把下面三条命令都跑一遍全部有输出再往下走node -v # 期望 v18推荐 v20 npm -v # 期望 9 git --version # 期望 2.30如果npm版本过低可以单独升级npm install -g npmlatest环境这关过了后面安装基本就是一条命令的事。我建议你把这一节的命令存成一个setup-check.sh换新机器时直接跑省得每次重新回忆。2. TaoToken 前置准备拿到 Base URL 与 API KeyClaude Code 装好只是有了「壳」真正让它干活的是背后的模型服务。默认它连的是 Anthropic 官方但国内开发者更常用的是兼容 Anthropic 协议的接入方式。这里我用 TaoToken 作为示例因为它同时提供模型对话、Coding Plan 和 API Key 管理配置起来比较顺。2.1 为什么需要单独配置接入点Claude Code 启动时会读取两个关键环境变量ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。前者告诉它「请求发到哪」后者是身份凭证。如果你不配它会尝试走官方默认地址而官方地址在国内网络环境下往往连不上于是你就看到各种超时或 401。TaoToken 的作用就是提供一个兼容 Anthropic 接口规范的接入点你只要把 Base URL 指向它、把 Key 填进去Claude Code 就能正常对话。它不是什么「中转黑盒」而是一个标准的 API 网关请求格式和官方一致。2.2 获取 API Key 的步骤打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册登录后进入控制台。左侧菜单找到 API Keys 相关入口新建一个令牌。创建时注意选择支持 Claude 系列模型的分组复制出来的 Key 通常长这样sk-xxxxxxxxxxxxxxxxxxxxxxxx这个 Key 只显示一次务必先存到密码管理器里。如果你同时用多个工具建议一个工具一个 Key方便后续排查是哪个客户端在消耗额度。2.3 理解 Base URL 与 Model ID配置时你会用到三个东西我列个表对照一下配置项作用示例值Base URL请求发往的地址https://taotoken.net/apiAPI Key身份凭证sk-xxxxModel ID指定用哪个模型claude-sonnet-4-5 等注意 Base URL 这里用的是https://taotoken.net/api不要多加路径后缀Claude Code 会自己拼接/v1/messages。Model ID 则取决于你在控制台看到的具体模型名填错会报「model not found」。2.4 环境变量该配在哪不同系统配法不一样但原则是「配到当前 shell 能读到的地方」。临时测试可以直接在终端 export长期使用建议写进 shell 配置文件。macOS/Linuxbash写进~/.bashrc或~/.zshrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的KeyWindows PowerShell 临时设置$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你的KeyWindows 永久设置用setxsetx ANTHROPIC_BASE_URL https://taotoken.net/api setx ANTHROPIC_AUTH_TOKEN sk-你的Keysetx写完后要重开终端才生效。这一步最常见的错误是把 Key 里的空格或换行也复制进去导致鉴权失败粘贴后建议肉眼核对一遍首尾字符。3. 可复制配置Claude Code 安装命令与 settings 片段这一节是全文最核心的部分我把安装、配置、初始化拆成可以直接复制的步骤。你按顺序执行中间不要跳步。3.1 安装 Claude Code 的多种方式官方提供了一键脚本也有包管理器方式。macOS、Linux、WSL 用curl -fsSL https://claude.ai/install.sh | bashWindows PowerShellirm https://claude.ai/install.ps1 | iexWindows CMDcurl -fsSL https://claude.ai/install.cmd -o install.cmd install.cmd del install.cmd如果你更喜欢包管理器Homebrewbrew install --cask claude-codeWinGetwinget install Anthropic.ClaudeCodenpm 全局安装跨平台通用npm install -g anthropic-ai/claude-code我实测下来npm 方式最不容易出幺蛾子因为它复用了你已经装好的 Node 环境。一键脚本偶尔会因为网络问题中断重试即可。安装完验证claude --version输出类似2.1.81 (Claude Code)就说明装好了。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里npm config get prefix把这个路径加到 PATH 再重开终端。3.2 settings.json 配置文件写法Claude Code 支持通过配置文件持久化设置路径通常在用户目录下的.claude/settings.json。你可以手动创建内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [ Read, Edit, Bash(git status), Bash(git diff) ] } }这个片段里env段负责注入环境变量permissions段控制它默认能执行哪些操作。刚开始建议保守一点只放开读和 git 查看类命令等熟悉了再逐步加。如果你用 CC Switch 这类工具管理多套配置它本质上也是帮你切换这个 settings.json 里的 Base URL 和 Key。三件套Base URL Key Model ID必须同时正确缺一个都会失败。3.3 项目级配置与初始化进入你的项目根目录执行初始化cd /path/to/your-project claude首次启动它会引导你完成一些设置比如是否信任当前目录、是否允许读取文件。确认后进入交互界面。你也可以在项目里放一个.claude/settings.json覆盖全局配置适合团队统一环境。初始化时它会生成一个项目级的上下文索引这一步会读取你的目录结构。如果项目特别大比如几万个文件建议先在.claudeignore里排除node_modules、dist等目录否则首次索引会很慢。3.4 验证配置是否生效在交互界面里输入一句简单的话测试请用一句话介绍这个项目的技术栈如果它能正常回复说明 Base URL、Key、Model 三件套都通了。如果报错先别急着改配置往下看第五节我按真实报错逐条拆。4. 验证请求从启动到第一次成功对话配置写完不代表能用必须跑一次完整链路验证。这一节我带你走一遍从终端启动到拿到模型回复的全过程并给出每一步的预期结果。4.1 启动 Claude Code 并观察输出在项目目录下执行claude正常情况你会看到类似这样的欢迎信息然后进入提示符等待输入Claude Code v2.1.81 Tips: Use to reference files, /help for commands 如果卡在这里很久没反应多半是网络请求超时检查 Base URL 是否可达curl -I https://taotoken.net/api返回 200 或 401 都说明网络通401 只是没带 Key属于正常。4.2 发起第一次对话请求在提示符后输入请快速浏览项目结构告诉我技术栈和主要模块预期它会先调用文件读取工具列出目录然后给出分析。你会看到类似● Read(package.json) ● Read(src/) ⎿ 分析完成这是一个 React Vite 项目...这一步成功说明模型调用链路完全打通。如果它只回复文字但不读文件可能是权限没放开检查 settings.json 里的permissions.allow。4.3 用 引用上下文测试Claude Code 支持file和dir语法手动指定上下文。试一下请看 package.json 帮我解释一下依赖版本预期它会精准读取该文件并回答。这个功能很实用能避免它在大项目里乱翻文件。实测下来明确用指定文件比让它自己找响应速度快不少。4.4 验证 Git 相关能力让它生成一次 diff 看看请查看当前 git 改动总结我改了什么预期它会执行git diff并给出摘要。如果报「not a git repository」说明你不在 Git 仓库里先git init或切到正确目录。4.5 一次完整成功结果的判断标准把上面几步串起来一次成功的验证应该满足启动无报错、能读文件、能回答技术问题、能识别 Git 改动。四条都过说明你的 Claude Code 已经可以投入日常使用了。任何一条失败对照下一节排查。5. 本篇常见报错排查401、local proxy failed 与 reading choices这一节我按真实遇到的报错逐条拆每条给出原因和修复动作。你对照自己的终端输出找对应项。5.1 401 Unauthorized 鉴权失败报错长这样API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}原因通常是三类Key 复制错了、Key 前后有空格、环境变量没生效。排查顺序先确认环境变量真的被读到了echo $ANTHROPIC_AUTH_TOKEN如果输出为空说明没配成功。Windows 用echo $env:ANTHROPIC_AUTH_TOKEN有输出但仍是 401就把 Key 重新复制一遍注意不要带上Bearer前缀Claude Code 会自己加。还有一种情况是 Key 被禁用或额度耗尽去控制台确认状态。5.2 local proxy failed 连接失败报错Error: local proxy failed to connect这通常是 Base URL 写错或网络不通。检查两点一是 URL 结尾不要多写/v1正确写法是https://taotoken.net/api二是确认本机 DNS 能解析该域名。用 curl 测一下curl -v https://taotoken.net/api/v1/messages如果连 TCP 都建不起来就是网络层问题换个网络环境再试。5.3 reading choices 解析异常报错TypeError: Cannot read properties of undefined (reading choices)这个多半是返回体格式和预期不符常见于 Base URL 指向了一个 OpenAI 格式的接口而 Claude Code 期望 Anthropic 格式。确认你的 Base URL 是 Anthropic 兼容端点而不是 OpenAI 兼容端点。两者路径和请求体结构不同混用必报这个错。5.4 OAuth 相关报错报错OAuth error: invalid_grant如果你之前登录过官方账号本地可能残留了 OAuth token和现在的 API Key 模式冲突。清理掉旧凭证rm -rf ~/.claude/credentials.json然后重新用环境变量方式启动。注意使用 API Key 模式时不要再走 OAuth 登录流程两者选其一。5.5 命令找不到与权限错误claude: command not found说明 PATH 没配好回到 3.1 节检查 npm prefix。EACCES: permission denied则是 npm 全局目录权限问题macOS/Linux 可以改用 nvm 避免 sudonvm install 20 nvm use 20 npm install -g anthropic-ai/claude-code5.6 排查通用思路遇到任何报错先做三件事claude --version确认版本、echo $ANTHROPIC_BASE_URL确认地址、curl测端点连通性。这三步能定位 80% 的问题。剩下 20% 看具体错误信息里的关键词对照上面几节找。6. 长期使用建议与接入文档入口装好只是开始怎么用得顺手才是关键。这一节给你几条实战建议以及后续深入学习的入口。6.1 先计划再动手复杂任务别一上来就让它改代码。我习惯先要求请先给我一个分步骤计划不要改代码我确认后再执行这样能有效防止 AI 在理解复杂业务时跑偏。等计划确认了再让它逐步执行每步都能 review。6.2 善用上下文引用file和dir是提效利器。与其让它自己猜不如明确指定请看 src/app.tsx 帮我加一个 loading 状态定位更准响应更快也省 token。6.3 工程化协作改完代码后可以直接要求请按最佳实践新建一个 feature 分支并给出 PR 描述它会自动执行 git 操作并生成规范的提交信息。这一步建议先在测试仓库练手熟悉它的行为边界。6.4 多工具统一管理如果你同时用 Cline、Codex 等工具建议统一用同一套 Base URL 和 Key 管理避免到处散落凭证。TaoToken 的 Coding Plan 适合长期编码场景模型对话入口适合临时验证模型效果API Keys 页面则是所有接入的起点。6.5 后续学习入口想深入配置和排障可以查阅接入文档想先验证模型能力直接进模型对话页面试几句准备长期把 Claude Code 用于日常开发可以了解 Coding Plan。所有入口都在同一个控制台里配置一次到处复用。最后留一个实用技巧把本文 3.1 到 3.3 的命令整理成一个install-claude.sh换机器时一键跑完比每次翻文档快得多。环境变量和 settings.json 建议纳入你的 dotfiles 仓库这样新设备几分钟就能恢复完整开发环境。