Claude Code + cc-switch + Skills 搭建出一个完整的 AI Agent 编程环境

1. 为什么单装 Claude Code 还不够：多模型切换与技能编排的真实痛点

很多人第一次接触 Claude Code，是把它当成一个「终端里的 AI 补全」来用的：装好、填个 Key、进项目目录敲claude，然后就开始对话。用一两天没问题，但只要项目稍微复杂一点，问题就冒出来了。我自己最早那套环境就是这么搭的，结果一周之内踩了三个坑，最后不得不把整个工具链重新设计一遍。

第一个坑是模型切换。Claude Code 本身支持通过环境变量或配置文件指定 endpoint 和模型，但每次换供应商——比如从官方接口切到某个兼容 Anthropic 协议的通道，或者从 Opus 换到更便宜的模型做批量重构——你都得手动改~/.claude/settings.json，改完还要重启会话。如果同时开着两个项目，一个要用强模型做架构设计，一个要用快模型跑单元测试，来回改配置简直是灾难。cc-switch 这类工具就是为解决这个痛点生的：它把多套供应商配置存成独立 profile，图形界面一键切换，还能同步 MCP 配置、穿透 WSL 环境。

第二个坑是能力扩展。Claude Code 默认只会「读代码、写代码、跑命令」，但真实开发里你需要它按团队规范生成 commit message、需要它调用内部 API 文档、需要它执行一套固定的代码审查清单。这些如果每次都靠 prompt 里手写，既啰嗦又容易漏。Agent Skills 就是把这套「可复用的操作流程」沉淀成技能包：一个SKILL.md加若干脚本，Claude Code 在需要时自动加载，用完即走，不占常驻上下文。它和 MCP、斜杠命令的区别在于——MCP 是接外部工具，斜杠命令是手动触发，而 Skills 是「渐进式披露」：模型先看到技能名和描述，判断相关才读全文，省 token 也省心。

第三个坑是 Key 管理。多供应商意味着多套 Key、多个 Base URL，散落在各个配置文件里，哪天某个通道限流了，排查起来要翻半天。把 endpoint 统一收敛到一个兼容 Anthropic 协议的 Key 通道，是让整套环境稳定的关键一步。TaoToken 在这里扮演的就是这个「统一入口」的角色：一个 Key、一个 Base URL，Claude Code、Codex、Cline 都能接，切换模型时只改 Model ID，不用动鉴权。

所以完整环境应该是三层：Claude Code 是执行引擎，cc-switch 是调度层，Skills 是能力层，底下再垫一个统一的 API 通道。下面按这个顺序，从零搭一遍。

2. 前置准备：TaoToken 统一 Key 通道与 Claude Code 安装

在动 cc-switch 和 Skills 之前，先把底座打好。这一层的目标是：拿到一个兼容 Anthropic Messages API 的 Base URL 和 Key，并确认 Claude Code 能正常发起请求。

先说 Key。打开 TaoToken 官网https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册后在控制台创建 API Key。这里要注意，创建时选「Anthropic 兼容」类型的 Key，因为 Claude Code 走的是 Anthropic 的/v1/messages协议，不是 OpenAI 的/v1/chat/completions。Key 拿到后先存好，后面 cc-switch 和 Claude Code 都要用。

Base URL 用https://taotoken.net/api，注意这个地址后面不加任何 UTM 参数，直接写进配置就行。模型 ID 方面，Claude 系列填claude-sonnet-4-5或claude-opus-4-1这类官方命名，具体以控制台「模型对话」页面列出的为准。如果你还想接 Codex 或 Cline，同一个 Key 也能用，只是协议路径不同。

接下来装 Claude Code。官方推荐两种方式，我实测下来命令行安装最干净：

# 方式一：npm 全局安装（需要 Node 18+） npm install -g @anthropic-ai/claude-code # 验证版本 claude --version

如果你用 VS Code 或 Cursor，也可以在扩展市场搜「Claude Code」装插件版，但插件版底层还是调同一个 CLI，配置路径一致，所以本文以 CLI 为准。

装完后先别急着配 cc-switch，手动验证一次通道是否通。创建配置目录并写入最小配置：

mkdir -p ~/.claude cat > ~/.claude/settings.json <<'EOF' { "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } } EOF

注意ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY的区别：前者会作为Authorization: Bearer头发送，后者走x-api-key头。TaoToken 的 Anthropic 兼容通道用ANTHROPIC_AUTH_TOKEN更稳，实测下来不会出现 401。写完后进任意项目目录跑一次：

cd ~/your-project claude -p "用一句话说明这个项目是做什么的"

如果返回了合理回答，说明底座通了。如果报 401，先检查 Key 有没有复制全、有没有多余空格；如果报local proxy failed，多半是 Base URL 写成了带路径的完整地址，改成https://taotoken.net/api即可。这一步通了，再往上叠 cc-switch 才有意义。

3. cc-switch 配置：多供应商 profile 与 settings.json 片段

cc-switch 的核心价值是把「改配置文件」变成「点一下按钮」。它支持 Claude Code 和 Codex 两套配置管理，每个供应商存成一个 profile，切换时自动改写对应的 settings 文件。下面给出可直接复制的配置结构。

先装 cc-switch。它是个桌面应用，去 GitHub Releases 下载对应平台安装包即可（Mac 选 dmg，Windows 选 exe）。装好后首次启动，它会自动检测~/.claude/settings.json和~/.codex/auth.json是否存在，不存在就引导你创建。

cc-switch 的配置本质上是把多套settings.json存成 JSON 数组，存在它自己的配置目录里。以 macOS 为例，路径是~/Library/Application Support/cc-switch/config.json。你可以直接在界面里加，也可以手动编辑。一个包含「TaoToken 主通道」和「备用通道」的配置片段长这样：

{ "claude": { "providers": [ { "name": "TaoToken-Sonnet", "settingsConfig": { "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } } }, { "name": "TaoToken-Opus", "settingsConfig": { "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "claude-opus-4-1" } } } ], "current": "TaoToken-Sonnet" } }

这里有个关键点：cc-switch 切换时，会把current指向的 profile 的settingsConfig整个写入~/.claude/settings.json。所以你在界面里点「TaoToken-Opus」，Claude Code 下次启动就会用 Opus。不需要重启 cc-switch，也不需要手动改文件。

如果你同时用 Codex，cc-switch 还能管~/.codex/auth.json。Codex 的配置三件套是 Base URL、Key、Model ID，对应到 auth.json 里是：

{ "OPENAI_BASE_URL": "https://taotoken.net/api/v1", "OPENAI_API_KEY": "sk-你的TaoTokenKey", "model": "gpt-5-codex" }

注意 Codex 走的是 OpenAI 兼容协议，所以 Base URL 要带/v1，而 Claude Code 走 Anthropic 协议不带。这是两套配置最容易混的地方，cc-switch 分栏管理正好避免搞错。

再讲一个实用功能：MCP 配置同步。Claude Code 支持 MCP server，但 MCP 配置写在~/.claude.json里，和 settings.json 分开。cc-switch 可以在切换供应商时一并同步 MCP 配置，保证你换模型后工具链不断。WSL 用户还要注意，cc-switch 有「WSL 穿透」选项，开启后它会自动把 Windows 侧的配置映射到 WSL 的~/.claude，省得两边各配一份。

配完后回到 Claude Code，跑claude -p "当前用的是哪个模型"，如果回答里提到 Sonnet 或 Opus 与你切换的一致，说明 cc-switch 生效了。这一步是整个环境的中枢，配好之后模型切换就是点一下的事。

4. Skills 目录结构与渐进式披露：让 Agent 拥有可复用技能

Skills 是这套环境里最容易被低估的一层。很多人以为它就是个「提示词模板」，其实它的设计目标是让 Agent 在需要时自动加载能力，而不是把所有指令塞进系统提示。核心机制叫「渐进式披露」：Claude Code 启动时只读每个 Skill 的name和description，判断当前任务相关才读SKILL.md全文，再按需执行脚本。这样既省 token，又不会让无关技能干扰判断。

目录结构有固定约定。Skills 放在~/.claude/skills/下，每个技能一个子目录，目录名就是技能名：

~/.claude/skills/ ├── commit-helper/ │ ├── SKILL.md │ └── scripts/ │ └── gen_commit.sh ├── code-review/ │ ├── SKILL.md │ └── checklist.md └── api-doc-lookup/ ├── SKILL.md └── fetch_doc.py

SKILL.md必须包含 YAML frontmatter，至少写name和description。description 要写清楚「什么时候用这个技能」，因为模型就是靠它判断相关性的。一个 commit-helper 的例子：

--- name: commit-helper description: 当用户要求生成 git commit message、整理变更摘要、或提交代码时使用。按团队规范生成中文 commit。 --- # Commit Helper ## 步骤 1. 运行 `git diff --staged` 获取暂存区变更 2. 按以下格式生成 commit： - 类型(scope): 简述 - 空行 - 详细说明（可选） 3. 类型限定为 feat/fix/docs/refactor/test/chore ## 脚本 如需自动提交，调用 `scripts/gen_commit.sh`。

装好后怎么验证？进项目目录，敲claude进入交互模式，然后说「帮我生成这次改动的 commit message」。如果 Claude Code 回复里提到它调用了 commit-helper 技能，并且按你定义的格式输出，说明 Skills 加载成功。如果没反应，先检查目录名和 frontmatter 的name是否一致，再检查~/.claude/skills/路径有没有写错——WSL 下容易配到 Windows 路径去。

