1. 从零跑通 Claude CodeNode.js 环境准备与 npm 安装避坑Claude Code 是 Anthropic 推出的命令行 AI 编程助手简单说就是你把需求用中文讲给它它自己读文件、改代码、跑命令、修 bug。适合谁适合刚接触命令行、想用 AI 辅助写代码但不想折腾复杂 IDE 插件的开发者。它跑在终端里所以第一步不是装 Claude Code而是把 Node.js 和 npm 准备好——因为 Claude Code 是通过 npm 分发的。我见过太多人卡在第一步终端里敲node --version提示「不是内部或外部命令」或者 npm 装到一半卡死。这一节就把这些坑一次填平。先检查你电脑上有没有 Node.js。打开终端Windows 按 WinR 输入 cmdmacOS 打开「终端」输入node --version npm --version如果输出类似v20.11.0和10.2.4说明已经有了直接跳到第 2 节。如果提示找不到命令就按下面系统对应安装。Windows 用户去 nodejs.org点左边绿色的 LTS 按钮下载.msi安装包双击一路 Next → Install → Finish。装完必须关掉终端重新开一个否则 PATH 不生效。macOS 用户推荐用 Homebrew一条命令搞定brew install node没装过 Homebrew 的话先执行官方安装脚本。LinuxUbuntu/Debian用 NodeSource 源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完再验证一次node --version看到版本号才算过关。接下来装 Claude Code 本体npm install -g anthropic-ai/claude-code-g是全局安装装完在任何目录都能用claude命令。验证claude --version看到v2.x.x就成功了。如果 npm 下载慢或卡住换国内镜像npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.commacOS/Linux 如果报EACCES权限错误别急着加 sudo更推荐改 npm 全局目录一劳永逸mkdir ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后重新执行安装命令。这一步做完环境就齐了。很多人问「Claude Code 本地安装教程」到底难在哪其实难点全在环境变量和 PATH 上命令本身只有一行。2. TaoToken 前置准备API Key 获取与 Base URL 配置Claude Code 装好了但它还不知道该调用哪个模型。默认情况下它会找 Anthropic 官方接口需要付费订阅。对国内开发者更友好的做法是走兼容 Anthropic 协议的 API 服务TaoToken 就是这样一个入口它提供统一的 Base URL 和 API KeyClaude Code 只要改两个环境变量就能接上。先去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号登录后进入控制台。在左侧找到「API Keys」点创建复制那串sk-开头的密钥。这个 Key 只显示一次先存到记事本里。TaoToken 的 API 地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 Base URL 使用。Claude Code 认的环境变量名是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN前者填 TaoToken 的 API 地址后者填你刚复制的 Key。这里有个关键点Claude Code 会区分不同档位的模型Haiku/Sonnet/Opus你需要告诉它每个档位实际映射到哪个模型 ID。TaoToken 控制台的「模型对话」页面能看到当前可用的模型列表把模型 ID 抄下来填进配置。如果你不确定填什么先用一个通用模型 ID 跑通链路后面再细化。配置方式有两种写配置文件或者设系统环境变量。推荐写配置文件因为 Claude Code 每次启动都会读~/.claude/settings.json不用每次开终端都 export。Windows 用户注意路径是%USERPROFILE%\.claude\settings.jsonmacOS/Linux 是~/.claude/settings.json。创建目录mkdir -p ~/.claudeWindows 在文件资源管理器地址栏输入%USERPROFILE%新建.claude文件夹。然后在这个文件夹里新建settings.json内容下一节给。这一步做完Claude Code 就知道「去哪调用、用哪个 Key、用哪个模型」了。顺便说一句如果你后面要长期跑编码任务或 Agent 流程可以了解下 Coding Plan它针对高频调用做了额度优化比按次计费更划算。入口在控制台里能找到。3. 可复制配置settings.json 完整片段与参数说明这一节直接给可复制的配置。在~/.claude/settings.json里写入以下 JSON{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: 你的主模型ID, ANTHROPIC_DEFAULT_HAIKU_MODEL: 你的轻量模型ID, ANTHROPIC_DEFAULT_SONNET_MODEL: 你的中档模型ID, ANTHROPIC_DEFAULT_OPUS_MODEL: 你的高档模型ID } }把sk-你的TaoToken密钥换成第 2 节复制的真实 Key把四个模型 ID 换成 TaoToken 控制台里看到的实际值。四个模型字段的作用是当你用/model haiku切换时Claude Code 会去调ANTHROPIC_DEFAULT_HAIKU_MODEL指定的模型不指定--model时用ANTHROPIC_MODEL。如果你只想先跑通可以四个字段填同一个模型 ID等链路验证成功再细分。JSON 格式很严格键和值都要双引号最后一项后面不能有逗号。写完可以用在线 JSON 校验工具过一遍或者直接让 Claude Code 自己检查。Windows 用户如果不想写文件也可以用 PowerShell 设环境变量setx ANTHROPIC_BASE_URL https://taotoken.net/api setx ANTHROPIC_AUTH_TOKEN sk-你的TaoToken密钥但setx设置的是用户级环境变量需要重开终端才生效而且模型映射字段不好设所以还是推荐 settings.json。配置文件的路径必须准确。macOS/Linux 下~展开是/Users/你的用户名或/home/你的用户名Windows 下是C:\Users\你的用户名。如果你把文件放错地方Claude Code 读不到就会报「未设置 ANTHROPIC_API_KEY」。写完后可以快速检查文件是否存在cat ~/.claude/settings.jsonWindows 用type %USERPROFILE%\.claude\settings.json能看到内容就说明路径对了。这一步是整个接入的核心配置对了后面就顺了。4. 验证请求最小对话与项目上下文读取实测配置写完先做最小验证。在终端输入claude -p hello-p是 print 模式问一句答一句就退出。如果返回一段问候语说明 Base URL、Key、模型 ID 三者都通了。如果报错先看第 5 节的排查表。链路通了之后验证它能不能读项目上下文。随便找个项目目录cd /你的项目路径 claude -p 帮我看看这个项目在做什么 --max-turns 5--max-turns 5限制最多执行 5 轮操作防止它跑飞。正常的话它会列出目录结构、读几个关键文件然后给你一段项目概述。这一步验证的是 Claude Code 的工具调用能力——它不只是聊天而是真的能读文件。再试一个代码审查场景git diff | claude -p 帮我审查这些改动重点看有没有 bug 和安全问题 --max-turns 1把git diff的输出通过管道传给它它就能针对改动给意见。这个用法在提交代码前特别实用。最后验证 CLAUDE.md 是否生效。在项目根目录新建CLAUDE.md# 我的项目 ## 技术栈 - Python 3.12 FastAPI SQLAlchemy - PostgreSQL 数据库 ## 常用命令 - pytest 跑测试 - ruff check . 做代码检查 ## 代码规范 - Python 用 4 空格缩进 - 所有公开函数必须有类型标注 - 测试文件命名 test_*.py然后问它claude -p 这个项目用什么测试命令如果它回答pytest说明 CLAUDE.md 被自动读取了。Claude Code 每次进入项目都会读这个文件相当于给它的「项目记忆」。你可以在里面写技术栈、目录约定、禁止修改的文件、提交规范等省得每次重复交代。交互模式也值得试一下claude直接回车进入 TUI 界面可以多轮对话、用/model切模型、用/compact压缩上下文省 token、用/review审查改动、用/help看所有命令。按 CtrlD 退出。交互模式适合边聊边改代码-p模式适合脚本化和一次性任务。5. 常见报错排查401、local proxy failed、reading choices 对照解决这一节按真实报错对照排查。第一个高频错误是401 Unauthorized或authentication_error。原因通常是 Key 填错、Key 过期、或者 Base URL 写成了带路径的形式。检查settings.json里ANTHROPIC_AUTH_TOKEN是不是完整的sk-开头字符串ANTHROPIC_BASE_URL是不是https://taotoken.net/api末尾不要加/v1或斜杠。改完保存重开终端再试。第二个是local proxy failed或连接超时。这通常是网络层问题不是配置问题。先确认能不能访问 Base URLcurl -I https://taotoken.net/api如果 curl 都连不上说明本机网络到服务端不通检查防火墙或公司网络策略。如果 curl 通但 Claude Code 报错可能是代理环境变量干扰检查HTTP_PROXY/HTTPS_PROXY是否设了奇怪的值临时清掉再试。第三个是reading choices或unexpected response format。这通常意味着返回的不是 Anthropic 兼容格式多半是模型 ID 填错了或者 Base URL 指向了非兼容端点。回 TaoToken 控制台的「模型对话」页面确认模型 ID 拼写注意大小写。有些模型 ID 带版本号后缀少一段就匹配不上。第四个是OAuth相关报错比如提示登录 Anthropic 账号。这说明 Claude Code 没读到你的 settings.json走了默认官方认证流程。检查文件路径macOS/Linux 是~/.claude/settings.jsonWindows 是%USERPROFILE%\.claude\settings.json。注意.claude前面有个点Windows 下创建时别被资源管理器吞掉。可以用dir %USERPROFILE%\.claude确认文件真的在。第五个是claude: command not found。装完了但终端找不到命令通常是 npm 全局 bin 目录不在 PATH 里。执行npm config get prefix看全局路径把这个路径下的bin子目录加进 PATH。macOS/Linux 改~/.bashrc或~/.zshrcWindows 在「系统属性 → 环境变量」里加。第六个是 Windows 终端乱码。系统自带 cmd 对 UTF-8 支持差换成 Windows TerminalMicrosoft Store 免费下载或者在 cmd 里先执行chcp 65001切到 UTF-8。如果你用的是 CC Switch 或 Cline MCP 这类工具管理多套配置记住三件套必须齐全Base URL、API Key、Model ID。缺任何一个都会报错。CC Switch 里切换配置后确认它写进了正确的 settings.json 路径。排查顺序建议先claude -p hello确认链路再claude --version确认安装最后cat ~/.claude/settings.json确认配置。三步定位问题在哪一层。6. 接入文档与后续进阶从跑通到日常编码链路跑通只是开始。日常用起来claude -p适合一次性任务交互模式适合复杂重构。几个实用参数值得记住--allowedTools Read,Edit限制它只能用读和改防止误执行命令--output-format json输出结构化结果方便接自动化脚本-c继续上次对话不用重新交代上下文--dangerously-skip-permissions跳过确认弹窗仅限 CI 或你完全信任的场景用。CLAUDE.md 可以写得更细。除了技术栈和命令还能写「不要修改 migrations 目录」「提交信息用中文」「新增依赖前先问我」这类约束。它每次进项目都会读相当于给 AI 立规矩。项目大了可以拆成多个文件用引用。如果你要长期跑编码任务或 Agent 流程建议了解 Coding Plan它针对高频调用做了额度优化。需要更多模型或查看完整参数去模型对话页面实测Key 管理在 API Keys 页面完整接入说明看接入文档。遇到报错先把错误信息贴给 Claude Code 自己它往往能直接告诉你哪配错了。最后提醒一句配置文件里的 Key 不要提交到 Git~/.claude/目录本身在用户目录下一般不会被项目仓库跟踪但如果你把配置复制到了项目里记得加进.gitignore。装好之后多用-p模式熟悉基本用法再慢慢进阶到交互模式和项目级开发。