LM Studio with OpenClaw

LM Studio serves llama.cpp (GGUF) or MLX models locally, either through a graphical interface or the command-line llmster daemon. Installation instructions and product details live at lmstudio.ai.

Quick start

Install and start the server

Get LM Studio (desktop) or llmster (headless) installed, then launch the server:

lms server start --port 1234

Alternatively, start the headless daemon:

lms daemon up

With the desktop app, turn on JIT so models load smoothly; consult the LM Studio JIT and TTL guide for details.

Set an API key if auth is enabled

export LM_API_TOKEN="your-lm-studio-api-token"

When LM Studio runs without authentication, leave the API key empty during configuration. Refer to LM Studio Authentication for more.

Run onboarding

openclaw onboard

Select LM Studio, then choose a model at the Default model prompt.

During a fresh guided setup, OpenClaw first contacts /api/v1/models on the default or configured LM Studio host. An existing LLM is proposed automatically only when LM Studio indicates tool training and at least 16K of usable context. For models already loaded, the loaded instance context overrides the larger advertised maximum. The same CLI/macOS setup ladder validates the route with an actual completion before persisting it. The automatic check never downloads a model and skips embedding-only catalog entries.

To change the default model later:

openclaw models set lmstudio/qwen/qwen3.5-9b

LM Studio model keys follow an author/model-name format (e.g. qwen/qwen3.5-9b); OpenClaw model refs add the provider prefix: lmstudio/qwen/qwen3.5-9b. To locate the exact key for a model, execute the command below and inspect the key field:

curl http://localhost:1234/api/v1/models

Non-interactive onboarding

openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice lmstudio

Alternatively, provide base URL, model, and API key explicitly:

openclaw onboard \
  --non-interactive \
  --accept-risk \
  --skip-health \
  --auth-choice lmstudio \
  --custom-base-url http://localhost:1234/v1 \
  --lmstudio-api-key "$LM_API_TOKEN" \
  --custom-model-id qwen/qwen3.5-9b

--custom-model-id accepts the model key as LM Studio returns it (e.g. qwen/qwen3.5-9b), without the lmstudio/ provider prefix. For authenticated servers, pass --lmstudio-api-key (or set LM_API_TOKEN); for unauthenticated servers, omit it and OpenClaw saves a local non-secret marker instead. --custom-api-key remains supported for backward compatibility, but --lmstudio-api-key is the recommended option.

This action writes models.providers.lmstudio and assigns the default model as lmstudio/<custom-model-id>. Supplying an API key also creates the lmstudio:default auth profile.

Interactive setup may also ask for a preferred load context length and applies it across the discovered models it stores in config.

Configuration

Streaming usage compatibility

LM Studio sometimes omits an OpenAI-shaped usage object on streamed responses. OpenClaw instead derives token counts from llama.cpp-style timings.prompt_n / timings.predicted_n metadata. Any OpenAI-compatible endpoint resolved as a local endpoint (loopback host) receives this same fallback, which also covers other local backends like vLLM, SGLang, llama.cpp, LocalAI, Jan, TabbyAPI, and text-generation-webui.

Thinking compatibility

When LM Studio's /api/v1/models discovery reports model-specific reasoning options, OpenClaw exposes matching reasoning_effort values (none, minimal, low, medium, high, xhigh) in model compat metadata. Some LM Studio builds advertise a binary UI option (allowed_options: ["off", "on"]) while rejecting those literal values on /v1/chat/completions; OpenClaw normalizes that binary shape to the six-level scale before sending requests, including for older saved config that still has off/on reasoning maps.

Explicit configuration

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        models: [
          {
            id: "qwen/qwen3-coder-next",
            name: "Qwen 3 Coder Next",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Disabling preload

LM Studio provides just-in-time (JIT) model loading, which loads models on first request. OpenClaw preloads models through LM Studio's native load endpoint by default, a step that helps when JIT is off. To hand model lifecycle control to LM Studio's JIT, idle TTL, and auto-evict behavior instead, turn off OpenClaw's preload step:

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        api: "openai-completions",
        params: { preload: false },
        models: [{ id: "qwen/qwen3.5-9b" }],
      },
    },
  },
}

LAN or tailnet host

Use the LM Studio host's reachable address, keep /v1, and ensure LM Studio is bound beyond loopback on that machine:

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://gpu-box.local:1234/v1",
        apiKey: "lmstudio",
        api: "openai-completions",
        models: [{ id: "qwen/qwen3.5-9b" }],
      },
    },
  },
}

lmstudio grants automatic trust to its configured endpoint for model requests, covering loopback, LAN, and tailnet hosts, though metadata, link-local, and local-use NAT64 64:ff9b:1::/48 origins are excluded. Any custom or local OpenAI-compatible provider entry receives the same exact-origin trust. For requests directed at a different private host or port, models.providers.<id>.request.allowPrivateNetwork: true is still necessary; setting it to false disables the default trust.

Troubleshooting

LM Studio not detected

Ensure LM Studio is operational:

lms server start --port 1234

When authentication is enabled, LM_API_TOKEN must also be configured. Confirm the API is accessible:

curl http://localhost:1234/api/v1/models

Authentication errors (HTTP 401)

Confirm that LM_API_TOKEN aligns with the key specified in LM Studio.
Refer to LM Studio Authentication for details.
If the server lacks authentication requirements, omit the key during setup.