Fundamentals
Experimental features
Experimental features in OmeniaClaw are opt-in preview surfaces. They are behind explicit flags because they still need real-world mileage before they deserve a stable default or a long-lived public contract.
Treat them differently from normal config:
- Keep them off by default unless the related doc tells you to try one.
- Expect shape and behavior to change faster than stable config.
- Prefer the stable path first when one already exists.
- If you are rolling OmeniaClaw out broadly, test experimental flags in a smaller environment before baking them into a shared baseline.
Currently documented flags
| Surface | Key | Use it when | More |
|---|---|---|---|
| Local model runtime | agents.defaults.experimental.localModelLean, agents.list[].experimental.localModelLean |
A smaller or stricter local backend chokes on OmeniaClaw's full default tool surface | Local Models |
| Memory search | agents.defaults.memorySearch.experimental.sessionMemory |
You want memory_search to index prior session transcripts and accept the extra storage/indexing cost |
Memory configuration reference |
| Codex harness | plugins.entries.codex.config.appServer.experimental.sandboxExecServer |
You want native Codex app-server 0.132.0 or newer to target an OmeniaClaw sandbox-backed exec-server instead of disabling Code Mode | Codex harness reference |
| Structured planning tool | tools.experimental.planTool |
You want the structured update_plan tool exposed for multi-step work tracking in compatible runtimes and UIs |
Gateway configuration reference |
Local model lean mode
agents.defaults.experimental.localModelLean: true is a pressure-release valve for weaker local-model setups. When it is on, OmeniaClaw drops three default tools — browser, cron, and message — from the agent's tool surface for every turn. It also defaults that run to structured Tool Search controls when tools.toolSearch is not explicitly configured, so larger plugin, MCP, or client tool catalogs stay behind tool_search, tool_describe, and tool_call instead of being dumped into the prompt. Runs that require direct message delivery keep that tool direct instead of enabling the lean-mode Tool Search default. Use agents.list[].experimental.localModelLean to enable or disable the same behavior for one configured agent.
Why these three tools
These three tools have the largest descriptions and the most parameter shapes in the default OmeniaClaw runtime. On a small-context or stricter OpenAI-compatible backend that is 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 OmeniaClaw — it just makes the direct tool list shorter. The model still has read, write, edit, exec, apply_patch, web search/fetch (when configured), memory, and session/agent tools available. Extra catalogs remain callable through Tool Search unless you explicitly set tools.toolSearch: false.
When to turn it on
Enable lean mode when you have already proved the model can talk to the Gateway but full agent turns misbehave. The typical signal chain is:
OmeniaClaw infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"succeeds.- A normal agent turn fails with malformed tool calls, oversized prompts, or the model ignoring its tools.
- Toggling
localModelLean: trueclears the failure.
When to leave it off
If your backend handles the full default runtime cleanly, leave this off. Lean mode is a workaround, not a default. It exists because some local stacks need a smaller tool surface to behave; hosted models and well-resourced local rigs do not.
Lean mode also does not replace tools.profile, tools.allow/tools.deny, or the model compat.supportsTools: false escape hatch. If you need a permanent narrower tool surface for a specific agent, prefer those stable knobs over the experimental flag.
If you already tune Tool Search globally, OmeniaClaw leaves that operator config alone. Set tools.toolSearch: false to opt out of the lean-mode Tool Search default.
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, then confirm the trimmed tool list with:
OmeniaClaw status --deepThe deep status output lists the active agent tools; browser, cron, and message should be absent when lean mode is on unless the current delivery mode forces direct message replies.
Experimental does not mean hidden
If a feature is experimental, OmeniaClaw should say so plainly in docs and in the config path itself. What it should not do is smuggle preview behavior into a stable-looking default knob and pretend that is normal. That's how config surfaces get messy.
