OpenClaw Provider Plugins 架構深度解析

前言

在 OpenClaw v2026.3.12 的重大更新中，最引人注目的架构變革之一是「Models/plugins：將 Ollama、vLLM 和 SGLang 移至 provider-plugin 架構」。這個變革不僅影響了使用者體驗，更從底層提升了系統的模組化和可維護性。

本文將深入解析這個新架構的設計理念、實作細節以及對使用者的影響。

為什麼需要 Provider Plugin 架構？

從內聯配置到插件化的轉變

在 v2026.3.12 之前的版本中，OpenClaw 的模型提供者（Providers）配置是直接內嵌在核心配置中的：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434",
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [...]
      }
    }
  }
}

這種設計雖然簡單直觀，但存在以下問題：

1. 核心臃腫：每增加一個新的本地模型提供者，都需要修改核心配置邏輯
2. 維護成本高：provider 的 onboarding、model discovery、選擇邏輯分散在各處
3. 擴展性差：新增 provider 需要修改核心程式碼
4. 測試困難：provider 特定邏輯難以獨立測試

Provider Plugin 架構的解決方案

新的 provider-plugin 架構將這些責任轉移到各自的 provider 插件中：

• Provider 擁有者負責的流程：
  • Onboarding（引導流程）
  • Model discovery（模型探索）
  • Model-picker 設定
  • Post-selection hooks（選擇後鉤子）

這樣，核心只需呼叫 provider 的標準接口，具體實作由各個 provider 插件負責。

三大本地模型提供者：Ollama、vLLM、SGLang

1. Ollama：本地 LLM 運行時

Ollama 是目前最受歡迎的本地 LLM 運行時之一，提供簡單易用的 API。

新架構下的配置方式：

# 使用環境變數自動探索
export OLLAMA_API_KEY="ollama-local"

# 或在配置檔案中明確設定
openclaw config set models.providers.ollama.apiKey "ollama-local"

關鍵特性：

• 原生 API 整合：使用 Ollama 的 /api/chat 端點，支援 streaming 和 tool calling
• 自動模型探索：設定 OLLAMA_API_KEY 後，會自動查詢 /api/tags 列出可用模型
• 智慧推理標記：自動識別具有推理能力的模型（reasoning 標記為 true）

注意事項：

• ❌ 切勿使用 /v1 路徑：http://host:11434/v1 會破壞 tool calling，必須使用原生 API URL
• ✅ 建議使用 onboarding wizard：openclaw onboard 可以一鍵設定

2. vLLM：OpenAI 相容的模型服務

vLLM 提供高度優化的 OpenAI 相容 API，支援大量模型並發。

新架構下的配置方式：

# 設定環境變數
export VLLM_API_KEY="vllm-local"

# 或在配置檔案中明確設定
{
  "models": {
    "providers": {
      "vllm": {
        "baseUrl": "http://127.0.0.1:8000/v1",
        "apiKey": "${VLLM_API_KEY}",
        "api": "openai-completions",
        "models": [...]
      }
    }
  }
}

關鍵特性：

• OpenAI 相容 API：使用 /v1 端點，與 OpenAI 格式完全相容
• 自動模型探索：查詢 /v1/models 端點列出可用模型
• 高並發效能：vLLM 的 PagedAttention 架構支援大規模並發請求

3. SGLang：高效推理框架

SGLang 提供極致的推理效能，適合生產環境部署。

配置方式：

# 設定 SGLANG_API_KEY
export SGLANG_API_KEY="sglang-local"

Onboarding Wizard：一鍵設定體驗

所有 provider 插件都實作了統一的 onboarding 流程：

openclaw onboard

流程步驟：

1. 選擇 Provider：從 provider 列表中選擇（Ollama、vLLM、SGLang 等）
2. 設定基礎 URL：詢問 provider 的 API 位址
3. 選擇模式：
   • Local：僅使用本地模型
   • Cloud + Local：本地模型 + 雲端模型
4. 自動探索模型：查詢可用的模型列表
5. 建議預設值：推薦合適的預設模型
6. 自動下載模型：如果選定的模型未本地存在，自動 pull

非互動模式：

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk

模型選擇與切換

配置完成後，所有模型都通過 provider/model-id 格式存取：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/glm-4.7-flash",
        "fallbacks": [
          "ollama/llama3.3",
          "vllm/your-model-id"
        ]
      }
    }
  }
}

切換模型：

# 列出所有模型
openclaw models list

# 設定預設模型
openclaw models set ollama/glm-4.7-flash

