LM Studio Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: LM Studio

개요

이 페이지는 OpenClaw LM Studio provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Run OpenClaw with LM Studio

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

공식 문서 기반 상세

아래는 공식 providers/lmstudio 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

LM Studio runs llama.cpp (GGUF) or MLX models locally, as a GUI app or the headless llmster daemon. For install and product docs, see lmstudio.ai.

빠른 시작

Install and start the server

Install LM Studio (desktop) or `llmster` (headless), then start the server:

```bash
lms server start --port 1234
```

Or run the headless daemon:

```bash
lms daemon up
```

If using the desktop app, enable JIT for smooth model loading; see the
[LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict).

Set an API key if auth is enabled

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

If LM Studio authentication is disabled, leave the API key blank during setup. See
[LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication).

Run onboarding

```bash
openclaw onboard
```

Choose `LM Studio`, then pick a model at the `Default model` prompt.

On a fresh guided setup, OpenClaw first queries `/api/v1/models` on the
default or configured LM Studio host. An existing LLM is offered automatically
only when LM Studio reports tool training and at least 16K of effective
context. For loaded models, the loaded instance context takes precedence over
the larger advertised maximum. The same CLI/macOS setup ladder verifies the
route with a real completion before saving it. The automatic check never
downloads a model and ignores embedding-only catalog entries.

Change the default model later:

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

LM Studio model keys use an author/model-name format (e.g. qwen/qwen3.5-9b); OpenClaw model refs prepend the provider: lmstudio/qwen/qwen3.5-9b. Find the exact key for a model by running the command below and looking at the key field:

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

Non-interactive onboarding

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

Or specify base URL, model, and API key explicitly:

openclaw onboard \
  --non-interactive \
  --accept-risk \
  --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 takes the model key as returned by LM Studio (e.g. qwen/qwen3.5-9b), without the lmstudio/ provider prefix. Pass --lmstudio-api-key (or set LM_API_TOKEN) for authenticated servers; omit it for unauthenticated servers and OpenClaw stores a local non-secret marker instead. --custom-api-key is still accepted for compatibility, but --lmstudio-api-key is preferred.

This writes models.providers.lmstudio and sets the default model to lmstudio/<custom-model-id>. Providing an API key also writes the lmstudio:default auth profile.

Interactive setup can additionally prompt for a preferred load context length and applies it across the discovered models it saves to config.

설정

Streaming usage compatibility

LM Studio doesn't always emit an OpenAI-shaped usage object on streamed responses. OpenClaw recovers token counts from llama.cpp-style timings.prompt_n / timings.predicted_n metadata instead. Any OpenAI-compatible endpoint resolved as a local endpoint (loopback host) gets this same fallback, which covers other local backends such as 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 supports just-in-time (JIT) model loading, loading models on first request. OpenClaw preloads models through LM Studio's native load endpoint by default, which helps when JIT is disabled. To let LM Studio's JIT, idle TTL, and auto-evict behavior own model lifecycle instead, disable 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 make sure 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 automatically trusts its configured endpoint for model requests, including loopback, LAN, and tailnet hosts (except metadata/link-local origins). Any custom/local OpenAI-compatible provider entry gets the same exact-origin trust. Requests to a different private host or port still require models.providers.<id>.request.allowPrivateNetwork: true; set it to false to opt out of the default trust.

문제 해결

LM Studio not detected

Make sure LM Studio is running:

lms server start --port 1234

If authentication is enabled, also set LM_API_TOKEN. Verify the API is reachable:

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

Authentication errors (HTTP 401)

• Check that LM_API_TOKEN matches the key configured in LM Studio.
• See LM Studio Authentication.
• If the server does not require authentication, leave the key blank during setup.

관련 문서

• Model selection
• Ollama
• Local models

검증 체크리스트

• openclaw models list --provider lmstudio 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers