OpenClawのLLM設定：Ollama・クラウド接続とモデル切り替えの手順

OpenClawでLLMを使うには、Gatewayが動くマシンで接続先と認証を設定し、利用できるモデルを選択して、実際の会話で動作を確認します。最初の設定はopenclaw onboardから始めると、提供元ごとの接続手順を確認しながら進められます。設定済みのモデルを変更する場合は、openclaw models listで正確なモデルIDを調べ、openclaw models setで既定モデルを指定します。公式のモデル設定手順

ローカルLLMなら、まずOllamaのLocal onlyかLM Studioの接続を一つ完成させてください。Ollamaはネイティブの/api/chatを使い、LM StudioとvLLMはOpenAI互換の/v1/chat/completionsを使います。どの接続先にも同じURLやAPI形式を貼り付けると、モデル一覧は見えてもツールが動かない構成になり得ます。

最初に、Gatewayから使える接続先を選ぶ

モデルを実行するのは、通常、チャット画面を開いたブラウザではなくGateway側です。ノートPCにOllamaをインストールしても、Gatewayが別のサーバーやDockerコンテナで動いていれば、同じマシン上の接続にはなりません。まずGatewayの実行場所、OSユーザー、参照している状態ディレクトリを揃えてください。

ローカル構成を選ぶ理由は、手元の推論サーバーを使いたいからです。何GBのメモリなら必ず動く、GPUなら必ず何倍速い、といった一律の目安だけでは選べません。モデルの重み、量子化、コンテキスト長、実行方式によって必要容量が変わります。まず一つのモデルで、短い回答とツール操作を完了できるか確認します。

クラウドLLMを接続する：認証してからモデルを指定する

初回はGatewayホストの対話型ターミナルで次を実行します。

openclaw --version
openclaw gateway status
openclaw onboard

提供元と、そのアカウントで使う認証方式を選び、表示される手順を完了してください。すでに設定済みの環境へ認証を追加するなら、Control UIのSettings → Models → Connect providerも使えます。対象のagentを選んでから接続します。接続情報を保存する操作と、モデルを試して選ぶTest & useは区別されています。現在の接続画面と認証方法

OpenAIはAPIキーとCodexログインを区別する

OpenAI PlatformのAPI課金を使う場合は、APIキーの対話型ログインを選びます。

openclaw models auth login --provider openai --method api-key
openclaw models list --provider openai

ChatGPT/Codexアカウントで利用できるモデルを使う場合は、ブラウザOAuth、またはリモート環境向けのdevice codeを選びます。次の二つは用途に合わせて一方を実行します。

openclaw models auth login --provider openai --method oauth
openclaw models auth login --provider openai --method device-code

現在の正規のモデル参照は、どちらもopenai/モデルIDです。openai/という接頭辞だけでは、API課金かサブスクリプション枠か、どのagent実行方式を使うかは決まりません。選択された認証情報と接続経路を確認します。アカウントで使えるモデルは一覧と実際の要求で確認し、月額プランがすべてのAPI利用を含むとは考えないでください。OpenAIの接続・認証仕様

旧設定にopenai-codexやcodexの参照が残っている場合は、現在の設定と互換性があるかopenclaw doctorで確認します。移行が必要なら、バックアップを取ってから提示された修復を実行してください。古い接頭辞を新規設定へコピーする必要はありません。正規のモデル参照と移行

Anthropic・Gemini・Bedrockも認証を使い回さない

Anthropic APIキーと、GatewayホストにあるネイティブClaude CLIのログインは別の接続です。CLIを再利用するなら、そのホストのclaudeプロセスが認証を管理します。常時稼働するGatewayでは、公式案内はAPIキーによる認証を、課金を明示的に管理しやすい選択肢として勧めています。Anthropicの認証手順

Geminiの通常のAPI接続はgoogle/モデルIDとGoogle AI StudioのAPIキーを使います。google-gemini-cliは別途指定する実行方式で、新規のGemini CLI OAuthやAntigravity OAuth設定は現在のOpenClawで提供されていません。Googleの設定

