Skip to main content

MiniMax OAuth

Hermes Agent supports MiniMax through a browser-based OAuth login flow, using the same credentials as the MiniMax portal. No API key or credit card is required — log in once and Hermes automatically refreshes your session.

The transport reuses the anthropic_messages adapter (MiniMax exposes an Anthropic Messages-compatible endpoint at /anthropic), so all existing tool-calling, streaming, and context features work without any adapter changes.

Overview​

ItemValue
Provider IDminimax-oauth
Display nameMiniMax (OAuth)
Auth typeBrowser OAuth (PKCE device-code flow)
TransportAnthropic Messages-compatible (anthropic_messages)
ModelsMiniMax-M2.7, MiniMax-M2.7-highspeed
Global endpointhttps://api.minimax.io/anthropic
China endpointhttps://api.minimaxi.com/anthropic
Requires env varNo (MINIMAX_API_KEY is not used for this provider)

Prerequisites​

  • Python 3.9+
  • Hermes Agent installed
  • A MiniMax account at minimax.io (global) or minimaxi.com (China)
  • A browser available on the local machine (or use --no-browser for remote sessions)

Quick Start​

# Launch the provider and model picker
hermes model
# → Select "MiniMax (OAuth)" from the provider list
# → Hermes opens your browser to the MiniMax authorization page
# → Approve access in the browser
# → Select a model (MiniMax-M2.7 or MiniMax-M2.7-highspeed)
# → Start chatting

hermes

After the first login, credentials are stored under ~/.hermes/auth.json and are refreshed automatically before each session.

Logging In Manually​

You can trigger a login without going through the model picker:

hermes auth add minimax-oauth

China region​

If your account is on the China platform (minimaxi.com), pass --region cn:

hermes auth add minimax-oauth --region cn

Remote / headless sessions​

On servers or containers where no browser is available:

hermes auth add minimax-oauth --no-browser

Hermes will print the verification URL and user code — open the URL on any device and enter the code when prompted.

The OAuth Flow​

Hermes implements a PKCE device-code flow against the MiniMax OAuth endpoints:

  1. Hermes generates a PKCE verifier / challenge pair and a random state value.
  2. It POSTs to {base_url}/oauth/code with the challenge and receives a user_code and verification_uri.
  3. Your browser opens verification_uri. If prompted, enter the user_code.
  4. Hermes polls {base_url}/oauth/token until the token arrives (or the deadline passes).
  5. Tokens (access_token, refresh_token, expiry) are saved to ~/.hermes/auth.json under the minimax-oauth key.

Token refresh (standard OAuth refresh_token grant) runs automatically at each session start when the access token is within 60 seconds of expiry.

Checking Login Status​

hermes doctor

The ◆ Auth Providers section will show:

✓ MiniMax OAuth  (logged in, region=global)

or, if not logged in:

⚠ MiniMax OAuth  (not logged in)

Switching Models​

hermes model
# → Select "MiniMax (OAuth)"
# → Pick from the model list

Or set the model directly:

hermes config set model MiniMax-M2.7
hermes config set provider minimax-oauth

Configuration Reference​

After login, ~/.hermes/config.yaml will contain entries similar to:

model:
  default: MiniMax-M2.7
  provider: minimax-oauth
  base_url: https://api.minimax.io/anthropic

--region flag​

ValuePortalInference endpoint
global (default)https://api.minimax.iohttps://api.minimax.io/anthropic
cnhttps://api.minimaxi.comhttps://api.minimaxi.com/anthropic

Provider aliases​

All of the following resolve to minimax-oauth:

hermes --provider minimax-oauth    # canonical
hermes --provider minimax-portal   # alias
hermes --provider minimax-global   # alias
hermes --provider minimax_oauth    # alias (underscore form)

Environment Variables​

The minimax-oauth provider does not use MINIMAX_API_KEY or MINIMAX_BASE_URL. Those variables are for the API-key-based minimax and minimax-cn providers only.

VariableEffect
MINIMAX_API_KEYUsed by minimax provider only — ignored for minimax-oauth
MINIMAX_CN_API_KEYUsed by minimax-cn provider only — ignored for minimax-oauth

To force the minimax-oauth provider at runtime:

HERMES_INFERENCE_PROVIDER=minimax-oauth hermes

Models​

ModelBest for
MiniMax-M2.7Long-context reasoning, complex tool-calling
MiniMax-M2.7-highspeedLower latency, lighter tasks, auxiliary calls

Both models support up to 200,000 tokens of context.

MiniMax-M2.7-highspeed is also used automatically as the auxiliary model for vision and delegation tasks when minimax-oauth is the primary provider.

Troubleshooting​

Token expired — not re-logging in automatically​

Hermes refreshes the token on every session start if it is within 60 seconds of expiry. If the access token is already expired (for example, after a long offline period), the refresh happens automatically on the next request. If refresh fails with refresh_token_reused or invalid_grant, Hermes marks the session as requiring re-login.

Fix: run hermes auth add minimax-oauth again to start a fresh login.

Authorization timed out​

The device-code flow has a finite expiry window. If you don't approve the login in time, Hermes raises a timeout error.

Fix: re-run hermes auth add minimax-oauth (or hermes model). The flow starts fresh.

State mismatch (possible CSRF)​

Hermes detected that the state value returned by the authorization server does not match what it sent.

Fix: re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response.

Logging in from a remote server​

If hermes cannot open a browser window, use --no-browser:

hermes auth add minimax-oauth --no-browser

Hermes prints the URL and code. Open the URL on any device and complete the flow there.

"Not logged into MiniMax OAuth" error at runtime​

The auth store has no credentials for minimax-oauth. You have not logged in yet, or the credential file was deleted.

Fix: run hermes model and select MiniMax (OAuth), or run hermes auth add minimax-oauth.

Logging Out​

To remove stored MiniMax OAuth credentials:

hermes auth remove minimax-oauth

See Also​