Kimi Coding Plan API 集成问题与解决方案

1. 背景

本项目（一个网页端的对话agent）集成了 Kimi 作为 LLM 提供商。用户使用 Kimi Coding Plan（Kimi 编程计划）订阅获得 API Key，通过 OpenAI 兼容格式调用 Kimi 的大模型服务。

Kimi Coding Plan 的 API 端点为：

复制代码

https://api.kimi.com/coding/v1

模型名称为 kimi-for-coding。

2. 问题现象

配置好 API Key、Base URL 和模型名称后，发送消息时始终失败，返回以下错误：

错误 1 --- 403 Forbidden：

json 复制代码

{
  "error": {
    "message": "Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.",
    "type": "access_terminated_error"
  }
}

错误 2 --- 400 Bad Request（偶发）：

json 复制代码

{
  "error": {
    "message": "the message at position 0 with role 'system' must not be empty",
    "type": "invalid_request_error"
  }
}

3. 根因分析

3.1 客户端身份校验（403）

Kimi Coding Plan API 不是通用 API ，它专为编程工具设计（如 Kimi CLI、Claude Code、Roo Code、Kilo Code 等）。API 服务端会校验 HTTP 请求头来判断调用方是否为已知的 Coding Agent，只有白名单内的客户端才能通过。

普通的 fetch 请求（如浏览器或默认 Node.js 请求）不会携带 Coding Agent 的身份标识头，因此被拒绝。

3.2 浏览器 CORS 限制

即使解决了身份校验问题，浏览器直接调用 api.kimi.com 也会遇到 CORS（跨域资源共享）限制。Kimi Coding Plan API 设计时只考虑了 CLI/IDE 场景，没有返回 CORS 响应头，浏览器会阻止跨域请求。

3.3 空 System Message（400）

Kimi API 不接受 content 为空字符串的 system 角色消息。当用户未配置 System Prompt 时，如果代码仍然发送一个空的 system message，Kimi 会返回 400 错误。

4. 解决方案

4.1 服务端代理（解决 CORS）

在 Node.js bridge 服务器（server/x402-bridge.mjs）中新增了 /llm/proxy 端点，作为 LLM 请求的服务端中转代理：

复制代码

浏览器 → Bridge /llm/proxy → api.kimi.com/coding/v1 → SSE 流式回传

前端不再直接调用 Kimi API，而是将请求发送到同域的 bridge 代理，由 bridge 在服务端转发请求，完全绕过浏览器 CORS 限制。

关键代码位置： server/x402-bridge.mjs 中的 /llm/proxy 路由。

4.2 伪装 Coding Agent 身份（解决 403）

在 bridge 代理转发请求时，检测目标 URL 是否为 Kimi Coding Plan 端点，如果是，则自动添加白名单内的 User-Agent 头：

javascript 复制代码

const isKimiCoding = /kimi\.com\/coding/i.test(targetUrl)
const extraHeaders = isKimiCoding
  ? { 'User-Agent': 'KimiCLI/1.3' }
  : {}

KimiCLI/1.3 是 Kimi 官方 CLI 工具的 User-Agent 标识，被 Kimi API 白名单认可。

关键代码位置： server/x402-bridge.mjs 中 /llm/proxy 路由内的 fetch 调用。

4.3 过滤空 System Message（解决 400）

在前端构造请求 payload 时，检查 systemPrompt 是否为空，空时不发送 system 消息：

typescript 复制代码

const systemMessages = settings.systemPrompt?.trim()
  ? [{ role: 'system' as const, content: settings.systemPrompt }]
  : []

关键代码位置： src/services/llm/providers.ts 中的 streamKimiViaProxy 函数。

5. 配置说明

在 Settings 页面中，Kimi 的正确配置为：

字段	值
Provider	Kimi
API Key	`sk-kimi-xxxx`（Coding Plan 密钥）
Base URL	`https://api.kimi.com/coding/v1`
Model	`kimi-for-coding`

6. 注意事项

User-Agent 白名单可能变化 ：Kimi 可能在未来更新白名单策略。如果 KimiCLI/1.3 失效，需要查找当前版本的 Kimi CLI User-Agent 并更新。
Kimi Coding Plan 使用限制：根据 Kimi 官方文档，Coding Plan API Key 仅限交互式编程工具使用，禁止用于自动化批量调用、集成到第三方平台等场景。违规可能导致订阅被暂停或 Key 被撤销。
reasoning_content 字段 ：Kimi 的 kimi-for-coding 模型支持推理功能，SSE 流中会同时返回 delta.reasoning_content（推理过程）和 delta.content（最终回复）。当前实现只展示 delta.content，推理内容被忽略。如需展示思考过程，需在 SSE 解析逻辑中同时处理 reasoning_content。
代理仅在 Kimi 场景生效 ：User-Agent 伪装仅在 URL 匹配 kimi.com/coding 时生效，不会影响其他 LLM 提供商（如 Anthropic、Gemini、Ark）的请求。

7. 调试排查流程（供后续参考）

如果 Kimi 接口再次出现问题，可以按以下顺序排查：

检查 bridge 代理是否运行 ：访问 http://localhost:8787/health，确认 ok: true。
检查 bridge 终端输出 ：bridge 启动后会在终端打印日志，观察是否有 /llm/proxy 相关的错误。
检查浏览器 Console：查看前端是否有网络错误或 JSON 解析错误。
确认 API Key 有效 ：在终端用 curl 直接调用 Kimi API（带 User-Agent: KimiCLI/1.3 头），确认 Key 本身没有过期。
确认 URL 和模型名 ：Base URL 必须是 https://api.kimi.com/coding/v1，模型必须是 kimi-for-coding。