Run OpenClaw with LM Studio Locally

LM Studio executes llama.cpp (GGUF) or MLX models on your own machine, either through its GUI application or via the headless llmster daemon. Installation instructions and product documentation live at lmstudio.ai.

Quick start

Install and start the server

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

lms server start --port 1234

Alternatively, launch the headless daemon:

lms daemon up

When you use the desktop app, turn on JIT so models load without hiccups; the LM Studio JIT and TTL guide covers this.

Set an API key if auth is enabled

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

Should authentication be turned off in LM Studio, simply leave the API key field empty while configuring. Refer to LM Studio Authentication.

Run onboarding

openclaw onboard

Pick LM Studio, and when the Default model prompt appears, select a model.

During a first-time guided setup, OpenClaw begins by querying /api/v1/models on whichever LM Studio host is default or configured. An already-present LLM gets offered automatically only if LM Studio reports tool training plus an effective context of at least 16K. When models are loaded, the context of the loaded instance wins over the larger advertised maximum. That same CLI/macOS setup ladder confirms the route by running a real completion before persisting it. No model is ever downloaded by the automatic check, and catalog entries that are embedding-only get skipped.

To swap the default model afterward:

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

Model keys in LM Studio follow an author/model-name pattern (for example qwen/qwen3.5-9b); OpenClaw model refs put the provider in front: lmstudio/qwen/qwen3.5-9b. To locate a model's exact key, run the command shown 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

You can also give the base URL, model, and API key directly:

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 expects the model key exactly as LM Studio returns it (for example qwen/qwen3.5-9b), with no lmstudio/ provider prefix. For servers that require authentication, supply --lmstudio-api-key (or define LM_API_TOKEN); when the server is unauthenticated, leave it out and OpenClaw instead saves a local non-secret marker. --custom-api-key remains accepted for backward compatibility, though --lmstudio-api-key is the better choice.

This operation writes models.providers.lmstudio and assigns lmstudio/<custom-model-id> as the default model. If you supply an API key, the lmstudio:default auth profile is written too.

The interactive setup may also ask for a preferred load context length, which then gets applied to every discovered model it writes to config.

Configuration

Streaming usage compatibility

On streamed responses, LM Studio does not always produce an OpenAI-shaped usage object. Instead, OpenClaw reconstructs token counts from llama.cpp-style timings.prompt_n / timings.predicted_n metadata. This same fallback applies to any OpenAI-compatible endpoint classified as local (loopback host), which includes other local backends like vLLM, SGLang, llama.cpp, LocalAI, Jan, TabbyAPI, and text-generation-webui.

Thinking compatibility

Whenever LM Studio's /api/v1/models discovery advertises model-specific reasoning options, OpenClaw surfaces the corresponding reasoning_effort values (none, minimal, low, medium, high, xhigh) in model compat metadata. Certain LM Studio builds advertise a binary UI option (allowed_options: ["off", "on"]) yet reject those literal values on /v1/chat/completions; before sending requests, OpenClaw converts that binary shape into the six-level scale, and it does the same for older saved config that still carries 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,
          },
        ],
      },
    },
  },
}

Model instances and context

Once preload is on, OpenClaw directs chat requests to a loaded instance whose context is large enough for the chosen model budget. The identifier LM Studio returns is what addresses a freshly loaded instance. Meanwhile, your configured model reference and the conversation's model identity retain the canonical model key.

Preload also makes embedding requests verify that their model is loaded, routing to the instance provisioned for the configured context length. This prevents input from being truncated by a smaller loaded instance, and it allows memory embeddings to recover after model eviction even when LM Studio JIT loading is off. The canonical model key is preserved for both embedding model and cache identity.

Disabling preload

Just-in-time (JIT) model loading is supported by LM Studio, meaning models load on the first request. By default OpenClaw preloads models via LM Studio's native load endpoint, which is useful when JIT is disabled. If you would rather have LM Studio's JIT, idle TTL, and auto-evict behavior control model lifecycle, turn OpenClaw's preload step off:

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

LAN or tailnet host

Point at the LM Studio host's reachable address, leave /v1 as is, and confirm 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 gives automatic trust to whatever endpoint it is configured with for model requests, covering loopback, LAN, and tailnet hosts (but not metadata, link-local, or local-use NAT64 64:ff9b:1::/48 origins). The same exact-origin trust applies to any custom or local OpenAI-compatible provider entry. If a request targets a different private host or port, models.providers.<id>.request.allowPrivateNetwork: true is still needed; to opt out of the default trust, set it to false.

Troubleshooting

Model discovery failures

If a configured server is unable to list models, OpenClaw reports either an unavailable catalog or a catalog authentication rejection. When the connection and credentials still match, a refresh can preserve the last successful inventory. A successful empty response wipes discovered models; models that were explicitly configured stay available without discovery. Fix the server connection or its credentials, then refresh the model list.

LM Studio not detected

Confirm that LM Studio is running:

lms server start --port 1234

When authentication is turned on, set LM_API_TOKEN as well. Check that the API can be reached:

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

Authentication errors (HTTP 401)

• Verify that LM_API_TOKEN corresponds to the key configured in LM Studio.
• Refer to LM Studio Authentication.
• If the server does not need authentication, keep the key empty during setup.

Related

• Model selection
• Ollama
• Local models