本地模型

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

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

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

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

  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` 验证中暴露它：

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

## 更小或更严格的后端 {#smaller-or-stricter-backends}

如果模型能正常加载，但完整的 agent 轮次出现异常，请先检查传输，然后检查工具使用和上下文预算。

1. **检查本地模型是否响应** - 无工具、无 agent 上下文：

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

2. **检查 Gateway 路由** - 仅发送 prompt。它会跳过对话记录、AGENTS 引导、context-engine 组装、工具以及捆绑的 MCP 服务器。它仍然会验证 Gateway 路由、认证和 provider 选择：

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

3. **检查 Tool Search**：如果两个探测都通过，但真实 agent 轮次因格式错误的工具调用或过大的 prompt 而失败。本地 Ollama 模型、LM Studio 以及托管本地服务在 `tools.toolSearch` 未设置时会自动使用结构化 [Tool Search](../tools/tool-search.md)。其他后端可以通过 `tools.toolSearch: { mode: "tools" }` 启用它。这会延迟加载 schema，同时保留策略批准的能力。保持 `localModelLean` 未设置或将其设置为 `false`，以便可选工具仍然可用。同时检查服务器的实际上下文分配和内存使用情况。

4. **作为最后手段完全禁用工具**：通过为该模型设置 `models.providers.<provider>.models[].compat.supportsTools: false` - 此时 agent 将在无工具调用的情况下运行。

5. **检查失败的请求和服务器日志。** 检查聊天模板、上下文窗口、内存压力和服务器错误。仅文本探测成功并不能证明模型能够可靠地完成多步 agent 任务。

## 故障排除 {#troubleshooting}

- **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 crash/jetsam 日志进行比对，以检查模型服务器是否被终止。
- **上下文错误？** OpenClaw 会根据检测到的模型窗口或按模型设置的 `models.providers.<provider>.models[].contextTokens` 上限推导上下文窗口预检阈值。低于 20% 时发出警告，下限为 **8k**。低于 10% 时硬性阻止，下限为 **4k**。降低该模型条目的 `contextTokens` 或提高服务器/模型上下文限制。
- **`messages[].content ... expected a string`？** 在该模型条目上添加 `compat.requiresStringContent: true`。
- **`validation.keys`，或 “message entries only allow `role` and `content`”？** 在该模型条目上添加 `compat.strictMessageKeys: true`。
- **直接调用 `/v1/chat/completions` 可以工作，但 `openclaw infer model run --local` 在 Gemma 或其他本地模型上失败？** 首先检查 provider URL、模型引用、认证标记和服务器日志。`model run` 会完全跳过 agent 工具。如果 `model run` 成功但更大的 agent 轮次失败，请检查 Tool Search 和已分配的上下文。仅对于无法可靠调用工具的模型使用 `compat.supportsTools: false`。
- **工具调用显示为原始 JSON/XML/ReAct 文本，或 provider 返回空的 `tool_calls` 数组？** 不要添加一个盲目地将 assistant 文本转换为工具执行的代理。请先修复服务器的聊天模板和解析器。如果模型仅在强制使用工具时才能工作，请添加上述 `params.extra_body.tool_choice: "required"` 覆盖。仅将该模型条目用于每轮都预期有工具调用的会话。
- **安全**：本地模型会跳过 provider 侧过滤器。保持 agent 范围狭窄，并保持 compaction 开启，以限制 prompt 注入的影响范围。

### 本地模型精简模式 {#local-model-lean-mode}

在 **设置 → 代理默认值 → 代理** 中配置精简模式（显示高级设置），或使用下面的配置示例。保留的 `experimental.localModelLean` 键仍然受支持。

精简模式是一种高级故障排除覆盖，它会显式限制能力。本地推理通常使用 [Tool Search](../tools/tool-search.md) 来延迟加载 schema，同时保留能力，因此除非你确实想要更小的工具集，否则请保持精简模式关闭。

`agents.defaults.experimental.localModelLean: true` 会在目录构建之前移除可选工具：`browser`、`automations`、`message`、`image_generate`、`music_generate`、`video_generate`、`tts` 和 `pdf`。这些被移除的工具无法通过 Tool Search 找到。显式允许或交付必需的工具仍然可用，尽管 Tool Search 可能会将它们编入目录而不是直接暴露。当 `tools.toolSearch` 尚未设置时，精简模式还会将目录默认设置为结构化 Tool Search（`tool_search`、`tool_describe`、`tool_call`）。使用 `agents.entries.*.experimental.localModelLean` 将此范围限定到一个 agent。



安装流程不再写入此标志。对于较早的安装，`openclaw doctor --fix` 会在其所有权标记仍与默认模型匹配时，移除由入门流程拥有的 `true`。显式设置以及带有过期所有权标记的设置会被保留。将保留的标志设置为 `false` 可恢复可选能力；自动 Tool Search 仍适用于本地路由。

如果你已经全局调整了 Tool Search，OpenClaw 会保留该配置。设置 `tools.toolSearch: false` 可退出精简模式的 Tool Search 默认行为。

在结构化 `tools` 模式下，精简运行会让 `exec` 在 Tool Search 控件旁边直接可见，以便经过编码调优的本地模型仍可选择其熟悉的 shell 路径。这仅改变 schema 可见性：常规工具策略、沙箱和 exec 审批仍然适用。显式 `code` 和 `directory` 模式保持其常规压缩行为。

#### 为什么是这些工具 {#why-these-tools}

这些工具拥有最长的描述、最宽泛的参数结构，或者最可能让小型模型偏离正常的编码和对话路径。在小上下文或更严格的 OpenAI 兼容后端上，这决定了以下差异：

- 工具 schema 能放入提示词，还是挤占对话历史。
- 模型选择正确的工具，还是因过多相似 schema 而发出格式错误的工具调用。
- Chat Completions 适配器保持在结构化输出限制内，还是因工具调用负载大小而返回 400。

模型仍拥有 `read`、`write`、`edit`、`exec`、`apply_patch`、图像理解、网络搜索/抓取（如果已配置）、记忆以及会话/代理工具。除非设置 `tools.toolSearch: false`，否则其余目录工具仍可通过 Tool Search 访问；显式工具允许项可以恢复被精简模式移除的能力。

#### 何时开启 {#when-to-turn-it-on}

在证明模型能够与 Gateway 通信，但完整代理轮次出现异常后，再启用精简模式：

1. `openclaw infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"` 成功。
2. 普通代理轮次因格式错误的工具调用、提示词过大或模型忽略其工具而失败。
3. 切换 `localModelLean: true` 可消除该故障。

#### 何时保持关闭 {#when-to-leave-it-off}

保持精简模式未设置，或设置 `agents.defaults.experimental.localModelLean: false`，以保留完整的策略批准工具集。安装流程会保留显式选择，并且永远不会自动启用精简模式。

精简模式不会替代 `tools.profile`、`tools.allow`/`tools.deny`，或模型 `compat.supportsTools: false` 逃生门。如果要在特定代理上永久使用更窄的工具面，请优先使用这些稳定配置项。

#### 启用 {#enable}

```json5
{
  agents: {
    defaults: {
      experimental: {
        localModelLean: true,
      },
    },
  },
}

{
  agents: {
    entries: {
      local: {
        default: true,
        model: "lmstudio/gemma-4-e4b-it",
        experimental: {
          localModelLean: true,
        },
      },
    },
  },
}