古法编程

Appearance

OpenClaw 运行本地模型时，推荐用 LM Studio + Responses API 方案，要求 ≥2 台 Mac Studio 或等效 GPU 设备（约 3 万美元以上）。配置核心：在 models.providers 下声明 endpoint、api 类型、模型 ID，并保持 models.mode: "merge" 让托管模型作为回退。如果本地模型工具调用异常，先用 openclaw infer model run --local 确认基础响应，再逐步排查。

OpenClaw 本地模型配置：LM Studio、vLLM、LiteLLM 接入指南 ​

本地模型可行，但 OpenClaw 对模型有较高要求：大上下文窗口 + 强抗提示注入能力。小型或过度量化的模型会截断上下文并泄漏安全防护。本页面是从高端本地技术栈到自定义 OpenAI 兼容服务器的实操指南。首次接入可先用 Ollama 配合 openclaw onboard 快速上手。

若要配置仅在选中模型需要时才启动的本地服务，参见 本地模型服务。

硬件门槛 ​

目标：≥2 台满血 Mac Studio 或同等 GPU 设备（约 3 万美元以上） 才能获得流畅的 Agent 循环体验。单块 24 GB 显卡仅能应对较轻的提示，延迟较高。请始终使用你能运行的最大 / 完整版本模型；小型或激进量化的 checkpoint 会提高提示注入风险（参见 安全）。

选择后端 ​

后端适用场景
ds4本地 DeepSeek V4 Flash，macOS Metal 加速，OpenAI 兼容工具调用
LM Studio首次本地设置、图形化加载器、原生 Responses API
LiteLLM / OAI-proxy / 自定义 OpenAI 兼容代理前端对接其他模型 API，让 OpenClaw 视作 OpenAI
MLX / vLLM / SGLang高吞吐自托管服务，暴露 OpenAI 兼容 HTTP 端点
OllamaCLI 工作流、模型库、免 handsoff systemd 服务

如果后端支持，优先使用 Responses API（api: "openai-responses"，LM Studio 已支持），否则使用 Chat Completions（api: "openai-completions"）。

WARNING

WSL2 + Ollama + NVIDIA/CUDA 用户： Ollama Linux 官方安装程序会启用 Restart=always 的 systemd 服务。在 WSL2 GPU 环境下，自动启动可能会在开机时重新加载上次模型并固定宿主机内存。如果启用 Ollama 后 WSL2 VM 反复重启，参见 WSL2 崩溃循环。

推荐方案：LM Studio + 大模型（Responses API） ​

当前最佳本地技术栈。在 LM Studio 中加载一个大型模型（例如完整版的 Qwen、DeepSeek、Llama），启用本地服务器（默认 http://127.0.0.1:1234），并使用 Responses API 将推理过程与最终文本分离。