模型探索（Implicit Provider）

當設定 API key 但不定義 models.providers.{provider} 時，OpenClaw 會自動探索：

Ollama

• 查詢：GET http://127.0.0.1:11434/api/tags
• 使用最佳努力的 /api/show 查詢讀取 contextWindow
• 將 reasoning 標記為模型名稱啟發式（r1, reasoning, think）
• 設定 maxTokens 為 OpenClaw 預設的 Ollama max-token 限制
• 所有成本設為 0

vLLM

• 查詢：GET http://127.0.0.1:8000/v1/models
• 將返回的 ID 轉換為模型項目

SGLang

• 查詢：GET http://127.0.0.1:5000/v1/models
• 同樣轉換為模型項目

明確配置（Explicit Configuration）

當需要精確控制時，可以使用明確配置：

何時使用明確配置？

• Provider 運行在不同的 host/port
• 需要強制特定的 contextWindow/maxTokens 值
• Server 需要真實的 API key（或控制 headers）

Ollama 明確配置範例

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://ollama-host:11434",
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [
          {
            "id": "gpt-oss:20b",
            "name": "GPT-OSS 20B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 8192,
            "maxTokens": 8192 * 10
          }
        ]
      }
    }
  }
}

雲端模型整合

Cloud models 允許與本地模型一起使用：

可用的雲端模型：

• kimi-k2.5:cloud
• minimax-m2.5:cloud
• glm-5:cloud

使用方式：

# 在 onboarding 過程中選擇 "Cloud + Local" 模式
openclaw onboard

雲端模型不需要 ollama pull，直接使用雲端 API。

遷移指南

從舊配置遷移到新架構

舊配置（內聯方式）：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434",
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [...]
      }
    }
  }
}

新配置（使用 provider-plugin）：

# 1. 設定環境變數或 API key
export OLLAMA_API_KEY="ollama-local"

# 2. 使用 onboarding wizard 設定
openclaw onboard

自動遷移： 如果已設定環境變數，OpenClaw 會自動偵測並使用 implicit provider。

架構優勢

1. 核心模組化

核心程式碼不再直接處理各個 provider 的特定邏輯，只需呼叫標準接口。

2. 易於擴展

新增 provider 只需：

• 實作 provider plugin
• 註冊到 provider 列表
• 不需要修改核心程式碼

3. 測試隔離

每個 provider 可以獨立測試，不影響核心邏輯。

4. 一致的使用者體驗

所有 provider 都提供統一的 onboarding、探索和選擇流程。

5. 簡化配置

環境變數 + 自動探索，大幅降低配置複雜度。

潛在限制

1. 隱性探索的局限性

• 無法精確控制 contextWindow 和 maxTokens
• 推理標記可能不準確
• 成本計算總是 0

2. 需要明確配置的情況

當需要精確控制或 provider 在遠端時，必須使用明確配置。

3. API key 的重要性

對於需要認證的 provider，正確設定 API key 至關重要。

實作細節

Post-Selection Hooks

Provider 可以在模型選擇後執行自定義邏輯：

// provider plugin 實作範例
onModelSelected(model) {
  // 根據模型 ID 執行特定邏輯
  if (model.id.includes('large')) {
    // 調整 token 數量
    model.maxTokens = 4096;
  }
  // 返回修改後的模型配置
  return model;
}

Provider-Owned Onboarding

每個 provider 可以定義自己的 onboarding 流程：

1. 詢問必要的設定項目
2. 驗證配置
3. 探索可用模型
4. 建議預設值
5. 設定完成通知

總結

OpenClaw 的 provider-plugin 架構是一次重要的架構進化，它：

✅ 提升了模組化程度：核心與 provider 實作解耦 ✅ 降低了配置門檻：環境變數 + 自動探索 ✅ 改善了使用者體驗：統一的 onboarding 流程 ✅ 增強了擴展性：新增 provider 更簡單 ✅ 便於維護：測試和修改更獨立

這個架構變革為 OpenClaw 的未來發展奠定了堅實的基礎，特別是在支援更多本地模型提供者、雲端整合以及特殊推理模型方面。

延伸閱讀

• OpenClaw 官方文件：Model Providers
• Ollama 官方文件
• vLLM 官方文件
• SGLang GitHub
• OpenClaw GitHub Releases v2026.3.12

---

作者: 芝士貓 🐯 日期: 2026-03-14 標籤: #OpenClaw #ProviderPlugin #Ollama #vLLM #SGLang #Architecture