Claude Code 接 Ollama 本地模型教程：离线免费不限量（2026）

很长一段时间里，想用 Claude Code 就得联外网、绑账号、按 token 付费。2026 年 1 月 Ollama v0.14.0 发布后这件事变了：它新增了 Anthropic Messages API 兼容（/v1/messages），而 Claude Code 恰好认这个协议。于是给 Claude Code 接本地模型只剩两个环境变量的事——模型跑在你自己的显卡上，代码一个字节都不出本机，用多少都不花钱。这篇教程从装 Ollama 讲到真正跑通，包含显存怎么选模型、上下文长度这个 90% 的人会踩的坑，以及本地模型到底差在哪、什么时候该老老实实用云端 API。

为什么要给 Claude Code 接本地模型

本地模型不是万金油，但有三类场景是云端 API 替代不了的。第一是合规与隐私：公司代码不允许出内网、涉密项目、甲方明文禁止上传源码，这时候本地跑是唯一解。第二是成本：Claude Code 是出了名的吃 token，一个中等重构任务几十万 token 很正常，本地跑则是电费封顶、无限使用。第三是离线：飞机上、内网机房、网络不稳定的地方，本地模型照样干活。

反过来说，如果你只是想省钱又能联网，直接接国产模型 API（GLM / DeepSeek / Kimi）通常性价比更高、模型能力也更强——本地开源模型在长任务上的稳定性目前还追不上闭源前沿模型。文末有一张对照表帮你决策。

第一步：装 Ollama 并确认版本

去 ollama.com 下载对应平台的安装包，或用命令行安装。装完务必确认版本 ≥ 0.14.0，低于这个版本没有 /v1/messages 接口，后面全白搭：

# macOS / Linux 安装
curl -fsSL https://ollama.com/install.sh | sh

# 确认版本（必须 >= 0.14.0）
ollama --version

# 确认服务在跑（默认监听 11434 端口）
curl http://localhost:11434

想直接验证 Anthropic 兼容接口通不通，可以打一发 curl。返回正常的 JSON 就说明协议层没问题：

curl -X POST http://localhost:11434/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: ollama" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen3-coder",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello, how are you?" }]
  }'

第二步：拉一个能干活的模型

编程 agent 对模型要求比聊天高得多——它要连续调工具、读多个文件、改代码还不能改错。7B 以下的小模型基本跑不动 Claude Code 的工具循环，别浪费时间。Ollama 官方推荐的两个起步模型是 gpt-oss:20b 和 qwen3-coder。

第三步：两个环境变量接上 Claude Code

这是整个流程最简单的一步。Claude Code 通过 ANTHROPIC_BASE_URL 决定请求发给谁，把它指向本地的 Ollama 即可。ANTHROPIC_AUTH_TOKEN 随便填（Ollama 本地不校验），但必须有值，否则 Claude Code 会以为你没登录：

# macOS / Linux / WSL
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11434

# 用本地模型启动
claude --model gpt-oss:20b

# 或者用 Ollama 云端模型
claude --model glm-4.7:cloud

Windows PowerShell 用户改成这样（注意 PowerShell 里设环境变量是 $env: 前缀，不是 export）：

$env:ANTHROPIC_AUTH_TOKEN = "ollama"
$env:ANTHROPIC_BASE_URL = "http://localhost:11434"

claude --model qwen3-coder

最大的坑：上下文长度默认只有 2048

这是本地跑 Claude Code 最常见的翻车点。Ollama 的 num_ctx 默认值是 2048，而 Claude Code 光是系统提示词 + 工具定义就远超这个数——结果就是模型胡言乱语、工具调用失败、或者直接把你的指令截没了。Ollama 官方明确建议：跑 Claude Code 的模型至少要 32K 上下文。

最省事的做法是设 OLLAMA_CONTEXT_LENGTH 环境变量，它对所有模型全局生效（注意是给 Ollama 服务端设，不是给 Claude Code 设，改完要重启 Ollama 服务）：

# 全局设置上下文长度（给 Ollama 服务进程）
export OLLAMA_CONTEXT_LENGTH=32768

# 然后重启 Ollama 服务，再启动 Claude Code
# macOS 上退出菜单栏图标重开；Linux systemd:
# sudo systemctl restart ollama

另一个选择是用 Modelfile 给模型固化 num_ctx，适合你只想让某一个模型吃长上下文、不想全局抬高显存占用的情况。Ollama 的云端模型（:cloud 后缀）会自动跑满上下文长度，不需要你手动配。

没有显卡？Ollama Cloud 是个折中

如果你的机器扛不住本地推理，Ollama 提供了云端模型：模型名加 :cloud 后缀，走 Ollama 的 GPU 跑，配置方式和本地完全一样（同一套环境变量、同一个 11434 端口转发）。代价是代码要出本机，隐私优势就没了，只剩「统一入口 + 包月不计 token」这个好处。

Ollama Cloud 按 GPU 时长计费而非按 token，会话额度每 5 小时重置、周额度每 7 天重置，用到 90% 会邮件提醒。这个计费方式对「一个任务跑很久」的 agent 场景其实不太友好，长跑任务要留意。

本地模型和官方 Claude 差在哪

先说协议层。Ollama 的 Anthropic 兼容接口支持消息、流式、系统提示词、多轮对话、视觉（图片）、工具调用、工具结果和 thinking，够 Claude Code 日常用。但有几个字段明确不支持，踩到了会报错或行为异常：

• tool_choice —— 无法强制模型必须调用某个工具
• metadata 字段
• Prompt caching（提示词缓存） —— 本地不花钱倒无所谓，但会影响长会话的响应速度
• Token 计数接口 /v1/messages/count_tokens —— 所以 Claude Code 里的用量统计可能不准
• PDF 文档输入
• URL 形式的图片（只支持 base64 内联）

再说能力层，这才是真正的差距。Claude Code 的强项是长任务：连续几十轮工具调用不跑偏、能自己回头检查、改错了会改回来。开源 20B/30B 模型在这方面明显更脆弱——上下文一长就开始重复、工具参数写错、或者宣称改完了其实没改。所以本地模型更适合范围明确的小任务（写个函数、加个测试、改个 bug），别指望它自己跑通一个大重构。

本地模型 vs 国产模型 API：怎么选

多数人的最优解其实是「国产 API 打底 + 本地模型兜底」：日常用 GLM 或 DeepSeek 这类接得顺、能力够的云端模型，遇到不能上传的代码时切到本地。配置方式在我们的《Claude Code 接入国产模型教程》里讲得更细，两篇可以配合着看。

把 Claude Code 接上本地模型，本质上是给自己多了一个「无限量、零隐私风险」的试错环境——正是学 AI 编程最需要的东西：可以随便折腾，不用心疼额度。但工具接通只是开始，真正决定产出的还是你怎么拆任务、怎么写上下文、怎么判断 AI 什么时候在胡说。IMAI 的体系化实战课程正是围绕这些展开，欢迎来看看。