@lark-apaas/openclaw-scripts-diagnose-cli 0.1.1-alpha.22 → 0.1.1-alpha.24

package/dist/index.cjs

@@ -31,6 +31,12 @@ let node_path = require("node:path");
 node_path = __toESM(node_path);
 let node_child_process = require("node:child_process");
 let node_crypto = require("node:crypto");
+node_crypto = __toESM(node_crypto);
+let node_stream = require("node:stream");
+let node_stream_promises = require("node:stream/promises");
+let node_assert = require("node:assert");
+node_assert = __toESM(node_assert);
+let _lark_apaas_http_client = require("@lark-apaas/http-client");
 //#region src/rule-engine/base.ts
 /** Abstract base class for all diagnose rules */
 var DiagnoseRule = class {
@@ -127,6 +133,14 @@ function isValidJWT(token) {
 		return false;
 	}
 }
+/**
+* Return `val` as a plain-object record (non-null, non-array object), or
+* `undefined` otherwise. Cheaper than `getNestedMap` when the value is already
+* at hand.
+*/
+function asRecord(val) {
+	return val != null && typeof val === "object" && !Array.isArray(val) ? val : void 0;
+}
 /** Set a deeply nested value, creating intermediate objects as needed. */
 function setNestedValue(obj, keys, value) {
 	let current = obj;
@@ -268,7 +282,7 @@ function findHighestBackup(backupFiles) {
 }
 let ConfigFileBackupRule = class ConfigFileBackupRule extends DiagnoseRule {
 	validate(ctx) {
-		const configPath = ctx.config.__configPath;
+		const { configPath } = ctx;
 		if (!configPath) return {
 			pass: false,
 			message: "configPath not provided"
@@ -281,7 +295,7 @@ let ConfigFileBackupRule = class ConfigFileBackupRule extends DiagnoseRule {
 		return { pass: true };
 	}
 	repair(ctx) {
-		const configPath = ctx.config.__configPath;
+		const { configPath } = ctx;
 		if (!configPath) return;
 		const best = findHighestBackup(findBackupFiles(configPath));
 		if (!best) return;
@@ -310,7 +324,7 @@ function hasBackupFiles(configPath) {
 }
 let ConfigFileMissingRule = class ConfigFileMissingRule extends DiagnoseRule {
 	validate(ctx) {
-		const configPath = ctx.config.__configPath;
+		const { configPath } = ctx;
 		if (!configPath) return {
 			pass: false,
 			message: "configPath not provided"
@@ -332,7 +346,7 @@ ConfigFileMissingRule = __decorate([Rule({
 //#region src/rules/config-syntax.ts
 let ConfigSyntaxRule = class ConfigSyntaxRule extends DiagnoseRule {
 	validate(ctx) {
-		const configPath = ctx.config.__configPath;
+		const { configPath } = ctx;
 		if (!fileExists(configPath)) return { pass: true };
 		try {
 			loadJSON5().parse(readFile(configPath));
@@ -600,27 +614,6 @@ FeishuChannelRule = _FeishuChannelRule = __decorate([Rule({
 	repairMode: "standard"
 })], FeishuChannelRule);
 //#endregion
-//#region src/rules/feishu-default-account.ts
-let FeishuDefaultAccountRule = class FeishuDefaultAccountRule extends DiagnoseRule {
-	validate(ctx) {
-		const feishu = getNestedMap(ctx.config, "channels", "feishu");
-		if (feishu && "defaultAccount" in feishu) return {
-			pass: false,
-			message: "channels.feishu.defaultAccount should be removed"
-		};
-		return { pass: true };
-	}
-	repair(ctx) {
-		const feishu = getNestedMap(ctx.config, "channels", "feishu");
-		if (feishu && "defaultAccount" in feishu) delete feishu.defaultAccount;
-	}
-};
-FeishuDefaultAccountRule = __decorate([Rule({
-	key: "feishu_default_account",
-	dependsOn: ["config_syntax_check"],
-	repairMode: "standard"
-})], FeishuDefaultAccountRule);
-//#endregion
 //#region src/rules/gateway.ts
 var _GatewayRule;
 let GatewayRule = class GatewayRule extends DiagnoseRule {
@@ -884,6 +877,217 @@ SecretsRule = __decorate([Rule({
 	skipWhen: ({ hasMiaoda, deps }) => !hasMiaoda || !deps.usesMiaodaSecretProvider
 })], SecretsRule);
 //#endregion
+//#region src/rules/cleanup-install-backup-dirs.ts
+const DIR_PREFIX = ".openclaw-install-";
+function resolveExtensionsDir(configPath) {
+	return node_path.default.join(node_path.default.dirname(configPath), "extensions");
+}
+function findLeftoverDirs(extensionsDir) {
+	if (!fileExists(extensionsDir)) return [];
+	let entries;
+	try {
+		entries = node_fs.default.readdirSync(extensionsDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((e) => e.isDirectory() && e.name.startsWith(DIR_PREFIX)).map((e) => node_path.default.join(extensionsDir, e.name));
+}
+let CleanupInstallBackupDirsRule = class CleanupInstallBackupDirsRule extends DiagnoseRule {
+	validate(ctx) {
+		const configPath = ctx.config.__configPath;
+		if (!configPath) return { pass: true };
+		const dirs = findLeftoverDirs(resolveExtensionsDir(configPath));
+		if (dirs.length === 0) return { pass: true };
+		return {
+			pass: false,
+			message: `extensions 目录下发现 ${dirs.length} 个 ${DIR_PREFIX}* 脏目录需要清理`
+		};
+	}
+	repair(ctx) {
+		const configPath = ctx.config.__configPath;
+		if (!configPath) return;
+		const dirs = findLeftoverDirs(resolveExtensionsDir(configPath));
+		const failures = [];
+		for (const dir of dirs) try {
+			node_fs.default.rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch (e) {
+			failures.push(`${node_path.default.basename(dir)}: ${e.message}`);
+		}
+		if (dirs.length > 0 && failures.length === dirs.length) throw new Error(`cleanup_install_backup_dirs: 全部清理失败: ${failures.join("; ")}`);
+	}
+};
+CleanupInstallBackupDirsRule = __decorate([Rule({
+	key: "cleanup_install_backup_dirs",
+	repairMode: "standard"
+})], CleanupInstallBackupDirsRule);
+//#endregion
+//#region src/rules/miaoda-official-plugins-install-spec-unlock.ts
+/**
+* Official miaoda-side plugins that must track manifest — version-locked specs
+* here block upgrades. Third-party / user-installed plugins are intentionally
+* out of scope (users may pin them deliberately).
+*/
+const OFFICIAL_PLUGIN_NAMES = new Set([
+	"openclaw-extension-miaoda",
+	"openclaw-extension-miaoda-coding",
+	"openclaw-guardian-plugin",
+	"openclaw-mem0-plugin",
+	"openclaw-lark"
+]);
+const LOCKED_NPM_SPEC = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*@[^@/:#\s]+$/i;
+function isLockedNpmSpec(spec) {
+	return typeof spec === "string" && LOCKED_NPM_SPEC.test(spec);
+}
+function unlockSpec(spec) {
+	const slash = spec.indexOf("/");
+	const cut = slash === -1 ? spec.indexOf("@") : spec.indexOf("@", slash + 1);
+	return spec.slice(0, cut);
+}
+/** Yield `[key, lockedSpec]` for every official-plugin install whose `spec` is locked. */
+function* iterLockedOfficialInstalls(config) {
+	const installs = getNestedMap(config, "plugins", "installs");
+	if (!installs) return;
+	for (const [key, entry] of Object.entries(installs)) {
+		if (!OFFICIAL_PLUGIN_NAMES.has(key)) continue;
+		const spec = asRecord(entry)?.spec;
+		if (isLockedNpmSpec(spec)) yield [key, spec];
+	}
+}
+let MiaodaOfficialPluginsInstallSpecUnlockRule = class MiaodaOfficialPluginsInstallSpecUnlockRule extends DiagnoseRule {
+	validate(ctx) {
+		const locked = [...iterLockedOfficialInstalls(ctx.config)].map(([k]) => k);
+		if (locked.length === 0) return { pass: true };
+		return {
+			pass: false,
+			message: "plugins.installs 中官方插件存在锁版本的 spec: " + locked.sort().join(",")
+		};
+	}
+	repair(ctx) {
+		for (const [key, spec] of iterLockedOfficialInstalls(ctx.config)) setNestedValue(ctx.config, [
+			"plugins",
+			"installs",
+			key,
+			"spec"
+		], unlockSpec(spec));
+	}
+};
+MiaodaOfficialPluginsInstallSpecUnlockRule = __decorate([Rule({
+	key: "miaoda_official_plugins_install_spec_unlock",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard"
+})], MiaodaOfficialPluginsInstallSpecUnlockRule);
+//#endregion
+//#region src/rules/old-miaoda-plugins-cleanup.ts
+const NEW_MIAODA = "openclaw-extension-miaoda";
+const OLD_PLUGIN_NAMES = Object.freeze([
+	"openclaw-feishu-greeting",
+	"openclaw-miaoda-keepalive",
+	"feishu-greeting",
+	"miaoda-keepalive"
+]);
+function getPluginMaps(config) {
+	const rawAllow = asRecord(config.plugins)?.allow;
+	return {
+		entries: getNestedMap(config, "plugins", "entries"),
+		installs: getNestedMap(config, "plugins", "installs"),
+		allow: Array.isArray(rawAllow) ? rawAllow : void 0
+	};
+}
+function getExtensionsDir(configPath) {
+	return node_path.default.join(node_path.default.dirname(configPath), "extensions");
+}
+function hasNewMiaoda({ entries, installs, allow }) {
+	return asRecord(entries?.[NEW_MIAODA]) != null || asRecord(installs?.[NEW_MIAODA]) != null || (allow?.includes(NEW_MIAODA) ?? false);
+}
+function findResiduals({ entries, installs, allow }, extensionsDir) {
+	return OLD_PLUGIN_NAMES.filter((name) => entries?.[name] != null || installs?.[name] != null || (allow?.includes(name) ?? false) || node_fs.default.existsSync(node_path.default.join(extensionsDir, name)));
+}
+let OldMiaodaPluginsCleanupRule = class OldMiaodaPluginsCleanupRule extends DiagnoseRule {
+	validate(ctx) {
+		const maps = getPluginMaps(ctx.config);
+		if (!hasNewMiaoda(maps)) return { pass: true };
+		const residuals = findResiduals(maps, getExtensionsDir(ctx.configPath));
+		if (residuals.length === 0) return { pass: true };
+		return {
+			pass: false,
+			message: "旧 miaoda 插件残留: " + residuals.sort().join(",")
+		};
+	}
+	repair(ctx) {
+		const maps = getPluginMaps(ctx.config);
+		if (!hasNewMiaoda(maps)) return;
+		const extensionsDir = getExtensionsDir(ctx.configPath);
+		const { entries, installs, allow } = maps;
+		const oldSet = new Set(OLD_PLUGIN_NAMES);
+		if (allow) for (let i = allow.length - 1; i >= 0; i--) {
+			const v = allow[i];
+			if (typeof v === "string" && oldSet.has(v)) allow.splice(i, 1);
+		}
+		for (const name of OLD_PLUGIN_NAMES) {
+			if (entries && name in entries) delete entries[name];
+			if (installs && name in installs) delete installs[name];
+			const target = node_path.default.join(extensionsDir, name);
+			const rel = node_path.default.relative(extensionsDir, target);
+			if (!rel || rel.startsWith("..") || node_path.default.isAbsolute(rel)) continue;
+			try {
+				node_fs.default.rmSync(target, {
+					recursive: true,
+					force: true
+				});
+			} catch (e) {
+				console.error(`[old_miaoda_plugins_cleanup] rmSync ${target} failed: ${e.message}`);
+			}
+		}
+	}
+};
+OldMiaodaPluginsCleanupRule = __decorate([Rule({
+	key: "old_miaoda_plugins_cleanup",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard"
+})], OldMiaodaPluginsCleanupRule);
+//#endregion
+//#region src/rules/lark-plugin-allow.ts
+const LARK_PLUGIN = "openclaw-lark";
+const LARK_PLUGIN_NAMES = [LARK_PLUGIN, "feishu-openclaw-plugin"];
+let LarkPluginAllowRule = class LarkPluginAllowRule extends DiagnoseRule {
+	validate(ctx) {
+		const allow = getAllow(ctx.config);
+		if (LARK_PLUGIN_NAMES.some((name) => allow.includes(name))) return { pass: true };
+		return {
+			pass: false,
+			message: `plugins.allow 缺少飞书插件 (expected one of: ${LARK_PLUGIN_NAMES.join(", ")})`
+		};
+	}
+	repair(ctx) {
+		if (ctx.config.plugins == null || typeof ctx.config.plugins !== "object" || Array.isArray(ctx.config.plugins)) {
+			ctx.config.plugins = { allow: [LARK_PLUGIN] };
+			return;
+		}
+		const pluginsMap = ctx.config.plugins;
+		const rawAllow = pluginsMap.allow;
+		const original = Array.isArray(rawAllow) ? rawAllow : [];
+		const stringAllow = original.filter((e) => typeof e === "string");
+		if (LARK_PLUGIN_NAMES.some((name) => stringAllow.includes(name))) return;
+		original.push(LARK_PLUGIN);
+		pluginsMap.allow = original;
+	}
+};
+LarkPluginAllowRule = __decorate([Rule({
+	key: "lark_plugin_allow",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard"
+})], LarkPluginAllowRule);
+function getAllow(config) {
+	const plugins = config.plugins;
+	if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) return [];
+	const allow = plugins.allow;
+	if (!Array.isArray(allow)) return [];
+	return allow.filter((e) => typeof e === "string");
+}
+//#endregion
 //#region src/check.ts
 function runCheck(input) {
 	const result = { failedRules: {
@@ -896,12 +1100,14 @@ function runCheck(input) {
 	const failedKeys = /* @__PURE__ */ new Set();
 	let configParsed = false;
 	let ctx = {
-		config: { __configPath: input.configPath },
+		config: {},
+		configPath: input.configPath,
 		vars: input.vars,
 		providerDeps: {
 			usesMiaodaProvider: false,
 			usesMiaodaSecretProvider: false
-		}
+		},
+		templateVars: input.templateVars
 	};
 	for (const rule of rules) {
 		const meta = rule.meta;
@@ -912,8 +1118,10 @@ function runCheck(input) {
 			const deps = analyzeProviderDeps(parsed);
 			ctx = {
 				config: parsed,
+				configPath: input.configPath,
 				vars: input.vars,
-				providerDeps: deps
+				providerDeps: deps,
+				templateVars: input.templateVars
 			};
 			configParsed = true;
 		} catch {
@@ -965,12 +1173,14 @@ function runRepair(input) {
 			if (rule.meta.repairMode !== "standard") continue;
 			if (rule.meta.dependsOn?.includes("config_syntax_check")) continue;
 			rule.repair({
-				config: { __configPath: input.configPath },
+				config: {},
+				configPath: input.configPath,
 				vars: input.vars,
 				providerDeps: {
 					usesMiaodaProvider: false,
 					usesMiaodaSecretProvider: false
-				}
+				},
+				templateVars: input.templateVars
 			});
 		}
 		const JSON5 = loadJSON5();
@@ -986,8 +1196,10 @@ function runRepair(input) {
 		const deps = analyzeProviderDeps(config);
 		const ctx = {
 			config,
+			configPath: input.configPath,
 			vars: input.vars,
-			providerDeps: deps
+			providerDeps: deps,
+			templateVars: input.templateVars
 		};
 		let configDirty = false;
 		for (const rule of rules) {
@@ -1032,6 +1244,14 @@ function resetResultFile(taskId) {
 function resetLogFile(taskId) {
 	return `${DIAGNOSE_DIR}/reset-${taskId}.log`;
 }
+/** Sandbox workspace root where openclaw config + agent state lives. */
+const WORKSPACE_DIR = "/home/gem/workspace/agent";
+/** File containing the provider key used by the openclaw miaoda provider. */
+const PROVIDER_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-provider-key";
+/** File containing the miaoda openclaw secrets JSON. */
+const SECRETS_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-openclaw-secrets.json";
+/** Absolute path to the openclaw config JSON. */
+const CONFIG_PATH = `${WORKSPACE_DIR}/openclaw.json`;
 //#endregion
 //#region src/logger.ts
 function makeLogger(logFile) {
@@ -1100,6 +1320,234 @@ function startAsyncReset(ctxBase64) {
 	return { taskId };
 }
 //#endregion
+//#region src/oss/fetchManifest.ts
+async function fetchManifest(ossFileMap, tag) {
+	const key = `builtin/manifests/openclaw/recommended/${tag}.json`;
+	const url = ossFileMap[key];
+	if (!url) throw new Error(`manifest signed URL missing for ${key}`);
+	const res = await fetch(url);
+	if (!res.ok) throw new Error(`fetch manifest failed: HTTP ${res.status} ${res.statusText}`);
+	return await res.json();
+}
+async function downloadWithCache(pkg, ossFileMap, opts = {}) {
+	const cacheRoot = opts.cacheRoot ?? "/tmp/openclaw-diagnose/resources";
+	const shortHash = pkg.shasum.slice(0, 16);
+	const destDir = node_path.default.join(cacheRoot, shortHash);
+	const destFile = node_path.default.join(destDir, node_path.default.posix.basename(pkg.ossKey));
+	node_fs.default.mkdirSync(destDir, { recursive: true });
+	if (node_fs.default.existsSync(destFile)) return destFile;
+	const url = ossFileMap[pkg.ossKey];
+	if (!url) throw new Error(`signed URL missing for ${pkg.ossKey}`);
+	if (!pkg.integrity.startsWith("sha512-")) throw new Error(`unsupported integrity format: ${pkg.integrity}`);
+	const expected = pkg.integrity.slice(7);
+	const tmpFile = node_path.default.join(destDir, `.tmp.${process.pid}.${node_crypto.default.randomBytes(4).toString("hex")}`);
+	try {
+		const res = await fetch(url);
+		if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`);
+		if (!res.body) throw new Error(`download failed: empty body for ${pkg.ossKey}`);
+		const hasher = node_crypto.default.createHash("sha512");
+		const source = node_stream.Readable.fromWeb(res.body);
+		async function* teeAndHash(src) {
+			for await (const chunk of src) {
+				hasher.update(chunk);
+				yield chunk;
+			}
+		}
+		await (0, node_stream_promises.pipeline)(source, teeAndHash, node_fs.default.createWriteStream(tmpFile));
+		const actual = hasher.digest("base64");
+		if (actual !== expected) {
+			const envBypass = process.env.OPENCLAW_DEBUG_SKIP_INTEGRITY === "1";
+			if (opts.skipIntegrity || envBypass) {
+				const sourceLabel = opts.skipIntegrity ? "skipIntegrity=true" : "OPENCLAW_DEBUG_SKIP_INTEGRITY=1";
+				console.error(`⚠ [downloadWithCache] INTEGRITY BYPASS for ${pkg.ossKey}: expected ${expected.slice(0, 12)}… got ${actual.slice(0, 12)}… — ${sourceLabel}. DO NOT use this flag in production.`);
+			} else throw new Error(`integrity mismatch for ${pkg.ossKey}: expected ${expected} got ${actual}`);
+		}
+		node_fs.default.renameSync(tmpFile, destFile);
+		return destFile;
+	} catch (e) {
+		try {
+			node_fs.default.unlinkSync(tmpFile);
+		} catch {}
+		throw e;
+	}
+}
+async function installOpenclaw(openclawTag, ossFileMap, opts = {}) {
+	const homeBase = opts.homeBase ?? "/home/gem";
+	const t0 = Date.now();
+	const pkg = (await fetchManifest(ossFileMap, openclawTag)).packages.find((p) => p.role === "cli" && p.name === "openclaw");
+	if (!pkg) throw new Error("install-openclaw: role=cli,name=openclaw not found in manifest");
+	const targetDir = opts.targetDir ?? node_path.default.join(homeBase, pkg.installPath);
+	const bakDir = targetDir + ".bak";
+	const tarball = await downloadWithCache(pkg, ossFileMap, opts);
+	console.error(`[install-openclaw] tag=${openclawTag} shasum=${pkg.shasum.slice(0, 12)}...`);
+	if (node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
+		recursive: true,
+		force: true
+	});
+	const hadExisting = node_fs.default.existsSync(targetDir);
+	if (hadExisting) node_fs.default.renameSync(targetDir, bakDir);
+	try {
+		node_fs.default.mkdirSync(targetDir, { recursive: true });
+		(0, node_child_process.execSync)(`tar -xzf '${tarball}' -C '${targetDir}' --strip-components=1`, { stdio: "ignore" });
+		if (!node_fs.default.existsSync(node_path.default.join(targetDir, "package.json"))) throw new Error("extracted tarball missing package.json");
+	} catch (e) {
+		try {
+			node_fs.default.rmSync(targetDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		if (hadExisting && node_fs.default.existsSync(bakDir)) node_fs.default.renameSync(bakDir, targetDir);
+		throw e;
+	}
+	if (node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
+		recursive: true,
+		force: true
+	});
+	console.error(`[install-openclaw] done in ${Date.now() - t0}ms`);
+}
+async function installExtension(tag, ossFileMap, opts = {}) {
+	const homeBase = opts.homeBase ?? "/home/gem";
+	const hasAll = !!opts.all;
+	const hasNames = (opts.names?.length ?? 0) > 0;
+	if (hasAll && hasNames) throw new Error("install-extension: --all and --extension are mutually exclusive");
+	if (!hasAll && !hasNames) throw new Error("install-extension: must provide --all or --extension=<name>");
+	const allExts = (await fetchManifest(ossFileMap, tag)).packages.filter((p) => p.role === "extension");
+	let targets;
+	if (hasAll) targets = allExts;
+	else {
+		const wanted = new Set(opts.names);
+		targets = allExts.filter((p) => wanted.has(p.name) || p.packageName != null && wanted.has(p.packageName));
+		const foundKeys = /* @__PURE__ */ new Set();
+		for (const t of targets) {
+			foundKeys.add(t.name);
+			if (t.packageName) foundKeys.add(t.packageName);
+		}
+		const missing = opts.names.filter((n) => !foundKeys.has(n));
+		if (missing.length > 0) throw new Error(`install-extension: not found in manifest: ${missing.join(", ")}`);
+	}
+	console.error(`[install-extension] tag=${tag} targets=${targets.length}`);
+	const t0 = Date.now();
+	const tarballs = await Promise.all(targets.map(async (p) => {
+		const tb = await downloadWithCache(p, ossFileMap, opts);
+		console.error(`[install-extension]   ${p.name}: downloaded`);
+		return {
+			pkg: p,
+			tarball: tb
+		};
+	}));
+	for (const { pkg, tarball } of tarballs) {
+		installOne(pkg, tarball, homeBase);
+		console.error(`[install-extension]   ${pkg.name}: installed`);
+	}
+	if (!opts.skipConfigUpdate) updatePluginInstalls(opts.configPath ?? node_path.default.join(homeBase, "workspace/agent/openclaw.json"), targets);
+	else console.error(`[install-extension] skipConfigUpdate=true — not touching openclaw.json`);
+	console.error(`[install-extension] done ${targets.length}/${targets.length} in ${Date.now() - t0}ms`);
+}
+/**
+* Merge each installed extension's installMetadata into openclaw.json's
+* plugins.installs[<pkg.name>]. Atomic write via tmp + rename.
+*
+* - No openclaw.json → log + return (not an error; some install contexts don't have it yet)
+* - Extension without installMetadata in manifest → skip that entry (log)
+* - Existing plugins.installs entries for other extensions left untouched
+*/
+function updatePluginInstalls(configPath, installedPkgs) {
+	if (!node_fs.default.existsSync(configPath)) {
+		console.error(`[install-extension] no config at ${configPath} — skip plugins.installs update`);
+		return;
+	}
+	const JSON5 = loadJSON5();
+	const raw = node_fs.default.readFileSync(configPath, "utf-8");
+	const config = JSON5.parse(raw);
+	if (!config.plugins || typeof config.plugins !== "object") config.plugins = {};
+	const plugins = config.plugins;
+	if (!plugins.installs || typeof plugins.installs !== "object") plugins.installs = {};
+	const installs = plugins.installs;
+	let updated = 0;
+	let skipped = 0;
+	for (const pkg of installedPkgs) if (pkg.installMetadata) {
+		installs[pkg.name] = pkg.installMetadata;
+		updated++;
+	} else skipped++;
+	const tmpPath = configPath + ".installs-tmp";
+	node_fs.default.writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+	node_fs.default.renameSync(tmpPath, configPath);
+	console.error(`[install-extension] plugins.installs updated: ${updated} entry(ies) in ${configPath}` + (skipped > 0 ? ` (${skipped} package(s) without installMetadata skipped)` : ""));
+}
+function installOne(pkg, tarball, homeBase) {
+	const destDir = node_path.default.join(homeBase, pkg.installPath);
+	const stagingDir = destDir + ".new";
+	const oldDir = destDir + ".old";
+	node_fs.default.mkdirSync(node_path.default.dirname(destDir), { recursive: true });
+	if (node_fs.default.existsSync(stagingDir)) node_fs.default.rmSync(stagingDir, {
+		recursive: true,
+		force: true
+	});
+	node_fs.default.mkdirSync(stagingDir);
+	try {
+		(0, node_child_process.execSync)(`tar -xzf '${tarball}' -C '${stagingDir}' --strip-components=1`, { stdio: "ignore" });
+		if (!node_fs.default.existsSync(node_path.default.join(stagingDir, "package.json"))) throw new Error(`extension tarball missing package.json: ${pkg.name}`);
+	} catch (e) {
+		try {
+			node_fs.default.rmSync(stagingDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		throw e;
+	}
+	const hadOld = node_fs.default.existsSync(destDir);
+	if (hadOld) node_fs.default.renameSync(destDir, oldDir);
+	node_fs.default.renameSync(stagingDir, destDir);
+	if (hadOld && node_fs.default.existsSync(oldDir)) node_fs.default.rmSync(oldDir, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Download + extract a config/template package to its install destination.
+*
+* Current manifest has all resources as format=tgz with content at the root
+* (config: openclaw.json file at root; template: scripts/ dir at root), so we
+* always `tar -xzf` without --strip-components into `dirname(fullInstallPath)`.
+* The final artefact ends up at exactly `homeBase + pkg.installPath`.
+*/
+async function downloadResource(tag, ossFileMap, opts) {
+	const homeBase = opts.homeBase ?? "/home/gem";
+	const pkg = (await fetchManifest(ossFileMap, tag)).packages.find((p) => p.role === opts.role && p.name === opts.name);
+	if (!pkg) throw new Error(`download-resource: not found in manifest: role=${opts.role} name=${opts.name}`);
+	const file = await downloadWithCache(pkg, ossFileMap, opts);
+	const fullInstallPath = node_path.default.join(homeBase, pkg.installPath);
+	const extractDir = opts.dir ?? node_path.default.dirname(fullInstallPath);
+	node_fs.default.mkdirSync(extractDir, { recursive: true });
+	const format = (pkg.format ?? "").toLowerCase();
+	const lower = pkg.ossKey.toLowerCase();
+	if (format === "tgz" || lower.endsWith(".tgz") || lower.endsWith(".tar.gz")) {
+		(0, node_child_process.execSync)(`tar -xzf '${file}' -C '${extractDir}'`, { stdio: "ignore" });
+		console.error(`[download-resource] ${opts.role}/${opts.name}: extracted to ${extractDir}`);
+	} else {
+		const basename = node_path.default.posix.basename(pkg.ossKey);
+		node_fs.default.copyFileSync(file, node_path.default.join(extractDir, basename));
+		console.error(`[download-resource] ${opts.role}/${opts.name}: copied ${basename} to ${extractDir}`);
+	}
+}
+//#endregion
+//#region src/oss/getOpenclawTag.ts
+/**
+* Extracts the openclaw tag from the manifest key present in ossFileMap.
+* Avoids passing an extra ctx field — we already know the tag from the
+* well-known manifest key studio_server included.
+*
+* Manifest key shape: builtin/manifests/openclaw/recommended/<tag>.json
+*/
+function getOpenclawTagFromOssFileMap(ossFileMap) {
+	const prefix = "builtin/manifests/openclaw/recommended/";
+	const suffix = ".json";
+	for (const key of Object.keys(ossFileMap)) if (key.startsWith(prefix) && key.endsWith(suffix)) return key.slice(39, -5);
+	throw new Error("cannot resolve openclaw tag: ossFileMap missing manifest key");
+}
+//#endregion
 //#region src/reset.ts
 const STEPS = [
 	"备份当前配置",
@@ -1108,21 +1556,11 @@ const STEPS = [
 	"等待沙箱初始化完成",
 	"确认 openclaw 版本",
 	"合并核心备份配置",
-	"复制启动脚本",
+	"检查启动脚本",
 	"安装扩展",
 	"启动并验证"
 ];
 const TOTAL_STEPS = STEPS.length;
-/** Pre-packed extensions archive on OSS. Update this URL when releasing a new version. */
-const EXTENSIONS_OSS_URL = "https://miaoda-template-online.oss-cn-beijing.aliyuncs.com/builtin/tool/pkg/openclaw-extensions-2026.4.9.tar.gz";
-/**
-* Directory holding the bundled openclaw template (openclaw.json + scripts/).
-* Synced from git@code.byted.org:apaas/miaoda-openclaw-template.git via
-* scripts/sync-template.sh and published alongside dist/.
-*
-* At runtime, __dirname points to dist/, so the template lives one level up.
-*/
-const TEMPLATE_DIR = node_path.default.resolve(__dirname, "..", "template");
 function writeResultFile(resultFile, result) {
 	const dir = node_path.default.dirname(resultFile);
 	if (!node_fs.default.existsSync(dir)) node_fs.default.mkdirSync(dir, { recursive: true });
@@ -1160,6 +1598,33 @@ function markFailed(resultFile, step, error, startedAt) {
 		completedAt: (/* @__PURE__ */ new Date()).toISOString()
 	});
 }
+/**
+* Download the template assets (config/openclaw.json + template/scripts) from
+* OSS into a scratch directory so the existing step 2 (generateDefaultConfig)
+* and step 7 (copyStartupScripts) can consume them as local files — the rest
+* of the orchestrator code stays untouched.
+*
+* Called once before step 1. The caller is responsible for rm -rf'ing
+* stagedDir in a finally{} block after the reset completes (or fails).
+*/
+async function stageTemplate(openclawTag, ossFileMap, stagedDir, configDir, log) {
+	if (node_fs.default.existsSync(stagedDir)) node_fs.default.rmSync(stagedDir, {
+		recursive: true,
+		force: true
+	});
+	node_fs.default.mkdirSync(stagedDir, { recursive: true });
+	await downloadResource(openclawTag, ossFileMap, {
+		role: "config",
+		name: "openclaw.json",
+		dir: stagedDir
+	});
+	await downloadResource(openclawTag, ossFileMap, {
+		role: "template",
+		name: "scripts",
+		dir: configDir
+	});
+	log(`staged openclaw.json to ${stagedDir}, scripts directly to ${configDir}/scripts`);
+}
 /** Step 1: Backup current config as openclaw.json.bak.N */
 function backupCurrentConfig(configPath, log) {
 	if (!fileExists(configPath)) {
@@ -1184,7 +1649,7 @@ function backupCurrentConfig(configPath, log) {
 /** Step 2: Replace $$__XXX__ placeholders and write default config. */
 function generateDefaultConfig(srcDir, configPath, templateVars, log) {
 	const srcConfigPath = node_path.default.join(srcDir, "openclaw.json");
-	if (!fileExists(srcConfigPath)) throw new Error("template openclaw.json not found at " + srcConfigPath);
+	if (!fileExists(srcConfigPath)) throw new Error("staged openclaw.json not found at " + srcConfigPath);
 	let content = node_fs.default.readFileSync(srcConfigPath, "utf-8");
 	let replaced = 0;
 	for (const [placeholder, value] of Object.entries(templateVars)) {
@@ -1205,11 +1670,14 @@ function killOpenclawProcesses(log) {
 }
 /**
 * Step 4: Wait for the sandbox's own init (init_sandbox.sh / concurrent npm
-* install) to finish before we start our own npm i -g. Two npm processes
-* sharing ~/.npm cache + competing for disk/network just makes everything
-* crawl; letting init finish first is the cleanest way to get exclusive
-* access. Polls every 10s up to `maxWaitMs`. If the deadline is hit we fall
-* through anyway — better to try than to fail the reset outright.
+* install) to finish before we start our own work. Two processes sharing
+* ~/.npm cache + competing for disk/network just makes everything crawl;
+* letting init finish first is the cleanest way to get exclusive access.
+* Polls every 10s up to `maxWaitMs`. If the deadline is hit we fall through
+* anyway — better to try than to fail the reset outright.
+*
+* Kept even after we switched off `npm install` because the sandbox init
+* script still runs `npm install` for other packages and holds cache locks.
 */
 function waitForInitNpm(maxWaitMs, log) {
 	const deadline = Date.now() + maxWaitMs;
@@ -1237,81 +1705,15 @@ function waitForInitNpm(maxWaitMs, log) {
 	log(`deadline (${maxWaitMs}ms) hit after ${polls} poll(s), proceeding anyway`);
 }
 /**
-* Step 5: Ensure openclaw binary is at the template's recommended version.
-*
-* Only checks/installs the binary — does NOT run `doctor --fix` any more.
-* Extensions are installed separately via OSS tar.gz (Step 8), which means
-* the openclaw-lark extension schema is already in place when openclaw
-* starts, avoiding the schema-priority mismatch that caused doctor to
-* reject valid config fields like threadSession / footer.
+* Step 5: Install openclaw from the OSS-provided tarball at the target tag,
+* then verify `openclaw --version` output contains that tag. No npm involved.
 */
-function ensureOpenclawBinary(srcDir, configPath, log) {
-	const targetVersion = loadJSON5().parse(node_fs.default.readFileSync(node_path.default.join(srcDir, "openclaw.json"), "utf-8")).meta?.lastTouchedVersion;
-	log(`target openclaw version: ${targetVersion ?? "<unset>"}`);
-	if (targetVersion && isOpenclawAtVersion(targetVersion)) {
-		log("openclaw already at target version, nothing to do");
-		return;
-	}
-	if (isOpenclawInstalled()) {
-		const updateCmd = `openclaw update${targetVersion ? " --tag " + targetVersion : ""} --yes --no-restart`;
-		log(`openclaw installed but version mismatched, running: ${updateCmd}`);
-		const timeout = 12 * 6e4;
-		const t = Date.now();
-		const tmpConfig = configPath + ".update-tmp";
-		const hadConfig = node_fs.default.existsSync(configPath);
-		if (hadConfig) {
-			node_fs.default.renameSync(configPath, tmpConfig);
-			log("temporarily hid config to bypass config guard");
-		}
-		try {
-			shell(updateCmd, timeout);
-			log(`openclaw update done in ${Date.now() - t}ms`);
-		} catch (e) {
-			const elapsed = Date.now() - t;
-			if (elapsed >= timeout - 1e3) log(`openclaw update timed out after ${elapsed}ms (non-fatal, continuing)`);
-			else throw e;
-		} finally {
-			if (hadConfig && node_fs.default.existsSync(tmpConfig)) {
-				node_fs.default.renameSync(tmpConfig, configPath);
-				log("restored config after update");
-			}
-		}
-	} else {
-		log("openclaw binary not found, running full reinstall");
-		fullReinstall(targetVersion, log);
-	}
-}
-/** Check if openclaw command exists (regardless of version). */
-function isOpenclawInstalled() {
-	try {
-		shell("which openclaw 2>/dev/null", 5e3);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/** Full uninstall + reinstall from npm (slow path, triggers postinstall). */
-function fullReinstall(targetVersion, log) {
-	try {
-		shell("npm uninstall -g openclaw 2>/dev/null || true", 6e4);
-	} catch {}
-	try {
-		shell("rm -rf /home/gem/.npm-global/lib/node_modules/openclaw /home/gem/.npm-global/bin/openclaw 2>/dev/null || true", 1e4);
-		log("force-cleaned residual openclaw global dir");
-	} catch {}
-	const installCmd = `npm i -g openclaw@${targetVersion || "latest"}`;
-	log(`running: ${installCmd}`);
-	const t = Date.now();
-	shell(installCmd, 30 * 6e4);
-	log(`npm install done in ${Date.now() - t}ms`);
-}
-/** Return true if `openclaw --version` output contains `targetVersion`. */
-function isOpenclawAtVersion(targetVersion) {
-	try {
-		return shell("openclaw --version 2>&1 || true", 1e4).includes(targetVersion);
-	} catch {
-		return false;
-	}
+async function step5InstallOpenclaw(openclawTag, ossFileMap, log) {
+	log(`install-openclaw tag=${openclawTag}`);
+	await installOpenclaw(openclawTag, ossFileMap);
+	const out = shell("openclaw --version 2>&1 || true", 1e4).trim();
+	if (!out.includes(openclawTag)) throw new Error(`openclaw version verify failed: got "${out}"`);
+	log(`openclaw version verified: ${out}`);
 }
 /** Step 6: Merge coreBackup from resetData + ensure allowedOrigins. */
 function mergeCoreBackupAndOrigins(configPath, vars, resetData, log) {
@@ -1405,73 +1807,31 @@ function mergeCoreBackupAndOrigins(configPath, vars, resetData, log) {
 	node_fs.default.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
 	log(`allowedOrigins: added ${added.length} (${JSON.stringify(added)}), total now ${mergedOrigins.length}`);
 }
-/** Step 7: Copy startup scripts from template to agent dir. */
-function copyStartupScripts(srcDir, configDir, log) {
-	const srcScriptsDir = node_path.default.join(srcDir, "scripts");
+/**
+* Step 7: Verify startup scripts landed in configDir/scripts/.
+*
+* Scripts are extracted directly to configDir/scripts/ during stageTemplate —
+* there's no intermediate copy any more. This step is now a verification gate
+* (rather than a copy action) so the step count stays at 9 and we fail early
+* if the template tgz didn't carry a scripts/ dir.
+*/
+function verifyStartupScripts(configDir, log) {
 	const targetScriptsDir = node_path.default.join(configDir, "scripts");
-	if (!node_fs.default.existsSync(srcScriptsDir)) {
-		log(`no scripts/ in template, skip`);
-		return;
-	}
-	if (!node_fs.default.existsSync(targetScriptsDir)) node_fs.default.mkdirSync(targetScriptsDir, { recursive: true });
-	shell(`cp -r '${srcScriptsDir}'/* '${targetScriptsDir}/'`, 1e4);
-	log(`copied scripts/* -> ${targetScriptsDir}`);
+	if (!node_fs.default.existsSync(targetScriptsDir)) throw new Error(`scripts dir missing at ${targetScriptsDir} — template download failed?`);
+	log(`scripts dir present at ${targetScriptsDir}`);
 }
 /**
-* Step 8: Install extensions from OSS tar.gz or fall back to `openclaw plugins update`.
-*
-*   1. Derive the OSS URL from the openclaw version in the template config
-*   2. Download tar.gz → extract to a staging dir
-*   3. For each included extension, backup (mv) the user's existing copy
-*      to a temp dir — extensions NOT in the archive are left untouched
-*   4. Move the fresh extensions from staging to the target dir
-*
-* This bypasses npm entirely and avoids the schema-priority mismatch where
-* `openclaw doctor --fix` would validate config against the bundled feishu
-* plugin's strict schema before openclaw-lark is installed.
-*
-* Falls back to `openclaw plugins update --all` if the OSS download fails.
+* Step 8: Install all extensions listed in the OSS manifest at `openclawTag`.
+* Replaces the old `plugins update --all` / pre-packed tar.gz flow — the
+* manifest is now the single source of truth for which extensions ship.
 */
-function installExtensions(configDir, log) {
-	const ossUrl = EXTENSIONS_OSS_URL;
-	const targetExtDir = node_path.default.join(configDir, "extensions");
-	const tmpDir = node_path.default.join(configDir, `.ext-reset-tmp-${Date.now()}`);
-	const tarPath = node_path.default.join(tmpDir, "extensions.tar.gz");
-	node_fs.default.mkdirSync(tmpDir, { recursive: true });
-	try {
-		log(`downloading extensions from ${ossUrl}`);
-		const dlStart = Date.now();
-		shell(`curl -fsSL '${ossUrl}' -o '${tarPath}'`, 5 * 6e4);
-		const size = node_fs.default.statSync(tarPath).size;
-		log(`download done in ${Date.now() - dlStart}ms (${(size / 1024 / 1024).toFixed(1)}MB)`);
-		shell(`tar -xzf '${tarPath}' -C '${tmpDir}'`, 6e4);
-		const stagedExtDir = node_path.default.join(tmpDir, "extensions");
-		if (!node_fs.default.existsSync(stagedExtDir)) throw new Error("tar.gz does not contain an extensions/ directory");
-		const extNames = node_fs.default.readdirSync(stagedExtDir).filter((name) => node_fs.default.statSync(node_path.default.join(stagedExtDir, name)).isDirectory());
-		log(`archive contains ${extNames.length} extension(s): ${extNames.join(", ")}`);
-		for (const name of extNames) {
-			const target = node_path.default.join(targetExtDir, name);
-			if (node_fs.default.existsSync(target)) node_fs.default.rmSync(target, {
-				recursive: true,
-				force: true
-			});
-			node_fs.default.renameSync(node_path.default.join(stagedExtDir, name), target);
-			log(`  ${name}: installed`);
-		}
-		const packinfo = node_path.default.join(stagedExtDir, ".packinfo.json");
-		if (node_fs.default.existsSync(packinfo)) {
-			node_fs.default.copyFileSync(packinfo, node_path.default.join(targetExtDir, ".packinfo.json"));
-			log(`packinfo: ${node_fs.default.readFileSync(packinfo, "utf-8").trim()}`);
-		}
-		log("extensions installed from OSS successfully");
-	} finally {
-		try {
-			node_fs.default.rmSync(tmpDir, {
-				recursive: true,
-				force: true
-			});
-		} catch {}
-	}
+async function step8InstallExtensions(openclawTag, ossFileMap, log) {
+	log(`install-extension --all tag=${openclawTag}`);
+	await installExtension(openclawTag, ossFileMap, {
+		all: true,
+		skipConfigUpdate: true
+	});
+	log("extensions installed");
 }
 /** Step 9: Write secrets/provider key files and restart openclaw. */
 function writeSecretsAndRestart(vars, resetData, configDir, log) {
@@ -1496,26 +1856,37 @@ function writeSecretsAndRestart(vars, resetData, configDir, log) {
 * Each step is an independent function. The orchestrator handles progress
 * reporting, error handling, and process-level exception guards.
 *
-* The openclaw.json / scripts/*.sh template files are bundled with this CLI
-* (see TEMPLATE_DIR) and synced from the miaoda-openclaw-template repo via
-* scripts/sync-template.sh, so no runtime download is required.
+* Template assets (openclaw.json + scripts/) are downloaded from OSS into a
+* scratch dir via `stageTemplate` before step 1 — there is no bundled
+* `template/` directory at runtime any more.
 */
-function runReset(input, taskId, resultFile) {
+async function runReset(input, taskId, resultFile) {
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const { configPath, vars, resetData } = input;
 	const configDir = node_path.default.dirname(configPath);
-	const srcDir = TEMPLATE_DIR;
+	const stagedDir = node_path.default.join(DIAGNOSE_DIR, `reset-${taskId}-template`);
 	let currentStep = 0;
 	let stepStartedAt = Date.now();
 	const log = makeLogger(resetLogFile(taskId));
 	log(`=== reset started, taskId=${taskId}, pid=${process.pid} ===`);
-	log(`configPath=${configPath}, configDir=${configDir}, templateDir=${srcDir}`);
-	if (!node_fs.default.existsSync(node_path.default.join(srcDir, "openclaw.json"))) {
-		const err = `bundled template not found at ${srcDir}`;
+	log(`configPath=${configPath}, configDir=${configDir}, stagedDir=${stagedDir}`);
+	const ossFileMap = resetData.ossFileMap;
+	if (!ossFileMap || Object.keys(ossFileMap).length === 0) {
+		const err = "resetData.ossFileMap missing or empty";
 		log(`ERROR: ${err}`);
 		markFailed(resultFile, 0, err, startedAt);
 		process.exit(1);
 	}
+	let openclawTag;
+	try {
+		openclawTag = getOpenclawTagFromOssFileMap(ossFileMap);
+	} catch (e) {
+		const err = e.message;
+		log(`ERROR: ${err}`);
+		markFailed(resultFile, 0, err, startedAt);
+		process.exit(1);
+	}
+	log(`openclawTag=${openclawTag}`);
 	process.on("uncaughtException", (err) => {
 		log(`FATAL uncaughtException: ${err.message}\n${err.stack ?? ""}`);
 		markFailed(resultFile, currentStep, `uncaught exception: ${err.message}`, startedAt);
@@ -1535,22 +1906,23 @@ function runReset(input, taskId, resultFile) {
 		updateProgress(resultFile, n, startedAt);
 	};
 	try {
+		await stageTemplate(openclawTag, ossFileMap, stagedDir, configDir, log);
 		step(1);
 		backupCurrentConfig(configPath, log);
 		step(2);
-		generateDefaultConfig(srcDir, configPath, resetData.templateVars, log);
+		generateDefaultConfig(stagedDir, configPath, resetData.templateVars, log);
 		step(3);
 		killOpenclawProcesses(log);
 		step(4);
 		waitForInitNpm(10 * 6e4, log);
 		step(5);
-		ensureOpenclawBinary(srcDir, configPath, log);
+		await step5InstallOpenclaw(openclawTag, ossFileMap, log);
 		step(6);
 		mergeCoreBackupAndOrigins(configPath, vars, resetData, log);
 		step(7);
-		copyStartupScripts(srcDir, configDir, log);
+		verifyStartupScripts(configDir, log);
 		step(8);
-		installExtensions(configDir, log);
+		await step8InstallExtensions(openclawTag, ossFileMap, log);
 		step(9);
 		writeSecretsAndRestart(vars, resetData, configDir, log);
 		log(`step 9 "${STEPS[8]}" done in ${Date.now() - stepStartedAt}ms`);
@@ -1561,6 +1933,13 @@ function runReset(input, taskId, resultFile) {
 		log(`ERROR in step ${currentStep} "${STEPS[currentStep - 1] ?? "init"}" after ${Date.now() - stepStartedAt}ms: ${err}\n${e.stack ?? ""}`);
 		markFailed(resultFile, currentStep, err, startedAt);
 		process.exit(1);
+	} finally {
+		try {
+			node_fs.default.rmSync(stagedDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
 	}
 }
 //#endregion
@@ -1602,55 +1981,485 @@ function sleepSync(ms) {
 	Atomics.wait(arr, 0, 0, ms);
 }
 //#endregion
+//#region src/oss/resolveOssFileMap.ts
+/**
+* Pick an OssFileMap in the order of decreasing specificity:
+*   1. `--oss_file_map=` flag — operator override (manual invocations, tests)
+*   2. `ctx.install.ossFileMap` — new shape (innerapi-driven DoctorCtx)
+*   3. `ctx.resetData.ossFileMap` — legacy shape (sandbox_console push path)
+*
+* Throws when none of the three yields a non-empty map. Empty maps are
+* treated as missing — an empty map is useless downstream and almost always
+* indicates a ctx wiring bug.
+*/
+function resolveOssFileMap(args) {
+	if (args.ossFileMapFlag) return JSON.parse(Buffer.from(args.ossFileMapFlag, "base64").toString("utf-8"));
+	if (args.installOssFileMap && Object.keys(args.installOssFileMap).length > 0) return args.installOssFileMap;
+	if (args.resetDataOssFileMap && Object.keys(args.resetDataOssFileMap).length > 0) return args.resetDataOssFileMap;
+	throw new Error("ossFileMap missing: provide --oss_file_map flag, ctx.install.ossFileMap, or resetData.ossFileMap");
+}
+//#endregion
+//#region src/innerapi/fetchCtx.ts
+/**
+* CLI-side client for studio_server's `openclaw.get_doctor_ctx` inner API.
+*
+* Mirrors the proven pattern in
+* `packages/openclaw/extensions/miaoda/src/shared/innerapi-client.ts`:
+*
+*   - `baseURL` from env `FORCE_AUTHN_INNERAPI_DOMAIN` (injected into every
+*     openclaw sandbox).
+*   - `platform: { enabled, tokenProvider: { type: 'file' } }` — the platform
+*     plugin auto-attaches the sandbox's identity JWT loaded from the
+*     rootfs token file. Same auth that the miaoda extension already uses.
+*   - POST `/api/v1/studio/innerapi/integration_apis/call`
+*     body = { apiName: 'openclaw.get_doctor_ctx', input: {}, bizType: 'openclaw' }
+*     — the server-side APICall dispatches by `apiName` to
+*     `GetDoctorCtxAPICall.Execute` whose `Name()` returns that string.
+*   - Response envelope: { status_code, error_msg?, data: { success, output, ... } }.
+*     `status_code` is a *string* ('0' = success).
+*     Actual DoctorCtx lives in `data.output`.
+*   - `x-tt-logid` header is logged on every failure path for cross-service
+*     traceability.
+*
+* On HTTP 401 (sandbox identity token expired/invalid) we `process.exit(77)`
+* instead of throwing — the outer catch in `index.ts` cannot then mask auth
+* failure as a generic "Error: ...". Caller (e.g. sandbox_console) sees the
+* exit code and can refresh the token + retry.
+*/
+const INNERAPI_CALL_PATH = "/api/v1/studio/innerapi/integration_apis/call";
+const API_NAME = "openclaw.get_doctor_ctx";
+const BIZ_TYPE = "openclaw";
+const API_TIMEOUT_MS = 3e4;
+const MAX_LOG_BODY = 500;
+let clientInstance = null;
+function getHttpClient() {
+	if (!clientInstance) {
+		const apiUrl = process.env.FORCE_AUTHN_INNERAPI_DOMAIN;
+		(0, node_assert.default)(apiUrl, "missing env: FORCE_AUTHN_INNERAPI_DOMAIN (openclaw sandbox runtime must expose this)");
+		clientInstance = new _lark_apaas_http_client.HttpClient({
+			baseURL: apiUrl,
+			timeout: API_TIMEOUT_MS,
+			platform: {
+				enabled: true,
+				tokenProvider: { type: "file" }
+			}
+		});
+	}
+	return clientInstance;
+}
+/**
+* Fetch the sandbox's DoctorCtx by calling the innerapi's generic
+* `integration_apis/call` dispatcher with apiName=openclaw.get_doctor_ctx.
+*
+* Throws on HTTP (non-401) / decode / business errors. On 401 calls
+* `process.exit(77)` directly.
+*/
+async function fetchCtxViaInnerApi() {
+	const client = getHttpClient();
+	const body = {
+		apiName: API_NAME,
+		input: {},
+		bizType: BIZ_TYPE
+	};
+	const start = Date.now();
+	const headers = { "Content-Type": "application/json" };
+	const ttEnv = process.env.X_TT_ENV;
+	if (ttEnv) headers["x-tt-env"] = ttEnv;
+	let response;
+	try {
+		response = await client.post(INNERAPI_CALL_PATH, body, { headers });
+	} catch (e) {
+		const durationMs = Date.now() - start;
+		if (e instanceof _lark_apaas_http_client.HttpError && e.response) {
+			const status = e.response.status;
+			const logId = e.response.headers.get("x-tt-logid") ?? "";
+			if (status === 401) {
+				console.error(`[CLI] innerapi 401 (logID: ${logId}) — sandbox identity token expired/invalid; exiting 77`);
+				process.exit(77);
+			}
+			throw new Error(`fetchCtxViaInnerApi HTTP ${status} ${e.response.statusText} (logID: ${logId}, durationMs: ${durationMs})`);
+		}
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`fetchCtxViaInnerApi network error: ${msg} (durationMs: ${durationMs})`);
+	}
+	const logId = response.headers.get("x-tt-logid") ?? "";
+	const durationMs = Date.now() - start;
+	if (!response.ok) {
+		if (response.status === 401) {
+			console.error(`[CLI] innerapi 401 (logID: ${logId}) — sandbox identity token expired/invalid; exiting 77`);
+			process.exit(77);
+		}
+		let preview = "";
+		try {
+			preview = (await response.text()).slice(0, MAX_LOG_BODY);
+		} catch {}
+		throw new Error(`fetchCtxViaInnerApi HTTP ${response.status} ${response.statusText} (logID: ${logId}, durationMs: ${durationMs})${preview ? ` body=${preview}` : ""}`);
+	}
+	let envelope;
+	try {
+		envelope = await response.json();
+	} catch {
+		throw new Error(`fetchCtxViaInnerApi decode error (logID: ${logId}, durationMs: ${durationMs})`);
+	}
+	if (envelope.status_code !== "0") throw new Error(`fetchCtxViaInnerApi API error (logID: ${logId}, durationMs: ${durationMs}): code=${envelope.status_code}, message=${envelope.error_msg ?? ""}`);
+	if (envelope.data && envelope.data.success === false) throw new Error(`fetchCtxViaInnerApi business error (logID: ${logId}, durationMs: ${durationMs}): ${envelope.error_msg ?? JSON.stringify(envelope.data)}`);
+	const output = envelope.data?.output;
+	if (!output || typeof output !== "object") throw new Error(`fetchCtxViaInnerApi empty/invalid output (logID: ${logId}, durationMs: ${durationMs})`);
+	return output;
+}
+//#endregion
+//#region src/ctx/normalize.ts
+/**
+* Accept raw ctx from any of these sources and produce a uniform view:
+*   - New shape (DoctorCtx): `{ app, install, secrets, reset }` — from innerapi.
+*   - Old shape (ResetInput): `{ configPath, vars, resetData }` — from
+*     sandbox_console push path.
+* Detection is structural: if the top-level has all four new-shape groups we
+* pass through; otherwise we remap from the old shape.
+*
+* Missing fields fall back to safe empty defaults (empty strings / arrays /
+* maps) so every downstream consumer can read e.g. `ctx.app.feishuAppID`
+* without an extra nullish guard.
+*/
+function normalizeCtx(raw) {
+	const r = raw ?? {};
+	if (r.app && typeof r.app === "object" && r.install && typeof r.install === "object" && r.secrets && typeof r.secrets === "object" && r.reset && typeof r.reset === "object") return {
+		app: fillApp(r.app),
+		install: {
+			openclawTag: r.install.openclawTag,
+			ossFileMap: r.install.ossFileMap ?? {}
+		},
+		secrets: {
+			secretsContent: r.secrets.secretsContent ?? "",
+			providerKeyContent: r.secrets.providerKeyContent ?? ""
+		},
+		reset: {
+			templateVars: r.reset.templateVars ?? {},
+			coreBackup: r.reset.coreBackup
+		}
+	};
+	const vars = r.vars ?? {};
+	const resetData = r.resetData ?? {};
+	const repairData = r.repairData ?? {};
+	return {
+		app: fillApp(vars),
+		install: {
+			openclawTag: r.install?.openclawTag ?? r.openclawTag,
+			ossFileMap: r.install?.ossFileMap ?? resetData.ossFileMap ?? r.ossFileMap ?? {}
+		},
+		secrets: {
+			secretsContent: resetData.secretsContent ?? repairData.secretsContent ?? "",
+			providerKeyContent: resetData.providerKeyContent ?? repairData.providerKeyContent ?? ""
+		},
+		reset: {
+			templateVars: resetData.templateVars ?? {},
+			coreBackup: resetData.coreBackup
+		}
+	};
+}
+function fillApp(src) {
+	return {
+		feishuAppID: src.feishuAppID ?? "",
+		feishuAppSecret: src.feishuAppSecret ?? "",
+		feishuOpenID: src.feishuOpenID ?? "",
+		openClawName: src.openClawName ?? "",
+		gatewayToken: src.gatewayToken ?? "",
+		innerAPIKey: src.innerAPIKey ?? "",
+		baseURL: src.baseURL ?? "",
+		miaodaDomain: src.miaodaDomain ?? "",
+		miaodaOrigin: src.miaodaOrigin ?? "",
+		expectedOrigins: Array.isArray(src.expectedOrigins) ? src.expectedOrigins : []
+	};
+}
+//#endregion
+//#region src/ctx-input.ts
+/**
+* Build legacy Check/Repair/Reset input shapes from a raw ctx object. Shared
+* by both the top-level CLI dispatcher (`index.ts`) and the new `doctor`
+* subcommand (`doctor.ts`), which need identical input synthesis.
+*
+* Behavior:
+*   - If `raw` already carries the legacy `configPath + vars` shape (the one
+*     sandbox_console push emits), it's trusted and returned as-is. This
+*     keeps the existing sandbox_console push contract working.
+*   - Otherwise `raw` is treated as the new-shape DoctorCtx (or anything
+*     structurally close — `normalizeCtx` fills the gaps with safe empties)
+*     and the legacy Vars shape is synthesised using the hardcoded sandbox
+*     path invariants from `paths.ts`.
+*
+* The optional `configPathOverride` lets unit tests point the builder at a
+* tmp file; production callers should leave it undefined so the sandbox
+* invariant from `paths.ts` is used.
+*/
+function buildCheckInput(raw, configPathOverride) {
+	const r = raw ?? {};
+	if (r.configPath && r.vars) {
+		if (configPathOverride) return {
+			...r,
+			configPath: configPathOverride
+		};
+		return r;
+	}
+	const ctx = normalizeCtx(raw);
+	return {
+		configPath: configPathOverride ?? CONFIG_PATH,
+		vars: {
+			feishuAppID: ctx.app.feishuAppID,
+			feishuAppSecret: ctx.app.feishuAppSecret,
+			innerAPIKey: ctx.app.innerAPIKey,
+			gatewayToken: ctx.app.gatewayToken,
+			baseURL: ctx.app.baseURL,
+			expectedOrigins: ctx.app.expectedOrigins,
+			providerFilePath: PROVIDER_FILE_PATH,
+			secretsFilePath: SECRETS_FILE_PATH
+		},
+		templateVars: ctx.reset.templateVars
+	};
+}
+function buildRepairInput(raw, configPathOverride) {
+	const r = raw ?? {};
+	if (r.configPath && r.vars) {
+		if (configPathOverride) return {
+			...r,
+			configPath: configPathOverride
+		};
+		return r;
+	}
+	const ctx = normalizeCtx(raw);
+	return {
+		configPath: configPathOverride ?? CONFIG_PATH,
+		vars: {
+			feishuAppID: ctx.app.feishuAppID,
+			feishuAppSecret: ctx.app.feishuAppSecret,
+			innerAPIKey: ctx.app.innerAPIKey,
+			gatewayToken: ctx.app.gatewayToken,
+			baseURL: ctx.app.baseURL,
+			expectedOrigins: ctx.app.expectedOrigins,
+			providerFilePath: PROVIDER_FILE_PATH,
+			secretsFilePath: SECRETS_FILE_PATH
+		},
+		repairData: {
+			secretsContent: ctx.secrets.secretsContent,
+			providerKeyContent: ctx.secrets.providerKeyContent
+		},
+		templateVars: ctx.reset.templateVars
+	};
+}
+function buildResetInput(raw, configPathOverride) {
+	const r = raw ?? {};
+	if (r.configPath && r.vars && r.resetData) {
+		if (configPathOverride) return {
+			...r,
+			configPath: configPathOverride
+		};
+		return r;
+	}
+	const ctx = normalizeCtx(raw);
+	return {
+		configPath: configPathOverride ?? CONFIG_PATH,
+		vars: {
+			feishuAppID: ctx.app.feishuAppID,
+			feishuAppSecret: ctx.app.feishuAppSecret,
+			innerAPIKey: ctx.app.innerAPIKey,
+			gatewayToken: ctx.app.gatewayToken,
+			baseURL: ctx.app.baseURL,
+			expectedOrigins: ctx.app.expectedOrigins,
+			providerFilePath: PROVIDER_FILE_PATH,
+			secretsFilePath: SECRETS_FILE_PATH
+		},
+		resetData: {
+			templateVars: ctx.reset.templateVars,
+			secretsContent: ctx.secrets.secretsContent,
+			providerKeyContent: ctx.secrets.providerKeyContent,
+			coreBackup: ctx.reset.coreBackup,
+			ossFileMap: ctx.install.ossFileMap
+		}
+	};
+}
+//#endregion
+//#region src/doctor.ts
+async function runDoctor(rawCtx, opts) {
+	if (opts.fix && opts.rules.length > 0) {
+		const repairInput = buildRepairInput(rawCtx, opts.configPath);
+		repairInput.failedRules = opts.rules;
+		repairInput.repairData = {
+			...repairInput.repairData ?? {},
+			restartCommand: ""
+		};
+		return { repair: runRepair(repairInput) };
+	}
+	const check = runCheck(buildCheckInput(rawCtx, opts.configPath));
+	if (!opts.fix) return { failedRules: check.failedRules };
+	const repairInput = buildRepairInput(rawCtx, opts.configPath);
+	repairInput.failedRules = check.failedRules.standard;
+	return {
+		check,
+		repair: runRepair(repairInput)
+	};
+}
+//#endregion
 //#region src/index.ts
 const args = node_process.default.argv.slice(2);
 const mode = args.find((a) => !a.startsWith("--"));
-switch (mode) {
-	case "check":
-	case "repair": {
-		const ctx = args.find((a) => a.startsWith("--ctx="))?.slice(6);
-		if (!ctx) {
-			console.error("Error: --ctx=<base64> is required");
-			node_process.default.exit(1);
+/**
+* Decode `--ctx=<base64>` into an opaque JSON object. Returns undefined when
+* the flag isn't present — the caller decides whether to fall back to the
+* innerapi or to error out.
+*
+* The object's shape is not enforced here; downstream code consumes it via
+* either `normalizeCtx()` (new path) or direct field access for the legacy
+* check/repair/reset contract still used by sandbox_console push.
+*/
+function parseCtxFlag(args) {
+	const ctxArg = args.find((a) => a.startsWith("--ctx="));
+	if (!ctxArg) return void 0;
+	const b64 = ctxArg.slice(6);
+	return JSON.parse(Buffer.from(b64, "base64").toString("utf-8"));
+}
+/**
+* Pull the first non-flag positional after the mode name.
+* (The mode itself is args[0] in the filtered set, so we skip index 0.)
+*/
+function getPositionalTag(args, modeName) {
+	return args.find((a, i) => i > 0 && !a.startsWith("--") && a !== modeName);
+}
+function getFlag(args, name) {
+	const prefix = `--${name}=`;
+	return args.find((a) => a.startsWith(prefix))?.slice(prefix.length);
+}
+function getMultiFlag(args, name) {
+	const prefix = `--${name}=`;
+	return args.filter((a) => a.startsWith(prefix)).map((a) => a.slice(prefix.length));
+}
+async function main() {
+	switch (mode) {
+		case "check":
+		case "repair": {
+			const raw = parseCtxFlag(args) ?? await fetchCtxViaInnerApi();
+			if (mode === "check") console.log(JSON.stringify(runCheck(buildCheckInput(raw))));
+			else console.log(JSON.stringify(runRepair(buildRepairInput(raw))));
+			break;
+		}
+		case "doctor": {
+			const fix = args.includes("--fix");
+			const rules = getMultiFlag(args, "rule");
+			const result = await runDoctor(await fetchCtxViaInnerApi(), {
+				fix,
+				rules
+			});
+			console.log(JSON.stringify(result));
+			break;
 		}
-		const input = JSON.parse(Buffer.from(ctx, "base64").toString("utf-8"));
-		if (mode === "check") console.log(JSON.stringify(runCheck(input)));
-		else console.log(JSON.stringify(runRepair(input)));
-		break;
-	}
-	case "reset":
-		if (args.includes("--async")) {
-			const ctx = args.find((a) => a.startsWith("--ctx="))?.slice(6);
-			if (!ctx) {
-				console.error("Error: --ctx=<base64> is required");
+		case "reset":
+			if (args.includes("--async")) {
+				const ctxArg = args.find((a) => a.startsWith("--ctx="));
+				let ctxBase64;
+				if (ctxArg) ctxBase64 = ctxArg.slice(6);
+				else {
+					const fetched = await fetchCtxViaInnerApi();
+					ctxBase64 = Buffer.from(JSON.stringify(fetched), "utf-8").toString("base64");
+				}
+				console.log(JSON.stringify(startAsyncReset(ctxBase64)));
+			} else if (args.includes("--worker")) {
+				const taskId = args.find((a) => a.startsWith("--task-id="))?.slice(10);
+				if (!taskId) {
+					console.error("Error: --task-id=<id> is required for worker");
+					node_process.default.exit(1);
+				}
+				const resultFile = resetResultFile(taskId);
+				await runReset(buildResetInput(parseCtxFlag(args) ?? await fetchCtxViaInnerApi()), taskId, resultFile);
+			} else {
+				console.error("Usage: reset --async [--ctx=<base64>] | reset --worker --task-id=<id> [--ctx=<base64>]");
 				node_process.default.exit(1);
 			}
-			console.log(JSON.stringify(startAsyncReset(ctx)));
-		} else if (args.includes("--worker")) {
-			const ctx = args.find((a) => a.startsWith("--ctx="))?.slice(6);
+			break;
+		case "get_reset_task": {
 			const taskId = args.find((a) => a.startsWith("--task-id="))?.slice(10);
-			if (!ctx || !taskId) {
-				console.error("Error: --ctx=<base64> and --task-id=<id> are required for worker");
+			if (!taskId) {
+				console.error("Error: --task-id=<id> is required");
 				node_process.default.exit(1);
 			}
-			const resultFile = resetResultFile(taskId);
-			runReset(JSON.parse(Buffer.from(ctx, "base64").toString("utf-8")), taskId, resultFile);
-		} else {
-			console.error("Usage: reset --async --ctx=<base64> | reset --worker --task-id=<id> --ctx=<base64>");
-			node_process.default.exit(1);
+			console.log(JSON.stringify(getResetTask(taskId)));
+			break;
 		}
-		break;
-	case "get_reset_task": {
-		const taskId = args.find((a) => a.startsWith("--task-id="))?.slice(10);
-		if (!taskId) {
-			console.error("Error: --task-id=<id> is required");
-			node_process.default.exit(1);
+		case "install-openclaw": {
+			const tag = getPositionalTag(args, "install-openclaw");
+			if (!tag) {
+				console.error("Usage: install-openclaw <tag> [--ctx=<base64> | --oss_file_map=<base64>]");
+				node_process.default.exit(1);
+			}
+			const ossFileMapFlag = getFlag(args, "oss_file_map");
+			let installOssFileMap;
+			if (!ossFileMapFlag) installOssFileMap = normalizeCtx(parseCtxFlag(args) ?? await fetchCtxViaInnerApi()).install.ossFileMap;
+			await installOpenclaw(tag, resolveOssFileMap({
+				ossFileMapFlag,
+				installOssFileMap
+			}));
+			console.log(JSON.stringify({ ok: true }));
+			break;
+		}
+		case "install-extension": {
+			const tag = getPositionalTag(args, "install-extension");
+			if (!tag) {
+				console.error("Usage: install-extension <tag> (--all | --extension=<name>...) [--home_base=<dir>] [--config_path=<path>] [--skip-config-update] [--ctx=<base64> | --oss_file_map=<base64>]");
+				node_process.default.exit(1);
+			}
+			const all = args.includes("--all");
+			const names = getMultiFlag(args, "extension");
+			const homeBase = getFlag(args, "home_base");
+			const configPath = getFlag(args, "config_path");
+			const skipConfigUpdate = args.includes("--skip-config-update");
+			const ossFileMapFlag = getFlag(args, "oss_file_map");
+			let installOssFileMap;
+			if (!ossFileMapFlag) installOssFileMap = normalizeCtx(parseCtxFlag(args) ?? await fetchCtxViaInnerApi()).install.ossFileMap;
+			await installExtension(tag, resolveOssFileMap({
+				ossFileMapFlag,
+				installOssFileMap
+			}), {
+				all,
+				names: names.length > 0 ? names : void 0,
+				homeBase,
+				configPath,
+				skipConfigUpdate
+			});
+			console.log(JSON.stringify({ ok: true }));
+			break;
+		}
+		case "download-resource": {
+			const tag = getPositionalTag(args, "download-resource");
+			if (!tag) {
+				console.error("Usage: download-resource <tag> --role=<role> --name=<name> [--dir=<dir>] [--ctx=<base64> | --oss_file_map=<base64>]");
+				node_process.default.exit(1);
+			}
+			const role = getFlag(args, "role");
+			const name = getFlag(args, "name");
+			const dir = getFlag(args, "dir");
+			if (!role || !name) {
+				console.error("Usage: download-resource <tag> --role=<role> --name=<name> [--dir=<dir>]");
+				node_process.default.exit(1);
+			}
+			const ossFileMapFlag = getFlag(args, "oss_file_map");
+			let installOssFileMap;
+			if (!ossFileMapFlag) installOssFileMap = normalizeCtx(parseCtxFlag(args) ?? await fetchCtxViaInnerApi()).install.ossFileMap;
+			await downloadResource(tag, resolveOssFileMap({
+				ossFileMapFlag,
+				installOssFileMap
+			}), {
+				role,
+				name,
+				dir
+			});
+			console.log(JSON.stringify({ ok: true }));
+			break;
 		}
-		console.log(JSON.stringify(getResetTask(taskId)));
-		break;
+		default:
+			console.error("Usage: mclaw-diagnose <check|repair|doctor|reset|get_reset_task|install-openclaw|install-extension|download-resource> [options]");
+			node_process.default.exit(1);
 	}
-	default:
-		console.error("Usage: mclaw-diagnose <check|repair|reset|get_reset_task> [options]");
-		node_process.default.exit(1);
 }
+main().catch((err) => {
+	const msg = err instanceof Error ? err.message : String(err);
+	console.error(`Error: ${msg}`);
+	node_process.default.exit(1);
+});
 //#endregion