Claude Code 接入 Ollama 本地模型 - 离线运行 Qwen / Llama 完整教程

把 Claude Code 接到本地模型上跑，是离 “完全自主可控” 最近的一种 AI 编码方式：claudecode 接入 ollama 之后，所有 prompt、所有代码都不出本机，API 账单清零，没网也能用。代价是要承担一部分能力下降——本地模型再强也打不过 Claude Sonnet，但日常 70% 的小任务足够了。

本文从硬件门槛讲到完整跑通，主走 Ollama + LiteLLM + Claude Code 这条最经济的路径。如果你是企业要做更大规模私有化，文末会提 vLLM 替代方案。完整的企业版部署看 Claude Code 私有化部署指南。

为什么把 Claude Code 接到本地

动机	说明
隐私	私有代码、未公开项目、商业机密项目
合规	金融、医疗、政企，数据不能出本机 / 不能出本地网络
离线	飞机上、出差弱网、内网开发
零 API 费	长期重度使用，电费比 API 费便宜
实验研究	微调自己的模型、研究新 base model

要诚实承认的限制：claude code 本地模型 在能力上有明显落差，Sub-agent 链路、复杂工具调用、超长上下文都会受影响。所以这套方案最适合”小修小补 + 隐私敏感”的人。

适合人群

读完下面这几条对号入座：

私有代码场景：公司禁止把代码发到外部 API，但希望保留 AI 辅助编码能力
离线 / 内网环境：科研院所、保密单位、网络隔离机房
个人折腾党：有 Mac M 系列芯片或 RTX 显卡，想薅本地算力
实验研究：研究 prompt engineering / 微调，需要快速试本地模型

不适合：

想”零成本完全替代 Sonnet 跑生产项目”——能力差距实打实
笔记本只有 8GB 内存——根本跑不动有用的模型
不愿意花时间调 Ollama 参数——本地模型配置远比云端 API 麻烦

硬件要求

本地跑大模型最大的成本是显存 / 统一内存。claudecode 本地大模型 想真正能干活，下面是一个能用的最低线参考：

模型档位	内存 / 显存最低	推荐配置	体感
7B-Q4	8GB	16GB	能跑，工具调用经常坏
14B-Q4	16GB	24GB	可用门槛，日常勉强
32B-Q4	32GB	48GB	体感接近 GLM-Air
70B-Q4	48GB	64GB+	接近 GLM-4.6

几条经验：

Mac M 系列芯片优势巨大：M2/M3/M4 系列的统一内存架构跑 LLM 比同等价位 PC + 显卡更划算，M3 Max 64GB 能跑 70B 量化模型
Windows / Linux 走 NVIDIA：至少 RTX 3090/4090（24GB），低于 12GB 显存就别碰 14B 以上
量化等级：Q4_K_M 是质量 / 体积平衡点，Q8 慢一倍但效果更好，Q2 速度极快但能力崩盘
CPU 跑也能跑：但 32B 模型 CPU 推理速度约 1-3 token/s，写一段代码要等几分钟，不实用

主流可用模型简评

不是所有 Ollama 模型都适合接 Claude Code——function calling / tool use 支持是硬要求。当前（截至本文撰写时）几个真正能用的：

模型	推荐版本	工具调用	中文	编码能力	备注
Qwen2.5-Coder	14B / 32B	良好	优秀	强	本地 Claude Code 首选
Llama 3.3	70B	良好	一般	良好	通用强，中文弱
DeepSeek-Coder-V2	16B / 236B	中等	良好	强（代码）	大版本只能云端
Codestral	22B	良好	一般	良好	Mistral 出品，英文场景
Qwen2.5	32B / 72B	良好	优秀	良好	通用版，非 Coder 专用

结论：本地跑 Claude Code，Qwen2.5-Coder 32B 是当前性价比最高的选择，14B 是低配兜底，70B-Llama 是英文重度用户的备选。下面用 Qwen2.5-Coder 演示。

第 1 步：安装 Ollama

macOS

