openclaw - 💡(How to fix) Fix [Bug]: models.providers.<id>.timeoutSeconds documented in schema as standalone-valid, rejected by startup validator on built-in providers

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

The schema (openclaw config schema) declares models.providers.<id>.timeoutSeconds as a standalone integer key with a description that explicitly recommends using it instead of changing global agent timeouts. The startup validator, however, refuses to load any config containing a models.providers.<id> block unless baseUrl (string) and models (array) are also present — which only makes sense for custom provider declarations, not for tuning a built-in provider's request timeout.

This makes the schema-documented escape from the 120s clampImplicitTimeoutMs ceiling unreachable for built-in providers (OpenAI, Anthropic, Google) without also doing a full custom-provider registration that defeats the schema description's stated use case ("instead of changing global agent timeouts") and risks shadowing eventual upstream fixes for related bugs.

Steps to reproduce

Patch ~/.openclaw/openclaw.json to add the documented per-provider timeout: { "models": { "providers": { "openai": { "timeoutSeconds": 600 } } } } Run:

openclaw gateway restart

Observed: Gateway aborted: config is invalid. models.providers.openai.baseUrl: Invalid input: expected string, received undefined models.providers.openai.models: Invalid input: expected array, received undefined Fix the config and retry, or run "openclaw doctor" to repair.

Expected behavior

(Source paths from ~/.npm-global/lib/node_modules/openclaw/dist/, build 2eae30e.)

The timeoutSeconds value would, if accepted, flow through:

model-CYlos1Q6.js:272 — resolveProviderRequestTimeoutMs(timeoutSeconds) converts seconds → ms, lands on model.requestTimeoutMs.
selection-DL4MPaGt.js:7456 — passed as modelRequestTimeoutMs into resolveLlmIdleTimeoutMs.
selection-DL4MPaGt.js:6086 — uses clampTimeoutMs (no DEFAULT_LLM_IDLE_TIMEOUT_MS cap).

So the code would honor the key for built-in providers. The validator is the only thing preventing it.

Actual behavior

Gateway aborted: config is invalid. models.providers.openai.baseUrl: Invalid input: expected string, received undefined models.providers.openai.models: Invalid input: expected array, received undefined Fix the config and retry, or run "openclaw doctor" to repair.

OpenClaw version

2026.5.3-1 (2eae30e)

Operating system

Ubuntu 24.04 (HWE kernel 6.17.0-29-generic)

Install method

npm -g

Model

openai/gpt-5.4 and openai/gpt-5.5

Provider / routing chain

Built-in OpenAI provider via OpenClaw 2026.5.3-1 → OpenAI Responses API (api.openai.com/v1). No reverse proxy, no router, no custom provider registered. Standard systemd-gateway install (npm -g), API key in ~/.openclaw/gateway.systemd.env. The bug is in OpenClaw's config validator at gateway-startup time — it fails before any provider request actually goes out.

Additional provider/model setup details

No response

Logs, screenshots, and evidence

openclaw config schema returns this for models.providers.<id>.timeoutSeconds (read via additionalProperties.properties):

{
  "type": "integer",
  "exclusiveMinimum": 0,
  "maximum": 9007199254740991,
  "title": "Model Provider Request Timeout",
  "description": "Optional per-provider model request timeout in seconds. Applies to provider HTTP fetches, including connect, headers, body, and total request abort handling. Use this for slow local or self-hosted model servers instead of changing global agent timeouts."
}

No required: ["baseUrl", "models"] declared at the models.providers.<id> level (only additionalProperties with the keys: baseUrl, apiKey, auth, api, contextWindow, contextTokens, maxTokens, timeoutSeconds, injectNumCtxForOpenAICompat, params, headers, authHeader, request, models).

The description directly recommends this key for the exact use case the validator blocks.

Impact and severity

There's a known stack of related issues affecting GPT-5.x cron/sub-agent reliability:

#63369 (open) — reasoning_effort not forwarded to OpenAI Responses API for GPT-5.x models in isolated/cron sessions
#59946 — sub-agent extended-thinking streaming connection silently severed by provider idle timeout
#65576 — cron runs without explicit idleTimeoutSeconds disable the watchdog, hung provider consumes full cron timeout

The documented models.providers.<id>.timeoutSeconds escape would let operators work around the 120s clampImplicitTimeoutMs ceiling in DEFAULT_LLM_IDLE_TIMEOUT_MS while waiting for those upstream fixes to ship. This validator mismatch makes that escape unusable for built-in providers, which is most users' situation.

Additional information

Two-option fix

Either fix is small and self-contained:

(A) Make the validator accept standalone timeoutSeconds for built-in providers. Preserves the schema description as accurate. baseUrl + models[] remain required only when no built-in provider exists with that name. This matches the user-mental-model of "I'm overriding one knob on a built-in provider."
(B) Make the schema description honest about requiring baseUrl + models[]. Update the description to say something like "Only valid when registering a custom provider with baseUrl and models[]. Built-in providers use the global agents.defaults.timeoutSeconds instead." Tells operators where to actually look.

(A) preserves more capability and is the better fix if there's a way to do it cleanly. (B) is faster to ship and at least removes the contradiction.