OpenClaw 入門実践ガイド

# OpenClaw入門ガイド：実践的なスタートアップ

先週末、最新システムでレガシーなCLAW形式のシミュレーションを動かそうとして3時間を費やしました。元のソフトウェアは2011年に開発が放棄され、ドキュメントは4つの閉鎖されたフォーラムに散在し、唯一見つけた「チュートリアル」は、2008年当時のC++のコンパイル方法を既に知っていることを前提とした難解なREADMEだけでした。そんな時に見つけたのがOpenClaw——実際に動作する、モダンでオープンソースの再実装です。

その3時間を節約しましょう。OpenClawの正確な起動方法、問題が発生する箇所、そしてその修正方法を説明します。

## OpenClawとは（そしてなぜ注目すべきか）

OpenClawは、CLAW（Computational Lagrangian Advection and Wave）シミュレーションフレームワークのクロスプラットフォーム、MITライセンスの再実装です。単なる移植ではなく、C++17でゼロから書き直され、元の`.claw`および`.clw`ファイル形式を読み取ります。2000年代のレガシーシミュレーションデータ（海洋波浪モデリング、土砂輸送、大気境界層研究など）をお持ちなら、現在それらのモデルを実行する現実的な唯一の方法がOpenClawです。

2019年製MacBook Pro（Intel）、Windows 11デスクトップ、Ubuntu 22.04サーバーでテストしました。実際に動作した手順をご紹介します。

## インストール：3つの方法

### 方法1：バイナリリリース（最も簡単だが制限あり）

