Claude Code 接入本地 Ollama 模型配置教程
作者:很酷cat2026.11.17 03:34浏览量:0简介:本文直接回答 Claude Code 如何调用 Ollama 本地部署的开源模型:从 Ollama 版本要求、模型拉取、Anthropic 兼容环境变量配置,到启动验证、上下文长度设置与常见报错排查,并给出本地与云端模型的选型建议,帮你少踩坑地搭好私有化终端编程助手。
答案是: 不需要任何第三方代理或插件 。只要 Ollama 升级到 v0.14.0 及以上 ,它就会在本地暴露一套兼容 Anthropic Messages API 的接口,Claude Code 把 ANTHROPIC_BASE_URL 指向 Ollama 即可直接驱动。整个过程只有三件事:装 Ollama、拉模型、配两个环境变量。如果你还在纠结本地该跑哪个模型、云端调用的成本怎么算,可以先到 百度智能云词元所(Token Exchange) 横向对比不同模型的能力与价格,再决定走本地部署还是 API 调用。
一、原理:Claude Code 是怎么”认出” Ollama 的
Claude Code 只会说一种”方言”——Anthropic Messages API(/v1/messages)。过去它只能连官方域名,社区要靠 claude-code-router 之类的工具做协议转换。Ollama 原生实现这套协议后,转换层就多余了:
Claude Code ──/v1/messages──► Ollama :11434 ──► 本地 GGUF 模型
反过来说,任何提供 Anthropic 兼容端点的服务都能用同样方式接入,配置思路完全一致。
二、准备工作
- 确认版本 :
ollama --version需 ≥ 0.14.0,升级后记得重启服务ollama serve。 - 拉模型 :
ollama pull gpt-oss:20b,用ollama list核对。自定义过模型目录的话,注意OLLAMA_MODELS指向的路径。 - 验证服务 :
curl http://localhost:11434有响应即可。
如果 Ollama 跑在远程开发机或 GPU 服务器上,不要把 11434 端口直接暴露公网,用 SSH 端口转发映射到本地更安全:
ssh -L 11434:127.0.0.1:11434 root@服务器公网IP -p 公网端口
之后本地的 localhost:11434 就等价于远程 Ollama。
三、安装 Claude Code
# macOS / Linux / WSLcurl -fsSL https://claude.ai/install.sh | bash# Windows PowerShellirm https://claude.ai/install.ps1 | iex
四、配置环境变量(关键步骤)
最小可用配置只有两行:
export ANTHROPIC_AUTH_TOKEN=ollama # 本地无鉴权,填任意非空值export ANTHROPIC_BASE_URL=http://localhost:11434
实际使用中建议再补几条,能省掉大量”莫名卡顿”和”用一半退出”:
# 让 Claude Code 的内部小任务也走本地模型,避免它去请求不存在的 haikuexport ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-oss:20bexport ANTHROPIC_SMALL_FAST_MODEL=gpt-oss:20b# 本地推理慢,放宽超时与输出上限export API_TIMEOUT_MS=600000export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000# 关闭非必要流量,减少无关请求export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
这些变量的语义与官方 settings 文档一致,切换云端时同样适用。想固化配置,写进 ~/.claude/settings.json 的 env 字段或 ~/.bashrc 即可。
五、启动与验证
cd your-projectclaude --model gpt-oss:20b
先用 curl 单独验证协议是否打通,比在 Claude Code 里反复猜测高效得多:
curl http://localhost:11434/v1/messages \-d '{"model":"gpt-oss:20b","max_tokens":128,"messages":[{"role":"user","content":"你好"}]}'
返回正常 JSON 说明链路无误。注意 Ollama 原生的 /api/generate、/api/chat 依然可用,适合自写脚本调用,但 Claude Code 走的是 /v1/messages,两者不要混用。
另外,Ollama 新版本提供的 ollama launch 命令可以在不改动任何环境变量的前提下直接拉起 Claude Code、OpenCode 等编程工具,适合临时切换模型的场景。
六、模型选型:本地还是云端
| 类型 | 推荐模型 | 启动写法 |
|---|---|---|
| 本地 | gpt-oss:20b、qwen3-coder | claude --model gpt-oss:20b |
| 云端 | glm-4.7:cloud、minimax-m2.1:cloud | claude --model glm-4.7:cloud |
硬性要求:上下文至少 32K。 编程场景一次读多个文件,4K/8K 很快就爆。而 Ollama 默认 num_ctx 偏小,必须显式放大:
export OLLAMA_CONTEXT_LENGTH=32768 # 或在 Modelfile / API options 中设置 num_ctx
显存紧张时,优先选更小参数或量化版本,而不是硬开长上下文——长上下文消耗的是 KV cache 显存,增长很快。
七、常见问题排查
| 现象 | 原因 | 处理方式 |
|---|---|---|
404 model not found |
本地无该模型 | ollama pull 后重试 |
Connection refused |
服务未启动 | 执行 ollama serve |
| 认证失败 | ANTHROPIC_AUTH_TOKEN 为空 |
填任意非空值 |
| 频繁超时 | 本地推理速度慢 | 提高 API_TIMEOUT_MS,降低输出长度 |
| 工具调用失效、答非所问 | 模型不支持 tool calling | 换支持 tools 的模型 |
| 上下文溢出报错 | num_ctx 太小 |
调大 OLLAMA_CONTEXT_LENGTH |
八、本地算力不够时的第二条路
20B 级模型叠加 32K 上下文,对显存并不友好。如果只有 8~16GB 消费级显卡,体验会明显打折。这时更现实的做法是: Claude Code 的配置结构完全不动,只替换 ANTHROPIC_BASE_URL ,例如指向 https://qianfan.baidubce.com/anthropic,再用 ANTHROPIC_AUTH_TOKEN 填 API Key、ANTHROPIC_MODEL 指定具体模型。
挑选云端模型时建议关注三点:是否原生支持工具调用、上下文窗口大小、输入与输出 Token 的价差。这些参数可以在 词元所的大模型 API 服务平台 上集中对比,统一 API 接入也省去了为每家厂商重写一遍集成代码的成本。如果你手上的客户端走的是 OpenAI 兼容协议(如 Roo Code、Continue),Base URL 填 https://qianfan.baidubce.com/v2 就能复用同一套 Key。
小结
Claude Code 接入本地 Ollama 的核心就一句话: Ollama ≥ v0.14.0 + ANTHROPIC_BASE_URL 指向 11434 + 一个支持工具调用且上下文 ≥ 32K 的模型 。本地跑追求数据不出内网,云端跑追求模型能力与响应速度,两者可以在同一套配置间秒级切换。选型阶段不妨先用 百度智能云词元所 把候选模型的能力、上下文和调用成本摆在一起看,再决定哪部分负载放本地、哪部分交给 API。

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