【Claude Code 第三方 API 配置完全指南（Windows版）】

Claude Code 第三方 API 配置完全指南Windows版从注册到实战10 分钟搞定国内直连第一章什么是 Claude CodeClaude Code 是由 Anthropic 官方推出的命令行 AI 编程助手它将大语言模型的能力直接嵌入开发者最熟悉的终端环境中。作为当前最主流的 AI 编码工具之一Claude Code 无需图形界面或浏览器开发者在命令行中即可完成从代码生成到项目重构的全流程操作真正实现对话即编程。核心能力智能代码生成根据自然语言描述直接生成可运行的代码片段支持数十种主流编程语言上下文感知编辑自动理解当前项目结构与文件内容精准定位并修改代码而非简单的文本替换多工具协同调度内置文件读写、终端执行、搜索检索等工具链能自主规划并完成多步骤的复杂任务全生命周期覆盖从需求分析、代码编写、测试运行到 Git 提交一条命令流水线贯通开发全过程适用人群Claude Code 尤其适合日常工作在终端环境中的开发者——无论你是需要快速搭建原型的全栈工程师、频繁处理代码审查与重构的后端开发者还是希望借助 AI 加速学习的编程新手都能从中获得显著的效率提升。它的命令行原生特性也使其成为 SSH 远程开发、CI/CD 流水线集成等场景的理想选择。了解了 Claude Code 的定位与能力后接下来我们将从零开始搭建运行环境完成必要的前置配置让你能够尽快上手体验。第二章前置准备获取 API Key2.1 环境准备在使用 Claude Code 之前请先确认你的 Windows 开发环境满足以下条件① 操作系统要求Windows 101903 及以上或 Windows 11建议使用Git Bash作为终端环境安装 Git 时自动附带② 安装 GitClaude Code 依赖 Git 进行项目管理与版本控制请先完成安装前往 Git 官网下载页 下载 Windows 安装包运行安装程序关键选项建议保持默认确保勾选Git Bash Here安装完成后打开Git Bash或 ****执行验证命令git --v③ 安装 Node.jsv18Claude Code 基于 Node.js 运行请确保已安装 v18 或更高版本前往 Node.js 官网 下载LTS长期支持版本的 Windows 安装包运行安装程序保持默认选项即可会自动配置环境变量并附带 npm安装完成后打开CMD命令提示符或Git Bash执行验证命令node -v npm -v⚠️ 如果执行node -v提示不是内部或外部命令请重启终端或检查系统环境变量中是否包含 Node.js 安装路径。④ 安装 Claude Code CLIGit 和 Node.js 就绪后即可通过 npm 一键安装 Claude Code:: 全局安装推荐任意目录均可调用 npm install -g anthropic-ai/claude-code安装完成后执行验证命令claude -v⑤ 跳过官方登录引导Claude Code 首次启动时会强制引导你登录 Anthropic 官方账号但国内网络环境下这一步通常无法完成。我们需要手动跳过该流程找到配置文件路径C:\Users\你的用户名\.claude.json用记事本或任意文本编辑器打开该文件在 JSON 中添加以下字段{hasCompletedOnboarding:true}⚠️ 如果文件中已有其他内容将hasCompletedOnboarding: true添加到现有 JSON 对象中即可注意前一行末尾需要加英文逗号,。如果文件不存在直接新建并写入上述内容。保存文件后重新打开 CMD 执行claude即可跳过登录直接进入命令行界面 此时 Claude Code 虽然能启动但尚未接入任何大模型还无法进行对话。接下来我们将通过配置 API Key 和 Base URL接入第三方中转服务的大模型来驱动它。2.2 前置说明由于 Anthropic 官方 API 在部分地区存在访问限制或延迟较高的问题许多开发者会选择通过第三方中转服务来调用 Claude 模型。中转服务的工作原理十分简单它提供一个兼容 OpenAI 格式的 API 端点你的请求先发送到中转服务器再由其转发至 Anthropic 官方接口响应结果原路返回。对于开发者而言只需替换 Base URL 和 API Key代码无需任何改动。2.3 获取 API Key本文以ClaudeAPI平台为例进行演示其他同类平台操作路径基本一致打开浏览器访问中转服务平台https://claudeapi.com并完成注册登录进入主页 或 你的中转平台的控制台Dashboard找到「API 密钥」或「令牌管理」入口点击「创建新密钥」为密钥添加备注名称如claude-code-dev复制生成的 API Key格式通常为sk-xxxxxxxx请立即保存部分平台仅展示一次在平台文档或密钥页面中找到 Base URL格式如https://hk.claudeapi.com2.4 关键信息记录请妥善记录以下两项关键信息它们将在第三章配置环节中使用配置项示例值用途Base URLhttps://hk.claudeapi.com告诉 Claude Code 将请求发送到哪个服务端点API Keysk-xxxxxxxxxxxxxxxx身份验证凭证用于授权你的每一次 API 调用⚠️安全提醒API Key 等同于你的账户密码切勿提交至公开代码仓库或分享给他人。建议使用环境变量方式存储避免硬编码在配置文件中。2.5 章节收尾环境与凭证准备就绪后接下来我们将正式进入 Claude Code 的核心配置步骤让工具真正跑起来。第三章核心配置——Claude Code 环境变量设置Claude Code 通过读取系统环境变量来获取 API 凭证信息。本章将在 Windows 环境下以CMD命令提示符和Git Bash为主要终端分别介绍临时设置和持久化写入两种方案。3.1 需要配置的环境变量变量名作用示例值ANTHROPIC_API_KEYAPI 身份验证密钥sk-xxxxxxxxxxxxxxxxANTHROPIC_BASE_URLAPI 服务端点地址使用中转服务时必填https://hk.claudeapi.com如果你直接使用 Anthropic 官方 API只需设置ANTHROPIC_API_KEY无需配置ANTHROPIC_BASE_URL。使用第三方中转服务时两者都必须设置。3.2 方案一临时设置当前终端会话有效临时设置仅在当前终端窗口中生效关闭窗口后自动失效。适合快速测试或临时切换不同 API 配置。CMD命令提示符set ANTHROPIC_API_KEYsk-你的密钥 set ANTHROPIC_BASE_URLhttps://hk.claudeapi.com⚠️ CMD 中set命令的等号两边不能有空格值也不需要加引号。Git BashexportANTHROPIC_API_KEYsk-你的密钥exportANTHROPIC_BASE_URLhttps://hk.claudeapi.com设置后立即验证是否生效:: CMD 验证 echo %ANTHROPIC_API_KEY% echo %ANTHROPIC_BASE_URL%# Git Bash 验证echo$ANTHROPIC_API_KEYecho$ANTHROPIC_BASE_URL如果输出了你填入的值说明临时设置成功可以直接跳到第四章进行连通性测试。3.3 方案二持久化写入永久生效推荐持久化设置会写入系统或用户级配置重启终端、重启电脑后依然有效。推荐日常使用此方式。方式 A通过 CMD 命令写入用户环境变量使用setx命令可以将变量永久写入当前用户的环境变量setx ANTHROPIC_API_KEY sk-你的密钥 setx ANTHROPIC_BASE_URL https://hk.claudeapi.com执行成功后会提示成功: 指定的值已得到保存。⚠️setx写入的变量不会在当前窗口生效必须重新打开一个 CMD 窗口才能读取到。这是 Windows 的正常行为不是报错。重新打开 CMD 后验证echo %ANTHROPIC_API_KEY% :: 预期输出sk-你的密钥 echo %ANTHROPIC_BASE_URL% :: 预期输出https://hk.claudeapi.com方式 B通过系统设置界面手动添加如果你不习惯命令行操作也可以通过图形界面完成按Win S搜索“编辑系统环境变量”点击打开在弹出的「系统属性」窗口中点击右下角「环境变量」按钮在「用户变量」区域点击「新建」变量名ANTHROPIC_API_KEY变量值sk-你的密钥再次点击「新建」变量名ANTHROPIC_BASE_URL变量值https://hk.claudeapi.com依次点击「确定」关闭所有窗口重新打开终端执行验证命令确认生效方式 C写入 Git Bash 配置文件仅 Git Bash 生效如果你主要使用 Git Bash 作为终端可以将变量写入~/.bashrcechoexport ANTHROPIC_API_KEYsk-你的密钥~/.bashrcechoexport ANTHROPIC_BASE_URLhttps://hk.claudeapi.com~/.bashrcsource~/.bashrc此方式仅对 Git Bash 有效。如果你希望 CMD 也能读取到请使用方式 A 或方式 B。3.4 多配置切换技巧如果你同时持有多个中转平台的 API Key如测试环境与生产环境可以编写简单的批处理脚本快速切换批处理示例保存为switch-api.batecho off if %1test ( set ANTHROPIC_API_KEYsk-测试环境密钥 set ANTHROPIC_BASE_URLhttps://测试环境地址.com echo 已切换至测试环境 ) else if %1prod ( set ANTHROPIC_API_KEYsk-正式环境密钥 set ANTHROPIC_BASE_URLhttps://正式环境地址.com echo 已切换至正式环境 ) else ( echo 用法: switch-api.bat [test^|prod] )使用方式在 CMD 中执行switch-api.bat test :: 切换到测试环境 switch-api.bat prod :: 切换到正式环境 批处理脚本中的set是临时设置仅在当前 CMD 窗口有效。如需持久切换将set改为setx即可。3.5 章节小结环境变量配置完成后Claude Code 就拥有了访问 API 的通行证。接下来我们将通过多种方式验证配置是否正确、API 是否连通。第四章配置验证——测试 API 连通性配置完环境变量后务必进行连通性测试。以下提供三种验证方式由简到繁建议至少完成第一种。4.1 方式一Claude Code 直接对话最快捷打开 CMD 或 Git Bash直接启动 Claude Codeclaude进入交互界面后输入一条简单的提示词你好请用一句话介绍你自己。预期结果我是 Claude由 Anthropic 开发的 AI 助手擅长编程、写作和问题分析。如果能正常收到回复说明 API Key、Base URL、网络三项配置均已生效可以跳过后续验证。如果报错请继续使用方式二、三排查定位。4.2 方式二curl 手动请求精准定位问题通过 curl 直接向 API 端点发送请求可以绕过 Claude Code 本身单独验证 API 层是否通畅。在 Git Bash 中执行curl-shttps://hk.claudeapi.com/v1/messages\-HContent-Type: application/json\-Hx-api-key: sk-你的密钥\-Hanthropic-version: 2023-06-01\-d{ model: claude-haiku-4-5-20251001, max_tokens: 100, messages: [ {role: user, content: 说你好} ] }在 CMD 中执行注意 CMD 不支持单引号和反斜杠换行需用双引号并转义curl -s https://hk.claudeapi.com/v1/messages -H Content-Type: application/json -H x-api-key: sk-你的密钥 -H anthropic-version: 2023-06-01 -d {\model\:\claude-haiku-4-5-20251001\,\max_tokens\:100,\messages\:[{\role\:\user\,\content\:\说你好\}]}预期输出JSON 格式{id:msg_xxxxxxxxxxxx,type:message,role:assistant,content:[{type:text,text:你好有什么我可以帮助你的吗}],model:claude-haiku-4-5-20251001,stop_reason:end_turn} 这里选用claude-haiku-4-5-20251001模型进行测试因为它响应最快、费用最低非常适合做连通性验证。常见异常输出对照输出内容含义{error:{type:authentication_error,...}}API Key 无效或已过期{error:{type:not_found_error,...}}Base URL 错误或模型名称不正确curl: (6) Could not resolve host域名解析失败检查 Base URL 拼写或网络curl: (28) Connection timed out网络不通检查代理或防火墙设置4.3 方式三Python 脚本测试开发集成参考如果你的电脑已安装 Python 3可以使用以下脚本进行更完整的验证同时作为后续开发集成的参考模板# test_api.py —— API 连通性测试脚本importosimportrequests api_keyos.environ.get(ANTHROPIC_API_KEY)base_urlos.environ.get(ANTHROPIC_BASE_URL,https://api.anthropic.com)ifnotapi_key:print(未检测到 ANTHROPIC_API_KEY 环境变量请先完成第三章配置)exit(1)print(fBase URL:{base_url})print(fAPI Key:{api_key[:8]}...{api_key[-4:]})print(-*40)try:responserequests.post(f{base_url}/v1/messages,headers{Content-Type:application/json,x-api-key:api_key,anthropic-version:2023-06-01},json{model:claude-haiku-4-5-20251001,max_tokens:100,messages:[{role:user,content:回复OK两个字母即可}]},timeout30)ifresponse.status_code200:resultresponse.json()textresult[content][0][text]print(f连通成功模型回复{text})else:print(f请求失败状态码{response.status_code})print(f错误信息{response.text})exceptrequests.exceptions.ConnectionError:print(连接失败请检查 Base URL 或网络环境)exceptrequests.exceptions.Timeout:print(请求超时请检查网络或稍后重试)运行方式pip install requests :: 首次运行需安装依赖 python test_api.py预期输出Base URL: https://hk.claudeapi.com API Key: sk-xxxxxx...xxxx ---------------------------------------- 连通成功模型回复OK4.4 章节小结三种验证方式任选其一通过即可确认环境配置无误。如果遇到报错请参考下一章的常见问题排错指南进行排查。第五章常见问题排错指南在配置和使用 Claude Code 的过程中可能会遇到各种报错。本章汇总了最高频的问题及其解决方案帮助你快速定位并修复。5.1 API 请求类错误错误现象可能原因解决方案401 Unauthorized/authentication_errorAPI Key 无效、已过期或格式错误① 检查 Key 是否复制完整注意首尾空格② 登录中转平台确认 Key 状态是否为「启用」③ 重新生成一个新 Key 并替换403 Forbidden/permission_errorAPI Key 权限不足或账户余额为零① 检查中转平台账户余额是否充足② 确认 Key 的权限范围是否包含目标模型③ 联系平台客服确认账户状态404 Not Found/not_found_errorBase URL 错误或请求的模型不存在① 核对 Base URL 是否拼写正确注意https://前缀② 确认模型名称是否为平台支持的模型如claude-sonnet-4-6而非自定义名称③ 查看平台文档确认可用模型列表429 Too Many Requests/rate_limit_error请求频率超过限制① 降低请求频率等待 30-60 秒后重试② 检查是否有多个进程同时使用同一 Key③ 联系平台确认当前套餐的速率限制RPM/TPM500 / 502 / 503服务端错误中转服务或上游 API 暂时不可用① 等待 1-2 分钟后重试② 检查中转平台公告是否有维护通知③ 尝试切换到其他可用模型5.2 网络连接类错误错误现象可能原因解决方案Could not resolve host域名解析失败① 检查 Base URL 中的域名是否拼写正确② 在终端执行ping 你的域名测试 DNS 是否正常③ 尝试更换 DNS如8.8.8.8或223.5.5.5Connection timed out/ETIMEDOUT网络不通或被防火墙拦截① 检查网络代理设置是否正确② 在浏览器中直接访问 Base URL 确认可达③ 检查防火墙/安全软件是否拦截了终端的出站请求SSL/TLS handshake failed证书问题或 HTTPS 配置异常① 确认 Base URL 使用https://而非http://② 更新系统根证书③ 如使用公司内网代理确认已安装代理 CA 证书5.3 环境变量类错误错误现象可能原因解决方案Claude Code 提示API key not found环境变量未设置或未生效① 在 CMD 中执行echo %ANTHROPIC_API_KEY%确认变量值② 如使用setx持久化方案确认已重新打开终端③ 检查变量名拼写是否正确区分大小写使用setx后当前窗口仍然读不到setx写入的变量不在当前会话中这是正常现象。setx写入注册表仅对新打开的终端生效。当前窗口需额外执行set命令临时补充Git Bash 中echo $ANTHROPIC_API_KEY为空.bashrc未被加载或未通过系统变量设置① 执行source ~/.bashrc手动加载② 或改用setx/图形界面设置Git Bash 也能自动读取系统环境变量5.4 Claude Code CLI 类错误错误现象可能原因解决方案claude 不是内部或外部命令CLI 未安装或 npm 全局路径不在 PATH 中① 重新执行npm install -g anthropic-ai/claude-code② 执行npm list -g确认已安装③ 执行npm config get prefix查看全局路径确认该路径在系统 PATH 中安装时报EACCES或权限错误npm 全局目录无写入权限① 以管理员身份运行 CMD 重新安装② 或修改 npm 全局路径npm config set prefix %USERPROFILE%\.npm-global后将该路径加入 PATHError: Cannot find module ...Node.js 版本过低或安装损坏① 执行node -v确认版本 ≥ v18② 如版本过低卸载后重新安装 LTS 版本③ 尝试清除 npm 缓存npm cache clean --force5.5 快速自检清单遇到问题时可按以下顺序逐项排查Node.js 版本node -v输出 ≥ v18Git 已安装git --version能正常输出CLI 已安装claude --version能正常输出API Key 已设置echo %ANTHROPIC_API_KEY%CMD或echo $ANTHROPIC_API_KEYGit Bash有值Base URL 已设置echo %ANTHROPIC_BASE_URL%CMD或echo $ANTHROPIC_BASE_URLGit Bash有值网络可达curl https://你的中转地址.com有响应终端已重启使用setx持久化写入后是否打开了新的终端窗口按此清单从上到下排查大多数问题都能在前 3 步内定位到根因。第六章进阶使用——多模型切换与效率技巧完成基础配置后Claude Code 还有许多进阶能力值得探索。简单介绍一下模型切换、配置文件定制以及日常提效技巧帮助你更高效地使用这款工具。6.1 认识 Claude 模型家族Claude 目前提供三个主力模型定位各不相同模型模型 ID特点适用场景Haikuclaude-haiku-4-5-20251001响应最快、费用最低简单问答、代码补全、快速验证Sonnetclaude-sonnet-4-6速度与能力均衡日常编程、代码审查、中等复杂度任务Opusclaude-opus-4-6最强推理能力复杂架构设计、大规模重构、深度分析 费用参考Opus 约为 Haiku 的 30-50 倍。日常开发建议以 Sonnet 为主力遇到复杂问题再切换 Opus。6.2 切换模型的方法方法一交互界面内切换在 Claude Code 对话中直接输入斜杠命令/model claude-opus-4-6切换后当前会话立即生效无需重启。方法二通过环境变量指定默认模型在 CMD 中设置CLAUDE_MODEL环境变量每次启动 Claude Code 时自动使用指定模型:: 临时设置当前窗口 set CLAUDE_MODELclaude-sonnet-4-6 :: 持久化设置重启后生效 setx CLAUDE_MODEL claude-sonnet-4-6方法三启动时指定模型claude --model claude-opus-4-6适合临时使用某个模型处理单次任务不影响默认配置。6.3 配置文件高级定制Claude Code 的配置文件位于用户目录下的.claude/settings.json可以通过它定制更多行为。查看配置文件路径:: Windows 下的默认路径 echo %USERPROFILE%\.claude\settings.json常用配置项示例{permissions:{allow:[Bash(npm install:*),Bash(npm run:*),Bash(git:*)]},env:{CLAUDE_MODEL:claude-sonnet-4-6}}配置项说明配置项作用说明permissions.allow自动授权的工具命令避免每次执行npm、git等命令时弹出确认提示env环境变量覆盖可在此处设置默认模型、API 地址等优先级高于系统环境变量⚠️ 权限配置请谨慎添加仅对你信任的命令开放自动授权。6.4 项目级配置CLAUDE.md在项目根目录创建CLAUDE.md文件可以为 Claude Code 提供项目上下文让它更准确地理解你的代码规范# 项目说明 - 本项目使用 Node.js Express 框架 - 代码风格遵循 ESLint Airbnb 规范 - 测试框架使用 Jest - 提交信息格式type(scope): descriptionClaude Code 启动时会自动读取该文件后续对话中会遵循其中的约定显著减少重复说明。6.5 日常提效技巧技巧命令/操作说明快速启动claude在项目目录下直接启动自动加载上下文继续上次对话claude --continue恢复上一次会话无需重新描述背景非交互模式claude -p 你的问题单次提问直接返回结果适合脚本调用查看帮助claude --help查看所有可用参数和命令清除上下文/clear在对话中清除历史释放上下文窗口查看费用/cost查看当前会话的 Token 消耗和费用 善用claude -p非交互模式可以将 Claude Code 集成到批处理脚本或自动化流程中实现批量代码审查、自动生成提交信息等操作。6.6 延伸学习资源资源地址说明Claude Code 官方文档https://docs.anthropic.com/en/docs/claude-code最权威的功能说明与 API 参考Anthropic 官方博客https://www.anthropic.com/news模型更新、功能发布等最新动态Claude Code GitHubhttps://github.com/anthropics/claude-code源码、Issue 反馈与社区讨论Prompt 工程指南https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering编写高质量提示词的官方指南Node.js 官方文档https://nodejs.org/docs/latest/api/Node.js 环境相关问题的参考6.7 写在最后Claude Code 的真正价值在于实践。建议你从一个小型项目开始——无论是写一个脚本、重构一段旧代码还是用它帮你理解一个陌生的开源项目——动手尝试才是最快的学习路径。祝您编码愉快