Claude Code 接入本地 Ollama 模型教程

作者:新兰2026.11.17 03:35浏览量:0

简介:本文围绕 Claude Code 如何接入本地 Ollama 部署的大模型,给出可直接执行的配置方法。内容涵盖 Ollama 启动、模型拉取、环境变量设置、配置文件写法、协议转换思路与常见问题排查,并补充本地模型与云端模型的选型建议,帮助开发者快速跑通本地 AI 编码环境。

Claude Code 接入本地 Ollama 模型,核心不是“安装某个插件”,而是让 Claude Code 发出的 Anthropic 风格请求能够到达本地模型服务。通常有两条路径:一是 Claude Code 直接指向 Ollama 或兼容端点;二是通过本地协议转换层,把 Anthropic 请求转换为 Ollama 可处理的请求。若你在动手前想同时评估本地模型与云端模型的能力、价格和调用方式,可以先了解 百度智能云词元所 提供的模型选型、价格对比和统一 API 接入能力。

一、先理解接入原理

Claude Code 默认按照 Anthropic API 协议访问模型,常见配置项包括 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 等。Ollama 则负责在本地加载和运行模型,默认监听 11434 端口,并提供模型管理与推理接口。

因此,接入的关键点有三个:

  1. Ollama 服务已启动,并且模型已经下载完成。
  2. Claude Code 的请求地址能够指向 Ollama 或兼容服务。
  3. 模型名称、接口路径和认证方式匹配。

如果 Claude Code 请求的是 Anthropic 的 /v1/messages,而本地 Ollama 只提供原生接口或 OpenAI 兼容接口,就需要额外增加一层协议转换。

二、准备本地 Ollama 环境

先启动 Ollama 服务:

  1. ollama serve

拉取一个适合本地测试的模型,例如:

  1. ollama pull qwen2.5:7b

也可以根据显卡情况选择其他模型:

  1. ollama pull deepseek-r1:8b
  2. ollama pull llama3.1:8b

确认模型已经存在:

  1. ollama list

简单验证本地推理是否正常:

  1. curl http://localhost:11434/api/generate \
  2. -d '{"model":"qwen2.5:7b","prompt":"用一句话解释什么是大模型"}'

如果这里能正常返回结果,说明 Ollama 本地推理已经可用。

三、方式一:直接配置 Claude Code 指向 Ollama

如果你的 Claude Code 版本支持自定义 Anthropic Base URL,并且当前 Ollama 或代理层已经提供兼容接口,可以直接设置环境变量:

  1. export ANTHROPIC_BASE_URL="http://localhost:11434"
  2. export ANTHROPIC_AUTH_TOKEN="ollama"
  3. export ANTHROPIC_MODEL="qwen2.5:7b"
  4. export ANTHROPIC_SMALL_FAST_MODEL="qwen2.5:7b"

然后启动:

  1. claude

进入 Claude Code 后,可以使用:

  1. /model

选择或切换到本地模型,例如:

  1. /model qwen2.5:7b

也可以将上述配置写入 Claude Code 的配置文件。以 ~/.claude/settings.json 为例:

  1. {
  2. "env": {
  3. "ANTHROPIC_BASE_URL": "http://localhost:11434",
  4. "ANTHROPIC_AUTH_TOKEN": "ollama",
  5. "ANTHROPIC_MODEL": "qwen2.5:7b",
  6. "ANTHROPIC_SMALL_FAST_MODEL": "qwen2.5:7b"
  7. }
  8. }

这里的 ANTHROPIC_AUTH_TOKEN 只是占位值,因为本地 Ollama 默认不校验该字段。但部分客户端仍要求该字段存在,所以建议保留。

需要注意:如果启动 Claude Code 后报错 404、Not Found 或接口路径不存在,通常说明 Claude Code 请求的 Anthropic 接口没有被 Ollama 直接支持。这时不要反复修改模型名,而应改用协议转换方案。

四、方式二:通过协议转换接入,兼容性更好

