import crypto from "node:crypto";

import fs from "node:fs";

import os from "node:os";

import path from "node:path";

import JSON5 from "json5";

import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope-config.js";

import { ensureOwnerDisplaySecret } from "../agents/owner-display.js";

import { applyRuntimeLegacyConfigMigrations } from "../commands/doctor/shared/runtime-compat-api.js";

import { loadDotEnv } from "../infra/dotenv.js";

import { formatErrorMessage } from "../infra/errors.js";

import { resolveRequiredHomeDir } from "../infra/home-dir.js";

import {

loadShellEnvFallback,

resolveShellEnvFallbackTimeoutMs,

shouldDeferShellEnvFallback,

shouldEnableShellEnvFallback,

} from "../infra/shell-env.js";

import {

collectRelevantDoctorPluginIds,

listPluginDoctorLegacyConfigRules,

} from "../plugins/doctor-contract-registry.js";

import {

loadInstalledPluginIndexInstallRecordsSync,

resolveInstalledPluginIndexRecordsStorePath,

writePersistedInstalledPluginIndexInstallRecordsSync,

} from "../plugins/installed-plugin-index-records.js";

import {

loadPluginMetadataSnapshot,

type PluginMetadataSnapshot,

} from "../plugins/plugin-metadata-snapshot.js";

import { sanitizeTerminalText } from "../terminal/safe-text.js";

import { isRecord } from "../utils.js";

import { VERSION } from "../version.js";

import { DuplicateAgentDirError, findDuplicateAgentDirs } from "./agent-dirs.js";

import { maintainConfigBackups } from "./backup-rotation.js";

import { restoreEnvVarRefs } from "./env-preserve.js";

import {

type EnvSubstitutionWarning,

MissingEnvVarError,

containsEnvVarReference,

resolveConfigEnvVars,

} from "./env-substitution.js";

import { applyConfigEnvVars } from "./env-vars.js";

import {

ConfigIncludeError,

readConfigIncludeFileWithGuards,

resolveConfigIncludes,

} from "./includes.js";

import {

appendConfigAuditRecord,

appendConfigAuditRecordSync,

createConfigWriteAuditRecordBase,

finalizeConfigWriteAuditRecord,

formatConfigOverwriteLogMessage,

type ConfigWriteAuditResult,

} from "./io.audit.js";

import { throwInvalidConfig } from "./io.invalid-config.js";

import {

maybeRecoverSuspiciousConfigRead,

maybeRecoverSuspiciousConfigReadSync,

promoteConfigSnapshotToLastKnownGood as promoteConfigSnapshotToLastKnownGoodWithDeps,

recoverConfigFromLastKnownGood as recoverConfigFromLastKnownGoodWithDeps,

} from "./io.observe-recovery.js";

import { persistGeneratedOwnerDisplaySecret } from "./io.owner-display-secret.js";

import {

collectChangedPaths,

createMergePatch,

formatConfigValidationFailure,

applyUnsetPathsForWrite,

projectSourceOntoRuntimeShape,

restoreEnvRefsFromMap,

resolvePersistCandidateForWrite,

resolveManagedUnsetPathsForWrite,

resolveWriteEnvSnapshotForPath,

} from "./io.write-prepare.js";

import { findLegacyConfigIssues } from "./legacy.js";

import {

asResolvedSourceConfig,

asRuntimeConfig,

materializeRuntimeConfig,

} from "./materialize.js";

import { applyMergePatch } from "./merge-patch.js";

import { resolveConfigPath, resolveStateDir } from "./paths.js";

import {

extractShippedPluginInstallConfigRecords,

stripShippedPluginInstallConfigRecords,

} from "./plugin-install-config-migration.js";

import { applyConfigOverrides } from "./runtime-overrides.js";

import {

clearRuntimeConfigSnapshot as clearRuntimeConfigSnapshotState,

createRuntimeConfigWriteNotification,

finalizeRuntimeSnapshotWrite,

getRuntimeConfigSnapshotMetadata as getRuntimeConfigSnapshotMetadataState,

getRuntimeConfigSnapshot as getRuntimeConfigSnapshotState,

getRuntimeConfigSourceSnapshot as getRuntimeConfigSourceSnapshotState,

loadPinnedRuntimeConfig,

notifyRuntimeConfigWriteListeners,

registerRuntimeConfigWriteListener,

resetConfigRuntimeState as resetConfigRuntimeStateState,

resolveRuntimeConfigCacheKey,

selectApplicableRuntimeConfig,

setRuntimeConfigSnapshot as setRuntimeConfigSnapshotState,

getRuntimeConfigSnapshotRefreshHandler as getRuntimeConfigSnapshotRefreshHandlerState,

setRuntimeConfigSnapshotRefreshHandler as setRuntimeConfigSnapshotRefreshHandlerState,

type ConfigWriteAfterWrite,

type RuntimeConfigWriteNotification,

} from "./runtime-snapshot.js";

