> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/integrations/kilo-code-integration.md).

# Kilo Code integration

Configure Kilo Code with the nexos.ai API Gateway for multi-provider LLM access in VS Code. A guide for API keys, provider config, and model selection.

Configure Kilo Code with the nexos.ai API Gateway for multi-provider LLM access in VS Code and in the terminal. A guide for API keys, provider config, and model selection.

Connect **Kilo Code** to the **nexos.ai API Gateway** to use the models available in your nexos.ai platform directly inside Visual Studio Code or from the Kilo CLI.

Kilo Code supports any OpenAI-compatible endpoint through a **Custom provider**. By adding nexos.ai as a custom provider, every request Kilo Code makes (chat, tool calls, optional codebase indexing) is routed through nexos.ai using your nexos.ai API key, with the usual load balancing, cost tracking and observability.

**One configuration for VS Code and CLI.** The current Kilo Code extension is built on top of the Kilo CLI (a fork of [OpenCode](https://docs.nexos.ai/gateway-api/integrations/opencode)). Both share the same `kilo.jsonc` config file, so a nexos.ai provider added in one is available in the other.

## What is Kilo Code? <a href="#what-is-kilo-code" id="what-is-kilo-code"></a>

Kilo Code is an open-source (MIT) AI coding agent available as a VS Code extension, a JetBrains plugin and a terminal CLI. It can read and edit files, run terminal commands, browse the web and use MCP servers to complete multi-step tasks.

**Key features:**

* **Agents (modes)** – built-in Code, Plan, Ask and Debug agents, plus custom agents and subagents, keep the model focused on a specific kind of work. (The former Orchestrator agent is deprecated: Code, Plan and Debug launch subagents themselves.)
* **Provider agnostic** – works with 30+ providers and any OpenAI-compatible endpoint, including the nexos.ai Gateway.
* **Separate model roles** – main, small, subagent, compaction and memory models can each point at a different model.
* **MCP support** – connect Model Context Protocol servers to extend the agent with external tools.
* **Codebase indexing** – semantic search over your project using an embedding model and a LanceDB (built-in) or Qdrant vector store.
* **Kilo CLI** – the same agent in your terminal, scriptable and usable over SSH.

**Useful links:**

* [Kilo Code Documentation](https://kilo.ai/docs)
* [GitHub - Kilo-Org/kilocode: Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.](https://github.com/Kilo-Org/kilocode)
* [Open VSX Registry](https://open-vsx.org/extension/kilocode/Kilo-Code)

***

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* A **nexos.ai API key** (user key or team key). See [How to generate a nexos.ai API key](https://docs.nexos.ai/gateway-api/api-keys).
* **Visual Studio Code 1.105.1 or later** (VSCodium, Windsurf and other Open VSX editors also work), and/or **Node.js with npm** for the Kilo CLI.
* At least one model in your nexos.ai workspace that supports the **Chat Completions** endpoint **and native tool calling**. Kilo Code edits files and runs commands through tool calls, so a model without tool calling cannot do agentic work.

{% hint style="warning" %}
Gateway base URL used throughout this guide: `https://api.nexos.ai/v1`. The `/v1` suffix is required.
{% endhint %}

***

## How to connect Kilo Code (VS Code) with nexos.ai <a href="#how-to-connect-kilo-code-vs-code-with-nexos.ai" id="how-to-connect-kilo-code-vs-code-with-nexos.ai"></a>

### 1. Generate your nexos.ai API key <a href="#id-1.-generate-your-nexos.ai-api-key" id="id-1.-generate-your-nexos.ai-api-key"></a>

In your nexos.ai workspace open the **API Keys** tab, select **Generate API Key**, enter a name for the key and click **Generate**. Copy the key immediately: it is shown only once and cannot be retrieved after the dialog is closed.

The key inherits the settings configured by your organization owner (enabled models, fallbacks, limits). API usage requires purchased API credits.

{% hint style="warning" %}
Store your API key safely and never share it. Kilo Code keeps keys entered in the UI in `~/.local/share/kilo/auth.json` (plain text, readable only by your user), not in VS Code secret storage. Never put the key in a project-level `kilo.json` / `kilo.jsonc` that is committed to a repository.
{% endhint %}

### 2. Install the Kilo Code extension <a href="#id-2.-install-the-kilo-code-extension" id="id-2.-install-the-kilo-code-extension"></a>

Kilo Code is published on the VS Code Marketplace by **kilocode** (`kilocode.Kilo-Code`). This guide requires version **7.x or later**, which is the regular release.

* **VS Code Extensions tab (recommended)** – open the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`), search for **"Kilo Code"**, select **Kilo Code: AI Coding Agent, Copilot, and Autocomplete** by **kilocode** and click **Install**.
* **Command line**:

{% code lineNumbers="true" %}

```shellscript
code --install-extension kilocode.Kilo-Code
```

{% endcode %}

On macOS, if you get `command not found: code`, open VS Code, press `Cmd+Shift+P` and run **Shell Command: Install 'code' command in PATH**, then open a new terminal. Alternatively, call it by its full path: `"/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"`.

* **Open VSX** (VSCodium, Windsurf and other editors without Marketplace access) – search for "Kilo Code" in the editor's Extensions view, or use [open-vsx.org/extension/kilocode/Kilo-Code](https://open-vsx.org/extension/kilocode/Kilo-Code).
* **Manual VSIX** – download the `.vsix` from [GitHub Releases](https://github.com/Kilo-Org/kilocode/releases) and use **Extensions → ... → Install from VSIX...**.

{% hint style="warning" %}
You may be asked whether you trust the publisher of the extension. Make sure you are familiar with the risks of installing third-party extensions.
{% endhint %}

After installation a Kilo Code icon appears in the VS Code Activity Bar. On first launch Kilo Code asks you to sign in to a Kilo account. **A Kilo account is not needed for the nexos.ai setup.** See [Keep all traffic on nexos.ai](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1476198404/Kilo+Code+Integration#Keep-all-traffic-on-nexos.ai) for why you may prefer not to sign in.

### 3. Add nexos.ai as a custom provider <a href="#id-3.-add-nexos.ai-as-a-custom-provider" id="id-3.-add-nexos.ai-as-a-custom-provider"></a>

Open the Kilo Code panel, click the **gear icon** to open **Settings** and go to the **Providers** tab. Scroll to the bottom and click **Custom provider**.

Fill in the custom provider dialog as follows:

| **Setting**      | **Value**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider ID**  | `nexos` (lowercase letters, numbers, hyphens or underscores; used as the prefix in `nexos/<model-id>`)                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Display name** | `nexos.ai`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Provider API** | `OpenAI Compatible`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Base URL**     | `https://api.nexos.ai/v1`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **API key**      | The nexos.ai key generated in step 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Models**       | Click **Fetch models** and select the chat models you want, or click **Add model** and enter the **ID** exactly as returned by `GET /v1/models`, e.g. `Claude Sonnet 5.5` (see step 4). The fetched list contains every model in your workspace, including embedding, image, speech and rerank models: add only chat models. Each model row has a **Reasoning** toggle (sets `reasoning: true`; turn it on for reasoning models) and an **Image** toggle (lets you send screenshots to models with vision). |
| **Headers**      | Leave empty                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2FI2QrA7gaowRrBMXV1h8O%2Fimage.png?alt=media&amp;token=bc90eb01-5c41-4a68-a48d-fa0e31220aca" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2FXunT8KNZ2EOp5gt9tCKj%2Fimage.png?alt=media&amp;token=a1716f79-e238-4e3e-8e70-f4b4792e22a8" alt="" width="563"><figcaption></figcaption></figure>

Click **Submit** to save. The nexos.ai models now appear in the model picker. To change the provider later, click **Edit provider** next to it in the connected providers section.

Behind the scenes Kilo writes the provider (without the key) to your global config `~/.config/kilo/kilo.jsonc` and stores the key in `~/.local/share/kilo/auth.json`. The Kilo CLI on the same machine picks up both automatically.

{% hint style="info" %}
**Start with OpenAI Compatible.** A custom provider uses one Provider API for all its models, and Chat Completions is the only one supported by every chat model in nexos.ai. If you use **Claude** models, also add a second provider with **Anthropic Messages**: it enables prompt caching and makes long agent sessions noticeably cheaper. See [Choosing the Provider API](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1476198404/Kilo+Code+Integration#Choosing-the-Provider-API).
{% endhint %}

### 4. Choose a model and set its limits <a href="#id-4.-choose-a-model-and-set-its-limits" id="id-4.-choose-a-model-and-set-its-limits"></a>

Once the Base URL and API key are filled in, Kilo Code queries the Gateway's `/v1/models` endpoint and shows a searchable model picker. Click **Fetch models** to retry if the list did not load. To double-check a model's capabilities, query the nexos.ai Models endpoint directly:

{% code lineNumbers="true" %}

```shellscript
curl "https://api.nexos.ai/v1/models" \
 -H "Authorization: Bearer $NEXOS_API_KEY"
```

{% endcode %}

Each entry in `data` contains the `id` to use in Kilo Code (usually a readable name such as `Claude Sonnet 5.5` or `GPT 5.5`; spaces are fine, and some models also have slug aliases such as `claude-sonnet-5`), together with `context_length`, `max_tokens`, `pricing` and the supported `endpoints`. Matching of the model ID is case-insensitive but otherwise exact; the `nexos_model_id` UUID is accepted as well.

When picking a model for Kilo Code make sure that:

* its `endpoints` include `chat_completion`, and
* it supports **native tool calling**: `"supports_tools": true`. Do not rely on `function_calling` in `input_capabilities`: several current models (e.g. Claude Sonnet 5.5, GPT 5.4 mini) support tools without listing it there. Frontier coding models such as the current Claude Sonnet/Opus, GPT-5 family or Gemini Pro models do; small or older models often do not.

**Set the context and output limits.** The custom provider dialog does not ask for token limits, and models added through it get a context window and output limit of `0`. A context window of `0` **disables automatic context compaction**: the conversation grows until the Gateway rejects the request. An output limit of `0` also breaks the thinking budgets Kilo derives from it. Use **Edit advanced settings in the JSON config file** in the Edit provider dialog (or open `~/.config/kilo/kilo.jsonc` directly) and add the limits to each model:

{% code lineNumbers="true" %}

```json
{
  "provider": {
    "nexos": {
      "models": {
        "Claude Sonnet 5.5": {
          "name": "Claude Sonnet 5.5",
          "tool_call": true,
          "limit": {
            "context": 1000000, // context_length from /v1/models
            "output": 32000     // max_tokens from /v1/models, capped by Kilo at 32000
          }
        }
      }
    }
  }
}
```

{% endcode %}

Mapping between `/v1/models` and Kilo model fields:

| **Kilo field**              | **Source in `/v1/models`**               | **Why it matters**                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `limit.context`             | `context_length`                         | Kilo uses it to compact the conversation before the limit is reached. When `limit` is present, **both** `context` and `output` are required; otherwise the model is dropped with a `Skipped invalid model configuration` warning                                                                                                     |
| `limit.output`              | `max_tokens`                             | Upper bound for a single response. Kilo caps it at 32,000 regardless of a higher `max_tokens` (and uses 32,000 when unset), so `32000` is the practical value                                                                                                                                                                        |
| `tool_call`                 | `supports_tools`                         | Must be `true` for the agent to edit files and run commands                                                                                                                                                                                                                                                                          |
| `modalities` + `attachment` | `input_capabilities` (`image`, `vision`) | Enables sending screenshots/images, e.g. `{"input": ["text", "image"], "output": ["text"]}` plus `"attachment": true`                                                                                                                                                                                                                |
| `cost`                      | `pricing`                                | Only used for Kilo's cost estimate. Kilo expects USD **per million tokens**, while `pricing` is per token (as a string): multiply by 1,000,000 (e.g. `input_cost_per_token` `"0.0000022"` → `"input": 2.2`). Both `input` and `output` are required when `cost` is present. The nexos.ai usage dashboard remains the source of truth |

{% hint style="warning" %}
Treat `GET /v1/models` as the source of truth for the models your key can use. Model availability is controlled by your workspace administrator. Learn more at [docs.nexos.ai/gateway-api/models](https://docs.nexos.ai/gateway-api/models).
{% endhint %}

### 5. Send your first message <a href="#id-5.-send-your-first-message" id="id-5.-send-your-first-message"></a>

Open a project folder, select a **nexos.ai** model in the model picker, pick the **Code** agent and send a simple request, for example *"Explain what this repository does"*. The response should stream in and any file reads should appear as tool calls in the task timeline. The request is visible in your nexos.ai usage dashboard, which confirms that traffic is flowing through the Gateway.

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2Fmvreb3x5oCAEG3dv3edX%2FScreenshot%202026-10-16%20at%2016.58.34.png?alt=media&amp;token=3992cfca-16a7-41fc-af77-33114fecc89c" alt="" width="552"><figcaption></figcaption></figure>

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2FUYq7sAHLn73czu26Jc31%2Fimage.png?alt=media&amp;token=d17c7c92-f956-4202-b19a-3fbc8d92c1d7" alt="" width="552"><figcaption></figcaption></figure>

Kilo Code now routes all requests through the **nexos.ai API Gateway**, giving you access to multiple LLM providers through a single endpoint with centralized cost tracking, limits and observability.

***

## Using the Kilo CLI with nexos.ai <a href="#using-the-kilo-cli-with-nexos.ai" id="using-the-kilo-cli-with-nexos.ai"></a>

The Kilo CLI reads the same configuration as the extension. If you have already completed the VS Code setup on this machine, just run `kilo` and pick a `nexos/…` model with `/models`. Otherwise:

1. Install the CLI:

{% code lineNumbers="true" %}

```shellscript
npm install -g @kilocode/cli
kilo --version
```

{% endcode %}

2. Export your nexos.ai API key, e.g. in `~/.zshrc` or `~/.bashrc`:

{% code lineNumbers="true" %}

```shellscript
export NEXOS_API_KEY="<your nexos.ai API key>"
```

{% endcode %}

3. Create or edit the global config file `~/.config/kilo/kilo.jsonc`:

{% code lineNumbers="true" %}

```json
{
  "$schema": "https://app.kilo.ai/config.json",
  "provider": {
    "nexos": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "nexos.ai",
      "options": {
        "baseURL": "https://api.nexos.ai/v1",
        "apiKey": "{env:NEXOS_API_KEY}"
      },
      "models": {
        "Claude Sonnet 5.5": {
          "name": "Claude Sonnet 5.5",
          "tool_call": true,
          "limit": { "context": 1000000, "output": 32000 }
        },
        "Claude Haiku 5.5": {
          "name": "Claude Haiku 5.5",
          "tool_call": true,
          "limit": { "context": 1000000, "output": 32000 }
        }
      }
    }
  },
  "model": "nexos/Claude Sonnet 5.5",
  "small_model": "nexos/Claude Haiku 5.5"
}
```

{% endcode %}

Replace the model IDs and limits with models enabled in your workspace (see step 4 above). For Claude models, consider the Anthropic Messages provider from [Choosing the Provider API](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1476198404/Kilo+Code+Integration#Choosing-the-Provider-API) instead.

4. Check that the config is valid and the nexos.ai models are listed, then start Kilo in your project directory:

{% code lineNumbers="true" %}

```shellscript
kilo config check
kilo models nexos
kilo
```

{% endcode %}

5. Optionally, run a one-off task without the interactive UI:

{% code lineNumbers="true" %}

```shellscript
kilo run "Explain what this repository does"
```

{% endcode %}

Configuration breakdown:

* `npm` – `@ai-sdk/openai-compatible` tells Kilo to talk to the Gateway via the Chat Completions API.
* `options.baseURL` – the nexos.ai Gateway URL, including `/v1`.
* `options.apiKey` – `{env:NEXOS_API_KEY}` reads the key from the environment, so it is not stored in the file.
* `models` – an object (not an array) keyed by nexos.ai model ID. IDs with spaces work as keys (`nexos/Claude Sonnet 5.5`). If you prefer a shorter name, use your own key and put the real ID in the `id` field, e.g. `"sonnet": { "id": "Claude Sonnet 5.5", ... }` → `nexos/sonnet`.
* `model` / `small_model` – the default main and small model, in the `provider-id/model-id` format.

{% hint style="warning" %}
`{env:…}` references are allowed **only in the global config** (`~/.config/kilo/`). A project-level `kilo.json` / `kilo.jsonc` that contains one is rejected as a whole. This is a Kilo security feature that stops a malicious repository from sending your key to its own `baseURL`. Keep the nexos.ai provider in your global config.
{% endhint %}

***

## Choosing the Provider API <a href="#choosing-the-provider-api" id="choosing-the-provider-api"></a>

The nexos.ai Gateway exposes three APIs that Kilo Code can use. A Kilo custom provider talks to exactly one of them, so if you want more than one, add several custom providers that point to the same Base URL and API key (e.g. `nexos`, `nexos-anthropic`, `nexos-openai`). Their models all appear in the model picker.

| **Provider API in Kilo**                            | **nexos.ai endpoint**  | **Models**                                                         | **Recommended for**                                                     |
| --------------------------------------------------- | ---------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| **OpenAI Compatible** (`@ai-sdk/openai-compatible`) | `/v1/chat/completions` | All chat models (`chat_completion` in `endpoints`)                 | Default for everything; Gemini, Mistral, DeepSeek, GLM and other models |
| **Anthropic Messages** (`@ai-sdk/anthropic`)        | `/v1/messages`         | Models with `messages` in `endpoints` (all Claude models)          | **Claude models**: enables prompt caching                               |
| **OpenAI Responses** (`@ai-sdk/openai`)             | `/v1/responses`        | Models with `responses` in `endpoints` (GPT, Grok and some others) | Optional for GPT models: OpenAI's native API for reasoning models       |

How each option behaves with Kilo Code:

| **Model / API**               | **Tool calls and file edits** | **Prompt caching**                                                                                           | **Reasoning / thinking variants**                                                                                                                          |
| ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude via OpenAI Compatible  | Works                         | **None** with the readable nexos.ai IDs (e.g. `Claude Sonnet 5.5`): every step is billed as full-price input | Works when the model's **Reasoning** toggle is on (`reasoning: true`): Kilo sends `reasoning_effort`, which the Gateway maps to Claude's adaptive thinking |
| Claude via Anthropic Messages | Works                         | **Works**: the repeated context is read from cache on every step                                             | Works after defining variants (see below)                                                                                                                  |
| GPT via OpenAI Compatible     | Works                         | Works (automatic)                                                                                            | Works                                                                                                                                                      |
| GPT via OpenAI Responses      | Works                         | Works (automatic)                                                                                            | Works                                                                                                                                                      |

#### Claude models via Anthropic Messages (recommended for Claude) <a href="#claude-models-via-anthropic-messages-recommended-for-claude" id="claude-models-via-anthropic-messages-recommended-for-claude"></a>

Claude models only cache prompts when the client marks the reusable part of the conversation. Kilo adds these markers on the Anthropic Messages API (see the nexos.ai [Messages endpoint](https://docs.nexos.ai/gateway-api/messages)); on OpenAI Compatible it does so only for model IDs containing lowercase `claude`, which the readable nexos.ai IDs do not. With caching, the repeated part of the context (system prompt, tool definitions, earlier turns) costs about a tenth of the normal input price after the first write. Even in a short five-step agent task, input cost is about 40% lower than through OpenAI Compatible, and the saving grows with every further step of a session.

**In VS Code:** add a second custom provider (**Settings → Providers → Custom provider**):

| **Setting**      | **Value**                                                                                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider ID**  | `nexos-anthropic`                                                                                                                                                                                                                                           |
| **Display name** | `nexos.ai (Claude)`                                                                                                                                                                                                                                         |
| **Provider API** | `Anthropic Messages`                                                                                                                                                                                                                                        |
| **Base URL**     | `https://api.nexos.ai/v1`                                                                                                                                                                                                                                   |
| **API key**      | Your nexos.ai key                                                                                                                                                                                                                                           |
| **Models**       | Click **Add model** and enter Claude model IDs from `/v1/models`, e.g. `Claude Sonnet 5.5`, `Claude Haiku 5.5`, and turn on the **Reasoning** toggle for models you want thinking variants for. Models are not fetched automatically for this Provider API. |

Then add the token limits and thinking variants in `kilo.jsonc` as shown below, and pick the **nexos.ai (Claude)** models in the model picker.

**In kilo.jsonc** (VS Code and CLI), next to the `nexos` provider:

{% code lineNumbers="true" %}

```json
{
  "provider": {
    "nexos-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "nexos.ai (Claude)",
      "options": {
        "baseURL": "https://api.nexos.ai/v1",
        "apiKey": "{env:NEXOS_API_KEY}"
      },
      "models": {
        "Claude Sonnet 5.5": {
          "name": "Claude Sonnet 5.5",
          "tool_call": true,
          "reasoning": true,
          "limit": { "context": 1000000, "output": 32000 },
          "variants": {
            "low":  { "thinking": { "type": "adaptive", "display": "summarized" }, "effort": "low" },
            "high": { "thinking": { "type": "adaptive", "display": "summarized" }, "effort": "high" }
          }
        },
        "Claude Haiku 5.5": {
          "name": "Claude Haiku 5.5",
          "tool_call": true,
          "limit": { "context": 1000000, "output": 32000 }
        }
      }
    }
  },
  "model": "nexos-anthropic/Claude Sonnet 5.5",
  "small_model": "nexos-anthropic/Claude Haiku 5.5"
}
```

{% endcode %}

If you entered the key in the VS Code dialog, leave out `apiKey`: the key is already stored in `auth.json`.

{% hint style="warning" %}
**Define the thinking variants yourself.** Kilo only recognises Claude models whose ID contains `claude-`, so for nexos.ai IDs such as `Claude Sonnet 5.5` it falls back to an older thinking format that current Claude models reject (`"thinking.type.enabled" is not supported for this model`). The `variants` block above uses adaptive thinking with an effort level and works. `"display": "summarized"` asks Claude to return a summary of its thinking, which Kilo shows as a reasoning block (**Settings → Display → Reasoning Blocks**); without it, current Claude models return no thinking text. Select a variant in the model picker or with `kilo run --variant high`. Models that also have a `claude-…` alias in `/v1/models` (e.g. `claude-sonnet-5`) are recognised automatically when added under that alias and need no manual variants.
{% endhint %}

#### GPT models via OpenAI Responses (optional) <a href="#gpt-models-via-openai-responses-optional" id="gpt-models-via-openai-responses-optional"></a>

GPT models work well through OpenAI Compatible, including automatic prompt caching and reasoning levels. Use OpenAI Responses if you want OpenAI's native API for reasoning models; it behaves the same for tool calls and caching. Add a provider with **Provider API** `OpenAI Responses`, or in `kilo.jsonc`:

{% code lineNumbers="true" %}

```json
{
  "provider": {
    "nexos-openai": {
      "npm": "@ai-sdk/openai",
      "name": "nexos.ai (GPT)",
      "options": {
        "baseURL": "https://api.nexos.ai/v1",
        "apiKey": "{env:NEXOS_API_KEY}"
      },
      "models": {
        "GPT 5.5": {
          "name": "GPT 5.5",
          "tool_call": true,
          "reasoning": true,
          "limit": { "context": 1050000, "output": 32000 }
        }
      }
    }
  }
}
```

{% endcode %}

Only add models whose `endpoints` in `/v1/models` include `responses`.

***

## Keep all traffic on nexos.ai <a href="#keep-all-traffic-on-nexos.ai" id="keep-all-traffic-on-nexos.ai"></a>

Kilo Code ships with its own hosted gateway (Kilo Gateway). Even without a Kilo account, the model picker also lists Kilo's free models (`kilo-auto/free` and others), and some background tasks can fall back to Kilo Gateway when you are signed in. To make sure every LLM request goes through nexos.ai:

* **Pick a nexos.ai model** (shown under your nexos.ai provider) in the model picker, and set it as the default with `model` in `kilo.jsonc` (or **Settings → Models**).
* **Do not sign in to Kilo, or sign out** in the extension or CLI. Kilo documents logging out of Kilo Gateway as the way to guarantee that no inference goes through it.
* **Set the Small model explicitly** to a nexos.ai model (**Settings → Models → Small Model**, or `small_model` in `kilo.jsonc`). It is used for session titles, commit messages, branch names and prompt enhancement. If unset while signed in, Kilo uses `kilo-auto/small` on Kilo Gateway.
* **Subagent, compaction and memory models** inherit the current session's model when left unset, so they stay on nexos.ai. You can also point each of them at a cheaper nexos.ai model under **Settings → Models** (`subagent_model`, `agent.compaction.model` and `memory_model` in `kilo.jsonc`).
* **Autocomplete** (inline code suggestions) is a separate feature that always runs through Kilo Gateway, also when you bring your own Mistral or Inception key on app.kilo.ai. It cannot be routed through nexos.ai, so disable it if you need all traffic on nexos.ai.

Kilo still downloads its public model catalog from [models.dev](https://models.dev/) on startup and refreshes it hourly. This is model metadata only; no prompts or code are sent. Set `KILO_DISABLE_MODELS_FETCH=1` to turn it off.

***

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* **"Model not found"** (HTTP 404, code `100110`) – the model ID must be exactly as returned by `GET /v1/models` for your key (case does not matter). If the model is missing from the list, ask your workspace administrator to enable it.
* **Connection errors, or** `Not Found: {"error":{"message":"Not Found"}}` **on every request** – check that the Base URL is exactly `https://api.nexos.ai/v1`, including `/v1`, and that the Provider API matches the models (see [Choosing the Provider API](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1476198404/Kilo+Code+Integration#Choosing-the-Provider-API)).
* **The model list does not load** – check the API key and click **Fetch models**. You can always add model IDs manually. For Anthropic Messages, models are never fetched automatically.
* **The agent answers in plain text but never edits files, or errors mention** `tools` – the selected model does not support native tool calling. Switch to a model that does and set `"tool_call": true`.
* **Long sessions fail with a context-length error** – `limit.context` is not set, so Kilo never compacts the conversation. See step 4.
* **A model disappears from the picker after editing** `kilo.jsonc`, with a `Skipped invalid model configuration` warning – `limit` needs both `context` and `output`, and `cost` needs both `input` and `output`. Config warnings are listed in **View → Output → Kilo Config Warnings**.
* **Long Claude sessions are expensive** – Claude through OpenAI Compatible gets no prompt caching. Use a provider with Anthropic Messages for Claude models.
* `"thinking.type.enabled" is not supported for this model` **when choosing a reasoning level for a Claude model** – define adaptive thinking `variants` for the model. See [Choosing the Provider API](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1476198404/Kilo+Code+Integration#Choosing-the-Provider-API).
* **Claude answers but no thinking is shown** – add `"display": "summarized"` to the `thinking` object of each variant, and check **Settings → Display → Reasoning Blocks**.
* `Model not found: nexos/…` **although the model is in your config** – the config file was rejected. Run `kilo config check` in the project directory to see why. A common cause is `environment references are not allowed in project config`: the provider is defined in a project-level `kilo.json` using `{env:…}`. Move it to `~/.config/kilo/kilo.jsonc`.
* **Config error** `provider.nexos.models: Expected object | undefined, got [...]` – `models` must be an object keyed by model ID, not an array.
* **Requests do not show up in the nexos.ai usage dashboard** – you are signed in to Kilo and a Kilo Gateway model is selected. See [Keep all traffic on nexos.ai](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1476198404/Kilo+Code+Integration#Keep-all-traffic-on-nexos.ai).

For request-level debugging in VS Code run **Developer: Open Webview Developer Tools** from the Command Palette and check the Console and Network tabs; config problems are listed under **View → Output → Kilo Config Warnings**. CLI logs are under `~/.local/share/kilo/log`. Community help: [Kilo Code Discord](https://kilo.ai/discord), [GitHub Issues](https://github.com/Kilo-Org/kilocode/issues).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexos.ai/gateway-api/integrations/kilo-code-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
