> 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/cline-integration.md).

# Cline integration

Configure Cline 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 **Cline** to the **nexos.ai API Gateway** to use the models available in your nexos.ai platform directly inside Visual Studio Code or from the Cline CLI.

Cline supports any OpenAI-compatible endpoint through its **OpenAI Compatible** provider. By pointing it at nexos.ai, every request Cline makes (chat, tool calls, file edits) is routed through nexos.ai using your nexos.ai API key, with the usual load balancing, cost tracking and observability.

### What is Cline? <a href="#what-is-cline" id="what-is-cline"></a>

Cline is an open-source (Apache 2.0) AI coding agent for VS Code, JetBrains IDEs and the terminal. It reads and edits files, runs terminal commands and uses MCP servers, asking for your approval before each action unless you enable auto-approve.

**Key features:**

* **Plan & Act modes** – plan a change with the model first, then let it implement the plan. Each mode can use a different model.
* **Provider agnostic** – works with 30+ providers and any OpenAI-compatible endpoint, including the nexos.ai Gateway.
* **Checkpoints** – roll back file changes made during a task while keeping the conversation.
* **MCP support** – connect Model Context Protocol servers to extend the agent with external tools.
* **Rules and skills** – project and global instructions that Cline follows in every task.
* **Cline CLI** – the same agent in your terminal, interactive or scripted.

**Useful links:**

