@coclaw/openclaw-coclaw 0.25.0 → 0.26.0

package/index.js

@@ -810,11 +810,14 @@ const plugin = {
 			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）
+			// 驱动 provider 自带的 device_code 登录方法（codex/copilot 及以后任意 device_code provider）；
+			// 同时供 providerAuth.catalog 拿 setup 全集（mode:'setup'）
 			loadProviderCatalogRuntime: () => import('openclaw/plugin-sdk/provider-catalog-runtime'),
+			// agent-runtime 供 providerAuth.catalog 的 hasCred 别名归一基座 id（resolveProviderIdForAuth）
+			loadAgentRuntime: () => import('openclaw/plugin-sdk/agent-runtime'),
 		});
 
-		// 模型默认配置 RPC（coclaw.model.set / list / listUsable）。三个 SDK 子入口的字面量
+		// 模型默认配置 RPC（coclaw.model.set / list / listAvailable + listUsable 过渡别名）。三个 SDK 子入口的字面量
 		// dynamic import 必须留在本入口源码——OpenClaw plugin loader 只扫入口源码
 		// 命中 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；藏在子模块的字面量
 		// loader 看不到 → 原生 Node 解析必败。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",
@@ -55,6 +55,10 @@
     "verify": "pnpm check && pnpm test",
     "link": "bash ./scripts/link.sh",
     "unlink": "bash ./scripts/unlink.sh",
+    "wt:up": "bash ./scripts/worktree-gateway.sh up",
+    "wt:reload": "bash ./scripts/worktree-gateway.sh reload",
+    "wt:call": "bash ./scripts/worktree-gateway.sh call",
+    "wt:down": "bash ./scripts/worktree-gateway.sh down",
     "install:npm": "bash ./scripts/install-npm.sh",
     "uninstall:npm": "bash ./scripts/uninstall-npm.sh",
     "release:pre": "bash ./scripts/prerelease.sh",

package/src/model-default/handlers.js

@@ -1,25 +1,28 @@
 /**
- * model-default/handlers.js —— coclaw.model.set / list / listUsable 三个 RPC 的纯函数实现
+ * model-default/handlers.js —— coclaw.model.set / list / listAvailable 三个 RPC 的纯函数实现
+ *   （listAvailable 即原 listUsable 改名；index.js 把 listUsable 留作过渡别名映到同一 handler）
  *
  * 设计要点（详见 docs/model-config-api.md § 3）：
  * - DI 注入 sdk（mutateConfigFile / loadModelCatalog / provider-auth 凭据探针 / resolveProviderIdForAuth）
  *   + loadConfig + resolveAgentDir，便于单测；产线注入在 ./index.js
  * - **出参不加 status wrap**（gateway-method-design skill 约定）：set → {}；list → { default, agents }；
- *   listUsable → { byProvider, configuredProviders }
+ *   listAvailable → { byProvider }（configuredProviders 已迁出，UI 加 provider 排除改吃 catalog.hasCred）
  * - 错误码只用 INVALID_ARGS / IO_FAILED，参考 provider-auth/handlers.js
  *   既有 plugin 的 respondError 用 INTERNAL_ERROR 与本节契约不一致，所以本模块自带局部 helper
  * - set 校验 fail-fast 顺序：params shape → 拒未知字段 → agentId → primary 类型 → primary 形态
  *   （纯字符串：含 '/'、'/' 不在端点；不依赖 cfg）→ loadConfig → 凭据门 → 存在性
  *   形态校验**前置在 loadConfig 之前**，cfg 不可读时非法形态仍是 INVALID_ARGS 而非 IO_FAILED
  * - 凭据门 + 选模型器枚举 + list 信号全部走统一别名感知原语（resolve.js），杜绝跨界面口径分叉（§ 3.2.1）
- * - set 存在性 + listUsable 枚举走同一干净目录 loadModelCatalog({readOnly:true})：选得到 ⇒ 设得上（红线天然成立）
+ * - set 存在性 + listAvailable 枚举走同一目录源 loadModelCatalog({readOnly:false})：选得到 ⇒ 设得上（红线天然成立）。
+ *   用 readOnly:false（含 manifest 合并）才带进 openai-codex/* 等 manifest-only provider；readOnly:true 只读落盘，
+ *   这类从不落盘的 provider 缺失（oauth 已授权却选不出，本次回归根因）。
  */
 
 import { listAllPrimariesWithCredentials, computeProviderUsable, enumerateUsableModels } from './resolve.js';
 import { writePrimary } from './persist.js';
 
 const SET_ALLOWED_KEYS = new Set(['agentId', 'primary']);
-const LISTUSABLE_ALLOWED_KEYS = new Set(['agentId']);
+const LISTAVAILABLE_ALLOWED_KEYS = new Set(['agentId']);
 
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_ARGS', message });
@@ -50,7 +53,7 @@ function parseProviderModel(primary) {
 }
 
 /**
- * 构造 set / listUsable 用的统一别名感知凭据 deps。
+ * 构造 set / listAvailable 用的统一别名感知凭据 deps。
  * @param {object} sdk
  * @param {string} agentDir
  * @returns {object}
@@ -66,15 +69,16 @@ function buildCredDeps(sdk, agentDir) {
 }
 
 /**
- * cfg 相关的 primary 校验：凭据门 + 干净目录存在性。
+ * 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 是写操作，失败安全为先）。
+ * - 存在性走目录源 loadModelCatalog({readOnly:false})（与选模型器枚举同源 → 「选得到设不上」红线天然成立）；
+ *   用 readOnly:false（含 manifest 合并）才有 openai-codex/* 这类 manifest-only provider（readOnly:true 只读落盘缺它们）。
+ *   它返回全量 manifest，但与凭据门联用并不过松——无凭据 provider 仍被门挡住；且非 buildModelsProviderData，无幽灵注入。
+ *   整体抛错由外层 catch 映射 IO_FAILED（set 是写操作，失败安全为先）。
  *
  * @returns {Promise<string|null>} 错误 message；null 表通过
  */
@@ -82,7 +86,7 @@ async function validateProviderCredAndCatalog({ provider, model, primary, cfg, s
 	if (!computeProviderUsable(primary, cfg, deps)) {
 		return `provider "${provider}" has no usable credential`;
 	}
-	const entries = await sdk.loadModelCatalog({ readOnly: true });
+	const entries = await sdk.loadModelCatalog({ readOnly: false });
 	const exists = Array.isArray(entries)
 		&& entries.some((e) => e && e.provider === provider && e.id === model);
 	if (!exists) {
@@ -92,19 +96,19 @@ async function validateProviderCredAndCatalog({ provider, model, primary, cfg, s
 }
 
 /**
- * 构造 set / list / listUsable 三个 handler。
+ * 构造 set / list / listAvailable 三个 handler。
  *
  * @param {object} opts
  * @param {object} opts.sdk
  * @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.loadModelCatalog - openclaw/plugin-sdk/agent-runtime（set 存在性 + listAvailable 枚举的目录源）
  * @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.ensureAuthProfileStore - openclaw/plugin-sdk/provider-auth（账本非空判定）
  * @param {Function} opts.sdk.resolveProviderIdForAuth - openclaw/plugin-sdk/agent-runtime（别名归一）
  * @param {Function} opts.loadConfig - 返回当前 cfg snapshot；缺失时返回 null
  * @param {Function} opts.resolveAgentDir - 返回 agent /agent 子目录全路径（默认 main agent；agentId 贯穿）
- * @returns {{ set: Function, list: Function, listUsable: Function }}
+ * @returns {{ set: Function, list: Function, listAvailable: Function }}
  */
 export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir }) {
 	async function set({ params, respond }) {
@@ -204,14 +208,14 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 		}
 	}
 
-	async function listUsable({ params, respond }) {
+	async function listAvailable({ 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)) {
+				if (!LISTAVAILABLE_ALLOWED_KEYS.has(key)) {
 					respondInvalid(respond, `unknown field: ${key}`);
 					return;
 				}
@@ -233,16 +237,12 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 			// 故四个消费点在产线天然同 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 = [];
-			}
+			// 目录源 loadModelCatalog({readOnly:false})：含 manifest 合并，才有 openai-codex/* 这类 manifest-only provider
+			// （readOnly:true 只读落盘缺它们 → oauth 已授权却选不出，本次回归根因）。
+			// 抛错（罕见，如 runtime config 取不到）→ 走外层 catch 映射 IO_FAILED，不吞成空 entries：
+			// byProvider 同时驱动前端 primary 有效性（计算属性），把"清单没加载出来"伪装成"权威空清单"会让前端
+			// 误报主模型失效。如实暴露失败 → UI 维持 available=null="先不下结论"，与"真空（无凭据）"区分开。
+			const entries = await sdk.loadModelCatalog({ readOnly: false });
 
 			respond(true, enumerateUsableModels(entries, cfg, deps));
 		}
@@ -251,5 +251,5 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 		}
 	}
 
-	return { set, list, listUsable };
+	return { set, list, listAvailable };
 }

package/src/model-default/index.js

@@ -1,5 +1,6 @@
 /**
- * model-default 注册入口 —— 把 coclaw.model.set / list / listUsable 接到 gateway。
+ * model-default 注册入口 —— 把 coclaw.model.set / list / listAvailable 接到 gateway
+ *（listAvailable 即原 listUsable 改名；listUsable 作过渡别名继续注册、映到同一 handler）。
  *
  * 设计（同 provider-auth/index.js）：
  * - 三个 SDK 子入口（config-mutation / provider-auth / agent-runtime）懒加载，
@@ -34,7 +35,7 @@ function defaultLoadProviderAuth() {
 }
 function defaultLoadAgentRuntime() {
 	// agent-runtime barrel 同时给：resolveProviderIdForAuth（别名归一）+ loadModelCatalog（干净目录，
-	// set 存在性 / listUsable 选模型器枚举同源）。barrel re-export provider-auth-aliases.js + model-catalog.js。
+	// set 存在性 / listAvailable 选模型器枚举同源）。barrel re-export provider-auth-aliases.js + model-catalog.js。
 	_agentRuntimeP ??= import('openclaw/plugin-sdk/agent-runtime');
 	return _agentRuntimeP;
 }
@@ -49,7 +50,8 @@ export function __resetSdkCaches() {
 }
 
 /**
- * 在 gateway api 上注册 `coclaw.model.set` / `coclaw.model.list` / `coclaw.model.listUsable`。
+ * 在 gateway api 上注册 `coclaw.model.set` / `coclaw.model.list` / `coclaw.model.listAvailable`
+ *（外加过渡别名 `coclaw.model.listUsable`，与 listAvailable 映同一 handler）。
  *
  * 仅 `register(api)` 的 `if (api.registrationMode === 'full')` 分支调；
  * 其它 mode 注册副作用违规（参 plugins/openclaw/CLAUDE.md "Service / register 副作用边界"）。
@@ -80,13 +82,13 @@ export function registerModelDefaultHandlers(api, opts = {}) {
 				]);
 				const sdk = {
 					mutateConfigFile: configMutation.mutateConfigFile,
-					// 干净目录（set 存在性 + listUsable 枚举同源）：agent-runtime barrel re-export model-catalog.js
+					// 干净目录（set 存在性 + listAvailable 枚举同源）：agent-runtime barrel re-export model-catalog.js
 					loadModelCatalog: agentRuntime.loadModelCatalog,
-					// 凭据信号（providerUsable / hasAnyUsableCredential / 凭据门 / configuredProviders）
+					// 凭据信号（providerUsable / hasAnyUsableCredential / 凭据门）
 					isProviderApiKeyConfigured: providerAuth.isProviderApiKeyConfigured,
 					hasConfiguredSecretInput: providerAuth.hasConfiguredSecretInput,
 					ensureAuthProfileStore: providerAuth.ensureAuthProfileStore,
-					// 别名归一（内联凭据信号 + 选模型器枚举 + configuredProviders）
+					// 别名归一（内联凭据信号 + 选模型器枚举）
 					resolveProviderIdForAuth: agentRuntime.resolveProviderIdForAuth,
 				};
 				return buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir });
@@ -114,5 +116,7 @@ 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'));
+	api.registerGatewayMethod('coclaw.model.listAvailable', wrap('listAvailable'));
+	// 过渡别名：旧 UI 仍调 listUsable，映到同一 handler（决策1：纯过渡，不加任何额外兜底）
+	api.registerGatewayMethod('coclaw.model.listUsable', wrap('listAvailable'));
 }

package/src/model-default/resolve.js

@@ -123,21 +123,49 @@ function hasInlineKey(cfg, provider, deps) {
 	return false;
 }
 
+/**
+ * 某 provider（裸名）在自管账本里有没有任一来源凭据（oauth / token / api-key）。
+ * 别名感知：查询名与各 profile 的 cred.provider 两侧都过 resolveProviderIdForAuth 归一后比较，
+ * 与 computeConfiguredProviders 的账本口径一致（不校验 type：匹配到任一 well-formed profile 即算）。
+ * 补 isProviderApiKeyConfigured 只认 api-key 的缺口：纯 OAuth provider（codex / copilot 等设备码家族）
+ * 只有 oauth 凭据、无 key，旧逻辑两路皆 false 会被全组丢出 byProvider（见 changeset / TODO 根成因）。
+ * 归一为空串的 provider 不匹配（与 computeConfiguredProviders 的丢弃空 id 一致），
+ * 避免 whitespace-only 查询名与 whitespace-only cred 同归一到 '' 的误命中。
+ * @param {string} provider - 裸 provider 名
+ * @param {object} deps - { agentDir, ensureAuthProfileStore, resolveProviderIdForAuth }
+ * @returns {boolean}
+ */
+function hasLedgerCred(provider, deps) {
+	const store = deps.ensureAuthProfileStore(deps.agentDir, { allowKeychainPrompt: false });
+	if (!store || !store.profiles || typeof store.profiles !== 'object') return false;
+	const targetId = deps.resolveProviderIdForAuth(provider);
+	if (!targetId) return false;
+	for (const cred of Object.values(store.profiles)) {
+		if (!cred || typeof cred.provider !== 'string' || cred.provider.length === 0) continue;
+		if (deps.resolveProviderIdForAuth(cred.provider) === targetId) return true;
+	}
+	return false;
+}
+
 /**
  * 某 provider（裸名，无斜杠）有没有可用凭据 —— 统一别名感知原语。
- * 判定 = isProviderApiKeyConfigured（覆盖 env + 自管账本，别名归一其内部完成）
- *        ∪ hasInlineKey（内联 key，别名归一）。
- * 覆盖 env + 内联 + 账本 + 别名套餐；统一漏 IAM/本地（hasAuthForModelProvider 未导出 plugin-sdk，接受）。
- * 选模型器枚举 / model.set 门 / providerUsable / noKey 四个消费点同吃这一个原语，杜绝跨界面口径分叉。
+ * 判定 = isProviderApiKeyConfigured（env + 账本里的 api-key，别名归一其内部完成）
+ *        ∪ hasInlineKey（内联 key，别名归一）
+ *        ∪ hasLedgerCred（账本里的 oauth/token 等非 api-key 凭据，别名归一）。
+ * 覆盖 env + 内联 + 账本（api-key / oauth / token 全口径）+ 别名套餐；
+ * 统一漏 IAM/本地（hasAuthForModelProvider 未导出 plugin-sdk，接受）。
+ * 选模型器枚举 / model.set 门 / providerUsable 三个消费点同吃本原语；noKey 走姊妹原语
+ * computeHasAnyUsableCredential（同源探针 + 账本判定），口径与本原语对齐、不跨界面分叉。
  * @param {string|null} provider - 裸 provider 名（如 'openai' / 'volcengine-plan'）
  * @param {object} cfg
- * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, resolveProviderIdForAuth }
+ * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, ensureAuthProfileStore, 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);
+	if (hasInlineKey(cfg, provider, deps)) return true;
+	return hasLedgerCred(provider, deps);
 }
 
 /**
@@ -244,8 +272,8 @@ export function computeConfiguredProviders(cfg, deps) {
 }
 
 /**
- * 选模型器枚举（纯同步）：把干净目录按 entry.provider 分组，留 computeProviderUsableByName 为真的 provider。
- * catalogEntries 由调用方传入（子任务 2 的 handler 调 loadModelCatalog({readOnly:true}) 后传进来），
+ * 选模型器枚举（纯同步）：把目录源按 entry.provider 分组，留 computeProviderUsableByName 为真的 provider。
+ * catalogEntries 由调用方传入（handler 调 loadModelCatalog({readOnly:false}) 后传进来；含 manifest 才有 openai-codex/* 这类 manifest-only provider），
  * 本函数不自己 await loadModelCatalog；空 / 非数组 entries → 空 byProvider。
  * 变体 provider（如 volcengine-plan）经 manifest 目录行进入 entries、再经基座 key 别名感知保留；
  * 无凭据 provider 被丢（含幽灵——幽灵根本不在 loadModelCatalog 这个源里）。
@@ -254,10 +282,10 @@ export function computeConfiguredProviders(cfg, deps) {
  * （image_generation 等是网关响应的另一类型；imageModel 注入只在 buildModelsProviderData 尾部、不在此源），
  * 故无"纯图像/视频生成"条目混入；entry.input 是"输入"模态而非输出 kind，按它滤会误删多模态文本模型。
  *
- * @param {object[]} catalogEntries - loadModelCatalog({readOnly:true}) 的结果（ModelCatalogEntry[]）
+ * @param {object[]} catalogEntries - loadModelCatalog({readOnly:false}) 的结果（ModelCatalogEntry[]）
  * @param {object} cfg
  * @param {object} deps - { agentDir, isProviderApiKeyConfigured, hasConfiguredSecretInput, resolveProviderIdForAuth, ensureAuthProfileStore }
- * @returns {{ byProvider: Record<string, string[]>, configuredProviders: string[] }}
+ * @returns {{ byProvider: Record<string, string[]> }}
  */
 export function enumerateUsableModels(catalogEntries, cfg, deps) {
 	const grouped = new Map(); // provider -> Set<modelId>
@@ -279,7 +307,9 @@ export function enumerateUsableModels(catalogEntries, cfg, deps) {
 			byProvider[provider] = [...ids].sort();
 		}
 	}
-	return { byProvider, configuredProviders: computeConfiguredProviders(cfg, deps) };
+	// 只返回 byProvider；configuredProviders 已迁出（catalog 经 computeConfiguredProviders 单独算 hasCred，
+	// UI 加 provider 排除改吃 catalog.hasCred）。computeConfiguredProviders 仍具名导出供 catalog 复用。
+	return { byProvider };
 }
 
 /**

package/src/provider-auth/handlers.js

@@ -38,7 +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 { listAllPrimaries, providerSegmentOf, computeConfiguredProviders } from '../model-default/resolve.js';
 import { deepMergeInto } from '../utils/deep-merge.js';
 import {
 	isVerificationNote,
@@ -50,6 +50,14 @@ import {
 const VALID_CRED_TYPES = new Set(['api_key', 'oauth', 'token']);
 const PORTAL_PROFILE_ID = `${PORTAL_PROVIDER_ID}:default`;
 
+// catalog 出参的 authMethods 映射（一条规则零特判）：只露这三 kind，token/custom 不进出参。
+// kind 五值见上游 types.ts（oauth|api_key|token|device_code|custom）。
+const KIND_TO_AUTH_METHOD = {
+	device_code: 'oauth-device-code',
+	oauth: 'oauth-login',
+	api_key: 'api-key',
+};
+
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_ARGS', message });
 }
@@ -84,7 +92,9 @@ function isNonEmptyString(v) {
  * @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 }}
+ * @param {Function} [opts.resolveSetupProviders] - ({ config }) → ProviderPlugin[]；catalog 经它拿 setup 全集（mode:'setup', activate:false, cache:true，生产由入口注入），默认抛错
+ * @param {Function} [opts.loadProviderIdResolver] - () → Promise<resolveProviderIdForAuth>；catalog 算 hasCred 时别名归一基座 id（生产由入口惰性加载 agent-runtime），默认抛错
+ * @returns {{ setApiKey, list, remove, loginOauth, cancelOauth, catalog }}
  */
 export function buildProviderAuthHandlers({
 	sdk,
@@ -96,6 +106,8 @@ export function buildProviderAuthHandlers({
 	logRemote = remoteLog,
 	resolveConfig = getClawConfig,
 	resolveProviders = () => { throw new Error('provider catalog runtime not injected'); },
+	resolveSetupProviders = () => { throw new Error('provider catalog runtime not injected'); },
+	loadProviderIdResolver = () => { throw new Error('agent runtime not injected'); },
 }) {
 	// TODO: 将来若要支持"设默认模型 / 多账号顺序"等需要写 cfg 的操作，会撞上
 	// gateway 重启窗口的 UX 问题——参 docs/model-config-api.md § 3 / § 5（占位章节）。
@@ -553,7 +565,79 @@ export function buildProviderAuthHandlers({
 		}
 	}
 
-	return { setApiKey, list, remove, loginOauth, cancelOauth };
+	// --- provider 目录（能力 1）：枚举全集 provider + 各自认证方式 + 是否已配凭据 ---
+
+	// 无参；出参 { providers: [{ provider, authMethods, hasCred }] }（命名对象、不 wrap、不 undefined）。
+	// 数据源 = resolvePluginProviders(setup) 全集（含未配 provider）；authMethods 一条规则零特判
+	// （device_code/oauth/api_key 三 kind 露出，token/custom 不露，authMethods 空则该 provider 不进出参）；
+	// hasCred 复用 computeConfiguredProviders 三源（账本/内联/env）别名归一基座 id。
+	// 错误码：未知字段 → INVALID_ARGS（params:{} / undefined / null 都放行）；解析/凭据探针/store 读抛错 → IO_FAILED。
+	async function catalog({ params, respond }) {
+		try {
+			// 无参方法：params 缺省（undefined / null）或空对象都放行；带任何字段即未知字段。
+			if (params !== undefined && params !== null) {
+				if (typeof params !== 'object' || Array.isArray(params)) {
+					respondInvalid(respond, 'params must be an object');
+					return;
+				}
+				const keys = Object.keys(params);
+				if (keys.length > 0) {
+					respondInvalid(respond, `unknown field: ${keys[0]}`);
+					return;
+				}
+			}
+
+			const config = resolveConfig() ?? {};
+			// setup 全集（含未配）：activate:false 零副作用、cache:true 复用进程内发现缓存。生产由入口注入。
+			const providers = await resolveSetupProviders({ config });
+			// 别名归一基座 id（hasCred 计算用）：agent-runtime 惰性加载，失败走 IO_FAILED。
+			const resolveProviderIdForAuth = await loadProviderIdResolver();
+			// 三源 hasCred（账本/内联/env），全过 resolveProviderIdForAuth 归一基座 id。
+			const configuredSet = new Set(computeConfiguredProviders(config, {
+				agentDir: resolveAgentDir(),
+				isProviderApiKeyConfigured: sdk.isProviderApiKeyConfigured,
+				hasConfiguredSecretInput: sdk.hasConfiguredSecretInput,
+				ensureAuthProfileStore: sdk.ensureAuthProfileStore,
+				resolveProviderIdForAuth,
+			}));
+
+			const out = [];
+			for (const p of providers ?? []) {
+				const provider = p?.id;
+				if (typeof provider !== 'string' || provider.length === 0) continue;
+				const authMethods = mapAuthMethods(p.auth);
+				if (authMethods.length === 0) continue; // custom-only / token-only / 空 auth[] 自然排除
+				out.push({ provider, authMethods, hasCred: configuredSet.has(provider) });
+			}
+			respond(true, { providers: out });
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	return { setApiKey, list, remove, loginOauth, cancelOauth, catalog };
+}
+
+/**
+ * 把 provider 的 auth[] 映射成对外的 authMethods（catalog 用，一条规则零特判）：
+ * device_code→oauth-device-code、oauth→oauth-login、api_key→api-key；token/custom 不露。
+ * 保留 auth[] 出现顺序，按方法名去重（一 provider 可多入口、同 kind 多条只算一次）。
+ * @param {Array<{kind?:string}>} authArr - resolvePluginProviders 返回项的 auth 数组
+ * @returns {string[]}
+ */
+function mapAuthMethods(authArr) {
+	const out = [];
+	const seen = new Set();
+	if (!Array.isArray(authArr)) return out;
+	for (const a of authArr) {
+		const method = KIND_TO_AUTH_METHOD[a?.kind];
+		if (method && !seen.has(method)) {
+			seen.add(method);
+			out.push(method);
+		}
+	}
+	return out;
 }
 
 /**

package/src/provider-auth/index.js

@@ -25,6 +25,7 @@ import { mainAgentDir } from '../claw-paths.js';
 let _sdkPromise;
 let _configMutationPromise;
 let _catalogRuntimePromise;
+let _agentRuntimePromise;
 
 // 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入，
 // 因为 OpenClaw plugin loader 只扫入口源码识别 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；
@@ -45,6 +46,12 @@ function defaultLoadProviderCatalogRuntime() {
 	return _catalogRuntimePromise;
 }
 
+function defaultLoadAgentRuntime() {
+	// agent-runtime barrel 提供 resolveProviderIdForAuth（别名归一基座 id）——catalog 算 hasCred 用。
+	_agentRuntimePromise ??= import('openclaw/plugin-sdk/agent-runtime');
+	return _agentRuntimePromise;
+}
+
 /**
  * 测试辅助：清掉懒加载 SDK 缓存。
  */
@@ -52,6 +59,7 @@ export function __resetSdkCache() {
 	_sdkPromise = undefined;
 	_configMutationPromise = undefined;
 	_catalogRuntimePromise = undefined;
+	_agentRuntimePromise = undefined;
 }
 
 /**
@@ -65,7 +73,8 @@ 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 {Function} [opts.loadProviderCatalogRuntime] - 必传（同上，通用 device-code 登录 B1 + catalog setup 全集拿 resolvePluginProviders 用）
+ * @param {Function} [opts.loadAgentRuntime] - 必传（同上，catalog 算 hasCred 拿 resolveProviderIdForAuth 用）
  * @param {object} [opts.registry] - 覆盖 oauth-registry（默认模块级单例）
  */
 export function registerProviderAuthHandlers(api, opts = {}) {
@@ -73,9 +82,10 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 	const loadSdk = opts.loadSdk ?? defaultLoadSdk;
 	const loadConfigMutation = opts.loadConfigMutation ?? defaultLoadConfigMutation;
 	const loadProviderCatalogRuntime = opts.loadProviderCatalogRuntime ?? defaultLoadProviderCatalogRuntime;
+	const loadAgentRuntime = opts.loadAgentRuntime ?? defaultLoadAgentRuntime;
 	const registry = opts.registry ?? { registerLogin, getLogin, removeLogin };
 
-	// catalog-runtime 仅通用 device-code 登录（B1）才需要，独立惰性加载——不耦合进 getHandlers
+	// catalog-runtime 仅通用 device-code 登录（B1）与 catalog 才需要，独立惰性加载——不耦合进 getHandlers
 	// 的 Promise.all，避免 setApiKey / list / remove / minimax-oauth 因这个 SDK 子入口缺失而连带失败。
 	let catalogRuntimePromise;
 	const resolveProviders = async ({ config, providerRefs }) => {
@@ -89,6 +99,25 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 			mode: 'runtime',
 		});
 	};
+	// catalog 用的 setup 全集解析（独立于上面的 runtime 闭包——B1 登录仍走 runtime）：
+	// mode:'setup' 无条件返回全部 provider（含未配过的），activate:false 零副作用、cache:true 复用发现缓存。
+	const resolveSetupProviders = async ({ config }) => {
+		catalogRuntimePromise ??= loadProviderCatalogRuntime();
+		const catalogRuntime = await catalogRuntimePromise;
+		return catalogRuntime.resolvePluginProviders({
+			config,
+			activate: false,
+			cache: true,
+			mode: 'setup',
+		});
+	};
+	// agent-runtime 同样独立惰性加载（仅 catalog 的 hasCred 别名归一才需要），不耦合进 getHandlers。
+	let agentRuntimePromise;
+	const loadProviderIdResolver = async () => {
+		agentRuntimePromise ??= loadAgentRuntime();
+		const agentRuntime = await agentRuntimePromise;
+		return agentRuntime.resolveProviderIdForAuth;
+	};
 
 	let handlersPromise;
 	async function getHandlers() {
@@ -107,7 +136,15 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 					generatePkce: providerAuthSdk.generatePkceVerifierChallenge,
 					toForm: providerAuthSdk.toFormUrlEncoded,
 				});
-				return buildProviderAuthHandlers({ sdk, resolveAgentDir, oauth, registry, resolveProviders });
+				return buildProviderAuthHandlers({
+					sdk,
+					resolveAgentDir,
+					oauth,
+					registry,
+					resolveProviders,
+					resolveSetupProviders,
+					loadProviderIdResolver,
+				});
 			})();
 		}
 		return handlersPromise;
@@ -136,4 +173,5 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 	api.registerGatewayMethod('coclaw.providerAuth.remove', wrap('remove'));
 	api.registerGatewayMethod('coclaw.providerAuth.loginOauth', wrap('loginOauth'));
 	api.registerGatewayMethod('coclaw.providerAuth.cancelOauth', wrap('cancelOauth'));
+	api.registerGatewayMethod('coclaw.providerAuth.catalog', wrap('catalog'));
 }