1. 为什么要在本地用 Ollama 跑 Claude CodeClaude Code 是 Anthropic 官方推出的终端编程助手它能直接读写项目文件、执行 shell 命令、自动修 Bug交互体验接近一个坐在你旁边的工程师。但官方订阅价格对个人开发者不算友好而且所有代码都要发到远端公司内部项目往往不允许。Ollama 从 0.15 版本开始兼容 Anthropic Messages API 协议这件事的意义在于Claude Code 客户端只认ANTHROPIC_BASE_URL这个环境变量只要有一个服务能按 Anthropic 的消息格式响应它就会把对方当成官方后端。于是我们可以让 Claude Code 把请求发给本地 Ollama用 Qwen2.5-Coder、DeepSeek、gpt-oss 这类开源模型完成日常的增删改查、脚本生成、MVP 搭建。这套方案适合三类人一是想零成本体验 Claude Code 工作流的个人开发者二是代码不能出内网、需要离线推理的团队三是本地算力有限、想通过 TaoToken 这类兼容 Anthropic 协议的网关把请求转发到云端模型的人。本文会先讲纯本地 Ollama 的配置再讲当本地模型扛不住复杂任务时如何把 Base URL 切到 TaoToken 的 API 通道形成本地优先、云端兜底的双通道结构。需要提前说明的是Ollama 默认监听http://localhost:11434Claude Code 需要的路径是/v1/messagesOllama 已经内置了这个端点不需要额外装反向代理。整个链路是Claude Code → HTTP 请求 → Ollama → 本地模型推理 → 返回 Anthropic 格式响应。理解这条链路后面排查问题会轻松很多。2. 前置准备Ollama 安装与 Claude Code 客户端2.1 安装 Ollama 并确认版本去 Ollama 官网下载对应平台的安装包Windows 是.exemacOS 是.dmgLinux 用一条脚本。装完后打开终端验证ollama --version # 输出参考ollama version is 0.15.2版本必须 ≥ 0.15.0低于这个版本没有 Anthropic Messages API 兼容层Claude Code 会直接报 404。如果你之前装过旧版先卸载再装新版或者用ollama update升级。2.2 拉取适合代码生成的模型模型选择直接决定体验。我实测下来20B 级别的模型在 16GB 内存的机器上能跑但速度一般7B 级别流畅但复杂逻辑容易翻车。推荐两个方向# 本地主力gpt-oss:20b平衡速度与代码质量 ollama pull gpt-oss:20b # 备选Qwen2.5-Coder 系列中文注释友好 ollama pull qwen2.5-coder:7b # 复杂任务可临时调用云端大模型Ollama 提供一定免费额度 ollama pull qwen3-coder:480b-cloud拉取完成后用ollama list确认模型已在本地。注意模型文件动辄几个 GB磁盘空间要留够。2.3 安装 Claude Code 客户端Windows PowerShell 里直接跑官方安装脚本irm https://claude.ai/install.ps1 | iexmacOS 和 Linux 用 npm 更省事npm install -g anthropic-ai/claude-code装完后如果终端提示claude: command not found说明安装目录没进 PATH。Windows 下通常是%USERPROFILE%\.local\bin手动加进系统环境变量再重开终端即可。这一步踩坑的人最多别急着怀疑安装失败。2.4 启动 Ollama 服务并确认端口Ollama 安装后一般会作为后台服务自动运行。手动确认# 检查服务是否在监听 curl http://localhost:11434/api/tags如果返回模型列表的 JSON说明服务正常。如果连接被拒绝手动启动# Linux/macOS ollama serve # Windows 服务未启动时重新打开 Ollama 应用即可默认端口 11434如果被占用可以改OLLAMA_HOST环境变量但改完记得同步修改 Claude Code 的 Base URL。3. 可复制配置Base URL 与 Key 的完整片段这一节是全文核心配置写错一个字都跑不通。Claude Code 读取三个环境变量ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY。本地 Ollama 不校验 Key随便填一个非空字符串即可但变量必须存在否则客户端会报鉴权错误。3.1 纯本地 Ollama 配置PowerShell# 指向本地 Ollama 服务 $env:ANTHROPIC_BASE_URL http://localhost:11434 # 伪造令牌Ollama 不校验但变量不能为空 $env:ANTHROPIC_AUTH_TOKEN ollama $env:ANTHROPIC_API_KEY none # 启动并指定本地模型 claude --model gpt-oss:20b3.2 纯本地 Ollama 配置bash/zshexport ANTHROPIC_BASE_URLhttp://localhost:11434 export ANTHROPIC_AUTH_TOKENollama export ANTHROPIC_API_KEYnone claude --model gpt-oss:20b3.3 切换到 TaoToken 通道的配置当本地模型处理不了复杂重构或者你人在外面用笔记本、本地没跑 Ollama 时把 Base URL 换成 TaoToken 的 API 地址即可其余变量结构不变export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的 TaoToken API Key export ANTHROPIC_API_KEY你的 TaoToken API Key claude --model claude-sonnet-4-5Key 在 TaoToken 控制台的 API Keys 页面生成模型 ID 用官方命名即可。这套配置的好处是本地和云端共用同一份 Claude Code 客户端只切换环境变量工作流完全一致。3.4 用 settings.json 固化配置每次开终端都 export 太麻烦Claude Code 支持项目级配置文件。在项目根目录建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:11434, ANTHROPIC_AUTH_TOKEN: ollama, ANTHROPIC_API_KEY: none }, model: gpt-oss:20b }如果要走 TaoToken把ANTHROPIC_BASE_URL改成https://taotoken.net/api两个 Key 字段填真实 Keymodel改成对应模型 ID。这个文件可以提交到团队仓库新人 clone 下来就能用省去口口相传的配置成本。注意.claude/settings.json里的 Key 是明文走 TaoToken 时建议用.claude/settings.local.json并加进.gitignore避免密钥泄露。3.5 三件套对照表场景Base URLKeyModel ID本地 Ollamahttp://localhost:11434ollama任意非空gpt-oss:20bTaoToken 云端https://taotoken.net/api控制台生成的 Keyclaude-sonnet-4-5远程 Ollamahttp://你的服务器IP:11434ollamaqwen2.5-coder:7b三件套缺一不可尤其是 Model ID写错会直接报模型不存在。4. 验证请求一条命令确认链路走通配置写完别急着开干先用最小请求验证链路。Claude Code 本身没有 ping 命令但我们可以直接对 Base URL 发一条 Anthropic 格式的请求看返回结构对不对。4.1 用 curl 直接打 Ollama 的 messages 端点curl http://localhost:11434/v1/messages \ -H Content-Type: application/json \ -H x-api-key: ollama \ -H anthropic-version: 2023-06-01 \ -d { model: gpt-oss:20b, max_tokens: 128, messages: [ {role: user, content: 用一句话说明什么是递归} ] }如果返回 JSON 里带content字段和模型生成的文本说明 Ollama 的 Anthropic 兼容层工作正常。如果返回 404检查 Ollama 版本返回 401检查x-api-key头是否带上。4.2 用 Claude Code 做端到端验证环境变量设好后进入一个空目录直接启动claude --model gpt-oss:20b进去后输入一句简单指令比如帮我写一个打印当前时间的 Python 脚本。观察两件事一是终端有没有正常流式输出二是它有没有真的去创建文件。如果它回复需要先初始化 Git说明工具链联动已经生效回一句帮我初始化即可。4.3 验证 TaoToken 通道切换 Base URL 后重复上面的 curl把地址换成https://taotoken.net/api/v1/messagesKey 换成真实 Keycurl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: 你的Key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5, max_tokens: 128, messages: [{role: user, content: 回复 OK}] }返回正常文本就说明通道打通。这一步能帮你把客户端配置问题和服务端问题彻底分开排障效率翻倍。4.4 实测一个完整任务我试过让本地 gpt-oss:20b 写一个单文件看板应用需求是新增任务、拖拽换位、LocalStorage 持久化。它把 HTML/CSS/JS 全写在一个文件里dragstart 和 drop 监听逻辑都补上了还主动执行了打开浏览器的命令。复杂逻辑上确实不如云端大模型但日常脚本和 CRUD 完全够用。5. 常见报错排查401、proxy failed、reading choices配置过程中最容易撞的几个坑我按报错原文整理成对照表遇到直接查。5.1 401 UnauthorizedAPI Error: 401 {type:error,error:{type:authentication_error}}原因通常是ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY为空。Ollama 虽然不校验但 Claude Code 客户端在发请求前会检查变量是否存在为空直接本地拦截。解决两个变量都设成非空字符串本地填ollama走 TaoToken 填真实 Key。5.2 local proxy failed / connection refusedError: connect ECONNREFUSED 127.0.0.1:11434Ollama 服务没起来或者端口不是 11434。先curl http://localhost:11434/api/tags确认连不上就手动ollama serve。如果改过OLLAMA_HOSTBase URL 要同步改。Windows 上还有一种情况是 Ollama 应用没启动托盘图标里点一下即可。5.3 reading choices of undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错说明客户端收到了 OpenAI 格式的响应但 Claude Code 期望 Anthropic 格式。常见于 Base URL 指向了只支持 OpenAI 协议的端点。解决确认地址是http://localhost:11434Ollama 的 Anthropic 兼容端点或https://taotoken.net/api不要指向/v1/chat/completions这类 OpenAI 路径。5.4 OAuth 相关报错OAuth error: invalid_grantClaude Code 启动时会尝试走官方 OAuth 流程如果检测到ANTHROPIC_BASE_URL被改写但仍残留官方登录态会报这个错。解决清掉~/.claude下的凭据缓存或者用claude logout退出官方账号让客户端完全走环境变量指定的通道。5.5 模型不存在model xxx not foundModel ID 拼写错误或者模型没拉取。ollama list看本地有什么ollama pull补拉。走 TaoToken 时确认模型 ID 与控制台文档一致。5.6 响应极慢或超时本地模型推理速度取决于显存和内存。20B 模型在纯 CPU 上跑首 token 可能要等十几秒。可以换更小的模型或者把max_tokens调低。如果走 TaoToken 还慢检查本地网络到网关的连通性。排障顺序建议先 curl 打 Base URL 确认服务端再启动 Claude Code 确认客户端最后看模型 ID。三层分开定位比盲目改配置快得多。6. 本地与云端双通道的长期用法纯本地方案的优势是零成本和数据不出内网但本地模型在复杂重构、长上下文推理上确实有天花板。我的做法是保留两套环境变量用 shell 别名快速切换# ~/.bashrc 或 ~/.zshrc alias cc-localANTHROPIC_BASE_URLhttp://localhost:11434 ANTHROPIC_AUTH_TOKENollama ANTHROPIC_API_KEYnone claude --model gpt-oss:20b alias cc-cloudANTHROPIC_BASE_URLhttps://taotoken.net/api ANTHROPIC_AUTH_TOKEN$TAOTOKEN_KEY ANTHROPIC_API_KEY$TAOTOKEN_KEY claude --model claude-sonnet-4-5日常改 Bug、写脚本用cc-local遇到需要深度推理的任务切cc-cloud。TaoToken 的 Coding Plan 适合长期高频编码场景按量计费比订阅制灵活具体额度在控制台能看到。如果你想把本地 Ollama 暴露给团队用可以在内网服务器上跑 Ollama把 Base URL 指向那台机器的 IP团队成员共用一份算力比每人本地跑一份模型省资源。配置这件事跑通一次之后就是复制粘贴。真正花时间的是模型选型和提示词调优那部分只能靠实际项目慢慢磨。先把链路打通剩下的交给日常使用去验证。