Claude CodeをOllamaのローカルLLMに接続する手順と制約

Claude CodeはANTHROPIC_BASE_URLと認証情報の変数を差し替えるだけで、Anthropic以外のエンドポイントにつながります。Ollamaはこの仕組み向けにAnthropic Messages APIのサブセットをサーバー自身に実装しており、ローカルで動かすモデルにもOllama Cloud経由のモデルにも同じ入り口でつながります。つながること自体は簡単です。実際に詰まるのは、コンテキスト長の既定値、ツール呼び出しに対応しないモデル、Claude Code側で働かなくなる機能の3か所に集まります。

ローカルLLMで使いたい人が最初に知りたい点は3つです。モデルは手元のマシンで動き、リクエストがAnthropicのAPIを通らないので、トークン課金は発生しません。ただし動かすには、ツール呼び出しに対応したモデルと、十分なコンテキスト長が要ります。クラウドモデルは手元の計算資源を使わない代わりに、サインインやプランの条件が付きます。

VS Code拡張・デスクトップアプリ・GitHub Actions・Agent SDKでは、環境変数の渡し方がCLIと異なります。面ごとの手順はClaude CodeをLLMゲートウェイに接続する方法で扱っています。社内で推論サーバーを立てる側の調整はClaude CodeでvLLMの推論サーバーを詰めるにあります。ここではOllama固有の手順と制約を、症状から逆引きできる順に並べます。

最短の接続はollama launch claudeの1コマンド

Ollamaをインストール済みなら、専用のランチャーコマンドで接続できます。Claude Codeが未導入なら、ollama launch claudeが導入を提案します。

ollama launch claude

Ollamaのドキュメントでは、この1行がClaude Code連携ページの「Get started」の最初に載っています。対話プロンプトを飛ばしてスクリプトやCI・Dockerから起動したい場合は、--yesと--modelを組み合わせます。

ollama launch claude --model gemma4:cloud --yes -- -p "このリポジトリの構成を教えて"

--yesは選択画面を省き、必要ならモデルを取得します。代わりに--modelの指定が必須になります。--以降の引数はそのままClaude Codeへ渡るので、Claude Codeの-pによる非対話実行もこの形で書けます。

Ollamaの連携ページが挙げる対応機能は、チャット・コマンド実行・ツール呼び出し・ファイル編集・サブエージェント・Web検索・Web取得・画像入力・thinkingです。ツール呼び出しとthinkingは「対応モデルのみ」の注記が付いています。つまり、同じ操作でもモデルによって結果が変わります。

ローカルで無料に動かす条件

「Ollamaで無料でClaude Codeを使えるか」は、課金の出どころと手元の資源に分けて考えます。ANTHROPIC_BASE_URLをローカルのOllamaに向けると、送信先はlocalhost:11434です。Anthropicのトークン課金は関係せず、代わりに自分のGPUやメモリーが処理を担います。

手元の資源で効くのは、コンテキスト長です。既定値はVRAMが24GiB未満だと4kで、コーディングツールの目安である64,000には届きません。VRAMが小さいマシンでは、長さを上げるとモデルがCPUへ溢れて遅くなります。詳細は後述の切り分けの節にあります。

:cloud付きのモデルやOllama Cloud直結は別枠です。サインインが要り、モデルによっては有料プランが必要になります。無料枠の範囲はOllamaのプラン側の条件なので、利用前にOllamaの料金ページで確かめてください。

環境変数を自分で設定する

ランチャーを使わない場合、ローカルサーバーとOllama Cloud直結で変数の値が変わります。違いは次の2枚に収まります。

ローカルサーバーに接続する

Ollamaを手元で動かしているなら、次の4行です。

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder

