Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

docs/providers/ds4.md

@@ -0,0 +1,311 @@
+---
+summary: "Run OpenClaw through ds4, a local DeepSeek V4 Flash OpenAI-compatible server"
+read_when:
+  - You want to run OpenClaw against antirez/ds4
+  - You want a local DeepSeek V4 Flash backend with tool calls
+  - You need the OpenClaw config for ds4-server
+title: "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.
+
+<Warning>
+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.
+</Warning>
+
+## Quickstart
+
+<Steps>
+  <Step title="Start ds4-server">
+    Replace `<DS4_DIR>` with your ds4 checkout path.
+
+    ```bash
+    <DS4_DIR>/ds4-server \
+      --model <DS4_DIR>/ds4flash.gguf \
+      --host 127.0.0.1 \
+      --port 18000 \
+      --ctx 32768 \
+      --tokens 128
+    ```
+
+  </Step>
+  <Step title="Verify the OpenAI-compatible endpoint">
+    ```bash
+    curl http://127.0.0.1:18000/v1/models
+    ```
+
+    The response should include `deepseek-v4-flash`.
+
+  </Step>
+  <Step title="Add the OpenClaw provider config">
+    Add the config from [Full config](#full-config), then run a one-shot model
+    check:
+
+    ```bash
+    openclaw infer model run \
+      --local \
+      --model ds4/deepseek-v4-flash \
+      --thinking off \
+      --prompt "Reply with exactly: openclaw-ds4-ok" \
+      --json
+    ```
+
+  </Step>
+</Steps>
+
+## Full config
+
+Use this config when ds4 is already running on `127.0.0.1:18000`.
+
+```json5
+{
+  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
+{
+  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 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
+{
+  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
+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
+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
+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` is `ds4`
+- `executionTrace.winnerModel` is `deepseek-v4-flash`
+- `toolSummary.calls` is at least `1`
+- `finalAssistantVisibleText` starts with `tool-ok`
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="curl /v1/models cannot connect">
+    ds4 is not running or not bound to the host/port in `baseUrl`. Start
+    `ds4-server`, then retry:
+
+    ```bash
+    curl http://127.0.0.1:18000/v1/models
+    ```
+
+  </Accordion>
+
+  <Accordion title="500 prompt exceeds context">
+    The configured `--ctx` is too small for the OpenClaw turn. Raise
+    `ds4-server --ctx`, then update `models.providers.ds4.models[].contextWindow`
+    to match. Full agent turns with tools need substantially more context than a
+    direct one-message curl request.
+  </Accordion>
+
+  <Accordion title="Think Max does not activate">
+    ds4 only uses Think Max when `--ctx` is at least `393216` and the request
+    asks for `reasoning_effort: "max"`. Smaller contexts fall back to high
+    reasoning.
+  </Accordion>
+
+  <Accordion title="The first request is slow">
+    ds4 has a cold Metal residency and model warmup phase. Set
+    `localService.readyTimeoutMs: 300000` when OpenClaw starts the server on
+    demand.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Local model services" href="/gateway/local-model-services" icon="play">
+    Start local model servers on demand before model requests.
+  </Card>
+  <Card title="Local models" href="/gateway/local-models" icon="server">
+    Choose and operate local model backends.
+  </Card>
+  <Card title="Model providers" href="/concepts/model-providers" icon="layers">
+    Configure provider refs, auth, and failover.
+  </Card>
+  <Card title="DeepSeek" href="/providers/deepseek" icon="brain">
+    Native DeepSeek provider behavior and thinking controls.
+  </Card>
+</CardGroup>