解读文件：gateway/server.impl.ts

第一阶段：配置 & 认证（Config + Auth）

整体大纲如下：

startGatewayServer() //L572-822 — startGatewayServer 第一阶段主体

│  

|-server-startup-config.ts — loadGatewayStartupConfigSnapshot + prepareGatewayStartupConfig + createRuntimeSecretsActivator

├─ bootstrapGatewayNetworkRuntime()        // L619-620 网络栈初始化   

│     └─  server-network-runtime.ts — bootstrapGatewayNetworkRuntime（undici 代理初始化）

├─ createGatewayStartupTrace()             // L643, 启动性能打点器

│

├─ loadGatewayStartupConfigSnapshot()      // L652 ① 读取配置文件快照

│     └─ 返回 { snapshot, sourceConfig, pluginMetadataSnapshot }

│

├─ applyConfigOverrides(configSnapshot)    // ② 应用命令行覆盖

│

├─ prepareGatewayStartupConfig()           // L712-719 ③ 认证准备

│     ├─ resolveGatewayAuth() → // L1049-1056 解析 auth mode（token/device/tailscale）

|     |- auth.ts — resolveGatewayAuth + 认证授权核心逻辑      

|     |-auth-resolve.ts — auth mode 解析（token/password/tailscale/trusted-proxy）

│     ├─ 如果缺 token → 自动生成 + 持久化

|     |-startup-auth.ts — ensureGatewayStartupAuth（token 自动生成逻辑）

│     └─ activateRuntimeSecrets → // L695-702激活加密凭据

│

├─ isDiagnosticsEnabled()                  // L763 isDiagnosticsEnabled ④ 诊断开关

├─ setGatewaySigusr1RestartPolicy()        // L771 ⑤ SIGUSR1 重启策略

├─ setPreRestartDeferralCheck()            // L773-782 ⑥ 重启前检查（队列/连接/任务）

L575 — Promise<GatewayServer>

返回Promise<GatewayServer>，Promise<T> 是 JavaScript/TypeScript 的异步容器类型。Promise<GatewayServer> 表示这个函数不直接返回 GatewayServer 对象，而是返回一个"承诺"——异步操作完成后会给你一个 GatewayServer。调用方需要 await 或 .then() 才能拿到实际值。

// 调用方必须 await，才能拿到实际值。如：

const server: GatewayServer = await startGatewayServer(18789);

在源代码里的签名是：

L576 — normalizeStateDirEnv(process.env)

规范化 STATE_DIR  / OPENCLAW_STATE_DIR 等路径相关的环境变量，确保后续代码读取到的路径是标准化过的。

L577-589 — 数据库包导入

import 数据库相关的包，并行导入了三个模块：

openclaw-database-preflight.js（数据库预检）

openclaw-agent-db.js（agent 数据库）

openclaw-state-db.js（状态数据库）

L590-596 — 数据库 schema 预检

preflightOpenClawDatabaseSchemas 用实际运行环境变量和两个数据库支持的 schema 版本来做预检。

 L597-610 — 不兼容 schema 抛异常

如果数据库schema里有不兼容的，把所有不兼容的schema，记录异常日志，抛出 OpenClawDatabaseSchemaPreflightError。

L611-618 — 不确定的 schema

如果有不确定的schema，对 databaseSchemas.indeterminate 只打 warn 日志，不阻断启动。

L618-619 — 网络栈初始化

初始化 gateway 的网络运行时

L622-623 — 最小测试 Gateway

是否需要进行gateway最小测试，如果是测试运行环境，且OPENCLAW_TEST_MINIMAL_GATEWAY=1时，进行最小测试，否则不进行；

 L635-642 — 重启日志跟踪恢复

先尝试从环境变量恢复重启 trace，如果 resumeGatewayRestartTraceFromEnv 返回 false（表示环境变量中找不到恢复信息），再 fallback 到 handoff 文件。意味着如果从 env 恢复失败，才走 handoff

L643 — 启动性能打点

启动性能打点器；

L644-660 — 懒加载链路

懒加载配置模块-> 懒加载启动插件模块 -> await 配置模块（此时才真正加载）

 -> 启动前加载环境变量 -> 启动配置文件加载，读取配置文件快照 ；

L662 — auth 参数结构化复制

如果参数中有认证的参数，就把这些参数复制一份，结构化，用来重写认证参数。structuredClone 做深拷贝，防止意外修改原始参数。

L666-675 — Control UI Seed

minimalTestGateway 为 true 时直接跳过 seed，seededAllowedOrigins 设为 false；否则调用 maybeSeedControlUiAllowedOriginsAtStartup 真实创建 seed。

L676-682 — startupConfigSnapshot 合并

seed 成功后，用 seed 产出的 config 覆盖快照中的 runtimeConfig 和 config。

L684-693 — emitSecretsStateEvent

闭包函数，封装了 code、message、sessionKey、contextKey，调用 enqueueSystemEvent 放入消息队列。

L694 — 「真正启动配置文件模块」

真正启动配置文件模块

 L695-702 — 创建 secrets 激活器

创建运行时 secrets 激活器，用于激活加密凭据。createRuntimeSecretsActivator 接收日志、状态事件发射器、channel 抑制参数等，返回 activateRuntimeSecrets 函数（此时只是创建，还未调用）。

L709-721 — 认证准备

认证服务启动。传入快照、auth/tailscale 覆盖参数、secrets 激活器、日志、measure 等。

L712-718，认证准备。

需要准备：配置文件快照、启动之后认证参数会被覆盖、tailscaleOverride、激活运行时加密、日志、measure对象；传入快照、auth/tailscale 覆盖参数、secrets 激活器、日志、measure 等。

L727-749 — resolvedStartupAuthOverride 过滤

遍历 ["mode", "token", "password", "allowTailscale", "rateLimit", "trustedProxy"]

跳过 undefined 值

跳过 token/password 中值为 SecretRef 的情况（secret ref 单独处理）

通过的 key-value 用 structuredClone 深拷贝后组装进 resolvedStartupAuthOverride

L750-759 — startupAuthSecretRefOverride

通过token和password来认证。。专门处理 token 和 password 的 isSecretRef 情况，将它们分离到 startupAuthSecretRefOverride，后面会走 secret 解密链路。

 L760-762 — 合并 generatedToken

有动态生成的 token 就合并进去，否则直接用过滤后的覆盖配置。

L763-770 — 诊断开关

是否开启诊断。isDiagnosticsEnabled(cfgAtStart) 判断是否开启，开启则调 startDiagnosticHeartbeat。

L771 — 重启策略

设置gateway重启策略；

 L773-782 — 重启前检查

重启前检查（队列/连接/任务）检查总队列数+总pending回复数+活跃的嵌入式 run

+活跃的定时任务数+活跃的exec会话数+活跃的gateway工作数+活跃的task数（初始是0）；

L783-785 — seededControlUiAllowedOrigins

这是一个只读取值，如果 seed 成功了，取出 allowedOrigins；否则为 undefined。这不是"设置"而是"读取"。

L786-823 — applyFixedGatewayOverlays

设置网关认证配置参数。函数将 reloadAuthOverride、startupTailscaleOverride 和 seededControlUiAllowedOrigins 作为固定覆盖层 merge 到运行时 config 中：