Providers

Ollama

OpenClaw 會與 Ollama 的原生 API（/api/chat）通訊，而不是與 OpenAI 相容的 /v1 端點。支援三種模式：

模式	使用項目
雲端 + 本機	可連線的 Ollama 主機，提供本機模型以及（若已登入）`:cloud` 模型
僅雲端	直接使用 `https://ollama.com`，不使用本機常駐程式
僅本機	可連線的 Ollama 主機，僅提供本機模型

若要使用專用的 ollama-cloud 提供者 ID 進行純雲端設定，請參閱 Ollama Cloud。若要讓雲端路由與本機 ollama 提供者保持分離，請使用 ollama-cloud/<model> 參照。

標準設定鍵為 baseUrl。OpenAI SDK 風格的範例也接受 baseURL，但新設定應使用 baseUrl。

驗證規則

本機與區域網路主機

回送、私人網路、.local 及僅含主機名稱的 Ollama URL 不需要真正的持有人權杖。OpenClaw 會對這些主機使用 ollama-local 標記。

遠端與 Ollama Cloud 主機

公開遠端主機與 https://ollama.com 需要真正的認證資訊：OLLAMA_API_KEY、驗證設定檔，或提供者的 apiKey。若要直接使用託管服務，建議使用 ollama-cloud 提供者。

自訂提供者 ID

使用 api: "ollama" 的自訂提供者遵循相同規則。例如，指向私人區域網路主機的 ollama-remote 提供者可以使用 apiKey: "ollama-local"；子代理程式會透過 Ollama 提供者鉤子解析該標記，而不會將其視為缺少認證資訊。memory.search.provider 也可指向自訂提供者 ID，讓嵌入使用該 Ollama 端點。

驗證設定檔

auth-profiles.json 會儲存提供者 ID 的認證資訊；請將端點設定（baseUrl、api、模型、標頭、逾時）放在 models.providers.<id> 中。{ "ollama-windows": { "apiKey": "ollama-local" } } 等舊版平面檔案不是執行階段格式；openclaw doctor --fix 會將其重寫為標準的 ollama-windows:default API 金鑰設定檔，並建立備份。該舊版檔案中的 baseUrl 值是雜訊，應移至提供者設定。

記憶嵌入範圍

Ollama 記憶嵌入的持有人驗證範圍僅限其宣告的主機：

提供者層級的金鑰只會傳送至該提供者的主機。
memory.search.remote.apiKey 與各代理程式覆寫只會傳送至其遠端嵌入主機。
純 OLLAMA_API_KEY 環境變數值會被視為 Ollama Cloud 慣例，預設不會傳送至本機／自行託管的主機。

開始使用

初始設定（建議）

執行初始設定

bash

openclaw onboard

選取 Ollama，然後選擇模式：雲端 + 本機、僅雲端 或 僅本機。

在全新的引導式設定中，OpenClaw 會先檢查預設或已設定的 Ollama 主機。只有當 /api/show 確認支援工具，且上下文視窗至少為 16K 時，才會自動提供已安裝的模型；若缺少上下文中繼資料或大小較小，則會繼續使用手動設定流程。共用的命令列介面／macOS 設定階梯仍會在儲存前，透過實際補全來驗證所選路由。此自動檢查絕不會提取模型；如果不存在合適的已安裝模型，初始設定會繼續使用一般的 Ollama 選擇器。

選取模型

Cloud only 會提示輸入 OLLAMA_API_KEY，並建議託管的雲端預設值。Cloud + Local 與 Local only 會提示輸入 Ollama 基礎 URL、探索可用模型，並在缺少所選本機模型時自動提取。已安裝的 :latest 標籤（例如 gemma4:latest）只會顯示一次，而不會重複 gemma4。Cloud + Local 也會檢查主機是否已登入以取得雲端存取權。

驗證

bash

openclaw models list --provider ollama

非互動式：

bash

openclaw onboard --non-interactive \  --auth-choice ollama \  --custom-base-url "http://ollama-host:11434" \  --custom-model-id "qwen3.5:27b" \  --accept-risk

--custom-base-url 與 --custom-model-id 為選用項目；省略它們會使用本機預設主機與 gemma4 建議模型。

手動設定

安裝並啟動 Ollama

從 ollama.com/download 取得，然後提取模型：

bash

ollama pull gemma4

若要使用混合雲端存取，請在同一部主機上執行 ollama signin。

設定認證資訊

bash

export OLLAMA_API_KEY="ollama-local"    # 本機／區域網路主機，任何值皆可export OLLAMA_API_KEY="your-real-key"   # 僅適用於 https://ollama.com

或在設定中使用：openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"。

選取模型

bash

openclaw models listopenclaw models set ollama/gemma4

或在設定中使用：

json5

{  agents: {    defaults: {      model: { primary: "ollama/gemma4" },    },  },}

透過本機主機使用雲端模型

Cloud + Local 會透過單一可連線的 Ollama 主機路由本機與 :cloud 模型。這是 Ollama 的混合流程；若兩者都要使用，請在設定期間選擇此模式。

OpenClaw 會提示輸入基礎 URL、探索本機模型，並檢查 ollama signin 狀態。登入後，它會建議託管的預設值（kimi-k2.5:cloud、minimax-m2.7:cloud、glm-5.1:cloud、glm-5.2:cloud）。若未登入，設定會維持僅本機模式，直到執行 ollama signin。

若要在沒有本機常駐程式的情況下僅存取雲端，請使用 openclaw onboard --auth-choice ollama-cloud 並參閱 Ollama Cloud；該路徑不需要 ollama signin 或執行中的伺服器：

bash

openclaw onboard --auth-choice ollama-cloudopenclaw models set ollama-cloud/kimi-k2.5:cloud

openclaw onboard 期間顯示的雲端模型清單會即時從 https://ollama.com/api/tags 填入，上限為 500 個項目，因此選擇器會反映目前的託管目錄。如果在設定時無法連線至 ollama.com，或它未傳回任何模型， OpenClaw 會改用其硬式編碼的建議清單，讓初始設定仍可完成。

模型探索（隱含提供者）

當已設定 OLLAMA_API_KEY（或驗證設定檔），且未定義 models.providers.ollama 或其他使用 api: "ollama" 的自訂提供者時， OpenClaw 會從 http://127.0.0.1:11434 探索模型：

行為	詳細資料
目錄查詢	`/api/tags`
功能偵測	盡力透過 `/api/show` 讀取 `contextWindow`、`num_ctx` Modelfile 參數與功能（視覺／工具／思考）
視覺模型	來自 `/api/show` 的 `vision` 功能會將模型標記為支援影像（`input: ["text", "image"]`）
推理偵測	可用時使用來自 `/api/show` 的 `thinking` 功能；當 Ollama 省略功能時，則改用名稱啟發法（`r1`、`reason`、`reasoning`、`think`）。無論回報的功能為何，`glm-5.2:cloud` 與 `deepseek-v4-flash\|pro:cloud` 一律視為推理模型。
權杖限制	`maxTokens` 預設為 OpenClaw 的 Ollama 最大權杖上限
成本	所有成本皆為 `0`

bash

ollama listopenclaw models list

使用明確的 models 陣列設定 models.providers.ollama，或使用具有 api: "ollama" 與非回送 baseUrl 的自訂提供者，會停用自動探索；之後必須手動定義模型（請參閱設定）。指向託管 https://ollama.com 的 models.providers.ollama 項目也會略過探索，因為 Ollama Cloud 模型由提供者管理。 http://127.0.0.2:11434 等回送自訂提供者仍視為本機提供者，並保留自動探索。

你可以使用 ollama/<pulled-model>:latest 這類完整參照，而不必手動撰寫 models.json 項目；OpenClaw 會即時解析。對於已登入的主機，選取未列出的 ollama/<model>:cloud 參照時，會透過 /api/show 驗證該確切模型，且只有在 Ollama 確認中繼資料後才會將其加入執行階段目錄；拼字錯誤仍會因未知模型而失敗。

煙霧測試

若要執行略過完整代理程式工具介面的精簡文字探查：

bash

OLLAMA_API_KEY=ollama-local \  openclaw infer model run \    --local \    --model ollama/llama3.2:latest \    --prompt "僅回覆以下內容：pong" \    --json

加入 --file 與影像，即可執行精簡的視覺模型探查（接受 PNG／JPEG／WebP；非影像檔案會在呼叫 Ollama 前遭拒絕；音訊請使用 openclaw infer audio transcribe）：

bash

OLLAMA_API_KEY=ollama-local \  openclaw infer model run \    --local \    --model ollama/qwen2.5vl:7b \    --prompt "用一句話描述此影像。" \    --file ./photo.jpg \    --json

這兩種路徑都不會載入聊天工具、記憶或工作階段上下文。如果它能成功，但一般代理程式回覆失敗，問題可能出在模型的工具／代理程式能力，而不是端點。

使用 /model ollama/<model> 選擇模型是使用者的明確選擇：如果已設定的 baseUrl 無法連線，下一則回覆會因提供者錯誤而失敗，而不會默默改用另一個已設定的模型。

獨立的排程工作會在開始代理程式回合前增加一項本機安全檢查：如果所選模型解析為本機／私人網路／.local Ollama 提供者，且 /api/tags 無法連線，OpenClaw 會將該次執行記錄為 skipped，並在錯誤文字中包含模型。此端點檢查會依主機快取 5 分鐘，因此針對已停止常駐程式的重複排程工作，不會全部都發出注定失敗的要求。

即時驗證：

bash

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \  pnpm test:live -- extensions/ollama/ollama.live.test.ts

若使用 Ollama Cloud，請將同一個即時測試指向託管端點（預設略過嵌入；由於雲端金鑰可能未授權 /api/embed，可使用 OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 強制執行）：

bash

export OLLAMA_API_KEY='<your-ollama-cloud-api-key>'OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 \OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \pnpm test:live -- extensions/ollama/ollama.live.test.ts

若要新增模型，請拉取模型，系統就會自動探索：

bash

ollama pull mistral

節點本機推論

代理程式可將短任務委派給已配對桌面或伺服器節點上的 Ollama 模型。提示詞與回應會透過現有且已驗證的閘道／節點連線傳輸；要求會在節點本身的迴路 Ollama 端點（http://127.0.0.1:11434）上執行。

在節點上啟動 Ollama

bash

ollama pull qwen3:0.6bollama list

連線節點主機

bash

openclaw node run \  --host <gateway-host> \  --port 18789 \  --display-name "Local inference"

在閘道主機上核准裝置及其節點命令，然後進行驗證：

bash

openclaw devices listopenclaw devices approve <deviceRequestId>openclaw nodes pendingopenclaw nodes approve <nodeRequestId>openclaw nodes status --connected

首次連線或新增 Ollama 命令的升級可能會觸發節點命令核准。如果節點連線時未公告 ollama.models 和 ollama.chat，請再次檢查 openclaw nodes pending。

從代理程式使用

隨附的 Ollama 外掛會公開 node_inference 工具。代理程式會先呼叫 action: "discover"，再使用該結果中的節點和模型呼叫 action: "run" （只連線一個具備能力的節點時，run 可省略節點）。例如：「探索我各節點上的 Ollama 模型，然後使用已載入且速度最快的模型摘要這段文字。」

探索會讀取 /api/tags、檢查 /api/show 功能，並在可用時使用 /api/ps，優先排列已載入的模型。它只會傳回 Ollama 回報為支援聊天的本機模型（completion 功能）— Ollama Cloud 項目與僅限嵌入的模型會被排除。除非工具呼叫要求不同的 maxTokens，每次執行都會停用模型思考，並將輸出預設為 512 個權杖（硬上限為 8192）；部分模型（例如 GPT-OSS）不支援停用思考，因此仍可能輸出推理權杖。

若要讓 Ollama 持續在節點上執行，但不向代理程式公開：

bash

openclaw config set plugins.entries.ollama.config.nodeInference.enabled false

重新啟動節點（openclaw node restart；若是前景工作階段，則停止並重新執行 openclaw node run）。節點將停止公告 ollama.models 和 ollama.chat；Ollama 本身與閘道的 Ollama 提供者不受影響。將值設回 true 並重新啟動即可重新啟用；重新連線後，變更的命令介面可能需要再次核准 openclaw nodes pending。

不經過代理程式回合，直接驗證節點命令：

bash

openclaw nodes invoke \  --node "Local inference" \  --command ollama.models \  --params '{}' \  --invoke-timeout 90000 \  --timeout 100000 openclaw nodes invoke \  --node "Local inference" \  --command ollama.chat \  --params '{"model":"qwen3:0.6b","prompt":"Reply with exactly: pong","maxTokens":32,"timeoutMs":120000}' \  --invoke-timeout 130000 \  --timeout 140000

--invoke-timeout 限制節點執行命令的時間； --timeout 限制整體閘道呼叫的時間，且應設得更長。

節點本機推論一律使用節點本身的迴路端點，不會重複使用已設定的遠端／雲端 models.providers.ollama.baseUrl。節點命令預設可在 macOS、Linux 和 Windows 節點主機上使用，且仍受一般節點配對／命令原則約束。

視覺與影像描述

隨附的 Ollama 外掛會將 Ollama 註冊為支援影像的媒體理解提供者，因此 OpenClaw 可透過本機或託管的 Ollama 視覺模型，路由明確的影像描述要求和已設定的影像模型預設值。

bash

ollama pull qwen2.5vl:7bexport OLLAMA_API_KEY="ollama-local"openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json

--model 必須是完整的 <provider/model> 參照；設定後，infer image describe 會先嘗試該模型，而不會因模型已支援原生視覺而略過描述。如果呼叫失敗，OpenClaw 可繼續依序嘗試 agents.defaults.imageModel.fallbacks；檔案／URL 準備錯誤會在嘗試後援之前直接失敗。使用 infer image describe 執行 OpenClaw 的影像理解流程與已設定的 imageModel；使用 infer model run --file 搭配自訂提示詞進行原始多模態探測。

若要讓 Ollama 成為傳入媒體的預設影像理解提供者：

json5

{  agents: {    defaults: {      imageModel: {        primary: "ollama/qwen2.5vl:7b",      },    },  },}

建議使用完整的 ollama/<model> 參照。只有當像 qwen2.5vl:7b 這樣的裸 imageModel 參照，以該確切模型列於 models.providers.ollama.models 下且具有 input: ["text", "image"]，並且沒有其他已設定的影像提供者公開相同裸 ID 時，才會正規化為 ollama/qwen2.5vl:7b；否則請明確使用提供者前綴。

相較於雲端模型，較慢的本機視覺模型可能需要更長的影像理解逾時；如果 Ollama 嘗試配置模型所公告的完整視覺上下文，也可能在資源受限的硬體上當機。請設定功能逾時並限制 num_ctx：

json5

{  models: {    providers: {      ollama: {        models: [          {            id: "qwen2.5vl:7b",            name: "qwen2.5vl:7b",            input: ["text", "image"],            params: { num_ctx: 2048, keep_alive: "1m" },          },        ],      },    },  },  tools: {    media: {      image: {        timeoutSeconds: 180,        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],      },    },  },}

此逾時適用於傳入影像理解和明確的 image 工具。對一般模型呼叫而言，models.providers.ollama.timeoutSeconds 仍控制底層 Ollama HTTP 要求的防護機制。

即時驗證：

bash

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts

如果你手動定義 models.providers.ollama.models，請明確標記視覺模型：

json5

{  id: "qwen2.5vl:7b",  name: "qwen2.5vl:7b",  input: ["text", "image"],  contextWindow: 128000,  maxTokens: 8192,}

OpenClaw 會拒絕未標記為支援影像的模型所收到的影像描述要求。使用隱式探索時，此資訊來自 /api/show 的視覺功能。

設定

基本（隱式探索）

bash

export OLLAMA_API_KEY="ollama-local"

明確設定（手動模型）

若使用託管雲端設定、非預設主機／連接埠、強制上下文視窗或完全手動的模型清單，請使用明確設定：

json5

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 128000,            maxTokens: 8192          }        ]      }    }  }}

自訂基底 URL

明確設定會停用自動探索，因此必須列出模型：

json5

{  models: {    providers: {      ollama: {        apiKey: "ollama-local",        baseUrl: "http://ollama-host:11434", // 不含 /v1 — 原生 Ollama API URL        api: "ollama", // 明確指定：確保原生工具呼叫行為        timeoutSeconds: 300, // 選用：為冷啟動本機模型提供更長的連線／串流時間預算        models: [          {            id: "qwen3:32b",            name: "qwen3:32b",            params: {              keep_alive: "15m", // 選用：在回合之間保持模型載入            },          },        ],      },    },  },}

常見做法

請將模型 ID 替換為 ollama list 或 openclaw models list --provider ollama 中的確切名稱。

使用自動探索的本機模型

Ollama 與閘道位於同一台機器上，並自動探索：

bash

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

除非你需要手動模型，否則請勿新增 models.providers.ollama 區塊。

使用手動模型的區域網路 Ollama 主機

json5

{  models: {    providers: {      ollama: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            reasoning: true,            input: ["text"],            params: {              num_ctx: 32768,              thinking: false,              keep_alive: "15m",            },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/qwen3.5:9b" },    },  },}

contextWindow 是 OpenClaw 的上下文預算；params.num_ctx 會傳送至 Ollama。當硬體無法執行模型所公告的完整上下文時，請讓兩者保持一致。

僅使用 Ollama Cloud

不使用本機常駐程式，直接使用託管模型：

bash

export OLLAMA_API_KEY="your-ollama-api-key"

json5

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            contextWindow: 128000,            maxTokens: 8192,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/kimi-k2.5:cloud" },    },  },}

若要使用專用的 ollama-cloud 提供者 ID，而非此結構，請參閱 Ollama Cloud。

透過已登入的常駐程式同時使用雲端與本機

bash

ollama signinollama pull gemma4

json5

{  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        models: [          { id: "gemma4", name: "gemma4", input: ["text"] },          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },        ],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama/gemma4",        fallbacks: ["ollama/kimi-k2.5:cloud"],      },    },  },}

多個 Ollama 主機

執行多個 Ollama 伺服器時可使用自訂提供者 ID；每個提供者都有各自的主機、模型、驗證與逾時設定。

json5

{  models: {    providers: {      "ollama-fast": {        baseUrl: "http://mini.local:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],      },      "ollama-large": {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 420,        contextWindow: 131072,        maxTokens: 16384,        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama-fast/gemma4",        fallbacks: ["ollama-large/qwen3.5:27b"],      },    },  },}

OpenClaw 會先移除目前使用中的提供者前綴（若無則退回使用不含限定詞的 ollama/ 前綴），再呼叫 Ollama，因此 ollama-large/qwen3.5:27b 傳到 Ollama 時會成為 qwen3.5:27b。

精簡的本機模型設定檔

某些本機模型能處理簡單的提示詞，但難以應付完整的代理程式工具介面。修改全域執行階段設定前，請先限制工具與上下文：

json5

{  agents: {    list: [      {        id: "local",        experimental: {          localModelLean: true,        },        model: { primary: "ollama/gemma4" },      },    ],  },  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [          {            id: "gemma4",            name: "gemma4",            input: ["text"],            params: { num_ctx: 32768 },            compat: { supportsTools: false },          },        ],      },    },  },}

僅在模型或伺服器確實會因工具結構描述而失敗時使用 compat.supportsTools: false，因為它會以代理程式能力換取穩定性。除非明確要求，localModelLean 會從代理程式直接介面移除重量級的瀏覽器、排程、訊息、媒體生成、語音及 PDF 工具，並將較大的目錄置於「工具搜尋」之後。它不會變更 Ollama 的執行階段上下文或思考模式。對於會陷入迴圈或將額度耗費在隱藏推理上的小型 Qwen 類思考模型，請將其與 params.num_ctx 及 params.thinking: false 搭配使用。

模型選擇

json5

{  agents: {    defaults: {      model: {        primary: "ollama/gpt-oss:20b",        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],      },    },  },}

自訂提供者 ID 的運作方式相同：對於使用目前提供者前綴的參照（例如 ollama-spark/qwen3:32b），OpenClaw 會先移除該前綴，再呼叫 Ollama，並傳送 qwen3:32b。

對於速度較慢的本機模型，請優先調整提供者範圍內的設定，再考慮提高整個代理程式執行階段的逾時時間：

json5

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

timeoutSeconds 涵蓋模型 HTTP 請求：連線設定、標頭、本文串流，以及受保護擷取作業的總體中止。原生 /api/chat 請求會將 params.keep_alive 轉送為頂層 keep_alive；若首次回合的載入時間是瓶頸，請針對每個模型設定此值。

快速驗證

bash

# 此機器可連線至 Ollama 常駐程式curl http://127.0.0.1:11434/api/tags # OpenClaw 目錄與所選模型openclaw models list --provider ollamaopenclaw models status # 直接模型冒煙測試openclaw infer model run \  --model ollama/gemma4 \  --prompt "請完全依照以下內容回覆：ok"

對於遠端主機，請將 127.0.0.1 替換為 baseUrl 主機。如果 curl 可正常運作但 OpenClaw 無法運作，請檢查閘道是否在不同的機器、容器或服務帳號中執行。

Ollama 網頁搜尋

OpenClaw 內建 Ollama 網頁搜尋，作為 web_search 提供者。

屬性	詳細資訊
主機	若已設定則使用 `models.providers.ollama.baseUrl`，否則使用 `http://127.0.0.1:11434`；`https://ollama.com` 會直接使用託管 API
驗證	已登入的本機主機不需要金鑰；直接進行 `https://ollama.com` 搜尋或使用受驗證保護的主機時，需使用 `OLLAMA_API_KEY` 或已設定的提供者驗證資訊
必要條件	本機／自行託管的主機必須正在執行，且已使用 `ollama signin` 登入；直接託管搜尋需使用 `baseUrl: "https://ollama.com"` 加上真實的 API 金鑰

請在 openclaw onboard 或 openclaw configure --section web 期間選擇它，或設定：

json5

{  tools: {    web: {      search: {        provider: "ollama",      },    },  },}

若要透過 Ollama Cloud 直接進行託管搜尋：

json5

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],      },    },  },  tools: {    web: {      search: { provider: "ollama" },    },  },}

對於自行託管的主機，OpenClaw 會先嘗試本機 /api/experimental/web_search Proxy，接著退回同一主機上的託管 /api/web_search 路徑；已登入的本機常駐程式通常會透過本機 Proxy 回應。直接呼叫 https://ollama.com 一律使用託管的 /api/web_search 端點。

進階設定

舊版 OpenAI 相容模式

對於位於 /v1/chat/completions 後方的 Proxy，請明確設定 api: "openai-completions"：

json5

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // 預設值：true        apiKey: "ollama-local",        models: [...]      }    }  }}

此模式可能不支援同時使用串流與工具呼叫；你可能需要在模型上設定 params: { streaming: false }。

在此模式下，OpenClaw 預設會注入 options.num_ctx，以免 Ollama 在未提示的情況下退回 4096 個權杖的上下文。如果你的 Proxy 拒絕未知的 options 欄位，請將其停用：

json5

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

上下文視窗

對於自動探索到的模型，OpenClaw 會使用 /api/show 回報的上下文視窗，包括自訂 Modelfile 中較大的 PARAMETER num_ctx 值；否則會退回使用 OpenClaw 的預設 Ollama 上下文視窗。

提供者層級的 contextWindow、contextTokens 和 maxTokens 會為該提供者下的每個模型設定預設值，並可由個別模型覆寫。contextWindow 是 OpenClaw 自身的提示詞／壓縮額度。除非你明確設定 params.num_ctx，否則原生 /api/chat 請求會讓 options.num_ctx 保持未設定，因此 Ollama 會套用自己的模型預設值、OLLAMA_CONTEXT_LENGTH 或依 VRAM 決定的預設值；無效、零、負數或非有限的 params.num_ctx 值會被忽略。如果較舊的設定僅使用 contextWindow/maxTokens 強制指定原生請求上下文，請執行 openclaw doctor --fix，將這些值複製到 params.num_ctx。OpenAI 相容轉接器仍會預設依據已設定的 params.num_ctx 或 contextWindow 注入 options.num_ctx；若上游拒絕 options，請使用 injectNumCtxForOpenAICompat: false 停用。

原生模型項目也接受 params 下的常見 Ollama 執行階段選項，並以原生 /api/chat options 轉送：num_keep、seed、 num_predict、top_k、top_p、min_p、typical_p、repeat_last_n、 temperature、repeat_penalty、presence_penalty、frequency_penalty、 stop、num_batch、num_gpu、main_gpu、use_mmap 和 num_thread。少數鍵（format、keep_alive、truncate、shift）會以頂層請求欄位轉送，而非巢狀的 options。OpenClaw 僅會轉送這些 Ollama 請求鍵，因此僅供執行階段使用的參數（例如 streaming）絕不會傳送至 Ollama。使用 params.think（或 params.thinking）設定頂層 think；false 會停用 Qwen 類思考模型的 API 層級思考功能。

json5

