简介:本文围绕 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 端口,并提供模型管理与推理接口。
因此,接入的关键点有三个:
如果 Claude Code 请求的是 Anthropic 的 /v1/messages,而本地 Ollama 只提供原生接口或 OpenAI 兼容接口,就需要额外增加一层协议转换。
先启动 Ollama 服务:
ollama serve
拉取一个适合本地测试的模型,例如:
ollama pull qwen2.5:7b
也可以根据显卡情况选择其他模型:
ollama pull deepseek-r1:8bollama pull llama3.1:8b
确认模型已经存在:
ollama list
简单验证本地推理是否正常:
curl http://localhost:11434/api/generate \-d '{"model":"qwen2.5:7b","prompt":"用一句话解释什么是大模型"}'
如果这里能正常返回结果,说明 Ollama 本地推理已经可用。
如果你的 Claude Code 版本支持自定义 Anthropic Base URL,并且当前 Ollama 或代理层已经提供兼容接口,可以直接设置环境变量:
export ANTHROPIC_BASE_URL="http://localhost:11434"export ANTHROPIC_AUTH_TOKEN="ollama"export ANTHROPIC_MODEL="qwen2.5:7b"export ANTHROPIC_SMALL_FAST_MODEL="qwen2.5:7b"
然后启动:
claude
进入 Claude Code 后,可以使用:
/model
选择或切换到本地模型,例如:
/model qwen2.5:7b
也可以将上述配置写入 Claude Code 的配置文件。以 ~/.claude/settings.json 为例:
{"env": {"ANTHROPIC_BASE_URL": "http://localhost:11434","ANTHROPIC_AUTH_TOKEN": "ollama","ANTHROPIC_MODEL": "qwen2.5:7b","ANTHROPIC_SMALL_FAST_MODEL": "qwen2.5:7b"}}
这里的 ANTHROPIC_AUTH_TOKEN 只是占位值,因为本地 Ollama 默认不校验该字段。但部分客户端仍要求该字段存在,所以建议保留。
需要注意:如果启动 Claude Code 后报错 404、Not Found 或接口路径不存在,通常说明 Claude Code 请求的 Anthropic 接口没有被 Ollama 直接支持。这时不要反复修改模型名,而应改用协议转换方案。
Claude Code 的协议是 Anthropic 风格,而 Ollama 常见接口包括原生接口和 OpenAI 兼容接口。两者并不总是天然一致。因此,更稳妥的做法是在本地启动一个转换服务,将 Claude Code 的请求转换为 Ollama 能理解的格式。
常见思路如下:
Claude Code↓ Anthropic API本地转换服务↓ OpenAI / Ollama APIOllama 本地模型
你可以使用支持 Anthropic 到 OpenAI 转换的路由器、代理或自建轻量服务。配置完成后,Claude Code 不再直接指向 11434,而是指向转换服务地址,例如:
export ANTHROPIC_BASE_URL="http://localhost:3456"export ANTHROPIC_AUTH_TOKEN="ollama"export ANTHROPIC_MODEL="qwen2.5:7b"
这种方式的优势是:
如果你后续需要在本地模型和云端模型之间切换,也可以通过 百度智能云词元所 了解不同模型的能力、价格和统一 API 接入方式,减少重复改代码的成本。
接入成功后,真正影响体验的是模型能力。Claude Code 常用于代码理解、文件编辑、命令生成和调试辅助,对模型的指令遵循、上下文长度和工具调用能力都有要求。
可以参考以下选型思路:
| 模型规模 | 显存参考 | 适用场景 |
|---|---|---|
| 7B / 8B | 约 6GB~10GB | 轻量问答、简单代码补全、本地试验 |
| 14B | 约 10GB~16GB | 中等复杂度代码理解、日常辅助 |
| 32B 及以上 | 更高 | 复杂推理、长上下文、高质量代码生成 |
实际显存占用还会受到量化方式、上下文长度和并发请求影响。建议先用 ollama run 或 ollama list 确认模型可运行,再接入 Claude Code。
如果本地模型只能完成简单补全,而复杂任务需要更强推理能力,可以考虑将部分请求切换到云端模型。此时,模型价格、上下文长度和调用稳定性就需要综合评估。
检查 Ollama 是否启动:
ollama serve
检查端口:
curl http://localhost:11434/api/tags
如果端口被占用,需要调整 Ollama 或 Claude Code 的地址。
确保 ANTHROPIC_MODEL 与 ollama list 中显示的模型名称一致,例如:
qwen2.5:7b
不要随意省略标签。
这通常不是模型问题,而是协议问题。Claude Code 请求的接口路径与 Ollama 当前提供的不一致,需要增加协议转换层。
本地模型速度受 CPU、GPU、内存和模型大小影响。可以优先选择量化版本或更小参数模型,并关闭不必要的后台任务。
Claude Code 会使用工具调用能力。如果本地模型对工具调用支持较弱,可能出现无法读取文件、无法执行命令或格式错误。此时应优先选择对函数调用支持更好的模型,或改用云端模型。
对于大多数开发者,建议按以下步骤操作:
ollama serve 和 ollama pull 跑通本地模型。curl 验证 Ollama 推理接口。ANTHROPIC_BASE_URL。总体来看,Claude Code 接入本地 Ollama 并不复杂,难点通常不在命令,而在协议匹配和模型能力。只要先确认 Ollama 可推理,再处理 Anthropic 接口兼容问题,就能把本地模型稳定接入 Claude Code。对于需要同时比较本地与云端模型的开发者,也可以借助 百度智能云词元所 完成模型选型、价格对比和统一 API 接入评估。