> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ds4
[ds4](https://github.com/antirez/ds4) serves DeepSeek V4 Flash from a local
Metal backend with an OpenAI-compatible `/v1` API. OpenClaw connects to ds4
through the generic `openai-completions` provider family.
ds4 is not a bundled OpenClaw provider plugin. Configure it under
`models.providers.ds4`, then select `ds4/deepseek-v4-flash`.
| Property | Value |
| ----------- | --------------------------------------------------------- |
| Provider id | `ds4` |
| Plugin | none (config-only) |
| API | OpenAI-compatible Chat Completions (`openai-completions`) |
| Base URL | `http://127.0.0.1:18000/v1` (suggested) |
| Model id | `deepseek-v4-flash` |
| Tool calls | OpenAI-style `tools` / `tool_calls` |
| Reasoning | DeepSeek-style `thinking` and `reasoning_effort` |
## Requirements
* macOS with Metal support.
* A working ds4 checkout with `ds4-server` and the DeepSeek V4 Flash GGUF file.
* Enough memory for the context you choose; larger `--ctx` values allocate more
KV memory at server startup.
OpenClaw agent turns include tool schemas and workspace context. A tiny context
such as `--ctx 4096` can pass direct curl tests but fail full agent runs with
`500 prompt exceeds context`. Use at least `--ctx 32768` for agent and tool
smoke tests. Use `--ctx 393216` only with enough memory and to enable ds4
Think Max.
## Quickstart
Replace `` with your ds4 checkout path.
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
/ds4-server \
--model /ds4flash.gguf \
--host 127.0.0.1 \
--port 18000 \
--ctx 32768 \
--tokens 128
```
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl http://127.0.0.1:18000/v1/models
```
The response should include `deepseek-v4-flash`.
Add the config from [Full config](#full-config), then run a one-shot model
check:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw infer model run \
--local \
--model ds4/deepseek-v4-flash \
--thinking off \
--prompt "Reply with exactly: openclaw-ds4-ok" \
--json
```
## Full config
Use this config when ds4 is already running on `127.0.0.1:18000`.
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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"],
},
},
],
},
},
},
}
```
Keep `contextWindow` aligned with `ds4-server --ctx`. Keep `maxTokens` aligned
with `--tokens` unless you intentionally want OpenClaw to request less output
than the server default.
## On-demand startup
OpenClaw can start ds4 only when a `ds4/...` model is selected. Add
`localService` to the same provider entry:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
models: {
providers: {
ds4: {
baseUrl: "http://127.0.0.1:18000/v1",
apiKey: "ds4-local",
api: "openai-completions",
timeoutSeconds: 300,
localService: {
command: "/ds4-server",
args: [
"--model",
"/ds4flash.gguf",
"--host",
"127.0.0.1",
"--port",
"18000",
"--ctx",
"32768",
"--tokens",
"128",
],
cwd: "",
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 be an absolute executable path. Shell lookup and `~` expansion
are not used. See [Local model services](/gateway/local-model-services) for
every `localService` field.
## Think Max
ds4 applies Think Max only when both are true:
* `ds4-server` starts with `--ctx 393216` or higher.
* The request uses `reasoning_effort: "max"` (or the equivalent ds4 effort field).
If you run that large context, update both the server flags and OpenClaw model
metadata:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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, bypassing OpenClaw:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 (same as the Quickstart check):
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 context of at least 32768:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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