File interpreted: gateway/server.impl.ts
Phase 1: Config & Auth
Overall outline:
text
startGatewayServer() // L572-822 --- startGatewayServer phase 1 body
│
├─ server-startup-config.ts --- loadGatewayStartupConfigSnapshot + prepareGatewayStartupConfig + createRuntimeSecretsActivator
├─ bootstrapGatewayNetworkRuntime() // L619-620 Network stack initialisation
│ └─ server-network-runtime.ts --- bootstrapGatewayNetworkRuntime (undici proxy init)
├─ createGatewayStartupTrace() // L643, startup performance tracer
│
├─ loadGatewayStartupConfigSnapshot() // L652 ① Load config snapshot
│ └─ returns { snapshot, sourceConfig, pluginMetadataSnapshot }
│
├─ applyConfigOverrides(configSnapshot) // ② Apply CLI overrides
│
├─ prepareGatewayStartupConfig() // L712-719 ③ Auth preparation
│ ├─ resolveGatewayAuth() → // L1049-1056 resolve auth mode (token/device/tailscale)
│ │ ├─ auth.ts --- resolveGatewayAuth + core auth logic
│ │ └─ auth-resolve.ts --- auth mode parsing (token/password/tailscale/trusted-proxy)
│ ├─ if token missing → auto‑generate + persist
│ │ └─ startup-auth.ts --- ensureGatewayStartupAuth (token auto‑generation)
│ └─ activateRuntimeSecrets → // L695-702 activate encrypted credentials
│
├─ isDiagnosticsEnabled() // L763 ④ diagnostics switch
├─ setGatewaySigusr1RestartPolicy() // L771 ⑤ SIGUSR1 restart policy
├─ setPreRestartDeferralCheck() // L773-782 ⑥ pre‑restart checks (queues/connections/tasks)
L575 – Promise
Promise indicates that this function does not return a GatewayServer object directly, but rather a “promise” that will resolve to a GatewayServer once the asynchronous operation completes. Callers must await or use .then() to obtain the actual value.
typescript
// Caller must await to get the actual value:
const server: GatewayServer = await startGatewayServer(18789);
The signature in the source code is:
L576 – normalizeStateDirEnv(process.env)
Normalises environment variables such as STATE_DIR / OPENCLAW_STATE_DIR and other path‑related variables, ensuring that subsequent code reads standardised paths.
L577‑589 – Database package imports
Imports database‑related packages, in parallel:
openclaw-database-preflight.js (database pre‑flight checks)
openclaw-agent-db.js (agent database)
openclaw-state-db.js (state database)
L590‑596 – Database schema pre‑flight
preflightOpenClawDatabaseSchemas performs pre‑flight checks using the actual runtime environment and two database schema versions.
L597‑610 – Incompatible schemas throw errors
If any incompatible database schemas are found, all of them are logged, and an OpenClawDatabaseSchemaPreflightError is thrown.
L611‑618 – Indeterminate schemas
If there are indeterminate schemas, only a warn log is emitted for databaseSchemas.indeterminate; startup is not blocked.
L618‑619 – Network stack initialisation
Initialises the Gateway’s network runtime.
L622‑623 – Minimal test Gateway
Checks whether a minimal Gateway test is required. If it is a test environment and OPENCLAW_TEST_MINIMAL_GATEWAY=1, then a minimal test is performed; otherwise, it is skipped.
L635‑642 – Restart trace recovery
First attempts to restore the restart trace from environment variables. If resumeGatewayRestartTraceFromEnv returns false (meaning no recovery info is found in the environment), it falls back to the handoff file. This means the handoff path is only taken when environment‑based recovery fails.
L643 – Startup performance tracer
Starts the performance tracer.
L644‑660 – Lazy loading chain
Lazy‑loads the config module → then lazy‑loads the startup plugins module → await on the config module (at this point it is actually loaded) → loads environment variables before startup → loads the startup config file and reads the config snapshot.
L662 – Structured copy of auth parameters
If authentication parameters are present in the arguments, they are copied in a structured way to override auth settings. structuredClone performs a deep copy to prevent accidental modification of the original parameters.
L666‑675 – Control UI Seed
When minimalTestGateway is true, seeding is skipped and seededAllowedOrigins is set to false; otherwise, maybeSeedControlUiAllowedOriginsAtStartup is called to actually create the seed.
L676‑682 – Merge startupConfigSnapshot
After seeding succeeds, the config produced by the seed overrides the runtimeConfig and config fields in the snapshot.
L684‑693 – emitSecretsStateEvent
A closure that encapsulates code, message, sessionKey, contextKey, and calls enqueueSystemEvent to put them into the message queue.
L694 – “Really start the config module”
Actually starts the config module.
L695‑702 – Create secrets activator
Creates the runtime secrets activator, used to activate encrypted credentials. createRuntimeSecretsActivator receives logger, state event emitter, channel suppression parameters, etc., and returns an activateRuntimeSecrets function (created here but not yet invoked).
L709‑721 – Auth preparation
Auth service startup. Passes in snapshot, auth/tailscale override parameters, secrets activator, logger, measure, etc.
L712‑718 – Auth preparation (detailed)
Prepares config snapshot, startup auth override parameters, tailscale override, runtime secrets activation, logger, measure, etc.
L727‑749 – Filter resolvedStartupAuthOverride
Iterates over ["mode", "token", "password", "allowTailscale", "rateLimit", "trustedProxy"]
Skips undefined values
Skips cases where token/password are SecretRef (handled separately)
Key‑value pairs that pass are deep‑cloned via structuredClone and assembled into resolvedStartupAuthOverride
L750‑759 – startupAuthSecretRefOverride
Handles authentication via token and password. Specifically deals with isSecretRef cases for token and password, separating them into startupAuthSecretRefOverride to be processed later through the secret decryption path.
L760‑762 – Merge generatedToken
If a dynamically generated token exists, merge it in; otherwise, use the filtered override configuration directly.
L763‑770 – Diagnostics switch
Checks whether diagnostics are enabled via isDiagnosticsEnabled(cfgAtStart). If enabled, calls startDiagnosticHeartbeat.
L771 – Restart policy
Sets the Gateway restart policy.
L773‑782 – Pre‑restart checks
Checks before restart: total queue count, total pending replies, active embedded runs, active scheduled tasks, active exec sessions, active Gateway workers, and active tasks (initial value 0).
L783‑785 – seededControlUiAllowedOrigins
This is a read‑only value. If seeding succeeded, allowedOrigins is taken from the seed; otherwise it is undefined. This is not a “set” operation, but a “read”.
L786‑823 – applyFixedGatewayOverlays
Sets Gateway authentication config parameters. This function merges reloadAuthOverride, startupTailscaleOverride, and seededControlUiAllowedOrigins as fixed overlays into the runtime config.
A book on “OpenClaw Source Code Decoding” is in the pipeline – publishers and editors are welcome to get in touch.
Top comments (0)