SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

Ollamaをコーディングエージェントで使う方法

Ollamaをコーディングエージェントにつなぐ設定を解説します。base URL、無視されるダミーキー、context lengthで壊れる原因、ローカルモデルが得意な作業を確認できます。

接続する対象

コーディングエージェントで Ollama を使用できます。接続設定は、想定より簡単です。変更するのは base URL 1 つと、model name 1 つです。API key のフィールドには値が必要ですが、ローカルサーバーはその値を無視するため、どのような文字列でも使用できます。

Ollama は port 11434 で待ち受け、3 つの API サーフェスを同時に提供します。/api は Ollama のネイティブ API です。/v1 は OpenAI-compatible layer で、そこには複数の形式が含まれます。/v1/chat/completions、/v1/responses、/v1/completions、/v1/models、/v1/embeddings です。Ollama のドキュメントでは、そこでの key は必須ですが無視されると説明されています。3 つ目のサーフェスは Anthropic-compatible です。client は http://localhost:11434 を base URL として使用し、/v1/messages を追加します。これは Claude Code が使用する形式です。通常、エージェントは /v1/chat/completions を使用し、Codex は /v1/responses を使用し、Claude Code は /v1/messages を使用します。使用しているエージェントは、すでにこれらのいずれかを使用できるため、それ以外を変更する必要はありません。

接続の設定には 5 分かかります。結果を実用に耐えるものにできるかどうかは、ほとんど誰も変更しない 2 つの設定、context length と keep-alive、およびモデルが得意とする種類の作業を与えることにかかっています。これらについてはそれぞれ個別のセクションで説明し、正直な限界については最後に扱います。

ローカルの base URL を受け付けるコーディングエージェント

確認する点は 1 つです。ツールに base URL の設定項目があるかどうかです。設定できる場合、そのツールはサーバーに接続できます。

Ollama は Claude Code、OpenCode、Codex、Cline、Roo Code、Zed、JetBrains IDEs、VS Code の連携ページを公開しています。Aider については、Ollama のサポートを別途説明しています。これで、2026 年 10 月時点で一般にコーディングエージェントと呼ばれるものの大半をカバーできます。ただし、すべてが同じ形式で通信するわけではなく、この違いが構成の失敗につながります。

  • ほとんどのエージェントは OpenAI-compatible endpoint を要求します。base URL http://localhost:11434/v1 と、空でない任意の API key 文字列を指定します。
  • Claude Code は OpenAI base URL をまったく受け付けません。Anthropic Messages API を使用するため、ANTHROPIC_BASE_URL に http://localhost:11434 を設定する必要があります。Ollama は /v1/messages でサービスを提供します。
  • Codex は OpenAI Responses API を使用します。Ollama は /v1/responses も提供しており、version 0.13.3 で追加されました。
  • base URL の設定項目がないエージェントは、endpoint が client に組み込まれているため、接続先を変更できません。カスタム URL を受け付けても、別の API 形式が必要な場合は、self-hosted LiteLLM gateway などの translation layer を前段に置きます。そのうえで、client が要求する形式でモデルを再公開します。

Ollama はこれらの config を作成できます。ollama launch opencode は、選択したモデルの inline config で OpenCode を起動します。ollama launch claude は Claude Code に対して同じ処理を行います。ollama launch droid --config はツールを起動せずに config を書き込みます。

Ollama をインストールし、ツールを呼び出せるモデルを pull する

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

インストーラーは systemd unit を追加して起動するため、systemctl status ollama を実行すると active (running) と表示されるはずです。表示されない場合は、journalctl -e -u ollama で理由を確認できます。

