Severity Assessment

CVSS Assessment

Threat Model Alignment

Classification: security-specific

This is a security-specific availability failure, not a documentation defect. The crash loop affects internet-exposed Fly.io gateway deployments on first boot, which is precisely when operators have the least monitoring and recovery capability. The --bind lan flag is required for Fly.io's HTTP proxy to reach the gateway, making the crash unavoidable for any deployment following the official fly.toml template. The auto-generated gateway token persisted to /data/openclaw.json before the crash creates a latent credential exposure risk: the operator cannot retrieve the token through normal channels, and the token persists on the volume across restarts, available to anyone with SSH access to the Fly VM.

Impact

Any operator who deploys OpenClaw to Fly.io using the provided fly.toml template will experience a gateway that crashes on every startup, making the service permanently unavailable. The auto-generated auth token is written to the persistent /data volume before the crash, but the operator has no in-band way to retrieve it or recover the deployment without SSH console access.

Affected Component

File: openclaw/fly.toml:18

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

File: openclaw/src/gateway/server-runtime-config.ts:138-147

if (
  controlUiEnabled &&
  !isLoopback(bind) &&
  allowedOrigins.length === 0
) {
  throw new Error(
    "non-loopback Control UI requires gateway.controlUi.allowedOrigins"
  );
}

File: openclaw/src/gateway/server.impl.ts:284-289

const authConfig = await ensureGatewayStartupAuth(cliParams, {
  persist: true,
  stateDir: runtimePaths.stateDir,
  logger: scopedLogger("startup-auth"),
});

Technical Reproduction

1. Clone the repository and deploy to Fly.io using fly deploy with the provided fly.toml unmodified.
2. Observe that fly logs shows the gateway process starting, ensureGatewayStartupAuth auto-generating a token (no OPENCLAW_GATEWAY_TOKEN env var is set), writing it to /data/openclaw.json (the persistent openclaw_data Fly volume), then resolveGatewayRuntimeConfig throwing: "non-loopback Control UI requires gateway.controlUi.allowedOrigins".
3. The process exits non-zero. Fly restarts it. Every subsequent restart hits the same throw because controlUiEnabled defaults to true (server-runtime-config.ts:76), bind is lan (0.0.0.0, non-loopback), and no OPENCLAW_GATEWAY_ALLOWED_ORIGINS is set in [env].

Demonstrated Impact

The root cause is a three-way interaction:

1. fly.toml specifies --bind lan (resolves to 0.0.0.0) and omits both OPENCLAW_GATEWAY_TOKEN and any controlUi.allowedOrigins configuration.
2. ensureGatewayStartupAuth (called with persist: true) auto-generates a token and writes it to /data/openclaw.json before resolveGatewayRuntimeConfig is called.
3. resolveGatewayRuntimeConfig unconditionally throws when controlUiEnabled=true (the default), bind is non-loopback, and allowedOrigins is empty — which is exactly the state every fresh Fly deployment is in.

The crash happens after the token is persisted, so every restart sees a token already on disk (skipping re-generation) but still hits the same throw. The deployment is permanently wedged. The operator cannot retrieve the auto-generated token via the application; they must manually SSH into the Fly VM and read /data/openclaw.json directly. Additionally, --allow-unconfigured in the command line does not bypass this check — it only bypasses the gateway.mode=local check (run.ts:318-331).

The trust boundary impact is that the gateway never accepts connections, so all external-to-gateway traffic is denied. However, the persistent volume now contains a gateway token the operator may not know exists, creating a latent credential management problem if/when the deployment is eventually fixed.

Environment

Reproduced by static analysis against the repository. Affects any Fly.io deployment using fly.toml or fly.private.toml as provided. Both files contain the same --bind lan command with no OPENCLAW_GATEWAY_ALLOWED_ORIGINS in their [env] blocks. The [mounts] section in both files maps source = "openclaw_data" to destination = "/data", confirming the persistent volume is always present.

Remediation Advice

Either add OPENCLAW_CONTROL_UI_ENABLED = "false" to the [env] block in fly.toml (and fly.private.toml) to disable the Control UI for non-loopback deploys, or add a placeholder OPENCLAW_GATEWAY_ALLOWED_ORIGINS env var with documentation instructing operators to set it before deploying. Additionally, add OPENCLAW_GATEWAY_TOKEN as a placeholder env var (or reference a Fly secret) so operators understand they must configure authentication before the first deploy.