1. 第一次在终端里跑 Claude Code，Mac 和 Windows 到底差在哪
Claude Code 是 Anthropic 推出的终端原生 AI 编程助手，简单说就是你把需求用中文讲给它，它自己读项目、改文件、跑命令、修 bug。它和 IDE 补全插件最大的区别是：补全工具是你写一行它猜一行，Claude Code 是你描述一个功能，它把整条链路走完再交给你 review。适合谁？适合已经习惯命令行、项目有一定规模、经常做跨文件重构或批量改动的开发者。如果你只是想要个自动补全，那它可能有点重。
但第一次上手，Mac 和 Windows 的体验差异比想象中大。Mac 上一条 curl 脚本基本就完事，Windows 上你会遇到 PowerShell 执行策略、路径反斜杠、Git Bash 缺失导致 Bash 工具回退等一系列小坑。这篇就按「装完能跑通第一次请求」为目标，把两个平台的 CLI 安装、环境变量、settings 配置、auth.json 改写逐条拆开。我试过在一台 M2 MacBook 和一台 Win11 台式机上从零走一遍，下面命令都是实测可复制的。
核心检索词先明确：Claude Code 安装配置、Mac Windows CLI、settings.json、auth.json、环境变量。这几个词会贯穿全文，你照着搜也能找到对应段落。
先说清楚一个前提：Claude Code 默认连的是 Anthropic 官方端点，国内直连经常超时。所以本文会把 endpoint 和认证配置改到 TaoToken 的兼容端点，这样首次运行就能通。TaoToken 官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数，配置里填这个就行。
安装前你需要准备三样东西：一个能用的终端（Mac 用 Terminal 或 iTerm2，Windows 用 Windows Terminal 或 PowerShell 7）、一个代码项目目录（空目录也行，但最好有真实项目）、以及一个可用的 API Key。Key 的获取在下一节讲。系统要求不高，Node 环境不是必须的，官方安装脚本会处理运行时，但 Windows 上强烈建议先装 Git for Windows，否则 Claude Code 的 Bash 工具会退化成 PowerShell，很多 shell 命令行为不一致。
Mac 的安装路径有三条：官方脚本、Homebrew、手动下载。官方脚本最省事，Homebrew 适合你已经用 brew 管理一切，手动下载适合公司网络限制 curl 的场景。Windows 有四条：PowerShell 脚本、CMD、WinGet、WSL。WSL 本质是 Linux 环境，装法和 Mac 一样，但要注意 WSL 里的项目路径和 Windows 侧文件系统的映射关系，否则 Claude Code 读文件会绕远路。
这一节先把平台差异和准备清单讲透，下一节进入 TaoToken 的前置配置。别急着敲安装命令，先把 Key 和端点想清楚，能省掉后面反复改配置的时间。
2. TaoToken 前置：拿 Key、认端点、想清楚 auth.json 放哪
在装 Claude Code 之前，先把认证和端点这两件事定下来，否则装完第一次运行会卡在登录环节。Claude Code 支持多种认证方式，官方订阅、Console API Key、以及兼容端点的 API Key。本文走的是兼容端点路线，也就是把 Base URL 指向 TaoToken，用它的 Key 做认证。
第一步，拿 Key。打开 TaoToken 控制台，路径是 https://taotoken.net/console ，登录后进 API Keys 页面，新建一个 Key。建议按项目或按用途建多个 Key，方便后面排查是哪个 Key 出的问题。新建后立刻复制，页面刷新后通常不再完整显示。控制台入口带 UTM：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
第二步，认端点。TaoToken 的 API 根地址是 https://taotoken.net/api ，注意这里不加任何查询参数。Claude Code 需要的 Base URL 通常要带版本路径，具体填法在下一节的配置片段里给全。模型 ID 方面，Claude 系列常用的是 claude-sonnet-4 这类标识，具体以你控制台里可用的模型列表为准，别照抄网上的旧 ID。
第三步，想清楚 auth.json 放哪。Claude Code 的认证信息默认存在用户目录下的配置文件夹里。Mac 是 ~/.claude/ ，Windows 是 %USERPROFILE%.claude\ 。auth.json 这个文件承载 API Key 和端点信息，settings.json 承载模型、权限、环境变量等。两个文件分工不同，别混在一起写。
这里有个容易踩的坑：很多人以为改了环境变量就够了，但 Claude Code 启动时会优先读 auth.json 和 settings.json，环境变量只是其中一层。所以正确做法是三个地方保持一致：shell 里的环境变量、settings.json 里的 env 段、auth.json 里的认证字段。任何一处写错，都会出现「明明 Key 是对的却 401」的情况。
再提醒一点，TaoToken 是兼容端点，不是让你绕过什么，它就是把请求转发到对应模型服务。配置时把 Base URL 和 Key 填对，Claude Code 本身不需要改源码，也不需要装额外插件。这一点对新手很友好，你只要会改 JSON 就行。
如果你后面还要用 Claude Code 的 coding plan 或长期 Agent 任务，建议单独看一下 Coding Plan 页面，路径是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它和按量计费的 Key 是两套东西，别搞混。模型对话的在线验证入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，配完可以先去那里发一条消息确认 Key 活着。
这一节的核心就三件事：Key 从 console 拿、端点认准 https://taotoken.net/api 、auth.json 和 settings.json 分开放。下一节进入可复制的配置片段，Mac 和 Windows 分别给。
3. 可复制配置：settings.json、auth.json 与环境变量三件套
这一节是全文最该照着敲的部分。Claude Code 的配置核心是三个东西：Base URL、API Key、Model ID。业内常说的「三件套」就是这三个，缺一个都跑不起来。下面按 Mac 和 Windows 分别给路径和片段，你直接复制改 Key 就行。
先看 Mac。配置文件目录是 ~/.claude/ ，如果不存在就手动建：
mkdir -p ~/.claudesettings.json 路径是 ~/.claude/settings.json ，内容如下：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4" }, "permissions": { "allow": [], "deny": [] } }auth.json 路径是 ~/.claude/auth.json ，内容如下：
{ "apiKey": "sk-你的TaoToken密钥", "baseURL": "https://taotoken.net/api" }注意 auth.json 里的字段名是 apiKey 和 baseURL，大小写敏感，别写成 api_key 或 base_url。settings.json 里的 env 段是给 Claude Code 进程注入环境变量用的，和 shell 里的 export 是两套，但值要一致。
再看 Windows。配置目录是 %USERPROFILE%.claude\ ，在 PowerShell 里可以这样建：
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude"settings.json 路径是 %USERPROFILE%.claude\settings.json ，内容和 Mac 一样，注意 JSON 里路径分隔符不用改，因为这里没有文件路径字段。auth.json 路径是 %USERPROFILE%.claude\auth.json ，内容也一样。
环境变量方面，Mac 在 ~/.zshrc 或 ~/.bashrc 里加：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoToken密钥" export ANTHROPIC_MODEL="claude-sonnet-4"Windows 在 PowerShell 里临时设置：
$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的TaoToken密钥" $env:ANTHROPIC_MODEL="claude-sonnet-4"要永久生效就写进系统环境变量，或者用 setx 命令。但记住，settings.json 里的 env 段优先级更高，所以最稳的做法是只维护 settings.json，环境变量作为备用。
如果你用的是 Codex 或 Cline 这类工具，它们的 auth.json 结构可能不同。Codex 的 auth.json 通常在 ~/.codex/auth.json ，字段是 OPENAI_API_KEY 和 base_url 那一套。Cline MCP 的配置在 IDE 插件设置里，走的是 MCP server 配置。本文聚焦 Claude Code，其他工具的 auth.json 别直接套用。
配置写完，先别急着启动。用一条命令检查 JSON 语法：
python3 -m json.tool ~/.claude/settings.jsonWindows 上用：
Get-Content "$env:USERPROFILE\.claude\settings.json" | ConvertFrom-Json语法错了会直接报行号，比启动后报 401 好排查得多。下一节进入验证请求，看第一次运行到底通没通。
4. 验证请求：从 claude --version 到第一次成功对话
配置写完，进入验证环节。验证分三层：命令能不能跑、认证能不能过、模型能不能回。三层都过，才算首次运行即通。
第一层，装完先看版本。Mac 和 Windows 都是：
claude --version能打印版本号，说明二进制在 PATH 里。如果提示 command not found，Mac 检查 /usr/local/bin 或 ~/.local/bin 是否在 PATH，Windows 检查安装脚本有没有把目录写进 PATH，重开一个终端再试。
第二层，认证验证。进入你的项目目录，启动：
cd /path/to/your/project claude首次启动会读 auth.json 和 settings.json。如果配置正确，它会直接进入交互界面，不会弹登录。如果弹了登录页，说明 auth.json 没被读到，检查路径和字段名。进入交互后，先发一条最简单的：
> 你好，请回复 ok如果模型回了 ok，说明认证和端点都通了。如果报 401，看下一节的排查。如果报 model not found，说明 ANTHROPIC_MODEL 填的 ID 不对，去控制台确认可用模型列表。
第三层，验证工具能力。发一条会触发文件读取的指令：
> 看一下当前目录有哪些文件，列出前五个Claude Code 会调用 shell 工具执行 ls 或 dir，然后返回结果。这一步能过，说明 Bash 工具正常。Windows 上如果这一步报错，多半是没装 Git for Windows，Bash 工具回退到 PowerShell 后命令不兼容。
再验证一次写文件能力：
> 在当前目录创建一个 test_claude.txt，内容写 hello它会请求权限确认，你按 y 同意。然后检查文件是否真的创建了：
cat test_claude.txtWindows 上用 type test_claude.txt 。文件内容对，说明写权限和路径处理都正常。
如果你更想先在网页端确认 Key 活着，可以去模型对话页面发一条消息，路径是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。网页端通了，说明 Key 和端点没问题，问题就缩小到 Claude Code 的本地配置。
验证通过后，建议把这次成功的配置备份一份。Mac 上：
cp ~/.claude/settings.json ~/.claude/settings.json.bakWindows 上：
Copy-Item "$env:USERPROFILE\.claude\settings.json" "$env:USERPROFILE\.claude\settings.json.bak"后面改配置改坏了，直接还原。下一节进入常见报错排查，把 401、local proxy failed、reading choices、OAuth 这几类真实错误逐条拆。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节按真实报错来。你启动 Claude Code 后大概率会遇到下面几类，每类给现象、原因、修法。
第一类，401 Unauthorized。现象是模型请求返回 401，或者交互界面提示认证失败。原因通常是三个：Key 写错、Key 前后有空格、auth.json 和 settings.json 里的 Key 不一致。修法是先确认 Key 没有多余空格，然后对比两个文件里的 Key 是否完全一致。可以用命令检查：
grep -r "sk-" ~/.claude/Windows 上用：
Select-String -Path "$env:USERPROFILE\.claude\*" -Pattern "sk-"如果两个文件里的 Key 不一样，以 auth.json 为准改 settings.json。还有一种情况是 Key 被控制台删了或过期了，去 console 重新建一个。
第二类，local proxy failed。现象是启动时报本地代理失败，或者请求发不出去。这个错误通常和网络层有关，不是 Key 的问题。先确认你的 Base URL 填的是 https://taotoken.net/api ，没有多余斜杠，也没有写成 http。然后确认本机没有残留的代理环境变量干扰：
env | grep -i proxy如果有 http_proxy 或 https_proxy 指向一个已经关掉的本地端口，就会报 local proxy failed。清掉这些变量：
unset http_proxy https_proxy all_proxyWindows 上用：
Remove-Item Env:http_proxy -ErrorAction SilentlyContinue Remove-Item Env:https_proxy -ErrorAction SilentlyContinue第三类，reading choices 相关报错。现象是模型返回的 JSON 结构解析失败，提示读取 choices 字段出错。这类错误多半是端点返回格式和 Claude Code 预期不一致。先确认 Base URL 是 https://taotoken.net/api ，不要自己拼 /v1/chat/completions 这种完整路径，Claude Code 会自己拼。如果还是报错，去模型对话页面发一条消息，看返回结构是否正常。网页端正常而 CLI 报错，通常是 CLI 版本太旧，升级：
claude update第四类，OAuth 相关报错。现象是启动时弹浏览器授权，或者提示 OAuth token 无效。这是因为 Claude Code 默认可能走 OAuth 登录流程，而你用的是 API Key。修法是确保 auth.json 存在且字段正确，Claude Code 检测到 auth.json 里有 apiKey 就不会走 OAuth。如果它还是弹 OAuth，检查 auth.json 的路径是不是放错了，Mac 是 ~/.claude/auth.json ，Windows 是 %USERPROFILE%.claude\auth.json ，别放到项目目录里。
第五类，模型 ID 报错。现象是提示 model not found 或 unsupported model。修法是去控制台确认可用模型列表，把 ANTHROPIC_MODEL 改成列表里存在的 ID。别照抄博客里的旧 ID，模型迭代很快。
排查顺序建议固定下来：先看 claude --version 确认装上了，再看 auth.json 和 settings.json 的 Key 是否一致，再看 Base URL 是否是 https://taotoken.net/api ，最后看模型 ID。这四步能覆盖八成问题。如果还不行，去接入文档页面看最新配置说明，路径是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
6. 配好之后：把 Claude Code 用顺手的几个实操建议
配置通了只是起点，真正决定体验的是你怎么用它。这一节给几个实操建议，都是踩过坑之后留下来的。
第一，项目根目录放一个 CLAUDE.md。Claude Code 启动时会读这个文件，里面写清楚项目技术栈、常用命令、代码规范。比如：
# 项目说明 这是一个 Spring Boot 后端项目。 ## 技术栈 - Java 21 - Spring Boot 3.3.5 - MySQL ## 常用命令 - 编译: mvn clean package -DskipTests - 测试: mvn clean test - 启动: mvn spring-boot:run ## 代码规范 - 使用构造器注入 - 日志用 @Slf4j有了这个文件，它不用每次问你项目怎么跑，直接按里面的命令执行。这一步对首次使用体验提升最大。
第二，权限配置别全放开。Claude Code 默认改文件前会问你，这是安全设计。你可以在 settings.json 的 permissions.allow 里加白名单，比如允许它读文件但不允许写：
{ "permissions": { "allow": ["Read"], "deny": ["Write"] } }具体权限名以官方文档为准。全放开虽然省事，但一旦它误删文件就麻烦了。
第三，长任务用 Coding Plan。如果你要让 Claude Code 连续跑几个小时做重构或 Agent 任务，按量计费的 Key 可能不够划算，去看一下 Coding Plan 页面，路径是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它和按量 Key 是两套计费，选适合你使用强度的。
第四，Key 轮换。别一个 Key 用到底，按项目或按周轮换。控制台里可以随时删旧建新，路径是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。轮换后记得同步改 auth.json 和 settings.json，两个文件都要改。
第五，Windows 用户把 Git for Windows 装上。这不是可选项，是强烈建议。装了之后 Claude Code 的 Bash 工具才能正常工作，很多 shell 命令行为才和 Mac 一致。装完在 PowerShell 里确认：
git --version能打印版本号就行。
最后，遇到问题先看接入文档，路径是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面通常有最新的配置示例和常见问题。文档比博客更新快，以文档为准。配好之后，Claude Code 就能在你的 Mac 或 Windows 上稳定跑起来了，剩下的就是拿真实项目去练。
