LM Studio 登录与鉴权配置：拿到密钥并填对客户端

截至 2026 年 11 月抓取时，LM Studio 官网首页同时挂着 Bionic agent、LM Link 与 LM Studio Hub（Beta），GitHub 上官方 docs 仓库最后更新在 2026 年 10 月 20 日。工具从「本地跑个模型」扩展到带云侧与 Agent 入口之后，账号和本地密钥变成了两条必须分开填的线：一条决定你能不能用云功能，另一条决定别的客户端能不能连你本机的 localhost:1234。本文只处理后者这条最容易卡住的鉴权链。

两套登录别搞混

在 lmstudio.ai 顶部能看到 Login、Create account、Pricing 和 Download 四个入口，这是官网账号体系：用于云侧功能与账户相关的操作，官网首页并未逐项列出「哪些功能必须登录」，这部分以官方定价页与账户页说明为准。

而第三方客户端（Onyx、OpenClaw 这类工具）要访问的是你本机 LM Studio 桌面端里跑的本地服务器，它对外提供 OpenAI 兼容接口，默认地址是 http://localhost:1234，是否需要密钥由本地服务器自己是否开启鉴权决定。这条线的官方说明在 LM Studio Authentication。

把这两件事混在一起最典型的后果是：你在第三方工具里反复登录 LM Studio 官网账号，但客户端连的其实是本机服务，永远 401。

开始前的 3 件事

1. 装好并启动 LM Studio 桌面端，客户端从 https://lmstudio.ai/ 的 Download 按钮拿安装包（首页同时提供 Copy download link）。装完确认系统托盘/窗口里有应用在运行，本地服务器随应用一起提供。
2. 确认本地服务器已经起来了：在终端执行 curl http://localhost:1234/api/v1/models，能返回模型列表即说明服务在监听；连不上就是服务没开，先回桌面端看本地服务器面板的状态。
3. 先决定要不要开鉴权。官方 OpenClaw 接入文档写得很直白：如果 LM Studio 关闭了鉴权，客户端把 API Key 留空即可；只有开启了鉴权的服务器才需要密钥。所以「要不要密钥」这一步是在桌面端决定的，不是客户端决定的。

拿密钥：桌面端到命令行验证

按官方鉴权文档的路径走（2026-11-03 与文档原文核对）：桌面端 Developers 页 → Server Settings，把鉴权开关打开——官方原话是 toggle the switch in the Developers Page > Server Settings；然后在同一处点 Manage Tokens 打开 API Tokens 弹窗 → Create Token，给它起名并勾选权限后创建、复制。官方明确说明：开关一开，REST API、Python SDK、Typescript SDK 的所有请求都要带这串 Token。

拿到密钥后先用命令行验一遍，这是最省事的排错手段——先确认服务本身通不通，再谈客户端：

# 不带密钥：若本地服务器未开鉴权，这里就能返回模型列表
curl http://localhost:1234/api/v1/models

# 带密钥（OpenAI 兼容的 Bearer 写法，官方鉴权页为准）
curl -H "Authorization: Bearer <你的密钥>" http://localhost:1234/api/v1/models

返回结果里每个模型有一个 key 字段，格式是 作者/模型名，例如 qwen/qwen3.5-9b。这个字符串后面填进客户端的「模型 ID」时要用，OpenClaw 官方文档明确说：取 key 字段的值，不带 lmstudio/ 这个 provider 前缀。

密钥填到哪里：三种位置对照

密钥最终要落到三个地方之一，取决于你用的是终端工具、脚本，还是别人的 Web 界面：

终端与脚本走环境变量，这是官方 OpenClaw 文档给出的写法：

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

OpenClaw 的非交互式配置把三件事一起给了：base URL、密钥、模型 ID。--custom-model-id 只填 key 字段的值：

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

第三方 Web 后台这边，Onyx 的 LM Studio 配置文档会自动帮你补上 /v1 路径（官方原话：Onyx adds the /v1 path for you）——所以 base URL 直接填 http://localhost:1234 即可，不要再手动拼 /v1；可选的 API Key 字段里粘贴密钥，服务器要求鉴权时才填。

四个最容易填错的地方

其一，base URL 手动拼了 /v1。 Onyx 会自动追加这个后缀，你再拼一次就成了 /v1/v1，请求直接 404——这类”看着更完整反而错”的填法最常见。

其二，模型 ID 带了 provider 前缀。 填 lmstudio/qwen/qwen3.5-9b 是错的，正确值是 qwen/qwen3.5-9b。核对方法很直接：curl http://localhost:1234/api/v1/models 看 key 字段。

其三，参数名用了旧写法。 --custom-api-key 仍然被接受以兼容旧配置，但官方文档写明推荐改用 --lmstudio-api-key。

其四，没开鉴权却硬塞密钥。 反过来也一样：服务端关着鉴权时客户端应当把 API Key 留空，OpenClaw 在这种情况下会存一个本地非密标记（空值标记），而不是真密钥。硬填多出来的密钥有时反而让某些客户端校验失败。

令牌的两条使用纪律

令牌只出现在请求头里：Authorization: Bearer <token>（OpenAI 兼容写法，官方鉴权页为准）。三条红线别踩——不把 token 写进会提交到 Git 的配置文件；不把同一枚 token 发到公开聊天/issue 里（看到即等于泄露，回 Server Settings 删掉重建）；客户端留空 API Key 的前提是服务端确实关着鉴权，开与关必须两端一致。

怎么算成功

三个可观察信号，任意一个通过都说明鉴权链是通的：

• 不带密钥的 curl http://localhost:1234/api/v1/models 能返回模型列表 —— 服务在跑，且鉴权未开。
• 带上 Authorization: Bearer <密钥> 后能返回列表 —— 密钥有效（若服务端未开鉴权，带不带都通，那说明你根本不需要填密钥）。
• 客户端侧能列出 qwen/qwen3.5-9b 这类模型 ID 并完成一次对话 —— 位置填对了。注意「能对话」比「能列模型」更强，因为有的客户端列模型不校验鉴权，只在真正推理时才用。

官方入口与延伸

• 官网与下载：https://lmstudio.ai/ （Download、Login、Pricing、Changelog 都在顶部导航）
• 官方鉴权文档：https://lmstudio.ai/docs/developer/core/authentication
• 官方 GitHub 组织：https://github.com/lmstudio-ai ，含 CLI lms、TypeScript SDK lmstudio-js、Python SDK lmstudio-python 与 docs 仓库（截至 2026-11 抓取，lms 约 5.4k star、lmstudio-js 约 1.8k、lmstudio-python 约 888）
• OpenClaw 的 LM Studio 接入文档：https://github.com/openclaw/openclaw/blob/70c40e4bdcbc4e9952d30121e8de86eeb0781618/docs/providers/lmstudio.md
• Onyx 后台的 LM Studio 配置说明：https://docs.onyx.app/admins/ai_models/lm_studio
• 桌面端问题反馈仓库：https://github.com/lmstudio-ai/lmstudio-bug-tracker

（本文标注为「官方文档写明」的部分均出自上述链接；把默认端口、密钥格式、参数命名串起来的那套排错判断，是基于这些文档做的推算，不是官方结论。）

参考来源

• LM Studio – Onyx Documentation
• LM Studio
• LM Studio