本地模型 - OpenClaw

本地模型可以工作，但它们会提高对硬件、上下文大小和提示注入防护的要求：小型模型或激进量化的模型会截断上下文，并跳过提供商侧的安全过滤器。本页介绍较高端的本地栈和自定义 OpenAI 兼容服务器。阻力最小的路径请从 LM Studio 或 Ollama 以及 openclaw onboard 开始。对于只应在所选模型需要时才启动的本地服务器，请参阅本地模型服务。

硬件底线

为了获得舒适的 Agent loop，目标应是 2 台以上配置拉满的 Mac Studio，或等效的 GPU 设备（约 3 万美元以上）。单张 24 GB GPU 只能以较高延迟处理较轻的提示。始终运行你能托管的最大 / 完整尺寸变体 - 小型或重度量化的检查点会提高提示注入风险（见安全）。

选择后端

后端	适用场景
ds4	macOS Metal 上的本地 DeepSeek V4 Flash，支持 OpenAI 兼容的工具调用
LM Studio	首次本地设置、GUI 加载器、原生 Responses API
LiteLLM / OAI-proxy / 自定义 OpenAI 兼容代理	你在前面接入另一个模型 API，并需要 OpenClaw 将其视为 OpenAI
MLX / vLLM / SGLang	使用 OpenAI 兼容 HTTP 端点进行高吞吐自托管服务
Ollama	CLI 工作流、模型库、免维护 systemd 服务

当后端支持时，使用 api: "openai-responses"（LM Studio 支持）。否则使用 api: "openai-completions"。如果带有 baseUrl 的自定义提供商省略了 api，OpenClaw 默认使用 openai-completions。

**WSL2 + Ollama + NVIDIA/CUDA：**官方 Ollama Linux 安装器会启用带有 Restart=always 的 systemd 服务。在 WSL2 GPU 设置中，自动启动可能会在启动期间重新加载上一个模型并占住主机内存，导致虚拟机反复重启。参见 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
下载可用的最大模型构建（避免“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"，让托管模型仍可作为回退使用。

混合配置：托管主模型，本地回退

{
  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"。

区域托管 / 数据路由

托管的 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，并带有区域固定端点（例如美国托管）。选择区域变体可将流量保留在你选择的司法辖区内，同时保留 models.mode: "merge" 作为 Anthropic/OpenAI 回退。本地-only 仍是最强的隐私路径；当你需要提供商功能但希望控制数据流时，托管区域路由是折中方案。

其他 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 来源来发起受保护的模型请求，包括 loopback、LAN、tailnet 和私有 DNS 主机。无论如何都会阻止元数据/link-local 来源。对其他私有来源的请求仍需要 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 请求的连接、响应头、正文流式传输和总受保护 fetch 中止 - 如果智能体/运行超时更低，也要提高它，因为提供商超时无法延长整个运行。

对于自定义 OpenAI 兼容提供商，当 baseUrl 解析到 loopback、私有 LAN、.local 或裸主机名时，会接受非机密本地标记，例如 apiKey: "ollama-local" - OpenClaw 会将其视为有效本地凭证，而不是报告缺少密钥。对于任何接受公共主机名的提供商，请使用真实值。

本地/代理 /v1 后端的行为说明：

OpenClaw 将这些视为代理风格的 OpenAI 兼容路由，而不是原生 OpenAI 端点。
原生 OpenAI 专用请求整形不适用：没有 service_tier，没有 Responses store，没有 OpenAI reasoning-compat 载荷整形，也没有提示缓存提示。
隐藏的 OpenClaw 归因标头（originator、version、User-Agent）不会注入到自定义代理 URL。

适用于更严格 OpenAI 兼容后端的兼容覆盖：

仅字符串内容：某些服务器只接受字符串 messages[].content，不接受结构化 content-part 数组。设置 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 推理强度，请在模型的兼容块中声明它们。添加 "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" },
            },
          },
        ],
      },
    },
  },
}

更小或更严格的后端

如果模型可以干净加载，但完整智能体轮次行为异常，请自上而下排查：先确认传输，再缩小范围。

确认本地模型会响应 - 无工具，无智能体上下文：

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

确认 Gateway 网关路由 - 只发送提示词，跳过转录、AGENTS 引导、context-engine 组装、工具和内置 MCP 服务器，但仍会测试 Gateway 网关路由、凭证和提供商选择：
```
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
```
如果两个探测都通过，但真实智能体轮次因格式错误的工具调用或过大的提示词而失败，请尝试精简模式：设置 agents.defaults.experimental.localModelLean: true。它会丢弃重量级的浏览器、cron、消息、媒体生成、语音和 PDF 工具，除非明确需要，并默认将较大的工具目录放在结构化的 Tool Search 控制之后。有关详情以及如何确认它已开启，请参阅实验性功能 -> 本地模型精简模式。
作为最后手段，完全禁用工具：为该模型设置 models.providers.<provider>.models[].compat.supportsTools: false - 然后智能体将在没有工具调用的情况下运行。
再往后，瓶颈就在上游。 如果后端在精简模式和 supportsTools: false 之后，仍然只在较大的 OpenClaw 运行中失败，剩余问题通常是模型或服务器本身 - 上下文窗口、GPU 内存、kv-cache 淘汰，或后端 bug - 而不是 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" 覆盖，并且只在每个轮次都预期有工具调用的会话中使用该模型条目。
安全：本地模型会跳过提供商侧过滤器。保持智能体范围收窄，并开启压缩，以限制提示注入的影响范围。

​硬件底线

​选择后端

​LM Studio + 大型本地模型（Responses API）

​混合配置：托管主模型，本地回退

​区域托管 / 数据路由

​其他 OpenAI 兼容本地代理

​更小或更严格的后端

​故障排查

​相关

硬件底线

选择后端

LM Studio + 大型本地模型（Responses API）

混合配置：托管主模型，本地回退

区域托管 / 数据路由

其他 OpenAI 兼容本地代理

更小或更严格的后端

故障排查

相关