lmstudio-cli

LM Studio CLI

当实际任务是操作 LM Studio 本身时，请使用此技能：确认是否存在 lms，检查本地或远程 LM Studio 服务是否确实在运行，发现准确的模型 ID，判断 OpenAI 兼容端点是否足够，以及为下游工具配置正确的基础 URL 和模型标识符。

不要将此技能用作通用的本地大模型比较技能。广泛的提供商比较或平台选择应交由研究/调研工作处理。一旦确认 LM Studio 本身正常运行，下游工具专属的扫描或应用安全操作应交由该工具的技能处理（例如 strix）。

何时使用此技能

• 用户直接提及 LM Studio、lms 或 LM Studio 服务
• 需要确认 LM Studio 是否在本地或另一台已授权主机上运行
• 需要获取 /v1/models 返回的准确模型 ID，以便配置其他工具
• 需要在 LM Studio 的 OpenAI 兼容端点和原生 REST API 之间做出选择
• 需要加载、检查或确认模型，以便 Agent 或 CLI 使用
• 下游工具支持 OpenAI 兼容端点，但用户需要 LM Studio 专属的设置帮助
• 远程/无头 LM Studio 工作流出现故障，需要确定性的验证路径

指令

步骤 1：确定运行模式

在执行命令前，先对请求分类：

1. 本地原生 CLI 模式 — 机器上应已安装 LM Studio，且可使用 lms
2. 远程 HTTP 模式 — 只需测试或使用已授权的 LM Studio 端点
3. LM Studio 原生管理模式 — 用户需要模型加载/列出/卸载行为，这些操作超出了通用 OpenAI 兼容调用的范围
4. 下游配置模式 — 用户已运行 LM Studio，需要将其他工具指向它

使用能够满足请求的最精简模式。

步骤 2：检查本地是否存在 lms

如果预期使用本地 CLI，先进行验证：

command -v lms
lms --help

如果缺少 lms，不要臆造本地 CLI 输出。只有在主机/端点明确获得授权时，才继续进行远程 HTTP 验证。

步骤 3：验证服务状态或端点连通性

进行本地原生检查：

lms server status
lms server status --json --quiet

进行远程或客户端式冒烟测试：

curl -fsS http://HOST:PORT/v1/models

可选的最简响应测试：

curl -fsS http://HOST:PORT/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "reply with exactly OK"}],
    "temperature": 0,
    "max_tokens": 8
  }'

如果需要可复用的解析器，而不是反复复制粘贴 curl，请使用 python3 scripts/check_lmstudio_endpoint.py --base-url http://HOST:PORT/v1。

步骤 4：发现准确的模型标识符

不要猜测模型名称。

任选以下一种方式：

lms ls
lms ls --llm
lms ps --json
curl -fsS http://HOST:PORT/v1/models

如果用户需要准确的已加载实例或运行时状态，优先使用 lms ps 或原生 REST API，而不是通用下游客户端视图。

步骤 5：仅在需要时使用 LM Studio 原生管理

当 OpenAI 兼容功能不足以满足需求时，使用原生 REST API 或 LM Studio 原生命令：

curl -fsS http://HOST:PORT/api/v1/models
curl -fsS http://HOST:PORT/api/v1/models/load \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_KEY",
    "context_length": 262144,
    "echo_load_config": true
  }'

以及本地命令：

lms load MODEL_KEY --identifier my-model
lms ps --json

对于上下文长度、加载状态或特定实例相关的问题，请使用此路径。如果 /v1/models 和 /v1/chat/completions 已能满足用户需求，不要把所有集成问题都当作原生管理问题。

步骤 6：谨慎配置下游工具

对于需要 OpenAI 兼容服务的工具，请传入准确的模型 ID 和基础 URL：

export LLM_API_BASE="http://HOST:PORT/v1"
export STRIX_LLM="openai/MODEL_ID"

某些 OpenAI 兼容客户端仍会要求填写 API 密钥，即使 LM Studio 本身不需要真实的提供商密钥。遇到这种情况时，只在下游工具的配置中设置客户端要求的虚拟密钥，不要声称 LM Studio 需要进行身份验证。

步骤 7：报告实际运行情况，不要猜测

一份良好的最终报告应包括：

• 本地是否存在 lms
• 是否已在本地、远程或两者均验证服务
• 测试所用的准确基础 URL
• 发现的准确模型 ID
• 用户是否只需要 OpenAI 兼容调用，还是需要 LM Studio 原生管理
• 下游工具所需的最终环境变量/配置片段或命令

示例

示例 1：安装了 LM Studio 的本地机器

用户询问：“是否已安装 lms，以及加载了哪个模型？”

推荐流程：

command -v lms
lms server status --json --quiet
lms ps --json

示例 2：供其他工具使用的远程 LM Studio 主机

用户询问：“让 Strix 连接到我的 LM Studio 主机。”

推荐流程：

curl -fsS http://HOST:PORT/v1/models
python3 scripts/check_lmstudio_endpoint.py --base-url http://HOST:PORT/v1
export STRIX_LLM="openai/MODEL_ID"
export LLM_API_BASE="http://HOST:PORT/v1"

示例 3：需要的不只是 OpenAI 兼容性冒烟测试

用户询问：“加载模型时使用更大的上下文长度，并告诉我实际生效的设置。”

推荐流程：

curl -fsS http://HOST:PORT/api/v1/models
curl -fsS http://HOST:PORT/api/v1/models/load \
  -H 'Content-Type: application/json' \
  -d '{"model":"MODEL_KEY","context_length":262144,"echo_load_config":true}'

示例 4：无头模式故障排查

用户询问：“我的 Linux 虚拟机上的 lms server start 出错了。我应该先检查什么？”

推荐流程：

• 验证 lms --help
• 运行 lms server status --json --quiet
• 如有需要，使用详细日志重新运行
• 修改配置前，先区分本地守护进程／服务故障与下游 OpenAI 客户端故障

最佳实践

1. 将本地 CLI 是否可用与远程 HTTP 是否可访问区分开来；两者相关，但并非同一事实。
2. 使用 LM Studio 返回的确切模型 ID，不要手动缩短名称。
3. 为下游工具配置连接时，优先使用 OpenAI 兼容端点；处理模型管理问题时，则优先使用原生 REST／CLI 接口。
4. 如果下游客户端要求填写 API 密钥字段，应将其说明为客户端兼容性问题，而非 LM Studio 的要求。
5. 将远程专用网络主机视为敏感对象；只探测用户授权访问的端点。
6. 只有在更简单的 /v1/models 路径无法满足需求时，才进一步提供加载状态或上下文长度方面的指导。
7. 明确职责边界：lmstudio-cli 用于验证和配置 LM Studio 本身；下游工具的技能负责端点正常工作后的操作。

参考资料

• references/cli-and-server-basics.md
• references/endpoints-and-escalation.md
• references/downstream-tool-wiring.md
• scripts/check_lmstudio_endpoint.py
• LM Studio CLI 文档
• LM Studio OpenAI 兼容性文档
• LM Studio REST API 文档