logo

Claude Code 接入本地 Ollama 的 3 种实操方案

作者:梅琳marlin2026.11.17 03:41浏览量:0

简介:本文围绕 Claude Code 接入本地 Ollama 的协议差异,给出 claude-code-router、LiteLLM、换用 OpenAI 兼容 Agent 三种方案。内容包含前置条件、安装命令、num_ctx 调优、显存估算、环境变量与排障清单,并附 FAQ,帮助读者快速跑通或选择本地与云端混合架构。

一、结论:为什么 Claude Code 不能直接连 Ollama

很多人第一次尝试 Claude Code 接入本地模型时,会把 ANTHROPIC_BASE_URL 直接设置成 http://localhost:11434,但通常无法跑通。原因并不在于 Ollama 不能提供模型,而是协议格式不一致。

Claude Code 默认发送的是 Anthropic Messages API 格式请求,核心入口通常是 POST /v1/messages。而 Ollama 对外暴露的接口主要是原生 /api/chat,以及 OpenAI 兼容的 /v1/chat/completions。两者在请求体结构、消息格式、工具调用格式、流式 SSE 事件类型上都有明显差异。

因此,接入本地 Ollama 时,通常有三条路径:

  1. 使用 claude-code-router 做 Anthropic 到 OpenAI 的协议转换。
  2. 使用 LiteLLM 作为统一网关,同时暴露 Anthropic 格式入口。
  3. 放弃 Claude Code,改用原生支持 OpenAI 兼容协议的 Coding Agent,例如 Cline、Roo Code、OpenCode。

本文会给出这三种方案的完整操作步骤,并补充前置条件、显存估算、参数验证和常见问题排查。

二、前置条件:先准备这些环境

在开始之前,建议先确认以下条件:

  • 已安装 Claude Code,并能正常启动。本文假设 Claude Code 由读者自行安装配置。
  • 已安装 Ollama。
  • 如果 Ollama 已经作为系统服务常驻运行,不需要再手动执行 ollama serve。
  • 如果选择 claude-code-router,需要 Node.js 环境。
  • 如果选择 LiteLLM,需要 Python 环境。
  • 显卡显存要足够加载模型,并为上下文缓存预留空间。

不同版本的 Claude Code、Ollama、claude-code-router、LiteLLM 在命令和配置字段上可能略有差异。如果实际执行结果与本文不一致,建议以对应工具的官方文档为准。

三、启动 Ollama,并选择合适的本地模型

如果还没有拉取模型,可以先执行:

  1. ollama list
  2. ollama pull qwen2.5-coder:32b
  3. ollama run qwen2.5-coder:32b

如果 Ollama 尚未启动,可以执行:

  1. ollama serve

但如果系统服务已经在后台运行 Ollama,则不需要重复执行该命令。

Claude Code 与普通聊天工具不同,它需要模型理解系统提示词、工具定义、文件路径、命令输出和多轮上下文。因此,模型选型不能只看“能不能聊天”,还要看工具调用能力和上下文长度。

以下显存数据为 Q4 量化场景下的粗略估算,仅用于单请求、无并发、未考虑系统开销的情况,实际占用会受模型打包方式、上下文长度、显卡驱动和量化实现影响。

模型 Q4 显存参考 说明
qwen2.5-coder:14b 约 8~10 GB 适合入门验证,工具调用能力弱于更大模型
qwen3-coder:30b 约 16~20 GB 可作为单卡较强候选,需关注实际上下文占用
qwen2.5-coder:32b 权重约 18~20 GB 长上下文场景总占用通常更高
gpt-oss:20b 约 12 GB 可作为中等规模候选,具体以实际模型为准
llama3.1:70b 约 40 GB 以上 消费级单卡通常较吃力,更适合多卡环境

对于 Claude Code 这类工具型 Agent,7B 级别模型在生成工具调用参数、修改文件、执行命令时容易出现格式错误或遗漏字段。更稳妥的做法是从 14B 或更高规模模型开始测试。

