Codex Plugins插件机制详解与本地安装教程

数码系统

相机 win10

测评 win11

手机智车

华为 Tesla

小米理想

苹果蔚来

游戏软件

LOL 抖音

原神微信

当前位置：首页

AI教程

Codex Plugins插件机制详解与本地安装教程

作者:怪兽小助手时间：2026-06-17

转载

Codex Plugins 插件机制详解与本地安装实战指南在AI工作流领域，如何实现高效复用一直是用户关注的焦点。Codex Plugins精准地回应了这一需求——它将Prompt规则与工具调用封装为可跨项目安装、复用的“能力包”。本文将从底层机制入手，带你全面理解其工作原理，并手把手指导你完成本

Codex Plugins 插件机制详解与本地安装实战指南

在AI工作流领域，如何实现高效复用一直是用户关注的焦点。Codex Plugins精准地回应了这一需求——它将Prompt规则与工具调用封装为可跨项目安装、复用的“能力包”。本文将从底层机制入手，带你全面理解其工作原理，并手把手指导你完成本地插件的搭建。

在这里插入图片描述

一、Codex Plugins 究竟是什么（先建立准确认知）

Codex Plugins不能简单等同于浏览器插件或IDE扩展，从工程角度看，它更像一套封装好的规则与工具调用机制。你可以将其视为一种可跨项目安装复用的“AI工作流包”，类似于npm包，但其内容并非代码模块，而是AI执行任务所需的指令集合。

一个典型的插件通常包含以下组成部分：

Skills：具体任务的执行规则，这是插件的核心所在
Apps：外部应用集成能力，属于可选功能
MCP servers：外部工具或上下文服务，同样为可选组件

二、官方插件目录的界面与功能

官方文档中呈现的插件目录更像一个“能力市场”，集筛选、安装、启用等功能于一体，操作流畅。它并非简单的列表，而是一个可交互的目录系统，旨在帮助用户快速定位并激活所需能力。

插件目录

三、6 个关键结论（建议优先掌握）

Codex Plugin = 可安装的 AI 工作流包
一个插件 = skills + (apps + MCP) 的组合体
CLI 与 UI 两种方式均可完成插件安装
小型需求优先编写 skill，不必直接制作 plugin
只有在需要跨项目复用时，才值得升级为 plugin
官方公共插件的发布功能仍在持续完善中

四、普通用户如何安装与使用插件

1）在 Codex App 中直接安装

官方提供了插件目录入口，支持一键安装：选择所需插件，点击启用，系统将自动加载 skills 并完成工具配置。这一设计让用户能够零门槛地快速获得现成的AI能力，无需任何复杂操作。

2）通过 CLI 方式使用插件

在命令行中执行以下指令：

codex/plugins

界面效果如下：

CLI插件界面

需要说明的是：CLI方式更适合开发者或需要批量管理插件的使用场景。

五、本地插件创建方法（核心重点）

方式1：使用 @plugin-creator 工具（强烈推荐）

官方推荐的创建方式是利用 @plugin-creator 工具：

@plugin-creator

该工具能够自动生成以下内容：

plugin.json 配置文件
本地插件结构目录
用于测试的 marketplace 配置

效果如下：

plugin creator

方式2：手动创建（用于理解底层结构）

一个最小化的插件结构如下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── demo-skill/
│       └── SKILL.md

六、plugin.json 文件详解（核心配置）

最简版本的 plugin.json 示例如下：

{
    "name": "my-first-plugin",
    "version": "1.0.0",
    "description": "一个可复用的工作流插件",
    "skills": "./skills/"
}

常用字段说明：

字段	作用
name	插件的唯一标识符
version	版本管理
description	插件功能描述
skills	skills 目录的入口路径

七、marketplace 的正确理解（常见误区）

很多人误以为 marketplace 就是“插件商店”。实际上，Codex 通过它来加载插件的列表信息，它更像是插件的注册索引，而非真正的商店。

1）Repo marketplace（仓库级别）

适用于项目内部的插件，配置文件路径：

$REPO_ROOT/.agents/plugins/marketplace.json

插件目录路径：

$REPO_ROOT/plugins/my-plugin

示例结构：

{
    "name": "local-repo",
    "interface": {
        "displayName": "项目插件集"
    },
    "plugins": [{
        "name": "my-plugin",
        "source": {
            "source": "local",
            "path": "./plugins/my-plugin"
        },
        "policy": {
            "installation": "A VAILABLE",
            "authentication": "ON_INSTALL"
        },
        "category": "Productivity"
    }]
}

2）Personal marketplace（个人级别）

适用于跨项目复用场景，配置文件路径：

~/.agents/plugins/marketplace.json

插件目录路径：

~/.codex/plugins/my-plugin

八、插件缓存机制（理解安装流程的关键）

安装完成后，Codex 会将插件缓存到以下路径：

~/.codex/plugins/cache/$MARKETPLACE/$PLUGIN/$VERSION/

本地插件的版本通常标识为：

local

启用状态则记录在：

~/.codex/config.toml

九、标准插件目录结构一览

一个规范的插件通常包含以下目录结构：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── .app.json
├── .mcp.json
└── assets/
    ├── icon.png
    └── logo.png

关键点总结：