Hermes Agent 接入 MiniMax OAuth：国产大模型 OAuth 集成

Hermes Agent 支持通过浏览器 OAuth 登录流程接入 MiniMax，使用与 MiniMax 门户相同的账号凭证，无需 API Key 或信用卡——登录一次后 Hermes 会自动刷新会话。

底层传输复用了 anthropic_messages 适配器（MiniMax 在 /anthropic 路径暴露了兼容 Anthropic Messages 的端点），因此所有现有的工具调用、流式输出和上下文功能均无需修改适配器即可正常工作。

概览

前置条件

• Python 3.9+
• 已安装 Hermes Agent
• 拥有 MiniMax 账号（minimax.io 全球站 或 minimaxi.com 国内站）
• 本机可使用浏览器（远程会话可使用 --no-browser 参数）

快速开始

# 启动 Provider 和模型选择器
hermes model
# → 从 Provider 列表选择 "MiniMax (OAuth)"
# → Hermes 将打开浏览器跳转到 MiniMax 授权页面
# → 在浏览器中批准访问
# → 选择模型（MiniMax-M2.7 或 MiniMax-M2.7-highspeed）
# → 开始对话

hermes

首次登录后，凭证将存储在 ~/.hermes/auth.json 中，并在每次会话开始前自动刷新。

手动登录

无需通过模型选择器即可触发登录：

hermes auth add minimax-oauth

国内区域

如果你的账号在国内平台（minimaxi.com），请使用国内区域的 OAuth Provider ID minimax-cn，或者跳过 OAuth 直接配置 MINIMAX_CN_API_KEY / MINIMAX_CN_BASE_URL。旧文档中描述的 --region cn 标志未接入 CLI 参数解析器，请改用 minimax-cn Provider：

hermes auth add minimax-cn --type oauth   # 如果你的国内账号支持 OAuth
# 或更简单的方式：
echo 'MINIMAX_CN_API_KEY=your-key' >> ~/.hermes/.env

远程/无头会话

在没有浏览器的服务器或容器中：

hermes auth add minimax-oauth --no-browser

Hermes 将打印验证 URL 和用户码——在任意设备上打开该 URL 并按提示输入用户码即可。

OAuth 流程详解

Hermes 对 MiniMax OAuth 端点实现了 PKCE 设备码流程：

1. Hermes 生成 PKCE 验证器/挑战对以及一个随机 state 值。
2. 向 {base_url}/oauth/code 发送 POST 请求（携带 challenge），获取 user_code 和 verification_uri。
3. 浏览器打开 verification_uri，按提示输入 user_code。
4. Hermes 轮询 {base_url}/oauth/token 直到获取令牌（或超时）。
5. 令牌（access_token、refresh_token、过期时间）保存到 ~/.hermes/auth.json 的 minimax-oauth 键下。

令牌刷新（标准 OAuth refresh_token 授权）在每次会话启动时自动执行——当 access token 距过期不足 60 秒时触发。

检查登录状态

hermes doctor

◆ Auth Providers 部分将显示：

若未登录则显示：

切换模型

hermes model
# → 选择 "MiniMax (OAuth)"
# → 从模型列表中选择

或直接设置模型：

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

配置参考

登录后，~/.hermes/config.yaml 将包含类似以下内容：

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

区域端点

Provider 别名

以下所有写法均解析为 minimax-oauth：

hermes --provider minimax-oauth    # 规范写法
hermes --provider minimax-portal   # 别名
hermes --provider minimax-global   # 别名
hermes --provider minimax_oauth    # 别名（下划线形式）

环境变量

minimax-oauth Provider 不使用 MINIMAX_API_KEY 或 MINIMAX_BASE_URL。这些变量仅用于基于 API Key 的 minimax 和 minimax-cn Provider。

运行时强制使用 minimax-oauth Provider：

HERMES_INFERENCE_PROVIDER=minimax-oauth hermes

模型说明

两个模型均支持最高 200,000 token 的上下文长度。

当 minimax-oauth 作为主 Provider 时，MiniMax-M2.7-highspeed 也会自动作为视觉和委托任务的辅助模型使用。

常见问题排查

Token 过期——未自动重新登录

Hermes 在每次会话启动时，若 access token 距过期不足 60 秒则自动刷新。若 access token 已过期（例如长时间离线后），刷新会在下次请求时自动执行。若刷新失败并返回 refresh_token_reused 或 invalid_grant，Hermes 将标记该会话需要重新登录。

解决方法： 再次运行 hermes auth add minimax-oauth 发起新的登录。

授权超时

设备码流程有有限的有效期窗口。若未及时批准登录，Hermes 将抛出超时错误。

解决方法： 重新运行 hermes auth add minimax-oauth（或 hermes model），流程将重新开始。

State 不匹配（可能的 CSRF）

Hermes 检测到授权服务器返回的 state 值与发送值不匹配。

解决方法： 重新登录。若持续出现，请检查是否有代理或重定向在修改 OAuth 响应。

从远程服务器登录

如果 hermes 无法打开浏览器窗口，请使用 --no-browser：

hermes auth add minimax-oauth --no-browser

Hermes 将打印 URL 和用户码，在任意设备上打开 URL 完成授权流程即可。

运行时报错 "Not logged into MiniMax OAuth"

认证存储中没有 minimax-oauth 的凭证，可能是尚未登录或凭证文件被删除。

解决方法： 运行 hermes model 并选择 MiniMax (OAuth)，或运行 hermes auth add minimax-oauth。

退出登录

移除已存储的 MiniMax OAuth 凭证：

hermes auth remove minimax-oauth

相关文档

• AI Providers 参考
• 环境变量
• 配置
• hermes doctor