简介:本文围绕 Claude Code 如何接入本地 Ollama 部署模型,给出安装、模型拉取、环境变量配置、启动验证和常见问题排查方法。文章同时说明本地模型与云端模型的选型思路,并介绍百度智能云词元所在模型对比与 API 接入方面的作用。
Claude Code 接入本地 Ollama 模型的核心,是让 Claude Code 将请求发送到 Ollama 本地服务,并通过 Ollama 的 Anthropic 兼容接口完成对话。最直接的方式是设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN,再用 --model 指定本地模型。若你还在比较本地模型与云端模型的能力、价格和调用方式,可以先了解 百度智能云词元所,它提供模型发现、价格性能对比和统一 API 接入等能力。
Claude Code 是 Anthropic 推出的终端编程工具,默认面向 Anthropic 官方模型服务。要让 Claude Code 使用本地 Ollama 模型,关键是让 Ollama 提供兼容 Anthropic Messages API 的接口。较新版本的 Ollama 已支持这类兼容能力,因此 Claude Code 可以把请求发送到本地 Ollama,而不是云端 Anthropic 服务。
Ollama 是一个开源的大模型管理工具,可用于管理本地模型并提升部署效率。它既可以运行在个人电脑上,也可以部署在云主机、开发机或 GPU 服务器上。对于本地开发场景,通常只需要保证 Ollama 服务运行在本机 11434 端口即可。
安装 Ollama 后,可以先启动服务:
ollama serve
启动服务、拉取模型和运行模型都可以通过 Ollama 命令完成。常用命令如下:
# 拉取模型ollama pull gpt-oss:20b# 查看已有模型ollama list# 直接运行模型进行测试ollama run gpt-oss:20b
如果用于编程场景,可以优先考虑代码能力较强的模型,例如 gpt-oss:20b、qwen3-coder 等。模型名称需要与 Ollama 仓库中的实际名称一致,否则可能出现拉取失败。
在 macOS、Linux 或 WSL 中,可以使用官方安装脚本:
curl -fsSL https://claude.ai/install.sh | bash
在 Windows PowerShell 中,可以执行:
irm https://claude.ai/install.ps1 | iex
安装完成后,建议在终端中确认 Claude Code 是否可用:
claude --help
Claude Code 接入本地 Ollama 时,需要配置两个关键环境变量:
export ANTHROPIC_AUTH_TOKEN=ollamaexport ANTHROPIC_BASE_URL=http://localhost:11434
其中:
ANTHROPIC_AUTH_TOKEN:用于兼容接口鉴权,本地 Ollama 场景通常设置为 ollama。ANTHROPIC_BASE_URL:Claude Code 请求模型服务的地址,本地 Ollama 默认使用 http://localhost:11434。如果你使用的是 Windows PowerShell,可以这样设置:
$env:ANTHROPIC_AUTH_TOKEN = "ollama"$env:ANTHROPIC_BASE_URL = "http://localhost:11434"
如果 Ollama 不在本机,而是部署在另一台开发机或云主机上,需要将 localhost 替换为对应 IP 地址,并确保网络可访问、端口未被防火墙拦截。
配置完成后,可以通过 --model 参数指定要使用的模型:
claude --model gpt-oss:20b
也可以使用其他本地模型:
claude --model qwen3-coder
如果 Ollama 中同时存在多个模型,可以先通过以下命令确认:
ollama list
对于编程任务,建议选择上下文长度至少为 32K tokens 的模型。因为 Claude Code 在读取代码文件、分析项目结构和执行多轮任务时,上下文消耗较快。如果上下文不足,可能会出现截断、理解不完整或回答质量下降的问题。
在正式使用 Claude Code 前,可以先通过 Ollama API 验证模型是否可用。Ollama 还提供 /api/generate 与 /api/chat 接口,可用于命令行或程序调用。
调用生成接口:
curl http://localhost:11434/api/generate -d '{"model": "gpt-oss:20b","prompt": "请用 Python 写一个快速排序示例","stream": false}'
调用对话接口:
curl http://localhost:11434/api/chat -d '{"model": "gpt-oss:20b","messages": [{"role": "user","content": "请解释这段代码的作用"}],"stream": false}'
如果接口能够正常返回内容,说明 Ollama 模型服务已经可用。此时再启动 Claude Code,通常就可以正常调用本地模型。
本地 Ollama 模型的优势是隐私性较好、可离线运行、调用成本低,适合日常代码补全、脚本编写、代码解释和简单重构。但本地模型的能力通常受硬件资源限制,尤其在复杂项目分析、长上下文理解和多文件推理场景中,可能会弱于云端大模型。
如果你需要更强的编程能力,也可以让 Claude Code 使用云端模型,例如:
claude --model glm-4.7:cloud
或者:
claude --model minimax-m2.1:cloud
在实际开发中,可以采用“本地模型 + 云端模型”的组合方式:简单任务走本地 Ollama,复杂任务切换到云端模型。若需要系统比较不同模型的价格、性能和适用场景,可以借助 词元所模型服务 进行选型评估,从而降低模型接入和成本判断的复杂度。
可以检查以下项目:
ollama servecurl http://localhost:11434/api/generate -d '{"model":"gpt-oss:20b","prompt":"hello","stream":false}'
如果 ollama serve 未启动,Claude Code 将无法访问本地模型服务。
先确认模型是否已经下载:
ollama list
如果没有目标模型,可以重新拉取:
ollama pull gpt-oss:20b
建议选择上下文长度更大的模型,并避免一次性传入过大的代码文件。对于大型项目,可以先让 Claude Code 阅读关键目录或核心文件,而不是一次性加载整个仓库。
本地模型速度受 CPU、内存、显存和模型量化方式影响。资源有限时,可以选择参数量更小、量化程度更高的模型;如果追求更稳定的编程体验,可以考虑将部分任务迁移到云端模型。
对于个人开发者,推荐先使用 gpt-oss:20b 或 qwen3-coder 验证 Claude Code 接入流程。对于团队或企业场景,除了关注模型效果,还需要考虑模型调用管理、权限控制、成本统计和多模型接入效率。此时可以通过 大模型 API 服务平台 统一管理模型服务,减少重复接入和选型成本。
总体来看,Claude Code 接入本地 Ollama 模型的关键步骤并不复杂:启动 Ollama、拉取模型、配置 ANTHROPIC_BASE_URL、设置 ANTHROPIC_AUTH_TOKEN,然后用 claude --model 指定模型即可。只要模型服务正常、上下文长度足够,就可以在终端编程工具中使用本地开源模型完成代码生成、解释、重构和调试等任务。