chore(sync): mirror docs from openclaw/openclaw@e69da9d578

.openclaw-sync/source.json

@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "072e73d7c30e215084c3fa3c2d1807af7028b1ec",
-  "syncedAt": "2026-04-29T18:43:52.081Z"
+  "sha": "e69da9d5781c0f60ee10ffcec6aa78e1994a416c",
+  "syncedAt": "2026-04-29T18:55:20.228Z"
 }

docs/cli/gateway.md

@@ -112,6 +112,7 @@ Inline `--password` can be exposed in local process listings. Prefer `--password
 ### Startup profiling
 
 - Set `OPENCLAW_GATEWAY_STARTUP_TRACE=1` to log phase timings during Gateway startup, including per-phase `eventLoopMax` delay and plugin lookup-table timings for installed-index, manifest registry, startup planning, and owner-map work.
+- Set `OPENCLAW_DIAGNOSTICS=timeline` with `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` to write a best-effort JSONL startup diagnostics timeline for external QA harnesses. You can also enable the flag with `diagnostics.flags: ["timeline"]` in config; the path is still env-provided. Add `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` to include event-loop samples.
 - Run `pnpm test:startup:gateway -- --runs 5 --warmup 1` to benchmark Gateway startup. The benchmark records first process output, `/healthz`, `/readyz`, startup trace timings, event-loop delay, and plugin lookup-table timing details.
 
 ## Query a running Gateway

docs/diagnostics/flags.md

@@ -50,6 +50,43 @@ Disable all flags:
 OPENCLAW_DIAGNOSTICS=0
 ```
 
+## Timeline artifacts
+
+The `timeline` flag writes structured startup and runtime timing events for
+external QA harnesses:
+
+```bash
+OPENCLAW_DIAGNOSTICS=timeline \
+OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
+openclaw gateway run
+```
+
+You can also enable it in config:
+
+```json
+{
+  "diagnostics": {
+    "flags": ["timeline"]
+  }
+}
+```
+
+The timeline file path still comes from
+`OPENCLAW_DIAGNOSTICS_TIMELINE_PATH`. When `timeline` is enabled only from
+config, the earliest config-loading spans are not emitted because OpenClaw has
+not read config yet; subsequent startup spans use the config flag.
+
+`OPENCLAW_DIAGNOSTICS=1`, `OPENCLAW_DIAGNOSTICS=all`, and
+`OPENCLAW_DIAGNOSTICS=*` also enable the timeline because they enable every
+diagnostics flag. Prefer `timeline` when you only want the JSONL timing
+artifact.
+
+Timeline records use the `openclaw.diagnostics.v1` envelope. Events can include
+process ids, phase names, span names, durations, plugin ids, dependency counts,
+event-loop delay samples, provider operation names, child-process exit state,
+and startup error names/messages. Treat timeline files as local diagnostics
+artifacts; review them before sharing outside your machine.
+
 ## Where logs go
 
 Flags emit logs into the standard diagnostics log file. By default: