---
title: "Kilo Code Custom Provider Setup: Add Any OpenAI-Compatible API"
description: "Add Haimaker, OpenRouter, Ollama, or any OpenAI-compatible API to Kilo Code. Covers the OpenAI Compatible provider, the OpenRouter path with kilo.json, the Model Configuration fields custom endpoints need, and fixes for the common errors."
date: 2026-06-25
location: San Francisco, CA – Jun 25th, 2026
image: /images/kilo-code-custom-provider-setup-hero.jpg
unlisted: true
keywords: "kilo code custom provider, kilo code openai compatible, kilo code openrouter, kilo code add provider, kilo code model, kilo code haimaker, kilo code llm provider, kilo code api key, kilo.json"
faq:
  - question: "How do I add a custom provider to Kilo Code?"
    answer: "Open Kilo Code settings (gear icon), set API Provider to 'OpenAI Compatible', then enter the Base URL and API Key from your provider and the Model ID. Open Model Configuration to set Context Window, Max Output Tokens, and Computer Use for agentic coding. For example, point the Base URL at https://api.haimaker.ai/v1 for Haimaker and route many model families through one key. For Haimaker specifically, 'npx -y @haimaker/connect --kilo' writes this provider config for you."
  - question: "What is the difference between the OpenAI Compatible and OpenRouter providers in Kilo Code?"
    answer: "OpenRouter is a built-in aggregator: you paste one OpenRouter key and pick from its model menu, and Kilo Code can store it in kilo.json. OpenAI Compatible is the generic path for any endpoint that speaks the OpenAI chat format, where you supply the Base URL yourself. Use OpenAI Compatible for a gateway like Haimaker, a local runtime, or an internal endpoint."
  - question: "Why does my custom Kilo Code model fail or behave strangely?"
    answer: "For OpenAI Compatible providers, Kilo Code cannot auto-detect model limits, so check that Context Window and Max Output Tokens match the model and that Computer Use is on for agentic work. Also note: do not use the OpenAI Compatible provider for Azure GPT-5 deployments, which reject the max_tokens parameter. Use Kilo Code's native Azure provider for those."
---

Kilo Code is an open-source agentic coding platform (~25K GitHub stars) that runs as a VS Code extension and a CLI. It bundles a long list of providers, but two paths matter when the model you want is not on that list or you want to route many models through one key: the **OpenAI Compatible** provider and the built-in **OpenRouter** aggregator.

This guide covers both. The OpenAI Compatible provider is the one to reach for when you have a gateway, a local runtime, or an internal endpoint and you want to supply the Base URL yourself. OpenRouter is the quicker path when you just want one key in front of a large public model menu.

> **Just want Haimaker in Kilo Code?** Skip the manual settings — run `npx -y @haimaker/connect --kilo` and the CLI writes Kilo Code's OpenAI Compatible provider config (endpoint, key, and model) for you, then exits. The two paths below are the general methods for wiring up any endpoint by hand. See the [connect guide](/connect) for the one-command path.

## When to use each path

