From a00e7d3898cf812dccd0efdf4714d59e7cfcf2e0 Mon Sep 17 00:00:00 2001 From: Dave Morin Date: Tue, 19 May 2026 16:33:18 -0700 Subject: [PATCH] docs: clarify xai oauth setup (#84350) --- docs/concepts/model-providers.md | 4 +- docs/providers/xai.md | 107 ++++++++++++++++++++++------- docs/start/wizard-cli-reference.md | 12 +++- docs/tools/code-execution.md | 47 +++++++++---- 4 files changed, 130 insertions(+), 40 deletions(-) diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 12ab503a91cb..cf5e2f9e5ee5 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -314,7 +314,7 @@ See [/providers/kilocode](/providers/kilocode) for setup details. | Venice | `venice` | `VENICE_API_KEY` | - | | Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | | Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` | +| xAI | `xai` | SuperGrok/X Premium OAuth or `XAI_API_KEY` | `xai/grok-4.3` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | #### Quirks worth knowing @@ -333,7 +333,7 @@ See [/providers/kilocode](/providers/kilocode) for setup details. Model ids use a `nvidia//` namespace (for example `nvidia/nvidia/nemotron-...` alongside `nvidia/moonshotai/kimi-k2.5`); pickers preserve the literal `/` composition while the canonical key sent to the API stays single-prefixed. - Uses the xAI Responses path. `grok-4.3` is the bundled default chat model. `/fast` or `params.fastMode: true` rewrites `grok-3`, `grok-3-mini`, `grok-4`, and `grok-4-0709` to their `*-fast` variants. `tool_stream` defaults on; disable via `agents.defaults.models["xai/"].params.tool_stream=false`. + Uses the xAI Responses path. The recommended path is SuperGrok/X Premium OAuth; API keys still work via `XAI_API_KEY` or plugin config. `grok-4.3` is the bundled default chat model. `/fast` or `params.fastMode: true` rewrites `grok-3`, `grok-3-mini`, `grok-4`, and `grok-4-0709` to their `*-fast` variants. `tool_stream` defaults on; disable via `agents.defaults.models["xai/"].params.tool_stream=false`. Ships as the bundled `cerebras` provider plugin. GLM uses `zai-glm-4.7`; OpenAI-compatible base URL is `https://api.cerebras.ai/v1`. diff --git a/docs/providers/xai.md b/docs/providers/xai.md index 6a1a9952b6ec..590f5a4b880b 100644 --- a/docs/providers/xai.md +++ b/docs/providers/xai.md @@ -6,30 +6,74 @@ read_when: title: "xAI" --- -OpenClaw ships a bundled `xai` provider plugin for Grok models. +OpenClaw ships a bundled `xai` provider plugin for Grok models. For most +users, the recommended path is Grok OAuth with an eligible SuperGrok or X Premium +subscription. OpenClaw stays local-first: the Gateway, config, routing, and +tools run on your machine, while Grok model requests authenticate through xAI +and are sent to xAI's API. -## Getting started +OAuth does not require an xAI API key, and it does not require the Grok Build +app. xAI may still show Grok Build on the consent screen because OpenClaw uses +xAI's shared OAuth client. + +## Choose your setup path + +Use the path that matches your OpenClaw install state: - - Use either an API key from the [xAI console](https://console.x.ai/), - xAI OAuth browser sign-in with an eligible xAI account, or xAI device-code - sign-in for remote/VPS hosts where a localhost browser callback is awkward. - OAuth does not require an xAI API key, and OpenClaw does not require the - Grok Build app. xAI may still label the consent app as Grok Build because - OpenClaw uses xAI's shared OAuth client. - - - Set `XAI_API_KEY`, run the API-key wizard, or start the OAuth flow: + + Run onboarding with daemon install when you are setting up a new local + Gateway, then choose the xAI/Grok OAuth option in the model/auth step: + + ```bash + openclaw onboard --install-daemon + ``` + + On a VPS or over SSH, use device-code during onboarding: + + ```bash + openclaw onboard --install-daemon --auth-choice xai-device-code + ``` + + OAuth does not require an xAI API key. OpenClaw does not require the Grok + Build app. xAI may still label the consent app as Grok Build because + OpenClaw uses xAI's shared OAuth client. + + + + If OpenClaw is already configured, sign in to xAI only. Do not rerun full + onboarding or reinstall the daemon just to connect Grok: ```bash - openclaw onboard --auth-choice xai-api-key - openclaw onboard --auth-choice xai-oauth - openclaw onboard --auth-choice xai-device-code openclaw models auth login --provider xai --method oauth + ``` + + Use the device-code flow instead when the Gateway runs over SSH, Docker, or + a VPS and a localhost browser callback is awkward: + + ```bash openclaw models auth login --provider xai --device-code ``` + To make Grok the default model after signing in, apply it separately: + + ```bash + openclaw models set xai/grok-4.3 + ``` + + Rerun full onboarding only if you intentionally want to change Gateway, + daemon, channel, workspace, or other setup choices. + + + + API-key setup still works for xAI Console keys and for media surfaces that + require key-backed provider config: + + ```bash + openclaw models auth login --provider xai --method api-key + export XAI_API_KEY=xai-... + ``` + ```json5 @@ -42,9 +86,9 @@ OpenClaw ships a bundled `xai` provider plugin for Grok models. OpenClaw uses the xAI Responses API as the bundled xAI transport. The same -credential from `openclaw onboard --auth-choice xai-api-key` or -`openclaw onboard --auth-choice xai-oauth` / -`openclaw onboard --auth-choice xai-device-code` can also power first-class +credential from `openclaw models auth login --provider xai --method oauth`, +`openclaw models auth login --provider xai --device-code`, or +`openclaw models auth login --provider xai --method api-key` can also power first-class `x_search`, remote `code_execution`, and xAI image/video generation. Speech and transcription currently require `XAI_API_KEY` or provider config. `XAI_API_KEY` or plugin web-search config can power Grok-backed `web_search` too. @@ -55,6 +99,22 @@ and, by default, `x_search` through an operator xAI Responses proxy. `code_execution` tuning lives under `plugins.entries.xai.config.codeExecution`. +## OAuth troubleshooting + +- If browser OAuth cannot reach `127.0.0.1:56121`, use + `openclaw models auth login --provider xai --device-code`. +- If sign-in succeeds but Grok is not the default model, run + `openclaw models set xai/grok-4.3`. +- To inspect saved xAI auth profiles, run: + + ```bash + openclaw models auth list --provider xai + openclaw models status + ``` + +- xAI decides which accounts can receive OAuth API tokens. If an account is not + eligible, try the API-key path or check the subscription on xAI's side. + Use `xai-device-code` when signing in from SSH, Docker, or a VPS. OpenClaw prints an xAI URL and short code; finish sign-in in any local browser while the @@ -427,11 +487,12 @@ Legacy aliases still normalize to the canonical bundled ids: - xAI auth can use an API key, environment variable, plugin config fallback, - or xAI OAuth browser sign-in with an eligible xAI account. OAuth uses a - local callback on `127.0.0.1:56121`; for remote hosts, forward that port - before opening the sign-in URL. xAI decides which accounts can receive - OAuth API tokens, and the consent page may show Grok Build even though - OpenClaw does not require the Grok Build app. + browser OAuth, or device-code OAuth with an eligible xAI account. Browser + OAuth uses a local callback on `127.0.0.1:56121`; for remote hosts, use + `xai-device-code` unless you want to forward that port before opening the + sign-in URL. xAI decides which accounts can receive OAuth API tokens, and + the consent page may show Grok Build even though OpenClaw does not require + the Grok Build app. - `grok-4.20-multi-agent-experimental-beta-0304` is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard OpenClaw xAI transport. diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index 28c29e2eb105..74551a8cbc1c 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -153,8 +153,18 @@ What you set: Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or `openai-codex/*`. + + Browser sign-in for eligible SuperGrok or X Premium accounts. This is the + recommended xAI path for most users. OpenClaw stores the resulting auth + profile for Grok models, `x_search`, and `code_execution`. + + + Remote-friendly browser sign-in with a short code instead of a localhost + callback. Use this from SSH, Docker, or VPS hosts. + - Prompts for `XAI_API_KEY` and configures xAI as a model provider. + Prompts for `XAI_API_KEY` and configures xAI as a model provider. Use this + when you want an xAI Console API key instead of subscription OAuth. Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog. diff --git a/docs/tools/code-execution.md b/docs/tools/code-execution.md index a10d1ec2c3ff..c111d6e6a0bd 100644 --- a/docs/tools/code-execution.md +++ b/docs/tools/code-execution.md @@ -9,14 +9,14 @@ title: "Code execution" `code_execution` runs sandboxed remote Python analysis on xAI's Responses API. It is registered by the bundled `xai` plugin (under the `tools` contract) and dispatches to the same `https://api.x.ai/v1/responses` endpoint used by `x_search`. -| Property | Value | -| ------------------ | --------------------------------------------------------------------------------- | -| Tool name | `code_execution` | -| Provider plugin | `xai` (bundled, `enabledByDefault: true`) | -| Auth | xAI auth profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey` | -| Default model | `grok-4-1-fast` | -| Default timeout | 30 seconds | -| Default `maxTurns` | unset (xAI applies its own internal limit) | +| Property | Value | +| ------------------ | --------------------------------------------------------------------------------------- | +| Tool name | `code_execution` | +| Provider plugin | `xai` (bundled, `enabledByDefault: true`) | +| Auth | xAI OAuth auth profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey` | +| Default model | `grok-4-1-fast` | +| Default timeout | 30 seconds | +| Default `maxTurns` | unset (xAI applies its own internal limit) | This is different from local [`exec`](/tools/exec): @@ -36,12 +36,29 @@ Do **not** use it when you need local files, your shell, your repo, or paired de ## Setup - - Run `openclaw onboard --auth-choice xai-api-key` for `code_execution` and - `x_search`, or set `XAI_API_KEY` / configure the key under the xAI plugin - when you also want Grok web search to use the same credential: + + Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription, + use the remote-friendly device-code flow, or store an API key. OAuth works + for `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search + config can also power Grok `web_search`. ```bash + openclaw models auth login --provider xai --method oauth + openclaw models auth login --provider xai --device-code + ``` + + During a fresh install, the same auth choices are available inside + onboarding: + + ```bash + openclaw onboard --install-daemon + openclaw onboard --install-daemon --auth-choice xai-device-code + ``` + + Or use an API key: + + ```bash + openclaw models auth login --provider xai --method api-key export XAI_API_KEY=xai-... ``` @@ -66,7 +83,9 @@ Do **not** use it when you need local files, your shell, your repo, or paired de - The tool is gated on `plugins.entries.xai.config.codeExecution.enabled`. Default is off. + `code_execution` is available when xAI credentials are available. Set + `plugins.entries.xai.config.codeExecution.enabled` to `false` to disable it, + or use the same block to tune the model and timeout. ```json5 { @@ -124,7 +143,7 @@ When the tool runs without auth, it returns a structured `missing_xai_api_key` e ```json { "error": "missing_xai_api_key", - "message": "code_execution needs an xAI API key. Run openclaw onboard --auth-choice xai-api-key, set XAI_API_KEY in the Gateway environment, or configure plugins.entries.xai.config.webSearch.apiKey.", + "message": "code_execution needs xAI credentials. Run `openclaw models auth login --provider xai --method oauth` to sign in with Grok, run `openclaw models auth login --provider xai --method api-key`, set `XAI_API_KEY` in the Gateway environment, or configure `plugins.entries.xai.config.webSearch.apiKey`.", "docs": "https://docs.openclaw.ai/tools/code-execution" } ```