#21599: fix(xai): extend Grok model prefix support + add native Responses API config

## Summary Addresses two related xAI/Grok issues that together prevent Grok models from working reliably in OpenClaw sub-agents and limit Grok to the OpenAI-compat API path. --- ### Fix 1 — Closes #15709: Grok sub-agents crash / show `configured,missing` **Root cause:** `XAI_PREFIXES` in `live-model-filter.ts` only contained `["grok-4"]`. Any model from the `grok-2` or `grok-3` families was not recognised as a valid xAI model, causing sub-agents spawned with `xai/grok-3`, `xai/grok-3-fast`, `xai/grok-3-mini` or `xai/grok-2` to crash or silently fall back with no diagnostic output. **Fix:** - Extend `XAI_PREFIXES` to `["grok-2", "grok-3", "grok-4"]` — covering all current Grok generations via prefix matching - Add `XAI_EXTRA_MODELS` array in `onboard-auth.models.ts` defining `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast`, `grok-2-1212` so they are registered in the provider config - Switch `applyXaiProviderConfig` to `applyProviderConfigWithDefaultModels` to include the full model set - After this fix, users with insufficient API key permissions get a **clean, diagnostic error** from xAI (e.g. `Forbidden: API key lacks permissions for grok-3-fast`) rather than a silent crash --- ### Fix 2 — Refs #6872: Native xAI Responses API support **Context:** xAI's Responses API (`/v1/responses`) unlocks server-side tools — `web_search`, `x_search`, `code_execution` — that run autonomously on xAI's infrastructure. Currently OpenClaw hardcodes `api: 'openai-completions'` for xAI, bypassing this entirely. **Fix:** Add `applyXaiResponsesApiConfig()` — a new exported function alongside `applyXaiConfig()` that configures the xAI provider with `api: 'openai-responses'`. Backward compatible; existing `applyXaiConfig()` unchanged. Adds JSDoc documenting both modes. --- ## Files Changed | File | Change | |------|--------| | `src/agents/live-model-filter.ts` | Extend `XAI_PREFIXES` from `["grok-4"]` → `["grok-2", "grok-3", "grok-4"]` | | `src/commands/onboard-auth.models.ts` | Add `XAI_EXTRA_MODELS` (grok-3/3-fast/3-mini/3-mini-fast/2-1212) | | `src/commands/onboard-auth.config-core.ts` | Use `applyProviderConfigWithDefaultModels`, add `applyXaiResponsesApiConfig()`, add JSDoc | | `src/agents/live-model-filter.test.ts` | **New:** 6 unit tests covering grok-2/3/4 prefix recognition | ## Testing - ✅ `pnpm run check` — 0 errors, 0 warnings - ✅ 6/6 unit tests pass (`live-model-filter.test.ts`) - ✅ Live API test: `xai/grok-4-1-fast` confirmed working via opencode - ✅ grok-3 now surfaces a clean API-level permissions error instead of a silent crash ## Related Issues - Fixes #15709 - Refs #6872 --- ## ☕ Support This fix was researched and shipped by [@RonySpark](https://x.com/ronyspark) — diagnosed after 3 days of the community (and myself) hitting silent Grok sub-agent crashes. If this unblocks your setup or saves you API costs: 👉 **[buymeacoffee.com/ronyspark](https://buymeacoffee.com/ronyspark)**