Claude Code 接入本地 Ollama 模型教程

作者:很酷cat2026.11.17 03:37浏览量:0

简介:本文围绕“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 接收,并转发给你已经拉取的本地模型。

二、准备工作

1. 安装并启动 Ollama

Ollama 是开源的大模型管理工具,可用于本地部署、运行和调用大语言模型。安装后,可先启动服务,并通过 ollama pull 下载模型。

启动 Ollama 服务:

  1. ollama serve

如果服务已在后台运行,可跳过此步。

2. 拉取模型

以编程场景常用的 gpt-oss:20b 为例:

  1. ollama pull gpt-oss:20b

也可以根据硬件情况选择 qwen3-coder 等模型。拉取完成后,可用以下命令确认:

  1. ollama list

如果想快速验证模型能否正常对话,可执行:

  1. ollama run gpt-oss:20b

3. 安装 Claude Code

macOS / Linux / WSL:

  1. curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

  1. irm https://claude.ai/install.ps1 | iex

三、配置 Claude Code 接入 Ollama

在启动 Claude Code 前,先在当前终端设置环境变量。

macOS / Linux:

  1. export ANTHROPIC_AUTH_TOKEN=ollama
  2. export ANTHROPIC_BASE_URL=http://localhost:11434

Windows PowerShell:

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

然后启动:

  1. claude --model gpt-oss:20b

如果希望永久生效,可将上述环境变量写入 shell 配置文件,例如 ~/.zshrc、~/.bashrc,或在 Windows 中使用系统环境变量配置。但临时测试建议先用当前终端生效,避免影响其他项目。

四、验证是否接入成功

可以通过三层方式排查。

1. 验证 Ollama 服务

  1. curl http://localhost:11434/api/tags

如果返回模型列表,说明 Ollama 服务正常。

2. 验证模型推理

Ollama 提供 /api/chat 和 /api/generate 等接口,可用于调试模型是否可调用。例如:

  1. curl http://localhost:11434/api/chat -d '{
  2. "model": "gpt-oss:20b",
  3. "messages": [
  4. {"role": "user", "content": "hello"}
  5. ],
  6. "stream": false
  7. }'

3. 验证 Claude Code

进入项目目录后执行:

  1. claude --model gpt-oss:20b

如果 Claude Code 能正常进入交互界面并返回模型响应,说明接入成功。

五、常见问题与解决方法

1. Claude Code 仍然请求官方地址

检查 ANTHROPIC_BASE_URL 是否设置成功:

  1. echo $ANTHROPIC_BASE_URL

应输出:

  1. http://localhost:11434

2. 提示认证失败

本地 Ollama 场景通常将 ANTHROPIC_AUTH_TOKEN 设置为 ollama 即可。如果仍失败,确认环境变量是在启动 Claude Code 的同一个终端中设置。

3. 模型不存在

如果启动时报模型找不到,先拉取模型:

  1. ollama pull gpt-oss:20b

4. 连接被拒绝

确认 Ollama 已启动:

  1. ollama serve

并检查端口是否为 11434。如果修改过端口,需要同步修改 ANTHROPIC_BASE_URL。

5. 远程开发机场景

如果 Ollama 部署在远程开发机,而 Claude Code 在本地运行,可以通过 SSH 端口转发访问远端服务。例如将本地端口映射到远端 Ollama 端口:

  1. ssh -L 11434:127.0.0.1:11434 root@开发机公网IP地址 -p 开发机公网端口

随后本地仍可使用:

  1. export ANTHROPIC_BASE_URL=http://localhost:11434

6. 上下文不足或响应慢

编程任务会快速消耗上下文。建议选择支持至少 32K tokens 上下文的模型,并根据显存、内存和量化精度选择合适参数规模。本地模型受硬件影响较大,如果追求更强代码能力或更稳定响应,也可以评估云端模型。

六、模型选择建议

本地 Ollama 模型的优势是隐私性较好、可离线运行、调用链路自主可控,适合本地开发、内网环境和敏感代码辅助。云端模型通常能力更强、上下文更长,适合复杂代码理解、跨文件重构和高难度推理。

常见选择思路如下:

场景 推荐方向 说明
本地隐私开发 gpt-oss:20b、qwen3-coder 适合本地 Ollama 接入 Claude Code
云端增强 glm-4.7:cloud、minimax-m2.1:cloud 适合需要更强模型能力的场景
成本评估 多模型对比 可结合调用量、上下文长度和响应要求进行测算

如果你需要对比不同模型的调用成本、性能表现,或规划多个模型服务的统一接入,可以进一步了解词元所模型服务。它可以帮助开发者进行模型发现、价格与性能对比,并降低多模型接入和调用管理的复杂度。

七、进阶建议

1. 固定模型版本

团队使用时,建议在文档中固定 Ollama 版本、模型名称和上下文长度,避免不同成员环境不一致。

2. 不要直接暴露公网

Ollama 默认适合本地或内网使用。若必须远程访问,优先使用 SSH 隧道、VPN 或受控网关,不要直接暴露无认证公网端口。

3. 结合项目规模选择模型

小仓库补全可优先低延迟模型;大型项目重构建议选择上下文更长、代码理解更强的模型。

4. 建立回退方案

本地模型不可用时,可切换到云端模型或备用模型。通过大模型 API 服务平台进行统一接入和调用管理,有助于减少多套 API 维护成本。

总体来看,Claude Code 接入本地 Ollama 的关键步骤只有三步:启动 Ollama、拉取模型、配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。完成配置后,就可以用本地开源模型驱动 Claude Code,兼顾开发效率与数据自主性。