brew install ollama
# 或者直接下载安装包：访问 ollama.com 下载 dmg

启动 Ollama 服务：

ollama serve

或者直接打开 Ollama 应用，托盘会自动起服务。

Linux

curl -fsSL https://ollama.com/install.sh | sh

服务会自动注册为 systemd 单元：

sudo systemctl start ollama
sudo systemctl enable ollama

Windows

去 ollama.com 下载 Windows 安装包，双击装好后 Ollama 会自动以服务形式启动。

验证安装

ollama --version
curl http://localhost:11434/api/tags

第二条返回 JSON（即使是空 models 数组）就说明 Ollama 服务跑起来了。

第 2 步：拉取模型

# 32B Coder 版本（推荐，需 32GB+ RAM）
ollama pull qwen2.5-coder:32b

# 14B 版本（16GB+ RAM 可用）
ollama pull qwen2.5-coder:14b

# 7B 版本（仅做最低验证，工具调用经常崩）
ollama pull qwen2.5-coder:7b

32B 模型约 20GB 下载量，国内网络可能需要小时级时间。可以并行下别的事。

验证模型可用：

ollama run qwen2.5-coder:32b "用 Python 写一个 fibonacci 函数"

能正常出代码就行。注意这一步是 Ollama 原生对话，还没经过 Claude Code。

第 3 步：理解协议差异

Ollama 提供两种 HTTP 接口：

原生 Ollama API：/api/generate、/api/chat，自定义格式
OpenAI 兼容 API：/v1/chat/completions，OpenAI Chat Completions 格式

Claude Code 客户端发出去的是 Anthropic Messages API 格式，三个东西彼此不兼容。所以要在中间塞一层协议转换器，最常用的就是 LiteLLM。

完整链路：

Claude Code (Anthropic Messages 协议)
     │
     ▼
LiteLLM 本地代理（监听 4000 端口）
     │  转换协议
     ▼
Ollama OpenAI 兼容接口（11434 端口）
     │
     ▼
Qwen2.5-Coder 模型推理

每一层都跑在 localhost，全程不出本机。

第 4 步：跑 LiteLLM 本地代理

安装 LiteLLM

python -m venv litellm-env
source litellm-env/bin/activate     # macOS / Linux
# Windows PowerShell:
# litellm-env\Scripts\Activate.ps1

pip install "litellm[proxy]"

写 litellm.yaml

新建 litellm.yaml：

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: ollama_chat/qwen2.5-coder:32b
      api_base: http://localhost:11434

  - model_name: claude-opus-4-7
    litellm_params:
      model: ollama_chat/qwen2.5-coder:32b
      api_base: http://localhost:11434

  - model_name: claude-haiku-4-5
    litellm_params:
      model: ollama_chat/qwen2.5-coder:14b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  request_timeout: 600
  num_retries: 1
  set_verbose: false

general_settings:
  master_key: sk-local-no-auth

几个要点：

用 ollama_chat/ 前缀，不要用 ollama/。ollama_chat 走 OpenAI 兼容路径，工具调用支持好得多；ollama/ 走原生 generate 接口，不支持 tool use
master_key 是本地代理的访问凭证，名字可以随便起，但 Claude Code 端必须填一样的值
request_timeout: 600 是必须的——本地推理 32B 大模型一次输出可能要几十秒到几分钟，默认 timeout 太短会被截断
不同 model_name 都映射到同一个 Ollama 模型，这样 Claude Code 切档位（Opus/Sonnet/Haiku）实际都走 Qwen

启动 LiteLLM

litellm --config litellm.yaml --port 4000

看到 LiteLLM Proxy initialized 算成功。

另开终端测试桥接：

curl -X POST http://localhost:4000/v1/messages \
  -H "x-api-key: sk-local-no-auth" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

返回 200 + Qwen 自报家门就说明 Anthropic 协议 → OpenAI 协议 → Ollama 的完整链路通了。

第 5 步：Claude Code 跳过认证

