Claude CodeをOllamaのローカルLLMに接続する手順と制約
Claude CodeはANTHROPIC_BASE_URL経由でOllamaに接続できます。ollama launch claudeでの最短接続と、tool_choice非対応などOllama特有の制約をまとめます。
Claude CodeはANTHROPIC_BASE_URLと認証情報の変数を差し替えるだけで、Anthropic以外のエンドポイントにつながります。Ollamaはこの仕組み向けにAnthropic Messages APIのサブセットをサーバー自身に実装しており、ローカルで動かすモデルにもOllama Cloud経由のモデルにも同じ入り口でつながります。ただしtool_choiceやプロンプトキャッシュ、Batches APIなど非対応の機能があり、コンテキスト長の既定値もモデルによっては数千トークンしかありません。CLI以外の面(VS Code拡張・デスクトップアプリ・GitHub Actions・Agent SDK)へ環境変数を渡す一般的な手順はClaude CodeをLLMゲートウェイに接続する方法で扱っているので、ここではOllama固有の手順と制約だけに絞ります。
Claude CodeとOllamaを最短でつなぐ
Ollamaをインストール済みなら、専用のランチャーコマンド1つで接続できます。
ollama launch claudeClaude Codeが未インストールならOllama側が導入を提案し、モデル選択のプロンプトが続きます。選んだモデルに応じてANTHROPIC_BASE_URLなどの環境変数はOllamaが自動で設定するため、次の章の手動設定は不要です。対話プロンプトを飛ばしてスクリプトやCI・Dockerから起動したい場合は--yesと--modelを組み合わせます。
ollama launch claude --model gemma4:cloud --yes -- -p "このリポジトリの構成を教えて"--yesはモデル選択などの確認を省略するフラグで、--modelの指定を必須にします。--以降の引数はそのままClaude Codeへ渡ります。
この経路で使える機能はOllama側が公式に一覧化しており、チャット・コマンド実行・ツール呼び出し・ファイル編集・サブエージェント・Web検索・Web取得・画像入力・thinkingが並びます。ただしツール呼び出しとthinkingは「対応モデルのみ」という注記付きで、すべてのモデルが同じ挙動をするわけではありません。
環境変数を手動で設定する
ランチャーを使わず自分で設定する場合、ローカルサーバーとOllama Cloud直結では変数の値が変わります。
ローカルサーバーに接続する
Ollamaをローカルで動かしている場合、認証は検証されないためAPIキーは実質どんな文字列でも構いません。
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coderANTHROPIC_AUTH_TOKEN=ollamaは「値は必須だが中身は無視される」というOllama側の仕様に合わせたプレースホルダーです。ANTHROPIC_API_KEYを空文字で明示するのは、保存済みのAPIキーが優先されて意図しない認証経路を使ってしまうのを防ぐためで、Ollama公式のセットアップ手順もこの2行をセットで案内しています。
Ollama Cloudに直結する
Ollamaをインストールせず、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クラウド直結では認証が実際に検証されます。Authorization: Bearerヘッダーでのbearer認証が必須で、x-api-key単体では通りません。ローカルサーバーとの違いはここだけ押さえておけば十分です。
環境変数を設定ファイルへ永続化する方法やCLI以外の面での置き場所は前述の記事にまとめてあり、ANTHROPIC_BASE_URLを向けた場合の共通の挙動はANTHROPIC_BASE_URLでAPIエンドポイントを切り替えるで扱っています。ここでの手順は変数の値がOllama向けになっている点だけが違います。
モデルを選ぶ — ツール対応とデフォルト名のマッピング
Ollamaはローカルモデルとクラウドモデルの両方をサポートします。ローカルで動かすなら、事前にモデルを取得します。
ollama pull qwen3-coderOllama公式が推奨するローカルモデルはqwen3-coder(コーディング用途向け)とgpt-oss:20b(汎用)の2つです。クラウドモデルはollama.com/search?c=cloudのカタログから選び、Ollamaサーバーにサインインしていればgemma4:cloudのような:cloudサフィックス付き名称でそのまま使えます。
Claude Codeのファイル編集やコマンド実行はツール呼び出し(function calling)に依存するため、選ぶモデルがツール呼び出しに対応しているかを先に確認します。Ollama側もClaude Code連携の案内で「ツールに対応したクラウドモデルを選ぶ」ことを明示しており、対応していないモデルを選ぶとチャットやファイル閲覧はできてもツール呼び出しを伴う操作だけが失敗します。
is not a recognized model idエラーはAnthropic API直結時のローカルチェックで、ANTHROPIC_BASE_URLをOllama向けに設定している間はこのチェック自体が働きません。Claude Codeは任意の文字列をそのままモデル名として渡すため、Ollama側にそのモデルが存在しない場合はOllama側のエラーとして返ります(詳細は「is not a recognized model id」の意味と対処を参照)。セッション中にモデルを切り替えたい場合は/modelコマンドが使え、使い方はClaude Codeの/modelにまとめています。
claude-3-5-sonnetのようなAnthropicのデフォルトモデル名を前提にしたツールを使う場合は、ollama cpで手元のモデルに別名を付けられます。
ollama cp qwen3-coder claude-3-5-sonnetコピー後はclaude-3-5-sonnetという名前でそのままリクエストできます。Claude Code自体はモデル名をOllamaにそのまま渡すだけなので、この操作はOllama側でのエイリアス作成であり、Claude Codeの設定は変わりません。
Ollama特有の制約 — 何が動いて何が動かないか
Ollamaの/v1/messagesはAnthropic Messages APIの全体ではなくサブセットです。Ollama公式が「サポートしない機能」「部分対応の機能」として明示している項目と、Claude Codeでの影響は次の表のとおりです。
| 機能 | 状態 | Claude Codeでの影響 |
|---|---|---|
tool_choice | 状態非対応 | Claude Codeでの影響特定ツールの強制利用や無効化はできない |
metadata(user_id等) | 状態非対応 | Claude Codeでの影響リクエストへのメタデータ付与はできない |
プロンプトキャッシュ(cache_control) | 状態非対応 | Claude Codeでの影響繰り返し送るシステムプロンプトも毎回フルコストになる |
| Batches API | 状態非対応 | Claude Codeでの影響非同期の一括処理は使えない |
| Citations | 状態非対応 | Claude Codeでの影響引用ブロックは返らない |
PDF(documentブロック) | 状態非対応 | Claude Codeでの影響PDFを直接渡す操作は失敗する |
| ストリーミング中のエラーイベント | 状態非対応 | Claude Codeでの影響エラーはHTTPステータスで返り、ストリーム途中のerrorイベントにはならない |
| 画像入力 | 状態部分対応 | Claude Codeでの影響base64画像は使えるが、URL指定の画像は使えない |
| 拡張思考(thinking) | 状態部分対応 | Claude Codeでの影響budget_tokensは受理されるが強制はされない |
/v1/messages/count_tokens | 状態非対応 | Claude Codeでの影響トークン数は基盤モデルのトークナイザーに基づく概算値になる |
これに加えて、ローカルサーバーはAPIキーを検証しない、クラウド直結はanthropic-versionが2023-06-01以降でないと拒否される、という挙動差もOllama公式が明記しています。
よくあるつまずき
コンテキストが足りずリポジトリの内容を読み切れない
Ollamaはモデルのコンテキスト長をVRAM容量に応じて既定値で決めており、VRAMが24GiB未満のマシンでは既定で4kトークンしか割り当てません。Claude Codeのようにリポジトリ全体を読み込むコーディングツールは、公式ドキュメントも最低64,000トークンを推奨しています。既定値のままだと大きめのファイルを開いた時点でコンテキストが溢れ、応答が不自然に途切れる形で症状が出ます。
OLLAMA_CONTEXT_LENGTH=64000 ollama serve実際に割り当てられているコンテキスト長はollama psのCONTEXT列で確認できます。Claude Code側がモデルのコンテキストサイズをどう認識しているかを個別に上書きしたい場合は、CLAUDE_CODE_MAX_CONTEXT_TOKENSという変数もあります。
ツール呼び出し非対応のモデルで操作が止まる
チャット自体は正常に動くのに、ファイル編集やコマンド実行だけが反応しないときは、選んだモデルがツール呼び出しに対応していない可能性が高いです。前章の「ツール対応」を確認済みのモデルに切り替えます。
ANTHROPIC_API_KEYを空にし忘れる
ANTHROPIC_AUTH_TOKENを設定していても、以前保存したANTHROPIC_API_KEYが環境に残っていると優先順位が意図と食い違うことがあります。Ollama向けに切り替える際はANTHROPIC_API_KEY=""を明示し、/statusでどの認証情報が実際に使われているかを確認します。
Ollama Cloudでx-api-keyだけを送って401になる
ローカルサーバーの検証なしの挙動に慣れていると見落としがちですが、クラウド直結はAuthorization: Bearerヘッダーが必須です。x-api-keyだけを送るリクエストは拒否されます。
PDFやURL画像を渡すと失敗する
前章の制約表のとおり、PDFのdocumentブロックとURL指定の画像はOllama側で非対応です。ファイルを直接読ませたい場合はbase64画像に変換するか、テキストとして貼り付けます。
Claude以外のOllama連携との違い
Ollamaの公式サイトには「Apps」機能もあり、macOS版のOllamaアプリからClaude Desktop(claude.aiのデスクトップアプリ)のモデルバックエンドを差し替えることもできます(Windows対応は今後の予定)。これは本記事で扱ったANTHROPIC_BASE_URLによるClaude Codeへの接続とは別の仕組みで、Ollamaアプリの「Apps」画面からClaude Desktopをペアリングする操作になります。Claude.aiのWeb版・Claude Desktop・Claude Codeでは接続手段自体が異なる点に注意してください。
よくある質問
ローカルのOllamaは無料で使えますか
ローカルで動かすモデルはOllama自体もモデルの実行も無料です。Ollama Cloudのモデルを使う場合はAPIキーが必要で、一部のモデルは有料プランを要求します。
Claude Code on the webやSlackからもOllamaに接続できますか
できません。これらはAnthropicがホストする面で、常にAnthropicのAPIを直接使うためANTHROPIC_BASE_URLを含むゲートウェイ系の環境変数は適用されません。
まとめ
Ollamaへの最短接続はollama launch claudeの1コマンドで、環境変数を自分で管理したい場合もローカルはANTHROPIC_BASE_URL=http://localhost:11434、クラウド直結はANTHROPIC_BASE_URL=https://ollama.comとOLLAMA_API_KEYを渡すだけです。つまずきやすいのは接続そのものより、コンテキスト長の既定値が小さいこととツール呼び出し非対応モデルを選んでしまうことの2点で、どちらも公式ドキュメントに明記された既知の制約です。tool_choiceやプロンプトキャッシュなどAnthropic APIの一部機能が非対応な点も踏まえたうえで、コーディング用途にはツール対応モデルと64k以上のコンテキスト長を選んでください。