---
summary: "启用并保护 MCP Apps 主机桥，以呈现服务器提供的 HTML 视图"
title: "MCP 应用程序"
read_when:
  - "启用 MCP Apps 主机桥"
  - "检查应用程序的沙箱来源、侦听器端口和安全边界"
---

## <a id="mcp-apps"></a> MCP 应用程序

OpenClaw 可以渲染实现稳定的 [MCP Apps 扩展 ](https://modelcontextprotocol.io/extensions/apps) 的工具。应用程序是选择加入的，因为它们的 HTML 来自配置的 MCP 服务器。具有当前应用程序交互权限的视图可以从同一服务器请求应用程序可见的工具和资源。

启用主机桥接：

```bash
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 提供专用的公共源，并仅将该源代理到沙箱监听器：

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

沙箱源必须与 Control UI 源不同。不要在其上托管其他已认证或敏感内容。

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

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

## <a id="plugin-extensions"></a> 插件扩展

Control UI 还可以识别 [OpenAI MCP 插件 Extensions](https://developers.openai.com/plugins/build/extensions)。这些扩展了相同的 MCP Apps 主机；他们不会安装第二个插件运行时或授予对 ChatGPT 帐户的访问权限。连接插件的 MCP 服务器并使用上述设置启用应用程序。现有的服务器启用、会话工具访问和帐户权限仍然适用。

扩展让服务器贡献：

- **应用程序和对话面板：** 直接打开广告的全局或线程入口点，而不要求模型首先发现并调用其工具。每个对话都保留自己的应用程序实例。
- **Settings：** 使用本机控件呈现服务器提供的字段和组，或打开通告的设置操作。 MCP 服务器拥有保存的值；这些控件不会修补网关配置。
- **Composer 资源：** 搜索插件的文件和其他资源，并将选定的引用附加到对话中。这些与人的提及是分开的。
- **模型上下文：** 附加当前应用程序选择中的文本、图像和资源。稍后的更新将取代该应用程序的早期上下文。下一个回合会消耗附件并清除其作曲家芯片。删除项目也会更新应用程序。演示元数据不参与模型输入，应用程序提供的内容仍然是对话数据而不是系统指令。
- **文件查看器和编辑器：** 为支持的工作区文件选择广告查看器。该应用程序接收不透明资源 URI，而不是不受限制的文件系统访问。主机检查当前会话和请求者的读取、订阅和保存情况。当提供的版本不再匹配时，条件保存会报告冲突。
- **Onboarding：** 显式运行打包的安装技能。安装或发现插件不会自动运行该技能。

服务器在其正常工具描述符上通告入口点：

```json
{
  "name": "parts.library",
  "title": "Parts library",
  "inputSchema": { "type": "object", "properties": {} },
  "_meta": {
    "ui": { "resourceUri": "ui://parts/library" },
    "openai/ui": { "entrypoints": [{ "type": "global" }, { "type": "thread" }] }
  }
}
```

全局和线程入口点工具接受 `{}`。文件入口点声明带有前导点的扩展名，例如 `.stl`，并接收所选文件的名称和主机发出的资源 URI。主机向应用程序提供初始工具结果；应用程序应该呈现该结果，而不是重复打开工具调用。

应用程序资源元数据可以声明支持的和首选的显示模式。应用程序必须在使用扩展之前检查实际的主机功能：独立通道窗口并不具有连接的 Control UI 对话的所有功能。不要仅从成功的 MCP 连接推断文件、消息传递或模型上下文权限。

当应用程序要求向助手发送消息时，请查看其预览并在应用程序窗格的确认栏中选择 **Send** 或 **Cancel**。

文件保存遵循扩展协议的可选 `ifMatch` 前提条件。发送上次读取的 ETag 可防止过时的保存替换较新的编辑；省略 `ifMatch` 将执行无条件保存（最后写入者获胜）。应用程序作者在保护并发编辑时应发送 ETag。两种形式仍然需要可写读取、主机发出的文件 URI 以及当前会话和请求者权限。

本机 Codex 应用程序借用对话的现有 MCP 连接并保留其批准策略。交互式表单需要允许提示的本机策略；参见[丰富的MCP表格](/plugins/codex-harness/native-features#rich-mcp-forms)。每台服务器一次只能调用一个本机应用程序工具，且对话一次只能处于活动状态；等待它完成后再开始另一个。每个视图还强制执行四个并发请求、每分钟 120 个请求和每分钟 30 个工具调用的限制。后台预览生成与用户触发的调用消耗相同的限制。

这些扩展使用下面的现有沙箱和权限边界。服务器拥有的设置和插件数据仍属于其现有所有者。原始应用程序状态不是新的持久网关存储，重建的成绩单预览也不是运行工具的新授权。

## <a id="tool-approvals"></a> 工具认证

当App工具调用需要批准时，选择**允许一次**、**在此App打开时允许**或**拒绝**。 **允许一次** 仅批准该呼叫。 **在此应用程序打开时允许**允许同一请求者从同一当前视图再次调用确切的server/tool对，而无需其他提示。

该授权仅存在于视图的十分钟内存租约中。当租约被释放、到期或被替换时，它就结束了；重新启动或重建视图不会使其继续前进。不同的工具、视图、会话或请求者需要自己的批准。该授权永远不会更新配置或持久工具白名单，并且不批准模型驱动的调用。

当前的服务器和会话策略仍然适用，并在执行前再次检查。服务器批准模式已允许的调用不会提示。在视图存在之前进行的调用，例如打开入口点，保留 **允许一次** 和 **Deny**。

## <a id="behavior-and-security-boundaries"></a> 行为和安全边界

- 只有在启用 Apps 时，OpenClaw 才会声明 `io.modelcontextprotocol/ui` 扩展。
- 只有 `ui://` 资源且 MIME 类型精确为 `text/html;profile=mcp-app` 时才会渲染。
- UI 资源大小上限为 2 MiB，放置在专用外层源上的双 iframe 代理后面，加载到不透明的内层 App 源中，并受由资源元数据派生的 CSP 约束。
- 仅限 App 的工具（`_meta.ui.visibility: ["app"]`）不会出现在模型工具列表中。Apps 只能调用其所属服务器上对 app 可见的工具，并且这些工具还必须通过创建该视图的运行所对应的有效 OpenClaw 工具策略。
- 相同服务器资源列表和读取需要相同的当前应用程序交互权限。 OpenClaw 在上游资源工作后重新检查，因此在运行中撤销的授权无法将资源数据返回给应用程序。
- 基于源绑定的 App 权限（如摄像头、麦克风和地理位置）不会授予，因为内层 App 文档使用不透明源以实现跨 App 隔离。
- App HTML、完整的工具参数和原始结果存在于有限的十分钟内存视图租用中，不会写入磁盘或复制到转录预览元数据中。转录本仅存储与原始工具调用 ID 关联的有界 server/tool/resource 描述符。网关重新启动后，Control UI 可以根据经过身份验证的会话记录验证该描述符，并重新获取 `ui://` 文档以进行显示；在重新运行建立当前的应用程序交互权限之前，重建的视图无法调用工具或使用资源桥。 Control UI 使用恢复消息标记非活动视图。入口点面板提供 **Relaunch**；文字记录预览要求您发送消息以再次交互。
- 在频道对话中，某一轮中最新成功的 App 视图会在最终的助手回复中增加一个 **打开应用** 风格的动作。Telegram 私信使用原生 Mini App 按钮；Slack 和 Discord 将相同的可移植动作渲染为链接。其他频道则保留原始回复文本，并附加一个可理解的 HTTPS 链接。
- 仅当 Gateway Tailscale 曝光已准备好已发布的 HTTPS 源时， 通道启动链接才可用。 `gateway.tailscale.mode: "serve"` 只能从尾网到达；可通过公共互联网访问经过密码验证的 `"funnel"`。针对普通网关侦听器的外部托管漏斗路由必须迁移到托管 `"funnel"` 模式，然后 OpenClaw 才能发布可通过 Internet 访问的源。请参见 [Tailscale](/gateway/tailscale)。
- 启动票据是不透明的，仅在生成最终频道回复时铸造，并在最多两分钟后或底层视图租约到期时失效，以先发生者为准。URL 不包含 Gateway bearer 凭证、会话密钥、视图元数据、App HTML、工具输入或工具结果。
- 独立应用程序窗口允许 30 秒加载视图。每个服务器的 `requestTimeoutMs` 适用于单独的 MCP 请求，而不适用于可能在调用工具之前刷新目录的完整应用程序操作。应用程序请求取消或关闭窗口会中止其浏览器请求并传播到托管 MCP 运行时；其他调用者仍然可以完成共享目录刷新。取消无法撤消服务器已执行的副作用。
- Tool 请求在批准后启动，并保留其配置的活动工作超时，每次调用的待处理人工输入问题最多可共享 10 分钟的时间，并且每个问题本身的到期时间仍然有效。
- 当应用程序请求拆卸时，现有调用和授权清理调用可以完成，直到应用程序确认关闭或一秒宽限期到期。关闭或离开窗口会立即取消。
- 返回到从浏览器的 back/forward 缓存恢复的独立应用程序会重新加载并重新验证视图，而不是恢复其已断开的连接。这会重置临时应用程序状态，并且不会自动重试中断的操作。如果启动票已过期，请打开新的应用程序链接。
- 如果没有可用的已发布源或票据容量，或者视图/票据已过期，或者传输无法渲染原生控件，则保留原始助手文本。Control UI 会保留其现有的内联 App 画布，并且不会收到重复的启动动作。
- 在桥接启用时，`openclaw security audit` 会发出警告。若不需要，请使用 `openclaw config set mcp.apps.enabled false --strict-json` 将其禁用。