本地跑没真实 API key，claudecode 配置本地大模型跳过认证 的关键是给 Claude Code 一个”假”的 key——本地代理不校验它，但客户端要求 key 字段非空。

编辑 ~/.claude/settings.json（Windows 是 %USERPROFILE%\.claude\settings.json）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-local-no-auth"
  },
  "model": "claude-sonnet-4-6"
}

ANTHROPIC_AUTH_TOKEN 的值必须和 litellm.yaml 里 master_key 一致。如果你想让 LiteLLM 完全不校验，把 general_settings.master_key 那行删掉，但 Claude Code 端仍然要填一个非空字符串，比如 "sk-fake-key"。

也可以用环境变量：

# macOS / Linux
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=sk-local-no-auth

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
$env:ANTHROPIC_AUTH_TOKEN = "sk-local-no-auth"

启动：

claude --print "你是谁？哪家公司训练的？"

返回提到 “通义千问” / “Qwen” / “阿里” 就说明全链路通了。

上下文窗口（num_ctx）调优

这是本地跑大模型最容易踩的坑：Ollama 默认 num_ctx 只有 2048 token，远小于 Claude Code 实际工作需要的 32K-128K。表现是模型读两个文件就”忘了”前面的内容、工具调用半截卡住、多步骤任务彻底乱掉。

方法 1：用 Modelfile 永久放大

新建 Modelfile-qwen-big：

FROM qwen2.5-coder:32b
PARAMETER num_ctx 32768
PARAMETER num_predict 8192
PARAMETER temperature 0.3

然后：

ollama create qwen-coder-32b-big -f Modelfile-qwen-big

之后在 litellm.yaml 里把 model 改成 ollama_chat/qwen-coder-32b-big。

方法 2：通过 LiteLLM 传参

在 litellm.yaml 里：

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: ollama_chat/qwen2.5-coder:32b
      api_base: http://localhost:11434
      num_ctx: 32768

效果一样。

需要多大 num_ctx？

基础够用：8192，能读 2-3 个中等文件
正常使用：32768，能跑日常 Claude Code 工作流
大项目：65536+，但显存消耗指数级增长

每提升一档 num_ctx，显存占用大幅增加。32B 模型 + 32K 上下文，Mac M3 Max 64GB 单元能撑住，PC + 24GB 显卡可能会撑爆——降低量化等级（Q4 → Q5 反而省显存的反例）或者降低 num_ctx。

实测：Qwen2.5-Coder-32B 在 Claude Code 里的编辑能力

测试场景：约 80 个文件的 Python Flask 项目，让 Claude Code 完成三件事——

任务 A：写一个新 API

“在 app/api/users.py 里加一个 DELETE /users/<id> 接口，加 admin 权限校验。”

Qwen2.5-Coder-32B 表现：

正确读了现有路由风格
加了 @admin_required 装饰器（项目里有这个），不是自己造一个
一次写对，工具调用准确
处理速度：完整任务约 25 秒（M3 Max），同样任务 Sonnet 约 8 秒

评价：能用，慢但准。

任务 B：修一个 bug

“登录后偶尔返回 401，看看是不是 token 校验问题。”

Qwen2.5-Coder-32B 表现：

读了 6 个文件后说”需要更多信息”，要求查日志
给出了 3 个可能原因，但没直接定位根因
比 Sonnet / GLM 弱明显——后两者通常能直接找到问题

评价：复杂 bug 定位能力弱，需要人工辅助。

任务 C：跑测试

“运行 pytest，把失败的修了。”

Qwen2.5-Coder-32B 表现：

正确调用 Bash 工具
解析 pytest 输出找到 4 个失败用例
修复了 2 个，1 个改坏（原本能过的也挂了），1 个跳过
工具调用 11 次里有 1 次格式错（路径多了引号）

评价：基本工具调用 OK，但稳定性比云端 API 差。

综合实测结论

维度	Qwen2.5-Coder-32B 本地
单文件代码生成	良好
多文件理解	中等
复杂 Agent 任务	弱（不推荐）
工具调用稳定性	中等（90% 准确）
速度	慢，约 Sonnet 的 1/3 - 1/5
离线 / 隐私	完美