import { resolveShellEnvExpectedKeys } from "./shell-env-expected-keys.js";

import type { OpenClawConfig, ConfigFileSnapshot, LegacyConfigIssue } from "./types.js";

import {

validateConfigObjectRawWithPlugins,

validateConfigObjectWithPlugins,

} from "./validation.js";

import { shouldWarnOnTouchedVersion } from "./version.js";

export {

clearRuntimeConfigSnapshotState as clearRuntimeConfigSnapshot,

getRuntimeConfigSnapshotMetadataState as getRuntimeConfigSnapshotMetadata,

getRuntimeConfigSnapshotState as getRuntimeConfigSnapshot,

getRuntimeConfigSourceSnapshotState as getRuntimeConfigSourceSnapshot,

resetConfigRuntimeStateState as resetConfigRuntimeState,

resolveRuntimeConfigCacheKey,

selectApplicableRuntimeConfig,

setRuntimeConfigSnapshotState as setRuntimeConfigSnapshot,

setRuntimeConfigSnapshotRefreshHandlerState as setRuntimeConfigSnapshotRefreshHandler,

};

// Re-export for backwards compatibility

export { CircularIncludeError, ConfigIncludeError } from "./includes.js";

export { MissingEnvVarError } from "./env-substitution.js";

export { resolveShellEnvExpectedKeys } from "./shell-env-expected-keys.js";

type ShippedPluginInstallConfigWriteMigration =

| {

migrated: false;

}

| {

migrated: true;

filePath: string;

previousFile:

| {

existed: false;

}

| {

existed: true;

raw: string;

};

};

type ShippedPluginInstallConfigReadMigration = {

config: unknown;

persistedRootParsed?: unknown;

persistedRootRaw?: string;

};

const CONFIG_HEALTH_STATE_FILENAME = "config-health.json";

const loggedInvalidConfigs = new Set<string>();

type ConfigHealthFingerprint = {

hash: string;

bytes: number;

mtimeMs: number | null;

ctimeMs: number | null;

dev: string | null;

ino: string | null;

mode: number | null;

nlink: number | null;

uid: number | null;

gid: number | null;

hasMeta: boolean;

gatewayMode: string | null;

observedAt: string;

};

type ConfigHealthEntry = {

lastKnownGood?: ConfigHealthFingerprint;

lastPromotedGood?: ConfigHealthFingerprint;

lastObservedSuspiciousSignature?: string | null;

};

type ConfigHealthState = {

entries?: Record<string, ConfigHealthEntry>;

};

export type ParseConfigJson5Result = { ok: true; parsed: unknown } | { ok: false; error: string };

export type ConfigWriteOptions = {

/**

* Read-time env snapshot used to validate `${VAR}` restoration decisions.

* If omitted, write falls back to current process env.

*/

envSnapshotForRestore?: Record<string, string | undefined>;

/**

* Optional safety check: only use envSnapshotForRestore when writing the

* same config file path that produced the snapshot.

*/

expectedConfigPath?: string;

/**

* Paths that must be explicitly removed from the persisted file payload,

* even if schema/default normalization reintroduces them.

*/

unsetPaths?: string[][];

/**

* Internal fast path for callers that already hold a fresh config snapshot.

* Avoids rereading the full config just to prepare an immediate write.

*/

baseSnapshot?: ConfigFileSnapshot;

/**

* Internal one-shot CLI fast path. When no runtime snapshot is active, skip

* the post-write runtime snapshot refresh/reload tail entirely.

*/

skipRuntimeSnapshotRefresh?: boolean;

/**

* Allow intentionally destructive config writes, such as explicit reset flows.

* Normal writers must keep this false so clobbers are rejected before disk commit.

*/

allowDestructiveWrite?: boolean;

/**

* Suppress human-readable output logs (overwrite/anomaly messages).

* Useful when the caller wants machine-readable output only (--json mode).

*/

skipOutputLogs?: boolean;

/**

* Runtime reload intent for observers that react to committed config writes.

* Omitted means the observer should use its normal reload plan.

*/

afterWrite?: ConfigWriteAfterWrite;

};

