企业官网建设流程全解析

1. 国内开发者第一次跑 Claude Code 到底卡在哪

Claude Code 是 Anthropic 出的命令行 Agent 框架，能读你项目里的文件、执行命令、改代码、跑测试，本质是一个「会自己动手的编程助手外壳」。它本身不产出智能，智能来自背后的大语言模型。原版默认连 Anthropic 官方模型，国内开发者第一次上手，卡点通常集中在三件事：装不上、连不通、不敢用。

装不上是因为 Claude Code 在 Windows 上依赖 Git Bash 执行部分命令，很多人只装了 Node 却没装 Git，运行时报一堆找不到 shell 的错。连不通是因为默认走官方端点，没有可用通道时请求直接超时。不敢用是因为一上来就在 C 盘根目录启动，Agent 扫描整个磁盘，既慢又容易误操作。

这篇教程面向 Windows 10/11 的国内开发者，从 winget 安装、API Key 获取、CC Switch 配置到 CLAUDE.md 初始化，给出一条能完整跑通的路径。核心思路是：Claude Code 作为 Agent 框架保留，把背后的模型换成国内可直接调用的兼容接口。这样你既用上了公认最强的 Agent 框架，又不需要折腾网络环境。

适合谁看：刚接触命令行 Agent 的后端/前端开发者、想用 AI 辅助写脚本的产品或数据同学、以及被各种模型周更搞得眼花、想先搭一个稳定工作流的人。全程用 PowerShell，命令可直接复制。我试过在一台干净的 Win11 机器上从零走一遍，大概二十分钟能跑通第一个任务。

需要提前说清楚一个概念：模型会不断被替代，但 Agent 框架是更持久的基础设施。今天你用某个模型，明天可能换更强的，但 Claude Code 这套「读文件—规划—执行—验证」的工作方式不会变。所以先把框架搭稳，模型随时可换，这才是省时间的做法。

下面按「概念—前置—配置—验证—排障—收尾」的顺序展开。概念部分别跳过，尤其是 CC Switch 和 CLAUDE.md 这两个东西，理解了后面配置会顺很多。

2. 搭 Claude Code 前必须搞懂的 CC Switch 与 API Key

在动手之前，把几个反复出现的名词讲透，后面配置时你就知道每一栏该填什么。

Agent 框架就是 Claude Code 本身。它负责接收你的自然语言指令，自主决定读哪些文件、执行哪些命令、生成哪些代码。它调用背后的「大脑」来做规划和推理。框架和模型是分离的，这是整个方案能成立的前提。

API Key是身份通行证。你用的国内模型跑在厂商的云端服务器上，你的电脑要通过网络向服务器发请求。Key 就是证明「这次请求是我发的」的凭证。在模型开放平台注册账号后可以创建，形如sk-xxxxxxxx或xxxxxxxx.yyyyyyyy。它等同于密码，不要提交到 Git，不要写进代码。

CC Switch是给 Claude Code 换大脑的遥控器。它是一个图形化小工具，能添加任意兼容 OpenAI API 格式的模型端点，一键切换当前 Claude Code 使用的模型，还能管理多组 API Key 和配置。没有它，你得手动改环境变量或配置文件，切一次模型折腾半天；有了它，点一下就行。

CLAUDE.md是 Claude Code 的协作规则文件。它分全局和项目级两种。全局放在%USERPROFILE%\.claude\CLAUDE.md，所有项目生效；项目级放在项目文件夹内，只对当前项目生效。里面写清楚沟通语言、哪些操作必须先问你、工程习惯等。第一天就配好全局文件，能省掉后面大量重复解释。

上下文污染是个容易被忽视的坑。如果你在C:\根目录启动 Claude Code，它会看到整台电脑的所有文件夹，信息量爆炸，导致分析变慢、误判、甚至误操作。正确做法是为每个项目建独立文件夹，cd进去再启动，让它只关注当前项目。

winget是 Windows 官方包管理器，相当于命令行版应用商店。一条命令就能装 Git 和 Claude Code，比手动下载安装包省事。

把这些串起来：winget 装好 Git 和 Claude Code，CC Switch 负责把模型端点指向国内可调用的服务并填入 API Key，CLAUDE.md 设定协作规则，最后在独立项目文件夹里启动。整条链路清晰了，下面进入实操。

3. 可复制的 Claude Code 安装与 CC Switch 配置片段

这一节是全文技术核心，每一步都给完整命令和配置片段，路径与原文一致，可直接复制。

