OpenClaw 串接 Ollama 怎麼設定？先分清本機、Cloud 與 `/v1` 邊界

先選三種連線模式#

這三者不是只換一個模型 ID。Cloud only 的 ollama-cloud/<model> provider、透過本機 daemon 的 ollama/<model>:cloud，以及本機模型的 ollama/<model>，在認證、端點與驗證方式上都不同。

如果你只是要最快完成一次安裝，也可以從 Ollama 端執行：

1
ollama launch openclaw

官方整合流程會協助安裝 OpenClaw、選擇模型、建立 gateway 設定，並啟用 Ollama 的 web search；但使用本機模型時，官方建議至少準備 64k context，硬體是否能負擔仍要自己驗證。

用 onboarding 建立本機設定#

先確認 Ollama 正在執行，並拉一個確實存在的模型：

1
ollama serve
2
ollama pull gemma4
3
curl http://127.0.0.1:11434/api/tags

接著啟動 OpenClaw onboarding：

1
openclaw onboard

在介面中選 Ollama，再選 Local only。完成後用下面兩個指令確認 catalog 與預設模型：

1
openclaw models list --provider ollama
2
openclaw models status

如果你不想把本機設定寫死在互動流程，也可以使用官方提供的非互動形式。模型 ID 必須替換成 ollama list 或 openclaw models list 顯示的完整名稱：

1
export OLLAMA_API_KEY='ollama-local'
2

3
openclaw onboard --non-interactive \
4
  --auth-choice ollama \
5
  --custom-base-url 'http://127.0.0.1:11434' \
6
  --custom-model-id 'gemma4' \
7
  --accept-risk

對本機或 LAN host，OLLAMA_API_KEY 可以是讓 OpenClaw 啟用 provider 檢查的本地值；連到 https://ollama.com 時，則應使用真正的 Ollama API key。不要把真正的 key 寫進 repository 或貼到 log。

手動設定時，baseUrl 不要寫成 /v1#

需要連到另一台 GPU 主機時，可以在 OpenClaw 設定中明確描述 provider。這個範例使用原生 Ollama API：

1
{
2
  models: {
3
    providers: {
4
      ollama: {
5
        baseUrl: "http://gpu-box.local:11434",
6
        api: "ollama",
7
        apiKey: "ollama-local",
8
        timeoutSeconds: 300,
9
        models: [
10
          {
11
            id: "qwen3.5:9b",
12
            name: "qwen3.5:9b",
13
            input: ["text"],
14
            contextWindow: 32768,
15
            maxTokens: 8192,
16
            params: {
17
              num_ctx: 32768,
18
              thinking: false,
19
              keep_alive: "15m",
20
            },
21
          },
22
        ],
23
      },
24
    },
25
  },
26
  agents: {
27
    defaults: {
28
      model: {
29
        primary: "ollama/qwen3.5:9b",
30
      },
31
    },
32
  },
33
}

這裡有三個容易漏掉的邊界：

1. baseUrl 是 host 根目錄，不是 http://gpu-box.local:11434/v1。
2. primary 使用 provider/model 格式，provider 前綴要保留。
3. contextWindow 是 OpenClaw 的上下文預算，params.num_ctx 是傳給 Ollama 的執行參數；使用人工指定值時，兩者應一起檢查。

依 v2026.11.3 的 model discovery 文件，Ollama 已在 agent 的模型 scope 中時，明確指定的自架 endpoint 即使已有 models 清單，仍會探索其他已安裝的 chat models；手動模型保留自己的設定。要只列設定中的模型，可使用 models.mode: "replace" 或 plugins.entries.ollama.config.discovery.enabled: false，修改前先確認是否會影響其他 provider。

/api/tags 成功時，還會比對設定模型是否存在；名稱錯誤會出現警告，離線時則沒有這個缺少模型警告。因此「沒有警告」不足以證明 host 可達。一次 discovery 失敗也可能保留相同 endpoint／憑證的上次成功 inventory；目錄可見與當下可推論應分開查。

Cloud + Local 與 Cloud only 怎麼分#

1
ollama signin
2
openclaw models list --provider ollama
3
# 確認這個完整 ID 在你的 host 可用後再選用：
4
openclaw models set ollama/kimi-k2.5:cloud

1
export OLLAMA_API_KEY='你的 Ollama API key'
2
openclaw onboard --auth-choice ollama-cloud
3
openclaw models set ollama-cloud/kimi-k2.5:cloud

四層驗證，找出到底是哪裡壞#

1
curl -fsS http://127.0.0.1:11434/api/tags

1
ollama list
2
openclaw models list --provider ollama

1
curl http://127.0.0.1:11434/api/chat \
2
  -H 'Content-Type: application/json' \
3
  -d '{
4
    "model": "gemma4",
5
    "messages": [{"role": "user", "content": "Reply with exactly: ok"}],
6
    "stream": false
7
  }'

1
OLLAMA_API_KEY=ollama-local \
2
  openclaw infer model run \
3
    --local \
4
    --model ollama/llama3.2:latest \
5
    --prompt "Reply with exactly: pong" \
6
    --json

本機推論和 web search 各自驗收#

Ollama Web Search 文件要求自架 host 已執行 ollama signin；直接連 https://ollama.com 則需真正的 API key。純本機文字推論成功，無法證明搜尋的登入與外部服務也成功。

Ollama 整合流程會自動啟用搜尋；手動調整使用 openclaw configure --section web。先以無私人內容的查詢驗證搜尋，再確認回覆實際使用了搜尋結果。需要完全本機資料路徑時，應分別評估 cloud model 與 web search 的對外傳輸。

若只想改 Ollama 整合設定，可用 ollama launch openclaw --config；官方另提醒，已有 Gateway 時，選用新模型可能讓它重新啟動，操作前先安排現有任務。

給 agent 工作流的設定檢查表#

• 將本機、LAN、Cloud + Local、Cloud only 寫成明確選項，不讓使用者只填一個模糊的「Ollama URL」。
• 使用 ollama list 或 /api/tags 的實際結果建立模型選擇，避免把文章中的示例模型當成固定目錄。
• 原生工具呼叫使用 api: "ollama" 與 host 根 URL；若被迫接相容代理，另寫清楚功能取捨。
• 把 contextWindow、num_ctx、timeout 與 keep_alive 分別記錄，問題才不會都被叫成「模型太慢」。
• 設定完成後，分別完成目錄、最小文字推論、完整 agent 工具往返；有啟用搜尋時再驗收搜尋。
• 對連到 LAN 或雲端的 provider，把 key 的來源、傳送目的地與輪替責任寫進交接文件。

先確認 host 與模型，再驗收文字、工具和搜尋；每層留下結果，才能把 daemon、目錄、Gateway 網路與模型能力分開處理。

常見問題#