@coclaw/openclaw-coclaw 0.24.0 → 0.25.0

package/index.js

@@ -814,14 +814,15 @@ const plugin = {
 			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.24.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 { listAllPrimariesWithCredentials } 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,42 +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（set 用）
- * @param {Function} opts.sdk.isProviderApiKeyConfigured - openclaw/plugin-sdk/provider-auth（list 凭据信号用）
- * @param {Function} opts.sdk.hasConfiguredSecretInput - openclaw/plugin-sdk/provider-auth（list 内联 key 判定）
- * @param {Function} opts.sdk.ensureAuthProfileStore - openclaw/plugin-sdk/provider-auth（list 账本非空判定）
+ * @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 }) {
@@ -92,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;
 				}
@@ -137,7 +159,7 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 					primary,
 					cfg,
 					sdk,
-					agentDir: resolveAgentDir(),
+					deps: buildCredDeps(sdk, resolveAgentDir()),
 				});
 				if (validationError) {
 					respondInvalid(respond, validationError);
@@ -171,21 +193,63 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 				respondIoFailed(respond, new Error('runtime config not available'));
 				return;
 			}
-			// 凭据信号（providerUsable / hasAnyUsableCredential）借三源判定：
-			// env+账本 走 isProviderApiKeyConfigured（别名归一化其内部完成），
-			// 内联 key 走 hasConfiguredSecretInput，账本非空走 ensureAuthProfileStore。
-			const deps = {
-				agentDir: resolveAgentDir(),
-				isProviderApiKeyConfigured: sdk.isProviderApiKeyConfigured,
-				hasConfiguredSecretInput: sdk.hasConfiguredSecretInput,
-				ensureAuthProfileStore: sdk.ensureAuthProfileStore,
-			};
-			respond(true, listAllPrimariesWithCredentials(cfg, deps));
+			// 凭据信号（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,33 +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,
-					// list 凭据信号用（provider-auth barrel 已加载，无需新增子入口字面量）
+					// 干净目录（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 });
 			})();
@@ -110,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

@@ -102,37 +102,95 @@ export function providerSegmentOf(primary) {
 }
 
 /**
- * 某 provider 是否配了内联 key（cfg.models.providers[provider].apiKey）。
+ * 某 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, hasConfiguredSecretInput) {
-	const entry = cfg?.models?.providers?.[provider];
-	return entry ? hasConfiguredSecretInput(entry.apiKey) : false;
+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;
 }
 
 /**
- * 该 primary 那家 provider 有没有可用凭据。
- * 判定 = isProviderApiKeyConfigured（覆盖环境变量 + 自管账本，别名归一化其内部完成）
- *        或 该 provider 配了内联 key。
+ * 某 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 - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput }
+ * @param {object} deps - 同 computeProviderUsableByName
  * @returns {boolean}
  */
 export function computeProviderUsable(primary, cfg, deps) {
-	const provider = providerSegmentOf(primary);
-	if (!provider) return false;
-	if (deps.isProviderApiKeyConfigured({ provider, agentDir: deps.agentDir })) return true;
-	return hasInlineKey(cfg, provider, deps.hasConfiguredSecretInput);
+	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 有没有任何可用凭据：自管账本非空 或 任一 provider 节点有内联 key。
- * 驱动 UI 的 noKey 引导。
+ * 这台 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 }
+ * @param {object} deps - { agentDir, ensureAuthProfileStore, hasConfiguredSecretInput, isProviderApiKeyConfigured }
  * @returns {boolean}
  */
 export function computeHasAnyUsableCredential(cfg, deps) {
@@ -144,14 +202,91 @@ export function computeHasAnyUsableCredential(cfg, deps) {
 			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 }
+ * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, ensureAuthProfileStore, resolveProviderIdForAuth }
  * @returns {{
  *   default: { primary: string|null, providerUsable: boolean },
  *   agents: Record<string, { primary: string|null, providerUsable: boolean }>,

package/src/provider-auth/handlers.js

@@ -38,6 +38,7 @@ import { PORTAL_PROVIDER_ID, CONFIG_DEFAULT_BASE_URL, VALID_REGIONS } from './mi
 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,
@@ -149,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) {
@@ -171,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);
@@ -528,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) {
@@ -547,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/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 };