1. 为什么我们需要一个统一的模型网关如果你最近在折腾大模型应用尤其是尝试对接多个不同厂商的API比如OpenAI的GPT-4、Anthropic的Claude、Google的Gemini或者国内的一些模型服务那你大概率已经体会过这种“甜蜜的烦恼”了。每个模型都有自己的API端点、认证方式、计费规则和调用格式。你的代码里可能散落着各种openai.ChatCompletion.create、anthropic.Anthropic的初始化以及一堆不同格式的API Key。这还只是调用层面更别提成本监控、失败重试、负载均衡这些生产级需求了。我最近就在重构一个内部工具它需要根据用户请求的复杂度、预算和当前各API的延迟动态选择最合适的模型。最初我写了一大堆if-else分支来处理不同模型的调用逻辑代码臃肿不说每次新增一个模型支持都得在好几个地方修改。更头疼的是错误处理每个模型的错误码和返回格式都不一样写起来异常痛苦。这时候一个统一的“模型网关”就成了刚需。它的核心价值在于抽象与统一对外提供一个标准化的接口无论底层对接的是哪个模型上层应用都用同一种方式调用。这就像给你的应用装了一个“万能适配器”把后端复杂的模型生态差异给屏蔽掉了。而LiteLLM正是这样一个在开发者社区里口碑极佳的轻量级库它完美地扮演了这个适配器的角色。那么有了LiteLLM是不是就万事大吉了对于简单的原型或小项目可能够了。但当你管理的API Key数量多起来需要精细化的权限控制、成本分摊、使用审计或者需要一套友好的界面来管理这些配置时纯代码配置就显得力不从心了。这就是OpenClaw出场的时候。它本质上是一个为LiteLLM设计的可视化配置管理后台。你可以把它理解为一个“控制面板”而LiteLLM是“执行引擎”。两者结合就构成了一套从配置管理到实际调用的完整解决方案。这套组合拳能解决几个非常实际的问题配置集中化所有模型的API Key、基础URL、模型映射规则等不再散落在各个环境变量或代码文件里而是通过OpenClaw的Web界面进行统一管理。动态路由与降级可以轻松配置规则比如“优先使用GPT-4如果超时或达到速率限制则自动降级到Claude-3-Sonnet”。成本与用量可视化OpenClaw可以记录每次调用的模型、Token消耗和估算成本帮助你清晰地了解钱花在了哪里。团队协作与安全可以分配不同的权限给团队成员避免敏感的API Key在代码仓库里明文暴露。接下来我们就从零开始搭建这套系统并深入每一个技术细节。2. 环境搭建与核心组件部署实战的第一步是把环境跑起来。这里我们采用Docker Compose进行部署这是目前最简洁、可复现的方式。你需要确保本地已经安装了Docker和Docker Compose。2.1 项目结构与配置文件解析首先创建一个项目目录比如llm-gateway。在这个目录下我们需要准备几个核心文件。docker-compose.yml文件详解这是整个服务的编排核心。我们主要部署两个服务openclaw管理后台和litellm-proxy代理服务。version: 3.8 services: openclaw: image: ghcr.io/openclaw-ai/openclaw:latest container_name: openclaw ports: - 3000:3000 # OpenClaw管理界面端口 environment: - DATABASE_URLpostgresql://postgres:your_secure_passworddb:5432/openclaw - NEXTAUTH_SECRETyour_very_strong_nextauth_secret_key_here # 用于会话加密 - NEXTAUTH_URLhttp://localhost:3000 # 认证回调地址根据实际部署域名修改 depends_on: - db volumes: - ./openclaw_data:/app/data # 持久化存储防止容器重启数据丢失 networks: - llm-network litellm-proxy: image: ghcr.io/berriai/litellm:main-latest container_name: litellm-proxy ports: - 4000:4000 # LiteLLM代理服务器端口 command: --config /app/config.yaml --port 4000 --detailed_debug # 建议在调试阶段开启生产环境可关闭 volumes: - ./config.yaml:/app/config.yaml:ro # 挂载配置文件 - ./litellm_logs:/app/logs # 挂载日志目录 environment: - OPENAI_API_KEY${OPENAI_API_KEY} # 通过环境变量传入敏感Key而非写在配置文件中 - ANTHROPIC_API_KEY${ANTHROPIC_API_KEY} # 可以继续添加其他模型API_KEY的环境变量 depends_on: - openclaw # 代理启动前确保管理后台已就绪用于可能的配置拉取此处主要为顺序 networks: - llm-network db: image: postgres:15-alpine container_name: postgres-db environment: - POSTGRES_USERpostgres - POSTGRES_PASSWORDyour_secure_password # 务必修改为强密码 - POSTGRES_DBopenclaw volumes: - ./postgres_data:/var/lib/postgresql/data # 数据库数据持久化 networks: - llm-network networks: llm-network: driver: bridge关键点解析网络我们创建了一个独立的Docker网络llm-network让三个服务OpenClaw, LiteLLM Proxy, PostgreSQL在同一个网络内通信使用容器名如db即可互访无需关心IP地址。数据持久化通过volumes将容器内的数据目录如/app/data,/var/lib/postgresql/data映射到宿主机目录。这是必须做的否则容器重启后所有配置和数据库数据都会丢失。环境变量与安全注意litellm-proxy服务中的OPENAI_API_KEY等。我们通过${}语法引用宿主机环境变量而不是将密钥硬编码在Compose文件中。你需要创建一个.env文件在项目根目录切记加入.gitignore内容如下OPENAI_API_KEYsk-your-openai-key-here ANTHROPIC_API_KEYsk-ant-your-anthropic-key-here然后在运行docker-compose up时这些变量会自动注入。这是保护敏感信息的最佳实践。命令参数litellm-proxy的command指定了启动参数。--config指向容器内的配置文件我们通过卷挂载将本地的config.yaml映射进去。--detailed_debug在初期调试时非常有用它会打印详细的请求和响应日志。2.2 LiteLLM 代理配置文件解析接下来创建config.yaml文件。这是LiteLLM代理的核心定义了模型、路由、预算等所有行为。model_list: - model_name: gpt-4-turbo # 对外暴露的统一模型名 litellm_params: model: openai/gpt-4-turbo # 实际调用的模型格式为 provider/model-name api_key: os.environ/OPENAI_API_KEY # 从环境变量读取Key api_base: https://api.openai.com/v1 - model_name: claude-3-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY api_base: https://api.anthropic.com - model_name: gemini-1.5-pro litellm_params: model: gemini/gemini-1.5-pro api_key: os.environ/GEMINI_API_KEY # 假设你在.env中也配置了 api_base: https://generativelanguage.googleapis.com/v1beta - model_name: fallback-gpt-3.5 # 定义一个低成本备用模型 litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY litellm_settings: drop_params: true # 是否丢弃请求中LiteLLM不认识的参数建议为true避免干扰 set_verbose: true # 在代理日志中输出详细信息 general_settings: master_key: sk-my-master-key-for-admin # 用于访问代理管理API的密钥请修改并保管好 database_url: postgresql://postgres:your_secure_passworddb:5432/openclaw # 可选如果希望LiteLLM也使用同一个DB记录日志配置逻辑深度解读model_list这是核心数组。每个元素定义了一个“逻辑模型”。model_name是你给上层应用调用的名字如gpt-4-turbo而litellm_params下的model字段才是真正的后端模型标识。LiteLLM通过provider/model-name的格式来识别该调用哪个供应商的SDK。os.environ/语法这是LiteLLM的一个安全特性。它允许你直接在配置文件中引用环境变量名而不是写死密钥值。代理在启动时会从环境变量中读取对应的值。这比在YAML里写明文密钥安全得多。fallback模型我特意定义了一个fallback-gpt-3.5。在后续的路由规则中它可以作为降级目标。这是一种重要的容错设计。master_key这个密钥用于访问LiteLLM代理的管理端点如/key/generate生成子密钥/model/list查看模型。务必设置为一个强密码因为它拥有很大权限。2.3 启动服务与初始化验证所有文件准备就绪后在项目根目录执行docker-compose up -d-d参数表示在后台运行。等待片刻后你可以通过以下命令检查服务状态docker-compose ps应该看到三个服务的状态都是Up。验证步骤访问OpenClaw管理界面打开浏览器访问http://localhost:3000。首次访问通常会引导你进行初始设置如创建管理员账户。按照页面提示完成即可。访问LiteLLM代理健康检查访问http://localhost:4000/health。你应该看到返回一个简单的JSON响应如{status: healthy}这表示代理服务运行正常。测试模型列表端点使用curl或Postman测试管理端点需要master keycurl -X GET http://localhost:4000/model/list \ -H Authorization: Bearer sk-my-master-key-for-admin你应该能收到一个JSON里面包含你在config.yaml中定义的model_list。如果以上步骤都成功那么基础部署就完成了。但我们现在有两个独立的系统OpenClaw管理界面和LiteLLM代理。它们之间还没有联动。接下来的部分就是让它们协同工作的关键。3. 打通OpenClaw与LiteLLM配置同步与密钥管理部署完两个服务只是第一步让OpenClaw成为LiteLLM代理的“大脑”才是价值所在。这里有两种主要的集成模式我推荐并详细讲解动态配置模式。3.1 集成模式选择静态配置 vs. 动态配置静态配置在config.yaml中写好所有模型和密钥启动LiteLLM代理。OpenClaw仅作为一个独立的“看板”通过读取LiteLLM的日志或调用其管理API来展示用量和成本。这种模式简单但任何模型配置变更都需要修改YAML文件并重启代理服务不够灵活。动态配置LiteLLM代理在启动时只加载基本配置或者甚至从一个简单的配置开始。然后它将模型列表、密钥、路由规则等核心配置的“管理权”交给一个外部数据库正是OpenClaw使用的PostgreSQL。OpenClaw在界面上做的任何修改都会实时同步到数据库LiteLLM代理会监听这些变化并动态更新自己的运行状态。这才是生产环境该用的方式。OpenClaw项目本身的设计目标就是作为LiteLLM的动态配置源。我们需要对配置进行一些调整。3.2 配置LiteLLM使用OpenClaw数据库首先确保docker-compose.yml中litellm-proxy服务的database_url环境变量指向正确的OpenClaw数据库我们在前面已经配置了。更重要的是我们需要修改LiteLLM的启动命令告诉它使用数据库中的配置。更新docker-compose.yml中litellm-proxy服务的command部分command: --config /app/config.yaml --port 4000 --use_background_health_checks --config http://openclaw:3000/api/litellm/config # 关键从OpenClaw拉取动态配置这里--config参数后面跟的不再是一个单纯的YAML文件路径而是一个HTTP端点。LiteLLM代理在启动时会向这个地址发起GET请求期望获取到与本地config.yaml结构相同的配置JSON。OpenClaw的/api/litellm/config端点正是为此设计的。接下来我们需要在OpenClaw界面中配置模型信息使其能通过这个端点提供正确的数据。3.3 在OpenClaw中配置模型与密钥登录OpenClaw访问http://localhost:3000用你初始化时创建的账号登录。添加模型供应商Provider在侧边栏找到类似“供应商”或“Providers”的菜单。点击添加填写信息。例如名称: OpenAI类型: OpenAI (通常有下拉选择)API Base URL:https://api.openai.com/v1(一般使用默认值)API Key: 在这里填入你的OpenAI API Key。注意OpenClaw提供了比环境变量更细粒度的管理。你可以在这里为不同团队或项目分配不同的Key。添加模型Model找到“模型”或“Models”菜单。点击添加将你在config.yaml中定义的逻辑模型一个个添加进去。例如添加gpt-4-turbo模型标识符:gpt-4-turbo(这与LiteLLMmodel_name对应)所属供应商: 选择上一步创建的OpenAI后端模型名:gpt-4-turbo(这是实际调用OpenAI的模型名)成本可以填写每百万输入/输出Token的单价OpenClaw会自动计算花费。验证配置同步添加完模型后重启LiteLLM代理服务以使新的--config参数生效。docker-compose restart litellm-proxy然后再次调用LiteLLM的模型列表接口curl -X GET http://localhost:4000/model/list \ -H Authorization: Bearer sk-my-master-key-for-admin此时返回的列表应该就是你在OpenClaw界面中配置的模型而不是最初config.yaml里写死的那个。这证明动态配置同步成功了。3.4 密钥Key管理与使用策略在OpenClaw中除了配置模型另一个核心功能是管理“密钥”。这里的概念有点绕需要厘清供应商API Key这是你从OpenAI、Anthropic等平台购买的真实密钥。你在OpenClaw的“供应商”配置里填的就是这个。它用于实际调用大模型API。LiteLLM Master Key这是在LiteLLM代理的config.yaml或环境变量中设置的master_key。它拥有最高权限用于管理代理本身如生成子密钥、查看所有请求。LiteLLM 终端用户Key这是通过Master Key在LiteLLM代理上生成的、给最终应用程序使用的密钥。应用程序在调用代理时需要在请求头中携带这个Key。最佳实践流程你在OpenClaw中管理供应商API Key。LiteLLM代理从OpenClaw动态获取配置其中包含了这些供应商Key或引用方式。你通过LiteLLM的管理API用Master Key生成一个或多个终端用户Key并可以设置这些Key的预算、权限例如只能访问特定模型。你的应用程序使用终端用户Key来调用http://localhost:4000这个统一的网关。生成终端用户Key的命令示例curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-my-master-key-for-admin \ -H Content-Type: application/json \ -d { models: [gpt-4-turbo, claude-3-sonnet], # 这个key允许访问的模型列表 max_budget: 10.0, # 最大预算单位美元 user_id: internal-tool-01 # 便于识别的用户ID }返回的JSON中会包含key字段那就是你的应用程序要用的密钥。这样做的好处是你永远不需要将供应商的真实API Key分发到各个应用或开发者手中。你通过LiteLLM代理进行了一层中转和管控实现了成本的隔离、用量的监控和权限的控制。4. 高级路由策略与模型切换实战网关的核心智能体现在路由策略上。我们不仅要把请求发出去还要能根据条件智能地决定发给谁。LiteLLM支持强大的路由策略我们可以通过OpenClaw界面或直接修改数据库配置来管理这些策略。4.1 基于负载均衡与权重的路由最简单的策略是负载均衡。假设我们为同一个逻辑模型如high-performance-llm配置了多个后端比如Azure OpenAI的GPT-4终端和OpenAI官方的GPT-4终端我们可以让流量按权重分配。在OpenClaw的“模型”配置中或者直接在LiteLLM的config.yaml如果使用静态配置中可以这样定义model_list: - model_name: high-performance-llm litellm_params: model: openai/gpt-4-turbo api_key: os.environ/OPENAI_KEY_1 rpm: 100 # 每分钟请求数限制 tpm: 40000 # 每分钟Token数限制 - model_name: high-performance-llm # 相同的逻辑模型名 litellm_params: model: azure/gpt-4-turbo api_key: os.environ/AZURE_OPENAI_KEY api_base: https://your-resource.openai.azure.com/ rpm: 200 weight: 2 # 权重为2当应用调用high-performance-llm时LiteLLM会按照权重默认权重为1来分配请求。上面配置中Azure终端的权重是2OpenAI官方终端是1这意味着大约2/3的请求会发给Azure1/3发给OpenAI官方。这常用于成本优化或利用不同服务商的配额。4.2 基于内容或性能的智能路由更复杂的策略需要用到LiteLLM的Router类在代码中或通过其/router/route端点。不过在代理模式下我们可以通过**设置model_group和routing_strategy**来实现一定程度的智能路由。一种常见的场景是质量降级。我们希望首选性能最好的模型如GPT-4但当其返回特定错误如超时、上下文过长或响应时间超过阈值时自动切换到备用模型如Claude-3-Sonnet或GPT-3.5。目前LiteLLM代理的YAML配置对复杂策略的支持还在演进中。一个实用的方法是利用其**/chat/completions端点的model参数可以接受一个列表**的特性。你可以在应用层实现简单的重试逻辑或者使用LiteLLM的SDK。示例应用层伪代码import openai from litellm import completion client openai.OpenAI( api_keyyour-litellm-end-user-key, base_urlhttp://localhost:4000 # 指向LiteLLM代理 ) def smart_completion(messages, model_list[gpt-4-turbo, claude-3-sonnet, gpt-3.5-turbo]): for model in model_list: try: response client.chat.completions.create( modelmodel, # 依次尝试列表中的模型 messagesmessages, timeout15 # 设置超时 ) return response except (openai.APITimeoutError, openai.APIError) as e: print(fModel {model} failed with error: {e}. Trying next...) continue raise Exception(All models failed.)在这个例子中应用代码负责重试逻辑。而LiteLLM网关的价值在于无论我尝试哪个模型gpt-4-turbo,claude-3-sonnet我都用同一套代码、同一个API端点、同一种请求格式只是改变model参数。后端的认证、路由、计费都由网关统一处理。4.3 通过OpenClaw监控与调整路由OpenClaw的仪表盘在这里发挥了巨大作用。在“请求日志”或“分析”页面你可以清晰地看到每个终端用户Key的调用量、Token消耗和成本。每个模型逻辑模型和后端模型的成功率、平均响应时间。错误类型分布如速率限制、认证失败、上下文超长。基于这些数据你可以动态调整OpenClaw中的配置。例如发现某个Azure区域的失败率飙升你可以临时在OpenClaw中调低该后端模型的权重甚至禁用它。所有更改会通过动态配置机制近乎实时地同步到LiteLLM代理无需重启服务。5. 生产环境部署考量与故障排查将这套系统用于生产有几个关键点需要特别注意。5.1 安全性加固网络暴露litellm-proxy的端口默认4000不应该直接暴露在公网。应该放在内网通过反向代理如Nginx对外提供服务并在Nginx上配置SSL/TLS、速率限制、IP白名单等。密钥管理如前所述供应商API Key存在OpenClaw中并通过环境变量传递给LiteLLM。Master Key和OpenClaw的数据库密码、NEXTAUTH_SECRET等都是敏感信息。务必使用.env文件管理并确保其不被提交到代码仓库。在生产环境中应考虑使用专业的密钥管理服务如HashiCorp Vault、AWS Secrets Manager。OpenClaw身份验证确保OpenClaw的登录认证足够强壮并为不同团队成员分配适当的角色如管理员、只读用户。5.2 高可用与可观测性数据库高可用生产环境的PostgreSQL应考虑主从复制或使用云上的托管数据库服务如AWS RDS。服务多实例可以考虑将litellm-proxy部署为多个实例前面用负载均衡器如Nginx分流提高吞吐量和可用性。需要注意如果使用内存中的缓存或计数器多实例间可能需要共享状态如限流计数这需要更复杂的配置。日志聚合将Docker容器的日志特别是litellm-proxy的访问日志和详细调试日志收集到ELK栈或Loki等日志系统中便于问题追踪。指标监控为LiteLLM代理和OpenClaw添加Prometheus指标暴露和监控关注请求延迟、错误率、Token消耗速率等关键指标。5.3 常见故障与排查思路问题一调用LiteLLM代理返回401 Authentication Error检查步骤确认请求头中的Authorization字段格式正确Bearer your-end-user-key。在OpenClaw或使用Master Key调用/key/info端点确认该终端用户Key是否有效、是否过期、预算是否耗尽。检查LiteLLM代理日志看是否有更详细的错误信息。可以通过docker-compose logs -f litellm-proxy查看。问题二调用成功但返回内容提示“模型不存在”或路由错误检查步骤确认请求体中的model参数名称是否与OpenClaw中配置的“模型标识符”完全一致大小写敏感。在OpenClaw界面检查该模型是否已启用对应的供应商配置API Key, Base URL是否正确。检查LiteLLM代理是否成功从OpenClaw拉取了最新配置。可以重启litellm-proxy服务并观察启动日志。问题三OpenClaw界面无法添加或修改模型配置检查步骤检查OpenClaw容器日志看是否有数据库连接错误或应用错误。确认PostgreSQL容器运行正常且网络互通。检查OpenClaw的数据库迁移是否完成。有时新版本需要执行数据库迁移查看启动日志确认。问题四动态配置不生效检查步骤确认docker-compose.yml中litellm-proxy的command里--config参数指向的是OpenClaw的API端点http://openclaw:3000/api/litellm/config。手动访问这个端点看是否能返回正确的JSON配置可能需要添加认证头具体看OpenClaw文档。LiteLLM代理默认会有缓存。检查配置中是否有缓存设置或者尝试重启代理服务强制刷新。这套LiteLLM OpenClaw的组合将模型管理的复杂度从应用代码中剥离出来形成了一个专业、可控的中台层。从最初的杂乱无章到现在的统一网关、可视化管理和智能路由整个大模型应用的开发和运维体验得到了质的提升。它可能不是解决所有问题的银弹但对于任何需要管理多个模型、关注成本与稳定性的团队来说投入时间搭建这样一套基础设施回报是显而易见的。 
长河君 · 2026/8/26 13:08:37 · 阅读 1.2k 基于LiteLLM与OpenClaw构建统一AI模型网关：从原理到生产部署
1. 为什么我们需要一个统一的模型网关如果你最近在折腾大模型应用尤其是尝试对接多个不同厂商的API比如OpenAI的GPT-4、Anthropic的Claude、Google的Gemini或者国内的一些模型服务那你大概率已经体会过这种“甜蜜的烦恼”了。每个模型都有自己的API端点、认证方式、计费规则和调用格式。你的代码里可能散落着各种openai.ChatCompletion.create、anthropic.Anthropic的初始化以及一堆不同格式的API Key。这还只是调用层面更别提成本监控、失败重试、负载均衡这些生产级需求了。我最近就在重构一个内部工具它需要根据用户请求的复杂度、预算和当前各API的延迟动态选择最合适的模型。最初我写了一大堆if-else分支来处理不同模型的调用逻辑代码臃肿不说每次新增一个模型支持都得在好几个地方修改。更头疼的是错误处理每个模型的错误码和返回格式都不一样写起来异常痛苦。这时候一个统一的“模型网关”就成了刚需。它的核心价值在于抽象与统一对外提供一个标准化的接口无论底层对接的是哪个模型上层应用都用同一种方式调用。这就像给你的应用装了一个“万能适配器”把后端复杂的模型生态差异给屏蔽掉了。而LiteLLM正是这样一个在开发者社区里口碑极佳的轻量级库它完美地扮演了这个适配器的角色。那么有了LiteLLM是不是就万事大吉了对于简单的原型或小项目可能够了。但当你管理的API Key数量多起来需要精细化的权限控制、成本分摊、使用审计或者需要一套友好的界面来管理这些配置时纯代码配置就显得力不从心了。这就是OpenClaw出场的时候。它本质上是一个为LiteLLM设计的可视化配置管理后台。你可以把它理解为一个“控制面板”而LiteLLM是“执行引擎”。两者结合就构成了一套从配置管理到实际调用的完整解决方案。这套组合拳能解决几个非常实际的问题配置集中化所有模型的API Key、基础URL、模型映射规则等不再散落在各个环境变量或代码文件里而是通过OpenClaw的Web界面进行统一管理。动态路由与降级可以轻松配置规则比如“优先使用GPT-4如果超时或达到速率限制则自动降级到Claude-3-Sonnet”。成本与用量可视化OpenClaw可以记录每次调用的模型、Token消耗和估算成本帮助你清晰地了解钱花在了哪里。团队协作与安全可以分配不同的权限给团队成员避免敏感的API Key在代码仓库里明文暴露。接下来我们就从零开始搭建这套系统并深入每一个技术细节。2. 环境搭建与核心组件部署实战的第一步是把环境跑起来。这里我们采用Docker Compose进行部署这是目前最简洁、可复现的方式。你需要确保本地已经安装了Docker和Docker Compose。2.1 项目结构与配置文件解析首先创建一个项目目录比如llm-gateway。在这个目录下我们需要准备几个核心文件。docker-compose.yml文件详解这是整个服务的编排核心。我们主要部署两个服务openclaw管理后台和litellm-proxy代理服务。version: 3.8 services: openclaw: image: ghcr.io/openclaw-ai/openclaw:latest container_name: openclaw ports: - 3000:3000 # OpenClaw管理界面端口 environment: - DATABASE_URLpostgresql://postgres:your_secure_passworddb:5432/openclaw - NEXTAUTH_SECRETyour_very_strong_nextauth_secret_key_here # 用于会话加密 - NEXTAUTH_URLhttp://localhost:3000 # 认证回调地址根据实际部署域名修改 depends_on: - db volumes: - ./openclaw_data:/app/data # 持久化存储防止容器重启数据丢失 networks: - llm-network litellm-proxy: image: ghcr.io/berriai/litellm:main-latest container_name: litellm-proxy ports: - 4000:4000 # LiteLLM代理服务器端口 command: --config /app/config.yaml --port 4000 --detailed_debug # 建议在调试阶段开启生产环境可关闭 volumes: - ./config.yaml:/app/config.yaml:ro # 挂载配置文件 - ./litellm_logs:/app/logs # 挂载日志目录 environment: - OPENAI_API_KEY${OPENAI_API_KEY} # 通过环境变量传入敏感Key而非写在配置文件中 - ANTHROPIC_API_KEY${ANTHROPIC_API_KEY} # 可以继续添加其他模型API_KEY的环境变量 depends_on: - openclaw # 代理启动前确保管理后台已就绪用于可能的配置拉取此处主要为顺序 networks: - llm-network db: image: postgres:15-alpine container_name: postgres-db environment: - POSTGRES_USERpostgres - POSTGRES_PASSWORDyour_secure_password # 务必修改为强密码 - POSTGRES_DBopenclaw volumes: - ./postgres_data:/var/lib/postgresql/data # 数据库数据持久化 networks: - llm-network networks: llm-network: driver: bridge关键点解析网络我们创建了一个独立的Docker网络llm-network让三个服务OpenClaw, LiteLLM Proxy, PostgreSQL在同一个网络内通信使用容器名如db即可互访无需关心IP地址。数据持久化通过volumes将容器内的数据目录如/app/data,/var/lib/postgresql/data映射到宿主机目录。这是必须做的否则容器重启后所有配置和数据库数据都会丢失。环境变量与安全注意litellm-proxy服务中的OPENAI_API_KEY等。我们通过${}语法引用宿主机环境变量而不是将密钥硬编码在Compose文件中。你需要创建一个.env文件在项目根目录切记加入.gitignore内容如下OPENAI_API_KEYsk-your-openai-key-here ANTHROPIC_API_KEYsk-ant-your-anthropic-key-here然后在运行docker-compose up时这些变量会自动注入。这是保护敏感信息的最佳实践。命令参数litellm-proxy的command指定了启动参数。--config指向容器内的配置文件我们通过卷挂载将本地的config.yaml映射进去。--detailed_debug在初期调试时非常有用它会打印详细的请求和响应日志。2.2 LiteLLM 代理配置文件解析接下来创建config.yaml文件。这是LiteLLM代理的核心定义了模型、路由、预算等所有行为。model_list: - model_name: gpt-4-turbo # 对外暴露的统一模型名 litellm_params: model: openai/gpt-4-turbo # 实际调用的模型格式为 provider/model-name api_key: os.environ/OPENAI_API_KEY # 从环境变量读取Key api_base: https://api.openai.com/v1 - model_name: claude-3-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY api_base: https://api.anthropic.com - model_name: gemini-1.5-pro litellm_params: model: gemini/gemini-1.5-pro api_key: os.environ/GEMINI_API_KEY # 假设你在.env中也配置了 api_base: https://generativelanguage.googleapis.com/v1beta - model_name: fallback-gpt-3.5 # 定义一个低成本备用模型 litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY litellm_settings: drop_params: true # 是否丢弃请求中LiteLLM不认识的参数建议为true避免干扰 set_verbose: true # 在代理日志中输出详细信息 general_settings: master_key: sk-my-master-key-for-admin # 用于访问代理管理API的密钥请修改并保管好 database_url: postgresql://postgres:your_secure_passworddb:5432/openclaw # 可选如果希望LiteLLM也使用同一个DB记录日志配置逻辑深度解读model_list这是核心数组。每个元素定义了一个“逻辑模型”。model_name是你给上层应用调用的名字如gpt-4-turbo而litellm_params下的model字段才是真正的后端模型标识。LiteLLM通过provider/model-name的格式来识别该调用哪个供应商的SDK。os.environ/语法这是LiteLLM的一个安全特性。它允许你直接在配置文件中引用环境变量名而不是写死密钥值。代理在启动时会从环境变量中读取对应的值。这比在YAML里写明文密钥安全得多。fallback模型我特意定义了一个fallback-gpt-3.5。在后续的路由规则中它可以作为降级目标。这是一种重要的容错设计。master_key这个密钥用于访问LiteLLM代理的管理端点如/key/generate生成子密钥/model/list查看模型。务必设置为一个强密码因为它拥有很大权限。2.3 启动服务与初始化验证所有文件准备就绪后在项目根目录执行docker-compose up -d-d参数表示在后台运行。等待片刻后你可以通过以下命令检查服务状态docker-compose ps应该看到三个服务的状态都是Up。验证步骤访问OpenClaw管理界面打开浏览器访问http://localhost:3000。首次访问通常会引导你进行初始设置如创建管理员账户。按照页面提示完成即可。访问LiteLLM代理健康检查访问http://localhost:4000/health。你应该看到返回一个简单的JSON响应如{status: healthy}这表示代理服务运行正常。测试模型列表端点使用curl或Postman测试管理端点需要master keycurl -X GET http://localhost:4000/model/list \ -H Authorization: Bearer sk-my-master-key-for-admin你应该能收到一个JSON里面包含你在config.yaml中定义的model_list。如果以上步骤都成功那么基础部署就完成了。但我们现在有两个独立的系统OpenClaw管理界面和LiteLLM代理。它们之间还没有联动。接下来的部分就是让它们协同工作的关键。3. 打通OpenClaw与LiteLLM配置同步与密钥管理部署完两个服务只是第一步让OpenClaw成为LiteLLM代理的“大脑”才是价值所在。这里有两种主要的集成模式我推荐并详细讲解动态配置模式。3.1 集成模式选择静态配置 vs. 动态配置静态配置在config.yaml中写好所有模型和密钥启动LiteLLM代理。OpenClaw仅作为一个独立的“看板”通过读取LiteLLM的日志或调用其管理API来展示用量和成本。这种模式简单但任何模型配置变更都需要修改YAML文件并重启代理服务不够灵活。动态配置LiteLLM代理在启动时只加载基本配置或者甚至从一个简单的配置开始。然后它将模型列表、密钥、路由规则等核心配置的“管理权”交给一个外部数据库正是OpenClaw使用的PostgreSQL。OpenClaw在界面上做的任何修改都会实时同步到数据库LiteLLM代理会监听这些变化并动态更新自己的运行状态。这才是生产环境该用的方式。OpenClaw项目本身的设计目标就是作为LiteLLM的动态配置源。我们需要对配置进行一些调整。3.2 配置LiteLLM使用OpenClaw数据库首先确保docker-compose.yml中litellm-proxy服务的database_url环境变量指向正确的OpenClaw数据库我们在前面已经配置了。更重要的是我们需要修改LiteLLM的启动命令告诉它使用数据库中的配置。更新docker-compose.yml中litellm-proxy服务的command部分command: --config /app/config.yaml --port 4000 --use_background_health_checks --config http://openclaw:3000/api/litellm/config # 关键从OpenClaw拉取动态配置这里--config参数后面跟的不再是一个单纯的YAML文件路径而是一个HTTP端点。LiteLLM代理在启动时会向这个地址发起GET请求期望获取到与本地config.yaml结构相同的配置JSON。OpenClaw的/api/litellm/config端点正是为此设计的。接下来我们需要在OpenClaw界面中配置模型信息使其能通过这个端点提供正确的数据。3.3 在OpenClaw中配置模型与密钥登录OpenClaw访问http://localhost:3000用你初始化时创建的账号登录。添加模型供应商Provider在侧边栏找到类似“供应商”或“Providers”的菜单。点击添加填写信息。例如名称: OpenAI类型: OpenAI (通常有下拉选择)API Base URL:https://api.openai.com/v1(一般使用默认值)API Key: 在这里填入你的OpenAI API Key。注意OpenClaw提供了比环境变量更细粒度的管理。你可以在这里为不同团队或项目分配不同的Key。添加模型Model找到“模型”或“Models”菜单。点击添加将你在config.yaml中定义的逻辑模型一个个添加进去。例如添加gpt-4-turbo模型标识符:gpt-4-turbo(这与LiteLLMmodel_name对应)所属供应商: 选择上一步创建的OpenAI后端模型名:gpt-4-turbo(这是实际调用OpenAI的模型名)成本可以填写每百万输入/输出Token的单价OpenClaw会自动计算花费。验证配置同步添加完模型后重启LiteLLM代理服务以使新的--config参数生效。docker-compose restart litellm-proxy然后再次调用LiteLLM的模型列表接口curl -X GET http://localhost:4000/model/list \ -H Authorization: Bearer sk-my-master-key-for-admin此时返回的列表应该就是你在OpenClaw界面中配置的模型而不是最初config.yaml里写死的那个。这证明动态配置同步成功了。3.4 密钥Key管理与使用策略在OpenClaw中除了配置模型另一个核心功能是管理“密钥”。这里的概念有点绕需要厘清供应商API Key这是你从OpenAI、Anthropic等平台购买的真实密钥。你在OpenClaw的“供应商”配置里填的就是这个。它用于实际调用大模型API。LiteLLM Master Key这是在LiteLLM代理的config.yaml或环境变量中设置的master_key。它拥有最高权限用于管理代理本身如生成子密钥、查看所有请求。LiteLLM 终端用户Key这是通过Master Key在LiteLLM代理上生成的、给最终应用程序使用的密钥。应用程序在调用代理时需要在请求头中携带这个Key。最佳实践流程你在OpenClaw中管理供应商API Key。LiteLLM代理从OpenClaw动态获取配置其中包含了这些供应商Key或引用方式。你通过LiteLLM的管理API用Master Key生成一个或多个终端用户Key并可以设置这些Key的预算、权限例如只能访问特定模型。你的应用程序使用终端用户Key来调用http://localhost:4000这个统一的网关。生成终端用户Key的命令示例curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-my-master-key-for-admin \ -H Content-Type: application/json \ -d { models: [gpt-4-turbo, claude-3-sonnet], # 这个key允许访问的模型列表 max_budget: 10.0, # 最大预算单位美元 user_id: internal-tool-01 # 便于识别的用户ID }返回的JSON中会包含key字段那就是你的应用程序要用的密钥。这样做的好处是你永远不需要将供应商的真实API Key分发到各个应用或开发者手中。你通过LiteLLM代理进行了一层中转和管控实现了成本的隔离、用量的监控和权限的控制。4. 高级路由策略与模型切换实战网关的核心智能体现在路由策略上。我们不仅要把请求发出去还要能根据条件智能地决定发给谁。LiteLLM支持强大的路由策略我们可以通过OpenClaw界面或直接修改数据库配置来管理这些策略。4.1 基于负载均衡与权重的路由最简单的策略是负载均衡。假设我们为同一个逻辑模型如high-performance-llm配置了多个后端比如Azure OpenAI的GPT-4终端和OpenAI官方的GPT-4终端我们可以让流量按权重分配。在OpenClaw的“模型”配置中或者直接在LiteLLM的config.yaml如果使用静态配置中可以这样定义model_list: - model_name: high-performance-llm litellm_params: model: openai/gpt-4-turbo api_key: os.environ/OPENAI_KEY_1 rpm: 100 # 每分钟请求数限制 tpm: 40000 # 每分钟Token数限制 - model_name: high-performance-llm # 相同的逻辑模型名 litellm_params: model: azure/gpt-4-turbo api_key: os.environ/AZURE_OPENAI_KEY api_base: https://your-resource.openai.azure.com/ rpm: 200 weight: 2 # 权重为2当应用调用high-performance-llm时LiteLLM会按照权重默认权重为1来分配请求。上面配置中Azure终端的权重是2OpenAI官方终端是1这意味着大约2/3的请求会发给Azure1/3发给OpenAI官方。这常用于成本优化或利用不同服务商的配额。4.2 基于内容或性能的智能路由更复杂的策略需要用到LiteLLM的Router类在代码中或通过其/router/route端点。不过在代理模式下我们可以通过**设置model_group和routing_strategy**来实现一定程度的智能路由。一种常见的场景是质量降级。我们希望首选性能最好的模型如GPT-4但当其返回特定错误如超时、上下文过长或响应时间超过阈值时自动切换到备用模型如Claude-3-Sonnet或GPT-3.5。目前LiteLLM代理的YAML配置对复杂策略的支持还在演进中。一个实用的方法是利用其**/chat/completions端点的model参数可以接受一个列表**的特性。你可以在应用层实现简单的重试逻辑或者使用LiteLLM的SDK。示例应用层伪代码import openai from litellm import completion client openai.OpenAI( api_keyyour-litellm-end-user-key, base_urlhttp://localhost:4000 # 指向LiteLLM代理 ) def smart_completion(messages, model_list[gpt-4-turbo, claude-3-sonnet, gpt-3.5-turbo]): for model in model_list: try: response client.chat.completions.create( modelmodel, # 依次尝试列表中的模型 messagesmessages, timeout15 # 设置超时 ) return response except (openai.APITimeoutError, openai.APIError) as e: print(fModel {model} failed with error: {e}. Trying next...) continue raise Exception(All models failed.)在这个例子中应用代码负责重试逻辑。而LiteLLM网关的价值在于无论我尝试哪个模型gpt-4-turbo,claude-3-sonnet我都用同一套代码、同一个API端点、同一种请求格式只是改变model参数。后端的认证、路由、计费都由网关统一处理。4.3 通过OpenClaw监控与调整路由OpenClaw的仪表盘在这里发挥了巨大作用。在“请求日志”或“分析”页面你可以清晰地看到每个终端用户Key的调用量、Token消耗和成本。每个模型逻辑模型和后端模型的成功率、平均响应时间。错误类型分布如速率限制、认证失败、上下文超长。基于这些数据你可以动态调整OpenClaw中的配置。例如发现某个Azure区域的失败率飙升你可以临时在OpenClaw中调低该后端模型的权重甚至禁用它。所有更改会通过动态配置机制近乎实时地同步到LiteLLM代理无需重启服务。5. 生产环境部署考量与故障排查将这套系统用于生产有几个关键点需要特别注意。5.1 安全性加固网络暴露litellm-proxy的端口默认4000不应该直接暴露在公网。应该放在内网通过反向代理如Nginx对外提供服务并在Nginx上配置SSL/TLS、速率限制、IP白名单等。密钥管理如前所述供应商API Key存在OpenClaw中并通过环境变量传递给LiteLLM。Master Key和OpenClaw的数据库密码、NEXTAUTH_SECRET等都是敏感信息。务必使用.env文件管理并确保其不被提交到代码仓库。在生产环境中应考虑使用专业的密钥管理服务如HashiCorp Vault、AWS Secrets Manager。OpenClaw身份验证确保OpenClaw的登录认证足够强壮并为不同团队成员分配适当的角色如管理员、只读用户。5.2 高可用与可观测性数据库高可用生产环境的PostgreSQL应考虑主从复制或使用云上的托管数据库服务如AWS RDS。服务多实例可以考虑将litellm-proxy部署为多个实例前面用负载均衡器如Nginx分流提高吞吐量和可用性。需要注意如果使用内存中的缓存或计数器多实例间可能需要共享状态如限流计数这需要更复杂的配置。日志聚合将Docker容器的日志特别是litellm-proxy的访问日志和详细调试日志收集到ELK栈或Loki等日志系统中便于问题追踪。指标监控为LiteLLM代理和OpenClaw添加Prometheus指标暴露和监控关注请求延迟、错误率、Token消耗速率等关键指标。5.3 常见故障与排查思路问题一调用LiteLLM代理返回401 Authentication Error检查步骤确认请求头中的Authorization字段格式正确Bearer your-end-user-key。在OpenClaw或使用Master Key调用/key/info端点确认该终端用户Key是否有效、是否过期、预算是否耗尽。检查LiteLLM代理日志看是否有更详细的错误信息。可以通过docker-compose logs -f litellm-proxy查看。问题二调用成功但返回内容提示“模型不存在”或路由错误检查步骤确认请求体中的model参数名称是否与OpenClaw中配置的“模型标识符”完全一致大小写敏感。在OpenClaw界面检查该模型是否已启用对应的供应商配置API Key, Base URL是否正确。检查LiteLLM代理是否成功从OpenClaw拉取了最新配置。可以重启litellm-proxy服务并观察启动日志。问题三OpenClaw界面无法添加或修改模型配置检查步骤检查OpenClaw容器日志看是否有数据库连接错误或应用错误。确认PostgreSQL容器运行正常且网络互通。检查OpenClaw的数据库迁移是否完成。有时新版本需要执行数据库迁移查看启动日志确认。问题四动态配置不生效检查步骤确认docker-compose.yml中litellm-proxy的command里--config参数指向的是OpenClaw的API端点http://openclaw:3000/api/litellm/config。手动访问这个端点看是否能返回正确的JSON配置可能需要添加认证头具体看OpenClaw文档。LiteLLM代理默认会有缓存。检查配置中是否有缓存设置或者尝试重启代理服务强制刷新。这套LiteLLM OpenClaw的组合将模型管理的复杂度从应用代码中剥离出来形成了一个专业、可控的中台层。从最初的杂乱无章到现在的统一网关、可视化管理和智能路由整个大模型应用的开发和运维体验得到了质的提升。它可能不是解决所有问题的银弹但对于任何需要管理多个模型、关注成本与稳定性的团队来说投入时间搭建这样一套基础设施回报是显而易见的。