@lark-apaas/openclaw-scripts-diagnose-cli 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -31,6 +31,14 @@ 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_os = require("node:os");
+node_os = __toESM(node_os);
+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 {
@@ -81,6 +89,17 @@ function topoSort(rules) {
 //#endregion
 //#region src/utils.ts
 /**
+* Canonical provider-ref for the feishu app secret. Both
+* `feishu_default_account` (multi-agent path) and `feishu_channel`
+* (single-agent path) use this as the source-of-truth `appSecret`
+* value when repairing.
+*/
+const DEFAULT_FEISHU_APP_SECRET = {
+	source: "file",
+	provider: "miaoda-secret-provider",
+	id: "/channels_feishu_app_secret"
+};
+/**
 * Navigate nested object by keys, returning the value if it's a non-array object,
 * or undefined otherwise.
 */
@@ -127,6 +146,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;
@@ -137,6 +164,25 @@ function setNestedValue(obj, keys, value) {
 	}
 	current[keys[keys.length - 1]] = value;
 }
+/**
+* Locate the "main" agent in `agents.list`. Preference order:
+*   1. Explicit `default: true` entry.
+*   2. Entry with `id === 'main'` (project naming convention).
+*   3. First entry in the list (positional fallback).
+* Returns `undefined` when `agents.list` is missing or empty.
+*/
+function findMainAgent(config) {
+	const agents = getNestedMap(config, "agents");
+	if (!agents) return void 0;
+	const list = agents.list;
+	if (!Array.isArray(list) || list.length === 0) return void 0;
+	const isObj = (a) => a != null && typeof a === "object" && !Array.isArray(a);
+	const explicit = list.find((a) => isObj(a) && a.default === true);
+	if (explicit) return explicit;
+	const namedMain = list.find((a) => isObj(a) && a.id === "main");
+	if (namedMain) return namedMain;
+	return isObj(list[0]) ? list[0] : void 0;
+}
 /** Analyze which miaoda providers the config references. */
 function analyzeProviderDeps(config) {
 	const deps = {
@@ -268,7 +314,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 +327,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 +356,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 +378,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));
@@ -351,6 +397,74 @@ ConfigSyntaxRule = __decorate([Rule({
 	repairMode: "ai"
 })], ConfigSyntaxRule);
 //#endregion
+//#region src/rules/template-vars-unreplaced.ts
+/**
+* Placeholder format used by miaoda-openclaw-template and Go-side templateVars,
+* e.g. `$$__FEISHU_APP_ID__`. Double underscores on both sides act as a natural
+* boundary so split-join replacement can't accidentally overlap between keys.
+*/
+const PLACEHOLDER_RE = /\$\$__[A-Z0-9_]+__/g;
+let TemplateVarsUnreplacedRule = class TemplateVarsUnreplacedRule extends DiagnoseRule {
+	validate(ctx) {
+		const found = /* @__PURE__ */ new Set();
+		collectPlaceholders(ctx.config, found);
+		if (found.size === 0) return { pass: true };
+		return {
+			pass: false,
+			message: "存在未替换的模板占位符: " + [...found].sort().join(", ")
+		};
+	}
+	repair(ctx) {
+		const map = ctx.templateVars;
+		if (!map || Object.keys(map).length === 0) return;
+		replaceInPlace(ctx.config, Object.entries(map));
+	}
+};
+TemplateVarsUnreplacedRule = __decorate([Rule({
+	key: "template_vars_unreplaced",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard"
+})], TemplateVarsUnreplacedRule);
+function collectPlaceholders(value, found) {
+	if (typeof value === "string") {
+		const matches = value.match(PLACEHOLDER_RE);
+		if (matches) for (const m of matches) found.add(m);
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const v of value) collectPlaceholders(v, found);
+		return;
+	}
+	if (value && typeof value === "object") for (const v of Object.values(value)) collectPlaceholders(v, found);
+}
+function replaceInPlace(value, entries) {
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const el = value[i];
+			if (typeof el === "string") value[i] = applyVars(el, entries);
+			else replaceInPlace(el, entries);
+		}
+		return;
+	}
+	if (value && typeof value === "object") {
+		const obj = value;
+		for (const key of Object.keys(obj)) {
+			const v = obj[key];
+			if (typeof v === "string") obj[key] = applyVars(v, entries);
+			else replaceInPlace(v, entries);
+		}
+	}
+}
+/** Split-join replacement — matches the algorithm in reset.ts:120 and avoids regex-escaping `$$`. */
+function applyVars(str, entries) {
+	let out = str;
+	for (const [placeholder, value] of entries) {
+		if (!value) continue;
+		if (out.includes(placeholder)) out = out.split(placeholder).join(value);
+	}
+	return out;
+}
+//#endregion
 //#region src/rules/model-provider.ts
 var _ModelProviderRule;
 let ModelProviderRule = class ModelProviderRule extends DiagnoseRule {
@@ -534,16 +648,11 @@ SecretProviderRule = _SecretProviderRule = __decorate([Rule({
 })], SecretProviderRule);
 //#endregion
 //#region src/rules/feishu-channel.ts
-var _FeishuChannelRule;
+/**
+* Owns `channels.feishu.enabled` + single-agent top-level appId/appSecret.
+* Multi-agent shape (`accounts` present) belongs to `feishu_default_account`.
+*/
 let FeishuChannelRule = class FeishuChannelRule extends DiagnoseRule {
-	static {
-		_FeishuChannelRule = this;
-	}
-	static DEFAULT_APP_SECRET = {
-		source: "file",
-		provider: "miaoda-secret-provider",
-		id: "/channels_feishu_app_secret"
-	};
 	validate(ctx) {
 		const feishu = getNestedMap(ctx.config, "channels", "feishu");
 		if (!feishu) return {
@@ -554,16 +663,16 @@ let FeishuChannelRule = class FeishuChannelRule extends DiagnoseRule {
 			pass: false,
 			message: "channels.feishu.enabled mismatch: got " + feishu.enabled + ", expected true"
 		};
+		if (asRecord(feishu.accounts)) return { pass: true };
 		if (feishu.appId !== ctx.vars.feishuAppID) return {
 			pass: false,
-			message: "channels.feishu.appId mismatch: got " + feishu.appId + ", expected " + ctx.vars.feishuAppID
+			message: `channels.feishu.appId mismatch: got ${feishu.appId}, expected ${ctx.vars.feishuAppID}`
 		};
-		const expectedSecret = _FeishuChannelRule.DEFAULT_APP_SECRET;
 		const secret = feishu.appSecret;
 		if (typeof secret === "object" && secret !== null && !Array.isArray(secret)) {
-			if (!matchMap(secret, expectedSecret)) return {
+			if (!matchMap(secret, DEFAULT_FEISHU_APP_SECRET)) return {
 				pass: false,
-				message: "channels.feishu.appSecret object mismatch: got " + JSON.stringify(secret)
+				message: `channels.feishu.appSecret object mismatch: got ${JSON.stringify(secret)}`
 			};
 		} else if (typeof secret === "string") {
 			if (secret !== ctx.vars.feishuAppSecret) return {
@@ -582,6 +691,7 @@ let FeishuChannelRule = class FeishuChannelRule extends DiagnoseRule {
 			"feishu",
 			"enabled"
 		], true);
+		if (asRecord(getNestedMap(ctx.config, "channels", "feishu").accounts)) return;
 		setNestedValue(ctx.config, [
 			"channels",
 			"feishu",
@@ -591,15 +701,167 @@ let FeishuChannelRule = class FeishuChannelRule extends DiagnoseRule {
 			"channels",
 			"feishu",
 			"appSecret"
-		], _FeishuChannelRule.DEFAULT_APP_SECRET);
+		], DEFAULT_FEISHU_APP_SECRET);
 	}
 };
-FeishuChannelRule = _FeishuChannelRule = __decorate([Rule({
+FeishuChannelRule = __decorate([Rule({
 	key: "feishu_channel",
-	dependsOn: ["config_syntax_check"],
+	dependsOn: ["config_syntax_check", "feishu_default_account"],
 	repairMode: "standard"
 })], FeishuChannelRule);
 //#endregion
+//#region src/rules/feishu-default-account.ts
+/**
+* Owner of the multi-agent feishu channel shape: migrates legacy v1/v2
+* (top-level appId + defaultAccount/default) into v3 (`bot-<appId>` account),
+* detects + fixes drift on the main bot's appId/appSecret. Single-agent
+* configs (no `accounts`) are out of scope — handled by `feishu_channel`.
+*/
+let FeishuDefaultAccountRule = class FeishuDefaultAccountRule extends DiagnoseRule {
+	validate(ctx) {
+		const feishu = getNestedMap(ctx.config, "channels", "feishu");
+		if (!feishu) return { pass: true };
+		const accounts = asRecord(feishu.accounts);
+		if (!accounts) return { pass: true };
+		const topAppId = feishu.appId;
+		if (typeof topAppId === "string" && topAppId !== "") return {
+			pass: false,
+			message: "channels.feishu has legacy shape; needs migration to accounts.bot-<appId>"
+		};
+		const mainBot = findMainBotAccount(ctx.config, accounts);
+		if (mainBot) {
+			const expectedAppId = ctx.vars?.feishuAppID;
+			if (typeof expectedAppId === "string" && expectedAppId !== "" && mainBot.acc.appId !== expectedAppId) return {
+				pass: false,
+				message: `accounts.${mainBot.accountId}.appId mismatch: got ${mainBot.acc.appId}, expected ${expectedAppId}`
+			};
+			if (!secretMatchesCanonical(mainBot.acc.appSecret)) return {
+				pass: false,
+				message: `accounts.${mainBot.accountId}.appSecret drift`
+			};
+		}
+		return { pass: true };
+	}
+	repair(ctx) {
+		const feishu = getNestedMap(ctx.config, "channels", "feishu");
+		if (!feishu) return;
+		const accounts = asRecord(feishu.accounts);
+		if (!accounts) return;
+		const topAppId = feishu.appId;
+		if (typeof topAppId === "string" && topAppId !== "") {
+			this.migrate(ctx, feishu, accounts, topAppId);
+			return;
+		}
+		this.enforceMainBotValues(ctx, accounts);
+	}
+	migrate(ctx, feishu, accounts, topAppId) {
+		const effectiveAppId = nonEmpty(ctx.vars?.feishuAppID) ?? topAppId;
+		const expectedKey = `bot-${effectiveAppId}`;
+		const existingBot = asRecord(accounts[expectedKey]) ?? {};
+		const defaultAccount = asRecord(accounts.defaultAccount) ?? {};
+		const defaultAcc = asRecord(accounts.default) ?? {};
+		const merged = {
+			...existingBot,
+			...defaultAccount,
+			...defaultAcc,
+			appId: effectiveAppId,
+			appSecret: DEFAULT_FEISHU_APP_SECRET
+		};
+		const chatID = ctx.vars?.teamChatID;
+		if (typeof chatID === "string" && chatID !== "") {
+			const existingGroups = asRecord(merged.groups) ?? {};
+			if (!(chatID in existingGroups)) merged.groups = {
+				...existingGroups,
+				[chatID]: { requireMention: false }
+			};
+		}
+		accounts[expectedKey] = merged;
+		delete accounts.defaultAccount;
+		delete accounts.default;
+		delete feishu.appId;
+		delete feishu.appSecret;
+		this.rewireBindings(ctx.config, expectedKey);
+	}
+	enforceMainBotValues(ctx, accounts) {
+		const mainBot = findMainBotAccount(ctx.config, accounts);
+		if (!mainBot) return;
+		const acc = accounts[mainBot.accountId];
+		const expectedAppId = nonEmpty(ctx.vars?.feishuAppID);
+		if (expectedAppId !== void 0 && acc.appId !== expectedAppId) acc.appId = expectedAppId;
+		if (!secretMatchesCanonical(acc.appSecret)) acc.appSecret = DEFAULT_FEISHU_APP_SECRET;
+	}
+	rewireBindings(config, expectedKey) {
+		if (!Array.isArray(config.bindings)) return;
+		const bindings = config.bindings;
+		for (const b of bindings) {
+			const match = asRecord(asRecord(b)?.match);
+			if (match && match.channel === "feishu" && (match.accountId === "defaultAccount" || match.accountId === "default")) match.accountId = expectedKey;
+		}
+		const seen = /* @__PURE__ */ new Set();
+		const deduped = [];
+		for (const b of bindings) {
+			const rec = asRecord(b);
+			if (!rec) continue;
+			const match = asRecord(rec.match);
+			const key = JSON.stringify([
+				rec.agentId,
+				match?.channel,
+				match?.accountId
+			]);
+			if (seen.has(key)) continue;
+			seen.add(key);
+			deduped.push(rec);
+		}
+		const mainId = findMainAgent(config)?.id;
+		if (typeof mainId === "string" && mainId !== "") {
+			if (!deduped.some((b) => {
+				const m = asRecord(b.match);
+				return b.agentId === mainId && m?.channel === "feishu" && m?.accountId === expectedKey;
+			})) deduped.push({
+				type: "route",
+				agentId: mainId,
+				match: {
+					channel: "feishu",
+					accountId: expectedKey
+				}
+			});
+		}
+		config.bindings = deduped;
+	}
+};
+FeishuDefaultAccountRule = __decorate([Rule({
+	key: "feishu_default_account",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard"
+})], FeishuDefaultAccountRule);
+function nonEmpty(v) {
+	return typeof v === "string" && v !== "" ? v : void 0;
+}
+function findMainBotAccount(config, accounts) {
+	const mainId = findMainAgent(config)?.id;
+	if (typeof mainId !== "string" || mainId === "") return void 0;
+	const bindings = Array.isArray(config.bindings) ? config.bindings : [];
+	for (const b of bindings) {
+		const rec = asRecord(b);
+		const match = asRecord(rec?.match);
+		if (rec && match && rec.agentId === mainId && match.channel === "feishu") {
+			const accountId = match.accountId;
+			if (typeof accountId === "string") {
+				const acc = asRecord(accounts[accountId]);
+				if (acc) return {
+					accountId,
+					acc
+				};
+			}
+		}
+	}
+}
+/** Bot accounts must carry the canonical provider-ref `appSecret`. */
+function secretMatchesCanonical(secret) {
+	if (typeof secret !== "object" || secret === null || Array.isArray(secret)) return false;
+	return matchMap(secret, DEFAULT_FEISHU_APP_SECRET);
+}
+//#endregion
 //#region src/rules/gateway.ts
 var _GatewayRule;
 let GatewayRule = class GatewayRule extends DiagnoseRule {
@@ -607,12 +869,17 @@ let GatewayRule = class GatewayRule extends DiagnoseRule {
 		_GatewayRule = this;
 	}
 	static DEFAULT_PORT = 18789;
+	static DEFAULT_MODE = "local";
+	static DEFAULT_BIND = "loopback";
 	static DEFAULT_AUTH_MODE = "token";
 	static DEFAULT_AUTH_TOKEN = {
 		source: "file",
 		provider: "miaoda-secret-provider",
 		id: "/gateway_auth_token"
 	};
+	/** Required entries in gateway.trustedProxies. Repair appends any missing
+	*  entries while preserving caller-added extras (no overwrite). */
+	static DEFAULT_TRUSTED_PROXIES = ["::1", "127.0.0.1"];
 	validate(ctx) {
 		const gateway = ctx.config.gateway;
 		if (!gateway || typeof gateway !== "object") return {
@@ -624,6 +891,14 @@ let GatewayRule = class GatewayRule extends DiagnoseRule {
 			pass: false,
 			message: "gateway.port mismatch: got " + gw.port + ", expected " + _GatewayRule.DEFAULT_PORT
 		};
+		if (gw.mode !== _GatewayRule.DEFAULT_MODE) return {
+			pass: false,
+			message: "gateway.mode mismatch: got " + gw.mode + ", expected " + _GatewayRule.DEFAULT_MODE
+		};
+		if (gw.bind !== _GatewayRule.DEFAULT_BIND) return {
+			pass: false,
+			message: "gateway.bind mismatch: got " + gw.bind + ", expected " + _GatewayRule.DEFAULT_BIND
+		};
 		const auth = gw.auth;
 		if (!auth || typeof auth !== "object") return {
 			pass: false,
@@ -658,10 +933,22 @@ let GatewayRule = class GatewayRule extends DiagnoseRule {
 			pass: false,
 			message: "gateway.controlUi.dangerouslyDisableDeviceAuth must be true, got " + controlUi.dangerouslyDisableDeviceAuth
 		};
+		const proxies = gw.trustedProxies;
+		if (!Array.isArray(proxies)) return {
+			pass: false,
+			message: "gateway.trustedProxies missing or not an array"
+		};
+		const missing = _GatewayRule.DEFAULT_TRUSTED_PROXIES.filter((p) => !proxies.includes(p));
+		if (missing.length > 0) return {
+			pass: false,
+			message: "gateway.trustedProxies missing: " + JSON.stringify(missing)
+		};
 		return { pass: true };
 	}
 	repair(ctx) {
 		setNestedValue(ctx.config, ["gateway", "port"], _GatewayRule.DEFAULT_PORT);
+		setNestedValue(ctx.config, ["gateway", "mode"], _GatewayRule.DEFAULT_MODE);
+		setNestedValue(ctx.config, ["gateway", "bind"], _GatewayRule.DEFAULT_BIND);
 		setNestedValue(ctx.config, [
 			"gateway",
 			"auth",
@@ -677,6 +964,14 @@ let GatewayRule = class GatewayRule extends DiagnoseRule {
 			"controlUi",
 			"dangerouslyDisableDeviceAuth"
 		], true);
+		const gw = ctx.config.gateway ?? {};
+		const current = Array.isArray(gw.trustedProxies) ? gw.trustedProxies.slice() : [];
+		const seen = new Set(current.map((v) => String(v)));
+		for (const p of _GatewayRule.DEFAULT_TRUSTED_PROXIES) if (!seen.has(p)) {
+			current.push(p);
+			seen.add(p);
+		}
+		setNestedValue(ctx.config, ["gateway", "trustedProxies"], current);
 	}
 };
 GatewayRule = _GatewayRule = __decorate([Rule({
@@ -863,6 +1158,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;
+		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;
+		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: {
@@ -875,12 +1381,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;
@@ -891,8 +1399,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 {
@@ -944,12 +1454,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();
@@ -965,8 +1477,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) {
@@ -1011,8 +1525,64 @@ 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
+/**
+* Shared CLI log file. Every log line the CLI emits — whether through
+* `console.error` (rules, helpers, errors) or through the per-task
+* `makeLogger` (reset worker) — is tee'd here so operators have a single
+* file to tail when diagnosing a sandbox.
+*
+* `/tmp` is ephemeral on sandbox restart; we rely on that for rotation
+* (no size-based rotation implemented).
+*/
+const CLI_LOG_FILE = "/tmp/openclaw-diagnose/cli.log";
+/** Append one line to the shared cli.log. Swallows any fs error —
+*  logging must never break the business flow. */
+function appendCliLog(line) {
+	try {
+		const dir = node_path.default.dirname(CLI_LOG_FILE);
+		if (!node_fs.default.existsSync(dir)) node_fs.default.mkdirSync(dir, { recursive: true });
+		node_fs.default.appendFileSync(CLI_LOG_FILE, line);
+	} catch {}
+}
+let stderrMirrorInstalled = false;
+/**
+* Install a process-wide `console.error` interceptor that mirrors each
+* line to BOTH the original stderr AND cli.log. Call once at CLI entry
+* before any subcommand dispatch; idempotent.
+*
+* Why console.error and not console.log: the CLI's stdout carries the
+* structured JSON result protocol consumed by sandbox_console and other
+* callers — any log line on stdout would corrupt JSON parsing. Rules,
+* helpers, and error paths therefore must route debug output through
+* console.error (stderr).
+*/
+function installStderrMirror() {
+	if (stderrMirrorInstalled) return;
+	stderrMirrorInstalled = true;
+	const original = console.error.bind(console);
+	console.error = (...args) => {
+		original(...args);
+		const body = args.map((a) => typeof a === "string" ? a : safeStringify(a)).join(" ");
+		appendCliLog(`[${(/* @__PURE__ */ new Date()).toISOString()}] ${body}\n`);
+	};
+}
+function safeStringify(v) {
+	try {
+		return JSON.stringify(v);
+	} catch {
+		return String(v);
+	}
+}
 function makeLogger(logFile) {
 	try {
 		const dir = node_path.default.dirname(logFile);
@@ -1023,9 +1593,143 @@ function makeLogger(logFile) {
 		try {
 			node_fs.default.appendFileSync(logFile, line);
 		} catch {}
+		appendCliLog(line);
 	};
 }
 //#endregion
+//#region src/fs-utils.ts
+/**
+* Rename src → dst, falling back to `mv` (which handles cross-device copy)
+* when the kernel returns EXDEV.
+*
+* Sandbox filesystems can put sibling paths on different "devices" from
+* rename(2)'s point of view: bind mounts, overlayfs copy-up, and
+* mount-point children inside a single directory all trip EXDEV. Seen in
+* production when reset's atomic swap did
+*   /home/gem/.npm-global/lib/node_modules/openclaw → openclaw.bak
+* and the openclaw subdir was a bind-mounted volume.
+*
+* Behavior:
+*   - Happy path hits rename(2) — atomic, single syscall, microseconds.
+*   - EXDEV path shells out to `mv`, which does rename() then copy+unlink
+*     on failure. Non-atomic but correct; callers already have rollback
+*     logic (install-openclaw restores from .bak) so loss of atomicity
+*     only matters if the process dies mid-copy, and that's survivable.
+*   - Any other error (ENOENT, EACCES, EBUSY...) rethrows as-is so callers
+*     see the real problem instead of a misleading `mv` fallback failure.
+*/
+function moveSafe(src, dst) {
+	try {
+		node_fs.default.renameSync(src, dst);
+	} catch (e) {
+		if (e?.code !== "EXDEV") throw e;
+		execCaptureErr(`mv ${shellQuote(src)} ${shellQuote(dst)}`);
+	}
+}
+/**
+* Run a shell command, re-throwing with stderr attached on failure.
+*
+* Node's `execSync(..., { stdio: 'ignore' })` swallows stderr entirely —
+* callers only see "Command failed: <cmd>" with no hint of the real error
+* (ENOSPC, EROFS, "unrecognized option", etc.). Production debugging on
+* sandboxed boxes is painful without the underlying message, so we pipe
+* stderr, capture it, and embed it in the thrown Error. stdout stays
+* suppressed because the commands we run here (tar/mv) are silent on
+* success.
+*/
+function execCaptureErr(cmd) {
+	try {
+		(0, node_child_process.execSync)(cmd, { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+	} catch (e) {
+		const stderr = e?.stderr;
+		const stderrStr = (typeof stderr === "string" ? stderr : stderr?.toString("utf8") ?? "").trim();
+		const base = e?.message ?? "command failed";
+		throw new Error(stderrStr ? `${base}\nstderr: ${stderrStr}` : base);
+	}
+}
+/** POSIX single-quote shell escape. Paths with embedded quotes are rare but
+*  the token-file path conventions in sandboxes don't guarantee cleanliness. */
+function shellQuote(s) {
+	return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* Extract an npm-packed gzipped tarball.
+*
+* ## The problem this works around
+*
+* Some tarballs (openclaw's among them — they're not packed by vanilla
+* `npm pack`) include relative symlinks inside nested .bin/ dirs whose
+* targets contain `..`, e.g.
+*   node_modules/<pkg>/node_modules/.bin/foo -> ../foo/bin/cli.js
+*
+* GNU tar classifies any symlink target with `..` or a leading `/` as
+* "dangerous" and defers its extraction to a post-files pass, while also
+* needing a post-files pass to restore directory permissions/mtimes. The
+* two passes race: the deferred-symlink handling mutates parent-dir inodes,
+* then the directory stat-restore pass does `fstatat()` and the recorded
+* inode doesn't match, firing
+*
+*   tar: <path>: Directory renamed before its status could be extracted
+*
+* from `apply_nonancestor_delayed_set_stat()` in extract.c. This is an
+* `ERROR` (hard-fail, exit 2) — the `--warning=no-rename-directory`
+* keyword controls a different, incremental-archive code path and does
+* NOT silence this. Reference: Paul Eggert, bug-tar 2004-04:
+* https://lists.gnu.org/archive/html/bug-tar/2004-04/msg00021.html
+*
+* ## The fix
+*
+* Pass `--absolute-names` (aka `-P`). Per GNU tar docs, this disables the
+* "normalize dangerous names" logic — including the deferred-symlink pass
+* that's racing us. Also stops stripping leading `/`, but our tarballs
+* only contain relative (`./node_modules/...`) paths so there's nothing
+* to strip. Safe because:
+*   - The tarball is sha512-verified upstream (downloadWithCache)
+*   - All entry paths are relative, no absolute-path escape risk
+*   - All dangerous symlink targets resolve within the extracted tree
+*
+* ## Belt-and-suspenders
+*
+* If some tar variant still emits the error despite -P, we fall through
+* to checking the stderr pattern: if every error line is the benign
+* "Directory renamed …" text (no real failures like ENOSPC/EACCES/gzip
+* CRC/etc.), swallow exit 2. Callers MUST still verify extraction
+* (e.g. `fs.existsSync(path.join(dest, 'package.json'))`) — tar's
+* `skip_this_one = 1` after the error means some dirs missed their
+* mtime/mode restore, but content was written.
+*/
+function extractTarballTolerant(tarball, destDir, opts = {}) {
+	const strip = opts.stripComponents ?? 0;
+	const stripFlag = strip > 0 ? ` --strip-components=${strip}` : "";
+	const cmd = `tar -xzf ${shellQuote(tarball)} -C ${shellQuote(destDir)}${stripFlag} -P`;
+	try {
+		execCaptureErr(cmd);
+		return;
+	} catch (e) {
+		const msg = e?.message ?? "";
+		const hasFalseAlarm = msg.includes("Directory renamed before its status could be extracted");
+		const hasFatal = [
+			/Cannot open/i,
+			/Cannot mkdir/i,
+			/Cannot create/i,
+			/No space left on device/i,
+			/Disk quota exceeded/i,
+			/Permission denied/i,
+			/Read-only file system/i,
+			/unrecognized option/i,
+			/gzip:/i,
+			/Unexpected EOF/i,
+			/Invalid argument/i
+		].some((r) => r.test(msg));
+		if (!hasFalseAlarm || hasFatal) throw e;
+		console.error(`[tar] -P did not suppress "Directory renamed" on ${tarball}; tolerating (content must be verified by caller)`);
+	}
+}
+//#endregion
 //#region src/reset-async.ts
 /**
 * Start an async reset task: spawn a detached child process and return the taskId.
@@ -1048,7 +1752,7 @@ function startAsyncReset(ctxBase64) {
 	const dir = node_path.default.dirname(resultFile);
 	if (!node_fs.default.existsSync(dir)) node_fs.default.mkdirSync(dir, { recursive: true });
 	node_fs.default.writeFileSync(tmpPath, JSON.stringify(initial), "utf-8");
-	node_fs.default.renameSync(tmpPath, resultFile);
+	moveSafe(tmpPath, resultFile);
 	const child = (0, node_child_process.spawn)(process.execPath, [
 		process.argv[1],
 		"reset",
@@ -1072,13 +1776,266 @@ function startAsyncReset(ctxBase64) {
 		};
 		const errTmpPath = resultFile + ".tmp";
 		node_fs.default.writeFileSync(errTmpPath, JSON.stringify(failResult));
-		node_fs.default.renameSync(errTmpPath, resultFile);
+		moveSafe(errTmpPath, resultFile);
 	});
 	child.unref();
 	log(`spawned worker pid=${child.pid}`);
 	return { taskId };
 }
 //#endregion
+//#region src/oss/fetchManifest.ts
+const MANIFEST_PREFIX = "builtin/manifests/openclaw/recommended/";
+const MANIFEST_SUFFIX = ".json";
+async function fetchManifest(ossFileMap, tag) {
+	const key = `${MANIFEST_PREFIX}${tag}${MANIFEST_SUFFIX}`;
+	const url = ossFileMap[key];
+	if (!url) {
+		const available = Object.keys(ossFileMap).filter((k) => k.startsWith(MANIFEST_PREFIX) && k.endsWith(MANIFEST_SUFFIX)).map((k) => k.slice(39, -5));
+		const availStr = available.length ? available.join(", ") : "(none)";
+		throw new Error(`manifest signed URL missing for tag "${tag}" (key ${key}). Available tags in ossFileMap: ${availStr}. Either pass an available tag or update the studio_server TCC openclaw_upgrade_config supported_versions.`);
+	}
+	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}`);
+		}
+		moveSafe(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 newDir = targetDir + ".new";
+	const tarball = await downloadWithCache(pkg, ossFileMap, opts);
+	console.error(`[install-openclaw] tag=${openclawTag} shasum=${pkg.shasum.slice(0, 12)}...`);
+	if (node_fs.default.existsSync(newDir)) node_fs.default.rmSync(newDir, {
+		recursive: true,
+		force: true
+	});
+	if (node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
+		recursive: true,
+		force: true
+	});
+	node_fs.default.mkdirSync(node_path.default.dirname(targetDir), { recursive: true });
+	const tmpStage = node_fs.default.mkdtempSync(node_path.default.join(opts.tmpRoot ?? node_os.default.tmpdir(), "openclaw-install-"));
+	try {
+		extractTarballTolerant(tarball, tmpStage, { stripComponents: 1 });
+		if (!node_fs.default.existsSync(node_path.default.join(tmpStage, "package.json"))) throw new Error("extracted tarball missing package.json");
+		moveSafe(tmpStage, newDir);
+		const hadExisting = node_fs.default.existsSync(targetDir);
+		try {
+			if (hadExisting) moveSafe(targetDir, bakDir);
+			moveSafe(newDir, targetDir);
+		} catch (e) {
+			if (hadExisting && !node_fs.default.existsSync(targetDir) && node_fs.default.existsSync(bakDir)) try {
+				moveSafe(bakDir, targetDir);
+			} catch {}
+			try {
+				node_fs.default.rmSync(newDir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			throw e;
+		}
+		if (hadExisting && node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
+			recursive: true,
+			force: true
+		});
+	} finally {
+		if (node_fs.default.existsSync(tmpStage)) try {
+			node_fs.default.rmSync(tmpStage, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
+	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");
+	moveSafe(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 {
+		extractTarballTolerant(tarball, stagingDir, { stripComponents: 1 });
+		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) moveSafe(destDir, oldDir);
+	moveSafe(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")) {
+		extractTarballTolerant(file, extractDir);
+		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 = [
 	"备份当前配置",
@@ -1087,27 +2044,17 @@ 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 });
 	const tmpPath = resultFile + ".tmp";
 	node_fs.default.writeFileSync(tmpPath, JSON.stringify(result), "utf-8");
-	node_fs.default.renameSync(tmpPath, resultFile);
+	moveSafe(tmpPath, resultFile);
 }
 function updateProgress(resultFile, step, startedAt) {
 	writeResultFile(resultFile, {
@@ -1139,6 +2086,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)) {
@@ -1163,7 +2137,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)) {
@@ -1184,11 +2158,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;
@@ -1216,81 +2193,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) {
@@ -1384,73 +2295,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) {
@@ -1475,26 +2344,38 @@ 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;
+	if (resetData.openclawTag) openclawTag = resetData.openclawTag;
+	else 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);
@@ -1514,22 +2395,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`);
@@ -1540,6 +2422,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
@@ -1581,55 +2470,750 @@ 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 ?? "",
+		teamChatID: typeof src.teamChatID === "string" && src.teamChatID !== "" ? src.teamChatID : void 0,
+		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,
+			teamChatID: ctx.app.teamChatID,
+			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,
+			teamChatID: ctx.app.teamChatID,
+			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,
+			teamChatID: ctx.app.teamChatID,
+			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,
+			openclawTag: ctx.install.openclawTag
+		}
+	};
+}
+//#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/help.ts
+const BIN = "mclaw-diagnose";
+function versionBanner() {
+	return `v0.1.3`;
+}
+const COMMANDS = [
+	{
+		name: "doctor",
+		hidden: false,
+		summary: "Diagnose openclaw config; apply repairs with --fix",
+		help: `USAGE
+  ${BIN} doctor [--fix] [--rule=<key>]...
+
+DESCRIPTION
+  Fetches DoctorCtx via innerapi, then runs one of three modes depending
+  on the flags. Output is a single JSON object on stdout.
+
+MODES
+  (no flags)              Check-only. Runs the rule engine against the
+                          sandbox's current openclaw config and returns
+                            { failedRules: { standard, ai, reset } }
+                          No files are mutated. Use this when you just
+                          want to know what's wrong.
+
+  --fix                   Check + repair-all. First runs the rule engine,
+                          then repairs every failing standard-mode rule.
+                          Returns
+                            { check: {...}, repair: {...} }
+                          Use this as the default "fix everything" action.
+
+  --fix --rule=<key>...   Targeted repair. Skips the check pass entirely
+                          and runs repair against the listed rule keys
+                          only. Unknown keys are silently ignored.
+                          Returns { repair: {...} } with only those
+                          rules' outcomes. Use this when you already
+                          know which rules need fixing.
+
+OPTIONS
+  --fix                   Enable repair. See MODES above.
+  --rule=<key>            Repair only this rule key. Repeatable. Only
+                          meaningful together with --fix.
+
+EXAMPLES
+  ${BIN} doctor                                            # check only
+  ${BIN} doctor --fix                                      # check then repair all
+  ${BIN} doctor --fix --rule=gateway                       # repair 'gateway' only
+  ${BIN} doctor --fix --rule=gateway --rule=jwt_token      # repair multiple
+
+EXIT CODES
+  0    success
+  1    generic error
+  77   innerapi authentication failed (sandbox JWT expired/invalid)
+`
+	},
+	{
+		name: "check",
+		hidden: true,
+		summary: "Run rule-engine check only",
+		help: `USAGE
+  ${BIN} check [--ctx=<base64>]
+
+DESCRIPTION
+  Runs the rule engine against the sandbox's current openclaw config and
+  returns { failedRules }. Used by sandbox_console's push-style callers
+  that already own the ctx — end-users should prefer \`doctor\`.
+
+OPTIONS
+  --ctx=<base64>   Opaque ctx JSON (base64). When absent, fetched from
+                   innerapi (same path as doctor).
+`
+	},
+	{
+		name: "repair",
+		hidden: true,
+		summary: "Apply standard-mode repairs",
+		help: `USAGE
+  ${BIN} repair [--ctx=<base64>]
+
+DESCRIPTION
+  Runs repair for the failing rules listed inside the ctx's repairData.
+  Intended for sandbox_console's push path — end-users should use
+  \`doctor --fix\` instead.
+
+OPTIONS
+  --ctx=<base64>   Opaque ctx JSON (base64). When absent, fetched from
+                   innerapi.
+`
+	},
+	{
+		name: "reset",
+		hidden: true,
+		summary: "Re-initialize sandbox via the 9-step reset pipeline",
+		help: `USAGE
+  ${BIN} reset --async  [--ctx=<base64>]
+  ${BIN} reset --worker --task-id=<id> [--ctx=<base64>]
+
+DESCRIPTION
+  Two-phase pipeline driven asynchronously: the --async invocation spawns
+  a detached worker and returns { taskId } immediately; the --worker
+  invocation (spawned by --async) runs the actual 9 steps and writes
+  progress to /tmp/openclaw-diagnose/reset-<taskId>.json.
+
+  Poll progress with \`${BIN} get_reset_task --task-id=<id>\`.
+
+OPTIONS
+  --async           Start a detached worker and return taskId on stdout.
+  --worker          Internal — run the 9-step pipeline (launched by --async).
+  --task-id=<id>    Required with --worker; identifies the progress file.
+  --ctx=<base64>    Opaque ctx JSON; fetched from innerapi when absent.
+`
+	},
+	{
+		name: "get_reset_task",
+		hidden: true,
+		summary: "Poll progress of an async reset task",
+		help: `USAGE
+  ${BIN} get_reset_task --task-id=<id>
+
+DESCRIPTION
+  Reads /tmp/openclaw-diagnose/reset-<taskId>.json and prints its content
+  as JSON on stdout. Safe to call repeatedly while reset is in progress.
+
+OPTIONS
+  --task-id=<id>    Required. Matches the id returned by \`reset --async\`.
+`
+	},
+	{
+		name: "install-openclaw",
+		hidden: true,
+		summary: "Download + install the openclaw tarball",
+		help: `USAGE
+  ${BIN} install-openclaw <tag> [--ctx=<base64> | --oss_file_map=<base64>]
+
+DESCRIPTION
+  Downloads the openclaw@<tag> tgz via the signed OSS URL found in the
+  ctx's install.ossFileMap, extracts it into a tmpfs staging dir, and
+  atomically swaps it into /home/gem/.npm-global/lib/node_modules/openclaw.
+  Used by step 5 of reset.
+
+ARGUMENTS
+  <tag>                Openclaw version tag, e.g. 2026.4.11.
+
+OPTIONS
+  --ctx=<base64>       Opaque ctx; ossFileMap is extracted from it.
+  --oss_file_map=...   Pre-built OSS URL map (base64 JSON); skips innerapi
+                       entirely. Wins over --ctx when both provided.
+`
+	},
+	{
+		name: "install-extension",
+		hidden: true,
+		summary: "Install openclaw extension package(s)",
+		help: `USAGE
+  ${BIN} install-extension <tag> (--all | --extension=<name>...) [options]
+
+DESCRIPTION
+  Downloads + installs one or more openclaw extension tarballs
+  (feishu, miaoda, etc.) into <home_base>/workspace/agent/extensions/,
+  then splices installMetadata into openclaw.json's plugins.installs
+  unless --skip-config-update is passed.
+
+ARGUMENTS
+  <tag>                Openclaw version tag; extension versions resolved
+                       against the matching manifest.
+
+OPTIONS
+  --all                Install every extension in the manifest.
+  --extension=<name>   Install a specific extension (repeatable).
+  --home_base=<dir>    Override the /home/gem base (tests).
+  --config_path=<p>    Override the openclaw.json path (tests).
+  --skip-config-update Leave plugins.installs in openclaw.json untouched.
+  --ctx=<base64>       Opaque ctx; see install-openclaw for semantics.
+  --oss_file_map=...   Pre-built OSS URL map (base64 JSON).
+`
+	},
+	{
+		name: "download-resource",
+		hidden: true,
+		summary: "Download + extract a single OSS resource",
+		help: `USAGE
+  ${BIN} download-resource <tag> --role=<role> --name=<name> [--dir=<dir>] [options]
+
+DESCRIPTION
+  Downloads one resource (template, config asset, etc.) identified by
+  (role, name) from the manifest and extracts/copies it to <dir>.
+
+ARGUMENTS
+  <tag>                Openclaw version tag.
+
+OPTIONS
+  --role=<role>        Package role (e.g. template, config).
+  --name=<name>        Package name within the role.
+  --dir=<dir>          Target dir (defaults to dirname(pkg.installPath)).
+  --ctx=<base64>       Opaque ctx; ossFileMap is extracted from it.
+  --oss_file_map=...   Pre-built OSS URL map (base64 JSON).
+`
+	}
+];
+function parseHelpFlags(args) {
+	return {
+		help: args.includes("--help") || args.includes("-h"),
+		expert: args.includes("-x") || args.includes("--expert")
+	};
+}
+/**
+* Render the top-level help to the given stream. When `expert` is true,
+* hidden commands are listed alongside the user-facing ones.
+*/
+function formatTopLevelHelp(expert) {
+	const visible = COMMANDS.filter((c) => !c.hidden);
+	const hidden = COMMANDS.filter((c) => c.hidden);
+	const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+	const w = Math.max(...COMMANDS.map((c) => c.name.length)) + 2;
+	const lines = [];
+	lines.push(`${BIN} — OpenClaw config diagnose / repair CLI`);
+	lines.push(versionBanner());
+	lines.push("");
+	lines.push("USAGE");
+	lines.push(`  ${BIN} <command> [options]`);
+	lines.push(`  ${BIN} <command> --help       per-command help`);
+	lines.push(`  ${BIN} --help                 this message`);
+	lines.push("");
+	lines.push("COMMANDS");
+	for (const c of visible) lines.push(`  ${pad(c.name, w)}${c.summary}`);
+	if (expert && hidden.length > 0) {
+		lines.push("");
+		lines.push("INTERNAL COMMANDS (revealed by -x)");
+		for (const c of hidden) lines.push(`  ${pad(c.name, w)}${c.summary}`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+/** Render per-command help. Returns undefined when the name is unknown. */
+function formatCommandHelp(name) {
+	const cmd = COMMANDS.find((c) => c.name === name);
+	if (!cmd) return void 0;
+	return cmd.help;
+}
+//#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);
+const mode = args.find((a) => !a.startsWith("-"));
+/**
+* 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() {
+	installStderrMirror();
+	const helpFlags = parseHelpFlags(args);
+	if (mode && helpFlags.help) {
+		const body = formatCommandHelp(mode);
+		if (body) {
+			node_process.default.stdout.write(body);
+			return;
 		}
-		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");
+		node_process.default.stderr.write(`Unknown command: ${mode}\n\n`);
+		node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));
+		node_process.default.exit(1);
+	}
+	if (!mode) {
+		if (helpFlags.help) {
+			node_process.default.stdout.write(formatTopLevelHelp(helpFlags.expert));
+			return;
+		}
+		node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));
+		node_process.default.exit(1);
+	}
+	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;
+		}
+		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;
 		}
-		console.log(JSON.stringify(getResetTask(taskId)));
-		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;
+		}
+		default:
+			node_process.default.stderr.write(`Unknown command: ${mode}\n\n`);
+			node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));
+			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