How to Set Up Grok on Hermes Agent (and Fix the 3 Bugs That Break It)

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)

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.

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: 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.

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), or complete OAuth on a local machine and copy ~/.hermes/auth.json to your server.

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 →