OpenClaw Adds One-Click Local Model Setup and Constrained Planner Output

OpenClaw has merged two complementary local-model changes into main: administrators can start Ollama or llama.cpp model preparation from web and macOS onboarding, and the conversational setup planner can request schema-constrained output from supported backends.

Together they remove two common failure points—dropping to the CLI to download a recommended model, then asking a small model to produce command JSON using prompt instructions alone. Neither merge changes the selected default model automatically, and neither is guaranteed to be present in an installed release yet.

What operators get

A setup action in web and macOS

PR #113476 connects the existing Gateway preparation transport to the web model-setup page and macOS onboarding.

When the Gateway advertises the method and the user has administrator scope, the client can show a set up local model action for the two currently supported preparation choices:

• ollama; and
• llama-cpp.

Starting the action uses the existing openclaw.setup.prepare.start wizard, displays streamed progress and refreshes model detection after completion. The action is hidden on older Gateways that do not advertise the method and suppressed when a usable detected candidate already covers the provider.

Completion deliberately does not claim setup is finished or make the downloaded model the default. Preparation proves that an artifact was pulled or downloaded; selection, configuration and a successful inference request remain separate acceptance steps.

A constrained setup planner

PR #113482 adds an optional JSON Schema response format to the embedded model stream and uses it for the system-agent planner only.

The planner expects a small object with a required reply, an optional command and no additional properties. Supported backends can constrain generation before OpenClaw’s tolerant parser receives the result:

• local Ollama uses its native format support;
• node-llama-cpp builds a JSON-schema grammar for tool-free requests;
• selected OpenAI and explicitly compatible OpenAI-style endpoints receive a json_schema response format; and
• unsupported or unknown backends omit the field and keep existing behaviour.

Ordinary agent-loop turns and prompts are unchanged. Tools continue to take precedence in the llama.cpp path.

Upstream reports that a real planner benchmark with gemma4:e4b improved from 26 successful cases out of 30 to 28 out of 30, with parse failures eliminated by constrained decoding. That is an upstream measurement, not an Academy reproduction, and it is not a promise that every small model will choose the semantically correct command.

The OpenAI-compatible limitation matters

The merged implementation does not set OpenAI’s strict: true mode. The maintainer’s recorded reason is that OpenClaw’s portable planner schema keeps command optional, while strict structured-output handling requires a different all-properties-required representation. Changing the shared planner contract or adding a backend-specific rewrite was left outside this patch.

The tolerant parser therefore remains the semantic boundary for that path. Operators should read “constrained planner output” carefully:

• Ollama and llama.cpp can apply backend-native grammar or format constraints;
• the OpenAI-compatible request is schema-guided but not an exact strict-schema guarantee; and
• a custom provider receives the request only when compat.supportsJsonSchemaResponseFormat explicitly enables that contract.

Do not set the compatibility flag merely because an endpoint accepts OpenAI-shaped requests. Confirm that it understands response_format: json_schema, handles OpenClaw’s optional command field, and fails predictably when the schema is unsupported.

A safer local-model rollout

When the features reach a release you intend to deploy:

1. Confirm Gateway/client compatibility. An old Gateway should hide the preparation action rather than receiving an unknown method.
2. Use an administrator account deliberately. Model downloads consume storage, bandwidth and potentially significant memory; the action is correctly scoped as an administrative operation.
3. Check the destination and size first. Ensure the host has sufficient disk space and that model artifacts land in the backup/exclusion policy you expect.
4. Watch the full progress stream. A button click is not completion. Confirm the wizard reaches a terminal success and model detection refreshes.
5. Select the model explicitly. Preparation does not set the default. Review context size, tool support and resource requirements before selection.
6. Run a direct inference smoke test. Prove the model loads after restart and returns a basic response without exhausting the host.
7. Exercise planner semantics. Test a reply-only request, a valid setup command, an ambiguous request and a denied or malformed action.
8. Retain fallback access. Keep a known-working provider or CLI recovery route until the local model survives restart and the setup flow is repeatable.

Plugin and provider implications

supportsJsonSchemaResponseFormat is now a persisted compatibility capability. That makes it more than a private planner optimisation: catalog normalization and configured-provider behaviour can preserve the setting over time.

Provider integrators should test the exact outbound request shape and response behaviour rather than advertising support by name. Unknown providers intentionally receive no response-format field, which is safer than sending a parameter they may reject.

Client maintainers should also note the current preparation contract: web and macOS encode the two accepted choice IDs. A future third preparable provider will require coordinated client work or a Gateway capability that advertises preparable choices dynamically.

Evidence and limits

For the UI change, upstream reports 44 web tests, 85 macOS onboarding tests, a successful macOS debug build and clean lint/format checks. The PR record did not include a redacted live web or macOS run showing click, streamed download and refreshed detection before merge.

For planner constraints, upstream reports 373 focused tests across 11 files, green backend capability suites and the cited 26/30 to 28/30 benchmark basis. The final maintainer note says the latest commits changed request typing and lazy tool detection rather than rerunning both real backends.

OpenClaw Academy reviewed the official merged PR records and chronology. We did not download a model, run the web/macOS wizard or reproduce the benchmark. The numbers and runtime behaviour above are attributed to upstream evidence.

Bottom line

OpenClaw’s local-model path is becoming an actual onboarding product rather than a collection of CLI prerequisites. One-click preparation reduces friction, while constrained decoding targets the exact point where small models often turn a setup conversation into malformed planner output.

The right operator stance is optimistic but unsentimental: a completed download is not a configured default, schema guidance is not semantic correctness, and the OpenAI-compatible path is not strict. Verify resource use, model selection and planner behaviour on the hardware and backend you will actually run.