Model Configuration Guide

Overview

This chapter explains how to configure the backend LLM service for the CLI and how to manage available models at runtime. It applies to the following scenarios:

• Specifying which LLM service to use after installing the CLI for the first time.
• Switching service providers (for example, from DashScope to an OpenAI-compatible service) or replacing an API key.
• Temporarily switching the model used in the current conversation without restarting the session.
• Enabling multiple models for the same service provider to make day-to-day switching easier.

This chapter covers: initial configuration, the fuzzy-matching model selector, in-session reconfiguration, and model list management.

Command Relationships

Model-related capabilities in the CLI fall into two categories:

• Full reconfiguration: unitarylab configure outside a session, and the /config and /setup commands within a session. These run the complete Provider → API Base → API Key → model list configuration flow.
• Runtime management: The in-session /model command switches the current model, and the /models command maintains and inspects the list of available models. Neither command modifies the API Base or API Key.

Both categories of commands sync changes to the local configuration file and to the current process, taking effect on the next request.

Initial Configuration

Run:

unitarylab configure

Or run /config within a session. The configuration flow is as follows:

1. Choose a Service Provider

The CLI supports three providers:

• DashScope: Alibaba Cloud’s DashScope service, using a preset endpoint and a default model list.
• OpenAI: OpenAI’s official service, using a preset endpoint and a default model list.
• Custom: Any OpenAI-compatible service. Selecting this option requires you to provide an API Base (the root path of the OpenAI-compatible service). Common examples include:
  • SiliconFlow
  • A local vLLM instance

2. Enter the API Key

Paste the API key for the corresponding service when prompted. Input is not echoed to the screen.

3. Choose the Model List

After you provide the API Base and API Key, the CLI attempts to call the service’s /models endpoint (per the OpenAI-compatible specification):

• If the call succeeds and returns a non-empty list: A multi-select interface appears. For long lists, you can type a model_id directly to enter search mode. Already-enabled models are pre-selected, and recently used models are automatically pinned to the top. If the model ID you want to configure is not in the list, press Space to select “Add custom model ID,” then press Enter to open the manual entry page and follow the prompts.
• If the call fails or the endpoint is not supported: You will instead enter a comma-separated list of model IDs manually. For a Custom provider, no example models are pre-filled; DashScope and OpenAI continue to use their respective preset default lists.

The CLI will reject obvious placeholder model IDs (such as your-model-id, example, and so on).

4. Connectivity Check

Before writing the configuration, the CLI sends a minimal request using the first model in the list:

• Check passes: The configuration is written to the local file and synced to the current process.
• Check fails: The configuration is not written, and the CLI reports the cause of the failure (such as an incorrect API key, a wrong Base URL, a non-existent model ID, or a network error).

This step may consume a very small number of tokens. To skip the check (for example, when the service does not support chat/completions probing), set the environment variable UNITARYLAB_CONFIGURE_SKIP_PROBE=1 when running configure.

In-Session Reconfiguration

You can run the following at any time during a session:

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

Or use the equivalent /setup command. The flow is identical to unitarylab configure, with one difference:

• Cancelling /config mid-way: The existing configuration is preserved, and the session continues.
• Cancelling unitarylab configure mid-way: The existing configuration is preserved, but the process exits with a non-zero exit code.

In-session reconfiguration is particularly useful in the following situation: when the model returns a 401 error (an invalid or expired API key), the CLI asks in the interactive terminal whether you want to reconfigure immediately. If you confirm, you are taken through the /config flow, and once it completes, you can resend your previous message.

The Fuzzy-Matching Model Selector

The same selector is used by /model (when called without arguments), by the model selection step in the unitarylab setup wizard, and by the selection screen shown after the /models endpoint is queried:

• Type to filter: Once the selector is open, any character you type goes into the query buffer — there is no need to type / first.
• Fuzzy matching: Supports subsequence matching, with bonus scoring for token prefixes and full prefixes; matching is case-insensitive. For example:
  • qwmx matches qwen-max.
  • seed18 matches doubao-seed-1-8.
• Automatic pinning: Sort priority is: the current model → recently used models → all other models. The first two categories are labelled current / recently used on the right.
• Key bindings: ↑ / ↓ or Ctrl-P / Ctrl-N to move between options; Enter to confirm; Esc or Ctrl-C to cancel.

Switching the Current Model: /model

Once in a session, you can switch the model used in the current conversation at any time:

[agent│deepseek-v4-pro] › /model
(opens the fuzzy-matching selector)

You can also pass an argument directly to bypass the selector:

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

The switch is written to the local configuration file immediately and synced to the current process, taking effect on the next request. The prompt updates to [agent│qwen3.5-flash] ›.

Switching requires that the target model already exist in the “available models” list. If it does not, run /config to fetch the list again.

If you use /model to switch to a custom-entered model name, the local prompt is updated immediately, but the actual call to the server is not made until you send your next substantive message. If the model name does not exist or has not been enabled for your account, you will see the following error when sending a message:

Model unavailable (does not exist or is not enabled).

Managing the Model List: /models

The /models command lets you adjust the current list of available models without running configure again. All changes are synced to the local configuration file and to the current process, taking effect on the next request.

/models does not modify the API Base or API Key. To switch LLM endpoints, use the /config command.

Recommendations

• Prefer /models refresh over /config: If you only need to add or remove enabled models, there is no need to re-enter the API key — refreshing the list directly is more convenient and safer.
• When the API key has expired: Run /config directly so the CLI can re-run the connectivity check, preventing a faulty configuration from propagating further.
• When switching frequently between multiple providers: Maintain a separate configuration file for each provider and specify the path with --dotenv <path> at startup, rather than repeatedly running /config to overwrite the configuration.
• For enterprise-internal model services: If the service does not support the /models endpoint, choose the Custom provider and enter the model list manually.