fix(agents): broaden local model lean profile

vincentkoc · vincentkoc · commit e66d7c6713ea · 2026-05-29T19:50:40.000+02:00
diff --git a/docs/concepts/experimental-features.md b/docs/concepts/experimental-features.md
@@ -30,17 +30,24 @@ Treat them differently from normal config:
 
 ## Local model lean mode
 
-`agents.defaults.experimental.localModelLean: true` is a pressure-release valve for weaker local-model setups. When it is on, OpenClaw drops three default tools — `browser`, `cron`, and `message` — from the agent's tool surface for every turn. Nothing else changes. Use `agents.list[].experimental.localModelLean` to enable or disable the same behavior for one configured agent.
+`agents.defaults.experimental.localModelLean: true` is a pressure-release valve for weaker local-model setups. When it is on, OpenClaw keeps the core coding/status surface but drops heavyweight web, media, channel, scheduler, node, and orchestration tools from the agent's tool surface for every turn. Use `agents.list[].experimental.localModelLean` to enable or disable the same behavior for one configured agent.
 
-### Why these three tools
+### What it trims
 
-These three tools have the largest descriptions and the most parameter shapes in the default OpenClaw runtime. On a small-context or stricter OpenAI-compatible backend that is the difference between:
+Lean mode trims tool families that tend to be noisy for small-context or stricter OpenAI-compatible backends:
+
+- Web and browser tools: `browser`, `web_fetch`, `web_search`, `x_search`.
+- Channel/scheduler/orchestration tools: `message`, `cron`, `gateway`, `nodes`, `agents_list`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `subagents`.
+- Media and document-generation tools: `canvas`, `image`, `image_generate`, `music_generate`, `pdf`, `tts`, `video_generate`.
+- Hosted code-execution style tools: `code_execution`.
+
+That can be the difference between:
 
 - Tool schemas fitting cleanly in the prompt vs. crowding out conversation history.
 - The model picking the right tool vs. emitting malformed tool calls because there are too many similar-looking schemas.
 - The Chat Completions adapter staying inside the server's structured-output limits vs. tripping a 400 on tool-call payload size.
 
-Removing them does not silently rewire OpenClaw — it just makes the tool list shorter. The model still has `read`, `write`, `edit`, `exec`, `apply_patch`, web search/fetch (when configured), memory, and session/agent tools available.
+Removing them does not silently rewire OpenClaw — it just makes the tool list shorter. The model still has core coding tools such as `read`, `write`, `edit`, `exec`, `apply_patch`, and `process`, plus lightweight status/planning tools such as `session_status` and `update_plan`. Plugin-owned memory tools stay available unless you narrow them separately with `tools.profile`, `tools.allow`, or `tools.deny`.
 
 ### When to turn it on
 
@@ -94,7 +101,7 @@ Restart the Gateway after changing the flag, then confirm the trimmed tool list
 openclaw status --deep
 ```
 
-The deep status output lists the active agent tools; `browser`, `cron`, and `message` should be absent when lean mode is on.
+The deep status output lists the active agent tools. Heavyweight web, media, channel, scheduler, node, and orchestration tools should be absent when lean mode is on.
 
 ## Experimental does not mean hidden
 
diff --git a/docs/gateway/local-models.md b/docs/gateway/local-models.md
@@ -315,7 +315,7 @@ If the model loads cleanly but full agent turns misbehave, work top-down — con
    openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
    ```
 
