Summary

• add configurable retries for isolated cron local-model provider preflight
• expose cron.modelPreflight.timeoutMs, maxAttempts, and retryDelayMs
• document the settings for sleeping/cold-starting Ollama, vLLM, SGLang, LM Studio, and other local providers
• keep defaults unchanged: one 2500ms probe and no retry delay
• enforce one shared 55s preflight deadline across the full fallback candidate chain

Why

Isolated cron jobs run a lightweight preflight before starting an agent turn for local/private model providers. Current upstream can advance from an unreachable local primary to configured fallback model candidates, but each local candidate still gets only one default 2.5s preflight probe.

That still leaves the cold-start/sleeping-provider case: a local endpoint can become healthy moments after the single probe fails. This PR keeps the fallback behavior intact while letting operators configure a short wake-up window before cron advances to a fallback or marks the run skipped.

The configured per-endpoint retry window is validated at or below 55s, and the runtime now shares one 55s deadline across the complete preflight candidate chain so multi-local fallback paths stay below cron's isolated-agent setup watchdog.

Review fix

After ClawSweeper noted that the original 55s cap applied per endpoint, this branch now:

• computes one preflight deadline before walking candidates
• passes that same deadline to every candidate preflight
• clamps each local probe timeout and retry delay to the remaining shared budget
• skips additional local endpoint probes once the shared budget is exhausted
• still allows remote/cloud fallback candidates to be selected immediately

Supplemental verification

• corepack pnpm install --frozen-lockfile
• node scripts/run-vitest.mjs src/cron/isolated-agent/model-preflight.runtime.test.ts src/cron/isolated-agent.model-preflight.test.ts src/cron/isolated-agent/run-fallback-policy.test.ts src/config/config-misc.test.ts - 113 tests passed across focused config and cron shards
• node scripts/run-vitest.mjs src/commands/agent-via-gateway.test.ts - 55 tests passed, covering the previously failing unrelated CI shard locally
• pnpm lint --threads=8 - passed
• pnpm exec oxfmt --check docs/cli/cron.md docs/gateway/configuration-reference.md docs/providers/ollama.md src/config/config-misc.test.ts src/config/schema.help.ts src/config/schema.labels.ts src/config/types.cron.ts src/config/zod-schema.ts src/cron/isolated-agent/model-preflight.runtime.test.ts src/cron/isolated-agent/model-preflight.runtime.ts src/cron/isolated-agent.model-preflight.test.ts src/cron/isolated-agent/run.ts - passed
• git diff --check - passed
• pnpm tsgo:core - passed

pnpm check currently passes all guards except the local npm-shrinkwrap.json is stale guard. The ready-for-review CI run on this branch previously passed the shrinkwrap check, so I did not include unrelated generated dependency metadata in this cron patch.

Real behavior proof

Behavior addressed: A sleeping or cold-starting local model provider can miss cron's default single 2.5s preflight probe even though it becomes reachable moments later. Configured retries should let that same local candidate wake before cron advances to a fallback or skips the run.

Real environment tested: macOS local OpenClaw source checkout rebased onto upstream main, Node v22.22.0, pnpm v11.2.2. A real loopback OpenAI-compatible HTTP endpoint was started after an 800ms delay. The actual preflightCronModelProvider runtime used its real network fetch and SSRF-guard path against http://127.0.0.1:<port>/v1/models.

Exact steps or command run after this patch: Ran a pnpm exec tsx -e live harness that started the local HTTP endpoint after 800ms and invoked preflightCronModelProvider twice: first with default settings, then with { timeoutMs: 500, maxAttempts: 2, retryDelayMs: 1000 }.

Evidence after fix: Copied live console output from the real delayed endpoint run:

{"label":"default-single-attempt","result":{"status":"unavailable","provider":"delayed","model":"delayed-local-model","baseUrl":"http://127.0.0.1:54323/v1","retryAfterMs":300000,"reason":"Agent cron job uses delayed/delayed-local-model but the local provider endpoint is not reachable at http://127.0.0.1:54323/v1. Skipping this cron run after 1 preflight attempt; OpenClaw will retry the provider preflight on a later scheduled run. Last error: TypeError: fetch failed"},"elapsedMs":159,"serverHits":0}
{"label":"configured-retry-window","result":{"status":"available"},"elapsedMs":1019,"serverHits":1}

Observed result after fix: With defaults, the endpoint was reported unavailable before it woke, confirming the cold-start issue still exists. With the configured retry window, the first connection failed while the endpoint was offline, cron waited, the endpoint started, and the next probe succeeded with status: "available" and one observed /models request.

What was not tested: A separate real Ollama daemon was not stopped and restarted during this run. The proof used a real delayed local OpenAI-compatible endpoint to exercise the same production preflight runtime and network path deterministically.