---
title: "marketplace add 用 --ref 钉版本，用 --sparse 只拉插件目录"
summary: "Git 源用 --ref 或 owner/repo@ref 钉提交。大仓加 --sparse 只 checkout 插件路径。加完还要 plugin add；0.154 起先看当前会话。"
category: skills
level: intermediate
surfaces: [cli, app]
tags: ["plugins", "marketplace", "--sparse"]
canonical: /tips/plugin-marketplace-ref-sparse/
---

# marketplace add 用 --ref 钉版本，用 --sparse 只拉插件目录

Git 源用 --ref 或 owner/repo@ref 钉提交。大仓加 --sparse 只 checkout 插件路径。加完还要 plugin add；0.154 起先看当前会话。

`codex plugin marketplace add` 接受 GitHub 简写、HTTPS / SSH Git URL，以及本地 marketplace 根目录。Git 源把整仓 clone 进来很慢，也容易超时。官方 CLI 参考给了钉 ref 和稀疏检出：

```bash
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add owner/repo@main
codex plugin marketplace add owner/repo --sparse .agents/plugins --json
codex plugin marketplace add https://github.com/owner/repo --sparse plugins/foo --sparse skills/bar
codex plugin marketplace list --json
```

`owner/repo@ref` 和 `--ref` 等价，用来钉分支、标签或提交。`--sparse PATH` 只对 Git 源有效，可重复；本地目录 marketplace 不要加 `--sparse`。`--json` 成功时给出 `marketplaceName`、`installedRoot`、`alreadyAdded`，方便脚本判断是新加还是已经有了。

加 marketplace **不等于**装插件。还要：

```bash
codex plugin add name@marketplace
codex plugin list --json
```

0.154 起当前会话通常会捡起新装的插件工具；`/plugins` 和斜杠技能仍没有再新开。不要写成 `codex marketplace add`（少了 `plugin`）。也不要把 `features.plugins = true` 抄进用户 `config.toml` 当现行必写键；个人机默认就能用插件，企业关插件是另一套 `requirements.toml`。

## 来源

- [OpenAI · CLI reference](https://developers.openai.com/codex/cli/reference)
- [Codex Knowledge Base · plugin management](https://codex.danielvaughan.com/2026/06/04/codex-cli-plugin-management-terminal-commands-marketplace-json-output-v0137/)