O sistema de plugins da Codex CLI está evoluindo rapidamente. O comando /plugins já permite navegar, instalar, ativar e desativar plugins por categorias de mercado, e cada vez mais equipes estão empacotando suas cadeias de ferramentas internas em plugins Codex reutilizáveis. No entanto, a entrada de autoatendimento no Marketplace oficial ainda está em fase de "revisão". Os desenvolvedores precisam primeiro entender a estrutura do manifesto e os métodos de depuração local antes de passar pelo processo de submissão e revisão para que o plugin chegue aos usuários. Este artigo detalha, passo a passo, o fluxo completo desde a criação do zero, testes locais e distribuição via Git, até a submissão para revisão oficial, além de resumir alguns pontos críticos onde é fácil cometer erros.
Do que é composto um plugin Codex
Um plugin Codex é, essencialmente, o empacotamento de várias capacidades em uma unidade instalável e distribuível. De acordo com a documentação oficial da OpenAI, os plugins podem conter skills (instruções de tarefas reutilizáveis), aplicativos baseados em MCP (serviços que conectam ferramentas externas), hooks de ciclo de vida e, opcionalmente, extensões de navegador e modelos de tarefas agendadas. Esses componentes não precisam estar presentes simultaneamente; um plugin leve contendo apenas skills pode ser instalado e usado normalmente.
Entender os limites de responsabilidade de cada componente é o pré-requisito para escrever um manifesto adequado. A tabela abaixo resume o caminho de armazenamento e a função dos quatro componentes principais no diretório de um plugin Codex:
| Componente | Caminho de armazenamento | Função | Obrigatório |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
Identidade e metadados do plugin | Sim |
| skills | skills/<skill-name>/SKILL.md |
Define instruções de tarefas reutilizáveis | Não |
| Servidores MCP | .mcp.json |
Configura a conexão com serviços de ferramentas externas | Não |
| hooks | hooks/hooks.json |
Declara comandos de gancho de ciclo de vida | Não |
Vale notar que, se o plugin for apenas um arquivo SKILL.md para uso interno da equipe, não é necessário passar pelo processo completo do manifesto — basta colocar o arquivo diretamente no diretório .agents/skills/ e o Codex o detectará automaticamente, sem a necessidade de uma lista de plugins. Essa é uma forma intermediária comum para muitas equipes que estão migrando de "scripts internos" para "plugins oficiais".
O limite de capacidade de um plugin é mais amplo do que muitos imaginam. Além de skills e aplicativos baseados em MCP, que são os componentes mais comuns, a documentação oficial menciona que os plugins podem carregar declarações de capacidade necessárias para extensões de navegador e modelos de tarefas agendadas. Isso significa que um plugin pode lidar tanto com solicitações interativas "iniciadas pelo usuário" quanto com cenários de automação de "execução periódica em segundo plano". Escolher quais componentes combinar em um mesmo plugin é, fundamentalmente, uma questão de equilibrar a experiência de instalação e o custo de manutenção — quanto mais componentes, mais completo é o plugin, mas os materiais de revisão e casos de teste correspondentes também aumentam. Antes de enviar, é melhor ter clareza sobre qual nível de capacidade seus usuários-alvo realmente precisam, em vez de colocar todos os componentes em um único pacote.
Começando pelo plugin.json: Entendendo o arquivo de manifesto do plugin
O plugin.json é o documento de identidade do seu plugin; é ele que determina como o Codex identifica, carrega e exibe o seu trabalho. Um manifesto funcional mínimo exige apenas três campos:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
Para o campo name, recomendo usar uma nomenclatura estável em kebab-case. Não altere esse identificador em atualizações futuras, caso contrário, o marketplace não reconhecerá o plugin como uma iteração do mesmo projeto. O campo version segue a especificação de versionamento semântico, e é através dele que o marketplace decide se deve ou não notificar o usuário sobre uma atualização. Todos os caminhos referenciados no manifesto devem ser relativos ao diretório raiz do plugin, começar com ./ e nunca sair da pasta raiz.
Além desses campos básicos, skills pode apontar para um array de diretórios de habilidades, enquanto os campos hooks, mcpServers e apps apontam para os arquivos de configuração hooks/hooks.json, .mcp.json e .app.json, respectivamente. Esse design de "campos que apontam para arquivos" mantém o manifesto enxuto, separando as descrições de habilidades e as configurações de ferramentas em arquivos independentes. Isso facilita muito o trabalho em equipe, permitindo que várias pessoas modifiquem componentes diferentes simultaneamente sem gerar conflitos.
Se você pretende enviar seu plugin para o Marketplace oficial, precisará adicionar um conjunto de metadados focados na exibição. A tabela abaixo lista os campos essenciais que recomendamos preencher durante a fase de publicação:
| Campo | Tipo | Descrição |
|---|---|---|
| author / repository | String | Identifica a origem do plugin, deve coincidir com a identidade verificada |
| interface.displayName | String | Nome do plugin exibido na lista do marketplace |
| interface.category | String | Categoria do plugin, influencia a navegação do usuário |
| interface.capabilities | Array | Declara as etiquetas de capacidades do plugin |
| mcpServers / apps / hooks | Objeto | Aponta para os arquivos de configuração dos componentes correspondentes |
O erro mais comum ao escrever o manifesto é a referência incorreta de caminhos — como usar caminhos absolutos no campo skills ou esquecer o ./ inicial. Isso faz com que o plugin funcione localmente, mas seja invalidado durante a revisão. Recomendo clonar o repositório do plugin em um diretório limpo antes de enviar, simulando um ambiente de instalação real para realizar um teste completo.
Scaffold local e depuração: Colocando o plugin para rodar
Escrever o manifesto do zero não é eficiente. A equipe oficial disponibilizou a habilidade $plugin-creator para montar a estrutura básica, permitindo que você gere tudo via diálogo no Codex CLI:
codex "Use o scaffold $plugin-creator para gerar um plugin chamado infra-monitor"
Esse comando gera automaticamente o manifesto, um exemplo de skill e a entrada no marketplace local, poupando o trabalho manual de criar a estrutura de pastas. Após a geração, o plugin já pode ser instalado e testado no ambiente local, sem a necessidade de publicar em qualquer repositório remoto.
Durante a fase de depuração local, se a skill do seu plugin envolver a invocação de modelos de diferentes fabricantes para testes comparativos, um gateway de API unificado pode reduzir drasticamente o custo de alternância de ambiente. Ao validar a capacidade de servidor MCP do plugin, costumamos apontar a base_url para o serviço proxy de API fornecido pela APIYI (apiyi.com). Com uma única chave API, você pode alternar entre diferentes modelos dentro do plugin, facilitando a comparação do desempenho de cada um sob a mesma lógica:
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 Dica de depuração: Durante o desenvolvimento de plugins para o Codex, é comum precisar testar repetidamente a qualidade da resposta do servidor MCP em diferentes modelos. Recomendamos usar a plataforma APIYI (apiyi.com) para gerenciar centralizadamente a invocação do modelo, evitando ter que solicitar chaves separadas para cada modelo ou manter lógicas de chamada independentes. Assim, você mantém o foco no aprimoramento das funcionalidades do seu plugin.
Além de configurar manualmente a entrada no marketplace local, você também pode declarar o caminho do plugin local diretamente em ~/.agents/plugins/marketplace.json (nível pessoal) ou no .agents/plugins/marketplace.json da raiz do repositório (nível de equipe), definindo o campo source como local. Isso permite a instalação e validação sem precisar de um push remoto.
Se o seu plugin incluir um app baseado em MCP que precise de depuração com o modo de desenvolvedor do ChatGPT, existe outro caminho: ative o modo de desenvolvedor nas configurações do ChatGPT, crie um app baseado em MCP, obtenha o ID do app e use o $plugin-creator para associá-lo. Isso permite verificar o fluxo de dados entre o plugin e o app em um ambiente de conversa real. Esse passo é muito mais próximo da experiência final do que a depuração via linha de comando, por isso recomendo realizá-lo antes de enviar para revisão.
Registro no Git Marketplace e distribuição interna
Depois que o plugin for validado localmente, a distribuição interna na equipe geralmente não precisa esperar pela revisão oficial; basta configurar um repositório Git como fonte de mercado. O Codex CLI oferece um conjunto de comandos dedicados para o gerenciamento do marketplace:
| Comando | Finalidade |
|---|---|
codex plugin marketplace add owner/repo |
Adiciona um repositório GitHub como fonte de mercado |
codex plugin marketplace add owner/repo --ref v2.1.0 |
Bloqueia uma branch ou tag específica para controlar o lançamento gradual |
codex plugin marketplace list |
Lista os mercados adicionados |
codex plugin marketplace upgrade |
Busca atualizações do mercado |
codex plugin marketplace remove |
Remove uma fonte de mercado |
Para equipes com repositórios de código muito grandes, você também pode usar o parâmetro --sparse .agents/plugins para baixar apenas o diretório relacionado ao plugin, evitando que o clone de todo o repositório torne a instalação lenta. Esse modelo de mercado via Git é ideal para cadeias de ferramentas internas — não exige revisão pública e, para atualizar o plugin, basta enviar uma nova tag e pedir que os membros da equipe executem o comando upgrade uma vez para sincronizar.
Na prática, o modelo de mercado via Git tem uma vantagem oculta: permite desacoplar o ritmo de iteração do plugin do ritmo de lançamento interno da equipe. O código de negócio pode ser mesclado várias vezes ao dia, mas, como o plugin faz parte de uma cadeia de ferramentas conversacional, uma frequência de atualização muito alta pode acabar quebrando o modelo mental dos usuários. A recomendação é vincular as versões do plugin e as tags a janelas de lançamento fixas, como mesclar alterações semanalmente ou quinzenalmente. Isso garante a velocidade de iteração de funcionalidades sem forçar os membros da equipe a se readaptarem constantemente a novas formas de interação.
Processo completo de submissão ao Marketplace oficial
A entrada de autoatendimento para o Marketplace oficial ainda não foi totalmente aberta; a documentação da OpenAI indica claramente que esta parte está "em breve". Atualmente, a submissão formal para usuários públicos passa por um processo de revisão manual no portal de submissão de plugins. Antes de enviar, é necessário concluir a verificação de identidade — desenvolvedores individuais precisam passar pela verificação individual, enquanto empresas precisam passar pela verificação comercial. Os revisores verificarão se a identidade do editor corresponde aos materiais enviados.
A lista de materiais necessários para a submissão formal é a seguinte:
| Categoria do Material | Requisitos Específicos |
|---|---|
| Informações básicas do plugin | Nome, descrição, logotipo, categoria, URLs relacionadas |
| Servidor MCP | Domínio acessível publicamente, política CSP, configuração de autenticação |
| Conta de demonstração | Acesso direto, sem necessidade de MFA ou verificação secundária por e-mail |
| Casos de teste | Exatamente 5 cenários positivos + 3 cenários negativos |
| Marcação de ferramentas | readOnlyHint, openWorldHint, destructiveHint devem ser consistentes com o comportamento real |
O processo de submissão é dividido em vários blocos de formulário: Info (informações da listagem pública), MCP (configuração de servidor e autenticação), Skills (upload do pacote de habilidades final), Prompts (exemplos de comandos iniciais), Testing (casos de teste), Global (países e regiões disponíveis) e, finalmente, o bloco Submit para preencher as notas de lançamento e confirmar as políticas. Após a aprovação, o momento do lançamento é escolhido pelo próprio desenvolvedor no portal, e o plugin aparecerá simultaneamente no diretório unificado de plugins do ChatGPT e do Codex.
Se o plugin incluir um aplicativo baseado em MCP, também é necessário verificar a propriedade do domínio para garantir que o domínio onde o servidor MCP está implantado seja o mesmo declarado pelo plugin. A equipe de revisão focará em verificar se os resultados retornados pela ferramenta contêm dados pessoais ou informações de chaves desnecessárias; isso é algo que deve ser evitado desde o design do formato de saída da ferramenta, em vez de esperar que a revisão rejeite para só então fazer alterações.
Gerenciamento de versão e armadilhas comuns
Após o lançamento do plugin, os detalhes do gerenciamento de versão afetam diretamente a experiência de atualização do usuário. O marketplace depende do campo version para determinar se há atualizações disponíveis, por isso é fundamental seguir rigorosamente a especificação de versionamento semântico: use o número de patch para correções de bugs, o número minor para novas funcionalidades e o major apenas para mudanças que quebrem a compatibilidade.
Os plugins instalados são armazenados em cache no caminho local ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Ao investigar problemas como "o plugin foi atualizado, mas o comportamento não mudou", verificar se o cache foi atualizado para a nova versão costuma ser mais rápido do que depurar a lógica do código. Em ambientes corporativos, você também pode encontrar políticas de lista de permissões forçadas pelo requirements.toml; o servidor MCP precisa ter o nome e a identidade correspondentes. Qualquer inconsistência resultará na desativação silenciosa do serviço, sem mensagens de erro claras. Para esses casos, recomendo testar as configurações de política em um ambiente de teste antes de ir para a produção.
A tabela abaixo resume alguns pontos críticos relatados por desenvolvedores e como lidar com eles:
| Problema comum | Como resolver |
|---|---|
| Caminho do manifest como absoluto | Altere para caminhos relativos começando com ./ |
| Chamada implícita aciona plugin inesperado | Use @plugin-name para especificar o plugin explicitamente |
| Comportamento não mudou após atualização | Verifique se o diretório de cache local do plugin foi atualizado |
| MCP falha silenciosamente sob política corporativa | Verifique se o nome e a identidade coincidem no requirements.toml |
Antes de enviar oficialmente para revisão, recomendo executar a ferramenta de terceiros codex-plugin-scanner. Ela avalia o plugin em dimensões como instalabilidade, estado de manutenção, segurança MCP e origem da publicação. Especialmente para plugins destinados a clientes corporativos, identificar problemas antecipadamente economiza muito mais tempo do que ter o envio rejeitado na revisão.
Outro detalhe frequentemente ignorado é a diferença entre chamadas explícitas e descoberta implícita. Quando nenhum plugin é especificado, o Codex combina automaticamente as habilidades mais relevantes com base no contexto. Se vários plugins com funções semelhantes estiverem instalados no mesmo espaço de trabalho, essa correspondência implícita pode não selecionar o que você esperava. Criar o hábito de declarar explicitamente usando @plugin-name, especialmente em espaços de trabalho compartilhados por equipes, reduz o custo de depuração desses "conflitos entre plugins".
Perguntas frequentes (FAQ) sobre desenvolvimento de plugins Codex
Qual a diferença entre um plugin e um arquivo SKILL.md isolado?
O SKILL.md é um componente dentro de um plugin. Quando usado isoladamente, não precisa de um manifest; basta colocá-lo no diretório .agents/skills/ para ser descoberto automaticamente. Já o plugin empacota vários componentes, como skills, servidor MCP e hooks, em um conjunto com identidade e gerenciamento de versão, sendo ideal para cenários que exigem distribuição formal e rastreamento de atualizações.
O que fazer se eu precisar de várias contas de modelos para testes comparativos durante o desenvolvimento?
Este é um problema prático comum no desenvolvimento de plugins, especialmente para aqueles que envolvem seleção de modelos ou ajuste de comando. Em vez de abrir contas individuais e gerenciar chaves para cada fornecedor de modelo, utilize um gateway unificado como o APIYI (apiyi.com). Com uma única chave, você pode invocar os principais modelos para realizar testes A/B, focando a depuração na lógica do plugin em vez de na gestão de contas.
A distribuição via mercado Git e a listagem no Marketplace oficial podem coexistir?
Sim. Muitas equipes usam o mercado Git para validação interna e testes em pequena escala (canary releases). Após confirmar a estabilidade, seguem com o processo de envio oficial. Os dois métodos de distribuição não conflitam e a estrutura do manifest é universal.
Quanto tempo leva a revisão do plugin?
A documentação oficial não fornece um prazo fixo, informando apenas que o processo de revisão está em constante expansão e não suporta solicitações de urgência. Recomendo considerar o ciclo de revisão como uma variável incerta no cronograma do projeto. Preparar todos os materiais com antecedência e de forma completa é a maneira mais prática de reduzir o tempo total até o lançamento, evitando idas e vindas por falta de informações.
Considerações finais
O desafio central no desenvolvimento de plugins para o Codex não está propriamente no código, mas sim em compreender os requisitos do manifesto e preparar a documentação para o processo de revisão — esses detalhes não são tão complexos quanto parecem, mas é fácil ter o projeto rejeitado por causa de um caminho de arquivo mal escrito ou um campo ausente. Recomendo seguir a ordem: "validação em ambiente local → distribuição em pequena escala via Git → submissão para revisão oficial", reservando tempo para testes em ambiente real em cada etapa. Se o seu plugin envolver a invocação do modelo ou exigir alternância frequente entre modelos de teste, o serviço proxy de API oferecido pela APIYI (apiyi.com) pode economizar um tempo precioso na configuração do ambiente, permitindo que você foque sua energia no refinamento do plugin em si.