Amazon BedrockはAWS SDKの認証チェーン、リージョン、対象モデルへのアクセスを確認します。Anthropicのキーを設定しても、Bedrockの認証にはなりません。Bedrockの設定

保存したキーをGatewayが使えることを確認する

ターミナルで設定した環境変数が、systemdやlaunchdのサービスにそのまま届くとは限りません。環境変数方式なら、Gatewayサービスが読む環境に設定します。公式案内にはGatewayホストの~/.openclaw/.envを使う方法があります。対話型オンボーディングで保存する方法も選べます。サービス向けの認証設定

現在の認証情報はSQLiteで管理され、モデルのbaseUrl、API形式、モデルIDなどの接続設定とは役割が異なります。共有認証情報は~/.openclaw/state/openclaw.sqlite、agentローカルの上書きと状態は各agentのopenclaw-agent.sqliteにあります。古いauth-profiles.jsonを直接編集して新しい実行時設定として使わないでください。認証情報の保存仕様

認証を追加・更新しても、既存の既定モデルは通常維持されます。意図して変更するには、モデル選択の操作が必要です。保存後にCLIが再起動を求めた場合や自動再読み込みが無効な場合は、openclaw gateway restartで反映します。認証追加と既定モデルの関係

OllamaのローカルLLMを有効化する

以下はGatewayとOllamaを同じマシンで動かす対話型の手順です。Ollamaを公式ダウンロードページからインストールし、サーバーを起動しておきます。アプリやサービスですでに起動中なら、重ねて別のサーバーを起動する必要はありません。手動起動する構成では、別のターミナルで次を実行して稼働させます。

ollama serve

モデルを取得して動作を確認します。ここでは公式手順にあるgemma4を例にします。ハードウェアに合うモデルを選び、別のモデルを使う場合は以降の名前も、そのマシンの正確なタグへ置き換えてください。

ollama pull gemma4
ollama list
ollama run gemma4

対話が開いたら「短く日本語で挨拶してください」と送って、回答が返ることを確認します。この段階の成功はOllama単体の動作確認です。OpenClawのagentやツールが動いた証明ではありません。Ollamaの公式セットアップ

続いて、Gateway側でオンボーディングを実行します。

openclaw onboard

1. 提供元でOllamaを選びます。
2. モードでLocal onlyを選びます。
3. 同じマシンのOllamaへ接続するため、案内された既定のローカル接続先を確認します。別マシン用のURLに書き換える必要はありません。
4. 検出されたモデルから、使うモデルを選びます。ダウンロードが提案された場合は、サイズと実行環境を確認してから許可します。
5. 実際の短い応答による接続確認まで完了させます。モデルが見つかっただけで設定完了とは判断しません。

初回のガイド付き自動選択は、/api/psで確認できるメモリに読み込み済みのモデルを対象に、/api/showでツール対応と16K以上のコンテキストを確認します。ディスクに取得済みでも、待機中のモデルはこの自動候補に入りません。デスクトップのModel Setupで取得済みモデルを使うなら、OllamaカードのChoose connection → Local onlyから明示的に設定します。この経路はモデルを準備してから実応答を確認できます。自動選択と明示的設定の条件

設定後、OpenClaw側の一覧を確認します。

openclaw models list --provider ollama
openclaw models status

表示された完全な参照を既定モデルに指定します。例えば一覧がollama/gemma4を示した場合は次です。ollama/gemma4:latestなど別の表記なら、実際の一覧の参照をそのまま使います。

openclaw models set ollama/gemma4

OllamaのbaseUrlに/v1を付けるべきですか？

ネイティブOllama接続には付けません。api: "ollama"と、OllamaホストのURLを使い、推論は/api/chatへ送ります。この方式ではストリーミングとツール呼び出しを併用できます。Ollamaの設定、ストリーミングの仕様

/v1とapi: "openai-completions"を指定する方式は、Ollamaの旧来のOpenAI互換接続です。公式はこの経路のツール呼び出しを信頼できる前提にしていません。Ollama向けの古い互換API例を、agent用の標準設定として流用しないでください。一方、LM StudioやvLLMでは互換APIが通常の推論経路なので、そちらの/v1を削除するのも誤りです。

モデルを取得したのに一覧へ出ない場合

ガイド付き自動選択と、通常のモデル一覧の検出を分けて確認します。一般のOllama検出では/api/tagsからインストール済みモデルを調べ、/api/showで能力を読み取ります。初回ガイドの「読み込み済み・ツール対応・16K以上」という候補条件とは同じではありません。モデル検出の仕様

まず同じホストのollama listとOpenClawの一覧を照合してください。明示設定のmodels.providers.ollama.modelsに一つ以上のモデルを記載すると、手動のモデル一覧が使われ、通常の自動検出は省略されます。新しくpullしたモデルがその手動リストへ自動追加されるとは考えないでください。使うモデルの正確なIDを登録するか、適切な自動検出構成へ戻します。

LM Studio・vLLMは互換APIの手順で接続する

LM Studioなら、アプリまたはヘッドレスのllmsterでモデルを用意し、サーバーを起動します。

lms server start --port 1234
openclaw onboard

提供元にLM Studioを選び、同じマシンで動くサーバーの接続先を確認してモデルを選びます。LM Studio側の認証が無効なら、セットアップのキー欄は空にします。認証が有効なら、サーバーで設定したトークンを使用し、環境変数方式ではLM_API_TOKENを設定します。LM Studioの公式手順

LM Studioのモデルキーがqwen/qwen3.5-9bなら、OpenClawでの参照はlmstudio/qwen/qwen3.5-9bです。作者名を含むモデルキーに、提供元の接頭辞を一つ追加します。モデル検出・読み込みにはネイティブの/api/v1/modelsなどを、推論には/v1/chat/completionsを使います。

初回の自動候補はツール学習済みで、有効なコンテキストが16K以上のLLMです。読み込み済みインスタンスのコンテキストが小さい場合、公称最大値だけでは候補条件を満たしません。実応答の確認まで終えてください。JITやTTLによる読み込み・解放と、OpenClawの事前読み込みは別の設定です。

vLLMをすでに運用しているなら、vllm提供元とapi: "openai-completions"を使い、/v1を公開する推論サーバーへ接続します。VLLM_API_KEYは自動検出を有効にする手掛かりになりますが、サーバーが認証を要求するなら本物の対応キーが必要です。認証なしサーバー用の非秘密マーカーでは代用できません。vLLMの設定

LANやtailnet上の別マシンを使う場合、名前をURLへ書くだけでは接続できません。Gatewayからそのホストへ到達でき、推論サーバーがそのマシンのループバック以外でも接続を受け、必要なポートが許可されていることが前提です。手元のPCから成功することと、Gatewayのコンテナから成功することも区別します。

既定モデルと、会話だけのモデル切り替えを分ける

openclaw models setが変更するのはagents.defaults.model.primaryです。既存の会話に固定されたモデルは、その変更だけでは置き換わりません。新しい既定モデルを使いたい会話では、先に/model statusで選択状態を確認します。モデル選択の公式仕様

特定のOllamaモデルを会話で試すなら、例えば次のように選びます。モデル名はその環境の一覧と一致させてください。

/model ollama/gemma4
/model status

そのモデルを試す目的で明示的に選んだ会話は、通常の既定モデルとは復旧動作も異なります。選択したモデルが失敗しても、別のモデルが黙って回答する構成にはなりません。既定の復旧設定を使うなら、会話で次を実行して固定を解除します。

/model default
/model status

モデルに短い別名を付けるagents.defaults.modelsと、選択制限のagents.defaults.modelPolicy.allowも別です。別名を書くだけでは新しい実行モデルは登録されません。カスタム提供元はmodels.providersにAPI形式、接続先、正確なモデルIDを登録します。選択を制限したい場合にだけ、明示的な許可リストを使います。カスタムモデルの登録

