Model providers: official, gateway and custom endpoint

Model providers come in three types: official, third-party gateway and custom endpoint. All three work, but auth, model lists and error codes differ, and configuring by type is what makes diagnosis fast.

Three provider types

Compare the differences, then pick one.

Official is the least work. Few fields and a stable model list suit most daily use (source).

A gateway adds a forwarding layer. It can unify auth or billing, but protocol and model list depend on its implementation; read the docs before configuring.

A custom endpoint is the most flexible and the easiest to mistype. You align base URL, protocol and model name yourself, and one extra or missing path segment returns 404.

Official provider: smallest working config

The key is a valid key and the right model.

1. Obtain an API key and confirm quota and permissions.
2. Select the official provider in model settings.
3. Enter the key and choose the target model.
4. Save, then send a test message.
5. Confirm the request succeeds before tuning parameters.

Leave advanced parameters alone at first, and keep key and model matched. Temperature and output limits stay default until the minimal request passes. A privileged key paired with a model you cannot access shows up as an auth failure or a missing model.

Gateway: confirm the protocol first

Gateways differ in protocol and model list.

1. Determine whether the gateway is OpenAI-compatible or uses its own protocol.
2. Enter the gateway URL and key, noting any extra headers.
3. Test the model list; if it fails, enter the model name manually.
4. Send a message to confirm the forwarding chain works.
5. Record gateway version and configuration for later diagnosis.

A gateway may rewrite error codes. An upstream 401 can surface as a 500; read gateway logs instead of trusting the client message.

Gateway model names may be renamed. It maps its own aliases to upstream models, and a wrong alias looks like a missing model.

Custom endpoint: address and path

Custom endpoints fail most often on the base URL.

1. Confirm the protocol: OpenAI-compatible or something else.
2. Enter the base URL with or without /v1 and version segments exactly as documented.
3. Enter the model name matching case and suffix character for character.
4. Add extra headers and timeouts if required.
5. Save, test the list, then test a conversation.

One extra path segment means 404. Some services require /v1, others reject it; copy the docs instead of guessing.

A model name is not a display name. The name in an interface may be an alias; configuration needs the identifier from the vendor docs.

Fields and order

Fill identity, address, model, then parameters.

1. Provider ID: use a distinguishable name such as official or gateway-a.
2. base URL: default for official, required for gateways and custom endpoints.
3. Key: must belong to the same service as the address, never mixed.
4. Model: discover automatically, then enter manually if that fails.
5. Parameters: tune last, so configuration and parameter problems stay separate.

The order exists so each layer is verified. Wrong identity invalidates everything after it, wrong address blocks the model list, and a wrong model fails the request.

Configure one provider at a time. Adding several at once makes the failing entry unidentifiable.

Connectivity tests

Three tests, one layer at a time.

1. List test: if models load, address and auth are broadly correct.
2. Chat test: a short message returns a reply, so the chain is complete.
3. Log test: requests hit the expected address and model with no retries or fallbacks.

A failed list is not always a key problem. 404 points to the address, 401 to auth; read the status code before editing configuration.

A failed chat needs the full error. Client messages may be wrapped; upstream errors in logs are more specific.

Troubleshooting

Four failure classes cover most provider setups.

1. 401/403: wrong, expired or unauthorized key; check key and endpoint.
2. 404: wrong base URL or model name; check docs and path.
3. Timeout: network, proxy or slow gateway forwarding; test connectivity first.
4. List works, chat fails: protocol or model permission issue; inspect the request body and logs.

The entry points are status code, logs and docs. The code identifies the layer, logs give detail, docs confirm field names.

Roll back to the last working config. After a bad edit, do not keep trying variations; restore a known-good state and change one thing at a time.

Next steps

Choose the type, fill in order, run three tests. For local models, read Connecting DeepSeek Harness to a local model. For two common errors, read Invalid API key and model discovery 404. For proxy setup, read How to configure a proxy.

Sources: DeepSeek Harness documentation, dsh CLI README, DeepSeek API documentation