Can You Use Ollama With Claude Code?

Can You Use Ollama With Claude Code?

Yes, and the interesting part is that the two companies involved disagree about whether you should.

Ollama documents the integration enthusiastically, with a dedicated Claude Code page and a one-command launcher. Anthropic has never mentioned Ollama in any Claude Code documentation or in its changelog, and publishes a sentence stating it does not support routing Claude Code to non-Claude models at all.

Both statements are true at once, and the gap between them is what you need to understand before relying on this setup.

Can You Use Ollama With Claude Code?

Yes. Ollama version 0.14.0 and later expose an Anthropic-compatible API, so pointing Claude Code at a local Ollama server with two environment variables makes it run against a local or open-weight model instead of Claude.

Ollama's own v0.14.0 release notes list the feature as "Anthropic API compatibility: support for the /v1/messages API". That release landed in January 2026, and Ollama published a blog post about Claude Code support days later.

The mechanism is Claude Code's ANTHROPIC_BASE_URL variable, which Anthropic documents fully. What Anthropic does not do is bless this use of it.

Free SEO + AI Search Audit. Find out whether your site is visible in Google and in AI search engines like ChatGPT, Claude and Perplexity. Run your free audit in 60 seconds.

What Does Anthropic Actually Publish?

Anthropic documents the plumbing in detail and declines the use case explicitly.

The variable is documented, as a gateway feature

Anthropic's environment variable reference describes ANTHROPIC_BASE_URL as a way to "Override the API endpoint to route requests through a proxy or gateway." Note the framing. Not a local model, not an alternative model, not an Anthropic-compatible server — a proxy or gateway.

Every variable Ollama's instructions use is documented by Anthropic: ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_MODEL and ANTHROPIC_CUSTOM_HEADERS. Anthropic's gateway page even prints the same two-line shape Ollama does.

The whole concept is framed as organizational infrastructure, though — credentials, usage tracking, cost controls, audit logging. As the gateway overview puts it: "The gateway decides where requests go, not which model the developer selects."

The declination, in Anthropic's own words

Anthropic states the limit outright, in materially identical wording on two separate documentation pages: "Anthropic doesn't endorse, maintain, or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway."

That is not silence or an oversight. It is a published position, and it appears twice.

The absence is total

The word "Ollama" appears zero times across Anthropic's gateway documentation, its gateway protocol reference, its model configuration page, its settings page, its enterprise deployment overview, its Bedrock and Google Cloud pages, and its legal and compliance page. It also appears zero times in the entire Claude Code changelog, a file of roughly 1.19 MB.

The only third-party model providers Anthropic names anywhere are Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry. All four serve Claude models. There is no local, on-device or bring-your-own-model option in Anthropic's documentation.

And yet Anthropic ships code for this case

Here is the genuine contradiction. While declining to support non-Claude models, Anthropic has shipped behaviour specifically for them.

Claude Code v2.1.251 "Changed the default commit trailer to Co-Authored-By: Claude Code when the active model isn't a recognized Claude model (e.g. third-party models behind a custom ANTHROPIC_BASE_URL)". Version 2.1.268 "Fixed every turn failing with HTTP 400 on third-party Anthropic-compatible endpoints (ANTHROPIC_BASE_URL) since 2.1.265". Version 2.1.304 turned tool search on by default behind a custom base URL.

So the honest reading is this: unsupported does not mean blocked, abandoned or deprecated. Anthropic maintains the path while refusing to put its name on it.

How Do You Connect Claude Code to Ollama?

The one-command route

Ollama now ships its own launcher. Running ollama launch claude sets up the connection without you touching environment variables.

The manual local route

If you would rather see what is happening, three exports do it:

• export ANTHROPIC_AUTH_TOKEN=ollama
• export ANTHROPIC_API_KEY=""
• export ANTHROPIC_BASE_URL=http://localhost:11434

Then start Claude Code with an explicit model, such as claude --model qwen3.5.

Why the empty API key matters

That middle line is easy to skip and it is the most common reason this fails. Anthropic's documentation explains why: ANTHROPIC_API_KEY is "API key sent as X-Api-Key header. When set, this key is used instead of your Claude Pro, Max, Team, or Enterprise subscription even if you are logged in."

A saved Anthropic key will quietly override your gateway. Blanking it stops that.

Pointing at Ollama's cloud instead

Ollama also runs a hosted endpoint, using ANTHROPIC_BASE_URL=https://ollama.com with your Ollama key in ANTHROPIC_AUTH_TOKEN. That endpoint needs a bearer token and will not accept an x-api-key alone; a local server does not validate keys at all, so any placeholder works.

Getting the model to appear in the picker

Your Ollama model will probably not show up when you run /model, and Anthropic's protocol reference explains exactly why: "Claude Code keeps an entry when its id contains claude or anthropic anywhere in the string, matched case-insensitively, and ignores the rest."

A model called qwen3.5 contains neither, so it is filtered out. That is why Ollama suggests ollama cp to copy a model under a Claude-shaped name. The cleaner fix is ANTHROPIC_CUSTOM_MODEL_OPTION, since "Claude Code skips validation for the model ID set in ANTHROPIC_CUSTOM_MODEL_OPTION, so you can use any string your API endpoint accepts."

Is your site visible in AI answers? Developers increasingly find tools through AI assistants rather than search results. A free SEO + AI search audit shows where you appear in both. Check your visibility.

Which Claude Code Features Stop Working?

Anthropic has never published a single list of what degrades when you leave its API. Assembled from its own scattered documentation, here is what you lose.

Features that switch off entirely

Remote Control and voice dictation both depend on a claude.ai identity. Anthropic's documentation states they "are unavailable while ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or an apiKeyHelper is active" and adds that "Remote Control is also disabled while ANTHROPIC_BASE_URL points at a non-Anthropic host, so signing in with claude.ai isn't enough on its own."

Fast mode breaks in a way that looks like a network fault: /fast reports "Fast mode unavailable due to network connectivity issues" while inference requests work fine, because its availability check "goes directly to api.anthropic.com and doesn't follow ANTHROPIC_BASE_URL".

MCP tool search is also disabled by default against a non-first-party host, recoverable by setting ENABLE_TOOL_SEARCH=true if your endpoint forwards tool_reference blocks. And Claude Code in Slack and cloud sessions are not part of a gateway deployment at all.

Features that degrade silently

These are worse, because nothing tells you.

Prompt caching stops working with "No error: the conversation bills as uncached input on every turn, visible as high input_tokens with little or no cache activity in usage". Ollama lists prompt caching among the things it does not support, so this is the behaviour you will actually get.

Token counting falls back: Anthropic notes that "Token-counting endpoints are the only optional ones: when they're absent, Claude Code falls back to counting context usage through the inference endpoint instead."

The context window is guessed. Anthropic's model configuration page warns that an unrecognised model ID means Claude Code "can't tell the model's context window and assumes 200K tokens", printing a warning to that effect. Set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the real figure, or proactive compaction will fire at the wrong point.

One oddity worth knowing: Claude Code "prepends a short attribution block to the system prompt containing the client version and a fingerprint derived from the conversation", and while api.anthropic.com strips that block, "Any other upstream receives it as part of the prompt." Your local model reads it. CLAUDE_CODE_ATTRIBUTION_HEADER=0 removes it.

What happens to your subscription

If you set a gateway credential, your Claude subscription is simply not used. Anthropic is clear that "the credential replaces the subscription login for that session, and the subscription's usage limits don't apply."

The reverse trap is worth noting too: setting only ANTHROPIC_BASE_URL without a credential "doesn't replace the subscription. Requests still route through the gateway, but a saved claude.ai login remains the active credential, so its usage limits and billing apply."

What Does Ollama Not Support?

Ollama is candid here, describing its implementation as a subset of the Anthropic Messages API rather than a complete one. The /v1/messages endpoint is supported; /v1/messages/count_tokens and /v1/messages/batches are not.

Also unsupported: tool_choice, metadata, prompt caching, the Batches API, citations, PDF documents, and error events during streaming. URL-based images do not work, and budget_tokens is accepted but not enforced. Token counts are approximations from the model's tokenizer.

Two further practical constraints. The model needs tool-calling support, because Claude Code is a tool-driven agent — Ollama tells you to choose a model that supports tools. And context length matters: Ollama's January blog post suggested at least 32K tokens, while its newer Claude Code documentation recommends 64k or higher for larger repositories.

Anthropic's protocol reference adds two requirements your endpoint must meet. Streaming must not be buffered, since "Claude Code reads the stream as it arrives, so if your gateway buffers complete responses before relaying them, Claude Code stalls." And the stream must stay alive: Claude Code "aborts a stream that goes silent for 300 seconds by default."

See where you rank in AI search. Documentation gaps are an opportunity. A free SEO + AI search audit shows which of your pages get cited by AI assistants. Start your free audit.

When Is This Worth Doing?

It is worth doing when the reason is privacy or cost rather than capability. Code that cannot leave your machine, an air-gapped environment, or an expensive experiment you would rather not meter are all good reasons.

It is not worth doing if you expect Claude Code to feel the same. You are removing prompt caching, accurate token accounting, Remote Control, voice dictation, fast mode and tool search, and asking a smaller model to drive an agent loop designed around a larger one. Multi-step autonomous work is where the difference shows most.

The pragmatic answer for most people is both: Claude Code against Anthropic for real work, and against Ollama for the subset of tasks where local execution is the actual requirement.

Is It Actually Allowed?

Anthropic's legal and compliance documentation contains no clause prohibiting, restricting or even mentioning the use of Claude Code against a non-Anthropic model. It does require that "The Claude Code binary must not be modified" and must be "installed and run as published by Anthropic", which pointing an environment variable at a different endpoint does not violate.

There is an enumerated list of credential types — an Anthropic API key, subscription credentials, or a Bedrock, Agent Platform or Foundry credential — but it governs customers redistributing or preinstalling Claude Code inside their own products, not an individual developer configuring their own CLI.

So the accurate statement is that this is neither permitted nor forbidden. It is unaddressed. Anyone telling you Anthropic's terms ban it is reading a redistribution clause out of context.

Free SEO + AI Search Audit. Before your next content push, see how your site performs in traditional search and in AI assistants. Get your free audit in under a minute.

Final Thoughts

You can run Claude Code against Ollama, and the setup is genuinely two environment variables plus an empty third. Ollama documents it properly and even ships a launcher for it.

Just hold both facts at once. Ollama supports this; Anthropic explicitly does not, while quietly maintaining the code path anyway. That means no support channel when it breaks, a documented subset rather than the full API, and a handful of features that switch off or degrade without telling you.

If you are weighing this against paying for the real thing, the subscription mechanics are worth understanding first — our guide to Claude Code usage limits covers what Anthropic does and does not publish about its own metering.

Use it for the tasks where local matters. Do not expect it to replace the thing it is imitating.