Web 仪表盘（`gateway.web_dist_dir`）

网关守护进程将其 HTTP API 内置于二进制文件中，但 Web 仪表板的 HTML/JS/CSS 则以磁盘文件形式存放于由 Vite 生成的 web/dist/ 目录中。gateway.web_dist_dir 设置（及其 schema 镜像环境变量覆盖项 ZEROCLAW_gateway__web_dist_dir）用于告知守护进程该目录的位置。当该设置和已知的回退位置均不包含已构建的 index.html 时，网关将以 API-only mode 启动，仪表板 URL 会返回“不可用“消息。

太长不看

sh

# 等效的环境变量覆盖（仅存于内存中，从不持久化）
export ZEROCLAW_gateway__web_dist_dir="/absolute/path/to/zeroclaw/web/dist"

然后构建一次 bundle：

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 是一个 Option<String>，指向包含已构建的 index.html 的目录。在网关启动时，守护进程会：

读取已配置的值（或环境变量覆盖值）。
验证目录在本机上存在且包含 index.html。
如果是，则从该路径提供仪表板服务。
如果没有，则记录一条 WARN 日志（“path doesn’t contain index.html on this machine; falling back to auto-detect”），并尝试下面的自动检测候选项。
如果自动检测同样未找到任何内容，网关将以仅 API 模式运行，GET / 会返回一条“不可用“消息，并指向此处。

该值被视为一种提示，而非强制要求。失效的路径（拼写错误、从其他机器复制的特定主机路径、缺失的构建）会降级为自动检测，而不会导致每个仪表盘请求崩溃。

默认：自动检测顺序

当 gateway.web_dist_dir 未设置（或设置为不包含 index.html 的路径）时，守护进程会按顺序探测以下位置，并从第一个包含 index.html 的位置提供服务：

#	候选项	当其匹配时
1	`./web/dist`（相对于当前工作目录）	在开发环境中从仓库根目录运行 `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 的方式相匹配的选项。

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。

覆盖优先级

该值按照标准的配置层级顺序进行解析：

ZEROCLAW_gateway__web_dist_dir（架构镜像环境变量，参见环境变量）
配置的 gateway.web_dist_dir
自动检测（上述五个候选项）

环境变量覆盖仅应用于内存中的 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)

同样的三个步骤可为其他每个 gateway 配置项生成环境变量名，例如 gateway.request_timeout_secs 会变为 ZEROCLAW_gateway__request_timeout_secs。

常见陷阱

不要使用 `~` 或 `$HOME`

网关不会展开字面量波浪号；请为 gateway.web_dist_dir 使用绝对路径。Shell 变量（$HOME、%USERPROFILE%）同样不会被展开；如果你以这种方式设置该值，请在环境变量中预先展开它们：

sh

export ZEROCLAW_gateway__web_dist_dir="$HOME/zeroclaw/web/dist"   # shell 展开 $HOME

配套的 PR #6961 为 zeroclaw doctor 和 zeroclaw self-test 两个命令添加了 issue #6079 中跟踪的针对性检查：“看起来像是未展开的 ~ / $VAR，请在写入此值前对其执行 shellexpand”，该检查为 Warn 级别诊断。在当前的 master 上，这两个命令都不会显示该检查，因此在 #6961 合入之前，请在写入 gateway.web_dist_dir 之前自行展开 ~ / $VAR（例如写 /home/alice/zeroclaw/web/dist 而非 ~/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）或设置路径。

另见

环境变量：完整的模式镜像语法
网关 HTTP API：仪表板与之通信的对象
构建 Web 仪表板：cargo web 子命令及其生成的内容

Keyboard shortcuts

ZeroClaw Docs