在 Kilo Code 中配置 OpenAI 兼容 Provider从自定义端点连接到模型调优实战【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode导读Kilo Code 内置了 OpenAI、Anthropic、Google 等官方模型提供商的深度集成但真实项目中你往往需要接入自建推理服务Ollama、LM Studio、聚合网关或非官方云厂商Together AI、Perplexity、Anyscale 等——这些服务大多暴露的是 OpenAI Chat Completions 兼容 API。本文以 OpenAI-Compatible Provider 官方文档 为骨架结合仓库源码 provider-options.ts 与 Custom Models 指南完整讲解如何在 Kilo Code 的 VSCode 界面和 CLI 配置文件中接入任意 OpenAI 兼容端点并深入模型级参数token 限额、工具调用、变体、自动模型检测与常见故障排查。读完后你将能独立配置并调优一个自定义 OpenAI 兼容 Provider并在团队或企业中安全地复用这套配置。什么是 OpenAI 兼容 ProviderOpenAI 兼容 Provider 指任何实现了 OpenAI API 标准的服务端——即提供/v1/chat/completionsChat Completions或/v1/models等标准端点、请求与响应遵循 OpenAI 协议的服务。Kilo Code 支持这类端点意味着你可以接入本地模型通过 Ollama、LM Studio 等工具运行的开源模型这两个工具在 ollama.md 与 lmstudio.md 中有独立章节。接入云厂商Perplexity、Together AI、Anyscale 等。接入任何其他暴露 OpenAI 兼容端点的服务企业内网网关、自建代理、团队共享推理集群等。本文聚焦于官方 OpenAI API其有独立的 openai.md 配置页之外的兼容 Provider。重要警告Azure OpenAI GPT-5 部署不要使用通用兼容 ProviderAzure GPT-5 会拒绝通用 OpenAI 兼容 Provider 发送的max_tokens参数它期望的是max_completion_tokens需要 Azure 专属处理。请改用 Kilo Code 原生的azureProvider当你的 Azure 部署名与在 Kilo 中选择的模型名不一致时通过模型的id字段映射详见下文“用 id 字段映射模型名”一节。VSCode 图形界面配置创建自定义 Provider打开设置齿轮图标进入Providers选项卡。滚动到底部点击Custom provider按钮。在自定义 Provider 对话框中填写以下字段字段说明Provider ID唯一标识符如my-provider建议使用小写字母、数字、连字符或下划线它将作为provider_id/model_id格式中的provider_idDisplay name在 UI 中显示的可读名称Provider API选择OpenAI Compatible面向 OpenAI Chat Completions 兼容端点OpenAI 与 xAI 模型请用OpenAI ResponsesAnthropic 与 MiniMax 模型请用Anthropic MessagesBase URLProvider 的 API 端点如https://api.your-provider.com/v1。当 URL 有效且暴露 OpenAI 兼容的 models 端点时Kilo 会自动拉取可用模型列表API key你的 API 密钥。可选——若认证通过自定义请求头处理可留空Models手动添加模型或从自动拉取的列表中选择见下文“自动模型检测”Headers可选以键值对形式添加的自定义 HTTP 请求头点击Submit保存该 Provider 的模型即出现在模型选择器中。如需更精细的模型配置token 限额、工具调用、变体等可直接编辑kilo.jsonc配置文件——见下文 CLI 一节或参阅 Custom Models 指南。自动模型检测Automatic Model Detection配置自定义 OpenAI 兼容 Provider 时Kilo Code 会自动从你的 Provider 的/v1/models端点检测可用模型输入有效的Base URL和API Key后Kilo Code 会查询该端点并弹出可搜索的模型选择器列出所有可用模型。支持模糊搜索例如输入gpt4o能匹配到gpt-4o-mini。可逐个勾选模型加入 Provider 配置。之后可编辑已有的自定义 Provider增删模型。这一机制免去了手动查询和录入模型 ID 的繁琐。若自动检测失败例如 Provider 不支持/v1/models端点仍可手动输入模型 ID 兜底。CLI 配置文件接入在kilo.json配置文件中定义自定义 Provider配置文件位于~/.config/kilo/kilo.json或项目根目录./kilo.json。Provider 键如vllm是你自己选择的标识符可任意命名。必须定义至少一个模型建议设置name与limit上下文窗口与最大输出 token以便 Agent 正确管理上下文{ provider: { vllm: { npm: ai-sdk/openai-compatible, models: { qwen35: { name: Qwen 3.5, limit: { context: 262144, output: 16384, }, }, }, options: { apiKey: none, baseURL: http://my.url:8000/v1, }, }, }, }随后用provider-id/model-id格式设置默认模型{ model: vllm/qwen35, }配置字段详解npm— API 协议包。面向 OpenAI Chat Completions 兼容端点使用ai-sdk/openai-compatible省略时的默认值ai-sdk/openai对应 OpenAI Responses 端点ai-sdk/anthropic对应 Anthropic Messages 端点。models— 模型 ID 到模型定义的映射。每个模型应包含name与包含context、outputtoken 数的limit。若limit.context或limit.output省略默认值为0会限制上下文管理能力详见下文“token 限额”。options.baseURL— Provider API 端点的基础 URL。Azure OpenAI GPT-5 应改用provider.azure。options.apiKey— API 密钥。若 Provider 不需要认证可填任意非空字符串如none。通过环境变量注入 API Key除了将密钥写入配置文件也可以用env字段指定要读取的环境变量{ provider: { my-provider: { env: [MY_PROVIDER_API_KEY], models: { my-model: { name: My Model, limit: { context: 128000, output: 4096 }, }, }, options: { baseURL: https://api.my-provider.com/v1, }, }, }, }这样密钥只存在于环境变量中便于 CI 与多机部署场景复用同一份配置文件。此外在受信任配置中apiKey还支持{env:VAR}与{file:...}引用语法例如apiKey: {env:MY_PROVIDER_API_KEY}但注意该语法只在受信任配置位置生效全局配置~/.config/kilo、通过KILO_CONFIG/KILO_CONFIG_CONTENT传入的配置、组织/MDM 托管配置。提交到仓库的项目级kilo.json无法解析{env:VAR}——引用会被忽略并记录警告这是为了防止恶意仓库通过打开即窃取你的密钥。{file:...}在项目配置中仍然可用但只能引用项目根目录内的文件越界绝对路径、../遍历与符号链接逃逸都会被拒绝。完整端点 URL 支持Full Endpoint URLKilo Code 支持在 Base URL 字段填写完整的端点 URL提供更大的配置灵活性标准 Base URL 格式https://api.provider.com/v1完整端点 URL 格式https://api.provider.com/v1/chat/completions https://custom-endpoint.provider.com/api/v2/models/chat该增强能力允许你连接端点结构非标准的 Provider使用自定义 API 网关或代理服务对接要求特定端点路径的 Provider集成企业或自托管 API 部署。注意使用完整端点 URL 时请确保 URL 指向你所用 Provider 正确的 chat completions 端点。源码视角OpenAI 兼容 Provider 的请求是如何构建的理解了配置字段后不妨看一下底层实现这能帮你定位排查方向。在 packages/core/src/v1/config/provider-options.ts 中Kilo Code 为不同npm包定义了各自的请求“降级器”Lowerer。ai-sdk/openai-compatible对应openaiCompatible实现第 128–140 行const openaiCompatible: Lowerer { provider(options) { return { ...direct(options, [baseURL]), url: string(options.baseURL) } }, request(options) { const result clone(options) if (options.reasoningEffort ! undefined) { result.reasoning_effort options.reasoningEffort delete result.reasoningEffort } return result }, }从中可以确认两点实现事实baseURL被提取为请求 URL其余选项含自定义headers原样透传若配置了reasoningEffort会被转换为 OpenAI 协议中的reasoning_effort请求字段——这就是在兼容端点上开启“思考强度”控制的通道。同一文件中多个官方 SDK 包ai-sdk/cerebras、ai-sdk/deepinfra、ai-sdk/groq、ai-sdk/mistral、ai-sdk/togetherai、ai-sdk/xai、openrouter/ai-sdk-provider等共享同一个openaiCompatible实现第 151–159 行说明这些服务本质上都走 OpenAI Chat Completions 协议——这也解释了为什么自定义 Provider 能与它们使用相同的配置形态。此外packages/core/src/plugin/provider/openai-compatible.ts 中的插件会在检测到ai-sdk/openai-compatible包时默认开启includeUsage并动态加载createOpenAICompatible工厂构造 SDK 实例保证请求/响应的用量统计可用。模型级参数调优Token 限额、工具调用与变体在 CLI 配置中provider.provider_id.models.model_id下的模型字段其 Schema 定义见 packages/core/src/v1/config/provider.ts支持以下可选配置字段类型说明namestring模型选择器中显示的名称idstring实际发送给 Provider 的 API 模型 ID默认取配置键tool_callboolean模型是否支持工具/函数调用Kilo 的文件编辑、终端等工具依赖此开关reasoningboolean模型是否支持扩展思考extended thinkingtemperatureboolean模型是否支持 temperature 参数attachmentboolean模型是否支持文件附件modalitiesobject支持的输入/输出内容类型{ input, output }数组元素可取text、image、audio、video、pdflimitobjecttoken 限额{ context, output, input? }costobject每百万 token 定价{ input, output, cache_read?, cache_write? }optionsobject任意 Provider 特定的模型选项headersobject请求中附加的自定义 HTTP 头providerobject覆盖{ npm?, api? }—— 该模型的 AI SDK 包或基础 API URLvariantsobject具名变体配置如不同的思考强度当模型 ID 与内置目录Kilo 内置了 models.dev 的快照并每小时刷新中的条目匹配时你的配置值会合并覆盖在默认值之上只需写明想覆盖的字段即可。token 限额limit与上下文管理limit对象控制 Kilo 如何管理模型的上下文窗口与输出长度单位为token子字段类型必填说明contextnumber否模型总上下文窗口大小如 128K 模型填131072用于判断何时应压缩对话历史outputnumber否单次响应最大生成 token 数会以max_tokens或等价参数发给 Provider默认上限 32,000inputnumber否可选的更严格输入限额部分 Provider 有低于完整上下文窗口的输入 token 上限设置后按此值而非context触发压缩limit: { context: 131072, output: 16384 }Kilo 按以下顺序解析限额你的配置→内置目录模型 ID 匹配时使用目录默认值→回退为 0。当context与output均为0自定义/本地模型未设置限额且不在目录中时会产生实质性副作用上下文压缩被禁用context: 0时溢出检测被跳过对话将无限增长直到 Provider 拒绝请求输出回退为 32,000 tokenoutput: 0时使用内部默认值 32,000可通过KILO_EXPERIMENTAL_OUTPUT_TOKEN_MAX环境变量调整无上下文用量追踪依赖上下文大小的用量指标被跳过。对于自定义与本地模型务必设置与实际能力相符的limit.context与limit.output否则自动上下文管理将被关闭。变体variants与推理控制示例可以在模型下定义具名变体以切换请求参数。例如 MiniMax 的 OpenAI 兼容 Chat Completions API 支持可选的布尔字段reasoning_split可把它设到变体上控制思考内容的返回格式variants: { thinking: { reasoning_split: true, }, }true时 MiniMax 将思考内容单独放在reasoning_content与reasoning_details中返回——该设置只改变响应格式不改变模型是否思考。不支持的 Provider包括使用 Anthropic Messages API 的 MiniMax请勿设置。用 id 字段映射模型名当配置中的模型键与 Provider 期望的名称不一致时使用id字段。例如 LM Studio 本地模型{ model: lmstudio/my-local-llama, provider: { lmstudio: { models: { my-local-llama: { id: meta-llama-3.1-8b-instruct, name: Llama 3.1 8B (Local), }, }, }, }, }此处my-local-llama是你在配置与模型选择器中使用的键meta-llama-3.1-8b-instruct才是实际发给 LM Studio API 的模型标识。同样的手法用于 Azure用原生azureProvider当部署名与模型键不同时把部署名填进id。切勿将 Azure GPT-5 系列部署配置在openai-compatible下因为该 Provider 发送max_tokens而 Azure GPT-5 期望max_completion_tokens{ model: azure/gpt-5.5, provider: { azure: { options: { apiKey: {env:AZURE_API_KEY}, resourceName: my-azure-resource, }, models: { gpt-5.5: { id: my-gpt-5-5-deployment, name: GPT-5.5 on Azure, reasoning: true, tool_call: true, temperature: false, limit: { context: 400000, output: 128000, }, }, }, }, }, }若想配置完整 Azure 端点而非资源名可将resourceName替换为baseURL如baseURL: https://my-resource.openai.azure.com/openai两者同时配置时 Kilo Code 使用baseURL并忽略resourceName以避免发送冲突的 Azure SDK 选项。Provider 级选项超时控制Provider 级options中值得特别关注的是超时相关配置定义于 provider.ts 的Info.optionsSchema选项类型说明timeoutnumber \| false完整请求超时毫秒覆盖等待响应头与响应体首字节的时间。默认3000005 分钟设false禁用。数据开始到达后超时不再生效因此慢速流式响应不会被切断——响应中途的停滞请用chunkTimeoutheaderTimeoutnumber \| false等待响应头的超时时间毫秒Provider 集成可能设置默认值设false禁用chunkTimeoutnumber流式 SSE 块之间的超时毫秒。窗口内无新块到达则中止请求并重试用于捕获 TCP 连接存活但 SSE 流停止的静默掉线。对流式不稳定的 Provider建议15000–3000015–30 秒{ provider: { openai: { options: { apiKey: {env:OPENAI_API_KEY}, baseURL: https://my-proxy.example.com/v1, timeout: 300000, }, }, }, }常见故障排查Invalid API Key再次核对 API 密钥是否输入正确若认证走自定义请求头确认 Headers 键值对无误。Model Not Found确认使用了所选 Provider 的有效模型 ID必要时在模型定义中通过id字段映射真实模型标识。连接错误核实 Base URL 是否正确、Provider 的 API 是否可达本地模型请确认推理服务已启动且监听在配置的地址上。Azure GPT-5 拒绝max_tokensAzure GPT-5 部署必须使用 Kilo Code 原生azureProvider。通用 OpenAI 兼容自定义 Provider 会发送max_tokens而 Azure GPT-5 期望max_completion_tokens因而拒绝请求。模型不出现在模型选择器中确认 Provider 凭据有效API key 或本地服务运行中、模型键与model: provider/model-key一致可运行kilo models列出全部可用模型以确认 Provider 处于激活状态。模型行为异常或对话无限增长检查tool_call: true是否已为需要工具的模型开启确认limit.context与limit.output已设置若对话不压缩多半是limit.context为0即未设置。结果不符合预期尝试切换不同的模型进行对比。结语借助 OpenAI 兼容协议这一事实标准Kilo Code 能以统一的配置形态接入本地推理、云厂商与自建网关。从 VSCode 界面几步即可完成接入并享受自动模型检测需要精细控制时kilo.json中的npm/options/models/variants组合提供了从 token 限额到变体参数的完整调优空间。配置完成后请始终以你所接入 Provider 的官方文档为准核对端点路径、模型 ID 与认证方式的最新变化。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考