Skip to main content
Experimental features are opt-in preview surfaces behind explicit flags. They need more real-world mileage before they get a stable default or a long-lived contract.
  • Off by default unless a doc tells you to enable one.
  • Shape and behavior can change faster than stable config.
  • Prefer a stable path when one already exists.
  • Roll out broadly only after testing in a smaller environment first.

​
Currently documented flags

SurfaceKeyUse it whenMore
Local model runtimeagents.defaults.experimental.localModelLean, agents.list[].experimental.localModelLeanA smaller or stricter local backend chokes on OpenClaw’s full default tool surfaceLocal Models
Memory searchagents.defaults.memorySearch.experimental.sessionMemoryYou want memory_search to index prior session transcripts and accept the extra storage/indexing costMemory configuration reference
Codex harnessplugins.entries.codex.config.appServer.experimental.sandboxExecServerYou want native Codex app-server 0.132.0 or newer to target an OpenClaw sandbox-backed exec-server instead of disabling Code ModeCodex harness reference
Structured planning tooltools.experimental.planToolYou want the structured update_plan tool exposed for multi-step work tracking in compatible runtimes and UIsGateway configuration reference

​
Local model lean mode

agents.defaults.experimental.localModelLean: true drops heavyweight optional tools from the agent’s direct surface every turn: browser, cron, message, image_generate, music_generate, video_generate, tts, and pdf. Explicitly allowed or delivery-required tools remain available, though Tool Search may catalog them instead of exposing them directly. Lean mode also defaults plugin/MCP/client catalogs to structured Tool Search (tool_search, tool_describe, tool_call) when tools.toolSearch is not already set. Use agents.list[].experimental.localModelLean to scope this to one agent. If you already tune Tool Search globally, OpenClaw leaves that config alone. Set tools.toolSearch: false to opt out of the lean-mode Tool Search default.

​
Why these tools

These tools have the largest descriptions, broadest parameter shapes, or highest chance of distracting a small model from the normal coding and conversation path. On a small-context or stricter OpenAI-compatible backend that is the difference between:
  • Tool schemas fitting the prompt vs. crowding out conversation history.
  • The model picking the right tool vs. emitting malformed tool calls from too many similar schemas.
  • The Chat Completions adapter staying inside structured-output limits vs. a 400 on tool-call payload size.
Removing them only shortens the direct tool list. The model still has read, write, edit, exec, apply_patch, image understanding, web search/fetch (when configured), memory, and session/agent tools. Extra catalogs stay reachable through Tool Search unless you set tools.toolSearch: false; explicit tool allows can opt a lean agent back into a trimmed workflow.

​
When to turn it on

Enable lean mode once you have proved the model can talk to the Gateway but full agent turns misbehave:
  1. openclaw infer model run --gateway --model <ref> --prompt "Reply with exactly: pong" succeeds.
  2. A normal agent turn fails with malformed tool calls, oversized prompts, or the model ignoring its tools.
  3. Toggling localModelLean: true clears the failure.

​
When to leave it off

If your backend handles the full default runtime cleanly, leave this off. It is a workaround for local stacks that need a smaller tool surface, not a default for hosted models or well-resourced local rigs. Lean mode does not replace tools.profile, tools.allow/tools.deny, or the model compat.supportsTools: false escape hatch. For a permanent narrower tool surface on a specific agent, prefer those stable knobs.

​
Enable

{
  agents: {
    defaults: {
      experimental: {
        localModelLean: true,
      },
    },
  },
}
For one agent only: 
{
  agents: {
    list: [
      {
        id: "local",
        model: "lmstudio/gemma-4-e4b-it",
        experimental: {
          localModelLean: true,
        },
      },
    ],
  },
}
Restart the Gateway after changing the flag. Lean filtering removes browser, cron, message, image_generate, music_generate, video_generate, tts, and pdf unless you explicitly preserve them with tools.allow or tools.alsoAllow; Tool Search may still catalog preserved tools instead of exposing them directly.

​
Experimental does not mean hidden

An experimental feature should say so plainly in docs and in the config path itself, not hide behind a stable-looking default knob.