- **OpenAI Compatible** — any endpoint that speaks the OpenAI chat completions format and where you control the Base URL. This is the path for [Haimaker](https://haimaker.ai) (one key across many model families), a local Ollama or LM Studio server, or a company-hosted gateway.
- **OpenRouter** — a built-in aggregator. You paste a single OpenRouter key and choose from its model menu. Good when you want breadth fast and do not need a custom endpoint.

Both end up doing the same thing: sending OpenAI-format requests to a model. The difference is who owns the Base URL and how the credential is stored.

## Path A: OpenAI Compatible provider (Haimaker, Ollama, internal gateways)

### Step 1: Open settings and select the provider

Click the gear icon to open Kilo Code settings. Under **API Provider**, choose **OpenAI Compatible**. The form switches to the generic fields: Base URL, API Key, Model, and a Model Configuration section.

### Step 2: Enter the Base URL and API key

- **Base URL** — the provider's endpoint. For Haimaker that is `https://api.haimaker.ai/v1`. Kilo Code accepts both the version-prefixed base (`https://api.provider.com/v1`) and a full chat-completions URL (`https://api.provider.com/v1/chat/completions`).
- **API Key** — the secret key from your provider, pasted raw with no `Bearer` prefix.

### Step 3: Set the Model

In the **Model** field, enter the exact model identifier the provider expects. Kilo Code passes this through unchanged, so it must match the upstream API. For Haimaker:

```text
anthropic/claude-sonnet-4-6
openai/gpt-5.4-mini
minimax/minimax-m2.5
qwen/qwen3-coder
```

### Step 4: Fill in Model Configuration

For an OpenAI Compatible provider, Kilo Code cannot detect a model's capabilities, so it falls back to defaults. Open **Model Configuration** and set:

- **Context Window** — the model's real input limit.
- **Max Output Tokens** — the per-response output cap.
- **Image Support** — on only for multimodal models.
- **Computer Use** — turn this **on** for models you want to drive agentic edits and tool calls. Left off, Kilo Code treats the model as chat-only and agentic actions fail.
- **Input / Output Pricing** — the provider's per-million-token rates, used for the in-session cost estimate only.

Getting Context Window and Computer Use right resolves most "connected but broken" cases.

## Path B: OpenRouter

OpenRouter is built in, so the setup is shorter.

### Step 1: Get an OpenRouter key

Sign in at [openrouter.ai](https://openrouter.ai/) with Google or GitHub, open the [keys page](https://openrouter.ai/keys), and create a key. Copy it.

### Step 2: Add it in Kilo Code

Open Settings (gear icon), go to the **Providers** tab, choose **OpenRouter**, and paste your key. The VS Code extension stores this in your `kilo.json` configuration file automatically. Then pick a model from the OpenRouter menu.

### Editing kilo.json directly

If you prefer to edit config by hand, the OpenRouter block in `kilo.json` looks like this:

```json
{
  "provider": {
    "openrouter": {
      "models": {
        "anthropic/claude-sonnet-4-20250514": {
          "options": {}
        }
      }
    }
  }
}
```

Anything under `options` passes straight through to the OpenRouter API without validation. Two useful ones:

- **`"transforms": ["middle-out"]`** — OpenRouter's middle-out compression, which helps when a conversation runs past the model's context window.
- **Provider routing** — `sort`, `order`, `only`, and `data_collection` let you steer which upstream inference provider OpenRouter uses.

## Testing it

Whichever path you used, confirm it resolves before pointing Kilo Code at real code:

1. Pick the model in Kilo Code and send a small prompt in a throwaway task.
2. If it fails, isolate the provider from the config by calling the API directly:

```bash
curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"
```

A clean JSON list back means your key and endpoint are good and the issue is in the Kilo Code form. Use the exact `id` values from that response in the Model field.

## Common errors and fixes

#### Model connects but agentic actions fail

**Computer Use** is off, so Kilo Code is treating the model as chat-only. Turn it on in Model Configuration. If it is on and tool calls still fail, the model may be weak at structured tool use; switch to one known for agentic coding.

#### Output truncates or you hit context errors

The **Context Window** or **Max Output Tokens** value does not match the model. Kilo Code used a default for the OpenAI Compatible provider. Set both to the model's real limits.

#### Requests 404 or hit the wrong model

The **Model ID** does not match the upstream API. `anthropic/claude-sonnet-4-6` and `claude-sonnet-4-6` are different strings. Copy the exact `id` from the provider's `/models` response.

#### Azure GPT-5 rejects the request

Do **not** use the OpenAI Compatible provider for Azure GPT-5 deployments. Azure GPT-5 rejects the `max_tokens` parameter that the OpenAI Compatible path sends. Use Kilo Code's native **Azure** provider instead, and map deployment names with the model `id` field in `kilo.json`.

#### Long OpenRouter conversations error out

Add `"transforms": ["middle-out"]` under the model's `options` in `kilo.json` so OpenRouter compresses the middle of the context instead of overflowing it.

## How to access these models

You can reach the same models through more than one route. In rough order of how little configuration each takes:

- **[haimaker.ai](https://haimaker.ai)** — one OpenAI-compatible key across many model families, with [unified pricing and benchmarks](https://haimaker.ai/models); drop it into the OpenAI Compatible provider and switch models by changing one field.
- **OpenRouter** — built into Kilo Code as an aggregator; one key, a large public menu, with `kilo.json` routing controls.
- **A provider's own API** — point the OpenAI Compatible Base URL straight at a single vendor when you only need one model family.
- **Local (Ollama / LM Studio)** — run models on your machine via `http://localhost:11434/v1` or `http://127.0.0.1:1234/v1` for private work.

## The practical setup

For most Kilo Code users, a small mix covers everything:

1. **Haimaker** through the OpenAI Compatible provider for cloud models and one-key routing.
2. **Local models** via Ollama for private work.
3. **One premium model** for hard debugging and multi-file refactors.

That gives you breadth without juggling a dozen credentials, local privacy when it matters, and a stronger model on hand for the expensive tasks.

<a href="https://app.haimaker.ai/sign-up?utm_source=openclaw_blog&utm_medium=cta&utm_campaign=kilo_code_custom_provider" class="cta-button">USE HAIMAKER WITH KILO CODE</a>

---

*Setting up a different agent? See [Cline Custom Provider Setup](/blog/cline-custom-provider-setup/), [OpenCode Custom Provider Setup](/blog/opencode-custom-provider-setup/), and [OpenClaw Custom Provider Setup](/blog/openclaw-custom-provider-setup/) for the same pattern. For help picking a model, see [Best Models for OpenClaw](/blog/best-models-for-openclaw/).*