Claude Code 接入本地 Ollama 模型教程
作者:梅琳marlin2026.11.17 03:29浏览量:0简介:本文讲解如何让 Claude Code 调用本地 Ollama 部署的开源模型,涵盖 Ollama 启动、模型拉取、Anthropic 兼容配置、连通性验证与常见问题排查,并介绍通过百度智能云词元所进行模型选型、价格对比和统一 API 接入的方法。
Claude Code 接入本地 Ollama 模型的核心,是把 Claude Code 的请求地址指向 Ollama 提供的 Anthropic Messages API 兼容端点。只要本地 Ollama 已加载模型,Claude Code 就可以像调用云端 Claude 一样调用本地开源模型。若你还在比较本地模型、云端模型和不同 API 接入方案,可以先了解 百度智能云词元所,它提供模型发现、价格与性能对比、统一 API 接入等能力,便于做选型和成本评估。
一、前置条件
Ollama 已安装并可运行
较新版本的 Ollama 可支持 Anthropic Messages API。若你计划用 Claude Code 直连本地模型,建议将 Ollama 升级到最新稳定版。已拉取至少一个本地模型
例如llama3、qwen或其他可在 Ollama 中运行的模型。已安装 Claude Code
确保 Claude Code 可以在终端中正常启动。
二、启动 Ollama 并准备模型
在终端中启动 Ollama 服务:
ollama serve
拉取一个模型,以 llama3 为例:
ollama pull llama3
启动模型进行简单测试:
ollama run llama3
查看当前已下载的模型:
ollama list
这些命令可以帮助你快速确认 Ollama 服务、模型文件和推理链路是否正常。如果你是在云平台或容器环境中部署 Ollama,也可以使用预置的 Ollama 镜像模板,并注意模型文件通常会存放在 OLLAMA_MODELS 指定的目录中,例如 /root/ollama/ollama_cache/models。
三、配置 Claude Code 指向 Ollama
在启动 Claude Code 之前,可以通过环境变量将请求地址指向本地 Ollama:
export ANTHROPIC_BASE_URL="http://127.0.0.1:11434"export ANTHROPIC_AUTH_TOKEN="ollama"export ANTHROPIC_MODEL="llama3"claude
各参数含义如下:
| 环境变量 | 作用 |
|---|---|
ANTHROPIC_BASE_URL |
Claude Code 请求的基础地址,通常填写 Ollama 服务根地址 |
ANTHROPIC_AUTH_TOKEN |
本地 Ollama 通常不校验真实密钥,可填写任意非空值 |
ANTHROPIC_MODEL |
指定要调用的模型名称,需要与 ollama list 中显示的一致 |
如果 Claude Code 需要配置轻量模型,也可以额外设置:
export ANTHROPIC_SMALL_FAST_MODEL="llama3"
如果你连接的是远程 Ollama 服务,可以把 127.0.0.1 替换为实际可访问的 IP 或域名,并确保网络、防火墙和鉴权策略允许访问。
四、验证 Ollama 接口是否正常
在配置 Claude Code 之前,建议先用 Ollama 原生 API 验证模型是否可以正常响应。例如使用生成接口:
curl http://127.0.0.1:11434/api/generate \-d '{"model":"llama3","prompt":"Why is the sky blue?","stream":false}'
也可以使用对话接口:
curl http://127.0.0.1:11434/api/chat \-d '{"model":"llama3","messages":[{"role":"user","content":"why is the sky blue?"}],"stream":false}'
这类 /api/generate 和 /api/chat 接口可以用于确认模型加载、推理服务和请求链路是否正常。如果 Ollama 原生接口都无法返回结果,Claude Code 通常也无法正常调用。
五、常见问题与排查
1. connection refused
可能原因:
- Ollama 服务未启动。
11434端口不可访问。- 远程服务器防火墙或安全组未放行。
解决方法:
ollama serve
并确认本地或远程端口可访问。
2. model not found
可能原因:
- 模型未下载。
ANTHROPIC_MODEL填写错误。- 模型名称大小写或版本不一致。
解决方法:
ollama list
然后确保 ANTHROPIC_MODEL 与列表中的模型名称一致。
3. 404 Not Found
可能原因:
ANTHROPIC_BASE_URL填写错误。- 误把
/v1、/api等路径直接写进基础地址。
建议:
export ANTHROPIC_BASE_URL="http://127.0.0.1:11434"
通常填写服务根地址即可,由客户端自动拼接具体接口路径。
4. 鉴权失败
如果本地 Ollama 出现鉴权问题,可以尝试设置一个非空的 ANTHROPIC_AUTH_TOKEN:
export ANTHROPIC_AUTH_TOKEN="ollama"
如果连接的是远程服务或网关,则需要确认网关是否要求真实 API Key。
5. 响应慢或上下文截断
可能原因:
- 模型参数量较大。
- 显存或内存不足。
- 上下文过长。
- 模型量化版本不适合当前硬件。
可以尝试:
- 使用更小的模型。
- 降低上下文长度。
- 选择量化版本更合适的模型。
- 检查 GPU 或 CPU 资源占用情况。
6. 工具调用不稳定
Claude Code 类工具通常会涉及文件读取、命令执行、代码修改等 Agent 能力,这对模型的指令跟随和工具调用能力要求较高。并非所有开源模型都能稳定完成复杂工具调用。
建议优先测试模型在以下方面的表现:
- 代码理解能力。
- 长上下文处理能力。
- 指令跟随能力。
- 工具调用稳定性。
- 多轮对话一致性。
六、从本地 Ollama 到多模型接入
本地 Ollama 适合隐私敏感、低延迟、离线实验和本地开发场景。但在实际项目中,团队往往还需要比较云端模型、开源模型和不同 API 的调用成本。此时可以通过 百度智能云词元所 了解不同模型的能力、价格和接入方式,减少多模型集成时的选型成本。
如果你后续需要统一管理多个模型服务,统一 API 接入和调用管理能力也能降低开发与运维复杂度。尤其是在同时使用本地模型、云端模型和第三方模型时,统一接入层可以帮助团队减少重复适配工作。
七、最佳实践建议
- 先用
ollama run验证模型本身可用,再配置 Claude Code。 - 固定模型名称和版本,避免环境切换后调用失败。
- 对远程 Ollama 服务启用鉴权、内网访问或反向代理,避免直接暴露公网。
- 如果 Claude Code 主要用于代码生成,应重点测试模型的代码理解、长上下文和工具调用能力。
- 在正式接入业务前,建议对模型效果、响应速度和调用成本进行综合评估,可借助 词元所模型服务 做进一步比较。

登录后可评论,请前往 登录 或 注册