kukuai.fyi 通用接入教程

一篇统一 Claude 与 OpenAI 兼容心智的上手教程：理解 kukuai.fyi 是什么、如何选择模型与线路、如何跑通第一次请求，以及接下来应该看哪篇文档。

kukuai.fyi 是一个面向开发者的统一大模型 API 网关。你不需要为每个模型单独维护一套接入方式，只要把请求指向 kukuai.fyi，就可以在同一套协议下切换不同模型、不同线路和不同工具。

从使用者角度看，它解决的是三类问题：

把多家模型统一成一套接口：你可以在 OpenAI 兼容工具里接入，也可以在 Claude / Anthropic 风格工具里接入。
把网络选择统一成一个开关：中国调用、海外全球加速、主域都可以作为等价端点使用。
把配置打包成可导出的文件：在控制台里选好 API Key、模型、调用线路和目标工具后，就能直接导出或一键导入。

如果你已经会用 OpenAI SDK 或 Claude Code，这个教程会告诉你如何尽量少改代码；如果你还没接触过这些工具，它也会告诉你该从哪一步开始。

适合谁 / 这篇教程适用对象

你适合先看这篇教程，如果你是：

第一次接入 kukuai.fyi，想先建立整体心智；
已经在用 OpenAI SDK，想最低成本迁移；
已经在用 Claude Code / Anthropic SDK，想把同一套配置换到 kukuai.fyi；
团队里有多种工具（Claude Code、Cursor、OpenCode、cURL、Python、Node.js），希望统一成一套 Base URL 和一组模型。

你看完后应该能做到：

理解 OpenAI 兼容 和 Claude 兼容 的区别；
知道什么时候用 https://www.kukuai.fyi/api-proxy/china/v1，什么时候用根地址；
会用 API Key + 模型 + 线路 + 工具这四个变量组合成一套可用配置；
能在 cURL、Python、Node.js、Claude Code、Cursor 里跑通第一次请求；
遇到 401、404、429、超时等常见问题时知道先查什么。

Claude 与 OpenAI 通用兼容心智

你可以把 kukuai.fyi 理解成“统一入口”。它不是让你再学一套全新的模型协议，而是把两种最常见的接法包在一起：

接入模式

典型工具

Base URL 形态

你通常要改什么

OpenAI 兼容

OpenAI Python / Node SDK、Cursor、OpenCode、cURL、Hermes、很多第三方框架

https://www.kukuai.fyi/api-proxy/china/v1

只改 base_url 和 api_key，其余尽量不动

Claude / Anthropic 兼容

Claude Code、Anthropic SDK、OpenClaw

https://www.kukuai.fyi/api-proxy/china

只改 base_url / endpoint 路径，让工具按 Claude 风格发请求

核心原则：

同一个 API Key 可以同时用于多种工具；
同一个模型 可以在不同工具里复用；
同一组端点 在中国调用、海外全球加速和主域之间是等价的；
你真正需要关心的，通常只有 工具类型、Base URL、默认模型、网络线路。

mental modeltext

OpenAI 风格工具 / SDK
  → Base URL：以 /v1 结尾
  → 例：https://www.kukuai.fyi/api-proxy/china/v1
  → 典型：OpenAI Python / Node SDK、Cursor、OpenCode、cURL、Hermes

Claude / Anthropic 风格工具 / SDK
  → Base URL：根地址，不带 /v1
  → 例：https://www.kukuai.fyi/api-proxy/china
  → 典型：Claude Code、Anthropic SDK、OpenClaw

你真正要记住的一句话
  → OpenAI 风格用 /v1，Claude 风格用根地址。

开始前需要准备什么

开始之前，先完成下面这个最小清单：

before you starttext

1. 前往 kukuai.fyi 控制台创建一把 API Key
2. 选一个默认模型（先求跑通，不必一上来就纠结最强）
3. 选对线路（中国调用 / 海外全球加速 / 海外直连 / 海外 CDN / 主域）
4. 识别你当前工具属于 OpenAI 风格还是 Claude / Anthropic 风格
5. 先发一条最小请求验证连通性

