本地模型

本地模型可以工作，但它们对硬件、上下文大小和提示词注入防御提出了更高要求：小型或激进量化的模型会截断上下文并跳过提供商侧的安全过滤器。本页介绍高端本地技术栈和自定义 OpenAI 兼容服务器。若要选择最省事的路径，请从 LM Studio 或 Ollama 开始，并参阅 openclaw onboard。

对于仅应在所选模型需要时启动的本地服务器，请参阅本地模型服务。

硬件门槛

为获得顺畅的 Agent loop，建议使用 2 台以上满配 Mac Studio 或同等 GPU 设备（约 $30k+）。单张 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 变体，并带有区域锁定的端点（例如在美国托管）。选择区域变体，可在保留 models.mode: "merge" 以用于 Anthropic/OpenAI 回退的同时，让流量留在你所选的司法管辖区。本地独占仍是隐私保护最强的路径；当你需要提供商功能但又想控制数据流时，托管式区域路由是一种折中方案。

其他 OpenAI 兼容本地代理

如果 MLX（mlx_lm.server）、vLLM、SGLang、LiteLLM、OAI-proxy 或任何自定义 Gateway 网关公开 OpenAI 风格的 /v1/chat/completions 端点，即可使用。除非后端明确说明支持 /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 来源，以用于受防护的模型请求，包括回环地址、LAN、tailnet 和私有 DNS 主机。无论如何，元数据/链路本地来源始终会被阻止。向其他私有来源发送请求仍需要 models.providers.<id>.request.allowPrivateNetwork: true；将信任标志设置为 false 可选择退出精确来源信任。

models.providers.<id>.models[].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 中的确切引用，或通过 CLI 设置：

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

• 额外推理强度：如果自定义 OpenAI 兼容模型接受内置配置之外的 OpenAI 推理强度，请在模型的 compat 块中声明它们。添加 "xhigh" 后，该强度会针对 /think xhigh 中的该模型引用、会话选择器、Gateway 网关验证和 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. 确认 Gateway 网关路由——仅发送提示词，跳过对话记录、AGENTS 引导加载、上下文引擎组装、工具和内置 MCP 服务器，但仍会验证 Gateway 网关路由、身份验证和提供商选择：

   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 的传输层。

故障排查

• Gateway 网关无法访问代理？ 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" 覆盖项，并且仅将该模型条目用于预期每个轮次都会调用工具的会话。
• 安全性：本地模型会跳过提供商侧的过滤器。请缩小智能体的功能范围并启用压缩，以限制提示词注入的影响范围。

相关内容

• 配置参考
• 模型故障转移