Grok

The Grok provider drives the Grok CLI on the relay's machine. There is no API key to enter in OAR: Grok uses the account the CLI is signed in to, and you can install the CLI and sign in from the browser.

Grok has no question cards, no steering and no plan mode that OAR can enforce. The table of all providers is on Providers at a glance.

What you need #

• The Grok CLI (grok) on the machine the relay runs on. OAR can install it for you (see The Grok CLI row).
• A Grok account, signed in on that machine. You can sign in from the browser (see Signing in) or by running grok login on the machine. The relay stores no Grok secret: the CLI keeps the login in ~/.grok/auth.json.

The Grok CLI row looks for grok on the relay's PATH, then in ~/.grok/bin, ~/.local/bin and /usr/local/bin. Sessions, sign-in and model discovery start grok from the PATH, or the binary named in GROK_CLI_COMMAND (see Environment variables).

The Grok CLI row #

At the top of Settings → Providers → Grok a Grok CLI row shows whether the CLI is installed. When it is, the row shows the version, where it is, how it was installed and whether it is up to date, for example 1.0.13 · ~/.grok/bin/grok · native · up to date, or update available (…) when a newer version exists. Its buttons depend on the state:

The output streams into the panel as Install log, also on other devices. Only one install runs at a time on the relay, and one that runs longer than 10 minutes is stopped. The commands are fixed in the relay and never run with sudo. After an install or update, new sessions use the new binary at once, and the relay remembers it across restarts; running sessions keep the one they started with. See also Installing or updating a provider's CLI.

Switching it on #

Grok is off by default. Open Settings → Providers → Grok. Under Grok:

A line under the controls says what state Grok is in. Switching Grok off moves conversations that have not sent a message yet back to Copilot. Conversations that have already started keep Grok. See Starting a conversation.

Further down the same panel is Grok monthly plan allowance (see Usage).

Signing in #

Under the CLI row, the account row names the account state. Signed in, it shows what the CLI's billing information gives, for example 70% of weekly quota used with a product name in front when there is exactly one. Signed out, it reads Not signed in. A token that has run out shows token expired, may need a new sign-in; the CLI normally renews it by itself. The row only recognizes a login made with the CLI.

Sign in #

1. Press Sign in. The relay runs grok login --device-auth on its machine.
2. The panel says Starting the Grok sign-in on the relay host…, then shows the x.ai sign-in link with a Copy link button, and next to it the code in the form XXXX-XXXX.
3. Open the link on any device, for example a phone, and confirm in the browser. Check that the code the browser shows is the one in the panel. The code is already part of the link, so you type nothing.
4. The panel changes by itself to Signed in to Grok. and, a moment later, the login area folds away. Nothing is pasted back into OAR: the CLI waits for x.ai and finishes on its own. A fresh model discovery runs, so you do not restart the relay.

Cancel abandons the login. An unfinished login ends after 10 minutes with Grok login timed out after 600s. Only one runs at a time on a relay, and every open browser sees it, so you can start it on one device and finish it on another. If it fails, the panel shows the error and a Dismiss button.

Sign out #

Sign out opens a confirmation that names the account and says how many Grok workers are running. Confirm with Sign out. New Grok turns then fail until you sign in again. The button is off while a sign-in is in progress or when no account is signed in.

Running Grok sessions keep the previous account until their worker process exits. New sessions use the new account.

On a failed reply #

When a turn fails because the CLI is missing or not signed in, the failed reply carries buttons that go to the fix:

Send the message again once the install or sign-in has finished.

Models #

Switching Grok on discovers the models the CLI offers and adds them to the pickers. The relay asks the CLI when you switch Grok on, when you change the model ID, after a sign-in and after an install from the panel. If the CLI reports none, only grok-4.5 and your model ID are offered. In Select Models the Grok tab chooses which of them show in the composer (then 💾 Save enabled models); the default model always stays enabled.

The model is fixed #

A Grok conversation keeps one model. The model you pick in New Chat is passed to the CLI when the session starts, and the CLI cannot switch models inside a session. Once the first message has been sent, the composer pins the picker, and the relay refuses a different model with Grok model switching requires creating a new Grok conversation. To use another model, start another conversation. See Starting a conversation.

