本服务面向非中国大陆地区 · ZetaAPI.AI 的网站与控制台主要面向非中国大陆市场，注册与开通功能在你当前地区不可用。

接入自检 — 连不上 / 填错 / 报错时先跑这条命令

一条命令定位接入问题。分开检查 DNS、TCP、TLS、代理、系统时钟、Base URL 的 /v1 写法、API Key 有效性，以及你的分组下到底有哪些模型可填，并给出每一项该怎么处理。没装 Node 的话另有 curl 版逐步排查。

更新于 2026-09-20

一条命令

npx --prefer-online zetaapi@latest doctor --api-url=https://api.staging.cosmos-router.com

不需要 API Key 就能跑 —— 连不上的时候，你往往还没走到拿 Key 那一步。

想一次把 Key 和 Base URL 也检查掉：

ZETAAPI_KEY=sk-你的Key npx --prefer-online zetaapi@latest doctor --api-url=https://api.staging.cosmos-router.com \
  --client=cline \
  --base-url="https://api.staging.cosmos-router.com/v1"

Key 优先用环境变量传，别写成 --key= —— 后者会出现在进程列表里，同机其他用户可见。

注意：ZETAAPI_KEY=... npx ... 和 export ZETAAPI_KEY=... 都会被 shell 记进 history。 要彻底避免，需要其中之一：命令以空格开头输入（需 shell 开启 HIST_IGNORE_SPACE / HISTCONTROL=ignorespace）、 用交互式读入（read -s ZETAAPI_KEY; export ZETAAPI_KEY）、或在 CI 里用 secret 变量。

--base-url 填你实际配在工具里的那个值，记得加引号（不加的话 < > 会被 shell 当成重定向）。

--client 填你用的工具（cline / cursor / codex / claude-code）。 两种协议对 /v1 的要求正好相反，不指定的话只能把两种情况都列给你，没法直接判定对错。

它检查什么

检查项能发现的问题
代理环境变量curl 能通但工具不通（见下方说明）
DNS 解析域名解析不了、被内网 DNS 拦下
IPv6 (AAAA)纯 IPv6 网络下连不上
TCP 握手端口不通、被防火墙丢包
TLS 握手证书链被中间设备替换、系统时钟不准
逐 IP 探测某一个后端 IP 异常（其余正常）
本机时钟偏差过大导致证书校验失败
Base URL 体检/v1 该不该带、有没有写成 /v1/v1（配合 --client 可直接判对错）
API KeyKey 无效、复制到的是打码显示的串
可用模型你这把 Key 能列出哪些模型名（列得出 ≠ 一定调得通，见文末边界说明）

全部通过时最后一行是 ✔ 全部检查通过。有未通过项时退出码为 1，方便在脚本里判断。

Base URL：到底带不带 /v1

这是接入失败最集中的一处，因为两种协议的要求正好相反：

你用的客户端Base URL 要填为什么
Cline / Cursor / OpenAI SDK / 多数工具（OpenAI 兼容）https://api.staging.cosmos-router.com/v1要带 /v1。客户端会在其后拼 /chat/completions
Claude Codehttps://api.staging.cosmos-router.com不要带 /v1。客户端会自己拼 /v1/messages

Claude 系模型仅限 Claude Code 客户端。用 anthropic 官方 SDK 自建程序调用会被拒绝 —— 这不是 Base URL 的问题，改写法也无效。有此需求请联系我们。

写反了会让请求打到不存在的路径：

多数情况下你会看到 404，但也可能是 401、403、405 或网关的自定义报错 —— 错误码不固定，别只按 404 去排查。

另外，结尾不要多写 / —— 部分客户端会拼出 // 同样导致 404。

自检会直接对你填的值做实测并给出结论：

✗ Base URL 体检              **不适配**你指定的客户端，应填 https://api.staging.cosmos-router.com/v1
    OpenAI 兼容客户端（Cline / Cursor / Codex / OpenAI SDK）  ✗ 应填 https://api.staging.cosmos-router.com/v1
    Claude Code 客户端  ✔ 你填的可用
    实测 GET https://api.staging.cosmos-router.com/models → 404，OpenAI 形状不可用