export type ReadConfigFileSnapshotForWriteResult = {

snapshot: ConfigFileSnapshot;

writeOptions: ConfigWriteOptions;

};

export type ConfigWriteNotification = RuntimeConfigWriteNotification;

export type ConfigSnapshotReadMeasure = <T>(name: string, run: () => T | Promise<T>) => Promise<T>;

export class ConfigRuntimeRefreshError extends Error {

constructor(message: string, options?: { cause?: unknown }) {

super(message, options);

this.name = "ConfigRuntimeRefreshError";

}

}

function hashConfigRaw(raw: string | null): string {

return crypto

.createHash("sha256")

.update(raw ?? "")

.digest("hex");

}

async function tightenStateDirPermissionsIfNeeded(params: {

configPath: string;

env: NodeJS.ProcessEnv;

homedir: () => string;

fsModule: typeof fs;

}): Promise<void> {

if (process.platform === "win32") {

return;

}

const stateDir = resolveStateDir(params.env, params.homedir);

const configDir = path.dirname(params.configPath);

if (path.resolve(configDir) !== path.resolve(stateDir)) {

return;

}

try {

const stat = await params.fsModule.promises.stat(configDir);

const mode = stat.mode & 0o777;

if ((mode & 0o077) === 0) {

return;

}

await params.fsModule.promises.chmod(configDir, 0o700);

} catch {

// Best-effort hardening only; callers still need the config write to proceed.

}

}

export function resolveConfigSnapshotHash(snapshot: {

hash?: string;

raw?: string | null;

}): string | null {

if (typeof snapshot.hash === "string") {

const trimmed = snapshot.hash.trim();

if (trimmed) {

return trimmed;

}

}

if (typeof snapshot.raw !== "string") {

return null;

}

return hashConfigRaw(snapshot.raw);

}

function coerceConfig(value: unknown): OpenClawConfig {

if (!value || typeof value !== "object" || Array.isArray(value)) {

return {};

}

return value as OpenClawConfig;

}

function hasConfigMeta(value: unknown): boolean {

if (!isRecord(value)) {

return false;

}

const meta = value.meta;

return isRecord(meta);

}

function resolveGatewayMode(value: unknown): string | null {

if (!isRecord(value)) {

return null;

}

const gateway = value.gateway;

if (!isRecord(gateway) || typeof gateway.mode !== "string") {

return null;

}

const trimmed = gateway.mode.trim();

return trimmed.length > 0 ? trimmed : null;

}

function collectEnvRefPaths(value: unknown, path: string, output: Map<string, string>): void {

if (typeof value === "string") {

if (containsEnvVarReference(value)) {

output.set(path, value);

}

return;

}

if (Array.isArray(value)) {

value.forEach((item, index) => {

collectEnvRefPaths(item, `${path}[${index}]`, output);

});

return;

}

if (isRecord(value)) {

for (const [key, child] of Object.entries(value)) {

const childPath = path ? `${path}.${key}` : key;

collectEnvRefPaths(child, childPath, output);

}

}

}

function resolveConfigHealthStatePath(env: NodeJS.ProcessEnv, homedir: () => string): string {

return path.join(resolveStateDir(env, homedir), "logs", CONFIG_HEALTH_STATE_FILENAME);

}

function normalizeStatNumber(value: number | null | undefined): number | null {

return typeof value === "number" && Number.isFinite(value) ? value : null;

}

function normalizeStatId(value: number | bigint | null | undefined): string | null {

if (typeof value === "bigint") {

return value.toString();

}

if (typeof value === "number" && Number.isFinite(value)) {

return String(value);

}

return null;

}

function resolveConfigStatMetadata(

stat: fs.Stats | null,

): Pick<ConfigHealthFingerprint, "dev" | "ino" | "mode" | "nlink" | "uid" | "gid"> {

return {

dev: normalizeStatId(stat?.dev ?? null),

ino: normalizeStatId(stat?.ino ?? null),

mode: normalizeStatNumber(stat ? stat.mode & 0o777 : null),

nlink: normalizeStatNumber(stat?.nlink ?? null),

uid: normalizeStatNumber(stat?.uid ?? null),

gid: normalizeStatNumber(stat?.gid ?? null),

};

}

function resolveConfigWriteSuspiciousReasons(params: {

existsBefore: boolean;

previousBytes: number | null;

nextBytes: number | null;

hasMetaBefore: boolean;

gatewayModeBefore: string | null;

gatewayModeAfter: string | null;

}): string[] {

const reasons: string[] = [];

if (!params.existsBefore) {

return reasons;

}

if (

typeof params.previousBytes === "number" &&

typeof params.nextBytes === "number" &&

params.previousBytes >= 512 &&

params.nextBytes < Math.floor(params.previousBytes * 0.5)

) {

reasons.push(`size-drop:${params.previousBytes}->${params.nextBytes}`);

}

if (!params.hasMetaBefore) {

reasons.push("missing-meta-before-write");

}

if (params.gatewayModeBefore && !params.gatewayModeAfter) {

reasons.push("gateway-mode-removed");

}

return reasons;

}

function resolveConfigWriteBlockingReasons(suspicious: string[]): string[] {

return suspicious.filter(

(reason) => reason.startsWith("size-drop:") || reason === "gateway-mode-removed",

);

}

async function readConfigHealthState(deps: Required<ConfigIoDeps>): Promise<ConfigHealthState> {

try {

const healthPath = resolveConfigHealthStatePath(deps.env, deps.homedir);

const raw = await deps.fs.promises.readFile(healthPath, "utf-8");

const parsed = JSON.parse(raw);

return isRecord(parsed) ? (parsed as ConfigHealthState) : {};

} catch {

return {};

}

}

function readConfigHealthStateSync(deps: Required<ConfigIoDeps>): ConfigHealthState {

try {

const healthPath = resolveConfigHealthStatePath(deps.env, deps.homedir);

const raw = deps.fs.readFileSync(healthPath, "utf-8");

const parsed = JSON.parse(raw);

return isRecord(parsed) ? (parsed as ConfigHealthState) : {};

} catch {

return {};

}

}

async function writeConfigHealthState(

deps: Required<ConfigIoDeps>,

state: ConfigHealthState,

): Promise<void> {

try {

const healthPath = resolveConfigHealthStatePath(deps.env, deps.homedir);

await deps.fs.promises.mkdir(path.dirname(healthPath), { recursive: true, mode: 0o700 });

await deps.fs.promises.writeFile(healthPath, `${JSON.stringify(state, null, 2)}\n`, {

encoding: "utf-8",

mode: 0o600,

});

} catch {

// best-effort

}

}

function writeConfigHealthStateSync(deps: Required<ConfigIoDeps>, state: ConfigHealthState): void {

try {

const healthPath = resolveConfigHealthStatePath(deps.env, deps.homedir);

deps.fs.mkdirSync(path.dirname(healthPath), { recursive: true, mode: 0o700 });

deps.fs.writeFileSync(healthPath, `${JSON.stringify(state, null, 2)}\n`, {

encoding: "utf-8",

mode: 0o600,

});

} catch {

// best-effort

}

}

function getConfigHealthEntry(state: ConfigHealthState, configPath: string): ConfigHealthEntry {

const entries = state.entries;

if (!entries || !isRecord(entries)) {

return {};

}

const entry = entries[configPath];

return entry && isRecord(entry) ? entry : {};

}

function setConfigHealthEntry(

state: ConfigHealthState,

configPath: string,

entry: ConfigHealthEntry,

): ConfigHealthState {

return {

...state,

entries: {

...state.entries,

[configPath]: entry,

},

};

}

function isUpdateChannelOnlyRoot(value: unknown): boolean {

if (!isRecord(value)) {

return false;

}

const keys = Object.keys(value);

if (keys.length !== 1 || keys[0] !== "update") {

return false;

}

const update = value.update;

if (!isRecord(update)) {

return false;

}

const updateKeys = Object.keys(update);

return updateKeys.length === 1 && typeof update.channel === "string";

}

