著者 Ollamaをコーディングエージェントで使う方法
Ollamaをローカルでコーディングエージェントにつなぐ設定を解説します。base URL、無視されるdummy key、context lengthで動かなくなる理由、ローカルモデルが得意な作業を確認できます。
接続先
コーディングエージェントから Ollama を使用できます。接続に必要な変更は、想定より少ないものです。ベース URL を1つ変更し、モデル名を1つ選びます。API key の欄には値が必要ですが、ローカルサーバーはその値を無視するため、どの文字列でも使用できます。
Ollama は port 11434 で待ち受け、2種類のリクエスト形式を同時に提供します。/v1/chat/completions は OpenAI-compatible 形式です。Ollama のドキュメントでは、この形式の key は必須ですが無視されると説明されています。/v1/messages は Anthropic-compatible 形式で、Claude Code が使用する形式です。エージェントはすでに2種類のいずれかに対応しているため、それ以外を変更する必要はありません。
この設定には5分ほどしかかかりません。実用性を左右するのは、ほとんど誰も変更しない2つの設定、context length と keep-alive です。また、モデルが得意とする種類の作業を与えることも重要です。それぞれについて個別のセクションで説明し、最後に現実的な制限を示します。
ローカルのベース URL に対応するコーディングエージェント
確認方法は 1 つです。ツールにベース URL の設定項目があるかを確認します。設定できる場合は、サーバーに接続できます。
Ollama は Claude Code、OpenCode、Codex、Cline、Roo Code、Zed、JetBrains IDE、VS Code 向けの統合ページを公開しています。Aider も Ollama のサポートを別途ドキュメント化しています。これらは、2026 年 8 月時点で一般にコーディングエージェントと呼ばれるものの大半をカバーしています。ただし、すべてが同じ API 形式に対応しているわけではありません。この違いが構成の失敗につながります。
- ほとんどのエージェントは OpenAI 互換エンドポイントを必要とします。ベース URL
http://localhost:11434/v1と、空でない任意の API key 文字列を指定します。 - Claude Code は OpenAI のベース URL を受け付けません。Anthropic Messages API を使用するため、
ANTHROPIC_BASE_URLにhttp://localhost:11434を設定する必要があります。Ollama はここで/v1/messagesを提供します。 - Codex は OpenAI Responses API を使用します。Ollama も
/v1/responsesを提供しており、version 0.13.3 で追加されました。 - ベース URL の設定項目がないエージェントは、エンドポイントがクライアントに組み込まれているため、接続先を変更できません。その場合は、セルフホストの LiteLLM gateway などの変換層を前段に置き、クライアントが要求する形式でモデルを再公開します。
Ollama にこれらの設定を作成させることもできます。ollama launch opencode は選択したモデル用のインライン設定で OpenCode を起動し、ollama launch claude は Claude Code で同じ処理を行います。ollama launch droid --config はツールを起動せずに設定を書き込みます。
Ollama をインストールし、ツール呼び出しに対応したモデルを取得する
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 で理由を確認できます。
エージェントを動作させるには、モデルがツール呼び出しに対応している必要があります。エージェントはツール呼び出しによって、ファイルを読み取り、パッチを書き込み、テストを実行し、失敗内容を読み取って再試行します。ツール呼び出しを出力できないモデルは、編集を実行せずに文章で説明するため、エージェントがループするか停止します。pull する前に、ollama.com のモデルページで tools ラベルを確認してください。qwen3-coder:30b はこのラベルに対応しており、2026 年 8 月時点では 19 GB のダウンロードと 256K のコンテキストウィンドウが必要です。CPU のみで動作させる場合や RAM が少ない場合は、VPS での Qwen 27B タグのメモリ計算で、ダウンロードを開始する前に 8 から 64 GB の範囲で実際に収まる構成を確認できます。
次に、サーバーが実際に提供している名前を確認します。
curl http://localhost:11434/v1/modelsこの出力に含まれる文字列を、エージェントの設定に文字単位でそのまま指定する必要があります。先に確認しておけば、model not found エラーの大半を解消できます。Ollama をまだインストールしていない場合は、VPS で Ollama を使って LLM をセルフホストする方法に詳しい手順があります。
OpenCode の接続先を Ollama に設定する
~/.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 を実行する を参照してください。
Ollama に Claude Code を接続する
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30bANTHROPIC_API_KEY は意図的に空文字列に設定します。環境に実際のキーが残っていると、リクエストがホスト型 API に送信されます。その結果、料金が発生し、ローカル推論は実行されません。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:30bAider のドキュメントでは、ollama/ より ollama_chat/ プレフィックスを推奨しています。また、.aider.model.settings.yml でモデルごとにコンテキストウィンドウを固定できます。モデルによってサーバーのデフォルト値とは異なるウィンドウが必要な場合に便利です。
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536動作している構成でも無意味な出力になる理由
ここが重要な箇所です。Ollama は認識できる VRAM（GPU 上のビデオメモリ）からデフォルトのコンテキスト長を選択します。このデフォルト値は公開されています。
The data behind this chart
[
{
"label": "Under 24 GiB VRAM",
"default_context_tokens": "4,096"
},
{
"label": "24 to 48 GiB VRAM",
"default_context_tokens": "32,768"
},
{
"label": "48 GiB VRAM or more",
"default_context_tokens": "262,144"
}
]ほとんどの VPS プランと CPU のみのサーバーは、最初の行に該当します。デフォルトのコンテキスト長は 4,096 トークンです。最後の行にある 262,144 トークンを使用できるのは、大容量の GPU だけです。
エージェントは、処理を始める前に 4096 トークンを消費します。システムプロンプト、ツール定義、リポジトリ一覧、最初に開くファイルだけで、すでにこの値を超えます。次に起きることが、問題の本質です。エラーは発生しません。Aider のドキュメントによると、Ollama はウィンドウを超えたコンテキストを暗黙的に破棄します。古いトークンから順に消えるため、モデルは見えなくなったファイルについて自信を持って回答したり、2 つ前の手順で指定した指示を忘れたりします。ローカルモデルはコードを書くには能力が低すぎるという報告の多くは、この仕組みによるものです。
Ollama のドキュメントでは、エージェントやコーディングツールなどのタスクには、少なくとも 64000 トークンを設定するよう推奨しています。サーバーで設定します。
sudo systemctl edit ollama.serviceoverride ファイルに次の行を追加します。
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"その後、設定を再読み込みして再起動します。
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psollama ps が確認に使用するコマンドです。CONTEXT 列を出力し、その値がモデルが実際に受け取ったコンテキスト長です。ID と SIZE の値は環境によって異なります。
NAME ID SIZE PROCESSOR CONTEXT UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 4 minutes from nowエージェントではなくサーバーで設定してください。理由は 2 つあります。OpenAI chat completions スキーマにはコンテキスト長を指定するフィールドがないため、OpenAI 互換クライアントから指定できません。また、この設定はサーバー単位で適用されるため、そのサーバーを指定するすべてのエージェントが設定を継承します。モデルごとに異なるウィンドウが必要な場合は、Modelfile を使ってコピーに設定を組み込みます。
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f Modelfileコンテキストは無料ではありません。ウィンドウを長くするとメモリ使用量が増えるため、PROCESSOR 列を監視してください。確認したいのは 100% GPU です。モデルの一部が CPU に移るとトークン生成速度が大幅に低下し、エージェントのループが実用にならなくなります。ローカル LLM の 1 秒あたりのトークン数を測定する方法で、サーバーの実際の上限を確認できます。購入前のマシン構成の見積もりについては、コーディングエージェント用 VPS に必要な RAM と CPU の量で説明しています。
リクエスト間でモデルを読み込んだままにする
デフォルトでは、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 エンドポイントにのみ存在し、互換エンドポイントにはありません。そのため、エージェントがリクエストごとに設定することはできません。使用できる唯一の設定手段は環境変数です。メモリを解放する必要がある場合は、ollama stop qwen3-coder:30b でサーバーを停止せずにモデルをアンロードできます。
別のサーバーで Ollama を実行する
Ollama は localhost にバインドします。別のマシンから接続するには、同じ systemd override で OLLAMA_HOST=0.0.0.0:11434 を設定し、サービスを再起動します。
これはプライベートネットワーク内でのみ行ってください。Ollama のドキュメントによると、ローカル API に認証は必要ありません。そのため、ポート 11434 をインターネットに公開すると、誰でもハードウェアを使用でき、エージェントが送信する内容を読み取れます。安全な方法は 2 つあります。バインド先を localhost のままにし、ノート PC から 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 の比較では、スループットの差が問題になり始める条件を説明しています。
ローカルのコーディングモデルが有効な場面と、そうでない場面
自分でホストするモデルを使ったエージェントが、すべてのタスクで最先端の API に置き換わるわけではありません。次の4種類の作業では、明確に有利です。
- 変更内容が小さく、結果を確認できる機械的な一括編集です。リポジトリ全体での名前変更、型ヒントの追加、docstring の記述、コメントの翻訳などが該当します。モデルを数時間動かしても、請求額は増えません。
- ハードウェアの外部に持ち出してはならない作業です。秘密保持契約の対象であるクライアントコードや、第三者に送信することを許可されていない内部リポジトリなどです。
- ホスト型 API をまったく呼び出せない、オフラインまたはエアギャップ環境のマシンです。
- コストを予測しやすい作業です。サーバーの費用を支払った後は、エージェントがループ内でトークンを消費し続けても追加費用はかかりません。従量制 API とは正反対です。計算方法は GPU VPS と API トークンの損益分岐点 に示しています。
一方、長い複数ステップのタスクでは不利です。「このテストが失敗する理由を調べ、原因を修正し、呼び出し元を更新する」には、すべての履歴をコンテキストに保持したまま、多数のツール呼び出しを連続して正しく実行する必要があります。中程度のサーバー上で 8B から 14B 程度のモデルを使うと、不正なツール呼び出しを生成したり、数ターン後に計画を失ったりします。その結果、タスク自体にかかる時間よりも、モデルの誘導に時間がかかります。これは、プロンプトを工夫すれば解決できる問題ではありません。モデルの処理能力の問題です。
また、誤りのコストが高く、すべての行を確認しない場合も不利です。ローカルモデルには、出力を検証できる狭い範囲の作業を任せてください。手順ごとに確認しない作業には、ホスト型モデルを使い続けます。
障害のパターンと表示される文字列
curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. サーバーが起動していないか、agent が別のホストを参照しています。systemctl status ollamaを実行し、続いてjournalctl -e -u ollamaを実行します。
agent がモデルは存在しないと報告する。 設定ファイルの名前が、サーバーが提供する名前と一致していません。curl http://localhost:11434/v1/modelsと照合し、そこにある文字列をコピーします。タグも名前の一部です。そのため、インストール済みのモデルに似ていても、まだ取得していないタグを指定した設定は失敗します。
agent が文章で回答するだけで、ファイルを編集しない。 モデルがツールに対応していないか、リクエストとツール定義だけですでにコンテキストウィンドウを使い切っています。モデルページのtoolsラベルを確認し、続いてollama psのCONTEXT列を確認します。
最初のトークンが出るまで長く待たされ、その後は通常の速度になる。 keep-alive の期限が切れ、重みがディスクから再度読み込まれています。OLLAMA_KEEP_ALIVEを設定します。
モデルが、直前に読み取ったファイルと矛盾する回答をする。 コンテキストが切り詰められています。ollama psには通常、設定したつもりの値より小さいCONTEXT値が表示されます。環境変数が systemd unit ではなく、シェルに設定されているためです。
すべて動作するが遅く、PROCESSORが100% GPUではない。 モデルとそのコンテキストが VRAM に収まりません。コンテキスト長を短くするか、より小さいモデルまたはより小さい量子化を使用します。
FAQ
Claude Code から Ollama を指定できますか？
はい。ただし、OpenAI 互換 URL は使用できません。Claude Code は Anthropic Messages API を使用し、Ollama は同じポート 11434 の /v1/messages でこの形式を提供します。ANTHROPIC_BASE_URL=http://localhost:11434、ANTHROPIC_AUTH_TOKEN=ollama、空の ANTHROPIC_API_KEY を export してから、claude --model qwen3-coder:30b で起動します。ollama launch claude を使うと、これらの設定が自動的に書き込まれます。この互換レイヤーは tool_choice と prompt caching を実装していません。また、token counting endpoint もないため、報告される token 数は概算です。
ローカルモデルが認識できないコードについて回答するのはなぜですか？
リクエストが context window に収まらなくなり、最も古い部分がエラーなしで削除されたためです。Ollama は検出した VRAM からデフォルトの context を設定します。24 GiB 未満では、そのデフォルトは 4,096 tokens です。これは agent の system prompt と tool definitions だけでも超過します。systemd unit で OLLAMA_CONTEXT_LENGTH=64000 を設定し、Ollama を再起動してください。その後、ollama ps の CONTEXT 列に新しい値が表示されることを確認します。
VPS で coding agent を実行する場合、どのモデルを選ぶべきですか？
64k の context window とともにメモリへ収まり、tools ラベルが付いた最大のモデルを選んでください。コード向けに調整されたモデルを優先します。十分な VRAM がある GPU サーバーでは、qwen3-coder:30b が一般的な選択肢です。おおむね 14B parameters 未満のモデルでもコードに関する質問には十分回答できますが、複数段階の編集では失敗することがあります。agent の処理では、tool calls の小さな書式ミスが大きく影響するためです。サンプルの prompt ではなく、自分の repository にある実際のタスクでテストしてください。
自分のモデルで coding agent を実行するには GPU が必要ですか？
実際には、必要です。CPU のみの inference も動作し、単発の質問には十分です。しかし agent は 1 つのタスクで多数のリクエストを送り、そのたびに長い履歴を再読み込みします。そのため token rate が遅いと、2 分のタスクが 1 時間かかります。ollama ps の PROCESSOR 列を確認してください。100% GPU 以外の値は、モデルの一部が CPU 上で実行されていることを示し、token rate が大幅に低下します。