fallbackは、使える二つ目のモデルを確認してから追加する

既定モデルの失敗に備えるなら、候補を一つずつ動作確認してからfallbackへ追加します。まず一覧を見て、追加したい完全なモデル参照を確認します。次のSECOND_MODEL_REFには、確認済みの参照を入れます。

SECOND_MODEL_REF='確認済みのprovider/modelに置き換える'
openclaw models fallbacks add "$SECOND_MODEL_REF"
openclaw models fallbacks list
openclaw models status

この操作は既定モデル用のagents.defaults.model.fallbacksを管理します。現在のOpenClawは、該当する一時的な失敗には回数を限定した同一モデルの回復を試し、提供元内の認証プロファイル切り替えを経て、許可されている次のモデルへ進みます。現在のfallbackはそのターンに適用され、会話の選択モデル自体を次回用に書き換えません。fallbackと選択元の仕様

個別agentに独自のprimaryを設定した場合は、そのagent自身のmodel.fallbacksで復旧を有効にする必要があります。fallbacks: []は無効化の明示です。会話で具体的なモデルを固定した場合も、その選択は厳密に扱われます。「fallbackを設定したのに別モデルへ移らない」場合は、まずこの二つを確認してください。

fallbackは用途別に安いモデルへ仕事を自動配分する仕組みではありません。障害時の回復候補です。実行全体の期限、キャンセル、費用制限などで停止する場合もあり、すでに実行されたツールの副作用を取り消すものでもありません。

ローカル専用にしたい場合はクラウド経路も確認する

OllamaのCloud + Localでは、同じOllamaホストを経由していても、:cloudモデルの推論はクラウド側です。直接ホスト型サービスを使う場合は、ローカルのollamaと分けたollama-cloudも選べます。公開リモートホストやOllama Cloudには実際の認証情報が必要です。Ollamaのモードと認証ルール

ローカルモデルをprimaryにしただけでは、OpenClaw全体の外部通信はなくなりません。クラウドfallback、メモリ用の埋め込み、検索、プラグインやツールの接続先も確認します。データを外へ出さない運用なら、推論先だけでなく、実際に使う機能ごとに接続先を点検してください。

動作確認は「一覧・選択・応答・ツール」の順に行う

図は確認手順のイメージです。実際の画面や検証結果を示すものではありません。

以下を同じGateway、agent、会話で順番に確認すると、どこまで成功したかを区別できます。CLIが対象agentを省略した場合に意図と違うagentを調べないよう、複数agentを使う環境では--agentで実際のIDを指定します。

ツール確認には、対象agentのワークスペース内にllm-setup-check.txtを作り、推測では答えられない任意の確認文字列を一つ書きます。例えばCHECK-20261004-K7です。そのファイル以外を変更する必要はありません。

会話では、次のように依頼します。

ワークスペースのllm-setup-check.txtを読み取り専用のツールで開き、
書かれている確認文字列をそのまま返してください。
ほかのファイルの変更や外部への送信は行わないでください。

実行履歴に本当の読み取りツール呼び出しがあり、返された内容がファイルと一致することを成功条件にします。単に「読みました」と答えたり、JSON/XML形式のツール名を本文へ出力したりするだけなら、ツール実行の成功ではありません。実行権限で止まった場合は、許可された読み取りツールとワークスペースを確認します。モデルに接続できない場合と分けてください。

Ollamaで短い生成だけを切り分けたい場合は、次のような限定した確認も使えます。モデル参照は取得済みのものに置き換えます。

openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"

この確認は通常のチャットツール、メモリ、会話のコンテキストを読み込みません。成功しても、agentのツール操作まで成功したとは判断できません。限定した確認の範囲

models status --probeを実行する場合の前提

通常のmodels statusはモデル呼び出しテストではありません。--checkの終了コード0も、設定された経路に認証・実行方式の問題が見つからなかったという意味です。状態表示の読み方

--probeは実要求を行い、トークン消費やレート制限を伴います。現在の直接probeは状態ディレクトリの排他的な使用を必要とするため、稼働中のGatewayを停止してから実行し、probeと後処理が終了してから起動し直します。タイムアウトだけでは状態ロックの解放完了を確認できません。常時稼働環境では停止時間を確保してください。通常の初回確認なら、上の同じ会話での短い応答と読み取り操作から始められます。probeの制約

応答しない・ツールが動かないときの確認先

vLLMでツール構文が文章として出る場合は、まずそのモデルに対応したtool-call parserとchat templateを確認します。全モデルにtool_choice: "required"を設定する方法は標準解決策ではありません。モデル固有の回避策は、通常のautoでの結果と、毎ターンツールを強制する影響を確かめてから選びます。vLLMのツール切り分け

コンテキスト調整では、contextWindowはモデルのネイティブな上限情報、contextTokensはOpenClawの有効入力予算、maxTokensは出力上限です。Ollamaの明示的なparams.num_ctxは実際の要求コンテキストへ影響します。公称上限を大きく書けばモデルが強くなるわけではないため、サーバーで動かせる値と揃えます。Ollamaのコンテキスト設定

初回読み込みが原因のタイムアウトなら、提供元のtimeoutSecondsや、Ollamaのモデル単位のkeep_aliveを検討できます。ただし、接続先が間違っている状態で待ち時間を延ばしても直りません。実行全体の期限が短ければ、提供元のタイムアウトだけでは延長できない点にも注意してください。Ollamaの調整例

401やinvalid bearer tokenが残る場合は、OpenClawの401認証エラーを切り分ける手順へ進んでください。Gateway接続トークン、モデルAPIキー、CLIログイン、agentローカルの上書きを区別して確認できます。

よくある質問

OpenClawにAPIキーは必須ですか？

すべての接続で必須ではありません。ローカル・LANのOllamaは本物のベアラートークンを必要とせず、OpenClawはollama-localマーカーを使います。公開リモートホストとOllama Cloudには実際の認証が必要です。クラウド提供元でも、利用可能なOAuth方式とAPIキー方式は別なので、選んだ接続の条件に従います。Ollamaの認証ルール

小さいローカルLLMでもagentとして使えますか？

使えるかは、テキスト生成に加えてツールを扱えるか、必要なコンテキストを実行環境で確保できるかで判断します。まず短い回答と確認用ファイルの読み取りを分けて試してください。初回Ollamaガイドの自動候補は、読み込み済み・ツール対応・16K以上の条件を確認します。モデルのパラメータ数だけで成功や速度は保証できません。選択条件

models setを実行したのに、チャットのモデルが変わらないのはなぜですか？

会話にモデルが固定されているか、個別agentに別のprimaryが設定されている可能性があります。その会話の/model statusを見てください。既定へ戻したい場合は/model defaultで会話の固定を解除します。CLIの設定状態だけでは、会話固有の選択は分かりません。モデル選択と会話

Ollamaを使えば料金は必ずゼロになりますか？

必ずゼロになるとは限りません。モデルの設定情報にあるcost: 0は実際の請求書ではありません。ローカル推論にも機器・電力・運用の費用があり、:cloudモデルやクラウドfallback、外部ツールは別の利用条件です。どのホストとアカウントへ要求が送られるかを確認してください。モードの違い、カスタム提供元のcost初期値

fallbackを設定すれば、会話で選んだモデルの障害にも対応できますか？

具体的なモデルを明示選択した会話は厳密な選択として扱われ、別モデルへ黙って移りません。既定モデルのfallbackを使いたいなら、/model defaultでその会話を既定へ戻します。個別agentに独自primaryがある場合は、そのagentのfallback設定も確認します。選択元ごとの復旧動作

この記事は2026年10月4日に確認した公式資料に基づく設定ガイドです。OpenClaw・Ollama・LM Studioの実機検証、有料モデルへの呼び出し、GPU速度比較は実施していません。コマンドの結果とツール実行記録を使い、ご自身の接続で動作を確認できる手順として示しています。