function resolveConfigObserveSuspiciousReasons(params: {

bytes: number;

hasMeta: boolean;

gatewayMode: string | null;

parsed: unknown;

lastKnownGood?: ConfigHealthFingerprint;

}): string[] {

const reasons: string[] = [];

const baseline = params.lastKnownGood;

if (!baseline) {

return reasons;

}

if (baseline.bytes >= 512 && params.bytes < Math.floor(baseline.bytes * 0.5)) {

reasons.push(`size-drop-vs-last-good:${baseline.bytes}->${params.bytes}`);

}

if (baseline.hasMeta && !params.hasMeta) {

reasons.push("missing-meta-vs-last-good");

}

if (baseline.gatewayMode && !params.gatewayMode) {

reasons.push("gateway-mode-missing-vs-last-good");

}

if (baseline.gatewayMode && isUpdateChannelOnlyRoot(params.parsed)) {

reasons.push("update-channel-only-root");

}

return reasons;

}

async function readConfigFingerprintForPath(

deps: Required<ConfigIoDeps>,

targetPath: string,

): Promise<ConfigHealthFingerprint | null> {

try {

const raw = await deps.fs.promises.readFile(targetPath, "utf-8");

const stat = await deps.fs.promises.stat(targetPath).catch(() => null);

const parsedRes = parseConfigJson5(raw, deps.json5);

const parsed = parsedRes.ok ? parsedRes.parsed : {};

return {

hash: hashConfigRaw(raw),

bytes: Buffer.byteLength(raw, "utf-8"),

mtimeMs: stat?.mtimeMs ?? null,

ctimeMs: stat?.ctimeMs ?? null,

...resolveConfigStatMetadata(stat),

hasMeta: hasConfigMeta(parsed),

gatewayMode: resolveGatewayMode(parsed),

observedAt: new Date().toISOString(),

};

} catch {

return null;

}

}

function readConfigFingerprintForPathSync(

deps: Required<ConfigIoDeps>,

targetPath: string,

): ConfigHealthFingerprint | null {

try {

const raw = deps.fs.readFileSync(targetPath, "utf-8");

const stat = deps.fs.statSync(targetPath, { throwIfNoEntry: false }) ?? null;

const parsedRes = parseConfigJson5(raw, deps.json5);

const parsed = parsedRes.ok ? parsedRes.parsed : {};

return {

hash: hashConfigRaw(raw),

bytes: Buffer.byteLength(raw, "utf-8"),

mtimeMs: stat?.mtimeMs ?? null,

ctimeMs: stat?.ctimeMs ?? null,

...resolveConfigStatMetadata(stat),

hasMeta: hasConfigMeta(parsed),

gatewayMode: resolveGatewayMode(parsed),

observedAt: new Date().toISOString(),

};

} catch {

return null;

}

}

function formatConfigArtifactTimestamp(ts: string): string {

return ts.replaceAll(":", "-").replaceAll(".", "-");

}

async function persistClobberedConfigSnapshot(params: {

deps: Required<ConfigIoDeps>;

configPath: string;

raw: string;

observedAt: string;

}): Promise<string | null> {

const targetPath = `${params.configPath}.clobbered.${formatConfigArtifactTimestamp(params.observedAt)}`;

try {

await params.deps.fs.promises.writeFile(targetPath, params.raw, {

encoding: "utf-8",

mode: 0o600,

flag: "wx",

});

return targetPath;

} catch {

return null;

}

}

function persistClobberedConfigSnapshotSync(params: {

deps: Required<ConfigIoDeps>;

configPath: string;

raw: string;

observedAt: string;

}): string | null {

const targetPath = `${params.configPath}.clobbered.${formatConfigArtifactTimestamp(params.observedAt)}`;

try {

params.deps.fs.writeFileSync(targetPath, params.raw, {

encoding: "utf-8",

mode: 0o600,

flag: "wx",

});

return targetPath;

} catch {

return null;

}

}

function sameFingerprint(

left: ConfigHealthFingerprint | undefined,

right: ConfigHealthFingerprint,

): boolean {

if (!left) {

return false;

}

return (

left.hash === right.hash &&

left.bytes === right.bytes &&

left.mtimeMs === right.mtimeMs &&

left.ctimeMs === right.ctimeMs &&

left.dev === right.dev &&

left.ino === right.ino &&

left.mode === right.mode &&

left.nlink === right.nlink &&

left.uid === right.uid &&

left.gid === right.gid &&

left.hasMeta === right.hasMeta &&

left.gatewayMode === right.gatewayMode

);

}

async function observeConfigSnapshot(

deps: Required<ConfigIoDeps>,

snapshot: ConfigFileSnapshot,

): Promise<void> {

if (!snapshot.exists || typeof snapshot.raw !== "string") {

return;

}

const stat = await deps.fs.promises.stat(snapshot.path).catch(() => null);

const now = new Date().toISOString();

const current: ConfigHealthFingerprint = {

hash: resolveConfigSnapshotHash(snapshot) ?? hashConfigRaw(snapshot.raw),

bytes: Buffer.byteLength(snapshot.raw, "utf-8"),

mtimeMs: stat?.mtimeMs ?? null,

ctimeMs: stat?.ctimeMs ?? null,

...resolveConfigStatMetadata(stat),

hasMeta: hasConfigMeta(snapshot.parsed),

gatewayMode: resolveGatewayMode(snapshot.resolved),

observedAt: now,

};

let healthState = await readConfigHealthState(deps);

const entry = getConfigHealthEntry(healthState, snapshot.path);

const backupBaseline =

entry.lastKnownGood ??

(await readConfigFingerprintForPath(deps, `${snapshot.path}.bak`)) ??

undefined;

const suspicious = resolveConfigObserveSuspiciousReasons({

bytes: current.bytes,

hasMeta: current.hasMeta,

gatewayMode: current.gatewayMode,

parsed: snapshot.parsed,

lastKnownGood: backupBaseline,

});

if (suspicious.length === 0) {

if (snapshot.valid) {

const nextEntry: ConfigHealthEntry = {

...entry,

lastKnownGood: current,

lastObservedSuspiciousSignature: null,

};

if (

!sameFingerprint(entry.lastKnownGood, current) ||

entry.lastObservedSuspiciousSignature !== null

) {

healthState = setConfigHealthEntry(healthState, snapshot.path, nextEntry);

await writeConfigHealthState(deps, healthState);

}

}

return;

}

const suspiciousSignature = `${current.hash}:${suspicious.join(",")}`;

if (entry.lastObservedSuspiciousSignature === suspiciousSignature) {

return;

}

const backup =

(backupBaseline?.hash ? backupBaseline : null) ??

(await readConfigFingerprintForPath(deps, `${snapshot.path}.bak`));

const clobberedPath = await persistClobberedConfigSnapshot({

deps,

configPath: snapshot.path,

raw: snapshot.raw,

observedAt: now,

});

deps.logger.warn(`Config observe anomaly: ${snapshot.path} (${suspicious.join(", ")})`);

await appendConfigAuditRecord({

fs: deps.fs,

env: deps.env,

homedir: deps.homedir,

record: {

ts: now,

source: "config-io",

event: "config.observe",

phase: "read",

configPath: snapshot.path,

pid: process.pid,

ppid: process.ppid,

cwd: process.cwd(),

argv: process.argv.slice(0, 8),

execArgv: process.execArgv.slice(0, 8),

exists: true,

valid: snapshot.valid,

hash: current.hash,

bytes: current.bytes,

mtimeMs: current.mtimeMs,

ctimeMs: current.ctimeMs,

dev: current.dev,

ino: current.ino,

mode: current.mode,

nlink: current.nlink,

uid: current.uid,

gid: current.gid,

hasMeta: current.hasMeta,

gatewayMode: current.gatewayMode,

suspicious,

lastKnownGoodHash: entry.lastKnownGood?.hash ?? null,

lastKnownGoodBytes: entry.lastKnownGood?.bytes ?? null,

lastKnownGoodMtimeMs: entry.lastKnownGood?.mtimeMs ?? null,

lastKnownGoodCtimeMs: entry.lastKnownGood?.ctimeMs ?? null,

lastKnownGoodDev: entry.lastKnownGood?.dev ?? null,

lastKnownGoodIno: entry.lastKnownGood?.ino ?? null,

lastKnownGoodMode: entry.lastKnownGood?.mode ?? null,

lastKnownGoodNlink: entry.lastKnownGood?.nlink ?? null,

lastKnownGoodUid: entry.lastKnownGood?.uid ?? null,

lastKnownGoodGid: entry.lastKnownGood?.gid ?? null,

lastKnownGoodGatewayMode: entry.lastKnownGood?.gatewayMode ?? null,

backupHash: backup?.hash ?? null,

backupBytes: backup?.bytes ?? null,

backupMtimeMs: backup?.mtimeMs ?? null,

backupCtimeMs: backup?.ctimeMs ?? null,

backupDev: backup?.dev ?? null,

backupIno: backup?.ino ?? null,

backupMode: backup?.mode ?? null,

backupNlink: backup?.nlink ?? null,

backupUid: backup?.uid ?? null,

backupGid: backup?.gid ?? null,

backupGatewayMode: backup?.gatewayMode ?? null,

clobberedPath,

restoredFromBackup: false,

restoredBackupPath: null,

},

});

healthState = setConfigHealthEntry(healthState, snapshot.path, {

...entry,

lastObservedSuspiciousSignature: suspiciousSignature,

});

await writeConfigHealthState(deps, healthState);

}

