From 0796e992e463d836ff35c1fd20cc181b8bf23eed Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 03:58:46 -0400
Subject: [PATCH] docs: document config schema runtime helpers

---
 src/config/agent-limits.ts                              | 1 +
 src/config/channel-capabilities.test.ts                 | 1 +
 src/config/config-misc.test.ts                          | 1 +
 src/config/config.legacy-config-provider-shapes.test.ts | 1 +
 src/config/gateway-dispatch-config.test.ts              | 1 +
 src/config/group-policy.ts                              | 1 +
 src/config/includes-scan.ts                             | 1 +
 src/config/io.shell-env-fallback.test.ts                | 1 +
 src/config/io.ts                                        | 1 +
 src/config/io.write-prepare.test.ts                     | 1 +
 src/config/plugin-auto-enable.model-support.test.ts     | 1 +
 src/config/port-defaults.test.ts                        | 1 +
 src/config/runtime-group-policy.test.ts                 | 1 +
 src/config/runtime-group-policy.ts                      | 1 +
 src/config/runtime-overrides.ts                         | 1 +
 src/config/schema.help.ts                               | 1 +
 src/config/schema.shared.ts                             | 1 +
 src/config/sensitive-paths.ts                           | 1 +
 src/config/talk-defaults.test.ts                        | 1 +
 src/config/types.agents.ts                              | 1 +
 src/config/types.whatsapp.ts                            | 1 +
 src/config/zod-schema.agent-defaults.test.ts            | 1 +
 src/config/zod-schema.markdown-tables.test.ts           | 1 +
 src/config/zod-schema.session.ts                        | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/config/agent-limits.ts b/src/config/agent-limits.ts
index fb001b75059f..7e9a10ba7f33 100644
--- a/src/config/agent-limits.ts
+++ b/src/config/agent-limits.ts
@@ -1,3 +1,4 @@
+// Resolves per-agent runtime limits from config.
 import type { OpenClawConfig } from "./types.js";
 
 /** Default maximum concurrent top-level agent runs. */
