跳转至

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

在 LM Studio 中安装另一个模型后,刷新 OpenClaw 的模型列表:

openclaw models list --provider lmstudio --refresh

在默认合并模式下,刷新会添加发现的模型,同时保留你已配置的条目及其自定义元数据,包括名称和上下文限制。 空的已配置 models 数组也支持在未认证服务器上进行发现。models.mode: "replace" 仅保留显式配置的模型。

非交互式入门

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。

Gemma 4 工具调用恢复

对于使用 openai-completions 的 Gemma 4 模型,如果服务器以文本形式返回完整的独立 <|tool_call>call:...<tool_call|> 批次,OpenClaw 会恢复它们, 包括当该调用是 finish_reason: "stop" 之前的最后内容时。 恢复会保留原始字符串参数,并要求完整的参数对象; 不完整的调用、普通文本和代码示例仍保持为文本。被截断、过滤、 取消或未终止的流不会授权恢复的调用。如果原生 工具调用也出现在流中,它们仍保持权威,原始文本 不会被提升。

思考兼容性

当 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 推理映射的旧保存配置。

对于分级选项,新的发现会将 max(以及 Ultra 的提供商推理强度)映射到最高的 已宣传规范推理强度,无论选项顺序如何。例如,off、low、medium 会将 max 映射到 medium。现有保存的分级 reasoningEffortMap 值仍保持为显式 配置;重新运行 LM Studio 设置以根据当前服务器元数据重新生成它们。

显式配置

{
  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 返回的标识符进行寻址。您配置的模型引用和会话模型身份会保留规范模型键。

模型加载使用已配置提供程序的 timeoutSeconds(或请求超时覆盖值),默认值为两分钟,与嵌入加载一致。对于缓慢的冷加载,请增大 models.providers.lmstudio.timeoutSeconds。如果加载失败,且所有已知已加载实例都太小,OpenClaw 会报告模型和请求的上下文,而不是将提示发送到较小的实例。请在 LM Studio 中等待加载完成并重试,或降低模型的 contextTokens。

启用预加载后,嵌入请求也会检查其模型是否已加载,并路由到为已配置上下文长度准备好的实例。这可避免通过较小的已加载实例截断输入,并让内存嵌入在模型被逐出后恢复,即使 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" }],
      },
    },
  },
}

LAN 或 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 会自动信任其配置的端点用于模型请求,包括回环、LAN 和 tailnet 主机(元数据、链路本地以及本地用途 NAT64 64:ff9b:1::/48 源除外)。任何自定义/本地 OpenAI 兼容提供程序条目都会获得相同的精确源信任。对不同的私有主机或端口的请求仍需要 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 身份验证。
  • 如果服务器不需要身份验证,请在设置期间将密钥留空。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw