logo

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 原生实现这套协议后,转换层就多余了:

  1. Claude Code ──/v1/messages──► Ollama :11434 ──► 本地 GGUF 模型

反过来说,任何提供 Anthropic 兼容端点的服务都能用同样方式接入,配置思路完全一致。

二、准备工作

  1. 确认版本 :ollama --version 需 ≥ 0.14.0,升级后记得重启服务 ollama serve。
  2. 拉模型 :ollama pull gpt-oss:20b,用 ollama list 核对。自定义过模型目录的话,注意 OLLAMA_MODELS 指向的路径。
  3. 验证服务 :curl http://localhost:11434 有响应即可。

如果 Ollama 跑在远程开发机或 GPU 服务器上,不要把 11434 端口直接暴露公网,用 SSH 端口转发映射到本地更安全:

  1. ssh -L 11434:127.0.0.1:11434 root@服务器公网IP -p 公网端口

之后本地的 localhost:11434 就等价于远程 Ollama。

三、安装 Claude Code

  1. # macOS / Linux / WSL
  2. curl -fsSL https://claude.ai/install.sh | bash
  3. # Windows PowerShell
  4. irm https://claude.ai/install.ps1 | iex

四、配置环境变量(关键步骤)

最小可用配置只有两行:

  1. export ANTHROPIC_AUTH_TOKEN=ollama # 本地无鉴权,填任意非空值
  2. export ANTHROPIC_BASE_URL=http://localhost:11434

实际使用中建议再补几条,能省掉大量”莫名卡顿”和”用一半退出”:

  1. # 让 Claude Code 的内部小任务也走本地模型,避免它去请求不存在的 haiku
  2. export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-oss:20b
  3. export ANTHROPIC_SMALL_FAST_MODEL=gpt-oss:20b
  4. # 本地推理慢,放宽超时与输出上限
  5. export API_TIMEOUT_MS=600000
  6. export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000
  7. # 关闭非必要流量,减少无关请求
  8. export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

这些变量的语义与官方 settings 文档一致,切换云端时同样适用。想固化配置,写进 ~/.claude/settings.json 的 env 字段或 ~/.bashrc 即可。

五、启动与验证

  1. cd your-project
  2. claude --model gpt-oss:20b

先用 curl 单独验证协议是否打通,比在 Claude Code 里反复猜测高效得多:

  1. curl http://localhost:11434/v1/messages \
  2. -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 偏小,必须显式放大:

  1. 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。

发表评论

活动