1. 为什么新手装完 Claude Code 还是用不了从零跑通国产大模型接入的真实场景Claude Code 是 Anthropic 推出的终端 AI 编程助手能直接在命令行里读写文件、跑脚本、改项目对习惯用 VS Code 的人来说相当于多了一个会自己动手的结对程序员。但它默认连的是官方服务国内网络环境下经常卡在登录或请求失败很多人装完敲claude只看到报错就放弃了。这篇教程面向 Windows 和 macOS 新手从 Node.js 环境准备开始用 cc-switch 把 Base URL 改到 TaoToken再配合 VS Code 插件把整条对话链路一次跑通。我自己第一次装的时候卡在claude -v能出版本号、但一对话就 401 的阶段折腾了半天才发现是环境变量和 cc-switch 的配置没对上。所以下面每一步我都会把「为什么这么做」和「做错了会怎样」讲清楚你照着复制粘贴基本不会翻车。先明确三个关键词方便你建立整体印象Claude Code跑在终端里的 AI 编程工具通过npm全局安装命令是claude。cc-switch一个给 Claude Code 切换模型供应商的图形化小工具本质是帮你改配置文件省得手动编辑 JSON。TaoToken提供兼容 Anthropic 接口的 API 服务把 Base URL 指过去Claude Code 就能用上国产大模型。适合谁看完全没碰过命令行的新手、装过 Claude Code 但连不上官方服务的、想用国产大模型又不想折腾复杂配置的开发者。整篇教程的节奏是「装环境 → 拿 Key → 配 cc-switch → 验证 → 排错 → 接 VS Code」你可以按顺序跟做也可以直接跳到卡住的那一步。需要提前说明的是Claude Code 本身只是个客户端它能不能干活取决于背后连的模型服务。官方服务在国内访问不稳定所以我们用 cc-switch 把请求地址换成 TaoToken 的兼容端点这样既保留了 Claude Code 的交互体验又能稳定调用国产大模型。下面正式开始。2. 前置准备Node.js 环境、TaoToken API Key 与 cc-switch 安装的完整清单这一节把三样东西备齐Node.js 运行环境、TaoToken 的 API Key、cc-switch 工具本体。缺任何一样后面都会报错所以建议一次性搞定。2.1 安装 Node.js 并验证 npm 可用Claude Code 是用 Node.js 写的必须先把 Node 装上。Windows 和 macOS 的步骤略有不同但逻辑一样。Windows 用户打开浏览器访问 Node.js 官网下载 LTS 版本长期支持版稳定双击安装包一路下一步即可。安装完成后按Win R输入cmd回车在黑色窗口里敲node -v npm -v如果分别输出版本号比如v20.11.0和10.2.4说明装好了。macOS 用户可以用 Homebrew也可以直接下 pkg 安装包brew install node node -v npm -v版本号低于 18 的建议升级Claude Code 对 Node 版本有要求太老会报Unsupported engine之类的错。2.2 全局安装 Claude Code环境就绪后一条命令装 Claude Codenpm install -g anthropic-ai/claude-code装完验证claude -v能出版本号就说明客户端本身没问题。这时候如果你直接敲claude进入对话大概率会卡在登录或请求失败因为还没配模型服务别慌这是正常的。2.3 获取 TaoToken API Key打开 TaoToken 官网注册登录进入控制台找到 API Keys 页面创建一个新的 Key。创建时给它起个名字方便识别比如claude-code-test然后把生成的字符串复制下来保存好。这个 Key 只显示一次丢了就得重新建。拿到 Key 之后记下两个地址Base URLhttps://taotoken.net/apiAPI Key你刚复制的那串字符这两个东西后面配 cc-switch 时都要填。如果你还没注册可以先访问官网了解下https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content2.4 下载安装 cc-switchcc-switch 是一个开源的小工具作用是图形化地管理 Claude Code 的模型配置。去它的 GitHub Releases 页面下载对应系统的版本Windows 选.exe或免安装压缩包macOS 选.dmg。下载后解压或安装打开就能看到界面。打开 cc-switch 后顶部会有几个页签分别对应 Claude Code、Codex、Gemini 等。我们这次只关心 Claude Code点进去准备添加配置。到这一步三样前置就齐了下一节开始真正写配置。3. 可复制配置用 cc-switch 把 Base URL 改到 TaoToken 的完整步骤这一节是核心我会给出可以直接复制的配置片段并解释每个字段的含义。cc-switch 的本质是帮你生成并写入 Claude Code 的配置文件所以理解字段比死记步骤更重要。3.1 cc-switch 里添加供应商配置打开 cc-switch选择 Claude Code 页签点击右侧的「添加」按钮。在弹出的表单里填写以下内容字段填写值说明供应商标识taotoken自定义名称方便自己识别API Key你的 TaoToken Key从控制台复制的那串请求地址 / Base URLhttps://taotoken.net/api注意不要多加斜杠模型 ID按平台文档填写例如 claude-3-5-sonnet 对应的国产模型标识填完点击保存然后在列表里点「启用」让这条配置生效。3.2 配置文件长什么样cc-switch 底层改的是 Claude Code 的 settings 文件。Windows 路径通常在C:\Users\你的用户名\.claude\settings.jsonmacOS 路径在~/.claude/settings.json启用后文件内容大致如下你可以对照检查{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-3-5-sonnet-20241022 } }三个字段的作用分别是ANTHROPIC_BASE_URL决定请求发到哪ANTHROPIC_API_KEY是身份凭证ANTHROPIC_MODEL指定用哪个模型。Base URL 和 Key 必须成对出现只改一个会直接 401。注意如果你之前手动配过环境变量比如在系统里设过ANTHROPIC_BASE_URL它可能会覆盖 cc-switch 的配置。排查时先用echo $ANTHROPIC_BASE_URLmacOS或echo %ANTHROPIC_BASE_URL%Windows确认一下。3.3 三件套必须齐全不管用 cc-switch 还是手动改文件接入任何兼容 Anthropic 的服务都要保证三件套完整Base URL、API Key、Model ID。少任何一个都会失败这是新手最容易踩的坑。cc-switch 的好处就是它把这三个字段放在一个表单里填完自动写入不用你手动拼 JSON。如果你更习惯手动配置也可以直接编辑上面的settings.json效果一样。改完保存重启终端让配置生效。下一节我们验证请求是否真的通了。4. 验证请求终端启动 Claude Code 并确认对话链路跑通配置写完不代表就能用得实际发一次请求确认。这一节给出验证命令和成功标志以及失败时怎么快速定位。4.1 启动 Claude Code打开终端Windows 用 PowerShell 或 cmdmacOS 用 Terminal随便进一个空文件夹敲claude第一次启动会提示你确认权限或信任当前目录按回车继续。如果配置正确你会看到 Claude Code 的交互界面出现输入提示符。4.2 发一条测试指令在提示符后输入一句简单的话比如你是什么大模型回车后如果能看到模型正常回复说明整条链路通了。回复内容可能因你选的模型而异但只要能返回文字就证明 Base URL、Key、Model 三件套都对上了。4.3 用 curl 单独验证接口如果 Claude Code 里没反应可以先用 curl 直接打接口排除是客户端问题还是配置问题curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-3-5-sonnet-20241022, max_tokens: 100, messages: [{role: user, content: 你好}] }如果 curl 能返回正常 JSON说明服务端没问题问题出在 Claude Code 的配置读取上如果 curl 也报错那就是 Key 或 Base URL 填错了。4.4 成功后的表现配置正确时你会看到类似这样的返回结构{ id: msg_xxx, type: message, role: assistant, content: [{type: text, text: 你好我是...}] }看到content里有文字就说明请求成功。这时候回到 Claude Code 界面它应该也能正常对话了。如果这一步过了恭喜你核心链路已经打通剩下的就是接 VS Code 和排错。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 的对照处理新手在这一步最容易卡住我把几个高频报错和对应动作列出来你对着自己的终端输出找就行。5.1 401 Unauthorized这是最常见的意思是身份验证失败。原因通常是 API Key 填错、Key 已失效、或者 Base URL 和 Key 不匹配。处理动作回到 cc-switch 检查 Key 是否有多余空格确认 Base URL 是https://taotoken.net/api然后重新启用配置。如果还不行去 TaoToken 控制台重新生成一个 Key 替换。5.2 local proxy failed / connection refused这个报错说明请求根本没发出去通常是本地代理或网络配置干扰。检查系统里有没有设HTTP_PROXY、HTTPS_PROXY环境变量有的话先清掉再试。另外确认 Base URL 没有写成localhost或某个本地端口。5.3 reading choices / unexpected response出现reading choices或类似字段读取错误多半是模型返回格式和客户端预期不一致常见于 Model ID 填错。回到 cc-switch 确认ANTHROPIC_MODEL填的是平台文档里给出的准确标识不要自己猜名字。5.4 OAuth 相关报错如果看到OAuth、login required之类的提示说明 Claude Code 还在尝试走官方登录流程。这时候要确认settings.json里的ANTHROPIC_BASE_URL已经生效并且没有残留的官方登录缓存。可以删掉~/.claude下的缓存文件后重启终端。5.5 配置不生效的通用排查顺序遇到任何报错按这个顺序查先claude -v确认客户端在再echo环境变量确认没被覆盖再 curl 打接口确认服务端通最后看 cc-switch 里配置是否处于「启用」状态。四步走完基本能定位到具体哪一环断了。提示改完配置一定要重启终端环境变量和 settings 文件都是启动时读取的不重启不生效。6. 接入 VS Code 与后续进阶让 Claude Code 在编辑器里干活命令行用熟了之后很多人会想直接在 VS Code 里用。这一节讲插件安装和后续能做的事。6.1 安装 VS Code 与 Claude Code 插件去 VS Code 官网下载安装打开后点左侧扩展图标搜索Claude Code找到官方插件点安装。装完后按Ctrl Shift PmacOS 是Cmd Shift P打开命令面板输入Claude就能看到相关命令。插件会读取你之前配好的settings.json所以只要终端里能跑通插件里一般也能直接用。如果插件报错优先检查它读的是不是同一个配置文件。6.2 在编辑器里发指令插件装好后可以在侧边栏打开 Claude Code 面板直接输入指令让它改代码、解释文件、生成测试。体验和终端一致但多了编辑器上下文改起项目来更顺手。6.3 后续可以深入的方向Claude Code 装好只是起点真正提升效率的是给它配 skill专业技能包和调整思考模式。skill 相当于给模型装插件让它更擅长特定任务比如写 SQL、做代码审查。这些进阶内容我后面会单独整理你可以先把基础链路跑稳。如果你在配置过程中需要查文档可以访问接入文档页想先体验模型对话效果可以去模型对话页试试打算长期用来写代码或跑 Agent 任务可以了解下 Coding Plan。这几个入口按需取用即可。最后说个实用技巧把settings.json备份一份换电脑或重装时直接复制过去省得重新配。配置这东西配一次记一辈子下次五分钟搞定。
