---
title: "marketplace 的 source.path 相对仓根或家目录，不是 json 所在文件夹"
summary: "个人清单里 ./plugins/foo 解析到 ~/plugins/foo，不是 ~/.agents/plugins/plugins/foo。必须以 ./ 开头，并写在 marketplace 根内。"
category: skills
level: intermediate
surfaces: [cli, app]
tags: ["plugins", "marketplace", "source.path"]
canonical: /tips/marketplace-source-path-root/
---

# marketplace 的 source.path 相对仓根或家目录，不是 json 所在文件夹

个人清单里 ./plugins/foo 解析到 ~/plugins/foo，不是 ~/.agents/plugins/plugins/foo。必须以 ./ 开头，并写在 marketplace 根内。

手写 `marketplace.json` 时，`source.path` 不是相对这份 json 所在的 `.agents/plugins/`，而是相对 **marketplace 根**：

| 清单位置 | marketplace 根 | `./plugins/my-plugin` 实际落到 |
| --- | --- | --- |
| `~/.agents/plugins/marketplace.json` | 家目录 `~` | `~/plugins/my-plugin` |
| 仓库 `.agents/plugins/marketplace.json` | 仓库根 | 仓库根下的 `plugins/my-plugin` |

这是最常见的踩坑：把插件拷进 `~/.agents/plugins/plugins/my-plugin`，清单里写 `./plugins/my-plugin`，桌面和 CLI 都找不到。官方 plugin-creator 规范写明：个人清单里的 `./plugins/foo` 解析到 `~/plugins/foo`。

个人机两种都能用，选一种并让路径对上：

```bash
mkdir -p ~/plugins/my-plugin ~/.agents/plugins
# 把插件目录拷到 ~/plugins/my-plugin（里面要有 plugin.json 或 .codex-plugin/plugin.json）
```

`~/.agents/plugins/marketplace.json`：

```json
{
  "name": "personal",
  "interface": {
    "displayName": "My plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
```

官方打包页另一种个人布局是插件放 `~/.codex/plugins/my-plugin`，对应 `source.path` 写成 `"./.codex/plugins/my-plugin"`。两种都合法，因为都相对家目录；不要混用。

本地条目也可以把 `source` 写成字符串 `"./plugins/my-plugin"`。必须以 `./` 开头，留在 marketplace 根内，不能写 `../`。插件就在仓根（仓本身就是一份插件）时，现行代码允许 `"."` 或 `"./"`。空路径、不带 `./`、带 `..` 的路径会被拒。

每条还必须有 `policy.installation`（`AVAILABLE` / `INSTALLED_BY_DEFAULT` / `NOT_AVAILABLE`）、`policy.authentication`（`ON_INSTALL` / `ON_USE`）和 `category`。

Git 源不要抄成本地 path。插件在仓根用 `"source": "url"`；在子目录用 `"source": "git-subdir"` 再给 `path` 和 `ref` / `sha`。某一条解析失败时 **跳过该插件**，整份 marketplace 还在。npm 源是 `"source": "npm"` 加 `package`，本机要有 `npm`，安装时不跑 lifecycle 脚本。

`codex plugin marketplace add` 的 `--sparse` 是 Git clone 的稀疏检出路径，相对被 clone 的仓库根，**不是** 这份 json 里的 `source.path`。本地 marketplace 把含 `.agents/plugins/marketplace.json` 的根目录交给 `marketplace add .`，不要把 json 文件路径当根。

个人清单默认就会被扫到。改完先核对解析根，再装：

```bash
codex plugin marketplace list --json
codex plugin add my-plugin@personal
codex plugin list --json
```

ChatGPT 桌面改本地 `marketplace.json` 后仍要重启应用。CLI 0.154 起 `plugin add` 后先看当前会话的 `/plugins`。

## 来源

- [OpenAI · Package your plugin](https://learn.chatgpt.com/plugins/build/plugins)
- [openai/codex · plugin-json-spec](https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md)