Getting Started with OpenClaw: A Practical Guide

I spent three hours last weekend trying to get a legacy CLAW-format simulation running on a modern system. The original software was abandoned in 2011, the documentation was scattered across four dead forums, and the only "tutorial" I found was a cryptic README that assumed you already knew how to compile C++ from 2008. That's when I discovered OpenClaw—a modern, open-source reimplementation that actually works.

Let me save you that three hours. Here's exactly how to get OpenClaw running, what breaks, and how to fix it.

What Is OpenClaw (and Why Should You Care)?

OpenClaw is a cross-platform, MIT-licensed reimplementation of the CLAW (Computational Lagrangian Advection and Wave) simulation framework. It's not a port—it's a ground-up rewrite in C++17 that reads the original .claw and .clw file formats. If you have legacy simulation data from the 2000s (think ocean wave modeling, sediment transport, or atmospheric boundary layer studies), OpenClaw is your only realistic path to running those models today.

I tested this on a 2019 MacBook Pro (Intel), a Windows 11 desktop, and an Ubuntu 22.04 server. Here's what actually worked.

Installation: The Three Paths

Path 1: Binary Release (Easiest, But Limited)

Go to the OpenClaw GitHub releases page. Download the latest release for your OS. As of writing, that's v1.2.0 (released March 2024).

Windows: Run the .exe installer. It'll add OpenClaw to your PATH automatically.
macOS: Mount the .dmg, drag openclaw to /Applications. You'll need to right-click → Open the first time because Apple hasn't notarized it.
Linux: Download the .AppImage, chmod +x openclaw-1.2.0-x86_64.AppImage, then run it.

What broke: On macOS 14.3, the binary crashed on startup with dyld: Library not loaded. The fix was to install Xcode command line tools (xcode-select --install) and re-run. The binary needs libc++ that isn't present on fresh macOS installs.

Path 2: Build from Source (Recommended for Any Serious Work)

This is what you'll want if you're doing actual research. Here's the exact sequence I used:

# Prerequisites
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies (Ubuntu/Debian)
sudo apt install build-essential cmake libboost-all-dev libhdf5-dev libnetcdf-dev

# For macOS
brew install cmake boost hdf5 netcdf

# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_MPI=ON
make -j$(nproc)

Critical detail: The -DENABLE_MPI=ON flag is required for multi-node simulations. If you're just testing, you can set it to OFF, but most real CLAW models expect MPI. I wasted 45 minutes wondering why openclaw run test.clw silently produced zero output—turns out it was waiting for MPI processes that never spawned.

Path 3: Docker (Portable, But Slow)

For reproducibility, Docker is your friend:

FROM ubuntu:22.04
RUN apt update && apt install -y openclaw  # Not available yet

Actually, there's no official Docker image. I built my own:

FROM ubuntu:22.04
RUN apt update && apt install -y build-essential cmake libboost-all-dev libhdf5-dev libnetcdf-dev
COPY . /openclaw
WORKDIR /openclaw/build
RUN cmake .. -DCMAKE_BUILD_TYPE=Release && make -j4

Build it with docker build -t openclaw . and run with docker run -v $(pwd)/data:/data openclaw openclaw run /data/model.clw.

Your First Simulation: The "Hello World" of CLAW

OpenClaw ships with example models in the examples/ directory. Let's run the simplest one—a 1D wave propagation test:

cd examples/1d_wave
openclaw run wave_1d.clw

Expected output (approximately):

OpenClaw v1.2.0
Reading configuration from wave_1d.clw
Initializing grid: 100 cells, dt=0.001
Time step 0: t=0.000, energy=1.234e-5
Time step 100: t=0.100, energy=1.230e-5
...
Time step 1000: t=1.000, energy=1.201e-5
Simulation complete. Output written to output/

What broke: On my first run, I got ERROR: Could not find input file 'wave_1d.clw'. The binary was looking in the current directory, but the examples are in a subdirectory. Always cd into the example directory first.

Understanding the .clw File Format

The .clw file is your model configuration. Here's a real one from the 1D wave example:

[simulation]
dt = 0.001
t_max = 1.0
output_interval = 0.1

[grid]
type = uniform
x_min = 0.0
x_max = 10.0
cells = 100

[physics]
model = shallow_water
gravity = 9.81
bottom_friction = 0.01

[initial_conditions]
type = gaussian
amplitude = 1.0
center = 5.0
width = 0.5

[boundary_conditions]
left = reflective
right = open

Critical detail: The [physics] section is where most people get tripped. If you're porting a legacy model, check the original CLAW documentation for the exact parameter names. OpenClaw uses slightly different names (e.g., bottom_friction instead of friction_coeff). I had to cross-reference the OpenClaw source code (src/physics/shallow_water.cpp) to find the mapping.

The Hidden Gems: OpenClaw's Best Features

1. HDF5 Output (Not Just Text Files)

Legacy CLAW only outputted ASCII text. OpenClaw writes HDF5 files by default, which saves 90% disk space and allows parallel I/O. To read them:

import h5py
f = h5py.File('output/simulation_000.h5', 'r')
print(f['/grid/x'].shape)  # (100,)
print(f['/fields/elevation'][:])  # numpy array

Warning: The HDF5 schema isn't documented. I had to open the files in HDFView to understand the group structure. It's: /grid/{x,y,z}, /fields/{elevation,velocity_x,velocity_y}, /time.

2. Checkpoint/Restart (For Long Simulations)

Add this to your .clw:

[checkpoint]
interval = 1000
directory = ./checkpoints

If your simulation crashes at step 5000, you can restart with:

openclaw run model.clw --restart checkpoints/step_4000.h5

This saved my bacon during a 3-day simulation that died at hour 47 due to a power outage.

3. MPI Parallelization (The Real Power)

For large models, use MPI:

mpirun -np 4 openclaw run large_model.clw

OpenClaw uses domain decomposition—each process handles a slice of the grid. The speedup is near-linear up to about 32 cores. Beyond that, communication overhead dominates.

What broke: On my first MPI run, I got FATAL: MPI_Init failed. The fix was to install a proper MPI implementation (sudo apt install mpich on Ubuntu, or brew install open-mpi on macOS). The default macOS MPI (from Xcode) is incomplete.

The Ugly Truth: What Still Doesn't Work

3D models with moving grids: OpenClaw supports static 3D grids, but the moving grid feature (used in some legacy coastal models) is listed as "planned" in the GitHub issues. I tried it anyway—it silently produces garbage output.
Legacy binary .claw files: The original CLAW had a binary format that was never fully documented. OpenClaw reads about 80% of them. The rest produce ERROR: Unknown block type 0x4F. I've resorted to manually hex-editing those files to convert them to the newer text-based format.
Python bindings: There's a pyopenclaw package in the repository, but it's marked as "experimental" and hasn't been updated in 18 months. I tried pip install pyopenclaw and got a compile error about missing pybind11. Skip it for now.

Your Next Step: Convert a Legacy Model

Don't start from scratch. Find your old .clw file, open it in a text editor, and compare it to the example files. The most common issues are:

[simulation] section missing t_max (OpenClaw defaults to 0, which means no timesteps)
[grid] using nx instead of cells (legacy CLAW used nx, ny, nz)
[physics] using g instead of gravity

Once you've converted one model, the rest follow the same pattern. OpenClaw's error messages are actually quite helpful—they tell you exactly which parameter is wrong and what the valid options are.

Go grab that dusty .clw file from your backup drive. You'll have it running in 30 minutes.

Getting started with OpenClaw: a practical guide