保姆级 Claude Code 全攻略：安装、API Key 配置、cc-switch 切换、接入 DeepSeek 国产模型，一篇搞定 TaoToken

1. 为什么第一次装 Claude Code 的人总在 API Key 这步卡住Claude Code 是 Anthropic 官方推出的终端 AI 编程智能体简单说就是你把需求丢给它它自己读文件、改代码、跑命令、修 bug循环到任务完成。它和 Cursor、Copilot 那种「编辑器里补全」的形态不一样Claude Code 是跑在终端里的自主 Agent适合习惯命令行、想让 AI 从头到尾干完一个任务的开发者。如果你是第一次接触它大概率会在三个地方卡住装完之后不知道用哪种方式登录、API Key 到底该放哪个环境变量、以及想换成 DeepSeek 这类国产模型时配置写不对。我自己第一次配的时候把官方 Key 和第三方 Token 同时塞进环境变量结果启动直接报 Auth conflict排查了半小时才发现是两个认证变量打架。这篇就把安装、API Key 配置、cc-switch 多环境切换、接入 DeepSeek 国产模型这条链路一次讲透每一步都给可复制的配置片段和验证命令你照着敲就能跑通。先说清楚 Claude Code 能做什么避免你装完不知道拿它干嘛。它能读文件、写文件、改文件能执行 shell 命令跑测试、装依赖、git 操作能全代码库搜索能通过 MCP 连接数据库、浏览器、API 这类外部工具还能分析完代码库给你出一份架构方案。定位一句话你负责下需求它负责动手你在旁边审核。适合谁适合想让 AI 真正「干活」而不是「补全几行」的开发者尤其是愿意在终端里工作、想把它塞进 CI/CD 做无人值守的人。安装本身不复杂官方原生安装零依赖macOS 和 Linux 一行命令Windows 用 PowerShell 一行命令。真正让人头疼的是装完之后首次启动要登录登录有 OAuth 和 API Key 两条路想省钱接 DeepSeek又得改 base_url 和 token手上同时有官方 Key、DeepSeek、公司内网模型手动改 settings.json 改到崩溃。所以这篇的重点不在「怎么装」而在「装完之后怎么把配置管明白」这也是 cc-switch 这类工具存在的意义。下面按顺序来先讲安装和首次启动再讲 API Key 配置的核心逻辑然后是 settings.json 配置体系接着重点讲接入 DeepSeek再用 cc-switch 把多环境切换管起来最后给验证命令和常见报错排查。每一节都有可直接复制的片段你不需要理解全部原理先跑通再回头细看。2. 安装 Claude Code 与首次启动登录认证的完整步骤安装 Claude Code 有三种方式我建议新手直接用官方原生安装零依赖不用先装 Node.js。macOS 和 Linux 打开终端执行curl -fsSL https://claude.ai/install.sh | bashWindows 用管理员权限打开 PowerShellirm https://claude.ai/install.ps1 | iex如果你要锁版本或者跑 CI/CD用 npm 安装更合适npm install -g anthropic-ai/claude-codemacOS 用户也可以用 Homebrewbrew install --cask claude-code国内网络下 npm 安装经常慢到超时换国内镜像源能明显改善npm config set registry https://registry.npmmirror.com npm install -g anthropic-ai/claude-code装完验证一下能输出版本号就说明成功了claude --version以后升级用claude update就行。这里提醒一句Windows 用户优先用 Git Bash 或 WSL 跑 Claude CodePowerShell 也能用但可能要先解决执行策略问题后面排查章节会讲。装好之后进项目目录启动cd /path/to/your-project claude首次启动会要求登录有两条路。路线 A 是 Claude 订阅用户走 OAuth 浏览器登录输入claude后选择浏览器登录会自动打开浏览器完成授权Token 自动缓存你完全不用管 API Key。路线 B 是 API Key 用户走命令行登录claude auth login --api-key然后粘贴你的 Key。查看和退出登录状态用claude auth status claude auth logout会话内也可以随时输入/login、/logout切换账号多账号场景很有用。这里有个关键点如果你打算接 DeepSeek 这类国产模型走的是 API Key 路线而且配置前最好先claude auth logout并清掉官方 Key 的环境变量否则两个认证变量会冲突。这一步很多人忽略直接导致后面接 DeepSeek 时报错。3. API Key 配置与 settings.json 配置体系的可复制片段API Key 配置是整条链路的核心。先搞清楚两个变量别搞混ANTHROPIC_API_KEY用于 Anthropic 官方 API KeyANTHROPIC_AUTH_TOKEN用于任意 Bearer Token也就是中转站、国产模型、DeepSeek 这类。这两个不要同时设会触发 Auth conflict 报错。切到国产模型时把官方 Key 清掉。临时配置用环境变量macOS 和 Linuxexport ANTHROPIC_API_KEYsk-ant-xxxWindows PowerShell$env:ANTHROPIC_API_KEYsk-ant-xxx这种是临时的关掉终端就没了。想永久生效macOS 和 Linux 写进~/.zshrc或~/.bashrcecho export ANTHROPIC_API_KEYsk-ant-xxx ~/.zshrc source ~/.zshrc但我更推荐用 settings.jsonCLI 和 VS Code 通吃不用碰系统环境变量。macOS 和 Linux 路径是~/.claude/settings.jsonWindows 是C:\Users\你的用户名\.claude\settings.json。最基础的写法{ env: { ANTHROPIC_API_KEY: sk-ant-xxx } }Claude Code 的配置是三级级联的优先级从低到高用户级~/.claude/settings.json全局生效项目级.claude/settings.json进 git 团队共享项目级个人.claude/settings.local.json不进 git 只给自己用。原则很简单个人私货Key、本地路径放 settings.local.json团队规范放 settings.json。改完配置重启 Claude Code 生效。配置内容主要四块env、permissions、hooks、mcpServers。一个「什么都配好」的样板长这样{ env: { ANTHROPIC_MODEL: claude-sonnet-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5, ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-5, ANTHROPIC_DEFAULT_SONNET_MODEL: claude-sonnet-5, ANTHROPIC_DEFAULT_HAIKU_MODEL: claude-haiku-4-5, CLAUDE_CODE_EFFORT_LEVEL: medium, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 } }这里解释几个关键变量。ANTHROPIC_BASE_URL是接口地址接入国产模型和中转站全靠它。ANTHROPIC_MODEL是默认主模型。ANTHROPIC_SMALL_FAST_MODEL是后台轻量任务用的小模型这是省钱关键。官方主模型分 Opus、Sonnet、Haiku 三档Sonnet 是日常主力Opus 干重活Haiku 跑后台小任务。CLAUDE_CODE_EFFORT_LEVEL控制推理强度可选 low、medium、high、max。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设为 1 关闭遥测隐私友好。如果你用 TaoToken 这类平台配置思路完全一样把 base_url 指向对应端点、token 换成平台 Key 即可。TaoToken 的 API 地址是https://taotoken.net/api控制台在https://taotoken.net/consoleAPI Key 在https://taotoken.net/api-keys申请。配置片段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的 TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 } }注意 base_url 末尾一般不要加斜杠认证用ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY。这两点写错是最常见的接入失败原因。4. 接入 DeepSeek 国产模型并验证 API 连通性DeepSeek 官方直接提供了 Anthropic 兼容接口https://api.deepseek.com/anthropic也就是说不用任何第三方工具把ANTHROPIC_BASE_URL指过去、Token 换成 DeepSeek 的 Key就能让 Claude Code 跑在 DeepSeek 模型上。这是目前最省心的方案。先临时试水macOS 和 Linuxexport ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的 DeepSeek API Key export ANTHROPIC_MODELdeepseek-v4-pro[1m] export ANTHROPIC_DEFAULT_OPUS_MODELdeepseek-v4-pro[1m] export ANTHROPIC_DEFAULT_SONNET_MODELdeepseek-v4-pro[1m] export ANTHROPIC_DEFAULT_HAIKU_MODELdeepseek-v4-flash export CLAUDE_CODE_SUBAGENT_MODELdeepseek-v4-flash export CLAUDE_CODE_EFFORT_LEVELmax export CLAUDE_CODE_AUTO_COMPACT_WINDOW786432Windows PowerShell 对应写法$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKEN你的 DeepSeek API Key $env:ANTHROPIC_MODELdeepseek-v4-pro[1m] $env:ANTHROPIC_DEFAULT_OPUS_MODELdeepseek-v4-pro[1m] $env:ANTHROPIC_DEFAULT_SONNET_MODELdeepseek-v4-pro[1m] $env:ANTHROPIC_DEFAULT_HAIKU_MODELdeepseek-v4-flash $env:CLAUDE_CODE_SUBAGENT_MODELdeepseek-v4-flash $env:CLAUDE_CODE_EFFORT_LEVELmax $env:CLAUDE_CODE_AUTO_COMPACT_WINDOW786432长期用就写进 settings.json{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: 你的 DeepSeek API Key, ANTHROPIC_MODEL: deepseek-v4-pro[1m], ANTHROPIC_DEFAULT_OPUS_MODEL: deepseek-v4-pro[1m], ANTHROPIC_DEFAULT_SONNET_MODEL: deepseek-v4-pro[1m], ANTHROPIC_DEFAULT_HAIKU_MODEL: deepseek-v4-flash, CLAUDE_CODE_SUBAGENT_MODEL: deepseek-v4-flash, CLAUDE_CODE_EFFORT_LEVEL: max, CLAUDE_CODE_AUTO_COMPACT_WINDOW: 786432, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 } }配置前先claude auth logout并清掉ANTHROPIC_API_KEY避免两个认证变量冲突。DeepSeek 会自动把 Claude Code 发出的档位请求映射成自己的模型claude-opus 开头的映射到 deepseek-v4-proclaude-sonnet 开头的映射到 deepseek-v4-flashclaude-haiku 开头的也映射到 deepseek-v4-flash。怎么验证接入成功三个办法。第一直接正常对话能回复就基本成功。第二故意问一个需要执行命令或改文件的任务看它是否真的动手。第三去 DeepSeek 控制台的用量页面看有没有调用记录这个最可靠。注意一个坑问「你是什么模型」它可能还回答 Claude这是系统提示词写死的不能作为判断依据。如果你想用 TaoToken 接入配置片段是{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的 TaoToken Key, ANTHROPIC_MODEL: deepseek-v4-pro[1m], ANTHROPIC_SMALL_FAST_MODEL: deepseek-v4-flash } }验证连通性可以用 curl 直接打接口确认 Key 和地址没问题curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的 Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-5,max_tokens:64,messages:[{role:user,content:ping}]}返回里有正常的 content 字段就说明链路通了。如果返回 401说明 Key 有问题返回 model 相关错误说明模型 ID 配错了。5. cc-switch 多环境切换与常见报错排查手上同时有官方 Key、DeepSeek、中转站、公司内网模型时手动改 settings.json 很痛苦容易漏逗号一错 Claude Code 直接连不上来回改环境变量和模型名烦多台机器配置还不一致。cc-switch 系列工具就是解决这个的把多套「供应商配置」保存为模板一键写入 Claude Code 配置附带备份和回滚。市面上叫 cc-switch 的有好几个讲清楚三个最主流的。第一个是 farion1231/cc-switch桌面 GUI 版新手首选。macOS 用brew install --cask cc-switch或下载 dmgWindows 下载 msiLinux 用 deb 或 rpm。使用步骤打开 CC Switch进「供应商管理」页点右上角加号添加供应商填入供应商名称、API Key、请求地址末尾不要加斜杠、API 格式选 Anthropic Messages 原生点「使用」写入配置重启 Claude Code 完成。它支持模型别名映射还会抹平 Windows 和 WSL 路径差异。第二个是 cc-switch-config轻量 TUI 终端版适合项目级秒切。安装npm install -g cc-switch-config核心命令cc-config # 打开交互式 TUI 仪表盘 cc-config 配置名 # 一步把当前项目切到某配置 cc-config list # 列出所有已注册项目 cc-config config add # 新建模板 cc-config register /path/to/project cc-config switch 项目 配置 cc-config undo # 撤销上次切换它写入的是 settings.local.json优先级高于项目级 settings而且只改 env 和 model 字段不碰你的 permissions、hooks、mcpServers这点很良心。完整流程cc-config config add # 名称: deepseek # API Key: sk-xxx # Base URL: https://api.deepseek.com/anthropic # 模型: deepseek-v4-pro[1m] cc-config register . cc-config switch . deepseek第三个是 aravhawk/cc-switch命令行 Profile 管理器把整个 settings.json 副本存在~/.cc-switch/profiles/管理。安装npm install -g aravhawk/cc-switch命令有cc-switch --list、cc-switch --current、cc-switch --create work --template moonshot --api-key sk-xxx等内置 anthropic、moonshot、zai、minimax 模板。现在讲常见报错排查这些都是真实会遇到的。报错Unable to connect to Anthropic services如果你用了 claude-code-router必须用ccr code启动而不是claude如果是网络问题检查是否走代理或换国产模型。报错Auth conflict是ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY同时存在执行claude auth logout并清掉其中一个。报错 401 或 Invalid API KeyKey 抄错或过期或中转站余额为 0确认变量用对了。报错Missing model in request body模型 ID 配错检查ANTHROPIC_MODEL是否和平台真实模型 ID 一致。报错local proxy failed通常是本地代理端口没起来或配置的 base_url 不可达检查代理进程和地址。报错reading choices这类解析错误多半是接口返回格式和预期不符确认用的是 Anthropic Messages 原生格式而不是 OpenAI 格式。Windows PowerShell 无法运行脚本执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。还有一个高频问题接入 DeepSeek 后没反应或行为怪异。先确认ANTHROPIC_BASE_URL末尾没多余斜杠确认地址是https://api.deepseek.com/anthropic而不是 chat/completions再claude update升级到最新版。连接超时或频繁 429是触发限流稍等重试或降级到更小更便宜的模型。6. 把配置管明白之后Claude Code 才真正好用跑通全流程之后你会发现 Claude Code 的价值不在「装上了」而在「配置管明白了」。日常开发循环是改需求Claude 实现自动跑测试失败自动修最后/commit提交。新项目第一天先/init生成项目说明书再让它出架构方案然后开始实现第一个模块。代码审查用/review安全审查用/security-review。几个实用技巧。上下文用到 70% 到 80% 就/compact或/clear别让它撞顶。模型分工日常用 Sonnet 或 DeepSeek 便宜档重活切 Opus后台小任务用 Haiku 或 flash。CLAUDE.md 要「薄」只记代码里看不出来的事别把整个 README 抄进去。必须执行的动作用 Hooks别指望 CLAUDE.md因为 CLAUDE.md 只是建议Hooks 是外壳强制执行的。善用claude -p把 AI 塞进 CI无人值守自动修测试。多账号多供应商用 cc-switch 管起来别手动改 JSON。安全红线也要记住。API Key 永远不入库、不提交.claude/加进.gitignore。提示词注入要警惕在 PreToolUse 里拦一手别让 AI 盲信文件内容里的「指令」。权限里 deny 掉危险操作比如 force push、hard reset、删根目录、读密钥文件。中转站小额充值别放太多钱。如果你还没开始建议的路径是先用官方原生安装装好用 OAuth 或官方 Key 跑通一次对话确认 Claude Code 本身没问题然后按第 4 节接 DeepSeek验证省钱方案能跑最后用 cc-switch 把官方和 DeepSeek 两套配置存成模板以后一键切换。这样即使某一套配置出问题你还有另一套能立刻用不会卡死在排查里。需要 Key 和接入文档的话TaoToken 的 API Key 在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc模型对话入口在https://taotoken.net/chat。如果你打算长期用 Claude Code 做编码和 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan。先把配置跑通再考虑长期方案顺序别反了。