Claude Code 2026 中文入门指南：Mac/Windows 安装配置与 CLI 全流程

1. 第一次在终端里跑 Claude CodeMac 和 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个就行。安装前你需要准备三样东西一个能用的终端Mac 用 Terminal 或 iTerm2Windows 用 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 出的问题。新建后立刻复制页面刷新后通常不再完整显示。控制台入口带 UTMhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它和按量计费的 Key 是两套东西别搞混。模型对话的在线验证入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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\.claudesettings.json 路径是 %USERPROFILE%.claude\settings.json 内容和 Mac 一样注意 JSON 里路径分隔符不用改因为这里没有文件路径字段。auth.json 路径是 %USERPROFILE%.claude\auth.json 内容也一样。环境变量方面Mac 在 ~/.zshrc 或 ~/.bashrc 里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4Windows 在 PowerShell 里临时设置$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的TaoToken密钥 $env:ANTHROPIC_MODELclaude-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 foundMac 检查 /usr/local/bin 或 ~/.local/bin 是否在 PATHWindows 检查安装脚本有没有把目录写进 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 WindowsBash 工具回退到 PowerShell 后命令不兼容。再验证一次写文件能力 在当前目录创建一个 test_claude.txt内容写 hello它会请求权限确认你按 y 同意。然后检查文件是否真的创建了cat test_claude.txtWindows 上用 type test_claude.txt 。文件内容对说明写权限和路径处理都正常。如果你更想先在网页端确认 Key 活着可以去模型对话页面发一条消息路径是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它和按量 Key 是两套计费选适合你使用强度的。第四Key 轮换。别一个 Key 用到底按项目或按周轮换。控制台里可以随时删旧建新路径是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。轮换后记得同步改 auth.json 和 settings.json两个文件都要改。第五Windows 用户把 Git for Windows 装上。这不是可选项是强烈建议。装了之后 Claude Code 的 Bash 工具才能正常工作很多 shell 命令行为才和 Mac 一致。装完在 PowerShell 里确认git --version能打印版本号就行。最后遇到问题先看接入文档路径是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面通常有最新的配置示例和常见问题。文档比博客更新快以文档为准。配好之后Claude Code 就能在你的 Mac 或 Windows 上稳定跑起来了剩下的就是拿真实项目去练。