简介:只需三步:把 `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 来用,中间层被彻底省掉。
先确认版本,这是最常见的翻车点:
ollama --version # 低于 v0.14.0 请先升级ollama serve # 启动服务,前台运行ollama pull qwen3:8b # 拉取模型ollama list # 确认模型名与 tag
模型仓库在 https://ollama.com/library,也可以把下载好的模型文件直接放进 OLLAMA_MODELS=/root/ollama/ollama_cache/models 目录加载。常用管理命令包括 ollama show(查看模型信息)、ollama create(从模型文件创建)、ollama rm(删除)、ollama cp(复制)和 ollama help。
curl -fsSL https://claude.ai/install.sh | bashexport ANTHROPIC_AUTH_TOKEN=ollamaexport ANTHROPIC_BASE_URL=http://localhost:11434claude --model qwen3:8b
ANTHROPIC_AUTH_TOKEN 在本地场景下只是占位符,Ollama 不校验它,但 不能留空 ,否则 Claude Code 会在发请求前就报认证错误。
如果 Ollama 跑在另一台机器或容器里,把地址换成对端 IP 即可,同时需要让 Ollama 监听所有网卡:
export OLLAMA_HOST=0.0.0.0:11434ollama serve
同样的思路适用于其他实现了 Anthropic 兼容接口的推理工具,比如 LM Studio:
export ANTHROPIC_AUTH_TOKEN=lmstudioexport ANTHROPIC_BASE_URL=http://192.168.5.236:1234claude --model gpt-oss:20b
每次 export 太麻烦,把配置写进项目的 .claude/settings.json 更稳妥,也方便团队共享:
{"env": {"ANTHROPIC_BASE_URL": "http://localhost:11434","ANTHROPIC_AUTH_TOKEN": "ollama","ANTHROPIC_MODEL": "qwen3:8b","ANTHROPIC_SMALL_FAST_MODEL": "qwen3:8b","CLAUDE_CODE_MAX_OUTPUT_TOKENS": 16000,"API_TIMEOUT_MS": 600000},"permissions": { "allow": [], "deny": [] }}
几个参数的实际作用:
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,能快速区分是模型问题还是接入问题:
curl http://localhost:11434/api/chat -d '{"model": "qwen3:8b","messages": [{"role": "user", "content": "why is the sky blue?"}],"stream": false}'
Ollama 同时提供 /api/generate(单轮补全)和 /api/chat(多轮对话)两类接口,更多端点可参考官方 API 文档。这条命令能正常返回,说明模型侧没问题;此时 Claude Code 仍报错,就要回头检查环境变量是否被 settings.json 或其他 shell 配置覆盖。