Skills 和 MCP 的分工要理清：MCP 适合接「外部服务」，比如数据库、内部 API；Skills 适合封装「操作流程」，比如代码审查清单、发布步骤。两者可以组合，比如一个 Skill 里调用 MCP 工具。斜杠命令则是手动触发的快捷方式，适合高频但不需要模型判断的场景。理解这三者区别，编排时就不会乱。

5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth

环境搭起来后，报错基本集中在四类。下面按真实遇到的顺序列，每条给出定位方法和修复动作。

401 Unauthorized。最常见，九成是 Key 问题。先确认ANTHROPIC_AUTH_TOKEN用的是 TaoToken 控制台创建的 Anthropic 兼容 Key，不是 OpenAI 兼容 Key。再检查有没有把 Key 写进ANTHROPIC_API_KEY而不是ANTHROPIC_AUTH_TOKEN——这两个头不一样，写错就是 401。最后用 curl 直接打一次，排除 Claude Code 本身的干扰：

curl https://taotoken.net/api/v1/messages \ -H "Authorization: Bearer sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-5","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

返回 200 和内容就说明 Key 和通道都没问题，问题在 Claude Code 配置。

local proxy failed。这个报错通常出现在 Base URL 写错时。Claude Code 会尝试把请求发到一个不存在的本地代理。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/v1/messages这种带完整路径的地址——正确写法是https://taotoken.net/api，路径由 Claude Code 自己拼。另外确认没有多余的末尾斜杠。

reading choices 报错。这个多出现在 Codex 或 Cline 走 OpenAI 兼容协议时，说明返回体不是预期的choices结构。原因通常是 Base URL 少了/v1，或者 Model ID 填成了 Anthropic 的模型名。Codex 要用https://taotoken.net/api/v1加 OpenAI 系模型 ID，别和 Claude Code 的配置混用。

OAuth 相关报错。Claude Code 首次启动可能引导你登录 Anthropic 账号，如果你用的是第三方通道，要在配置里显式设置ANTHROPIC_AUTH_TOKEN并跳过登录。如果它仍然弹 OAuth，删掉~/.claude/下的凭据缓存文件再重启。cc-switch 切换 profile 时也会重写这部分，所以配好 cc-switch 后这类问题基本消失。

排查顺序建议：先 curl 验通道，再验 Claude Code 配置，最后验 cc-switch 是否写对了文件。三层分开定位，比一股脑改配置快得多。

6. 跑通一次完整任务：从需求到提交的 Agent 工作流

前面都是零件，这一节把它们装成一台能跑的机器。任务选一个真实场景：给现有项目加一个「用户注册接口的参数校验」，要求生成代码、跑测试、按规范提交。

第一步，用 cc-switch 切到 Opus profile，因为架构设计需要强模型。打开 cc-switch 点一下「TaoToken-Opus」，确认~/.claude/settings.json里的 Model 变成claude-opus-4-1。

第二步，进项目目录启动 Claude Code：

cd ~/your-project claude

第三步，在交互模式里描述需求。因为装了 code-review 和 commit-helper 两个 Skill，你可以直接说：

帮我给 /api/register 接口加参数校验： - email 必填且格式合法 - password 至少 8 位含大小写 - 生成对应的单元测试 - 完成后按团队规范提交

Claude Code 会先读代码、判断需要哪些 Skill。它可能先调用 code-review 的清单确认校验点，再写代码和测试，最后触发 commit-helper 生成 commit message。整个过程你可以在终端里看到它调用了哪些工具、读了哪些文件。

第四步，验证结果。跑一次测试：

npm test -- --grep "register"

如果测试通过，再看 git 状态：

git log -1 --stat

确认 commit message 是feat(api): 增加注册接口参数校验这种格式，说明 commit-helper 生效了。

第五步，如果这个任务你更在意成本，切回 Sonnet profile 再跑一遍类似任务，对比输出质量。cc-switch 切换后新开的 Claude Code 会话就会用新模型，老会话不受影响。

这套流程跑通后，你就有了一条可复用的链路：cc-switch 管模型调度，Skills 管能力复用，TaoToken 管统一鉴权。下次遇到新需求，不用重新配环境，切个 profile、说句话就行。如果想把这条链路固化下来长期用，可以看看 TaoToken 的 Coding Plan，它按周期给编码额度，适合每天都要跑 Agent 任务的场景；临时验证模型效果的话，用「模型对话」页面直接试更轻。接入文档在https://taotoken.net/doc，API Key 在https://taotoken.net/api-keys管理，需要哪块直接点过去就行。