Getting started with OpenClaw: a practical guide
# 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](https://github.com/openclaw/openclaw/releases). 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:
```bash
# 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:
```dockerfile
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:
```dockerfile
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:
```bash
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:
```ini
[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:
```python
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`:
```ini
[checkpoint]
interval = 1000
directory = ./checkpoints
```
If your simulation crashes at step 5000, you can restart with:
```bash
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:
```bash
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
1. **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.
2. **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.
3. **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.