本機模型

本機模型可以運作，但對硬體、上下文大小與提示詞注入防護的要求更高：小型或高度量化的模型會截斷上下文，並略過供應商端的安全篩選機制。本頁涵蓋高階本機堆疊與自訂 OpenAI 相容伺服器。若要採用最省事的方式，請從 LM Studio 或 Ollama 與 openclaw onboard 開始。

對於只應在所選模型需要時才啟動的本機伺服器，請參閱本機模型服務。

硬體最低需求

若要順暢執行代理程式循環，建議使用 2 台以上配備頂規的 Mac Studio，或同等級的 GPU 設備（約 30,000 美元以上）。單張 24 GB GPU 只能以較高延遲處理較輕量的提示詞。務必執行可承載的最大／完整尺寸版本——小型或高度量化的檢查點會增加提示詞注入風險（請參閱安全性）。

選擇後端

後端支援時請使用 api: "openai-responses"（LM Studio 支援）。否則請使用 api: "openai-completions"。如果具有 baseUrl 的自訂供應商省略 api，OpenClaw 會預設使用 openai-completions。

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
• 下載可用的最大模型組建（避免「小型」／高度量化的變體），啟動伺服器，並確認 http://127.0.0.1:1234/v1/models 有列出該模型。
• 將 my-local-model 替換為 LM Studio 中顯示的實際模型 ID。
• 保持模型已載入；冷啟動載入會增加啟動延遲。
• 如果你的 LM Studio 組建有所不同，請調整 contextWindow／maxTokens。
• 對於 WhatsApp，請使用 Responses API，確保只傳送最終文字。
• 保持 models.mode: "merge"，讓託管模型仍可作為後備方案。

混合設定：以託管模型為主要模型，以本機模型為後備模型

{  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／fallbacks 的順序，同時保留相同的 providers 區塊與 models.mode: "merge"。

區域託管／資料路由

OpenRouter 上也提供託管的 MiniMax／Kimi／GLM 變體，並具有鎖定區域的端點（例如託管於美國）。選擇區域變體，可在為 Anthropic／OpenAI 保留 models.mode: "merge" 後備方案的同時，讓流量維持在你選擇的司法管轄區內。純本機仍是隱私保護最強的方式；當你需要供應商功能，但又希望控制資料流向時，託管的區域路由則是折衷方案。

其他 OpenAI 相容本機代理

只要公開 OpenAI 風格的 /v1/chat/completions 端點，MLX（mlx_lm.server）、vLLM、SGLang、LiteLLM、OAI-proxy 或任何自訂閘道皆可使用。除非後端明確記載支援 /v1/responses，否則請使用 openai-completions。

{  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 來源，以進行受防護的模型要求，包括迴路介面、區域網路、tailnet 與私人 DNS 主機。無論如何，中繼資料／鏈路本機來源一律會遭到封鎖。向其他私人來源發出的要求仍需設定 models.providers.<id>.request.allowPrivateNetwork: true；若要退出精確來源信任，請將此信任旗標設為 false。

models.providers.<id>.models[].id 是供應商本機 ID——請勿包含供應商前綴。對於使用 mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit 啟動的 MLX 伺服器：

• 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"]，讓影像附件能注入代理程式回合。互動式自訂供應商引導程序會推斷常見的視覺模型 ID，且只會詢問無法辨識的名稱；非互動式引導程序使用相同的推斷方式，並可透過 --custom-image-input／--custom-text-input 覆寫。

對於緩慢的本機／遠端模型伺服器，請先使用 models.providers.<id>.timeoutSeconds，再提高 agents.defaults.timeoutSeconds。供應商逾時涵蓋連線、標頭、本文串流，以及僅針對模型 HTTP 要求的受防護擷取總中止時間——如果代理程式／執行逾時較低，也請一併提高，因為供應商逾時無法延長整個執行時間。

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

• OpenClaw 將這些路由視為代理型 OpenAI 相容路由，而非原生 OpenAI 端點。
• 僅限原生 OpenAI 的要求塑形不適用：不含 service_tier、Responses store、OpenAI 推理相容承載資料塑形，也不含提示詞快取提示。
• 在自訂代理 URL 上，不會注入隱藏的 OpenClaw 歸屬標頭（originator、version、User-Agent）。

針對較嚴格 OpenAI 相容後端的相容性覆寫：

• 僅限字串內容：部分伺服器只接受字串形式的 messages[].content，不接受結構化的內容部分陣列。請設定 models.providers.<provider>.models[].compat.requiresStringContent: true。

• 嚴格訊息鍵值：如果伺服器拒絕包含 role／content 以外欄位的訊息項目，請設定 compat.strictMessageKeys: true。

• 括號式工具文字：部分本機模型會將獨立的括號式工具要求輸出為文字，例如 [tool_name] 後接 JSON 與 [END_TOOL_REQUEST]。只有當名稱與該回合已註冊工具的名稱完全相符時，OpenClaw 才會將其提升為真正的工具呼叫；否則會保留為隱藏且不受支援的文字。

• 看似工具呼叫的非結構化文字：如果模型輸出看似工具呼叫，但並非結構化叫用的 JSON／XML／ReAct 風格文字，OpenClaw 會將其保留為文字，並記錄警告，其中包含執行 ID、供應商／模型、偵測到的模式，以及可取得時的工具名稱。這代表供應商／模型不相容，而不是已完成工具執行。

• 強制使用工具：如果工具以助理文字呈現（原始 JSON／XML／ReAct，或空的 tool_calls 陣列），請先確認伺服器的聊天範本／剖析器支援工具呼叫。如果剖析器僅在強制使用工具時運作，請針對各模型覆寫預設代理值 tool_choice: "auto"：

  {  agents: {    defaults: {      models: {        "local/my-local-model": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

  只有在每個一般回合都應呼叫工具時才使用此設定。請將 local/my-local-model 替換為 openclaw models list 所列的精確參照，或透過命令列介面設定：

  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

• 額外推理強度：如果自訂 OpenAI 相容模型接受內建設定檔以外的 OpenAI 推理強度，請在模型的相容性區塊中宣告。加入 "xhigh" 後，即可針對該模型參照，在 /think xhigh、工作階段選擇器、閘道驗證與 llm-task 驗證中使用：

  {  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" },            },          },        ],      },    },  },}

較小型或較嚴格的後端

如果模型能正常載入，但完整代理程式回合行為異常，請由上而下排查：先確認傳輸，再縮小問題範圍。

1. 確認本機模型有回應——不使用工具，也不含代理程式上下文：

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

2. 確認閘道路由 - 僅傳送提示詞，略過逐字稿、AGENTS 啟動程序、情境引擎組裝、工具及隨附的 MCP 伺服器，但仍會測試閘道路由、驗證和供應商選擇：

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

3. 如果兩項探測皆通過，但實際代理執行仍因工具呼叫格式錯誤或提示詞過大而失敗，請嘗試精簡模式：設定 agents.defaults.experimental.localModelLean: true。除非明確需要，否則此模式會移除重量級的瀏覽器、排程、訊息、媒體生成、語音和 PDF 工具，並預設將較大的工具目錄置於結構化的工具搜尋控制後方，同時維持 exec 直接可見。詳情及如何確認其已啟用，請參閱實驗性功能 -> 本機模型精簡模式。

4. 最後手段是完全停用工具：為該模型設定 models.providers.<provider>.models[].compat.supportsTools: false，之後代理將不使用工具呼叫執行。

5. 超出此範圍後，瓶頸便在上游。 如果後端在精簡模式和 supportsTools: false 下，仍只於較大型的 OpenClaw 執行中失敗，剩餘問題通常出在模型或伺服器本身，例如情境視窗、GPU 記憶體、kv-cache 淘汰或後端錯誤，而非 OpenClaw 的傳輸層。

疑難排解

• 閘道無法連上代理伺服器？ curl http://127.0.0.1:1234/v1/models。
• LM Studio 模型已卸載？ 請重新載入；冷啟動是常見的「停滯」原因。
• 本機伺服器顯示 terminated、ECONNRESET，或在執行途中關閉串流？ OpenClaw 會在診斷資料中記錄低基數的 model.call.error.failureKind，以及 OpenClaw 程序的 RSS/堆積快照。若是 LM Studio/Ollama 的記憶體壓力，請將該時間戳記與伺服器日誌或 macOS 當機/jetsam 日誌比對，以確認模型伺服器是否遭到終止。
• 情境錯誤？ OpenClaw 會根據偵測到的模型視窗（或 agents.defaults.contextTokens 將其降低時的上限視窗）推導情境視窗的預先檢查門檻：低於 20% 時警告，最低門檻為 8k；低於 10% 時直接阻擋，最低門檻為 4k（門檻會限制在有效情境視窗內，避免過大的模型中繼資料拒絕有效的使用者上限）。請降低 contextWindow，或提高伺服器/模型的情境上限。
• messages[].content ... expected a string？ 在該模型項目中加入 compat.requiresStringContent: true。
• 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" 覆寫，並只在預期每一輪都會呼叫工具的工作階段中使用該模型項目。
• 安全性：本機模型會略過供應商端的篩選機制。請縮小代理的權限與範圍，並啟用壓縮，以限制提示詞注入的影響範圍。

相關內容

• 設定參考
• 模型容錯移轉