### Fixes

- Gateway/diagnostics: add opt-in critical memory pressure stability snapshots with gateway logs, V8 heap, cgroup, active-resource, and redacted large session-file evidence. Fixes #82518.

- CLI/config: show concise human config-write output with an indented backup path instead of printing checksum-heavy overwrite audit details by default.

- CLI/docs: call the canonical lowercase docs MCP search tool and surface MCP errors instead of returning empty search results. Fixes #82702. (#82704) Thanks @hclsys.

- QA-Lab: ignore heartbeat-only operational transcripts when capturing runtime parity cells so background checks cannot replace the scenario reply. (#80323) Thanks @100yenadmin.

c79ffc4fd2a7aa7e33a3fa12f22b3d42658a3148f9927c638afdc0fee5512f00 config-baseline.json

b2c0fbfdbfc23bd617233e9b78740aa2b5e0f272f5c666e90c2504a8887ae6b8 config-baseline.core.json

240af35b9ff0d5f6cdef89ddea23ddbec55e8c152648eb039814ed2bd3985161 config-baseline.json

58c0e8c24b8811be2727a3fbf4848807b047cfed17076d3997f24a0636db5ac0 config-baseline.core.json

fe4f1cb00d7d1dee9746779ec3cf14236e5f672c91502268a12ad6e467a2c4ad config-baseline.channel.json

e9049ce0154f484f44bb0ac174a44198269256044da5ba62a6e107e78bfd7a70 config-baseline.plugin.json

"source": "Gateway",

"target": "Gateway 网关"

},

{

"source": "Gateway health",

"target": "Gateway 健康"

},

