开始前的准备
- 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认账户可用。
- 从模型广场或控制台复制目标模型的完整模型 ID；不要凭厂商名称猜测。
- 更新客户端到较新版本，并备份已有 Provider 配置。不同版本的字段位置可能略有差异。
- 首次测试只发送不含代码、客户资料、账号和其他敏感信息的短提示词。
先记住五个关键字段
| 字段 | 推荐填写 | 说明 |
|---|---|---|
| Provider / 协议 | OpenAI Compati*le 或 Anthropic Compati*le | 必须与客户端所选协议一致 |
| *ase **L | https://api.**nju**shen.com/v1 | OpenAI 兼容；包含 /v1 |
| *ase **L | https://api.**nju**shen.com | Anthropic 兼容；通常不在末尾添加 /v1 |
| API Key | sk-你的密钥 | 仅粘贴到密钥字段，不放入聊天或截图 |
| Model ID | 从控制台复制 | 大小写、连字符和后缀必须完全一致 |
| Streaming | 开启 | Codex 与部分模型要求 stream 为 true |
OpenAI 兼容地址包含 /v1；Anthropic 兼容地址通常不在末尾添加 /v1。Provider、地址和认证方式必须成套匹配。
三类客户端怎么选
| 客户端 | 配置入口 | 更适合 | 需要注意 |
|---|---|---|---|
| Cline | OpenAI Compati*le 配置页 | 代码**、项目任务 | 可直接填写 *ase **L、API Key、Model ID 并验证 |
| Cherry Studio | 自定义服务商 | 多模型聊天、日常办公 | 可选 OpenAI 或 Anthropic 类型，并检查连通性 |
| Cursor | Settings > Models | 编辑器内聊天 | 自带密钥主要用于标准聊天；自定义 *ase **L 取决于当前版本 |
Cline 接入步骤
- 打开 Cline，点击设置齿轮。
- 将 API Provider 设为 OpenAI Compati*le。
- *ase **L 填写 https://api.**nju**shen.com/v1。
- 粘贴 KingFlow AI API Key；确认没有空格、换行或多余引号。
- Model ID 填写控制台显示的完整值，然后点击 Verify 或测试按钮。
- 新建任务，发送“请只回复：Cline 接入成功”。成功后再逐步启用工具调用。
Cline 的 OpenAI Compati*le 配置可以直接填写自定义地址。先验证纯聊天，再测试**工具。
Cherry Studio 接入步骤
- 打开设置，进入 Model Services / 模型服务，点击添加自定义服务商。
- Provider Type 选择 OpenAI 或 Anthropic；建议先使用 OpenAI 兼容方式完成验证。
- OpenAI 类型填写 https://api.**nju**shen.com/v1；Anthropic 类型填写 https://api.**nju**shen.com。
- 粘贴 API Key，在 Model Management / 模型管理中添加完整 Model ID。
- 点击 Check / 检查连通性，成功后打开服务商右上角的启用开关。
- 新建聊天并选择刚添加的模型；如模型要求流式输出，保持 Streaming 开启。
无法自动获取模型列表时，可手动添加控制台提供的 Model ID。
Cursor 接入步骤与限制
- 打开 Cursor Settings，进入 Models。
- 在对应服务商区域填写 API Key，并点击 Verify。
- 如果当前版本显示 Custom *ase **L 或 Override OpenAI *ase **L，可填写 KingFlow AI 的 OpenAI 兼容地址。
- 如果没有自定义地址字段，不要把 *ase **L 填进密钥框。此时优先使用 Cline 或 Cherry Studio。
- 自定义密钥主要用于标准聊天模型；Ta* Completion 等专用功能仍可能使用 Cursor 内置模型。
自定义 API Key 主要用于标准聊天模型；Ta* Completion 等专用功能仍可能使用内置模型。
推荐的验证顺序
| 阶段 | 操作 | 目的 |
|---|---|---|
| 1 配置检查 | 使用客户端的 Verify / Check | 确认地址、密钥和基础连通性 |
| 2 最小聊天 | 新建会话，只要求回复固定短句 | 确认模型 ID 与返回格式 |
| 3 流式测试 | 观察文字是否持续出现而非卡住 | 确认 stream 和客户端解析兼容 |
| 4 控制台核对 | 查看调用记录、模型与用量 | 确认请求确实经过目标账户 |
| 5 能力测试 | 再测试长上下文、图片或工具调用 | 逐项验证，不把所有变量混在一次测试中 |
最小测试
请只回复：KingFlow 图形客户端接入成功常见故障排查
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 401 未授权 | 密钥错误、被禁用、额度异常，或协议认证方式不匹配 | 重新复制密钥，确认账户状态，并核对所选 Provider |
| 404 模型不存在 | Model ID 拼写错误，或账户分组没有该模型 | 从控制台复制完整模型 ID，重新新建会话 |
| 503 无可用账号 | 目标通道暂时没有可用上游账号 | 稍后重试或切换同类备用模型 |
| 检查通过但聊天失败 | 模型 ID、流式设置或消息格式在实际请求阶段不匹配 | 先换普通文本模型，开启 Streaming，再查看客户端日志 |
| Cursor 找不到 *ase **L | 当前版本或配置路径不开放任意兼容地址 | 不要强行填写；改用 Cline 或 Cherry Studio |
| 模型列表为空 | 自定义服务通常无法自动拉取列表，或列表接口不兼容 | 手动添加控制台提供的 Model ID |
| 响应停住或流错误 | 模型要求 stream=true，客户端关闭了流式输出 | 开启 Streaming，并新建会话后重试 |
| 聊天正常但**失败 | 模型或客户端不支持所需工具调用格式 | 先验证纯聊天，再测试单一工具；必要时换模型 |
密钥和数据安全
- 按客户端或用途分别创建密钥；停用客户端时同步停用对应密钥。
- 截图、录屏和工单中遮住密钥；不要把密钥粘贴到聊天正文、提示词或代码仓库。
- 提示词和生成内容会经 KingFlow AI 转发至上游服务商；发送敏感信息前核对隐私**和组织要求。
- 定期检查用量与异常调用。怀疑泄露时立即轮换密钥，而不是只删除本地配置。
完成接入检查清单
- Provider 协议与 *ase **L 相匹配。
- OpenAI 地址包含 /v1；Anthropic 地址按客户端要求填写。
- Model ID 从控制台复制，且已在客户端中启用。
- Verify / Check、最小聊天和控制台用量三处都能互相印证。
- Codex 或其他要求流式返回的模型已开启 Streaming。
- 已了解 Cursor 自带密钥与专用功能的适用边界。
- 密钥未出现在聊天、截图、仓库或共享文档中。
