# 本地模型接入 Claude Code 指南 目标将本地运行的 Qwen2.5-7B-Instruct通过 Ollama接入 Claude Code实现用本地模型替代 Anthropic 云端模型进行编程辅助。 前提条件已完成 Ollama 安装并成功运行 qwen2.5:7b 模型。---## 目录1. [原理说明](#一原理说明)2. [前置条件检查](#二前置条件检查)3. [方案一LiteLLM 代理推荐](#三方案一litellm-代理推荐)4. [方案二claude-code-router 路由器](#四方案二claude-code-router-路由器)5. [方案三直接环境变量最简单](#五方案三直接环境变量最简单)6. [配置 Claude Code 使用本地模型](#六配置-claude-code-使用本地模型)7. [验证与测试](#七验证与测试)8. [使用体验与局限说明](#八使用体验与局限说明)9. [常见问题排查](#九常见问题排查)10. [进阶多模型路由配置](#十进阶多模型路由配置)---## 一、原理说明### 1.1 为什么不能直接对接Claude Code → 只会说「Anthropic API 格式」Ollama → 只会说「OpenAI API 格式」需要中间一个「翻译」层Claude Code → 翻译代理 → Ollama(本地模型)### 1.2 API 格式差异| 特性 | Anthropic APIClaude Code 用的 | OpenAI APIOllama 提供的 || -------- | ---------------------------------- | ----------------------------- || 对话端点 | /v1/messages | /v1/chat/completions || 认证方式 | x-api-key 头 | Authorization: Bearer 头 || 消息格式 | messages system 独立字段 | messages 内含 system role || 流式格式 | event: content_block_delta | data: {choices: [...]} || 工具调用 | tool_use / tool_result | function / tool_calls |### 1.3 三种接入方案对比| 方案 | 原理 | 优点 | 缺点 | 推荐度 || ---------------------------- | --------------- | --------------------- | --------------------------- | ---------- || **LiteLLM** | Python 代理服务 | 成熟稳定、支持多模型 | 需装 Python 环境 | ★★★★★ || **claude-code-router** | Node.js 路由器 | 专为 Claude Code 设计 | 需 Node.js | ★★★★☆ || **环境变量直连** | 指向兼容端点 | 零依赖最简单 | 需要端点兼容 Anthropic 格式 | ★★★☆☆ |---## 二、前置条件检查### 2.1 确认 Ollama 正在运行cmd:: 检查 Ollama 服务curl http://localhost:11434/api/version:: 检查模型是否已下载ollama list确认输出包含 qwen2.5:7b。### 2.2 确认 OpenAI 兼容 API 可用cmdcurl http://localhost:11434/v1/chat/completions -H Content-Type: application/json -d {\model\:\qwen2.5:7b\,\messages\:[{\role\:\user\,\content\:\hi\}],\stream\:false}能收到正常回复说明 API 正常。### 2.3 确认 Claude Code 已安装cmdclaude --version如果未安装cmdnpm install -g anthropic-ai/claude-code---## 三、方案一LiteLLM 代理推荐LiteLLM 是一个成熟的 API 代理工具能将 Anthropic 格式的请求翻译成 OpenAI 格式发送给 Ollama。### 3.1 安装 LiteLLMcmdpip install litellm### 3.2 启动 LiteLLM 代理服务cmd:: 基础启动方式litellm --model ollama/qwen2.5:7b --port 4000### 3.3 进阶使用配置文件推荐创建配置文件 D:\Ollama\litellm_config.yamlyamlmodel_list:# 主对话模型 - 用于 Claude Code 的主要交互- model_name: claude-sonnet-4-20250514litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b# 备用模型槽位 - Claude Code 可能请求不同模型名- model_name: claude-haiku-4-20250414litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b- model_name: claude-3-5-sonnet-20241022litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b# 小模型槽位 - 用于快速任务- model_name: claude-3-5-haiku-20241022litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7blitellm_settings:# 支持流式输出stream: true# 超时设置秒request_timeout: 120# 重试次数num_retries: 2general_settings:master_key: sk-local-anykey使用配置文件启动cmdlitellm --config D:\Ollama\litellm_config.yaml --port 4000### 3.4 验证 LiteLLM 代理cmd:: 测试 Anthropic 格式的请求Claude Code 用的就是这种格式curl http://localhost:4000/v1/messages -H x-api-key: sk-local-anykey -H anthropic-version: 2023-06-01 -H Content-Type: application/json -d {\model\:\claude-sonnet-4-20250514\,\max_tokens\:256,\messages\:[{\role\:\user\,\content\:\你好\}]}收到中文回复说明代理工作正常。### 3.5 创建启动脚本创建 D:\Ollama\start_litellm.batbatecho offecho Starting LiteLLM Proxy...litellm --config D:\Ollama\litellm_config.yaml --port 4000pause以后双击即可启动。---## 四、方案二claude-code-router 路由器claude-code-router 是专为 Claude Code 设计的模型路由工具。### 4.1 安装cmdnpm install -g anthropic-ai/claude-code-router### 4.2 创建配置文件创建 D:\Ollama\ccr_config.jsonjson{Providers: [{name: ollama,api_base_url: http://localhost:11434/v1/chat/completions,api_key: ollama,models: [qwen2.5:7b],transforms: { ClaudeMessagesToOpenAI: true}}],Router: {default: ollama,qwen2.5:7b,background: ollama,qwen2.5:7b,think: ollama,qwen2.5:7b,longContext: ollama,qwen2.5:7b}}### 4.3 启动路由器cmdccr start### 4.4 通过路由器启动 Claude Codecmdccr code这会自动设置环境变量并启动 Claude Code所有请求将路由到本地 Ollama 模型。---## 五、方案三直接环境变量最简单### 5.1 原理Claude Code 支持通过环境变量 ANTHROPIC_BASE_URL 重定向 API 请求。但需要端点兼容 Anthropic API 格式所以仍需配合 LiteLLM 使用。### 5.2 配置如果已按方案一启动了 LiteLLM端口 4000只需设置环境变量**Windows 命令行临时**cmdset ANTHROPIC_BASE_URLhttp://localhost:4000set ANTHROPIC_API_KEYsk-local-anykeyclaude**PowerShell临时**powershell$env:ANTHROPIC_BASE_URL http://localhost:4000$env:ANTHROPIC_API_KEY sk-local-anykeyclaude**永久设置系统环境变量**cmdsetx ANTHROPIC_BASE_URL http://localhost:4000setx ANTHROPIC_API_KEY sk-local-anykey设置后重新打开终端直接运行 claude 即可使用本地模型。### 5.3 一键启动脚本创建 D:\Ollama\start_claude_local.batbatecho offecho echo Claude Code Local Model (Qwen2.5-7B)echo :: 检查 Ollama 是否运行curl -s http://localhost:11434/api/version nul 21if %errorlevel% neq 0 (echo [ERROR] Ollama is not running! Starting Ollama...start ollama servetimeout /t 3 /nobreak nul):: 检查 LiteLLM 是否运行curl -s http://localhost:4000/health nul 21if %errorlevel% neq 0 (echo [INFO] Starting LiteLLM proxy...start cmd /k litellm --config D:\Ollama\litellm_config.yaml --port 4000timeout /t 5 /nobreak nul):: 设置环境变量set ANTHROPIC_BASE_URLhttp://localhost:4000set ANTHROPIC_API_KEYsk-local-anykeyecho [OK] Environment configured.echo [OK] Starting Claude Code with local model...echo.claude以后双击此脚本即可一键启动。---## 六、配置 Claude Code 使用本地模型### 6.1 Claude Code 配置文件Claude Code 的配置文件位于%USERPROFILE%\.claude\settings.json创建或编辑此文件json{model: claude-sonnet-4-20250514,smallModel: claude-3-5-haiku-20241022,apiBaseUrl: http://localhost:4000,apiKey: sk-local-anykey} model 和 smallModel 的值对应 LiteLLM 配置中 model_name 的名字LiteLLM 会将其路由到本地 qwen2.5:7b。### 6.2 命令行参数方式也可以在启动时指定cmdclaude --model claude-sonnet-4-20250514 --base-url http://localhost:4000 --api-key sk-local-anykey### 6.3 三层架构总览┌─────────────┐ Anthropic API ┌─────────────┐ OpenAI API ┌─────────┐│ Claude Code │ ──── /v1/messages ───→ │ LiteLLM │ ── /v1/chat/completions ──→ │ Ollama ││ (CLI工具) │ 格式请求 │ (翻译代理) │ 格式请求 │ (本地模型) │└─────────────┘ └─────────────┘ └─────────┘│端口 4000 端口 11434---## 七、验证与测试### 7.1 基本对话测试启动 Claude Code确保 LiteLLM 和 Ollama 都在运行cmdclaude输入测试提示请用 Python 写一个快速排序函数如果收到正常的代码回复说明接入成功。### 7.2 检查请求路径在 LiteLLM 的控制台输出中应该能看到类似LiteLLM: API Call - Model: claude-sonnet-4-20250514→ Translating to Ollama format→ Sending to http://localhost:11434← Response received (xx tokens)### 7.3 检查模型是否实际被调用在另一个终端窗口运行cmdollama ps如果看到 qwen2.5:7b 正在运行且有活跃连接说明请求确实路由到了本地模型。### 7.4 运行编码任务测试读取当前目录下的 package.json 文件并解释依赖创建一个 hello.py 文件输出 hello world确认 Claude Code 的文件读写能力在本地模型下也能正常工作。---## 八、使用体验与局限说明### 8.1 能正常使用的功能| 功能 | 本地模型可行性 | 说明 || -------- | -------------- | ----------------------- || 代码生成 | ✅ 可以 | Qwen2.5-7B 代码能力很强 || 代码解释 | ✅ 可以 | 理解和解释代码没问题 || 代码修改 | ✅ 可以 | 能读写文件并修改 || 命令执行 | ✅ 可以 | 能运行命令行命令 || 中文对话 | ✅ 优秀 | Qwen2.5 中文能力最强 || 项目问答 | ✅ 可以 | 能读取和分析项目文件 |### 8.2 可能受限的功能| 功能 | 本地模型局限 | 说明 || ------------------- | ------------------- | ------------------------------ || 复杂多步推理 | ⚠️ 有时出错 | 7B 模型推理深度不如 Claude || 工具调用 (Tool Use) | ⚠️ 格式可能不兼容 | LiteLLM 翻译可能丢失部分字段 || 超长上下文 | ⚠️ 受限于显存 | 7B 模型上下文窗口 32K || 复杂 Agent 编排 | ⚠️ 能力有限 | 多步规划可能不如大模型稳定 || 代码质量 | ⚠️ 中等 | 复杂重构建议不如 Claude Sonnet || 响应速度 | ⚠️ 取决于硬件 | 本地推理 25-40 tokens/s |### 8.3 建议适合场景✅ 日常编程辅助写函数、解释代码、修 Bug✅ 离线/隐私敏感场景不发送数据到云端✅ 学习和实验✅ 简单的代码审查和重构不适合场景❌ 大型项目重构需要更强的推理能力❌ 复杂的多文件关联分析上下文窗口限制❌ 商业级生产环境7B 模型能力有限❌ 需要极高准确率的代码生成### 8.4 与 Claude 云端模型对比| 维度 | 本地 Qwen2.5-7B | Claude Sonnet云端 || -------- | ----------------- | --------------------- || 代码质量 | 7/10 | 9.5/10 || 中文能力 | 9/10 | 9/10 || 复杂推理 | 6/10 | 9/10 || 响应速度 | 25-40 tok/s | 50 tok/s || 隐私性 | 10/10完全本地 | 5/10数据上传 || 成本 | 免费 | API 费用 || 离线使用 | 可以 | 不可以 |---## 九、常见问题排查### 9.1 Claude Code 报错 Connection refused**原因**LiteLLM 代理未启动或端口不对。**解决**cmd:: 检查 LiteLLM 是否运行curl http://localhost:4000/health:: 如果没有响应启动 LiteLLMlitellm --config D:\Ollama\litellm_config.yaml --port 4000### 9.2 Claude Code 报错 Model not found**原因**LiteLLM 配置中的 model_name 与 Claude Code 请求的模型名不匹配。**解决**确认 LiteLLM 配置中包含 Claude Code 默认请求的模型名yamlmodel_list:- model_name: claude-sonnet-4-20250514 # ← 必须和这个名字完全一致litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b### 9.3 回复速度很慢**原因**可能模型加载到了 CPU 而非 GPU。**解决**cmd:: 检查模型运行状态ollama ps:: 如果显示 CPU说明显存不足:: 尝试使用更小的量化版本ollama pull qwen2.5:7b-instruct-q4_0### 9.4 回复内容被截断**原因**max_tokens 设置太小。**解决**在 LiteLLM 配置中添加默认参数yamlmodel_list:- model_name: claude-sonnet-4-20250514litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7bmodel_kwargs:max_tokens: 4096### 9.5 工具调用 / 文件操作不工作**原因**Anthropic 的 tool_use 格式与 OpenAI 的 function_calling 格式有差异LiteLLM 的翻译可能不完美。**解决**在 LiteLLM 配置中启用工具调用转换yamllitellm_settings:drop_params: truelangfuse_debug: true### 9.6 中文输出偶尔检查环境变量编码cmd:: 确保终端使用 UTF-8 编码chcp 65001### 9.7 Ollama 响应超时在 LiteLLM 配置中增加超时时间yamllitellm_settings:request_timeout: 300 # 5 分钟---## 十、进阶多模型路由配置### 10.1 混合使用本地 云端模型在实际使用中可以配置不同任务使用不同模型——简单任务用本地模型复杂任务用云端模型。修改 D:\Ollama\litellm_config.yamlyamlmodel_list:# 本地模型 # haiku 槽位 → 用本地小模型处理简单任务- model_name: claude-3-5-haiku-20241022litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b# 云端模型需要 API Key# sonnet 槽位 → 用 Claude Sonnet 处理复杂任务- model_name: claude-sonnet-4-20250514litellm_provider: anthropicapi_key: os.environ/ANTHROPIC_API_KEYmodel: claude-sonnet-4-20250514litellm_settings:stream: truerequest_timeout: 120这样 Claude Code 的简单任务如生成 commit message走本地模型复杂任务如代码重构走云端模型。### 10.2 使用多个本地模型如果在本地安装了多个模型yamlmodel_list:# 日常对话用 7B- model_name: claude-3-5-haiku-20241022litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b# 编程任务用 7B-Coder- model_name: claude-sonnet-4-20250514litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5-coder:7b# 长文本任务用更大的模型- model_name: claude-opus-4-20250514litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:14b### 10.3 负载均衡yamlmodel_list:# 同一个模型名映射到多个实例需多个 Ollama 实例- model_name: claude-sonnet-4-20250514litellm_provider: ollamaapi_base: http://localhost:11434model: qwen2.5:7b- model_name: claude-sonnet-4-20250514litellm_provider: ollamaapi_base: http://localhost:11435model: qwen2.5:7blitellm_settings:num_retries: 2routing_strategy: simple-shuffle # 轮询负载均衡---## 附录完整启动流程速查┌─────────────────────────────────────────────────────────┐│ 本地模型接入 Claude Code 全流程 │├─────────────────────────────────────────────────────────┤│ ││ 1. 启动 Ollama 服务 ││ ollama serve ││ ││ 2. 启动 LiteLLM 代理 ││ litellm --config D:\Ollama\litellm_config.yaml ││ ││ 3. 设置环境变量 ││ set ANTHROPIC_BASE_URLhttp://localhost:4000 ││ set ANTHROPIC_API_KEYsk-local-anykey ││ ││ 4. 启动 Claude Code ││ claude ││ ││ ───────────────────────────────────────────────────── ││ ││ 或者 一键启动 ││ 双击 D:\Ollama\start_claude_local.bat ││ │└─────────────────────────────────────────────────────────┘## 附录文件清单| 文件 | 位置 | 说明 || -------------------------- | -------------------------- | ----------------------------------- || litellm_config.yaml | D:\Ollama\ | LiteLLM 代理配置 || start_litellm.bat | D:\Ollama\ | LiteLLM 启动脚本 || start_claude_local.bat | D:\Ollama\ | Claude Code 一键启动脚本 || ccr_config.json | D:\Ollama\ | claude-code-router 配置方案二用 || settings.json | %USERPROFILE%\.claude\ | Claude Code 全局设置 |---## 总结三种接入方案按需选择方案一推荐Ollama LiteLLM Claude Code→ 最稳定、最灵活、支持多模型路由→ 适合长期使用方案二备选Ollama claude-code-router Claude Code→ 专为 Claude Code 设计、配置简单→ 适合快速上手方案三极简Ollama LiteLLM 环境变量→ 最少配置、一条命令启动→ 和方案一配合使用