企业官网建设流程全解析

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

openclaw dashboard是 OpenClaw CLI 中用于打开浏览器版 Control UI（控制面板）的核心维护命令：它会读取当前配置与认证信息，自动拼装带令牌的访问 URL，并完成"打印 → 复制剪贴板 → 启动浏览器"的一站式流程。本文以 docs/cli/dashboard.md 为主线，结合 commands/dashboard.ts 的实现、commands/dashboard.test.ts 与 commands/dashboard.links.test.ts 的测试用例，以及 docs/web/control-ui.md 的配套说明，深入讲解该命令的用法、令牌解析链路、SecretRef 防泄漏设计、URL 生成规则与无图形环境下的 SSH 隧道方案，帮助你安全、高效地在浏览器中管理 OpenClaw 网关。

命令概览：openclaw dashboard

dashboard是 OpenClaw CLI 的维护类（maintenance）命令之一，注册于 cli/program/register.maintenance.ts（与doctor、reset、uninstall同组），官方描述为"Open the Control UI with your current token"，即使用当前认证信息打开 Control UI。

基本用法：

# 默认行为：打印/复制 URL，并自动启动浏览器 openclaw dashboard # 只打印 URL，不启动浏览器（适合服务器、SSH 会话、脚本场景） openclaw dashboard --no-open

完整命令定义见 cli/program/register.maintenance.ts#L43-L58：

在无头服务器、Docker 容器或 SSH 会话中执行时，浏览器启动通常会失败，命令会自动降级为打印 URL 与 SSH 隧道提示（详见下文"无图形环境"小节）。

前置条件：网关与 Control UI

dashboard打开的是由Gateway托管的 Control UI——一个基于Vite + Lit的单页应用，与网关 WebSocket 同端口通信（默认18789）。因此执行该命令前需先确认网关正在运行：

openclaw gateway

如果网关未启动，页面将无法加载。Control UI 的默认访问地址为http://127.0.0.1:18789/（或http://localhost:18789/），也可以通过在配置中设置gateway.controlUi.basePath增加路径前缀，例如/openclaw后地址变为http://127.0.0.1:18789/openclaw/。Control UI 的能力范围包括：与模型聊天（chat.history/chat.send/chat.abort/chat.inject）、渠道状态与二维码登录、实例/Session 管理、Cron 任务面板、Skills 管理、配置查看与热重载（config.get/config.set/config.apply）、日志实时查看、执行审批与设备管理，详见 docs/web/control-ui.md。

令牌来源解析：gateway.auth.token的完整查找链

dashboard命令的关键动作之一是解析配置中的gateway.auth.token。从源码 commands/dashboard.ts#L19-L48 看，其解析函数resolveDashboardToken委托给resolveConfiguredSecretInputWithFallback（实现在 gateway/resolve-configured-secret-input-string.ts），令牌来源优先级如下：

1. config（配置明文）：gateway.auth.token直接配置为普通字符串（如"replace-me"）；
2. secretRef（SecretRef 引用）：gateway.auth.token是 SecretRef 结构（{ source, provider, id }），或环境变量模板字符串（如"${OPENCLAW_GATEWAY_TOKEN}"），尝试从秘密提供方解析出真实值；
3. env（环境变量回退）：以上均无结果时，回退读取环境变量OPENCLAW_GATEWAY_TOKEN（见 gateway/credentials.ts 中导出的readGatewayTokenEnv）。

最终返回值带source: "config" | "env" | "secretRef"标记，用于区分令牌到底来自哪一层。测试 commands/dashboard.links.test.ts#L157-L179 验证了"SecretRef 无法解析但存在环境变量回退"的场景：此时虽然OPENCLAW_GATEWAY_TOKEN可作回退，URL 仍保持非令牌化（见下节）。

SecretRef 防泄漏设计：为什么 URL 有时不带令牌

文档明确指出，dashboard会尽可能解析gateway.auth.token的 SecretRef；但对于 SecretRef 托管的令牌（无论是否成功解析），命令都不会把令牌拼进 URL，而是打印/复制/打开一个非令牌化（non-tokenized）URL。这一设计的核心目的是：避免外部托管的秘密出现在终端输出、剪贴板历史或浏览器启动参数中。

对应源码逻辑见 commands/dashboard.ts#L71-L76：

