ibam28/dsh-llm-minimax-oauth

dsh-llm-minimax-oauth

License: MIT
DeepSeek Harness
Node
OAuth
Platform

DeepSeek Harness 插件：通过浏览器登录使用 MiniMax Global OAuth / Coding Plan。

通过自定义 LlmAdapter 在 DSH 的 LLM 运行时上注册 minimax-portal 提供商路由。用户通过基于浏览器的设备码 PKCE 流程授权一次；令牌持久化到 $DSH_HOME/minimax-oauth.json，在临近过期时透明刷新，并序列化到 DSH_MINIMAX_OAUTH_TOKEN_MINIMAX_PORTAL 环境变量中，以便适配器能够使用 Authorization: Bearer  针对 https://api.minimax.io/anthropic/v1/messages 对 Anthropic Messages 请求进行身份验证。

内置的 pi-ai minimax 路由（读取 MINIMAX_API_KEY 并发送 x-api-key 的 API 密钥路径）保持不变，仍可供通过 API 密钥进行身份验证的用户使用。OAuth 路径位于单独的路由 ID 上，因此两种身份验证通道永远不会冲突。

目录

- 先决条件
- 安装
- 使用
- 解锁的模型
- 身份验证
- 故障排除
- 安全
- 卸载
- 面向插件作者
- API 参考
- 参考
- 许可证

先决条件

- DeepSeek Harness 0.1.1-rc.2 或兼容版本（任何暴露 llm 和 webServer cordis 服务的版本）
- Node.js ^22.19.0 或 >=24.0.0
- 一个拥有有效 Coding Plan 或 Credits 余额的 MiniMax 账户（platform.minimax.io）
- 一个启用了弹出窗口的现代浏览器（或者愿意手动复制授权 URL——参见故障排除）

安装

该插件作为 DSH 捆绑包注册在你当前配置文件的 pnpm-workspace.yaml 和 cordis.patch.yml 中。最快的安装方式是通过 dsh plugin，它会为你写入这两个文件：

dsh plugin --profile web add /absolute/path/to/dsh-llm-minimax-oauth
or, from inside the plugin checkout:
dsh plugin --profile web add .

确认该层：

dsh --profile web --dump-config

通过 git 安装时，可能会要求你在配置文件的 pnpm-workspace.yaml 中允许 prepare（否则 pnpm ≥10 会拒绝生命周期脚本）：

allowBuilds:
dsh-llm-minimax-oauth: true

当插件通过 npm 发布时（未来），同样的命令会从你的注册表解析该包，而不是使用本地路径。

使用
在 http://127.0.0.1:3080 打开 Web UI，进入 Settings → MiniMax OAuth，
然后点击 Login with MiniMax。浏览器会打开一个新标签页，跳转到 MiniMax OAuth
授权页面。批准后返回设置面板——状态会在约 5 秒内变为“已登录”。

对于无头 / 远程会话，请运行 CLI 备用方案：

dsh-minimax-login              # interactive
dsh-minimax-login --no-browser # print URL, do not auto-open
dsh-minimax-login --logout     # clear stored token

登录后，在 ~/.dsh/settings.yaml 中设置默认模型：

agent-default-model:
provider: minimax-portal
model: MiniMax-M3

已解锁的模型

提供方 minimax-portal（本插件中的自定义适配器）位于
https://api.minimax.io/anthropic，提供 MiniMax-M3（1M 上下文、
视觉、推理）、MiniMax-M2.7 和 MiniMax-M2.7-highspeed。

MiniMax-M3 是默认模型，也是 Coding Plan 的推荐选择。

截图

成功登录后的 Settings → MiniMax OAuth 面板：

设置面板显示已登录状态及过期时间戳

点击“Login with MiniMax”后打开的浏览器端 MiniMax 授权页面：

浏览器授权页面确认授权成功

身份验证

该插件使用 Authorization: Bearer  进行身份验证，
与 MiniMax Global OAuth 契约一致，该契约记录于
，并在
OpenClaw 的 extensions/minimax/provider-registration.ts 中实现。

OAuth 流程形态（设备代码 + PKCE S256 + 状态验证）与 OpenClaw 的参考实现
逐字节一致：

- 设备代码端点：https://account.minimax.io/oauth2/device/code
- 令牌端点：https://account.minimax.io/oauth2/token
- 客户端 ID：78257093-7e40-4613-99e0-527b14b39113（OpenClaw 公共客户端 ID）
- 作用域：group_id profile model.completion
- 授权类型：urn:ietf:params:oauth:grant-type:user_code
- 刷新授权：refresh_token

令牌持久化于 $DSH_HOME/minimax-oauth.json（默认
~/.dsh/minimax-oauth.json），并作为 JSON 信封镜像到
DSH_MINIMAX_OAUTH_TOKEN_MINIMAX_PORTAL 环境变量中
（{access, refresh, expires_at, inference_base_url, oauth_base_url}）。

流程概览

┌──────────┐  POST /minimax-oauth/start   ┌─────────┐
│          │ ──────────────────────────▶ │         │
│          │ ◀── { userCode,             │ Server  │
│  Client  │      verificationUri }      │  (DSH)  │
│  (Web)   │                             │         │
│   UI     │ window.open(verificationUri) │         │
│          │                             │         │
│          │  GET /minimax-oauth/status  │  polls  │
│          │ ──────────────────────────▶ │  /oauth2│
│          │ ◀── { logged_in: true }     │  /token │
│          │                             │         │
│          │ writes access_token into    │         │
│          │ env DSH_MINIMAX_OAUTH_TOKEN │         │
└──────────┘                             └─────────┘
Bearer 认证 ──────────────────▶ MiniMax /v1/messages

为什么分两个阶段（而不是一个？） 面向浏览器的端点会在不到 1 秒内返回
设备代码。令牌轮询在服务器端后台运行，并在授权成功的那一刻将凭据写入
磁盘。这样可以保持 HTTP 连接简短，并避免阻塞式轮询会造成的
“正在等待浏览器……”卡死现象。

故障排查

插件已加载，但 /minimax-oauth/start 返回 405。 检查 DSH
Web 服务器路由注册是否已运行。查看构建产物 —— lib/index.mjs
必须包含 ctx.effect(() => ctx.webServer.register({...}))，而不是分离的
const r = ctx.webServer.register; r(...)。如果打包文件看起来是旧的，
请用 pnpm run build 重新构建。

浏览器不会自动打开。 弹窗拦截器可能会阻止
window.open。要么允许 127.0.0.1:3080 的弹窗，要么使用手动
流程：从设置面板复制验证 URL + 用户代码，然后在浏览器中
完成授权。

登录报告“Token Plan usage limit reached”。 账户配额已耗尽；
OAuth 握手成功，但模型端点返回了 429。请等待
配额重置，或在 MiniMax 的 Token Plan 页面升级套餐。

MiniMax OAuth refresh failed: invalid_grant。 存储的刷新令牌
已被撤销或过期（服务器端策略）。运行 dsh-minimax-login --logout
并重新授权。

MiniMax OAuth timed out before authorization completed。 用户
未在设备代码有效期内（默认约 10 分钟）完成授权。
请重新运行登录流程。

dsh plugin add 失败并提示 prepare script denied。 pnpm ≥10 默认
拒绝运行安装脚本。编辑配置文件的 pnpm-workspace.yaml，
并添加 安装 中的 allowBuilds 片段。

安全

- 令牌持久化在 $DSH_HOME/minimax-oauth.json，权限为 0600。
请勿提交或分享此文件。
- OAuth refresh_token 是敏感信息 —— 任何有权访问的人都可以签发
访问令牌，直到从你的 MiniMax 账户设置中显式撤销为止。
- 插件从不记录完整的令牌值；适配器在错误路径中仅记录经过
脱敏的预览。
- DSH_MINIMAX_OAUTH_TOKEN_MINIMAX_PORTAL 是一个进程本地环境变量，
镜像持久化的令牌；本插件不会从任何 shell rc 文件中导出或
加载它。
- 除了 MiniMax OAuth 端点和模型 API 之外，本插件不会启用遥测、
分析或对外网络调用。

卸载
sh
dsh plugin --profile web remove dsh-llm-minimax-oauth

然后移除持久化的凭据：
sh
rm -f ~/.dsh/minimax-oauth.json
unset DSH_MINIMAX_OAUTH_TOKEN_MINIMAX_PORTAL

内置的 pi-ai minimax 路由（API 密钥路径）不受影响，卸载后
仍可使用。

面向插件作者

本插件是一个可用的参考示例，展示了如何**通过
DSH Web 包中的 ctx.effect()。有两种可复制的模式：
ts
// 直接方法调用——通过 Reflect 代理保留 this 绑定。
// 切勿分离引用（const r = ctx.webServer.register; r(...)），
// 因为未绑定的方法调用会在 WebServer 内部崩溃，并抛出
// Cannot read properties of undefined (reading 'exact')。
ctx.effect(
() => ctx.webServer.register({ kind: 'exact', path: '/your/path', handler: ... }),
'descriptive-label',
)

// 客户端插槽注册——slots 必须在 inject 中声明。
ctx.effect(
() => ctx.slots.inject('your.slot.name', () =>
ctx.slots.register({ name: 'your.slot.name', ... }, YourComponent)),
'label',
)

该插件还展示了两阶段 OAuth 模式：服务器立即返回
设备代码 + 用户代码，浏览器打开 URL，轮询
在后台运行。避免让 HTTP 请求阻塞在长时间运行的
设备代码流程上。

API 参考

src/index.ts 导出运行时组件：
ts
import {
// 针对 minimax-portal 路由注册的 LlmAdapter
MiniMaxAdapter,
// 基于文件的令牌存储，采用原子写入
FileCredentialStore,
// 带有稳定 .code 值的 OAuth 错误类
MiniMaxOAuthError,
// OAuth 辅助函数（两阶段）
startAuthorization,  // 阶段 1：请求设备代码，返回 userCode + verificationUri
waitForToken,        // 阶段 2：轮询令牌，持久化状态
// 访问辅助函数
resolveAccessToken,   // 返回有效的 access_token，若已过期则刷新
refreshAccessToken,   // 使用存储的 refresh_token 强制刷新
// 令牌信封序列化（用于环境变量镜像）
readSerializedToken,
// 常量
MINIMAX_PROVIDER_ID, MINIMAX_INFERENCE_ENV_VAR,
MINIMAX_DEFAULT_MODEL_CATALOG, ...,
} from 'dsh-llm-minimax-oauth'

dsh.client 插槽注册位于 src/client/apply.ts。设置面板的
React UI 位于 src/client/index.tsx。

参考

OAuth 流程形态参照 OpenClaw 的参考实现：

端点 URL、scope、client id、PKCE 方法、grant type 以及
refresh-token 处理均相同。

许可证

MIT — 版权所有 (c) 2026 Bambang Saputra Jaya。