核心结论：LiteLLM 接入 Claude API 的排障不要先改业务代码，建议先验证后端请求，再查网关配置，最后看客户端处理。

运行环境说明

一、最小可运行配置（基准）

以下配置作为后续排障的参考基准：

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 Key"exportLITELLM_MASTER_KEY="sk-litellm-local-test"litellm--configlitellm_config.yaml--port4000

验证模型列表：

curlhttp://localhost:4000/v1/models\-H"Authorization: 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\-H"Content-Type: application/json"\-H"x-api-key:${CLAUDE_API_KEY}"\-H"anthropic-version: 2023-06-01"\-H"anthropic-beta: extended-thinking-2025-01-01"\-d'{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "test"}] }'

直连成功 → 问题在 LiteLLM 层。

Step 2：检查drop_params

litellm_settings:drop_params:false# 确保为 false

Step 3：启用 DEBUG 日志验证 header

exportLITELLM_LOG="DEBUG"

搜索日志中的anthropic-beta，对比入站与出站请求。

修复

litellm_settings:drop_params:false

或在litellm_params中显式声明extra_headers（参考 LiteLLM 文档）。

三、问题二：Streaming 流式输出中断

现象

• stream=true时响应中途断开
• 客户端报错Incomplete chunked read

根因

排查

Step 1：直连测试 Streaming

curlhttps://gw.claudeapi.com/v1/messages\-H"Content-Type: application/json"\-H"x-api-key:${CLAUDE_API_KEY}"\-H"anthropic-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:300

Step 3：客户端超时对齐

importanthropic client=anthropic.Anthropic(api_key="YOUR_API_KEY",base_url="https://你的LiteLLM代理地址",timeout=600,# 必须大于 LiteLLM 的 stream_timeout)withclient.messages.stream(model="claude-haiku-4-5-20251001",max_tokens=1024,messages=[{"role":"user","content":"请写一首短诗"}],)asstream:fortextinstream.text_stream:print(text,end="",flush=True)

修复

litellm_settings:request_timeout:600stream_timeout:300

若频繁 529，配置 fallback：

model_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 found
• LiteLLM 日志显示路由到错误后端

根因

litellm_params.model缺少 provider 前缀，LiteLLM 无法确定协议类型。

配置对照表

排查

Step 1：查询 LiteLLM 已注册模型

curlhttp://localhost:4000/v1/models

Step 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\-H"Content-Type: application/json"\-H"Authorization: Bearer${LITELLM_PROXY_KEY}"\-d'{ "model": "claude-sonnet-5", "messages": [{"role": "user", "content": "hi"}] }'

五、问题四：MCP OAuth 会话状态丢失

现象

• 401 Unauthorized/Missing OAuth session state
• OAuth 授权第一步成功，callback 失败

根因

多实例负载均衡下，session 存储在本地内存，callback 打到无 session 的实例。

排查

Step 1：确认部署模式

Step 2：验证 state 参数一致性

对比三个位置的state：

1. 授权请求 URL 中的state
2. Callback URL 中的state
3. LiteLLM DEBUG 日志中的state

三者必须一致。

Step 3：检查 callback 路径

确保redirect_uri指向 LiteLLM 代理的 callback 端点。

修复

多实例部署配置 Redis：

# 参考 LiteLLM 企业版/文档中的 session backend 配置# 确保 drop_params: false，防止过滤 OAuth 参数litellm_settings:drop_params:false

六、排障速查表

七、分层定位命令集

后端直测（不经过 LiteLLM）

# Anthropic 原生格式curlhttps://gw.claudeapi.com/v1/messages\-H"x-api-key:${CLAUDE_API_KEY}"\-H"anthropic-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\-H"Authorization: Bearer${CLAUDE_API_KEY}"\-H"Content-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\-H"Authorization: Bearer${LITELLM_PROXY_KEY}"\-H"Content-Type: application/json"\-d'{"model":"claude-sonnet-5","messages":[{"role":"user","content":"test"}]}'

启用调试日志

exportLITELLM_LOG="DEBUG"

八、健康检查脚本：一次性验证四类问题

下面这个脚本用于发布前自检：模型列表、普通请求、Streaming、header 透传都测一遍。生产环境运行前请把日志中的 Key 做脱敏。

importosimportsysimportrequests LITELLM_BASE=os.getenv("LITELLM_BASE","http://localhost:4000")LITELLM_KEY=os.getenv("LITELLM_MASTER_KEY","sk-litellm-local-test")MODEL=os.getenv("LITELLM_MODEL","claude-sonnet-5")headers={"Authorization":f"Bearer{LITELLM_KEY}","Content-Type":"application/json",}defcheck_models()->None:r=requests.get(f"{LITELLM_BASE}/v1/models",headers=headers,timeout=30)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,}r=requests.post(f"{LITELLM_BASE}/v1/chat/completions",headers=headers,json=payload,timeout=60)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",headers=headers,json=payload,stream=True,timeout=120,)asr:r.raise_for_status()chunks=0forlineinr.iter_lines(decode_unicode=True):ifline:chunks+=1print("[stream] chunks=",chunks)ifchunks==0: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,file=sys.stderr)sys.exit(1)

推荐把它放进部署流水线：配置变更后先跑健康检查，成功后再切流量。

九、日志脱敏建议

排障时会打开LITELLM_LOG=DEBUG，但 DEBUG 日志可能包含 Authorization、x-api-key或 OAuthstate。保存日志前建议至少做三件事：

# 示例：把常见 Key 字段做粗略脱敏后再发给团队排查python -<<'PY' import re from pathlib import Path path = Path("litellm-debug.log") text = path.read_text(encoding="utf-8", errors="ignore") text = re.sub(r"(Authorization: Bearer )[^'\"\\s]+", r"\1***", text) text = re.sub(r"(x-api-key['\"]?\\s*[:=]\\s*['\"]?)[^'\"\\s,}]+", r"\1***", text, flags=re.I) text = re.sub(r"(api_key['\"]?\\s*[:=]\\s*['\"]?)[^'\"\\s,}]+", r"\1***", text, flags=re.I) Path("litellm-debug.redacted.log").write_text(text, encoding="utf-8") PY

不要把含真实 Key 的日志直接贴到 Issue、论坛或 IM 群里。排障需要的是 header 是否存在、路由是否正确、状态码和响应体摘要，不需要暴露完整密钥。

数据与事实声明

• ClaudeAPI 网关：https://gw.claudeapi.com，发布前需以 2026-07-07 控制台实际展示为准。
• 模型 ID：claude-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 排障指南