// 避免把外部托管的 SecretRef 令牌嵌入终端/剪贴板/浏览器参数 const includeTokenInUrl = token.length > 0 && !resolvedToken.tokenSecretRefConfigured; // 优先使用 URL fragment，避免令牌通过 query 参数泄露 const dashboardUrl = includeTokenInUrl ? `${links.httpUrl}#token=${encodeURIComponent(token)}` : links.httpUrl;

三种典型场景汇总：

另外两个安全细节值得注意：

• 使用 URL fragment（#token=...）而非 query 参数（?token=...）传递令牌。fragment 不会随 HTTP 请求发送到服务器，也不会出现在代理日志或Referer头中，降低泄露面。
• 当 SecretRef 未解析时，命令不会在 URL 中嵌入无效的令牌占位符，而是打印明确的修复指引：

Token auto-auth unavailable: gateway.auth.token SecretRef is unresolved (env:default:MISSING_GATEWAY_TOKEN). Set OPENCLAW_GATEWAY_TOKEN in this shell or resolve your secret provider, then rerun `openclaw dashboard`.

测试 commands/dashboard.links.test.ts#L132-L155 验证了该场景下剪贴板与浏览器打开的都是http://127.0.0.1:18789/（无令牌），且日志包含上述指引。

SecretRef 的结构定义见 config/types.secrets.ts#L10-L16：SecretInput = string | SecretRef，其中SecretRef = { source: "env" | "file" | "exec"; provider: string; id: string }。环境变量模板字符串（如"${CUSTOM_GATEWAY_TOKEN}"）同样被识别为外部秘密引用。

URL 生成细节：bind 模式、端口与 basePath

dashboard生成 URL 时，并非简单拼接127.0.0.1:18789，而是基于配置实时计算。核心逻辑在resolveControlUiLinks（commands/onboard-helpers.ts#L302-L331），它同时输出 HTTP 与 WebSocket 地址：

// 输入：port、bind、customBindHost、basePath // 输出：{ httpUrl, wsUrl }

URL 的主机部分由gateway.bind决定（bind默认值为loopback，见 config/types.gateway.ts#L393-L412）：

其中"lan 强制映射为 loopback"是一个值得关注的安全细节，源码注释与测试 commands/dashboard.test.ts#L75-L89 均有说明：LAN 地址在浏览器中无法通过 secure-context 校验（非安全上下文会阻断 WebCrypto 等能力），因此dashboard只做lan → loopback的单向转换，其余 bind 模式原样保留。

// commands/dashboard.ts#L65-L70 const links = resolveControlUiLinks({ port, bind: bind === "lan" ? "loopback" : bind, customBindHost, basePath, });

测试同时验证了custom（bind: "custom", customBindHost: "10.0.0.5"）与tailnet两种模式会被完整保留（commands/dashboard.test.ts#L91-L115）。

gateway.controlUi.basePath会作为路径前缀拼入 URL；若设置了gateway.controlUi.root，还可指定 Control UI 静态资源目录（默认dist/control-ui）。完整的GatewayControlUiConfig字段见 config/types.gateway.ts#L99-L121：

