1. 为什么你的多模型调用总是乱成一锅粥

如果你同时用过 OpenAI、Claude、通义千问、本地 Ollama，大概率经历过这种场面：每个厂商的 SDK 长得不一样，鉴权方式不一样，返回结构也不一样。今天想从 GPT-4o 换到本地 qwen2.5-coder 跑个离线任务，结果发现代码里到处是if model == "xxx"的分支判断，改一处漏一处。更别提团队协作时，每个人的 Key 散落在各自的.env里，谁用了多少额度、哪个模型超支了，全靠猜。

LiteLLM 就是来解决这个问题的。它是一个开源的 LLM 网关和 SDK，核心能力是把 100 多种大模型的调用方式统一转换成 OpenAI 兼容格式。你只需要学会一套 OpenAI 的调用姿势，就能无缝切换 Anthropic、Google、Azure、HuggingFace、Ollama、vLLM 等后端。对开发者来说，这意味着业务代码里只认base_url和model两个变量，背后换什么模型都不用动代码。

这篇文章面向的是需要在多个模型之间频繁切换的开发者，尤其是那些想让 Claude Code、Cline 这类工具接入本地模型，或者想给团队搭一个统一 AI 入口的人。我会交付可复制的 LiteLLMconfig.yaml、TaoToken 统一 Key 的接入示例，以及调用验证和错误排查的完整步骤。你跟着做，能跑通一个「一个 Key 管所有模型」的网关。

先说清楚 LiteLLM 的两种使用模式，这决定了你后面怎么落地。第一种是 Python SDK，适合在代码里直接集成，最轻量；第二种是 Proxy Server，把 LiteLLM 跑成一个独立 HTTP 服务，任何语言都能调，适合生产环境和多团队协作。大部分人的痛点其实在第二种，因为一旦有了统一网关，前端、后端、脚本工具就都只认一个地址了。

我试过在本地同时跑 Ollama 和几个云端模型，最开始也是每个项目单独配 Key，后来发现 LiteLLM 的 Proxy 模式能把这事收拢到一个配置文件里。下面从环境准备开始，一步步把网关搭起来。

2. TaoToken 统一 Key 与 LiteLLM 网关的前置准备

在动手写配置之前，先把「Key 从哪来」这件事理清楚。LiteLLM 本身是一个路由层，它不生产模型能力，只负责把请求转发到各个后端。所以你需要为每个后端准备凭证。如果每个厂商都单独申请 Key，管理成本还是很高。这时候可以用 TaoToken 作为统一入口，它提供 OpenAI 兼容的 API 地址，一个 Key 就能访问多种模型，省去在 LiteLLM 里维护一堆厂商 Key 的麻烦。

TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为api_base使用。你需要在控制台生成一个 API Key，这个 Key 就是后面 LiteLLM 配置里api_key字段的值。生成 Key 的入口在控制台的 API Keys 页面，登录后就能看到创建按钮。如果你还没账号，可以先到官网了解整体能力，再决定要不要接入。

这里要强调一个概念：LiteLLM 的model_list里，每个条目代表一个「对外暴露的模型名」到「实际后端」的映射。你可以把 TaoToken 当成一个后端，也可以把本地 Ollama 当成另一个后端，两者在 LiteLLM 里是平级的。这样设计的好处是，业务侧只看到你定义的model_name，完全不用关心背后是云端还是本地。

前置准备清单如下：Python 3.9 以上环境（LiteLLM 对版本有要求，太低会装不上）、pip 包管理工具、一个 TaoToken API Key、以及可选的本地 Ollama 服务。如果你打算用 Docker 部署，还需要 Docker 和 Docker Compose。我建议先用 pip 方式跑通，确认逻辑没问题再上 Docker，这样排错更直观。

安装 LiteLLM 的 proxy 版本，命令是pip install 'litellm[proxy]'。注意引号不能省，否则 shell 可能把方括号当成通配符处理。装完之后用litellm --version验证一下，能输出版本号就说明环境 OK。这一步如果卡在依赖编译上，通常是 Python 版本太老或者缺少编译工具链，升级 Python 或安装 build-essential 即可。

3. 可复制的 LiteLLM config.yaml 与 TaoToken 接入配置

这一节是全文的核心，直接给你能用的配置文件。先建一个工作目录，比如litellm-gateway，在里面创建config.yaml。下面这份配置同时接了 TaoToken 和本地 Ollama，你可以按需删减。

