diff --git a/src/gateway/assistant-identity.ts b/src/gateway/assistant-identity.ts
index f448345a2e57..63138d0aece5 100644
--- a/src/gateway/assistant-identity.ts
+++ b/src/gateway/assistant-identity.ts
@@ -1,3 +1,5 @@
+// Gateway assistant identity resolver.
+// Combines UI, agent config, and workspace identity files for Control UI display.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { resolveAgentIdentity } from "../agents/identity.js";
 import { loadAgentIdentity } from "../commands/agents.config.js";
@@ -81,6 +83,7 @@ function normalizeEmojiValue(value: string | undefined): string | undefined {
   return trimmed;
 }
 
+/** Resolve the display name/avatar/emoji for an agent-facing assistant identity. */
 export function resolveAssistantIdentity(params: {
   cfg: OpenClawConfig;
   agentId?: string | null;
diff --git a/src/gateway/chat-display-projection.ts b/src/gateway/chat-display-projection.ts
index 8f1991b59344..ff5c6cbfa031 100644
--- a/src/gateway/chat-display-projection.ts
+++ b/src/gateway/chat-display-projection.ts
@@ -1,3 +1,5 @@
+// Gateway chat display projection.
+// Converts raw transcript messages into bounded Control UI/history display records.
 import { createHash } from "node:crypto";
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { asOptionalRecord as readRecord } from "@openclaw/normalization-core/record-coerce";
@@ -35,6 +37,7 @@ type PendingMessageToolVisibleReply = {
   succeeded: boolean;
 };
 
+/** Resolve the text cap used when projecting chat history for display. */
 export function resolveEffectiveChatHistoryMaxChars(_cfg: unknown, maxChars?: number): number {
   if (typeof maxChars === "number") {
     return maxChars;
@@ -55,6 +58,7 @@ function truncateChatHistoryText(
   };
 }
 
+/** Return true for known tool-call/tool-result block type spellings in transcripts. */
 export function isToolHistoryBlockType(type: unknown): boolean {
   if (typeof type !== "string") {
     return false;
diff --git a/src/gateway/http-endpoint-helpers.ts b/src/gateway/http-endpoint-helpers.ts
index 29a9c53b0f9c..047f0bd4502a 100644
--- a/src/gateway/http-endpoint-helpers.ts
+++ b/src/gateway/http-endpoint-helpers.ts
@@ -1,3 +1,5 @@
+// Gateway HTTP endpoint helpers.
+// Wraps common POST JSON method, auth, scope, and body handling.
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { AuthRateLimiter } from "./auth-rate-limit.js";
 import type { ResolvedGatewayAuth } from "./auth.js";
@@ -13,8 +15,6 @@ import {
 } from "./http-utils.js";
 import { authorizeOperatorScopesForMethod } from "./method-scopes.js";
 
-// Generic POST+JSON endpoint wrapper used by gateway HTTP surfaces that share
-// auth, scope, body-size, and method handling but implement their own payload.
 /** Handles a gateway POST JSON endpoint and returns the parsed body when authorized. */
 export async function handleGatewayPostJsonEndpoint(
   req: IncomingMessage,
diff --git a/src/gateway/node-registry.ts b/src/gateway/node-registry.ts
index 2081c9ed6988..c427d874c483 100644
--- a/src/gateway/node-registry.ts
+++ b/src/gateway/node-registry.ts
@@ -1,3 +1,5 @@
+// Gateway node registry.
+// Tracks connected node clients, invoke requests, broadcasts, and system.run approvals.
 import { randomUUID } from "node:crypto";
 import {
   addTimerTimeoutGraceMs,
@@ -9,8 +11,6 @@ import { logRejectedLargePayload } from "../logging/diagnostic-payload.js";
 import { MAX_BUFFERED_BYTES } from "./server-constants.js";
 import type { GatewayWsClient } from "./server/ws-types.js";
 
-// Registry for connected Gateway nodes plus invoke and system.run authorization state.
-
 /** Connected node session advertised over Gateway websocket. */
 export type NodeSession = {
   nodeId: string;
diff --git a/src/gateway/operator-approval-runtime-token.ts b/src/gateway/operator-approval-runtime-token.ts
index 48e65a631479..0b8ea24e7d5f 100644
--- a/src/gateway/operator-approval-runtime-token.ts
+++ b/src/gateway/operator-approval-runtime-token.ts
@@ -1,3 +1,5 @@
+// Operator approval runtime token.
+// Provides a process-local loopback token for approval helper clients.
 import { randomBytes, timingSafeEqual } from "node:crypto";
 
 let approvalRuntimeToken: string | null = null;
diff --git a/src/gateway/plugin-channel-reload-targets.ts b/src/gateway/plugin-channel-reload-targets.ts
index d578a00462d4..c89f4ad28ae0 100644
--- a/src/gateway/plugin-channel-reload-targets.ts
+++ b/src/gateway/plugin-channel-reload-targets.ts
@@ -1,9 +1,8 @@
+// Gateway channel plugin reload targeting.
+// Maps channel/plugin ids and aliases to config path prefixes for hot reload.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { ChannelId } from "../channels/plugins/index.js";
 
-// Channel plugin reload targeting maps a channel id, plugin id, and aliases to
-// config path prefixes so hot reload can decide whether a change affects a
-// specific channel runtime.
 export type ChannelPluginReloadTarget = {
   channelId: ChannelId;
   pluginId?: string | null;
diff --git a/src/gateway/server-channel-runtime.types.ts b/src/gateway/server-channel-runtime.types.ts
index a92fea7c517b..a3fdf7bf5243 100644
--- a/src/gateway/server-channel-runtime.types.ts
+++ b/src/gateway/server-channel-runtime.types.ts
@@ -1,7 +1,7 @@
+// Gateway channel runtime snapshot types.
+// Exposes read-only channel/account state to status and server-method surfaces.
 import type { ChannelId, ChannelAccountSnapshot } from "../channels/plugins/types.public.js";
 
-// Channel runtime snapshots are the read-only Gateway view of channel/account
-// state used by status and server-method surfaces.
 /** Snapshot of channel runtime state keyed by channel and account id. */
 export type ChannelRuntimeSnapshot = {
   channels: Partial<Record<ChannelId, ChannelAccountSnapshot>>;
diff --git a/src/gateway/server-model-catalog.ts b/src/gateway/server-model-catalog.ts
index ade35a49bce4..4482fa7a9837 100644
--- a/src/gateway/server-model-catalog.ts
+++ b/src/gateway/server-model-catalog.ts
@@ -1,3 +1,5 @@
+// Gateway model catalog cache.
+// Serves model catalogs with stale-while-refresh behavior for Gateway surfaces.
 import { getRuntimeConfig } from "../config/io.js";
 
 export type GatewayModelChoice = import("../agents/model-catalog.js").ModelCatalogEntry;
@@ -88,6 +90,7 @@ function startGatewayModelCatalogRefresh(
   return refresh;
 }
 
+/** Mark cached model catalogs stale after config/plugin reload changes. */
 export function markGatewayModelCatalogStaleForReload(): void {
   readOnlyModelCatalogCache.staleGeneration += 1;
   fullModelCatalogCache.staleGeneration += 1;
@@ -103,6 +106,7 @@ export async function resetModelCatalogCacheForTest(): Promise<void> {
   resetModelCatalogCacheForTestLocal();
 }
 
+/** Load the Gateway model catalog, returning cached data while stale refreshes run. */
 export async function loadGatewayModelCatalog(
   params?: LoadGatewayModelCatalogParams,
 ): Promise<GatewayModelChoice[]> {
diff --git a/src/gateway/server-node-events-types.ts b/src/gateway/server-node-events-types.ts
index 0a848e6ef6c2..2d21c7f165e1 100644
--- a/src/gateway/server-node-events-types.ts
+++ b/src/gateway/server-node-events-types.ts
@@ -1,3 +1,5 @@
+// Gateway node event types.
+// Defines the narrowed context and event envelope for node-originated handlers.
 import type { ModelCatalogEntry } from "../agents/model-catalog.js";
 import type { CliDeps } from "../cli/deps.types.js";
 import type { HealthSummary } from "../commands/health.js";
@@ -5,8 +7,6 @@ import type { ChatAbortControllerEntry } from "./chat-abort.js";
 import type { ChatRunEntry } from "./server-chat.js";
 import type { DedupeEntry } from "./server-shared.js";
 
-// Node event handlers receive a narrowed context instead of the full gateway
-// request context so node-originated events can mutate only the state they own.
 /** Runtime context available to node event handlers. */
 export type NodeEventContext = {
   deps: CliDeps;
diff --git a/src/gateway/server-startup-memory.ts b/src/gateway/server-startup-memory.ts
index e56f6fcfef68..bf54e45b2a04 100644
--- a/src/gateway/server-startup-memory.ts
+++ b/src/gateway/server-startup-memory.ts
@@ -1,3 +1,5 @@
+// Gateway memory startup helper.
+// Starts qmd memory boot sync for eligible agents without loading every agent.
 import { listAgentEntries, listAgentIds, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { resolveMemorySearchConfig } from "../agents/memory-search.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/gateway/session-transcript-path.ts b/src/gateway/session-transcript-path.ts
index 5d7fbbd44e4f..33dcac528a5e 100644
--- a/src/gateway/session-transcript-path.ts
+++ b/src/gateway/session-transcript-path.ts
@@ -1,10 +1,10 @@
+// Session transcript path comparison helper.
+// Normalizes transcript paths for cache, history, and update matching.
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
-/**
- * Resolves transcript file paths into a stable comparison key for history and update matching.
- */
+/** Resolve a transcript file path into a stable comparison key. */
 export function resolveTranscriptPathForComparison(value: string | undefined): string | undefined {
   const trimmed = normalizeOptionalString(value);
   if (!trimmed) {
diff --git a/src/gateway/startup-auth.ts b/src/gateway/startup-auth.ts
index 56f588cf7169..265a36addf55 100644
--- a/src/gateway/startup-auth.ts
+++ b/src/gateway/startup-auth.ts
@@ -1,3 +1,5 @@
+// Gateway startup auth preparation.
+// Merges auth overrides, resolves secret refs, validates weak secrets, and generates fallbacks.
 import crypto from "node:crypto";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { GatewayAuthConfig, GatewayTailscaleConfig } from "../config/types.gateway.js";