3.1 用 winget 安装 Git 和 Claude Code

先装 Git，Claude Code 在 Windows 上依赖 Git Bash 执行部分命令。打开 PowerShell，建议以管理员身份运行：

winget install Git.Git

等待出现「已成功安装」，然后验证：

git --version

输出版本号如git version 2.42.0即成功。如果提示找不到命令，关掉 PowerShell 重开一次，让 PATH 刷新。

接着装 Claude Code：

winget install Anthropic.ClaudeCode

装完验证：

claude --version

看到版本号就说明框架本体就位。如果提示「claude 不是可识别的命令」，同样是重开终端或检查 PATH。PATH 就是系统记录程序文件夹位置的地图，安装程序一般会自动配好，个别情况需要手动把安装目录加进去。

3.2 获取 API Key 并配置 CC Switch

去你选定的模型开放平台注册账号，进入「API 管理」或「API Keys」页面，创建 Key 并复制。不同厂商入口名称略有差异，认准「开放平台」和「API 管理」这两个关键词即可。

打开 CC Switch，在 Claude 选项卡点右上角加号新增配置。需要填三件套：

这三件套是任何兼容 OpenAI 格式接入的通用结构，CC Switch、Cline MCP、Codex 的 auth.json 都遵循同一套逻辑：Base URL 指向服务端点，Key 证明身份，Model ID 指定用哪个模型。填完点「添加」，再在主界面点一下让它变为「启用」状态。

如果你更习惯直接改配置文件，Claude Code 的 settings 片段结构如下，路径为%USERPROFILE%\.claude\settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://你的端点地址/v1", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "你的模型ID" } }

注意 JSON 里不能有多余逗号，Key 和端点都要用英文引号包住。改完保存，重启终端生效。用 CC Switch 的好处是它会帮你管理这份配置，切换模型时不用手动改文件。

3.3 初始化 CLAUDE.md

先创建全局配置目录：

mkdir $env:USERPROFILE\.claude -Force

再用记事本打开文件：

notepad $env:USERPROFILE\.claude\CLAUDE.md

粘贴下面这份模板，按自己情况改：

## 关于我 新手开发者，主要用 Claude Code 写 Python 脚本和学习代码。 ## 沟通风格 - 使用中文交流，代码和命令用英文 - 直接给答案，不要客套 - 我的想法有问题就直接指出 ## 红线（必须问我） - 删除任何文件或文件夹 - 修改 .env、密钥、token - 修改数据库结构 - git push、强制重置代码 - 安装全局依赖 ## 工程习惯 - 改动代码后自动运行测试或验证命令 - 不要把密钥、密码写进代码 - 大改动前先给方案确认

保存关闭。以后每次启动 Claude Code，这些规则自动生效。项目级 CLAUDE.md 可选，进入项目文件夹启动后直接说「请根据这个项目结构帮我生成一份 CLAUDE.md」，它会自动扫描创建。

3.4 在独立文件夹启动

不要在根目录启动。新建一个项目文件夹，比如D:\MyCode\project1，在文件夹地址栏输入powershell回车，或先开 PowerShell 再cd进去。然后执行：

claude

出现启动标识就成功了。如果不想每次点权限确认，可以用claude --dangerously-skip-permissions，但删除文件、改密钥这类高风险操作依然会询问，红线规则仍然生效。

4. 验证 Claude Code 连通性的第一次对话请求

配置完不验证，等于没配。这一节用一个最小任务确认整条链路通了。

在项目文件夹里启动 Claude Code 后，先输入一个简单指令，比如：

帮我创建一个 hello.py，打印当前时间，然后运行它

正常情况下，你会看到它先规划步骤，然后调用写文件能力生成hello.py，再执行python hello.py，最后把输出贴给你。这个过程说明三件事都通了：框架能读指令、模型端点能返回结果、本地能执行命令。

如果模型没连上，这一步会卡住或报错，常见的是 401 认证失败或连接超时。401 基本是 Key 填错或没启用配置；超时多半是 Base URL 写错或端点不可达。对照第 5 节排查。

再验证一下模型切换。在对话中输入：

/model

它会列出你所有已配置的模型，用方向键选择即可切换。切换后再跑一个小任务，确认新模型也能正常返回。这一步能帮你确认 CC Switch 的多配置管理是生效的。

还可以验证 CLAUDE.md 是否被读取。直接问：

你现在遵循哪些协作规则？

