> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 安全模型

> Mini App 的运行权限，以及宿主对端口、凭据和 Agent 接口的限制。

## Mini App 运行时

Mini App 的 Node 代码以当前用户身份在本机运行，和本地插件、MCP 服务器一样，可以读写用户有权限访问的文件、启动程序、发起网络请求。请只安装来源可信的 Mini App，安装前先阅读它的 README，确认它会访问哪些数据。

宿主没有使用 seccomp、seatbelt 等操作系统沙箱，主要是考虑到跨平台支持、调试和第三方依赖的成本。相应地，宿主严格限制向 Mini App 开放的能力，防止第三方 Mini App 投毒，也防止 Agent 因幻觉生成有害代码。

## 宿主的安全边界

| 边界 | 实现方式 |
| - | - |
| 只对本机可见 | 每个 Mini App 在独立进程中运行，只监听 `127.0.0.1` 上分配的端口 |
| 端口访问 | 每次运行生成一个凭据，只有 Mini App 页面和托管 MCP 客户端能使用；其他本地进程、其他浏览器标签和 DNS rebinding 请求都会收到 `401` |
| 插件不接触凭证 | 第三方服务通过 Host Connector 调用，使用用户在 MiniMax Code 中授权的账号；Mini App 不保存凭证 |
| 页面不接触凭证 | 宿主凭据、内部端口、运行 ID 和 Connector 工具引用都不会暴露给页面 |
| 显式授权 | `hostConnectorAccess` 列出允许使用的 provider；`agentAccess` 分别声明 `session.run` 和 `session.read`；`toolAccess`、`deviceAccess` 按需声明，需要声明的能力未声明时默认禁止 |
| 权限开关 | 用户可在插件详情逐项关闭已声明的能力，宿主在调用时重新检查，无需重启 Mini App |
| 不可变的运行副本 | 进程只从宿主复制并重新校验过的副本启动，发布后再修改源文件不会生效 |
| 窗口能力上限 | 置顶和鼠标穿透必须在 manifest 中声明，才能在运行时开启；切换窗口模式需要由用户操作触发；窗口必须位于某块屏幕的可见范围内 |

## 端口与凭据

Mini App 只监听本机地址，但本机的其他进程和浏览器页面仍可能访问它的端口，包括利用 DNS rebinding 的恶意网页。因此，宿主会在端口上校验调用方身份：