モデルは tool calling に対応している必要があります。tool calling はエージェントが動作する仕組みだからです。エージェントはファイルを読み、patch を書き、テストを実行し、失敗内容を読んで再試行します。tool call を出力できないモデルは、編集を実行せずに文章で説明するため、エージェントがループするか停止します。pull する前に、ollama.com のモデルページで tools ラベルを確認してください。qwen3-coder:30b はこのラベルに対応しており、2026 年 10 月時点で、そのタグは 19 GB のダウンロードで、256K のコンテキストウィンドウを備えています。CPU のみの環境や RAM が少ない環境では、ダウンロードを始める前に、VPS 上の Qwen 27B タグに必要なメモリの計算で 8 から 64 GB の範囲で実際に収まる構成を確認してください。pull すると、その数 GB のファイルはサーバーの root ディスクに保存されます。VPS では root ディスクの空き容量が最も少ないことが多いため、ディスクが満杯になる前に、Ollama がモデルファイルを保存する場所と、別の場所へ移動する方法を確認しておく価値があります。

次に、サーバーが実際に提供している名前を確認します。

curl http://localhost:11434/v1/models

このレスポンス内の文字列が、エージェントの設定に 1 文字も変えずに記述すべき値です。先に確認しておけば、model-not-found エラーの大半を解消できます。まだ Ollama をインストールしていない場合は、詳しい手順を VPS 上で Ollama を使って LLM をセルフホストする方法で確認できます。

Ollama に OpenCode を接続する

~/.config/opencode/opencode.json を編集します。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

models の下にあるキーは Ollama に送信するモデル名なので、ollama ls と完全に一致させる必要があります。name フィールドはモデル選択画面に表示されるラベルにすぎません。opencode を起動して Ollama プロバイダーに切り替え、journalctl -e -u ollama を監視して、リクエストが別の場所ではなくサーバーに到達したことを確認します。エージェント自体の設定については、VPS 上で OpenCode を実行するで説明しています。

Claude Code の接続先を Ollama に設定する

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

ANTHROPIC_API_KEY は意図的に空文字列に設定します。ベース URL がリクエストの送信先を制御するため、このキーを空にすると、ホスト側の認証情報がローカル環境に入りません。ollama launch claude がこれらをすべて設定します。

互換レイヤーに含まれない機能を把握しておく必要があります。tool_choice とプロンプトキャッシュには対応していません。また、トークン数を取得するエンドポイントもないため、表示されるトークン数はモデル自身の tokenizer による近似値です。Claude Code は大きなシステムプロンプトと多数のツールも送信するため、チャットクライアントより多くのコンテキストが必要です。何が引き継がれ、何が引き継がれないかについては、Claude をセルフホストできるかどうかで説明しています。

Ollama を指すように Aider を設定する

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Aider のドキュメントでは、ollama/ よりも ollama_chat/ プレフィックスを推奨しています。デフォルトでは、Aider は各リクエストに必要なコンテキストに加えて、応答用に 8k トークンを要求します。また、.aider.model.settings.yml でモデルごとにコンテキストウィンドウを固定できます。モデルによってサーバーのデフォルトとは異なるウィンドウが必要な場合に便利です。

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

動作している構成でも意味不明な出力になる理由

ここが重要な部分です。Ollama は、認識できる GPU の合計 VRAM(ビデオメモリ)からデフォルトのコンテキスト長を選びます。検出した GPU ごとに OLLAMA_GPU_OVERHEAD を差し引きます。実装では、次のしきい値が使用されます。

