Claude Code 接入本地 Ollama 完整指南

作者:4042026.11.17 03:37浏览量:0

简介:本文讲清 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.js 18 或更高版本,npm 可以正常使用。
  • Python 3.9 或更高版本,用于安装 LiteLLM。
  • Ollama 已安装并处于运行状态。
  • 端口 11434 和 4000 没有被其他程序占用。

可以用下面的命令检查环境:

  1. node --version
  2. npm --version
  3. python3 --version
  4. ollama --version
  5. curl http://localhost:11434

如果 Ollama 没有运行,执行 ollama serve 启动服务。curl http://localhost:11434 正常时会返回 Ollama is running。如果返回连接失败,先处理服务启动问题,再继续后面的步骤。

三、安装 Claude Code 并拉取编码模型

安装 Claude Code:

  1. npm install -g @anthropic-ai/claude-code@latest
  2. claude --version

拉取代码模型并确认已下载:

  1. ollama pull qwen2.5-coder:7b
  2. ollama list

qwen2.5-coder:7b 的默认量化版本约占 4.7 GB 磁盘空间。运行时建议至少有 8 GB 可用内存或显存。如果机器配置较低,可以改用 qwen2.5-coder:3b,响应更快,但代码质量会下降。模型越大,对硬件的要求越高,选型时应同时考虑显存、内存和响应速度。

四、安装 LiteLLM 适配层

使用 pip 安装 LiteLLM 代理组件:

  1. pip install 'litellm[proxy]'

在工作目录下创建配置文件 litellm_config.yaml:

  1. model_list:
  2. - model_name: claude-local
  3. litellm_params:
  4. model: ollama/qwen2.5-coder:7b
  5. api_base: http://localhost:11434

这里有两个名字需要区分。model_name 是 Claude Code 中使用的名称,本例为 claude-local。model 是 Ollama 中的真实模型名,必须带有 ollama/ 前缀,并与 ollama list 显示的名称一致。

启动适配层:

  1. litellm --config litellm_config.yaml --port 4000

启动后,在另一个终端中用 curl 验证 Anthropic 格式的请求能否正常返回:

  1. curl http://localhost:4000/v1/messages \
  2. -H "content-type: application/json" \
  3. -H "x-api-key: sk-local" \
  4. -H "anthropic-version: 2023-06-01" \
  5. -d '{"model":"claude-local","max_tokens":256,"messages":[{"role":"user","content":"用一句话解释闭包"}]}'

如果返回了包含模型回答的 JSON,说明链路已经打通。如果返回 404,检查请求路径是否为 /v1/messages。如果返回模型不存在的错误,检查配置文件中的 model_name 和 model 是否正确。

五、配置 Claude Code 指向适配层

配置时,ANTHROPIC_BASE_URL 应指向适配层地址 http://localhost:4000,不能再写 11434:

  1. export ANTHROPIC_BASE_URL=http://localhost:4000
  2. export ANTHROPIC_AUTH_TOKEN=sk-local
  3. claude --model claude-local

ANTHROPIC_AUTH_TOKEN 在本地场景中只是占位值,适配层没有设置主密钥时不会校验它。

这里要注意作用域。把变量写入 ~/.zshrc 或 ~/.bashrc 后,所有读取 Anthropic 环境变量的工具都会受影响,包括其他 SDK 脚本和 CLI 工具。更稳妥的做法是只在特定项目中生效。例如使用 direnv,在项目目录下创建 .envrc 文件并写入上述变量,进入该目录时自动加载,离开时自动失效。如果只是临时测试,直接在当前终端中 export 即可,关闭终端后变量会失效。

六、代理导致连接失败的处理方法

配置完成后如果出现 API Error: Connection error,常见原因是系统代理把 localhost 的请求转发到了代理服务器。可以临时清除代理变量:

  1. unset http_proxy
  2. unset https_proxy

也可以让本地地址绕过代理:

  1. export no_proxy=localhost,127.0.0.1