function observeConfigSnapshotSync(

deps: Required<ConfigIoDeps>,

snapshot: ConfigFileSnapshot,

): void {

if (!snapshot.exists || typeof snapshot.raw !== "string") {

return;

}

const stat = deps.fs.statSync(snapshot.path, { throwIfNoEntry: false }) ?? null;

const now = new Date().toISOString();

const current: ConfigHealthFingerprint = {

hash: resolveConfigSnapshotHash(snapshot) ?? hashConfigRaw(snapshot.raw),

bytes: Buffer.byteLength(snapshot.raw, "utf-8"),

mtimeMs: stat?.mtimeMs ?? null,

ctimeMs: stat?.ctimeMs ?? null,

...resolveConfigStatMetadata(stat),

hasMeta: hasConfigMeta(snapshot.parsed),

gatewayMode: resolveGatewayMode(snapshot.resolved),

observedAt: now,

};

let healthState = readConfigHealthStateSync(deps);

const entry = getConfigHealthEntry(healthState, snapshot.path);

const backupBaseline =

entry.lastKnownGood ??

readConfigFingerprintForPathSync(deps, `${snapshot.path}.bak`) ??

undefined;

const suspicious = resolveConfigObserveSuspiciousReasons({

bytes: current.bytes,

hasMeta: current.hasMeta,

gatewayMode: current.gatewayMode,

parsed: snapshot.parsed,

lastKnownGood: backupBaseline,

});

if (suspicious.length === 0) {

if (snapshot.valid) {

const nextEntry: ConfigHealthEntry = {

...entry,

lastKnownGood: current,

lastObservedSuspiciousSignature: null,

};

if (

!sameFingerprint(entry.lastKnownGood, current) ||

entry.lastObservedSuspiciousSignature !== null

) {

healthState = setConfigHealthEntry(healthState, snapshot.path, nextEntry);

writeConfigHealthStateSync(deps, healthState);

}

}

return;

}

const suspiciousSignature = `${current.hash}:${suspicious.join(",")}`;

if (entry.lastObservedSuspiciousSignature === suspiciousSignature) {

return;

}

const backup =

(backupBaseline?.hash ? backupBaseline : null) ??

readConfigFingerprintForPathSync(deps, `${snapshot.path}.bak`);

const clobberedPath = persistClobberedConfigSnapshotSync({

deps,

configPath: snapshot.path,

raw: snapshot.raw,

observedAt: now,

});

deps.logger.warn(`Config observe anomaly: ${snapshot.path} (${suspicious.join(", ")})`);

appendConfigAuditRecordSync({

fs: deps.fs,

env: deps.env,

homedir: deps.homedir,

record: {

ts: now,

source: "config-io",

event: "config.observe",

phase: "read",

configPath: snapshot.path,

pid: process.pid,

ppid: process.ppid,

cwd: process.cwd(),

argv: process.argv.slice(0, 8),

execArgv: process.execArgv.slice(0, 8),

exists: true,

valid: snapshot.valid,

hash: current.hash,

bytes: current.bytes,

mtimeMs: current.mtimeMs,

ctimeMs: current.ctimeMs,

dev: current.dev,

ino: current.ino,

mode: current.mode,

nlink: current.nlink,

uid: current.uid,

gid: current.gid,

hasMeta: current.hasMeta,

gatewayMode: current.gatewayMode,

suspicious,

lastKnownGoodHash: entry.lastKnownGood?.hash ?? null,

lastKnownGoodBytes: entry.lastKnownGood?.bytes ?? null,

lastKnownGoodMtimeMs: entry.lastKnownGood?.mtimeMs ?? null,

lastKnownGoodCtimeMs: entry.lastKnownGood?.ctimeMs ?? null,

lastKnownGoodDev: entry.lastKnownGood?.dev ?? null,

lastKnownGoodIno: entry.lastKnownGood?.ino ?? null,

lastKnownGoodMode: entry.lastKnownGood?.mode ?? null,

lastKnownGoodNlink: entry.lastKnownGood?.nlink ?? null,

lastKnownGoodUid: entry.lastKnownGood?.uid ?? null,

lastKnownGoodGid: entry.lastKnownGood?.gid ?? null,

lastKnownGoodGatewayMode: entry.lastKnownGood?.gatewayMode ?? null,

backupHash: backup?.hash ?? null,

backupBytes: backup?.bytes ?? null,

backupMtimeMs: backup?.mtimeMs ?? null,

backupCtimeMs: backup?.ctimeMs ?? null,

backupDev: backup?.dev ?? null,

backupIno: backup?.ino ?? null,

backupMode: backup?.mode ?? null,

backupNlink: backup?.nlink ?? null,

backupUid: backup?.uid ?? null,

backupGid: backup?.gid ?? null,

backupGatewayMode: backup?.gatewayMode ?? null,

clobberedPath,

restoredFromBackup: false,

restoredBackupPath: null,

},

});

healthState = setConfigHealthEntry(healthState, snapshot.path, {

...entry,

lastObservedSuspiciousSignature: suspiciousSignature,

});

writeConfigHealthStateSync(deps, healthState);

}

