1. Symptoms
When the clw-sandbox-exhausted error occurs during OpenClaw execution, users encounter several distinct indicators that signal resource depletion within the sandbox environment. The error manifests immediately after initiating a sandboxed operation, typically during code execution, test runs, or build processes that require isolated runtime environments.
The primary symptom presents as an explicit error message displayed in the terminal output:
[ERROR] clw-sandbox-exhausted: Sandbox resource limits have been reached
Sandbox execution terminated. Current usage exceeds allocated quota.
Beyond the primary error message, secondary symptoms often accompany this failure. Users frequently report that the process terminates abruptly without producing expected output files, logs, or artifacts. The exit code returned to the shell is typically non-zero, often 137 which indicates the process was killed by the system due to resource constraints. In containerized environments, the container may enter a restart loop or remain in a terminated state.
Memory exhaustion manifests through additional warning messages such as Cannot allocate memory or Out of memory: Kill process. CPU exhaustion produces messages indicating Maximum execution time exceeded or CPU quota exceeded. Disk space exhaustion results in No space left on device errors preceding or following the sandbox exhaustion notification.
The sandbox health check, when run after the failure, typically shows zero available resources across all monitored dimensions. Network connectivity tests may fail if the sandbox relies on external resources, though this depends on the specific sandbox configuration and resource type that was exhausted.
2. Root Cause
The clw-sandbox-exhausted error emerges from OpenClaw’s resource management system when the allocated sandbox resources are fully consumed during operation. Understanding the underlying architecture requires examining how OpenClaw implements sandbox isolation and resource enforcement.
OpenClaw constructs isolated execution environments using container technology under the hood, applying cgroup (control group) limits to constrain resource consumption. These constraints include memory limits, CPU time quotas, disk I/O throttling, process count limits, and network bandwidth restrictions. When any resource dimension reaches its configured threshold, the sandbox enforcement mechanism terminates the contained operation to prevent system-level impacts.
The root causes typically fall into several distinct categories. Memory exhaustion occurs when the executed code allocates more memory than the sandbox limit permits. This commonly happens with algorithms that consume large data structures, memory leaks in long-running processes, or applications that load extensive datasets into memory without streaming.
CPU exhaustion results from computational workloads that exceed the allocated CPU time quota. Infinite loops, recursive algorithms without proper termination conditions, and CPU-intensive computations on large datasets frequently trigger this limitation. The sandbox enforces time-based CPU accounting, and operations exceeding the threshold are forcibly terminated.
Storage exhaustion happens when temporary files, cached data, or output artifacts exceed the allocated disk quota. This frequently occurs in build processes that generate numerous intermediate files, test suites that produce large coverage reports, or applications that fail to clean up temporary resources properly.
Process limit exhaustion manifests when the workload spawns more threads or child processes than the sandbox permits. Parallel processing frameworks, worker pool implementations, and applications that fork extensively can quickly exhaust process quotas.
Network resource exhaustion, though less common, occurs when sandbox operations require network access that exceeds allocated bandwidth or connection limits. API calls, database connections, or external service requests that aggregate beyond thresholds trigger this exhaustion mode.
3. Step-by-Step Fix
Resolving the clw-sandbox-exhausted error requires identifying the specific resource dimension that was exhausted and adjusting sandbox configuration accordingly. The following step-by-step approach addresses each potential cause systematically.
Step 1: Identify the Exhausted Resource Type
Examine the full error output and any preceding warning messages to determine which resource dimension triggered the exhaustion. Run the sandbox with verbose logging enabled:
openclaw run --verbose your-script.sh
Review the resource usage summary printed before the failure to pinpoint the exact limitation that was exceeded.
Before:
openclaw run ./build-process.sh
After:
openclaw run --verbose --resource-report ./build-process.sh
Step 2: Increase Memory Allocation
If memory exhaustion is identified, modify the sandbox configuration to allocate additional memory:
Before:
{
"sandbox": {
"memory_limit": "256MB"
}
}
After:
{
"sandbox": {
"memory_limit": "1GB"
}
}
Alternatively, pass the memory limit via command line:
openclaw run --memory-limit 1G ./build-process.sh
Step 3: Extend CPU Time Quota
For CPU exhaustion issues, increase the maximum execution time and CPU allocation:
Before:
openclaw run --cpu-limit 0.5 --timeout 60s ./computation-heavy-task.sh
After:
openclaw run --cpu-limit 2 --timeout 300s ./computation-heavy-task.sh
Step 4: Expand Disk Quota
When storage limits are reached, configure increased disk allocation:
Before:
{
"sandbox": {
"disk_limit": "500MB"
}
}
After:
{
"sandbox": {
"disk_limit": "2GB"
}
}
Clean up existing temporary files before retrying:
rm -rf ~/.openclaw/tmp/*
openclaw run --disk-limit 2G ./build-process.sh
Step 5: Increase Process Limits
For process limit exhaustion, adjust the maximum process count:
Before:
openclaw run --max-processes 50 ./parallel-workers.sh
After:
openclaw run --max-processes 200 ./parallel-workers.sh
Step 6: Optimize Code to Reduce Resource Consumption
When increasing limits is not feasible, optimize the workload:
# Use streaming instead of loading all data in memory
openclaw run ./memory-efficient-script.sh
# Enable output buffering to reduce disk usage
openclaw run --buffered-output ./file-processing.sh
# Use process pooling to reduce process count
openclaw run --worker-count 4 ./task-execution.sh
Step 7: Configure Global Defaults
For repeated issues, configure global sandbox defaults:
# Edit the openclaw configuration file
nano ~/.openclaw/config.yaml
Before:
sandbox:
memory_limit: 256MB
cpu_limit: 0.5
disk_limit: 500MB
max_processes: 50
timeout: 60s
After:
sandbox:
memory_limit: 1GB
cpu_limit: 2
disk_limit: 2GB
max_processes: 200
timeout: 600s
4. Verification
Confirming the successful resolution of the clw-sandbox-exhausted error requires systematic validation across multiple dimensions. The verification process must demonstrate that the sandbox executes the workload completely without resource exhaustion.
Primary Verification Method
Execute the previously failing command and verify successful completion:
openclaw run --verbose ./build-process.sh
A successful execution produces exit code zero with output similar to:
[INFO] Sandbox initialized with 1GB memory, 2 CPU cores
[INFO] Starting execution of ./build-process.sh
[INFO] Execution completed successfully
[INFO] Resource usage: Memory 512MB, CPU 1.2 cores, Disk 800MB
[SUCCESS] Exit code: 0
Resource Usage Monitoring
Enable detailed resource monitoring during execution to confirm consumption stays within limits:
openclaw run --resource-monitor ./build-process.sh
Verify that peak usage for each resource dimension remains below the configured limits. The output should show continuous monitoring data without any “limit reached” warnings.
Stress Testing Verification
For production workloads, run extended stress tests to ensure stability:
openclaw run --repeat 10 ./production-workload.sh
All iterations should complete successfully, demonstrating that resource allocation is sufficient for repeated operations.
Post-Execution Health Check
Run the sandbox health check to confirm resource availability:
openclaw health-check
Expected output confirms available resources:
Sandbox Health Status: OK
Memory Available: 512MB of 1GB
CPU Available: 0.8 cores
Disk Available: 1.2GB of 2GB
Processes Available: 150 of 200
5. Common Pitfalls
When resolving the clw-sandbox-exhausted error, practitioners frequently encounter several mistakes that can delay resolution or cause the error to reoccur.
Insufficient Limit Increases
A common error is increasing resource limits by marginal amounts that remain insufficient for the workload. When memory exhaustion occurs, doubling the allocation from 256MB to 512MB may still fall short for memory-intensive operations. Evaluate the actual memory consumption and increase limits substantially—for example, from 256MB to 1GB or 2GB—to provide adequate headroom.
Configuration File Syntax Errors
YAML configuration files are sensitive to syntax errors. Incorrect indentation, missing colons, or improper key names silently fail to apply settings, leaving the default restrictive limits in effect. Always validate configuration syntax using a YAML linter or the openclaw config --validate command before execution.
Environment Variable Override Conflicts
Environment variables sometimes override configuration file settings in unexpected ways. Check for variables like OPENCLAW_MEMORY_LIMIT that may be set in shell profiles or CI/CD pipelines, causing them to conflict with intended configuration values. Unset these variables or ensure consistency across all configuration sources.
Resource Leaks Between Executions
Temporary files and cached data can accumulate across multiple executions, gradually consuming the disk quota. Failing to clean the sandbox cache before retrying causes disk exhaustion even with increased limits. Implement cleanup steps in repeated operations:
openclaw clean --cache
openclaw run ./build-process.sh
Testing with Small Workloads Only
Verifying the fix with minimal test cases provides false confidence. The error may still occur with production-scale workloads that stress resource boundaries differently. Always validate fixes with representative workloads that mirror actual usage patterns.
Ignoring Exit Code 137
Exit code 137 specifically indicates the process was killed by SIGKILL, typically due to memory pressure from the operating system or container runtime, not just OpenClaw’s sandbox limits. This exit code suggests the resource exhaustion may originate from system-level constraints beyond OpenClaw configuration. Investigate host machine resource availability in addition to sandbox settings.
6. Related Errors
The clw-sandbox-exhausted error shares characteristics with several related OpenClaw errors that involve resource constraints or sandbox termination conditions.
clw-timeout-exceeded
This error occurs when operation execution exceeds the configured time limit before resource exhaustion. While clw-sandbox-exhausted focuses on resource consumption, clw-timeout-exceeded addresses temporal constraints. Both errors result in sandbox termination, but clw-timeout-exceeded can occur even when resource consumption remains within limits. The fix involves extending timeout durations via --timeout flag or configuration file settings.
clw-container-killed
When the underlying container runtime forcibly terminates the sandbox environment, this error surfaces. Unlike clw-sandbox-exhausted which originates from OpenClaw’s resource tracking, clw-container-killed indicates external container runtime intervention, often triggered by system-level OOM (Out of Memory) conditions. Investigating host machine memory availability and kernel-level cgroup settings resolves this error.
clw-process-limit-reached
This error specifically addresses process count exhaustion within the sandbox. When workloads spawn processes exceeding the configured limit, execution terminates with this error. The relationship to clw-sandbox-exhausted is direct: process limits represent one dimension of the broader resource management system. Fixing clw-process-limit-reached requires adjusting --max-processes configuration, while clw-sandbox-exhausted may involve any resource dimension.
related_errors:
- id: "clw-timeout-exceeded"
title: "OpenClaw Execution Timeout"
relationship: "Sister error - temporal constraint failure"
- id: "clw-container-killed"
title: "Container Runtime Termination"
relationship: "Parent error - external system intervention"
- id: "clw-process-limit-reached"
title: "Process Count Exhaustion"
relationship: "Subset error - specific resource dimension"