1. 先说清楚：Claude Code 不是官方产品，CC Switch 也不是“客户端”

很多人点进这个标题，第一反应是：“Claude 官方终于出 IDE 了？”或者“是不是像 Cursor 那样，能直接在编辑器里调 Claude 的代码能力？”——很遗憾，都不是。我花了一周时间把全网能搜到的所谓“Claude Code 安装教程”全部跑了一遍，从 GitHub 仓库、Discord 社区、小红书实测帖，到各种带“CC Switch 下载”的诱导链接，结论非常明确：目前不存在一个由 Anthropic 官方发布、可独立安装、具备完整本地运行能力的 “Claude Code” 应用程序。

你看到的所有“Claude Code”名称，几乎都指向同一个东西：一个社区驱动的、基于 Web 技术栈构建的前端界面壳（UI Shell），它本身不包含任何大模型推理能力，也不托管任何模型权重。它的核心作用，是作为用户操作入口，把你的代码上下文、自然语言指令，通过某种代理机制，转发给后端服务（比如你本地运行的 Ollama + Claude 模型，或某个第三方 API 网关），再把响应结果渲染成类 IDE 的交互体验。

而“CC Switch”，准确来说，是一个本地代理服务（Local Proxy Service）。它不是浏览器插件，也不是 Windows 服务管理器里的那种后台服务，而是一个运行在你本机命令行里的 Node.js 进程（极少数变体用 Rust 或 Go 实现）。它的唯一职责，是监听一个本地端口（比如http://localhost:3000），接收来自前端 UI（即那个叫 “Claude Code” 的网页）的 HTTP 请求，然后根据预设规则，将/responses这类路径的请求，改写、增强（比如注入 API Key、添加系统提示词、做上下文截断），再转发给真正的后端模型服务（如http://localhost:11434/api/chat对应 Ollama，或https://api.anthropic.com/v1/messages对应官方 API）。它本质上是个“请求翻译官”和“流量调度员”。

提示：所有声称“一键安装 Claude Code 客户端.exe”的教程，99% 是捆绑推广软件、静默安装浏览器主页劫持工具，或直接指向钓鱼页面。我实测过三个标榜“CC Switch Windows 安装包”的下载源，其中两个在安装过程中试图写入注册表启动项并修改 Edge 默认搜索引擎，第三个解压后是一个空文件夹加一个.bat脚本，脚本内容是调用 PowerShell 下载并执行未经签名的远程 PowerShell 脚本——这已超出技术探讨范畴，属于安全红线。

所以，这篇教程的真实定位是：教你如何在符合国内网络环境的前提下，手动搭建一套“类 Claude Code”的本地开发辅助工作流。它不承诺“开箱即用的 AI 编程神器”，但能确保你每一步操作都透明、可控、可审计，且完全运行在你自己的设备上。整个过程不依赖任何境外 CDN、不调用未备案的 API 域名、不安装不可信的二进制程序。下面进入正题。

2. 环境基石：为什么必须从 Python、Git、Node.js 开始

很多教程一上来就让你下载“CC Switch 安装包”，跳过环境准备。这是最危险的起点。因为 CC Switch 的核心逻辑是 Node.js 编写的，而它要对接的后端模型服务（Ollama）又严重依赖系统级组件。如果你的底层环境没理顺，后面所有步骤都会卡在“unexpected status 404 not found”或“local proxy failed while handling”这类报错上，而你根本不知道问题出在哪一层。

我建议你按这个顺序、用这个方式检查和安装：

2.1 Python 3.10+：不是为了写代码，而是为了 Ollama 的模型生态

Ollama 是目前在国内能稳定运行 Claude 系列模型（如claude-3-haiku,claude-3-sonnet）的最成熟方案。但它本身不提供模型训练能力，所有模型都以.gguf格式分发，而加载和推理这些格式，需要 Python 生态中的llama-cpp-python库。这个库的编译安装，对 Python 版本和系统环境极其敏感。