上面是 Cline 用户漏了 /v1 的典型输出：填的值本身是合法的（对 Claude Code 有效）， 但对他实际用的客户端是错的。指定了 --client 才能判成失败 —— 不指定的话只能两种都列出来。

各项结论怎么处理

⚠ 代理环境变量已设置

Node.js 的 http/https 不会自动使用 HTTPS_PROXY / ALL_PROXY 这些环境变量，而 curl 会。

所以「curl 测能通，但工具里就是连不上」这个现象，多数就是这个差异造成的，并不是你的 Key 或 Base URL 有问题。若你的网络必须走代理，请在工具自身的代理设置里配置，而不是只设环境变量。

✗ DNS 解析失败（ENOTFOUND / EAI_AGAIN）

本机解析不了域名。先核对域名拼写，再用 dig api.zetaapi.ai 或 nslookup 复核。

公司网络下请先咨询内网管理员 —— 自行改公共 DNS 可能绕过公司的分流与安全策略。

✗ 能解析出 IP，但连不上 —— 先确认解析结果是否异常

比上一条隐蔽：nslookup / dig 正常返回了地址，看起来一切都对，但连接失败。表现可能是超时（ETIMEDOUT、UND_ERR_CONNECT_TIMEOUT、curl: (28)），也可能是连接被拒绝或证书校验失败 —— 取决于拿到的那个地址上恰好有什么。

⚠️ 解析异常只是可能原因之一。 拿到正确地址后，路由、防火墙、中间设备或服务本身的问题同样会让你连不上。下面给的是排查线索，不是确诊依据。

怎么取证：用多个解析器查同一个域名做对照。

nslookup api.zetaapi.ai 223.5.5.5      # 阿里
nslookup api.zetaapi.ai 119.29.29.29   # 腾讯

判读时请注意：

拿不准就把 nslookup 的完整输出发给我们，我们可以确认那个地址是否属于当前的服务配置。

可以尝试的处理：

做法说明与限度
换公共解析器改用 223.5.5.5 或 119.29.29.29，改完清缓存。这对「某个解析器给了错答案」有效；如果干预发生在网络路径上，明文查询仍可能被改写
启用加密 DNS（DoH / DoT）保护你到解析器之间这一段不被改写，但不保证解析器本身的答案是对的
用 TUN / 全局模式代理能否接管 DNS 解析取决于该软件的具体配置，不是选了模式就必然生效，改完请复查实际解析路径

清 DNS 缓存：

# Windows
ipconfig /flushdns
# macOS
sudo killall -HUP mDNSResponder

改完后请确认客户端实际走的是新的解析路径（部分运行时自带 DNS 缓存，需要重启进程），再跑一次自检。

✗ 网站能打开，但客户端连不上 API

这是最常见的一种情况。

如果你是用浏览器插件 / 扩展式的代理（SwitchyOmega、各类「VPN」浏览器扩展）打开官网、 完成注册的，那类代理只接管浏览器流量 —— 命令行工具、SDK、编辑器插件都不经过它。 所以网站打得开、注册也成功，但 Cline / Codex / Claude Code 一调用就连不上。

请改用下列任一种：

做法说明
TUN / 虚拟网卡 / 增强模式代理软件接管全部系统流量，最省事，推荐
系统代理需确认你的工具确实遵循系统代理设置（不少工具不遵循）
工具自身的代理设置在 Cline / Cursor 等工具的设置里单独填代理

⚠️ 设置 HTTPS_PROXY 等环境变量对本 CLI 无效（Node 不读取它们）， 对你的工具也未必有效。这正是「curl 能通、工具却不通」的原因。

改完后跑 npx --prefer-online zetaapi@latest doctor --api-url=https://api.staging.cosmos-router.com 确认。

✗ 连接超时（ETIMEDOUT）/ 被重置（ECONNRESET）

