Fix clw-agent-not-found: Agent binary not found in OpenClaw

1. Symptoms

When the clw-agent-not-found error occurs, you’ll observe one or more of the following symptoms in your OpenClaw deployment:

Primary Error Message:

[ERROR] clw-agent-not-found: Could not locate clw-agent binary in system PATH or configured directory
---

**Additional Console Output:**
```bash
$ openclaw agent start
OpenClaw v2.4.1 - Initializing agent subsystem...
[ERROR] Agent binary not found at expected location: /usr/local/bin/clw-agent
[ERROR] Searched paths:
  - /usr/local/bin
  - /usr/bin
  - /opt/openclaw/bin
  - ~/.openclaw/agents/current
[ERROR] Exit code: 127

Application-Level Symptoms:

The error manifests differently depending on how you’re using OpenClaw:

CLI Invocation: Commands like openclaw agent status, openclaw deploy, or openclaw monitor fail immediately with exit code 127.
SDK Integration: Python or Go SDKs raise an AgentNotFoundError exception when attempting to initialize the agent.
Docker/Container Deployments: Container logs show the agent binary is missing from the image, causing the entrypoint script to fail.
Systemd Services: The openclaw-agent.service enters a failed state and logs indicate the binary path is invalid.

Error Code Reference:

# Python SDK error example
from openclaw import Agent, OpenClawException

try:
    agent = Agent()
    agent.start()
except OpenClawException as e:
    print(f"Error code: {e.code}")  # Output: clw-agent-not-found
    print(f"Message: {e.message}")

2. Root Cause

The clw-agent-not-found error stems from one or more of the following root causes:

1. Incomplete Installation

The most common cause is an incomplete or interrupted OpenClaw installation. When the installation process fails to copy the clw-agent binary to the system PATH, the agent remains unavailable:

# Installation interrupted before binary placement
$ sudo ./openclaw-install.sh
Downloading clw-agent... Done
Extracting archive... Done
Installing configuration... Done
[INTERRUPTED - power loss/signal kill]
Configuring systemd service... [SKIPPED]
Binary installation to PATH... [SKIPPED]

2. PATH Configuration Issues

The agent binary may exist on the system but is not discoverable because it’s not in any directory listed in the $PATH environment variable:

# Binary exists but not in PATH
$ ls -la /opt/openclaw/clw-agent
-rwxr-xr-x 1 root staff 4.2M /opt/openclaw/clw-agent

$ echo $PATH
/usr/local/bin:/usr/bin:/bin

# /opt/openclaw is not in PATH

3. Incorrect Installation Directory

Some installation methods default to non-standard directories that aren’t automatically added to PATH:

Installation Method	Default Binary Location	PATH Updated?
Homebrew (macOS)	`/usr/local/bin`	Yes
APT package	`/usr/bin`	Yes
Manual tarball	`/opt/openclaw/bin`	No
Docker container	Container internal	N/A
Kubernetes	Configured via ConfigMap	N/A

4. Symbolic Link Issues

The binary may have been moved, deleted, or the symbolic link may be broken:

$ ls -la /usr/local/bin/clw-agent
lrwxrwxrwx 1 root staff /usr/local/bin/clw-agent -> /opt/openclaw/v2.4.1/bin/clw-agent

# Target directory was removed during upgrade:
$ ls -la /opt/openclaw/v2.4.1/bin/clw-agent
ls: cannot access '/opt/openclaw/v2.4.1/bin/clw-agent': No such file or directory

5. Architecture Mismatch

Downloading the wrong binary architecture (ARM vs x86_64) can cause the shell to report the file not found, even though it exists:

$ file /usr/local/bin/clw-agent
/usr/local/bin/clw-agent: ELF 64-bit LSB executable, x86-64

$ uname -m
aarch64

# Binary compiled for wrong architecture

3. Step-by-Step Fix

Step 1: Verify Binary Location and PATH Configuration

First, determine whether the clw-agent binary exists anywhere on your system:

# Search for the binary in common locations
$ find /usr /opt /home -name "clw-agent" -type f 2>/dev/null

# Check if it's in your current PATH
$ which clw-agent

# If which returns nothing, check PATH
$ echo $PATH

Step 2: Reinstall OpenClaw (Recommended)

The most reliable fix is a clean reinstall:

Before:

# Remove any partial installation
$ sudo rm -rf /opt/openclaw
$ sudo rm -f /usr/local/bin/clw-agent  # If exists

# Attempt installation with debug output
$ curl -sSL https://get.openclaw.io/install.sh | bash -x

After:

# Clean reinstall
$ curl -sSL https://get.openclaw.io/install.sh | sudo bash

# Verify installation
$ ls -la /usr/local/bin/clw-agent
-rwxr-xr-x 1 root staff 4218624 Jan 15 10:30:00 /usr/local/bin/clw-agent

$ clw-agent --version
OpenClaw Agent v2.4.1 (build 20250115)

Step 3: Manually Add to PATH (Alternative)

If you installed to a non-standard directory, add it to PATH:

Before:

# Check where the binary actually is
$ find /opt -name "clw-agent" -type f
/opt/openclaw/clw-agent

$ echo $PATH
/usr/local/bin:/usr/bin:/bin

# Binary not in PATH - will fail
$ clw-agent --version
bash: clw-agent: command not found

After:

# Add to PATH for current session
$ export PATH="/opt/openclaw:$PATH"
$ clw-agent --version
OpenClaw Agent v2.4.1 (build 20250115)

# Make permanent - add to shell profile
$ echo 'export PATH="/opt/openclaw:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

Step 4: Create Symbolic Link

Create a symbolic link in a PATH directory:

Before:

$ ls /opt/openclaw/clw-agent
/opt/openclaw/clw-agent

$ which clw-agent
clw-agent not found

After:

# Create symbolic link
$ sudo ln -s /opt/openclaw/clw-agent /usr/local/bin/clw-agent

# Verify
$ which clw-agent
/usr/local/bin/clw-agent

$ clw-agent --version
OpenClaw Agent v2.4.1 (build 20250115)

Step 5: Fix Architecture Mismatch

Download the correct binary for your system architecture:

# Identify your architecture
$ uname -m
aarch64

# Download correct binary (ARM64 version)
$ curl -o /tmp/clw-agent \
  https://get.openclaw.io/releases/latest/clw-agent-linux-arm64

$ chmod +x /tmp/clw-agent
$ sudo mv /tmp/clw-agent /usr/local/bin/clw-agent

Step 6: Fix Docker/Kubernetes Deployments

For containerized deployments, update your Dockerfile:

Before:

FROM ubuntu:22.04

# Partial installation - missing agent binary
RUN apt-get update && apt-get install -y openclaw-client
# Agent binary not included in openclaw-client package

CMD ["openclaw", "agent", "start"]

After:

FROM ubuntu:22.04

# Install full OpenClaw package including agent
RUN apt-get update && \
    apt-get install -y wget && \
    wget https://get.openclaw.io/releases/latest/openclaw-full.tar.gz && \
    tar -xzf openclaw-full.tar.gz && \
    mv clw-agent /usr/local/bin/ && \
    chmod +x /usr/local/bin/clw-agent && \
    rm openclaw-full.tar.gz

# Add to PATH
ENV PATH="/usr/local/bin:${PATH}"

CMD ["openclaw", "agent", "start"]

4. Verification

After applying the fix, verify the agent is correctly installed and operational:

Basic Verification:

# Check binary is findable
$ which clw-agent
/usr/local/bin/clw-agent

# Verify version and basic functionality
$ clw-agent --version
OpenClaw Agent v2.4.1 (build 20250115)

$ clw-agent status
Agent Status: Running
Agent ID: agent-7f3a2b9c
Version: 2.4.1
Uptime: 0h 0m 15s
Connected: true

Integration Verification:

# Test via OpenClaw CLI
$ openclaw agent status
Agent Status: Running
Connected to controller: wss://controller.openclaw.io
Last heartbeat: 2025-01-15T10:45:32Z

# Test SDK integration
$ python3 -c "
from openclaw import Agent
agent = Agent()
agent.connect()
print('Agent connected successfully:', agent.is_connected())
"
Agent connected successfully: True

Systemd Service Verification (Linux):

$ systemctl status openclaw-agent
● openclaw-agent.service - OpenClaw Agent Service
     Loaded: loaded (/etc/systemd/system/openclaw-agent.service)
     Active: active (running) since Thu 2025-01-15 10:45:00 UTC
   Main PID: 1234 (clw-agent)
      Tasks: 5 (limit: 4915)
     Memory: 45.2M

Docker Container Verification:

$ docker run --rm openclaw-demo openclaw agent status
Agent Status: Running
Connected: true

5. Common Pitfalls

Pitfall 1: Forgetting to Reload Shell Configuration

After modifying .bashrc or .zshrc, the current terminal session won’t have the updated PATH:

# WRONG - just editing the file
$ nano ~/.bashrc
$ clw-agent --version
bash: clw-agent: command not found

# CORRECT - source the file or start a new session
$ source ~/.bashrc
$ clw-agent --version
OpenClaw Agent v2.4.1

Pitfall 2: Permission Issues on Binary

The binary might exist but lack execute permissions:

# Check permissions
$ ls -la /usr/local/bin/clw-agent
-rw-r--r-- 1 root staff 4218624 /usr/local/bin/clw-agent  # No execute bit

# Fix permissions
$ sudo chmod +x /usr/local/bin/clw-agent
$ /usr/local/bin/clw-agent --version
OpenClaw Agent v2.4.1

Pitfall 3: Conflicting Old Installation

Multiple versions or installations can cause PATH conflicts:

# Check for multiple installations
$ which -a clw-agent
/usr/bin/clw-agent
/usr/local/bin/clw-agent

# Remove the older/broken one
$ sudo rm /usr/bin/clw-agent
$ clw-agent --version
OpenClaw Agent v2.4.1  # Now uses the correct one

Pitfall 4: Docker Layer Caching

Docker builds may use cached layers that don’t include the new binary:

# Force rebuild without cache
$ docker build --no-cache -t my-openclaw-app .

# Or use build secret for installation
$ docker build --secret id=openclaw_token \
    -t my-openclaw-app .

Pitfall 5: SELinux or AppArmor Blocking

Security modules may block execution from certain paths:

# Check for SELinux denials
$ sudo ausearch -m AVC -c clw-agent

# If blocked, either relabel or adjust policy
$ sudo semanage fcontext -a -t bin_t "/opt/openclaw(/.*)?"
$ sudo restorecon -Rv /opt/openclaw

Pitfall 6: Kubernetes Init Container Order

If using Kubernetes, ensure the agent binary is available before the main container starts:

apiVersion: v1
kind: Pod
metadata:
  name: openclaw-agent
spec:
  initContainers:
    - name: install-agent
      image: openclaw/installer:latest
      command: ['sh', '-c', 'cp /agent/clw-agent /shared/bin/']
      volumeMounts:
        - name: shared-bin
          mountPath: /shared/bin
  containers:
    - name: agent
      image: my-app:latest
      command: ['/shared/bin/clw-agent']
      volumeMounts:
        - name: shared-bin
          mountPath: /shared/bin

clw-agent-permission-denied Similar to clw-agent-not-found, this error occurs when the binary exists but cannot be executed due to insufficient permissions. If you encounter clw-agent-not-found after confirming the binary exists, verify execute permissions with ls -la /path/to/clw-agent and apply chmod +x if needed.

clw-agent-timeout This error indicates the agent was found but failed to connect to the controller within the timeout period. This typically occurs after a successful installation when network connectivity is blocked or the controller endpoint is unreachable.

clw-config-invalid Configuration errors can prevent the agent from locating required resources. If clw-agent-not-found persists after fixing the binary path, verify your configuration file points to the correct agent location:

$ cat ~/.openclaw/config.yaml
agent:
  binary_path: /usr/local/bin/clw-agent
  data_dir: /var/lib/openclaw

clw-connection-refused When the agent binary is found but the connection to the OpenClaw controller is refused, this error occurs. It’s distinct from clw-agent-not-found because it indicates the agent started successfully but cannot reach the server.

For additional troubleshooting, consult the OpenClaw Installation Guide or run openclaw doctor to auto-diagnose common configuration issues.

1. Symptoms

2. Root Cause

3. Step-by-Step Fix

Step 1: Verify Binary Location and PATH Configuration

Step 2: Reinstall OpenClaw (Recommended)

Step 3: Manually Add to PATH (Alternative)

Step 4: Create Symbolic Link

Step 5: Fix Architecture Mismatch

Step 6: Fix Docker/Kubernetes Deployments

4. Verification

5. Common Pitfalls

6. Related Errors