> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ollama OpenClaw 會與 Ollama 的原生 API（`/api/chat`）通訊，而不是與 OpenAI 相容的 `/v1` 端點。支援三種模式： | 模式 | 使用項目 | | ------- | ---------------------------------------- | | 雲端 + 本機 | 可連線的 Ollama 主機，提供本機模型以及（若已登入）`:cloud` 模型 | | 僅雲端 | 直接使用 `https://ollama.com`，不使用本機常駐程式 | | 僅本機 | 可連線的 Ollama 主機，僅提供本機模型 | 若要使用專用的 `ollama-cloud` 提供者 ID 進行純雲端設定，請參閱 [Ollama Cloud](/zh-TW/providers/ollama-cloud)。若要讓雲端路由與本機 `ollama` 提供者 保持分離，請使用 `ollama-cloud/` 參照。 請勿使用 `/v1` OpenAI 相容 URL（`http://host:11434/v1`）。這會破壞工具呼叫，且模型可能會將原始工具呼叫 JSON 當作純文字輸出。請使用原生 URL：`baseUrl: "http://host:11434"`（不含 `/v1`）。 標準設定鍵為 `baseUrl`。OpenAI SDK 風格的範例也接受 `baseURL`，但新設定應使用 `baseUrl`。 ## 驗證規則 回送、私人網路、`.local` 及僅含主機名稱的 Ollama URL 不需要真正的持有人權杖。OpenClaw 會對這些主機使用 `ollama-local` 標記。 公開遠端主機與 `https://ollama.com` 需要真正的認證資訊：`OLLAMA_API_KEY`、驗證設定檔，或提供者的 `apiKey`。若要直接使用託管服務，建議使用 `ollama-cloud` 提供者。 使用 `api: "ollama"` 的自訂提供者遵循相同規則。例如，指向私人區域網路主機的 `ollama-remote` 提供者可以使用 `apiKey: "ollama-local"`；子代理程式會透過 Ollama 提供者鉤子解析該標記，而不會將其視為缺少認證資訊。`memory.search.provider` 也可指向自訂提供者 ID，讓嵌入使用該 Ollama 端點。 `auth-profiles.json` 會儲存提供者 ID 的認證資訊；請將端點設定（`baseUrl`、`api`、模型、標頭、逾時）放在 `models.providers.` 中。`{ "ollama-windows": { "apiKey": "ollama-local" } }` 等舊版平面檔案不是執行階段格式；`openclaw doctor --fix` 會將其重寫為標準的 `ollama-windows:default` API 金鑰設定檔，並建立備份。該舊版檔案中的 `baseUrl` 值是雜訊，應移至提供者設定。 Ollama 記憶嵌入的持有人驗證範圍僅限其宣告的主機： * 提供者層級的金鑰只會傳送至該提供者的主機。 * `memory.search.remote.apiKey` 與各代理程式覆寫只會傳送至其遠端嵌入主機。 * 純 `OLLAMA_API_KEY` 環境變數值會被視為 Ollama Cloud 慣例，預設不會傳送至本機／自行託管的主機。 ## 開始使用 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models list --provider ollama ``` 非互動式： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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.com/download](https://ollama.com/download) 取得，然後提取模型： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama pull gemma4 ``` 若要使用混合雲端存取，請在同一部主機上執行 `ollama signin`。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models list openclaw models set ollama/gemma4 ``` 或在設定中使用： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/zh-TW/providers/ollama-cloud)；該路徑不需要 `ollama signin` 或執行中的伺服器： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --auth-choice ollama-cloud openclaw 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama list openclaw models list ``` 使用明確的 `models` 陣列設定 `models.providers.ollama`，或使用具有 `api: "ollama"` 與非回送 `baseUrl` 的自訂提供者，會停用 自動探索；之後必須手動定義模型（請參閱 [設定](#configuration)）。指向託管 `https://ollama.com` 的 `models.providers.ollama` 項目也會略過探索，因為 Ollama Cloud 模型由提供者管理。 `http://127.0.0.2:11434` 等回送自訂提供者仍視為本機提供者，並保留自動探索。 你可以使用 `ollama/:latest` 這類完整參照，而不必手動撰寫 `models.json` 項目；OpenClaw 會即時解析。對於已登入的主機， 選取未列出的 `ollama/:cloud` 參照時，會透過 `/api/show` 驗證該確切模型，且只有在 Ollama 確認中繼資料後才會將其加入執行階段目錄； 拼字錯誤仍會因未知模型而失敗。 ### 煙霧測試 若要執行略過完整代理程式工具介面的精簡文字探查： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} OLLAMA_API_KEY=ollama-local \ openclaw infer model run \ --local \ --model ollama/qwen2.5vl:7b \ --prompt "用一句話描述此影像。" \ --file ./photo.jpg \ --json ``` 這兩種路徑都不會載入聊天工具、記憶或工作階段上下文。如果它能成功， 但一般代理程式回覆失敗，問題可能出在模型的工具／代理程式能力， 而不是端點。 使用 `/model ollama/` 選擇模型是使用者的明確選擇：如果已設定的 `baseUrl` 無法連線，下一則回覆會因提供者錯誤而失敗， 而不會默默改用另一個已設定的模型。 獨立的排程工作會在開始代理程式回合前增加一項本機安全檢查： 如果所選模型解析為本機／私人網路／`.local` Ollama 提供者，且 `/api/tags` 無法連線，OpenClaw 會將該次執行記錄為 `skipped`，並在錯誤文字中包含模型。此端點檢查會依主機快取 5 分鐘，因此針對已停止常駐程式的重複排程工作，不會全部都 發出注定失敗的要求。 即時驗證： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} export OLLAMA_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 theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama pull mistral ``` ## 節點本機推論 代理程式可將短任務委派給已配對桌面或伺服器節點上的 Ollama 模型。 提示詞與回應會透過現有且已驗證的閘道／節點連線傳輸；要求會在節點本身的 迴路 Ollama 端點（`http://127.0.0.1:11434`）上執行。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama pull qwen3:0.6b ollama list ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw node run \ --host \ --port 18789 \ --display-name "Local inference" ``` 在閘道主機上核准裝置及其節點命令，然後進行驗證： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices list openclaw devices approve openclaw nodes pending openclaw nodes approve 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama pull qwen2.5vl:7b export OLLAMA_API_KEY="ollama-local" openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json ``` `--model` 必須是完整的 `` 參照；設定後，`infer image describe` 會先嘗試該模型，而不會因模型已支援原生視覺而略過描述。如果呼叫失敗，OpenClaw 可繼續依序嘗試 `agents.defaults.imageModel.fallbacks`；檔案／URL 準備錯誤會在嘗試後援之前 直接失敗。使用 `infer image describe` 執行 OpenClaw 的影像理解流程與已設定的 `imageModel`；使用 `infer model run --file` 搭配自訂提示詞進行原始多模態探測。 若要讓 Ollama 成為傳入媒體的預設影像理解提供者： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { imageModel: { primary: "ollama/qwen2.5vl:7b", }, }, }, } ``` 建議使用完整的 `ollama/` 參照。只有當像 `qwen2.5vl:7b` 這樣的裸 `imageModel` 參照，以該確切模型列於 `models.providers.ollama.models` 下且具有 `input: ["text", "image"]`，並且沒有其他已設定的影像提供者公開 相同裸 ID 時，才會正規化為 `ollama/qwen2.5vl:7b`；否則請明確使用提供者前綴。 相較於雲端模型，較慢的本機視覺模型可能需要更長的影像理解逾時； 如果 Ollama 嘗試配置模型所公告的完整視覺上下文，也可能在資源受限的硬體上 當機。請設定功能逾時並限制 `num_ctx`： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { id: "qwen2.5vl:7b", name: "qwen2.5vl:7b", input: ["text", "image"], contextWindow: 128000, maxTokens: 8192, } ``` OpenClaw 會拒絕未標記為支援影像的模型所收到的影像描述要求。 使用隱式探索時，此資訊來自 `/api/show` 的視覺功能。 ## 設定 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OLLAMA_API_KEY="ollama-local" ``` 如果已設定 `OLLAMA_API_KEY`，你可以省略提供者項目中的 `apiKey`；OpenClaw 會填入該值以供可用性檢查。 若使用託管雲端設定、非預設主機／連接埠、強制上下文視窗或完全手動的模型清單， 請使用明確設定： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 } ] } } } } ``` 明確設定會停用自動探索，因此必須列出模型： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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", // 選用：在回合之間保持模型載入 }, }, ], }, }, }, } ``` 請勿新增 `/v1`。該路徑會選取 OpenAI 相容模式，而此模式的工具呼叫並不可靠。 ## 常見做法 請將模型 ID 替換為 `ollama list` 或 `openclaw models list --provider ollama` 中的確切名稱。 Ollama 與閘道位於同一台機器上，並自動探索： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama serve ollama pull gemma4 export OLLAMA_API_KEY="ollama-local" openclaw models list --provider ollama openclaw models set ollama/gemma4 ``` 除非你需要手動模型，否則請勿新增 `models.providers.ollama` 區塊。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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。當硬體無法執行模型所公告的完整上下文時，請讓兩者保持一致。 不使用本機常駐程式，直接使用託管模型： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OLLAMA_API_KEY="your-ollama-api-key" ``` ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/zh-TW/providers/ollama-cloud)。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama signin ollama pull gemma4 ``` ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 伺服器時可使用自訂提供者 ID；每個提供者都有各自的 主機、模型、驗證與逾時設定。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} # 此機器可連線至 Ollama 常駐程式 curl http://127.0.0.1:11434/api/tags # OpenClaw 目錄與所選模型 openclaw models list --provider ollama openclaw 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { web: { search: { provider: "ollama", }, }, }, } ``` 若要透過 Ollama Cloud 直接進行託管搜尋： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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` 端點。 如需完整設定與行為說明，請參閱 [Ollama 網頁搜尋](/zh-TW/tools/ollama-search)。 ## 進階設定 **此模式下的工具呼叫並不可靠。** 僅在 Proxy 需要 OpenAI 格式，且你不依賴原生工具呼叫時使用。 對於位於 `/v1/chat/completions` 後方的 Proxy，請明確設定 `api: "openai-completions"`： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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/"].params.num_ctx` 也 適用；如果兩者皆有設定，會以明確的供應商模型項目為準。 OpenClaw 會依照 Ollama 的預期轉送思考設定：使用頂層的 `think`，而非 `options.think`。自動探索且其 `/api/show` 回報 `thinking` 功能的模型，會提供 `/think low`、`/think medium`、`/think high` 和 `/think max`；非思考模型則只提供 `/think off`。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw agent --model ollama/gemma4 --thinking off openclaw agent --model ollama/gemma4 --thinking low ``` 或設定模型預設值： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama pull deepseek-r1:32b ``` Ollama 在本機執行且免費，因此自動探索與手動定義模型的所有模型成本皆為 `0`。 隨附的 Ollama 外掛會為[記憶搜尋](/zh-TW/concepts/memory)註冊記憶嵌入供應商。它會使用已設定的 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](/zh-TW/security/network-proxy#gateway-loopback-mode)。 | 屬性 | 值 | | ------- | -------------------------------------------------- | | 預設模型 | `nomic-embed-text` | | 自動提取 | 是，若本機尚未存在 | | 預設行內並行數 | 1（其他供應商的預設值較高；若主機可承受，請使用 `nonBatchConcurrency` 提高） | 查詢階段的嵌入會針對要求或建議使用擷取前綴的模型套用此前綴： `nomic-embed-text`、`qwen3-embedding` 和 `mxbai-embed-large`。文件批次會維持原始內容，因此現有索引 不需要格式遷移。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { memory: { search: { provider: "ollama", remote: { // Ollama 的預設值。如果在較大型主機上重新建立索引太慢，請提高此值。 nonBatchConcurrency: 1, }, }, }, } ``` 若使用遠端嵌入主機，請將驗證範圍限制在該主機： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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"`。 若要改用 OpenAI 相容端點，請參閱上方的「舊版 OpenAI 相容模式」；在該模式下，串流與工具呼叫可能無法同時運作。 ## 疑難排解 在搭配 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo systemctl disable ollama ``` 在 Windows 端，將以下內容新增至 `%USERPROFILE%\.wslconfig`，然後執行 `wsl --shutdown`： ```ini theme={"theme":{"light":"min-light","dark":"min-dark"}} [experimental] autoMemoryReclaim=disabled ``` 或縮短保持連線時間／僅在需要時手動啟動 Ollama： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OLLAMA_KEEP_ALIVE=5m ollama serve ``` 請參閱 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。 確認 Ollama 正在執行、已設定 `OLLAMA_API_KEY`（或驗證設定檔）， 且**未**明確定義 `models.providers.ollama`： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama serve curl http://localhost:11434/api/tags ``` 在本機提取模型，或在 `models.providers.ollama` 中明確定義： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ollama list # 查看已安裝的項目 ollama pull gemma4 ollama pull gpt-oss:20b ollama pull llama3.3 # 或其他模型 ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 檢查 Ollama 是否正在執行 ps aux | grep ollama # 或重新啟動 Ollama ollama serve ``` 請從執行閘道的同一台機器和執行階段進行驗證： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway status --deep curl http://ollama-host:11434/api/tags ``` 常見原因： * `baseUrl` 指向 `localhost`，但閘道是在 Docker 或其他主機上執行。 * URL 使用 `/v1`，因此選用了 OpenAI 相容行為，而非原生 Ollama。 * 遠端主機需要調整防火牆或 LAN 繫結設定。 * 模型位於你筆記型電腦的常駐程式上，而非遠端常駐程式。 通常是因為供應商處於 OpenAI 相容模式，或模型無法處理 工具結構描述。建議使用原生模式： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { models: { providers: { ollama: { baseUrl: "http://ollama-host:11434", api: "ollama", }, }, }, } ``` 若小型本機模型仍無法處理工具結構描述，請在該模型項目上設定 `compat.supportsTools: false`，然後重新測試。 託管的 Kimi/GLM 回應若包含長串且不具語言意義的符號，會被視為供應商呼叫失敗， 而非成功回覆，因此會接手執行一般的重試／後援／錯誤處理， 而不會將損毀的文字保存至工作階段。 若問題再次發生，請擷取模型名稱、目前的工作階段檔案，以及該次執行使用的是 `Cloud + Local` 還是 `Cloud only`，然後嘗試新的 工作階段與後援模型： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "請只回覆：ok" --json openclaw models set ollama/gemma4 ``` 大型本機模型第一次載入可能需要很長時間。請將逾時範圍限定於 Ollama 供應商，並可選擇讓模型在多輪之間維持載入狀態： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`。 更多協助：[疑難排解](/zh-TW/help/troubleshooting)和[常見問題](/zh-TW/help/faq)。 ## 相關內容 使用專用 `ollama-cloud` 供應商的純雲端設定。 所有供應商、模型參照與容錯移轉行為的概覽。 如何選擇及設定模型。 Ollama 支援的網頁搜尋完整設定與行為詳細資訊。 完整設定參考。