LiteLLM 接入 Claude API 排障完全指南：anthropic-beta、Streaming、路由与 MCP OAuth（2026）

核心结论LiteLLM 接入 Claude API 的排障不要先改业务代码建议先验证后端请求再查网关配置最后看客户端处理。运行环境说明组件版本/地址说明LiteLLM Proxy发布前以当前稳定版为准开源 LLM GatewayClaude API 后端https://gw.claudeapi.comClaudeAPI 网关Anthropic API 地址为https://api.anthropic.com模型claude-sonnet-4-6、claude-haiku-4-5-20251001以控制台列表为准协议Anthropic Messages API / OpenAI Chat Completions API由provider前缀决定一、最小可运行配置基准以下配置作为后续排障的参考基准model_list:-model_name:t-5litellm_params:model:anthropic/claude-sonnet-5api_key:os.environ/CLAUDE_API_KEYapi_base:https://gw.claudeapi.com-model_name:claude-haiku-4-5-20251001litellm_params:model:anthropic/claude-haiku-4-5-20251001api_key:os.environ/CLAUDE_API_KEYapi_base:https://gw.claudeapi.comlitellm_settings:drop_params:falserequest_timeout:600stream_timeout:300保存为litellm_config.yaml后启动exportCLAUDE_API_KEY你的 ClaudeAPI KeyexportLITELLM_MASTER_KEYsk-litellm-local-testlitellm--configlitellm_config.yaml--port4000验证模型列表curlhttp://localhost:4000/v1/models\-HAuthorization: Bearer${LITELLM_MASTER_KEY}如果这里就看不到claude-sonnet-5先不要调业务代码优先检查 YAML 缩进、model_name拼写和 LiteLLM 启动日志。二、问题一anthropic-beta Header 被覆盖或丢失现象Beta 功能请求返回400或功能未生效直连 Claude API 正常走 LiteLLM 代理后失效根因drop_params: true或默认值过滤未知参数导致anthropic-betaheader 未透传。排查Step 1直连验证curlhttps://gw.claudeapi.com/v1/messages\-HContent-Type: application/json\-Hx-api-key:${CLAUDE_API_KEY}\-Hanthropic-version: 2023-06-01\-Hanthropic-beta: extended-thinking-2025-01-01\-d{ model: claude-sonnet-5, max_tokens: 1024, messages: [{role: user, content: test}] }直连成功 → 问题在 LiteLLM 层。Step 2检查drop_paramslitellm_settings:drop_params:false# 确保为 falseStep 3启用 DEBUG 日志验证 headerexportLITELLM_LOGDEBUG搜索日志中的anthropic-beta对比入站与出站请求。修复litellm_settings:drop_params:false或在litellm_params中显式声明extra_headers参考 LiteLLM 文档。三、问题二Streaming 流式输出中断现象streamtrue时响应中途断开客户端报错Incomplete chunked read根因层面原因客户端超时太短、SSE 解析错误LiteLLMstream_timeout未设置或太短后端529 Overloaded、429 Rate Limit排查Step 1直连测试 Streamingcurlhttps://gw.claudeapi.com/v1/messages\-HContent-Type: application/json\-Hx-api-key:${CLAUDE_API_KEY}\-Hanthropic-version: 2023-06-01\-d{ model: claude-haiku-4-5-20251001, max_tokens: 1024, messages: [{role: user, content: 请写一首短诗}], stream: true }期望输出SSE 数据流正常结束。若直连即中断问题在后端。Step 2检查超时配置litellm_settings:request_timeout:600stream_timeout:300Step 3客户端超时对齐importanthropic clientanthropic.Anthropic(api_keyYOUR_API_KEY,base_urlhttps://你的LiteLLM代理地址,timeout600,# 必须大于 LiteLLM 的 stream_timeout)withclient.messages.stream(modelclaude-haiku-4-5-20251001,max_tokens1024,messages[{role:user,content:请写一首短诗}],)asstream:fortextinstream.text_stream:print(text,end,flushTrue)修复litellm_settings:request_timeout:600stream_timeout:300若频繁 529配置 fallbackmodel_list:-model_name:claude-sonnet-5litellm_params:model:anthropic/claude-sonnet-5api_base:https://gw.claudeapi.comfallback:-claude-haiku-4-5-20251001四、问题三模型路由配置错误现象404 model not foundLiteLLM 日志显示路由到错误后端根因litellm_params.model缺少 provider 前缀LiteLLM 无法确定协议类型。配置对照表后端协议provider 前缀api_base 示例Anthropic 原生anthropic/xxxhttps://gw.claudeapi.comOpenAI 兼容openai/xxxhttps://gw.claudeapi.com/v1排查Step 1查询 LiteLLM 已注册模型curlhttp://localhost:4000/v1/modelsStep 2核对配置model_list:-model_name:claude-sonnet-5litellm_params:model:claude-sonnet-5# 缺少前缀错误点litellm_params.model缺少 provider 前缀。model_list:-model_name:claude-sonnet-5litellm_params:model:anthropic/claude-sonnet-5api_base:https://gw.claudeapi.com适用于 Anthropic Messages API。model_list:-model_name:claude-sonnet-5litellm_params:model:openai/claude-sonnet-5api_base:https://gw.claudeapi.com/v1适用于 OpenAI Chat Completions 兼容调用。Step 3验证路由curlhttp://localhost:4000/v1/chat/completions\-HContent-Type: application/json\-HAuthorization: Bearer${LITELLM_PROXY_KEY}\-d{ model: claude-sonnet-5, messages: [{role: user, content: hi}] }五、问题四MCP OAuth 会话状态丢失现象401 Unauthorized/Missing OAuth session stateOAuth 授权第一步成功callback 失败根因多实例负载均衡下session 存储在本地内存callback 打到无 session 的实例。排查Step 1确认部署模式部署模式session 存储要求单实例本地内存即可多实例必须配置 Redis / 共享数据库Step 2验证 state 参数一致性对比三个位置的state授权请求 URL 中的stateCallback URL 中的stateLiteLLM DEBUG 日志中的state三者必须一致。Step 3检查 callback 路径确保redirect_uri指向 LiteLLM 代理的 callback 端点。修复多实例部署配置 Redis# 参考 LiteLLM 企业版/文档中的 session backend 配置# 确保 drop_params: false防止过滤 OAuth 参数litellm_settings:drop_params:false六、排障速查表报错首查配置修复动作401 Unauthorizedx-api-key是否透传检查 header drop_params404 model not foundmodel_list路由加anthropic/或openai/前缀400 Bad Request协议与端点匹配api_base与 provider 前缀对齐429 Rate Limit后端限流配置 retry fallback529 Overloaded模型过载fallback 到轻量模型Streaming 断开超时配置增大stream_timeoutOAuth session 丢失部署架构多实例配 RedisBeta 功能不生效header 透传drop_params: false DEBUG 日志七、分层定位命令集后端直测不经过 LiteLLM# Anthropic 原生格式curlhttps://gw.claudeapi.com/v1/messages\-Hx-api-key:${CLAUDE_API_KEY}\-Hanthropic-version: 2023-06-01\-d{model:claude-sonnet-5,max_tokens:1024,messages:[{role:user,content:test}]}# OpenAI 兼容格式curlhttps://gw.claudeapi.com/v1/chat/completions\-HAuthorization: Bearer${CLAUDE_API_KEY}\-HContent-Type: application/json\-d{model:claude-sonnet-5,messages:[{role:user,content:test}]}通过 LiteLLM 代理# 查询模型列表curlhttp://localhost:4000/v1/models# 测试代理路由curlhttp://localhost:4000/v1/chat/completions\-HAuthorization: Bearer${LITELLM_PROXY_KEY}\-HContent-Type: application/json\-d{model:claude-sonnet-5,messages:[{role:user,content:test}]}启用调试日志exportLITELLM_LOGDEBUG八、健康检查脚本一次性验证四类问题下面这个脚本用于发布前自检模型列表、普通请求、Streaming、header 透传都测一遍。生产环境运行前请把日志中的 Key 做脱敏。importosimportsysimportrequests LITELLM_BASEos.getenv(LITELLM_BASE,http://localhost:4000)LITELLM_KEYos.getenv(LITELLM_MASTER_KEY,sk-litellm-local-test)MODELos.getenv(LITELLM_MODEL,claude-sonnet-5)headers{Authorization:fBearer{LITELLM_KEY},Content-Type:application/json,}defcheck_models()-None:rrequests.get(f{LITELLM_BASE}/v1/models,headersheaders,timeout30)r.raise_for_status()names[item.get(id)foriteminr.json().get(data,[])]print([models],names)ifMODELnotinnames:raiseRuntimeError(f{MODEL}not found in /v1/models)defcheck_chat()-None:payload{model:MODEL,messages:[{role:user,content:回复 ok}],max_tokens:32,}rrequests.post(f{LITELLM_BASE}/v1/chat/completions,headersheaders,jsonpayload,timeout60)r.raise_for_status()print([chat],r.json()[choices][0][message][content])defcheck_stream()-None:payload{model:MODEL,messages:[{role:user,content:数到 5每个数字单独输出}],max_tokens:128,stream:True,}withrequests.post(f{LITELLM_BASE}/v1/chat/completions,headersheaders,jsonpayload,streamTrue,timeout120,)asr:r.raise_for_status()chunks0forlineinr.iter_lines(decode_unicodeTrue):ifline:chunks1print([stream] chunks,chunks)ifchunks0:raiseRuntimeError(stream returned no chunks)if__name____main__:try:check_models()check_chat()check_stream()print(LiteLLM Claude API health check passed.)exceptExceptionasexc:print(health check failed:,exc,filesys.stderr)sys.exit(1)推荐把它放进部署流水线配置变更后先跑健康检查成功后再切流量。九、日志脱敏建议排障时会打开LITELLM_LOGDEBUG但 DEBUG 日志可能包含 Authorization、x-api-key或 OAuthstate。保存日志前建议至少做三件事# 示例把常见 Key 字段做粗略脱敏后再发给团队排查python -PY import re from pathlib import Path path Path(litellm-debug.log) text path.read_text(encodingutf-8, errorsignore) text re.sub(r(Authorization: Bearer )[^\\\s], r\1***, text) text re.sub(r(x-api-key[\]?\\s*[:]\\s*[\]?)[^\\\s,}], r\1***, text, flagsre.I) text re.sub(r(api_key[\]?\\s*[:]\\s*[\]?)[^\\\s,}], r\1***, text, flagsre.I) Path(litellm-debug.redacted.log).write_text(text, encodingutf-8) PY不要把含真实 Key 的日志直接贴到 Issue、论坛或 IM 群里。排障需要的是 header 是否存在、路由是否正确、状态码和响应体摘要不需要暴露完整密钥。数据与事实声明ClaudeAPI 网关https://gw.claudeapi.com发布前需以 2026-07-07 控制台实际展示为准。模型 IDclaude-haiku-4-5-20251001、claude-sonnet-5发布前需以控制台模型列表为准。LiteLLM 配置参数基于 LiteLLM 开源项目公开文档与社区配置2026-07-07 复核请以 LiteLLM 当前版本文档为准。额外核验点LiteLLM 文档已有 Anthropic provider、Drop Unsupported Params、/v1/messages和 Auto Sync Anthropic Beta Headers 页面如果你的配置依赖 beta header发布前建议确认当前版本是否需要手动设置或可自动同步。curl 命令基于 Anthropic Messages API 与 OpenAI Chat Completions API 规范编写。本文的持续更新版本可查看LiteLLM 接入 Claude API 排障指南