{ gateway: { controlUi: { enabled: true, // 是否托管 Control UI，默认开启 basePath: "/openclaw", // 可选路径前缀 root: "dist/control-ui", // 静态资源根目录 allowedOrigins: [], // WebSocket 允许的浏览器来源 // dangerouslyAllowHostHeaderOriginFallback: false, // 危险项：Host 头回退 // allowInsecureAuth: false, // 非安全上下文认证开关 // dangerouslyDisableDeviceAuth: false, // 危险项：关闭设备身份校验 }, }, }

端口由resolveGatewayPort解析，默认18789（GatewayConfig.port，见 config/types.gateway.ts#L394-L395）。

无图形环境：自动输出 SSH 隧道提示

当命令所在环境没有可用的 GUI（例如通过 SSH 登录服务器）时，dashboard会检测浏览器启动支持，失败后回退为打印 SSH 隧道指引（commands/onboard-helpers.ts#L137-L168）：

No GUI detected. Open from your computer: ssh -N -L 18789:127.0.0.1:18789 user@<host> Then open: http://localhost:18789/

该提示通过formatControlUiSshHint生成，其中 SSH 目标主机取自SSH_CONNECTION环境变量，用户名取自USER/LOGNAME。若令牌可安全嵌入（非 SecretRef 托管），还会额外打印带#token=...的自动认证地址。测试 commands/dashboard.links.test.ts#L104-L117 覆盖了"浏览器无法打开时打印 SSH 提示"的分支。

--no-open：纯输出模式与剪贴板复制

在 CI、脚本或远程环境中，--no-open会跳过detectBrowserOpenSupport与openUrl调用，仅输出一行提示：

Browser launch disabled (--no-open). Use the URL above.

无论是否--no-open，命令都会尝试把 dashboard URL 复制到剪贴板（通过 infra/clipboard.js 的copyToClipboard，无剪贴板环境会静默降级并打印 "Copy to clipboard unavailable."）。测试 commands/dashboard.links.test.ts#L119-L130 验证了--no-open下既不会检测浏览器支持、也不会调用打开动作。

首次连接：设备配对（Pairing）

通过dashboard打开 Control UI 后，若是从新的浏览器或设备首次连接，网关会要求一次性的设备配对审批——即使位于同一 Tailnet 且设置了gateway.auth.allowTailscale: true也不例外（这是防止未授权访问的安全措施）。典型表现是页面显示disconnected (1008): pairing required。

处理方式（详见 docs/web/control-ui.md 与 docs/cli/devices.md）：

# 列出待审批请求 openclaw devices list # 按 requestId 审批 openclaw devices approve <requestId> # 不传 ID 时自动审批最近一条请求 openclaw devices approve openclaw devices approve --latest # 撤销已配对设备（需指定设备 ID 与角色） openclaw devices revoke --device <deviceId> --role node

注意：本地连接（127.0.0.1）会自动批准，无需手动配对；LAN、Tailnet 等远程连接必须显式审批；每个浏览器 profile 会产生独立设备 ID，切换浏览器或清除浏览器数据后需重新配对。这些命令要求operator.pairing（或operator.admin）权限。

远程访问与 HTTPS 建议

文档 docs/web/control-ui.md 建议了两类远程访问方案：

方案一：Tailscale Serve（推荐，自动 HTTPS）——保持网关在 loopback，用 Tailscale Serve 反向代理：

openclaw gateway --tailscale serve

然后通过https://<magicdns>/访问（或配置的gateway.controlUi.basePath前缀）。默认情况下，gateway.auth.allowTailscale: true时可通过 Tailscale 身份头（tailscale-user-login）认证。

方案二：tailnet 绑定 + 令牌：

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

然后访问http://<tailscale-ip>:18789/，在 UI 设置中粘贴令牌（以connect.params.auth.token发送）。

需要提醒的是：通过纯 HTTP 访问 LAN/Tailnet 地址属于非安全上下文，浏览器会阻断 WebCrypto，默认情况下 Control UI 会拒绝无设备身份的连接。若确需在非安全上下文中使用（应急场景），可显式配置gateway.controlUi.allowInsecureAuth: true；注意该开关不会绕过设备身份与配对检查。更彻底的"破窗"选项gateway.controlUi.dangerouslyDisableDeviceAuth: true会关闭设备身份校验，属于严重的安全降级，仅建议应急使用后立即还原。

小结：命令执行全景

openclaw dashboard从配置读取到浏览器打开的完整链路可归纳为：

1. 读取配置快照（readConfigFileSnapshot），解析网关端口、bind 模式、customBindHost、basePath；
2. 按config → secretRef → 环境变量的顺序解析gateway.auth.token（回退变量OPENCLAW_GATEWAY_TOKEN）；
3. 依据 bind 模式生成 URL（lan强制映射为loopback，其余保留）；
4. 根据"是否 SecretRef 托管"决定是否将令牌以fragment（#token=）形式嵌入 URL，避免 query 参数与终端日志泄露；
5. 打印 URL → 复制剪贴板 → 检测浏览器支持并打开；失败则输出 SSH 隧道提示。

整个行为由 commands/dashboard.ts 实现，并由 commands/dashboard.test.ts（bind 模式选择）与 commands/dashboard.links.test.ts（令牌泄漏防护、--no-open、SSH 提示）双层测试锁定，可作为深入阅读与二次开发的入口。

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