{  models: {    providers: {      ollama: {        contextWindow: 32768,        models: [          {            id: "llama3.3",            contextWindow: 131072,            maxTokens: 65536,            params: {              num_ctx: 32768,              temperature: 0.7,              top_p: 0.9,              thinking: false,            },          }        ]      }    }  }}

每個模型的 agents.defaults.models["ollama/<model>"].params.num_ctx 也適用；如果兩者皆有設定，會以明確的供應商模型項目為準。

思考控制

OpenClaw 會依照 Ollama 的預期轉送思考設定：使用頂層的 think，而非 options.think。自動探索且其 /api/show 回報 thinking 功能的模型，會提供 /think low、/think medium、/think high 和 /think max；非思考模型則只提供 /think off。

bash

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

或設定模型預設值：

json5

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

每個模型的 params.think/params.thinking 可針對特定模型停用或強制啟用 API 思考。當作用中的執行只有隱含的 off 預設值時，OpenClaw 會保留該明確設定；非關閉狀態的執行階段命令（例如 /think medium）仍會覆寫它。若模型明確標記為 reasoning: false，絕不會向其傳送真值的思考要求；無論如何都會傳送 think: false 要求。

推理模型

名稱為 deepseek-r1、reasoning、reason 或 think 的模型，預設會視為具備推理能力，不需要額外設定：

bash

ollama pull deepseek-r1:32b

模型成本

Ollama 在本機執行且免費，因此自動探索與手動定義模型的所有模型成本皆為 0。

記憶嵌入

隨附的 Ollama 外掛會為記憶搜尋註冊記憶嵌入供應商。它會使用已設定的 Ollama 基礎 URL 和 API 金鑰、呼叫 /api/embed，並在可行時將多個記憶區塊批次放入單一 input 要求中。

當 proxy.enabled=true 時，向由已設定的 baseUrl 衍生出的精確主機本機回送來源所提出的嵌入要求，會使用 OpenClaw 受防護的直接路徑，而非受管理的轉送 Proxy。設定的主機名稱本身必須是 localhost 或回送 IP 常值；僅透過 DNS 解析為回送位址的名稱仍會使用受管理的 Proxy 路徑。LAN、tailnet、私人網路與公用 Ollama 主機一律使用受管理的 Proxy 路徑，重新導向至其他主機／連接埠也不會繼承信任。 proxy.loopbackMode: "proxy" 仍會透過 Proxy 路由回送流量；proxy.loopbackMode: "block" 則會在連線前拒絕該流量；請參閱受管理的 Proxy。

屬性	值
預設模型	`nomic-embed-text`
自動提取	是，若本機尚未存在
預設行內並行數	1（其他供應商的預設值較高；若主機可承受，請使用 `nonBatchConcurrency` 提高）

查詢階段的嵌入會針對要求或建議使用擷取前綴的模型套用此前綴： nomic-embed-text、qwen3-embedding 和 mxbai-embed-large。文件批次會維持原始內容，因此現有索引不需要格式遷移。

json5

