@coclaw/openclaw-coclaw 0.22.3 → 0.23.0

package/index.js

@@ -18,7 +18,9 @@ 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';
 
 import { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
 export { getPluginVersion, __resetPluginVersion };
@@ -32,6 +34,15 @@ export function awaitPluginInit() {
 	return __pluginInitDone;
 }
 
+// abort-threw 远端日志节流：gateway 进程活动期间最多上报一次，避免上游 handle.abort
+// 持续抛错时 500ms tick 重试把 remote-log 刷爆。logger.info 已对 abort-threw 静默
+// （见 coclaw.agent.abort handler 注释），但完全失去诊断信号会让运维瞎子，故保留首条。
+let __abortThrewReported = false;
+
+export function __resetAbortThrewReported() {
+	__abortThrewReported = false;
+}
+
 // 侧门注册表观测：patch OpenClaw embeddedRunState.activeRuns 的 set/delete，
 // 用于跟踪 sessionId 何时注册/注销（agent 取消流程实际读取的就是这张表）。
 // OpenClaw 侧门形状变化时（缺失 / 抛异常），通过 remoteLog 上报为升级契约变更的早期信号。
@@ -70,8 +81,9 @@ function patchMapLogging(map, label, logger) {
 	}
 	const origSet = map.set.bind(map);
 	const origDel = map.delete.bind(map);
-	// log 行包 try/catch 兜底：上游若把 Map 换成有 throwing getter（如 Proxy）的对象，
-	// 不能让本插件的诊断 log 把 OpenClaw 内部 set/delete 流程带崩
+	// AGENTS.md §"日志器"一般规则是"调用点不要再包 try/catch"，此处特例：safeLog/safeSize
+	// 是绑到 OpenClaw 内部 Map.set/delete 路径上的诊断仪器，上游若把 Map 换成 throwing-getter
+	// Proxy 或 logger 自身异常都不能把宿主的 set/delete 流程带崩，故保留 swallow 兜底
 	const safeLog = (msg) => {
 		try { logger?.info?.(msg); } catch { /* swallow — diag log 不得影响主流程 */ }
 	};
@@ -192,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。
@@ -692,8 +713,8 @@ const plugin = {
 				const runDuration = typeof params?.runDuration === 'number' ? params.runDuration : undefined;
 				const abortDuration = typeof params?.abortDuration === 'number' ? params.abortDuration : undefined;
 				const result = decideCancelResponse(abortResult, { runDuration, abortDuration });
-				// not-found 是 UI 重试期常态（注册空窗），不打日志避免噪音；其余分支保留 info
-				if (result.reason !== 'not-found') {
+				// not-found（注册空窗）与 abort-threw（上游 handle.abort 持续抛）都是 UI 500ms tick 重试期常态，跳过 info 日志避免洪水；其余分支保留 info
+				if (result.reason !== 'not-found' && result.reason !== 'abort-threw') {
 					logger.info?.(`[coclaw.agent.abort] result sessionId=${sessionId} ok=${result.ok}${result.reason ? ` reason=${result.reason}` : ''}${result.error ? ` error=${result.error}` : ''}`);
 				}
 				if (result.ok) {
@@ -707,6 +728,12 @@ const plugin = {
 					// 启发升格：双闸均达阈值，把 not-found 升格为 gone，让 UI 主动 settleByCancel
 					remoteLog(`abort.gone sid=${sessionId} runDur=${runDuration} abortDur=${abortDuration}`);
 				}
+				else if (result.reason === 'abort-threw' && !__abortThrewReported) {
+					// 一次性：上游 handle.abort 首次抛错时上报，让运维知道这个 gateway 实例发生过；
+					// 后续 tick 重试不再上报，避免被 UI 500ms 拍频刷爆远端日志
+					__abortThrewReported = true;
+					remoteLog(`abort.threw sid=${sessionId} error=${result.error || ''}`);
+				}
 				respond(true, result);
 			}
 			catch (err) {
@@ -729,7 +756,7 @@ const plugin = {
 
 		const fileHandler = createFileHandler({
 			resolveWorkspace: (agentId) => {
-				const cfg = api.runtime?.config?.loadConfig();
+				const cfg = getClawConfig();
 				const dir = api.runtime?.agent?.resolveAgentWorkspaceDir(cfg, agentId);
 				if (!dir) {
 					const err = new Error('Cannot resolve workspace: runtime not available');
@@ -773,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 子入口的字面量
@@ -811,8 +840,13 @@ const plugin = {
 
 				try {
 					if (action === 'bind') {
+						// 先校验非空 code，避免无效输入触发 doBind 内的 cancelActiveEnroll 副作用
+						const code = positionals[0];
+						if (typeof code !== 'string' || code.length === 0) {
+							return { text: 'Error: binding code is required' };
+						}
 						const result = await doBind({
-							code: positionals[0],
+							code,
 							serverUrl: options.server,
 						});
 						return { text: bindOk(result) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",
@@ -50,7 +50,7 @@
     "typecheck": "echo \"No typecheck configured yet (coclaw openclaw plugin)\"",
     "check": "pnpm lint && pnpm typecheck",
     "test:plugin": "node --test src/plugin-mode.test.js",
-    "test": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov bash -c 'for f in src/**/*.test.js src/*.test.js index.test.js; do node --test \"$f\" || exit 1; done'",
+    "test": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov bash -c 'node --test src/**/*.test.js src/*.test.js index.test.js'",
     "e2e": "node --test --test-concurrency=1 e2e/*.e2e.spec.js",
     "verify": "pnpm check && pnpm test",
     "link": "bash ./scripts/link.sh",

package/src/auto-upgrade/updater.js

@@ -191,7 +191,11 @@ function loadInstallRecordFromLegacyConfig(pluginId) {
 		const config = getClawConfig();
 		return config?.plugins?.installs?.[pluginId] ?? null;
 	}
-	catch {
+	catch (err) {
+		// 与同函数其他 catch 风格对齐：旧版账本读取异常也外推诊断信号，
+		// 否则下游只能看到笼统的 "Skipping: not an npm-installed plugin"，无定位线索
+		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+		remoteLog(`upgrade.legacy-config-read-failed msg=${err?.message ?? String(err)}`);
 		return null;
 	}
 }

package/src/chat-history-manager/manager.js

@@ -39,6 +39,8 @@ export function classifyChatHistorySessionKey(sessionKey) {
 	//   由 cron 守卫挡住即可，避免与 IM per-account DM accountId="cron"/"subagent" 形态冲突
 	//   （accountId 仅按 [a-z0-9_-]{1,64} 校验，"cron"/"subagent" 都是合法账户名）。
 	if (parts[2] === 'explicit') return { ok: false, reason: 'explicit' };
+	// agent:<id>:cron:<jobId>:subagent:<uuid> 形态命中 cron 守卫返回 reason='cron'，
+	// 丢一层嵌套语义；上报信号目前无下游按 reason 细分计数/告警，留作识别到才说
 	if (parts[2] === 'cron') return { ok: false, reason: 'cron' };
 	if (parts[2] === 'subagent') return { ok: false, reason: 'subagent' };
 	return { ok: true, reason: null };
@@ -193,6 +195,7 @@ export class ChatHistoryManager {
 			for (let i = 1; i < list.length; i++) {
 				const item = list[i];
 				if (!item || typeof item !== 'object' || item.archivedAt) continue;
+				// 复用 archivedAt 写补登时间；事后与正常归档无法区分，线下分析靠下方 chat-history.sanitize-coerce 上报信号
 				item.archivedAt = now;
 				this.__logger.warn?.(
 					`[coclaw] chat-history sanitize: non-head unarchived entry coerced sessionKey=${sessionKey} sid=${item.sessionId}`,
@@ -352,6 +355,8 @@ export class ChatHistoryManager {
 		} catch (err) {
 			this.__reportLoadError(filePath, err, '__reloadFromDisk');
 		}
+		// 读盘失败 + cache 已热身 → 保留旧 cache（best-effort 容忍）。下次写盘会把旧数据回灌磁盘自愈；
+		// 但若长期无新写入，磁盘上的损坏内容不会被主动修复
 		if (!this.__cache.has(agentId)) {
 			this.__cache.set(agentId, emptyStore());
 		}

package/src/file-manager/handler.js

@@ -643,6 +643,17 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		let wsBackpressureCount = 0;
 		let wsError = false;
 		let finishing = false;
+		// 一次性 cleanup attach 守卫：dc.onerror 后 pion 通常紧跟 dc.onclose，
+		// 两条 cleanup 路径若都向 ws 挂 'close' 监听会重复 safeUnlink。
+		// 用 flag 而不是 wsError 守卫，是为了不破坏 SIZE_EXCEEDED 等"先同步 unlink、
+		// 再触发 dc.close → dc.onclose"路径：那条路径同样设 wsError=true 但**没**
+		// attach 过，仍需 dc.onclose 兜底 attach（fopen 完成后才删到真文件）
+		let cleanupAttached = false;
+		function attachTmpCleanupOnce() {
+			if (cleanupAttached) return;
+			cleanupAttached = true;
+			ws.on('close', () => safeUnlink(tmpPath));
+		}
 
 		// --- 受控写入：中间缓冲 + drain 循环 ---
 		const pendingQueue = [];
@@ -672,9 +683,11 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				draining = false;
 				pendingQueue.length = 0;
 				log.warn?.(`[coclaw/file] drainLoop write error: ${err.message}`);
+				// 走安全网而非同步 safeUnlink：fopen 未完成时 sync unlink 扑空被吞，
+				// fopen 后留孤儿。attach 在 destroy 之前确保 'close' emit 时 listener 已就位
+				attachTmpCleanupOnce();
 				ws.destroy();
 				if (!dcClosed) sendError(dc, 'WRITE_FAILED', err.message);
-				safeUnlink(tmpPath);
 				const elapsed = Date.now() - startTime;
 				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=drain-write-error err=${err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
 				return;
@@ -692,8 +705,17 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		function finishUpload() {
 			if (finishing) return;
 			finishing = true;
-			ws.end(async () => {
+			ws.end(async (err) => {
 				const elapsed = Date.now() - startTime;
+				// ws 在 'finish' 之前被 destroy 时，Node Writable 会用 err 调 pending end cb
+				//（destroy(e) 用 e；destroy() 用 ERR_STREAM_DESTROYED）。任何 ws 中途夭折的
+				// 产线路径都已经在 ws.on('error') / dc.onclose / dc.onerror / drainLoop catch
+				// 里 attach 过清理 + 打过更具体的 fail log；这里只需兜底 attach 一次（idempotent）
+				// 防御未来路径漏挂，并跳过 rename / size 校验 / 成功响应
+				if (err) {
+					attachTmpCleanupOnce();
+					return;
+				}
 				if (dcClosed) {
 					safeUnlink(tmpPath);
 					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed-before-flush received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
@@ -795,15 +817,20 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			if (doneReceived) {
 				// done 已收到但 drain 未完成 — finishUpload 中会检测 dcClosed 并清理 tmp
 				if (!finishing) finishUpload();
-			} else {
-				// 等 ws 关闭后再 unlink——fopen 未完成时直接 safeUnlink 会扑空被吞，
-				// 随后 fopen 完成创建文件却没人清，留下孤儿 tmp
-				ws.on('close', () => safeUnlink(tmpPath));
-				ws.destroy();
-				const elapsed = Date.now() - startTime;
-				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
-				log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+				return;
 			}
+			// 等 ws 关闭后再 unlink——fopen 未完成时直接 safeUnlink 会扑空被吞，
+			// 随后 fopen 完成创建文件却没人清，留下孤儿 tmp。flag 守卫保证 dc.onerror
+			// 已 attach 过时不会重挂第二个 listener
+			attachTmpCleanupOnce();
+			ws.destroy();
+			// dc.onerror 已打过 reason=dc-error fail 日志 → 跳过 reason=dc-closed
+			// 避免双触发时 fail 日志重复（SIZE_EXCEEDED 路径打的是 reason=size-exceeded
+			// 的 reject 日志，不在此 fail 命名空间，不受影响）
+			if (wsError) return;
+			const elapsed = Date.now() - startTime;
+			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+			log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 		};
 
 		// pion 异步 send 错误经此回调上报；触发已有清理路径
@@ -813,7 +840,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			draining = false;
 			pendingQueue.length = 0;
 			// 同上：等 ws 关闭后再 unlink，避开 fopen-vs-unlink race
-			ws.on('close', () => safeUnlink(tmpPath));
+			attachTmpCleanupOnce();
 			ws.destroy();
 			const elapsed = Date.now() - startTime;
 			/* c8 ignore next -- ?? fallback for non-Error throw */
@@ -832,11 +859,16 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			draining = false;
 			pendingQueue.length = 0;
 			log.warn?.(`[coclaw/file] write stream error: ${err.message}`);
+			// 安全网先装：sendError 会同步 dc.close → dc.onclose，doneReceived=true 且
+			// !finishing 时会同步重入 finishUpload → ws.end，整条 sync 链全跑完才回到这里。
+			// 与 drainLoop catch 顺序对齐。显式 ws.destroy() 不依赖 Node autoDestroy
+			// （注入的非标准 stream 可能不触发）触发 ws 关闭流程；listener 在 'close' emit 时 fire
+			attachTmpCleanupOnce();
+			ws.destroy();
 			if (!dcClosed) {
 				const code = err.code === 'ENOSPC' ? 'DISK_FULL' : 'WRITE_FAILED';
 				sendError(dc, code, err.message);
 			}
-			safeUnlink(tmpPath);
 			const elapsed = Date.now() - startTime;
 			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=write-error err=${err.code || err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
 			log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=write-error received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms err=${err.code || err.message}`);
@@ -904,7 +936,13 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	}
 
 	function safeUnlink(filePath) {
-		_unlink(filePath).catch(() => {});
+		// ENOENT 静默：tmp 可能尚未创建（fopen 未完成）或已被另一路径删过，均属预期。
+		// 其余错（EACCES / EBUSY / EIO）若完全无声会让孤儿 tmp 悄悄积累——warn 一下，
+		// 仍保留 fire-and-forget 语义；scheduleTmpCleanup 仍是最终兜底
+		_unlink(filePath).catch((err) => {
+			if (err?.code === 'ENOENT') return;
+			log.warn?.(`[coclaw/file] safeUnlink failed: ${filePath} ${err?.code || err?.message}`);
+		});
 	}
 
 	return {

package/src/model-default/handlers.js

@@ -105,11 +105,13 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 				respondInvalid(respond, 'primary is required');
 				return;
 			}
-			const primary = params.primary;
-			if (primary !== null && typeof primary !== 'string') {
+			const rawPrimary = params.primary;
+			if (rawPrimary !== null && typeof rawPrimary !== 'string') {
 				respondInvalid(respond, 'primary must be a string or null');
 				return;
 			}
+			// 复制粘贴常带前后空白；trim 后再做形态/凭据/catalog 校验，并按 trim 后的值落盘
+			const primary = rawPrimary === null ? null : rawPrimary.trim();
 			if (primary !== null && primary.length === 0) {
 				respondInvalid(respond, 'primary must be a non-empty string or null');
 				return;

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' };
+}

package/src/realtime-bridge.js

@@ -112,6 +112,7 @@ export function defaultResolveGatewayAuthToken() {
 		}
 	}
 	catch (err) {
+		// register 早期 / runtime 未注入完成时也可能被触达，注入 logger 此时未必可用，用 console.warn 兜底
 		console.warn?.(`[coclaw] resolve gateway auth token failed: ${String(err?.message ?? err)}`);
 	}
 	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
@@ -584,12 +585,11 @@ export class RealtimeBridge {
 			const hostName = getHostName();
 			const pluginVersion = await getPluginVersion();
 			const agentModels = await this.__collectAgentModels();
-			broadcastPluginEvent('coclaw.info.updated', {
-				name,
-				hostName,
-				pluginVersion,
-				agentModels,
-			});
+			// 采集失败时漏报 agentModels（而非显式 null）：server / UI 走 patch 语义
+			// 保留旧值，避免 admin 仪表盘瞬时清空（OpenClaw manifest cache 偶发卡顿时易触发）
+			const payload = { name, hostName, pluginVersion };
+			if (agentModels !== null) payload.agentModels = agentModels;
+			broadcastPluginEvent('coclaw.info.updated', payload);
 		}
 		catch (err) {
 			/* c8 ignore next 2 -- 防御性兜底 */
@@ -603,7 +603,9 @@ export class RealtimeBridge {
 	 */
 	async __collectAgentModels() {
 		try {
-			const result = await this.__gatewayRpc('agents.list', {}, { timeoutMs: 3000 });
+			// OpenClaw agents.list 走 manifest cache 加载链路，偶发 cache mismatch 时 ~10s 才回
+			// （issue #80697）；timeout 给到 30s 让本地 cache miss 有恢复窗口
+			const result = await this.__gatewayRpc('agents.list', {}, { timeoutMs: 30000 });
 			if (result?.ok !== true) return null;
 			const agents = result?.response?.payload?.agents;
 			if (!Array.isArray(agents)) return null;
@@ -1128,9 +1130,11 @@ export class RealtimeBridge {
 			this.logger.warn?.(
 				`[coclaw] dc gateway req invalid: id=${typeof payload?.id} method=${typeof payload?.method}`,
 			);
-			// 有合法 id 时回 INVALID_REQUEST 让发起方尽快放弃等待；id 不合法时只能 drop
+			// 有合法 id 时回 INVALID_REQUEST 让发起方尽快放弃等待；id 不合法时只能 drop。
+			// 单播：connId 来自每条连接的闭包必非空，只发给发出乱码请求的连接，
+			// 不打扰其他客户端（旁边 OFFLINE / SEND_FAILED 分支属系统级公告保留广播语义）
 			if (hasValidId) {
-				this.webrtcPeer?.broadcast({
+				await this.webrtcPeer?.sendTo(connId, {
 					type: 'res',
 					id: payload.id,
 					ok: false,
@@ -1604,6 +1608,8 @@ export class RealtimeBridge {
 		});
 		this.__runEventRoutes.init();
 		// 外线（plugin↔远端 server）先发起 connectIfNeeded：仅创建 WebSocket 即返回，不阻塞内线。
+		// 不包 try/catch：__connectIfNeeded → getBindingsPath → pluginDir 链路依赖 runtime 已注入，
+		// register full 模式下 setRuntime 必然先于 service.start 完成，pluginDir 不会抛
 		await this.__connectIfNeeded();
 		// 三条线各自独立启动：内线（plugin↔本机 gateway）由 start() 主动触发，
 		// 不再依附于外线 open。即便外线建连失败/未配置 token，内线仍能起来支撑 DC RPC。

package/src/topic-manager/manager.js

@@ -229,6 +229,7 @@ export class TopicManager {
 		const srcPath = nodePath.join(this.__sessionsDir(agentId), `${topicId}.jsonl`);
 		const tempId = randomUUID();
 		const tempPath = nodePath.join(this.__sessionsDir(agentId), `${tempId}.jsonl`);
+		// fs.copyFile 非 atomic；崩在半路的临时 *.jsonl 可能被 session-manager 扫到列为幽灵会话，用户重试导出即恢复
 		await this.__copyFile(srcPath, tempPath);
 		return { tempId, tempPath };
 	}

package/src/utils/memory-queue.js

@@ -282,8 +282,11 @@ class MemoryQueue {
 		return this.tag ? ` ${this.tag}` : '';
 	}
 
+	// AGENTS.md §"日志器" 一般规则是"调用点不要再包 try/catch"，此处特例：
+	// __safeWarn 是 enqueue 同步入口的兜底，enqueue 对外承诺不抛业务无关错误，
+	// 哪怕 logger 自身坏了也不能传染到 RPC 数据通路，故保留 swallow
 	__safeWarn(msg) {
-		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 enqueue 抛 */ }
+		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* swallow */ }
 	}
 }
 

package/src/webrtc/dc-chunking.js

@@ -60,29 +60,6 @@ export function buildChunks(jsonStr, maxMessageSize, getNextMsgId) {
 	return chunks;
 }
 
-/**
- * 按需分片并发送消息（薄包装：buildChunks + dc.send）
- * 注意：无应用层流控；生产路径请使用 MemoryQueue + RpcDcSender
- * @param {object} dc - DataChannel
- * @param {string} jsonStr - 已序列化的 JSON 字符串
- * @param {number} maxMessageSize - 对端声明的 maxMessageSize
- * @param {() => number} getNextMsgId - 获取下一个 msgId
- * @param {object} [logger] - 可选 logger
- */
-export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger) {
-	const chunks = buildChunks(jsonStr, maxMessageSize, getNextMsgId);
-	if (!chunks) {
-		dc.send(jsonStr);
-		return;
-	}
-	const msgId = chunks[0].readUInt32BE(1);
-	const totalBytes = chunks.reduce((n, c) => n + (c.length - HEADER_SIZE), 0);
-	logger?.info?.(`[dc-chunking] chunking msgId=${msgId}: ${totalBytes} bytes → ${chunks.length} chunks (maxMsgSize=${maxMessageSize})`);
-	for (const chunk of chunks) {
-		dc.send(chunk);
-	}
-}
-
 /**
  * 创建分片重组器
  * @param {(jsonStr: string) => void} onComplete - 完整消息回调

package/src/webrtc/rpc-dc-sender.js

@@ -160,8 +160,11 @@ class RpcDcSender {
 		return this.tag ? ` ${this.tag}` : '';
 	}
 
+	// AGENTS.md §"日志器" 一般规则是"调用点不要再包 try/catch"，此处特例：
+	// __safeWarn 在 send/BAL 热路径里调，logger 异常不能升级为协议错（caller 只
+	// 等 RPC 应答，不该收到 logger 自身的 stack），故保留 swallow
 	__safeWarn(msg) {
-		try { this.logger.warn?.(`[rpc-dc-sender${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了不能让 send 抛非协议错 */ }
+		try { this.logger.warn?.(`[rpc-dc-sender${this.__tagSuffix()}] ${msg}`); } catch { /* swallow */ }
 	}
 
 	__safeRemoteLog(text) {