feat(cli): add minimax-oauth provider with PKCE browser flow by amanning3390 · Pull Request #15203 · NousResearch/hermes-agent

amanning3390 · 2026-04-24T15:01:13Z

What

Adds minimax-oauth as a first-class inference provider in Hermes Agent, alongside the existing API-key minimax / minimax-cn providers. Users can now log in to MiniMax via browser OAuth instead of pasting an API key.

New provider id: minimax-oauth (aliases: minimax-portal, minimax-global, minimax_oauth)
Auth: PKCE browser-based OAuth flow against https://api.minimax.io/oauth/code and /oauth/token
Transport: reuses the existing anthropic_messages api_mode against https://api.minimax.io/anthropic — no new adapter, no new api_mode, since agent/anthropic_adapter.py already supports Bearer-token auth
Tokens persisted in the existing auth store (get_hermes_home()), with standard OAuth2 refresh_token grant and refresh_token_reused / invalid_grant detection
--region global|cn flag to select between api.minimax.io and api.minimaxi.com
Supports MiniMax-M2.7 and MiniMax-M2.7-highspeed; MiniMax-M2.7-highspeed is wired as the auxiliary model

Why

MiniMax's platform docs describe OAuth as a supported auth method for AI coding tools, and it ships today in OpenClaw via the bundled minimax extension. Per the Hermes Adding Providers guide, OAuth flows warrant a first-class built-in provider so that hermes model → MiniMax (OAuth) can drive browser login end-to-end, tokens auto-refresh, and the experience matches the existing Nous Portal / OpenAI Codex OAuth paths.

The OAuth flow is ported from openclaw/extensions/minimax/oauth.ts (PKCE S256, urn:ietf:params:oauth:grant-type:user_code grant, state validation, poll-with-deadline).

How to test

Automated

# Clean pytest run (new tests)
pytest tests/test_minimax_oauth.py -v -p no:xdist
# → 15 passed

pytest tests/hermes_cli/test_api_key_providers.py tests/hermes_cli/test_runtime_provider_resolution.py -v -p no:xdist
# → 223 passed (including the new provider-resolution + runtime cases)

Manual smoke test

hermes model
# Select "MiniMax (OAuth)" → browser opens at verification URL
# Approve in browser
# Pick MiniMax-M2.7 or MiniMax-M2.7-highspeed

hermes doctor
# Should show "MiniMax OAuth: logged in (region=global)"

hermes  # or any inference-driving command
# First prompt goes through /anthropic with Bearer <access_token>

Refresh path can be exercised by manually rolling expires_at backwards in the auth store and issuing any request — the next resolve_minimax_oauth_runtime_credentials() call triggers a standard grant_type=refresh_token exchange.

Provider-alias resolution

hermes --provider minimax-portal ...    # → resolves to minimax-oauth
hermes --provider minimax-global ...    # → resolves to minimax-oauth

What platforms

macOS 14 (darwin-arm64, Python 3.11) — full test suite green, manual login path exercised
Linux (Debian 12, Python 3.11) — full test suite green

Browser open is skipped automatically on remote/headless sessions (reuses the existing _is_remote_session() helper); the user gets the verification URL + user code printed for manual paste.

Related issues

#6039 — minimax provider ignores custom base_url: orthogonal to this PR. The OAuth path always resolves inference_base_url from the registry + region flag and cannot be confused by a stale model.base_url.
#13757 — doctor uses /v1/models for MiniMax: the new get_minimax_oauth_auth_status() check used by hermes doctor only verifies local token state (present / not expired), so it does not hit the broken endpoint. Fix for the API-key doctor path is out of scope here.
#6620 — minimax-cn not shown in /model list: unrelated to the OAuth provider wiring; the new minimax-oauth entry is added to both CANONICAL_PROVIDERS and the select_provider_and_model() flow, so it shows up in hermes model and hermes setup from day one.

Scope / non-goals

No change to the existing API-key minimax or minimax-cn providers. MINIMAX_API_KEY / MINIMAX_CN_API_KEY continue to work for those, and are explicitly documented as not consumed by minimax-oauth.
No new adapter or api_mode. This is a Path A contribution per the Adding Providers guide.
Web search / image / speech MiniMax capabilities (present in the OpenClaw plugin) are not ported — only text inference.

Checklist (per Adding Providers)

Implementation ported from OpenClaw's reference OAuth flow at openclaw/extensions/minimax/oauth.ts. By contributing, I agree that this contribution will be licensed under the MIT License.