如果它能把你在 CLAUDE.md 里写的红线、沟通风格复述出来，说明全局配置已加载。没加载的话检查文件路径是否为%USERPROFILE%\.claude\CLAUDE.md，文件名大小写是否一致。

一个完整的成功结果长这样：你输入指令，它读文件、写代码、执行、返回结果，全程在项目文件夹内，不碰其他目录。跑通这个最小闭环后，你就可以把真实任务交给它了，比如「读一下这个项目的结构，告诉我入口文件在哪」或者「帮我把这个脚本里的硬编码路径改成参数」。

验证阶段别急着上复杂任务。先用 hello.py 这种无副作用的例子确认链路，再逐步加码。这样出问题时容易定位是配置问题还是任务本身的问题。

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

配置过程中最容易撞上的几类报错，这里逐个对照给解法。

401 认证失败。报错通常长这样：401 Unauthorized或invalid api key。原因有三：Key 复制时带了空格或换行；Key 已过期或被平台禁用；CC Switch 里配置没点「启用」。解法是重新复制 Key，确认没有首尾空白，在 CC Switch 主界面确认目标配置处于启用状态。如果手动改了 settings.json，检查ANTHROPIC_API_KEY的值是否被引号正确包裹。

local proxy failed / connection refused。这类报错说明请求根本没发出去，或者发到了错误地址。检查ANTHROPIC_BASE_URL是否写成了完整端点，末尾的/v1有没有漏。有些平台要求路径带版本号，有些不需要，以平台文档为准。另外确认没有残留的旧环境变量覆盖了新配置，可以在 PowerShell 里执行echo $env:ANTHROPIC_BASE_URL看当前生效值。

reading choices 相关报错。这通常出现在返回体解析阶段，说明端点返回的 JSON 结构不符合预期。多半是 Base URL 指向了不兼容的接口，或者 Model ID 填了一个该端点不支持的模型名。回到 CC Switch 核对三件套，Model ID 必须和平台文档里列出的完全一致，大小写敏感。

OAuth 相关报错。如果你看到提示要求登录或 OAuth 授权，说明 Claude Code 还在尝试走官方认证流程，没读到你的自定义配置。检查 settings.json 是否放在了正确路径%USERPROFILE%\.claude\settings.json，以及 CC Switch 是否真的把配置写进去了。用 CC Switch 管理时，切换配置后建议重启一次终端。

claude 命令找不到。这是 PATH 问题。关掉所有终端重开，让环境变量刷新。还不行就手动把 Claude Code 安装目录加到系统 PATH 里，或者直接用完整路径调用一次确认程序存在。

启动后扫描范围过大。如果你发现它开始分析一堆无关文件夹，说明你在根目录或用户主目录启动了。停掉，cd到具体项目文件夹再启动。这是上下文污染的典型表现，养成「一项目一文件夹」的习惯就能避免。

排查的通用顺序是：先确认命令能找到，再确认配置路径正确，再确认三件套填写无误，最后确认端点可达。按这个顺序走，大部分问题五分钟内能定位。

6. 把 Claude Code 用顺手的几个长期习惯

跑通第一个任务只是开始，真正省时间的是把工作流固定下来。

第一，每个项目独立文件夹，进去再启动。这条能避免九成的上下文污染问题，也让 CLAUDE.md 的项目级配置有地方放。

第二，全局 CLAUDE.md 一次写好，红线规则列清楚。删除文件、改密钥、git push 这些高风险操作必须让它先问你。这不是不信任 AI，是给自己留一道保险。

第三，模型随时可换，别绑死。CC Switch 里可以存多组配置，今天用这个模型，明天换更强的，点一下切换即可。Agent 框架不变，模型跟着需求走。

第四，验证习惯要保留。每次换模型或改配置后，用一个小任务确认链路通，再上真实项目。省这几分钟，可能省掉后面半小时的排查。

如果你想把 Claude Code 接到更完整的开发流程里，比如长期跑编码任务、管理多个 Agent 会话，可以了解一下 Coding Plan 这类方案，它针对持续性的编码场景做了优化。想先体验模型对话效果，可以直接在模型对话页面试。需要管理多组 Key 或查看用量，去控制台和 API Keys 页面操作。接入细节和参数说明，官方文档里有完整清单。

工具搭好之后，剩下的就是把它用进日常。从一个真实的小需求开始，比如让它帮你重构一个函数、补一段测试、解释一段看不懂的代码。用得越多，你越清楚哪些任务适合交给它，哪些还得自己来。这个边界感，才是效率提升的关键。