Manage LLM Providers

Pinchy is model-agnostic. You bring the API key (or local URL) for whichever LLM provider you trust, and every agent picks a model from the providers you've enabled. This guide covers what to do after the initial setup wizard — adding more providers, switching models, removing keys.

For the very first provider during the setup wizard, see Installation. For the air-gapped local Ollama setup, see the dedicated Ollama (Local) guide.

Supported providers

Provider	Auth	What you get
Anthropic	API key	Claude family — strongest tool calling and reasoning
OpenAI	API key	GPT-5 family, o-series reasoning models
Google	API key	Gemini family — long context, fast and cheap
Ollama Cloud	API key	Hosted open-source models (Kimi, Qwen, Mistral, Gemini Flash) via ollama.com
Ollama (Local)	URL	Fully air-gapped local inference — see Ollama setup
OpenAI-compatible	URL + API key	Any endpoint that speaks the OpenAI API — sovereign EU clouds, self-hosted gateways. See below

You can have any combination of providers configured at the same time. Each agent picks one model from one provider.

Add a provider

Note

Only admins can configure providers.

Settings → AI Provider shows a single grid: a tile for each of the 5 built-in providers, one tile per OpenAI-compatible provider you've already added, and a dashed Add custom provider tile. Selecting any tile opens its panel below the grid.

1. Go to Settings → AI Provider
2. Click the provider you want to add
3. Paste your API key (or for local Ollama, enter the URL)
4. Click Save

Pinchy validates the credentials immediately by making a test call to the provider's /models endpoint. If the key works, the provider activates and its models become available in every agent's model dropdown within a few seconds.

API keys are encrypted at rest with AES-256-GCM. They never appear in logs, audit events, or error messages.

Change an agent's model

Each agent uses one model at a time. To change it:

1. Open the agent's chat
2. Click the gear icon next to the agent name → General
3. Pick a new model from the Model dropdown
4. Click Save

The dropdown shows every model from every configured provider. Models are grouped by provider, so you can quickly compare options.

Caution

Pinchy agents require models with tool calling support. Models without it appear disabled in the dropdown with the reason shown inline. If a provider has no compatible models, you can't select that provider for an agent at all.

Switch the default provider

The "default provider" is the one Pinchy reaches for when creating new agents. In the grid, the default tile carries a star in its top-right corner; every other configured tile — built-in or custom — carries a small check. The grid lists the default first, then the other configured providers, then the rest.

The very first provider you configure — built-in or custom — automatically becomes the default. After that, adding more providers never changes the default: you switch it explicitly. To switch the default, click the tile you want, then click Set as default in its panel (shown whenever that provider is configured and isn't already the default). Existing agents keep their current model — only newly created agents pick up the new default.

Remove a provider

1. Go to Settings → AI Provider
2. Click the provider's tile in the grid
3. Click Remove key / Remove URL (built-in) or Remove provider (custom), and confirm

Agents pinned to a model from the removed provider are moved to a still-configured one, so no agent is left on a model that no longer exists. If you removed your default provider, the provider those agents moved to becomes the new default.

Pinchy refuses to remove the last configured provider — add another one first. That is what keeps the sentence above true: there is always somewhere for an orphaned agent to go.

The move is a starting point, not a verdict: pick a different model for any agent afterwards — see Change an agent's model.

OpenAI-compatible providers

Beyond the built-in providers, Pinchy can connect to any endpoint that speaks the OpenAI API. If a service exposes the familiar /v1/chat/completions and /v1/models routes with Bearer-token auth, you can wire it in — no code changes, no waiting for us to add it as a first-class provider.

This is the option to reach for when you want to run agents on:

• Sovereign EU model clouds — Swisscom AI Platform, IONOS AI Model Hub, OVHcloud AI Endpoints, Scaleway, T-Systems, and similar, so data stays with a provider under your jurisdiction.
• Your own inference servers — a self-hosted vLLM or TGI deployment serving open-weight models on your hardware.
• LLM gateways — a LiteLLM (or similar) proxy that fronts several upstream models behind one OpenAI-style endpoint.

Unlike the built-in providers, you can add as many OpenAI-compatible endpoints as you like and manage them side by side.

Add an OpenAI-compatible provider

Note

Only admins can configure providers.

You can add one during the initial setup wizard — it's offered as a Custom provider action below the built-in provider tiles — or any time afterwards from Settings → AI Provider. The fields are the same in both places:

1. Open Settings → AI Provider and click the dashed Add custom provider tile in the grid (in the wizard, click Custom provider). Every custom provider you've already added shows as its own tile in the same grid — click one to edit it.
2. Name — a label you choose, shown wherever the provider's models appear (e.g. "Swisscom AI Platform").
3. Base URL — the endpoint's base, entered exactly as the provider documents it, including the /v1 path (e.g. https://api.example.com/v1). Pinchy appends the standard routes to this base, so don't trim the version segment.
4. API key — your key for the endpoint.
5. Click Add provider.

That's it — there's no separate discover-and-select step. This works just like the built-in providers: you supply the credentials, and Pinchy takes it from there. Once added, the provider's tile carries the same Set as default and remove affordances as a built-in provider — see Switch the default provider and Remove a provider above.

How models are detected

When you save, Pinchy calls GET <base URL>/models and offers every chat model the endpoint serves — no manual selection. The list is fetched live (briefly cached), so a model you add on the provider's side later shows up on its own, and models are picked per agent from the usual model dropdown, exactly like every other provider. Non-chat models (embeddings, rerankers, transcription, and the like) are filtered out automatically. Capabilities — context window, vision, and more — come from Pinchy's bundled model catalog, with safe defaults for models it doesn't recognise (see Where capabilities come from).

Some endpoints — a bare vLLM server, say — don't publish a /models list. When Pinchy finds none, it asks you to enter the model ids by hand (comma-separated); everything else is unchanged.

Tip

Editing a provider later? For security, Pinchy never shows a saved key. Leave the API key blank to keep the current one, or re-enter it to rotate it.

Which base URLs are allowed

Because Pinchy connects to the base URL from the server, it guards against being pointed at somewhere it shouldn't reach:

• Public endpoints (sovereign clouds, hosted gateways) and private-network endpoints (a self-hosted vLLM/TGI box on your LAN, e.g. http://10.0.0.5:8000/v1) both work out of the box.
• Reserved and internal addresses are refused — loopback, cloud-metadata/link-local (169.254.x.x), multicast, and non-http(s) URLs. These are never a real model endpoint, and blocking them protects the host Pinchy runs on.

If you operate Pinchy as a managed/multi-tenant host (where the person configuring a provider isn't the owner of the underlying network), set PINCHY_PROVIDER_BLOCK_PRIVATE_NETWORKS=1 to also refuse private-network addresses. Self-hosted deployments leave it unset so LAN endpoints keep working.

Note

Editing a provider and removing a model that agents were already using? Pinchy moves those agents onto another of the same provider's models automatically, so none are left pointing at a model that no longer exists.

Where capabilities come from

Pinchy resolves each model's capabilities — context window, vision, and more — from a catalog snapshot bundled with the app. A model the catalog recognises arrives with sensible values already filled in; anything unknown falls back to conservative defaults (a modest context window and no vision).

The catalog refreshes with every Pinchy release, so upgrading is how you pick up metadata for newer models. See Upgrading to stay current.

One capability is deliberately bounded: agents run on at most 256K tokens of context, even where a model advertises more. That's what keeps automatic summarization firing on very-long-window models instead of letting a conversation grow until every turn is slow and expensive. Models at or below 256K are unaffected, and the model's real context window is still what the catalog says. See Session lifecycle and compaction for the full picture.

Your keys stay yours

Every OpenAI-compatible key is encrypted at rest and handled exactly like every other provider secret: it's never written into the OpenClaw configuration in plaintext — only an encrypted reference is — and it never appears in logs, audit events, or error messages. See Secret handling for the full picture.

Model capability catalog

Pinchy maintains a models table that tracks which capabilities each model supports — vision, long context, and tool calling. The table is seeded automatically at every boot from Pinchy's built-in catalog for Anthropic, OpenAI, Google, and Ollama Cloud. You don't need to configure anything.

For local Ollama, capabilities depend on which model you've pulled. Pinchy reads this from the Ollama API when you save the URL during setup or settings, and updates the catalog accordingly.

Capability data drives two things in practice:

1. Template model selection — when you create an agent from a template, Pinchy picks the first model from your configured providers that meets the template's required capabilities (e.g. vision for a document-analyzer). If no model qualifies, you see a warning.
2. Pre-send checks — if you attach an image and the agent's current model doesn't support vision, Pinchy warns you before sending and shows you how to switch to a capable model. PDFs are never blocked: they are analyzed by a dedicated PDF tool whose model Pinchy picks from your configured providers, independent of the agent's chat model (see Upload Files in Chat).

Admins can inspect raw capability data by querying the models table directly:

SELECT provider, model_id, vision, long_context, tools
FROM models
ORDER BY provider, model_id;

A future admin UI will surface this without needing database access.

How costs are tracked

Tokens used through every provider are recorded in the Usage Dashboard at /usage. Cost is estimated using the per-model prices baked into Pinchy's model config — provider invoices remain the source of truth. Local Ollama records token counts but always shows zero cost.

Troubleshooting

When a provider returns an error, Pinchy shows it directly in the chat as a distinct error card with the agent name and the provider's error message. Admins see a hint pointing to Settings → AI Provider; non-admin users see a prompt to contact their administrator. Transient errors (rate limits, timeouts) suggest trying again.

Model-unavailable errors

When the provider returns a server error (HTTP 5xx) that Pinchy recognises as a model availability problem — for example, the model has been discontinued or is temporarily offline — the chat shows a structured model-unavailable bubble instead of a raw error message. The bubble includes:

• The agent name and the model identifier that failed
• A short plain-English explanation of what happened
• A collapsible section with the raw technical details if you need them for support
• A Switch model → link that takes you directly to the agent's model settings so you can pick a replacement in one click

This avoids having to hunt through menus when a model goes down.

Removed model: ollama-cloud/kimi-k2-thinking

ollama-cloud/kimi-k2-thinking has been removed from Pinchy's supported model list. Agents that used this model will show the model-unavailable bubble the next time they receive a message. To resolve it:

1. Click Switch model → in the error bubble, or open the agent's settings manually (gear icon → General → Model).
2. Select a replacement — ollama-cloud/deepseek-v4-pro is a good like-for-like option for reasoning-heavy workloads.
3. Click Save. The agent is ready immediately.

"Invalid API key" — Double-check the key with the provider's own dashboard. Anthropic keys start with sk-ant-, OpenAI keys with sk-, Google keys are typically AIza....

"Your credit balance is too low" — The provider account has run out of credits. Top up on the provider's billing page.

"Rate limit exceeded" — Too many requests in a short window. Wait a moment and try again. If this happens often, check your plan's rate limits on the provider's dashboard.

"Could not reach the provider" — Network problem between your Pinchy instance and the provider. If you're running behind a strict firewall, allowlist the provider's API hostname.

"No compatible models found" — The provider responded but none of its models support tool calling. For Ollama-local, pull a tool-capable model like qwen3.5:9b. For cloud providers, this should not happen — file an issue if it does.

The model dropdown is empty after adding a key — Pinchy caches the model list for one hour for cloud providers. Try waiting a minute, or remove and re-add the provider to force a refresh. Local Ollama is always fetched live.

Ollama Cloud returns HTTP 500: "Internal Server Error (ref: …)" on every retry — Ollama Cloud occasionally retires a model from its serving fleet without surfacing a model_not_found error or a deprecation header. The model can still appear on ollama.com/library/<model> and pull fine for self-hosted Ollama, but the hosted ollama.com/v1 endpoint no longer routes to it, so every request to that one model ends in a generic upstream 500 with a fresh reference ID. We first saw this with kimi-k2-thinking on 2026-05-08; consecutive retries each produced different upstream reference IDs, all 500. If retries fail consistently and other Ollama Cloud models on the same key still work, treat the failing model as unavailable and switch the agent to another Ollama Cloud model (for example Kimi K2.5, Kimi K2.6, or DeepSeek V4). If every Ollama Cloud model fails, the issue is transient — wait a moment and retry.