已知限制清单

1. 上下文窗口默认 2K 是大坑

Ollama 不在 Modelfile 里显式拉大 num_ctx，默认就是 2048。这个坑文档不写显眼，新手 90% 都会踩。表现是工具调用看似正常，但模型完全记不住前面对话。一定要用上面的 Modelfile 方法放大到至少 16K-32K。

2. Tool use 兼容性参差

Qwen2.5-Coder：良好，90% 工具调用准确
Llama 3.3：可用，偶尔格式错乱
DeepSeek-Coder-V2 16B：一般，调用频率高时会崩
任何 < 7B 模型：基本不能用，工具调用准确率 < 50%

LiteLLM 偶尔的版本 bug 会让工具调用退化，先升 LiteLLM 再排查模型问题：

pip install -U "litellm[proxy]"

3. Sub-agent 不稳定

Claude Code 的 sub-agent 工作流对工具调用准确性和长程一致性要求都很高，本地模型几乎都做不好。强烈建议不要在本地模型上跑复杂 sub-agent 工作流——任务越深，错误率指数级累积。

简单的”单层 sub-agent 调一次工具”还能跑，多层嵌套基本翻车。

4. 推理速度看硬件

硬件	32B 模型推理速度
Mac M3 Max 64GB	约 15-25 token/s
Mac M2 32GB	约 8-12 token/s
RTX 4090 24GB	约 30-50 token/s
RTX 3090 24GB	约 20-30 token/s
纯 CPU（Xeon）	约 2-5 token/s

Claude Code 在工具调用密集型工作流里，本地推理总耗时通常比云端慢 3-5 倍。心理预期要调好——本地是”私密性 / 离线 / 零账单”换”速度”。

5. 流式响应偶尔卡顿

Ollama 流式 → LiteLLM 翻译 → Claude Code 渲染，三层流式偶发 buffer 错位。表现是字符一坨一坨出现而不是流畅滚动。多数时候不影响功能，强迫症会难受。

6. 多模态不支持

Qwen2.5-Coder 是纯文本模型。Claude Code 的图片输入（截图分析、Mermaid 图等）功能完全失效。需要图像能力的话用 Qwen-VL 系列，但工具调用支持会更差。

适合 / 不适合的具体任务

适合本地模型的任务

单文件函数 / 类的实现
写单元测试
重命名 / 简单重构
加注释 / 生成文档
简单 bug 修复（一两个文件内）
代码补全 / 模板生成

不适合本地模型的任务

跨 10+ 文件的大型重构
复杂 bug 定位（需要长程推理）
Sub-agent 编排
架构设计建议
罕见技术栈（小众语言、新框架）
紧急 / 时间敏感任务（本地慢）

企业级延伸：vLLM 替代 Ollama

Ollama 优势是简单，缺点是单机性能、并发能力都弱。claudecode 私有化部署 到企业级，建议换 vLLM：

维度	Ollama	vLLM
安装难度	极简	需要 CUDA / 容器
并发支持	单用户	高并发
性能	一般	显著更高（PagedAttention）
OpenAI 兼容	是	是
模型生态	内置 registry	用 HuggingFace 模型
部署运维	极轻	需运维投入

vLLM 启动示例：

pip install vllm

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --port 8000 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9

LiteLLM 配置：

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: openai/Qwen/Qwen2.5-Coder-32B-Instruct
      api_base: http://your-vllm-server:8000/v1
      api_key: sk-anything

剩下流程和 Ollama 路径一样。企业内部多人共享一台 vLLM 服务器，多端 Claude Code 连同一个 LiteLLM 代理。

完整的企业部署架构看 Claude Code 私有化部署。

FAQ

claudecode 接入 ollama 本地模型哪个最强？

当前（截至本文撰写时）综合最强的是 Qwen2.5-Coder 32B，编码能力、工具调用、中文表达都在线。如果你能跑 70B，Llama 3.3 70B 通用能力更强但中文偏弱。别碰 7B 以下，工具调用基本崩。

跑不了 32B 怎么办？

降到 14B：qwen2.5-coder:14b，16GB 内存可用，能力下降但工具调用基本还在线。再低就 7B，但要做好”经常工具调用失败”的心理准备。

claudecode 配置本地大模型跳过认证的最简方案？

ANTHROPIC_AUTH_TOKEN 填一个非空字符串（任意值），ANTHROPIC_BASE_URL 指向本地 LiteLLM。LiteLLM 不配 master_key 时不校验任何 key。

必须用 LiteLLM 吗？能不能直接连 Ollama？

不能直接连。Claude Code 发的是 Anthropic Messages 格式，Ollama 接受的是 OpenAI 兼容格式或原生格式，必须有协议翻译层。LiteLLM 是开源、活跃、最成熟的选择。

本地跑能用 Sub-agent 吗？

简单 sub-agent 能跑，复杂多层调度极不稳定。重要工作流别用本地，留给 Claude Sonnet/Opus 兜底。

同时跑 Ollama 和 vLLM 行吗？

行。LiteLLM 的 model_list 可以同时配多个后端，按 model_name 路由。比如 claude-sonnet-4-6 走 Ollama，claude-opus-4-7 走 vLLM。

Claude Code 在本地模式下还能用 `/cost` 吗？

显示的数字毫无意义。本地推理零 API 费，但 Claude Code 不知道，它会按 Anthropic 定价表算一个虚假数字。直接忽略。

本地模型怎么升级到新版本？

ollama pull qwen2.5-coder:32b

会增量更新到最新 tag。但要注意每次升级后重新创建你的自定义 Modelfile（带 num_ctx 那个），否则上下文又退回 2K。

Mac M 系列真的比 PC 更适合本地跑吗？

单看跑大模型的性价比是的：M3 Max 64GB 一台机器能跑 70B-Q4 模型，PC 配同样能力需要 RTX 4090 双卡或者 A6000 级别，整机预算高得多。但 PC 在批量微调、分布式训练上仍有优势。个人本地 Claude Code 场景，Mac 是更省心的选择。

为什么把 Claude Code 接到本地

适合人群

硬件要求

主流可用模型简评

第 1 步：安装 Ollama

macOS

Linux

Windows

验证安装

第 2 步：拉取模型

第 3 步：理解协议差异

第 4 步：跑 LiteLLM 本地代理

安装 LiteLLM

写 litellm.yaml

启动 LiteLLM

第 5 步：Claude Code 跳过认证

上下文窗口（num_ctx）调优

方法 1：用 Modelfile 永久放大

方法 2：通过 LiteLLM 传参

需要多大 num_ctx？

实测：Qwen2.5-Coder-32B 在 Claude Code 里的编辑能力

任务 A：写一个新 API

任务 B：修一个 bug

任务 C：跑测试

综合实测结论

已知限制清单

1. 上下文窗口默认 2K 是大坑

2. Tool use 兼容性参差

3. Sub-agent 不稳定

4. 推理速度看硬件

5. 流式响应偶尔卡顿

6. 多模态不支持

适合 / 不适合的具体任务

适合本地模型的任务

不适合本地模型的任务

企业级延伸：vLLM 替代 Ollama

FAQ

claudecode 接入 ollama 本地模型 哪个最强？

跑不了 32B 怎么办？

claudecode 配置本地大模型 跳过认证 的最简方案？

必须用 LiteLLM 吗？能不能直接连 Ollama？

本地跑能用 Sub-agent 吗？

同时跑 Ollama 和 vLLM 行吗？

Claude Code 在本地模式下还能用 /cost 吗？

本地模型怎么升级到新版本？

Mac M 系列真的比 PC 更适合本地跑吗？

claudecode 接入 ollama 本地模型哪个最强？

claudecode 配置本地大模型跳过认证的最简方案？

Claude Code 在本地模式下还能用 `/cost` 吗？