控制 UI 小程序
在 Telegram 中以 Mini App 方式运行 Control UI。
Control UI Mini App¶
Control UI Mini App 会将完整的 OpenClaw Control UI 作为 Telegram WebApp 打开。在与机器人的私聊中运行 /controlui,然后点按 打开 Control UI。该命令会在 Telegram 插件激活时自动注册;没有单独的 Mini App 开关。
/dashboard 会在 Telegram 上创建或更新会话仪表盘,与其他频道上的行为一致。请使用 /controlui 打开 OpenClaw 的 Control UI。
要求:
- 将
gateway.tailscale.mode设为"serve"或"funnel",用于已发布的 HTTPS Mini App URL。 - 你的数字 Telegram 用户 ID 必须位于所选账户的有效
allowFrom或commands.ownerAllowFrom中。通配符和用户名不会授予 Mini App 所有者访问权限。 - 请使用私聊。在群组中,
/controlui会回复open this in a DM with the bot,并且不会发送按钮。 - Docker 安装:Serve/Funnel 模式要求网关绑定到
tailscaled旁边的 loopback,桥接网络加已发布端口无法满足此要求。请使用network_mode: host运行网关容器,并将宿主机的tailscaledsocket(/var/run/tailscale)以及tailscaleCLI 挂载到容器中。
如果 /controlui 回复 Restricted to the bot owner,请让 OpenClaw 管理员将回复中显示的数字 Telegram 用户 ID 添加到所选机器人账户的 allowFrom(例如 channels.telegram.accounts.ops.allowFrom)或 commands.ownerAllowFrom,使用 telegram:<userId> 条目。保留现有允许列表条目,并在配置更改生效后重试 /controlui。管理员还可以将该数字 ID 添加到该所有者列表已引用的访问组的 Telegram 成员中。
从 /dashboard 升级¶
早期版本(包括 OpenClaw 2026.8.x 和 2026.9.1)使用 /dashboard 打开 Telegram Mini App。升级后请使用 /controlui,并更新指向 Mini App 的已保存说明、快捷方式和自定义机器人菜单描述。/dashboard 现在会创建或更新会话仪表盘,而不再重定向到 /controlui。
当 Telegram 账户启动时,网关会在机器人菜单中注册新命令。Mini App URL 和 Tailscale 配置保持不变。请请求一个新的 /controlui 按钮;之前的启动链接有效时间较短。
升级后,仅包含通配符的访问组不再授予 Control UI 启动或 Mini App 身份验证权限。添加一个明确的数字所有者 ID 以恢复访问权限;用户名和通配符仍然不足。
发布 Mini App¶
配置以下受支持的 Tailscale 发布模式之一:
OpenClaw 在构建 Control UI 和 WebSocket URL 时会自动遵循 gateway.controlUi.basePath。
当 Mini App 打开时,Telegram 会提供签名后的 WebApp initData。OpenClaw 使用所选机器人账户的令牌验证其签名,拒绝缺失、无效、过期或重放的数据,提取数字 Telegram 用户 ID,并在移交给 Control UI 之前再次检查所有者访问权限。
如果 /controlui 无法解析已发布的 HTTPS URL,它会回复:
Mini App needs an HTTPS gateway URL. Set `gateway.tailscale.mode: serve` or `funnel`, then retry /controlui.
设置上述模式之一,确保 Tailscale 在网关主机上运行,然后重试该命令。
Mini App 是一个仅限 Tailscale 的 v1 路径,不支持 Telegram Web iframe。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw