Connecting Desktop LLM Clients to Custom API Gateways: A Practical Configuration Guide

1. Background and Motivation

As LLM capabilities become more widely available, more developers use desktop clients for daily chat, document processing, coding assistance, and similar tasks. Desktop clients offer clear advantages over web interfaces: local file reading and editing, scheduled task execution, and tighter integration with the operating system. A common pain point, however, is that most desktop clients only accept their official account system and API format by default. Existing third-party API resources, especially OpenAI-compatible model services, often cannot be connected directly.

The usual approach is to use the client’s developer mode to configure a custom inference gateway that forwards requests to your own API endpoint. This article focuses on the general technical workflow: end-to-end configuration, multi-model management strategies, and practical caveats. Whether a desktop client offers such developer mode depends on its implementation. Before configuring anything, confirm that your client supports this capability and comply with the service provider’s terms of use.

2. Prerequisites

Before configuring the gateway, complete the following preparation steps:

1. Download and install the official desktop client. Always obtain the installer from official channels. Avoid repackaged or unofficial builds, which can introduce API key leakage risks.

2. Prepare third-party API information, including three items:

   • Base URL: the root address of the API service, for example https://your-gateway.example.com/v1;
   • API Key: the key issued by the service provider;
   • Available model list: the model identifiers that your endpoint actually supports.

3. Confirm network connectivity. Verify the endpoint with curl beforehand:

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "your-model", "messages": [{"role": "user", "content": "ping"}]}'

If the request returns a valid JSON response, the gateway path is working and you can proceed to client configuration.

3. Enable Developer Mode

After installation, do not sign in with the official account first. The developer mode entry is usually available in the Help menu, and the path differs slightly by operating system:

• macOS: In the top menu bar, go to Help → Troubleshooting → Enable Developer mode.
• Windows: Check the official documentation. The same menu hierarchy is typically available from the menu button in the top-left corner of the desktop app.

After developer mode is enabled, a Developer entry appears in the menu. Select the third-party inference configuration item, similar to Configure third-party inference, to open the gateway configuration interface.

Note: Developer mode is an advanced-user feature, and its interface and options may change across versions. If you cannot find the relevant menu, check the latest official documentation first.

4. Gateway Parameter Configuration

The configuration interface mainly requires three items:

1. Connection method: Gateway

There are usually multiple connection options. Gateway means using your own API for inference, and it is often the default option. Selecting it means the client no longer relies on the built-in account authentication system; instead, it sends requests to the address and key you provide.

2. Gateway base URL

Enter the root address of the third-party API. There are several common pitfalls:

• Check whether the path requires a version prefix such as /v1. Conventions differ between providers, and an incorrect path can cause 404 errors.
• Avoid a trailing slash at the end of the address.
• For internally deployed model services, make sure the machine running the client can reach the address. Proxy settings may intercept local requests; configure a proxy allowlist if necessary.

3. Gateway API key

Enter your key. Security recommendations:

• Do not use a production root key. Use a scoped sub-key with limited permissions whenever possible.
• Rotate keys regularly.
• Do not commit configuration files containing keys to code repositories.

4. Model list

In the model section of the configuration interface, enter the model identifiers that your endpoint can call. These models will appear in the client’s model selector. Only list genuinely available models to avoid “ghost models” that fail as soon as they are selected.

For a typical OpenAI-compatible endpoint, the model list can be queried through the /v1/models endpoint:

curl https://your-gateway.example.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Fill the model IDs from the response into the configuration individually or in batches.

5. Managing Multiple Models and Configurations

If you have multiple LLM service addresses, such as services deployed with different capabilities or multiple custom gateways, use the configuration management feature to switch between them:

1. Default configuration: After the first configuration is completed, it becomes the default and takes effect. The interface usually shows the active status with an indicator such as a green dot.
2. Duplicate and rename: Copy an existing configuration, rename it, and change only the URL, key, and model list to quickly create a second configuration. This is faster than creating one from scratch.
3. New configuration: Create a blank configuration directly. This is useful when model formats differ significantly.
4. Direct access to configuration files: Each configuration corresponds to a JSON file, and the interface usually provides an entry to open the file location. This is important because you can edit the JSON directly for batch management or even generate configurations with scripts.

A typical configuration file structure looks roughly like this, with field names depending on the actual client:

{
  "gatewayBaseUrl": "https://your-gateway.example.com/v1",
  "gatewayApiKey": "YOUR_API_KEY",
  "models": ["model-a", "model-b"]
}

Consider storing configuration files in personal notes or a private configuration repository, with keys masked, so you can quickly restore your working environment across multiple devices.

6. Validation and Troubleshooting

After configuration, restart the client. The models you entered should appear in the model selection interface. Select one and start a conversation to validate the setup. If it fails, troubleshoot in the following order:

1. 401/403: Invalid key or insufficient permissions. Check whether the key was copied completely and whether it contains extra spaces.
2. 404: The Base URL path is incorrect. Check the version prefix carefully.
3. Timeout: The network is unreachable or a proxy is blocking requests. Check system proxy and firewall settings.
4. Model not found: The model identifier in the request does not match what the endpoint actually supports. Recheck the model list.
5. Response format error: Confirm that the third-party endpoint is compatible with the request and response format expected by the client. If necessary, perform protocol conversion at the gateway layer.

7. Conclusion

Connecting a custom gateway through developer mode essentially turns a desktop client from a tool bound to a single service into a general inference frontend. The core configuration comes down to three things: the correct connection method, an accurate gateway URL and API key, and a real model list. For advanced use, JSON configuration files enable scripted management of multiple model environments. Combined with the desktop client’s local advantages in document operations and scheduled tasks, you can build an AI workspace with a model backend that you fully control.