diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index b67f63ae3..d660336a4 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -70,6 +70,7 @@ Good defaults: |---|---| | Least friction | Nous Portal or OpenRouter | | You already have Claude or Codex auth | Anthropic or OpenAI Codex | +| You want MiniMax models without an API key | MiniMax (OAuth) — browser login, no billing setup | | You want local/private inference | Ollama or any custom OpenAI-compatible endpoint | | You want multi-provider routing | OpenRouter | | You have a custom GPU server | vLLM, SGLang, LiteLLM, or any OpenAI-compatible endpoint | diff --git a/website/docs/guides/minimax-oauth.md b/website/docs/guides/minimax-oauth.md new file mode 100644 index 000000000..2bc1ef368 --- /dev/null +++ b/website/docs/guides/minimax-oauth.md @@ -0,0 +1,224 @@ +--- +sidebar_position: 15 +title: "MiniMax OAuth" +description: "Log into MiniMax via browser OAuth and use MiniMax-M2.7 models in Hermes Agent — no API key required" +--- + +# MiniMax OAuth + +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. + +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 + +| Item | Value | +|------|-------| +| Provider ID | `minimax-oauth` | +| Display name | MiniMax (OAuth) | +| Auth type | Browser OAuth (PKCE device-code flow) | +| Transport | Anthropic Messages-compatible (`anthropic_messages`) | +| Models | `MiniMax-M2.7`, `MiniMax-M2.7-highspeed` | +| Global endpoint | `https://api.minimax.io/anthropic` | +| China endpoint | `https://api.minimaxi.com/anthropic` | +| Requires env var | No (`MINIMAX_API_KEY` is **not** used for this provider) | + +## Prerequisites + +- Python 3.9+ +- Hermes Agent installed +- A MiniMax account at [minimax.io](https://www.minimax.io) (global) or [minimaxi.com](https://www.minimaxi.com) (China) +- A browser available on the local machine (or use `--no-browser` for remote sessions) + +## Quick Start + +```bash +# 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: + +```bash +hermes auth add minimax-oauth +``` + +### China region + +If your account is on the China platform (`minimaxi.com`), pass `--region cn`: + +```bash +hermes auth add minimax-oauth --region cn +``` + +### Remote / headless sessions + +On servers or containers where no browser is available: + +```bash +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 + +```bash +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 + +```bash +hermes model +# → Select "MiniMax (OAuth)" +# → Pick from the model list +``` + +Or set the model directly: + +```bash +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: + +```yaml +model: + default: MiniMax-M2.7 + provider: minimax-oauth + base_url: https://api.minimax.io/anthropic +``` + +### `--region` flag + +| Value | Portal | Inference endpoint | +|-------|--------|-------------------| +| `global` (default) | `https://api.minimax.io` | `https://api.minimax.io/anthropic` | +| `cn` | `https://api.minimaxi.com` | `https://api.minimaxi.com/anthropic` | + +### Provider aliases + +All of the following resolve to `minimax-oauth`: + +```bash +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. + +| Variable | Effect | +|----------|--------| +| `MINIMAX_API_KEY` | Used by `minimax` provider only — ignored for `minimax-oauth` | +| `MINIMAX_CN_API_KEY` | Used by `minimax-cn` provider only — ignored for `minimax-oauth` | + +To force the `minimax-oauth` provider at runtime: + +```bash +HERMES_INFERENCE_PROVIDER=minimax-oauth hermes +``` + +## Models + +| Model | Best for | +|-------|----------| +| `MiniMax-M2.7` | Long-context reasoning, complex tool-calling | +| `MiniMax-M2.7-highspeed` | Lower 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`: + +```bash +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: + +```bash +hermes auth remove minimax-oauth +``` + +## See Also + +- [AI Providers reference](../integrations/providers.md) +- [Environment Variables](../reference/environment-variables.md) +- [Configuration](../user-guide/configuration.md) +- [hermes doctor](../reference/cli-commands.md) diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 42280b4df..56a7a7fda 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -36,10 +36,10 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | `KIMI_CN_API_KEY` | Kimi / Moonshot China API key ([moonshot.cn](https://platform.moonshot.cn)) | | `ARCEEAI_API_KEY` | Arcee AI API key ([chat.arcee.ai](https://chat.arcee.ai/)) | | `ARCEE_BASE_URL` | Override Arcee base URL (default: `https://api.arcee.ai/api/v1`) | -| `MINIMAX_API_KEY` | MiniMax API key — global endpoint ([minimax.io](https://www.minimax.io)) | -| `MINIMAX_BASE_URL` | Override MiniMax base URL (default: `https://api.minimax.io/anthropic` — Hermes uses MiniMax's Anthropic Messages-compatible endpoint) | -| `MINIMAX_CN_API_KEY` | MiniMax API key — China endpoint ([minimaxi.com](https://www.minimaxi.com)) | -| `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/anthropic`) | +| `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). | +| `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`**. | +| `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). | +| `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/anthropic`). **Not used by `minimax-oauth`**. | | `KILOCODE_API_KEY` | Kilo Code API key ([kilo.ai](https://kilo.ai)) | | `KILOCODE_BASE_URL` | Override Kilo Code base URL (default: `https://api.kilo.ai/api/gateway`) | | `XIAOMI_API_KEY` | Xiaomi MiMo API key ([platform.xiaomimimo.com](https://platform.xiaomimimo.com)) | @@ -86,7 +86,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe | Variable | Description | |----------|-------------| -| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `kilocode`, `xiaomi`, `arcee`, `alibaba`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `google-gemini-cli`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway` (default: `auto`) | +| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `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`, `alibaba`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `google-gemini-cli`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway` (default: `auto`) | | `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) | | `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL | | `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 80f5c6f88..ab4364eb1 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -657,7 +657,11 @@ Every model slot in Hermes — auxiliary tasks, compression, fallback — uses t 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. -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` — or any named custom provider from your `custom_providers` list (e.g. `provider: "beans"`). +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` — or any named custom provider from your `custom_providers` list (e.g. `provider: "beans"`). + +:::tip MiniMax OAuth +`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). +::: :::warning `"main"` is for auxiliary tasks only 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. @@ -793,6 +797,7 @@ These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`, | `"openrouter"` | Force OpenRouter — routes to any model (Gemini, GPT-4o, Claude, etc.) | `OPENROUTER_API_KEY` | | `"nous"` | Force Nous Portal | `hermes auth` | | `"codex"` | Force Codex OAuth (ChatGPT account). Supports vision (gpt-5.3-codex). | `hermes model` → Codex | +| `"minimax-oauth"` | Force MiniMax OAuth (browser login, no API key). Uses MiniMax-M2.7-highspeed for auxiliary tasks. | `hermes model` → MiniMax (OAuth) | | `"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 | ### Common Setups @@ -836,6 +841,15 @@ auxiliary: # model defaults to gpt-5.3-codex (supports vision) ``` +**Using MiniMax OAuth** (browser login, no API key needed): +```yaml +model: + default: MiniMax-M2.7 + provider: minimax-oauth + base_url: https://api.minimax.io/anthropic +``` +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. + **Using a local/self-hosted model:** ```yaml auxiliary: