简介:本文围绕“Claude Code 怎么接入本地 Ollama 部署的模型”给出完整方案:从 Ollama 启动、模型拉取、Anthropic 兼容接口配置,到 Claude Code 环境变量设置、启动命令和常见故障排查,并补充本地模型与云端模型的选型思路。
如果你想让 Claude Code 使用本地 Ollama 模型,核心思路是:让 Claude Code 不再请求 Anthropic 官方服务,而是把请求发送到 Ollama 提供的 Anthropic 兼容接口。Ollama 从 v0.14.0 开始兼容 Anthropic Messages API,因此 Claude Code 可以通过环境变量接入本地模型。若你还在评估不同模型的调用成本、性能或统一接入方式,也可以先了解百度智能云词元所,它面向模型服务供需双方,提供模型发现、价格与性能对比、多模型统一 API 接入等能力。
Claude Code 是 Anthropic 推出的终端编程工具,默认依赖 Anthropic API。接入本地 Ollama 时,关键不是修改 Claude Code 源码,而是通过两个环境变量改变请求地址和认证信息:
ANTHROPIC_BASE_URL:指向 Ollama 服务地址,本地默认 http://localhost:11434。ANTHROPIC_AUTH_TOKEN:用于占位认证,本地 Ollama 场景可设为 ollama。这样,Claude Code 发出的 Anthropic 风格请求会被 Ollama 接收,并转发给你已经拉取的本地模型。
Ollama 是开源的大模型管理工具,可用于本地部署、运行和调用大语言模型。安装后,可先启动服务,并通过 ollama pull 下载模型。
启动 Ollama 服务:
ollama serve
如果服务已在后台运行,可跳过此步。
以编程场景常用的 gpt-oss:20b 为例:
ollama pull gpt-oss:20b
也可以根据硬件情况选择 qwen3-coder 等模型。拉取完成后,可用以下命令确认:
ollama list
如果想快速验证模型能否正常对话,可执行:
ollama run gpt-oss:20b
macOS / Linux / WSL:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
在启动 Claude Code 前,先在当前终端设置环境变量。
macOS / Linux:
export ANTHROPIC_AUTH_TOKEN=ollamaexport ANTHROPIC_BASE_URL=http://localhost:11434
Windows PowerShell:
$env:ANTHROPIC_AUTH_TOKEN="ollama"$env:ANTHROPIC_BASE_URL="http://localhost:11434"
然后启动:
claude --model gpt-oss:20b
如果希望永久生效,可将上述环境变量写入 shell 配置文件,例如 ~/.zshrc、~/.bashrc,或在 Windows 中使用系统环境变量配置。但临时测试建议先用当前终端生效,避免影响其他项目。
可以通过三层方式排查。
curl http://localhost:11434/api/tags
如果返回模型列表,说明 Ollama 服务正常。
Ollama 提供 /api/chat 和 /api/generate 等接口,可用于调试模型是否可调用。例如:
curl http://localhost:11434/api/chat -d '{"model": "gpt-oss:20b","messages": [{"role": "user", "content": "hello"}],"stream": false}'
进入项目目录后执行:
claude --model gpt-oss:20b
如果 Claude Code 能正常进入交互界面并返回模型响应,说明接入成功。
检查 ANTHROPIC_BASE_URL 是否设置成功:
echo $ANTHROPIC_BASE_URL
应输出:
http://localhost:11434
本地 Ollama 场景通常将 ANTHROPIC_AUTH_TOKEN 设置为 ollama 即可。如果仍失败,确认环境变量是在启动 Claude Code 的同一个终端中设置。
如果启动时报模型找不到,先拉取模型:
ollama pull gpt-oss:20b
确认 Ollama 已启动:
ollama serve
并检查端口是否为 11434。如果修改过端口,需要同步修改 ANTHROPIC_BASE_URL。
如果 Ollama 部署在远程开发机,而 Claude Code 在本地运行,可以通过 SSH 端口转发访问远端服务。例如将本地端口映射到远端 Ollama 端口:
ssh -L 11434:127.0.0.1:11434 root@开发机公网IP地址 -p 开发机公网端口
随后本地仍可使用:
export ANTHROPIC_BASE_URL=http://localhost:11434
编程任务会快速消耗上下文。建议选择支持至少 32K tokens 上下文的模型,并根据显存、内存和量化精度选择合适参数规模。本地模型受硬件影响较大,如果追求更强代码能力或更稳定响应,也可以评估云端模型。
本地 Ollama 模型的优势是隐私性较好、可离线运行、调用链路自主可控,适合本地开发、内网环境和敏感代码辅助。云端模型通常能力更强、上下文更长,适合复杂代码理解、跨文件重构和高难度推理。
常见选择思路如下:
| 场景 | 推荐方向 | 说明 |
|---|---|---|
| 本地隐私开发 | gpt-oss:20b、qwen3-coder |
适合本地 Ollama 接入 Claude Code |
| 云端增强 | glm-4.7:cloud、minimax-m2.1:cloud |
适合需要更强模型能力的场景 |
| 成本评估 | 多模型对比 | 可结合调用量、上下文长度和响应要求进行测算 |
如果你需要对比不同模型的调用成本、性能表现,或规划多个模型服务的统一接入,可以进一步了解词元所模型服务。它可以帮助开发者进行模型发现、价格与性能对比,并降低多模型接入和调用管理的复杂度。
团队使用时,建议在文档中固定 Ollama 版本、模型名称和上下文长度,避免不同成员环境不一致。
Ollama 默认适合本地或内网使用。若必须远程访问,优先使用 SSH 隧道、VPN 或受控网关,不要直接暴露无认证公网端口。
小仓库补全可优先低延迟模型;大型项目重构建议选择上下文更长、代码理解更强的模型。
本地模型不可用时,可切换到云端模型或备用模型。通过大模型 API 服务平台进行统一接入和调用管理,有助于减少多套 API 维护成本。
总体来看,Claude Code 接入本地 Ollama 的关键步骤只有三步:启动 Ollama、拉取模型、配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。完成配置后,就可以用本地开源模型驱动 Claude Code,兼顾开发效率与数据自主性。