跳转至

MCP 应用

MCP 应用

OpenClaw 可以渲染实现稳定版 MCP Apps 扩展 的工具。这些应用是选择启用的,因为其 HTML 来自已配置的 MCP 服务器。具有当前应用交互权限的视图可以请求同一服务器上应用可见的工具和资源。

启用宿主桥接:

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

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

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

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

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

例如,官方的基础 React 演示可以配置为:

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

插件扩展

Control UI 还能识别 OpenAI MCP 插件扩展。这些扩展依托同一个 MCP Apps 宿主;它们不会安装第二个插件运行时,也不会授予对 ChatGPT 账户的访问权限。连接插件的 MCP 服务器,并使用上述设置启用应用。现有的服务器启用状态、会话工具访问权限和账户权限仍然适用。

扩展让服务器可以提供以下内容:

  • 应用和对话面板: 直接打开一个已声明的全局或线程入口点,无需先让模型发现并调用其工具。每个对话都保留自己的应用实例。
  • 设置: 使用原生控件渲染服务器提供的字段和分组,或打开一个已声明的设置操作。保存的值归 MCP 服务器所有;这些控件不会修改 Gateway 配置。
  • Composer 资源: 搜索插件文件和其他资源,并将所选引用附加到对话中。这与提及人员不同。
  • 模型上下文: 附加当前应用所选内容中的文本、图像和资源。后续更新会替换该应用之前提供的上下文。下一轮对话会消费这些附件并清除其 Composer 标签。移除某个项目也会更新该应用。展示元数据不会进入模型输入,应用提供的内容仍是对话数据,而非系统指令。
  • 文件查看器和编辑器: 为受支持的工作区文件选择一个已声明的查看器。应用收到的是一个不透明的资源 URI,而非不受限制的文件系统访问权限。宿主会在读取、订阅和保存时检查当前会话和请求者。有条件保存时,如果提供的版本不再匹配,会报告冲突。
  • 上手引导: 显式运行一个打包好的设置技能。安装或发现插件不会自动运行该技能。

服务器在其常规工具描述符上声明入口点:

{
  "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 连接就推断文件、消息传递或模型上下文权限。

当应用要求向助手发送消息时,请检查其预览,并在应用窗格的确认栏中选择发送或取消。

文件保存遵循扩展协议的可选 ifMatch 前置条件。发送上次读取时的 ETag 可防止过期保存覆盖较新的编辑;省略 ifMatch 则执行无条件保存(最后写入者胜出)。应用作者在保护并发编辑时应发送 ETag。两种形式仍需要有写权限的读取、宿主颁发的文件 URI,以及当前会话和请求者权限。

原生 Codex 应用借用对话现有的 MCP 连接,并保留其审批策略。交互式表单需要允许提示的原生策略;请参阅 丰富的 MCP 表单。每个服务器和对话每次只能有一个原生应用工具调用处于活动状态;请等待它完成后再开始另一个。每个视图还强制执行四个并发请求、每分钟 120 个请求和每分钟 30 个工具调用的限制。后台预览生成与用户触发的调用消耗相同的限制。

这些扩展使用下文所述的现有沙箱和权限边界。服务器拥有的设置和插件数据仍由其现有所有者持有。原始应用状态并不是 Gateway 新的持久化存储,重建的对话记录预览也不是重新授予运行工具的权限。

工具审批

当某个应用工具调用需要审批时,选择允许一次、在此应用打开期间允许或拒绝。允许一次只批准该次调用。在此应用打开期间允许允许同一请求者从同一当前视图中再次调用完全相同的服务器/工具对,而无需再次提示。

该授权仅存在于视图的十分钟内存租约中。当租约被释放、过期或被替换时,它会结束;重新启动或重建视图不会延续它。不同的工具、视图、会话或请求方需要各自的批准。该授权从不更新配置或持久化工具允许列表,也不会批准模型驱动的调用。

当前服务器和会话策略仍然适用,并会在执行前再次检查。服务器审批模式已允许的调用不会提示。在视图存在之前发起的调用(例如打开入口点)会保留 Allow once 和 Deny。

行为与安全边界

  • OpenClaw 仅在启用 Apps 时通告 io.modelcontextprotocol/ui 扩展。
  • 只有具有精确 text/html;profile=mcp-app MIME 类型的 ui:// 资源会渲染。
  • UI 资源上限为 2 MiB,放置在专用外层源上的双层 iframe 代理之后,加载到不透明内部 App 源中,并受由资源元数据派生的 CSP 约束。
  • 仅限 App 的工具(_meta.ui.visibility: ["app"])不会出现在模型工具列表中。Apps 只能调用其所属服务器上对 App 可见且同时通过创建该视图的运行的生效 OpenClaw 工具策略的工具。
  • 同服务器资源列表和读取需要相同的当前 App 交互权限。OpenClaw 会在上游资源操作后重新检查,因此在途撤销的授权无法向 App 返回资源数据。
  • 当内部 App 文档使用不透明源以实现跨 App 隔离时,不会授予与源绑定的 App 权限,例如摄像头、麦克风和地理位置。
  • App HTML、完整工具参数和原始结果保存在有界的十分钟内存视图租约中,不会写入磁盘或复制到转录预览元数据。转录仅存储一个有界的服务器/工具/资源描述符,并关联到原始工具调用 ID。Gateway 重启后,Control UI 可以针对已认证会话转录验证该描述符,并重新获取 ui:// 文档以显示;重建的视图无法调用工具或使用资源桥,直到新的运行建立当前 App 交互权限。Control UI 会使用恢复消息标记非活动视图。入口点面板提供 Relaunch;转录预览会提示你发送一条消息以再次交互。
  • 在频道对话中,一轮中最近一次成功的 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