Claude Gateway 排查教程check_claude_gateway.sh完整脚本源码与使用原理在 Claude 桌面端配置 Third-Party Inference / Gateway 后常见的问题不是“完全打不开”而是Claude 界面可以进入模型下拉框可以选择消息可以发送但一直停在Preparing session...或者返回Something went wrong或者报ContextWindowExceededError或者接口返回 200但实际没有任何文本输出这类问题只看 Claude 前端界面很难定位。更有效的方式是直接绕过前端用脚本验证 Gateway 是否真正满足 Claude 所需的 Anthropic Messages API 调用要求。这篇文章提供一个完整脚本check_claude_gateway.sh它可以帮助你快速判断问题出在Gateway 地址API Key/v1/messages路径Anthropic 协议兼容性流式 SSE 返回模型名映射system prompt 支持上下文窗口限制一、脚本适合解决什么问题当你遇到下面情况时建议优先运行这个脚本1. Claude 一直卡在Preparing session...这通常说明 Claude 已经尝试初始化会话但没有收到它期望的有效响应。可能原因包括Gateway 不支持 Anthropic Messages API流式事件格式不对返回内容为空模型路由异常请求被网关吞掉或超时2. Claude 报Something went wrong这类错误通常比较模糊前端不会告诉你后端真正发生了什么。脚本可以直接看到 HTTP 状态码和返回体例如401 Unauthorized403 Forbidden404 Not Found500 Internal Server ErrorContextWindowExceededErrormodel not foundinvalid request3. 模型能选但不能正常回答有些模型会出现在 Claude 的模型列表里但不代表它真的能通过当前 Gateway 的 Anthropic 路由正常调用。脚本可以验证这个模型名是否真的可调用是否能返回正常文本是否支持流式是否支持 system prompt4. 想确认 Gateway 是否真的兼容 Anthropic API很多中转网关会支持 OpenAI API但不一定完整支持 Anthropic Messages API。Claude Gateway 更关注的是POST /v1/messages而不是POST /v1/chat/completions所以这个脚本重点验证/v1/messages。二、完整脚本源码新建一个文件check_claude_gateway.sh写入以下内容#!/usr/bin/env bash# # check_claude_gateway.sh## 用途# 检查 Claude Desktop Third-Party Inference / Gateway# 是否真正支持 Anthropic Messages API。## 检查内容# 1. 基础连通性# 2. 非流式 /v1/messages# 3. 流式 /v1/messages# 4. 带 system prompt 的 /v1/messages## 使用方式# 1. 修改 BASE_URL / API_KEY / MODEL# 2. chmod x check_claude_gateway.sh# 3. ./check_claude_gateway.sh# BASE_URLhttps://你的网关地址API_KEY你的API_KEYMODEL你的模型名echoechoechoClaude Gateway CheckechoechoBASE_URL:$BASE_URLechoMODEL:$MODELechoechoecho 1. Basic connectivity curl-I$BASE_URLechoechoecho 2. Non-stream Anthropic Messages API curl-i$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\messages\: [ {\role\:\user\,\content\:\hi\} ] }echoechoecho 3. Stream Anthropic Messages API curl-N$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\stream\: true,\messages\: [ {\role\:\user\,\content\:\hi\} ] }echoechoecho 4. Messages API with system prompt curl-i$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\system\:\You are a helpful assistant.\,\messages\: [ {\role\:\user\,\content\:\Say hello\} ] }echoechoecho Done 三、如何使用脚本第一步保存脚本在终端执行vimcheck_claude_gateway.sh或者用你习惯的编辑器新建文件。把上面的完整脚本粘贴进去。第二步修改三个核心变量脚本顶部有三个变量BASE_URLhttps://你的网关地址API_KEY你的API_KEYMODEL你的模型名你需要替换成自己的配置。例如BASE_URLhttps://gateway.example.comAPI_KEYsk-xxxxxxMODELz-ai/glm-5.1注意BASE_URL最好不要以/结尾。推荐BASE_URLhttps://gateway.example.com不推荐BASE_URLhttps://gateway.example.com/因为脚本里会自动拼接$BASE_URL/v1/messages如果末尾多一个/可能变成https://gateway.example.com//v1/messages某些网关可能能兼容某些则不能。第三步赋予执行权限chmodx check_claude_gateway.sh第四步执行脚本./check_claude_gateway.sh四、脚本每一步在检查什么1. 基础连通性检查脚本第一段curl-I$BASE_URL这一段只做一件事确认这个网关地址是否有服务响应。它不要求一定返回 200。比如你可能看到HTTP/2 200也可能看到HTTP/2 405 allow: GET甚至可能看到HTTP/2 401这些都说明请求已经到达某个服务。真正有问题的是连接超时DNS 解析失败SSL 握手失败无任何响应代理层直接断开如果基础连通性都失败就不用继续排查模型了优先检查域名是否正确网络是否可达VPN / 代理是否生效网关服务是否启动HTTPS 证书是否正常2. 非流式/v1/messages检查脚本第二段curl-i$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\messages\: [ {\role\:\user\,\content\:\hi\} ] }这是最关键的一步。它验证的是你的 Gateway 是否支持 Anthropic Messages API。Claude Gateway 重点关注的是/v1/messages而不是 OpenAI 风格的/v1/chat/completions正常结果应该长什么样如果正常HTTP 状态码应该是HTTP/2 200返回体通常类似{id:msg_xxx,type:message,role:assistant,model:xxx,content:[{type:text,text:Hello!}],stop_reason:end_turn}重点看这些字段typerolecontentcontent[].typecontent[].textstop_reason如果返回 OpenAI 风格怎么办如果你看到的是{choices:[{message:{role:assistant,content:Hello}}]}这说明它更像 OpenAI Chat Completions 返回格式。这类返回不一定能被 Claude Desktop 正常识别。结论网关可能不是 Anthropic Messages 兼容入口或者协议转换不完整。常见 HTTP 状态码含义状态码含义优先排查200请求成功继续看返回结构和内容401鉴权失败API Key 是否正确403无权限Key 权限、模型权限、网关访问策略404路径不存在是否支持/v1/messages422请求参数不合法字段格式、模型名、provider 要求500后端异常网关日志、provider 调用异常502/503上游不可用模型服务、转发层、负载均衡3. 流式 SSE 检查脚本第三段curl-N$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\stream\: true,\messages\: [ {\role\:\user\,\content\:\hi\} ] }这里的关键是stream:trueClaude Desktop尤其是 Cowork / Code 这类任务模式经常更依赖流式返回。所以非流式成功不代表 Claude 一定能正常工作。正常流式返回应该长什么样一般会看到类似event: message_start data: {...} event: content_block_start data: {...} event: content_block_delta data: {...} event: message_delta data: {...} event: message_stop data: {}重点看content_block_delta里面是否真的有文本{type:content_block_delta,index:0,delta:{type:text_delta,text:Hello}}最危险的情况有事件但没内容有些 Gateway 会返回这样的结果event: content_block_delta data: {delta:{type:text_delta,text:}}如果连续很多个text都是空字符串最后却正常message_stop这说明协议层看起来成功但模型没有产出有效内容。这种问题在 Claude 前端里很容易表现为一直Preparing session...转圈不结束看起来像卡死停止按钮不生效没有明确错误提示这类问题比 401/404 更难查因为 HTTP 层面它可能是成功的。4. 带 system prompt 的检查脚本第四段curl-i$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\system\:\You are a helpful assistant.\,\messages\: [ {\role\:\user\,\content\:\Say hello\} ] }为什么要测system因为 Claude Desktop 的真实请求通常不是简单的一句 user message。它可能会自动拼接大量内容例如system prompt任务说明工具定义工作目录信息进度上下文安全策略会话历史所以一个 Gateway 能处理{role:user,content:hi}不代表它能处理更接近真实 Claude 请求的结构。这一步主要验证什么它主要验证Gateway 是否接受system字段provider 是否能处理 system prompt协议转换层是否会因为 system 字段报错模型是否在更复杂输入下正常输出如果简单消息正常但带 system 报错说明兼容层不完整。如果简单消息异常但带 system 正常说明该模型或路由对不同 prompt 形态表现不一致也需要继续排查。五、如何根据结果判断问题情况一curl -I都失败说明基础网络或地址有问题。优先检查BASE_URL是否写错网络是否能访问是否需要代理HTTPS 证书是否异常网关服务是否启动情况二/v1/messages返回 404说明路径大概率不对。常见原因你填的是 OpenAI 兼容地址这个网关只支持/v1/chat/completionsAnthropic 路由没有开启反向代理没有转发/v1/messages解决方向查看网关文档确认是否有 Anthropic-compatible endpoint确认 Claude 中填写的 Gateway base URL 是否应包含某个前缀路径情况三返回 401 / 403说明鉴权或权限有问题。优先检查API Key 是否填错Key 是否过期Key 是否有模型访问权限网关是否限制来源模型是否对该 Key 开放情况四返回 OpenAIchoices结构说明它不是标准 Anthropic Messages 返回。这类网关可能对普通 OpenAI 客户端可用但不一定适合 Claude Desktop Gateway。解决方向换 Anthropic 兼容入口调整 LiteLLM / OneAPI / 中转配置确认 provider 是否配置为 Anthropic-compatible route情况五HTTP 200但content.text为空这是非常关键的异常。表现可能是content:[{type:text,text:}]同时可能伴随stop_reason:max_tokens这说明接口协议层成功但模型没有生成有效文本。可能原因模型路由异常provider 映射异常Anthropic 转换层有 bug模型名别名解析不一致底层模型输出被过滤流式 delta 被错误转换成空字符串这类情况非常容易导致 Claude 卡在Preparing session...。情况六流式事件正常但全是空text_delta如果你看到event: content_block_delta data: {delta:{type:text_delta,text:}}并且连续很多条都是空字符串说明SSE 事件壳子是对的但内容是坏的。这时不要只看“有没有 message_stop”而要看中间的text_delta是否有真实内容。情况七报ContextWindowExceededError如果 Claude 前端或脚本返回类似ContextWindowExceededError: This models maximum context length is 30000 tokens. However, your request has 35457 input tokens.说明问题是当前模型上下文窗口不够。注意这并不一定是你输入太长。Claude Cowork 会自动拼接大量隐藏上下文包括系统提示词任务初始化说明工具 schema工作目录上下文历史状态所以你输入一句话真实请求可能已经超过 30k tokens。解决方向换更大上下文模型例如 64k / 128k检查网关里 model context window 是否配置过小尽量使用更轻量的模式验证不要用小上下文模型测试 Cowork六、建议增加的增强版测试如果基础脚本发现问题可以继续补充下面几类测试。1. 把max_tokens改小用于判断是否因为输出长度导致异常。curl-i$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 20,\messages\: [ {\role\:\user\,\content\:\hi\} ] }如果max_tokens从 100 改成 20 后仍然空输出说明不是输出长度问题而是生成或协议转换异常。2. 换一个更明确的 prompt例如curl-i$BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$API_KEY\-Hanthropic-version: 2023-06-01\-d{\model\:\$MODEL\,\max_tokens\: 100,\messages\: [ {\role\:\user\,\content\:\Reply with exactly: hello\} ] }如果hi空输出但这个 prompt 正常说明模型或网关对短 prompt 有特殊异常。3. 测真实模型名而不是别名如果你在 Claude 里看到模型名类似360/glm-5.1但接口返回里又出现z-ai/glm-5.1说明网关中可能存在模型别名映射。建议分别测试MODEL360/glm-5.1和MODELz-ai/glm-5.1如果一个异常、一个正常问题就集中在别名映射层。4. 换不同模型横向对比同一个 Gateway 下换多个模型跑同一脚本。例如MODELmodel-a./check_claude_gateway.sh再改成MODELmodel-b./check_claude_gateway.sh通过对比可以判断是 Gateway 整体有问题还是某个模型路由有问题是 GLM 类模型异常还是 Qwen 类模型上下文不够是 Anthropic 转换层通用问题还是单 provider 问题七、推荐的排查顺序建议按下面顺序执行第一步验证地址看curl -I $BASE_URL是否有响应。第二步验证/v1/messages看是否返回 200以及是否是 Anthropic message 结构。第三步验证内容不要只看状态码要看content[].text是否真的有文本。第四步验证流式看content_block_delta里是否有真实text。第五步验证 system看带system的请求是否正常。第六步换模型如果某个模型异常换另一个模型对照。第七步看上下文窗口如果 Cowork 报 context window 超限优先换大上下文模型。八、脚本结论如何用于 Claude Desktop跑完脚本后可以按下面方式判断 Claude Desktop 是否有希望正常工作。比较有希望正常工作的情况同时满足BASE_URL有响应/v1/messages返回 200返回结构是 Anthropic Messages 风格content[].text有真实内容stream: true返回标准 SSEcontent_block_delta有真实文本带system的请求正常模型上下文窗口足够大高概率会卡住的情况出现任一情况都要警惕/v1/messages404返回 OpenAIchoices结构HTTP 200 但content.text为空流式事件全是空text_delta带system报错模型名在 UI 可选但 API 调用时报model not foundCowork 请求超过模型上下文窗口九、为什么“接口能通”不等于“Cowork 可用”这是很多人容易误判的地方。Claude Desktop 的 Cowork 不是普通聊天框。它发给 Gateway 的请求通常更复杂prompt 更长system 内容更多可能包含工具说明可能包含任务状态可能包含工作目录上下文对流式返回更敏感对 Anthropic 协议结构更严格所以curl 能返回 200只能说明接口初步可用。不代表Claude Cowork 一定能正常工作更准确的判断应该是Gateway 可用 Anthropic 协议正确 流式正常 内容非空 上下文足够这些条件都满足Cowork 才比较稳定。十、总结check_claude_gateway.sh的核心价值不是“发几个 curl”而是把 Claude Gateway 的黑盒问题拆成可观察的几层网络是否可达路径是否正确鉴权是否通过是否支持 Anthropic Messages API非流式是否有真实内容流式 SSE 是否正常system prompt 是否兼容模型上下文窗口是否足够当 Claude 卡在Preparing session...时不要只在前端反复点击Try again。先用脚本把 Gateway 打穿一遍基本就能判断问题是在前端、网关、模型路由还是上下文窗口。一句话概括check_claude_gateway.sh是 Claude 第三方 Gateway 接入的最小可观测性脚本。它不负责修复问题但能快速告诉你问题大概率在哪里。