#11158: doctor: warn when system RAM is at or below 2 GB (deafult in the most cloud platform)
commands
stale
Cluster:
Memory Management Enhancements
**Title:** Doctor: warn when system RAM is at or below 2 GB
---
#### Summary
Add a low-memory warning to `openclaw doctor` that fires when total system RAM is 2 GB or less. Many cheap cloud VMs (default tier on most providers) ship with only 2 GB, and running `doctor` or other heavy operations on them can OOM the process silently. This surfaces the problem early and suggests adding swap.
#### Use Cases
- Users deploying OpenClaw on budget cloud VMs (Vultr, DigitalOcean, Hetzner, etc.) with 2 GB RAM hit OOM during `openclaw doctor` with no prior warning.
- The warning appears at the top of the doctor output so users see it before any heavy checks run.
#### Behavior Changes
- `openclaw doctor` now calls `noteLowMemoryWarning()` early in its flow (before config loading and gateway health checks).
- On systems with total RAM <= 2 GB, a "Low memory" note is printed with the detected RAM, the 2048 MB threshold, and a `fallocate` swap command.
- On systems with > 2 GB RAM, no output change.
#### Codebase and GitHub Search
- [x] Searched codebase for existing memory/RAM checks: none found (`os.totalmem` unused prior to this PR).
- [x] Searched GitHub issues for "OOM", "low memory", "doctor memory": no existing issue.
#### Tests
- `doctor-platform-notes.low-memory.test.ts` (3 tests, all passing):
- Warns at exactly 2 GB (boundary)
- Warns at 512 MB (well below threshold)
- Silent at 4 GB (above threshold)
```
pnpm test -- --run src/commands/doctor-platform-notes.low-memory.test.ts
✓ src/commands/doctor-platform-notes.low-memory.test.ts (3 tests) 9ms
Test Files 1 passed (1)
Tests 3 passed (3)
```
#### Manual Testing
N/A (unit-tested with dependency injection; `os.totalmem()` is injected via `deps.totalMemBytes`).
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a new platform note for `openclaw doctor` that warns when the machine has <= 2 GB of total system RAM. The warning is implemented as `noteLowMemoryWarning()` in `src/commands/doctor-platform-notes.ts` (using `os.totalmem()` by default, with dependency injection for tests), invoked early in `doctorCommand` before heavier checks run. It also adds a Vitest unit test suite covering the boundary and above/below-threshold behavior, and records the feature in the changelog.
<h3>Confidence Score: 3/5</h3>
- This PR is close to mergeable but has a robustness concern in the early doctor flow.
- The change is small and well-tested for normal paths, but the new early `os.totalmem()` call is unguarded; if it throws on a platform/host where total memory cannot be queried, it can crash `openclaw doctor` before other checks run.
- src/commands/doctor-platform-notes.ts
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#13045: feat(doctor): add memory search embeddings provider health check
by asklee-klawd · 2026-02-10
79.1%
#22327: fix(doctor): use gateway health status for memory search key check
by therk · 2026-02-21
73.6%
#9438: fix: auto-detect low-memory environments and prevent test OOM
by CompassHXM · 2026-02-05
73.6%
#21631: feat(doctor): detect memory plugins in memory search health check
by tsukhani · 2026-02-20
72.7%
#21240: fix: GH#20607 prevent doctor from dropping custom config sections
by theognis1002 · 2026-02-19
72.6%
#21742: fix(doctor): warn on conflicting exec approval config surfaces
by habakan · 2026-02-20
72.0%
#20125: fix(doctor): skip memorySearch provider check when using QMD backend
by brandonwise · 2026-02-18
71.7%
#17660: fix: skip embedding provider check in doctor when QMD backend is co...
by echoVic · 2026-02-16
71.5%
#10578: feat(doctor): exit with code 1 when critical errors are detected
by 13rac1 · 2026-02-06
71.5%
#21217: fix: memory prune command to prevent unbounded MEMORY.md growth
by theognis1002 · 2026-02-19
69.7%