no_proxy 的方式比清除代理更安全,因为它只影响本地地址,不影响其他外部请求。如果你已经用 unset 清除了代理,完成本地测试后要恢复代理设置,否则后续访问外部网络的命令可能失败。恢复时重新执行原来的设置,例如 export https_proxy=你原来的代理地址,或直接打开新终端。

如果清除代理后仍然失败,依次检查 Ollama 和 LiteLLM 是否在运行、端口是否被占用,以及 Claude Code 是否读取到了正确的环境变量。

七、用 SDK 调用本地模型

如果需要把本地模型嵌入自动化脚本、代码审查工具或内部 Agent 流程,可以直接使用 Anthropic Python SDK。请求地址指向适配层,并禁用环境代理:

  1. import anthropic
  2. import httpx
  3. client = anthropic.Anthropic(
  4. base_url="http://localhost:4000",
  5. api_key="sk-local",
  6. http_client=httpx.Client(trust_env=False),
  7. )
  8. with client.messages.stream(
  9. model="claude-local",
  10. max_tokens=1024,
  11. messages=[{"role": "user", "content": "写一个 Python 快速排序函数"}],
  12. ) as stream:
  13. for text in stream.text_stream:
  14. print(text, end="", flush=True)

如果不需要 Anthropic 的接口格式,也可以直接调用 Ollama 的 Python 库,少一层转发:

  1. import ollama
  2. client = ollama.Client(host="http://localhost:11434")
  3. resp = client.chat(
  4. model="qwen2.5-coder:7b",
  5. messages=[{"role": "user", "content": "写一个 Python 快速排序函数"}],
  6. )
  7. 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,确认两个服务都在运行。
  • 请求路径错误:Anthropic 格式的请求路径必须是 /v1/messages。直接访问 11434 会得到与 Claude Code 协议不匹配的结果。
  • 请求被代理拦截:执行 unset http_proxy 和 unset https_proxy,或设置 no_proxy。SDK 中可通过 trust_env=False 禁用环境代理。
  • 响应过慢:使用 ollama ps 查看模型是否已加载,以及是否有部分层运行在 CPU 上。如果资源不足,换用更小参数量的模型。
  • 输出质量不稳定:代码任务优先选择代码专用模型,并在提示词中明确输出格式和语言要求。
  • 工具调用失败或中途停止:Claude Code 依赖模型的工具调用能力来读写文件和执行命令。小参数量的本地模型在这方面往往不稳定。遇到此类问题,可以换用明确支持工具调用的模型,或改用更大的模型。

九、本地 Ollama 与云端模型如何选

本地 Ollama 的优势是数据留在本机、可以离线运行,并且没有按调用量计费的 Token 开销。不足是模型能力、推理速度和上下文长度受本地硬件限制。云端模型通常在复杂推理、长上下文和服务稳定性方面更强,更适合生产环境和高难度的编码任务。

维度 本地 Ollama 云端模型
数据隐私 数据留在本地 取决于服务商的安全策略
成本 主要是硬件与运维成本 按调用量或 Token 计费
模型能力 受本地资源和模型规模限制 通常可选择更多高性能模型
接入复杂度 需要维护本地服务和适配层 API 接入相对简单
适用场景 离线环境、测试、内部工具 生产应用、复杂任务

需要说明的是,成本和性能并非固定结论。它们取决于硬件配置、模型量化方式、上下文长度和并发请求数。表中内容反映的是一般情况,具体选型应结合自己的实际负载做测试。

如果需要对比不同模型的能力与调用价格,可以参考百度智能云词元所提供的模型选型与价格信息,按需了解。

十、总结

Claude Code 接入本地 Ollama 的关键有三点:通过适配层完成协议转换,把 ANTHROPIC_BASE_URL 指向适配层而不是 Ollama 原生端口,并确保模型名称在各个环节保持一致。按照本文的顺序逐步验证,每一步都用 curl 确认通过,可以