Web 仪表盘（`gateway.web_dist_dir`）

当 ZeroClaw 使用 embedded-web 特性构建时，编译内嵌的仪表板资源优先于 gateway.web_dist_dir 以及下文所述的文件系统位置。当内嵌资源不可用时，才会应用文件系统解析和仅 API 回退机制。

网关守护进程将其 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"

然后构建一次 bundle：

sh

cargo web build

……并重启守护进程。启动日志将从

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

到

Web dashboard: serving filesystem assets

解析后的目录会记录在该日志事件的结构化 path 字段中。

该设置的作用

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

读取已配置的值（或环境变量覆盖值）。
验证该目录是否存在，并确认其中的 index.html 在本机上能够正确解析到该仪表板根目录内。
如果是，则从该路径提供仪表板服务。
如果否，则记录一条 WARN 日志（“path has no usable 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 without a usable 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