Your Openclaw gateway is pinned at 80% CPU and you have not changed anything. Before you throw more cores at it or restart the container for the fifth time today, you need to identify which of the four common causes is responsible. Each one has a different fix, and applying the wrong one wastes time without moving the needle.
The pattern is consistent across deployments ranging from 2-core ARM boxes to 8-core production servers: most sustained CPU problems trace back to one of four root causes, and each takes under ten minutes to resolve once you know what you are looking at.
How to Diagnose Openclaw CPU Usage
Start by measuring before you fix anything. The diagnostic tool you use depends on your deployment method.
Docker Deployments
Run docker stats --no-stream to get a single snapshot of CPU and memory across all containers:
docker stats --no-stream
Look at the CPU % column for the Openclaw container. Occasional spikes to 80-100% are normal during task execution. Sustained usage above 70% when idle is the problem signal.
For continuous monitoring, drop the --no-stream flag:
docker stats
Bare Metal or VPS Deployments
Use htop for an interactive view that shows per-core CPU usage and process trees:
htop -p $(pgrep -f openclaw | tr '\n' ',')
This filters htop to only Openclaw-related processes. Watch for the gateway process specifically. If you see the Node.js process consuming sustained CPU while idle, you have confirmed the issue.
For a quick non-interactive check, top works:
top -b -n 1 | grep -i openclaw
The openclaw doctor Command
Before diving deeper, run the built-in health check:
openclaw doctor
This validates your configuration, checks connectivity, and flags known issues. If your config file contains an invalid agents.defaults.model schema, the gateway will spin at 100% CPU without producing a useful error message. The doctor command catches this.
Four Common Causes of High CPU
Once you have confirmed sustained high CPU, the cause falls into one of these categories, listed in order of frequency based on community reports.
Cause 1: Eager Channel SDK Loading
This is the most common cause on fresh installations. The Openclaw plugin runtime loads every channel SDK at startup, regardless of which channels you have enabled. Discord, Slack, Telegram, Signal, WhatsApp, iMessage, and Line SDKs all initialize even if you only use one.
The impact is measurable: the bundled chunk is roughly 3 MB containing over 1,000 import statements. On startup, this triggers more than 22,000 file system operations and nearly 14,000 syscalls in the first five seconds. On shared-CPU VPS instances, this alone pins the CPU at 75-85% for the entire startup phase, and on slower hardware it never fully recovers.
The fix: Disable channels you are not using in your configuration:
# openclaw.config.yaml
channels:
discord:
enabled: false
signal:
enabled: false
line:
enabled: false
imessage:
enabled: false
Only enable the channels you actively use. After changing this, restart the gateway. CPU during startup should drop significantly.
Cause 2: Runaway Context Windows
Every conversation round adds tokens to the context window. Without explicit limits, a 10-round conversation can grow from 5,000 tokens to over 150,000 tokens. Each subsequent API call processes the entire context, and the gateway spends CPU serializing, parsing, and managing that payload.
This is the cause when CPU is fine after a restart but degrades steadily over hours of active use. It is also the most expensive cause from an API billing perspective.
The fix: Set explicit context limits in your configuration:
# openclaw.config.yaml
agents:
defaults:
maxContextTokens: 32000
contextStrategy: "sliding-window"
The sliding-window strategy drops the oldest messages when the limit is reached, preserving the system prompt and recent exchanges. For most workflows, 32,000 tokens provides enough context without the CPU overhead of managing 150K+ token payloads.
If you need to preserve important context from earlier in a session, use the openclaw sessions summarize command to compress history before it hits the limit.
Cause 3: Tight Heartbeat Intervals
The heartbeat mechanism keeps Openclaw responsive to scheduled tasks and external triggers. The default interval is reasonable for most setups, but teams that reduce it below 30 seconds for faster trigger responsiveness pay for it with constant CPU wake-ups.
Each heartbeat cycle involves checking all active agents, evaluating trigger conditions, and pinging connected channels. At a 10-second interval with five agents and three channels, the gateway never gets a chance to idle.
The fix: Set the heartbeat interval to 60 seconds or higher unless you have a documented need for faster triggers:
# openclaw.config.yaml
heartbeat:
interval: 60000 # milliseconds
For workflows that genuinely need sub-minute responsiveness, consider using webhooks instead of polling-based heartbeats. Webhooks consume zero CPU between events.
Cause 4: Memory Leaks in Long Sessions
After approximately 13 hours of continuous operation, the Openclaw gateway process has been observed reaching 69.9% CPU with 1.9 GB of resident memory. This is a known issue tracked in the project’s GitHub repository. The gateway accumulates state from processed messages, WebSocket connections, and plugin lifecycle events that are not fully garbage collected.
The fix: For production deployments, schedule periodic restarts. In Docker, this is straightforward with a restart policy combined with a health check:
# docker-compose.yml (relevant section)
services:
openclaw:
restart: unless-stopped
healthcheck:
test: ["CMD", "openclaw", "gateway", "probe"]
interval: 120s
timeout: 10s
retries: 3
start_period: 60s
You can also prune stale sessions to reclaim memory without a full restart:
openclaw sessions prune --older-than 24h
For long-running production instances, setting a cron job that prunes sessions and restarts the gateway during a low-traffic window is a practical workaround. Blunt, but effective until the upstream memory management improves.
Docker Resource Limits for Openclaw
If you run Openclaw in Docker, resource limits prevent a misbehaving process from starving the host. This is particularly important on shared VPS instances where Openclaw competes with other services for CPU time.
Add these constraints to your docker-compose.yml:
services:
openclaw:
image: openclaw/openclaw:latest
deploy:
resources:
limits:
cpus: "2.0"
memory: 4G
reservations:
cpus: "0.5"
memory: 1G
environment:
- NODE_OPTIONS=--max-old-space-size=3072
restart: unless-stopped
The limits cap what the container can consume. The reservations guarantee a minimum allocation so the container is not starved by neighbors. Setting NODE_OPTIONS to 3072 MB gives Node.js room to operate within the 4 GB container memory limit while leaving headroom for the OS and other processes.
For sizing guidance:
- Personal use, 1-2 agents: 1 CPU, 2 GB memory
- Team use, 3-5 agents: 2 CPUs, 4 GB memory
- Production, 5+ agents with channels: 4 CPUs, 8 GB memory
If you have not yet set up Docker for Openclaw, our Docker deployment guide covers the full configuration from scratch.
When to Investigate Further
Not every CPU spike is a problem. During active task execution, agent reasoning, or tool use, high CPU is expected and temporary. The situations that warrant investigation:
- CPU stays above 70% when no tasks are running
- The gateway process grows in CPU usage over time without increased load
- Response latency increases steadily across a session
- The
openclaw doctorcommand reports warnings or failures
If you have applied all four fixes above and CPU remains high, check your logging configuration. Debug-level logging with verbose output generates significant I/O overhead. Set the log level to info for production:
logging:
level: info
For deeper performance work beyond CPU troubleshooting, our Openclaw performance optimization guide covers token cost reduction, model selection strategies, and cache tuning.
Frequently Asked Questions
Why is Openclaw using 100% CPU when idle?
The most likely cause is eager channel SDK loading at startup. The plugin runtime initializes all channel SDKs regardless of which ones you use, triggering over 22,000 file system operations. Disable unused channels in your config and restart. If CPU remains high after startup, run openclaw config validate to check for invalid configuration that causes the gateway to spin.
How much RAM does Openclaw need to run without CPU issues?
For personal use with one or two agents, 2 GB is the minimum. Team deployments with multiple agents and channels should target 4 GB. Production environments handling concurrent sessions need 8 GB or more. Insufficient memory forces aggressive garbage collection that manifests as CPU spikes, so memory and CPU issues are often related.
Will setting Docker CPU limits make Openclaw slower?
Limiting CPU prevents Openclaw from consuming the entire host, but it does not slow down normal operations. A 2-CPU limit handles most workloads without noticeable latency. The only operation that benefits from burst CPU above 2 cores is the initial startup when SDKs are loading, and that completes in under 30 seconds on most hardware.
Does the heartbeat interval really affect CPU?
Yes. At a 10-second interval with multiple agents and channels, the gateway evaluates trigger conditions, pings channels, and processes agent states dozens of times per minute. Each cycle is small, but the cumulative effect prevents the process from idling. Setting the interval to 60 seconds reduces these wake-ups by 83% with no impact on most workflows.
How do I stop memory leaks from causing high CPU over time?
Schedule periodic session pruning with openclaw sessions prune --older-than 24h and consider restarting the gateway during low-traffic windows. The underlying issue is that WebSocket connections and plugin lifecycle events accumulate state that is not fully garbage collected. This is a known upstream issue, and the workaround is lifecycle management rather than a configuration change.
Can I run Openclaw on a 2 GB VPS?
You can, but expect CPU pressure. With 2 GB total system memory, Node.js garbage collection runs aggressively, which consumes CPU cycles. Disable all unused channels and skills, set NODE_OPTIONS=--max-old-space-size=1536, limit yourself to one agent, and avoid long-running sessions. A 4 GB instance removes most of these constraints.
How do I tell if high CPU is from Openclaw or the LLM provider?
Run docker stats --no-stream or htop while Openclaw is idle (no active tasks). If CPU is high when idle, the problem is Openclaw itself. If CPU only spikes during active conversations, the overhead is from serializing API payloads and processing responses, which is normal. Provider-side latency shows up as slow responses rather than high local CPU.
Key Takeaways
- Diagnose first with
docker stats,htop, oropenclaw doctorbefore applying fixes - Disable unused channel SDKs to eliminate the most common cause of sustained high CPU at startup
- Set explicit context window limits to prevent token accumulation from degrading CPU over time
- Keep heartbeat intervals at 60 seconds or longer unless you need sub-minute trigger responsiveness
- Apply Docker resource limits (
cpus,memory,NODE_OPTIONS) to prevent host starvation - Schedule periodic session pruning and gateway restarts for long-running production instances
SFAI Labs