ANTHROPIC_AUTH_TOKEN=ollamaは、Ollama側の「値は必須だが無視される」という仕様に合わせたプレースホルダーです。ANTHROPIC_API_KEYを空文字にする2行目は、Ollamaのセットアップ手順にもセットで載っています。Claude Codeの認証順位ではANTHROPIC_AUTH_TOKENがキーより上です。それでも空にしておくと、別の場所で設定されたキーが混ざらず、トークンとキーの両方を検出したときの警告(Auth conflict)も避けられます。

Ollama Cloudに直結する

ollama.com/settings/keysで取得したAPIキーをOLLAMA_API_KEYに入れ、ANTHROPIC_AUTH_TOKENへ渡します。

ANTHROPIC_BASE_URL=https://ollama.com \
ANTHROPIC_AUTH_TOKEN="$OLLAMA_API_KEY" \
ANTHROPIC_API_KEY="" \
claude --model glm-5.3-flash

Ollamaの手順には「Claudeの設定ファイルがシェルの変数を上書きしうる」との注意があり、確認には/statusを使います。Claude Codeのゲートウェイ手順にも同じ確認があり、/statusのStatusタブで見るのは2行です。

環境変数を設定ファイルへ永続化する方法やCLI以外の面での置き場所は前述の記事にまとめてあります。ANTHROPIC_BASE_URLを向けた場合の共通の挙動はANTHROPIC_BASE_URLでAPIエンドポイントを切り替えるにあります。複数のプロバイダーを規則で振り分けたいなら、Claude Code Routerでモデルを別プロバイダーへ振り分ける設定と注意点も選択肢です。

認証変数と送信ヘッダーの対応は次のとおりです。ANTHROPIC_AUTH_TOKENはAuthorization: Bearerに、ANTHROPIC_API_KEYはx-api-keyに載ります。したがってクラウド直結でANTHROPIC_API_KEYにOllamaのキーを入れると、キーが正しくてもヘッダーが違うので401になります。ゲートウェイ手順にも、変数を取り違えると401になるとあります。

モデルの選び方 — ツール対応と名前の扱い

Ollamaはローカルモデルとクラウドモデルの両方をサポートします。ローカルで動かすなら、事前にモデルを取得します。

ollama pull qwen3-coder

Ollamaが推奨するローカルモデルは、コーディング向けのqwen3-coderと汎用のgpt-oss:20bの2つです。クラウドモデルはollama.com/search?c=cloudのカタログから選びます。サインイン済みのOllamaサーバーなら、gemma4:cloudのような:cloud付きの名前がそのまま使えます。クラウドに直接つなぐときは、gemma4:31bのようにホスト側の識別子を使います。ここは取り違えやすく、同じモデルでも接続経路で名前が変わります。

Claude Codeのファイル編集やコマンド実行は、ツール呼び出し(function calling)に依存します。Ollamaの連携ページも、ツール対応のクラウドモデルを選ぶよう案内しています。ツール非対応のモデルでの具体的な症状は、実機で確かめていません。後述の切り分けは、ドキュメントに書かれた範囲だけを根拠にしています。

Claude Codeのモデル名チェックについては、「is not a recognized model id」の意味と対処で扱っています。Claude Codeのモデル設定ページによれば、claude-で始まらないIDは、プロバイダーやカスタムの綴りとして扱われます。Ollamaのモデル名がまさにこれに当たります。セッション中の切り替えは/modelコマンドで、使い方はClaude Codeの/modelにまとめています。

Anthropicの既定モデル名を前提にしたツールを使うときは、ollama cpで手元のモデルに別名を付けられます。

ollama cp qwen3-coder claude-3-5-sonnet

コピー後はclaude-3-5-sonnetという名前でリクエストできます。これはOllama側のエイリアスで、Claude Codeの設定は変わりません。注意が1つあります。Claude Code側はclaude-で始まる名前を、Claudeモデルの綴りとして解釈しうる点です。別名が公式の表記と重なる場合の挙動は確かめていません。必要がなければ、qwen3-coderのように素の名前で指定するほうが読み違いを避けられます。

