Skip to content

Commit a00e7d3

Browse files
davemorindavemorin
authored
docs: clarify xai oauth setup (#84350)
1 parent 1bb0eba commit a00e7d3

4 files changed

Lines changed: 128 additions & 38 deletions

File tree

‎docs/concepts/model-providers.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -314,7 +314,7 @@ See [/providers/kilocode](/providers/kilocode) for setup details.
314314
| Venice | `venice` | `VENICE_API_KEY` | - |
315315
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
316316
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
317-
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` |
317+
| xAI | `xai` | SuperGrok/X Premium OAuth or `XAI_API_KEY` | `xai/grok-4.3` |
318318
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
319319

320320
#### Quirks worth knowing
@@ -333,7 +333,7 @@ See [/providers/kilocode](/providers/kilocode) for setup details.
333333
Model ids use a `nvidia/<vendor>/<model>` namespace (for example `nvidia/nvidia/nemotron-...` alongside `nvidia/moonshotai/kimi-k2.5`); pickers preserve the literal `<provider>/<model-id>` composition while the canonical key sent to the API stays single-prefixed.
334334
</Accordion>
335335
<Accordion title="xAI">
336-
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/<model>"].params.tool_stream=false`.
336+
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/<model>"].params.tool_stream=false`.
337337
</Accordion>
338338
<Accordion title="Cerebras">
339339
Ships as the bundled `cerebras` provider plugin. GLM uses `zai-glm-4.7`; OpenAI-compatible base URL is `https://api.cerebras.ai/v1`.

‎docs/providers/xai.md‎

Lines changed: 82 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,30 +6,74 @@ read_when:
66
title: "xAI"
77
---
88

9-
OpenClaw ships a bundled `xai` provider plugin for Grok models.
9+
OpenClaw ships a bundled `xai` provider plugin for Grok models. For most
10+
users, the recommended path is Grok OAuth with an eligible SuperGrok or X Premium
11+
subscription. OpenClaw stays local-first: the Gateway, config, routing, and
12+
tools run on your machine, while Grok model requests authenticate through xAI
13+
and are sent to xAI's API.
1014

11-
## Getting started
15+
OAuth does not require an xAI API key, and it does not require the Grok Build
16+
app. xAI may still show Grok Build on the consent screen because OpenClaw uses
17+
xAI's shared OAuth client.
18+
19+
## Choose your setup path
20+
21+
Use the path that matches your OpenClaw install state:
1222

1323
<Steps>
14-
<Step title="Choose auth">
15-
Use either an API key from the [xAI console](https://console.x.ai/),
16-
xAI OAuth browser sign-in with an eligible xAI account, or xAI device-code
17-
sign-in for remote/VPS hosts where a localhost browser callback is awkward.
18-
OAuth does not require an xAI API key, and OpenClaw does not require the
19-
Grok Build app. xAI may still label the consent app as Grok Build because
24+
<Step title="New OpenClaw install">
25+
Run onboarding with daemon install when you are setting up a new local
26+
Gateway, then choose the xAI/Grok OAuth option in the model/auth step:
27+
28+
```bash
29+
openclaw onboard --install-daemon
30+
```
31+
32+
On a VPS or over SSH, use device-code during onboarding:
33+
34+
```bash
35+
openclaw onboard --install-daemon --auth-choice xai-device-code
36+
```
37+
38+
OAuth does not require an xAI API key. OpenClaw does not require the Grok
39+
Build app. xAI may still label the consent app as Grok Build because
2040
OpenClaw uses xAI's shared OAuth client.
41+
2142
</Step>
22-
<Step title="Sign in">
23-
Set `XAI_API_KEY`, run the API-key wizard, or start the OAuth flow:
43+
<Step title="Existing OpenClaw install">
44+
If OpenClaw is already configured, sign in to xAI only. Do not rerun full
45+
onboarding or reinstall the daemon just to connect Grok:
2446

2547
```bash
26-
openclaw onboard --auth-choice xai-api-key
27-
openclaw onboard --auth-choice xai-oauth
28-
openclaw onboard --auth-choice xai-device-code
2948
openclaw models auth login --provider xai --method oauth
49+
```
50+
51+
Use the device-code flow instead when the Gateway runs over SSH, Docker, or
52+
a VPS and a localhost browser callback is awkward:
53+
54+
```bash
3055
openclaw models auth login --provider xai --device-code
3156
```
3257

58+
To make Grok the default model after signing in, apply it separately:
59+
60+
```bash
61+
openclaw models set xai/grok-4.3
62+
```
63+
64+
Rerun full onboarding only if you intentionally want to change Gateway,
65+
daemon, channel, workspace, or other setup choices.
66+
67+
</Step>
68+
<Step title="API-key path">
69+
API-key setup still works for xAI Console keys and for media surfaces that
70+
require key-backed provider config:
71+
72+
```bash
73+
openclaw models auth login --provider xai --method api-key
74+
export XAI_API_KEY=xai-...
75+
```
76+
3377
</Step>
3478
<Step title="Pick a model">
3579
```json5
@@ -42,9 +86,9 @@ OpenClaw ships a bundled `xai` provider plugin for Grok models.
4286

4387
<Note>
4488
OpenClaw uses the xAI Responses API as the bundled xAI transport. The same
45-
credential from `openclaw onboard --auth-choice xai-api-key` or
46-
`openclaw onboard --auth-choice xai-oauth` /
47-
`openclaw onboard --auth-choice xai-device-code` can also power first-class
89+
credential from `openclaw models auth login --provider xai --method oauth`,
90+
`openclaw models auth login --provider xai --device-code`, or
91+
`openclaw models auth login --provider xai --method api-key` can also power first-class
4892
`x_search`, remote `code_execution`, and xAI image/video generation.
4993
Speech and transcription currently require `XAI_API_KEY` or provider config.
5094
`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.
5599
`code_execution` tuning lives under `plugins.entries.xai.config.codeExecution`.
56100
</Note>
57101

102+
## OAuth troubleshooting
103+
104+
- If browser OAuth cannot reach `127.0.0.1:56121`, use
105+
`openclaw models auth login --provider xai --device-code`.
106+
- If sign-in succeeds but Grok is not the default model, run
107+
`openclaw models set xai/grok-4.3`.
108+
- To inspect saved xAI auth profiles, run:
109+
110+
```bash
111+
openclaw models auth list --provider xai
112+
openclaw models status
113+
```
114+
115+
- xAI decides which accounts can receive OAuth API tokens. If an account is not
116+
eligible, try the API-key path or check the subscription on xAI's side.
117+
58118
<Tip>
59119
Use `xai-device-code` when signing in from SSH, Docker, or a VPS. OpenClaw
60120
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:
427487

428488
<Accordion title="Known limits">
429489
- xAI auth can use an API key, environment variable, plugin config fallback,
430-
or xAI OAuth browser sign-in with an eligible xAI account. OAuth uses a
431-
local callback on `127.0.0.1:56121`; for remote hosts, forward that port
432-
before opening the sign-in URL. xAI decides which accounts can receive
433-
OAuth API tokens, and the consent page may show Grok Build even though
434-
OpenClaw does not require the Grok Build app.
490+
browser OAuth, or device-code OAuth with an eligible xAI account. Browser
491+
OAuth uses a local callback on `127.0.0.1:56121`; for remote hosts, use
492+
`xai-device-code` unless you want to forward that port before opening the
493+
sign-in URL. xAI decides which accounts can receive OAuth API tokens, and
494+
the consent page may show Grok Build even though OpenClaw does not require
495+
the Grok Build app.
435496
- `grok-4.20-multi-agent-experimental-beta-0304` is not supported on the
436497
normal xAI provider path because it requires a different upstream API
437498
surface than the standard OpenClaw xAI transport.

‎docs/start/wizard-cli-reference.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,8 +153,18 @@ What you set:
153153
Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or `openai-codex/*`.
154154

155155
</Accordion>
156+
<Accordion title="xAI (Grok) OAuth">
157+
Browser sign-in for eligible SuperGrok or X Premium accounts. This is the
158+
recommended xAI path for most users. OpenClaw stores the resulting auth
159+
profile for Grok models, `x_search`, and `code_execution`.
160+
</Accordion>
161+
<Accordion title="xAI (Grok) device code">
162+
Remote-friendly browser sign-in with a short code instead of a localhost
163+
callback. Use this from SSH, Docker, or VPS hosts.
164+
</Accordion>
156165
<Accordion title="xAI (Grok) API key">
157-
Prompts for `XAI_API_KEY` and configures xAI as a model provider.
166+
Prompts for `XAI_API_KEY` and configures xAI as a model provider. Use this
167+
when you want an xAI Console API key instead of subscription OAuth.
158168
</Accordion>
159169
<Accordion title="OpenCode">
160170
Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog.

‎docs/tools/code-execution.md‎

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@ title: "Code execution"
99

1010
`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`.
1111

12-
| Property | Value |
13-
| ------------------ | --------------------------------------------------------------------------------- |
14-
| Tool name | `code_execution` |
15-
| Provider plugin | `xai` (bundled, `enabledByDefault: true`) |
16-
| Auth | xAI auth profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey` |
17-
| Default model | `grok-4-1-fast` |
18-
| Default timeout | 30 seconds |
19-
| Default `maxTurns` | unset (xAI applies its own internal limit) |
12+
| Property | Value |
13+
| ------------------ | --------------------------------------------------------------------------------------- |
14+
| Tool name | `code_execution` |
15+
| Provider plugin | `xai` (bundled, `enabledByDefault: true`) |
16+
| Auth | xAI OAuth auth profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey` |
17+
| Default model | `grok-4-1-fast` |
18+
| Default timeout | 30 seconds |
19+
| Default `maxTurns` | unset (xAI applies its own internal limit) |
2020

2121
This is different from local [`exec`](/tools/exec):
2222

@@ -36,12 +36,29 @@ Do **not** use it when you need local files, your shell, your repo, or paired de
3636
## Setup
3737

3838
<Steps>
39-
<Step title="Provide an xAI API key">
40-
Run `openclaw onboard --auth-choice xai-api-key` for `code_execution` and
41-
`x_search`, or set `XAI_API_KEY` / configure the key under the xAI plugin
42-
when you also want Grok web search to use the same credential:
39+
<Step title="Provide xAI credentials">
40+
Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription,
41+
use the remote-friendly device-code flow, or store an API key. OAuth works
42+
for `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search
43+
config can also power Grok `web_search`.
4344

4445
```bash
46+
openclaw models auth login --provider xai --method oauth
47+
openclaw models auth login --provider xai --device-code
48+
```
49+
50+
During a fresh install, the same auth choices are available inside
51+
onboarding:
52+
53+
```bash
54+
openclaw onboard --install-daemon
55+
openclaw onboard --install-daemon --auth-choice xai-device-code
56+
```
57+
58+
Or use an API key:
59+
60+
```bash
61+
openclaw models auth login --provider xai --method api-key
4562
export XAI_API_KEY=xai-...
4663
```
4764

@@ -66,7 +83,9 @@ Do **not** use it when you need local files, your shell, your repo, or paired de
6683
</Step>
6784

6885
<Step title="Enable and tune code_execution">
69-
The tool is gated on `plugins.entries.xai.config.codeExecution.enabled`. Default is off.
86+
`code_execution` is available when xAI credentials are available. Set
87+
`plugins.entries.xai.config.codeExecution.enabled` to `false` to disable it,
88+
or use the same block to tune the model and timeout.
7089

7190
```json5
7291
{
@@ -124,7 +143,7 @@ When the tool runs without auth, it returns a structured `missing_xai_api_key` e
124143
```json
125144
{
126145
"error": "missing_xai_api_key",
127-
"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.",
146+
"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`.",
128147
"docs": "https://docs.openclaw.ai/tools/code-execution"
129148
}
130149
```

0 commit comments

Comments
 (0)