自检会标出是哪个阶段超时/被重置（TCP / TLS / HTTP）：

先换一个网络（例如手机热点）验证：换网能通，基本可确认是原链路的问题。若只有本域名异常、其他站点都正常，请把自检报告发给我们。

✗ TLS 证书链校验失败

拿到的证书链无法用本机信任库验证。最常见的是中间设备在解密并重签 TLS（企业安全网关、抓包工具、部分杀毒软件），也可能是本机缺少对应的根证书。

注意各客户端使用的信任库不同（Node 自带一套、系统一套），所以可能只有部分工具受影响。若确认是中间设备所致，需要在该设备上放行本域名。

⚠ 本机时钟偏差过大

TLS 校验对时间敏感，偏差过大会表现为「证书已过期 / 尚未生效」。开启系统自动对时即可。

✗ API Key 401

最常见的原因是：复制到的是控制台上打码显示的字符串（形如 sk-abc····wxyz），它不是真实 Key。请用控制台的复制按钮重新获取完整 Key。

· 列表里有 Claude 系模型，但用不了

Claude 系模型仅限 Claude Code 客户端调用。在 Cline / Cursor / OpenAI SDK 等 OpenAI 兼容客户端里填 Claude 型号会被拒绝，改任何配置都无效。

该填哪个模型名

不要凭印象填。平台按分组开放模型，不同分组可用的型号不同，没有哪个型号对所有分组都可用 —— 照抄别处看到的型号名，很可能得到 model_not_found。

自检的「可用模型」列的是你这把 Key 能列出来的型号，从中挑一个即可。

注意「在列表里」不等于「一定调得通」—— 列表反映的是你分组下开放了哪些型号， 真实调用还可能受余额、限流、客户端类型影响。Claude 系就是典型：它在列表里，但只对 Claude Code 开放。

把报告发给我们

npx --prefer-online zetaapi@latest doctor --api-url=https://api.staging.cosmos-router.com --json > zetaapi-doctor.json

报告里不含 API Key。写入报告前会对 URL 做脱敏：去掉用户名密码、查询串、片段；路径只保留已知的结构片段（如 /v1、/models），其余一律省略；代理只保留协议、地址和端口（仅 http / https / socks*，其余整体省略）。

报告确实会包含你的环境信息（解析到的 IP、代理地址、证书签发者、你分组下的模型列表）—— 这些不是密钥，但属于环境元数据，发给我们之外的第三方前请先过目一遍。

没装 Node？用 curl 逐步排查

自检做的就是下面这几步，可以手动跑：

# 1. DNS —— 应返回 IP
dig +short api.zetaapi.ai

# 2. TCP + TLS + HTTP —— 应返回 200
curl -sS -o /dev/null -w 'http=%{http_code} tcp=%{time_connect}s tls=%{time_appconnect}s\n' \
  https://api.staging.cosmos-router.com/health/ready

# 3. Key 是否有效 + 你能用哪些模型 —— 应返回模型列表
#    先 export ZETAAPI_KEY=sk-你的Key，避免真实 Key 写进命令行
curl -sS https://api.staging.cosmos-router.com/v1/models -H "Authorization: Bearer $ZETAAPI_KEY"

# 4. 真实调用（模型名从上一步的结果里挑）
curl -sS https://api.staging.cosmos-router.com/v1/chat/completions \
  -H "Authorization: Bearer $ZETAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"从第3步挑一个非 Claude 型号","messages":[{"role":"user","content":"hi"}],"max_tokens":16}'

怎么读这几步：

注意 curl 会使用 HTTPS_PROXY 等环境变量，而多数工具不会。若 curl 通而工具不通，请回看上面的「代理环境变量」一节。

这条命令查不到什么

它覆盖的是网络连通性与配置形状，不能替代真实客户端的一次成功调用。以下不在范围内：

所以「自检全绿但工具仍然报错」是可能的 —— 那说明问题出在客户端侧，把报告和客户端的错误原文一起发给我们。

还是没解决

带上 --json 报告，以及以下信息联系我们：