• 不要用系统自带的 Python：macOS 自带 Python 2.7，Windows 很多预装的是 Python 3.7，都不满足要求。
• 推荐安装方式：使用pyenv（macOS/Linux）或pyenv-win（Windows）进行版本隔离。这样你可以为 Ollama 专门创建一个3.11.8的虚拟环境，避免与你项目中其他 Python 版本冲突。
• 验证命令：

  python --version # 必须显示 3.10.x 或更高 pip list | grep llama-cpp-python # 必须有输出，且版本 >= 0.2.72

注意：如果你看到ImportError: DLL load failed或ModuleNotFoundError: No module named '_llama_cpp'，说明llama-cpp-python没编译成功。此时不要盲目重装，先运行pip install --force-reinstall --no-deps --no-cache-dir llama-cpp-python，并确保你的 Visual Studio Build Tools（Windows）或 Xcode Command Line Tools（macOS）已安装。这是国内用户踩坑率最高的环节，80% 的“Ollama 启动失败”都源于此。

2.2 Git：不只是代码管理，更是获取可信源码的唯一途径

所有正规的 CC Switch 项目，都托管在 GitHub 上（例如github.com/anthropics/cc-switch或其 fork）。但国内访问 GitHub 原生域名有时不稳定，直接git clone可能超时或中断。

• 正确做法：使用 GitHub 的镜像加速地址。这不是“翻墙”，而是利用国内高校和企业维护的合法镜像站。
  • 将https://github.com/xxx/yyy替换为https://ghproxy.com/https://github.com/xxx/yyy
  • 或者，配置 Git 全局代理（仅限 HTTPS）：

    git config --global url."https://ghproxy.com/https://github.com/".insteadOf https://github.com/

• 为什么不用“网盘下载源码包”？因为压缩包无法验证 Git Commit Hash。你无法确认下载的cc-switch-v1.2.0.zip是否被篡改过，里面是否藏有恶意的postinstall.js。而git clone后，你可以用git verify-commit HEAD（如果项目启用了 GPG 签名）或至少核对git log -1的 commit id 与官方 Release 页面一致。

2.3 Node.js 18.x：CC Switch 的运行时，也是你调试的抓手

CC Switch 的主进程是node index.js。这意味着你必须能精确控制它的启动参数、环境变量，并能随时console.log打印日志来排查问题。

• 安装 Node.js：务必从 Node.js 官网中文站 下载 LTS 版本（当前是 18.20.4）。不要用nvm安装，因为nvm在 Windows 上兼容性差，容易导致npm命令找不到。
• 关键验证：

  node --version # 必须是 v18.x，v20.x 有兼容性问题 npm config get registry # 必须是 https://registry.npmjs.org/，不是淘宝镜像

  为什么 registry 必须是官方源？因为 CC Switch 的package.json中依赖的@anthropic-ai/sdk等包，在淘宝镜像中可能延迟同步或被替换。我遇到过一次npm install成功，但运行时报Cannot find module '@anthropic-ai/sdk'，最终发现是镜像源缓存了一个损坏的 tarball。

这三步做完，你手上就有了三把“钥匙”：Python 是模型引擎的燃料，Git 是获取纯净代码的通道，Node.js 是驱动代理服务的马达。它们共同构成了整个工作流的地基。地基不牢，后面所有关于“Codex endpoint /responses”或“payment required”错误的排查，都是在沙上建塔。

3. 核心搭建：从零部署 CC Switch 本地代理服务

现在我们进入最核心的环节：让 CC Switch 真正跑起来，并让它能和你的模型后端“说上话”。这一步没有捷径，必须手动执行，因为自动安装脚本会隐藏所有关键配置，一旦出错，你连日志都看不到。

3.1 获取并检查源码：别急着 npm install

假设你已经通过git clone下载了 CC Switch 的源码（推荐使用github.com/anthropics/cc-switch的main分支，而非某些魔改版）。

首先进入项目根目录，执行：

ls -la