准备一个 API Key

先去 kukuai.fyi 控制台创建一把 Key。Key 是你的身份凭证，后续所有请求都会带上它。

建议你这样管理：

给每个项目 / 环境单独建一把 Key；
Key 只放在服务端或受控配置里；
截图、日志、分享文档时都要脱敏；
一旦怀疑泄露，立刻 revoke 并重新生成。

选一个默认模型

如果你是新用户，建议先选一个最能代表你主要场景的模型：

通用聊天 / 产品原型：优先选响应快、稳定的通用模型；
复杂推理 / 长文档：优先选 Claude 系较强推理模型；
代码与 Agent 工作流：优先选适合编程和 tool use 的模型；
多模态任务：按你是否需要图像 / 音频 / 视频接口再做选择。

不要在第一步就纠结“最强模型是哪一个”，更重要的是先跑通一次。

选对线路

如果你在中国大陆网络环境，优先选择中国调用；如果你在海外服务器、海外团队或跨境网络里工作，优先选择海外全球加速。

这些端点是等价的：

https://www.kukuai.fyi/api-proxy/china/v1
https://www.kukuai.fyi/api-proxy/china/v1
https://www.kukuai.fyi/api-proxy/china/v1
https://www.kukuai.fyi/api-proxy/china/v1
https://www.kukuai.fyi/api-proxy/china/v1

它们共享同一套 API Key、模型和字段语义，只是网络路由不同。

逐步接入流程

下面是最稳妥的顺序：

创建或选择 API Key
决定你要用的模型
选择网络线路
确认你要接入的工具属于 OpenAI 还是 Claude 风格
生成配置或直接拼 Base URL
先发一条最小请求验证连通性
再扩展到正式业务场景

如果你第一次接入失败，不要同时改很多变量。先只改一项：

先换线路；
再检查 Base URL；
再检查模型名；
最后检查 API Key。

按工具接入

cURL：最快的连通性验证

适合想快速确认“这条链路能不能通”的场景。你应该用它来：

排查网络问题；
验证 API Key 是否有效；
验证模型名是否拼对；
给 QA 或 CI 做健康检查。

curl-openai-compatible.shbash

curl https://www.kukuai.fyi/api-proxy/china/v1/chat/completions \
  -H "Authorization: Bearer $KUKUAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "messages": [
      {"role": "user", "content": "用一句话介绍 kukuai.fyi"}
    ]
  }'

Python SDK

如果你写的是 Python 服务，通常有两种情况：

OpenAI SDK 风格：直接把 base_url 换成 https://www.kukuai.fyi/api-proxy/china/v1；
Claude / Anthropic 风格：把 SDK 的 endpoint 指向根地址，并保持 Claude 风格请求结构。

适合：Web 服务、脚本、数据分析、Agent 原型。

python-openai-compatible.pypython

from openai import OpenAI

# OpenAI 风格工具 / SDK：base_url 以 /v1 结尾
client = OpenAI(
    base_url="https://www.kukuai.fyi/api-proxy/china/v1",
    api_key="YOUR_KUKUAI_API_KEY",
)

resp = client.chat.completions.create(
    model="claude-haiku-4-5-20251001",
    messages=[{"role": "user", "content": "用一句话介绍 kukuai.fyi"}],
)
print(resp.choices[0].message.content)

Node.js SDK

如果你在前后端同构或 Next.js / Express 项目里开发，Node.js SDK 是最常见的选择。

适合：

API 服务端代理；
前端项目的边缘函数；
CLI 工具；
流式输出和工具调用。

node-openai-compatible.tstypescript

import OpenAI from "openai";

// OpenAI 风格工具 / SDK：baseURL 以 /v1 结尾
const client = new OpenAI({
  baseURL: "https://www.kukuai.fyi/api-proxy/china/v1",
  apiKey: process.env.KUKUAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "claude-haiku-4-5-20251001",
  messages: [{ role: "user", content: "用一句话介绍 kukuai.fyi" }],
});
console.log(resp.choices[0].message.content);

Claude Code