export type ConfigIoDeps = {

fs?: typeof fs;

json5?: typeof JSON5;

env?: NodeJS.ProcessEnv;

homedir?: () => string;

configPath?: string;

logger?: Pick<typeof console, "error" | "warn">;

measure?: ConfigSnapshotReadMeasure;

};

function warnOnConfigMiskeys(raw: unknown, logger: Pick<typeof console, "warn">): void {

if (!raw || typeof raw !== "object") {

return;

}

const gateway = (raw as Record<string, unknown>).gateway;

if (!gateway || typeof gateway !== "object") {

return;

}

if ("token" in (gateway as Record<string, unknown>)) {

logger.warn(

'Config uses "gateway.token". This key is ignored; use "gateway.auth.token" instead.',

);

}

}

function stampConfigVersion(cfg: OpenClawConfig): OpenClawConfig {

const now = new Date().toISOString();

return {

...cfg,

meta: {

...cfg.meta,

lastTouchedVersion: VERSION,

lastTouchedAt: now,

},

};

}

function warnIfConfigFromFuture(cfg: OpenClawConfig, logger: Pick<typeof console, "warn">): void {

const touched = cfg.meta?.lastTouchedVersion;

if (!touched) {

return;

}

if (shouldWarnOnTouchedVersion(VERSION, touched)) {

logger.warn(

`Config was last written by a newer OpenClaw (${touched}); current version is ${VERSION}.`,

);

}

}

function resolveConfigPathForDeps(deps: Required<ConfigIoDeps>): string {

if (deps.configPath) {

return deps.configPath;

}

return resolveConfigPath(deps.env, resolveStateDir(deps.env, deps.homedir));

}

function normalizeDeps(overrides: ConfigIoDeps = {}): Required<ConfigIoDeps> {

return {

fs: overrides.fs ?? fs,

json5: overrides.json5 ?? JSON5,

env: overrides.env ?? process.env,

homedir:

overrides.homedir ?? (() => resolveRequiredHomeDir(overrides.env ?? process.env, os.homedir)),

configPath: overrides.configPath ?? "",

logger: overrides.logger ?? console,

measure: overrides.measure ?? (async (_name, run) => await run()),

};

}

function maybeLoadDotEnvForConfig(env: NodeJS.ProcessEnv): void {

// Only hydrate dotenv for the real process env. Callers using injected env

// objects (tests/diagnostics) should stay isolated.

if (env !== process.env) {

return;

}

loadDotEnv({ quiet: true });

}

export function parseConfigJson5(

raw: string,

json5: { parse: (value: string) => unknown } = JSON5,

): ParseConfigJson5Result {

try {

return { ok: true, parsed: json5.parse(raw) };

} catch (err) {

return { ok: false, error: String(err) };

}

}

function findJsonRootSuffix(

raw: string,

json5: { parse: (value: string) => unknown } = JSON5,

): { raw: string; parsed: unknown } | null {

if (/^\s*(?:\{|\[)/.test(raw)) {

return null;

}