四、为什么接入后模型答非所问?先调 num_ctx

在协议转换正确的前提下,如果 Claude Code 接入本地 Ollama 后出现回答混乱、工具调用失败、文件内容编造、上下文丢失等情况,常见原因之一是上下文窗口被截断。

Claude Code 的系统提示词、工具定义、历史消息和当前任务会占用大量 Token。Ollama 默认上下文窗口通常较小,如果 num_ctx 没有调大,模型可能只看到部分内容,从而产生异常行为。

可以用 Modelfile 固化一个长上下文版本:

  1. FROM qwen2.5-coder:32b
  2. PARAMETER num_ctx 32768
  3. PARAMETER temperature 0.2

然后创建自定义模型:

  1. ollama create qwen2.5-coder-32k -f Modelfile

创建完成后,可以用以下命令验证参数是否生效:

  1. ollama show qwen2.5-coder-32k

重点查看 num_ctx 是否已经变成 32768。

也可以使用:

  1. ollama ps

观察模型是否已加载、实际占用多少显存、是否频繁卸载重载。如果显存接近打满,或者每次请求后模型都重新加载,说明当前配置可能超出显卡承载能力。

显存估算示例

以 32B 级别模型、Q4 量化、32768 上下文为例:

  • 模型权重大致占用 18~20 GB。
  • KV Cache 会随上下文长度增长,32768 上下文通常需要额外预留数 GB。
  • 综合考虑后,实际占用可能在 22~26 GB 左右。

这个估算是经验性范围,不是精确测量值,实际结果取决于模型结构、量化格式、注意力机制和上下文长度。

如果显卡只有 24 GB,建议不要一开始就把 num_ctx 拉到 32768。可以优先尝试 16384,或者改用更小的模型。若开启长上下文后出现模型无法加载、响应变慢或频繁卸载,应降低 num_ctx。

另外,可以设置以下环境变量减少模型频繁卸载,并避免多请求抢占显存:

  1. export OLLAMA_KEEP_ALIVE=30m
  2. export OLLAMA_NUM_PARALLEL=1

需要注意,这两个变量需要设置在 Ollama 服务实际运行的环境中。如果 Ollama 由 systemd、Docker 或桌面服务托管,需要把变量写入对应服务配置。设置 OLLAMA_NUM_PARALLEL=1 后,并发请求会排队,不适合作为高并发方案。

五、三种方案怎么选?

方案 是否需要额外部署 是否适合多模型路由 调试成本
claude-code-router 需要 Node.js 和路由配置 可做基础多 Provider 配置 较低
LiteLLM 需要 Python 网关服务 更适合统一管理和后续扩展 中等
换用 OpenAI 兼容 Agent 不需要协议转换层 通常不支持复杂降级路由 较低

如果你的目标是尽快让 Claude Code 连上本地 Ollama,优先尝试 claude-code-router。如果后续还要接入多家云端模型,LiteLLM 更合适。如果不想折腾协议转换,可以直接换用支持 OpenAI 兼容协议的 Agent。

六、方案一:claude-code-router

claude-code-router 是社区维护的路由工具,常用于 Claude Code 接入非 Anthropic 模型。它需要 Node.js 环境。

安装命令:

  1. npm install -g @musistudio/claude-code-router

配置文件通常位于:

  1. ~/.claude-code-router/config.json

示例配置:

  1. {
  2. "LOG": true,
  3. "Providers": [
  4. {
  5. "name": "ollama",
  6. "api_base_url": "http://127.0.0.1:11434/v1/chat/completions",
  7. "api_key": "ollama",
  8. "models": ["qwen2.5-coder-32k"]
  9. }
  10. ],
  11. "Router": {
  12. "default": "ollama,qwen2.5-coder-32k",
  13. "background": "ollama,qwen2.5-coder-32k",
  14. "think": "ollama,qwen2.5-coder-32k",
  15. "longContext": "ollama,qwen2.5-coder-32k",
  16. "webSearch": "ollama,qwen2.5-coder-32k"
  17. }
  18. }

配置完成后,用以下命令启动:

  1. ccr code

这里的 Router 配置包含多个槽位:

  • default:主对话模型。
  • background:后台小任务模型。
  • think:思考模式模型。
  • longContext:长上下文模型。
  • webSearch:联网搜索相关模型。

本地部署初期,最稳妥的做法是所有槽位先指向同一个模型,等链路稳定后再区分不同任务。

七、方案二:用 LiteLLM 做统一网关

LiteLLM 可以同时提供 OpenAI 兼容接口,也支持通过配置暴露 Anthropic 格式入口。适合后续需要接入多个模型、做统一鉴权和统一路由的场景。

先安装 LiteLLM Proxy:

  1. pip install 'litellm[proxy]'

配置文件示例:

  1. model_list:
  2. - model_name: qwen2.5-coder-32k
  3. litellm_params:
  4. model: ollama_chat/qwen2.5-coder-32k
  5. api_base: http://127.0.0.1:11434

这里 model_name 需要和后续 ANTHROPIC_MODEL 保持一致,否则 Claude Code 侧可能找不到模型。

启动 LiteLLM:

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

然后设置 Claude Code 环境变量:

  1. export ANTHROPIC_BASE_URL=http://127.0.0.1:4000
  2. export ANTHROPIC_AUTH_TOKEN=sk-anything
  3. export ANTHROPIC_MODEL=qwen2.5-coder-32k
  4. export ANTHROPIC_SMALL_FAST_MODEL=qwen2.5-coder-32k
  5. claude

如果修改了 LiteLLM 的 model_list,通常需要重启 LiteLLM 进程,否则新模型可能不会被加载。

LiteLLM 的优势是后续接入云端模型时,不需要改动 Claude Code 太多配置,可以在网关层统一管理模型名称、路由和鉴权。

agent">八、方案三:换用原生支持 OpenAI 兼容协议的 Agent

如果不想维护协议转换层,也可以直接使用支持 OpenAI 兼容协议的 Coding Agent,例如 Cline、Roo Code、OpenCode。

配置时通常只需要三项:

  • Base URL:填写到 /v1 为止,例如 http://localhost:11434/v1
  • API Key:本地 Ollama 可填写任意占位值
  • Model:填写 Ollama 中实际存在的模型名,例如 qwen2.5-coder-32k

如果本地模型不是用 Ollama 启动,而是用 vLLM 等推理服务启动,只要其提供标准 OpenAI 兼容接口,也可以按类似方式填写。

这种方案的好处是不需要额外部署协议转换层,调试路径更短。但需要注意,所谓“零转换损耗”只是指协议层少了一层转换,并不意味着模型能力会自动提升。工具调用、文件编辑、代码理解能力仍然取决于本地模型本身。

九、Claude Code 侧环境变量调优

接入成功后,还可以调整 Claude Code 相关环境变量,以适应本地模型速度较慢的特点:

  1. export ANTHROPIC_MODEL=qwen2.5-coder-32k
  2. export ANTHROPIC_SMALL_FAST_MODEL=qwen2.5-coder-32k
  3. export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
  4. export API_TIMEOUT_MS=600000
  5. export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

其中:

  • ANTHROPIC_MODEL:指定主模型。
  • ANTHROPIC_SMALL_FAST_MODEL:指定轻量任务模型。
  • CLAUDE_CODE_MAX_OUTPUT_TOKENS:控制输出长度,长代码生成时可适当调大。
  • API_TIMEOUT_MS:本地推理通常比云端慢,超时时间要放大,否则容易中断。
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC:减少非必要流量,例如遥测或自动更新检查。

如果使用的是 LiteLLM,上述 ANTHROPIC_MODEL 必须与 LiteLLM 配置中的 model_name 一致。

十、常见问题排查

1. 404 或 not found

