ds4 Provider: Local DeepSeek V4 Flash via OpenAI-Compatible API

ds4 exposes DeepSeek V4 Flash from a local Metal backend using an API compatible with OpenAI's /v1. OpenClaw talks to ds4 via the generic openai-completions provider family.

This provider is not a dedicated OpenClaw plugin. Set it up under models.providers.ds4 and pick ds4/deepseek-v4-flash.

Requirements

• A Mac with Metal support.
• A functional ds4 checkout that includes ds4-server and the DeepSeek V4 Flash GGUF file.
• Sufficient memory for your chosen context; larger --ctx values consume more KV memory when the server starts.

Warning

Tool schemas and workspace context are part of OpenClaw agent turns. A small context like --ctx 4096 may work for direct curl tests but will fail during full agent runs with 500 prompt exceeds context. For agent and tool smoke tests, use at least --ctx 32768. Enable ds4 Think Max by using --ctx 393216 only when you have enough memory.

Quickstart

Start ds4-server

Swap <DS4_DIR> for the path to your ds4 checkout.

<DS4_DIR>/ds4-server \
  --model <DS4_DIR>/ds4flash.gguf \
  --host 127.0.0.1 \
  --port 18000 \
  --ctx 32768 \
  --tokens 128

Verify the OpenAI-compatible endpoint

curl http://127.0.0.1:18000/v1/models

You should see deepseek-v4-flash in the response.

Add the OpenClaw provider config

Add the configuration from Full config and then run a single-shot model verification:

openclaw infer model run \
  --local \
  --model ds4/deepseek-v4-flash \
  --thinking off \
  --prompt "Reply with exactly: openclaw-ds4-ok" \
  --json

Full config

Use this configuration when ds4 is already active on 127.0.0.1:18000.

{
  agents: {
    defaults: {
      model: { primary: "ds4/deepseek-v4-flash" },
      models: {
        "ds4/deepseek-v4-flash": {
          alias: "DS4 local",
        },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "deepseek-v4-flash",
            name: "DeepSeek V4 Flash (ds4)",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 32768,
            maxTokens: 128,
            compat: {
              supportsUsageInStreaming: true,
              supportsReasoningEffort: true,
              maxTokensField: "max_tokens",
              supportsStrictMode: false,
              thinkingFormat: "deepseek",
              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
            },
          },
        ],
      },
    },
  },
}

Make sure contextWindow matches ds4-server --ctx. Keep maxTokens in sync with --tokens unless you deliberately want OpenClaw to ask for fewer tokens than the server's default.

On-demand startup

OpenClaw can only launch ds4 when a ds4/... model is chosen. Include localService in the same provider entry:

{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "<DS4_DIR>/ds4-server",
          args: [
            "--model",
            "<DS4_DIR>/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "32768",
            "--tokens",
            "128",
          ],
          cwd: "<DS4_DIR>",
          healthUrl: "http://127.0.0.1:18000/v1/models",
          readyTimeoutMs: 300000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "deepseek-v4-flash",
            name: "DeepSeek V4 Flash (ds4)",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 32768,
            maxTokens: 128,
            compat: {
              supportsUsageInStreaming: true,
              supportsReasoningEffort: true,
              maxTokensField: "max_tokens",
              supportsStrictMode: false,
              thinkingFormat: "deepseek",
              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
            },
          },
        ],
      },
    },
  },
}

command must point to an absolute executable path. Shell lookup and ~ expansion are not performed. For details on every localService field, refer to Local model services.

Think Max

ds4 activates Think Max only when both conditions hold:

• ds4-server begins with --ctx 393216 or a higher value.
• The request uses reasoning_effort: "max" (or the corresponding ds4 effort field).

If you run that large context, adjust both the server flags and OpenClaw model metadata:

{
  contextWindow: 393216,
  maxTokens: 384000,
  compat: {
    supportsUsageInStreaming: true,
    supportsReasoningEffort: true,
    maxTokensField: "max_tokens",
    supportsStrictMode: false,
    thinkingFormat: "deepseek",
    supportedReasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
  },
}

Test

Direct HTTP check without OpenClaw:

curl http://127.0.0.1:18000/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Reply with exactly: ds4-ok"}],"max_tokens":16,"stream":false,"thinking":{"type":"disabled"}}'

OpenClaw model routing (identical to the Quickstart check):

openclaw infer model run \
  --local \
  --model ds4/deepseek-v4-flash \
  --thinking off \
  --prompt "Reply with exactly: openclaw-ds4-ok" \
  --json

Full agent and tool-call smoke test with a context of at least 32768:

openclaw agent \
  --local \
  --session-id ds4-tool-smoke \
  --model ds4/deepseek-v4-flash \
  --thinking off \
  --message "Use the shell command pwd once, then reply exactly: tool-ok <output>" \
  --json \
  --timeout 240

Expected result:

• executionTrace.winnerProvider corresponds to ds4
• executionTrace.winnerModel represents deepseek-v4-flash
• toolSummary.calls must be no lower than 1
• finalAssistantVisibleText begins with tool-ok

Troubleshooting

curl /v1/models cannot connect

Either ds4 is offline or it isn't listening on the address and port specified in baseUrl. Launch ds4-server, then try again:

curl http://127.0.0.1:18000/v1/models

500 prompt exceeds context

The value set for --ctx is insufficient for the OpenClaw turn. Increase ds4-server --ctx, and adjust models.providers.ds4.models[].contextWindow to reflect the change. Full agent turns involving tools demand significantly more context than a single message sent via curl.

Think Max does not activate

ds4 activates Think Max only when --ctx is set to at least 393216 and the request specifies reasoning_effort: "max". For smaller contexts, it falls back to high reasoning.

The first request is slow

ds4 undergoes a cold Metal residency and model warmup phase. Configure localService.readyTimeoutMs: 300000 when OpenClaw starts the server on demand.

Related

• Local model services, Spin up local model servers on demand before model requests arrive.

• Local models, Select and manage local model backends.

• Model providers, Set up provider references, authentication, and failover.

• DeepSeek, Native DeepSeek provider behavior and thinking controls.