星桥OpenAI 兼容 API 中转站接入与排错
接入 OpenAI 兼容 API 时，先确认三个配置：Base URL、API Key、模型名称。星桥的 OpenAI 风格接口使用站点地址加 /v1；如果客户端要求填写完整端点，应按该客户端说明配置，避免重复拼接路径。
第一步：确认模型和密钥
登录控制台创建 API 密钥，在模型价格页面确认模型名称和分组。以下代码使用环境变量，不包含真实密钥。YOUR_MODEL_ID 必须替换为你的密钥可以访问的实际模型。
第二步：获取可用模型
export XINGQIAO_BASE_URL="https://newapi.xingqiaoapi.cn/v1"
export XINGQIAO_API_KEY="替换为你的星桥密钥"
curl "$XINGQIAO_BASE_URL/models" \
-H "Authorization: Bearer $XINGQIAO_API_KEY"模型列表仍受密钥权限与分组限制。不要把网站展示的全部模型视为当前密钥一定可以调用的模型。
第三步：测试最小对话请求
curl "$XINGQIAO_BASE_URL/chat/completions" \
-H "Authorization: Bearer $XINGQIAO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"你好"}],"stream":false}'该示例要求所选模型和渠道支持 Chat Completions。需要 Responses 或 Anthropic Messages 的工具，请使用接入文档中的对应协议地址；不要直接套用此端点。
客户端应该怎么配置？
完整接入文档提供 Cursor、Codex CLI、Claude Code、Cherry Studio、OpenClaw 和 CC Switch 的配置方法。先验证最小请求，再检查流式输出、工具调用和实际任务。不同客户端版本的字段名称可能不同。
常见错误如何排查？
| 现象 | 优先检查 |
|---|---|
| 401 | 密钥是否完整、有效，是否使用 Bearer 请求头。 |
| 403 或权限提示 | 密钥分组、模型限制与账户权限，并阅读实际错误信息。 |
| 404 | 是否重复添加 /v1，端点是否适用于所选协议。 |
| 429 | 并发与速率限制、上游限流；根据错误和重试提示降低频率。 |
| 模型不可用 | 模型名是否逐字一致，密钥是否有权限，分组是否有可用渠道。 |
| 连接成功但工具失败 | 客户端是否需要 Responses、工具调用、图片等额外能力。 |
排错时保存状态码、错误文本和请求时间，并移除密钥及敏感对话。接口兼容并不意味着所有厂商功能都可用，能力以模型、分组和渠道为准。
遇到 503 route_unavailable、频繁限流或模型找不到时，参照状态码与错误代码排查步骤。桌面聊天客户端可参照Cherry Studio 的 New API 配置，不要混用根地址和完整请求端点。