-3. **Try lean mode.** If both probes pass but real agent turns fail with malformed tool calls or oversized prompts, enable `agents.defaults.experimental.localModelLean: true`. It drops the three heaviest default tools (`browser`, `cron`, `message`) so the prompt shape is smaller and less brittle. See [Experimental Features → Local model lean mode](/concepts/experimental-features#local-model-lean-mode) for the full explanation, when to use it, and how to confirm it is on.
+3. **Try lean mode.** If both probes pass but real agent turns fail with malformed tool calls or oversized prompts, enable `agents.defaults.experimental.localModelLean: true`. It keeps core coding/status tools but trims heavyweight web, media, channel, scheduler, node, and orchestration tools so the prompt shape is smaller and less brittle. See [Experimental Features → Local model lean mode](/concepts/experimental-features#local-model-lean-mode) for the full explanation, when to use it, and how to confirm it is on.
 
 4. **Disable tools entirely as a last resort.** If lean mode is not enough, set `models.providers.<provider>.models[].compat.supportsTools: false` for that model entry. The agent will then operate without tool calls on that model.
 
diff --git a/docs/providers/ollama.md b/docs/providers/ollama.md
@@ -679,7 +679,7 @@ Use these as starting points and replace model IDs with the exact names from `ol
     ```
 
     Use `compat.supportsTools: false` only when the model or server reliably fails on tool schemas. It trades agent capability for stability.
-    `localModelLean` removes the browser, cron, and message tools from the agent surface, but it does not change Ollama's runtime context or thinking mode. Pair it with explicit `params.num_ctx` and `params.thinking: false` for small Qwen-style thinking models that loop or spend their response budget on hidden reasoning.
+    `localModelLean` keeps core coding/status tools but removes heavyweight web, media, channel, scheduler, node, and orchestration tools from the agent surface. It does not change Ollama's runtime context or thinking mode. Pair it with explicit `params.num_ctx` and `params.thinking: false` for small Qwen-style thinking models that loop or spend their response budget on hidden reasoning.
 
   </Accordion>
 </AccordionGroup>
diff --git a/src/agents/agent-tools.model-provider-collision.test.ts b/src/agents/agent-tools.model-provider-collision.test.ts
@@ -141,6 +141,11 @@ describe("applyModelProviderToolPolicy", () => {
       [
         { name: "read" },
         { name: "browser" },
+        { name: "web_search" },
+        { name: "web_fetch" },
+        { name: "x_search" },
+        { name: "sessions_spawn" },
+        { name: "image_generate" },
         { name: "cron" },
         { name: "message" },
         { name: "exec" },
diff --git a/src/agents/local-model-lean.test.ts b/src/agents/local-model-lean.test.ts
@@ -8,6 +8,56 @@ function tools(names: string[]): AnyAgentTool[] {
 }
 
 describe("local model lean tool filtering", () => {
+  it("keeps core coding tools while trimming heavyweight surfaces", () => {
+    expect(
+      filterLocalModelLeanTools({
+        tools: tools([
+          "read",
+          "write",
+          "edit",
+          "exec",
+          "apply_patch",
+          "process",
+          "session_status",
+          "update_plan",
+          "browser",
+          "web_search",
+          "web_fetch",
+          "x_search",
+          "code_execution",
+          "gateway",
+          "nodes",
+          "sessions_spawn",
+          "sessions_yield",
+          "subagents",
+          "image_generate",
+          "video_generate",
+          "tts",
+          "cron",
+          "message",
+        ]),
+        config: {
+          agents: {
+            defaults: {
+              experimental: {
+                localModelLean: true,
+              },
+            },
+          },
+        },
+      }).map((tool) => tool.name),
+    ).toEqual([
+      "read",
+      "write",
+      "edit",
+      "exec",
+      "apply_patch",
+      "process",
+      "session_status",
+      "update_plan",
+    ]);
+  });
+
   it("filters heavyweight tools for one configured agent", () => {
     const cfg: OpenClawConfig = {
       agents: {
diff --git a/src/agents/local-model-lean.ts b/src/agents/local-model-lean.ts
@@ -3,7 +3,31 @@ import { normalizeAgentId, parseAgentSessionKey } from "../routing/session-key.j
 import { resolveAgentConfig, resolveDefaultAgentId } from "./agent-scope-config.js";
 import type { AnyAgentTool } from "./agent-tools.types.js";
 
-const LOCAL_MODEL_LEAN_DENY_TOOL_NAMES = new Set(["browser", "cron", "message"]);
+const LOCAL_MODEL_LEAN_DENY_TOOL_NAMES = new Set([
+  "agents_list",
+  "browser",
+  "canvas",
+  "code_execution",
+  "cron",
+  "gateway",
+  "image",
+  "image_generate",
+  "message",
+  "music_generate",
+  "nodes",
+  "pdf",
+  "sessions_history",
+  "sessions_list",
+  "sessions_send",
+  "sessions_spawn",
+  "sessions_yield",
+  "subagents",
+  "tts",
+  "video_generate",
+  "web_fetch",
+  "web_search",
+  "x_search",
+]);
 
 function resolveLocalModelLeanAgentId(params: {
   config?: OpenClawConfig;
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
@@ -252,7 +252,7 @@ export const FIELD_HELP: Record<string, string> = {
   "agents.list[].experimental":
     "Per-agent experimental flags. Omitted fields inherit agents.defaults.experimental.",
   "agents.list[].experimental.localModelLean":
-    "Per-agent override for lean local-model mode. Enable it for one smaller local-model agent without trimming tools from every agent.",
+    "Per-agent override for lean local-model mode. Enable it for one smaller local-model agent without trimming heavyweight web, media, channel, and orchestration tools from every agent.",
   "agents.defaults.contextLimits":
     "Focused per-agent-context budget defaults for selected high-volume excerpts and injected prompt blocks. Use this to tune bounded read/injection sizes without reopening any unbounded call paths.",
   "agents.defaults.contextLimits.memoryGetMaxChars":
@@ -1127,7 +1127,7 @@ export const FIELD_HELP: Record<string, string> = {
   "agents.defaults.experimental":
     "Experimental agent-default flags. Keep these off unless you are intentionally testing a preview surface.",
   "agents.defaults.experimental.localModelLean":
-    "Experimental local-model prompt trim. When enabled, OpenClaw drops heavyweight default tools like browser, cron, and message for weaker or smaller local-model backends.",
+    "Experimental local-model prompt trim. When enabled, OpenClaw keeps core coding/status tools but drops heavyweight web, media, channel, scheduler, and orchestration tools for weaker or smaller local-model backends.",
   "agents.defaults.bootstrapPromptTruncationWarning":
     'Inject agent-visible warning text when bootstrap files are truncated: "off", "once", or "always" (default).',
   "agents.defaults.startupContext":