model_list: - model_name: tao-gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: tao-claude-sonnet litellm_params: model: openai/claude-3-5-sonnet api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: local-qwen-coder litellm_params: model: ollama/qwen2.5-coder:7b api_base: http://localhost:11434 litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-litellm-local-2024

逐段解释一下。model_list里每一项的model_name是你对外暴露的名字，调用时用它；litellm_params.model是 LiteLLM 内部识别的后端标识，openai/前缀表示走 OpenAI 兼容协议，ollama/前缀表示走 Ollama 协议。TaoToken 因为是 OpenAI 兼容的，所以用openai/前缀，把api_base指向https://taotoken.net/api就行。

api_key: os.environ/TAOTOKEN_API_KEY这种写法表示从环境变量读取，不要把 Key 硬编码进配置文件，否则提交到 Git 就泄露了。启动前先设置环境变量：

export TAOTOKEN_API_KEY="你的实际Key"

Windows PowerShell 用$env:TAOTOKEN_API_KEY="你的实际Key"。drop_params: true的作用是当某个后端不支持某些参数时自动丢弃，避免报错，这个在多后端场景下很实用。master_key是 LiteLLM 自己的管理密钥，用来保护管理接口和生成虚拟 Key，跟后端厂商的 Key 是两回事。

启动网关：

litellm --config config.yaml --port 4000

看到Uvicorn running on http://0.0.0.0:4000就说明起来了。如果你想让配置更工程化，可以用 Docker Compose 部署，把config.yaml挂载进容器，同时接一个 Postgres 存用量数据。Docker 方式的docker-compose.yml里，environment段设置DATABASE_URL和STORE_MODEL_IN_DB=True，volumes段把本地config.yaml映射到容器内的/app/config.yaml，启动命令加上--config /app/config.yaml。这样重启容器配置不丢，用量也能持久化。

关于模型 ID 的写法，有个坑要提醒：TaoToken 侧的模型名要跟它文档里列出的保持一致，不要自己臆造。如果你不确定某个模型 ID 是否可用，先用模型对话页面手动发一条消息验证，确认能通再写进配置。LiteLLM 的model_name可以随便起，但litellm_params.model里的后半段必须是后端真实认的 ID。

4. 验证请求：从 curl 到 Claude Code 接入的完整链路

配置写好了，接下来验证它真的能通。最直接的方式是用 curl 打 LiteLLM 的/v1/chat/completions接口：

curl http://localhost:4000/v1/chat/completions \ -H "Authorization: Bearer sk-litellm-local-2024" \ -H "Content-Type: application/json" \ -d '{ "model": "tao-gpt-4o", "messages": [{"role": "user", "content": "用一句话解释什么是网关"}] }'

注意这里的Authorization用的是 LiteLLM 的master_key，不是 TaoToken 的 Key。LiteLLM 收到请求后，会根据model字段找到对应的后端，再用配置里的api_key去请求 TaoToken。如果返回里有choices[0].message.content，说明整条链路通了。如果返回 401，先检查master_key是否跟配置一致；如果返回的是后端鉴权错误，检查TAOTOKEN_API_KEY环境变量有没有生效。

Python 侧调用更简单，用 openai 库指向 LiteLLM 即可：

import openai client = openai.OpenAI( api_key="sk-litellm-local-2024", base_url="http://localhost:4000" ) resp = client.chat.completions.create( model="tao-claude-sonnet", messages=[{"role": "user", "content": "写一个二分查找"}] ) print(resp.choices[0].message.content)

换模型只改model参数，其他一行不动。这就是统一网关的价值。

接下来是很多人关心的场景：让 Claude Code 接入。Claude Code 默认走 Anthropic 协议，但 LiteLLM 可以把它转成 OpenAI 兼容。设置两个环境变量：

export ANTHROPIC_BASE_URL="http://localhost:4000" export ANTHROPIC_AUTH_TOKEN="sk-litellm-local-2024" claude

启动后在 Claude Code 里输入/model，选择你在config.yaml里定义的model_name，比如local-qwen-coder，就能用本地模型跑 tools 调用了。这里的关键是ANTHROPIC_BASE_URL指向 LiteLLM，而不是直连 Ollama，因为直连会因协议不兼容失败。LiteLLM 在中间做了协议转换，Claude Code 以为自己连的是 OpenAI 兼容服务，实际后端是本地模型。

如果你用的是 Cline 或 CC Switch 这类工具，配置逻辑一样：Base URL 填http://localhost:4000，API Key 填master_key，Model ID 填model_name。三件套缺一不可，尤其是 Model ID 必须跟配置文件里的model_name完全一致，大小写敏感。

