Fix clw-sandbox-not-found: OpenClaw Sandbox Environment Not Found

1. Symptoms

The clw-sandbox-not-found error surfaces when running OpenClaw CLI commands that depend on an active sandbox session. You will typically see the error immediately after invoking any clw command that requires a sandbox context, such as clw run, clw shell, or clw status.

Common symptoms include:

• Terminal output: The error message is printed to stderr and the command exits with a non-zero status code.
• Abrupt command termination: No further processing occurs after the error is thrown.
• Context-dependent failures: Commands like clw exec or clw attach fail because they cannot establish a sandbox connection.
• Stale shell sessions: If you previously had a sandbox open, attempting to interact with it may produce this error after the underlying sandbox was destroyed or expired.
• Missing sandbox file: The OpenClaw client writes a .clw-sandbox metadata file in the project directory. If this file is missing, corrupted, or points to a non-existent sandbox ID, the CLI raises this error.

Example error output:

$ clw shell my-project
[OpenClaw] Connecting to sandbox...
Error: clw-sandbox-not-found: Sandbox environment 'sb-7f3a92c1' could not be located.
The sandbox may have been deleted, expired, or the identifier is incorrect.
Run 'clw sandbox list' to view available sandbox environments.

$ clw run ./test-suite.js
[OpenClaw] Initializing sandbox session...
Error: clw-sandbox-not-found: No sandbox environment found in the current working directory.
Please initialize a sandbox with 'clw sandbox init' or specify one with '--sandbox-id'.

These two variants share the same error code but differ in the underlying cause, which is addressed in the Root Cause section.

2. Root Cause

The clw-sandbox-not-found error has three primary root causes:

1. Stale or corrupted .clw-sandbox metadata file

OpenClaw stores sandbox session metadata in a file named .clw-sandbox located at the root of your project directory. This file contains the sandbox ID, endpoint, and authentication token. If this file is accidentally deleted, manually edited, or corrupted by a concurrent process, the CLI cannot resolve the sandbox identity.

2. Sandbox expiration or manual deletion

Sandbox environments have a defined lifetime (configurable at creation time). When a sandbox expires or is explicitly destroyed via clw sandbox destroy, the server-side record is removed. Any local references to that sandbox (stored in .clw-sandbox) become orphaned. Subsequent commands that rely on the sandbox will fail with this error.

3. Incorrect working directory or sandbox ID

Running clw commands from a directory that does not contain a .clw-sandbox file, or passing an invalid --sandbox-id argument, causes the CLI to fail sandbox resolution. This is common when switching between multiple project directories or when the sandbox was created in a different working tree.

4. Configuration pointing to a non-existent environment endpoint

In multi-environment setups (staging vs. production), the OpenClaw configuration file (~/.clw/config.yaml) may specify an API endpoint that does not host the sandbox you are targeting. The CLI connects to the wrong environment and receives a 404 when attempting to resolve the sandbox.

Understanding which of these causes applies to your situation is critical for selecting the correct fix.

3. Step-by-Step Fix

Fix 1: Reinitialize the sandbox from the project directory

If the .clw-sandbox file is missing or corrupted, the simplest fix is to initialize a new sandbox session.

Before:

$ clw shell
Error: clw-sandbox-not-found: No sandbox environment found in the current working directory.

After:

$ clw sandbox init
[OpenClaw] Initializing new sandbox environment...
[OpenClaw] Sandbox created: sb-9a2d4f77
[OpenClaw] Environment file written: .clw-sandbox
[OpenClaw] Ready. Run 'clw shell' to connect.
$ clw shell
[OpenClaw] Connecting to sandbox sb-9a2d4f77...
[OpenClaw] Connected.
(sb-9a2d4f77) $

Fix 2: List available sandboxes and reconnect

If the sandbox still exists on the server but the local metadata is stale, list the available sandboxes and explicitly reconnect.

# Step 1: List all sandboxes associated with your account
$ clw sandbox list
AVAILABLE SANDBOXES
─────────────────────────────────────────────────────────────────
 ID           │ STATUS   │ CREATED          │ EXPIRES          │ PROJECT
─────────────────────────────────────────────────────────────────
 sb-9a2d4f77  │ running  │ 2025-01-10 14:00 │ 2025-01-17 14:00 │ my-project
 sb-3c1e89b5  │ stopped  │ 2025-01-08 09:30 │ 2025-01-15 09:30 │ legacy-app
─────────────────────────────────────────────────────────────────

# Step 2: Connect to a specific sandbox by ID
$ clw sandbox connect sb-9a2d4f77
[OpenClaw] Restoring connection to sandbox sb-9a2d4f77...
[OpenClaw] Connection established.
(sb-9a2d4f77) $

Fix 3: Remove stale metadata and reinitialize

When the .clw-sandbox file points to a deleted or expired sandbox, remove it and start fresh.

# Step 1: Inspect the stale file
$ cat .clw-sandbox
sandbox_id: sb-7f3a92c1
endpoint: https://api.openclaw.io/v2
token: eyJhbGc...
created_at: "2025-01-05T10:00:00Z"
expires_at: "2025-01-12T10:00:00Z"

# Step 2: Remove the stale file
$ rm .clw-sandbox

# Step 3: Initialize a new sandbox
$ clw sandbox init --project my-project
[OpenClaw] Creating sandbox for project 'my-project'...
[OpenClaw] Sandbox created: sb-0e5b23cd
[OpenClaw] Metadata written to .clw-sandbox

Fix 4: Verify the configuration endpoint (multi-environment setups)

If you are working with multiple OpenClaw environments, ensure your local configuration points to the correct API endpoint.

Before:

# ~/.clw/config.yaml (incorrect endpoint)
default_environment: staging
environments:
  staging:
    api_url: https://staging-api.openclaw.io/v2
    sandbox_region: us-west-2
  production:
    api_url: https://api.openclaw.io/v2
    sandbox_region: us-east-1
active_sandbox: sb-7f3a92c1  # This sandbox was created in production

After:

# ~/.clw/config.yaml (corrected configuration)
default_environment: production
environments:
  staging:
    api_url: https://staging-api.openclaw.io/v2
    sandbox_region: us-west-2
  production:
    api_url: https://api.openclaw.io/v2
    sandbox_region: us-east-1
active_sandbox: null

# Verify the active environment
$ clw config get environments.default
production

# Run the command again with the correct environment
$ clw sandbox init --env production
[OpenClaw] Connected to production environment.
[OpenClaw] Sandbox created: sb-f1a87bc3

Fix 5: Specify sandbox ID explicitly as a command argument

When the working directory contains the wrong metadata but you know the correct sandbox ID, bypass the local file with an explicit argument.

# Instead of relying on .clw-sandbox, pass the ID directly
$ clw run --sandbox-id sb-9a2d4f77 ./scripts/deploy.sh
[OpenClaw] Using explicit sandbox ID: sb-9a2d4f77
[OpenClaw] Executing deploy script...
[OpenClaw] Done. Exit code: 0.

4. Verification

After applying any of the fixes above, verify that the sandbox is accessible by running the following commands in sequence:

# Step 1: Confirm the .clw-sandbox file exists and is valid JSON
$ cat .clw-sandbox | python3 -m json.tool > /dev/null && echo "Valid JSON"
Valid JSON

# Step 2: Check sandbox status
$ clw sandbox status
[OpenClaw] Sandbox ID: sb-9a2d4f77
[OpenClaw] Status: running
[OpenClaw] Region: us-east-1
[OpenClaw] Expires: 2025-01-17T14:00:00Z
[OpenClaw] Connection: healthy

# Step 3: Run a simple command that requires the sandbox
$ clw exec --sandbox-id sb-9a2d4f77 -- echo "Sandbox is accessible"
Sandbox is accessible

# Step 4: Verify the active environment matches your target
$ clw config get environments.default
production

If all four verification steps pass, the clw-sandbox-not-found error has been resolved and the sandbox environment is accessible.

5. Common Pitfalls

Pitfall 1: Forgetting to remove stale metadata before reinitializing

Simply running clw sandbox init while a stale .clw-sandbox file exists may fail or create a conflicting entry. Always remove or rename the existing file before reinitializing:

$ mv .clw-sandbox .clw-sandbox.backup
$ clw sandbox init

Pitfall 2: Confusing sandbox expiration with deletion

Sandboxes that are expired may still appear in clw sandbox list with a status of expired rather than being absent entirely. Attempting to connect to an expired sandbox produces the same error. Always check the EXPIRES column and create a replacement if the sandbox has passed its lifetime.

Pitfall 3: Running clw from a subdirectory

The .clw-sandbox file must be in the directory where you invoke clw. If you change directories into a subfolder (e.g., src/) and run clw shell, the CLI traverses upward looking for .clw-sandbox, but if it was placed in the project root and you are deeper in the tree, it may not find it. Use --project-root to specify the correct path:

$ clw shell --project-root /path/to/my-project

Pitfall 4: Hardcoding sandbox IDs in CI/CD pipelines

Scripts and CI/CD configurations that hardcode a specific sandbox ID will fail once that sandbox expires or is replaced. Instead, retrieve the sandbox ID dynamically:

# Instead of hardcoding sb-9a2d4f77 in a CI script:
SANDBOX_ID=$(clw sandbox list --format json | jq -r '.[] | select(.project=="my-project" and .status=="running") | .id')
clw run --sandbox-id "$SANDBOX_ID" ./deploy.sh

Pitfall 5: Mixing environment configurations

In multi-environment setups, always verify which environment is active before running commands. A sandbox created in the staging environment cannot be accessed from the production endpoint and vice versa. Set the environment explicitly in your shell session:

$ eval "$(clw env activate production)"
[OpenClaw] Active environment: production

6. Related Errors

The clw-sandbox-not-found error is most commonly preceded by clw-env-parse-error when the .clw-sandbox file is corrupted, and most commonly followed by clw-auth-expired if the underlying issue is token invalidation rather than sandbox deletion.