本地导入

把插件 ZIP 导入 Coskey 本地插件市场，并在 ChatGPT.app 中安装、启用或升级。

拿到插件发布方提供的 ZIP 后，可以先把它导入 Coskey 的本地插件市场，再在 ChatGPT.app 中 完成安装或升级。这样不用等插件上架远端索引，也不会跳过 ChatGPT.app 的安装确认。

← 返回插件手册

插件市场中的本地导入入口

1. 先分清“导入”和“安装”

本地导入只是把 ZIP 校验并放进本地市场，不等于已经装进 ChatGPT.app：

动作 在哪里完成 结果
本地导入 Coskey「插件」页 校验 ZIP，放入本地集市；插件卡标「本地」
安装 / 启用 / 升级 ChatGPT.app「插件」页 把插件复制到应用缓存并写入启用状态

因此，在 Coskey 看到「未安装」是正常状态。刷新集市也不会删掉已经导入的本地插件。

2. 准备插件 ZIP

插件包是 .zip 文件，根目录应直接包含 plugin.json：

my-plugin.zip
├── plugin.json
├── assets/
│   └── logo.svg          # 可选：插件展示图标
├── skills/
│   └── example-skill/
│       └── SKILL.md
├── mcp.json              # 可选
└── server/               # 使用本地 MCP 时可选

也可以只用一层同名目录包裹，例如 my-plugin/plugin.json。不要同时把一部分文件放在根目录、 另一部分放进子目录；Coskey 最多剥掉一层包裹目录。

导入前至少确认：

  • 顶层或唯一包裹层内有根 plugin.json，且文件是 UTF-8 JSON；
  • name 与 semver 格式的 version 都存在，且 name 不是保留的内置插件名 coskey-tools；
  • 至少包含一个 skills/<技能名>/SKILL.md，或一份合法的 mcp.json；
  • ZIP 内没有符号链接、绝对路径、.. 路径、反斜杠路径、大小写重复路径或 Windows 保留名；
  • 源文件是非符号链接的普通 .zip 文件。

当前导入限制：

项目 上限
ZIP 文件大小 2 GiB
ZIP 条目数 409,600
解压后总大小 10 GiB
plugin.json 大小 1 MiB

如果 ZIP 是自行打包的，可以先检查前几层：

unzip -Z1 my-plugin.zip | sed -n '1,20p'

第一行附近应直接出现 plugin.json，或唯一一个包含它的包裹目录。

3. 导入 ZIP

  1. 打开 Coskey → 插件；
  2. 在插件卡列表末尾点击 「本地导入」；
  3. 选择准备好的 .zip 文件。

Coskey 会先检查文件类型、大小、路径与清单，通过后才写入本地集市；失败不会破坏已有版本。 导入成功会出现绿色提示，并在列表中增加一张带「本地」标签的插件卡：

导入完成后的本地插件卡

如果插件带展示图标，把它放在 ZIP 内，并用 extensions.com.openai.interface.logo 指向包内相对路径，例如 ./assets/local-example-logo.svg。不要直接写 ~/Downloads/... 这类本机路径；导入后 ChatGPT.app 会从插件清单读取并显示该图标。

卡片上的三个信息最值得确认：

信息 含义
版本 当前导入到本地市场的版本
「本地」 来源为 local-import，刷新集市仍会保留
未安装 / 已启用 ChatGPT.app 中是否已经安装并启用

点击卡片可查看展示名、插件 id、集市路径、技能、MCP 能力与安装状态。含本地 MCP 的插件会明确 提示它会在本机执行命令；安装前请确认来源可信，并核对 MCP 名称。

4. 在 ChatGPT.app 安装或启用

  1. 点击 Coskey 右上角的 「打开 ChatGPT.app」；
  2. 打开 ChatGPT.app 的 插件（Plugins）；
  3. 选择 Coskey 插件市场；
  4. 找到刚导入的插件，点击安装；已安装的版本则重新安装或启用；
  5. 回到 Coskey 的插件页，必要时点 「刷新集市」 更新安装状态。

插件页上方是「已安装」区域，Coskey 本地市场的条目列在下方的「Coskey 插件市场」。每张卡 右侧的「+」就是安装入口：

ChatGPT.app 插件页：已安装区域与 Coskey 插件市场

点开卡片可以查看插件详情：展示名、作者、说明，以及技能和「信息」中的开发者、类别、版本、网站。 含本地 MCP 的插件还会多出一个「MCP 服务器」区域，安装前先核对其中的名称与来源。详情页右上角的 「安装插件」与列表卡上的「+」作用相同：

本地导入插件的详情：技能与版本信息

这两张截图来自手册的隔离实例，图中插件是用于演示的「本地示例」；你的列表与详情以实际安装或 导入的插件为准。

Coskey 不会代写 ChatGPT.app 的插件缓存，也不会绕过应用内的安装确认。看到「已安装已启用」 后，插件才会出现在 ChatGPT.app 的可用插件中。

5. 更新与回滚

更新一个本地插件时：

  1. 先导入同名插件的新版本 ZIP；
  2. 新版本会成为本地市场的当前版本；
  3. 再回到 ChatGPT.app 重新安装或升级该插件；
  4. 在 Coskey 插件详情中确认应用缓存版本已经跟上。

导入新版不会自动替换 ChatGPT.app 里的旧缓存。若详情页显示上一代版本，可先回滚本地市场 版本，再到 ChatGPT.app 重新安装；应用中的插件仍以插件页最后一次安装的版本为准。

6. 常见问题

现象 处理
选择 ZIP 后没有导入 确认文件扩展名是 .zip、源文件不是符号链接；在文件选择框点「取消」不会产生任何改动
提示找不到 plugin.json 把 plugin.json 放到 ZIP 根目录，或只保留一层包含它的同名目录
提示名称或版本不合法 name 不能是 coskey-tools；version 必须是 1.0.0 这类 semver
提示没有技能或 MCP 至少加入 skills/<技能名>/SKILL.md 或合法的 mcp.json
提示 ZIP 条目不合法 删除符号链接、绝对路径、.. 路径、反斜杠路径和重复路径后重新打包
导入后显示「未安装」 正常；导入只更新本地市场，仍需在 ChatGPT.app 插件页安装
刷新集市后「本地」插件还在 预期行为；本地导入不会被远端索引刷新删除
ChatGPT.app 里找不到插件 重新打开 ChatGPT.app，确认选择的是「Coskey 插件市场」；仍不可见时在 Coskey 插件页运行「诊断」
更新后应用仍用旧版 在 ChatGPT.app 插件页重新安装或升级，不要只刷新 Coskey 集市

插件页打不开、插件集市缺失或界面语言异常时，见 ChatGPT.app 检测与个性化。

7. 安全边界

本地导入会检查包结构和路径，但这不等于审计插件代码。尤其是包含本地 MCP 的包，启用后可能 在电脑上执行命令；只导入可信来源，并在安装前查看插件详情中的权限信息。

相关：ChatGPT.app 检测与个性化、 常见问题。

上一篇插件手册下一篇远程插件