[OpenClaw GitHubリリースページ](https://github.com/openclaw/openclaw/releases)にアクセスし、お使いのOS用の最新リリースをダウンロードしてください。執筆時点ではv1.2.0（2024年3月リリース）です。

**Windows**：`.exe`インストーラーを実行します。自動的にOpenClawがPATHに追加されます。

**macOS**：`.dmg`をマウントし、`openclaw`を`/Applications`にドラッグします。初回は右クリック→「開く」が必要です（Appleが公証していないため）。

**Linux**：`.AppImage`をダウンロードし、`chmod +x openclaw-1.2.0-x86_64.AppImage`を実行後、起動します。

**発生した問題**：macOS 14.3では、バイナリが起動時に`dyld: Library not loaded`でクラッシュしました。修正方法は、Xcodeコマンドラインツールをインストール（`xcode-select --install`）して再実行することです。このバイナリは、新規のmacOSインストールには存在しないlibc++を必要とします。

### 方法2：ソースからビルド（本格的な作業には推奨）

実際の研究を行う場合はこちらを選びましょう。私が使用した正確な手順は以下の通りです：

```bash

# 前提条件

git clone https://github.com/openclaw/openclaw.git

cd openclaw

# 依存関係のインストール（Ubuntu/Debian）

sudo apt install build-essential cmake libboost-all-dev libhdf5-dev libnetcdf-dev

# macOSの場合

brew install cmake boost hdf5 netcdf

# ビルド

mkdir build && cd build

cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_MPI=ON

make -j$(nproc)

```

**重要な詳細**：`-DENABLE_MPI=ON`フラグはマルチノードシミュレーションに必須です。テストのみの場合は`OFF`に設定できますが、実際のCLAWモデルのほとんどはMPIを期待します。`openclaw run test.clw`が何も出力せずに終了する理由を45分も探していましたが、MPIプロセスが生成されないのを待っていただけでした。

### 方法3：Docker（ポータブルだが遅い）

再現性のためにはDockerが便利です：

```dockerfile

FROM ubuntu:22.04

RUN apt update && apt install -y openclaw # まだ利用不可

```

実際には公式Dockerイメージはありません。自分でビルドしました：

```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

```

`docker build -t openclaw .`でビルドし、`docker run -v $(pwd)/data:/data openclaw openclaw run /data/model.clw`で実行します。

## 最初のシミュレーション：CLAWの「Hello World」

OpenClawには`examples/`ディレクトリにサンプルモデルが付属しています。最もシンプルな1D波動伝搬テストを実行してみましょう：

```bash

cd examples/1d_wave

openclaw run wave_1d.clw

```

**期待される出力**（概算）：

```

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/

```

**発生した問題**：初回実行時、`ERROR: Could not find input file 'wave_1d.clw'`が表示されました。バイナリはカレントディレクトリを探していましたが、サンプルはサブディレクトリにあります。必ず先にサンプルディレクトリに`cd`してください。

## .clwファイル形式の理解

`.clw`ファイルはモデル設定です。以下は1D波動サンプルの実際のものです：

```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

```

**重要な詳細**：`[physics]`セクションで多くの人がつまずきます。レガシーモデルを移植する場合、元のCLAWドキュメントで正確なパラメータ名を確認してください。OpenClawは微妙に異なる名前を使用しています（例：`friction_coeff`ではなく`bottom_friction`）。私はOpenClawのソースコード（`src/physics/shallow_water.cpp`）をクロスリファレンスして対応関係を見つけました。

## 隠れた機能：OpenClawの優れた特徴

### 1. HDF5出力（テキストファイルだけではない）

レガシーCLAWはASCIIテキストのみ出力していました。OpenClawはデフォルトでHDF5ファイルを書き込み、90%のディスク容量を節約し、並列I/Oを可能にします。読み取り方法：

```python

import h5py

f = h5py.File('output/simulation_000.h5', 'r')

print(f['/grid/x'].shape) # (100,)

print(f['/fields/elevation'][:]) # numpy配列

```

**警告**：HDF5スキーマはドキュメント化されていません。HDFViewでファイルを開いてグループ構造を理解する必要がありました。構造は：`/grid/{x,y,z}`、`/fields/{elevation,velocity_x,velocity_y}`、`/time`です。

### 2. チェックポイント/再開（長時間シミュレーション用）

`.clw`に以下を追加：

```ini

[checkpoint]

interval = 1000

directory = ./checkpoints

```

シミュレーションがステップ5000でクラッシュした場合、以下で再開できます：

```bash

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

```

**これで助かりました**：47時間目に停電で停止した3日間のシミュレーションを復旧できました。

### 3. MPI並列化（真の力）

大規模モデルにはMPIを使用：

```bash

mpirun -np 4 openclaw run large_model.clw

```

OpenClawは領域分割を使用します——各プロセスがグリッドの一部を担当します。約32コアまでほぼ線形の速度向上が得られます。それ以上では通信オーバーヘッドが支配的になります。

**発生した問題**：初回のMPI実行時、`FATAL: MPI_Init failed`が発生しました。修正方法は適切なMPI実装をインストールすることです（Ubuntuでは`sudo apt install mpich`、macOSでは`brew install open-mpi`）。デフォルトのmacOS MPI（Xcode付属）は不完全です。

## 厳しい現実：まだ動作しないもの

1. **移動グリッドを使用した3Dモデル**：OpenClawは静的3Dグリッドをサポートしていますが、移動グリッド機能（一部のレガシー沿岸モデルで使用）はGitHubのIssueで「計画中」とされています。試してみましたが、無言でゴミ出力を生成しました。

2. **レガシーバイナリ.clawファイル**：元のCLAWには完全にドキュメント化されていないバイナリ形式がありました。OpenClawはその約80%を読み取ります。残りは`ERROR: Unknown block type 0x4F`を生成します。私は手動でそれらのファイルを16進数編集して、新しいテキストベースの形式に変換しています。

3. **Pythonバインディング**：リポジトリに`pyopenclaw`パッケージがありますが、「実験的」とマークされ、18ヶ月間更新されていません。`pip install pyopenclaw`を試しましたが、`pybind11`がないというコンパイルエラーが発生しました。今はスキップしてください。

## 次のステップ：レガシーモデルの変換

ゼロから始めないでください。古い`.clw`ファイルを見つけ、テキストエディタで開き、サンプルファイルと比較してください。最も一般的な問題は：

- `[simulation]`セクションに`t_max`がない（OpenClawのデフォルトは0、つまりタイムステップなし）

- `[grid]`で`cells`の代わりに`nx`を使用（レガシーCLAWは`nx`、`ny`、`nz`を使用）

- `[physics]`で`gravity`の代わりに`g`を使用

1つのモデルを変換できれば、残りも同じパターンに従います。OpenClawのエラーメッセージは実際に非常に役立ちます——どのパラメータが間違っていて、有効なオプションが何かを正確に教えてくれます。

バックアップドライブから埃をかぶった`.clw`ファイルを取り出してください。30分で動作させることができます。