Programs relying on GPU acceleration, such as compute shaders, machine learning inference, or scientific simulations built with OpenClaw, will either crash, log the error and degrade to CPU mode, or exit with a non-zero code. On Linux systems, you might see this in `dmesg` or application logs alongside OpenCL ICD loader warnings. Windows Event Viewer may log ICD-related failures under "Application" events. Performance drops are noticeable: GPU-bound kernels run 10-100x slower on CPU fallback.

In verbose mode (e.g., `CLW_LOG_LEVEL=debug`), additional diagnostics appear:

This error blocks parallel compute workloads, causing timeouts in HPC pipelines or reduced FPS in graphics/rendering apps using OpenClaw.

## 2. Root Cause

OpenClaw is a thin C/C++ wrapper around OpenCL 1.2/2.x APIs, providing functions like `clwGetPlatforms()`, `clwGetGpuDevices()`, and `clwCreateContext()`. The `clw-gpu-not-found` error (internal code often -1001 or CLW_DEVICE_NOT_FOUND) triggers when:

1. **No OpenCL-compatible GPU hardware**: Integrated GPUs (e.g., Intel UHD) may lack full OpenCL support, or discrete GPUs (NVIDIA/AMD) are absent/disabled in BIOS.

2. **Missing or incompatible drivers**:
   - NVIDIA: CUDA Toolkit without OpenCL ICD.
   - AMD: ROCm or legacy APP SDK not exposing OpenCL.
   - Intel: oneAPI Base Toolkit absent.
   - Vendor-agnostic: POCL (CPU-only) installed but no GPU ICD.

3. **ICD Loader misconfiguration**: OpenCL Installable Client Driver (ICD) registry (`/etc/OpenCL/vendors/` on Linux, `HKLM\SOFTWARE\Khronos\OpenCL\Vendors` on Windows) lacks `.icd` files pointing to GPU drivers.

4. **Platform/device filtering**: Code calls `clwGetGpuDevices()` without fallback, ignoring CPU or accelerator devices.

5. **Runtime environment**: Docker containers without `--gpus all`, WSL2 without GPU passthrough, or virtual machines without GPU acceleration.

6. **Hardware state**: GPU powered off, PCIe slot disabled, or overheating/throttled.

Use `clinfo` to diagnose:

Zero GPU entries confirm the issue. Kernel logs (`journalctl -u opencl` or `nvidia-smi`) reveal driver absences.

## 3. Step-by-Step Fix

Fix `clw-gpu-not-found` by verifying hardware/drivers, then updating code for robust device selection.

### Step 1: Verify GPU Hardware
Run `lspci | grep VGA` (Linux), `dxdiag` (Windows), or `system_profiler SPDisplaysDataType` (macOS).

If no GPU, enable in BIOS or add hardware.

### Step 2: Install OpenCL Drivers
- **NVIDIA (Linux/Windows)**:

Reboot, verify: `nvidia-smi`.

- **AMD (Linux)**:

- **Intel**:

- **Windows**: Download CUDA Toolkit (includes OpenCL), AMD Software, or Intel oneAPI.

### Step 3: Install clinfo and Validate

Expected:

Update ICD if needed:

### Step 4: Update OpenClaw Code
Modify device selection to enumerate all devices and prefer GPU.

**Before:**
```cpp
#include <openclaw/clw.h>

int main() {
    clw_int status;
    clw_device gpu;

    status = clwGetGpuDevice(0, &gpu);  // Assumes GPU at index 0
    if (status != CLW_SUCCESS) {
        fprintf(stderr, "clw-gpu-not-found\n");
        return -1;
    }

    clw_context ctx;
    clwCreateContext(&ctx, 1, &gpu);
    // ...
}

#include <openclaw/clw.h>
#include <vector>
#include <iostream>

int main() {
    clw_int status;
    clw_uint num_platforms, num_devices;
    std::vector<clw_device> devices;

    // Enumerate platforms
    status = clwGetPlatformCount(&num_platforms);
    if (status != CLW_SUCCESS) return -1;

    clw_platform* platforms = new clw_platform[num_platforms];
    clwGetPlatforms(platforms, num_platforms);

    // Collect all GPU devices, fallback to CPU
    for (clw_uint i = 0; i < num_platforms; ++i) {
        clwGetDeviceCount(platforms[i], CLW_DEVICE_TYPE_GPU, &num_devices);
        clw_device* gpus = new clw_device[num_devices];
        clwGetDevices(platforms[i], CLW_DEVICE_TYPE_GPU, gpus, num_devices);

        for (clw_uint j = 0; j < num_devices; ++j) {
            devices.push_back(gpus[j]);
        }
        delete[] gpus;

        // CPU fallback if no GPU
        if (devices.empty()) {
            clwGetDeviceCount(platforms[i], CLW_DEVICE_TYPE_CPU, &num_devices);
            clw_device* cpus = new clw_device[num_devices];
            clwGetDevices(platforms[i], CLW_DEVICE_TYPE_CPU, cpus, num_devices);
            if (num_devices > 0) devices.push_back(cpus[0]);
            delete[] cpus;
        }
    }
    delete[] platforms;

    if (devices.empty()) {
        std::cerr << "clw-gpu-not-found: No devices available" << std::endl;
        return -1;
    }

    clw_device selected = devices[0];  // Prefer first GPU or CPU
    clw_context ctx;
    clwCreateContext(&ctx, 1, &selected);

    std::cout << "Using device: GPU fallback handled" << std::endl;
    // Proceed with kernels...
    clwReleaseContext(ctx);
    return 0;
}

Platform Profile: FULL_PROFILE
Platform Version: OpenCL 3.0 CUDA 12.2.140
Name: NVIDIA GeForce RTX 3070

// Minimal test snippet
clwGetGpuDeviceCount(&count);
printf("GPU count: %u\n", count);  // Should be >0

# Pitfall: Only POCL installed
ls /etc/OpenCL/vendors/  # Should have nvidia.icd, not just pocl.icd