1. 从零装 Claude Code 到底卡在哪Windows 与 macOS 的安装前置条件Claude Code 是 Anthropic 官方推出的命令行编程助手能直接在终端里读写项目文件、跑命令、改代码适合习惯用命令行干活的开发者。它本身只是个客户端真正决定你能不能跑起来的是三件事Node 环境、Git BashWindows 专属、以及一个能用的 API 通道。很多人第一次装完输入claude就报地区不支持或者卡在 OAuth 登录页转圈问题基本都出在第三件事上。我先把安装链路拆开讲清楚再给一套把settings.json改到统一 Key/API 通道的完整配置最后用一条 curl 确认通道真的生效。整条链路走通之后Agent Skills 才有意义——因为 Skills 本质是让 Claude 按你的规范自动执行任务通道不通技能再全也调不动。先说环境依赖。Node.js 建议 18 LTS 以上npm 建议 9 以上这两个是跑npm install -g anthropic-ai/claude-code的基础。检查命令很简单node --version npm --version git --versionWindows 用户要特别注意 Git。Claude Code 在 Windows 上没有自带 bash必须依赖 Git 安装时附带的bash.exe。所以 Git 装的时候一路默认下一步别改选项默认配置会自动把 Git 加进环境变量。装完之后还要显式告诉 Claude Code 这个 bash 在哪用 PowerShell 执行一条永久环境变量命令[Environment]::SetEnvironmentVariable(CLAUDE_CODE_GIT_BASH_PATH, C:\Program Files\Git\bin\bash.exe, User)路径按你实际安装位置改。这条不设Windows 上启动 Claude Code 大概率直接报找不到 shell。macOS 和 Linux 用户跳过这一步系统自带 bash。装 Claude Code 本体用 npm 全局安装npm install -g anthropic-ai/claude-code成功会看到added x packages in xxs。验证claude --version后续更新用npm update -g anthropic-ai/claude-code卸载用npm uninstall -g anthropic-ai/claude-code。装完之后还有一个容易忽略的坑首次启动如果卡在引导页或报地区不支持需要手动改本地.claude.json。macOS 路径是/Users/用户名/.claude.jsonWindows 是C:\Users\你的用户名\.claude.json。在 JSON 末尾加一行hasCompletedOnboarding: true保存后重新启动claude会提示你选择信任文件夹选信任即可进入。这一步只是跳过引导真正决定请求能不能发出去的是下一步的 API 配置。2. 把 settings.json 改到 TaoTokenBase URL、Key 与 Model ID 三件套Claude Code 的所有请求走向由~/.claude/settings.json里的env段控制。默认它指向 Anthropic 官方地址国内直连经常超时或报地区限制。要换成统一通道核心就是改三个值ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。这三个凑齐通道才算配好缺一个都会在启动或首次请求时报错。TaoToken 提供统一的 API 通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先去控制台建一个 Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面新建复制出来形如sk-xxxx的字符串。这个 Key 就是后面ANTHROPIC_AUTH_TOKEN的值。配置文件完整片段如下路径~/.claude/settings.jsonWindows 是C:\Users\你的用户名\.claude\settings.json{ env: { ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5-20251001, ANTHROPIC_DEFAULT_SONNET_MODEL: claude-sonnet-4-5-20250929, ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-4-5-20251101, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8000, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 }, permissions: { allow: [], deny: [] } }几个字段的作用要讲清楚。ANTHROPIC_BASE_URL末尾不要加斜杠写https://taotoken.net/api就行。ANTHROPIC_MODEL是主模型ANTHROPIC_SMALL_FAST_MODEL是处理轻量任务比如生成标题、补全时用的快模型分开配能省额度。ANTHROPIC_DEFAULT_SONNET_MODEL和ANTHROPIC_DEFAULT_OPUS_MODEL是当你在会话里用/model切换时映射到的具体模型。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设成 1 可以关掉非必要的遥测请求减少干扰。如果你用 CC Switch 这类图形工具管理多套配置它写入的也是同一个settings.json。CC Switch 里填的三件套对应关系是Base URL 填https://taotoken.net/apiAPI Key 填 TaoToken 的 KeyModel 填你要用的模型 ID。工具只是帮你写文件理解字段含义才能自己排错。模型 ID 建议以 TaoToken 文档里列出的为准路径是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。不同模型 ID 对应不同能力和价格写错会直接报模型不存在。改完配置必须重启终端关掉当前 PowerShell 或 Terminal 重新开一个因为环境变量在进程启动时读取。3. 一条 curl 验证通道是否生效确认请求真的打到 TaoToken配置写完别急着进 Claude Code先用 curl 打一发确认 Key 和 Base URL 组合是通的。这一步能提前暴露 401、404、超时等问题比在 Claude Code 里看报错清楚得多。请求命令如下curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 128, messages: [ {role: user, content: 只回复两个字通了} ] }正常返回是一段 JSONcontent数组里能看到模型回复的文本。如果返回401说明 Key 不对或没带上返回404多半是 Base URL 路径写错注意是/api/v1/messages而不是别的返回超时检查网络能不能访问taotoken.net。这条 curl 通了说明通道层没问题剩下的就是 Claude Code 客户端读取配置的事。curl 通过后启动 Claude Codeclaude进入交互界面后输入/status能看到当前使用的 Base URL 和模型信息。如果这里显示的地址还是官方地址说明settings.json没被读到检查文件路径和 JSON 格式多余逗号会导致解析失败。确认无误后随便问一句比如「列出当前目录的文件」能正常返回就说明整条链路通了。这一步的验证逻辑很关键curl 验证的是「Key 通道」/status验证的是「客户端 配置」两者都过才算真正接入成功。很多人跳过 curl 直接进 Claude Code遇到报错分不清是 Key 问题还是配置问题排错成本翻倍。4. Agent Skills 目录结构与调用让 Claude 按你的规范干活通道通了之后Agent Skills 才是提效的重点。Skills 是 Anthropic 为 Claude Code 设计的模块化能力扩展包遵循 Agent Skills 开放标准。说白了它把某个领域的知识、工作流、规范封装成一个带SKILL.md的目录让 Claude 从通用助手变成懂你项目规范的专家。一个 Skill 就是一个文件夹唯一必填文件是SKILL.md里面是元数据加指令可以附带脚本、模板等支持文件。存放位置macOS/Linux 是~/.claude/skills/Windows 是C:\Users\你的用户名\.claude\skills\。创建目录mkdir -p ~/.claude/skillsWindows PowerShellNew-Item -Path $env:USERPROFILE\.claude\skills -ItemType Directory -Force目录结构长这样~/.claude/ ├── skills/ │ ├── review/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── init-project/ │ │ └── SKILL.md │ └── gen-tests/ │ └── SKILL.md └── settings.jsonSKILL.md的写法决定了技能能不能被正确触发。文件开头是 YAML 元数据name是技能名description是触发描述——这段描述最关键Claude 靠它判断你的自然语言请求该不该匹配这个技能。下面是一个代码审查技能的示例--- name: review description: 审查代码时使用检查安全漏洞、性能问题和规范符合度。当用户提到代码审查、review、检查代码质量时触发。 --- # 代码审查技能 ## 执行步骤 1. 读取目标文件识别语言和框架 2. 按以下维度逐项检查 - 安全SQL 注入、XSS、硬编码密钥 - 性能循环内查询、未加索引的查询、内存泄漏 - 规范命名、注释、错误处理 3. 输出问题列表每条附文件行号和修改建议 4. 按严重程度排序高危 中危 低危 ## 输出格式 | 行号 | 级别 | 问题 | 建议 |Skills 有两种触发方式。自动触发是默认行为Claude 分析你的请求匹配description里的关键词自动加载技能。比如你说「帮我审查这段 Python 代码找安全漏洞」它会自动匹配review技能。手动触发是输入/技能名强制调用比如/review。手动触发更可控适合你明确知道要用哪个技能的场景。查看已安装技能用/plugin list或者直接输入/看所有可用命令。禁用和启用分别是/plugin disable 插件名和/plugin enable 插件名卸载是/plugin uninstall 插件名。写description有个实用技巧把用户可能说的自然语言都列进去包括同义词。比如「审查、review、检查代码、code review」都写上匹配率会高很多。描述太窄技能就经常不触发描述太宽又会误触发到不相关的请求。这个平衡需要根据实际使用调几次。5. 常见报错排查401、local proxy failed 与 reading choices 怎么解接入过程中有几类报错反复出现我把它们和对应解法列出来遇到时直接对照。401 UnauthorizedKey 无效或没带上。检查settings.json里ANTHROPIC_AUTH_TOKEN的值有没有多余空格Key 是否已过期或被删。用第 3 节的 curl 单独测一次curl 也 401 就是 Key 本身的问题去控制台重新建一个。local proxy failed / connection refused客户端连不上 Base URL。先确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api末尾没加斜杠也没写成别的路径。再确认网络能访问taotoken.net用curl -I https://taotoken.net/api看能不能拿到响应头。reading choices / unexpected response format返回的 JSON 结构不符合预期通常是 Base URL 指错了端点或者模型 ID 写错导致服务端返回了错误结构。检查ANTHROPIC_MODEL是否在 TaoToken 文档的模型列表里路径 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。OAuth 登录页转圈 / 地区不支持这是没走 API Key 通道客户端还在尝试官方 OAuth。确认settings.json里ANTHROPIC_AUTH_TOKEN和ANTHROPIC_BASE_URL都配了并且重启了终端。如果.claude.json里没有hasCompletedOnboarding: true补上再试。模型不存在 / model not foundANTHROPIC_MODEL的值和通道支持的模型 ID 对不上。去文档页核对准确的 ID 字符串注意日期后缀不能省。配置改了没生效Claude Code 在进程启动时读配置改完必须关掉终端重开。另外检查 JSON 格式多一个逗号或少一个引号都会导致整个文件解析失败客户端会静默回退到默认配置。用cat ~/.claude/settings.json | python -m json.tool验证格式是否合法。排错的核心思路是分层先用 curl 确认通道层再用/status确认客户端层最后才看 Skills 层。大部分问题在前两层就能定位不用一上来就怀疑技能配置。6. 长期编码与 Agent 工作流的接入建议通道和 Skills 都跑通之后日常使用还有几个能省事的点。如果你经常在多个项目间切换可以把常用的 Skills 做成模板目录新项目直接软链过去不用每次重写SKILL.md。模型选择上主任务用能力强的模型补全和轻量任务交给ANTHROPIC_SMALL_FAST_MODEL额度和速度都更划算。需要长期跑编码任务或搭 Agent 工作流的可以看下 Coding Plan路径是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合把 Claude Code 当日常主力工具的开发者。只是想先验证模型对话效果的用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速试。Key 管理在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一个实操细节settings.json里的 Key 是明文存储的别把这个文件提交到 Git 仓库。可以在项目.gitignore里加上.claude/settings.json或者用环境变量在启动脚本里注入。Skills 目录里的SKILL.md如果包含内部规范同样注意别外泄。配置一次跑通之后后面就是往 Skills 里沉淀你自己的规范越用越顺手。