本機模型 - OpenClaw

本機模型是可行的。它們也會提高硬體、脈絡大小和提示注入防禦的門檻 — 小型或激進量化的顯卡會截斷脈絡並降低安全性。本頁是針對較高階本機堆疊和自訂 OpenAI 相容本機伺服器的立場明確指南。若要最低阻力的入門流程，請從 LM Studio 或 Ollama 和 openclaw onboard 開始。對於只應在所選模型需要時才啟動的本機伺服器，請參閱本機模型服務。

硬體底線

目標要高：≥2 台頂規 Mac Studio 或等效 GPU 機器（約 $30k+），才能有舒適的 agent 迴圈。單張 24 GB GPU 只適合較輕量的提示，且延遲較高。請一律執行你能承載的最大 / 完整大小變體；小型或高度量化的 checkpoint 會提高提示注入風險（請參閱安全性）。

選擇後端

後端	使用時機
LM Studio	首次本機設定、GUI 載入器、原生 Responses API
Ollama	CLI 工作流程、模型程式庫、免看管的 systemd 服務
MLX / vLLM / SGLang	透過 OpenAI 相容 HTTP 端點進行高吞吐量自託管服務
LiteLLM / OAI-proxy / 自訂 OpenAI 相容代理	你在另一個模型 API 前面做代理，且需要 OpenClaw 將它視為 OpenAI

後端支援時請使用 Responses API（api: "openai-responses"）（LM Studio 支援）。否則請維持使用 Chat Completions（api: "openai-completions"）。

WSL2 + Ollama + NVIDIA/CUDA 使用者： 官方 Ollama Linux 安裝程式會啟用帶有 Restart=always 的 systemd 服務。在 WSL2 GPU 設定中，自動啟動可能會在開機期間重新載入上一個模型並占住主機記憶體。如果你的 WSL2 VM 在啟用 Ollama 後反覆重新啟動，請參閱 WSL2 當機迴圈。

建議：LM Studio + 大型本機模型（Responses API）

目前最佳的本機堆疊。在 LM Studio 中載入大型模型（例如完整大小的 Qwen、DeepSeek 或 Llama 建置），啟用本機伺服器（預設 http://127.0.0.1:1234），並使用 Responses API 將推理與最終文字分離。

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

設定檢查清單

安裝 LM Studio：https://lmstudio.ai
在 LM Studio 中下載可用的最大模型建置（避免「small」/高度量化變體），啟動伺服器，確認 http://127.0.0.1:1234/v1/models 會列出它。
將 my-local-model 替換成 LM Studio 中顯示的實際模型 ID。
保持模型已載入；冷載入會增加啟動延遲。
如果你的 LM Studio 建置不同，請調整 contextWindow/maxTokens。
對 WhatsApp，請維持使用 Responses API，這樣只會送出最終文字。

即使執行本機模型，也請保留託管模型設定；使用 models.mode: "merge"，讓 fallback 保持可用。

混合設定：託管模型為主，本機為 fallback

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

本機優先，託管模型作為安全網

交換 primary 和 fallback 的順序；保留相同的 providers 區塊和 models.mode: "merge"，這樣當本機機器離線時，你可以 fallback 到 Sonnet 或 Opus。

區域託管 / 資料路由

託管的 MiniMax/Kimi/GLM 變體也存在於 OpenRouter，並提供區域釘選端點（例如美國託管）。在那裡選擇區域變體，即可在仍使用 models.mode: "merge" 取得 Anthropic/OpenAI fallback 的同時，將流量保留在你選擇的司法管轄區。
純本機仍是隱私性最強的路徑；當你需要供應商功能但想控制資料流時，託管區域路由是折衷方案。

其他 OpenAI 相容本機代理

MLX（mlx_lm.server）、vLLM、SGLang、LiteLLM、OAI-proxy 或自訂 Gateway 只要公開 OpenAI 風格的 /v1/chat/completions 端點即可運作。除非後端明確記載支援 /v1/responses，否則請使用 Chat Completions adapter。將上方 provider 區塊替換為你的端點和模型 ID：

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

如果在帶有 baseUrl 的自訂 provider 上省略 api，OpenClaw 預設使用 openai-completions。像 127.0.0.1 這類 loopback 端點會自動受信任； LAN、tailnet 和 private DNS 端點仍需要 request.allowPrivateNetwork: true。 models.providers.<id>.models[].id 值是 provider 本機範圍。請勿在此包含 provider 前綴。例如，以 mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit 啟動的 MLX 伺服器應使用以下 catalog id 和模型 ref：

models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

在本機或代理的視覺模型上設定 input: ["text", "image"]，讓圖片附件能注入 agent turn。互動式自訂 provider onboarding 會推斷常見的視覺模型 ID，並只詢問未知名稱。非互動式 onboarding 使用相同推斷；未知視覺 ID 請使用 --custom-image-input，已知外觀但在你的端點後方僅支援文字的模型則使用 --custom-text-input。保留 models.mode: "merge"，讓託管模型仍可作為 fallback。在提高 agents.defaults.timeoutSeconds 前，請先針對緩慢的本機或遠端模型伺服器使用 models.providers.<id>.timeoutSeconds。provider timeout 只套用於模型 HTTP 請求，包含連線、標頭、body 串流，以及總體 guarded-fetch 中止。

對於自訂 OpenAI 相容 provider，當 baseUrl 解析為 loopback、private LAN、.local 或裸 hostname 時，允許保存非機密的本機標記，例如 apiKey: "ollama-local"。OpenClaw 會將它視為有效的本機憑證，而不是回報缺少金鑰。任何接受公開 hostname 的 provider 都請使用真實值。

本機/代理 /v1 後端的行為注意事項：

OpenClaw 會將這些視為代理風格的 OpenAI 相容路由，而不是原生 OpenAI 端點
原生 OpenAI 專用請求塑形不會套用於此：沒有 service_tier、沒有 Responses store、沒有 OpenAI 推理相容 payload 塑形，也沒有 prompt-cache 提示
隱藏的 OpenClaw attribution 標頭（originator、version、User-Agent）不會注入到這些自訂代理 URL

較嚴格 OpenAI 相容後端的相容性注意事項：

有些伺服器在 Chat Completions 上只接受字串 messages[].content，不接受結構化 content-part 陣列。對這些端點設定 models.providers.<provider>.models[].compat.requiresStringContent: true。
有些本機模型會以文字輸出獨立的方括號工具請求，例如 [tool_name] 後接 JSON 和 [END_TOOL_REQUEST]。OpenClaw 只有在名稱完全符合該 turn 已註冊工具時，才會將它們提升為真正的工具呼叫；否則該區塊會被視為不支援的文字，並且從使用者可見的回覆中隱藏。
如果模型輸出看起來像工具呼叫的 JSON、XML 或 ReAct 風格文字，但 provider 沒有輸出結構化 invocation，OpenClaw 會將它保留為文字，並在可用時以 run id、provider/model、偵測到的模式和工具名稱記錄警告。請將其視為 provider/model 工具呼叫不相容，而不是已完成的工具執行。
如果工具以 assistant 文字形式出現而不是執行，例如原始 JSON、 XML、ReAct 語法，或 provider 回應中的空 tool_calls 陣列，請先確認伺服器正在使用支援工具呼叫的聊天範本/剖析器。對於剖析器只有在強制工具使用時才有效的 OpenAI 相容 Chat Completions 後端，請設定每模型請求覆寫，而不是依賴文字剖析：
```
{
  agents: {
    defaults: {
      models: {
        "local/my-local-model": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}
```
只在每個一般 turn 都應呼叫工具的模型/工作階段中使用此設定。它會覆寫 OpenClaw 預設代理值 tool_choice: "auto"。將 local/my-local-model 替換為 openclaw models list 顯示的確切 provider/model ref。
```
openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
```

如果自訂 OpenAI 相容模型接受超出內建 profile 的 OpenAI 推理強度，請在模型 compat 區塊上宣告它們。在這裡加入 "xhigh" 會讓 /think xhigh、工作階段選擇器、Gateway 驗證和 llm-task 驗證為該已設定的 provider/model ref 公開此層級：

{
  models: {
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-responses",
        models: [
          {
            id: "gpt-5.4",
            name: "GPT 5.4 via local proxy",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
            compat: {
              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
              reasoningEffortMap: { xhigh: "xhigh" },
            },
          },
        ],
      },
    },
  },
}

較小或較嚴格的後端

如果模型能正常載入，但完整代理回合表現異常，請由上而下處理 — 先確認傳輸，再縮小範圍。

確認本機模型本身會回應。 不使用工具，不帶代理內容：

openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json

確認 Gateway 路由。 只傳送提供的提示 — 跳過轉錄、AGENTS 啟動程序、內容引擎組裝、工具，以及內建 MCP 伺服器，但仍會測試 Gateway 路由、驗證與提供者選擇：
```
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
```
嘗試精簡模式。 如果兩個探測都通過，但實際代理回合因工具呼叫格式錯誤或提示過大而失敗，請啟用 agents.defaults.experimental.localModelLean: true。這會移除三個最重的預設工具（browser、cron、message），讓提示形狀更小且較不脆弱。完整說明、適用時機，以及如何確認它已開啟，請參閱實驗性功能 → 本機模型精簡模式。
最後手段是完全停用工具。 如果精簡模式仍不足，請為該模型項目設定 models.providers.<provider>.models[].compat.supportsTools: false。之後代理會在該模型上不使用工具呼叫運作。
再往後，瓶頸就在上游。 如果後端在精簡模式和 supportsTools: false 之後，仍只會在較大型的 OpenClaw 執行中失敗，剩下的問題通常是上游模型或伺服器容量 — 內容視窗、GPU 記憶體、kv-cache 淘汰，或後端錯誤。到這一步時，問題已不是 OpenClaw 的傳輸層。

疑難排解

Gateway 能連到代理嗎？curl http://127.0.0.1:1234/v1/models。
LM Studio 模型已卸載？請重新載入；冷啟動是常見的「卡住」原因。
本機伺服器顯示 terminated、ECONNRESET，或在回合中途關閉串流？ OpenClaw 會在診斷中記錄低基數的 model.call.error.failureKind，以及 OpenClaw 程序的 RSS/heap 快照。對於 LM Studio/Ollama 記憶體壓力，請將該時間戳與伺服器記錄或 macOS crash / jetsam 記錄比對，以確認模型伺服器是否被終止。
OpenClaw 會根據偵測到的模型視窗推導內容視窗預檢閾值；若 agents.defaults.contextTokens 降低了有效視窗，則會根據未設上限的模型視窗推導。低於 20% 且以 8k 為下限時會發出警告。硬性阻擋使用 10% 閾值，且以 4k 為下限，並限制在有效內容視窗內，避免過大的模型中繼資料拒絕原本有效的使用者上限。如果遇到該預檢，請提高伺服器/模型內容限制，或選擇更大的模型。
內容錯誤？降低 contextWindow，或提高你的伺服器限制。
OpenAI 相容伺服器回傳 messages[].content ... expected a string？請在該模型項目加入 compat.requiresStringContent: true。
OpenAI 相容伺服器回傳 validation.keys，或表示訊息項目只允許 role 和 content？請在該模型項目加入 compat.strictMessageKeys: true。
直接的小型 /v1/chat/completions 呼叫可運作，但 openclaw infer model run --local 在 Gemma 或其他本機模型上失敗？請先檢查提供者 URL、模型參照、驗證標記，以及伺服器記錄；本機 model run 不包含代理工具。如果本機 model run 成功，但較大的代理回合失敗，請使用 localModelLean 或 compat.supportsTools: false 縮減代理工具範圍。
工具呼叫顯示為原始 JSON/XML/ReAct 文字，或提供者回傳空的 tool_calls 陣列？不要加入會盲目將助理文字轉成工具執行的代理。請先修正伺服器聊天範本/剖析器。如果模型只有在強制使用工具時才可運作，請加入上方的逐模型 params.extra_body.tool_choice: "required" 覆寫，並且只在預期每個回合都會有工具呼叫的工作階段使用該模型項目。
安全性：本機模型會跳過提供者端篩選；請保持代理範圍精簡並開啟 Compaction，以限制提示注入的影響範圍。

Documentation Index

​硬體底線

​選擇後端

​建議：LM Studio + 大型本機模型（Responses API）

​混合設定：託管模型為主，本機為 fallback

​本機優先，託管模型作為安全網

​區域託管 / 資料路由

​其他 OpenAI 相容本機代理

​較小或較嚴格的後端

​疑難排解

​相關

硬體底線

選擇後端

建議：LM Studio + 大型本機模型（Responses API）

混合設定：託管模型為主，本機為 fallback

本機優先，託管模型作為安全網

區域託管 / 資料路由

其他 OpenAI 相容本機代理

較小或較嚴格的後端

疑難排解

相關