Skip to content

Commit 1417f04

Browse files
amanning3390nickdlkk
amanning3390
authored and
nickdlkk
committed
docs: document MiniMax OAuth login flow
Add comprehensive documentation for the minimax-oauth provider. New file: website/docs/guides/minimax-oauth.md - Overview table (provider ID, auth type, models, endpoints) - Quick start via 'hermes model' - Manual login via 'hermes auth add minimax-oauth' - --region global|cn flag reference - The PKCE OAuth flow explained step-by-step - hermes doctor output example - Configuration reference (config.yaml shape, region table, aliases) - Environment variables note: MINIMAX_API_KEY is NOT used by minimax-oauth (OAuth path uses browser login) - Models table with context length note - Troubleshooting section: expired token, timeout, state mismatch, headless/remote sessions, not logged in - Logout command Updated: website/docs/getting-started/quickstart.md - Add MiniMax (OAuth) to provider picker table as the recommended path for users who want MiniMax models without an API key Updated: website/docs/user-guide/configuration.md - Add 'minimax-oauth' to the auxiliary providers list - Add MiniMax OAuth tip callout in the providers section - Add minimax-oauth row to the provider table (auxiliary tasks) - Add MiniMax OAuth config.yaml example in Common Setups Updated: website/docs/reference/environment-variables.md - Annotate MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_CN_API_KEY, MINIMAX_CN_BASE_URL as NOT used by minimax-oauth - Add minimax-oauth to HERMES_INFERENCE_PROVIDER allowed values
1 parent 1bb6e8a commit 1417f04

4 files changed

Lines changed: 245 additions & 6 deletions

File tree

‎website/docs/getting-started/quickstart.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ Good defaults:
7777
| **Kimi / Moonshot China** | China-region Moonshot endpoint | Set `KIMI_CN_API_KEY` |
7878
| **Arcee AI** | Trinity models | Set `ARCEEAI_API_KEY` |
7979
| **GMI Cloud** | Multi-model direct API | Set `GMI_API_KEY` |
80+
| **MiniMax (OAuth)** | MiniMax-M2.7 via browser OAuth — no API key needed | `hermes model` → MiniMax (OAuth) |
8081
| **MiniMax** | International MiniMax endpoint | Set `MINIMAX_API_KEY` |
8182
| **MiniMax China** | China-region MiniMax endpoint | Set `MINIMAX_CN_API_KEY` |
8283
| **Alibaba Cloud** | Qwen models via DashScope | Set `DASHSCOPE_API_KEY` |

‎website/docs/guides/minimax-oauth.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
sidebar_position: 15
3+
title: "MiniMax OAuth"
4+
description: "Log into MiniMax via browser OAuth and use MiniMax-M2.7 models in Hermes Agent — no API key required"
5+
---
6+
7+
# MiniMax OAuth
8+
9+
Hermes Agent supports **MiniMax** through a browser-based OAuth login flow, using the same credentials as the [MiniMax portal](https://www.minimax.io). No API key or credit card is required — log in once and Hermes automatically refreshes your session.
10+
11+
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.
12+
13+
## Overview
14+
15+
| Item | Value |
16+
|------|-------|
17+
| Provider ID | `minimax-oauth` |
18+
| Display name | MiniMax (OAuth) |
19+
| Auth type | Browser OAuth (PKCE device-code flow) |
20+
| Transport | Anthropic Messages-compatible (`anthropic_messages`) |
21+
| Models | `MiniMax-M2.7`, `MiniMax-M2.7-highspeed` |
22+
| Global endpoint | `https://api.minimax.io/anthropic` |
23+
| China endpoint | `https://api.minimaxi.com/anthropic` |
24+
| Requires env var | No (`MINIMAX_API_KEY` is **not** used for this provider) |
25+
26+
## Prerequisites
27+
28+
- Python 3.9+
29+
- Hermes Agent installed
30+
- A MiniMax account at [minimax.io](https://www.minimax.io) (global) or [minimaxi.com](https://www.minimaxi.com) (China)
31+
- A browser available on the local machine (or use `--no-browser` for remote sessions)
32+
33+
## Quick Start
34+
35+
```bash
36+
# Launch the provider and model picker
37+
hermes model
38+
# → Select "MiniMax (OAuth)" from the provider list
39+
# → Hermes opens your browser to the MiniMax authorization page
40+
# → Approve access in the browser
41+
# → Select a model (MiniMax-M2.7 or MiniMax-M2.7-highspeed)
42+
# → Start chatting
43+
44+
hermes
45+
```
46+
47+
After the first login, credentials are stored under `~/.hermes/auth.json` and are refreshed automatically before each session.
48+
49+
## Logging In Manually
50+
51+
You can trigger a login without going through the model picker:
52+
53+
```bash
54+
hermes auth add minimax-oauth
55+
```
56+
57+
### China region
58+
59+
If your account is on the China platform (`minimaxi.com`), pass `--region cn`:
60+
61+
```bash
62+
hermes auth add minimax-oauth --region cn
63+
```
64+
65+
### Remote / headless sessions
66+
67+
On servers or containers where no browser is available:
68+
69+
```bash
70+
hermes auth add minimax-oauth --no-browser
71+
```
72+
73+
Hermes will print the verification URL and user code — open the URL on any device and enter the code when prompted.
74+
75+
## The OAuth Flow
76+
77+
Hermes implements a PKCE device-code flow against the MiniMax OAuth endpoints:
78+
79+
1. Hermes generates a PKCE verifier / challenge pair and a random state value.
80+
2. It POSTs to `{base_url}/oauth/code` with the challenge and receives a `user_code` and `verification_uri`.
81+
3. Your browser opens `verification_uri`. If prompted, enter the `user_code`.
82+
4. Hermes polls `{base_url}/oauth/token` until the token arrives (or the deadline passes).
83+
5. Tokens (`access_token`, `refresh_token`, expiry) are saved to `~/.hermes/auth.json` under the `minimax-oauth` key.
84+
85+
Token refresh (standard OAuth `refresh_token` grant) runs automatically at each session start when the access token is within 60 seconds of expiry.
86+
87+
## Checking Login Status
88+
89+
```bash
90+
hermes doctor
91+
```
92+
93+
The `◆ Auth Providers` section will show:
94+
95+
```
96+
✓ MiniMax OAuth (logged in, region=global)
97+
```
98+
99+
or, if not logged in:
100+
101+
```
102+
⚠ MiniMax OAuth (not logged in)
103+
```
104+
105+
## Switching Models
106+
107+
```bash
108+
hermes model
109+
# → Select "MiniMax (OAuth)"
110+
# → Pick from the model list
111+
```
112+
113+
Or set the model directly:
114+
115+
```bash
116+
hermes config set model MiniMax-M2.7
117+
hermes config set provider minimax-oauth
118+
```
119+
120+
## Configuration Reference
121+
122+
After login, `~/.hermes/config.yaml` will contain entries similar to:
123+
124+
```yaml
125+
model:
126+
default: MiniMax-M2.7
127+
provider: minimax-oauth
128+
base_url: https://api.minimax.io/anthropic
129+
```
130+
131+
### `--region` flag
132+
133+
| Value | Portal | Inference endpoint |
134+
|-------|--------|-------------------|
135+
| `global` (default) | `https://api.minimax.io` | `https://api.minimax.io/anthropic` |
136+
| `cn` | `https://api.minimaxi.com` | `https://api.minimaxi.com/anthropic` |
137+
138+
### Provider aliases
139+
140+
All of the following resolve to `minimax-oauth`:
141+
142+
```bash
143+
hermes --provider minimax-oauth # canonical
144+
hermes --provider minimax-portal # alias
145+
hermes --provider minimax-global # alias
146+
hermes --provider minimax_oauth # alias (underscore form)
147+
```
148+
149+
## Environment Variables
150+
151+
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.
152+
153+
| Variable | Effect |
154+
|----------|--------|
155+
| `MINIMAX_API_KEY` | Used by `minimax` provider only — ignored for `minimax-oauth` |
156+
| `MINIMAX_CN_API_KEY` | Used by `minimax-cn` provider only — ignored for `minimax-oauth` |
157+
158+
To force the `minimax-oauth` provider at runtime:
159+
160+
```bash
161+
HERMES_INFERENCE_PROVIDER=minimax-oauth hermes
162+
```
163+
164+
## Models
165+
166+
| Model | Best for |
167+
|-------|----------|
168+
| `MiniMax-M2.7` | Long-context reasoning, complex tool-calling |
169+
| `MiniMax-M2.7-highspeed` | Lower latency, lighter tasks, auxiliary calls |
170+
171+
Both models support up to 200,000 tokens of context.
172+
173+
`MiniMax-M2.7-highspeed` is also used automatically as the auxiliary model for vision and delegation tasks when `minimax-oauth` is the primary provider.
174+
175+
## Troubleshooting
176+
177+
### Token expired — not re-logging in automatically
178+
179+
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.
180+
181+
**Fix:** run `hermes auth add minimax-oauth` again to start a fresh login.
182+
183+
### Authorization timed out
184+
185+
The device-code flow has a finite expiry window. If you don't approve the login in time, Hermes raises a timeout error.
186+
187+
**Fix:** re-run `hermes auth add minimax-oauth` (or `hermes model`). The flow starts fresh.
188+
189+
### State mismatch (possible CSRF)
190+
191+
Hermes detected that the `state` value returned by the authorization server does not match what it sent.
192+
193+
**Fix:** re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response.
194+
195+
### Logging in from a remote server
196+
197+
If `hermes` cannot open a browser window, use `--no-browser`:
198+
199+
```bash
200+
hermes auth add minimax-oauth --no-browser
201+
```
202+
203+
Hermes prints the URL and code. Open the URL on any device and complete the flow there.
204+
205+
### "Not logged into MiniMax OAuth" error at runtime
206+
207+
The auth store has no credentials for `minimax-oauth`. You have not logged in yet, or the credential file was deleted.
208+
209+
**Fix:** run `hermes model` and select MiniMax (OAuth), or run `hermes auth add minimax-oauth`.
210+
211+
## Logging Out
212+
213+
To remove stored MiniMax OAuth credentials:
214+
215+
```bash
216+
hermes auth remove minimax-oauth
217+
```
218+
219+
## See Also
220+
221+
- [AI Providers reference](../integrations/providers.md)
222+
- [Environment Variables](../reference/environment-variables.md)
223+
- [Configuration](../user-guide/configuration.md)
224+
- [hermes doctor](../reference/cli-commands.md)

‎website/docs/reference/environment-variables.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,10 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
3838
| `ARCEE_BASE_URL` | Override Arcee base URL (default: `https://api.arcee.ai/api/v1`) |
3939
| `GMI_API_KEY` | GMI Cloud API key ([gmicloud.ai](https://www.gmicloud.ai/)) |
4040
| `GMI_BASE_URL` | Override GMI Cloud base URL (default: `https://api.gmi-serving.com/v1`) |
41-
| `MINIMAX_API_KEY` | MiniMax API key — global endpoint ([minimax.io](https://www.minimax.io)) |
42-
| `MINIMAX_BASE_URL` | Override MiniMax base URL (default: `https://api.minimax.io/anthropic` — Hermes uses MiniMax's Anthropic Messages-compatible endpoint) |
43-
| `MINIMAX_CN_API_KEY` | MiniMax API key — China endpoint ([minimaxi.com](https://www.minimaxi.com)) |
44-
| `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/anthropic`) |
41+
| `MINIMAX_API_KEY` | MiniMax API key — global endpoint ([minimax.io](https://www.minimax.io)). **Not used by `minimax-oauth`** (OAuth path uses browser login instead). |
42+
| `MINIMAX_BASE_URL` | Override MiniMax base URL (default: `https://api.minimax.io/anthropic` — Hermes uses MiniMax's Anthropic Messages-compatible endpoint). **Not used by `minimax-oauth`**. |
43+
| `MINIMAX_CN_API_KEY` | MiniMax API key — China endpoint ([minimaxi.com](https://www.minimaxi.com)). **Not used by `minimax-oauth`** (OAuth path uses browser login instead). |
44+
| `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/anthropic`). **Not used by `minimax-oauth`**. |
4545
| `KILOCODE_API_KEY` | Kilo Code API key ([kilo.ai](https://kilo.ai)) |
4646
| `KILOCODE_BASE_URL` | Override Kilo Code base URL (default: `https://api.kilo.ai/api/gateway`) |
4747
| `XIAOMI_API_KEY` | Xiaomi MiMo API key ([platform.xiaomimimo.com](https://platform.xiaomimimo.com)) |
@@ -93,7 +93,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
9393

9494
| Variable | Description |
9595
|----------|-------------|
96-
| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `custom`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `gemini`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `google-gemini-cli`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway` (default: `auto`) |
96+
| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `custom`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `gemini`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth` (browser OAuth login — no API key required; see [MiniMax OAuth guide](../guides/minimax-oauth.md)), `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `google-gemini-cli`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway` (default: `auto`) |
9797
| `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) |
9898
| `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL |
9999
| `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) |

‎website/docs/user-guide/configuration.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -737,7 +737,11 @@ Every model slot in Hermes — auxiliary tasks, compression, fallback — uses t
737737

738738
When `base_url` is set, Hermes ignores the provider and calls that endpoint directly (using `api_key` or `OPENAI_API_KEY` for auth). When only `provider` is set, Hermes uses that provider's built-in auth and base URL.
739739

740-
Available providers for auxiliary tasks: `auto`, `main`, plus any provider in the [provider registry](/docs/reference/environment-variables) — `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `google-gemini-cli`, `qwen-oauth`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `deepseek`, `nvidia`, `xai`, `ollama-cloud`, `alibaba`, `bedrock`, `huggingface`, `arcee`, `xiaomi`, `kilocode`, `opencode-zen`, `opencode-go`, `ai-gateway`, `azure-foundry` — or any named custom provider from your `custom_providers` list (e.g. `provider: "beans"`).
740+
Available providers for auxiliary tasks: `auto`, `main`, plus any provider in the [provider registry](/docs/reference/environment-variables) — `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `google-gemini-cli`, `qwen-oauth`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `ollama-cloud`, `alibaba`, `bedrock`, `huggingface`, `arcee`, `xiaomi`, `kilocode`, `opencode-zen`, `opencode-go`, `ai-gateway`, `azure-foundry` — or any named custom provider from your `custom_providers` list (e.g. `provider: "beans"`).
741+
742+
:::tip MiniMax OAuth
743+
`minimax-oauth` logs in via browser OAuth (no API key needed). Run `hermes model` and select **MiniMax (OAuth)** to authenticate. Auxiliary tasks use `MiniMax-M2.7-highspeed` automatically. See the [MiniMax OAuth guide](../guides/minimax-oauth.md).
744+
:::
741745

742746
:::warning `"main"` is for auxiliary tasks only
743747
The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and `fallback_model:` configs. It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](/docs/integrations/providers) for all main model provider options.
@@ -865,6 +869,7 @@ These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`,
865869
| `"openrouter"` | Force OpenRouter — routes to any model (Gemini, GPT-4o, Claude, etc.) | `OPENROUTER_API_KEY` |
866870
| `"nous"` | Force Nous Portal | `hermes auth` |
867871
| `"codex"` | Force Codex OAuth (ChatGPT account). Supports vision (gpt-5.3-codex). | `hermes model` → Codex |
872+
| `"minimax-oauth"` | Force MiniMax OAuth (browser login, no API key). Uses MiniMax-M2.7-highspeed for auxiliary tasks. | `hermes model` → MiniMax (OAuth) |
868873
| `"main"` | Use your active custom/main endpoint. This can come from `OPENAI_BASE_URL` + `OPENAI_API_KEY` or from a custom endpoint saved via `hermes model` / `config.yaml`. Works with OpenAI, local models, or any OpenAI-compatible API. **Auxiliary tasks only — not valid for `model.provider`.** | Custom endpoint credentials + base URL |
869874

870875
Direct API-key providers from the main provider catalog also work here when you want side tasks to bypass your default router. `gmi` is valid once `GMI_API_KEY` is configured:
@@ -919,6 +924,15 @@ auxiliary:
919924
# model defaults to gpt-5.3-codex (supports vision)
920925
```
921926

927+
**Using MiniMax OAuth** (browser login, no API key needed):
928+
```yaml
929+
model:
930+
default: MiniMax-M2.7
931+
provider: minimax-oauth
932+
base_url: https://api.minimax.io/anthropic
933+
```
934+
Run `hermes model` and select **MiniMax (OAuth)** to log in and set this automatically. For the China region, the base URL will be `https://api.minimaxi.com/anthropic`. See the [MiniMax OAuth guide](../guides/minimax-oauth.md) for the full walkthrough.
935+
922936
**Using a local/self-hosted model:**
923937
```yaml
924938
auxiliary:

0 commit comments

Comments
 (0)