* [Cline Overview - Cline](https://docs.cline.bot/)
* [GitHub - cline/cline: Autonomous coding agent as an SDK, IDE extension, or CLI assistant.](https://github.com/cline/cline)
* <https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev>

***

### 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.101.0 or later** (Cursor, Windsurf, VSCodium and other Open VSX editors also work), and/or **Node.js 20 or later** (22 recommended) for the Cline CLI.
* At least one model in your nexos.ai workspace that supports the **Chat Completions** endpoint **and native tool calling**. Cline edits files and runs commands through tool calls, so a model without function 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 Cline (VS Code) with nexos.ai <a href="#how-to-connect-cline-vs-code-with-nexos.ai" id="how-to-connect-cline-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. Do not commit it to a repository.
{% endhint %}

#### 2. Install the Cline extension <a href="#id-2.-install-the-cline-extension" id="id-2.-install-the-cline-extension"></a>

* **VS Code Extensions tab (recommended)** – open the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`), search for **"Cline"**, select **Cline** by **saoudrizwan** and click **Install**.
* **Command line**:

{% code lineNumbers="true" %}

```
code --install-extension saoudrizwan.claude-dev
```

{% 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.

* **Open VSX** (VSCodium, Windsurf and other editors without Marketplace access) – search for "Cline" in the editor's Extensions view.

{% 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 Cline icon appears in the VS Code Activity Bar. On first launch Cline asks **How will you use Cline?** Select **Bring my own API key** ("Use Cline with your provider of choice"). **A Cline account is not needed for the nexos.ai setup**: do not pick **Absolutely Free**, **ClinePass** or **Frontier Model**, which use Cline's own service.

<p align="center"><img src="https://media-cdn.atlassian.com/file/3b663869-0d7f-452d-9ee5-82ca989659cf/image/cdn?allowAnimated=true&#x26;client=7e828137-be0c-4e67-84fc-bd1b114e627a&#x26;collection=contentId-1484062744&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3ZTgyODEzNy1iZTBjLTRlNjctODRmYy1iZDFiMTE0ZTYyN2EiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0xNDg0MDYyNzQ0IjpbInJlYWQiXX0sImV4cCI6MTc5MzExMjUwOCwibmJmIjoxNzkzMTA5NjI4LCJhYUlkIjoiNzEyMDIwOjlmN2E3MTc1LWUxMmEtNDk4YS1hMzVkLWQ3MGQyMGIyM2U2MSIsImh0dHBzOi8vaWQuYXRsYXNzaWFuLmNvbS9hcHBBY2NyZWRpdGVkIjpmYWxzZSwiYXV0aFR5cGUiOiJzZXNzaW9uIn0.ViS99Mvjkf-MTadL76aCAgVn9pXmJSZ8y8S-OiPYj6M&#x26;width=527#media-blob-url=true&#x26;id=3b663869-0d7f-452d-9ee5-82ca989659cf&#x26;clientId=7e828137-be0c-4e67-84fc-bd1b114e627a&#x26;contextId=contentId-1484062744&#x26;collection=contentId-1484062744" alt="2026-10-21_19-09-47-20261021-170947.png"></p>

#### 3. Configure the OpenAI Compatible provider <a href="#id-3.-configure-the-openai-compatible-provider" id="id-3.-configure-the-openai-compatible-provider"></a>

On the **Configure your provider** screen, or later in Cline **Settings** (gear icon in the Cline panel), fill in the provider settings:

| Setting                                                          | Value                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **API Provider**                                                 | `OpenAI Compatible`                                                                                                                                                                                                                                                                                                      |
| **Base URL**                                                     | `https://api.nexos.ai/v1`                                                                                                                                                                                                                                                                                                |
| **OpenAI Compatible API Key**                                    | The nexos.ai key generated in step 1                                                                                                                                                                                                                                                                                     |
| **Model ID**                                                     | Once the Base URL and API key are filled in, Cline loads the models available to your key. Pick a chat model from the list, e.g. `Claude Sonnet 5.5`, or choose **Use custom model ID…** and enter the ID exactly as returned by `GET /v1/models`. The list also contains embedding and image models: pick a chat model. |
| **Custom Headers**                                               | None (do not click **Add Header**)                                                                                                                                                                                                                                                                                       |
| **Set Azure API version**, **Use Azure Identity Authentication** | Leave unchecked                                                                                                                                                                                                                                                                                                          |
| **Reasoning Effort**                                             | `None` for Claude models (see [Prompt caching and reasoning](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1484062744/Cline+Integration#Prompt-caching-and-reasoning))                                                                                                                                            |

<p align="center"><img src="https://media-cdn.atlassian.com/file/a712ab83-1deb-44e9-b556-525e485fd773/image/cdn?allowAnimated=true&#x26;client=7e828137-be0c-4e67-84fc-bd1b114e627a&#x26;collection=contentId-1484062744&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3ZTgyODEzNy1iZTBjLTRlNjctODRmYy1iZDFiMTE0ZTYyN2EiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0xNDg0MDYyNzQ0IjpbInJlYWQiXX0sImV4cCI6MTc5MzExMjUwOCwibmJmIjoxNzkzMTA5NjI4LCJhYUlkIjoiNzEyMDIwOjlmN2E3MTc1LWUxMmEtNDk4YS1hMzVkLWQ3MGQyMGIyM2U2MSIsImh0dHBzOi8vaWQuYXRsYXNzaWFuLmNvbS9hcHBBY2NyZWRpdGVkIjpmYWxzZSwiYXV0aFR5cGUiOiJzZXNzaW9uIn0.ViS99Mvjkf-MTadL76aCAgVn9pXmJSZ8y8S-OiPYj6M&#x26;width=470#media-blob-url=true&#x26;id=a712ab83-1deb-44e9-b556-525e485fd773&#x26;clientId=7e828137-be0c-4e67-84fc-bd1b114e627a&#x26;contextId=contentId-1484062744&#x26;collection=contentId-1484062744" alt="2026-10-21_19-15-46-20261021-171546.png"></p>

#### 4. Set the model configuration <a href="#id-4.-set-the-model-configuration" id="id-4.-set-the-model-configuration"></a>

Cline does not know the limits or prices of nexos.ai models: until you set them, it shows **Context: 128K, Input: Free, Output: Free** under the model. Expand **Model Configuration** and enter the values from the nexos.ai Models endpoint:

{% code lineNumbers="true" %}

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

{% endcode %}

| Cline field                  | Source in `/v1/models`                      | Example for Claude Sonnet 5.5 |
| ---------------------------- | ------------------------------------------- | ----------------------------- |
| **Context Window Size**      | `context_length`                            | `1000000`                     |
| **Max Output Tokens**        | up to `max_tokens`                          | `32000` (maximum `128000`)    |
| **Supports Images**          | `image` in `input_modalities`               | checked                       |
| **Input Price / 1M tokens**  | `pricing.input_cost_per_token` × 1,000,000  | `2.2`                         |
| **Output Price / 1M tokens** | `pricing.output_cost_per_token` × 1,000,000 | `11`                          |

Cline uses the context window to decide when to condense a long conversation, and the prices only for its own cost estimate. The nexos.ai usage dashboard remains the source of truth for costs. If a model has no `max_tokens` or `pricing` in the response, leave those fields empty. Leave **Temperature** empty unless you need a specific value.

When picking a model make sure that its `endpoints` include `chat_completion` and that it has `"supports_tools": true`. 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.

{% 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, start a new task in the Cline panel and send a simple request, for example *"Explain what this repository does"*. Cline asks for approval before reading files or running commands; approve the file reads. The request is visible in your nexos.ai usage dashboard, which confirms that traffic is flowing through the Gateway.

<p align="center"><img src="https://media-cdn.atlassian.com/file/8a0e515e-dc5c-47cd-8c4d-e54b99ff1dba/image/cdn?allowAnimated=true&#x26;client=7e828137-be0c-4e67-84fc-bd1b114e627a&#x26;collection=contentId-1484062744&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3ZTgyODEzNy1iZTBjLTRlNjctODRmYy1iZDFiMTE0ZTYyN2EiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0xNDg0MDYyNzQ0IjpbInJlYWQiXX0sImV4cCI6MTc5MzExMjUwOCwibmJmIjoxNzkzMTA5NjI4LCJhYUlkIjoiNzEyMDIwOjlmN2E3MTc1LWUxMmEtNDk4YS1hMzVkLWQ3MGQyMGIyM2U2MSIsImh0dHBzOi8vaWQuYXRsYXNzaWFuLmNvbS9hcHBBY2NyZWRpdGVkIjpmYWxzZSwiYXV0aFR5cGUiOiJzZXNzaW9uIn0.ViS99Mvjkf-MTadL76aCAgVn9pXmJSZ8y8S-OiPYj6M&#x26;width=682#media-blob-url=true&#x26;id=8a0e515e-dc5c-47cd-8c4d-e54b99ff1dba&#x26;clientId=7e828137-be0c-4e67-84fc-bd1b114e627a&#x26;contextId=contentId-1484062744&#x26;collection=contentId-1484062744" alt="2026-10-21_19-21-00-20261021-172100.png"></p>

Cline 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.

***

### Prompt caching and reasoning <a href="#prompt-caching-and-reasoning" id="prompt-caching-and-reasoning"></a>

* **Prompt caching** works without any setting. For Claude models the nexos.ai Gateway applies caching automatically, so the repeated part of the conversation (system prompt, tool definitions, earlier steps) is billed at the reduced cached-input price. GPT models cache automatically as well.
* **Reasoning effort with Claude models** – keep **Reasoning Effort** at **None** (the default) for Claude models used through OpenAI Compatible. With a reasoning level set, a task can stop with `Model ended without a recognized finish reason`. Reasoning effort works with GPT models.

{% hint style="info" %}
**Use OpenAI Compatible for Claude models too.** Cline's **Anthropic** provider only offers Anthropic's own model names in its model list, and the Cline CLI does not allow a custom base URL for it, so it cannot be pointed at nexos.ai models. The OpenAI Compatible provider covers all chat models in nexos.ai, including Claude.
{% endhint %}

***

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

1. Install the CLI (Node.js 20 or later):

{% code lineNumbers="true" %}

```shellscript
npm install -g cline
cline --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. Configure nexos.ai as the OpenAI Compatible provider and choose the default model:

{% code lineNumbers="true" %}

```shellscript
cline auth -p openai-compatible \
  -k "$NEXOS_API_KEY" \
  -b https://api.nexos.ai/v1 \
  -m "Claude Sonnet 5.5"
```

{% endcode %}

Cline saves the provider, including the key, in `~/.cline/data/settings/providers.json` (readable only by your user). The VS Code extension reads the same file.

4. Start Cline in your project directory, interactively or with a task:

{% code lineNumbers="true" %}

```shellscript
cline
cline "Explain what this repository does"
```

{% endcode %}

5. Optionally, switch to another nexos.ai model with `-m`. Cline keeps the model you pass as the new default for later runs:

{% code lineNumbers="true" %}

```shellscript
cline -P openai-compatible -m "GPT 5.4 mini" "Write unit tests for utils.py"
```

{% endcode %}

{% hint style="warning" %}
`cline "your task"` runs in Act mode with **auto-approve enabled by default**: Cline edits files and runs commands without asking. Use `--auto-approve false` to approve each action, or `-p` to start in Plan mode.
{% endhint %}

For Claude models, do not pass a reasoning level with `--thinking` (or pass `--thinking none`); see [Prompt caching and reasoning](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1484062744/Cline+Integration#Prompt-caching-and-reasoning).

***

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

* **Do not sign in to a Cline account** and do not select the **Cline** provider. The CLI uses the Cline provider by default until you run `cline auth` for another provider.
* **Plan and Act models** – if you enable **Use different models for Plan and Act modes**, configure both modes with the OpenAI Compatible provider and nexos.ai models.

***

### Advanced configuration <a href="#advanced-configuration" id="advanced-configuration"></a>

#### Different models for Plan and Act <a href="#different-models-for-plan-and-act" id="different-models-for-plan-and-act"></a>

Enable **Use different models for Plan and Act modes** (at the bottom of the provider settings) to plan with a strong model (e.g. `Claude Sonnet 5.5`) and implement with a cheaper, faster one (e.g. `GPT 5.4 mini`). Both use the same Base URL and API key; set the Model Configuration for each model.

#### MCP servers <a href="#mcp-servers" id="mcp-servers"></a>

MCP servers are configured independently of the model provider (Cline panel → **MCP Servers**, or `cline mcp` in the CLI). They work unchanged with the nexos.ai Gateway, as long as the selected model supports tool calling.

***

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

* **"Model Not Found"** – the model ID must be exactly as returned by `GET /v1/models` for your key, including spaces (e.g. `Claude Sonnet 5.5`). If the model is missing from the list, ask your workspace administrator to enable it.
* **Connection errors or 404 responses** – check that the Base URL is exactly `https://api.nexos.ai/v1`, including `/v1`, and that the API Provider is **OpenAI Compatible**.
* **The model list does not load** – check the API key. You can always choose **Use custom model ID…** and type the ID.
* `Model ended without a recognized finish reason` **with a Claude model** – set **Reasoning Effort** to **None** for that model.
* **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 with `"supports_tools": true`.
* **Long tasks fail with a context-length error** – set **Context Window Size** in Model Configuration (step 4).
* **Requests do not show up in the nexos.ai usage dashboard** – the **Cline** provider is selected instead of OpenAI Compatible. See [Keep all traffic on nexos.ai](https://nexos-ai.atlassian.net/wiki/spaces/NA2/pages/1484062744/Cline+Integration#Keep-all-traffic-on-nexos.ai).

For CLI logs run `cline doctor log`. Community help: [Cline Discord](https://discord.gg/cline), [GitHub Issues](https://github.com/cline/cline/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/cline-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.