常见原因是地址写错。使用 claude-code-router 时,配置中的 api_base_url 通常需要写到完整 OpenAI 接口路径,例如 /v1/chat/completions。不要把 Claude Code 的 ANTHROPIC_BASE_URL 直接指向 Ollama 的 /v1/messages。

使用 LiteLLM 时,ANTHROPIC_BASE_URL 一般填写 LiteLLM 服务根地址,例如:

  1. http://127.0.0.1:4000

不要再额外拼接 /v1/messages。

2. LiteLLM 报模型不存在

如果日志中出现类似 model not found 的错误,优先检查:

  • ANTHROPIC_MODEL 是否与 LiteLLM 的 model_name 完全一致。
  • LiteLLM 配置文件是否已经重新加载。
  • 是否需要重启 LiteLLM 进程。

例如配置中是 qwen2.5-coder-32k,那么 Claude Code 侧也应该使用 qwen2.5-coder-32k。

3. 工具调用失败或模型乱写文件

这通常是模型工具调用能力不足。解决方向包括:

  • 换用 14B 或更大规模模型。
  • 降低单次任务复杂度。
  • 减少一次性输入的文件数量。
  • 使用更稳定的代码模型,例如 qwen2.5-coder 系列。

4. 回答被截断或上下文丢失

优先检查 num_ctx:

  1. ollama show qwen2.5-coder-32k

确认上下文是否已经调整。如果显卡显存不足,不要盲目拉大 num_ctx,可以先尝试 16384,或换用更小模型。

5. 响应越来越慢

可以查看:

  1. ollama ps

如果显存接近打满、模型频繁卸载重载,说明当前配置可能超出显卡能力。可以尝试:

  • 降低 num_ctx。
  • 使用更小的量化版本。
  • 使用更小参数模型。
  • 关闭其他占用显存的程序。
  • 使用 OLLAMA_NUM_PARALLEL=1 避免并发抢占。

6. 出现 429 报错

本地 Ollama 通常不应该出现 429。如果出现,需要检查请求是否实际打到了云端,或者代理配置是否错误生效。

十一、什么时候应该考虑本地与云端混合

本地模型的隐性成本经常被低估,包括显卡折旧、电费、散热、维护成本,以及为了节省显存而降低模型规模后带来的效果损失。

如果任务只是日常探索、小范围代码修改、格式转换或简单问答,本地模型可以降低成本。但如果需要稳定处理大型仓库、多轮长链路重构、复杂依赖分析,本地小模型和云端旗舰模型之间仍可能有明显差距。

更现实的方案是混合架构:简单任务走本地模型,复杂任务路由到云端强模型。这样既能控制成本,也能保留高难度任务的处理能力。

十二、FAQ

Claude Code 能直连 Ollama 吗?

不能直接稳定跑通。Claude Code 默认使用 Anthropic Messages API,而 Ollama 主要提供原生接口和 OpenAI 兼容接口,通常需要中间转换层,或者改用支持 OpenAI 兼容协议的 Agent。

显存不够怎么办?

可以降低 num_ctx,例如从 32768 降到 16384;也可以换更小的模型、使用更低量化级别,或者把任务迁移到云端模型。

num_ctx 越大越好吗?

不是。更大的上下文会占用更多显存,也可能降低推理速度。应根据实际任务需要选择,通常 16384 或 32768 已经能覆盖多数本地编码场景。

为什么修改 LiteLLM 配置后没生效?

检查配置文件路径是否正确、LiteLLM 是否启动成功,并在修改 model_list 后重启 LiteLLM 服务。

本地模型可以完全替代云端模型吗?

取决于任务难度。简单任务通常可以,但复杂代码理解、长链路重构和高可靠工具调用仍可能依赖更强模型。

相关产品(推广/广告)

如果需要在本地模型与云端模型之间做选型、价格或能力对比,可以查看百度智能云词元所(Token Exchange):https://cloud.baidu.com/product-s/token_exchange.html?from=article 。本文仅作技术信息参考,不构成采购建议。

发表评论

活动