LM Studio Python SDK 鉴权配置实现教程

许多人在安装 Python SDK 后便不再关注其安全配置，若使用共享电脑，或将 LM Studio API 开放至局域网且未开启鉴权，潜在风险将随之而来。自 LM Studio 0.4.0 版本起已支持 API Token，但默认不强制校验令牌。本文目标明确：先在应用中启用令牌鉴权开关，再让 Python SDK 从 LM_API_TOKEN 环境变量中读取密钥，确保源码、截图、代码版本库中均不出现真实的令牌明文。

确认此配置方案是否适合您的环境

温馨提示：若仅在本地单机使用、仅通过回环地址访问，默认不开启鉴权确实可以简化操作；但一旦服务需要开放给同局域网的其他设备、多人共用，或属于长期运行的项目，务必优先启用令牌鉴权。动手前请核对以下前提：LM Studio 版本需为 0.4.0 及以上、已开启 Developer 模式、Local Server 能正常运行，并且已安装好 lmstudio 包的 Python 环境。

如何验证前提条件？打开 Developer 页面，应能看到 Server Settings、Require Authentication 和 Manage Tokens 等入口。若找不到这些选项，请先进入 Settings > Developer 开启 Developer mode，再核对应用版本，切勿依据旧版界面印象盲目寻找按钮位置。

在 LM Studio 中创建受控令牌

步骤一：开启 API Token 鉴权

入口位置：打开 Developer 页面，点击进入 Server Settings。操作步骤：将开关拨至开启状态。开关旁的 Manage Tokens 是后续管理令牌的入口。

成功标志：开关保持开启状态，Server Settings 页面中同时显示当前活动令牌数量及 Manage Tokens 入口。常见问题：若开启开关后，Python 不带令牌仍能访问，切勿急于将令牌硬编码到代码中——请先确认代码连接的是当前 LM Studio 实例，检查是否误连到其他主机或服务，避免用硬编码令牌掩盖真实的连接问题。

步骤二：打开令牌管理器

入口位置：仍在 Server Settings 页面，点击 Manage Tokens。操作步骤：在弹出的 LM Studio API Tokens 窗口中先查看现有令牌列表，再点击右上角的 Create new token 新建一个。

成功标志：弹出的窗口标题为 LM Studio API Tokens，能看到 Create new token 按钮；首次使用列表为空，属于正常现象。常见问题：若点击 Manage Tokens 未弹出窗口，请先检查 Local Server 是否在运行、应用版本是否满足要求，再退出重新进入 Server Settings 尝试。

步骤三：命名令牌并收紧权限

入口位置：点击 Create new token 后，进入 Create new permission token 页面。操作步骤：为令牌起一个易于识别的名称（例如使用项目名或设备名），然后逐项选择 Allow 或 Deny。牢记原则：仅授予当前 Python 项目必需的权限，对不理解的权限先选择拒绝，待后续真正需要时再回来修改。

成功标志：令牌名称一目了然，权限项与项目需求匹配，Create token 按钮可点击。常见问题：若不确定某权限是否需要开启，切勿图省事全部选允许——建议先创建最小权限令牌，若后续调用被拒，再回到令牌列表增加权限即可。

步骤四：仅保存一次完整令牌

入口位置：点击 Create token 后弹出创建成功窗口。操作步骤：立即将完整令牌存入安全位置，例如系统密钥库、项目部署平台的 Secret 配置，或仅当前会话可见的环境变量中，存完后关闭窗口。该完整令牌仅显示一次，切勿截图、发送至聊天框或提交到 Git 仓库。

成功标志：返回令牌列表后，可看到刚创建的令牌名称、打码前缀，以及编辑和删除按钮。常见问题：若尚未保存就不小心关闭了完整令牌窗口，不要试图从列表中找回原令牌——直接新建一个，更新项目配置中的令牌，再删除丢失的旧令牌即可。

让 Python SDK 从环境变量读取令牌

步骤五：在启动 Python 前设置 LM_API_TOKEN

入口位置：打开待运行 Python 项目的终端会话，请确认正确。macOS 或 Linux 系统使用以下命令：

export LM_API_TOKEN="paste-token-here"

Windows PowerShell 使用：

$env:LM_API_TOKEN = "paste-token-here"

操作步骤：将命令中的占位内容替换为刚保存的令牌，该变量仅存在于当前终端会话或受保护的 Secret 配置中，不会泄露。可使用以下命令检查变量是否设置成功，该命令仅输出布尔值，不会打印密钥：

python -c "import os; print(bool(os.getenv('LM_API_TOKEN')))"

成功标志：命令输出 True。常见问题：若输出 False，请检查设置环境变量的终端与运行 Python 的终端是否为同一会话；若使用 IDE 启动项目，需在启动 IDE 或配置运行参数时注入环境变量，切勿将令牌直接写入源码。

步骤六：通过推荐方式发起一次 SDK 请求

入口位置：在项目中新建测试文件，不要在其中写入密钥。操作步骤：环境变量设置完成后，SDK 会自动读取 LM_API_TOKEN，代码中完全无需出现令牌明文：

import lmstudio as lms

model = lms.llm()
result = model.respond("Reply with OK")
print(result)

成功标志：已加载的模型正常返回响应，代码和终端日志中均无令牌痕迹。常见问题：若连接失败，请先检查 Local Server 是否运行、代码连接的是否为正确实例；若鉴权失败，则检查环境变量中的令牌是否有效、是否被删除、权限是否足够；若为模型相关错误，请单独排查模型是否安装、能否正常加载，避免将所有错误归因于令牌。

步骤七：需要多客户端时显式传入令牌

入口位置：仅当同一进程内需使用不同客户端或配置不同权限时，才需要显式配置客户端。操作步骤：仍从环境变量中获取令牌，传给官方支持的 api_token 参数即可：

import os
import lmstudio as lms

lms.configure_default_client(
    api_token=os.environ["LM_API_TOKEN"]
)

model = lms.llm()
print(model.respond("Reply with OK"))

若需隔离客户端生命周期，也可将同一环境变量传给 lms.Client；异步项目使用 lms.AsyncClient，注意官方异步鉴权示例要求 Python SDK 版本为 1.5.0 及以上。

成功标志：指定客户端能正常发送请求并获取结果，退出作用域后不影响其他客户端。常见问题：若默认客户端与作用域内客户端表现不一致，请逐一核对它们使用的环境变量、连接目标及令牌权限，切勿为了排查问题而将参数值打印到日志中，以免泄露密钥。

完成后对照这份检查清单

• LM Studio 版本为 0.4.0 及以上，Developer 页面和 Local Server 均可正常使用。
• Require Authentication 已开启，未携带有效令牌的请求无法获取受保护资源。
• 令牌名称能对应具体项目或设备，权限仅覆盖当前任务所需范围。
• 完整令牌已存入受保护位置，源码、截图、终端记录和版本库中均无明文密钥。
• LM_API_TOKEN 的存在性检查返回 True，检查过程中未打印令牌值。
• Python SDK 能通过环境变量正常完成请求；连接、鉴权、模型相关错误已分开排查。
• 四张界面截图均可正常打开，分别对应鉴权开关、令牌管理、权限设置、令牌列表四个页面。