{  memory: {    search: {      provider: "ollama",      remote: {        // Ollama 的預設值。如果在較大型主機上重新建立索引太慢，請提高此值。        nonBatchConcurrency: 1,      },    },  },}

若使用遠端嵌入主機，請將驗證範圍限制在該主機：

json5

{  memory: {    search: {      provider: "ollama",      model: "nomic-embed-text",      remote: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        nonBatchConcurrency: 2,      },    },  },}

串流設定

Ollama 預設使用原生 API（/api/chat），同時支援串流與工具呼叫，不需要特殊設定。

對於原生要求，思考控制會直接轉送：除非已明確設定 params.think/params.thinking，否則 /think off 和 openclaw agent --thinking off 會傳送頂層的 think: false；/think low|medium|high 會傳送對應的投入程度字串； /think max 會對應至 Ollama 的最高投入程度 think: "high"。

疑難排解

WSL2 當機循環（重複重新啟動）

在搭配 NVIDIA/CUDA 的 WSL2 上，Ollama 官方 Linux 安裝程式會建立含有 Restart=always 的 ollama.service systemd 單元。若該服務在 WSL2 啟動期間自動啟動並載入 GPU 支援的模型，Ollama 可能會在載入時固定占用主機記憶體；Hyper-V 記憶體回收不一定能回收這些頁面，因此 Windows 可能會終止 WSL2 VM，systemd 接著重新啟動 Ollama，使循環不斷重複。

跡象：WSL2 重複重新啟動／終止、WSL2 啟動後 app.slice 或 ollama.service 的 CPU 使用率很高，以及 SIGTERM 來自 systemd，而非 Linux OOM 終止程式。

當 OpenClaw 偵測到 WSL2、已啟用 ollama.service 且設為 Restart=always，並看到 CUDA 標記時，會記錄啟動警告。

緩解方式：

bash

sudo systemctl disable ollama

在 Windows 端，將以下內容新增至 %USERPROFILE%\.wslconfig，然後執行 wsl --shutdown：

ini

[experimental]autoMemoryReclaim=disabled

或縮短保持連線時間／僅在需要時手動啟動 Ollama：

bash

export OLLAMA_KEEP_ALIVE=5mollama serve

請參閱 ollama/ollama#11317。

未偵測到 Ollama

確認 Ollama 正在執行、已設定 OLLAMA_API_KEY（或驗證設定檔），且未明確定義 models.providers.ollama：

bash

ollama servecurl http://localhost:11434/api/tags

沒有可用的模型

在本機提取模型，或在 models.providers.ollama 中明確定義：

bash

ollama list  # 查看已安裝的項目ollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # 或其他模型

連線遭拒

bash

# 檢查 Ollama 是否正在執行ps aux | grep ollama # 或重新啟動 Ollamaollama serve

遠端主機可搭配 curl 使用，但無法搭配 OpenClaw 使用

請從執行閘道的同一台機器和執行階段進行驗證：

bash

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

常見原因：

baseUrl 指向 localhost，但閘道是在 Docker 或其他主機上執行。
URL 使用 /v1，因此選用了 OpenAI 相容行為，而非原生 Ollama。
遠端主機需要調整防火牆或 LAN 繫結設定。
模型位於你筆記型電腦的常駐程式上，而非遠端常駐程式。

模型將工具 JSON 輸出為文字

通常是因為供應商處於 OpenAI 相容模式，或模型無法處理工具結構描述。建議使用原生模式：

json5

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

若小型本機模型仍無法處理工具結構描述，請在該模型項目上設定 compat.supportsTools: false，然後重新測試。

Kimi 或 GLM 傳回亂碼符號

託管的 Kimi/GLM 回應若包含長串且不具語言意義的符號，會被視為供應商呼叫失敗，而非成功回覆，因此會接手執行一般的重試／後援／錯誤處理，而不會將損毀的文字保存至工作階段。

若問題再次發生，請擷取模型名稱、目前的工作階段檔案，以及該次執行使用的是 Cloud + Local 還是 Cloud only，然後嘗試新的工作階段與後援模型：

bash

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "請只回覆：ok" --jsonopenclaw models set ollama/gemma4

冷啟動的本機模型逾時

大型本機模型第一次載入可能需要很長時間。請將逾時範圍限定於 Ollama 供應商，並可選擇讓模型在多輪之間維持載入狀態：

json5

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

若主機本身接受連線的速度很慢，timeoutSeconds 也會延長此供應商受防護的連線逾時。

大型上下文模型太慢或記憶體不足

許多模型宣告的上下文大小超過你的硬體可舒適執行的範圍。除非已設定 params.num_ctx，否則原生 Ollama 會使用自己的執行階段預設值。若要讓第一個 Token 的延遲可預測，請同時限制 OpenClaw 的預算和 Ollama 的要求上下文：

json5

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

若 OpenClaw 傳送太多提示詞，請降低 contextWindow。若 Ollama 的執行階段上下文對該機器而言太大，請降低 params.num_ctx。若生成執行時間太長，請降低 maxTokens。

Ollama

驗證規則

開始使用

初始設定（建議）

執行初始設定

選取模型

驗證

手動設定

安裝並啟動 Ollama

設定認證資訊

選取模型

透過本機主機使用雲端模型

模型探索（隱含提供者）

煙霧測試

節點本機推論

在節點上啟動 Ollama

連線節點主機

從代理程式使用

視覺與影像描述

設定

基本（隱式探索）

明確設定（手動模型）

自訂基底 URL

常見做法

模型選擇

快速驗證

Ollama 網頁搜尋

進階設定

疑難排解

相關內容

On this page

Molty