文档
进入控制台
文档目录
本页目录

集成

桌面与 Web 客户端

下文给出 Cherry Studio、Open WebUI、CC Switch 和 Claude Code 的地址与协议配置；Claude Code 也可按需通过 ccNexus 转换协议。Gemini CLI 暂未上线。

地址与协议速查

客户端填写地址协议或类型
Cherry Studiohttps://api.khaix.netOpenAI Responses
Open WebUIhttps://api.khaix.net/v1OpenAI · 默认 Chat Completions
CC Switch · Claude Codehttps://api.khaix.netAnthropic Messages
CC Switch · Codexhttps://api.khaix.net/v1OpenAI Responses
Claude Code 直连https://api.khaix.netAnthropic Messages
Claude Code 经 ccNexushttp://127.0.0.1:3000本地 Messages 转换；上游使用 Responses
Gemini CLI暂未上线依赖 Gemini 原生协议，当前不可配置

各客户端拼接请求路径的方式不同，地址请直接按表填写。有的需要站点根地址，有的需要带 /v1，不能套用同一个格式。

Cherry Studio

建议先从 Cherry Studio 官网更新到当前版本，再按 OpenAI Responses 配置 KHaiXAPI。

  1. 打开“模型服务”，选择“添加自定义提供商”。
  2. 名称填写 KHaiXAPI，API 地址填写 https://api.khaix.net。
  3. 填写分配给这个客户端的 API Key。
  4. 手工添加文字模型 gpt-5.6-sol。
  5. 打开该提供商的“更多端点”，启用 OpenAI Responses。
  6. 执行连接检测，保存后发送一条文字消息。

Open WebUI

通过 Open WebUI 的 OpenAI Compatible 连接添加 KHaiXAPI。

  1. 以管理员身份进入 Admin Settings → Connections → OpenAI。
  2. 添加连接，URL 填写 https://api.khaix.net/v1，并填写 API Key。
  3. 首次接入使用默认的 Chat Completions；图片调用请单独使用图片 API，不要在聊天模型中填写 gpt-image-2。
  4. 保存后检查模型列表；未自动出现时，在 Model IDs (Filter) 中填写 gpt-5.6-sol。
  5. 新建对话，发送一条文字消息，并在控制台核对调用记录。

如果当前版本提供 Responses API Type，可在 Chat Completions 接通后另行测试。会话、流式或工具调用出现异常时，切回 Chat Completions 对比即可判断是否与协议有关。

CC Switch

CC Switch 可以集中管理 Claude Code 与 Codex 等应用的供应商配置。请从官方 Releases 安装当前稳定版本，并参考官方添加供应商说明完成下列设置。

  1. 打开 CC Switch，在顶部应用切换器中先选择要配置的应用，再点击右上角“+”。只配置当前应用时选择“应用专属供应商”；需要复用配置时再选择“统一供应商”。
  2. 供应商名称填写 KHaiXAPI，选择自定义供应商，并为当前应用使用单独创建的 API Key。
  3. 配置 Claude Code 时，API 地址填写 https://api.khaix.net，API 格式选择 Anthropic Messages，主模型填写 claude-sonnet-5。需要角色映射时，可从控制台已支持的模型中选择 claude-opus-4-8 与 claude-fable-5。
  4. 配置 Codex 时，API 地址填写 https://api.khaix.net/v1，API 格式选择 OpenAI Responses，模型填写 gpt-5.6-sol。
  5. 使用 Fetch Models 拉取模型列表；若当前应用或供应商类型不支持自动拉取，就按上面的模型 ID 手工填写。保存后启用 KHaiXAPI 供应商。
  6. 先运行 Stream Check，成功后再从 CC Switch 启动目标应用。发送一条短消息，并在 KHaiXAPI 控制台核对协议、模型和状态。

Claude Code

KHaiXAPI 原生提供 POST /v1/messages，Claude Code 可以直接连接。分组不支持 Messages 调度、客户端版本较旧或需要本地模型映射时，再使用 ccNexus。

原生 Messages 直连

先在当前终端设置临时变量并启动 Claude Code。连接确认无误后，再通过操作系统或终端的 Secret 机制持久化。

macOS / Linux
export ANTHROPIC_BASE_URL="https://api.khaix.net"
export ANTHROPIC_AUTH_TOKEN="$KHAIX_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude
PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.khaix.net"
$env:ANTHROPIC_AUTH_TOKEN = $env:KHAIX_API_KEY
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
claude
  1. 启动后运行 /status，确认 Base URL、认证状态和模型。
  2. 先发送一个文字任务，再执行一次只读工具调用。
  3. 在 KHaiXAPI 控制台确认请求进入 Messages 协议且模型正确。

ccNexus 备选方案

ccNexus 是第三方本地协议转换器，只在直连不可用或需要本地模型映射时使用。安装前请核对版本和下载来源。

  1. 在 ccNexus 添加上游：API 地址填写 https://api.khaix.net，转换器选择 OpenAI Responses。
  2. 在 ccNexus 中填写 KHaiXAPI 密钥和文字模型 gpt-5.6-sol，保存并执行端点检测。
  3. 启动本地服务并确认仅监听本机地址；下面以默认端口 3000 为例。
  4. 将 Claude Code 的 ANTHROPIC_BASE_URL 改为 http://127.0.0.1:3000。
  5. Claude Code 的认证令牌填写本地代理接受的占位值。真实 KHaiXAPI 密钥只保存在 ccNexus 上游配置中。
macOS / Linux · ccNexus
export ANTHROPIC_BASE_URL="http://127.0.0.1:3000"
export ANTHROPIC_AUTH_TOKEN="ccnexus-local"
export ANTHROPIC_MODEL="gpt-5.6-sol"
claude

ccNexus 的监听端口或本地认证值有改动时，请同步替换示例中的值。Claude Code 侧只使用本地代理的认证值。

Gemini CLI

目前没有可用的 Base URL、环境变量或测试命令。上线状态以控制台为准。

验证与安全

  1. 密钥：每个客户端单独创建，便于限制、审计和撤销。
  2. 文字：发送“请回复：连接成功”，核对返回内容和控制台记录。
  3. 地址：遇到 404 时检查 /v1/v1、错误 endpoint 和客户端自动补路径。
  4. 流式与工具：文字接通后逐项开启，协议问题和密钥问题更容易区分。
  5. 日志：截图和支持记录中的密钥只保留少量字符。
  6. 自动执行：Claude Code 等 Agent 客户端在不可信目录中应保留权限确认。