How to Use SuperGrok With Hermes Agent Without an xAI API Key

By . in Toolkit. Updated on .

Hermes Agent can use Grok through an existing SuperGrok subscription, or through an X Premium+ subscription linked to the X account you sign in with. That means you do not need to create an XAI_API_KEY just to try xAI models inside Hermes.

You log in once through a browser-based OAuth flow, Hermes saves the tokens locally, and future sessions refresh automatically in the background.

Grok Hermes integration

That is the simple version. The nicer part is that the same login also covers Hermes’ direct xAI media tools, including text-to-speech, image generation, video generation, and transcription. The same xAI credentials can also enable X search if you want that tool available.

If you already pay for SuperGrok or X Premium+, this is a cleaner way to connect Hermes to Grok without juggling API keys. If you are still figuring out where Hermes fits, this OpenClaw vs Hermes Agent comparison is a useful companion.

What Hermes Is Actually Using

The provider is called xAI Grok OAuth (SuperGrok / X Premium+) inside Hermes. Its provider ID is:

xai-oauth

Under the hood, Hermes connects to xAI’s Responses-style API endpoint at:

https://api.x.ai/v1

Hermes reuses its codex_responses transport for this provider, so features such as reasoning, tool calling, streaming, and prompt caching work without needing a separate Grok-specific adapter.

The default model is currently:

grok-4.3

Hermes pins that model near the top of the picker after you log in.

What You Need First

Before setting this up, you need:

  • Python 3.9 or newer
  • Hermes Agent installed
  • An active SuperGrok subscription, or an X Premium+ subscription on the X account you use for login
  • A browser on the same machine, or SSH port forwarding if you are setting it up on a remote server

The important detail: this provider does not use XAI_API_KEY. If you want to use your Grok subscription instead of API billing, use the OAuth provider.

There is one caveat worth knowing early. Hermes’ docs note that xAI may restrict OAuth API access by tier. If the browser login works but inference returns HTTP 403, you may need to switch to the API-key provider instead.

Sign In Through the Model Picker

The easiest setup path is through Hermes’ model picker:

hermes model

Select xAI Grok OAuth (SuperGrok / X Premium+) from the provider list. Hermes opens accounts.x.ai in your browser, where you sign in and approve access. This is a normal OAuth-style login flow: you approve access in the browser instead of copying a long secret key into your terminal.

After that, pick a Grok model. For most people, grok-4.3 is the obvious starting point.

Then start Hermes normally:

hermes

Hermes stores the login credentials in:

~/.hermes/auth.json

Once the tokens are saved, Hermes refreshes them automatically before they expire. You should not have to repeat the browser login for every session.

Sign In Manually

If you already know you want the xAI OAuth provider, you can skip the model picker and start the auth flow directly:

hermes auth add xai-oauth

This launches the same browser login flow. After approval, Hermes saves the OAuth tokens and the provider is ready to use.

Set Grok as Your Default Model

You can switch providers through the interactive model picker:

hermes model

Or set the provider and model directly:

hermes config set model.default grok-4.3
hermes config set model.provider xai-oauth

Your ~/.hermes/config.yaml should then contain something like this:

model:
  default: grok-4.3
  provider: xai-oauth
  base_url: https://api.x.ai/v1

Hermes also accepts a few provider aliases if you prefer something more descriptive:

hermes --provider xai-oauth
hermes --provider grok-oauth
hermes --provider x-ai-oauth
hermes --provider xai-grok-oauth

I would still use xai-oauth in scripts and documentation. It is shorter and canonical.

Using It on a Remote Server

OAuth is slightly more annoying when Hermes is running on a server, container, or SSH session.

Hermes can print the authorization URL instead of opening a browser:

hermes auth add xai-oauth --no-browser

But the callback listener still runs on the remote machine at:

127.0.0.1:56121

If you open the printed URL on your laptop without forwarding that port, the browser cannot reach the callback listener. You will usually see a connection error.

Open a second terminal on your local machine and forward the port first:

ssh -N -L 56121:127.0.0.1:56121 user@remote-host

Then, in the SSH session where Hermes is running:

hermes auth add xai-oauth --no-browser

Open the printed URL in your local browser. The login should now redirect back through the forwarded port to Hermes on the remote machine.

If you connect through a jump host, add -J jump-user@jump-host to the SSH command.

Browser-Only Remote Consoles

If you are using a browser-based remote console, such as Cloud Shell, Codespaces, EC2 Instance Connect, Gitpod, or a similar environment, the SSH forwarding recipe may not be available.

In that case, use manual paste mode:

hermes auth add xai-oauth --manual-paste

Or launch it from the model picker:

hermes model --manual-paste

Hermes skips the local callback listener and lets you paste the failed callback URL from the browser instead.

Check Whether the Login Worked

Run:

hermes doctor

Look for the Auth Providers section and check the status for xai-oauth.

If Hermes has a valid OAuth entry, Grok should be available through the model picker and direct provider selection.

Use the Same Login for xAI Tools

The OAuth token is not limited to chat models. Hermes can reuse the same xAI login for several direct-to-xAI tools:

  • Text-to-speech
  • Image generation
  • Video generation
  • Transcription
  • X search

Open the tools picker:

hermes tools

Then choose the xAI backend where needed:

  • Text-to-Speech: xAI TTS
  • Image Generation: xAI Grok Imagine (image)
  • Video Generation: xAI Grok Imagine
  • X Search: xAI Grok OAuth (SuperGrok / X Premium+)

If your OAuth token is already stored, Hermes should detect it and skip the credential prompt.

A small gotcha: video generation is disabled by default, so enable it in hermes tools before expecting the agent to call the video tool. X search behaves differently: Hermes’ docs say it auto-enables when xAI credentials are present, but you can still disable it explicitly in the tools picker if you do not want it available.

Available Grok Models

The current xAI OAuth setup exposes Grok chat models such as:

  • grok-4.3
  • grok-4.20-0309-reasoning
  • grok-4.20-0309-non-reasoning
  • grok-4.20-multi-agent-0309

For media tools, Hermes lists xAI options such as:

  • grok-imagine-image
  • grok-imagine-image-quality
  • grok-imagine-video
  • xAI TTS through the /v1/tts endpoint

The chat model catalog is pulled from Hermes’ local models.dev cache, so new xAI model releases can appear after that cache refreshes.

Fix Common OAuth Problems

Most setup problems fall into a few predictable buckets.

Token Expired or Refresh Failed

Hermes refreshes tokens before a session and can also retry after a 401 response. If the refresh token was revoked or rotated, Hermes will ask you to authenticate again.

Run:

hermes auth add xai-oauth
Login Timed Out

The local callback listener only stays open for a limited window. If you do not approve the login quickly enough, the flow times out.

Run the login command again and approve the browser request within the window:

hermes auth add xai-oauth
State Mismatch

A state mismatch usually means the OAuth response did not match the request Hermes created. Re-run the login. If it keeps happening, check whether a proxy, browser extension, or redirect layer is interfering with the callback.

Remote Login Cannot Reach the App

This is the common SSH setup failure. The browser is on your laptop, but the callback listener is on the remote machine.

Forward the callback port:

ssh -N -L 56121:127.0.0.1:56121 user@remote-host

Then rerun:

hermes auth add xai-oauth --no-browser
HTTP 403 After a Successful Login

If OAuth login succeeds but inference returns HTTP 403, the problem may be subscription entitlement rather than a stale token. Hermes’ docs say xAI’s backend has been seen to restrict OAuth API access for some tiers.

If that happens, re-running hermes model is unlikely to fix it. Use the API-key provider instead:

export XAI_API_KEY=xai-...
hermes config set model.provider xai

Or upgrade your Grok subscription if the OAuth route is required.

No xAI Credentials Found

Hermes has no saved xai-oauth entry and no XAI_API_KEY set.

If you want to use SuperGrok or X Premium+ OAuth, run:

hermes model

Pick the xAI Grok OAuth provider, or run:

hermes auth add xai-oauth

Log Out When Needed

To remove saved xAI OAuth credentials:

hermes auth logout xai-oauth

That clears the OAuth entry from Hermes’ auth store.

If you only want to remove one credential entry from a pool, list the entries first:

hermes auth list xai-oauth

Then remove the specific entry:

hermes auth remove xai-oauth <index|id|label>

Final Thought

The appeal here is convenience. If you already have SuperGrok or X Premium+, Hermes can use that subscription through a normal browser login. No API key. No separate setup for every xAI tool. No awkward token copying.

For local use, the setup is basically hermes model, pick xAI OAuth, approve in the browser, and start chatting. If you prefer a GUI around Hermes, Hermes Desktop may be worth setting up too.

For remote machines, remember the callback port: 56121. That one small detail saves a lot of head-scratching.

WebsiteFacebookTwitterInstagramPinterestLinkedInGoogle+YoutubeRedditDribbbleBehanceGithubCodePenWhatsappEmail