Web ダッシュボード (`gateway.web_dist_dir`)

ゲートウェイデーモンはHTTP APIをバイナリに同梱していますが、WebダッシュボードのHTML/JS/CSSは、Viteによって生成されるweb/dist/ディレクトリ内のディスク上に配置されています。gateway.web_dist_dir設定（およびそのスキーマミラー環境変数オーバーライドであるZEROCLAW_gateway__web_dist_dir）は、そのディレクトリの場所をデーモンに伝えます。この設定にも既知のフォールバック場所にもビルド済みのindex.htmlが含まれていない場合、ゲートウェイはAPIのみモードで起動し、ダッシュボードのURLは「利用不可」というメッセージを返します。

要約

sh

# 同等の環境変数オーバーライド（メモリ内のみ、永続化されない）
export ZEROCLAW_gateway__web_dist_dir="/absolute/path/to/zeroclaw/web/dist"

バンドルを一度ビルドします:

sh

cargo web build

…そしてデーモンを再起動します。起動ログが次のように変わります

Web dashboard: not available — no web/dist found. Build with `cargo web build` …

に

Web dashboard: serving from /absolute/path/to/zeroclaw/web/dist

設定の機能

gateway.web_dist_dir は、ビルド済みの index.html を含むディレクトリを指す Option<String> です。ゲートウェイ起動時に、デーモンは次を行います:

設定された値（または環境変数による上書き）を読み取ります。
このマシン上にディレクトリが存在し、かつ index.html を含んでいることを確認します。
「yes」の場合、そのパスからダッシュボードを提供します。
いいえの場合、WARN（「このマシンではパスに index.html が含まれていません。以下の自動検出にフォールバックします」）をログに記録し、以下の自動検出候補を試します。
自動検出でも何も見つからない場合、ゲートウェイはAPI専用モードで動作し、GET / は「利用できません」というメッセージを返し、ここに戻るよう案内します。

値はハードな要件ではなくヒントとして扱われます。古いパス（タイプミス、別のマシンからコピーされたホスト固有のパス、ビルドの欠落）は、ダッシュボードのすべてのリクエストをクラッシュさせるのではなく、自動検出にフォールバックします。

デフォルト: 順序を自動検出

gateway.web_dist_dir が未設定の場合（または index.html が存在しないパスが設定されている場合）、デーモンは次の場所を順番に調べ、index.html を含む最初の場所から配信します:

#	候補	一致した場合
1	`./web/dist`（CWD からの相対パス）	開発環境でリポジトリのルートから `cargo run` を実行する
2	`<dir-of-binary>/web/dist`	パッケージ化されたバイナリは、自身の隣に `web/dist` を同梱します
3	`/zeroclaw-data/web/dist`	標準的な Docker / パッケージ化されたボリュームのレイアウト
4	`/usr/share/zeroclawlabs/web/dist`	AUR / システムパッケージのインストール
5	`${XDG_DATA_HOME:-~/.local/share}/zeroclaw/web/dist`	ビルド済みバイナリインストーラー（ユーザーごと）

お使いのディストリビューションがこれらのいずれかで、ダッシュボードが「そのまま動作する」場合は、gateway.web_dist_dir を設定する必要はまったくありません。自動検出が見つけてくれています。

`web/dist` を取得する方法

ZeroClawをインストールした方法に応じて、3つのオプションから選択してください。

A) ソースのチェックアウト（開発者・パッケージャー向け）

sh

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo web build           # `cargo run -p xtask --bin web -- build` のエイリアス
                          # 初回実行時に `npm install` を自動実行します

バンドルは web/dist/ に出力されます。web_dist_dir をそのディレクトリの絶対パスに設定するか、リポジトリのルートからデーモンを実行して自動検出の候補 1 に検出させてください。

cargo web のサブコマンド一式（dev、check、gen-api など）については、Web ダッシュボードのビルドで説明しています。

