Ollama Web Searchは、Ollamaが2025年9月24日に公開したWeb検索APIです。ローカルで動かすモデルに検索結果を渡して、学習データより新しい情報を答えさせる用途で使います。本記事では、公式ドキュメント、SDK、Ollama本体(v0.40.4)のソースコードを2026年10月14日時点で確認し、APIキーの設定、REST・Python・JavaScriptでの呼び出し方、OpenAI・Anthropic互換APIからの使い方、料金の扱いを整理しました。SDKはPython版0.6.3とJavaScript版0.6.4、本体はDocker上のv0.40.4を実行して挙動を確かめています(有効なキーでの検索結果の中身は含みません)。
まとめ:Ollama Web Searchの要点
- エンドポイントは
POST https://ollama.com/api/web_search(検索)と/api/web_fetch(ページ取得)の2本。検索件数は既定5件、最大10件。 - 利用には無料のOllamaアカウントが必要。直接呼ぶならAPIキーを環境変数
OLLAMA_API_KEYに入れてBearer認証で送り、ローカルのOllama経由ならollama signinだけで済む。 - 推論はローカルでも、検索クエリはollama.comへ送られる。社外に出せないクエリを扱うなら使わない。
- 2026年10月時点の料金ページにWeb検索の単価や無料枠の回数は載っていない。上限を超えると429が返る前提で実装する。
- Python SDKは既定3件で、キーはimport時に読む。JavaScript SDKは文字列を渡すと例外になり、件数を
maxResultsで渡すとAPIの仕様名と食い違う。どちらも公式サンプルと挙動が違う。 - Ollama v0.32.11以降は、ローカルサーバーの
/v1/responsesに{"type": "web_search"}を渡すと、モデルが検索ツールを呼び出した場合に、OpenAIのSDKから検索結果を踏まえた回答を得られる。
以下、仕組み、認証、呼び出し方、互換API、料金、外部ツール連携の順に解説します。
Ollama Web Searchの仕組みと提供範囲
Ollamaは、LlamaやQwen、gpt-ossなどのオープンモデルを自分のPCやサーバーで動かすためのツールです。Web Searchはその周辺機能で、検索そのものはOllama社のクラウド(ollama.com)が担います。ローカルのモデルが検索結果を受け取り、回答を組み立てる分担です。
web_searchとweb_fetchの違い
| API | 入力 | 返り値 | 用途 |
|---|---|---|---|
| web_search | query(必須)、max_results(既定5・最大10) | results[](title・url・content) | 候補ページを探す |
| web_fetch | url(必須) | title・content・links[] | 1ページの本文を読む |
web_searchが返す content は本文の抜粋です。詳細まで読ませたいときは、エージェントがweb_searchでURLを見つけ、web_fetchで本文を取りに行く2段構えになります。公式ドキュメントの検索エージェント例もこの形です。
呼び出し経路3つと認証方法
同じ検索機能に、認証方法の違う入口が3つあります。どれも最終的にはollama.comで検索が実行されます。
| 経路 | 宛先 | 認証 | 向く用途 |
|---|---|---|---|
| 直接呼び出し | ollama.com/api/web_search | APIキー | 自作アプリ・SDK |
| ローカル中継 | localhost:11434/api/experimental/web_search | ollama signin | 連携ツール |
| 互換APIの組み込み検索 | localhost:11434/v1/responses ほか | ollama signin | OpenAI・Anthropic SDK |
APIキーを配りたくない端末ではローカル経由、Ollama本体を置かないサーバーでは直接呼び出しを選びます。
ローカル推論時の検索クエリの送信先
モデルがローカルで動いていても、検索クエリと取得したいURLはollama.comへ送られます。公式FAQは、クラウド機能を止める方法として ~/.ollama/server.json に "disable_ollama_cloud": true を書くか、環境変数 OLLAMA_NO_CLOUD=1 を設定する手順を示しています。この設定はOllama本体に適用され、SDKやcURLからollama.comへの直接通信は遮断しません。PythonとJavaScriptのSDKは、host にローカルのURLを指定しても、web_searchだけは常に https://ollama.com/api/web_search へ送る作りです。OLLAMA_NO_CLOUD=1 を付けて起動したv0.40.4に /api/experimental/web_search を送ると、HTTP 403と ollama cloud is disabled: web search is unavailable が返り、起動ログには Ollama cloud disabled: true と出ました。完全オフラインを求められる環境では、Web Searchは最初から選択肢に入りません。
APIキーの発行と認証設定
APIキーの発行とOLLAMA_API_KEYへの設定
ollama.comにサインインし、https://ollama.com/settings/keys でキーを作成します。公式ドキュメントの記載は「A free Ollama account is required」で、有料プランは必須ではありません。発行したキーは環境変数に入れておくと、cURL・Python・JavaScriptのどれからも同じ設定で使えます。macOS・Linuxのシェルでは次のとおりです。
export OLLAMA_API_KEY="発行したキー"
WindowsのPowerShellでは次のように書きます。新しいウィンドウでも使うなら、システムの環境変数に登録してください。
$env:OLLAMA_API_KEY = "発行したキー"
公式の認証ドキュメントによると、APIキーに有効期限はなく、不要になったら同じ設定画面で失効させます。キーはブラウザで動くコードやGitリポジトリに含めないでください。なお、http://localhost:11434 のローカルAPIでモデルを動かすだけなら認証は要りません。「ollama api key」で調べてキーを探している場合、必要になるのはWeb検索やクラウドモデルをollama.comへ直接呼ぶときだけです。
「Web search requires an Ollama account」と表示される条件
このメッセージはOllamaデスクトップアプリのチャット画面に出るものです。アプリのソース(app/ui/app/src/components/ChatForm.tsx)を読むと、未サインインのままWeb検索ボタンを押すとこの表示に切り替わります。アプリ上の操作でサインインするか、ターミナルで ollama signin を実行すれば解消します。v0.34.2以降は、初めて ollama を起動したときにサインインするかローカルだけで使うかを選ぶ画面が出ます。ここでローカルを選んだ場合も、後から ollama signin でサインインできます。
そもそも検索ボタンが見当たらない場合は、選んでいるモデルがツール呼び出し(tools)に対応していないか、クラウド機能が無効になっています。ボタンの表示条件は「tools対応モデル」かつ「クラウド無効化の設定がない」の2つです。
REST APIの呼び出し方(cURL)
以下のcURL例はmacOS・Linuxのシェル向けです。PowerShellでは、環境変数の参照と行継続の構文を変更する必要があります。
検索は次の1リクエストで試せます。件数を変えたいときは max_results を1〜10の範囲で付けます。
curl https://ollama.com/api/web_search \
--header "Authorization: Bearer $OLLAMA_API_KEY" \
--header "Content-Type: application/json" \
-d '{"query": "ollama new engine", "max_results": 3}'
レスポンスは {"results": [{"title": ..., "url": ..., "content": ...}]} の形です。ページ本文を取得するweb_fetchは、URLを1つ渡します。
curl https://ollama.com/api/web_fetch \
--header "Authorization: Bearer $OLLAMA_API_KEY" \
--header "Content-Type: application/json" \
-d '{"url": "https://ollama.com/blog/web-search"}'
返り値の links にはページ内のリンク一覧が入ります。エージェントに次のページを辿らせる材料になりますが、そのまま全部をモデルに渡すとコンテキストを圧迫します。キーが誤っているときは Unauthorized(HTTP 401)が返ります。
PythonとJavaScriptからの呼び出し
Python:ollama 0.6.0以降のweb_search()と認証設定
Web検索の関数はPythonライブラリ0.6.0(2025年9月24日)で追加されました。2026年10月時点の最新は0.6.3(2026年9月29日)です。
python -m pip install "ollama==0.6.3"
上のコマンドをターミナルで実行した後、次のコードをPythonファイルに保存して実行します。
import ollama
res = ollama.web_search("ollama new engine", max_results=5)
for r in res.results:
print(r.title, r.url)
page = ollama.web_fetch("https://ollama.com/blog/web-search")
print(page.title, len(page.content))
注意点が2つあります。1つ目は件数の既定値です。web_search() のシグネチャは0.6.3でも max_results: int = 3 で、REST APIの既定5件より少なくなっています。5件ほしいなら明示してください。
2つ目はキーを読むタイミングです。ollama.web_search() などのモジュール関数は、import時に作られる既定クライアントを使い、クライアントは生成時に OLLAMA_API_KEY を読みます。0.6.3で、import ollama の後に os.environ["OLLAMA_API_KEY"] を設定して呼んだところ、ValueError: Authorization header with Bearer token is required for web search で止まりました。同じ状態で ollama.Client() を作り直すとキーが読まれ、リクエストがollama.comへ届きます。キーは起動前に環境変数で渡すか、設定後に作ったクライアントのインスタンスから呼びます。
JavaScript:webSearch()のオブジェクト引数
npmの ollama(npmのlatestタグは2026年10月時点で0.6.4。GitHubのリリース一覧ではプレリリース扱い)では、webSearch() と webFetch() の引数がオブジェクトです。公式ドキュメントのWeb search章には client.webSearch("what is ollama?") と文字列を渡す例がありますが、0.6.4で実行すると Query is required の例外になりました。
Node.js環境で npm install [email protected] を実行し、次のコードを search.mjs に保存して node search.mjs で実行します。
import { Ollama } from "ollama";
const client = new Ollama({
headers: { Authorization: `Bearer ${process.env.OLLAMA_API_KEY}` },
});
const res = await client.webSearch({ query: "ollama new engine" });
const page = await client.webFetch({ url: "https://ollama.com" });
console.log(res.results);
console.log(page.title, page.content.length);
件数の指定にも差があります。型定義上のプロパティ名は maxResults ですが、fetch を差し替えて送信内容を確かめると、ボディに {"query":"ollama","maxResults":3} とcamelCaseのまま入っていました。REST APIの仕様書にあるパラメータ名は max_results です。SDKは引数をそのまま展開して送るため、JavaScriptで { query: "ollama", max_results: 3 } と書けば仕様どおりの名前で届きます(TypeScriptでは型エラーになるので、件数を確実に指定したいならREST APIを直接呼びます)。返却件数は検索語によって指定上限を下回るため、results の長さだけでは指定が反映されたかを判定できません。
OpenAI・Anthropic互換APIの組み込みWeb検索(ローカルOllama経由)
ここからは、APIキーを使わずにサインイン済みのローカルOllamaを経由する方法です。実行前にOllamaサーバーを起動し、ollama pull qwen3:4b でモデルを取得してください。次のPython例には python -m pip install openai も必要です。接続先とモデル名をOllama向けに設定すると、OpenAI・Anthropic形式のリクエストで組み込みWeb検索を利用できます。
OpenAI互換Responses APIのweb_searchツール
Ollama v0.32.11(2026年8月14日)のリリースノートに「The OpenAI-compatible Responses API now supports web search」とあります。ローカルサーバーの /v1/responses に、OpenAIの組み込みツールと同じ {"type": "web_search"} を渡します。
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
res = client.responses.create(
model="qwen3:4b",
input="Ollamaの最新バージョンを調べて",
tools=[{"type": "web_search"}],
)
print(res.output_text)
v0.40.4のソース(middleware/openai.go)では、モデルがweb_searchを呼ぶとOllamaのサーバー側で検索を実行し、結果を渡して回答を続けさせます。検索結果の上限は1回あたり5件で、この組み込みツールから上限値は指定できません。1回の応答で検索できる回数は最大10回で、v0.35.1(2026年9月29日)で3回から引き上げられました。レスポンスの output には、実際に投げた検索語が web_search_call として入ります。
この機能はローカルサーバー専用です。OpenAI互換APIのドキュメントは、ollama.comのクラウドAPI(https://ollama.com/v1)について「built-in web search through /v1/responses」に対応しないと明記しています。クラウドモデルを使う場合も、localhost:11434 を経由させます。
未サインインのまま使うとどうなるかを、Docker上のOllama v0.40.4と qwen3:1.7b で確かめました。モデルが検索を呼んだ時点でHTTP 401が返り、本文は something went wrong, please see the ollama server logs for details だけです。サーバーログを見ると、Ollamaが内部で /api/experimental/web_search を呼び、そこで401になっていました。この401が出たら、まず ollama signin を済ませているかを確認します。なお qwen3:0.6b では、同じ指示を2回送っても検索を呼ばずに空の回答で終わりました。
Anthropic互換Messages APIのweb_searchツール
Anthropic互換の /v1/messages も、Anthropicの組み込みツール web_search_20250305 を受け付けます。ソース(middleware/anthropic.go)では、max_uses に正の整数を指定すると、その値と10の小さいほうが検索回数の上限になり、結果は web_search_tool_result ブロックとして返ります。Claude Code のようにAnthropic形式で話すツールをOllamaにつないだときも、この経路で検索が動きます。
失敗の返し方はResponses APIと違います。未サインインの状態で同じ環境から送ると、HTTPステータスは200のまま、server_tool_use の直後に "error_code": "unavailable" を持つ web_search_tool_result_error が入って応答が終わりました。ステータスコードだけを見ていると検索の失敗に気づけないため、content の中身でエラーを判定します。
curl http://localhost:11434/v1/messages \
-H "Content-Type: application/json" \
-d '{"model": "qwen3:4b", "max_tokens": 1024,
"messages": [{"role": "user", "content": "Ollamaの最新版を調べて"}],
"tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 2}]}'
ローカルサーバーの実験的検索APIとGoからの利用
Ollama本体のv0.18.0(2026年3月14日)以降には、ローカルサーバーに /api/experimental/web_search と /api/experimental/web_fetch があります。サーバーのサインイン情報でollama.comへ中継する作りで、クライアントが付けた Authorization ヘッダーは中継前に削除されます。OpenClawなどの連携ツールはこの経路を使います。Goなら、公式パッケージ github.com/ollama/ollama/api のクライアントに、このエンドポイントを呼ぶ実験的なメソッドがあります。ただし公開APIリファレンスには載っていないため、長く保守するアプリは https://ollama.com/api/web_search を直接呼ぶほうが安全です。
ツール呼び出しによる検索エージェントの実装
互換APIを使わずに検索の流れを自分で制御したいときは、Pythonライブラリのweb_searchとweb_fetchを関数のまま tools に渡します。モデルが検索の要否を判断し、必要なときだけ呼び出す作りです。
from ollama import chat, web_search, web_fetch
tools = {"web_search": web_search, "web_fetch": web_fetch}
messages = [{"role": "user", "content": "Ollamaの最新リリースの変更点は?"}]
while True:
res = chat(model="qwen3:4b", messages=messages,
tools=[web_search, web_fetch], think=True,
options={"num_ctx": 32768})
messages.append(res.message)
if not res.message.tool_calls:
print(res.message.content)
break
for call in res.message.tool_calls:
fn = tools.get(call.function.name)
out = fn(**call.function.arguments) if fn else "unknown tool"
messages.append({"role": "tool", "tool_name": call.function.name,
"content": str(out)[:8000]})
公式例と同じく、ツールの結果は8,000文字で切り詰めています。検索結果は数千トークンに達することがあり、公式ドキュメントはコンテキスト長を少なくとも約32,000トークンに広げるよう推奨しています。モデルはtools対応のものを選びます。公式例は qwen3:4b です。このループには回数の上限が無いので、本番では前章の互換APIと同じく10回程度で打ち切る条件を足します。ツール呼び出しの一般的な仕組みはAIツール使用(Tool Use)の仕組みと実装判断で解説しています。
料金と無料枠(2026年8月の改定後)
公開時のブログは「個人向けに十分な無料枠があり、より高いレート制限はOllamaのクラウドで提供する」と説明していました。その後、2026年8月31日にトークン単価制の新料金プランが導入されました。新規契約は新料金ですが、既存契約は旧料金体系を継続でき、利用者が設定画面で新料金へ移行できます。
| プラン | 月額 | 含まれる利用枠 | 同時実行 |
|---|---|---|---|
| Free | $0 | スターターモデル向けの少量 | 1 |
| Pro | $20(年$200) | $60分 | 3 |
| Max | $100 | $300分 | 10 |
| Team | $500 | $1,000分(共有) | 10 |
| Enterprise | 個別見積もり | 従量の個別単価 | – |
この表はクラウドモデルの推論に関する枠です。Freeでも利用クレジットを買い足せば全モデルを使え、ローカルで動かす推論は常に無制限です。2026年10月14日に公式の料金ページと2026年8月31日の改定告知を確認したところ、Web検索の単価や無料枠の回数はどちらにも記載がありませんでした。Web検索の公式ドキュメントも「無料アカウントが必要」と書くのみで、上限の数値は非公開です。
実装では、上限到達を例外ではなく通常の分岐として扱います。OllamaのAPIはレート制限の超過時にHTTP 429を返します。互換APIの組み込み検索では返し方が分かれ、Responses APIはHTTP 429のエラー応答(ストリーミング時は失敗イベントにエラーコード rate_limit_exceeded)、Messages APIは前述の web_search_tool_result_error(unavailable)になります。429を受けたら待って再試行し、同じクエリの結果はキャッシュして呼び出し回数を減らします。料金を理由にプランを決めるなら、ollama.com/settings/usage で実際の消費を見てからにしてください。
MCP・Open WebUI・コーディングエージェントからの利用
MCPサーバー経由(Cline・Codex・Goose)
公式はPython製のMCPサーバー(ollama-pythonリポジトリの examples/web-search-mcp.py)を用意しており、MCP対応クライアントにweb_searchとweb_fetchを追加できます。事前にuvをインストールして公式のweb-search-mcp.pyを保存し、設定例のスクリプトパスを保存先の絶対パスへ置き換えてください。Codexなら ~/.codex/config.toml に次を書きます。
[mcp_servers.web_search]
command = "uv"
args = ["run", "path/to/web-search-mcp.py"]
env = { "OLLAMA_API_KEY" = "発行したキー" }
Clineは「Manage MCP Servers」から同じ内容をJSONで登録します。CodexをOllamaのモデルで動かす手順はollama launch codex-appの手順にまとめています。
Open WebUIの検索エンジン設定
Open WebUIは検索エンジンの選択肢に ollama_cloud を持っており、内部で https://ollama.com/api/web_search を呼びます。管理画面のWeb検索設定で選ぶか、起動時の環境変数で指定します(v0.12.0で確認)。Open WebUIは ENABLE_PERSISTENT_CONFIG の既定値がTrueで、一度保存した管理画面の設定を環境変数より優先します。環境変数を書き換えて再起動しても反映されないときは、管理画面で検索エンジンとAPIキーを直してください。最後にチャット入力欄でWeb検索をオンにします。
ENABLE_WEB_SEARCH=true
WEB_SEARCH_ENGINE=ollama_cloud
OLLAMA_CLOUD_API_KEY=発行したキー
古い解説に出てくる ENABLE_RAG_WEB_SEARCH は旧名で、v0.6.10のソースでは既に ENABLE_WEB_SEARCH へ改称されています。Open WebUI自体の導入はOpen WebUIの使い方・インストール・APIキー発行、ファイルを読ませる構成はOllamaでファイルをアップロード・読み込む方法を参照してください。
Pi・OpenClawのWeb検索の自動設定
コーディングエージェントのPiでは、@ollama/pi-web-search パッケージがweb検索とfetchのツールを提供します。ollama launch pi で起動すればパッケージの導入と更新は自動で、手動なら pi install npm:@ollama/pi-web-search です。OpenClawは openclaw configure --section web でプロバイダーに「Ollama Web Search」を選ぶと、ローカルのOllamaを経由して検索します。この場合はAPIキーが不要で、ollama signin だけで動きます。Piの設定全体はPi(pi-coding-agent)をローカルLLMで動かす設定手順で扱っています。
Ollama Web Searchを使うべきでない場面と代替手段
検索基盤を自前で運用せず、APIキーかサインインだけで呼び出せる点が利点です。ただし、次の条件に当てはまるなら採用を見送ります。
- 検索クエリ自体が機密(顧客名、未発表の製品名、社内システム名など)で、社外送信の承認が取れない。
- 1回で10件を超える検索結果が必要、または検索エンジンや地域を指定したい。APIの入力はqueryとmax_resultsだけです。
- 上限や単価が公開されていないサービスに、SLAを前提とした本番処理を載せられない。
代替手段は理由によって分かれます。件数や検索エンジンを自分で決めたいなら、自前でホストするメタ検索エンジンSearXNGが候補で、Open WebUIでも searxng を選べます。ただしSearXNGは外部の検索サービスへ検索語を中継する仕組みなので、機密クエリの問題は解決しません。検索語そのものを社外へ出せない場合は、社内文書だけを対象にした検索基盤やRAGを選びます。どちらも運用の手間は自分で引き受けることになるため、検索基盤を自前で構築したくないプロトタイプや個人利用では、Ollama Web Searchを選べます。社内データと最新のWeb情報を組み合わせて答える仕組みを業務に載せる段階では、AIチャットボット開発として検索範囲とログの扱いから設計します。
よくある質問
Ollama Web Searchは無料で使えますか?
無料のOllamaアカウントがあれば使えます。ただし2026年10月時点で、無料枠の回数や有料時の単価は公式に公開されていません。上限を超えるとHTTP 429が返るため、再試行とキャッシュを前提に組み込みます。
OLLAMA_API_KEYはどこで取得しますか?
ollama.comにサインインし、https://ollama.com/settings/keys で作成します。取得したキーは環境変数 OLLAMA_API_KEY に設定し、Authorization: Bearer ヘッダーで送ります。キーに有効期限はありません。
ローカルのモデルだけでWeb検索できますか?
できません。検索はollama.comのクラウドで実行されるため、インターネット接続とアカウントが必要です。逆に検索を止めたい場合、OLLAMA_NO_CLOUD=1 で止まるのはOllama本体経由の検索だけで、SDKやcURLからの直接呼び出しは止まりません。
Ollamaアプリで「Web search requires an Ollama account」と出たらどうすればいいですか?
未サインインの状態で検索ボタンを押したときの表示です。アプリからサインインするか、ターミナルで ollama signin を実行してください。ボタン自体が出ない場合は、tools対応のモデルを選んでいるか、クラウド無効化の設定が入っていないかを確認します。
1回の検索で何件まで取得できますか?
REST APIは既定5件、最大10件です。Pythonライブラリの web_search() は既定値が3件なので、5件以上ほしいときは max_results を明示します。互換APIの組み込み検索は、1回あたりの取得上限が5件に固定されています。