@coclaw/openclaw-coclaw 0.22.4 → 0.23.0

package/index.js

@@ -18,6 +18,7 @@ import { abortAgentRun } from './src/agent-abort.js';
 import { decideCancelResponse } from './src/agent-cancel-heuristic.js';
 import { remoteLog } from './src/remote-log.js';
 import { registerProviderAuthHandlers } from './src/provider-auth/index.js';
+import { reconcilePortalModels } from './src/provider-auth/reconcile.js';
 import { registerModelDefaultHandlers } from './src/model-default/index.js';
 import { getClawConfig } from './src/claw-config.js';
 
@@ -203,7 +204,16 @@ const plugin = {
 			.catch((err) => {
 				logger.warn?.(`[coclaw] chat history manager load/reconcile failed: ${String(err?.message ?? err)}`);
 			});
-		__pluginInitDone = Promise.all([topicLoadP, chatHistoryLoadP]);
+		// 启动对账 minimax-portal 模型清单：已绑定且与内置表不一致才刷新（一致零写入，
+		// 防"写配置触发重启"时的反复重启）。升级补了新模型靠这条让老用户重启后自动同步。
+		// config-mutation 字面量 specifier 必须出现在本入口源码里（loader 只扫入口识别 jiti alias）。
+		const portalSyncP = import('openclaw/plugin-sdk/config-mutation')
+			.then(({ mutateConfigFile }) => reconcilePortalModels({ getConfig: getClawConfig, mutateConfigFile }))
+			.then((r) => { if (r.changed) logger.info?.('[coclaw] minimax-portal model list synced from plugin catalog'); })
+			.catch((err) => {
+				logger.warn?.(`[coclaw] minimax-portal model reconcile failed: ${String(err?.message ?? err)}`);
+			});
+		__pluginInitDone = Promise.all([topicLoadP, chatHistoryLoadP, portalSyncP]);
 
 		// 追踪 chat 因 reset 产生的 session 流水。双源回调（hook + sessions.changed）共用 helper。
 		// recordSessionTransition 内部已 __reloadFromDisk + mutex，外层无需再 cache.has + load。
@@ -790,13 +800,15 @@ const plugin = {
 			}
 		});
 
-		// provider 认证管理 RPC（API key 写入 / 列表 / 撤销）。SDK 走懒加载 dynamic import，
-		// 不增加本插件 cold-load 开销，也让测试环境无需 openclaw 包就能加载 index.js。
-		// loadSdk 字面量必须留在本入口源码里：OpenClaw plugin loader 只扫入口文件识别
+		// provider 认证管理 RPC（API key 写入 / 列表 / 撤销 + OAuth 登录/取消）。SDK 走懒加载
+		// dynamic import，不增加本插件 cold-load 开销，也让测试环境无需 openclaw 包就能加载 index.js。
+		// load* 字面量必须留在本入口源码里：OpenClaw plugin loader 只扫入口文件识别
 		// `openclaw/plugin-sdk/*` 字符串字面量、命中后才把整张依赖图过 jiti 改写到自家 dist；
-		// 字面量留在子模块里 loader 看不到 → 整张图走原生 Node 解析必败（plugin 部署目录不带 openclaw 包）
+		// 字面量留在子模块里 loader 看不到 → 整张图走原生 Node 解析必败（plugin 部署目录不带 openclaw 包）。
+		// config-mutation 供 OAuth 写 provider 节点 baseUrl（hot-reload，零打断）
 		registerProviderAuthHandlers(api, {
 			loadSdk: () => import('openclaw/plugin-sdk/provider-auth'),
+			loadConfigMutation: () => import('openclaw/plugin-sdk/config-mutation'),
 		});
 
 		// 模型默认配置 RPC（coclaw.model.set / list）。三个 SDK 子入口的字面量

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.22.4",
+  "version": "0.23.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",

package/src/provider-auth/handlers.js

@@ -1,5 +1,6 @@
 /**
- * provider-auth handlers —— `coclaw.providerAuth.*` 三个 RPC 的纯函数实现
+ * provider-auth handlers —— `coclaw.providerAuth.*` RPC 的纯函数实现
+ * （setApiKey / list / remove + OAuth 的 loginOauth / cancelOauth）
  *
  * 设计要点（详见 docs/model-config-api.md § 2 + § 6）：
  * - 通过 dependency injection 拿 SDK / agentDir 解析器，便于单测；产线注入在 ./index.js
@@ -20,9 +21,25 @@
  * 与 plugin 既有 `respondError` / `respondInvalid`（在 plugins/openclaw/index.js）的关系：
  * 既有 helper 用 `INVALID_INPUT` / `INTERNAL_ERROR`，与本节 RPC 契约（`INVALID_ARGS` /
  * `IO_FAILED`）不一致——所以本模块自带局部 helper，避免改既有 helper 影响所有现存 RPC。
+ *
+ * OAuth（loginOauth / cancelOauth）补充：
+ * - **真·两阶段 res**（plugin respond 可多调，详见 docs/model-config-api.md § 2.3.2）：
+ *   phase-1 同步 respond accepted 帧（payload 必带 `status:'accepted'` 否则中继提前清路由），
+ *   phase-2 后台轮询出结果后用同一 reqId respond 终态帧
+ * - phase-1 之前的失败（region 非法 / 设备码请求失败）走单帧错误响应（INVALID_ARGS / IO_FAILED）
+ * - phase-2 失败用 payload.status 区分语义（error / timeout / cancelled），结构化 error.code
+ *   按语义给 OAUTH_FAILED / OAUTH_TIMEOUT / OAUTH_CANCELLED；写凭据 null / 写配置抛错走 IO_FAILED
+ * - 后台轮询 fire-and-forget，但 runOAuthBackground 内全程 try/catch 保证恰好 respond 一次且不外抛；
+ *   终态在 finally 清 registry
  */
 
+import { randomUUID } from 'node:crypto';
+import { PORTAL_PROVIDER_ID, CONFIG_DEFAULT_BASE_URL, VALID_REGIONS } from './minimax-oauth.js';
+import { getPortalModels } from './portal-model-catalog.js';
+import { remoteLog } from '../remote-log.js';
+
 const VALID_CRED_TYPES = new Set(['api_key', 'oauth', 'token']);
+const PORTAL_PROFILE_ID = `${PORTAL_PROVIDER_ID}:default`;
 
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_ARGS', message });
@@ -40,7 +57,7 @@ function isNonEmptyString(v) {
 }
 
 /**
- * 构造三个 handler。
+ * 构造 handler 集合。
  *
  * @param {object} opts
  * @param {object} opts.sdk - openclaw/plugin-sdk/provider-auth 命名空间（或 stub）
@@ -49,10 +66,24 @@ function isNonEmptyString(v) {
  * @param {Function} opts.sdk.ensureAuthProfileStore - 位置参数 (agentDir, options?)
  * @param {Function} opts.sdk.removeProviderAuthProfilesWithLock - async；返回 store（成功）/ null（锁/磁盘失败）
  * @param {Function} opts.sdk.formatApiKeyPreview - 遮蔽显示 helper
+ * @param {Function} [opts.sdk.mutateConfigFile] - async；OAuth 写 cfg（openclaw/plugin-sdk/config-mutation）
  * @param {Function} opts.resolveAgentDir - 返回 main agent 完整路径（含 /agent 子目录）
- * @returns {{ setApiKey: Function, list: Function, remove: Function }}
+ * @param {object} [opts.oauth] - createMiniMaxOAuth 实例（requestDeviceCode / pollUntilSettled）；OAuth handler 才用
+ * @param {object} [opts.registry] - oauth-registry（registerLogin / getLogin / removeLogin）
+ * @param {Function} [opts.genLoginId] - () → loginId，默认 randomUUID
+ * @param {Function} [opts.scheduleBackground] - (promise) → void，挂后台轮询；默认 fire-and-forget + .catch
+ * @param {Function} [opts.logRemote] - (text) → void，OAuth 终态诊断推送；默认模块级 remoteLog（测试注入 spy）
+ * @returns {{ setApiKey, list, remove, loginOauth, cancelOauth }}
  */
-export function buildProviderAuthHandlers({ sdk, resolveAgentDir }) {
+export function buildProviderAuthHandlers({
+	sdk,
+	resolveAgentDir,
+	oauth,
+	registry,
+	genLoginId = randomUUID,
+	scheduleBackground = (p) => { p.catch(() => {}); },
+	logRemote = remoteLog,
+}) {
 	// TODO: 将来若要支持"设默认模型 / 多账号顺序"等需要写 cfg 的操作，会撞上
 	// gateway 重启窗口的 UX 问题——参 docs/model-config-api.md § 3 / § 5（占位章节）。
 	// 当前三个 RPC 都只动 secret 不动 cfg，零重启。
@@ -144,7 +175,179 @@ export function buildProviderAuthHandlers({ sdk, resolveAgentDir }) {
 		}
 	}
 
-	return { setApiKey, list, remove };
+	// --- OAuth（MiniMax device-code，真·两阶段 res） ---
+
+	// 写凭据 + 写 cfg；恰好 respond 一次，不外抛（成功 ok / 失败 IO_FAILED 都在内部消化）
+	async function persistOAuthSuccess({ region, token, loginId, respond }) {
+		try {
+			const credential = {
+				type: 'oauth',
+				provider: PORTAL_PROVIDER_ID,
+				access: token.access,
+				refresh: token.refresh,
+				expires: token.expires,
+			};
+			const result = await sdk.upsertAuthProfileWithLock({
+				profileId: PORTAL_PROFILE_ID,
+				credential,
+				agentDir: resolveAgentDir(),
+			});
+			// 同 setApiKey：锁/磁盘失败时上游静默返回 null
+			if (result === null) {
+				respond(false, { status: 'error' }, {
+					code: 'IO_FAILED',
+					message: 'failed to write auth-profiles store',
+				});
+				logRemote(`providerAuth.oauth.io-failed loginId=${loginId} stage=credential`);
+				return;
+			}
+			// 写 provider 节点 baseUrl —— hot-reload 路径，零打断（afterWrite:auto，禁传 restart）。
+			// baseUrl 优先用服务端动态返回的 resourceUrl，缺省回落 cn/global 默认（带 /anthropic 后缀）
+			const baseUrl = token.resourceUrl || CONFIG_DEFAULT_BASE_URL[region];
+			// 写模型清单进 provider 节点：上游对 minimax-portal 用写死静态清单且第三方触发不到其
+			// catalog discovery，不写则 catalog 为空、模型不可用。直接取内置静态表（与上游对齐），
+			// 不再网络拉取——避免登录拉一次后静态过时 + 带进旧模型。后续升级新模型靠启动对账补。
+			// 详见 docs/model-config-api.md § 2.3
+			const models = getPortalModels(PORTAL_PROVIDER_ID);
+			await sdk.mutateConfigFile({
+				afterWrite: { mode: 'auto' },
+				mutate(draft) {
+					if (!draft.models || typeof draft.models !== 'object' || Array.isArray(draft.models)) {
+						draft.models = {};
+					}
+					const p = draft.models.providers;
+					if (!p || typeof p !== 'object' || Array.isArray(p)) {
+						draft.models.providers = {};
+					}
+					draft.models.providers[PORTAL_PROVIDER_ID] = {
+						baseUrl,
+						api: 'anthropic-messages',
+						authHeader: true,
+						models,
+					};
+				},
+			});
+			respond(true, { status: 'ok', profileId: PORTAL_PROFILE_ID });
+			logRemote(`providerAuth.oauth.ok loginId=${loginId} profileId=${PORTAL_PROFILE_ID} models=${models.length}`);
+		}
+		catch (err) {
+			respond(false, { status: 'error' }, {
+				code: 'IO_FAILED',
+				message: String(err?.message ?? err),
+			});
+			logRemote(`providerAuth.oauth.io-failed loginId=${loginId} stage=config msg=${String(err?.message ?? err)}`);
+		}
+	}
+
+	// 后台轮询循环 → 终态 respond（phase-2）。全程 try/catch，保证恰好 respond 一次且不外抛；
+	// finally 清 registry，无论成功/失败/取消
+	async function runOAuthBackground({ region, loginId, deviceCode, abortController, respond }) {
+		try {
+			const outcome = await oauth.pollUntilSettled({
+				region,
+				userCode: deviceCode.userCode,
+				verifier: deviceCode.verifier,
+				expiresAt: deviceCode.expiresAt,
+				interval: deviceCode.interval,
+				signal: abortController.signal,
+			});
+			if (outcome.status === 'cancelled') {
+				respond(false, { status: 'cancelled' }, {
+					code: 'OAUTH_CANCELLED',
+					message: 'MiniMax OAuth login was cancelled',
+				});
+				logRemote(`providerAuth.oauth.cancelled loginId=${loginId}`);
+				return;
+			}
+			if (outcome.status === 'timeout') {
+				respond(false, { status: 'timeout' }, {
+					code: 'OAUTH_TIMEOUT',
+					message: 'MiniMax OAuth timed out before authorization completed',
+				});
+				logRemote(`providerAuth.oauth.timeout loginId=${loginId}`);
+				return;
+			}
+			if (outcome.status === 'error') {
+				respond(false, { status: 'error' }, {
+					code: 'OAUTH_FAILED',
+					message: outcome.message || 'MiniMax OAuth authorization failed',
+				});
+				logRemote(`providerAuth.oauth.error loginId=${loginId} msg=${outcome.message || 'authorization failed'}`);
+				return;
+			}
+			// success：persistOAuthSuccess 内部恰好 respond 一次，不外抛
+			await persistOAuthSuccess({ region, token: outcome.token, loginId, respond });
+		}
+		catch (err) {
+			// 防御：pollUntilSettled 未预期抛错（多半是 /oauth/token 轮询期的网络/传输失败）。
+			// 终态帧回 error + OAUTH_FAILED——属轮询阶段失败，区别于写盘失败的 IO_FAILED（见 docs § 2.3.6）；
+			// 避免发起方永远挂着
+			respond(false, { status: 'error' }, {
+				code: 'OAUTH_FAILED',
+				message: String(err?.message ?? err),
+			});
+			logRemote(`providerAuth.oauth.error loginId=${loginId} stage=poll msg=${String(err?.message ?? err)}`);
+		}
+		finally {
+			registry.removeLogin(loginId);
+		}
+	}
+
+	async function loginOauth({ params, respond }) {
+		try {
+			const region = params?.region ?? 'cn';
+			if (!VALID_REGIONS.has(region)) {
+				respondInvalid(respond, 'region must be "cn" or "global"');
+				return;
+			}
+			let deviceCode;
+			try {
+				deviceCode = await oauth.requestDeviceCode({ region });
+			}
+			catch (err) {
+				// phase-1 之前失败（网络 / HTTP / 响应不全）：单帧错误响应
+				respondIoFailed(respond, err);
+				return;
+			}
+			const loginId = genLoginId();
+			const abortController = new AbortController();
+			// 先登记再 respond accepted：让紧随其后的 cancelOauth 一定能找到该 loginId
+			registry.registerLogin(loginId, { abortController });
+			respond(true, {
+				status: 'accepted',
+				loginId,
+				verificationUri: deviceCode.verificationUri,
+				userCode: deviceCode.userCode,
+				expiresAt: deviceCode.expiresAt,
+				interval: deviceCode.interval,
+			});
+			scheduleBackground(
+				runOAuthBackground({ region, loginId, deviceCode, abortController, respond }),
+			);
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	async function cancelOauth({ params, respond }) {
+		try {
+			const loginId = params?.loginId;
+			if (!isNonEmptyString(loginId)) {
+				respondInvalid(respond, 'loginId must be a non-empty string');
+				return;
+			}
+			const entry = registry.getLogin(loginId);
+			// 幂等：未知 loginId 也回 {}（可能已终态自清，或从来没有）
+			if (entry) entry.abortController.abort();
+			respond(true, {});
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	return { setApiKey, list, remove, loginOauth, cancelOauth };
 }
 
 /**

package/src/provider-auth/index.js

@@ -1,38 +1,54 @@
 /**
- * provider-auth 注册入口 —— 把三个 handler 接到 gateway。
+ * provider-auth 注册入口 —— 把 handler 接到 gateway。
+ * （coclaw.providerAuth.setApiKey / list / remove / loginOauth / cancelOauth）
  *
  * 设计：
  * - SDK 通过**懒加载 dynamic import** 拿，避免本模块在测试环境（无 openclaw npm 包）下
  *   一加载就崩。第一次 RPC 调用时才解析；后续调用复用缓存的 promise
+ * - OAuth 额外需要 `mutateConfigFile`（config-mutation 子入口）写 provider 节点 baseUrl；
+ *   PKCE / 表单编码器从 provider-auth 子入口拿（同一 barrel 已导出）
  * - `mainAgentDir` 走 claw-paths.js 统一入口，handler 每次调用都现拿（state-dir 由 runtime 决定）
  * - `opts` 主要给单测用：可注入 fake sdk / agentDir resolver / loader
+ *
+ * 生产路径上 loadSdk / loadConfigMutation 必须由入口（plugins/openclaw/index.js）注入字面量
+ * dynamic import —— OpenClaw plugin loader 只扫入口源码识别 `openclaw/plugin-sdk/*` 字面量并
+ * 触发 jiti 重写；藏在本子模块的字面量 loader 看不到 → 原生 Node 解析必败。
  */
 import { buildProviderAuthHandlers } from './handlers.js';
+import { createMiniMaxOAuth } from './minimax-oauth.js';
+import { registerLogin, getLogin, removeLogin } from './oauth-registry.js';
 import { mainAgentDir } from '../claw-paths.js';
 
 // link-UNSAFE：模块级 dedup 缓存。`--link` 模式下两实例各自 lazy-load 一次
 // SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
 // 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _sdkPromise;
+let _configMutationPromise;
 
-// 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入 loadSdk，
+// 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入，
 // 因为 OpenClaw plugin loader 只扫入口源码识别 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；
 // 字面量留在本子模块里 loader 看不到 → 原生 Node 解析必败。
-// 此处的 import 在生产环境永不被调用；保留只为测试在不注入 opts.loadSdk 时仍能拿到一个失败路径
+// 此处的 import 在生产环境永不被调用；保留只为测试在不注入 opts.load* 时仍能拿到一个失败路径
 function defaultLoadSdk() {
 	_sdkPromise ??= import('openclaw/plugin-sdk/provider-auth');
 	return _sdkPromise;
 }
 
+function defaultLoadConfigMutation() {
+	_configMutationPromise ??= import('openclaw/plugin-sdk/config-mutation');
+	return _configMutationPromise;
+}
+
 /**
  * 测试辅助：清掉懒加载 SDK 缓存。
  */
 export function __resetSdkCache() {
 	_sdkPromise = undefined;
+	_configMutationPromise = undefined;
 }
 
 /**
- * 在 gateway api 上注册 `coclaw.providerAuth.setApiKey` / `list` / `remove`。
+ * 在 gateway api 上注册 `coclaw.providerAuth.*`。
  *
  * 仅 `register(api)` 的 `if (api.registrationMode === 'full')` 分支调；
  * 其它 mode 注册副作用违规（参 plugins/openclaw/CLAUDE.md "Service / register 副作用边界"）。
@@ -41,17 +57,33 @@ export function __resetSdkCache() {
  * @param {object} [opts]
  * @param {Function} [opts.resolveAgentDir] - 覆盖 agentDir 解析（默认 mainAgentDir）
  * @param {Function} [opts.loadSdk] - 必传（生产由入口注入字面量 dynamic import）；缺省回退仅为测试兜底
+ * @param {Function} [opts.loadConfigMutation] - 必传（同上，OAuth 写 cfg 用）
+ * @param {object} [opts.registry] - 覆盖 oauth-registry（默认模块级单例）
  */
 export function registerProviderAuthHandlers(api, opts = {}) {
 	const resolveAgentDir = opts.resolveAgentDir ?? mainAgentDir;
 	const loadSdk = opts.loadSdk ?? defaultLoadSdk;
+	const loadConfigMutation = opts.loadConfigMutation ?? defaultLoadConfigMutation;
+	const registry = opts.registry ?? { registerLogin, getLogin, removeLogin };
 
 	let handlersPromise;
 	async function getHandlers() {
 		if (!handlersPromise) {
 			handlersPromise = (async () => {
-				const sdk = await loadSdk();
-				return buildProviderAuthHandlers({ sdk, resolveAgentDir });
+				const [providerAuthSdk, configMutation] = await Promise.all([
+					loadSdk(),
+					loadConfigMutation(),
+				]);
+				const sdk = {
+					...providerAuthSdk,
+					mutateConfigFile: configMutation.mutateConfigFile,
+				};
+				// PKCE / 表单编码器从 provider-auth barrel 取，注入给设备码流原语
+				const oauth = createMiniMaxOAuth({
+					generatePkce: providerAuthSdk.generatePkceVerifierChallenge,
+					toForm: providerAuthSdk.toFormUrlEncoded,
+				});
+				return buildProviderAuthHandlers({ sdk, resolveAgentDir, oauth, registry });
 			})();
 		}
 		return handlersPromise;
@@ -78,4 +110,6 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 	api.registerGatewayMethod('coclaw.providerAuth.setApiKey', wrap('setApiKey'));
 	api.registerGatewayMethod('coclaw.providerAuth.list', wrap('list'));
 	api.registerGatewayMethod('coclaw.providerAuth.remove', wrap('remove'));
+	api.registerGatewayMethod('coclaw.providerAuth.loginOauth', wrap('loginOauth'));
+	api.registerGatewayMethod('coclaw.providerAuth.cancelOauth', wrap('cancelOauth'));
 }

package/src/provider-auth/minimax-oauth.js

@@ -0,0 +1,268 @@
+/**
+ * minimax-oauth.js —— 复刻 MiniMax 设备码（device-code）OAuth 流
+ *
+ * 上游无给第三方插件用的"发起 OAuth 登录"入口（登录是 provider 私有 auth method，
+ * 由 CLI 交互式 prompter 驱动），所以 CoClaw 自己复刻这套标准设备码流。端点 / client_id /
+ * scope / 轮询语义全部抄 openclaw-repo/extensions/minimax/oauth.ts，**共用同一 client_id**
+ * （token 最终要被 OpenClaw 自带的 minimax bundled 扩展认）。详见 docs/model-config-api.md § 2.3。
+ *
+ * 设计要点：
+ * - **注入式依赖**：fetch / PKCE 生成器 / 表单编码器 / 随机数 / sleep / now 全部可注入，
+ *   单测免网、不误触 global fetch；生产由 ./index.js 用 SDK + 全局 fetch 装配
+ * - `requestDeviceCode`：PKCE → POST /oauth/code，拿 user_code / verification_uri /
+ *   expired_in（**绝对 ms epoch 截止时刻**，与上游 `while (Date.now() < expired_in)` 同义）/ interval
+ * - `pollUntilSettled`：单 async 循环轮询 POST /oauth/token，pending→sleep 再轮；
+ *   success / error / 到期 / abort 四个出口。超时取 expired_in 与本地 MAX_LOGIN_WINDOW 的较早者——
+ *   服务端给离谱大 expired_in 也由本地硬窗口兜住，循环必定自我终止（不会永久挂死/泄漏）
+ *
+ * 注意两个 baseUrl 不是一回事：
+ * - OAuth 端点 base（建 /oauth/code、/oauth/token）：cn `https://api.minimaxi.com`
+ * - provider 配置 baseUrl 兜底（写 cfg 的 models.providers）：cn `https://api.minimaxi.com/anthropic`
+ *   （登录成功优先用服务端动态返回的 resourceUrl，缺省才回落到这个）
+ */
+
+import { randomBytes, randomUUID } from 'node:crypto';
+
+const OAUTH_REGION_CONFIG = {
+	cn: { baseUrl: 'https://api.minimaxi.com', clientId: '78257093-7e40-4613-99e0-527b14b39113' },
+	global: { baseUrl: 'https://api.minimax.io', clientId: '78257093-7e40-4613-99e0-527b14b39113' },
+};
+
+const OAUTH_SCOPE = 'group_id profile model.completion';
+const OAUTH_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:user_code';
+
+// 轮询间隔下限：服务端可能给更小或不给，统一兜到 2s（与上游一致）
+const MIN_POLL_INTERVAL = 2000;
+
+// 轮询间隔上限：服务端给离谱大值（误用单位 / 恶意）时兜住——否则单轮 sleep 可跨越数天，
+// 或 >2^31ms 时 setTimeout 被钳成 1ms 变成热轮询。60s 远高于任何正常设备码轮询间隔
+// （典型 ≤10s），不会误伤合法值。导出供测试引用。
+export const MAX_POLL_INTERVAL = 60_000;
+
+// 登录轮询的独立硬窗口：不论服务端给的 expired_in 多离谱，轮询最多跑这么久就必定超时收尾。
+// 杜绝"有限但巨大的 expired_in 让 now()>=expiresAt 恒假 → 永不超时 + registry 泄漏 + 发起方挂死"
+// （round-1 的 expired_in 守卫只挡了非数/NaN/Infinity，挡不住有限巨大值）。1h 远高于任何正常
+// 设备码寿命（典型分钟级），合法登录到不了上限，只有离谱值才会被它兜住。导出供测试引用。
+export const MAX_LOGIN_WINDOW = 60 * 60 * 1000;
+
+// 把服务端给的轮询间隔规整到 [MIN, MAX] 的有限值；非数 / NaN / Infinity → MIN
+function clampInterval(raw) {
+	const n = (typeof raw === 'number' && Number.isFinite(raw)) ? raw : MIN_POLL_INTERVAL;
+	return Math.min(Math.max(n, MIN_POLL_INTERVAL), MAX_POLL_INTERVAL);
+}
+
+// 跑模型用的 provider 节点 id（"token plan" 无独立 id，凭据 + 配置都落这）
+export const PORTAL_PROVIDER_ID = 'minimax-portal';
+
+// 写 cfg 的 baseUrl 兜底（带 /anthropic 后缀，区别于 OAuth 端点 base）
+export const CONFIG_DEFAULT_BASE_URL = {
+	cn: 'https://api.minimaxi.com/anthropic',
+	global: 'https://api.minimax.io/anthropic',
+};
+
+export const VALID_REGIONS = new Set(['cn', 'global']);
+
+function getEndpoints(region) {
+	const cfg = OAUTH_REGION_CONFIG[region];
+	return {
+		codeEndpoint: `${cfg.baseUrl}/oauth/code`,
+		tokenEndpoint: `${cfg.baseUrl}/oauth/token`,
+		clientId: cfg.clientId,
+	};
+}
+
+/**
+ * 默认 sleep：到点或 abort 任一即 resolve。abort 时立即清 timer 提前返回，
+ * 让轮询循环回到顶部判定 signal.aborted。
+ * 导出供单测直接覆盖三条路径（已 abort / 正常到点 / sleep 中途 abort）。
+ */
+export function defaultSleep(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve();
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener?.('abort', onAbort);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener?.('abort', onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener?.('abort', onAbort, { once: true });
+	});
+}
+
+/**
+ * 解析 /oauth/token 响应（抄上游 pollOAuthToken 的容错语义）。
+ * @returns {{status:'pending'}|{status:'success',token:object}|{status:'error',message:string}}
+ */
+async function parseTokenResponse(response) {
+	const text = await response.text();
+	let payload;
+	if (text) {
+		try { payload = JSON.parse(text); }
+		catch { payload = undefined; }
+	}
+	if (!response.ok) {
+		return {
+			status: 'error',
+			message: (payload?.base_resp?.status_msg ?? text) || 'MiniMax OAuth failed to parse response.',
+		};
+	}
+	if (!payload) {
+		return { status: 'error', message: 'MiniMax OAuth failed to parse response.' };
+	}
+	if (payload.status === 'error') {
+		return { status: 'error', message: 'An error occurred. Please try again later' };
+	}
+	if (payload.status !== 'success') {
+		return { status: 'pending' };
+	}
+	// token 的 expired_in 是凭据自身有效期，下游 OpenClaw 刷新逻辑按数字时间戳比较；
+	// 非有限正数（字符串 / NaN / 0 / 负）一律视为不全，避免把脏值落进凭据（与设备码 expired_in 守卫对齐）
+	const tokenExpires = payload.expired_in;
+	if (
+		!payload.access_token
+		|| !payload.refresh_token
+		|| typeof tokenExpires !== 'number'
+		|| !Number.isFinite(tokenExpires)
+		|| tokenExpires <= 0
+	) {
+		return { status: 'error', message: 'MiniMax OAuth returned incomplete token payload.' };
+	}
+	return {
+		status: 'success',
+		token: {
+			access: payload.access_token,
+			refresh: payload.refresh_token,
+			expires: tokenExpires,
+			// resource_url 会成为 provider 配置的 baseUrl；非字符串丢弃，让 handler 回落区域默认
+			resourceUrl: typeof payload.resource_url === 'string' ? payload.resource_url : undefined,
+		},
+	};
+}
+
+/**
+ * 构造一套设备码流原语，依赖全部可注入。
+ *
+ * @param {object} deps
+ * @param {Function} deps.generatePkce - () → { verifier, challenge }（来自 SDK generatePkceVerifierChallenge）
+ * @param {Function} deps.toForm - (obj) → x-www-form-urlencoded 串（来自 SDK toFormUrlEncoded）
+ * @param {Function} [deps.fetchImpl] - fetch 实现，默认 globalThis.fetch
+ * @param {Function} [deps.randomState] - () → state 串，默认 crypto 16 字节 base64url
+ * @param {Function} [deps.randomRequestId] - () → x-request-id，默认 randomUUID
+ * @param {Function} [deps.sleep] - (ms, signal) → Promise，默认到点/abort resolve
+ * @param {Function} [deps.now] - () → ms epoch，默认 Date.now
+ * @returns {{ requestDeviceCode: Function, pollUntilSettled: Function }}
+ */
+export function createMiniMaxOAuth(deps) {
+	const {
+		generatePkce,
+		toForm,
+		fetchImpl = globalThis.fetch,
+		randomState = () => randomBytes(16).toString('base64url'),
+		randomRequestId = () => randomUUID(),
+		sleep = defaultSleep,
+		now = () => Date.now(),
+	} = deps;
+
+	/**
+	 * 发起设备码请求。
+	 * @param {object} args
+	 * @param {string} args.region - 'cn' | 'global'
+	 * @returns {Promise<{verifier:string, userCode:string, verificationUri:string, expiresAt:number, interval:number}>}
+	 */
+	async function requestDeviceCode({ region }) {
+		const { verifier, challenge } = generatePkce();
+		const state = randomState();
+		const endpoints = getEndpoints(region);
+		const response = await fetchImpl(endpoints.codeEndpoint, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/x-www-form-urlencoded',
+				Accept: 'application/json',
+				'x-request-id': randomRequestId(),
+			},
+			body: toForm({
+				response_type: 'code',
+				client_id: endpoints.clientId,
+				scope: OAUTH_SCOPE,
+				code_challenge: challenge,
+				code_challenge_method: 'S256',
+				state,
+			}),
+		});
+		if (!response.ok) {
+			const text = await response.text();
+			throw new Error(`MiniMax OAuth authorization failed: ${text || response.statusText}`);
+		}
+		const payload = await response.json();
+		if (!payload?.user_code || !payload?.verification_uri) {
+			throw new Error(payload?.error ?? 'MiniMax OAuth authorization returned an incomplete payload.');
+		}
+		// expired_in 是绝对 ms epoch 截止时刻；缺失/非数会让轮询里 now()>=expiresAt 恒为 false →
+		// 永不超时、phase-2 永不 fire、registry 泄漏。fail-closed：缺则抛，走 phase-1 之前的单帧错误
+		// （镜像上游 `while (Date.now() < expireTimeMs)` 在 expired_in 非数时的隐式立即终止）
+		if (typeof payload.expired_in !== 'number' || !Number.isFinite(payload.expired_in)) {
+			throw new Error('MiniMax OAuth authorization returned an invalid expiry.');
+		}
+		if (payload.state !== state) {
+			throw new Error('MiniMax OAuth state mismatch: possible CSRF or session corruption.');
+		}
+		return {
+			verifier,
+			userCode: payload.user_code,
+			verificationUri: payload.verification_uri,
+			expiresAt: payload.expired_in,
+			// 规整到 [MIN, MAX] 有限值：服务端给非数会变 NaN 透到 UI，给离谱大值会拖垮轮询
+			interval: clampInterval(payload.interval),
+		};
+	}
+
+	/**
+	 * 单 async 轮询循环，直到出终态。四个出口：success / error / timeout / cancelled。
+	 * @param {object} args
+	 * @param {string} args.region
+	 * @param {string} args.userCode
+	 * @param {string} args.verifier
+	 * @param {number} args.expiresAt - 绝对 ms epoch 截止时刻
+	 * @param {number} args.interval - 轮询间隔 ms（已兜底 ≥2s）
+	 * @param {AbortSignal} [args.signal]
+	 * @returns {Promise<{status:'success',token:object}|{status:'error',message:string}|{status:'timeout'}|{status:'cancelled'}>}
+	 */
+	async function pollUntilSettled({ region, userCode, verifier, expiresAt, interval, signal }) {
+		const endpoints = getEndpoints(region);
+		const pollInterval = clampInterval(interval);
+		// 独立硬上限：真实截止取服务端 expiresAt 与本地 now()+MAX_LOGIN_WINDOW 的较早者。
+		// 服务端给离谱大 expiresAt 时由本地窗口兜住，循环必定自我终止（不再永久挂死/泄漏）。
+		const deadline = Math.min(expiresAt, now() + MAX_LOGIN_WINDOW);
+		for (;;) {
+			if (signal?.aborted) return { status: 'cancelled' };
+			if (now() >= deadline) return { status: 'timeout' };
+			const response = await fetchImpl(endpoints.tokenEndpoint, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/x-www-form-urlencoded',
+					Accept: 'application/json',
+				},
+				body: toForm({
+					grant_type: OAUTH_GRANT_TYPE,
+					client_id: endpoints.clientId,
+					user_code: userCode,
+					code_verifier: verifier,
+				}),
+			});
+			const result = await parseTokenResponse(response);
+			if (result.status === 'success') return { status: 'success', token: result.token };
+			if (result.status === 'error') return { status: 'error', message: result.message };
+			// pending：等一个间隔再轮（abort 会让 sleep 提前返回，回顶判 aborted）。
+			// pollInterval 已被 clampInterval 兜在 ≤MAX_POLL_INTERVAL，故循环必在 deadline+一个间隔内终止
+			await sleep(pollInterval, signal);
+		}
+	}
+
+	return { requestDeviceCode, pollUntilSettled };
+}

package/src/provider-auth/oauth-registry.js

@@ -0,0 +1,46 @@
+/**
+ * oauth-registry.js —— 进行中的 OAuth 登录的模块级登记表
+ *
+ * `loginOauth` 启动后台轮询时把 loginId → { abortController } 登记进来；
+ * `cancelOauth` 按 loginId 查到后 abort()；轮询循环终态时自行移除。
+ *
+ * link-safety：登录登记 / 取消 / 移除都只在 RPC handler 路径触发（由同一次
+ * registerProviderAuthHandlers 注册的 loginOauth + cancelOauth 共享同一模块实例），
+ * 不被任何 hook 回调访问——所以这个模块级单例对本用法是安全的。
+ * 详见 docs/module-boundaries.md 的双实例陷阱说明（hook ↔ RPC 才会分叉）。
+ */
+
+const __registry = new Map();
+
+/**
+ * 登记一个进行中的登录。
+ * @param {string} loginId
+ * @param {{ abortController: AbortController }} entry
+ */
+export function registerLogin(loginId, entry) {
+	__registry.set(loginId, entry);
+}
+
+/**
+ * 查登记项；未知 loginId 返回 undefined。
+ * @param {string} loginId
+ * @returns {{ abortController: AbortController } | undefined}
+ */
+export function getLogin(loginId) {
+	return __registry.get(loginId);
+}
+
+/**
+ * 移除登记项（终态清理）。
+ * @param {string} loginId
+ */
+export function removeLogin(loginId) {
+	__registry.delete(loginId);
+}
+
+/**
+ * 测试辅助：清空登记表。
+ */
+export function __resetRegistry() {
+	__registry.clear();
+}

package/src/provider-auth/portal-model-catalog.js

@@ -0,0 +1,62 @@
+/**
+ * portal-model-catalog.js —— OAuth/token-plan provider 的静态模型清单表
+ *
+ * 背景：上游对 minimax-portal 这类 provider 的模型走**写死的静态清单**，且第三方插件触发不到
+ * 它的 catalog discovery——实测 `models.list view:'all'` 也只为默认 provider + 声明了
+ * discovery-source 的插件跑发现，扫码 provider 永远是空。所以不把清单写进 OpenClaw 配置，
+ * catalog 就为空：UI 选不到、agent 用不了。CoClaw 在这里维护一份与上游对齐的静态表，
+ * 登录成功 + gateway 启动对账时写进配置。详见 docs/model-config-api.md § 2.3。
+ *
+ * 维护约定：
+ * - MiniMax 升代时**手动**更新本表（与上游 bundled `MINIMAX_TEXT_MODEL_ORDER` 对齐——
+ *   上游那份也是手填手维护的源码常量，本表负担与之持平）。
+ * - 将来再遇到同类"扫码/token-plan 但 catalog 不可达"的 provider，在此加一行即可。
+ * - `id` / `name` 必填非空（OpenClaw config model 条目 zod schema 要求）；id 用 provider
+ *   返回的 proper-case，name 用展示名。
+ * - 只维护**最必须的运行元数据**：`reasoning`（是否推理模型——缺省会被当成 false，导致推理
+ *   模型被按普通模型处理、思考模式出错）、`contextWindow`、`maxTokens`。**不写 `cost`**：
+ *   portal 走 token plan、不按量计费，价格无意义；`input` 也不写（系统默认即 `['text']`）。
+ *   这几个值与上游 `model-definitions.ts`（DEFAULT_MINIMAX_CONTEXT_WINDOW=204800 /
+ *   DEFAULT_MINIMAX_MAX_TOKENS=131072）+ `provider-models.ts`（reasoning 标记）对齐。
+ */
+
+export const PORTAL_MODEL_CATALOG = {
+	// 与 openclaw-repo/extensions/minimax/ 的 provider-models.ts(reasoning) +
+	// model-definitions.ts(contextWindow/maxTokens) 对齐
+	'minimax-portal': [
+		{ id: 'MiniMax-M2.7', name: 'MiniMax M2.7', reasoning: true, contextWindow: 204800, maxTokens: 131072 },
+		{ id: 'MiniMax-M2.7-highspeed', name: 'MiniMax M2.7 Highspeed', reasoning: true, contextWindow: 204800, maxTokens: 131072 },
+	],
+};
+
+/**
+ * 取某 provider 的静态清单。返回**深拷贝**，避免调用方改到共享常量。
+ * 未知 provider → 空数组。条目字段为扁平基本类型，`{ ...m }` 即为完整深拷贝。
+ *
+ * @param {string} providerId
+ * @returns {{id:string, name:string, reasoning?:boolean, contextWindow?:number, maxTokens?:number}[]}
+ */
+export function getPortalModels(providerId) {
+	const list = PORTAL_MODEL_CATALOG[providerId];
+	if (!Array.isArray(list)) return [];
+	return list.map((m) => ({ ...m }));
+}
+
+/**
+ * 判断配置里现有清单是否已**覆盖**目标的全部模型——**只按 id**，顺序无关。
+ * 启动对账靠它决定"要不要写"：目标里每个 id 都已在现有清单出现 → 视为已同步、一字不写。
+ *
+ * 只按 id（不连 name / 其它字段）是有意为之：模型能不能被选、被用由 id 决定。这样别的来源
+ * （如官方 MiniMax 插件）往同一 provider 写一份更大的清单（只要含我们的 id）时，配置成我们的
+ * 超集也判已覆盖、不去覆盖它——避免每次重启都把它改回我们这份、和它来回打架。name / 参数即便
+ * 与我们不同也不触发写：只保证我们的 id 在，别人的多余条目随它去。
+ *
+ * @param {unknown} current - 配置里现有 models（可能缺失/非数组/脏条目）
+ * @param {{id:string}[]} target - 目标清单（内置表，id 必为非空字符串）
+ * @returns {boolean} target 的每个 id 都在 current 出现 → true（空 target 天然被覆盖）
+ */
+export function portalModelsCoveredById(current, target) {
+	if (!Array.isArray(target)) return false;
+	const have = new Set(Array.isArray(current) ? current.map((m) => m?.id) : []);
+	return target.every((m) => have.has(m?.id));
+}

package/src/provider-auth/reconcile.js

@@ -0,0 +1,54 @@
+/**
+ * reconcile.js —— gateway 启动时把已绑定 provider 的配置模型清单对账成内置表
+ *
+ * 为什么需要：模型清单只在"登录成功那一刻"写一次。插件升级后表里补了新 MiniMax 模型，
+ * 但老用户早已绑定、不会重新扫码——配置里还是旧清单，新模型永远不出现。启动对账补上这条：
+ * 升级装新版必然重启 gateway，重启时拿表跟配置比，不一致就刷新，用户零操作。
+ *
+ * **关键防御（一致就一字不写）**：mutateConfigFile 是无条件写盘的（克隆→改→写，不做 diff 短路）。
+ * 而"写配置"将来万一被上游改成触发 gateway 重启，无脑每次启动都写就会反复重启。所以这里
+ * **先比对、只在真不一致时才写**——即便上游哪天那么干，也只会重启一次（写完即一致，下次启动
+ * 判定 in-sync 不写、不重启）。
+ */
+
+import { PORTAL_PROVIDER_ID } from './minimax-oauth.js';
+import { getPortalModels, portalModelsCoveredById } from './portal-model-catalog.js';
+
+/**
+ * 对账某个 portal-style provider 的配置模型清单。
+ *
+ * @param {object} opts
+ * @param {Function} opts.getConfig - () → 当前 cfg 快照（getClawConfig）；null/缺时跳过
+ * @param {Function} opts.mutateConfigFile - openclaw/plugin-sdk/config-mutation 的写盘入口
+ * @param {string} [opts.providerId] - 默认 minimax-portal
+ * @returns {Promise<{changed:boolean, reason:string}>} reason: no-config|not-bound|no-catalog|in-sync|updated
+ */
+export async function reconcilePortalModels({ getConfig, mutateConfigFile, providerId = PORTAL_PROVIDER_ID }) {
+	const cfg = getConfig?.();
+	// runtime 未注入 / config 不可读：跳过，下次启动再对
+	if (!cfg || typeof cfg !== 'object') return { changed: false, reason: 'no-config' };
+	const node = cfg.models?.providers?.[providerId];
+	// 未绑定（无 provider 节点）→ 不碰。登录成功时已写过节点 + 清单，绑定后才谈得上对账
+	if (!node || typeof node !== 'object' || Array.isArray(node)) return { changed: false, reason: 'not-bound' };
+	const target = getPortalModels(providerId);
+	// 表里没这个 provider（理论不该发生）→ 不动用户已有清单
+	if (target.length === 0) return { changed: false, reason: 'no-catalog' };
+	// 只按 id 判"已覆盖"：目标里每个 model id 都已在配置现有清单出现 → 视为已同步、零写入。
+	// 比"全等"宽容——配置是我们的超集（别的来源，如官方 MiniMax 插件，多写了几个模型）时也判已覆盖、
+	// 不去动它，避免和它来回覆盖、反复重启。仅当配置缺了我们某个 id（升级新增模型 / 老配置不全）才写。
+	// 顺带说清读/写不对称：getConfig 读「解析后」配置（config.current()），mutateConfigFile 默认写
+	// 「源」配置。即便上游将来在解析期给第三方 portal 注入额外模型，那也只是让配置成超集、我们的 id 仍在
+	// → 判已覆盖 → 不写，不会触发"永远判不一致、每次启动都写"的循环。
+	if (portalModelsCoveredById(node.models, target)) return { changed: false, reason: 'in-sync' };
+
+	await mutateConfigFile({
+		afterWrite: { mode: 'auto' },
+		mutate(draft) {
+			const p = draft.models?.providers?.[providerId];
+			// 读后到写之间被并发删（极少）→ 不无中生有重建节点，只刷新已存在的
+			if (!p || typeof p !== 'object' || Array.isArray(p)) return;
+			p.models = getPortalModels(providerId);
+		},
+	});
+	return { changed: true, reason: 'updated' };
+}