模型配置指南

概述

本章介绍如何为 CLI 配置后端 LLM 服务，以及如何在运行时管理可用模型。适用于以下场景：

• 初次安装 CLI 后，需要指定所使用的 LLM 服务。
• 切换服务提供商（例如从 DashScope 切换到 OpenAI 兼容服务）或更换 API Key。
• 在不重启会话的前提下，临时切换当前对话所使用的模型。
• 为同一服务提供商启用多个模型，便于日常切换。

本章涵盖以下内容：首次配置、模糊匹配模型选择器、会话内重新配置、模型列表管理。

命令关系说明

CLI 中模型相关能力划分为两类命令：

• 整体重配置：会话外的unitarylab configure 及会话内的 /config、/setup 命令，会完整执行 Provider → API Base → API Key → 模型列表的配置流程。
• 运行时管理：会话内的 /model 命令用于切换当前模型，/models 命令用于维护与查看可用模型列表，这两类命令不会修改 API Base 与 API Key。

两类命令均会将变更同步至本地配置文件及当前进程，下一轮请求即时生效。

首次配置

执行以下命令：

unitarylab configure

或在会话中执行 /config。具体配置流程如下：

1. 选择服务提供商

CLI 支持三种 Provider：

• DashScope：阿里云 DashScope 服务，使用预设的端点与模型默认列表。
• OpenAI：OpenAI 官方服务，使用预设的端点与模型默认列表。
• Custom：任意 OpenAI 兼容服务。选择此项后，需继续填写 API Base（OpenAI 兼容服务的根路径）。常见示例包括：
  • SiliconFlow
  • 本地 vLLM

2. 输入 API Key

根据提示粘贴对应服务的 API Key。输入过程中不会回显。

3. 选择模型列表

完成 API Base 与 API Key 的填写后，CLI 将尝试调用该服务的 /models 接口（OpenAI 兼容规范）：

• 拉取成功且列表非空：进入多选界面。列表较长时可直接输入model_id进入搜索模式；已启用的模型会被预选，最近使用过的模型自动置顶。 若希望配置的 模型id 在列表中不存在，可在按 Space 键选中 “补充模型id” 后按 Enter 进入补充模型 id的页面，根据指引完成配置。
• 拉取失败或不支持该接口：改为手动输入以逗号分隔的模型 ID 列表。对于 Custom Provider，不会预填示例模型；DashScope 与 OpenAI 仍会使用各自的预设默认列表。

CLI 将拒绝写入明显为占位符的模型 ID（例如 your-model-id、example 等）。

4. 连通性校验

写入配置前，CLI 会使用列表中的首个模型发起一次最小化请求：

• 校验成功：将配置写入本地文件，并将更新同步至当前进程。
• 校验失败：不写入配置，并输出失败原因（如 API Key 错误、Base 地址错误、模型 ID 不存在、网络不通等）。

此步骤可能产生极少量的 Token 消耗。如需跳过校验（例如服务不支持 chat/completions 探活），可在执行 configure 时设置环境变量 UNITARYLAB_CONFIGURE_SKIP_PROBE=1。

在会话内重新配置

在会话中，可随时执行：

[agent│deepseek-v4-pro] › /config

或等价的 /setup 命令。其流程与 unitarylab configure 完全一致，唯一区别在于：

• /config 中途取消：保留原有配置，不退出会话。
• unitarylab configure 中途取消：保留原有配置，但进程将以非零退出码退出。

会话内的重配置特别适用于以下场景：模型返回 401 错误（API Key 错误或过期）时，CLI 在交互式终端中会询问是否立即重新配置；确认后将进入 /config 流程，完成后可重发上一轮问题。

模糊匹配模型选择器

/model（无参数）、unitarylab 启动向导中的模型选择步骤以及拉取 /models 后的勾选页面，均使用同一套选择器：

• 直接键入即过滤：进入选择器后，任何输入字符都会进入查询缓冲区，无需先输入 /。
• 模糊匹配：支持子序列匹配、Token 前缀加分、整体前缀加分，且不区分大小写。例如：
  • qwmx 可匹配 qwen-max；
  • seed18 可匹配 doubao-seed-1-8。
• 自动置顶：排序优先级为：当前模型 → 最近使用过的模型 → 其余模型。前两类在右侧附有 当前 / 最近使用 标记。
• 键位操作：↑ / ↓ 或 Ctrl-P / Ctrl-N 移动选项；Enter 确认；Esc 或 Ctrl-C 取消。

切换当前模型：/model

进入会话后，可随时切换当前对话所使用的模型：

[agent│deepseek-v4-pro] › /model
（弹出模糊匹配选择器）

也可以直接携带参数，跳过选择器：

[agent│deepseek-v4-pro] › /model qwen3.5-flash
✓ model → qwen3.5-flash

切换操作会立即写入本地配置文件并同步至当前进程，下一轮请求即时生效。提示符将更新为 [agent│qwen3.5-flash] ›。

切换的前提是：目标模型必须已存在于「可用模型列表」中。若不存在，请通过 /config 重新拉取。

若使用 /model 切换到一个自定义输入的模型名称，系统会立即更新本地的提示符，但在你发送下一条实质性对话时才向服务器发起真实调用。如果你输入了不存在或未开通权限的模型名称，发送消息后会收到如下报错：

模型不可用（不存在或未开通）。

模型列表管理：/models

/models 命令允许在不重新执行 configure 的前提下，调整当前可用模型列表。所有变更均会同步至本地配置文件及当前进程，下一轮请求即时生效。

/models 不会修改 API Base 与 API Key。如需切换 LLM 端点，请使用 /config 命令。

使用建议

• 优先使用 /models refresh 而非 /config：如果仅需增减启用的模型，无需重新输入 API Key，直接刷新列表更为便捷且安全。
• API Key 失效时：直接执行 /config，让 CLI 重新进行连通性校验，避免错误配置的扩散。
• 多个 Provider 之间频繁切换：建议为每个 Provider 单独维护一份配置文件，并在启动时通过 --dotenv <path> 选项指定，而非反复执行 /config 进行覆盖。
• 企业内部模型服务：若服务不支持 /models 接口，可选择 Custom Provider 并手动输入模型列表。
• 网络环境：在国内使用DashScope API 不建议通过代理。若遇到连接失败或模型拉取超时,可优先排查网络配置。