json5
{
  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" 确保回退选项可用。

混合配置：托管主力 + 本地备用 ​

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

本地优先 + 托管兜底 ​

互换主力和回退顺序，保留相同的 providers 块和 models.mode: "merge"，在本地机器宕机时回退到 Sonnet 或 Opus。

区域托管 / 数据路由 ​

  • MiniMax/Kimi/GLM 的托管变体也在 OpenRouter 上提供区域锁定端点（如美国托管）。在那里选择区域变体可将流量保留在你选择的司法管辖区，同时仍使用 models.mode: "merge" 保持 Anthropic/OpenAI 回退。
  • 纯本地是最强的隐私路径；托管区域路由是在需要 provider 功能但想控制数据流向时的中间方案。

其他 OpenAI 兼容本地代理 ​

MLX（mlx_lm.server）、vLLM、SGLang、LiteLLM、OAI-proxy 或自定义网关，只要暴露 OpenAI 风格的 /v1/chat/completions 端点就能使用。除非后端明确文档支持 /v1/responses，否则使用 Chat Completions 适配器。将上面的 provider 块替换为你的端点和模型 ID：

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

如果自定义 provider 设置了 baseUrl 但省略 api，OpenClaw 默认为 openai-completions。自定义/本地 provider 条目信任其确切配置的 baseUrl origin 用于受保护的模型请求，包括 loopback、LAN、tailnet 和私有 DNS 主机。对其他私有 origin 的请求仍需 request.allowPrivateNetwork: true；元数据/链路本地 origin 在没有显式 opt-in 的情况下仍被阻止。设置为 false 可退出确切-origin 信任。

models.providers.<id>.models[].id 的值是 provider 本地的，不要在其中包含 provider 前缀。例如，用 mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit 启动的 MLX 服务器应使用以下 catalog id 和 model 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 对话轮次中。交互式自定义 provider 配置会推断常见视觉模型 ID，仅对未知名称进行询问。非交互式配置使用相同的推断；对未知视觉 ID 使用 --custom-image-input，当已知模型在你的端点后仅文本时使用 --custom-text-input。

保持 models.mode: "merge" 确保托管模型作为回退可用。使用 models.providers.<id>.timeoutSeconds 针对慢速本地或远程模型服务器，然后再调高 agents.defaults.timeoutSeconds。这个 provider 超时仅适用于模型 HTTP 请求（包括 connect、headers、body streaming 以及受保护的总 fetch abort）。如果 Agent 或 run 超时更低，也要提高该上限，因为 provider 超时不能延长整个 Agent run 的时间。

INFO

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

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

  • OpenClaw 将其视为代理风格的 OpenAI 兼容路由，而非原生 OpenAI 端点
  • 原生 OpenAI 独有请求塑造不适用：没有 service_tier、没有 Responses store、没有 OpenAI reasoning-compat 载荷塑造、没有 prompt-cache 提示
  • OpenClaw 的隐藏归属标头（originator、version、User-Agent）不会注入到这些自定义代理 URL

关于更严格的 OpenAI 兼容后端的兼容性说明：

  • 某些服务器在 Chat Completions 上只接受字符串 messages[].content，而非结构化内容部分数组。对这些端点设置 models.providers.<provider>.models[].compat.requiresStringContent: true。

  • 某些本地模型会以文本形式发出独立的括号工具请求，例如 [tool_name] 后跟 JSON 和 [END_TOOL_REQUEST]。OpenClaw 仅当名称与当前轮次注册的工具完全匹配时才将其提升为真实工具调用；否则该块被视为不支持的文本并从用户可见回复中隐藏。

  • 如果模型发出 JSON、XML 或 ReAct 风格文本，看起来像工具调用，但 provider 没有发出结构化调用，OpenClaw 会将其保留为文本，并记录包含 run id、provider/model、检测到的模式以及工具名称（如果可用）的警告。将其视为 provider/model 工具调用不兼容，而不是已完成的工具运行。

  • 如果工具以助手文本形式出现而没有运行，例如原始 JSON、XML、ReAct 语法或 provider 响应中的空 tool_calls 数组，首先确认服务器使用了支持工具调用的聊天模板/解析器。对于只有在强制使用工具时解析器才能正常工作的 OpenAI 兼容 Chat Completions 后端，设置每个模型的请求覆盖，而不是依赖文本解析：

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

    仅用于每个正常轮次都应调用工具的模型/会话。这会覆盖 OpenClaw 默认的代理值 tool_choice: "auto"。将 local/my-local-model 替换为 openclaw models list 显示的确切 provider/model ref。

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

  • 如果自定义 OpenAI 兼容模型接受超出内置配置的 OpenAI reasoning efforts，请在模型 compat 块中声明这些 effort。添加 "xhigh" 会让 /think xhigh、会话选择器、Gateway 验证和 llm-task 验证为已配置的 provider/model ref 暴露该级别：

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

小型或更严格的模型后端排查 ​

如果模型正常加载但完整 Agent 轮次异常，按顺序自上而下排查——先确认传输层，再缩小范围。

  1. 确认本地模型本身能响应。不带工具、不带 Agent 上下文：

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

  2. 确认 Gateway 路由。仅发送提供的提示——跳过 transcript、AGENTS 引导、上下文引擎组装、工具和捆绑的 MCP 服务器，但仍会经过 Gateway 路由、认证和 provider 选择：

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

  3. 尝试精简模式。如果两个探测都通过，但真实 Agent 轮次因格式错误的工具调用或过大提示而失败，启用 agents.defaults.experimental.localModelLean: true。它会删除三个最重的默认工具（browser、cron、message），使提示形状更小、更稳定。参见 实验功能 → 本地模型精简模式 了解完整说明、何时使用以及如何确认已开启。

  4. 完全禁用工具作为最后手段。如果精简模式不足，为该模型条目设置 models.providers.&lt;provider&gt;.models[].compat.supportsTools: false。Agent 将不使用工具调用来运行该模型。

  5. 超过这一步，瓶颈在上游。如果在精简模式和 supportsTools: false 后，后端在较大的 OpenClaw run 上仍失败，剩余问题通常是上游模型或服务器容量——上下文窗口、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 或调高服务器限制。
  • 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 或其他本地模型上失败？首先检查 provider URL、模型 ref、认证标记和服务器日志；本地 model run 不包含 Agent 工具。如果本地 model run 成功但更大的 Agent 轮次失败，用 localModelLean 或 compat.supportsTools: false 减少 Agent 工具表面。
  • 工具调用以原始 JSON/XML/ReAct 文本形式出现，或 provider 返回空 tool_calls 数组？不要添加盲目将助手文本转换为工具执行的代理。先修复服务器聊天模板/解析器。如果模型只在强制使用工具时才能工作，添加上面的每个模型 params.extra_body.tool_choice: "required" 覆盖，并仅将该模型条目用于预期每个轮次都调用工具的会话。
  • 安全性：本地模型跳过 provider 侧过滤器；保持 Agent 职责范围窄、开启压缩功能以限制提示注入的爆炸半径。

相关 ​

常见问题 ​

本地模型需要多大显存才能跑 OpenClaw？ ​

官方推荐至少 24 GB 显存，但仅适用于较轻的提示和较高延迟。要获得流畅的 Agent 循环（包括工具调用和大上下文），目标硬件是 ≥2 台满血 Mac Studio 或等效 GPU 设备（约 3 万美元以上）。使用完整版模型而非量化版，否则提示注入风险上升。

怎么用 LM Studio 搭配 OpenClaw？ ​

安装 LM Studio，下载一个大型模型（如 Qwen、DeepSeek 完整版），启动本地服务器（默认 http://127.0.0.1:1234）。然后在 OpenClaw 配置中添加 LM Studio provider，设置 api: "openai-responses"，保持 models.mode: "merge"。用 curl http://127.0.0.1:1234/v1/models 确认模型可达。

本地模型工具调用失败（返回原始 JSON/XML）怎么办？ ​

先用 openclaw infer model run --local 确认模型基础响应正常。如果工具以文本形式出现，检查服务器是否使用正确的 chat template/解析器。可以尝试设置 compat.supportsTools: false 完全禁用工具，或添加 params.extra_body.tool_choice: "required" 强制工具调用。若问题依旧，启用 localModelLean: true 减少默认工具负载。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策