B) ビルド済みのリリース成果物

リリースページのリリースアーカイブには、バイナリとともに web/dist/ があらかじめ配置されたデーモンが同梱されています。自動検出候補2がこれを検出するため、gateway.web_dist_dir の設定は不要です。

C) Docker イメージ

公式 Docker イメージでは、バンドルは /zeroclaw-data/web/dist（自動検出候補 3）に配置されます。すぐに利用できる状態になっているため、独自のボリュームをそのパスにマウントする場合のみ web_dist_dir を設定する必要があります。

オーバーライドの優先順位

値は標準の config レイヤー順で解決されます:

ZEROCLAW_gateway__web_dist_dir（スキーマミラー環境変数。環境変数を参照）
設定された gateway.web_dist_dir
自動検出（上記の5つの候補）

環境変数によるオーバーライドは、メモリ上の Config にのみ適用され、永続化されることはありません。

スキーマミラー文法：`ZEROCLAW_gateway__web_dist_dir` の導出

一般的な演算子オーバーライド文法（環境変数を参照）は、ドット区切りのTOMLパスを機械的に環境変数名にマッピングします。

TOML path:  gateway.web_dist_dir
            ─────── ─────────────
            section field-name (snake_case, kept as-is)

Env var:    ZEROCLAW_gateway__web_dist_dir
            ─────────       ──            ────────────
            prefix          path-separator  field-name
                            (`.` → `__`)    (unchanged)

同じ3つの手順により、他のすべてのゲートウェイ設定項目についても環境変数名が生成されます。例えば gateway.request_timeout_secs は ZEROCLAW_gateway__request_timeout_secs になります。

よくある落とし穴

`~` や `$HOME` を使用しないでください

リテラルのチルダはゲートウェイによって展開されません。gateway.web_dist_dir には絶対パスを使用してください。シェル変数（$HOME、%USERPROFILE%）も同様に展開されません。その方法で値を設定する場合は、環境変数内であらかじめ展開してください。

sh

export ZEROCLAW_gateway__web_dist_dir="$HOME/zeroclaw/web/dist"   # シェルが $HOME を展開する

関連する PR #6961 は、issue #6079 で追跡されている「展開されていない ~ / $VAR のように見えるため、この値を書き込む前に shellexpand してください」という対象を絞ったチェックを、Warn 重大度の診断として zeroclaw doctor と zeroclaw self-test の両方に追加します。現在の master ではどちらのコマンドもこれを表示しないため、#6961 がマージされるまでは、gateway.web_dist_dir を書き込む前に ~ / $VAR を自分で展開してください（例えば ~/zeroclaw/web/dist の代わりに /home/alice/zeroclaw/web/dist と書きます）。

相対パスは設定ファイルではなく CWD を基準に解決されます

web_dist_dir = "web/dist" は、設定ファイルの場所ではなく、起動時のデーモンの作業ディレクトリからの相対パスとして解釈されます。設定ファイルを別のホストに配布したり、異なるディレクトリからデーモンを起動したり（例: systemd 経由）すると、相対パス形式では誤った場所を参照してしまいます。web_dist_dir には絶対パスを使用してください。

起動時の “Stale path” 警告

WARN gateway.web_dist_dir points at a path that doesn't contain index.html
on this machine; falling back to auto-detect. Update or remove the setting
to silence this warning.

これはパスが構文的には有効であるものの、ファイルがまだ存在しないことを意味します。cargo web build を実行するか、パスを修正するか、設定を完全に削除して自動検出に任せてください。

起動時の「Web dashboard: not available」

INFO Web dashboard: not available — no web/dist found. Build with
`cargo web build` and point gateway.web_dist_dir at the resulting
web/dist directory.

APIエンドポイントは引き続き動作しており、HTML/JSバンドルのみが欠落しています。ビルドするか（上記のオプションA/B/C）、パスを設定してください。

ZeroClaw Docs