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 时,通常有三条路径:
- 使用
claude-code-router做 Anthropic 到 OpenAI 的协议转换。 - 使用 LiteLLM 作为统一网关,同时暴露 Anthropic 格式入口。
- 放弃 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,并选择合适的本地模型
如果还没有拉取模型,可以先执行:
ollama listollama pull qwen2.5-coder:32bollama run qwen2.5-coder:32b
如果 Ollama 尚未启动,可以执行:
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 固化一个长上下文版本:
FROM qwen2.5-coder:32bPARAMETER num_ctx 32768PARAMETER temperature 0.2
然后创建自定义模型:
ollama create qwen2.5-coder-32k -f Modelfile
创建完成后,可以用以下命令验证参数是否生效:
ollama show qwen2.5-coder-32k
重点查看 num_ctx 是否已经变成 32768。
也可以使用:
ollama ps
观察模型是否已加载、实际占用多少显存、是否频繁卸载重载。如果显存接近打满,或者每次请求后模型都重新加载,说明当前配置可能超出显卡承载能力。
显存估算示例
以 32B 级别模型、Q4 量化、32768 上下文为例:
- 模型权重大致占用 18~20 GB。
- KV Cache 会随上下文长度增长,32768 上下文通常需要额外预留数 GB。
- 综合考虑后,实际占用可能在 22~26 GB 左右。
这个估算是经验性范围,不是精确测量值,实际结果取决于模型结构、量化格式、注意力机制和上下文长度。
如果显卡只有 24 GB,建议不要一开始就把 num_ctx 拉到 32768。可以优先尝试 16384,或者改用更小的模型。若开启长上下文后出现模型无法加载、响应变慢或频繁卸载,应降低 num_ctx。
另外,可以设置以下环境变量减少模型频繁卸载,并避免多请求抢占显存:
export OLLAMA_KEEP_ALIVE=30mexport 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 环境。
安装命令:
npm install -g @musistudio/claude-code-router
配置文件通常位于:
~/.claude-code-router/config.json
示例配置:
{"LOG": true,"Providers": [{"name": "ollama","api_base_url": "http://127.0.0.1:11434/v1/chat/completions","api_key": "ollama","models": ["qwen2.5-coder-32k"]}],"Router": {"default": "ollama,qwen2.5-coder-32k","background": "ollama,qwen2.5-coder-32k","think": "ollama,qwen2.5-coder-32k","longContext": "ollama,qwen2.5-coder-32k","webSearch": "ollama,qwen2.5-coder-32k"}}
配置完成后,用以下命令启动:
ccr code
这里的 Router 配置包含多个槽位:
default:主对话模型。background:后台小任务模型。think:思考模式模型。longContext:长上下文模型。webSearch:联网搜索相关模型。
本地部署初期,最稳妥的做法是所有槽位先指向同一个模型,等链路稳定后再区分不同任务。
七、方案二:用 LiteLLM 做统一网关
LiteLLM 可以同时提供 OpenAI 兼容接口,也支持通过配置暴露 Anthropic 格式入口。适合后续需要接入多个模型、做统一鉴权和统一路由的场景。
先安装 LiteLLM Proxy:
pip install 'litellm[proxy]'
配置文件示例:
model_list:- model_name: qwen2.5-coder-32klitellm_params:model: ollama_chat/qwen2.5-coder-32kapi_base: http://127.0.0.1:11434
这里 model_name 需要和后续 ANTHROPIC_MODEL 保持一致,否则 Claude Code 侧可能找不到模型。
启动 LiteLLM:
litellm --config config.yaml --port 4000
然后设置 Claude Code 环境变量:
export ANTHROPIC_BASE_URL=http://127.0.0.1:4000export ANTHROPIC_AUTH_TOKEN=sk-anythingexport ANTHROPIC_MODEL=qwen2.5-coder-32kexport ANTHROPIC_SMALL_FAST_MODEL=qwen2.5-coder-32kclaude
如果修改了 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 相关环境变量,以适应本地模型速度较慢的特点:
export ANTHROPIC_MODEL=qwen2.5-coder-32kexport ANTHROPIC_SMALL_FAST_MODEL=qwen2.5-coder-32kexport CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192export API_TIMEOUT_MS=600000export 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 服务根地址,例如:
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:
ollama show qwen2.5-coder-32k
确认上下文是否已经调整。如果显卡显存不足,不要盲目拉大 num_ctx,可以先尝试 16384,或换用更小模型。
5. 响应越来越慢
可以查看:
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 。本文仅作技术信息参考,不构成采购建议。

登录后可评论,请前往 登录 或 注册