docs: document config recovery helpers

src/config/backup-rotation.ts

@@ -1,3 +1,4 @@
+// Rotates config backup files while preserving recent recovery points.
 import path from "node:path";
 
 const CONFIG_BACKUP_COUNT = 5;

src/config/config.acp-binding-cutover.test.ts

@@ -1,3 +1,4 @@
+// Regresses ACP binding cutover config compatibility behavior.
 import { describe, expect, it } from "vitest";
 import { OpenClawSchema } from "./zod-schema.js";
 

src/config/config.web-search-provider.test.ts

@@ -1,3 +1,4 @@
+// Covers web-search provider config parsing and provider defaults.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { testing as webSearchTesting } from "../agents/tools/web-search.js";
 import { buildWebSearchProviderConfig } from "./test-helpers.js";

src/config/cron-limits.ts

@@ -1,3 +1,4 @@
+// Computes cron scheduling limits from config.
 import type { CronConfig } from "./types.cron.js";
 
 /** Default maximum number of cron jobs allowed to run at once. */

src/config/future-version-guard.test.ts

@@ -1,3 +1,4 @@
+// Verifies config loading rejects unsupported future versions.
 import { describe, expect, it } from "vitest";
 import {
   ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS_ENV,

src/config/gateway-control-ui-origins.test.ts

@@ -1,3 +1,4 @@
+// Covers gateway Control UI origin parsing and defaults.
 import { describe, expect, it } from "vitest";
 import { ensureControlUiAllowedOriginsForNonLoopbackBind } from "./gateway-control-ui-origins.js";
 

src/config/gateway-control-ui-origins.ts

@@ -1,3 +1,4 @@
+// Resolves allowed Control UI origins for gateway access.
 import { DEFAULT_GATEWAY_PORT } from "./paths.js";
 import type { OpenClawConfig } from "./types.openclaw.js";
 

src/config/gateway-dispatch-config.ts

@@ -1,3 +1,4 @@
+// Loads gateway dispatch config from runtime state and files.
 import fs from "node:fs";
 import path from "node:path";
 import { parseJsonWithJson5Fallback } from "../utils/parse-json-compat.js";

src/config/io.best-effort.test.ts

@@ -1,3 +1,4 @@
+// Covers best-effort config IO reads and warning behavior.
 import fs from "node:fs/promises";
 import { describe, expect, it } from "vitest";
 import {

src/config/io.clobber-snapshot.ts

@@ -1,3 +1,4 @@
+// Detects suspicious config clobbers and finds recovery snapshots.
 import path from "node:path";
 
 /** Maximum retained clobbered-config snapshots per config file. */

src/config/io.observe-recovery.ts

@@ -1,3 +1,4 @@
+// Observes and recovers config files that appear missing, corrupt, or clobbered.
 import crypto from "node:crypto";
 import path from "node:path";
 import { isRecord } from "../utils.js";

src/config/issue-format.ts

@@ -1,3 +1,4 @@
+// Formats config validation issues for CLI and diagnostics.
 import { sanitizeTerminalText } from "../../packages/terminal-core/src/safe-text.js";
 import type { ConfigValidationIssue } from "./types.js";
 

src/config/merge-patch.ts

@@ -1,3 +1,4 @@
+// Applies JSON merge-patch updates to config-like objects.
 import { isPlainObject } from "../infra/plain-object.js";
 import { isBlockedObjectKey } from "./prototype-keys.js";
 

src/config/normalize-paths.ts

@@ -1,3 +1,4 @@
+// Normalizes path-like config values to canonical user paths.
 import { isPlainObject, resolveUserPath } from "../utils.js";
 import type { OpenClawConfig } from "./types.js";
 

src/config/plugin-auto-enable.channels.test.ts

@@ -1,3 +1,4 @@
+// Covers channel-driven plugin auto-enable decisions.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

src/config/sessions.cache.test.ts

@@ -1,3 +1,4 @@
+// Verifies session config cache invalidation and reload behavior.
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";

src/config/types.discord.ts

@@ -1,3 +1,4 @@
+// Defines Discord channel configuration types.
 import type {
   ChannelPreviewStreamingConfig,
   ChannelStreamingProgressConfig,

src/config/types.node-host.ts

@@ -1,3 +1,4 @@
+// Defines node-host browser proxy configuration types.
 export type NodeHostBrowserProxyConfig = {
   /** Enable the browser proxy on the node host (default: true). */
   enabled?: boolean;

src/config/types.tools.ts

@@ -1,3 +1,4 @@
+// Defines tool availability and allowlist configuration types.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { ChatType } from "../channels/chat-type.js";
 import type { SafeBinProfileFixture } from "../infra/exec-safe-bin-policy.js";

src/config/validation.cold-imports.test.ts

@@ -1,3 +1,4 @@
+// Guards config validation modules against expensive cold imports.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

src/config/version.test.ts

@@ -1,3 +1,4 @@
+// Verifies config version handling and future-version guards.
 import { describe, expect, it } from "vitest";
 import {
   compareOpenClawVersions,

src/config/zod-schema.providers-googlechat.ts

@@ -1,3 +1,4 @@
+// Defines Google Chat provider schema fragments.
 import { z } from "zod";
 import { ChannelBotLoopProtectionSchema } from "./zod-schema.channels-config.js";
 import { ChannelHealthMonitorSchema } from "./zod-schema.channels.js";

src/config/zod-schema.proxy.test.ts

@@ -1,3 +1,4 @@
+// Covers proxy schema parsing and validation behavior.
 import { describe, it, expect } from "vitest";
 import { ProxyConfigSchema } from "./zod-schema.proxy.js";
 

src/config/zod-schema.ts

@@ -1,3 +1,4 @@
+// Assembles the canonical Zod schema for OpenClaw config parsing.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeStringifiedOptionalString,