Criar plugins
Crie, teste e distribua plugins para o ChatGPT
Esta página destina-se a autores de plugins. Se pretender explorar, instalar e utilizar plugins com o ChatGPT Work na Web ou com o ChatGPT Work ou o Codex na aplicação ChatGPT para computador, consulte Plugins. Se ainda estiver a aperfeiçoar um único repositório ou fluxo de trabalho pessoal, comece por uma competência local. Crie um plugin quando pretender partilhar esse fluxo de trabalho entre equipas, agrupar conectores ou configuração MCP, empacotar hooks de ciclo de vida ou publicar um pacote estável.
Um plugin pode incluir competências, uma aplicação suportada por MCP ou ambos. Se o seu plugin precisar de estabelecer ligação a um serviço ou disponibilizar ferramentas através de um servidor MCP, consulte Criar uma aplicação.
Para obter exemplos públicos completos, consulte Figma, Notion e Criar aplicações Web.
Criar um plugin com @plugin-creator
Para a configuração mais rápida, utilize a competência @plugin-creator incorporada.
Esta cria a estrutura do manifesto .codex-plugin/plugin.json obrigatório e também pode
gerar uma entrada num marketplace local para testes. Se já tiver uma pasta de plugin,
pode continuar a utilizar @plugin-creator para a associar a um
marketplace local.
Criar e testar localmente um plugin que aponta para uma aplicação em modo de desenvolvimento suportada por um servidor MCP
Também pode utilizar a competência plugin-creator se pretender testar localmente um plugin que inclua uma aplicação suportada por um servidor MCP. O plugin continua a precisar de uma pasta de plugin e de um manifesto locais, mas a aplicação propriamente dita é iniciada no modo de programador do ChatGPT.
Primeiro, ative o modo de programador no ChatGPT:
- Abra o ChatGPT.
- Abra Definições.
- Selecione Segurança e início de sessão.
- Ative o Modo de programador.
Em seguida, crie a aplicação no modo de programador:
- Abra Definições → Plugins ou a página Plugins.
- Selecione o botão de adição.
- Preencha a janela modal para criar uma aplicação em modo de programador para o seu servidor MCP.
- Depois de o ChatGPT a criar, copie o ID da aplicação a partir do URL do browser. Este começa
por
plugin_asdk_app.
Forneça esse ID plugin_asdk_app... a @plugin-creator numa conversa do ChatGPT Work
ou a $plugin-creator no Codex. Por exemplo, com o ChatGPT Work:
Pedido para o Plugin Creator@plugin-creator create a Codex plugin for my ChatGPT app.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.A competência plugin-creator criará a pasta do plugin, criará o ficheiro
.codex-plugin/plugin.json obrigatório e adicionará a ligação à aplicação ChatGPT. Se lhe pedir
para criar uma entrada num marketplace pessoal, o plugin aparecerá na sua origem local
no Diretório de Plugins para testes.
Depois de a competência plugin-creator criar o plugin:
- Reveja
.app.jsone confirme que aponta para o IDplugin_asdk_app...correto. - Reveja
.codex-plugin/plugin.jsone certifique-se de que o respetivo campoappsaponta para./.app.json. - Adicione quaisquer competências incluídas em
skills/se o plugin tiver de incluir fluxos de trabalho repetíveis juntamente com a aplicação. - Se a competência tiver criado uma entrada num marketplace pessoal, atualize o ChatGPT, instale o plugin a partir da sua origem local no Diretório de Plugins e, em seguida, teste-o numa nova conversa.
Para conhecer o formato do manifesto e a disposição dos ficheiros, consulte Estrutura do plugin e Regras de caminhos.
Criar a sua própria lista selecionada de plugins
Um marketplace é um catálogo JSON de plugins. @plugin-creator pode gerar um
para um único plugin, e pode continuar a adicionar entradas ao mesmo marketplace
para criar a sua própria lista selecionada para um repositório, uma equipa ou um fluxo de trabalho pessoal.
No ChatGPT Work ou no Codex na aplicação ChatGPT para computador, cada marketplace aparece como uma
origem selecionável no Diretório de Plugins. Utilize
$REPO_ROOT/.agents/plugins/marketplace.json para uma lista limitada ao repositório ou
~/.agents/plugins/marketplace.json para uma lista pessoal. Adicione uma entrada por
plugin em plugins[], faça cada source.path apontar para a pasta do plugin através de um caminho
com o prefixo ./ relativo à raiz do marketplace e defina
interface.displayName como o nome que pretende que a aplicação apresente no seletor
de marketplaces. Em seguida, reinicie a aplicação ChatGPT para computador. Depois, abra o Diretório
de Plugins, escolha o seu marketplace e explore ou instale os plugins dessa
lista selecionada.
Não precisa de um marketplace separado para cada plugin. Um marketplace pode disponibilizar um único plugin durante os testes e, à medida que adiciona mais plugins, transformar-se num catálogo selecionado mais abrangente.
Adicionar um marketplace a partir da CLI
Utilize codex plugin marketplace add para adicionar e acompanhar uma origem de marketplace, em vez
de editar config.toml manualmente. Estes comandos permitem criar plugins e
configurar catálogos. Utilize a aplicação ChatGPT para computador para instalar e testar um plugin local.
codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-rootAs origens de marketplaces podem ser uma notação abreviada do GitHub (owner/repo ou
owner/repo@ref), URLs Git HTTP ou HTTPS, URLs Git SSH ou diretórios raiz de
marketplaces locais. Utilize --ref para fixar uma referência Git e repita --sparse PATH para utilizar um
checkout esparso em repositórios de marketplaces baseados em Git. --sparse só é válido para
origens de marketplaces Git.
Para inspecionar, atualizar ou remover marketplaces configurados:
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-namecodex plugin marketplace list apresenta cada marketplace que o Codex está a considerar
e o caminho raiz a partir do qual este é resolvido, incluindo marketplaces locais predefinidos e
instantâneos de marketplaces configurados.
Criar um plugin manualmente
Comece com um plugin mínimo que empacote uma competência.
- Crie uma pasta de plugin com um manifesto em
.codex-plugin/plugin.json.
mkdir -p my-first-plugin/.codex-pluginmy-first-plugin/.codex-plugin/plugin.json
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}Utilize um name de plugin estável em kebab-case. O Codex utiliza-o como identificador
do plugin e espaço de nomes dos componentes.
- Adicione uma competência em
skills/<skill-name>/SKILL.md.
mkdir -p my-first-plugin/skills/hellomy-first-plugin/skills/hello/SKILL.md
---
name: hello
description: Greet the user with a friendly message.
---
Greet the user warmly and ask how you can help.- Adicione o plugin a um marketplace. Utilize
@plugin-creatorpara gerar um ou siga Criar a sua própria lista selecionada de plugins para associar manualmente o plugin ao Codex.
A partir daí, pode adicionar a configuração MCP, conectores ou metadados do marketplace, conforme necessário.
Instalar manualmente um plugin local
Utilize um marketplace do repositório ou um marketplace pessoal, consoante quem deva poder aceder ao plugin ou à lista selecionada.
Repositório
Adicione um ficheiro de marketplace em `$REPO_ROOT/.agents/plugins/marketplace.json`
e armazene os seus plugins em `$REPO_ROOT/plugins/`.
**Exemplo de marketplace do repositório**
Passo 1: copie a pasta do plugin para `$REPO_ROOT/plugins/my-plugin`.mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-pluginPasso 2: adicione ou atualize `$REPO_ROOT/.agents/plugins/marketplace.json` para que
`source.path` aponte para esse diretório de plugin através de um caminho relativo com o prefixo
`./`:{
"name": "local-repo",
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}Passo 3: reinicie a aplicação ChatGPT para computador e confirme que o plugin aparece.Pessoal
Adicione um ficheiro de marketplace em `~/.agents/plugins/marketplace.json` e armazene
os seus plugins em `~/.codex/plugins/`.
**Exemplo de marketplace pessoal**
Passo 1: copie a pasta do plugin para `~/.codex/plugins/my-plugin`.mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-pluginPasso 2: adicione ou atualize `~/.agents/plugins/marketplace.json` para que o
campo `source.path` da entrada do plugin aponte para esse diretório.
Passo 3: reinicie a aplicação ChatGPT para computador e confirme que o plugin aparece.O ficheiro do marketplace aponta para a localização do plugin, pelo que esses diretórios são
exemplos e não requisitos fixos. O Codex resolve source.path relativamente
à raiz do marketplace, não relativamente à pasta .agents/plugins/. Consulte
Metadados do marketplace para conhecer o formato do ficheiro.
Depois de alterar o plugin, atualize o diretório de plugins para o qual aponta a entrada do marketplace e reinicie a aplicação ChatGPT para computador, para que a instalação local utilize os novos ficheiros.
Partilhar um plugin local com o seu espaço de trabalho
Depois de criar um plugin, adicione-o a partir da aplicação ChatGPT para computador. Selecione ChatGPT e mude para Work no seletor, ou selecione Codex e, em seguida, abra Plugins. Poderá então partilhá-lo com outros membros do seu espaço de trabalho do ChatGPT.
- Abra Plugins na aplicação ChatGPT para computador.
- Aceda a Criados por si e abra a página de detalhes do plugin.
- Selecione Partilhar.
- Adicione membros ou grupos do espaço de trabalho, ou copie uma ligação de partilha.
- Escolha quem tem acesso e, em seguida, envie o convite ou a ligação.
As pessoas com quem partilhar podem encontrar o plugin em Partilhados consigo no Diretório de Plugins. Partilhar um plugin local com o seu espaço de trabalho não o publica no Diretório de Plugins público. Os plugins partilhados permanecem dentro dos limites do seu espaço de trabalho e da sua organização; as contas que não tenham sessão iniciada nesse espaço de trabalho não lhes podem aceder. Utilize grupos quando uma equipa ou função deva partilhar o mesmo acesso a plugins. Utilize um marketplace quando pretender fazer a distribuição por repositório ou CLI e utilize a partilha no espaço de trabalho quando pretender que colegas selecionados instalem um plugin a partir da aplicação ChatGPT para computador.
Os administradores do espaço de trabalho podem desativar a partilha de plugins através de requisitos geridos na cloud,
adicionando features.plugin_sharing = false a requirements.toml:
features.plugin_sharing = falseMetadados do marketplace
Se mantiver um marketplace de repositório, defina-o em
$REPO_ROOT/.agents/plugins/marketplace.json. Para um marketplace pessoal, utilize
~/.agents/plugins/marketplace.json. Um ficheiro de marketplace controla a
ordenação dos plugins e as políticas de instalação na aplicação ChatGPT para computador. Pode representar um
único plugin durante os testes ou uma lista selecionada de plugins que pretende que a aplicação
apresente em conjunto sob um único nome de marketplace. Antes de adicionar um plugin a um
marketplace, certifique-se de que o respetivo version, os metadados do editor e o texto
da interface de instalação estão prontos para serem vistos por outros programadores.
{
"name": "local-example-plugins",
"interface": {
"displayName": "Local Example Plugins"
},
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
},
{
"name": "research-helper",
"source": {
"source": "local",
"path": "./plugins/research-helper"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}- Utilize
nameao nível superior para identificar o marketplace. - Utilize
interface.displayNamepara o título do marketplace apresentado na aplicação ChatGPT para computador. - Adicione um objeto por plugin em
pluginspara criar uma lista selecionada que a aplicação apresenta sob esse título do marketplace. - Aponte o
source.pathde cada entrada de plugin para o diretório do plugin que pretende que o Codex carregue. Em instalações de repositórios, este encontra-se frequentemente em./plugins/. Em instalações pessoais, um padrão comum é./.codex/plugins/<plugin-name>. - Mantenha
source.pathrelativo à raiz do marketplace, comece-o com./e mantenha-o dentro dessa raiz. - Para entradas locais,
sourcetambém pode ser um caminho como cadeia de texto simples, por exemplo"./plugins/my-plugin". - Inclua sempre
policy.installation,policy.authenticationecategoryem cada entrada de plugin. - Utilize valores de
policy.installationcomoAVAILABLE,INSTALLED_BY_DEFAULTouNOT_AVAILABLE. - Utilize
policy.authenticationpara decidir se a autenticação ocorre durante a instalação ou na primeira utilização.
O marketplace controla o local a partir do qual o Codex carrega o plugin. Um
source.path local pode apontar para outro local caso o plugin esteja fora desses
diretórios de exemplo. Um ficheiro de marketplace pode estar no repositório onde está a
desenvolver o plugin ou num repositório de marketplace separado, e um único ficheiro de
marketplace pode apontar para um ou vários plugins.
As entradas do marketplace também podem apontar para origens de plugins baseadas em Git. Utilize
"source": "url" quando o plugin estiver na raiz do repositório ou
"source": "git-subdir" quando o plugin estiver num subdiretório:
{
"name": "remote-helper",
"source": {
"source": "git-subdir",
"url": "https://github.com/example/codex-plugins.git",
"path": "./plugins/remote-helper",
"ref": "main"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}As entradas baseadas em Git podem utilizar seletores ref ou sha. Se o Codex não conseguir resolver a
origem de uma entrada do marketplace, ignora essa entrada de plugin em vez de causar uma falha em todo o
marketplace.
As entradas do marketplace também podem instalar um plugin a partir de um registo de pacotes JavaScript:
{
"name": "npm-helper",
"source": {
"source": "npm",
"package": "@example/codex-plugin",
"version": "^1.2.0",
"registry": "https://registry.npmjs.org"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}package é obrigatório e pode incluir um âmbito de registo. version é opcional
e aceita versões de pacotes, etiquetas de distribuição e intervalos de versões, mas não
seletores de caminho ou URL.
registry é opcional e tem de ser um URL HTTPS sem credenciais incorporadas,
parâmetros de consulta ou fragmentos. O Codex transfere o pacote sem executar scripts de
ciclo de vida. A CLI npm tem de estar instalada e a autenticação do registo provém
da respetiva configuração.
Como a aplicação ChatGPT para computador utiliza marketplaces
Um marketplace de plugins é um catálogo JSON de plugins que a aplicação ChatGPT para computador pode ler e instalar.
A aplicação pode ler ficheiros de marketplace a partir de:
- o marketplace selecionado que serve de base ao Diretório de Plugins oficial
- um marketplace de repositório em
$REPO_ROOT/.agents/plugins/marketplace.json - um marketplace compatível com versões legadas em
$REPO_ROOT/.claude-plugin/marketplace.json - um marketplace pessoal em
~/.agents/plugins/marketplace.json
Pode instalar qualquer plugin disponibilizado através de um marketplace. A aplicação instala
os plugins em
~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Para plugins
locais, $VERSION é local, e a aplicação carrega a cópia instalada a partir desse
caminho de cache em vez de o fazer diretamente a partir da entrada do marketplace.
Pode ativar ou desativar cada plugin individualmente. A aplicação guarda o estado ativado
ou desativado de cada plugin em ~/.codex/config.toml.
Empacotar e distribuir plugins
Estrutura do plugin
Cada plugin tem um manifesto em .codex-plugin/plugin.json. Também pode incluir
um diretório skills/, um diretório hooks/ para hooks de ciclo de vida, um ficheiro .app.json
que aponta para um ou mais conectores, um ficheiro .mcp.json que
configura servidores MCP e recursos utilizados para apresentar o plugin nas superfícies
suportadas.
my-plugin/
├── .codex-plugin/
│ └── plugin.json # Required: plugin manifest
├── skills/
│ └── my-skill/
│ └── SKILL.md # Optional: skill instructions
├── hooks/
│ └── hooks.json # Optional: lifecycle hooks
├── .app.json # Optional: app or connector mappings
├── .mcp.json # Optional: MCP server configuration
└── assets/ # Optional: icons, logos, screenshotsApenas plugin.json pertence a .codex-plugin/. Mantenha skills/, hooks/,
assets/, .mcp.json e .app.json na raiz do plugin.
Os plugins publicados utilizam normalmente um manifesto mais completo do que o exemplo mínimo que surge nas estruturas de início rápido. O manifesto tem três funções:
- Identificar o plugin.
- Apontar para componentes incluídos, como competências, conectores, servidores MCP ou hooks.
- Fornecer metadados da superfície de instalação, como descrições, ícones e ligações jurídicas.
Segue-se um exemplo de manifesto completo:
{
"name": "my-plugin",
"version": "0.1.0",
"description": "Bundle reusable skills and connectors.",
"author": {
"name": "Your team",
"email": "team@example.com",
"url": "https://example.com"
},
"homepage": "https://example.com/plugins/my-plugin",
"repository": "https://github.com/example/my-plugin",
"license": "MIT",
"keywords": ["research", "crm"],
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"apps": "./.app.json",
"hooks": "./hooks/hooks.json",
"interface": {
"displayName": "My Plugin",
"shortDescription": "Reusable skills and connectors",
"longDescription": "Distribute skills and connectors together.",
"developerName": "Your team",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"websiteURL": "https://example.com",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": [
"Use My Plugin to summarize new CRM notes.",
"Use My Plugin to triage new customer follow-ups."
],
"brandColor": "#10A37F",
"composerIcon": "./assets/icon.png",
"logo": "./assets/logo.png",
"screenshots": ["./assets/screenshot-1.png"]
}
}.codex-plugin/plugin.json é o ponto de entrada obrigatório. Os outros campos do manifesto
são opcionais, mas os plugins publicados utilizam-nos frequentemente.
Campos do manifesto
Utilize os campos de nível superior para definir os metadados do pacote e apontar para os componentes incluídos:
name,versionedescriptionidentificam o plugin.author,homepage,repository,licenseekeywordsfornecem metadados do editor e de descoberta.skills,mcpServers,appsehooksapontam para componentes incluídos relativamente à raiz do plugin.interfacecontrola a forma como as superfícies de instalação apresentam o plugin.
Utilize o objeto interface para os metadados da superfície de instalação:
displayName,shortDescriptionelongDescriptioncontrolam o título e o texto descritivo.developerName,categoryecapabilitiesadicionam metadados do editor e das capacidades.websiteURL,privacyPolicyURLetermsOfServiceURLfornecem ligações externas.defaultPrompt,brandColor,composerIcon,logoescreenshotscontrolam os pedidos iniciais e a apresentação visual.
Regras para caminhos
- Mantenha os caminhos do manifesto relativos à raiz do plugin e comece-os com
./. - Guarde recursos visuais como
composerIcon,logoescreenshotsem./assets/sempre que possível. - Utilize
skillspara pastas de competências incluídas,appspara.app.json,mcpServerspara.mcp.jsonehookspara hooks de ciclo de vida. - Os plugins ativados podem incluir hooks de ciclo de vida juntamente com competências, servidores MCP e conectores.
- Se o plugin guardar hooks em
./hooks/hooks.json, não é necessária uma entradahooksem.codex-plugin/plugin.json; o Codex verifica automaticamente esse ficheiro predefinido.
Servidores MCP e hooks de ciclo de vida incluídos
mcpServers pode apontar para um ficheiro .mcp.json que contenha um mapa direto de
servidores ou um objeto mcp_servers envolvente.
Mapa direto de servidores:
{
"docs": {
"command": "docs-mcp",
"args": ["--stdio"]
}
}Mapa envolvente de servidores:
{
"mcp_servers": {
"docs": {
"command": "docs-mcp",
"args": ["--stdio"]
}
}
}Após a instalação, os utilizadores podem ativar ou desativar um servidor MCP incluído e ajustar
a política de aprovação de ferramentas na configuração do Codex sem editar o plugin. Utilize
plugins.<plugin>.mcp_servers.<server> para a política do servidor MCP limitada ao âmbito do plugin:
[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]
[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"Quando o plugin está ativado, o Codex pode carregar hooks de ciclo de vida do plugin juntamente com hooks do utilizador, do projeto e geridos.
Instalar ou ativar um plugin não considera automaticamente os respetivos hooks como fidedignos. Os hooks incluídos no plugin são hooks não geridos, pelo que o Codex os ignora até o utilizador rever e considerar fidedigna a definição atual dos hooks.
O ficheiro predefinido de hooks do plugin é hooks/hooks.json:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",
"statusMessage": "Loading plugin context"
}
]
}
]
}
}Se definir hooks em .codex-plugin/plugin.json, o Codex utiliza essa entrada do
manifesto em vez do hooks/hooks.json predefinido. O campo do manifesto pode ser um
único caminho, uma matriz de caminhos, um objeto de hooks incorporado ou uma matriz de objetos
de hooks incorporados.
{
"name": "repo-policy",
"hooks": ["./hooks/session.json", "./hooks/tools.json"]
}Os caminhos dos hooks seguem as mesmas regras de caminhos do manifesto que skills, apps e
mcpServers: começam com ./, são resolvidos relativamente à raiz do plugin e permanecem
dentro da raiz do plugin.
Os comandos dos hooks do plugin recebem as variáveis de ambiente específicas do Codex
PLUGIN_ROOT e PLUGIN_DATA. PLUGIN_ROOT aponta para a raiz do plugin
instalado e PLUGIN_DATA aponta para o diretório de dados gravável do plugin. O Codex
também define CLAUDE_PLUGIN_ROOT e CLAUDE_PLUGIN_DATA para compatibilidade com
hooks de plugins existentes.
Os hooks de plugins utilizam o mesmo esquema de eventos que os hooks normais. Consulte Hooks para conhecer os eventos, entradas, saídas, revisão de confiança e limitações atuais suportados.
Publicar plugins públicos oficiais
Para publicar um plugin para utilização pública, submeta-o através do portal de submissão de plugins. Consulte Submeter plugins para conhecer o processo completo de revisão e publicação.