在 ChatBox 中使用 kukuai.fyi

把 kukuai.fyi 接入 ChatBox 桌面端的完整教程：如何配置 OpenAI 兼容接入、如何选择模型、如何验证连通性，以及常见问题怎么排查。

这篇教程的目标不是“知道有个配置项”，而是让你按截图一样把 ChatBox 从空白状态接成可用状态：先填 API Key，再填 Base URL，再选模型，最后做一轮验证。

开始之前，先确认这几件事：

checklisttext

1. 已安装 ChatBox 桌面端
2. 已注册 kukuai.fyi 账号并创建 API Key
3. 已确认你要接入的模型 ID
4. 已知道当前工具是 OpenAI 风格还是 Claude 风格
5. 已准备好一条最小测试消息

你需要什么

建议

原因

ChatBox 桌面端

优先用最新稳定版

新版本通常更好地兼容自定义 API Host 和模型选择。

API Key

在 kukuai.fyi 控制台新建一把独立 Key

方便按项目停用、限额和排查用量。

模型 ID

先从一个稳定模型开始，例如 gpt-5-2-chat-latest 或 claude-haiku-4-5-20251001

先跑通连通性，再切换更强或更贵的模型。

Base URL

OpenAI 风格用 https://www.kukuai.fyi/api-proxy/china/v1

这是 ChatBox 最通用、最少配置的接法。

第一步：启动 ChatBox 并开始配置

首次启动 ChatBox，通常会看到配置向导；如果已经配置过，也可以从设置里重新进入。目标只有一个：先把 API Host 和模型 Provider 配好。

启动 ChatBox 应用。
如果是首次使用，进入新建对话或配置向导。
如果已经配置过，打开左下角设置。
找到 AI Provider / 模型提供商相关配置项。

第二步：配置 kukuai.fyi

2.1 选择模型提供商

对 kukuai.fyi 来说，最常见的方案是直接选择 OpenAI API。如果你的 ChatBox 版本也提供 Claude API 选项，并且你要用 Claude 系列模型，可以切到 Claude 风格。

2.2 填写 API 信息

推荐先按 OpenAI 风格配置：

openai-configtext

Provider: OpenAI API
API Key: sk-你的-kukuai-api-key
API Host / API Domain: https://www.kukuai.fyi/api-proxy/china/v1
Model: claude-haiku-4-5-20251001 或 gpt-5-2-chat-latest

如果你准备走 Claude 风格，再改成下面这样：

claude-configtext

如果你的 ChatBox 版本提供 Claude API 选项：

Provider: Claude API
API Key: sk-你的-kukuai-api-key
API Host / API Domain: https://www.kukuai.fyi/api-proxy/china
Model: claude-sonnet-4-6 或 claude-haiku-4-5-20251001

配置时最容易出错的就是“地址形态”和“模型名”。你可以直接对照下面的简表：

配置项

OpenAI 风格

Claude 风格

API Key

填写 kukuai.fyi 控制台生成的 Key

同样填写 kukuai.fyi 控制台生成的 Key

API Host / Domain

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

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

模型选择

gpt-5-2-chat-latest / gpt-4o-mini

claude-sonnet-4-6 / claude-haiku-4-5-20251001

2.3 选择模型

配置好 Host 之后，模型选择是第二个关键点。ChatBox 支持手动输入模型 ID，如果下拉列表没有刷新，直接复制模型 ID 往往更快。

场景

建议模型

说明

快速问答

gpt-4o-mini / claude-haiku-4-5-20251001

响应快，适合先验证连通性。

通用对话

gpt-5-2-chat-latest / claude-sonnet-4-6

更适合日常聊天、总结和写作。

长上下文任务

claude-sonnet-4-6

更适合长文分析和复杂推理。

第三步：开始使用

配置完成后，回到主界面发一条最小请求。先确认能正常返回，再调整温度、最大输出长度和模型。

smoke-test.shbash

export KUKUAI_API_KEY="sk-你的-kukuai-api-key"

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

返回主界面，新建一个对话。
输入一句简单的问题，比如“用一句话介绍 kukuai.fyi”。
检查回复是否正常返回。
如果成功，再逐步切换到更复杂的提示词。

调整模型参数（可选）

参数

作用

建议

Temperature

控制输出随机性

0.7 适合创意，0.3 适合精确回答

Max Tokens

限制单次输出长度

先从 2000-4000 试起

Top P

控制采样范围

默认 0.9 通常足够

高级功能

多会话管理：为不同任务建立独立聊天窗口，避免上下文串线。
保存和导出对话：把有价值的讨论导出为 Markdown 或 JSON。
提示词模板：把常用提示词存成模板，减少重复输入。
模型切换：根据任务在快速模型和高质量模型之间切换。

排障清单

troubleshootingtext

1. 连不上服务
   - 检查是否写成了 https://www.kukuai.fyi/api-proxy/china 而不是 https://www.kukuai.fyi/api-proxy/china/v1
   - 检查 API Key 是否完整
   - 先用 curl 验证，再回到 ChatBox

2. 模型列表为空
   - 手动输入模型 ID
   - 到 /v1/models 或模型导航复制真实模型名

3. 返回 401
   - Key 无效、过期或权限不足

4. 返回 404
   - 多半是 Base URL 或模型名写错

5. 返回很慢
   - 先换一个更轻的模型测试网络和配置

如果你已经按上面的步骤配置完，还是不通，优先去控制台和 cURL 里确认 Key、模型权限与 Base URL，而不是先怀疑 ChatBox 本身。

常见问题

Q1: 无法连接到 kukuai.fyi？

先确认 API Host 是否写成了 https://www.kukuai.fyi/api-proxy/china/v1。
确认 API Key 是否完整，且前缀和控制台一致。
先用 cURL 验证接口，再回到 ChatBox 排查客户端设置。

Q2: 模型列表里没有显示模型？

直接手动输入模型 ID。
去 GET /v1/models 或模型导航复制真实模型名。

Q3: 对话报错怎么办？

401: 检查 Key 是否有效。
404: 检查模型名或接口路径。
429: 降低并发或换低成本模型。

Q4: 怎么看用量和费用？

到 kukuai.fyi 控制台查看。
建议给 ChatBox 单独用一把 Key，方便统计和停用。

Q5: ChatBox 支持哪些平台？

通常支持 Windows、macOS 和 Linux。
不同版本的配置名称可能略有差异，但核心字段通常都是 API Key、API Host、Model。

使用技巧

先跑通最小请求，再调参数。
把常用模型固定成默认模型，减少每次手动输入。
长任务用更强模型，简单问答用更便宜更快的模型。
如果你主要做开发，建议先看完整接入手册。

下一步

如果你要先理解整个站点的接入心智，可以看 kukuai.fyi 通用接入教程。
如果你要把配置同步给别的工具，可以看配置文件导出。
如果你想继续看更细的 API 说明，可以看快速开始和 Chat Completions API。

在 ChatBox 中使用 kukuai.fyi ​

第一步：启动 ChatBox 并开始配置 ​

第二步：配置 kukuai.fyi ​

2.1 选择模型提供商 ​

2.2 填写 API 信息 ​

2.3 选择模型 ​

第三步：开始使用 ​

调整模型参数（可选） ​

高级功能 ​

排障清单 ​

常见问题 ​

使用技巧 ​

下一步 ​