1. 从零跑通 Claude CodeWindows 与 macOS 环境准备Claude Code 是 Anthropic 推出的命令行原生 AI 编程助手它和 IDE 里那种只给建议的补全插件不一样能直接读写项目文件、执行命令、跑测试属于“独立执行者”定位。适合谁适合已经有一定编程基础、想让 AI 真正动手改代码而不是只给提示的开发者。这篇教程聚焦 Windows 和 macOS 下从零安装到跑通首个任务的完整链路包括 Node.js 与 npm 环境准备、settings.json 关键字段说明、cc switch 多配置切换目标是让你 30 分钟内搭好本地可用环境。我试过在 Windows 11 和 macOS Sonoma 上各装一遍踩过的坑主要集中在 Node 版本和鉴权配置这两块。下面按顺序来每一步都给可复制的命令和配置。1.1 前置环境检查Node.js 与 npmClaude Code 基于 Node.js 开发需要完整的 Node.js 运行环境。先确认版本建议 Node.js 18.0 或以上npm 9 以上更稳。打开终端Windows 用 PowerShell 或 CMDmacOS 用 Terminal执行node -v npm -v如果提示command not found或版本低于 18先去 Node.js 官网下载 LTS 版本安装。Windows 用户建议用官方 msi 安装包macOS 用户可以用 Homebrewbrew install node20安装完重新打开终端再验证一次。这里有个细节Windows 上如果之前装过旧版 Node最好先卸载再装新版否则 npm 全局路径可能冲突后面npm install -g会报权限错误。1.2 全局安装 Claude Code环境确认后运行全局安装npm install -g anthropic-ai/claude-codemacOS 如果报EACCES权限错误不要用sudo npm install -g正确做法是给 npm 配置用户级全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到~/.zshrc或~/.bashrc里然后重新执行安装命令。Windows 用户如果报权限错误用管理员身份打开 PowerShell 再装一次即可。安装完成后验证claude --version能打印出版本号就说明二进制已经就位。接下来进入配置环节。1.3 首次启动与信任确认在任意项目根目录输入claude并回车。首次运行会提示身份验证正常情况下会自动在浏览器打开登录页面。但国内网络环境下这一步经常连不上会看到类似报错Unable to connect to Anthropic services Failed to connect to api.anthropic.com: ERR_BAD_REQUEST这时候不用慌我们后面会用 settings.json 直接配置第三方兼容端点绕过这个引导。先处理首次启动的信任确认界面它会问你是否信任当前文件夹翻译过来就是“这是你自己创建的项目还是你信任的项目Claude Code 在这里能够读取、编辑和执行文件。”选择 Yes 即可。这个确认只针对当前目录换个项目还会再问一次属于安全机制。如果连信任界面都进不去直接跳到第 2 节配置 settings.json配好后再启动就能正常进入。2. TaoToken 前置获取 API Key 与模型信息Claude Code 默认走 Anthropic 官方端点国内直连不稳定。我们可以通过配置ANTHROPIC_BASE_URL指向兼容端点来解决。TaoToken 提供的就是这样一个兼容 Anthropic 协议的中转服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。2.1 注册与创建 API Key先访问官网注册账号然后进入控制台创建 API Key。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。在 API Keys 页面点击创建复制生成的 Key格式通常以sk-开头。这个 Key 只显示一次务必先存到安全的地方。如果你还没决定用哪个模型可以先去模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。在网页里选一个模型发条消息确认账号和额度正常再回到本地配置。2.2 确认 Base URL 与 Model IDTaoToken 的 Anthropic 兼容 Base URL 是https://taotoken.net/api注意这里不要加 UTM 参数API 调用只认纯地址。Model ID 需要根据你在控制台或模型对话里选的模型来填比如claude-sonnet-4-20250514这类。具体可用的 Model ID 以控制台模型列表为准填错会报model not found。2.3 三件套对照表配置 Claude Code 本质上就是填三件套Base URL、API Key、Model ID。下面这张表帮你对照配置项对应字段示例值Base URLANTHROPIC_BASE_URLhttps://taotoken.net/apiAPI KeyANTHROPIC_AUTH_TOKENsk-你的实际KeyModel IDANTHROPIC_MODELclaude-sonnet-4-20250514把这三个值准备好下一节直接写进 settings.json。3. 可复制配置settings.json 与 cc switch 示例这一节是核心给出可直接复制的 settings.json 片段和 cc switch 配置示例。配置文件的路径要记牢WindowsC:\Users\你的用户名\.claude\settings.jsonmacOS / Linux~/.claude/settings.json如果.claude目录或 settings.json 不存在手动新建即可。3.1 settings.json 完整片段用任意文本编辑器打开 settings.json粘贴以下内容把三个占位符替换成你自己的值{ env: { ANTHROPIC_AUTH_TOKEN: sk-你的实际Key, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: claude-sonnet-4-20250514, API_TIMEOUT_MS: 3000000 } }字段说明ANTHROPIC_AUTH_TOKEN填 API KeyANTHROPIC_BASE_URL填 TaoToken 的 API 地址ANTHROPIC_MODEL填你要用的 Model IDAPI_TIMEOUT_MS是超时时间单位毫秒设大一点避免长任务被截断。注意JSON 语法很严格最后一项后面不能有逗号引号必须是英文双引号。改完可以用在线 JSON 校验工具过一遍省得启动时报解析错误。3.2 绕过首次引导的补充配置如果启动时卡在登录引导还需要在用户主目录的.claude.json里加一个字段。路径WindowsC:\Users\你的用户名\.claude.jsonmacOS / Linux~/.claude.json在文件末尾的大括号}前添加hasCompletedOnboarding: true注意上一行末尾要补英文逗号。改完结构类似{ installMethod: native, autoUpdates: false, hasCompletedOnboarding: true }保存后关闭终端新开一个窗口再输入claude就能跳过引导直接进交互界面。3.3 cc switch 多配置切换cc switch 是跨平台的可视化 Claude Code 配置管理工具通过图形界面接管 API 路由调度支持 Claude Code、Codex、Gemini CLI 等多个工具。系统要求Windows 10 及以上macOS 12 及以上Linux 主流发行版。安装方式参考项目 READMEWindows 下下载 msi 安装包后双击运行按提示下一步、选安装目录、点 Install 即可。安装完成后打开 cc switch新建一个配置名称TaoTokenBase URLhttps://taotoken.net/apiAPI Keysk-你的实际KeyModelclaude-sonnet-4-20250514保存后点击应用cc switch 会自动把配置写入 settings.json。这样你可以在多个端点之间一键切换不用手动改文件。配置完成后重新打开终端输入claude下达指令终端界面保持原样但上下文数据已经被路由到你配置的模型处理。提示cc switch 和手动改 settings.json 二选一即可不要同时改否则可能互相覆盖。团队协作时建议统一用 cc switch 管理避免每人配置不一致。4. 验证请求一条命令确认鉴权生效配置写完怎么确认真的生效了最直接的方式是用单次命令模式跑一个简单任务。4.1 单次命令验证在终端里执行claude -p 回复一句话配置成功-p参数表示单次执行模式任务完成后自动退出终端控制权交还。如果配置正确你会看到模型返回的内容类似“配置成功”。如果报401或Not logged in说明 Key 或 Base URL 有问题回到第 3 节检查。4.2 交互式验证再进交互模式确认上下文记忆正常cd your-project claude进入后输入自然语言需求比如“帮我在 src 目录下新建一个 utils 文件夹并在里面写一个处理日期格式化的函数”。Claude Code 会保留上下文后续输入“增加对闰年的判断逻辑”会直接在刚才生成的文件基础上修改。退出用/quit、/exit或连续按两次 CtrlC。4.3 代码 Diff 确认机制只要 Claude Code 决定修改源文件都会触发差异确认。终端输出彩色对比红色行首-是即将删除的旧代码绿色行首是即将新增的新代码。确认选项Y同意单次操作仅授权当前这一次Y shifttab允许本会话所有编辑适合大规模重构N拒绝修改硬盘文件不变实测下来这个机制很实用尤其是第一次让 AI 改核心文件时逐次确认能避免误改。4.4 常用斜杠命令交互模式下以/开头的命令管理底层行为/init扫描项目生成 CLAUDE.md记录架构和构建命令/model运行时切换模型简单任务切便宜模型降成本/plan规划模式先输出步骤清单再写代码/compact压缩历史记录恢复响应速度/clear清除当前会话记忆换任务时强烈建议执行/cost打印 Token 数量和预估花销5. 本篇常见错排查401、local proxy failed 与 OAuth配置过程中最容易撞上几个报错逐个拆解。5.1 401 鉴权失败报错长这样401 Unauthorized原因通常是 API Key 填错、Key 已失效或者 Base URL 写成了带 UTM 的地址。检查三点Key 是否完整复制别漏字符、Base URL 是否为https://taotoken.net/api不带任何参数、settings.json 里字段名是否拼写正确。改完保存关闭终端重开再试。5.2 local proxy failed报错类似local proxy failed: connection refused这通常是本地网络代理或防火墙拦截了请求。先确认没有其他工具占用端口再检查系统代理设置。如果公司网络有出口限制换一个网络环境测试。注意不要配置任何非官方的网络转发工具直接用 TaoToken 的 API 地址即可。5.3 reading choices 解析错误报错error reading choices: unexpected end of JSON input这是响应体被截断或格式不对多半是API_TIMEOUT_MS设太小长任务没返回完就超时。把值调到300000050 分钟再试。如果还报检查 Model ID 是否在 TaoToken 支持列表里填了不存在的模型会返回异常结构。5.4 OAuth 引导卡死首次启动卡在浏览器授权或者报OAuth error。这就是前面说的引导问题解决办法是在.claude.json里加hasCompletedOnboarding: true跳过强制引导。加完保存新开终端再启动。5.5 配置不生效改完 settings.json 发现没变化八成是没重启终端。Claude Code 启动时读取配置运行中改文件不会热加载。关闭当前终端窗口新开一个再执行claude。另外确认改的是用户目录下的 settings.json不是项目里的同名文件。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔用 Claude Code 跑个小任务按上面的配置就够了。但如果打算长期用它做编码主力甚至跑 Agent 类自动化流程建议走 Coding Plan额度和稳定性更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各工具的详细配置说明。API Keys 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要轮换 Key 时来这里操作。最后给一个实用技巧把claude -p写进 shell 脚本做批量任务时记得在脚本开头export好环境变量或者确保 settings.json 已经配好否则非交互环境下读不到配置。另外/cost命令在跑长任务前先看一眼心里有数再放手让 AI 干活。