简介:本文讲清 Claude Code 连接本地 Ollama 的完整链路:为什么需要适配层,如何安装配置 LiteLLM,怎样拉取编码模型,代理报错如何处理,以及本地与云端模型该如何选。读完后,你可以在离线或低成本环境下跑通本地编码助手。
Claude Code 使用 Anthropic Messages 协议,请求地址的路径是 /v1/messages。Ollama 原生提供的接口是 /api/chat 和 /api/generate,另外还有 OpenAI 兼容的 /v1/chat/completions。两套协议的请求格式不同。如果把 ANTHROPIC_BASE_URL 直接指向 http://localhost:11434,Claude Code 发出的请求会与 Ollama 的接口对不上,结果通常是连接失败或返回格式错误。
因此,中间需要一个适配层,把 Anthropic 格式的请求转换成 Ollama 能处理的请求。常用的适配层有 LiteLLM Proxy 和 claude-code-router。本文以 LiteLLM 为例。不同版本的 Ollama 功能可能有差异,如果你使用的版本文档明确支持 Anthropic 兼容接口,可以省略适配层,但仍建议先用 curl 验证。
整体链路如下:Claude Code 把请求发给 LiteLLM(默认端口 4000),LiteLLM 转换格式后转发给 Ollama(默认端口 11434),Ollama 调用本地模型并返回结果。
开始前,请确认以下条件:
可以用下面的命令检查环境:
node --versionnpm --versionpython3 --versionollama --versioncurl http://localhost:11434
如果 Ollama 没有运行,执行 ollama serve 启动服务。curl http://localhost:11434 正常时会返回 Ollama is running。如果返回连接失败,先处理服务启动问题,再继续后面的步骤。
安装 Claude Code:
npm install -g @anthropic-ai/claude-code@latestclaude --version
拉取代码模型并确认已下载:
ollama pull qwen2.5-coder:7bollama list
qwen2.5-coder:7b 的默认量化版本约占 4.7 GB 磁盘空间。运行时建议至少有 8 GB 可用内存或显存。如果机器配置较低,可以改用 qwen2.5-coder:3b,响应更快,但代码质量会下降。模型越大,对硬件的要求越高,选型时应同时考虑显存、内存和响应速度。
使用 pip 安装 LiteLLM 代理组件:
pip install 'litellm[proxy]'
在工作目录下创建配置文件 litellm_config.yaml:
model_list:- model_name: claude-locallitellm_params:model: ollama/qwen2.5-coder:7bapi_base: http://localhost:11434
这里有两个名字需要区分。model_name 是 Claude Code 中使用的名称,本例为 claude-local。model 是 Ollama 中的真实模型名,必须带有 ollama/ 前缀,并与 ollama list 显示的名称一致。
启动适配层:
litellm --config litellm_config.yaml --port 4000
启动后,在另一个终端中用 curl 验证 Anthropic 格式的请求能否正常返回:
curl http://localhost:4000/v1/messages \-H "content-type: application/json" \-H "x-api-key: sk-local" \-H "anthropic-version: 2023-06-01" \-d '{"model":"claude-local","max_tokens":256,"messages":[{"role":"user","content":"用一句话解释闭包"}]}'
如果返回了包含模型回答的 JSON,说明链路已经打通。如果返回 404,检查请求路径是否为 /v1/messages。如果返回模型不存在的错误,检查配置文件中的 model_name 和 model 是否正确。
配置时,ANTHROPIC_BASE_URL 应指向适配层地址 http://localhost:4000,不能再写 11434:
export ANTHROPIC_BASE_URL=http://localhost:4000export ANTHROPIC_AUTH_TOKEN=sk-localclaude --model claude-local
ANTHROPIC_AUTH_TOKEN 在本地场景中只是占位值,适配层没有设置主密钥时不会校验它。
这里要注意作用域。把变量写入 ~/.zshrc 或 ~/.bashrc 后,所有读取 Anthropic 环境变量的工具都会受影响,包括其他 SDK 脚本和 CLI 工具。更稳妥的做法是只在特定项目中生效。例如使用 direnv,在项目目录下创建 .envrc 文件并写入上述变量,进入该目录时自动加载,离开时自动失效。如果只是临时测试,直接在当前终端中 export 即可,关闭终端后变量会失效。
配置完成后如果出现 API Error: Connection error,常见原因是系统代理把 localhost 的请求转发到了代理服务器。可以临时清除代理变量:
unset http_proxyunset https_proxy
也可以让本地地址绕过代理:
export no_proxy=localhost,127.0.0.1
no_proxy 的方式比清除代理更安全,因为它只影响本地地址,不影响其他外部请求。如果你已经用 unset 清除了代理,完成本地测试后要恢复代理设置,否则后续访问外部网络的命令可能失败。恢复时重新执行原来的设置,例如 export https_proxy=你原来的代理地址,或直接打开新终端。
如果清除代理后仍然失败,依次检查 Ollama 和 LiteLLM 是否在运行、端口是否被占用,以及 Claude Code 是否读取到了正确的环境变量。
如果需要把本地模型嵌入自动化脚本、代码审查工具或内部 Agent 流程,可以直接使用 Anthropic Python SDK。请求地址指向适配层,并禁用环境代理:
import anthropicimport httpxclient = anthropic.Anthropic(base_url="http://localhost:4000",api_key="sk-local",http_client=httpx.Client(trust_env=False),)with client.messages.stream(model="claude-local",max_tokens=1024,messages=[{"role": "user", "content": "写一个 Python 快速排序函数"}],) as stream:for text in stream.text_stream:print(text, end="", flush=True)
如果不需要 Anthropic 的接口格式,也可以直接调用 Ollama 的 Python 库,少一层转发:
import ollamaclient = ollama.Client(host="http://localhost:11434")resp = client.chat(model="qwen2.5-coder:7b",messages=[{"role": "user", "content": "写一个 Python 快速排序函数"}],)print(resp["message"]["content"])
两种方式的区别在于:前者与 Claude Code 使用同一套协议,便于复用已有的 Anthropic 调用代码;后者更直接,适合只使用本地模型的脚本。SDK 更适合做流程编排、日志记录和结果解析。
ollama list 确认模型名称和标签。再检查 LiteLLM 配置中 model 字段是否带有 ollama/ 前缀,以及 claude --model 是否与 model_name 一致。curl http://localhost:11434 和 curl http://localhost:4000,确认两个服务都在运行。/v1/messages。直接访问 11434 会得到与 Claude Code 协议不匹配的结果。unset http_proxy 和 unset https_proxy,或设置 no_proxy。SDK 中可通过 trust_env=False 禁用环境代理。ollama ps 查看模型是否已加载,以及是否有部分层运行在 CPU 上。如果资源不足,换用更小参数量的模型。本地 Ollama 的优势是数据留在本机、可以离线运行,并且没有按调用量计费的 Token 开销。不足是模型能力、推理速度和上下文长度受本地硬件限制。云端模型通常在复杂推理、长上下文和服务稳定性方面更强,更适合生产环境和高难度的编码任务。
| 维度 | 本地 Ollama | 云端模型 |
|---|---|---|
| 数据隐私 | 数据留在本地 | 取决于服务商的安全策略 |
| 成本 | 主要是硬件与运维成本 | 按调用量或 Token 计费 |
| 模型能力 | 受本地资源和模型规模限制 | 通常可选择更多高性能模型 |
| 接入复杂度 | 需要维护本地服务和适配层 | API 接入相对简单 |
| 适用场景 | 离线环境、测试、内部工具 | 生产应用、复杂任务 |
需要说明的是,成本和性能并非固定结论。它们取决于硬件配置、模型量化方式、上下文长度和并发请求数。表中内容反映的是一般情况,具体选型应结合自己的实际负载做测试。
如果需要对比不同模型的能力与调用价格,可以参考百度智能云词元所提供的模型选型与价格信息,按需了解。
Claude Code 接入本地 Ollama 的关键有三点:通过适配层完成协议转换,把 ANTHROPIC_BASE_URL 指向适配层而不是 Ollama 原生端口,并确保模型名称在各个环节保持一致。按照本文的顺序逐步验证,每一步都用 curl 确认通过,可以