![凭据流向](https://mintcdn.com/agent-cn/cVBevhAJXWhxEBzo/images/miniapp/credentials-zh.svg?fit=max\&auto=format\&n=cVBevhAJXWhxEBzo\&q=85\&s=73d7caf3340e9be463ae97673597df24)

凭据只在宿主、请求守卫和 Agent 的 MCP 客户端之间传递，页面、插件代码和外部调用方都无法获取。

* **每次运行生成一个凭据。**宿主每次启动进程时生成一个 32 字节的随机凭据，交给子进程里的请求守卫、宿主主进程和 Agent 的 MCP 客户端。页面不持有凭据。
* **守卫在插件代码之前加载。**子进程通过 IPC 接收初始化消息，缺少或多出字段都会导致启动失败；随后在 Node 内置 HTTP 服务的请求分发入口装上守卫，最后才加载插件代码。因此，插件创建的任何 `node:http` 服务收到的请求都已经过守卫检查。
* **校验 Host 和凭据。**`Host` 必须精确等于 `127.0.0.1:端口`，用于防范 DNS rebinding；凭据使用常量时间比对。WebSocket 升级和 CONNECT 请求也做同样的检查。验证通过后，凭据会从请求头中移除，不会传给插件的业务代码。
* **页面请求的凭据由宿主添加。**页面发出请求时，宿主主进程先核对请求的真实来源，再添加请求头；页面自行设置的同名请求头会被覆盖。Agent 访问 MCP 端点时，由 MCP 客户端在请求头中携带凭据，凭据不会写入对外可见的配置。

请求守卫和插件代码运行在同一个进程中，只能阻止外部调用方冒充宿主，无法隔离恶意插件。

## 声明与权限开关

Connector provider、Agent 的 `session.run` 和 `session.read`、`toolAccess` 的 `call`，以及麦克风、摄像头和系统通知各有自己的开关。已声明的权限默认开启，用户可在插件详情随时关闭；声明保持不变，接口对象也仍然存在，代码需要在调用处处理拒绝。`context.tool` 的每次调用还会按用户给 Agent 设置的工具权限规则判定，需要确认时由宿主询问。

关闭 Connector 或工具调用权限后，新调用被拒绝；关闭 `session.run` 会停止这个 Mini App 正在运行的 Agent 回合，关闭 `session.read` 会结束它的会话观察订阅。重新开启后可以再发起调用。

### 页面设备权限

麦克风需要在 manifest 的 `deviceAccess` 中声明 `microphone`，并保持权限开关开启。关闭后，下一次 `getUserMedia` 和 `speech.transcribe` 会被拒绝；页面已经取得的录音流不会被宿主强制停止，页面需自行停止 track。

摄像头和系统通知从 MiniMax Code v3.1.9 起正式提供，分别通过 `camera` 和 `notifications` 声明。用户可独立关闭这两项权限；关闭摄像头权限会拒绝新的采集请求，已经取得的视频流仍由页面停止。同时请求音视频需要麦克风与摄像头两项均已声明并开启，任一项关闭都会拒绝整个请求。

关闭通知权限会拒绝新的通知请求；通知能否显示还受操作系统的通知权限和设置影响。通知点击回调只能由仍在运行的创建页面处理，页面关闭或重载后，旧通知不能重新打开 Mini App。声明、版本要求和用法见[页面设备 API](https://agent.minimaxi.com/docs/miniapp/authors/client-api.md#devices)。

定位、剪贴板读取、屏幕捕获等未开放的页面系统权限默认拒绝。这些权限限制只约束受宿主管理的页面，Node 进程仍未受到操作系统沙箱隔离。

## Agent 接口的限制

* `session.run` 允许 Mini App 新建和续用自己创建的 Agent 会话、处理工具审批和问卷、查询模型和 Agent。会话归属由宿主记录；这项权限不允许控制用户的其他会话。
* `session.read` 独立授权列出、读取和观察用户的可见会话，包括会话详情和回合最终回复；它不授予运行回合、审批或回答问卷的能力。两项权限不会互相包含。
* `message.append` 只能经确认修改未发送的输入框草稿，不能修改已发送的消息，也不会替用户发送。
* 这些限制只约束宿主接口，Node 进程本身没有操作系统级隔离。

## 用户确认

* `message.append` 每次都需要用户确认，并由用户自行发送。宿主按 Electron 报告的真实页面核对调用方身份。
* Agent 审批只有「允许一次」和「拒绝」两个选项，Mini App 不能修改用户的全局权限规则；无人能回答的审批会直接被拒绝，见[谁能回答审批](https://agent.minimaxi.com/docs/miniapp/authors/agent.md#agent-interaction)。
* `context.tool` 使用宿主自己的工具审批框，可由用户选择「允许一次」「始终允许」或「拒绝」；只有用户在宿主确认框中选择「始终允许」才会写入全局规则，Mini App 不能代答，见[统一工具入口](https://agent.minimaxi.com/docs/miniapp/authors/data.md#tools)。
* 读取和观察用户会话需要单独声明并开启 `session.read`；`message.append` 不授予读取权限，也不能修改已发送的消息。

## 已知限制

* 端口鉴权只防范其他本地进程和浏览器标签，不防范恶意插件本身。
* 宿主只管理入口 Node 进程。插件启动的子进程需要在 `dispose` 中自行清理。
* 服务重启后，已打开的标签会收到 `401`，刷新或重新打开后恢复。