グラフOllama default context length by aggregate VRAM, checked 2026-10-26
このグラフのデータ
[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

ほとんどの VPS プランと、CPU のみのサーバーは最初の行に該当し、4,096 トークンになります。複数の小容量 GPU を合計すると、最後の行にある 262,144 トークンの 47 GiB しきい値に達することがあります。

エージェントは処理を開始する前に 4096 トークンを渡します。システムプロンプト、ツール定義、リポジトリ一覧、最初に開くファイルだけで、すでにそのサイズを超えます。ここで起きることが問題の本質です。エラーは発生しません。Aider のドキュメントによると、Ollama はウィンドウを超えたコンテキストを黙って破棄します。古いトークンから順に消えるため、モデルはすでに見えないファイルについて自信を持って回答したり、2 つ前に指定した指示を忘れたりします。ローカルモデルはコードを書くには賢くないという報告の多くは、この仕組みが原因です。値そのものを選ぶことも別途判断が必要です。設定値を決める前に、各サイズで num_ctx が KV キャッシュメモリに消費する量を確認してください。

Ollama のドキュメントでは、エージェントやコーディングツールなどのタスクには、少なくとも 64000 トークンを設定するよう推奨しています。サーバーで設定します。

sudo systemctl edit ollama.service

override ファイルに次の行を追加します。

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

その後、再読み込みして再起動します。

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

再起動後にエージェントからリクエストを送信し、続いて ollama ps を実行して、確認対象のモデルをロード済みにします。ollama ps が確認コマンドです。CONTEXT 列が表示され、その値がモデルが実際に受け取ったコンテキスト長です。ID と SIZE の値は異なります。

NAME               ID              SIZE     PROCESSOR    CONTEXT    RUNNER    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      ggml      4 minutes from now

エージェントではなくサーバーで設定してください。理由は 2 つあります。OpenAI chat completions のスキーマにはコンテキスト長のフィールドがないため、OpenAI 互換クライアントから指定できません。また、モデルまたはリクエストで上書きされない限り、サーバーのデフォルト値がすべてのエージェントに適用されます。出力側には独自の上限があります。コンテキスト長とは異なり、この値は互換エンドポイント経由で渡されます。そのため、パッチの途中で返信が止まる場合は、num_predict と、それに対応する max_tokens フィールドを使用します。1 つのモデルだけ別のウィンドウが必要な場合は、Modelfile でコピーに設定を組み込みます。

FROM qwen3-coder:30b
PARAMETER num_ctx 65536
ollama create qwen3-coder-64k -f Modelfile

コンテキストは無料ではありません。ウィンドウを長くするとメモリ消費量が増えるため、PROCESSOR 列を確認してください。目標にするのは 100% GPU です。モデルの一部が CPU に移るとトークン生成速度が大幅に低下し、エージェントのループが実用にならなくなります。ローカル LLM の 1 秒あたりのトークン数を測定する方法で、使用するマシンの実際の上限を確認できます。購入前のマシン規模の見積もりについては、コーディングエージェントに必要な RAM と CPU を備えた VPS の規模を参照してください。

リクエスト間でモデルをロードしたままにする

デフォルトでは、Ollama は最後のリクエストから 5 分後にモデルをアンロードします。チャットボックスには適していますが、エージェント処理には適していません。差分を読むために一時停止している間にタイマーが切れると、次のリクエストで最初のトークンが表示される前に、数十 GB の重みをディスクから再ロードします。ハングしているように見えます。

OLLAMA_KEEP_ALIVE には、10m や 24h のような期間文字列、秒数を表す単純な数値、モデルを無期限にロードしたままにする -1、または直ちにアンロードする 0 を指定します。コンテキスト長の設定と並べて指定します。

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

keep_alive リクエストフィールドは、Ollama のネイティブな /api/generate および /api/chat エンドポイントと、/v1/chat/completions 上の Ollama 拡張で利用できます。追加のリクエストフィールドを公開するエージェントであれば、そこに指定できます。そうでない場合は、環境変数を使用します。メモリを解放する必要がある場合は、ollama stop qwen3-coder:30b でサーバーを停止せずにモデルをアンロードできます。再起動後も設定を維持したい場合や、重みを終日メモリに保持することと、そのメモリを解放することのどちらを選ぶか検討したい場合は、Ollama のモデルをメモリにロードしたままにすることで、どちらにも対応できます。

別サーバーで Ollama を実行する

Ollama は localhost にバインドします。別のマシンから接続するには、同じ systemd override に OLLAMA_HOST=0.0.0.0:11434 を設定して、サービスを再起動します。

これはプライベートネットワークでのみ行ってください。Ollama のドキュメントによると、ローカル API に認証は必要ありません。そのため、ポート 11434 をインターネットに公開すると、誰でもハードウェアを使用できます。安全な方法は 2 つあります。バインド先を localhost のままにして、ノートパソコンから SSH 経由でポートを転送します。

ssh -N -L 11434:localhost:11434 you@your-vps

エージェントは引き続き http://localhost:11434/v1 を参照するため、違いを意識する必要はありません。もう 1 つの方法は VPN です。この場合、Ollama のバインド先を 0.0.0.0 ではなく VPN のアドレスにします。複数のユーザーまたは複数のエージェントで 1 台のマシンを共有する場合、メモリに余裕があれば Ollama は並列リクエストに対応します。また、Ollama と vLLM の比較では、スループットの差が問題になり始める箇所を確認できます。

ローカルのコーディングモデルが有効な場面と、そうでない場面

自分でホストするモデルを使うエージェントは、すべての作業で frontier API の代わりになるわけではありません。次の 4 種類の作業では明確に有効です。

  • 大量の機械的な編集。各変更が小さく、結果を確認できる作業です。リポジトリ全体での名前変更、型ヒントの追加、docstring の記述、コメントの翻訳などが該当します。モデルを数時間動かしても、料金は増えません。
  • ハードウェアの外部に出してはならない作業。秘密保持契約の対象であるクライアントコードや、第三者に送信することを許可されていない内部リポジトリなどです。
  • オフライン環境やエアギャップ環境。呼び出せるホスト型 API が存在しない環境です。
  • 予測可能なコスト。サーバーの支払いが済んでいれば、エージェントがループ内でトークンを消費しても追加費用はかかりません。これは従量制 API とは正反対です。GPU VPS と API トークンの損益分岐点で計算を示しています。

長い複数ステップの作業では不利です。「このテストが失敗する理由を調べ、原因を修正し、呼び出し側を更新する」には、履歴全体をコンテキストに保持したまま、多数のツール呼び出しを連続して正しく実行する必要があります。控えめなサーバー上で 8B から 14B のモデルを使うと、不正なツール呼び出しを生成したり、数ターン後に計画を失ったりします。その結果、作業自体にかかる時間よりも、モデルの誘導に時間がかかります。これは、プロンプトの書き方で解決できる問題ではありません。容量の問題です。

また、間違いのコストが高く、すべての行を読むことがない場合も不利です。出力を検証する狭い作業をローカルモデルに任せ、手順ごとに確認しない作業にはホスト型モデルを使います。

障害のパターンと表示される文字列

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused。 サーバーが起動していないか、エージェントが別のホストを参照しています。systemctl status ollama を実行し、続けて journalctl -e -u ollama を実行します。

エージェントがモデルが存在しないと報告する。 設定内の名前が、サーバーで提供されている名前と一致していません。curl http://localhost:11434/v1/models と照合し、そこに表示された文字列をコピーします。タグも名前の一部です。そのため、似たモデルがインストール済みでも、取得していないタグを設定で指定すると失敗します。

エージェントが文章で回答するだけで、ファイルを編集しない。 モデルがツールに対応していないか、リクエストとツール定義だけですでにコンテキストウィンドウを使い切っています。モデルページの tools ラベルを確認し、続いて ollama ps の CONTEXT 列を確認します。

最初のトークンまで長時間無応答になり、その後は通常の速度になる。 keep-alive の期限が切れ、重みがディスクから再度読み込まれています。OLLAMA_KEEP_ALIVE を設定します。

モデルが、直前に読み取ったファイルと矛盾する回答をする。 コンテキストが切り詰められています。ollama ps には、設定したつもりの値より小さい CONTEXT 値が表示されることがよくあります。環境変数が systemd unit ではなく、シェルに設定されているためです。

すべて動作するが遅く、PROCESSOR に 100% CPU または CPU/GPU の分割が表示される。 通常は、モデルとそのコンテキストが VRAM に収まりません。GPU を搭載したマシンで PROCESSOR が 100% CPU と表示される場合は、まず別の原因を除外します。Ollama が GPU 自体を検出できていない可能性があります。Ollama のドキュメントによると、Linux では suspend/resume サイクルの後に NVIDIA GPU の検出に失敗し、CPU にフォールバックすることがあります。この場合、sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm でドライバーを再読み込みすると回避できます。GPU が検出されても分割が残る場合は、コンテキスト長を短くするか、より小さいモデルまたはより小さい量子化を使用します。再取得する前に、q4_K_M、q8_0、fp16 それぞれのメモリ使用量と、実際に品質が低下する箇所で、1 段階小さくした場合に確保できる容量と、その代わりに失うものを確認できます。Unknown も PROCESSOR の値になる可能性がありますが、CPU オフロードが行われていることを示すものではありません。

FAQ

Claude Code を Ollama に接続できますか?

はい。ただし、OpenAI 互換 URL は使用しません。Claude Code は Anthropic Messages API を使用し、Ollama は同じポート 11434 で /v1/messages にその形式の API を提供します。ANTHROPIC_BASE_URL=http://localhost:11434、ANTHROPIC_AUTH_TOKEN=ollama、空の ANTHROPIC_API_KEY を export してから、claude --model qwen3-coder:30b で起動します。ollama launch claude を使うと、同じ設定が自動的に書き込まれます。この互換レイヤーは tool_choice とプロンプトキャッシュを実装していません。また、トークン数を数えるエンドポイントもないため、表示されるトークン数は近似値です。

ローカルモデルが認識できないコードについて回答するのはなぜですか?

リクエストがコンテキストウィンドウに収まらなくなり、先頭の古い部分がエラーなしで破棄されたためです。Ollama は、GPU ごとに設定されたオーバーヘッドを差し引いた、検出済み VRAM の合計値を基にデフォルトのコンテキストを設定します。23 GiB 未満ではデフォルトが 4,096 トークン、23 GiB 以上 47 GiB 未満では 32,768 トークン、47 GiB 以上では 262,144 トークンです。systemd unit に OLLAMA_CONTEXT_LENGTH=64000 を設定して Ollama を再起動し、ollama ps の CONTEXT 列に新しい値が表示されることを確認します。

VPS 上でコーディングエージェントを動かすには、どのモデルを選ぶべきですか?

64k のコンテキストウィンドウを確保した状態でメモリに収まり、tools ラベルが付いた最大のモデルを選びます。コード向けに調整されたモデルを優先してください。十分な VRAM を備えた GPU サーバーでは、qwen3-coder:30b が一般的な選択肢です。そのタグのモデルがサーバーに大きすぎる場合は、ダウンロードする前に Nemotron 3.5 Lightning の RAM 使用量と CPU のみでの速度 を比較すると役立ちます。おおむね 14B パラメータ未満のモデルでもコードに関する質問には適切に回答できますが、複数手順の編集では失敗することがあります。エージェント処理では、tool call の小さな書式ミスが問題になるためです。サンプルプロンプトではなく、自分のリポジトリにある実際のタスクを 1 つ使ってテストしてください。

自分のモデルでコーディングエージェントを動かすには、GPU が必要ですか?

実用上は必要です。CPU のみの推論も動作し、単発の質問には十分ですが、エージェントは 1 つのタスクで多数のリクエストを送り、そのたびに長い履歴を再読み込みします。そのため、トークン生成速度が遅いと、2 分のタスクが 1 時間かかることがあります。ollama ps の PROCESSOR 列を確認してください。100% CPU または CPU/GPU split と表示される場合は CPU が使用されており、推論速度が低下します。Unknown だけでは CPU offloading の実行を確認できません。

この記事は役に立ちましたか?

#ollama#coding-agent#openai-compatible#local-llm#self-hosted-ai