使用文档日常工作
CAGE · 使用手册

插件与插件市场

通过开放插件市场为环境里的 Claude 扩展 MCP 能力、定制 Cage 工作台页面,并管理主机调用的授权与安全边界。

本页内容

设计理念:插件 = MCP + 扩展

Cage 的核心路线是把有风险的运行外壳(Claude Code、Claude Desktop 与内置浏览器)关在轻量化的本地 Debian 13 隔离环境中,再通过标准 MCP 插件,让 Claude 安全、受控地使用本机能力。相比直接暴露主机 SSH,每一次越出环境的调用都有清晰的权限声明与用户授权。

在 Cage 中,插件 = MCP + 扩展,分别承担两项职责,一个插件可以同时提供两者:

形态 作用 对应清单字段
给 Claude 的能力(MCP) 提供标准输入输出的 MCP 工具,让环境里的 Claude 能够操作本机桌面、处理本地文档、调用本机软件或读写环境内服务 contributes.mcpServers
定制 Cage(扩展) 在 Cage 侧栏新增独立的沙箱页面,把状态面板、控制台或工作流界面直接融进工作台 contributes.views

通过开放的插件市场 cage-plugins,开源社区可以持续贡献各类 MCP 工具与工作台扩展,而不必挤进 Cage 主仓库的 Issue 列表;Cage 核心团队也能专注于隔离环境、网络与工作台本身的稳定性。

主机插件与环境内插件

按运行位置不同,插件分为两种 kind:

类型 运行位置 适用场景 授权方式
主机插件(host) 你的电脑(macOS / Windows / Linux) 需要本机能力:屏幕与键鼠控制、Office 文档读写、Blender 等桌面应用联动、在共享项目目录中运行本机命令 运行于你的用户权限,不受隔离保护;默认逐次弹窗确认,可按需开启「始终允许」
环境内插件(guest) Cage 内的 Debian 13 环境 只在环境内工作:查看系统状态、操作环境内文件、控制环境内 Chromium 浏览器或内部服务 未声明越出环境权限时无需弹窗确认

说明:本页介绍的是 Cage 侧栏的「插件」与开放插件市场(cage-plugins)。如果你在查找多账号之间如何共用 Claude Code 自己的技能、钩子与插件,请见多账号与额度。

从插件市场安装与管理

  1. 在工作台左侧栏打开 插件,先开启总开关。
  2. 切换到 插件市场,按分类(桌面控制、开发、系统与状态、网络、文件、效率、示例)浏览或搜索插件。
  3. 打开插件详情页,查看功能说明、声明的权限以及基于的上游开源项目信息,点击安装即可。

市场索引与压缩包来自 cage-plugins:

  • 校验与网络:应用读取市场索引、下载压缩包并核对 SHA-256,同时检查压缩包大小(解压后不超过 100 MiB、2000 个文件)以及索引权限与插件清单完全一致。读取和下载走电脑自己的网络,遵循系统代理设置。
  • 上游开源依赖:基于开源项目的插件会在详情页「上游项目」展示项目名、版本、许可证和地址。部分插件首次启动时通过 npx 或 uvx 拉取上游固定版本,需先在本机安装 Node.js 或 uv;主机插件启动时会使用与终端相同的 PATH。
  • 手动安装与调试:可将插件目录直接放入配置目录的 plugins/ 下(默认 ~/.claude-cage/plugins/<插件名>/),再在插件页点击 重新加载。环境内插件的文件会在启动与重新加载时同步到环境内的 ~/.local/share/plugins/<插件名>/。
  • 停用与卸载:每个插件(包括内置的命令插件)都可以单独停用,停用后停止运行且不向 Claude 暴露工具,文件留在原处。卸载或更新插件时,旧目录会移到配置目录的 plugins-removed/ 下保留,不会直接删除。

主机授权与安全边界

主机插件以你的系统用户权限运行在电脑上,是否放行由你掌控:

  • 显式确认:调用前弹出系统确认窗口,展示插件名、工具名和参数。可以选择拒绝、只允许这一次,或勾选「始终允许」。确认窗口 2 分钟未响应时自动按拒绝处理。
  • 持久化授权与撤销:「始终允许」按插件记录,覆盖该插件的全部工具(内置命令插件按项目目录记录),重启后依然有效。可在插件详情页的 授权与权限 中随时查看、授予或撤销;撤销后立即恢复逐次确认。从市场安装时也可勾选「安装后始终允许」。
  • 权限变更保护:插件更新后,只要声明了你此前未同意的新权限,原有授权会自动失效并重新询问。通过插件页卸载插件时,授权记录会一并清除。
  • 超长与不可见参数拦截:参数超过 4000 字节,或包含控制字符、不可见格式字符时,即使已勾选「始终允许」也会直接拒绝,防止确认窗口无法完整展示调用内容。较长内容应先写入文件,再传递文件路径。
  • 页面与模型共用授权:插件沙箱页面调用工具与 Claude 调用工具共享同一套授权;沙箱页面本身无法联网,也拿不到工作台凭据。
  • 跨平台提示:
    • Windows:系统确认窗口提供允许和拒绝两个按钮,「始终允许」需在插件详情页的「授权与权限」中设置(内置命令插件可按已打开的项目分别授权)。
    • Linux:弹出系统确认窗口依赖 zenity 或 kdialog;两者均未安装时,需要确认的主机调用一律拒绝。
  • 个人数据保留:授权记录保存在配置目录的 host-grants.json 中,属于个人数据,升级与重装 Cage 时保留。

常见插件示例

可以在官网插件市场在线浏览全部插件、权限声明与 SHA-256 校验值,或在 cage-plugins 仓库查看源码。代表性插件包括:

  • desktop-control(主机插件):查看屏幕并控制本机键鼠,声明 screen 和 input 权限。
  • blender(主机插件):连接并操作本机正在运行的 Blender(基于 ahujasid/blender-mcp)。
  • local-preview(主机插件):打开本机回环地址的开发预览页并读回标签页标题与地址。
  • excel-workbooks / word-documents / powerpoint-slides(环境内插件):无需安装 Office 即可读写表格、文档与演示文稿。
  • documents-to-markdown(环境内插件):将 PDF、Office、EPUB 与 HTML 文档解析为整洁 Markdown。
  • browser(环境内插件):控制环境内的 Chromium 浏览网页(基于 microsoft/playwright-mcp)。
  • system-status(环境内插件):同时提供 MCP 工具与自定义侧栏页面,展示环境处理器、内存与磁盘状态。
  • clock(主机插件):最小示例插件,适合作为开发模板。

开发与上架自己的插件

任何能读写标准输入输出的程序都可以写成 Cage 的 MCP 插件,任何静态 HTML/JS/CSS 页面都可以封装成工作台扩展视图。

  • 完整的清单格式(plugin.json)、权限列表、沙箱页面 JSON-RPC 协议、工具命名规则(不向模型暴露产品与运行环境名称)以及本地调试方法,见插件开发规范。
  • 打包脚本、审核要求与提交流程见 cage-plugins。欢迎把你的 MCP 工具和 Cage 扩展页面直接贡献到插件市场。

没有解决你的问题?附上版本、系统与错误原文,帮助我们定位。

向答疑助手提问 →反馈问题 ↗查看文档源码 ↗