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 的執行參數；使用人工指定值時，兩者應一起檢查。

若你設定了 models.providers.ollama.models，OpenClaw 會進入明確模型清單，不再完全依賴自動 discovery。因此模型 ID 拼錯時，先回到主機上的 ollama list，不要只改 allowlist。

Cloud + Local 與 Cloud only 怎麼分#

1
ollama signin
2
ollama pull gemma4
3
openclaw models list --provider ollama
4
openclaw models set ollama/gemma4

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
  }'

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

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

OpenClaw 和 Ollama 的整合重點不是「把一個模型接上去」，而是把路由、認證、原生 API 與上下文邊界寫清楚。先完成三層驗證，再把 messaging channels 或 web search 接上去，出錯時比較容易知道是模型、daemon 還是 gateway 設定。

常見問題#