企业官网建设流程全解析

# 本地模型接入 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 API（Claude Code 用的） | OpenAI API（Ollama 提供的） |
| -------- | ---------------------------------- | ----------------------------- |
| 对话端点 | `/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 可用

```cmd
curl 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 已安装

```cmd
claude --version
```

如果未安装：

```cmd
npm install -g @anthropic-ai/claude-code
```

---

## 三、方案一：LiteLLM 代理（推荐）

LiteLLM 是一个成熟的 API 代理工具，能将 Anthropic 格式的请求翻译成 OpenAI 格式发送给 Ollama。

### 3.1 安装 LiteLLM

```cmd
pip install litellm
```

### 3.2 启动 LiteLLM 代理服务

```cmd
:: 基础启动方式
litellm --model ollama/qwen2.5:7b --port 4000
```

### 3.3 进阶：使用配置文件（推荐）

创建配置文件 `D:\Ollama\litellm_config.yaml`：

```yaml
model_list:
# 主对话模型 - 用于 Claude Code 的主要交互
- model_name: claude-sonnet-4-20250514
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

# 备用模型槽位 - Claude Code 可能请求不同模型名
- model_name: claude-haiku-4-20250414
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

- model_name: claude-3-5-sonnet-20241022
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

# 小模型槽位 - 用于快速任务
- model_name: claude-3-5-haiku-20241022
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

litellm_settings:
# 支持流式输出
stream: true
# 超时设置（秒）
request_timeout: 120
# 重试次数
num_retries: 2

general_settings:
master_key: sk-local-anykey
```

使用配置文件启动：

```cmd
litellm --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.bat`：

```bat
@echo off
echo Starting LiteLLM Proxy...
litellm --config D:\Ollama\litellm_config.yaml --port 4000
pause
```

以后双击即可启动。

---

## 四、方案二：claude-code-router 路由器

claude-code-router 是专为 Claude Code 设计的模型路由工具。

### 4.1 安装

```cmd
npm install -g @anthropic-ai/claude-code-router
```

### 4.2 创建配置文件

创建 `D:\Ollama\ccr_config.json`：

```json
{
"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 启动路由器

```cmd
ccr start
```

### 4.4 通过路由器启动 Claude Code

```cmd
ccr code
```

这会自动设置环境变量并启动 Claude Code，所有请求将路由到本地 Ollama 模型。

---

## 五、方案三：直接环境变量（最简单）

### 5.1 原理

Claude Code 支持通过环境变量 `ANTHROPIC_BASE_URL` 重定向 API 请求。但需要端点兼容 Anthropic API 格式，所以仍需配合 LiteLLM 使用。

### 5.2 配置

如果已按方案一启动了 LiteLLM（端口 4000），只需设置环境变量：

**Windows 命令行（临时）**：

```cmd
set ANTHROPIC_BASE_URL=http://localhost:4000
set ANTHROPIC_API_KEY=sk-local-anykey
claude
```

**PowerShell（临时）**：

```powershell
$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
$env:ANTHROPIC_API_KEY = "sk-local-anykey"
claude
```

**永久设置（系统环境变量）**：

```cmd
setx ANTHROPIC_BASE_URL "http://localhost:4000"
setx ANTHROPIC_API_KEY "sk-local-anykey"
```

设置后重新打开终端，直接运行 `claude` 即可使用本地模型。

### 5.3 一键启动脚本

创建 `D:\Ollama\start_claude_local.bat`：

```bat
@echo off
echo ============================================
echo Claude Code + Local Model (Qwen2.5-7B)
echo ============================================

:: 检查 Ollama 是否运行
curl -s http://localhost:11434/api/version >nul 2>&1
if %errorlevel% neq 0 (
echo [ERROR] Ollama is not running! Starting Ollama...
start "" ollama serve
timeout /t 3 /nobreak >nul
)

:: 检查 LiteLLM 是否运行
curl -s http://localhost:4000/health >nul 2>&1
if %errorlevel% neq 0 (
echo [INFO] Starting LiteLLM proxy...
start "" cmd /k "litellm --config D:\Ollama\litellm_config.yaml --port 4000"
timeout /t 5 /nobreak >nul
)

:: 设置环境变量
set ANTHROPIC_BASE_URL=http://localhost:4000
set ANTHROPIC_API_KEY=sk-local-anykey

echo [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 命令行参数方式

也可以在启动时指定：

```cmd
claude --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 都在运行）：

```cmd
claude
```

输入测试提示：

```
请用 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 检查模型是否实际被调用

在另一个终端窗口运行：

```cmd
ollama 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

:: 如果没有响应，启动 LiteLLM
litellm --config D:\Ollama\litellm_config.yaml --port 4000
```

### 9.2 Claude Code 报错 "Model not found"

**原因**：LiteLLM 配置中的 `model_name` 与 Claude Code 请求的模型名不匹配。

**解决**：

确认 LiteLLM 配置中包含 Claude Code 默认请求的模型名：

```yaml
model_list:
- model_name: claude-sonnet-4-20250514 # ← 必须和这个名字完全一致
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b
```

### 9.3 回复速度很慢

**原因**：可能模型加载到了 CPU 而非 GPU。

**解决**：

```cmd
:: 检查模型运行状态
ollama ps

:: 如果显示 CPU，说明显存不足
:: 尝试使用更小的量化版本
ollama pull qwen2.5:7b-instruct-q4_0
```

### 9.4 回复内容被截断

**原因**：`max_tokens` 设置太小。

**解决**：

在 LiteLLM 配置中添加默认参数：

```yaml
model_list:
- model_name: claude-sonnet-4-20250514
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b
model_kwargs:
max_tokens: 4096
```

### 9.5 工具调用 / 文件操作不工作

**原因**：Anthropic 的 tool_use 格式与 OpenAI 的 function_calling 格式有差异，LiteLLM 的翻译可能不完美。

**解决**：

在 LiteLLM 配置中启用工具调用转换：

```yaml
litellm_settings:
drop_params: true
langfuse_debug: true
```

### 9.6 中文输出偶尔检查环境变量编码

```cmd
:: 确保终端使用 UTF-8 编码
chcp 65001
```

### 9.7 Ollama 响应超时

在 LiteLLM 配置中增加超时时间：

```yaml
litellm_settings:
request_timeout: 300 # 5 分钟
```

---

## 十、进阶：多模型路由配置

### 10.1 混合使用本地 + 云端模型

在实际使用中，可以配置不同任务使用不同模型——简单任务用本地模型，复杂任务用云端模型。

修改 `D:\Ollama\litellm_config.yaml`：

```yaml
model_list:
# ===== 本地模型 =====
# haiku 槽位 → 用本地小模型处理简单任务
- model_name: claude-3-5-haiku-20241022
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

# ===== 云端模型（需要 API Key）=====
# sonnet 槽位 → 用 Claude Sonnet 处理复杂任务
- model_name: claude-sonnet-4-20250514
litellm_provider: anthropic
api_key: os.environ/ANTHROPIC_API_KEY
model: claude-sonnet-4-20250514

litellm_settings:
stream: true
request_timeout: 120
```

这样 Claude Code 的简单任务（如生成 commit message）走本地模型，复杂任务（如代码重构）走云端模型。

### 10.2 使用多个本地模型

如果在本地安装了多个模型：

```yaml
model_list:
# 日常对话用 7B
- model_name: claude-3-5-haiku-20241022
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

# 编程任务用 7B-Coder
- model_name: claude-sonnet-4-20250514
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5-coder:7b

# 长文本任务用更大的模型
- model_name: claude-opus-4-20250514
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:14b
```

### 10.3 负载均衡

```yaml
model_list:
# 同一个模型名映射到多个实例（需多个 Ollama 实例）
- model_name: claude-sonnet-4-20250514
litellm_provider: ollama
api_base: http://localhost:11434
model: qwen2.5:7b

- model_name: claude-sonnet-4-20250514
litellm_provider: ollama
api_base: http://localhost:11435
model: qwen2.5:7b

litellm_settings:
num_retries: 2
routing_strategy: "simple-shuffle" # 轮询负载均衡
```

---

## 附录：完整启动流程速查

```
┌─────────────────────────────────────────────────────────┐
│ 本地模型接入 Claude Code 全流程 │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. 启动 Ollama 服务 │
│ ollama serve │
│ │
│ 2. 启动 LiteLLM 代理 │
│ litellm --config D:\Ollama\litellm_config.yaml │
│ │
│ 3. 设置环境变量 │
│ set ANTHROPIC_BASE_URL=http://localhost:4000 │
│ set ANTHROPIC_API_KEY=sk-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 + 环境变量
→ 最少配置、一条命令启动
→ 和方案一配合使用
```