Grok on Hermes Agent: SuperGrok OAuth Setup, API Key & Bug Fixes (2026)

Does Hermes Agent support Grok?

Yes. Hermes Agent supports xAI Grok from v0.14.0 onward (released May 16, 2026). You can connect it two ways: SuperGrok OAuth, which reuses your existing SuperGrok or X Premium+ subscription with no per-token bill, or an xAI API key for per-token billing and headless servers. The default model is grok-4.3 with a 1M-token context window. Both paths are covered below, along with fixes for the errors that break most setups.

How do I set up Grok on Hermes Agent?

Update to Hermes v0.14 or later. Run hermes model and select "xAI Grok OAuth (SuperGrok / X Premium+)." Sign in through your browser — no xAI API key required. Your existing SuperGrok or X Premium+ subscription powers grok-4.3 with its 1M-token context window. The full setup takes under 5 minutes if you don't hit the known bugs.

That's the happy path. Below is the exact command sequence, the OAuth-vs-API-key decision, and fixes for the three errors that break most setups: "user not found," HTTP 400, and silently dropped messages. (New to the framework? Our overview of what Hermes Agent is covers how the gateway, memory, and model providers fit together.)

Prerequisites

• Hermes Agent v0.14.0 or later (xAI OAuth doesn't exist before this — it landed May 16, 2026)
• An active SuperGrok subscription (grok.com) OR X Premium+ subscription (linked X account)
• No xAI API key required for the OAuth path
• If you use the API-key path instead: create a key at console.x.ai

Check your version with hermes --version. If you're on v0.13 or older, run hermes update first.

SuperGrok OAuth vs xAI API Key: Which Path to Use

Two completely separate ways to pay for Grok, mapping to two setup paths. Pick before you start — subscribing to SuperGrok does not grant you xAI API credit; they're billed separately.

SuperGrok OAuth path

• No per-token cost — included in your SuperGrok or X Premium+ subscription
• Browser-based OAuth flow; tokens save to ~/.hermes/auth.json and refresh automatically
• Known issues: the Responses streaming bug (#27197) and silent message drops on rate limits (#7100)
• Best for: personal agents, testing, low-to-medium volume

xAI API key path

• Pay per token from a pre-paid balance at console.x.ai (check xAI's pricing page — grok-4.3 plus a cheaper Fast variant)
• More stable — no Responses streaming bug when you pin Chat Completions
• Works in headless environments with no browser
• Best for: production agents, server deployments, high volume

Grok OAuth Setup on Hermes (Step by Step)

This is the copy-paste path. Assumes Hermes is installed and you have a SuperGrok or X Premium+ subscription.

Step 1 — Update Hermes to v0.14+

hermes update
hermes --version   # should show 0.14.0 or later

Step 2 — Run the model setup

hermes model

Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list. Hermes opens your default browser to xAI's auth page.

If you'd rather skip the picker and go straight to auth:

hermes auth xai

Step 3 — Complete browser OAuth

Sign in with the Grok/X account that holds your subscription and approve access. Credentials save to ~/.hermes/auth.json and refresh automatically.

Step 4 — Verify the connection

hermes

Send a test message. A response from grok-4.3 means setup is complete.

Step 5 — Pick your model (optional)

Available models on the xAI Grok OAuth provider: grok-4.3 (default, 1M-token context), grok-4.3-fast (cheaper, same large context), and the earlier grok-4 line where your subscription still exposes it. Run hermes model to see the exact list your account can access — it varies by subscription tier.

grok-4.3 is the default and the right pick for most agent work, thanks to its 1M-token context window. On the API-key path, a Grok Fast variant is the cheapest large-context option. Verify the current lineup on xAI's pricing page before committing — it changes often.

For a permanent config, edit ~/.hermes/config.yaml:

model:
  provider: xai-oauth
  default: grok-4.3

xAI API Key Setup on Hermes (Alternative)

Use this when you want per-token billing, dashboards, or a headless server with no browser. The same key works if you later deploy an AI agent on a hosted platform, so nothing you set up here is wasted.

Step 1 — Create an API key at console.x.ai.

Step 2 — Add it to ~/.hermes/.env:

XAI_API_KEY=xai-your-key-here

Step 3 — Point your config at the API provider and pin Chat Completions (see the HTTP 400 fix below for why):

model:
  provider: xai
  default: grok-4.3
  api_mode: chat_completions

Step 4 — Test with hermes. Note: if you have both an XAI_API_KEY in .env and an OAuth token in auth.json, the .env key wins — keep only the one you intend to use.

3 Known Bugs and How to Fix Each One

This is the section most people actually land here for. Each fix leads with the exact symptom.

Fix: "User Not Found in Auth Context"

What you see: After completing OAuth, Hermes returns User not found (often HTTP 401) when you try to chat, even though the subscription is active and Grok works in a browser.

Cause: Two common triggers. (1) A stale auth.json — when xAI's servers are briefly overloaded, Hermes can misread the error as a rate limit and rotate your credentials, corrupting the token. (2) An account mismatch — the OAuth token was created with a different X/Grok account than the one holding your active SuperGrok subscription (common if you have multiple accounts or bought SuperGrok on a different email).

Fix:

1. Confirm which account has the active subscription at grok.com/settings
2. Sign out of all X/Grok sessions in your browser
3. Clear the stale token: rm ~/.hermes/auth.json
4. Re-run hermes auth xai and sign in with the exact account that holds the subscription
5. Verify with hermes

This resolves it about 80% of the time. If it persists, check ~/.hermes/.env for a leftover XAI_API_KEY line — it overrides the OAuth token. Remove it and restart the gateway. Still failing? Some older SuperGrok plans don't include every capability; confirm your account's access at console.x.ai. For other credential rejections, our Hermes auth error fixes walk through the six most common authentication breaks.

Fix: "Existing Account Found" During Grok Sign-In

What you see: During the OAuth flow, xAI's page shows existing account found (or "an account with this email already exists") and either stalls or loops you back to sign-in instead of completing authorization.

Cause: You have more than one Grok/X identity tied to the same email — typically a standalone grok.com account and a Grok login linked through your X (Premium+) account. xAI can't decide which to authorize, so the callback never returns a token to Hermes.

Fix:

1. Pick the single identity that actually holds your active SuperGrok or X Premium+ subscription (check at grok.com/settings)
2. In your browser, sign out of every other X/Grok session so only that identity is live
3. Re-run hermes auth xai and complete sign-in with that one account
4. If the page still loops, open grok.com in a private/incognito window, sign in there first, then trigger hermes auth xai from the same browser profile

This is the same root problem as the account-mismatch case above — one clean, authorized identity is what OAuth needs.

Fix: HTTP 400 Error with Grok on Hermes

What you see: The agent connects but returns HTTP 400 on message send — either immediately or after a few messages ("Invalid arguments passed to the model," or a Responses stream that never emits a terminal response).

Cause 1 (most common): The Responses API streaming incompatibility (#27197). The xAI OAuth provider defaults to api_mode: codex_responses, and xAI's Responses streaming doesn't fully match the OpenAI SDK's state machine.

Fix — fall back to the more stable Chat Completions path:

model:
  provider: xai-oauth
  default: grok-4.3
  api_mode: chat_completions

Cause 2: Switching an existing long-running session to Grok mid-stream (#32617) replays encrypted reasoning items xAI can't decrypt.

Fix — start a fresh session (run /new to clear the conversation buffer), then resend.

Cause 3: Multiple credentials sent at once. If you previously used another provider, remove old keys from ~/.hermes/.env and config.yaml so only one credential is active.

For every other trigger of a 400, our Hermes Agent error 400 guide ranks each cause by frequency.

Fix: Grok Messages Silently Dropping

What you see: The agent appears to send a message to Grok, but no response comes back and no error appears in the logs. It just stops.

Cause: A rate limit hit without proper surfacing (#7100). Hermes retries HTTP 429 with backoff, but when all retries fail it marks the response failed_early and skips writing your message to the transcript — so the next turn loads a history missing what you just said.

Fix:

1. Check your rate-limit status at console.x.ai/usage
2. If rate-limited, wait ~60 seconds and retry
3. Turn on debug logging:
   Copy

   logging:
     level: debug
   

4. Watch logs for agent_failed_early — that's the silent-drop indicator
5. For production, lower request volume, add delays between tool-heavy operations, or switch to the API-key path, which surfaces rate-limit responses more clearly

If your agent is misbehaving in ways beyond Grok, our Hermes agent not working guide covers the broader failure modes.

Headless Grok Setup (No Browser Available)

For a VPS, container, or SSH session, you have two options.

Option 1 — Use the API-key path (above). No browser needed at all. Simplest for servers.

Option 2 — OAuth on a machine with a browser, then copy the token:

1. Complete the OAuth setup on your local machine
2. Copy ~/.hermes/auth.json to the server
3. Tokens refresh automatically from the server

Alternatively, Hermes detects a remote environment and prints the authorization URL instead of opening a browser — but its loopback listener runs on the server at 127.0.0.1:56121, so you must forward that port first (ssh -L 56121:127.0.0.1:56121 user@your-server) before triggering auth. If the server loses connection for extended periods, you may need to re-authenticate from a machine with a browser.

Option 3 — Manual paste (no port forwarding). Run hermes auth add xai-oauth --manual-paste: Hermes prints the auth URL, you open it in any browser, approve, then paste the returned code back into the terminal. This skips the loopback listener entirely, so there's no 56121 tunnel to set up — the cleanest option when SSH port forwarding isn't available.

Grok Build vs Hermes Agent: What's the Difference?

These get confused because both run Grok, but they solve different problems:

• Grok Build is xAI's own first-party agent surface. It runs only on Grok models, lives inside xAI's product, and is the fastest way to try an agent if you're already all-in on xAI and don't need to touch the plumbing.
• Hermes Agent is a model-agnostic framework you self-host. Grok is one of several providers it can drive — you also get local config (~/.hermes/config.yaml), a gateway, memory, tool wiring, and the ability to swap to another model without rebuilding your agent.

Pick Grok Build if you want a zero-setup, xAI-only agent and never plan to leave Grok. Pick Hermes Agent if you want to own the config, run headless on your own servers, or keep the option to switch models later — the trade-off is the setup and the three bugs this guide fixes. If you'd rather have Hermes-style provider freedom without the config and bug workarounds, BetterClaw runs Grok (and 28+ other providers) as a managed agent.

Skip the Config: Grok on BetterClaw

BetterClaw handles xAI/Grok as one of 28+ BYOK providers. Paste your xAI API key, pick grok-4.3, and your agent is live in about 60 seconds — no streaming-bug workarounds, no auth.json rotation, no SSH tunnels. Free plan, BYOK.

Frequently Asked Questions

How do I connect Grok to Hermes Agent?

Update to Hermes v0.14+, run hermes model, select "xAI Grok OAuth," and sign in through your browser. No API key is needed if you have SuperGrok or X Premium+. Credentials save to ~/.hermes/auth.json and refresh automatically.

What does "user not found in auth context" mean in Hermes?

Your OAuth token is stale or was created with a different account than your active SuperGrok subscription. Delete ~/.hermes/auth.json, re-run hermes auth xai, and sign in with the exact account that holds the subscription. Also check ~/.hermes/.env for a stale XAI_API_KEY that overrides OAuth.

Why does Grok return HTTP 400 on Hermes?

Most often it's the Responses API streaming bug (#27197). Add api_mode: chat_completions under the model section of your config to fall back to the more stable path. A 400 can also come from switching a long-running session to Grok mid-stream (#32617), which a fresh session fixes.

Do I need a SuperGrok subscription for Grok on Hermes?

For the OAuth path, yes — SuperGrok or X Premium+. For the API-key path you only need an xAI API key from console.x.ai, no subscription required. SuperGrok is roughly $30/month as of 2026.

Which Grok model should I use with Hermes?

grok-4.3 for most agent tasks — it has a 1M-token context window and is the default in the OAuth flow. On the API-key path, a Grok Fast variant is the cheapest large-context option. Verify current models on xAI's pricing page.

Can I use Grok on Hermes without a browser?

Yes. Use the API-key path (set XAI_API_KEY in ~/.hermes/.env), complete OAuth on a local machine and copy ~/.hermes/auth.json to your server, or run hermes auth add xai-oauth --manual-paste to approve in any browser and paste the code back — no port forwarding needed.

Why does Grok sign-in say "existing account found"?

You have more than one Grok/X identity on the same email — usually a standalone grok.com account and a Grok login linked through X Premium+. Sign out of all but the one holding your subscription, then re-run hermes auth xai. Using a private/incognito window for the sign-in step avoids the loop.

Is Grok Build the same as Hermes Agent?

No. Grok Build is xAI's first-party, Grok-only agent surface with zero setup. Hermes Agent is a self-hosted, model-agnostic framework where Grok is one of several providers — you own the config and can swap models, at the cost of more setup.

Run Grok without the OAuth dance.

Paste your xAI key, pick a Grok model, deploy a managed agent in 60 seconds. No SSH tunnels, no streaming bugs. BYOK, free forever, not a trial. Start free →