Claude Code 的重点不是“写一个请求”，而是“让 AI 以开发者助手的方式工作”。

适合：

理解代码库；
修改文件；
跑测试；
创建 PR；
做持续性开发任务。

这类工具通常走 Claude / Anthropic 风格配置，所以你要优先确认根地址和目标模型是否匹配。

Cursor / OpenCode / OpenClaw / Hermes

这类工具通常已经提供了某种“兼容 OpenAI 或 Claude”的输入项。你要做的事情就是：

选对工具类型；
填对 Base URL；
填对 API Key；
选对默认模型。

如果工具本身支持导入配置，那就把它交给配置文件导出页面生成。

为什么要有配置文件导出

如果你只是单次测试，手工填 Base URL 和 Key 就够了。

如果你已经在多个工具之间切换，就会反复遇到这些问题：

每个工具配置项名字不一样；
有的工具要 /v1，有的工具不要；
有的工具要单独的模型名映射；
有的工具需要导入链接，有的工具需要配置文件。

配置文件导出页面就是为了解决这些碎片化问题：

先把 API Key、模型和线路选对；
再选目标工具；
页面自动生成对应格式；
要么复制到目标工具，要么一键导入 CC Switch。

如果你是团队负责人，这个页面尤其适合拿来统一标准。

常见错误与排障

401：API Key 有问题

Key 是否复制完整；
是否已经被 revoke；
是否填到了正确的环境变量；
是否在客户端暴露了 Key。

404：Base URL 或路径不对

OpenAI 风格是不是忘了 /v1；
Claude 风格是不是错误地拼了 /v1；
你是否把中国调用 / 海外全球加速混用了；
你要调用的 endpoint 是否和模型类型一致。

429：限速或配额到了

当前 Key 的配额；
是否并发过高；
是否触发了重试风暴；
是否应该改用更稳定的模型或更低并发。

网络超时

当前线路是否适合你的网络；
是不是本地网络到网关慢，还是网关到上游慢；
是否需要切换线路重新导出配置。

模型不可用 / model not found

模型名是否拼错；
该 Key 是否允许调用这个模型；
该模型是否属于当前线路支持的集合；
是否需要重新导出配置。

最佳实践

先验证，再扩展：先用 cURL 或最小 SDK 调通，再上到复杂工具。
先统一，再分流：团队内先统一默认模型和默认 Base URL，再根据地区切线路。
Key 和模型分开管理：一个项目一把 Key，一个场景一个默认模型。
不要把 Key 写进前端：浏览器和客户端都不能作为 secret 的最终存放地。
保留排障证据：出问题时保留 request_id、时间、模型名、线路和错误码。
把文档和控制台一起看：本文档负责方法，控制台负责实时状态和数值。

应该搭配阅读哪些文档

建议阅读顺序：

产品概览 —— 先理解 kukuai.fyi 是什么；
快速开始 —— 跑通第一次请求；
认证与计费 —— 理解 Key、限速、计费和安全；
API Reference —— 看完整字段；
模型导航 —— 选模型；
配置文件导出 —— 把配置分发到具体工具；
FAQ —— 查常见问题。

一句话总结

如果你只记住一句话，那就是：

如果这篇文档和你的实际工具行为有差异，请以控制台实时配置为准。

kukuai.fyi 通用接入教程 ​

适合谁 / 这篇教程适用对象 ​

Claude 与 OpenAI 通用兼容心智 ​

开始前需要准备什么 ​

准备一个 API Key ​

选一个默认模型 ​

选对线路 ​

逐步接入流程 ​

按工具接入 ​

cURL：最快的连通性验证 ​

Python SDK ​

Node.js SDK ​

Claude Code ​

Cursor / OpenCode / OpenClaw / Hermes ​

为什么要有配置文件导出 ​

常见错误与排障 ​

401：API Key 有问题 ​

404：Base URL 或路径不对 ​

429：限速或配额到了 ​

网络超时 ​

模型不可用 / model not found ​

最佳实践 ​

应该搭配阅读哪些文档 ​

一句话总结 ​