验证本地 Ollama 那条链路时，先确认ollama list里有qwen2.5-coder:7b，没有的话先ollama pull。然后 curl 打local-qwen-coder，如果返回超时，多半是 Ollama 没启动或者端口不是 11434。Ollama 默认监听127.0.0.1:11434，LiteLLM 在容器里跑的话，localhost指向容器自身，需要改成宿主机的实际 IP 或用host.docker.internal。

5. 常见报错排查：401、local proxy failed 与 reading choices

排错是绕不开的环节，下面按真实报错逐个拆。

401 Unauthorized。这个最常见，分两种来源。第一种是 LiteLLM 层拒绝，说明请求头里的Authorization跟master_key不匹配，检查有没有多空格或者用了 TaoToken 的 Key 去调 LiteLLM。第二种是后端拒绝，LiteLLM 日志里会显示上游返回 401，这时候检查TAOTOKEN_API_KEY环境变量是否在当前 shell 生效，echo $TAOTOKEN_API_KEY看一眼。环境变量在启动 LiteLLM 的同一个终端里设置才有效，换个窗口就没了。

local proxy failed / connection refused。这个通常出现在 Docker 部署时。LiteLLM 容器里配置api_base: http://localhost:11434，但localhost在容器内指向容器自己，不是宿主机。解决办法是把api_base改成http://host.docker.internal:11434（Mac/Windows），Linux 下用宿主机的局域网 IP。另外确认 Ollama 是否允许外部访问，默认只监听本地回环，需要设置OLLAMA_HOST=0.0.0.0再重启。

reading 'choices' of undefined。这个报错说明返回结构里没有choices字段，通常是上游返回了错误信息但被当成正常响应解析了。打开set_verbose: true看 LiteLLM 的完整日志，找到上游实际返回的 JSON。常见原因是模型 ID 写错了，TaoToken 侧返回了model not found。对照文档核对litellm_params.model里的模型名，别把gpt-4o写成gpt4o。

OAuth / token 相关报错。如果你在 Claude Code 里看到 OAuth 报错，说明它还在尝试走 Anthropic 官方鉴权。确认ANTHROPIC_AUTH_TOKEN已设置，并且ANTHROPIC_BASE_URL指向 LiteLLM。有些版本还需要设置ANTHROPIC_API_KEY为空字符串来强制走 token 模式。

模型切换后 tools 调用失败。不是所有模型都支持 function calling。本地小模型如果没经过 tools 训练，Claude Code 的工具调用会失败。这时候换一个支持 tools 的模型，或者用 TaoToken 侧的云端模型验证。LiteLLM 的drop_params只能丢参数，不能给模型补能力。

排查通用套路：先看 LiteLLM 终端日志，它会打印请求转发到哪个后端、上游返回什么状态码；再用 curl 直接打后端地址，绕过 LiteLLM 确认后端本身可用；最后检查配置文件里的model_name和调用时传的model是否一致。三步下来基本能定位。

6. 把网关用起来：从验证到长期编码的落地建议

跑通验证只是第一步，真正让网关产生价值的是把它用进日常开发流。如果你主要在编辑器里写代码，可以把 Cline 或 Claude Code 的 Base URL 固定指向 LiteLLM，这样切换模型不用改编辑器配置，只改config.yaml重启即可。对于需要长期跑 Agent 任务的场景，建议用 Coding Plan 这类方案配合网关，把额度管理和模型路由统一起来，避免每个工具单独配 Key。

团队协作时，用 LiteLLM 的虚拟 Key 功能给每个成员或项目发独立 Key，设置预算上限。生成虚拟 Key 的接口是/key/generate，请求头带master_key，body 里指定models、budget、duration。这样谁超支了直接拒绝，用量日志也能追溯。虚拟 Key 只能调授权的模型，不能碰管理接口，安全性比直接发master_key高。

配置维护上，把config.yaml纳入版本管理，但 Key 走环境变量或密钥管理服务。每次加新模型，先在模型对话页面验证模型 ID 可用，再写进配置。改完配置重启 LiteLLM 生效，Docker 方式用docker-compose restart litellm。如果配置写错了导致启动失败，LiteLLM 会在终端打印 YAML 解析错误，按行号定位即可。

最后给一个实用技巧：在config.yaml里给常用模型起短名字，比如fast、smart、local，业务代码里用这些别名，背后映射到具体模型。这样以后换后端只改映射，调用方完全无感。网关的价值不在于接了多少模型，而在于让模型切换这件事对业务透明。把配置管好，剩下的就是安心写代码了。