Reasoning effort #

The reasoning effort picker offers none, low, medium and high, plus any other levels the CLI reports for the model. OAR sends the chosen level (except none) with each message as a hint. A CLI build that does not support it ignores it, so do not rely on it to change the answer.

What works and what does not #

• Streaming, thoughts and Stop. The reply and the agent's thoughts stream live. Stop cancels the turn.
• Permissions. OAR answers every permission request of the agent with allow once, in every mode. You are not asked.
• Question cards. There are none: the Grok protocol has no way to ask you. The agent can only ask in its reply text and wait for your next message. See ask_user.
• Relay modes. ask, autopilot and plan reach the agent as a [Relay mode: ...] line in front of your message, added when the mode changes. Nothing enforces them. See Relay modes.
• Plan board. In plan mode a Plan ready for review board appears when the final reply has at least two lines that look like plan steps. There is no plan tool to wait for.
• No steering. A message sent during a turn waits behind it, and the send button reads Queue. See Turns and the queue.
• OAR's agent tools. Grok gets preview and, when a relay is paired or agent sessions are on, relay_tool, from a small MCP server that OAR attaches to every Grok session. With OAR_MCP_SERVER=0 the server is not attached: there is no relay_tool, and the agent is told how to call the preview API instead. See Agent tools → By provider. A Grok conversation can also be watched by another agent.
• Attachments. Files reach the agent as a line [Attached file: <path>] after your text, not as content. The agent has to read the file itself.
• Sub-agents. A task or agent tool call of Grok shows as a sub-agent chip with its state. The nested text of a sub-agent is not recorded.
• Background tasks. Added in 0.9.12 The task panel lists every terminal the agent opens that runs longer than two seconds, as a Bash row with Stop and a console of its output. It leaves the panel when the agent is done with the terminal or the command exits. Background task timeout does not apply to Grok.
• Context. The 🧠 button shows the tokens of the last turn (input, cache, output). It adds a percentage of the window when the model's window size is known. There are no categories.
• Compaction. OAR sets and shows no automatic compaction and has no window setting for Grok. See Compacting a conversation.
• Silence and the turn ceiling. A turn that is quiet for too long fails: 120 s with nothing in flight, 300 s during a model request, 30 min while a tool runs. The silence is not counted while the agent waits on a relay_tool call, or on a command the relay runs for it that has printed something in the last 5 minutes. The turn is also capped by Max turn duration, counted from the start of the prompt, and a Grok turn that reaches it fails instead of returning to the queue. The windows, how to change them and the cap are on Turns and the queue.
• After a restart. The relay stores the Grok session id and loads that session when the worker starts again. If the CLI cannot load it, a note says so and the turn starts a fresh session without the earlier context. See Restarts and resuming.
• Usage. Grok replies have no usage line; see Usage.

Usage #

📊 Check Usage has a Grok card while Grok is switched on. It shows:

• Weekly plan usage, a live percentage bar with the reset date, read with the CLI's login. Without a CLI login the bar is missing and the card shows the estimates below.
• Latest turn: the cost (an estimate), the model, tokens in, out, cached and for reasoning, time spent in the API and number of agent turns, and a By model (last turn) breakdown.
• Current cycle (local): estimated spend, turns tracked and tokens since the last billing reset, summed from Grok turns on this relay.

The card links to the xAI console. Costs come from the agent's own report and are labeled as estimates.

Monthly allowance #

Grok does not report remaining credits to OAR, so OAR can compare its own estimate with a budget you give it. Under Grok monthly plan allowance:

Environment variables #

Set these in the environment the relay starts in.

The silence windows have their own variables, listed on Turns and the queue.

XAI_API_KEY is named in the sign-in error text and read by the CLI, but OAR does not pass it on to sessions, and the account row and weekly bar ignore it. Sign in with the CLI instead.

Limits #

• The model is fixed per conversation, and a different account applies to new sessions only.
• The sign-in uses the device-code flow only; the CLI's browser-callback and enterprise sign-ins are not offered.
• There is no uninstall button and no way to pin a CLI version.

Troubleshooting #

A failed reply ends with Error code: relay.<code>.; the codes below are the stable part.