diff --git a/src/config/channel-capabilities.test.ts b/src/config/channel-capabilities.test.ts
index 75083317e82c..9d1c2b732aa2 100644
--- a/src/config/channel-capabilities.test.ts
+++ b/src/config/channel-capabilities.test.ts
@@ -1,3 +1,4 @@
+// Covers channel capability config normalization and lookup behavior.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
diff --git a/src/config/config-misc.test.ts b/src/config/config-misc.test.ts
index ad1546ea10ea..fb6404a81f8c 100644
--- a/src/config/config-misc.test.ts
+++ b/src/config/config-misc.test.ts
@@ -1,3 +1,4 @@
+// Covers miscellaneous config schema defaults and validation cases.
 import { describe, expect, it } from "vitest";
 import {
   getConfigValueAtPath,
diff --git a/src/config/config.legacy-config-provider-shapes.test.ts b/src/config/config.legacy-config-provider-shapes.test.ts
index b326bdc690dd..3faf672ffc9f 100644
--- a/src/config/config.legacy-config-provider-shapes.test.ts
+++ b/src/config/config.legacy-config-provider-shapes.test.ts
@@ -1,3 +1,4 @@
+// Regresses legacy provider config shapes accepted by config loading.
 import { describe, expect, it } from "vitest";
 import { normalizeLegacyTalkConfig } from "../commands/doctor/shared/legacy-talk-config-normalizer.js";
 import type { OpenClawConfig } from "./types.js";
diff --git a/src/config/gateway-dispatch-config.test.ts b/src/config/gateway-dispatch-config.test.ts
index 90192efec914..af4e67e798ba 100644
--- a/src/config/gateway-dispatch-config.test.ts
+++ b/src/config/gateway-dispatch-config.test.ts
@@ -1,3 +1,4 @@
+// Covers gateway dispatch config loading and fallback behavior.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/config/group-policy.ts b/src/config/group-policy.ts
index 262123f2704c..a776322be163 100644
--- a/src/config/group-policy.ts
+++ b/src/config/group-policy.ts
@@ -1,3 +1,4 @@
+// Normalizes group-policy config for channel and runtime decisions.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/config/includes-scan.ts b/src/config/includes-scan.ts
index 42d9776fd479..843e9240831b 100644
--- a/src/config/includes-scan.ts
+++ b/src/config/includes-scan.ts
@@ -1,3 +1,4 @@
+// Scans included config files and resolves include graphs.
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { parseJsonWithJson5Fallback } from "../utils/parse-json-compat.js";
diff --git a/src/config/io.shell-env-fallback.test.ts b/src/config/io.shell-env-fallback.test.ts
index f43ffff61413..d594a8676d6c 100644
--- a/src/config/io.shell-env-fallback.test.ts
+++ b/src/config/io.shell-env-fallback.test.ts
@@ -1,3 +1,4 @@
+// Covers shell environment fallback handling in config IO.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/config/io.ts b/src/config/io.ts
index 340038a3a2a3..093cbe9c00ec 100644
--- a/src/config/io.ts
+++ b/src/config/io.ts
@@ -1,3 +1,4 @@
+// Loads, validates, migrates, snapshots, and writes OpenClaw config files.
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
diff --git a/src/config/io.write-prepare.test.ts b/src/config/io.write-prepare.test.ts
index 04b83006fb8a..3a65751549b4 100644
--- a/src/config/io.write-prepare.test.ts
+++ b/src/config/io.write-prepare.test.ts
@@ -1,3 +1,4 @@
+// Covers config write preparation diffs and metadata preservation.
 import { describe, expect, it } from "vitest";
 import {
   collectChangedPaths,
diff --git a/src/config/plugin-auto-enable.model-support.test.ts b/src/config/plugin-auto-enable.model-support.test.ts
index efbef5baa01c..aa430a277d31 100644
--- a/src/config/plugin-auto-enable.model-support.test.ts
+++ b/src/config/plugin-auto-enable.model-support.test.ts
@@ -1,3 +1,4 @@
+// Verifies model-support based plugin auto-enable decisions.
 import { describe, expect, it } from "vitest";
 import type { PluginManifestRegistry } from "../plugins/manifest-registry.js";
 import { applyPluginAutoEnable } from "./plugin-auto-enable.js";
diff --git a/src/config/port-defaults.test.ts b/src/config/port-defaults.test.ts
index a68b0729c3eb..c0d9c6f6c25d 100644
--- a/src/config/port-defaults.test.ts
+++ b/src/config/port-defaults.test.ts
@@ -1,3 +1,4 @@
+// Verifies default port config values and overrides.
 import { describe, expect, it } from "vitest";
 import {
   DEFAULT_BROWSER_CDP_PORT_RANGE_END,
diff --git a/src/config/runtime-group-policy.test.ts b/src/config/runtime-group-policy.test.ts
index 5475fc0643d9..8eb1cd0d639a 100644
--- a/src/config/runtime-group-policy.test.ts
+++ b/src/config/runtime-group-policy.test.ts
@@ -1,3 +1,4 @@
+// Covers runtime group-policy resolution from config and context.
 import { beforeEach, describe, expect, it } from "vitest";
 import {
   GROUP_POLICY_BLOCKED_LABEL,
diff --git a/src/config/runtime-group-policy.ts b/src/config/runtime-group-policy.ts
index eb8fa6e13330..fd5ac235a27c 100644
--- a/src/config/runtime-group-policy.ts
+++ b/src/config/runtime-group-policy.ts
@@ -1,3 +1,4 @@
+// Resolves runtime group-policy settings for channels and sessions.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { GroupPolicy } from "./types.base.js";
 
diff --git a/src/config/runtime-overrides.ts b/src/config/runtime-overrides.ts
index 49ae6cdf68ba..12fea459753c 100644
--- a/src/config/runtime-overrides.ts
+++ b/src/config/runtime-overrides.ts
@@ -1,3 +1,4 @@
+// Applies runtime-only config overrides without mutating persisted config.
 import { isPlainObject } from "../utils.js";
 import { parseConfigPath, setConfigValueAtPath, unsetConfigValueAtPath } from "./config-paths.js";
 import { isBlockedObjectKey } from "./prototype-keys.js";
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
index c0178e8215d5..d25cdec3a44a 100644
--- a/src/config/schema.help.ts
+++ b/src/config/schema.help.ts
@@ -1,3 +1,4 @@
+// Defines user-facing config field help text for docs and UI surfaces.
 import { MEDIA_AUDIO_FIELD_HELP } from "./media-audio-field-metadata.js";
 import { describeTalkSilenceTimeoutDefaults } from "./talk-defaults.js";
 
diff --git a/src/config/schema.shared.ts b/src/config/schema.shared.ts
index af9c59a60b72..4805d765b570 100644
--- a/src/config/schema.shared.ts
+++ b/src/config/schema.shared.ts
@@ -1,3 +1,4 @@
+// Provides shared JSON schema helpers for generated config metadata.
 type JsonSchemaObject = {
   type?: string | string[];
   properties?: Record<string, JsonSchemaObject>;
diff --git a/src/config/sensitive-paths.ts b/src/config/sensitive-paths.ts
index ca55c870f02f..222cebf2f755 100644
--- a/src/config/sensitive-paths.ts
+++ b/src/config/sensitive-paths.ts
@@ -1,3 +1,4 @@
+// Classifies sensitive config paths for redaction and validation.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /**
diff --git a/src/config/talk-defaults.test.ts b/src/config/talk-defaults.test.ts
index ece429fe17d1..9fdb0fa9eb1d 100644
--- a/src/config/talk-defaults.test.ts
+++ b/src/config/talk-defaults.test.ts
@@ -1,3 +1,4 @@
+// Verifies generated talk default config stays aligned with schema.
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/config/types.agents.ts b/src/config/types.agents.ts
index 20805c75cc8a..28911e191df8 100644
--- a/src/config/types.agents.ts
+++ b/src/config/types.agents.ts
@@ -1,3 +1,4 @@
+// Defines agent routing, model, and runtime configuration types.
 import type { ChatType } from "../channels/chat-type.js";
 import type {
   AgentContextLimitsConfig,
diff --git a/src/config/types.whatsapp.ts b/src/config/types.whatsapp.ts
index 3e59d96f24e6..a04914b21532 100644
--- a/src/config/types.whatsapp.ts
+++ b/src/config/types.whatsapp.ts
@@ -1,3 +1,4 @@
+// Defines WhatsApp channel configuration types.
 import type { ReactionLevel } from "../utils/reaction-level.js";
 import type {
   BlockStreamingCoalesceConfig,
diff --git a/src/config/zod-schema.agent-defaults.test.ts b/src/config/zod-schema.agent-defaults.test.ts
index b6b6a1b8b950..d058171bc285 100644
--- a/src/config/zod-schema.agent-defaults.test.ts
+++ b/src/config/zod-schema.agent-defaults.test.ts
@@ -1,3 +1,4 @@
+// Covers agent default schema parsing and compatibility behavior.
 import { describe, expect, it } from "vitest";
 import { validateConfigObject } from "./validation.js";
 import { AgentDefaultsSchema } from "./zod-schema.agent-defaults.js";
diff --git a/src/config/zod-schema.markdown-tables.test.ts b/src/config/zod-schema.markdown-tables.test.ts
index f67dec8b98c9..627f0f30dbeb 100644
--- a/src/config/zod-schema.markdown-tables.test.ts
+++ b/src/config/zod-schema.markdown-tables.test.ts
@@ -1,3 +1,4 @@
+// Verifies markdown table config schema parsing and defaults.
 import { describe, expect, it } from "vitest";
 import { MarkdownTableModeSchema } from "./zod-schema.core.js";
 
diff --git a/src/config/zod-schema.session.ts b/src/config/zod-schema.session.ts
index 534f57315585..6ba221dc7369 100644
--- a/src/config/zod-schema.session.ts
+++ b/src/config/zod-schema.session.ts
@@ -1,3 +1,4 @@
+// Defines session-related Zod schema fragments for config parsing.
 import { normalizeStringifiedOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { z } from "zod";
 import { parseByteSize } from "../cli/parse-bytes.js";