Fix clw-auth-not-found: Authentication Configuration File Not Found

By Alex Chen
OpenClaw intermediate Linux macOS Windows

1. Symptoms

When OpenClaw encounters the clw-auth-not-found error, you will observe the following symptoms in your development environment:

Primary Error Message:

Error: clw-auth-not-found
OpenClaw could not find the authentication configuration file at /path/to/auth.json

Additional Symptoms:

  • The CLI fails to authenticate with the OpenClaw API even though valid credentials were previously used
  • Commands like openclaw deploy, openclaw pull, and openclaw sync fail immediately upon execution
  • The error may appear after system updates, Docker container recreation, or moving to a new development machine
  • Environment variables related to authentication are set, but the CLI ignores them
  • Running openclaw auth status shows “No authentication file found”

Typical Terminal Output:

$ openclaw deploy --project my-app
[OpenClaw v2.3.1] Initializing deployment...
Connecting to api.openclaw.io...
Error: clw-auth-not-found
  → Authentication configuration file not found at ~/.openclaw/auth.json
  → Please run 'openclaw auth login' to create a new authentication file.
  → Alternatively, set OPENCLAW_AUTH_PATH environment variable to specify a custom location.

$ echo $?
1

This error is particularly common in CI/CD pipelines where the authentication file is not properly mounted or restored before running OpenClaw commands.

2. Root Cause

The clw-auth-not-found error stems from OpenClaw’s inability to locate the authentication configuration file. Understanding the root cause is essential for implementing the correct fix.

Primary Root Cause:

OpenClaw stores authentication credentials in a JSON file (typically auth.json) located in the OpenClaw configuration directory. When this file is missing, moved, or inaccessible, OpenClaw cannot authenticate API requests and throws the clw-auth-not-found error.

Secondary Root Causes:

  1. First-Time Installation: New installations have no authentication file because openclaw auth login has never been executed.

  2. File Deletion: The authentication file was manually deleted or removed by a cleanup script.

  3. Path Changes: The ~/.openclaw directory was deleted, renamed, or moved to a different location.

  4. Environment Variable Mismatch: The OPENCLAW_AUTH_PATH environment variable points to a non-existent location.

  5. Docker/Container Issues: In containerized environments, the volume containing the authentication file was not mounted correctly, or the container was rebuilt without preserving state.

  6. Permission Issues: The authentication file exists but cannot be read due to insufficient file permissions.

  7. Corrupted State: A partial authentication setup exists but lacks the required auth.json file.

OpenClaw searches for the authentication file in this order:

  1. Path specified by OPENCLAW_AUTH_PATH environment variable
  2. Default location: ~/.openclaw/auth.json on Linux/macOS or %USERPROFILE%\.openclaw\auth.json on Windows
  3. Current working directory: ./.openclaw/auth.json

If none of these locations contain a valid authentication file, the clw-auth-not-found error is thrown.

3. Step-by-Step Fix

Follow these steps to resolve the clw-auth-not-found error:

Step 1: Verify the OpenClaw Configuration Directory

First, check if the OpenClaw configuration directory exists and whether it contains an authentication file:

# Check if the OpenClaw config directory exists
ls -la ~/.openclaw/

# If using a custom path, check that environment variable
echo $OPENCLAW_AUTH_PATH

If the directory doesn’t exist, create it:

# Create the OpenClaw configuration directory
mkdir -p ~/.openclaw

# Set appropriate permissions (owner read/write only)
chmod 700 ~/.openclaw

Step 2: Run the Authentication Login

If you haven’t authenticated before, or if the previous authentication file is missing, run the login command:

# Start the authentication process
openclaw auth login

This will prompt you to enter your credentials or redirect you to a browser-based authentication flow:

$ openclaw auth login
[OpenClaw v2.3.1] Starting authentication flow...
Please open your browser and navigate to:
https://auth.openclaw.io/login?cli=true&device=abc123xyz

Or press Enter to open the URL automatically.

Waiting for authentication...
✓ Authentication successful!
✓ Credentials saved to ~/.openclaw/auth.json

Step 3: Restore an Existing Authentication File (If Available)

If you have a backup of your authentication file or are migrating from another machine:

Before:

// Missing file - ~/.openclaw/auth.json does not exist

After:

// Restored file - ~/.openclaw/auth.json
{
  "accessToken": "oc_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "refreshToken": "oc_refresh_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "userId": "user_12345",
  "orgId": "org_67890",
  "orgSlug": "my-organization"
}

Copy the authentication file to the correct location:

# Copy from backup location
cp /path/to/backup/auth.json ~/.openclaw/auth.json

# Set correct permissions
chmod 600 ~/.openclaw/auth.json

Step 4: Configure Environment Variable (For Custom Locations)

If you need to store the authentication file in a non-default location, set the environment variable:

Before:

# No environment variable set
$ echo $OPENCLAW_AUTH_PATH

# (empty output)

After:

# Add to shell profile (.bashrc, .zshrc, etc.)
export OPENCLAW_AUTH_PATH="/custom/path/to/auth.json"

# Or set inline for a single command
OPENCLAW_AUTH_PATH="/custom/path/to/auth.json" openclaw deploy

Step 5: Verify Authentication Status

After completing the fix steps, verify that OpenClaw can authenticate successfully:

# Check authentication status
openclaw auth status

Expected output:

$ openclaw auth status
[OpenClaw v2.3.1] Checking authentication...

✓ Authenticated as: [email protected]
✓ Organization: my-organization
✓ Token expires: 2024-06-15T12:00:00Z
✓ Token valid for: 89 days

4. Verification

After applying the fix, verify that the clw-auth-not-found error is resolved by running the following commands:

Test Basic Authentication

openclaw auth status

You should see the authenticated user information without any errors.

Test API Connection

openclaw org list

This command makes an authenticated API request. If authentication is working correctly, you should see a list of your organizations:

$ openclaw org list
[OpenClaw v2.3.1] Fetching organizations...

✓ Connected to api.openclaw.io
✓ Received 2 organizations:
  1. my-organization (org_67890)
  2. personal-org (org_11111)

Test Deployment Command

openclaw deploy --dry-run --project test-project

If this command completes without the clw-auth-not-found error, the authentication is properly configured.

Verify File Permissions

Ensure the authentication file has the correct permissions:

# Check file permissions
ls -la ~/.openclaw/auth.json

# Expected output: -rw-------
# The file should be owned by the current user with read/write permissions only

Check Environment Variable (If Using Custom Path)

# Verify environment variable is set
echo $OPENCLAW_AUTH_PATH

# Verify the file exists at that path
ls -la "$OPENCLAW_AUTH_PATH"

5. Common Pitfalls

Avoid these common mistakes when troubleshooting the clw-auth-not-found error:

Pitfall 1: Ignoring File Permissions on Shared Systems

Never set authentication file permissions to world-readable (e.g., chmod 777). The file contains sensitive credentials and must be readable only by the owner:

# WRONG - insecure
chmod 777 ~/.openclaw/auth.json

# CORRECT - secure
chmod 600 ~/.openclaw/auth.json

Pitfall 2: Mixing Up Token Types

OpenClaw uses different token types. If you copied a legacy API key instead of the OAuth tokens, authentication will fail:

# WRONG - API key format
{
  "apiKey": "oc_api_abc123..."
}

# CORRECT - OAuth token format
{
  "accessToken": "oc_live_...",
  "refreshToken": "oc_refresh_..."
}

Pitfall 3: Forgetting to Set Environment Variable in CI/CD

When running OpenClaw in CI/CD pipelines, ensure the environment variable is properly injected:

# Example GitHub Actions workflow
- name: Deploy with OpenClaw
  env:
    OPENCLAW_AUTH_PATH: /opt/app/.openclaw/auth.json
  run: |
    echo "${{ secrets.OPENCLAW_AUTH_JSON }}" > /opt/app/.openclaw/auth.json
    chmod 600 /opt/app/.openclaw/auth.json
    openclaw deploy --project my-app

Pitfall 4: Not Handling Docker Volume Mounts

In Docker environments, always mount the authentication directory:

# WRONG - volume not mounted
docker run my-app openclaw deploy

# CORRECT - volume mounted
docker run -v ~/.openclaw:/root/.openclaw my-app openclaw deploy

Pitfall 5: Assuming Login Persists Across Updates

After updating OpenClaw, the authentication file structure may change. Run openclaw auth login again after major version updates:

# Check current version
openclaw --version

# After updating
openclaw auth login

Pitfall 6: Missing Directory Creation

The openclaw auth login command may fail if the target directory doesn’t exist:

# Always create the directory first
mkdir -p ~/.openclaw
openclaw auth login

The following errors are related to clw-auth-not-found and may occur during OpenClaw authentication troubleshooting:

clw-auth-invalid: This error occurs when the authentication file exists but contains invalid or malformed credentials. The file structure does not match the expected format or the tokens are corrupted.

clw-auth-expired: This error indicates that the authentication tokens in the file have expired and need to be refreshed. Run openclaw auth refresh to obtain new credentials.

clw-api-key-missing: Similar to clw-auth-not-found, but specifically for API key-based authentication rather than OAuth tokens. This error occurs when the OPENCLAW_API_KEY environment variable is not set.

clw-config-corrupt: This error indicates that the OpenClaw configuration file exists but is corrupted or in an unsupported format. The JSON may be malformed or the file may contain incompatible version information.

clw-network-error: This error occurs when OpenClaw cannot reach the authentication server due to network connectivity issues. It may appear alongside clw-auth-not-found if the CLI attempts to refresh credentials after detecting a missing auth file.

clw-permission-denied: This error occurs when the authentication file exists but cannot be read due to insufficient file permissions. It is related to the permission issues described in the common pitfalls section.

For additional troubleshooting information, consult the OpenClaw documentation at https://docs.openclaw.io or run openclaw help for command-specific guidance.

authentication configuration clw-auth-not-found openclaw cli