著者 Ollamaをコーディングエージェントで使う方法
Ollamaをローカルでコーディングエージェントにつなぐ設定を解説します。base URL、無視されるdummy key、context lengthで起きる問題、ローカルモデルが得意な作業を確認できます。
接続先
Ollama はコーディングエージェントから利用できます。接続に必要な変更は、想定より少ないものです。ベース URL を変更し、モデル名を 1 つ選びます。API key の欄には値が必要ですが、ローカルサーバーはその値を無視するため、どの文字列でも使用できます。
Ollama は port 11434 で待ち受け、2 種類のリクエスト形式を同時に提供します。/v1/chat/completions は OpenAI-compatible 形式です。Ollama のドキュメントでは、この形式の key は必須ですが無視されると説明されています。/v1/messages は Anthropic-compatible 形式で、Claude Code が使用する形式です。エージェントはすでにどちらかの形式に対応しているため、それ以外を変更する必要はありません。
この設定には 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年8月時点で一般にコーディングエージェントと呼ばれるものの大半をカバーできます。ただし、すべてが同じ形式に対応しているわけではありません。この違いが構成の失敗につながります。
- 多くのエージェントは OpenAI 互換エンドポイントを必要とします。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 の設定項目がないエージェントは、エンドポイントがクライアントに組み込まれているため、接続先を変更できません。その場合は、自己ホスト型の 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 で原因を確認できます。
エージェントはツール呼び出しによって動作するため、モデルはツール呼び出しに対応している必要があります。ファイルを読み取り、パッチを書き込み、テストを実行し、失敗内容を読み取って再試行するという流れです。ツール呼び出しを出力できないモデルは、編集内容を文章で説明するだけで実際には変更しません。その結果、エージェントがループするか停止します。取得する前に、ollama.com のモデルページで tools ラベルを確認してください。qwen3-coder:30b はこのラベルに対応しており、2026 年 8 月時点では 19 GB のダウンロードと 256K のコンテキストウィンドウが必要です。サーバーが CPU のみで動作している場合や RAM が少ない場合は、ダウンロードを開始する前に、VPS で Qwen 27B タグを実行するためのメモリ計算で 8 ～ 64 GB に実際に収まる構成を確認してください。取得すると、その数 GB のファイルはサーバーの root ディスクに保存されます。VPS では root ディスクの空き容量が最も少ないことが多いため、ディスクが満杯になる前に Ollama がモデルファイルを保存する場所と、別の場所へ移動する方法を確認する価値があります。
次に、サーバーが実際に提供している名前を確認します。
curl http://localhost:11434/v1/modelsこのレスポンスに含まれる文字列を、エージェントの設定に1文字ずつ同じ内容で指定する必要があります。先に確認しておけば、モデルが見つからないエラーの大半を解消できます。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 を実行するを参照してください。
Claude Code を Ollama に接続する
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 とプロンプトキャッシュには対応していません。また、トークン数を数えるエンドポイントもないため、表示されるトークン数はモデル自身のトークナイザーによる概算です。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 つ前に与えた指示を忘れたりします。ローカルモデルではコードを書けないほど知能が低いという報告の多くは、この仕組みによるものです。値そのものを選ぶことも別の判断事項です。設定値を決める前に、各サイズの num_ctx が KV キャッシュメモリに必要とする量を確認してください。
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 互換クライアントから指定できません。また、この設定はサーバー単位なので、そのサーバーを指定するすべてのエージェントが継承します。出力側にも独自の上限があります。コンテキスト長とは異なり、こちらは互換エンドポイント経由で渡せるため、パッチの途中で応答が止まる場合は、num_predict と、それに対応する max_tokens フィールドを使います。モデルごとに異なるウィンドウが必要な場合は、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 でサーバーを停止せずにモデルをアンロードできます。設定を再起動後も維持したい場合や、1 日中重みをメモリに保持することとメモリを解放することのどちらがよいかを検討したい場合は、Ollama モデルをメモリに読み込んだままにすることで、どちらにも対応できます。
別のサーバーで Ollama を実行する
Ollama は localhost にバインドします。別のマシンから接続するには、同じ systemd の override で OLLAMA_HOST=0.0.0.0:11434 を設定し、サービスを再起動します。
この設定はプライベートネットワーク内でのみ行ってください。Ollama のドキュメントによると、ローカル API に認証は必要ありません。そのため、port 11434 をインターネットに公開すると、誰でもそのハードウェアを使用でき、エージェントが送信する内容を読み取れます。安全な方法は2つあります。localhost へのバインドを維持し、ラップトップから SSH で port を転送します。
ssh -N -L 11434:localhost:11434 you@your-vpsエージェントは http://localhost:11434/v1 を指定したまま動作し、違いを認識しません。もう1つの方法は VPN です。Ollama を 0.0.0.0 ではなく VPN のアドレスにバインドします。複数のユーザーまたは複数のエージェントで1台のマシンを共有する場合、Ollama の scheduler はその負荷を想定していません。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。 サーバーが起動していないか、エージェントが別のホストを参照しています。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% GPUではない。 モデルとそのコンテキストが VRAM に収まりません。コンテキスト長を短くするか、より小さいモデルまたはより小さい量子化を使用します。再取得する前に、q4_K_M、q8_0、fp16 それぞれのメモリ使用量と、実際に品質が低下する箇所で、1 段階小さくした場合に確保できる容量と、その代わりに失うものを確認できます。
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 とプロンプトキャッシュを実装していません。また、トークン数を数えるエンドポイントもないため、表示されるトークン数は概算です。
ローカルモデルが参照できないコードについて回答するのはなぜですか？
リクエストがコンテキストウィンドウに収まらなくなり、先頭の古い部分がエラーなしで削除されたためです。Ollama は検出した VRAM からデフォルトのコンテキスト長を決定します。24 GiB 未満では、そのデフォルト値は 4,096 トークンです。エージェントのシステムプロンプトとツール定義だけで、この容量を超えます。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 パラメータ未満のモデルでも、コードに関する質問には適切に回答できます。ただし、ツール呼び出しの小さな書式ミスがエージェント処理に大きく影響するため、複数段階の編集では失敗することがあります。サンプルプロンプトではなく、自分のリポジトリにある実際のタスクを1つ使ってテストしてください。
自分のモデルでコーディングエージェントを動かすには GPU が必要ですか？
実際には必要です。CPU のみの推論も動作し、単発の質問には十分です。ただし、エージェントは1つのタスクで多数のリクエストを送り、そのたびに長い履歴を再読み込みします。そのため、トークン生成速度が遅いと、2分のタスクが1時間かかることがあります。ollama ps の PROCESSOR 列を確認してください。100% GPU 以外の値は、モデルの一部が CPU で実行されていることを示します。この場合、トークン生成速度は大幅に低下します。