1. 为什么要在本地搭一套 AI 开发助手Claude Code 这类 Agent 框架真正好用的地方不是帮你补全一行代码而是能读整个项目目录、改文件、跑终端命令、根据报错自己迭代。我拿它重构过一个老 Node 项目它自己读 package.json、定位到某个依赖版本冲突、改完 lock 文件再跑一遍测试整个过程我只在关键节点点了几次确认。这种「项目感知 自主迭代」的能力和普通聊天式问答完全不是一个量级。但问题也很直接深度用起来官方 API 的调用量会迅速堆高。一次完整的 bug 修复循环可能触发十几次模型请求每个请求都带着项目上下文token 消耗非常可观。对于个人开发者或者想长期跑 Agent 工作流的人来说这笔成本很难忽略。于是就有了一个很自然的思路把「决策大脑」和「计算引擎」拆开。Claude Code 继续负责流程规划、工具调用、文件操作这些 Agent 逻辑底层推理换成本地跑的 Ollama 模型比如 Qwen、Deepseek、GLM 这些开源权重。这样整套系统可以完全跑在本地零 API 费用。不过这里有个现实问题Claude Code 默认只认 Anthropic 的接口格式而 Ollama 暴露的是 OpenAI 兼容的/v1/chat/completions。两者协议对不上直接连是连不通的。所以中间需要一层转发把 Claude Code 发出的请求翻译并路由到本地 Ollama 端点。CC Switch 就是干这个的中间件它让 Claude Code 以为自己在调官方接口实际请求全被重定向到127.0.0.1:11434。那 TaoToken 在这里扮演什么角色它提供统一的 Key 和 API 通道。当你不想完全依赖本地模型比如本地显存不够跑大参数模型或者需要在本地模型和云端模型之间灵活切换时TaoToken 的 API 通道可以作为统一入口配合 CC Switch 的配置切换让你在「纯本地零成本」和「本地云端混合」两种模式间自由切换。本文重点讲本地链路打通同时给出 TaoToken 接入的配置骨架方便你后续扩展。这套方案适合谁有独立显卡建议 8GB 显存起步、想长期跑 Agent 工作流、对数据隐私有要求、或者单纯想省 API 费用的开发者。下面从环境准备开始一步步把链路搭起来。2. 前置准备Ollama、Claude Code 与 CC Switch 安装配置先把三个核心组件装好。这一节的目标是让 Ollama 能跑起来、Claude Code 能启动、CC Switch 能拦截请求。2.1 Ollama 安装与模型拉取Ollama 是本地推理引擎负责实际跑模型。去官网下载对应系统的安装包Windows 和 macOS 都有图形化安装程序Linux 用一条命令curl -fsSL https://ollama.com/install.sh | sh装完后验证服务是否在跑ollama --version ollama listollama list如果返回空列表说明服务正常但还没拉模型。接下来根据你的显存选模型。8GB 显存建议跑 7B 量化版16GB 以上可以上 14B 或 32B# 7B 级别8GB 显存可跑 ollama pull qwen2.5-coder:7b # 14B 级别16GB 显存推荐 ollama pull deepseek-coder-v2:16b # 通用对话代码显存充足可选 ollama pull glm4:9b拉完后确认模型能正常推理ollama run qwen2.5-coder:7b 写一个 Python 快速排序能正常输出就说明本地推理链路通了。注意 Ollama 默认监听127.0.0.1:11434这个地址后面配置要用到。2.2 Claude Code 安装Claude Code 有桌面版和 CLI 版。桌面版去官网下载安装包CLI 版用 npm 装npm install -g anthropic-ai/claude-code装完先别急着配 Key因为我们要把它指向 CC Switch 的转发地址而不是官方端点。CLI 版启动命令是claude首次运行会引导你配置。2.3 CC Switch 安装CC Switch 是 API 转发层从它的 GitHub Release 页面下载对应平台的二进制文件。以 macOS 为例# 下载后赋予执行权限 chmod x cc-switch # 移动到 PATH sudo mv cc-switch /usr/local/bin/Windows 用户下载.exe直接双击运行即可。启动后它会监听一个本地端口默认 8080等待接收 Claude Code 的请求并转发。2.4 TaoToken 统一通道准备如果你打算后续接入云端模型做混合模式先去 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api-keys登录后在 API Keys 页面点创建复制生成的 Key 保存好。这个 Key 后面会写进配置文件作为云端通道的认证凭证。TaoToken 的 API 基础地址是https://taotoken.net/api兼容 OpenAI 的 Chat Completions 格式。这意味着 CC Switch 可以同时配置本地 Ollama 端点和 TaoToken 云端端点通过切换配置来决定请求走哪条路。三个组件装完后目录结构大致是这样Ollama 在后台跑推理服务CC Switch 在中间做协议转换和路由Claude Code 在最上层做 Agent 调度。下一节开始写具体配置。3. 可复制配置settings.json 与 CC Switch 骨架这一节是核心给出可以直接复制粘贴的配置文件。路径和字段名都按实际工具的要求来改完就能用。3.1 Claude Code 的 settings.jsonClaude Code 的配置文件在用户目录下。macOS/Linux 路径是~/.claude/settings.jsonWindows 是%USERPROFILE%\.claude\settings.json。如果目录不存在就手动创建。{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:8080, ANTHROPIC_API_KEY: sk-local-placeholder, ANTHROPIC_MODEL: qwen2.5-coder:7b, ANTHROPIC_SMALL_FAST_MODEL: qwen2.5-coder:7b }, permissions: { allow: [ Read, Write, Bash(git*), Bash(npm*) ] } }几个关键字段说明。ANTHROPIC_BASE_URL指向 CC Switch 的监听地址不是官方地址这样所有请求先到 CC Switch。ANTHROPIC_API_KEY填一个占位符就行因为本地 Ollama 不校验 Key但 Claude Code 的请求格式要求这个字段存在。ANTHROPIC_MODEL填你在 Ollama 里拉取的模型名必须完全一致。如果你要接入 TaoToken 云端通道把ANTHROPIC_BASE_URL改成https://taotoken.net/apiANTHROPIC_API_KEY换成真实的 TaoToken Key模型名换成云端支持的模型 ID。这就是统一通道的好处切换只改这几个字段。3.2 CC Switch 的 config.tomlCC Switch 的配置文件默认在~/.cc-switch/config.toml。它定义了两条转发规则一条指向本地 Ollama一条指向 TaoToken 云端。[server] listen 127.0.0.1:8080 log_level info [[providers]] name local-ollama base_url http://127.0.0.1:11434/v1 api_key ollama format openai models [qwen2.5-coder:7b, deepseek-coder-v2:16b, glm4:9b] [[providers]] name taotoken-cloud base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 format openai models [claude-sonnet-4-20250514, gpt-4o] [router] default local-ollama fallback taotoken-cloud[[providers]]定义了两个上游。local-ollama的base_url是 Ollama 的 OpenAI 兼容端点注意末尾的/v1不能少。format openai告诉 CC Switch 用 OpenAI 格式和上游通信它会自动把 Claude Code 发来的 Anthropic 格式转成 OpenAI 格式。[router]段设置默认走本地本地不可用时回退到 TaoToken 云端。这样即使 Ollama 服务挂了Agent 也不会直接报错中断。3.3 CC Switch 切换配置步骤CC Switch 支持多套配置快速切换。在它的配置目录下可以放多个 toml 文件比如local.toml和cloud.toml通过命令行参数指定加载哪个# 纯本地模式 cc-switch --config ~/.cc-switch/local.toml # 云端模式 cc-switch --config ~/.cc-switch/cloud.toml如果你用的是带图形界面的 CC Switch 版本在设置面板里可以直接选 provider切换后 Claude Code 不需要重启下一个请求就会走新通道。配置写完后先别启动 Claude Code用 curl 单独测一下 CC Switch 转发是否正常。下一节做连通性验证。4. 验证请求连通性测试与工具调用实测配置写完必须验证否则 Claude Code 报错时你分不清是配置问题还是模型问题。这一节从底层往上逐层测。4.1 直连 Ollama 验证先确认 Ollama 本身能响应 OpenAI 格式请求curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-coder:7b, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }正常返回的 JSON 里choices[0].message.content应该包含OK。如果这一步就失败检查 Ollama 服务是否在跑、模型名是否拼错。4.2 经 CC Switch 转发验证把请求打到 CC Switch 的端口验证协议转换是否生效curl http://127.0.0.1:8080/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-local-placeholder \ -H anthropic-version: 2023-06-01 \ -d { model: qwen2.5-coder:7b, max_tokens: 50, messages: [{role: user, content: 用一句话说明什么是递归}] }注意这里用的是 Anthropic 的/v1/messages端点和x-api-key头模拟 Claude Code 的真实请求格式。如果 CC Switch 配置正确它会把这个请求转成 OpenAI 格式发给 Ollama再把响应转回 Anthropic 格式。返回内容里能看到模型对递归的解释就说明转发链路通了。4.3 Claude Code 端到端验证启动 Claude Codeclaude进入交互界面后输入一个需要读文件的任务比如「读一下当前目录的 package.json告诉我项目用了哪些依赖」。观察它是否能正常调用 Read 工具、返回文件内容。这一步验证的是 Agent 的工具调用能力是否在本地模型上正常工作。实测下来7B 级别的模型在工具调用上偶尔会格式出错比如该输出 JSON 的时候输出了自然语言。如果遇到这种情况换 14B 以上的模型会稳定很多。Deepseek Coder V2 16B 在工具调用格式上表现明显好于 7B 模型。4.4 工具调用专项测试让 Claude Code 执行一个带终端命令的任务比如「在当前目录创建一个 test.txt 文件写入 hello然后用 cat 读出来」。这个任务会触发 Write 和 Bash 两个工具。如果它能正确完成说明本地模型支持多轮工具调用循环。成功的结果是文件被创建、内容正确、终端输出 hello。如果卡在某一步看 Claude Code 的日志输出通常会提示是模型返回格式不符合工具调用规范还是权限被拦截。5. 常见报错排查401、local proxy failed 与 OAuth 问题这一节列出实际搭建过程中最容易撞上的几个报错给出定位思路和修复方法。5.1 401 Unauthorized报错长这样API Error: 401 {type:error,error:{type:authentication_error,message:invalid x-api-key}}这个报错说明请求到了某个需要认证的端点但 Key 不对。分两种情况。如果你走的是本地 Ollama检查settings.json里的ANTHROPIC_API_KEY是否填了占位符Ollama 虽然不校验但字段不能为空。如果你走的是 TaoToken 云端检查 Key 是否复制完整、有没有多余空格以及ANTHROPIC_BASE_URL是否指向了https://taotoken.net/api。还有一种情况是 CC Switch 的config.toml里 provider 的api_key字段没填对。本地 provider 填ollama即可云端 provider 必须填真实的 TaoToken Key。5.2 local proxy failed / connection refused报错Error: connect ECONNREFUSED 127.0.0.1:8080这是 Claude Code 连不上 CC Switch。检查三件事CC Switch 进程是否在运行、监听端口是否和settings.json里的ANTHROPIC_BASE_URL一致、防火墙有没有拦截本地回环连接。用curl http://127.0.0.1:8080测一下端口是否可达。如果 CC Switch 在跑但端口不对改config.toml里的listen字段或者改settings.json里的地址两边保持一致。5.3 reading choices 解析错误报错Error: Cannot read properties of undefined (reading choices)这个报错说明 CC Switch 把上游响应转回 Anthropic 格式时没找到预期的choices字段。通常是上游返回了错误信息而不是正常响应但 CC Switch 没正确处理错误分支。排查方法直接 curl 上游端点看返回的原始 JSON 是什么。常见原因是模型名拼错Ollama 返回了model not found错误。还有一种可能是 Ollama 版本太老/v1/chat/completions端点行为不一致。升级到最新版 Ollama 通常能解决。5.4 OAuth 相关报错报错OAuth error: invalid_grantClaude Code 某些版本会尝试走 OAuth 流程做认证。如果你用的是 API Key 模式需要在配置里显式禁用 OAuth。在settings.json里加上{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:8080, ANTHROPIC_API_KEY: sk-local-placeholder, CLAUDE_CODE_DISABLE_OAUTH: 1 } }这个环境变量告诉 Claude Code 跳过 OAuth直接用 API Key 认证。如果你确实需要 OAuth比如用官方账号登录那就不能走本地转发链路两者是互斥的。5.5 模型返回格式不符合工具调用规范这个不算报错但表现为 Agent 卡住或反复重试。日志里会看到模型返回的 tool_use 块格式不对。解决办法有两个换更大的模型14B 以上或者在 CC Switch 配置里加一层响应修正。后者需要改 CC Switch 源码成本较高优先推荐换模型。排查时记住一个原则从下往上测。先 curl Ollama再 curl CC Switch最后跑 Claude Code。哪一层断了就修哪一层不要跳步。6. 长期使用建议与 TaoToken 通道扩展链路跑通后日常使用还有几个点值得注意。本地模型跑 Agent 工作流显存是硬约束。7B 模型在 8GB 显存上跑上下文一长就容易 OOM。建议在 Ollama 启动时限制上下文长度或者用OLLAMA_NUM_PARALLEL1减少并发。如果任务复杂、需要长上下文切到 TaoToken 云端通道更稳。混合模式是我比较推荐的用法日常简单任务走本地 Ollama零成本遇到需要强推理的复杂重构切到 TaoToken 云端通道调 Claude 或 GPT 系列。切换只需要改settings.json里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY或者用 CC Switch 的多配置切换。如果你要长期跑 Coding Agent 类工作流TaoToken 的 Coding Plan 提供了更稳定的调用配额适合高频使用场景。配置方式不变把 Base URL 指向https://taotoken.net/apiKey 换成 Coding Plan 对应的凭证即可。模型 ID 的填写要注意本地 Ollama 用你ollama pull时的完整名称比如qwen2.5-coder:7bTaoToken 云端用平台文档里列出的模型 ID。两边不要混填否则会报 model not found。最后提醒一点CC Switch 的配置文件里如果同时配了本地和云端 provider确保[router]的default指向你当前想用的那个。改完配置后重启 CC Switch 进程Claude Code 不用重启下一个请求就会走新路由。整套系统搭好后你可以把它当成一个完全可控的本地开发助手数据不出本机成本可控需要时再借云端算力补强。