本地模型

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

硬件门槛

​

选择后端

​

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

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "本地" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "本地模型",
            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，这样只会发送最终文本。

​

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

{
  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: "本地" },
        "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: "本地模型",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​

以本地优先，带托管安全网

​

区域托管 / 数据路由

• OpenRouter 上也提供托管的 MiniMax/Kimi/GLM 变体，并带有区域固定端点（例如美区托管）。在那里选择区域变体，以便在继续使用 Anthropic/OpenAI 回退时，将流量保留在你选择的司法辖区内，同时仍使用 models.mode: "merge"。
• 当你需要提供方特性但又希望控制数据流时，仅本地仍然是最强的隐私路径；区域化托管路由则是折中方案。

​

其他 OpenAI 兼容的本地代理

{
  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: "本地模型",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

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

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

• 某些服务器在 Chat Completions 中只接受字符串形式的 messages[].content，而不是结构化的内容片段数组。对于这些端点，请将 models.providers.<provider>.models[].compat.requiresStringContent: true。
• 某些本地模型会将独立的方括号工具请求作为文本输出，例如 [tool_name] 后接 JSON 和 [END_TOOL_REQUEST]。只有当名称与该轮已注册工具完全匹配时，OpenClaw 才会把它们提升为真实的工具调用；否则该块会被视为不支持的文本，并会从用户可见回复中隐藏。
• 如果模型输出看起来像工具调用的 JSON、XML 或 ReAct 风格文本，但 provider 并未发出结构化调用，OpenClaw 会保留为文本，并记录一条警告，内容包括运行 ID、provider/model、检测到的模式以及可用时的工具名。请将其视为 provider/model 的工具调用不兼容，而不是一次完成的工具运行。
• 如果工具作为 assistant 文本而不是实际执行出现，例如原始 JSON、XML、ReAct 语法，或者 provider 响应中的 tool_calls 数组为空，首先验证服务器是否使用支持工具调用的 chat 模板/解析器。对于其解析器只有在强制使用工具时才工作的 OpenAI 兼容 Chat Completions 后端，请设置按模型的请求覆盖，而不要依赖文本解析：
  {
    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 引用。
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• 如果自定义 OpenAI 兼容模型支持超出内置配置文件的 OpenAI reasoning efforts，请在模型 compat 区块中声明它们。在这里添加 "xhigh" 会让 /think xhigh、会话选择器、Gateway 验证以及 llm-task 验证在该已配置的 provider/model 引用上暴露该级别：
  {
    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",
              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. 确认本地模型本身有响应。 不使用工具、不带 agent 上下文：
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. 确认 Gateway 路由。 只发送提供的提示词——跳过 transcript、AGENTS 启动、context-engine 组装、工具和捆绑的 MCP 服务器，但仍会测试 Gateway 路由、认证和 provider 选择：
   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.<provider>.models[].compat.supportsTools: false。这样 agent 就会在该模型上不使用工具调用。
5. 再往后，瓶颈就在上游了。 如果后端在更大的 OpenClaw 运行中仍然失败，即使启用了精简模式和 supportsTools: false，剩余问题通常就是上游模型或服务器容量——上下文窗口、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/heap 快照。对于 LM Studio/Ollama 内存压力，请用该时间戳对照服务器日志或 macOS 崩溃 / jetsam 日志，以确认模型服务器是否被终止。
• OpenClaw 会根据检测到的模型窗口，或在 agents.defaults.contextTokens 降低有效窗口时根据未封顶的模型窗口推导上下文窗口预检阈值。它在低于 20% 时给出警告，并设置 8k 下限。硬性阻断使用 10% 阈值，并设置 4k 下限，同时将其封顶到有效上下文窗口，以便过大的模型元数据不会拒绝原本有效的用户上限。如果触发了该预检，请提高服务器/模型上下文限制或选择更大的模型。
• 上下文错误？降低 contextWindow 或提高你的服务器限制。
• OpenAI 兼容服务器返回 messages[].content ... expected a string？ 在该模型条目上添加 compat.requiresStringContent: true。
• 直接调用小型 /v1/chat/completions 可以工作，但 openclaw infer model run --local 在 Gemma 或其他本地模型上失败？先检查 provider URL、模型引用、认证 标记和服务器日志；本地 model run 不包含 agent 工具。 如果本地 model run 成功但更大的 agent 回合失败，请通过 localModelLean 或 compat.supportsTools: false 减少 agent 工具面。
• 工具调用以原始 JSON/XML/ReAct 文本形式出现，或者 provider 返回了 空的 tool_calls 数组？不要添加一个会盲目把 assistant 文本转换为工具执行的代理。先修复服务器的 chat 模板/解析器。如果 模型只有在强制使用工具时才可用，请添加上面的按模型 params.extra_body.tool_choice: "required" 覆盖，并且只在每一轮都预期有工具调用的会话中使用该模型 条目。
• 安全性：本地模型会跳过提供方侧过滤；请保持 agent 范围尽量窄，并开启 compaction 以限制提示注入的爆炸半径。

​

相关

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