本文指南旨在阐述一个革命性的本地化、零成本、高可控的AI开发助手系统。我们结合了功能强大的 Claude Code Agent 框架（负责复杂的流程规划和决策逻辑）与本地化、经济高效的 Ollama 模型（提供底层计算能力），从而实现一个完全免费运行的AI开发助手，彻底绕开了昂贵的外部商业API费用。
💡 核心概念与解决的问题（Core Concept & Problem Solved）
【原始痛点 Analysis】
Claude Code 是一个能力强大的 Agent 框架，它远超一般的聊天机器人。它的核心能力包括：阅读整个项目结构、修改文件内容、执行终端命令、自动修复代码 Bug 等，这些能力在软件开发工作流中具有革命性意义。然而，使用其官方的 Claude API 进行深度、多次迭代的开发工作流时，其费用成本是难以承受的"沉没成本"。
【我们的解决方案 Solution】
本项目提出了一种优雅的解决方案：
- 使用 Ollama 实现本地化执行： 将本地的开源 LLM（如 Qwen, Gemma, Deepseek 等）作为核心"大脑"。
- 引入 CC Switch 作为 API 转发层 (API Forwarding Layer)： 这是一个关键的中间件（Bridge）。它让 Claude Code 误以为它正在调用官方的 Claude API，但实际上，所有的 API 请求都会被透明地、秘密地路由和重定向到本地运行的 Ollama 服务端点。
核心理念： 解耦 AI 的"决策大脑"与"计算引擎"的物理分离。
🚀 Agent 的本质区别（The "Agent" Difference）
理解 Agent 与传统 AI 的区别至关重要：
- 传统 AI (Simple Q&A)： 仅停留在问答、文本生成层面，缺乏主动性和行动力。
- Claude Code Agent (Full Development Cycle)： 真正执行一个完整的、模拟开发人员的生命周期。它具备以下能力：
- 项目感知： 能够读取和消化整个项目目录结构（如
src/、components/、package.json等）。 - 自主迭代： 分析代码缺陷、自动修改文件、执行依赖安装命令、并迭代修复 Bug。
- 项目感知： 能够读取和消化整个项目目录结构（如
结论： 这个过程不是一次简单的聊天；它是一个集 AI 智能决策 + 交互式开发环境 (IDE) + 终端操作 (Terminal) 于一体的自动化开发循环。
🛠️ 本地化部署分步指南（Step-by-Step Local Deployment Guide）
目标：实现 100% 免费的本地部署。
1. 前置条件 (Prerequisites)
- Git: 确保本地已安装 Git 版本控制工具。
2. 核心工具下载与配置 (Core Tools Acquisition)
| 工具名称 | 作用 (Purpose) | 关键用途与注意事项 (Notes) |
|---|---|---|
| Claude Code Desktop | 主 Agent 界面。 负责提供用户交互的图形化界面，作为整个开发工作流的控制前端。 | https://claude.com/download |
| Ollama Client | 本地 LLM 计算引擎。 负责运行所有本地的、开源的大语言模型 (如 Qwen, Gemma, Deepseek R1, GLM)。所有推理计算在此完成。 | https://ollama.com/ |
| CC Switch | 关键的 API 转发中间件 (The Bridge)。 这是实现整个"骗局"的核心，负责拦截和重定向 API 请求。 | https://github.com/farion1231/cc-switch |
3. 本地模型推荐 (Ollama Model Recommendations)
模型选择应基于本地设备的 GPU VRAM 资源：
- 首选模型： Qwen 3.6/3.5、Gemma4、Deepseek R1、GLM 等。
- 建议： 选择与本地硬件资源兼容性最好的模型版本。
4. CC Switch 配置详解 (Configuration Details)
这是连接线上 Agent 和本地模型的"网络协议"：
- 请求地址 (Request Address): 必须设置为
http://127.0.0.1:11434/v1。 - API 格式 (API Format): 必须遵循 OpenAI Chat Completions 的标准模式，以确保 Claude Code 能够识别请求格式。
- 认证字段 (Authentication Field): 前端配置中可能会需要一个 Key 占位符，即使不用于认证，也应设置
ANTHROPIC_API_KEY以满足格式要求。
5. Claude Code 注册表注入（最关键步骤）
为了确保本地模型的使用不会被 Agent 的界面逻辑所忽略，必须修改 Claude Code 的自定义配置文件：
原配置示例：
"inferenceModels"="[\"haiku\",\"sonnet\",\"opus\"]"
修改目标：
"inferenceModels"="[\"haiku\",\"sonnet\",\"opus\"]"
(在实际操作中，需确保此处能兼容本地模型的显示或模拟显示)
🧠 技术深入解析：转发机制 (Technical Deep Dive: The Forwarding Mechanism)
- 拦截 (Interception): Claude Code Agent 发送所有 API 请求（它认为发送给 Claude API）。
- 重定向 (Redirection): CC Switch 代理层拦截了这个请求的全部内容。
- 转发 (Forwarding): CC Switch 识别出目标是开发流程，并将其透明地、无缝地重定向到本地的 Ollama API 端点 (
http://127.0.0.1:11434/v1)。 - 结果： Claude Code 永远不知道自己在与本地 Ollama 引擎对话，它只接收到了一个格式完美，且符合预期的"Claude 高级 API"的回复。
通过这套架构，开发者即可拥有一个完全免费、功能媲美付费版本的本地AI开发助手。