Configure model providers and API keys in DeepSeek Harness

DeepSeek Harness configures model providers under Settings → Models, with built-in provider ids such as anthropic, openai, moonshotai and zai; API keys go to $DSH_HOME/.credentials.yaml, while the providers block lives in cordis.patch.yml. This walks through where to configure, where things are stored, and how to fix the common errors.

Where to configure DeepSeek Harness model providers: built-in ids and Settings → Models

DeepSeek Harness configures model providers under Settings → Models, where built-in ids include anthropic, openai, moonshotai and zai; pick one, then add a key and a model name (source). Work through these steps:

1. Open the settings panel — go to Settings → Models to see the built-in provider list. Expected: common ids such as anthropic, openai, moonshotai and zai are selectable without adding anything from scratch.
2. Pick a provider id — with a built-in id you only add a model name; only self-hosted or third-party compatible services need a baseURL and an api protocol. Expected: api is one of openai-completions, openai-responses or anthropic-messages.
3. Fill in the model name — enter the model to use under that provider. Expected: the name must match what the provider actually exposes, otherwise the request fails with UNKNOWN_MODEL.
4. Save and verify — send one request after saving. Expected: a normal response means the provider works; changes apply on the next request without a restart.

Where DeepSeek Harness stores keys: .credentials.yaml and the providers block

DeepSeek Harness stores API keys in $DSH_HOME/.credentials.yaml (written when you save once in the UI), while structured provider settings go into the providers block of $DSH_HOME/profiles/<profile>/cordis.patch.yml (source). When you need to write structured settings by hand, use these fields:

1. providers — a block keyed by provider id that declares the connection and model information.
2. apiKeyEnv — names the environment variable to read the key from, useful when you do not want plaintext in the file.
3. baseURL and api — the address and protocol of a custom service; the protocol decides the request body format.
4. models / modelOverrides — models lists the models a provider supports, while modelOverrides overrides the parameters of just one model.
5. input / defaultInput — declare input modalities, which is where image capability settings live.
6. reasoning / reasoningEfforts — control reasoning tiers; an unsupported tier raises UNSUPPORTED_REASONING_EFFORT.
7. compat — compatibility switches including thinkingFormat, supportsDeveloperRole and maxTokensField, used to adapt to differing API flavors.

# $DSH_HOME/profiles/<profile>/cordis.patch.yml (structure sketch)
providers:
  openai:
    apiKeyEnv: OPENAI_API_KEY
    baseURL: https://api.openai.com/v1
    api: openai-completions
    models:
      - gpt-4o

Keys live in the credential file and structured switches in the patch file — keeping the two apart is the default design of DeepSeek Harness. When you want DSH plugins for memory or retrieval, browse DSH Plugin Hub, install, then return to the settings page for model setup.

Fixing MISSING_CREDENTIAL, UNKNOWN_MODEL and reasoning errors

MISSING_CREDENTIAL means no usable credential was found, UNKNOWN_MODEL means the model name is not in the models list, and UNSUPPORTED_REASONING_EFFORT means the reasoning tier is not supported — each has a fixed fix (source). Handle them by error code:

1. Read the error code first — the message states the code directly. Expected: you know whether it is a credential or a model issue before reinstalling anything.
2. MISSING_CREDENTIAL — re-save the key under Settings → Models; when using apiKeyEnv, confirm that variable exists in the environment starting DeepSeek Harness. Expected: the next request succeeds after saving.
3. UNKNOWN_MODEL — verify the model name spelling and case, or add the model to the models array of the providers block. Expected: the error clears once the name matches.
4. UNSUPPORTED_REASONING_EFFORT — drop to a reasoningEfforts tier the model supports. Expected: requests succeed with a supported tier.
5. Change not taking effect — confirm the edit is in the profile actually in use. Expected: switching profiles once rules out a wrong-layer write.

DeepSeek Harness model provider limits and cautions

1. .credentials.yaml is plaintext and sensitive: it holds API keys and the browser session signing key, so never commit it or share screenshots.
2. settings.yaml stores references, not secrets: the key itself lives in .credentials.yaml, so do not hardcode plaintext keys elsewhere.
3. The api protocol must match the service: pointing openai-completions at an anthropic-style endpoint fails, so confirm the interface format first.
4. Reasoning tiers are model-specific: an unsupported reasoningEfforts value errors out, so check the model docs first.
5. Configuration is layered: the providers block applies to whichever profile holds it; the full merge order is in how DeepSeek Harness merges plugin config.

Once models work, a machine or network change often needs proxy and certificate settings too, covered in setting up a network proxy for DeepSeek Harness.

Sources: Configuring models (official docs), dsh CLI README (official repository)