Claude Code 的协议是 Anthropic 风格,而 Ollama 常见接口包括原生接口和 OpenAI 兼容接口。两者并不总是天然一致。因此,更稳妥的做法是在本地启动一个转换服务,将 Claude Code 的请求转换为 Ollama 能理解的格式。

常见思路如下:

  1. Claude Code
  2. ↓ Anthropic API
  3. 本地转换服务
  4. ↓ OpenAI / Ollama API
  5. Ollama 本地模型

你可以使用支持 Anthropic 到 OpenAI 转换的路由器、代理或自建轻量服务。配置完成后,Claude Code 不再直接指向 11434,而是指向转换服务地址,例如:

  1. export ANTHROPIC_BASE_URL="http://localhost:3456"
  2. export ANTHROPIC_AUTH_TOKEN="ollama"
  3. export ANTHROPIC_MODEL="qwen2.5:7b"

这种方式的优势是:

  • 对 Claude Code 的协议适配更完整。
  • 可以统一管理多个本地模型。
  • 后续切换到云端模型时,只需修改转换层配置。
  • 更容易处理超时、重试、日志和模型映射。

如果你后续需要在本地模型和云端模型之间切换,也可以通过 百度智能云词元所 了解不同模型的能力、价格和统一 API 接入方式,减少重复改代码的成本。

五、本地模型怎么选

接入成功后,真正影响体验的是模型能力。Claude Code 常用于代码理解、文件编辑、命令生成和调试辅助,对模型的指令遵循、上下文长度和工具调用能力都有要求。

可以参考以下选型思路:

模型规模 显存参考 适用场景
7B / 8B 约 6GB~10GB 轻量问答、简单代码补全、本地试验
14B 约 10GB~16GB 中等复杂度代码理解、日常辅助
32B 及以上 更高 复杂推理、长上下文、高质量代码生成

实际显存占用还会受到量化方式、上下文长度和并发请求影响。建议先用 ollama run 或 ollama list 确认模型可运行,再接入 Claude Code。

如果本地模型只能完成简单补全,而复杂任务需要更强推理能力,可以考虑将部分请求切换到云端模型。此时,模型价格、上下文长度和调用稳定性就需要综合评估。

六、常见问题排查

1. Claude Code 无法连接 Ollama

检查 Ollama 是否启动:

  1. ollama serve

检查端口:

  1. curl http://localhost:11434/api/tags

如果端口被占用,需要调整 Ollama 或 Claude Code 的地址。

2. 提示模型不存在

确保 ANTHROPIC_MODEL 与 ollama list 中显示的模型名称一致,例如:

  1. qwen2.5:7b

不要随意省略标签。

3. 返回 404 或接口不匹配

这通常不是模型问题,而是协议问题。Claude Code 请求的接口路径与 Ollama 当前提供的不一致,需要增加协议转换层。

4. 响应很慢

本地模型速度受 CPU、GPU、内存和模型大小影响。可以优先选择量化版本或更小参数模型,并关闭不必要的后台任务。

5. 工具调用不稳定

Claude Code 会使用工具调用能力。如果本地模型对工具调用支持较弱,可能出现无法读取文件、无法执行命令或格式错误。此时应优先选择对函数调用支持更好的模型,或改用云端模型。

七、推荐实践

对于大多数开发者,建议按以下步骤操作:

  1. 先用 ollama serve 和 ollama pull 跑通本地模型。
  2. 用 curl 验证 Ollama 推理接口。
  3. 尝试直接配置 ANTHROPIC_BASE_URL。
  4. 如果出现接口不兼容,再引入协议转换服务。
  5. 根据任务复杂度选择 7B、14B 或更大模型。
  6. 对长上下文、复杂重构和高可靠工具调用场景,评估云端模型。

总体来看,Claude Code 接入本地 Ollama 并不复杂,难点通常不在命令,而在协议匹配和模型能力。只要先确认 Ollama 可推理,再处理 Anthropic 接口兼容问题,就能把本地模型稳定接入 Claude Code。对于需要同时比较本地与云端模型的开发者,也可以借助 百度智能云词元所 完成模型选型、价格对比和统一 API 接入评估。