From 0e614dd4524c6d3f6c01603760d7c207425d40bc Mon Sep 17 00:00:00 2001 From: chrarnoldus <12196001+chrarnoldus@users.noreply.github.com> Date: Thu, 18 Jun 2026 12:28:53 +0000 Subject: [PATCH] docs: refine custom provider recommendations Co-authored-by: kiloconnect[bot] <240665456+kiloconnect[bot]@users.noreply.github.com> --- .../pages/ai-providers/openai-compatible.md | 16 +++++----------- packages/kilo-docs/pages/ai-providers/openai.md | 1 - .../pages/code-with-ai/agents/custom-models.md | 13 ++++--------- 3 files changed, 9 insertions(+), 21 deletions(-) diff --git a/packages/kilo-docs/pages/ai-providers/openai-compatible.md b/packages/kilo-docs/pages/ai-providers/openai-compatible.md index 1ec53b478b..baabc630ed 100644 --- a/packages/kilo-docs/pages/ai-providers/openai-compatible.md +++ b/packages/kilo-docs/pages/ai-providers/openai-compatible.md @@ -14,12 +14,6 @@ Kilo Code supports a wide range of AI model providers that offer APIs compatible This document focuses on setting up providers _other than_ the official OpenAI API (which has its own [dedicated configuration page](/docs/ai-providers/openai)). -{% callout type="warning" %} -Do not use a custom OpenAI-compatible provider for Azure OpenAI GPT-5 deployments. Azure GPT-5 rejects the `max_tokens` parameter used by generic OpenAI-compatible providers and requires Azure-specific handling. - -Use Kilo Code's native `azure` provider instead. If your Azure deployment name differs from the model name you select in Kilo, map it with the model `id` field in `kilo.json`. -{% /callout %} - ## General Configuration {% tabs %} @@ -27,7 +21,7 @@ Use Kilo Code's native `azure` provider instead. If your Azure deployment name d The key to using an OpenAI-compatible provider is to configure two main settings: -1. **Base URL:** This is the API endpoint for the provider. It will _not_ be `https://api.openai.com/v1` (that's for the official OpenAI API). For Azure OpenAI GPT-5, do not enter your Azure endpoint here. Configure the native `azure` provider instead. +1. **Base URL:** This is the API endpoint for the provider. It will _not_ be `https://api.openai.com/v1` (that's for the official OpenAI API). 2. **API Key:** This is the secret key you obtain from the provider. 3. **Model ID:** This is the model name of the specific model. @@ -59,8 +53,8 @@ You'll find these settings in the Kilo Code settings panel (click the {% codicon - **Provider ID** — A unique identifier (e.g., `my-provider`). - **Display name** — A human-readable name shown in the UI. -- **Provider API** — Select **OpenAI Compatible** for an OpenAI Chat Completions-compatible endpoint. The custom provider dialog also supports **OpenAI Responses** and **Anthropic Messages** for endpoints that implement those protocols. -- **Base URL** — The provider's API endpoint (e.g., `https://api.your-provider.com/v1`). Kilo auto-fetches available models when a valid URL exposes an OpenAI-compatible models endpoint. For Azure OpenAI GPT-5, use the native `azure` provider instead. +- **Provider API** — Select **OpenAI Compatible** for an OpenAI Chat Completions-compatible endpoint. Use **OpenAI Responses** for OpenAI models, including Azure OpenAI, and xAI models. Use **Anthropic Messages** for Anthropic and MiniMax models. +- **Base URL** — The provider's API endpoint (e.g., `https://api.your-provider.com/v1`). Kilo auto-fetches available models when a valid URL exposes an OpenAI-compatible models endpoint. - **API key** — Your API key. Optional — leave empty if authentication is handled via headers. - **Models** — Add models manually or select from the auto-fetched list (see [Automatic Model Detection](#automatic-model-detection) below). - **Headers** (optional) — Custom HTTP headers as key-value pairs. @@ -121,9 +115,9 @@ Then set your default model using the `provider-id/model-id` format: **Configuration fields:** -- **`npm`** — The API protocol package. Use `@ai-sdk/openai-compatible` for OpenAI Chat Completions-compatible endpoints (the default when omitted), `@ai-sdk/openai` for OpenAI Responses, or `@ai-sdk/anthropic` for Anthropic Messages. +- **`npm`** — The API protocol package. Use `@ai-sdk/openai-compatible` for OpenAI Chat Completions-compatible endpoints (the default when omitted). Use `@ai-sdk/openai` for OpenAI models, including Azure OpenAI, and xAI models. Use `@ai-sdk/anthropic` for Anthropic and MiniMax models. - **`models`** — A map of model IDs to model definitions. Each model should include a `name` and `limit` with `context` and `output` token counts. If `limit.context` or `limit.output` is omitted, it defaults to `0`, which limits context management. -- **`options.baseURL`** — The base URL of your provider's API endpoint. For Azure OpenAI GPT-5, configure `provider.azure` instead. +- **`options.baseURL`** — The base URL of your provider's API endpoint. - **`options.apiKey`** — Your API key. Use any non-empty string (e.g., `"none"`) if the provider doesn't require authentication. You can also set the API key via an environment variable instead of putting it in the config file. Use the `env` field to specify which variable to read: diff --git a/packages/kilo-docs/pages/ai-providers/openai.md b/packages/kilo-docs/pages/ai-providers/openai.md index 867d6399be..087373acf2 100644 --- a/packages/kilo-docs/pages/ai-providers/openai.md +++ b/packages/kilo-docs/pages/ai-providers/openai.md @@ -75,4 +75,3 @@ Then set your default model: ## Tips and Notes - **Pricing:** Refer to the [OpenAI Pricing](https://openai.com/pricing) page for details on model costs. -- **Azure OpenAI Service:** Use Kilo Code's native `azure` provider for Azure OpenAI, especially GPT-5 deployments. Do not configure Azure GPT-5 through a generic [OpenAI-compatible](/docs/ai-providers/openai-compatible) custom provider. diff --git a/packages/kilo-docs/pages/code-with-ai/agents/custom-models.md b/packages/kilo-docs/pages/code-with-ai/agents/custom-models.md index ba76c73abf..955eece98e 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/custom-models.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/custom-models.md @@ -80,8 +80,8 @@ Custom providers can use three API protocols. In `kilo.jsonc`, set the provider- | Provider API | `npm` value | Use for | |---|---|---| | OpenAI Compatible | `@ai-sdk/openai-compatible` | OpenAI Chat Completions-compatible endpoints. This is the default when `npm` is omitted. | -| OpenAI Responses | `@ai-sdk/openai` | Endpoints that implement the OpenAI Responses API. | -| Anthropic Messages | `@ai-sdk/anthropic` | Endpoints that implement the Anthropic Messages API. | +| OpenAI Responses | `@ai-sdk/openai` | Recommended for OpenAI models, including Azure OpenAI, and xAI models. | +| Anthropic Messages | `@ai-sdk/anthropic` | Recommended for Anthropic and MiniMax models. | For example, configure a custom endpoint that implements the OpenAI Responses API like this: @@ -104,8 +104,6 @@ For example, configure a custom endpoint that implements the OpenAI Responses AP } ``` -Use `"npm": "@ai-sdk/anthropic"` instead for an Anthropic Messages endpoint. You can also override the package for one model with `provider..models..provider.npm`. - ## Model Configuration Fields All fields are optional. When a model ID matches one already in the built-in catalog, your values are merged on top of the defaults — you only need to specify what you want to override. @@ -327,13 +325,10 @@ MiniMax's OpenAI-compatible Chat Completions API supports the optional boolean ` "thinking": { "reasoning_split": true, }, - "standard": { - "reasoning_split": false, - }, } ``` -With `true`, MiniMax returns thinking separately in `reasoning_content` and `reasoning_details`; with `false`, thinking remains embedded in `content`. This setting changes only the response format, not whether the model thinks. Leave it unset for providers that do not support it. +With `true`, MiniMax returns thinking separately in `reasoning_content` and `reasoning_details`. This setting changes only the response format, not whether the model thinks. Leave it unset for providers that do not support it. ### Using the id field to map model names @@ -358,7 +353,7 @@ If the model key in your config differs from what the provider expects, use the Here `my-local-llama` is the key you use in your config and model picker, while `meta-llama-3.1-8b-instruct` is the actual model identifier sent to the LM Studio API. -For Azure OpenAI, use the native `azure` provider and set `id` to your Azure deployment name when it differs from the model key. Do not configure Azure GPT-5 family deployments under `openai-compatible`, because that provider sends `max_tokens` and Azure GPT-5 expects `max_completion_tokens`. +When using the native `azure` provider, set `id` to your Azure deployment name when it differs from the model key. ```jsonc {