🤖 AI 摘要
OpenAI-compatible API Gateway 是指使用与 OpenAI API 相同请求格式的 API 代理服务。它通过统一的 Base URL + API Key 机制，让各种客户端（Codex CLI、Cursor、Continue、LobeChat、NextChat 等）无需修改代码，只需要更换 Base URL 即可切换到不同的模型源。Link-AI 提供 api1（普通请求）和 api2（长任务直连）两个通道，兼容主流 OpenAI-compatible 客户端。选对 Base URL 和通道，可以显著减少 401、403、524 等错误。
💡 直接答案
OpenAI-compatible 的核心是 Base URL + API Key。换 Base URL = 换模型源，换 API Key = 换账户。Codex CLI、Claude Code 等长任务工具用 api2.link-ai.cc/v1；普通聊天工具（Cursor 快速问答、LobeChat）用 api1.link-ai.cc/v1。常见错误：401 = Key 无效，403 = 没权限，404 = 路径错误，524 = 超时（换 api2）。
OpenAI-compatible 是什么
OpenAI-compatible 是指 API 的请求格式与 OpenAI 官方 API 完全兼容：
- 请求格式：
POST /v1/chat/completions - 认证方式：
Authorization: Bearer sk-xxx - Body 结构：
model、messages、max_tokens等字段
只要中转站支持这个格式，客户端就可以通过换 Base URL 来接入，而不需要任何代码修改。
Base URL 和 API Key 的关系
- Base URL：API 服务器地址，决定请求发到哪里。例如
https://api1.link-ai.cc/v1 - API Key：身份认证令牌，从 Link-AI 控制台获取
- 两者的关系：Base URL 决定用哪个模型源（哪个中转站），API Key 决定用哪个账户
为什么很多客户端只要换 Base URL
因为这些客户端内置了 OpenAI API 兼容层。用户只需要：
- 填入 Base URL（指向 Link-AI 而不是 OpenAI）
- 填入从 Link-AI 获取的 API Key
- 选择想用的模型（claude-3-opus、gpt-4 等）
客户端会自动用 OpenAI 兼容格式发送请求，Link-AI 会处理并路由到对应模型。
主流客户端接入指南
| 客户端 | 使用场景 | 推荐文档 | 推荐 Base URL |
|---|---|---|---|
| Codex CLI | 编码代理、长任务 | docs/codex-cli | https://api2.link-ai.cc/v1 |
| Claude Code | 长上下文/Agent | docs/claude-code | https://api2.link-ai.cc/v1 |
| Cursor | IDE 编程 | docs/cursor-api-base-url | api1 或 api2 |
| Continue | IDE 插件 | docs/continue-api-base-url | api1 或 api2 |
| LobeChat / NextChat | 聊天前端 | docs/lobechat-nextchat | https://api1.link-ai.cc/v1 |
api1 / api2 怎么选
| 通道 | Base URL | 适合场景 | 不适合场景 |
|---|---|---|---|
| api1 | https://api1.link-ai.cc/v1 |
普通聊天、LobeChat、快速问答 | Claude Code 长任务、Codex CLI |
| api2 | https://api2.link-ai.cc/v1 |
Claude Code、Codex CLI、长上下文 | 对响应延迟敏感的快速问答 |
常见错误排查
| 错误码 | 含义 | 常见原因 | 解决方案 |
|---|---|---|---|
| 401 | 认证失败 | API Key 无效、未设置、格式错误 | 检查 ANTHROPIC_AUTH_TOKEN 或 Authorization header |
| 403 | 权限不足 | Key 没有该模型访问权限、用户分组限制 | 在控制台检查模型授权，参考 403 排查 |
| 404 | 未找到 | Base URL 路径错误、模型名不存在 | 确认 Base URL 是 /v1 结尾，模型名正确 |
| 524 | 超时 | 任务太长，Cloudflare 120s 超时 | 切换到 api2 直连通道，参考 524 排查 |
| 503 | 服务不可用 | 上游过载或暂时不可用 | 等待后重试，检查渠道状态，参考 503 排查 |
Link-AI 的接入路径
- 注册账号：api1.link-ai.cc/#/register
- 创建 API Key：在控制台 #/console/token 创建
- 选择客户端对应文档：根据上表的客户端类型，选择对应的配置文档
- 测试连通性：用 curl 或客户端自带测试功能验证
快速接入 Link-AI
注册后即可获取 API Key，支持所有主流 OpenAI-compatible 客户端
普通请求: https://api1.link-ai.cc/v1
|
长任务: https://api2.link-ai.cc/v1
FAQ
OpenAI-compatible 是什么？
OpenAI-compatible 指使用与 OpenAI API 相同的请求格式（Base URL + API Key + /v1/chat/completions），让各种客户端无需修改代码即可通过换 Base URL 接入不同模型。
Base URL 和 API Key 是什么关系？
Base URL 是 API 服务器地址，API Key 是身份认证令牌。更换 Base URL 可以切换到不同模型源，更换 API Key 可以切换到不同账户。
Codex CLI 用 api1 还是 api2？
Codex CLI 用于编码代理和长任务，推荐使用 api2.link-ai.cc/v1 作为 Base URL，可以有效减少 524 超时问题。
Cursor 适合用哪个通道？
Cursor 的普通聊天可以用 api1，长代码生成和重构任务建议用 api2。可以根据实际体验选择，api2 更稳定但响应可能稍慢。
LobeChat 用哪个 Base URL？
LobeChat 的聊天场景通常单次请求时间不长，可以用 api1.link-ai.cc/v1。详细配置参考 docs/lobechat-nextchat。
常见错误 401、403、404、524 分别是什么意思？
401 是 API Key 无效或未设置；403 是 Key 没有该模型的访问权限；404 是 Base URL 路径错误或模型不存在；524 是请求超时（任务太长了）。