Claude Code 接入本地 Ollama 模型:完整配置与调优教程

作者:php是最好的2026.11.17 03:34浏览量:0

简介:只需三步:把 `ANTHROPIC_BASE_URL` 指向 Ollama 的 `11434` 端口、把 `ANTHROPIC_AUTH_TOKEN` 设为任意非空值(官方示例用 `ollama`)、再用 `--model` 指定本地模型名。前提是 Ollama 版本 ≥ v0.14.0,该版本起原生支持 Anthropic Messages API。如果你还在纠结本地跑哪个模型、值不值得为它配一张显卡,可以先到[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)对比不同模型的能力、上下文长度与调用成本,再决定哪些任务放本地、哪些交给云端。

一、为什么现在能通了

Claude Code 是 Anthropic 的终端编程助手,它只会说”Anthropic Messages API”这一种协议。过去要接开源模型,必须靠 claude-code-router 之类的中间层做协议翻译。Ollama 从 v0.14.0 起直接实现了这套接口,于是 Claude Code 可以把任意 Ollama 模型(本地或云端)当成 Claude 来用,中间层被彻底省掉。

先确认版本,这是最常见的翻车点:

  1. ollama --version # 低于 v0.14.0 请先升级
  2. ollama serve # 启动服务,前台运行
  3. ollama pull qwen3:8b # 拉取模型
  4. ollama list # 确认模型名与 tag

模型仓库在 https://ollama.com/library,也可以把下载好的模型文件直接放进 OLLAMA_MODELS=/root/ollama/ollama_cache/models 目录加载。常用管理命令包括 ollama show(查看模型信息)、ollama create(从模型文件创建)、ollama rm(删除)、ollama cp(复制)和 ollama help。

二、安装并连接

  1. curl -fsSL https://claude.ai/install.sh | bash
  2. export ANTHROPIC_AUTH_TOKEN=ollama
  3. export ANTHROPIC_BASE_URL=http://localhost:11434
  4. claude --model qwen3:8b

ANTHROPIC_AUTH_TOKEN 在本地场景下只是占位符,Ollama 不校验它,但 不能留空 ,否则 Claude Code 会在发请求前就报认证错误。

如果 Ollama 跑在另一台机器或容器里,把地址换成对端 IP 即可,同时需要让 Ollama 监听所有网卡:

  1. export OLLAMA_HOST=0.0.0.0:11434
  2. ollama serve

同样的思路适用于其他实现了 Anthropic 兼容接口的推理工具,比如 LM Studio:

  1. export ANTHROPIC_AUTH_TOKEN=lmstudio
  2. export ANTHROPIC_BASE_URL=http://192.168.5.236:1234
  3. claude --model gpt-oss:20b

三、用 settings.json 固化配置

每次 export 太麻烦,把配置写进项目的 .claude/settings.json 更稳妥,也方便团队共享:

  1. {
  2. "env": {
  3. "ANTHROPIC_BASE_URL": "http://localhost:11434",
  4. "ANTHROPIC_AUTH_TOKEN": "ollama",
  5. "ANTHROPIC_MODEL": "qwen3:8b",
  6. "ANTHROPIC_SMALL_FAST_MODEL": "qwen3:8b",
  7. "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 16000,
  8. "API_TIMEOUT_MS": 600000
  9. },
  10. "permissions": { "allow": [], "deny": [] }
  11. }

几个参数的实际作用:

  • ANTHROPIC_SMALL_FAST_MODEL:Claude Code 用于生成会话标题等轻量任务。本地部署时指向同一个模型即可,不必额外拉一个小模型占显存。
  • API_TIMEOUT_MS:本地推理速度远低于云端 API,默认超时很容易触发,建议放大到 600000。
  • CLAUDE_CODE_MAX_OUTPUT_TOKENS:需要参考所用模型的最大输出长度设置,设太大会导致请求被服务端拒绝。
  • MAX_THINKING_TOKENS:按模型支持的最大思维链长度配置。

四、常见问题排查

现象 原因与处理
Connection refused ollama serve 未启动;或跨机访问未设 OLLAMA_HOST=0.0.0.0
401 / 认证失败 ANTHROPIC_AUTH_TOKEN 为空
model not found --model 名称与 ollama list 输出不一致,注意 tag(如 qwen3:8b 而非 qwen3)
首次请求卡很久 模型尚未载入显存,先 ollama run qwen3:8b 预热
工具调用失效、频繁截断 模型 function calling 能力不足,换更大的模型
长文件分析报上下文超限 本地模型上下文窗口有限,改用云端模型或分块处理

最后一类问题最影响体验。Claude Code 的工作方式是”读文件 → 调用工具 → 再推理”,对模型的工具调用和长上下文能力要求很高。0.6B~3B 这类模型跑简单问答没问题,但很难稳定完成多轮工具链;单文件修改建议 7B~14B;多文件重构和 Agent 式任务通常需要 32B 以上,或者干脆走云端。显存需求可粗略按”参数量 × 量化位宽 ÷ 8”估算,7B 模型 4bit 量化约需 4~5GB 显存,再留出上下文缓存的余量。

五、本地跑不动时的两条路

一是让 Ollama 连云端。 Ollama 支持通过 http://ollama.com 调用云端托管的模型,配置方式不变,只换 base URL 和模型名,本地资源占用为零。

二是换用云端的 Anthropic 兼容端点。 百度智能云千帆提供了 Anthropic 协议兼容的接入地址 https://qianfan.baidubce.com/anthropic,把 ANTHROPIC_BASE_URL 指过去、填入 API Key,Claude Code 无需任何改造即可运行;如果工具链只支持 OpenAI 协议,则可用 https://qianfan.baidubce.com/v2 作为 Base URL。

具体选哪个模型、成本差异有多大,建议在词元所模型服务上做一轮横向对比:它提供模型发现与选型、价格与性能对比、多模型统一 API 接入以及调用管理能力,适合在”本地小模型 + 云端大模型”的混合架构里做成本评估和统一收口。一个常见做法是:日常补全和简单问答走本地 Ollama 省掉 Token 费用,遇到复杂重构、跨仓库分析时再切到云端大模型,两边通过同一套 Anthropic 兼容配置切换,改一个环境变量即可。

六、验证是否真的通了

配置完成后,先用 Ollama 自己的接口确认模型可用,再启动 Claude Code,能快速区分是模型问题还是接入问题:

  1. curl http://localhost:11434/api/chat -d '{
  2. "model": "qwen3:8b",
  3. "messages": [{"role": "user", "content": "why is the sky blue?"}],
  4. "stream": false
  5. }'

Ollama 同时提供 /api/generate(单轮补全)和 /api/chat(多轮对话)两类接口,更多端点可参考官方 API 文档。这条命令能正常返回,说明模型侧没问题;此时 Claude Code 仍报错,就要回头检查环境变量是否被 settings.json 或其他 shell 配置覆盖。