MCP 应用

MCP 应用¶

OpenClaw 可以呈现实现稳定的 MCP Apps 扩展的工具。由于应用（Apps）的 HTML 来自所配置的 MCP 服务器，因此它们是选择加入的。拥有当前 App 交互权限的视图可以向同一服务器请求应用可见的工具和资源。

启用主机桥接：

openclaw config set mcp.apps.enabled true --strict-json

更改此设置后请重启 Gateway。启用后，OpenClaw 会在 Gateway 端口加一（默认 Gateway 为 18790）启动一个仅限沙箱的 HTTP(S) 监听器。Control UI 从该独立源加载 Apps；该监听器绝不提供 Control UI、经过身份验证的 Gateway 路由或用户数据。

直接连接 Gateway 需要访问这两个端口。如果反向代理或 TLS 终止器暴露了 Control UI，请为 Apps 提供专用的公共源，并仅将该源代理到沙箱监听器：

{
  mcp: {
    apps: {
      enabled: true,
      sandboxOrigin: "https://mcp-apps.example.com",
      sandboxPort: 18790,
    },
  },
}

沙箱源必须与 Control UI 源不同。不要在其上托管其他经过身份验证或敏感的内容。

例如，官方 basic React 演示可以配置为：

{
  mcp: {
    apps: { enabled: true },
    servers: {
      "basic-react": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],
      },
    },
  },
}

行为和安全性边界：

OpenClaw 仅在启用应用时通告 io.modelcontextprotocol/ui 扩展。
只有具有确切 text/html;profile=mcp-app MIME 类型的 ui:// 资源才会渲染。
UI 资源上限为 2 MiB，放置在专用外部源上的双 iframe 代理后面，加载到不透明的内部 App 源中，并受从资源元数据派生的 CSP 约束。
仅应用可见的工具（_meta.ui.visibility: ["app"]）不会出现在模型工具列表中。应用只能调用其所属服务器上应用可见的工具，且这些工具还必须通过创建该视图的那次运行的 OpenClaw 有效工具策略。
同一服务器上的资源列出和读取需要相同的当前 App 交互权限。OpenClaw 会在上游资源操作后重新检查，因此运行中被撤销的授权无法将资源数据返回给应用。
当内部 App 文档使用不透明源以实现跨应用隔离时，不会授予绑定源的应用权限（如摄像头、麦克风和地理位置）。
App HTML、完整的工具参数和原始结果保存在限时十分钟的内存视图租约中，不会写入磁盘，也不会复制到会话记录预览元数据中。会话记录仅存储与原始工具调用 ID 关联的受限服务器/工具/资源描述符。Gateway 重启后，Control UI 可以对照经过身份验证的会话记录验证该描述符，并重新获取 ui:// 文档进行显示；重建的视图无法调用工具或使用资源桥接，直到新的运行建立当前的 App 交互权限。
在渠道对话中，一个轮次中最新的成功应用视图会向最终助手回复添加一个 Open App 风格的操作。Telegram 私聊使用原生 Mini App 按钮；Slack 和 Discord 以链接形式呈现相同的可移植操作。其他渠道保留原始回复文本，并附加一个可理解的 HTTPS 链接。
渠道启动链接仅在 Gateway Tailscale 暴露已准备一个已发布的 HTTPS 源时才可用。gateway.tailscale.mode: "serve" 仅可从 tailnet 访问；密码认证的 "funnel" 可从公共互联网访问。针对普通 Gateway 监听器的外部管理 Funnel 路由必须迁移到受管理的 "funnel" 模式，OpenClaw 才能发布可通过互联网访问的源。参见 Tailscale。
启动票据是不透明的，仅在生成最终渠道回复时生成，并且最多在两分钟后或底层视图租约到期时（以先到者为准）过期。该 URL 不包含 Gateway Bearer 凭据、会话密钥、视图元数据、App HTML、工具输入或工具结果。
独立 App 窗口允许 30 秒来加载视图。每个服务器的 requestTimeoutMs 适用于单个 MCP 请求，而不是适用于可能在调用工具之前刷新目录的完整 App 操作。App 请求取消或关闭窗口会中止其浏览器请求，并传播到受管理的 MCP 运行时；其他调用者仍可完成共享目录刷新。取消无法撤销服务器已执行的副作用。
当 App 请求拆除时，现有调用和经授权的清理调用可以完成，直到 App 确认关闭或一秒钟宽限期到期。关闭窗口或从窗口导航离开会立即取消。
从浏览器的后退/前进缓存中恢复的独立 App 在返回时会重新加载并重新验证视图，而不是恢复其已拆除的连接。这会重置瞬态 App 状态，并且不会自动重试被中断的操作。如果启动票据已过期，请打开新的 App 链接。
如果没有可用的已发布源或票据容量，视图或票据已过期，或者传输方式无法渲染原生控件，则原始助手文本仍然可用。Control UI 保留其现有的内联 App 画布，并且不会收到重复的启动操作。
启用桥接时，openclaw security audit 会发出警告。当不需要时，可使用 openclaw config set mcp.apps.enabled false --strict-json 禁用它。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw