@coclaw/openclaw-coclaw 0.23.0 → 0.25.0

package/index.js

@@ -809,16 +809,20 @@ const plugin = {
 		registerProviderAuthHandlers(api, {
 			loadSdk: () => import('openclaw/plugin-sdk/provider-auth'),
 			loadConfigMutation: () => import('openclaw/plugin-sdk/config-mutation'),
+			// provider-catalog-runtime 供通用 device-code 扫码登录（B1）拿 resolvePluginProviders，
+			// 驱动 provider 自带的 device_code 登录方法（codex/copilot 及以后任意 device_code provider）
+			loadProviderCatalogRuntime: () => import('openclaw/plugin-sdk/provider-catalog-runtime'),
 		});
 
-		// 模型默认配置 RPC（coclaw.model.set / list）。三个 SDK 子入口的字面量
+		// 模型默认配置 RPC（coclaw.model.set / list / listUsable）。三个 SDK 子入口的字面量
 		// dynamic import 必须留在本入口源码——OpenClaw plugin loader 只扫入口源码
 		// 命中 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；藏在子模块的字面量
 		// loader 看不到 → 原生 Node 解析必败。
 		registerModelDefaultHandlers(api, {
 			loadConfigMutation: () => import('openclaw/plugin-sdk/config-mutation'),
-			loadModelsProviderRuntime: () => import('openclaw/plugin-sdk/models-provider-runtime'),
 			loadProviderAuth: () => import('openclaw/plugin-sdk/provider-auth'),
+			// agent-runtime barrel：resolveProviderIdForAuth（内联别名归一）+ loadModelCatalog（选模型器枚举 / set 存在性干净目录）
+			loadAgentRuntime: () => import('openclaw/plugin-sdk/agent-runtime'),
 		});
 
 		const scheduler = new AutoUpgradeScheduler({ pluginId: api.id, logger });

package/package.json

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

package/src/model-default/handlers.js

@@ -1,22 +1,25 @@
 /**
- * model-default/handlers.js —— coclaw.model.set / list 两个 RPC 的纯函数实现
+ * model-default/handlers.js —— coclaw.model.set / list / listUsable 三个 RPC 的纯函数实现
  *
  * 设计要点（详见 docs/model-config-api.md § 3）：
- * - DI 注入 sdk（mutateConfigFile / buildModelsProviderData / isProviderAuthProfileConfigured）
+ * - DI 注入 sdk（mutateConfigFile / loadModelCatalog / provider-auth 凭据探针 / resolveProviderIdForAuth）
  *   + loadConfig + resolveAgentDir，便于单测；产线注入在 ./index.js
- * - **出参不加 status wrap**（gateway-method-design skill 新约定）：set → {}；list → { default, agents }
+ * - **出参不加 status wrap**（gateway-method-design skill 约定）：set → {}；list → { default, agents }；
+ *   listUsable → { byProvider, configuredProviders }
  * - 错误码只用 INVALID_ARGS / IO_FAILED，参考 provider-auth/handlers.js
  *   既有 plugin 的 respondError 用 INTERNAL_ERROR 与本节契约不一致，所以本模块自带局部 helper
  * - set 校验 fail-fast 顺序：params shape → 拒未知字段 → agentId → primary 类型 → primary 形态
- *   （纯字符串：含 '/'、'/' 不在端点；不依赖 cfg）→ loadConfig → provider 凭据 → catalog
+ *   （纯字符串：含 '/'、'/' 不在端点；不依赖 cfg）→ loadConfig → 凭据门 → 存在性
  *   形态校验**前置在 loadConfig 之前**，cfg 不可读时非法形态仍是 INVALID_ARGS 而非 IO_FAILED
- * - catalog 校验用 `view: 'all'`：picker 可见性过滤会误判某些合法 provider 不存在（subagent 调研结论）
+ * - 凭据门 + 选模型器枚举 + list 信号全部走统一别名感知原语（resolve.js），杜绝跨界面口径分叉（§ 3.2.1）
+ * - set 存在性 + listUsable 枚举走同一干净目录 loadModelCatalog({readOnly:true})：选得到 ⇒ 设得上（红线天然成立）
  */
 
-import { listAllPrimaries } from './resolve.js';
+import { listAllPrimariesWithCredentials, computeProviderUsable, enumerateUsableModels } from './resolve.js';
 import { writePrimary } from './persist.js';
 
-const ALLOWED_KEYS = new Set(['agentId', 'primary']);
+const SET_ALLOWED_KEYS = new Set(['agentId', 'primary']);
+const LISTUSABLE_ALLOWED_KEYS = new Set(['agentId']);
 
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_ARGS', message });
@@ -47,39 +50,61 @@ function parseProviderModel(primary) {
 }
 
 /**
- * cfg 相关的 primary 校验：provider 凭据 + catalog 存在性。
+ * 构造 set / listUsable 用的统一别名感知凭据 deps。
+ * @param {object} sdk
+ * @param {string} agentDir
+ * @returns {object}
+ */
+function buildCredDeps(sdk, agentDir) {
+	return {
+		agentDir,
+		isProviderApiKeyConfigured: sdk.isProviderApiKeyConfigured,
+		hasConfiguredSecretInput: sdk.hasConfiguredSecretInput,
+		ensureAuthProfileStore: sdk.ensureAuthProfileStore,
+		resolveProviderIdForAuth: sdk.resolveProviderIdForAuth,
+	};
+}
+
+/**
+ * cfg 相关的 primary 校验：凭据门 + 干净目录存在性。
  * 形态拆分由调用方完成（fail-fast 前置在 loadConfig 之前）。
  *
+ * - 凭据门走统一原语 computeProviderUsable（取代旧 ledger-only isProviderAuthProfileConfigured）：
+ *   覆盖 env + 账本 + 内联 + 别名套餐，修「内联/env/别名 provider 选得到设不上」，且继续拒幽灵
+ *   （无任何源凭据的 openai/gpt-5.5 被门挡住）。cooldown 中凭据仍算已配置（沿用 isProviderApiKeyConfigured 立场）。
+ * - 存在性走干净目录 loadModelCatalog({readOnly:true})（与选模型器枚举同源 → 「选得到设不上」红线天然成立）；
+ *   去掉旧 buildModelsProviderData view:'all'（~1076 模型/~10s、鉴权盲、过松）。
+ *   loadModelCatalog readOnly 自带「持久化失败→静态 manifest」兜底；整体抛错由外层 catch 映射 IO_FAILED（set 是写操作，失败安全为先）。
+ *
  * @returns {Promise<string|null>} 错误 message；null 表通过
  */
-async function validateProviderCredAndCatalog({ provider, model, primary, cfg, sdk, agentDir }) {
-	// 凭据校验：isProviderAuthProfileConfigured 内部就是 listUsableProviderAuthProfileIds().length > 0
-	// cooldown profile 仍算"已配置"（cooldown 是临时态，上游 fallback 主循环会主动跳）
-	const hasCred = sdk.isProviderAuthProfileConfigured({ provider, cfg, agentDir });
-	if (!hasCred) {
-		return `provider "${provider}" has no usable auth profile`;
+async function validateProviderCredAndCatalog({ provider, model, primary, cfg, sdk, deps }) {
+	if (!computeProviderUsable(primary, cfg, deps)) {
+		return `provider "${provider}" has no usable credential`;
 	}
-
-	// catalog 校验：view: 'all' 绕开 picker 可见性过滤（picker 过滤掉的 provider 不影响合法性）
-	const data = await sdk.buildModelsProviderData(cfg, undefined, { view: 'all' });
-	const modelSet = data?.byProvider?.get(provider);
-	if (!modelSet || !modelSet.has(model)) {
+	const entries = await sdk.loadModelCatalog({ readOnly: true });
+	const exists = Array.isArray(entries)
+		&& entries.some((e) => e && e.provider === provider && e.id === model);
+	if (!exists) {
 		return `model "${primary}" not found in catalog`;
 	}
 	return null;
 }
 
 /**
- * 构造 set + list 两个 handler。
+ * 构造 set / list / listUsable 三个 handler。
  *
  * @param {object} opts
  * @param {object} opts.sdk
- * @param {Function} opts.sdk.mutateConfigFile - openclaw/plugin-sdk/config-mutation
- * @param {Function} opts.sdk.buildModelsProviderData - openclaw/plugin-sdk/models-provider-runtime
- * @param {Function} opts.sdk.isProviderAuthProfileConfigured - openclaw/plugin-sdk/provider-auth
+ * @param {Function} opts.sdk.mutateConfigFile - openclaw/plugin-sdk/config-mutation（set 写盘）
+ * @param {Function} opts.sdk.loadModelCatalog - openclaw/plugin-sdk/agent-runtime（set 存在性 + listUsable 枚举的干净目录）
+ * @param {Function} opts.sdk.isProviderApiKeyConfigured - openclaw/plugin-sdk/provider-auth（env+账本凭据信号，别名感知）
+ * @param {Function} opts.sdk.hasConfiguredSecretInput - openclaw/plugin-sdk/provider-auth（内联 key 判定）
+ * @param {Function} opts.sdk.ensureAuthProfileStore - openclaw/plugin-sdk/provider-auth（账本非空 / configuredProviders）
+ * @param {Function} opts.sdk.resolveProviderIdForAuth - openclaw/plugin-sdk/agent-runtime（别名归一）
  * @param {Function} opts.loadConfig - 返回当前 cfg snapshot；缺失时返回 null
- * @param {Function} opts.resolveAgentDir - 返回 main agent /agent 子目录全路径
- * @returns {{ set: Function, list: Function }}
+ * @param {Function} opts.resolveAgentDir - 返回 agent /agent 子目录全路径（默认 main agent；agentId 贯穿）
+ * @returns {{ set: Function, list: Function, listUsable: Function }}
  */
 export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir }) {
 	async function set({ params, respond }) {
@@ -89,7 +114,7 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 				return;
 			}
 			for (const key of Object.keys(params)) {
-				if (!ALLOWED_KEYS.has(key)) {
+				if (!SET_ALLOWED_KEYS.has(key)) {
 					respondInvalid(respond, `unknown field: ${key}`);
 					return;
 				}
@@ -134,7 +159,7 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 					primary,
 					cfg,
 					sdk,
-					agentDir: resolveAgentDir(),
+					deps: buildCredDeps(sdk, resolveAgentDir()),
 				});
 				if (validationError) {
 					respondInvalid(respond, validationError);
@@ -168,12 +193,63 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 				respondIoFailed(respond, new Error('runtime config not available'));
 				return;
 			}
-			respond(true, listAllPrimaries(cfg));
+			// 凭据信号（providerUsable / hasAnyUsableCredential）借统一别名感知原语：
+			// env+账本 走 isProviderApiKeyConfigured（别名归一其内部完成），
+			// 内联 key 走 hasConfiguredSecretInput + resolveProviderIdForAuth 两侧归一，
+			// 账本非空走 ensureAuthProfileStore。
+			respond(true, listAllPrimariesWithCredentials(cfg, buildCredDeps(sdk, resolveAgentDir())));
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	async function listUsable({ params, respond }) {
+		try {
+			if (!params || typeof params !== 'object' || Array.isArray(params)) {
+				respondInvalid(respond, 'params must be an object');
+				return;
+			}
+			for (const key of Object.keys(params)) {
+				if (!LISTUSABLE_ALLOWED_KEYS.has(key)) {
+					respondInvalid(respond, `unknown field: ${key}`);
+					return;
+				}
+			}
+			const { agentId } = params;
+			if (agentId !== undefined && !isNonEmptyString(agentId)) {
+				respondInvalid(respond, 'agentId must be a non-empty string when provided');
+				return;
+			}
+
+			const cfg = loadConfig();
+			if (!cfg) {
+				respondIoFailed(respond, new Error('runtime config not available'));
+				return;
+			}
+
+			// agentId 一路贯穿到凭据判定（与 set/providerUsable 同 agent 的 agentDir，不分叉）。
+			// 产线 resolveAgentDir=mainAgentDir 忽略入参恒 main（凭据按设计统一落 main、各 agent 层叠可见），
+			// 故四个消费点在产线天然同 dir；测试可注入按 agentId 分目录的 resolver 钉住贯穿。
+			const deps = buildCredDeps(sdk, resolveAgentDir(agentId));
+
+			// 干净目录 loadModelCatalog({readOnly:true}) 自带「持久化失败→静态 manifest」兜底（model-catalog.ts）。
+			// 仍整体抛错（罕见，如 runtime config 取不到）→ 兜空 entries：byProvider 退化为空，
+			// 但 configuredProviders 不依赖目录仍可算 → 「不空白」，UI 加 provider 排除照常工作（§ 3.2.1 降级）。
+			let entries;
+			try {
+				entries = await sdk.loadModelCatalog({ readOnly: true });
+			}
+			catch {
+				entries = [];
+			}
+
+			respond(true, enumerateUsableModels(entries, cfg, deps));
 		}
 		catch (err) {
 			respondIoFailed(respond, err);
 		}
 	}
 
-	return { set, list };
+	return { set, list, listUsable };
 }

package/src/model-default/index.js

@@ -1,8 +1,8 @@
 /**
- * model-default 注册入口 —— 把 coclaw.model.set / list 接到 gateway。
+ * model-default 注册入口 —— 把 coclaw.model.set / list / listUsable 接到 gateway。
  *
  * 设计（同 provider-auth/index.js）：
- * - 三个 SDK 子入口（config-mutation / models-provider-runtime / provider-auth）懒加载，
+ * - 三个 SDK 子入口（config-mutation / provider-auth / agent-runtime）懒加载，
  *   首次 RPC 调用才解析；失败硬编码 IO_FAILED 透 message
  * - mainAgentDir 走 claw-paths.js；loadConfig 走 claw-config.js
  * - opts 主要给单测用：可注入 fake sdk 工厂 / fake agentDir resolver / fake loadConfig
@@ -21,33 +21,35 @@ import { getClawConfig } from '../claw-config.js';
 // SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
 // 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _configMutationP;
-let _modelsP;
 let _providerAuthP;
+let _agentRuntimeP;
 
 function defaultLoadConfigMutation() {
 	_configMutationP ??= import('openclaw/plugin-sdk/config-mutation');
 	return _configMutationP;
 }
-function defaultLoadModelsProviderRuntime() {
-	_modelsP ??= import('openclaw/plugin-sdk/models-provider-runtime');
-	return _modelsP;
-}
 function defaultLoadProviderAuth() {
 	_providerAuthP ??= import('openclaw/plugin-sdk/provider-auth');
 	return _providerAuthP;
 }
+function defaultLoadAgentRuntime() {
+	// agent-runtime barrel 同时给：resolveProviderIdForAuth（别名归一）+ loadModelCatalog（干净目录，
+	// set 存在性 / listUsable 选模型器枚举同源）。barrel re-export provider-auth-aliases.js + model-catalog.js。
+	_agentRuntimeP ??= import('openclaw/plugin-sdk/agent-runtime');
+	return _agentRuntimeP;
+}
 
 /**
  * 测试辅助：清掉懒加载 SDK 缓存。
  */
 export function __resetSdkCaches() {
 	_configMutationP = undefined;
-	_modelsP = undefined;
 	_providerAuthP = undefined;
+	_agentRuntimeP = undefined;
 }
 
 /**
- * 在 gateway api 上注册 `coclaw.model.set` / `coclaw.model.list`。
+ * 在 gateway api 上注册 `coclaw.model.set` / `coclaw.model.list` / `coclaw.model.listUsable`。
  *
  * 仅 `register(api)` 的 `if (api.registrationMode === 'full')` 分支调；
  * 其它 mode 注册副作用违规（参 plugins/openclaw/CLAUDE.md "Service / register 副作用边界"）。
@@ -57,29 +59,35 @@ export function __resetSdkCaches() {
  * @param {Function} [opts.resolveAgentDir] - 覆盖 agentDir 解析（默认 mainAgentDir）
  * @param {Function} [opts.loadConfig] - 覆盖 cfg 读取（默认 getClawConfig）
  * @param {Function} [opts.loadConfigMutation] - 必传（生产由入口注入字面量 dynamic import）
- * @param {Function} [opts.loadModelsProviderRuntime] - 必传（同上）
  * @param {Function} [opts.loadProviderAuth] - 必传（同上）
+ * @param {Function} [opts.loadAgentRuntime] - 必传（同上；resolveProviderIdForAuth + loadModelCatalog）
  */
 export function registerModelDefaultHandlers(api, opts = {}) {
 	const resolveAgentDir = opts.resolveAgentDir ?? mainAgentDir;
 	const loadConfig = opts.loadConfig ?? getClawConfig;
 	const loadConfigMutation = opts.loadConfigMutation ?? defaultLoadConfigMutation;
-	const loadModelsProviderRuntime = opts.loadModelsProviderRuntime ?? defaultLoadModelsProviderRuntime;
 	const loadProviderAuth = opts.loadProviderAuth ?? defaultLoadProviderAuth;
+	const loadAgentRuntime = opts.loadAgentRuntime ?? defaultLoadAgentRuntime;
 
 	let handlersPromise;
 	async function getHandlers() {
 		if (!handlersPromise) {
 			handlersPromise = (async () => {
-				const [configMutation, modelsRuntime, providerAuth] = await Promise.all([
+				const [configMutation, providerAuth, agentRuntime] = await Promise.all([
 					loadConfigMutation(),
-					loadModelsProviderRuntime(),
 					loadProviderAuth(),
+					loadAgentRuntime(),
 				]);
 				const sdk = {
 					mutateConfigFile: configMutation.mutateConfigFile,
-					buildModelsProviderData: modelsRuntime.buildModelsProviderData,
-					isProviderAuthProfileConfigured: providerAuth.isProviderAuthProfileConfigured,
+					// 干净目录（set 存在性 + listUsable 枚举同源）：agent-runtime barrel re-export model-catalog.js
+					loadModelCatalog: agentRuntime.loadModelCatalog,
+					// 凭据信号（providerUsable / hasAnyUsableCredential / 凭据门 / configuredProviders）
+					isProviderApiKeyConfigured: providerAuth.isProviderApiKeyConfigured,
+					hasConfiguredSecretInput: providerAuth.hasConfiguredSecretInput,
+					ensureAuthProfileStore: providerAuth.ensureAuthProfileStore,
+					// 别名归一（内联凭据信号 + 选模型器枚举 + configuredProviders）
+					resolveProviderIdForAuth: agentRuntime.resolveProviderIdForAuth,
 				};
 				return buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir });
 			})();
@@ -106,4 +114,5 @@ export function registerModelDefaultHandlers(api, opts = {}) {
 
 	api.registerGatewayMethod('coclaw.model.set', wrap('set'));
 	api.registerGatewayMethod('coclaw.model.list', wrap('list'));
+	api.registerGatewayMethod('coclaw.model.listUsable', wrap('listUsable'));
 }

package/src/model-default/resolve.js

@@ -86,3 +86,228 @@ export function listAllPrimaries(cfg) {
 	}
 	return out;
 }
+
+/**
+ * 取 primary 的 provider 段（'<provider>/<model>' 中第一个 '/' 之前）。
+ * 不含 '/' 或 '/' 在开头（provider 段为空）时返回 null。
+ * 不做别名归一化——交给下游 isProviderApiKeyConfigured 内部完成。
+ * @param {string|null} primary
+ * @returns {string|null}
+ */
+export function providerSegmentOf(primary) {
+	if (typeof primary !== 'string') return null;
+	const slashIdx = primary.indexOf('/');
+	if (slashIdx <= 0) return null;
+	return primary.slice(0, slashIdx);
+}
+
+/**
+ * 某 provider 是否配了内联 key（cfg.models.providers.<id>.apiKey）。
+ * 别名感知：查询名与各内联节点 id 两侧都过 resolveProviderIdForAuth 归一后比较，
+ * 故持基座 volcengine 内联 key 的用户查 volcengine-plan（套餐变体）也命中。
+ * 仅是"配置信号"（hasConfiguredSecretInput 不验证 env 引用能否真解析，
+ * 见心智模型典型陷阱 #20），方向偏向少误报。
+ * @param {object} cfg
+ * @param {string} provider - 裸 provider 名
+ * @param {object} deps - { hasConfiguredSecretInput, resolveProviderIdForAuth }
+ * @returns {boolean}
+ */
+function hasInlineKey(cfg, provider, deps) {
+	const providers = cfg?.models?.providers;
+	if (!providers || typeof providers !== 'object') return false;
+	const targetId = deps.resolveProviderIdForAuth(provider);
+	for (const [nodeId, entry] of Object.entries(providers)) {
+		if (!entry || !deps.hasConfiguredSecretInput(entry.apiKey)) continue;
+		if (deps.resolveProviderIdForAuth(nodeId) === targetId) return true;
+	}
+	return false;
+}
+
+/**
+ * 某 provider（裸名，无斜杠）有没有可用凭据 —— 统一别名感知原语。
+ * 判定 = isProviderApiKeyConfigured（覆盖 env + 自管账本，别名归一其内部完成）
+ *        ∪ hasInlineKey（内联 key，别名归一）。
+ * 覆盖 env + 内联 + 账本 + 别名套餐；统一漏 IAM/本地（hasAuthForModelProvider 未导出 plugin-sdk，接受）。
+ * 选模型器枚举 / model.set 门 / providerUsable / noKey 四个消费点同吃这一个原语，杜绝跨界面口径分叉。
+ * @param {string|null} provider - 裸 provider 名（如 'openai' / 'volcengine-plan'）
+ * @param {object} cfg
+ * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, resolveProviderIdForAuth }
+ * @returns {boolean}
+ */
+export function computeProviderUsableByName(provider, cfg, deps) {
+	if (typeof provider !== 'string' || provider.length === 0) return false;
+	if (deps.isProviderApiKeyConfigured({ provider, agentDir: deps.agentDir })) return true;
+	return hasInlineKey(cfg, provider, deps);
+}
+
+/**
+ * 该 primary 那家 provider 有没有可用凭据：取 provider 段后委托 computeProviderUsableByName。
+ * primary 解析不出 provider 段（含 null）时恒 false（UI 此时走 noPrimary，不看它）。
+ * @param {string|null} primary
+ * @param {object} cfg
+ * @param {object} deps - 同 computeProviderUsableByName
+ * @returns {boolean}
+ */
+export function computeProviderUsable(primary, cfg, deps) {
+	return computeProviderUsableByName(providerSegmentOf(primary), cfg, deps);
+}
+
+/**
+ * 收集"候选 provider 名"（未归一、原始拼写）供 env 探测：
+ * default + 各 agent primary 的 provider 段 ∪ 内联节点 id ∪ 账本各 profile 的 provider。
+ * env-only 凭据无法穷举所有环境变量名，只在这些候选上用 isProviderApiKeyConfigured 探测，
+ * 与 providerAuth.list 的 env 口径一致（纯 env、又非主模型/账本/内联的 provider 不计，接受残留）。
+ * @param {object} cfg
+ * @param {object|null} store - ensureAuthProfileStore 返回值（可能为 null）
+ * @returns {Set<string>}
+ */
+function collectCandidateProviders(cfg, store) {
+	const out = new Set();
+	const base = listAllPrimaries(cfg);
+	const seg = providerSegmentOf(base.default.primary);
+	if (seg) out.add(seg);
+	for (const v of Object.values(base.agents)) {
+		const s = providerSegmentOf(v.primary);
+		if (s) out.add(s);
+	}
+	const providers = cfg?.models?.providers;
+	if (providers && typeof providers === 'object') {
+		for (const id of Object.keys(providers)) out.add(id);
+	}
+	if (store && store.profiles && typeof store.profiles === 'object') {
+		for (const cred of Object.values(store.profiles)) {
+			if (cred && typeof cred.provider === 'string' && cred.provider.length > 0) {
+				out.add(cred.provider);
+			}
+		}
+	}
+	return out;
+}
+
+/**
+ * 这台 claw 有没有任何可用凭据：自管账本非空 OR 任一内联 key OR 任一候选 provider 有 env key。
+ * 驱动 UI 的 noKey 引导。必补 C：补 env（候选集口径见 collectCandidateProviders），
+ * 与 per-provider 的 providerUsable 口径对齐，根治"纯 env-only 用户被误弹『还没加 key』"。
+ * 补后仅漏纯 IAM-only/本地（pro，接受 spurious noKey）。
+ * @param {object} cfg
+ * @param {object} deps - { agentDir, ensureAuthProfileStore, hasConfiguredSecretInput, isProviderApiKeyConfigured }
+ * @returns {boolean}
+ */
+export function computeHasAnyUsableCredential(cfg, deps) {
+	const store = deps.ensureAuthProfileStore(deps.agentDir, { allowKeychainPrompt: false });
+	if (store && store.profiles && Object.keys(store.profiles).length > 0) return true;
+	const providers = cfg?.models?.providers;
+	if (providers && typeof providers === 'object') {
+		for (const entry of Object.values(providers)) {
+			if (entry && deps.hasConfiguredSecretInput(entry.apiKey)) return true;
+		}
+	}
+	for (const provider of collectCandidateProviders(cfg, store)) {
+		if (deps.isProviderApiKeyConfigured({ provider, agentDir: deps.agentDir })) return true;
+	}
+	return false;
+}
+
+/**
+ * 别名归一的"已配 provider"集 = 用户已持任一来源凭据的基座 provider id 集，
+ * 供 UI 加 provider 时排除（套餐用户持 volcengine key 后不再被叫去加 volcengine/volcengine-plan）。
+ * 三源（每个都过 resolveProviderIdForAuth 归一后去重）：
+ *   ① 账本各 profile 的 cred.provider
+ *   ② 内联各带 apiKey 的节点 id
+ *   ③ env 候选（collectCandidateProviders 口径）中 isProviderApiKeyConfigured 命中的
+ * @param {object} cfg
+ * @param {object} deps - { agentDir, ensureAuthProfileStore, hasConfiguredSecretInput, isProviderApiKeyConfigured, resolveProviderIdForAuth }
+ * @returns {string[]} 升序去重
+ */
+export function computeConfiguredProviders(cfg, deps) {
+	const store = deps.ensureAuthProfileStore(deps.agentDir, { allowKeychainPrompt: false });
+	const out = new Set();
+	const add = (raw) => {
+		const id = deps.resolveProviderIdForAuth(raw);
+		if (id) out.add(id);
+	};
+	if (store && store.profiles && typeof store.profiles === 'object') {
+		for (const cred of Object.values(store.profiles)) {
+			if (cred && typeof cred.provider === 'string' && cred.provider.length > 0) add(cred.provider);
+		}
+	}
+	const providers = cfg?.models?.providers;
+	if (providers && typeof providers === 'object') {
+		for (const [id, entry] of Object.entries(providers)) {
+			if (entry && deps.hasConfiguredSecretInput(entry.apiKey)) add(id);
+		}
+	}
+	for (const provider of collectCandidateProviders(cfg, store)) {
+		if (deps.isProviderApiKeyConfigured({ provider, agentDir: deps.agentDir })) add(provider);
+	}
+	return [...out].sort();
+}
+
+/**
+ * 选模型器枚举（纯同步）：把干净目录按 entry.provider 分组，留 computeProviderUsableByName 为真的 provider。
+ * catalogEntries 由调用方传入（子任务 2 的 handler 调 loadModelCatalog({readOnly:true}) 后传进来），
+ * 本函数不自己 await loadModelCatalog；空 / 非数组 entries → 空 byProvider。
+ * 变体 provider（如 volcengine-plan）经 manifest 目录行进入 entries、再经基座 key 别名感知保留；
+ * 无凭据 provider 被丢（含幽灵——幽灵根本不在 loadModelCatalog 这个源里）。
+ *
+ * 文本模态过滤：核实结论 = 不过滤。loadModelCatalog 输出的 ModelCatalogEntry 无 output kind 字段
+ * （image_generation 等是网关响应的另一类型；imageModel 注入只在 buildModelsProviderData 尾部、不在此源），
+ * 故无"纯图像/视频生成"条目混入；entry.input 是"输入"模态而非输出 kind，按它滤会误删多模态文本模型。
+ *
+ * @param {object[]} catalogEntries - loadModelCatalog({readOnly:true}) 的结果（ModelCatalogEntry[]）
+ * @param {object} cfg
+ * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, resolveProviderIdForAuth, ensureAuthProfileStore }
+ * @returns {{ byProvider: Record<string, string[]>, configuredProviders: string[] }}
+ */
+export function enumerateUsableModels(catalogEntries, cfg, deps) {
+	const grouped = new Map(); // provider -> Set<modelId>
+	if (Array.isArray(catalogEntries)) {
+		for (const entry of catalogEntries) {
+			if (!entry || typeof entry.provider !== 'string' || entry.provider.length === 0) continue;
+			if (typeof entry.id !== 'string' || entry.id.length === 0) continue;
+			let set = grouped.get(entry.provider);
+			if (!set) {
+				set = new Set();
+				grouped.set(entry.provider, set);
+			}
+			set.add(entry.id);
+		}
+	}
+	const byProvider = {};
+	for (const [provider, ids] of grouped) {
+		if (computeProviderUsableByName(provider, cfg, deps)) {
+			byProvider[provider] = [...ids].sort();
+		}
+	}
+	return { byProvider, configuredProviders: computeConfiguredProviders(cfg, deps) };
+}
+
+/**
+ * 装配带凭据信号的 list 出参（docs/model-config-api.md § 3.4「凭据信号」）。
+ * 在 listAllPrimaries 基础上给每个 scope 加 providerUsable，并加顶层 hasAnyUsableCredential。
+ * @param {object} cfg
+ * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, ensureAuthProfileStore, resolveProviderIdForAuth }
+ * @returns {{
+ *   default: { primary: string|null, providerUsable: boolean },
+ *   agents: Record<string, { primary: string|null, providerUsable: boolean }>,
+ *   hasAnyUsableCredential: boolean,
+ * }}
+ */
+export function listAllPrimariesWithCredentials(cfg, deps) {
+	const base = listAllPrimaries(cfg);
+	const out = {
+		default: {
+			primary: base.default.primary,
+			providerUsable: computeProviderUsable(base.default.primary, cfg, deps),
+		},
+		agents: {},
+		hasAnyUsableCredential: computeHasAnyUsableCredential(cfg, deps),
+	};
+	for (const [id, v] of Object.entries(base.agents)) {
+		out.agents[id] = {
+			primary: v.primary,
+			providerUsable: computeProviderUsable(v.primary, cfg, deps),
+		};
+	}
+	return out;
+}

package/src/provider-auth/device-code-login.js

@@ -0,0 +1,123 @@
+/**
+ * device-code-login.js —— 通用「设备码扫码登录」驱动的可复用零件（B1：驱动上游 run）
+ *
+ * 不复刻任何一家的登录流程，而是经 plugin-sdk 的 resolvePluginProviders 拿到 provider 自己的
+ * device_code 登录方法，用一个「捕获型 prompter」的 ctx 去驱动它的 run(ctx)，跟随上游同步。
+ * 适用于**任何**暴露了 kind==='device_code' auth 方法的 provider（codex / copilot / 以后新增的），
+ * 不针对某一家硬编码。minimax-portal 例外（走自家 B2 复刻流，见 handlers.js 路由 + minimax-oauth.js）。
+ *
+ * 本模块只放**纯函数 + ctx 工厂**（无 I/O、无 respond / 落盘），编排与两阶段响应在 handlers.js。
+ *
+ * 关键事实（核实自 openclaw-repo，详见 docs/model-config-api.md § 6.16）：
+ * - device_code 方法的 run(ctx) 是「纯输出 + 后台轮询、零用户实时输入」：先 prompter.note 亮出
+ *   「URL + 码」，再内部轮询，拿到 token 才 resolve。故套得进 CoClaw 现有两阶段 RPC，无需多轮 prompt 管道。
+ * - codex / copilot 的验证 note 用同一套模板（`URL: <url>` 行 + `Code: <code>` 行），一条正则通吃。
+ *   抠不到也不报错——把 note 全文作为 rawText 交前端兜底（用户明确要求）。
+ * - codex 失败时会再发一条含 docs URL 的「帮助 note」；copilot 首条 note 是无 URL 的前导语。
+ *   故「是否验证 note」判定 = 含 URL 且非帮助/FAQ 文案，不能只看「第一条 note」。
+ * - copilot 已登录会先 confirm「是否重登」→ 捕获型 prompter 答 true（强制走一遍登录拿码）。
+ * - 输出型 prompter：text / select / multiselect / oauth.createVpsAwareHandlers 一旦被调即抛错
+ *   （= 该方法需要交互/回环、本通道不支持），错误经 run reject 暴露。
+ */
+
+// note 里的 URL：取到空白 / 右括号为止
+const URL_RE = /https?:\/\/[^\s)]+/;
+// 帮助 / FAQ 类 note 也含 URL，但不是验证信息，必须排除
+const HELP_NOTE_RE = /faq|help|trouble|docs\.openclaw/i;
+// 设备码样式短码兜底（如 ABCD-1234），仅在没有 `Code:` 行时用
+const DEVICE_CODE_RE = /\b[A-Z0-9]{4,}-[A-Z0-9]{4,}\b/;
+
+/**
+ * 判断一条 note 文本是否「验证信息 note」（亮 URL+码 的那条）。
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isVerificationNote(text) {
+	const t = String(text ?? '');
+	if (!URL_RE.test(t)) return false;
+	if (HELP_NOTE_RE.test(t)) return false;
+	return true;
+}
+
+/**
+ * 从验证 note 文本里尽力抠出结构化字段；抠不到的返回 null（绝不抛错）。
+ *
+ * URL：优先 `URL:` 行，回退首个 http(s) 链接。
+ * Code：优先 `Code:` 行，回退设备码样式短码。
+ *
+ * @param {string} text
+ * @returns {{ verificationUri: string|null, userCode: string|null }}
+ */
+export function extractVerification(text) {
+	const t = String(text ?? '');
+	let verificationUri = null;
+	const urlLine = t.match(/^[ \t]*URL:[ \t]*(\S+)/im);
+	if (urlLine) verificationUri = urlLine[1];
+	else {
+		const m = t.match(URL_RE);
+		if (m) verificationUri = m[0];
+	}
+	let userCode = null;
+	const codeLine = t.match(/^[ \t]*Code:[ \t]*(\S+)/im);
+	if (codeLine) userCode = codeLine[1];
+	else {
+		const m = t.match(DEVICE_CODE_RE);
+		if (m) userCode = m[0];
+	}
+	return { verificationUri, userCode };
+}
+
+/**
+ * 在 resolvePluginProviders 结果里找指定 provider 的 device_code 登录方法。
+ * @param {Array<{id:string, auth?:Array<{kind:string, run?:Function}>}>} providers
+ * @param {string} providerId
+ * @returns {{ id:string, run:Function }|null}
+ */
+export function findDeviceCodeMethod(providers, providerId) {
+	const provider = (providers ?? []).find((p) => p?.id === providerId);
+	if (!provider) return null;
+	const method = (provider.auth ?? []).find(
+		(m) => m?.kind === 'device_code' && typeof m.run === 'function',
+	);
+	return method ?? null;
+}
+
+/**
+ * 造一个「捕获型」ProviderAuthContext 去驱动 run。
+ *
+ * note 转发给 onNote（验证信息从这里来）；progress 空操作；confirm 答 true（copilot 重登放行）；
+ * 真交互（text / select / multiselect / 回环 handler）一旦被调即抛，标记为「需交互、不支持」。
+ * isRemote=true（codex 据此跳过本地 openUrl）；openUrl 空操作（copilot 会无条件调，安全吞掉）。
+ *
+ * @param {object} args
+ * @param {object} args.config - OpenClaw 运行时配置快照
+ * @param {string} [args.agentDir] - 凭据目录（copilot 据此探测已有登录）
+ * @param {(text:string, title?:string)=>void} args.onNote - 每条 note 的回调
+ * @returns {object} ProviderAuthContext 形状
+ */
+export function makeDeviceCodeCtx({ config, agentDir, onNote }) {
+	return {
+		config: config ?? {},
+		env: process.env,
+		agentDir,
+		prompter: {
+			intro: async () => {},
+			outro: async () => {},
+			plain: async () => {},
+			note: async (message, title) => { onNote(String(message ?? ''), title); },
+			progress: () => ({ update() {}, stop() {} }),
+			confirm: async () => true,
+			text: async () => { throw new Error('device-code login requires no text input'); },
+			select: async () => { throw new Error('device-code login requires no selection'); },
+			multiselect: async () => { throw new Error('device-code login requires no multiselect'); },
+		},
+		runtime: { log: () => {}, error: () => {}, exit: () => {} },
+		isRemote: true,
+		openUrl: async () => {},
+		oauth: {
+			createVpsAwareHandlers: () => {
+				throw new Error('device-code login does not support loopback handlers');
+			},
+		},
+	};
+}

package/src/provider-auth/handlers.js

@@ -37,6 +37,15 @@ 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';
+import { getClawConfig } from '../claw-config.js';
+import { listAllPrimaries, providerSegmentOf } from '../model-default/resolve.js';
+import { deepMergeInto } from '../utils/deep-merge.js';
+import {
+	isVerificationNote,
+	extractVerification,
+	findDeviceCodeMethod,
+	makeDeviceCodeCtx,
+} from './device-code-login.js';
 
 const VALID_CRED_TYPES = new Set(['api_key', 'oauth', 'token']);
 const PORTAL_PROFILE_ID = `${PORTAL_PROVIDER_ID}:default`;
@@ -68,11 +77,13 @@ function isNonEmptyString(v) {
  * @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 子目录）
- * @param {object} [opts.oauth] - createMiniMaxOAuth 实例（requestDeviceCode / pollUntilSettled）；OAuth handler 才用
- * @param {object} [opts.registry] - oauth-registry（registerLogin / getLogin / removeLogin）
+ * @param {object} [opts.oauth] - createMiniMaxOAuth 实例（requestDeviceCode / pollUntilSettled）；MiniMax B2 才用
+ * @param {object} [opts.registry] - oauth-registry（registerLogin / getLogin / removeLogin）；B2/B1 共用
  * @param {Function} [opts.genLoginId] - () → loginId，默认 randomUUID
- * @param {Function} [opts.scheduleBackground] - (promise) → void，挂后台轮询；默认 fire-and-forget + .catch
+ * @param {Function} [opts.scheduleBackground] - (promise) → void，挂后台任务；默认 fire-and-forget + .catch
  * @param {Function} [opts.logRemote] - (text) → void，OAuth 终态诊断推送；默认模块级 remoteLog（测试注入 spy）
+ * @param {Function} [opts.resolveConfig] - () → OpenClaw runtime config 快照；通用 device-code 登录（B1）拿 config 用，默认 getClawConfig
+ * @param {Function} [opts.resolveProviders] - ({ config, providerRefs }) → ProviderPlugin[]；B1 经它拿 provider 的 auth 方法（生产由入口注入，内部 activate:false），默认抛错
  * @returns {{ setApiKey, list, remove, loginOauth, cancelOauth }}
  */
 export function buildProviderAuthHandlers({
@@ -83,6 +94,8 @@ export function buildProviderAuthHandlers({
 	genLoginId = randomUUID,
 	scheduleBackground = (p) => { p.catch(() => {}); },
 	logRemote = remoteLog,
+	resolveConfig = getClawConfig,
+	resolveProviders = () => { throw new Error('provider catalog runtime not injected'); },
 }) {
 	// TODO: 将来若要支持"设默认模型 / 多账号顺序"等需要写 cfg 的操作，会撞上
 	// gateway 重启窗口的 UX 问题——参 docs/model-config-api.md § 3 / § 5（占位章节）。
@@ -137,14 +150,29 @@ export function buildProviderAuthHandlers({
 				respondInvalid(respond, 'provider must be a non-empty string when provided');
 				return;
 			}
+			// 账本来源（source='profile'）
 			const store = sdk.ensureAuthProfileStore(resolveAgentDir());
-			const profiles = [];
+			const ledger = [];
 			const raw = store?.profiles ?? {};
 			for (const [profileId, cred] of Object.entries(raw)) {
 				if (!isWellFormedCredential(cred)) continue;
-				if (filterProvider && cred.provider !== filterProvider) continue;
-				profiles.push(toListEntry(profileId, cred, sdk.formatApiKeyPreview));
+				ledger.push(toListEntry(profileId, cred, sdk.formatApiKeyPreview));
 			}
+			// 内联来源（source='inline'）：读 cfg；cfg 读不到时退化为仅账本，不连累 ledger 路径
+			let cfg = null;
+			try { cfg = resolveConfig(); }
+			catch { cfg = null; }
+			const inline = listInlineEntries(cfg, {
+				hasConfiguredSecretInput: sdk.hasConfiguredSecretInput,
+				formatApiKeyPreview: sdk.formatApiKeyPreview,
+			});
+			// env 来源（source='env'）：候选=账本∪内联∪主模型段；仅未被账本/内联覆盖的 sole-source 才列
+			const covered = new Set([...ledger, ...inline].map((e) => e.provider));
+			const candidates = new Set([...covered, ...collectPrimaryProviderSegments(cfg)]);
+			const env = listEnvEntries(candidates, covered, { resolveEnvApiKey: sdk.resolveEnvApiKey });
+
+			let profiles = [...ledger, ...inline, ...env];
+			if (filterProvider) profiles = profiles.filter((e) => e.provider === filterProvider);
 			respond(true, { profiles });
 		}
 		catch (err) {
@@ -159,16 +187,40 @@ export function buildProviderAuthHandlers({
 				respondInvalid(respond, 'provider must be a non-empty string');
 				return;
 			}
-			const result = await sdk.removeProviderAuthProfilesWithLock({
-				provider,
-				agentDir: resolveAgentDir(),
-			});
-			// 同 setApiKey：锁/磁盘失败时上游返回 null
-			if (result === null) {
-				respondIoFailed(respond, new Error('failed to update auth-profiles store'));
+			const source = params?.source ?? 'profile';
+			if (source === 'profile') {
+				const result = await sdk.removeProviderAuthProfilesWithLock({
+					provider,
+					agentDir: resolveAgentDir(),
+				});
+				// 同 setApiKey：锁/磁盘失败时上游返回 null
+				if (result === null) {
+					respondIoFailed(respond, new Error('failed to update auth-profiles store'));
+					return;
+				}
+				respond(true, {});
 				return;
 			}
-			respond(true, {});
+			if (source === 'inline') {
+				// 内联撤销：只删 cfg.models.providers[provider].apiKey 字段，保留节点其余内容
+				//（baseUrl/api/models 是用户的自定义 provider 定义，删整节点会把"没 key"恶化成"模型不存在"）。
+				// 删 key 后节点变空 {} → 顺手清掉空节点。afterWrite:auto → hot 路径零打断（docs § 2.5 / § 6.14）。
+				await sdk.mutateConfigFile({
+					afterWrite: { mode: 'auto' },
+					mutate(draft) {
+						const providers = draft?.models?.providers;
+						if (!providers || typeof providers !== 'object' || Array.isArray(providers)) return;
+						const node = providers[provider];
+						if (!node || typeof node !== 'object') return; // 幂等：无该节点视为已撤销
+						delete node.apiKey;
+						if (Object.keys(node).length === 0) delete providers[provider];
+					},
+				});
+				respond(true, {});
+				return;
+			}
+			// env 及未知 source：插件无法撤销（env 在进程环境里）→ 后端兜底拒绝
+			respondInvalid(respond, `cannot remove credential with source "${source}"`);
 		}
 		catch (err) {
 			respondIoFailed(respond, err);
@@ -293,7 +345,10 @@ export function buildProviderAuthHandlers({
 		}
 	}
 
-	async function loginOauth({ params, respond }) {
+	// MiniMax 设备码登录（B2：自家复刻设备码流，码已嵌在 verification URL 里 + 写静态模型清单）。
+	// 不并入通用 B1：MiniMax 不在 OpenClaw 内置 provider 字典，登录后还要补写 models.providers 清单
+	// （上游对 portal 不做 catalog discovery），与 codex/copilot「内置、模型自带」不同——见 docs § 6.16。
+	async function loginOauthMiniMax({ params, respond }) {
 		try {
 			const region = params?.region ?? 'cn';
 			if (!VALID_REGIONS.has(region)) {
@@ -330,6 +385,157 @@ export function buildProviderAuthHandlers({
 		}
 	}
 
+	// --- 通用设备码登录（B1：驱动上游 provider 的 device_code run，跟随上游同步） ---
+
+	// 设备码失败的终态响应：phase-1 已发过 accepted → 发 phase-2 错误帧（带 status）；
+	// phase-1 之前就失败 → 单帧错误（payload undefined，与 MiniMax phase-1 之前失败同形）
+	function respondDeviceFailure(respond, phase1Sent, code, message, status = 'error') {
+		if (phase1Sent) respond(false, { status }, { code, message });
+		else respond(false, undefined, { code, message });
+	}
+
+	// 设备码登录成功：逐个写凭据 + 有 configPatch 就深合并进 cfg（hot-reload，零打断），恰好 respond 一次
+	async function persistDeviceCodeSuccess({ provider, result, loginId, phase1Sent, respond }) {
+		try {
+			const profileIds = [];
+			for (const profile of result.profiles) {
+				// 同一 auth-profiles 文件，顺序写避免锁竞争（device-code 通常仅 1 个 profile）
+				 
+				const r = await sdk.upsertAuthProfileWithLock({
+					profileId: profile.profileId,
+					credential: profile.credential,
+					agentDir: resolveAgentDir(),
+				});
+				if (r === null) {
+					respondDeviceFailure(respond, phase1Sent, 'IO_FAILED', 'failed to write auth-profiles store');
+					logRemote(`providerAuth.deviceCode.io-failed provider=${provider} loginId=${loginId} stage=credential`);
+					return;
+				}
+				profileIds.push(profile.profileId);
+			}
+			const patch = result.configPatch;
+			if (patch && typeof patch === 'object' && !Array.isArray(patch)) {
+				// configPatch 是 provider 自带的 onboarding 默认（如 codex 写 agents.defaults.models 别名）；
+				// 深合并保留其它 provider，afterWrite:auto 走 hot-reload 不重启（与 MiniMax 写 cfg 一致）
+				await sdk.mutateConfigFile({
+					afterWrite: { mode: 'auto' },
+					mutate(draft) { deepMergeInto(draft, patch); },
+				});
+			}
+			respond(true, { status: 'ok', provider, profileIds });
+			logRemote(`providerAuth.deviceCode.ok provider=${provider} loginId=${loginId} profiles=${profileIds.length}`);
+		}
+		catch (err) {
+			respondDeviceFailure(respond, phase1Sent, 'IO_FAILED', String(err?.message ?? err));
+			logRemote(`providerAuth.deviceCode.io-failed provider=${provider} loginId=${loginId} stage=config msg=${String(err?.message ?? err)}`);
+		}
+	}
+
+	async function loginOauthDeviceCode({ provider, respond }) {
+		try {
+			const config = resolveConfig() ?? {};
+			let providers;
+			try {
+				// resolveProviders 可能 async（生产侧惰性加载 catalog-runtime SDK 后再 resolve）
+				providers = await resolveProviders({ config, providerRefs: [provider] });
+			}
+			catch (err) {
+				// 加载器异常（SDK import 失败 / resolvePluginProviders 抛错）：phase-1 之前，单帧错误
+				respondIoFailed(respond, err);
+				return;
+			}
+			const method = findDeviceCodeMethod(providers, provider);
+			if (!method) {
+				respond(false, undefined, {
+					code: 'NOT_FOUND',
+					message: `provider "${provider}" has no device-code login method`,
+				});
+				return;
+			}
+
+			const loginId = genLoginId();
+			const abortController = new AbortController();
+			let phase1Sent = false;
+
+			// run 内 prompter.note 吐出「含 URL 的验证 note」→ 触发 phase-1 accepted（仅一次）。
+			// 结构化字段抠不到给 null，rawText 永远带上全文交前端兜底。登记发生在 respond accepted 之前，
+			// 让紧随其后的 cancelOauth 一定能按 loginId 找到该登录。
+			const ctx = makeDeviceCodeCtx({
+				config,
+				agentDir: resolveAgentDir(),
+				onNote: (text) => {
+					if (phase1Sent || !isVerificationNote(text)) return;
+					phase1Sent = true;
+					registry.registerLogin(loginId, { abortController });
+					const { verificationUri, userCode } = extractVerification(text);
+					respond(true, {
+						status: 'accepted',
+						loginId,
+						provider,
+						verificationUri,
+						userCode,
+						rawText: text,
+					});
+				},
+			});
+
+			// 起 run（不 await 整体）；run 仅跑一次，resolve/reject 都到这里恰好终态一次。
+			// run 无 abort 钩子：取消停不掉上游后台轮询，cancelOauth 只 abort 信号 → run 到期自己 settle
+			// 时这里识别 aborted、回 cancelled 终态、不写凭据（终态必达 + 清理，不做复查骚操作）。
+			async function runAndSettle() {
+				let result;
+				let runErr;
+				try {
+					result = await Promise.resolve().then(() => method.run(ctx));
+				}
+				catch (err) {
+					runErr = err;
+				}
+				if (phase1Sent) registry.removeLogin(loginId);
+
+				if (runErr) {
+					respondDeviceFailure(respond, phase1Sent, 'OAUTH_FAILED', String(runErr?.message ?? runErr));
+					logRemote(`providerAuth.deviceCode.error provider=${provider} loginId=${loginId} stage=run msg=${String(runErr?.message ?? runErr)}`);
+					return;
+				}
+				if (abortController.signal.aborted) {
+					respondDeviceFailure(respond, phase1Sent, 'OAUTH_CANCELLED', `device-code login for ${provider} was cancelled`, 'cancelled');
+					logRemote(`providerAuth.deviceCode.cancelled provider=${provider} loginId=${loginId}`);
+					return;
+				}
+				// 上游会把中途失败吞成空 profiles（如 copilot access_denied / expired）→ 空即失败
+				const profiles = Array.isArray(result?.profiles) ? result.profiles : [];
+				if (profiles.length === 0) {
+					respondDeviceFailure(respond, phase1Sent, 'OAUTH_FAILED', `device-code login for ${provider} returned no credentials`);
+					logRemote(`providerAuth.deviceCode.error provider=${provider} loginId=${loginId} stage=empty-profiles`);
+					return;
+				}
+				await persistDeviceCodeSuccess({ provider, result, loginId, phase1Sent, respond });
+			}
+
+			scheduleBackground(runAndSettle());
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	// 登录入口路由：minimax-portal（或缺省，向后兼容）→ B2 自家流；其它任何带 device_code 方法的
+	// provider → 通用 B1 驱动。不针对 codex/copilot 硬编码，后续 OpenClaw 新增 device_code provider 自动适用。
+	async function loginOauth({ params, respond }) {
+		const provider = params?.provider;
+		// provider 给了就必须是非空串（缺省保留给 MiniMax B2 向后兼容）：空串 / 非串在边界挡掉，
+		// 不让其漏进 B1 当 NOT_FOUND，也不把非串塞给上游 resolvePluginProviders（providerRefs 期望串）
+		if (provider !== undefined && !isNonEmptyString(provider)) {
+			respondInvalid(respond, 'provider must be a non-empty string when provided');
+			return;
+		}
+		if (provider === undefined || provider === PORTAL_PROVIDER_ID) {
+			return loginOauthMiniMax({ params, respond });
+		}
+		return loginOauthDeviceCode({ provider, respond });
+	}
+
 	async function cancelOauth({ params, respond }) {
 		try {
 			const loginId = params?.loginId;
@@ -362,13 +568,15 @@ function isWellFormedCredential(cred) {
 }
 
 /**
- * 把单条 credential 转成 list RPC 出参元素。
+ * 把单条账本 credential 转成 list RPC 出参元素（source='profile'，可撤销）。
  * 关键：原始 key / token / OAuth access/refresh 绝不出 handler。
  */
 function toListEntry(profileId, cred, formatApiKeyPreview) {
 	const out = {
 		profileId,
 		provider: cred.provider,
+		source: 'profile',
+		removable: true,
 		type: cred.type,
 	};
 	if (cred.type === 'api_key' && typeof cred.key === 'string' && cred.key.length > 0) {
@@ -381,3 +589,78 @@ function toListEntry(profileId, cred, formatApiKeyPreview) {
 	}
 	return out;
 }
+
+/**
+ * 内联来源：cfg.models.providers 里 apiKey 配了的节点（用户手写 / OAuth 写的节点若带 key）。
+ * 只看 apiKey 字段——OAuth 登录写的节点无 apiKey，天然不会被误收（docs § 6.14）。
+ * @param {object} cfg
+ * @param {object} deps - { hasConfiguredSecretInput, formatApiKeyPreview }
+ * @returns {object[]} source='inline'、removable=true 的出参元素
+ */
+function listInlineEntries(cfg, { hasConfiguredSecretInput, formatApiKeyPreview }) {
+	const out = [];
+	const providers = cfg?.models?.providers;
+	if (!providers || typeof providers !== 'object' || Array.isArray(providers)) return out;
+	for (const [provider, node] of Object.entries(providers)) {
+		if (!node || typeof node !== 'object') continue;
+		if (!hasConfiguredSecretInput(node.apiKey)) continue;
+		const entry = {
+			profileId: `${provider}#inline`,
+			provider,
+			source: 'inline',
+			removable: true,
+			type: 'api_key',
+		};
+		// 仅明文 string key 给预览；{env}/{file} 引用形态不预览（避免怪异展示）
+		if (typeof node.apiKey === 'string' && !node.apiKey.startsWith('{')) {
+			entry.keyPreview = formatApiKeyPreview(node.apiKey);
+		}
+		out.push(entry);
+	}
+	return out;
+}
+
+/**
+ * env 来源：对候选 provider 集合探测环境变量；仅当该 provider 未被账本/内联覆盖（sole source）才列，
+ * 避免与已可撤销的行重复添噪。env 来源不可撤销（removable=false），仅展示。
+ * @param {Iterable<string>} candidates - 候选 provider（账本∪内联∪主模型段）
+ * @param {Set<string>} covered - 已由账本/内联列出的 provider（原始拼写）
+ * @param {object} deps - { resolveEnvApiKey }
+ * @returns {object[]} source='env'、removable=false 的出参元素
+ */
+function listEnvEntries(candidates, covered, { resolveEnvApiKey }) {
+	const out = [];
+	const seen = new Set();
+	for (const provider of candidates) {
+		if (!provider || covered.has(provider) || seen.has(provider)) continue;
+		const hit = resolveEnvApiKey(provider);
+		if (!hit?.apiKey) continue;
+		seen.add(provider);
+		out.push({
+			profileId: `${provider}#env`,
+			provider,
+			source: 'env',
+			removable: false,
+			type: 'api_key',
+		});
+	}
+	return out;
+}
+
+/**
+ * 收集 default + 各 agent 主模型的 provider 段（去重交给调用方的 Set）。
+ * 复用 model-default/resolve.js，不重复造主模型读取逻辑。
+ * @param {object} cfg
+ * @returns {string[]}
+ */
+function collectPrimaryProviderSegments(cfg) {
+	const all = listAllPrimaries(cfg);
+	const segs = [];
+	const push = (primary) => {
+		const seg = providerSegmentOf(primary);
+		if (seg) segs.push(seg);
+	};
+	push(all.default.primary);
+	for (const v of Object.values(all.agents)) push(v.primary);
+	return segs;
+}

package/src/provider-auth/index.js

@@ -24,6 +24,7 @@ import { mainAgentDir } from '../claw-paths.js';
 // 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _sdkPromise;
 let _configMutationPromise;
+let _catalogRuntimePromise;
 
 // 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入，
 // 因为 OpenClaw plugin loader 只扫入口源码识别 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；
@@ -39,12 +40,18 @@ function defaultLoadConfigMutation() {
 	return _configMutationPromise;
 }
 
+function defaultLoadProviderCatalogRuntime() {
+	_catalogRuntimePromise ??= import('openclaw/plugin-sdk/provider-catalog-runtime');
+	return _catalogRuntimePromise;
+}
+
 /**
  * 测试辅助：清掉懒加载 SDK 缓存。
  */
 export function __resetSdkCache() {
 	_sdkPromise = undefined;
 	_configMutationPromise = undefined;
+	_catalogRuntimePromise = undefined;
 }
 
 /**
@@ -58,14 +65,31 @@ export function __resetSdkCache() {
  * @param {Function} [opts.resolveAgentDir] - 覆盖 agentDir 解析（默认 mainAgentDir）
  * @param {Function} [opts.loadSdk] - 必传（生产由入口注入字面量 dynamic import）；缺省回退仅为测试兜底
  * @param {Function} [opts.loadConfigMutation] - 必传（同上，OAuth 写 cfg 用）
+ * @param {Function} [opts.loadProviderCatalogRuntime] - 必传（同上，通用 device-code 登录 B1 拿 resolvePluginProviders 用）
  * @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 loadProviderCatalogRuntime = opts.loadProviderCatalogRuntime ?? defaultLoadProviderCatalogRuntime;
 	const registry = opts.registry ?? { registerLogin, getLogin, removeLogin };
 
+	// catalog-runtime 仅通用 device-code 登录（B1）才需要，独立惰性加载——不耦合进 getHandlers
+	// 的 Promise.all，避免 setApiKey / list / remove / minimax-oauth 因这个 SDK 子入口缺失而连带失败。
+	let catalogRuntimePromise;
+	const resolveProviders = async ({ config, providerRefs }) => {
+		catalogRuntimePromise ??= loadProviderCatalogRuntime();
+		const catalogRuntime = await catalogRuntimePromise;
+		// 铁律：activate:false —— 只读拿 method.run，不激活 provider，零副作用（不动 gateway 活跃插件名册）。
+		return catalogRuntime.resolvePluginProviders({
+			config,
+			providerRefs,
+			activate: false,
+			mode: 'runtime',
+		});
+	};
+
 	let handlersPromise;
 	async function getHandlers() {
 		if (!handlersPromise) {
@@ -83,7 +107,7 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 					generatePkce: providerAuthSdk.generatePkceVerifierChallenge,
 					toForm: providerAuthSdk.toFormUrlEncoded,
 				});
-				return buildProviderAuthHandlers({ sdk, resolveAgentDir, oauth, registry });
+				return buildProviderAuthHandlers({ sdk, resolveAgentDir, oauth, registry, resolveProviders });
 			})();
 		}
 		return handlersPromise;

package/src/realtime-bridge.js

@@ -714,8 +714,9 @@ export class RealtimeBridge {
 		try {
 			const authToken = this.__resolveGatewayAuthToken();
 			const params = {
+				// 声明支持 v3–v4：OpenClaw 网关自 v4 起要求协议范围含 4，旧网关仍可协商回 v3
 				minProtocol: 3,
-				maxProtocol: 3,
+				maxProtocol: 4,
 				client: {
 					id: 'gateway-client',
 					version: this.__pluginVersion ?? 'unknown',

package/src/session-manager/manager.js

@@ -300,8 +300,18 @@ export function createSessionManager(options = {}) {
 	 * 按 sessionId 获取消息，返回完整 JSONL 行级结构。
 	 * 只返回 type==="message" 且有合法 message.role 的行。
 	 * limit 语义：不传/null/非 number/NaN/Infinity/<1 → 返回全部；>=1 的有限 number → 取最后 Math.trunc(limit) 条。无默认/最大值。
+	 *
+	 * 取不到正文时用错误码区分成因，调用方据此精确处置（不再统一塌缩成空数组）：
+	 * - transcript 文件不存在（裸名 / .reset. / .deleted. 变体全无）→ 抛 code='NOT_FOUND'
+	 * - 文件在但一行都解析不出（非空却零行成功 JSON.parse）→ 抛 code='PARSE_FAILED'
+	 * - 真·读盘 IO 错误：readTranscriptText 原样上抛（由 RPC 层映射）
+	 * 空文件 / 全空白行（含仅含空格、制表符的行）/ 文件在但无 message 行 → 正常返回 { messages: [] }（良性空，非失败）。
+	 *
+	 * 部分坏行（有成功解析的行 + 个别 JSON.parse 失败）走容错：返回解析出的消息，
+	 * 并在 payload 平行附 badLines（仅 >0 时）记录坏行原文供排障，不丢整段。
+	 * badLines[].index 是坏行在「非空白内容行」序列中的 0-based 位置（空白行已被跳过，故非原始文件行号）。
 	 * @param {{ sessionId: string, agentId?: string, limit?: number }} params
-	 * @returns {Promise<{ messages: object[] }>}
+	 * @returns {Promise<{ messages: object[], badLines?: { index: number, raw: string, error: string }[] }>}
 	 */
 	async function getById(params = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
@@ -313,25 +323,42 @@ export function createSessionManager(options = {}) {
 		const limitNum = useLimit ? Math.trunc(params.limit) : 0;
 		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
-			return { messages: [] };
+			throw Object.assign(new Error(`session transcript not found: ${sessionId}`), { code: 'NOT_FOUND' });
 		}
 
 		const text = await readTranscriptText(file);
 		const messages = [];
+		const badLines = [];
+		// parseOk 在 JSON.parse 成功后立即 +1，必须在 type 过滤之前——
+		// 否则"全合法 JSON 但无 message 行"会被错判 PARSE_FAILED
+		let parseOk = 0;
+		let index = -1;
 		for await (const line of iterTextLines(text)) {
+			// 纯空白行（仅空格/制表符等，iterTextLines 只跳零长度段）视同空行：
+			// 既不计入 parseOk 也不进 badLines，保证"全空白文件 → 良性空"不变量、不误判 PARSE_FAILED
+			if (line.trim() === '') continue;
+			index++;
+			let row;
 			try {
-				const row = JSON.parse(line);
-				if (row?.type !== 'message') continue;
-				const msg = row?.message;
-				if (!msg || typeof msg !== 'object' || !msg.role) continue;
-				messages.push(row);
+				row = JSON.parse(line);
 			}
 			catch (err) {
+				badLines.push({ index, raw: line, error: String(err?.message ?? err) });
 				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
+				continue;
 			}
+			parseOk++;
+			if (row?.type !== 'message') continue;
+			const msg = row?.message;
+			if (!msg || typeof msg !== 'object' || !msg.role) continue;
+			messages.push(row);
+		}
+		// 非空文件却一行都没解析出 = 整文损坏；空 / 全空白文件（含纯空格行）跳过后零内容行 → parseOk=0 且 badLines=[]，不算损坏
+		if (parseOk === 0 && badLines.length > 0) {
+			throw Object.assign(new Error(`session transcript unparseable: ${sessionId}`), { code: 'PARSE_FAILED' });
 		}
 		const sliced = (useLimit && messages.length > limitNum) ? messages.slice(-limitNum) : messages;
-		return { messages: sliced };
+		return badLines.length > 0 ? { messages: sliced, badLines } : { messages: sliced };
 	}
 
 	return { listAll, listAllEntries, get, getById };

package/src/utils/deep-merge.js

@@ -0,0 +1,40 @@
+/**
+ * deep-merge.js —— 把 patch 递归并入 target（就地修改）
+ *
+ * 语义（与上游 config patch 合并对齐 openclaw-repo/src/plugins/provider-auth-choice-helpers.ts
+ * 的 mergeConfigPatch）：
+ * - 两边都是 plain object → 递归并入；
+ * - 否则（数组 / 原始值 / null）→ patch 值直接覆盖；
+ * - 原型污染键（__proto__ / constructor / prototype）一律跳过。
+ *
+ * 用途：provider 登录返回的 configPatch（Partial<OpenClawConfig>）合并进 mutateConfigFile 的
+ * draft——不能裸 Object.assign（会把 models / agents 整段顶掉），必须逐层深合并保留其它 provider。
+ */
+
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function isPlainObject(v) {
+	return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * 把 patch 深合并进 target（就地修改 target）。
+ *
+ * target 非 plain object 时不做任何事（无处可并）。
+ *
+ * @param {object} target - 被修改的目标对象（如 mutateConfigFile 的 draft）
+ * @param {unknown} patch - 要并入的补丁；非 plain object 时整体忽略
+ */
+export function deepMergeInto(target, patch) {
+	if (!isPlainObject(target) || !isPlainObject(patch)) return;
+	for (const [key, value] of Object.entries(patch)) {
+		if (BLOCKED_KEYS.has(key)) continue;
+		if (isPlainObject(value)) {
+			if (!isPlainObject(target[key])) target[key] = {};
+			deepMergeInto(target[key], value);
+		}
+		else {
+			target[key] = value;
+		}
+	}
+}