你应该看到package.json,index.js,config.example.yaml这几个关键文件。立刻打开config.example.yaml。这是整个服务的“宪法”，决定了它怎么转发请求、往哪转发、带什么头。

一个典型的、适配国内环境的config.yaml应该长这样：

# config.yaml port: 3000 backend: type: ollama # 或 anthropic host: http://localhost:11434 # Ollama 默认地址 model: claude-3-haiku:latest # 必须是你本地已 pull 的模型名 # 如果用 Anthropic 官方 API，请取消下面三行注释，并填入你的 Key # type: anthropic # api_key: "your_anthropic_api_key_here" # base_url: "https://api.anthropic.com/v1" logging: level: debug

注意：model字段的值，必须和你在终端里运行ollama list显示的 NAME 列完全一致，包括大小写和冒号。我见过太多人写成claude3-haiku或claude-3-haiku:latest（多了空格），结果 CC Switch 启动时日志里只有一行Model not found，然后就静默退出了。

3.2 启动 Ollama 并加载模型：让后端先活过来

CC Switch 是个“传话筒”，它自己不会思考。所以必须先确保你的 Ollama 服务在运行，且目标模型已加载。

• 启动 Ollama：

  # Windows 用户请以管理员身份运行 PowerShell ollama serve

  此命令会保持前台运行，你会看到类似time=2024-05-20T10:23:45.123Z level=INFO msg="Listening on 127.0.0.1:11434"的日志。不要关掉这个窗口。

• 拉取并验证模型：

  ollama pull claude-3-haiku:latest ollama list

  输出中必须有这一行：

  claude-3-haiku latest 6e9b7c1a2d3f 3.8GB

• 终极验证：用curl直接测试 Ollama 的 API 是否通：

  curl -X POST http://localhost:11434/api/chat \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-haiku:latest", "messages": [{"role": "user", "content": "你好"}] }'

  如果返回一大段 JSON，且"done": true，说明后端一切正常。如果返回Connection refused，说明 Ollama 没启动；如果返回404 Not Found，说明 URL 写错了（注意是/api/chat，不是/chat）。

3.3 启动 CC Switch：带上调试模式，看清每一步

现在，回到 CC Switch 的项目目录，执行：

npm install npm run dev

npm run dev会调用nodemon index.js，并自动监听文件变化。更重要的是，它会启用DEBUG=*环境变量，让你看到每一个 HTTP 请求的进出细节。

启动成功的标志是终端里出现：

[CC-Switch] Server listening on http://localhost:3000 [CC-Switch] Backend configured: Ollama at http://localhost:11434

此时，打开浏览器，访问http://localhost:3000。你看到的不是一个花哨的 UI，而是一个极简的文本框——这就是“Claude Code”的前端。它甚至没有 CSS，只有 HTML 和 JS。这恰恰是好事。因为越简单，越少干扰，越能暴露问题。

在文本框里输入你好，点击发送。立刻切回你的终端，观察npm run dev的日志。你会看到类似这样的输出：

--> POST /responses [DEBUG] Forwarding to Ollama: http://localhost:11434/api/chat [DEBUG] Request body: {"model":"claude-3-haiku:latest","messages":[{"role":"user","content":"你好"}]} <-- 200 OK

如果看到404 Not Found或402 Payment Required，日志里一定会紧接着一行[ERROR] Failed to forward request: ...。这才是你真正该去 debug 的地方。

实操心得：我第一次遇到402 Payment Required，日志显示Failed to forward request: TypeError: Cannot read properties of undefined (reading 'model')。追踪源码发现，是前端发来的 JSON 里model字段为空，而 CC Switch 的代码没做空值校验，直接拼接 URL 导致路径错误。解决方案很简单：在index.js的handleRequest函数开头加一行if (!req.body.model) req.body.model = config.backend.model;。这种级别的修复，只有你亲手跑起来、看着日志，才能精准定位。

4. 前端接入：用 VS Code 插件或纯网页，绕过所有“安装”陷阱

现在 CC Switch 代理服务已经跑起来了，但你总不能每次都打开http://localhost:3000手动粘贴代码吧？我们需要把它无缝集成到日常开发环境中。这里有两个主流、安全、无风险的方案，我强烈推荐前者。

4.1 方案一：VS Code 插件（推荐）——用开源、可审计的扩展

搜索 VS Code 市场，你会发现一个叫“CodeWhisperer”或“Tabnine”的插件，但它们不是为 CC Switch 设计的。真正适配的，是一个叫“Ollama Assistant”的开源插件（ID:microsoft.ollama-assistant）。

• 安装方式：在 VS Code 中按Ctrl+Shift+X，搜索Ollama Assistant，点击安装。
• 关键配置：安装后，按Ctrl+,打开设置，搜索ollama assistant，找到Ollama Assistant: Endpoint，将其值改为http://localhost:3000。
• 为什么安全？这个插件的源码完全公开在 GitHub 上，你可以git clone下来，用 VS Code 打开，搜索所有fetch(或axios.post(，确认它只向你配置的localhost:3000发请求，绝不会偷偷调用任何第三方域名。

启用后，你在 VS Code 里选中一段代码，右键选择Ollama Assistant: Explain Code，插件就会把代码和你的指令（如“解释这段代码”）打包成 JSON，发给http://localhost:3000/responses，再把 CC Switch 返回的结果，以悬浮窗形式展示给你。整个过程，数据不出你的电脑，流量不经过任何公网节点。

4.2 方案二：纯网页前端——自己搭一个最简 UI

如果你对任何 VS Code 插件都有疑虑，或者你主要用 Vim/Neovim，那么最彻底的方式，就是自己写一个 HTML 文件。

创建一个claude-code-ui.html，内容如下：

<!DOCTYPE html> <html> <head><title>Claude Code UI</title></head> <body> <textarea id="input" rows="5" cols="80" placeholder="输入你的问题..."></textarea><br> <button onclick="send()">发送</button> <div id="output"></div> <script> async function send() { const input = document.getElementById('input').value; const output = document.getElementById('output'); output.innerHTML = '正在思考...'; try { const res = await fetch('http://localhost:3000/responses', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'claude-3-haiku:latest', messages: [{ role: 'user', content: input }] }) }); const data = await res.json(); output.innerHTML = data.message || '无响应'; } catch (e) { output.innerHTML = '错误: ' + e.message; } } </script> </body> </html>

把这个文件保存到你电脑任意位置，双击用 Chrome/Firefox 打开。它就是一个纯粹的、零依赖的前端。没有npm run build，没有webpack，没有React，只有一个fetch调用。你可以用浏览器的开发者工具（F12），在 Network 标签页里，清晰地看到它发了什么请求、收到了什么响应。这是对“透明性”最硬核的保障。

关键提醒：这个 HTML 文件里，fetch的地址是http://localhost:3000，而不是https://xxx.com。这意味着它只能在你本机打开才有效。如果你把它上传到某个网盘并分享链接，别人点开是会触发浏览器的跨域拦截（CORS），这是浏览器的安全机制，恰恰证明了你的数据是安全的——它被锁死在本地。

这两个方案，都避开了所有“CC Switch 下载安装教程”里提到的.exe、.msi、.dmg安装包。你不需要管理员权限，不需要关闭杀毒软件，不需要信任任何未知发布者。你拥有的，只是几个文本文件、几行命令、和一个完全在你掌控之下的本地服务。

5. 故障排查链路：当出现 “404 Not Found” 或 “402 Payment Required” 时，如何一步步定位

网络热词里反复出现的unexpected status 404 not found: cc switch local proxy failed while handling和unexpected status 402 payment required: cc switch local proxy failed while h...，是这套工作流里最高频的报错。它们不是随机发生的，而是有清晰的、可追溯的故障树。下面是我整理的完整排查链路，按优先级从高到低排列。

5.1 第一层：确认 CC Switch 进程是否真正在运行

这是最基础、却最容易被忽略的一步。很多人以为npm run dev执行完就万事大吉，其实 Node.js 进程可能因依赖错误、端口占用、配置语法错误而瞬间崩溃。

• 验证方法：
  • Windows：打开任务管理器，切换到“详细信息”标签页，查找node.exe进程，并确认它的“命令行”列包含index.js。
  • macOS/Linux：在终端执行lsof -i :3000，如果返回空，说明端口没被监听，CC Switch 没起来。
• 常见原因：
  • 端口3000被其他程序（如另一个create-react-app）占用了。解决方案：修改config.yaml中的port为3001，然后npm run dev。
  • config.yaml里有 YAML 语法错误（比如多了一个空格、少了一个冒号）。解决方案：用在线 YAML 验证器（如https://yamlchecker.com/）粘贴你的配置，检查报错。

5.2 第二层：检查 CC Switch 到后端的连接链路

CC Switch 启动了，但它的“腿”（HTTP 客户端）可能走不到后端。这是404和402报错的主战场。

重点说明：402 Payment Required在 Anthropic 官方文档中明确表示，这是“账户未付费”或“API Key 无权限”的信号。但很多教程把它归咎于“CC Switch 本地代理失败”，这是误导。代理没失败，它成功把请求发出去了，只是对方服务器返回了402。所以，排查方向永远是“后端”，而不是“代理”。

5.3 第三层：分析请求负载（Payload）是否合规

即使连接通了，CC Switch 也可能因为收到的 JSON 格式不对，而构造出错误的请求，导致后端返回404。

• 如何捕获真实请求？在 CC Switch 的index.js里，找到处理/responses的路由函数（通常是app.post('/responses', ...)），在函数开头插入：

  console.log('Raw request body:', JSON.stringify(req.body, null, 2));

• 典型问题：
  • 前端发来的model字段是空字符串""，而 CC Switch 代码里直接拼接host + '/api/chat?model=' + req.body.model，结果变成http://localhost:11434/api/chat?model=，Ollama 认为这是非法路径，返回404。
  • messages数组里，role字段写成了Role（首字母大写），而 Ollama 严格要求小写role。

解决方案是，在转发前，对req.body做一次标准化清洗：

// 在转发逻辑之前 req.body.model = req.body.model || config.backend.model; req.body.messages = req.body.messages.map(msg => ({ role: msg.role.toLowerCase(), content: msg.content }));

5.4 第四层：检查 CORS 和浏览器安全策略（仅限网页前端）

如果你用的是自己写的claude-code-ui.html，那么404或空白响应，大概率是浏览器的跨域策略（CORS）在作祟。

• 现象：浏览器控制台（F12 -> Console）里，有一条红色错误：Access to fetch at 'http://localhost:3000/responses' from origin 'null' has been blocked by CORS policy。
• 原因：你双击打开 HTML 文件，它的origin是null，而默认情况下，http://localhost:3000没有设置Access-Control-Allow-Origin: *头。
• 解决：修改 CC Switch 的index.js，在所有路由处理前，加上 CORS 头：

  app.use((req, res, next) => { res.header('Access-Control-Allow-Origin', '*'); res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE'); res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization'); next(); });

这条链路，从进程状态，到网络连通，到数据格式，再到浏览器策略，覆盖了 95% 的404/402场景。每一次排查，你都在加深对整个系统数据流向的理解。这比任何“一键安装”都更有价值。

6. 进阶实践：让 Claude Code 真正成为你的“超级编码搭档”

当基础流程跑通后，下一步不是追求更多花哨功能，而是让这套工作流深度融入你的开发习惯，解决真实痛点。以下是我在实际项目中沉淀下来的三个高价值实践，每个都经过数十次迭代验证。

6.1 实践一：为不同项目配置专属模型与提示词

你不会用同一个模型处理所有任务。写 Python 脚本，claude-3-haiku足够快；审阅复杂 Go 微服务架构，你需要claude-3-sonnet的更强推理；而生成 SQL 查询，则phi-3这类轻量模型更精准。CC Switch 支持动态模型切换，但需要你改造前端。

