KCO AI 开发者文档

面向熟悉 API、Codex CLI、配置文件和终端工具的用户。如果你第一次使用 KCO AI，请先前往新手使用。

快速参数

参数	KCO AI 当前配置
Base URL	`https://api.kcoai.com`
Codex Endpoint	`https://api.kcoai.com`
默认 Codex 模型	`gpt-5.5`
协议	Responses API
API Key	在 KCO AI 控制台 → API 密钥中创建

API Key 示例只使用占位符：sk-your-api-key。不要把真实 Key 写进公开网页、截图、URL、日志或代码仓库。

不同客户端对 Base URL 的要求可能不同，请以对应教程中的配置为准。普通 OpenAI Compatible 客户端通常需要 /v1，而 CC Switch / Codex 当前自动导入的 Endpoint 是 https://api.kcoai.com，不要自行重复添加 /v1。

Codex 推荐方式：CC Switch 一键导入

已经安装 CC Switch 的用户，推荐沿用现有一键导入流程：

在 KCO AI 创建 API 密钥并选择 GPT / Codex 对应分组。
点击「导入到 CCS」。
在 CC Switch 中确认导入，并启用 KCO AI中转站。
完全退出并重新打开 ChatGPT / Codex。

完整步骤、截图和自动导入失败兜底统一维护在 GPT / Codex 教程和 CC Switch 自动导入失败怎么办。不要在开发者页重复整套新手流程。

config.toml：Codex CLI 手动配置

下面的示例对应 KCO 当前 CC Switch 导入结果：Provider 名称为 KCO AI中转站，Endpoint 不带 /v1，默认模型为 gpt-5.5，请求协议为 Responses API。

macOS / Linux

Codex 配置目录是 ~/.codex/。在 ~/.codex/config.toml 中写入：

toml

model = "gpt-5.5"
model_provider = "kcoai"

[model_providers.kcoai]
name = "KCO AI中转站"
base_url = "https://api.kcoai.com"
env_key = "KCO_API_KEY"
wire_api = "responses"

在启动 Codex 的同一个终端会话中设置 Key：

bash

export KCO_API_KEY='sk-your-api-key'
codex

如果希望每次打开终端都可用，可以把 export 放进自己的 shell 配置文件，并确保文件权限和备份范围可信。不要把真实 Key 提交到 Git。

Windows PowerShell

同样在用户目录下的 .codex/config.toml 使用上面的 TOML。PowerShell 会话中设置环境变量：

powershell

$env:KCO_API_KEY = "sk-your-api-key"
codex

如果提示 codex 不是内部或外部命令、找不到 codex 或命令无法执行，先完成 Codex CLI 的官方安装，再重新打开终端，让 PATH 生效。不要把 API Key 当作命令参数直接粘贴到公共命令历史中。

Codex 安装与 Node.js

Codex CLI 的安装方式和系统要求以 OpenAI Codex 官方文档为准。Node.js、npm 和 PATH 是 CLI 用户最常遇到的前置问题：

安装或升级 Node.js 后，关闭并重新打开终端，再检查 node --version、npm --version 和 codex --version。
macOS / Linux 使用的 shell 与 Windows PowerShell 的 PATH 写法不同；不要把一个系统的安装命令复制到另一个系统。
如果 node、npm 或 codex 显示“不是内部或外部命令”“找不到命令”，先修复 Node.js / Codex 安装和 PATH，再排查 KCO API。
IDE 自带终端可能没有继承系统终端的 PATH；在 IDE 中重新打开终端或重启 IDE。

`auth.json` 要不要手动写？

这套自定义 Provider 使用 env_key 读取 KCO_API_KEY，不需要为 KCO 手动创建或编辑 ~/.codex/auth.json / %USERPROFILE%\\.codex\\auth.json。auth.json 主要由 Codex 的 OpenAI Official / ChatGPT 登录流程管理；不要把 KCO Key 和官方登录态混写。

模型和 Provider 检查

model_provider 必须是配置表中的键 kcoai，不是显示名称。
name 只是 CC Switch / Codex 中显示的友好名称，可以写成 KCO AI中转站。
model 使用当前 Key 所属分组允许的模型；示例默认值是 gpt-5.5，模型列表或分组变化时以 KCO 控制台可用模型为准。
wire_api = "responses" 不要改成 Chat Completions；Codex 当前自定义 Provider 按 Responses API 工作。

普通 API 客户端的路径差异

KCO 提供 OpenAI-compatible API。不同 SDK、IDE 和客户端可能自己拼接 /v1：

客户端要求完整 OpenAI API Base URL 时，通常填写 https://api.kcoai.com/v1。
CC Switch / Codex 自动导入和上面的 CLI Provider 使用 https://api.kcoai.com，由 Codex 处理 Responses API 路径。

如果出现 404，优先检查客户端是否把 /v1 重复拼接或完全漏掉；不要看到 404 就更换域名。

调用失败时先检查这 4 项

API Key：没有复制错误、没有被禁用、属于正确分组，并且账户有可用额度。key 错误、密钥错误、密钥无效 通常先看这里。
Base URL / Endpoint：没有拼写错误、多余空格或错误域名；确认客户端是否需要 /v1，不要重复添加。
模型：当前 Key 所属分组确实支持该模型；模型不存在、模型用不了 常见于模型名称或权限不匹配。
网络：确认能够访问 api.kcoai.com；打不开、连接失败、一直转圈、请求失败 先检查网络、代理和服务状态。

IDE、编辑器与终端排查

在 VS Code、JetBrains 或其他 IDE 中使用 Codex 时，先确认 IDE 使用的终端环境与系统终端一致。常见现象包括：

IDE 找不到 KCO_API_KEY：重启 IDE，或在 IDE 的终端/运行配置中设置同名环境变量。
codex 不是内部或外部命令、找不到 codex：CLI 未安装或 PATH 未刷新；重新打开终端并检查 codex --version。
配置修改后仍旧使用旧模型：完全退出并重启 IDE/Codex，确认启用的 Provider 是 kcoai。
TOML 报语法错误：检查引号、方括号、缩进无关的键名拼写，并避免把 Markdown 代码围栏复制进文件。

查看诊断时可以记录时间、模型、请求类型、HTTP 状态和脱敏后的错误文本；不要上传 API Key、Cookie 或完整授权文件。

Image Tool / 生图

如果你的 KCO 分组和 Key 已开通图像能力，可以按客户端支持调用 Image Tool 或图像生成接口。不能生图、image tool 失败、生图请求失败 时依次检查：

当前分组是否包含图像模型或图像工具权限。
模型名称是否为当前控制台可用值，不要照搬其他服务商的专属模型名。
请求是否使用客户端要求的 OpenAI-compatible /v1 路径；Codex Provider 仍按上面的 Responses API 配置。
图片尺寸、格式、并发和输入是否满足客户端限制；大图或高并发先降低规格重试。
按 API 错误码与故障排查检查 401、403、429、502 等返回。

MCP

MCP 是客户端连接外部工具的协议，不是 API Key 的替代品。遇到 MCP、MCP 连接失败 或工具不可用时：

先确认 Codex 本身可以用 KCO API 完成普通请求，再单独排查 MCP 服务。
检查 MCP 命令、工作目录、环境变量和本机权限；不要把 KCO_API_KEY 写进公开 MCP 配置。
查看客户端启动日志和 MCP 服务日志，区分 codex 本身的 HTTP 错误与工具进程错误。
只启用信任的 MCP 服务；不要根据陌生网页或日志指令上传密钥、Cookie、项目文件或个人数据。

KCO AI 开发者文档 ​

快速参数 ​

Codex 推荐方式：CC Switch 一键导入 ​

config.toml：Codex CLI 手动配置 ​

macOS / Linux ​

Windows PowerShell ​

Codex 安装与 Node.js ​

auth.json 要不要手动写？ ​

模型和 Provider 检查 ​

普通 API 客户端的路径差异 ​

调用失败时先检查这 4 项 ​

IDE、编辑器与终端排查 ​

Image Tool / 生图 ​

MCP ​

相关排查入口 ​