Add MiniMax OAuth (minimax-oauth) as a first-class provider using a PKCE device-code flow ported from openclaw/extensions/minimax/oauth.ts. Changes: - hermes_cli/auth.py: - Add 8 MINIMAX_OAUTH_* constants (client ID, scope, grant type, global/CN base URLs, inference URLs, refresh skew) - Add 'minimax-oauth' ProviderConfig to PROVIDER_REGISTRY (auth_type oauth_minimax) with global portal + inference base URLs and CN extras in the extra dict - Add provider aliases: minimax-portal, minimax-global, minimax_oauth - Implement _minimax_pkce_pair(), _minimax_request_user_code(), _minimax_poll_token(), _minimax_save_auth_state(), _minimax_oauth_login(), _refresh_minimax_oauth_state(), resolve_minimax_oauth_runtime_credentials(), get_minimax_oauth_auth_status(), _login_minimax_oauth() - Token refresh uses standard OAuth2 refresh_token grant; triggers relogin_required on invalid_grant / refresh_token_reused - hermes_cli/runtime_provider.py: - Add minimax-oauth branch (after qwen-oauth) that calls resolve_minimax_oauth_runtime_credentials() and returns api_mode='anthropic_messages' with the OAuth Bearer token - hermes_cli/auth_commands.py: - Add 'minimax-oauth' to _OAUTH_CAPABLE_PROVIDERS - Add auth_type auto-detection for oauth_minimax - Add provider == 'minimax-oauth' branch in auth_add_command - hermes_cli/doctor.py: - Import get_minimax_oauth_auth_status - Add MiniMax OAuth status check in the Auth Providers section

Wire MiniMax-M2.7 and MiniMax-M2.7-highspeed into the model catalog, CLI model picker, and agent auxiliary/metadata subsystems. Changes: - hermes_cli/models.py: - Add 'minimax-oauth' to _PROVIDER_MODELS with MiniMax-M2.7 and MiniMax-M2.7-highspeed - Add ProviderEntry('minimax-oauth', 'MiniMax (OAuth)', ...) to CANONICAL_PROVIDERS near existing minimax entries - Add aliases: minimax-portal, minimax-global, minimax_oauth in _PROVIDER_ALIASES - hermes_cli/main.py: - Add 'minimax-oauth' to provider_labels dict - Insert 'minimax-oauth' into providers list in select_provider_and_model() near the other minimax entries - Add 'minimax-oauth' to --provider argparse choices - Add _model_flow_minimax_oauth() function: ensures login via _login_minimax_oauth(), resolves runtime credentials, prompts for model selection, saves model choice and config - Add dispatch elif branch for selected_provider == 'minimax-oauth' - agent/auxiliary_client.py: - Add 'minimax-oauth': 'MiniMax-M2.7-highspeed' to _API_KEY_PROVIDER_AUX_MODELS - Add 'minimax-oauth' to _ANTHROPIC_COMPAT_PROVIDERS set - agent/model_metadata.py: - Add 'minimax-oauth' to _PROVIDER_PREFIXES frozenset - MiniMax-M2.7 context length (200_000) already covered by the existing 'minimax' substring match in DEFAULT_CONTEXT_LENGTHS

Add and extend tests for the minimax-oauth provider across three test modules. New file: tests/test_minimax_oauth.py (15 tests) - test_pkce_pair_produces_valid_s256: verifies PKCE verifier/challenge pair produces a valid S256 hash and correct lengths - test_request_user_code_happy_path: mocks httpx, verifies correct POST parameters and response parsing - test_request_user_code_state_mismatch_raises: verifies CSRF guard - test_request_user_code_non_200_raises: verifies HTTP error handling - test_poll_token_pending_then_success: verifies polling loop retries on 'pending' and returns on 'success' - test_poll_token_error_raises: verifies 'error' status raises AuthError - test_poll_token_timeout_raises: verifies deadline expiry raises - test_refresh_skip_when_not_expired: verifies no HTTP call when token is fresh - test_refresh_updates_access_token: verifies new access/refresh tokens stored on successful refresh - test_refresh_reuse_triggers_relogin_required: verifies relogin_required=True on invalid_grant/refresh_token_reused - test_resolve_credentials_requires_login: verifies AuthError when no stored state - test_provider_registry_contains_minimax_oauth: PROVIDER_REGISTRY key - test_minimax_oauth_alias_resolves: portal/global/underscore aliases - test_get_minimax_oauth_auth_status_not_logged_in - test_get_minimax_oauth_auth_status_logged_in Extended: tests/hermes_cli/test_runtime_provider_resolution.py - test_minimax_oauth_runtime_returns_anthropic_messages_mode - test_minimax_oauth_runtime_uses_inference_base_url Extended: tests/hermes_cli/test_api_key_providers.py - TestMinimaxOAuthProvider class (8 tests) covering registry keys, auth_type, endpoints, client_id, aliases, CANONICAL_PROVIDERS listing, _PROVIDER_MODELS entries, and aux model

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

Close integration gaps discovered by auditing qwen-oauth's file coverage. These are surfaces the original salvage missed — they all existed on main and were added in the 747 commits since PR #15203 was opened. Coverage added: - agent/credential_pool.py: seed pool from auth.json providers.minimax-oauth so `hermes auth list` reflects logged-in state and `hermes auth remove minimax-oauth <N>` works through the standard flow. - agent/credential_sources.py: register RemovalStep for minimax-oauth with suppression-aware `_clear_auth_store_provider`. - agent/models_dev.py: PROVIDER_TO_MODELS_DEV mapping (-> 'minimax' family). - hermes_cli/providers.py: HermesOverlay entry (anthropic_messages transport, oauth_external auth_type, api.minimax.io/anthropic base). - hermes_cli/model_normalize.py: add to _MATCHING_PREFIX_STRIP_PROVIDERS so `minimax-oauth/MiniMax-M2.7` in config.yaml gets correctly repaired. - hermes_cli/status.py: render MiniMax OAuth block in `hermes doctor` (logged-in / region / expires_at / error). - hermes_cli/web_server.py: register in OAUTH_PROVIDER_REGISTRY + dispatch branch in _resolve_provider_status so the dashboard auth page shows it. - website/docs/integrations/providers.md: full 'MiniMax (OAuth)' section. - website/docs/reference/cli-commands.md: --provider enum. - website/docs/user-guide/features/fallback-providers.md: fallback table row. - scripts/release.py AUTHOR_MAP: amanning3390 mapping (CI gate).

teknium1 · 2026-04-29T16:54:05Z

Merged via PR #17524 onto current main. All 4 of your original commits were cherry-picked with your authorship preserved (rebase-merge), plus a follow-up commit closed 10 integration gaps that peer OAuth providers had but hadn't existed yet when you opened this PR (credential pool seeding, credential_sources removal step, models_dev mapping, HermesOverlay, model normalize, hermes doctor block, dashboard auth page, and 3 docs pages). Thanks for the contribution — you're credited in scripts/release.py AUTHOR_MAP and in the merged git history.

Close integration gaps discovered by auditing qwen-oauth's file coverage. These are surfaces the original salvage missed — they all existed on main and were added in the 747 commits since PR NousResearch#15203 was opened. Coverage added: - agent/credential_pool.py: seed pool from auth.json providers.minimax-oauth so `hermes auth list` reflects logged-in state and `hermes auth remove minimax-oauth <N>` works through the standard flow. - agent/credential_sources.py: register RemovalStep for minimax-oauth with suppression-aware `_clear_auth_store_provider`. - agent/models_dev.py: PROVIDER_TO_MODELS_DEV mapping (-> 'minimax' family). - hermes_cli/providers.py: HermesOverlay entry (anthropic_messages transport, oauth_external auth_type, api.minimax.io/anthropic base). - hermes_cli/model_normalize.py: add to _MATCHING_PREFIX_STRIP_PROVIDERS so `minimax-oauth/MiniMax-M2.7` in config.yaml gets correctly repaired. - hermes_cli/status.py: render MiniMax OAuth block in `hermes doctor` (logged-in / region / expires_at / error). - hermes_cli/web_server.py: register in OAUTH_PROVIDER_REGISTRY + dispatch branch in _resolve_provider_status so the dashboard auth page shows it. - website/docs/integrations/providers.md: full 'MiniMax (OAuth)' section. - website/docs/reference/cli-commands.md: --provider enum. - website/docs/user-guide/features/fallback-providers.md: fallback table row. - scripts/release.py AUTHOR_MAP: amanning3390 mapping (CI gate).

amanning3390 added 4 commits April 24, 2026 14:31

alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have provider/minimax MiniMax (Anthropic transport) comp/cli CLI entry point, hermes_cli/, setup wizard area/auth Authentication, OAuth, credential pools labels Apr 24, 2026

This was referenced Apr 24, 2026

feat(cli): add minimax-oauth provider with PKCE browser flow (salvage #15203) #15419

Closed

feat(cli): add minimax-oauth provider with PKCE browser flow + full OAuth integration (salvage #15203) #17524

Merged

teknium1 closed this in #17524 Apr 29, 2026

subinium mentioned this pull request May 11, 2026

feat(providers): MiniMax as first-class provider (Hermes v0.12 parity) subinium/CrowClaw#322

Open

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add minimax-oauth provider with PKCE browser flow#15203

feat(cli): add minimax-oauth provider with PKCE browser flow#15203
amanning3390 wants to merge 4 commits into
NousResearch:mainfrom
amanning3390:feat/minimax-oauth-provider

amanning3390 commented Apr 24, 2026

Uh oh!

teknium1 commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

amanning3390 commented Apr 24, 2026

What

Why

How to test

Automated

Manual smoke test

Provider-alias resolution

What platforms

Related issues

Scope / non-goals

Checklist (per Adding Providers)

Uh oh!

teknium1 commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants