遇到这个问题,我会先确认请求到底有没有到达本地服务,而不是急着改配置。Claude Code 默认面向 Anthropic 官方模型,本地 Ollama 提供的是 OpenAI 兼容接口,两者协议不同,中间缺一个转换层,很多配置看起来对,实际请求根本没发到本地。
判断Claude Code能否直接使用Ollama,不能只看文档。Claude Code本身为Anthropic模型设计,默认不感知本地服务,但可以通过环境变量覆盖API端点,例如设置ANTHROPIC_BASE_URL指向本地地址。关键问题在于Ollama提供的是OpenAI兼容接口,而Claude Code期望的是Anthropic的messages格式,二者并不天然匹配。一个简单的判断方法:设置环境变量后运行claude,如果返回认证错误或端点错误,说明兼容层不工作,需要额外增加转换代理。另一个判断点是确认所装的Claude Code版本是否支持自定义base URL,旧版本可能直接忽略该变量,导致请求仍然发往官方服务器。
实际操作时,我会把 ANTHROPIC_BASE_URL 指向本地端口,跑一句最简单的“hi”。如果很快报认证错误,说明请求发出去了,但格式不对;如果一直等不到回包,可能是流式输出未处理。这两种现象对应不同排查方向。
容易误判的地方
模型名映射和 API 密钥往往是第一个卡点。
常见的坑是模型名映射。Claude Code在请求中会带上模型名,例如claude-3-5-sonnet-20241022,而Ollama注册的是qwen2.5等名称。若兼容层不做映射,Ollama会返回模型不存在的错误。解决办法是在转换层配置一张映射表,把所有Claude模型名替换成本地模型名。另一个坑是API密钥。即便用本地模型,Claude Code也要求环境变量ANTHROPIC_API_KEY非空,否则启动即拒绝运行。但Ollama并不校验密钥,所以可以随意填一个假key,但不能留空。测试时可用curl请求本地兼容层,观察是否正常返回,以排除密钥问题。
还有一个容易漏掉的细节:Anthropic 请求体里的 tools 字段,Ollama 的 OpenAI 兼容接口会忽略,但本地模型如果没有工具调用相关训练,拿到该字段也不会正确响应。所以不要一看 HTTP 200 就认为成功,要看输出里是否真的执行了函数调用。
建议的处理顺序
先跑通再调优,顺序很重要。
实际使用中,建议先用Ollama拉取一个中等规模的模型,例如qwen2.5:7b,并启动本地服务。随后安装一个兼容层,比如使用FastAPI编写简单的请求转发服务,把Anthropic的请求转换为OpenAI格式后发给Ollama。更省事的做法是直接使用现成的开源路由器,将Claude Code的base URL指向该路由器的监听端口。检查是否成功时,可以执行一次简单的代码生成任务,观察输出是否正常。如果出现卡顿或错误,查看Claude Code的日志,默认位置在用户目录下的.claude文件夹。需要注意,转换服务必须支持流式输出,否则Claude Code会在等待回包时超时退出。
我的操作顺序是:先启动 Ollama 服务,再启动兼容层,最后设置环境变量。顺序反了会让排查变得困难。比如我曾把兼容层放在后面,结果 Claude Code 已把请求发给官方端点,日志里全是网络错误,浪费不少时间。
配置与命令示例
下面是一组最简环境变量,兼容层监听在 8080 端口:
export ANTHROPIC_BASE_URL="http://localhost:8080"
export ANTHROPIC_API_KEY="local-only-key"
export ANTHROPIC_MODEL="qwen2.5:7b"
注意,这个 ANTHROPIC_MODEL 变量是否生效取决于 Claude Code 版本,有的版本会强制用请求里的模型名。所以兼容层要准备一张映射表,把类似 claude-3-5-sonnet-20241022 的模型名替换成本地实际运行的模型。映射表通常是一份 JSON,键是 Claude 模型名,值是对应 Ollama 模型名,这只是个思路,具体字段要结合你用的兼容层确认。
验证方法
配置完成后,不要直接打开交互式对话,先用 curl 探测兼容层。请求体可以模拟 Claude Code 的格式,看返回是不是 OpenAI 风格的响应。接着在 Ollama 侧查看是否收到请求,再运行一个简单的代码生成任务,观察输出是否完整。
这里要特别留意上下文窗口。Ollama 默认上下文长度可能比较小,长对话会被悄悄截断,表现为回答不完整但没有任何报错。我会在启动 Ollama 时把 OLLAMA_CONTEXT_LENGTH 设到 8192 以上,具体数值还要结合内存和模型大小调整。
回滚和风险边界
不想用本地方案时,撤销环境变量、重启 Claude Code 就能回到官方 API,不需要卸载任何依赖。但要注意风险边界:本地小参数模型在工具调用、多文件编辑场景下失败率偏高,这不是配置文件能解决的。如果你只做单轮问答或小段代码解释,可以接受;如果任务涉及自动执行命令,最好先手动跑一遍流程,评估模型是否理解工具定义。
另外,隐私和控制是选择本地的主要原因,但 Claude Code 本身可能包含遥测和自动更新,想完全离线需要主动关掉。混合路由也是一种思路,核心请求走本地、敏感度低的走官方,但需要额外的路由层,维护成本并不低。是否值得,取决于你的真实需求。