先给结论如果你的 Python 脚本调 API 返回 403而完全相同的请求用 curl 是 200先别怀疑 key。大概率是urllib/requests的默认 User-Agent 被 CDN 的 WAF 拦了——它返回的 403 和「鉴权失败」的 403 长得几乎一样但根本不是一回事。判别只要一步看 403 的响应体。响应体长什么样真正的原因纯文本error code: 1010WAF 拦截跟你的 key 无关JSON{error:{type:authentication_error,...}}鉴权真的失败了JSON{error:{type:permission_error,...}}key 有效但没这个权限下面是我实际走过的三条错误排查路径以及最后怎么定位的。命令都能直接复制运行。实测环境WSL2 (Ubuntu) Python 3.12端点用的是 Code2AIcode2ai.codes的 Anthropic 兼容网关前面挂着 Cloudflare。任何前置 CDN 的端点都会复现同样的现象。一、现象同端点、同 key、同 payload两个客户端两个结果我在跑一个自检脚本四项检查全部返回 403。脚本本身逻辑很简单就是往/v1/messages发几个最小请求。① 假模型名探测 ⚠️ 无法确认 HTTP403响应不是 Anthropic 的{type:error,error:{...}}结构 ② 上游响应头 ⚠️ 无法确认 ③ prompt caching ⚠️ 无法确认 HTTP403④ usage 字段结构 ⛔ 请求失败四项全灭看起来像是这个端点整个不可用或者 key 废了。但换 curl 发同一个请求curl-sS-XPOST$ANTHROPIC_BASE_URL/v1/messages\-Hcontent-type: application/json\-Hx-api-key:$ANTHROPIC_AUTH_TOKEN\-Hanthropic-version: 2023-06-01\-d{model:claude-sonnet-5,max_tokens:8, messages:[{role:user,content:hi}]}\-w\n[HTTP %{http_code}]\n{id:msg_01d6f8...,type:message,role:assistant,content:[{type:text,text:Hi! How can I help you today}],usage:{input_tokens:1593,output_tokens:105,...}}[HTTP200]200。同一个 key同一个 payload同一台机器差别只在客户端。二、三条错误的排查路径我全走了一遍排到这一步很容易往三个方向猜这三个方向都是错的。写下来省得你重复走。猜测怎么验证实测结果key 无效或过期换 curl 打同一个请求❌ 200key 是好的鉴权头形式不对x-api-key与Authorization: Bearer各打一次❌ 两种都 200端点挂了 / 路径不对不带任何凭证打一次看它怎么回❌ 端点活得好好的2.1 别急着换 key最直觉的反应是「key 是不是废了」。验证成本很低换个客户端打一次就知道curl-sS-o/dev/null-w%{http_code}\n-XPOST$ANTHROPIC_BASE_URL/v1/messages\-Hcontent-type: application/json-Hx-api-key:$ANTHROPIC_AUTH_TOKEN\-Hanthropic-version: 2023-06-01\-d{model:claude-sonnet-5,max_tokens:8,messages:[{role:user,content:hi}]}返回 200 就说明 key 没问题问题在你的客户端。这一条能砍掉一大半排查方向。2.2 两种鉴权头都试一次Anthropic 协议用x-api-key但很多兼容网关同时接受Authorization: Bearer。如果只试了一种容易误判成「这个端点不认我的鉴权方式」。实测两种都是 200# 形式一-Hx-api-key:$ANTHROPIC_AUTH_TOKEN# 形式二-HAuthorization: Bearer$ANTHROPIC_AUTH_TOKEN顺带一提这两种都支持是兼容网关的常见做法不代表任何异常。2.3 不带凭证打一次——这一步信息量最大这是我认为最被低估的一条排查动作故意不带 key 发一个请求看端点怎么拒绝你。curl-sS-XPOST$ANTHROPIC_BASE_URL/v1/messages\-Hcontent-type: application/json-d{}{error:{type:invalid_request_error,message:API key required. Use x-api-key or Authorization: Bearer header,request_id:c2a-990d2533}}这一个请求同时告诉你三件事端点是活的能正常处理请求它的错误响应是标准 JSON 结构带type和request_id它接受哪些鉴权头——直接写在报错里了第 2 点是关键既然这个端点拒绝请求时会返回结构化 JSON那我脚本收到的那个非 JSON的 403就一定不是这个端点发出来的。是中间有人替它回了。三、真正的原因默认 User-Agenturllib不设置 User-Agent 时默认发的是Python-urllib/3.12。Cloudflare 一类的 WAF 会直接拒掉这类特征明显的客户端签名。它返回的东西长这样HTTP403error code:1010纯文本没有 JSON 结构。Cloudflare 的 1010 是「基于浏览器签名拒绝访问」。这个 403 的迷惑性在于状态码和「鉴权失败」完全一样大部分客户端代码只看status_code不看 body于是它被当成「key 不对」或「没权限」排查方向从第一步就偏了四、控制变量确认只改 UA要坐实这个判断把其他变量全固定住只改 User-Agent跑一次对照importos,json,urllib.request,urllib.error BASEos.environ[ANTHROPIC_BASE_URL]BODYjson.dumps({model:claude-sonnet-5,max_tokens:8,messages:[{role:user,content:hi}]}).encode()defgo(ua):h{content-type:application/json,x-api-key:os.environ[ANTHROPIC_AUTH_TOKEN],anthropic-version:2023-06-01}ifua:h[user-agent]ua requrllib.request.Request(BASE/v1/messages,dataBODY,headersh,methodPOST)try:rurllib.request.urlopen(req,timeout30)returnfHTTP{r.status}excepturllib.error.HTTPErrorase:returnfHTTP{e.code}body:{e.read()[:60].decode(utf-8,ignore)}print(默认 UA:,go(None))print(普通 UA:,go(my-tool/1.0))实测输出默认 UA: HTTP403body: error code:1010普通 UA: HTTP200一行 header 的差别。其余全部相同。修复就是给你的客户端一个正常的 UA。建议报上工具自己的身份而不是伪装成浏览器——目的是可被识别不是绕过USER_AGENTmy-tool/1.0 (https://github.com/yourname/yourrepo)requests库默认 UA 是python-requests/2.x同样会被拦处理方式一样。五、同一家族的另外两类假象「表现像 A、实际是 B」的问题不止这一个。下面两类同样高频同样会把人带偏。5.1 代理环境变量看起来像「端点不通」本机配过http_proxy/https_proxy而那个代理地址已经不可用了。于是每个请求都要先去撞一次超时最后报连接失败——看起来和「端点挂了」一模一样。诊断env|grep-iproxy如果有输出先摘掉再测env-uhttp_proxy-uhttps_proxy-uHTTP_PROXY-uHTTPS_PROXY\curl-sS-o/dev/null-w%{http_code}\n$ANTHROPIC_BASE_URL/v1/messages-XPOST-d{}自检脚本里最好直接把这几个变量摘掉——你要测的是端点不是本机的网络配置forkin(http_proxy,https_proxy,HTTP_PROXY,HTTPS_PROXY,all_proxy,ALL_PROXY):os.environ.pop(k,None)这个现象的完整诊断流程我单独写过一份请求全部超时的排查记录里面按「本机 → DNS → 端点」分层给了命令。5.2base_url多写了一段404 而不是 403配ANTHROPIC_BASE_URL时把/v1/messages也写进去了# ❌ 错误exportANTHROPIC_BASE_URLhttps://example.com/v1/messages客户端会自己补/v1/messages实际请求路径变成/v1/messages/v1/messages然后吃一个莫名其妙的 404。写到域名为止就行# ✅ 正确exportANTHROPIC_BASE_URLhttps://example.com判别方法是直接看实际请求的完整 URL。这个坑和它的几种变体我整理在ANTHROPIC_BASE_URL 配置 404 的排查里。六、一个通用原则排查外部端点先建两个对照组上面三类假象的共同点是——故障现象出现的位置和故障原因所在的位置不是同一个地方。报错在你的脚本里原因在 CDN、在本机环境变量、在配置字符串里。想快速定位动手改代码之前先建两个对照组对照组怎么做能排除什么换客户端同一个请求用 curl 再打一次区分「端点问题」和「客户端问题」去掉凭证故意不带 key 打一次确认端点活着、看清它的错误结构长什么样两条都跑完绝大多数「403 / 404 / 超时」类问题的方向就定了。剩下的才值得去读代码。这类排查我整理成了一份手册放在 claude-code-cn-setupMIT——按「安装 / 请求 / 升级」三层分开每个报错都给了可直接复制的诊断命令。本文这个 UA 的坑收在docs/troubleshooting.md另外一项更难自己想到的是MTU 黑洞小请求正常、一发长内容就卡死因为路径 MTU 发现依赖的 ICMP 被中间设备丢了大包静默进黑洞——表现是「卡住」而不是「报错」。FAQQ为什么 curl 能过Python 不能curl 默认会发User-Agent: curl/8.xWAF 通常放行urllib默认发Python-urllib/3.x属于被拦截的特征。差别只在这一个 header。Q换requests库会不会好一点不会。requests默认 UA 是python-requests/2.x同样在拦截名单里。显式设置 UA 才是解法。Q自己加 User-Agent 算不算绕过风控看你加成什么。报上工具自己的名字和仓库地址是标准做法HTTP 规范里 UA 本来就是用于标识客户端的把 UA 伪装成 Chrome 浏览器则是另一回事。这两者的区别是「让我可以被识别」和「让我看起来像别人」。Q怎么快速确认是 WAF 拦截还是端点本身拒绝看 403 的响应体。WAF 返回的通常是纯文本或一整页 HTMLAPI 端点返回的是带type和request_id的结构化 JSON。另外看响应头有没有CF-RAY、Server: cloudflare这类 CDN 特征。Q状态码就一定能说明问题吗不能这正是本文的主题。403 可能来自 WAF、可能来自鉴权、可能来自权限404 可能是路径拼错、可能是模型名不存在。状态码只是入口响应体才是证据。小结现象先查什么而不是脚本 403、curl 200客户端 User-Agent换 key403 body 是纯文本CDN / WAF鉴权配置所有请求超时env | grep -i proxy端点可用性配置看着都对却 404base_url是否多写了/v1/messages重装客户端排查外部端点的时候先固定变量再改代码。换个客户端打一次、去掉凭证打一次这两个动作加起来不到一分钟能省掉一下午。