LM Studio

LM Studio 在本地运行 llama.cpp（GGUF）或 MLX 模型，可作为 GUI 应用或无头 llmster 守护进程。有关安装和产品文档，请参阅 lmstudio.ai。

快速开始¶

1. 安装并启动服务器

安装 LM Studio（桌面版）或 llmster（无头版），然后启动服务器：

lms server start --port 1234

或者运行无头守护进程：

lms daemon up

如果使用桌面应用，请启用 JIT 以实现流畅的模型加载；请参阅 LM Studio JIT 和 TTL 指南。

2. 如果启用了身份验证，请设置 API 密钥

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

如果 LM Studio 身份验证已禁用，请在设置期间将 API 密钥留空。请参阅 LM Studio 身份验证。

3. 运行入门引导

openclaw onboard

选择 LM Studio，然后在 Default model 提示处选择一个模型。

服务器 URL 提示也接受主机简写，例如 localhost:1234。 无效的 URL 会保留在提示中，以便你在模型发现之前进行更正。

在全新的引导式设置中，OpenClaw 会先查询默认或已配置的 LM Studio 主机上的 /api/v1/models。只有当 LM Studio 报告工具训练且至少 16K 有效上下文时， 才会自动提供一个现有 LLM。对于已加载的模型，已加载实例的上下文优先于 更大的标称最大值。相同的 CLI/macOS 设置流程会在保存前使用真实补全验证 该路由。自动检查绝不会下载模型，并会忽略仅嵌入的目录条目。

之后更改默认模型：

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

LM Studio 模型密钥使用 author/model-name 格式（例如 qwen/qwen3.5-9b）；OpenClaw 模型引用会在前面添加提供商：lmstudio/qwen/qwen3.5-9b。运行下面的命令并查看 key 字段，即可找到某个模型的精确密钥：

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

非交互式入门¶

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

或者显式指定基础 URL、模型和 API 密钥：

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 接受 LM Studio 返回的模型密钥（例如 qwen/qwen3.5-9b），不带 lmstudio/ 提供商前缀。对于已认证服务器，请传入 --lmstudio-api-key（或设置 LM_API_TOKEN）；对于未认证服务器，请省略它，OpenClaw 会改为存储一个本地非机密标记。 出于兼容性考虑，--custom-api-key 仍会被接受，但推荐使用 --lmstudio-api-key。

这会写入 models.providers.lmstudio，并将默认模型设置为 lmstudio/<custom-model-id>。 提供 API 密钥还会写入 lmstudio:default 身份验证配置。

添加 --json 以获取机器可读的结果。连接、HTTP 和模型选择 失败会返回 JSON 错误，其中包含与人类输出相同的恢复指导， 并以非零状态退出，而不会应用提议的提供商配置。

交互式设置还可以额外提示首选加载上下文长度，并将其应用于 保存到配置中的已发现模型。

配置¶

流式用量兼容性¶

LM Studio 并不总是在流式响应中发出 OpenAI 形状的 usage 对象。OpenClaw 会改为从 llama.cpp 风格的 timings.prompt_n / timings.predicted_n 元数据中恢复 token 计数。任何被解析为本地端点（回环主机）的 OpenAI 兼容端点都会获得相同的 回退机制，这涵盖了其他本地后端，例如 vLLM、SGLang、llama.cpp、LocalAI、Jan、TabbyAPI 和 text-generation-webui。

思考兼容性¶

当 LM Studio 的 /api/v1/models 发现报告了特定模型的推理选项时，OpenClaw 会在模型兼容元数据中公开对应的 reasoning_effort 值（none、minimal、low、medium、high、xhigh）。某些 LM Studio 版本会宣传一个二元 UI 选项（allowed_options: ["off", "on"]），但在 /v1/chat/completions 上拒绝这些字面值；OpenClaw 会在发送请求前将该二元形状规范化为六级量表，包括仍带有 off/on 推理映射的旧保存配置。

显式配置¶

{
  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,
          },
        ],
      },
    },
  },
}

模型实例与上下文¶

启用预加载后，OpenClaw 会将聊天请求路由到具有足够上下文以满足所选模型预算的已加载实例。新加载的实例通过 LM Studio 返回的标识符寻址。你配置的模型引用和会话模型身份会保留规范模型密钥。

启用预加载后，嵌入请求也会检查其模型是否已加载，并路由到为已配置上下文长度准备好的实例。这可以避免通过较小的已加载实例截断输入，并让内存嵌入在模型逐出后恢复，即使 LM Studio JIT 加载已禁用。嵌入模型和缓存身份会保留规范模型密钥。

禁用预加载¶

LM Studio 支持即时（JIT）模型加载，即在首次请求时加载模型。OpenClaw 默认通过 LM Studio 的原生加载端点预加载模型，这在 JIT 被禁用时很有帮助。若要改为由 LM Studio 的 JIT、空闲 TTL 和自动逐出行为管理模型生命周期， 请禁用 OpenClaw 的预加载步骤：

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

局域网或 tailnet 主机¶

使用 LM Studio 主机的可访问地址，保留 /v1，并确保 LM Studio 在该机器上绑定到回环地址以外：

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

lmstudio 会自动信任其配置的端点用于模型请求，包括回环、局域网和 tailnet 主机（元数据、链路本地以及本地用途 NAT64 64:ff9b:1::/48 源除外）。任何自定义/本地 OpenAI 兼容 provider 条目都会获得相同的精确源信任。请求不同的私有主机或端口仍需要 models.providers.<id>.request.allowPrivateNetwork: true；将其设置为 false 可退出默认信任。

故障排除¶

模型发现失败¶

当已配置的服务器无法列出模型时，OpenClaw 会报告目录不可用或目录身份验证被拒绝。如果连接和凭据仍然匹配，刷新可以保留最后一次成功的清单。成功的空响应会清除已发现的模型；显式配置的模型无需发现即可保持可用。恢复服务器连接或更正其凭据，然后刷新模型列表。

未检测到 LM Studio¶

确保 LM Studio 正在运行：

lms server start --port 1234

如果启用了身份验证，请同时设置 LM_API_TOKEN。验证 API 是否可访问：

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

身份验证错误（HTTP 401）¶

• 检查 LM_API_TOKEN 是否与 LM Studio 中配置的密钥匹配。
• 参见 LM Studio 身份验证。
• 如果服务器不需要身份验证，请在设置期间将密钥留空。

相关¶

• 模型选择
• Ollama
• 本地模型