{

"source": "Gateway RPC reference",

"target": "Gateway RPC 参考"

flags: ["telegram.*"],

stuckSessionWarnMs: 30000,

stuckSessionAbortMs: 300000,

memoryPressureSnapshot: false,

otel: {

enabled: false,

- `flags`: array of flag strings enabling targeted log output (supports wildcards like `"telegram.*"` or `"*"`).

- `stuckSessionWarnMs`: no-progress age threshold in ms for classifying long-running processing sessions as `session.long_running`, `session.stalled`, or `session.stuck`. Reply, tool, status, block, and ACP progress reset the timer; repeated `session.stuck` diagnostics back off while unchanged.

- `stuckSessionAbortMs`: no-progress age threshold in ms before eligible stalled active work may be abort-drained for recovery. When unset, OpenClaw uses the safer extended embedded-run window of at least 5 minutes and 3x `stuckSessionWarnMs`.

- `memoryPressureSnapshot`: captures a redacted pre-OOM stability snapshot when memory pressure reaches `critical` (default: `false`). Set to `true` to add the stability bundle file scan/write while keeping normal memory pressure events.

- `otel.enabled`: enables the OpenTelemetry export pipeline (default: `false`). For the full configuration, signal catalog, and privacy model, see [OpenTelemetry export](/gateway/opentelemetry).

- `otel.endpoint`: collector URL for OTel export.

- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: optional signal-specific OTLP endpoints. When set, they override `otel.endpoint` for that signal only.

Disabling diagnostics reduces bug-report detail. It does not affect normal

Gateway logging.

Critical memory pressure snapshots are off by default. To keep diagnostics

events and also capture the pre-OOM stability snapshot:

```json5

{

diagnostics: {

memoryPressureSnapshot: true,

},

}

```

Use this only on hosts that can tolerate the extra file-system scan and snapshot

write during critical memory pressure. Normal memory pressure events still

record RSS, heap, threshold, and growth facts when the snapshot is off.

## Related

- [Health checks](/gateway/health)

- Creds on disk: `ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).

- Session store: `ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.

- Relink flow: `openclaw channels logout && openclaw channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)

- Diagnostics are enabled by default. The gateway records operational facts unless `diagnostics.enabled: false` is set. Memory events record RSS/heap byte counts, threshold pressure, and growth pressure. Liveness warnings record event-loop delay, event-loop utilization, CPU-core ratio, and active/waiting/queued session counts when the process is running but saturated. Oversized-payload events record what was rejected, truncated, or chunked, plus sizes and limits when available. They do not record the message text, attachment contents, webhook body, raw request or response body, tokens, cookies, or secret values. The same heartbeat starts the bounded stability recorder, which is available through `openclaw gateway stability` or the `diagnostics.stability` Gateway RPC. Fatal Gateway exits, shutdown timeouts, and restart startup failures persist the latest recorder snapshot under `~/.openclaw/logs/stability/` when events exist; inspect the newest saved bundle with `openclaw gateway stability --bundle latest`.

- Diagnostics are enabled by default. The gateway records operational facts unless `diagnostics.enabled: false` is set. Memory events record RSS/heap byte counts, threshold pressure, and growth pressure. Critical memory pressure logs through the gateway logger. When `diagnostics.memoryPressureSnapshot: true` is set, critical memory pressure also writes a pre-OOM stability bundle with V8 heap stats, Linux cgroup counters when available, active resource counts, and the largest session/transcript files by redacted relative path. Liveness warnings record event-loop delay, event-loop utilization, CPU-core ratio, and active/waiting/queued session counts when the process is running but saturated. Oversized-payload events record what was rejected, truncated, or chunked, plus sizes and limits when available. They do not record the message text, attachment contents, webhook body, raw request or response body, tokens, cookies, or secret values. The same heartbeat starts the bounded stability recorder, which is available through `openclaw gateway stability` or the `diagnostics.stability` Gateway RPC. Fatal Gateway exits, shutdown timeouts, and restart startup failures persist the latest recorder snapshot under `~/.openclaw/logs/stability/` when events exist; critical memory pressure does too only when `diagnostics.memoryPressureSnapshot: true` is set. Inspect the newest saved bundle with `openclaw gateway stability --bundle latest`.

- For bug reports, run `openclaw gateway diagnostics export` and attach the generated zip. The export combines a Markdown summary, the newest stability bundle, sanitized log metadata, sanitized Gateway status/health snapshots, and config shape. It is meant to be shared: chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, and secret values are omitted or redacted. See [Diagnostics Export](/gateway/diagnostics).

## Health monitor config

- [Configuration](/gateway/configuration)

- [Doctor](/gateway/doctor)

## Gateway exits during high memory use

Use this when the Gateway disappears under load, the supervisor reports an OOM-style restart, or logs mention `critical memory pressure bundle written`.

```bash

openclaw gateway status --deep

openclaw logs --follow

openclaw gateway stability --bundle latest

openclaw gateway diagnostics export

```

Look for:

- `Reason: diagnostic.memory.pressure.critical` in the latest stability bundle.

- `Memory pressure:` with `critical/rss_threshold`, `critical/heap_threshold`, or `critical/rss_growth`.

- `V8 heap:` values near the heap limit.

- `Largest session files:` entries such as `agents/<agent>/sessions/<session>.jsonl` or `sessions/<session>.jsonl`.

- Linux cgroup memory counters when the gateway runs inside a container or memory-limited service.

Common signatures:

- `critical memory pressure bundle written` appears shortly before restart → OpenClaw captured a pre-OOM stability bundle. Inspect it with `openclaw gateway stability --bundle latest`.

- `memory pressure: level=critical ... memoryPressureSnapshot=disabled` appears in gateway logs → OpenClaw detected critical memory pressure, but the pre-OOM stability snapshot is off.

- `Largest session files:` points at a very large redacted transcript path → reduce retained session history, inspect session growth, or move old transcripts out of the active store before restarting.

- `V8 heap:` used bytes are close to the heap limit → lower prompt/session pressure, reduce concurrent work, or raise the Node heap limit only after confirming the workload is expected.

- `Memory pressure: critical/rss_growth` → memory grew quickly inside one sampling window. Check the latest logs for a large import, runaway tool output, repeated retries, or a batch of queued agent work.

- Critical memory pressure appears in logs but no bundle exists → this is the default. Set `diagnostics.memoryPressureSnapshot: true` to capture the pre-OOM stability bundle on future critical memory pressure events.

The stability bundle is payload-free. It includes operational memory evidence and redacted relative file paths, not message text, webhook bodies, credentials, tokens, cookies, or raw session ids. Attach the diagnostics export to bug reports instead of copying raw logs.

Related:

- [Gateway health](/gateway/health)

- [Diagnostics export](/gateway/diagnostics)

- [Sessions](/cli/sessions)

## Gateway rejected invalid config

Use this when Gateway startup fails with `Invalid config` or hot reload logs say

uptimeMs: 2000,

},

host: { hostname: "test-host" },

evidence: {

memoryPressure: {

level: "critical",

reason: "rss_threshold",

memory: {

rssBytes: 4096,

heapTotalBytes: 2048,

heapUsedBytes: 1536,

externalBytes: 128,

arrayBuffersBytes: 64,

},

thresholdBytes: 3000,

heapStatistics: {

totalHeapSizeBytes: 2048,

totalHeapSizeExecutableBytes: 256,

totalPhysicalSizeBytes: 2048,

totalAvailableSizeBytes: 8192,

usedHeapSizeBytes: 1536,

heapSizeLimitBytes: 4096,

mallocedMemoryBytes: 32,

externalMemoryBytes: 128,

},

activeResources: {

total: 2,

byType: { Timeout: 2 },

},

topSessionFiles: [

{

relativePath: "agents/<agent>/sessions/<session>.jsonl",

sizeBytes: 4096,

mtimeMs: Date.parse("2026-04-22T12:00:00.000Z"),

},

],

},

},

snapshot: {

generatedAt: "2026-04-22T12:00:00.000Z",

capacity: 1000,

expect(callGateway).not.toHaveBeenCalled();

expect(output).toContain("Stability bundle");

expect(output).toContain("gateway.restart_startup_failed");

expect(output).toContain("Memory pressure");

expect(output).toContain("rss_threshold");

expect(output).toContain("Largest session files");

expect(output).toContain("agents/<agent>/sessions/<session>.jsonl");

expect(output).toContain("payload.large");

expect(output).toContain("gateway.http.json");

} finally {

lines.push(`${colorize(rich, theme.muted, "Error:")} ${errorParts.join(" ")}`);

}

}

const memoryPressure = bundle.evidence?.memoryPressure;

if (memoryPressure) {

lines.push(

`${colorize(rich, theme.muted, "Memory pressure:")} ${memoryPressure.level}/${

memoryPressure.reason

} rss=${formatBytes(memoryPressure.memory.rssBytes)} heap=${formatBytes(

memoryPressure.memory.heapUsedBytes,

)} threshold=${formatBytes(memoryPressure.thresholdBytes)}`,

);

if (memoryPressure.heapStatistics) {

lines.push(

`${colorize(rich, theme.muted, "V8 heap:")} used=${formatBytes(

memoryPressure.heapStatistics.usedHeapSizeBytes,

)} limit=${formatBytes(

memoryPressure.heapStatistics.heapSizeLimitBytes,

)} available=${formatBytes(memoryPressure.heapStatistics.totalAvailableSizeBytes)}`,

);

}

if (memoryPressure.activeResources) {

const resources = Object.entries(memoryPressure.activeResources.byType)

.map(([type, count]) => `${type}=${count}`)

.join(", ");

lines.push(

`${colorize(rich, theme.muted, "Active resources:")} total=${

memoryPressure.activeResources.total

}${resources ? ` · ${resources}` : ""}`,

);

}

if (memoryPressure.topSessionFiles?.length) {

const files = memoryPressure.topSessionFiles

.slice(0, 5)

.map((file) => `${file.relativePath}=${formatBytes(file.sizeBytes)}`)

.join(", ");

lines.push(`${colorize(rich, theme.muted, "Largest session files:")} ${files}`);

}

}

lines.push("", ...renderStabilitySummary(snapshot, rich));

return lines;

}

});

});

describe("legacy diagnostics memory pressure snapshot migrate", () => {

it("renames the boolean toggle", () => {

const res = migrateLegacyConfigForTest({

diagnostics: {

enabled: true,

memoryPressureBundle: false,

},

});

expect(res.config?.diagnostics).toEqual({

enabled: true,

memoryPressureSnapshot: false,

});

expect(res.changes).toStrictEqual([

"Moved diagnostics.memoryPressureBundle → memoryPressureSnapshot.",

]);

});

it("preserves the renamed toggle when both keys are present", () => {

const res = migrateLegacyConfigForTest({

diagnostics: {

memoryPressureBundle: false,

memoryPressureSnapshot: true,

},

});

expect(res.config?.diagnostics).toEqual({

memoryPressureSnapshot: true,

});

expect(res.changes).toStrictEqual([

"Removed diagnostics.memoryPressureBundle (memoryPressureSnapshot already set).",

]);

});

it("moves nested enabled to the renamed boolean", () => {

const res = migrateLegacyConfigForTest({

diagnostics: {

enabled: true,

memoryPressureBundle: {

enabled: false,

},

},

});

expect(res.config?.diagnostics).toEqual({

enabled: true,

memoryPressureSnapshot: false,

});

expect(res.changes).toStrictEqual([

"Moved diagnostics.memoryPressureBundle → memoryPressureSnapshot.",

]);

});

it("moves empty object form to the renamed default boolean", () => {

const res = migrateLegacyConfigForTest({

diagnostics: {

memoryPressureBundle: {},

},

});

expect(res.config?.diagnostics).toEqual({

memoryPressureSnapshot: true,

});

expect(res.changes).toStrictEqual([

"Moved diagnostics.memoryPressureBundle → memoryPressureSnapshot.",

]);

});

});

describe("legacy thread binding spawn migrate", () => {

it("moves matching split spawn flags to unified spawnSessions", () => {

const res = migrateLegacyConfigForTest({