動くが何かおかしいときの切り分け

接続自体は成功して応答も返るのに、結果が期待と違う。この種の症状は、原因が2系統に分かれます。

コンテキスト長を上げる

最初のカードの対処は、Ollamaサーバーの起動時に長さを指定することです。

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Ollamaアプリを使っているなら、設定画面のスライダーで同じ値を変えられます。クラウドモデルは、既定で最大のコンテキスト長に設定されます。割り当て結果はollama psのCONTEXT列で確かめられます。同じコマンドのPROCESSOR列も、モデルがCPUへ溢れていないかを知る手がかりです。

Claude Code側にも同じ数字を伝える変数があります。CLAUDE_CODE_MAX_CONTEXT_TOKENSは、ゲートウェイ経由のモデルでClaude Codeが想定するコンテキストウィンドウを上書きします。Claude Codeのモデル設定ページによれば、claude-で始まらない未知のIDなら、この変数がそのまま効きます。想定した窓の大きさで、自動圧縮(コンパクション)の時機も決まります。

つまりOllama側とClaude Code側の2か所で、同じ値を揃える運用になります。

OLLAMA_CONTEXT_LENGTH=64000 ollama serve
# 別の端末で
CLAUDE_CODE_MAX_CONTEXT_TOKENS=64000 claude --model qwen3-coder

なお、IDに[1m]を含めた場合やclaude-始まりの名前では、この変数の効き方が変わります。詳細はモデル設定ページにあります。2つの数字が食い違うと、Ollama側の窓を超えた入力が送られうる、というのが筆者の読みです。実機では確かめていません。

認証変数が競合したとき

クラウド直結のコマンドはANTHROPIC_API_KEY=""を含みます。理由は、トークンとキーの二重設定を避けるためです。

キーだけで接続する場合は、事情が変わります。ANTHROPIC_API_KEYは、サブスクリプションのログインより優先されます。インタラクティブモードでは初回に承認を求められ、-pの非対話モードでは設定されていれば常にそのキーが使われます。ANTHROPIC_AUTH_TOKENは即座に優先されます。

ollama launchが設定する変数はドキュメントに書かれていません。非対話で使う前に、/statusで認証元を確かめます。

ゲートウェイ経由で働かなくなるClaude Codeの機能

Ollamaの制約は、サーバー側だけではありません。Claude Codeのゲートウェイ手順には、非Anthropicのエンドポイントを向けたときに変わるClaude Code側の挙動が載っています。Ollamaに限った話ではありませんが、ローカルLLMで試す人が踏みやすい点です。

• Remote Controlと音声入力: どちらもclaude.aiの身元に依存します。ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN・apiKeyHelperのどれかが有効な間は使えません。Remote Controlは、ANTHROPIC_BASE_URLが非Anthropicのホストを向いているときも無効になります(v2.1.196以降。それ以前は無効になりませんでした)
• /fast: 可用性の確認にはclaude.aiのログインかAnthropicのAPIキーが要ります。ベアラートークンだけのセッションでは確認を送らずに無効と扱われ、「組織で無効」(Fast mode has been disabled by your organization)と表示されます。CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1で確認を飛ばせますが、Ollama経由でfast modeが意味を持つかは別問題です
• Claude Code on the webとSlack連携: 常にAnthropicのAPIを使うので、ゲートウェイ系の環境変数は適用されません。Ollamaにつなげられるのは、手元で動かすCLIなどの面に限られます

CLIは設定ファイルや環境変数を読みますが、デスクトップアプリは別の設定(third-party inference configuration)を読みます。したがって、CLIで動いたからデスクトップアプリも動く、という期待はできません。

Ollama特有の制約 — 何が動いて何が動かないか

Ollamaの/v1/messagesは、Anthropic Messages APIの全体ではなくサブセットです。Ollamaの「Not supported」と「Partial support」の表を、Claude Codeでの影響とあわせて並べます。

この表には、Ollamaのページ内の食い違いが1か所あります。同じ「Anthropic compatibility」ページで、ストリーミングイベントの対応一覧にはerrorにチェックが付いています。一方で「Not supported」の表には、ストリーム中のerrorイベント(Server-sent errors)が載っています。どちらが現状かはページからは決められないので、ストリーム途中のエラーに頼る実装は、自分の環境で確かめるのが安全です。

ほかにも差があります。ローカルサーバーはAPIキーを検証しません。ホスト側のエンドポイントは、anthropic-versionが2023-06-01より古いと拒否します。トークン数は、基盤モデルのトークナイザーに基づく概算です。

手元のclaudeが受け付ける指定

この記事の執筆に使ったのは、v2.1.287です。Ollamaはインストールしていないので、接続自体の実機確認はしていません。確認したのは、claudeのヘルプに出る、接続まわりのオプション表記までです。

$ claude --version
2.1.287 (Claude Code)
 
$ claude --help
  --model <model>     Model for the current session. Provide an alias for the
                      latest model (e.g. 'fable', 'opus', or 'sonnet') or a
                      model's full name.
  --settings <file-or-json>
                      Path to a settings JSON file or a JSON string to load
                      additional settings from
  --bare              Minimal mode: ... Anthropic auth is strictly
                      ANTHROPIC_API_KEY or apiKeyHelper via --settings (OAuth
                      and keychain are never read). ...

2つの読み取りがあります。1つ目は--modelの説明です。例に挙がるのはエイリアスで、フルネームも渡せるとあり、qwen3-coderのような名前は後者の経路で渡されます。2つ目は--bareです。ヘルプ上、このモードのAnthropic認証はANTHROPIC_API_KEYかapiKeyHelperに限られます。ANTHROPIC_AUTH_TOKENは挙げられていません。--bareでOllamaにつなぎたいときは、ANTHROPIC_API_KEY=ollamaのように、キー側の変数で渡す形になる可能性があります。ローカルサーバーはキーを検証しないので、値は何でも通るはずですが、これはヘルプの文面からの推論で、実機では試していません。

--settingsを使えば、環境変数の組をJSONのenvブロックにまとめて、起動のたびに指定できます。Claude Codeのゲートウェイ手順にある設定ファイルの書式と同じです。

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_API_KEY": ""
  }
}

プロジェクトの.claude/settings.jsonに置いたenvは、対話セッションでは初回のセットアップと信頼確認のあとで適用されます。ログイン画面が先に出てしまうときは、シェルのexportか~/.claude/settings.jsonのほうが確実です。

Claude DesktopをOllamaのモデルで動かす別ルート

Ollamaには、Claude Desktopのモデルを差し替える経路もあります。OllamaアプリのApps画面でClaudeを接続し、Ollamaの設定から使うモデルを選ぶ流れです。対象はmacOSで、Windows対応は「近日対応予定」とされています。ローカルモデルは事前の取得が要り、クラウドモデルは、Ollamaにサインインしてクラウドモデルを有効にします。一部のモデルは有料プランが必要です。

元に戻す操作は、Appsの画面から切断するか、ターミナルでollama launch claude-desktop --restoreです。Ollamaを終了しても、接続中のClaudeは元の設定に戻ります。これはANTHROPIC_BASE_URLでClaude Codeに接続する仕組みとは別の経路です。Claude.aiのWeb版・Claude Desktop・Claude Codeで接続手段が違う点は、混同しやすいところです。

判断のまとめ

接続より先に揃えておきたいのは2か所です。選ぶモデルがツール呼び出しに対応しているかと、コンテキスト長をOllama側とClaude Code側の両方で合わせているかです。tool_choiceやキャッシュが使えないといった差はドキュメントに既知の制限として書かれているので、期待どおりに動かない機能があっても、まずそこを見ます。