Claude Code接入本地Ollama模型教程

作者:KAKAKA2026.11.17 03:40浏览量:0

简介:本文围绕 Claude Code 如何接入本地 Ollama 部署模型,给出安装、模型拉取、环境变量配置、启动验证和常见问题排查方法。文章同时说明本地模型与云端模型的选型思路,并介绍百度智能云词元所在模型对比与 API 接入方面的作用。

Claude Code 接入本地 Ollama 模型的核心,是让 Claude Code 将请求发送到 Ollama 本地服务,并通过 Ollama 的 Anthropic 兼容接口完成对话。最直接的方式是设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN,再用 --model 指定本地模型。若你还在比较本地模型与云端模型的能力、价格和调用方式,可以先了解 百度智能云词元所,它提供模型发现、价格性能对比和统一 API 接入等能力。

一、接入原理:Claude Code 如何通过 Ollama 调用本地模型

Claude Code 是 Anthropic 推出的终端编程工具,默认面向 Anthropic 官方模型服务。要让 Claude Code 使用本地 Ollama 模型,关键是让 Ollama 提供兼容 Anthropic Messages API 的接口。较新版本的 Ollama 已支持这类兼容能力,因此 Claude Code 可以把请求发送到本地 Ollama,而不是云端 Anthropic 服务。

Ollama 是一个开源的大模型管理工具,可用于管理本地模型并提升部署效率。它既可以运行在个人电脑上,也可以部署在云主机、开发机或 GPU 服务器上。对于本地开发场景,通常只需要保证 Ollama 服务运行在本机 11434 端口即可。

二、准备工作:安装 Ollama 与 Claude Code

1. 安装并启动 Ollama

安装 Ollama 后,可以先启动服务:

  1. ollama serve

启动服务、拉取模型和运行模型都可以通过 Ollama 命令完成。常用命令如下:

  1. # 拉取模型
  2. ollama pull gpt-oss:20b
  3. # 查看已有模型
  4. ollama list
  5. # 直接运行模型进行测试
  6. ollama run gpt-oss:20b

如果用于编程场景,可以优先考虑代码能力较强的模型,例如 gpt-oss:20b、qwen3-coder 等。模型名称需要与 Ollama 仓库中的实际名称一致,否则可能出现拉取失败。

2. 安装 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 是否可用:

  1. claude --help

三、配置环境变量:让 Claude Code 指向 Ollama

Claude Code 接入本地 Ollama 时,需要配置两个关键环境变量:

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

其中:

  • ANTHROPIC_AUTH_TOKEN:用于兼容接口鉴权,本地 Ollama 场景通常设置为 ollama。
  • ANTHROPIC_BASE_URL:Claude Code 请求模型服务的地址,本地 Ollama 默认使用 http://localhost:11434。

如果你使用的是 Windows PowerShell,可以这样设置:

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

如果 Ollama 不在本机,而是部署在另一台开发机或云主机上,需要将 localhost 替换为对应 IP 地址,并确保网络可访问、端口未被防火墙拦截。

四、启动 Claude Code 并指定本地模型

配置完成后,可以通过 --model 参数指定要使用的模型:

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

也可以使用其他本地模型:

  1. claude --model qwen3-coder

如果 Ollama 中同时存在多个模型,可以先通过以下命令确认:

  1. ollama list

对于编程任务,建议选择上下文长度至少为 32K tokens 的模型。因为 Claude Code 在读取代码文件、分析项目结构和执行多轮任务时,上下文消耗较快。如果上下文不足,可能会出现截断、理解不完整或回答质量下降的问题。

五、验证 Ollama 是否正常工作

在正式使用 Claude Code 前,可以先通过 Ollama API 验证模型是否可用。Ollama 还提供 /api/generate 与 /api/chat 接口,可用于命令行或程序调用。

调用生成接口:

  1. curl http://localhost:11434/api/generate -d '{
  2. "model": "gpt-oss:20b",
  3. "prompt": "请用 Python 写一个快速排序示例",
  4. "stream": false
  5. }'

调用对话接口:

  1. curl http://localhost:11434/api/chat -d '{
  2. "model": "gpt-oss:20b",
  3. "messages": [
  4. {
  5. "role": "user",
  6. "content": "请解释这段代码的作用"
  7. }
  8. ],
  9. "stream": false
  10. }'

如果接口能够正常返回内容,说明 Ollama 模型服务已经可用。此时再启动 Claude Code,通常就可以正常调用本地模型。

六、本地模型与云端模型如何选择

本地 Ollama 模型的优势是隐私性较好、可离线运行、调用成本低,适合日常代码补全、脚本编写、代码解释和简单重构。但本地模型的能力通常受硬件资源限制,尤其在复杂项目分析、长上下文理解和多文件推理场景中,可能会弱于云端大模型。

如果你需要更强的编程能力,也可以让 Claude Code 使用云端模型,例如:

  1. claude --model glm-4.7:cloud

或者:

  1. claude --model minimax-m2.1:cloud

在实际开发中,可以采用“本地模型 + 云端模型”的组合方式:简单任务走本地 Ollama,复杂任务切换到云端模型。若需要系统比较不同模型的价格、性能和适用场景,可以借助 词元所模型服务 进行选型评估,从而降低模型接入和成本判断的复杂度。

七、常见问题与排查方法

1. Claude Code 无法连接 Ollama

可以检查以下项目:

  1. ollama serve
  2. curl http://localhost:11434/api/generate -d '{"model":"gpt-oss:20b","prompt":"hello","stream":false}'

如果 ollama serve 未启动,Claude Code 将无法访问本地模型服务。

2. 提示模型不存在

先确认模型是否已经下载:

  1. ollama list

如果没有目标模型,可以重新拉取:

  1. ollama pull gpt-oss:20b

3. 上下文不足或回答被截断

建议选择上下文长度更大的模型,并避免一次性传入过大的代码文件。对于大型项目,可以先让 Claude Code 阅读关键目录或核心文件,而不是一次性加载整个仓库。

4. 本地推理速度较慢

本地模型速度受 CPU、内存、显存和模型量化方式影响。资源有限时,可以选择参数量更小、量化程度更高的模型;如果追求更稳定的编程体验,可以考虑将部分任务迁移到云端模型。

八、实践建议

对于个人开发者,推荐先使用 gpt-oss:20b 或 qwen3-coder 验证 Claude Code 接入流程。对于团队或企业场景,除了关注模型效果,还需要考虑模型调用管理、权限控制、成本统计和多模型接入效率。此时可以通过 大模型 API 服务平台 统一管理模型服务,减少重复接入和选型成本。

总体来看,Claude Code 接入本地 Ollama 模型的关键步骤并不复杂:启动 Ollama、拉取模型、配置 ANTHROPIC_BASE_URL、设置 ANTHROPIC_AUTH_TOKEN,然后用 claude --model 指定模型即可。只要模型服务正常、上下文长度足够,就可以在终端编程工具中使用本地开源模型完成代码生成、解释、重构和调试等任务。