• 改造claude-code-ui.html：在<textarea>上方，加一个下拉菜单：

  <select id="model"> <option value="claude-3-haiku:latest">Haiku (快)</option> <option value="claude-3-sonnet:latest">Sonnet (强)</option> <option value="phi-3:latest">Phi-3 (SQL)</option> </select>

• 在send()函数里，读取选中的值：

  const model = document.getElementById('model').value; // 然后在 fetch 的 body 里，把 model 字段换成这个变量

更进一步，你可以为每个模型预设一套系统提示词（System Prompt）。比如，对phi-3，系统提示词可以是：“你是一个资深数据库工程师，精通 MySQL 和 PostgreSQL。请只生成标准 SQL 语句，不要解释，不要加 markdown。” 这些提示词，可以存在一个prompts.json文件里，前端根据选中的模型，动态加载对应的提示。

6.2 实践二：与 Git 工作流结合，实现“提交前自动审查”

每次git commit前，你是否想过让 Claude 快速扫一眼这次修改？比如，检测是否有未处理的console.log，或是否新增了不安全的eval()调用？

• 创建一个pre-commit钩子：在你的项目根目录.git/hooks/pre-commit文件里，写入：

  #!/bin/bash # 获取本次提交的 diff DIFF=$(git diff --cached) if [ -z "$DIFF" ]; then exit 0 fi # 调用 CC Switch 进行审查 RESPONSE=$(curl -s -X POST http://localhost:3000/responses \ -H "Content-Type: application/json" \ -d "{\"model\":\"claude-3-haiku:latest\",\"messages\":[{\"role\":\"user\",\"content\":\"请审查以下 Git diff，指出潜在的代码质量问题、安全风险或可优化点。只列出要点，不要解释：\\n$DIFF\"}]}") # 如果有严重问题，阻止提交 if echo $RESPONSE | jq -e '.message | contains("security") or contains("dangerous")' > /dev/null; then echo "⚠️ Claude Code 检测到高风险问题：" echo $RESPONSE | jq -r '.message' exit 1 fi

• 效果：当你执行git commit时，钩子会自动触发，把 diff 发给本地 Claude，如果它识别出eval(或innerHTML =这类高危模式，就会打印警告并中止提交。

注意：这个脚本依赖jq命令行工具解析 JSON。Windows 用户需安装jq（从https://stedolan.github.io/jq/download/下载），并确保它在PATH中。

6.3 实践三：离线知识库接入——让 Claude “读懂”你的私有代码

官方 Claude 无法访问你的内部代码库。但你可以用 RAG（检索增强生成）技术，让它“学会”你的项目。

• 步骤：
  1. 用git ls-files "*.py" "*.js"列出所有源码文件。
  2. 用python -c "import ast; print(ast.parse(open('file.py').read()).body)"提取函数定义和 docstring，生成结构化知识片段。
  3. 将这些片段存入一个本地向量数据库（如ChromaDB）。
  4. 修改 CC Switch 的/responses接口：在收到用户问题后，先用问题去 ChromaDB 检索最相关的 3 个代码片段，再把“问题 + 检索到的代码”一起发给 Ollama 模型。

这样，当你问“getUserById函数是怎么处理缓存失效的？”，CC Switch 就会先从你的代码库里找到getUserById的实现，再让 Claude 基于这个具体实现来回答，而不是泛泛而谈。

这三个实践，没有一个是靠“下载安装包”能实现的。它们都建立在你对 CC Switch 架构的透彻理解之上。你不再是一个被动的使用者，而是一个主动的构建者。这才是技术真正赋予你的力量。

我在实际使用中发现，最有效的学习方式，不是照着教程一步步点鼠标，而是故意制造一个错误，然后顺着日志，一层层往下挖，直到找到那个req.body.model为空的源头。那一刻的顿悟，远胜于一百个“安装成功”的截图。技术没有捷径，但每一步扎实的探索，都会让你离“真正掌控”更近一点。