用本地Ollama跑Claude Code：完整实战指南

想让AI编程助手接触你的项目，又不想把代码上传到云端？把 Claude Code 接到本地 Ollama 模型是一条可行路径。这篇教程覆盖 Windows CMD、PowerShell、Linux 和 macOS 四套环境，从装工具到跑通一个真实文件操作，全流程可复现。

为什么要把 Claude Code 指向本地模型

Claude Code 原本是 Anthropic 的命令行编程代理，默认调用托管在云端的模型。通过环境变量或 Ollama 官方集成，你可以把它指向 localhost:11434 上的本地推理服务。这样做的好处是代码和提示词不出本机，适合处理敏感项目或在无外网环境下做实验。

代价也很直接：本地模型的能力上限由你的硬件决定。原文作者的测试机是 Windows、8 GB 内存，这个配置基本决定了后文的体验基调。

第一步：安装 Ollama 与 Claude Code

Ollama 负责在本地跑模型。Windows 用户注意区分：PowerShell 可以执行 irm https://ollama.com/install.ps1 | iex，但 CMD 不行，需要在 ollama.com/download 下载安装包手动安装后重开 CMD。macOS 和 Linux 用 curl -fsSL https://ollama.com/install.sh | sh。

Claude Code 的安装同理，Windows 用 PowerShell 脚本，macOS/Linux 用 curl ... | bash。装完关闭终端再重开，运行 ollama --version 和 claude --version 确认两个命令都在 PATH 里。命令找不到，先重开终端，再检查安装是否完成。

第二步：下载并验证本地模型

作者选的是 qwen2.5:1.5b，理由很实在——8 GB 内存只能带得动小模型。用 ollama pull qwen2.5:1.5b 下载，首次需要联网，之后推理全在本地。

下载完用 ollama run qwen2.5:1.5b 跑一句简单提问确认能响应，输入 /bye 退出，再用 ollama list 核对已装模型。这一步别省，后面接 Claude Code 出问题时，你能快速判断是模型层还是连接层的问题。

模型名称里的 1.5b、7b 指的是参数量（billion，十亿），它直接决定模型对显存/内存的需求和推理速度。粗略估算，4-bit 量化的模型每十亿参数约占用 0.7–1 GB 内存，所以 1.5b 模型大致占用 1–2 GB，7b 则要 5–8 GB，再加上操作系统和 Claude Code 自身的开销，8 GB 内存的机器跑 7b 会很吃紧，这正是原文中 7b 版本“同样非常慢”的硬件原因。参数量也与能力相关：小模型在遵循复杂指令、输出结构化工具调用格式上更容易出错，这与正文中“工具调用格式错误”的观察一致。选模型时先看自己可用内存，再考虑能力上限，不要只看模型榜单分数。

第三步：两种方式把 Claude Code 接到 Ollama

原文明确给了两条路，并建议优先用 A，不要无必要地混用两套配置。

方式 A：Ollama 启动器（推荐）

一行命令搞定：

ollama launch claude --model qwen2.5-coder:1.5b

这是 Ollama 官方提供的 Claude Code 集成，会自动选好本地模型。如果提示 launch 不认识，说明 Ollama 版本太旧，用最新安装包更新后重开终端。

方式 B：环境变量手动连接

当方式 A 不奏效时，用环境变量把 Claude Code 指向 Ollama 的本地 API。核心是三个变量：ANTHROPIC_BASE_URL 设为 http://localhost:11434，ANTHROPIC_AUTH_TOKEN 设为 ollama，ANTHROPIC_API_KEY 置空，然后 claude --model qwen2.5-coder:1.5b 启动。

Windows CMD 用 set，PowerShell 用 $env:，Linux/macOS 用 export。这些变量只对当前终端会话生效，关掉就没了，下次要重新设。原文特别提醒：不要随手用 setx 做持久化，它影响的是未来会话而非当前窗口，容易造成排查困惑。

ANTHROPIC_BASE_URL 是 Claude Code（以及 Anthropic SDK）用来指定 API 端点根地址的变量，默认指向 Anthropic 云端。把它改成 http://localhost:11434 后，Claude Code 的请求就会发往本机 Ollama 的兼容接口。ANTHROPIC_AUTH_TOKEN 是随请求发送的鉴权令牌，本地 Ollama 不校验真实密钥，所以填任意占位值（如 ollama）即可通过客户端对“必须提供凭据”的检查；ANTHROPIC_API_KEY 置空是为了避免客户端优先使用云端密钥而造成混淆。这种做法的前提是 Ollama 提供了与 Anthropic Messages API 兼容的端点，因此服务必须处于运行状态，且端点路径要与客户端期望的一致——这也是连接报错时首先要检查 localhost:11434 是否可访问的原因。

第四步：跑一个真实文件操作来验收

配置对不对，不看终端有没有报错，看代理能不能真的干活。新建一个空目录 local-agent-demo 并进入，然后给代理一个边界清晰的任务：创建 hello.py，内容为 print("Hello from local Ollama")，展示文件内容并说明如何运行，不许改动其他文件。

代理跑完后必须人工核验：dir / Get-ChildItem / ls -la 看文件是否真的存在，type / Get-Content / cat 看内容是否一致，再实际执行 python hello.py 看输出。原文的立场很明确——文件存在且输出匹配才算成功，批准命令前先审一遍改动。

实测结论：能聊天，不等于能当代理

这是全文最有价值的部分。在 8 GB 内存的 Windows 机器上，qwen2.5-coder:1.5b 做基础对话可用，但没有稳定表现出可靠编程代理的行为：部分工具调用格式错误，整个工作流很慢。换 qwen2.5-coder:7b 测试，在这台机器上同样非常慢。

作者强调这只是单一环境的测试结果，不是通用基准。小模型能回答提示词，不代表它能驾驭代理的工具调用、多步任务和系统指令。这个区分很重要：很多教程把"接上了"当成"能用了"，实际差着一大截。

编程代理与聊天机器人本质区别在于“工具调用”（tool calling）：代理需要按约定格式输出结构化请求，例如“调用写文件工具，参数为路径和内容”，由运行环境执行后把结果回传给模型，再进入下一轮。这要求模型严格遵循 JSON Schema 一类的格式约束，并在多步任务中记住上下文与系统指令。小模型往往在这类格式上不稳定，出现参数缺失、字段名错误或混合自然语言输出，导致解析失败、任务中断。此外代理流程是串行的多轮推理，每轮都要重新处理完整上下文，在 CPU 推理的低速环境下，延迟会成倍累积——这正是“能聊天却跑不动工作流”的技术根源。

常见问题速查

• ollama 找不到：重开终端，不行就重装。
• claude 找不到：重开终端，对照官方安装步骤检查。
• ollama launch 找不到：更新 Ollama。
• 连接报错：确认 Ollama 在运行，手动方式下端点是 http://localhost:11434。
• 响应慢或工具调用出错：简化提示词、缩小任务范围、手动核验结果——模型可能太小，撑不起代理场景。

结论

Ollama 让 Claude Code 用本地模型做推理成为可能，全程不需要托管模型 API。但这次实测给出的关键教训是：本地执行不等于快速可靠。从小任务起步，每一步都人工验证，选你硬件真正带得动的模型。如果你的目标是日常可用的编程代理，硬件和模型规模的门槛恐怕比想象中更高。