Plugins: instale um conjunto completo de capacidades com um clique

📚 Navegação da série: O artigo anterior 22 · Agent Skills ensinou como escrever "manuais de operação especializados" para o Codex — uma skill ensina ao Codex "execute este tipo de tarefa seguindo estas etapas". Mas ao escrever você vai perceber um problema: skills, configurações MCP e integrações de apps são todas "peças separadas configuradas individualmente". Este artigo ensina como empacotá-las em plugins: um pacote completo que é instalado, removido e compartilhado como um todo. O próximo artigo 24 · Regras e Hooks explica como adicionar "pontos de verificação automáticos" ao Codex.

Pessoal, hoje vamos falar de algo que parece ser um "recurso de enfeite" mas é na verdade essencial — plugins.

As pessoas costumam pensar que plugins são uma funcionalidade de conveniência de "empacotamento" — podem ter ou não, melhor dominar as funcionalidades individuais primeiro. Sendo honesto, esse raciocínio está errado. Aprendi isso na prática: em abril de 2025 configurei um conjunto de "executar migrações de banco de dados, gerar documentação de schema" de skills para um projeto no Codex, mais um MCP server conectando ferramentas internas — levei quase duas horas. Duas semanas depois, mudei para outro repositório e queria reutilizar o mesmo conjunto — copiei arquivo por arquivo do projeto antigo e esqueci de uma seção de variáveis de ambiente no .mcp.json, a ferramenta nova simplesmente não conseguia se conectar — mais meia hora de diagnóstico. Gerenciar peças separadas é trabalhoso e fácil de esquecer coisas.

Plugins são a resposta oficial do Codex para esse problema: empacotar skills, integrações de apps e MCP servers separados em um pacote que pode ser distribuído, instalado e removido como um todo. Aquele conjunto que você montou com esforço no projeto A, quando empacotado como plugin, o projeto B e os computadores dos colegas ficam completos com uma única instalação — sem copiar diretórios, sem esquecer nada.

Ao terminar este artigo, você terá:

• Quais três tipos de coisas um plugin empacota, e como escolher entre ele e "skills avulsas" — uma tabela explica tudo
• Como navegar no "Diretório de Plugins (Plugin Directory)" e como instalar — dois caminhos, CLI e desktop app
• Do CLI: adicionar um marketplace, instalar um plugin, chamá-lo com @ — comandos completos e resultados esperados
• Como é a estrutura do diretório de um pacote de plugin (.codex-plugin/plugin.json + pastas de componentes), para quando você quiser criar o seu
• A "verificação de confiança" que você precisa fazer antes de instalar plugins de terceiros e confiar nos hooks de um plugin

⚠️ Todos os comandos, configurações, caminhos de diretório e comportamentos padrão mencionados seguem a documentação oficial do Codex; nomes de modelos, planos e itens marcados como "em breve" podem mudar com as versões — consulte o que está disponível localmente no momento da leitura.

---

01 Entendendo o que um plugin empacota

Conclusão direta: um plugin é uma "pasta autocontida" que reúne fluxos de trabalho reutilizáveis — skills, integrações de apps, MCP servers — em um pacote que pode ser instalado, removido e compartilhado como um todo.

Por que precisamos disso? Porque a configuração avulsa tem três problemas inevitáveis: reutilização entre projetos é trabalhosa, compartilhamento com equipes depende de trabalho manual, atualizações não podem ser distribuídas de forma unificada. A skill mais a configuração MCP que você montou em um projeto, para levar a outro, você tem que copiar cada arquivo; para dar a um colega, precisa explicar onde colocar cada arquivo, qual trecho da configuração modificar. Um plugin empacota tudo isso "em uma caixa", e a caixa inteira vai junto, a caixa inteira é passada adiante.

Analogia: o "quarto modelo empacotado" da loja de móveis. Você gostou do escritório do quarto modelo — mesa, estante, abajur, organizadores — se comprasse separado, você teria que buscar cada número de item, verificar dimensões e montar o layout sozinho; a loja empacota diretamente como "conjunto escritório", um pedido e tudo chega, montando conforme o diagrama fica igual ao quarto modelo. Os plugins do Codex seguem essa lógica: empacotar capacidades dispersas em um conjunto, instalar de uma vez, sem configurar cada peça individualmente.

A documentação oficial descreve claramente o que os plugins podem conter — apenas três tipos. Condensei em uma tabela:

Componente	O que é	Como usar após instalar
Skills (habilidades)	Instruções reutilizáveis para tarefas específicas, carregadas conforme necessário pelo Codex, seguindo etapas e scripts de referência	O Codex seleciona automaticamente conforme a descrição da tarefa, ou chame explicitamente com @
Apps (integrações de aplicativos)	Canais para conectar ferramentas como GitHub, Slack, Google Drive — permitindo que o Codex leia informações e execute operações	Na instalação ou no primeiro uso, siga as instruções para autorizar no ChatGPT
MCP servers	Serviços que fornecem mais ferramentas ao Codex ou compartilham informações — frequentemente de sistemas externos ao projeto local	Pode precisar de configuração adicional ou autenticação antes de usar

Note que plugins do Codex empacotam esses três tipos — skill, app, MCP. Isso é consistente com os artigos anteriores: o artigo 22 ensinou a escrever skills, os artigos anteriores falaram sobre MCP, e integrações de apps são a forma do Codex se conectar a serviços externos (Gmail, Drive, Slack). O que plugins fazem é agrupar os três.

Como escolher entre plugin e "escrever uma skill avulsa"? Seguindo a lógica da documentação oficial: ainda iterando em um único repositório, um único fluxo de trabalho pessoal, use skills locais primeiro; quando quiser compartilhar entre equipes, empacotar integrações de apps e configurações MCP juntas, ou publicar um pacote versionado estável, aí use plugins.

Dimensão	Skill avulsa (uso pessoal local)	Plugin
Mais adequado para	Uso em repositório único, fluxo de trabalho pessoal, experimentos rápidos	Compartilhamento entre equipes, empacotar app + MCP, publicação versionada
O que empacota	Geralmente apenas uma skill	Skills + apps + MCP, mais hooks de ciclo de vida
Como compartilhar	Copiar arquivos manualmente para outros	Via marketplace ou compartilhamento de workspace — outros instalam com um clique
Pode versionar?	Não enfatizado	Tem campo version, publicação por versão

A lógica de decisão em uma frase: para uso pessoal em um único fluxo de trabalho, skills avulsas são suficientes; para compartilhar com outros, empacotar muitas configurações em um pacote, ou publicar versões, então use plugins. Não crie plugins para skills de uso único — seria exagero.

💡 Resumo em uma frase: um plugin do Codex é uma caixa de conjunto que reúne skills, integrações de apps e MCP servers em algo que pode ser instalado e removido como um todo; para uso pessoal em um único fluxo, skills avulsas bastam; para compartilhar, empacotar conjuntos de configurações e publicar versões, use plugins.

---

02 Por que empacotar em um único pacote é melhor do que deixar disperso

A seção anterior explicou "o que é", esta seção complementa "por que vale a pena" — porque apenas conhecer o conceito pode ainda fazer você pensar "copiar alguns arquivos também não é tão difícil".

A verdadeira diferença está em três lugares. Vou explicar com cenários específicos:

Primeiro, reutilização entre projetos. Usando minha situação do início como exemplo: um conjunto de "migrações + gerar documentação de schema" em skills mais um MCP conectando ferramentas internas, quando avulso e muda de projeto, é preciso copiar manualmente skills/ e .mcp.json, e uma vez esquecida aquela seção de variáveis de ambiente do MCP, a ferramenta nova simplesmente não consegue se conectar. Após empacotar em plugin, instalar de um marketplace no novo projeto e tudo fica pronto — nenhuma configuração é esquecida.

Segundo, compartilhamento com equipes. Compartilhar configurações avulsas com colegas basicamente depende de "você copia esta pasta, skill coloca aqui, aquela seção do MCP lembra de adicionar na configuração" — um monte de explicação verbal, e com alta probabilidade o outro vai configurar errado. Plugins são diferentes: você publica no marketplace (mesmo um marketplace privado interno do repositório), ou compartilha diretamente com membros do workspace no Codex App, outros clicam e instalam com as configurações completamente consistentes — sem "funciona na minha máquina mas não na sua".

Terceiro, gerenciamento unificado e versionamento. Plugins têm campo version — são pacotes legítimos que podem ser versionados; após instalados, o switch de cada plugin, se os MCP servers que trouxe devem estar habilitados, e como configurar aprovações de ferramentas, tudo pode ser ajustado individualmente na sua configuração do Codex sem modificar o plugin em si. Modificar uma configuração avulsa, quem já usou simplesmente não sabe, você só pode avisar todo mundo individualmente.

Analogia: instalar um "perfil de configuração / arquivo de configurações" no celular com um toque. Quando a empresa configura um celular de trabalho para você, não pede para você configurar manualmente o Wi-Fi, e-mail, VPN, certificado um por um — envia um "arquivo de perfil de configuração", você toca em um lugar, todas as configurações entram de uma vez, para revogar basta excluir todo o perfil. Plugins em relação a muitas configurações avulsas são como esse perfil de configuração em relação a configurações manuais uma a uma — instalar de uma vez, gerenciar de forma unificada, remover como um todo.

Comparação entre avulso e plugin nessas três dimensões:

O que você quer fazer	❌ Configuração avulsa	✅ Plugin
Mover para novo projeto	Copiar cada arquivo manualmente, fácil de esquecer MCP/variáveis de ambiente	Instalar do marketplace, tudo fica pronto
Dar para colega usar	Explicar verbalmente onde colocar e o que modificar	Publicar no marketplace ou compartilhar no workspace, outro instala com um clique
Gerenciamento posterior	Modificar uma coisa sem poder notificar, depende de avisar todo mundo	Com número de versão, switches e aprovações ajustáveis de forma unificada na configuração

Sendo honesto, para uma pessoa um projeto, os benefícios dos plugins não são muito sentidos; quando há muitas pessoas, muitos projetos e ainda com apps e MCP misturados, o avulso começa a atrasar. Depois de liderar equipes, normalmente você muda completamente para plugins — só para o item "novo colaborador configurar um conjunto de ferramentas internas no primeiro dia", você consegue reduzir de meia hora de explicação verbal para um único comando de instalação.

💡 Resumo em uma frase: o real valor dos plugins está em "escala" — reutilização entre projetos, compartilhamento com equipes, gerenciamento unificado e versionamento — quando avulso, tudo depende de trabalho manual; com plugins, é um clique; quanto mais pessoas e projetos, mais configurações complexas, maior essa diferença.

---

03 Diretório de Plugins: a "loja de aplicativos" do Codex

Sabendo o que são plugins, a próxima pergunta é: onde pego plugins que outros criaram? A resposta é o "Plugin Directory (Diretório de Plugins)" — a interface integrada do Codex para navegar e instalar.

Ele divide os plugins em três grupos — memorize os nomes, quando você ver vai entender imediatamente:

Analogia: três áreas em uma loja de aplicativos para celular. Uma é "recomendações dos editores" (selecionados cuidadosamente pelo oficial para todos), uma é "compartilhado por família / equipe" (outros membros do seu workspace compartilharam com você), e uma é "meus apps" (apps que você mesmo publicou ou adicionou). O diretório de plugins do Codex corresponde exatamente a isso:

Área	O que contém
Curated by OpenAI (seleção OpenAI)	Plugins selecionados pela OpenAI, disponíveis para todos os usuários do Codex — os mais confiáveis
Shared with you (compartilhados com você)	Plugins que outros membros do seu workspace ChatGPT compartilharam com você
Created by you (criados por você)	Plugins que você criou ou adicionou ao seu próprio workspace

Navegar e instalar tem dois caminhos — desktop app e CLI ambos funcionam; escolha o que preferir:

Desktop App: abra o painel Plugins no Codex App, navegue, pesquise, instale plugins selecionados diretamente — clique no "+" nos detalhes ou em Add to Codex para instalar.

CLI: depois de iniciar, digite o seguinte para abrir o navegador de plugins (note que é plural plugins):

codex
/plugins

O navegador de plugins do CLI agrupa por "marketplace" — use as guias de marketplace para alternar entre diferentes fontes; clique em um plugin para ver os detalhes, pode instalar e desinstalar; em plugins já instalados, pressione Space para alternar o estado de ativação (instalado mas temporariamente desativado).

Após instalar, como usar? A documentação oficial oferece dois modos de chamada — dois mentalidades diferentes:

• Apenas descreva o resultado que você quer. Por exemplo, "resumir e-mails não lidos do Gmail de hoje", "pegar as notas de lançamento mais recentes do Google Drive" — você diz o que quer, deixe o Codex escolher qual ferramenta instalada usar.
• Use @ para apontar para um plugin específico ou uma de suas skills. Quando você sabe claramente qual plugin ou skill usar, digite @ para chamá-la explicitamente sem deixar o Codex adivinhar.

Você deve reconhecer esse @ — no artigo 22 sobre skills, foi exatamente assim que as skills eram chamadas explicitamente. Skills empacotadas em plugins são chamadas da mesma forma que skills escritas individualmente — apenas vêm de um conjunto de plugin.

💡 Resumo em uma frase: o diretório de plugins é a loja de aplicativos integrada do Codex, com três áreas "seleção OpenAI / compartilhados com você / criados por você"; tanto o painel Plugins do desktop app como /plugins no CLI permitem navegar e instalar — após instalar, descreva a tarefa para o Codex selecionar, ou use @ para apontar explicitamente.

---

04 Instalar um plugin: como permissões e dados fluem

Clicar em "instalar" no /plugins e pronto? Não é tão simples — esta seção precisa explicar claramente que "instalar plugin ≠ autorizar automaticamente", este é o lugar onde iniciantes mais facilmente assumem coisas erroneamente.

A documentação oficial é muito clara sobre o princípio: instalar um plugin apenas torna seus fluxos de trabalho disponíveis no Codex, mas suas configurações de aprovação existentes ainda se aplicam. Em outras palavras, os plugins não contornam o conjunto de permissões que você configurou no artigo 15 ou a linha de segurança que você manteve no artigo 16 simplesmente por terem sido "instalados".

Cada um dos três tipos de componente tem um ritmo de entrada diferente:

Componente	Após instalar
Skills	Disponíveis imediatamente — sem autorização adicional necessária
Apps	Pode solicitar que você instale ou faça login nesse app no ChatGPT, na instalação ou no primeiro uso
MCP servers	Pode precisar de configuração adicional ou autenticação antes de funcionar

Viu? Skills ficam disponíveis imediatamente, apps e MCP podem exigir que você autorize mais uma etapa antes de usar. Então após instalar um plugin, você precisa saber quais tipos de componentes ele contém para saber se ainda falta uma etapa de autorização.

Há também uma frase relacionada a dados que deve ser memorizada: quando o Codex envia dados através de um app empacotado em um plugin, os termos e políticas de privacidade daquele app entram em vigor. Ou seja, os serviços externos que o plugin conecta (GitHub, Slack, Drive), como eles usam os dados é governado pelas políticas deles próprios — isso está diretamente ligado ao quanto você confia nesse serviço externo.

Analogia: instalar um app de casa inteligente no celular, as autorizações são dadas em etapas. Você instala um app de casa inteligente (o plugin em si instalado), mas para ele se conectar à fechadura inteligente, você ainda precisa autorizar separadamente por scan de QR code na fechadura (primeira autorização do app integrado); para ele acessar armazenamento em nuvem da câmera, é outro login de conta (autenticação adicional do MCP). Instalar o app é um passo, entregar a permissão de cada dispositivo externo são outros passos — o modelo de permissões dos plugins funciona assim; instalar é instalar, autorizar é autorizar, bem separados.

Não quer mais um determinado plugin — duas formas de lidar:

• Desinstalar completamente: reabra o plugin no navegador, selecione Uninstall plugin. Atenção — desinstalar apenas remove o plugin em si; os apps que ele instalou ainda ficam no ChatGPT e você mesmo precisa gerenciá-los no ChatGPT.
• Manter mas desligar: quer manter o plugin mas não usá-lo temporariamente — vá em ~/.codex/config.toml e configure aquele item como enabled = false, depois reinicie o Codex:

[plugins."gmail@openai-curated"]
enabled = false

Observe a sintaxe da chave — nome-do-plugin@nome-do-marketplace, gmail é o plugin e openai-curated é o marketplace. Pressionar Space em um plugin instalado no CLI para alternar o estado de ativação é a mesma coisa que modificar essa configuração.

💡 Resumo em uma frase: instalar plugin não é autorizar automaticamente — skills ficam disponíveis imediatamente, apps e MCP podem precisar de autorização adicional antes de usar, as configurações de aprovação originais ainda se aplicam ao plugin; para não querer mais, desinstalar remove apenas o plugin, para manter desabilitado configure enabled = false em config.toml e reinicie.

---

05 Prática: adicionar um marketplace, instalar um plugin e usá-lo

Apenas ler sem praticar é ineficaz. Esta seção te guia para adicionar um marketplace pelo CLI, instalar um plugin local e chamá-lo com @ — sem depender de nenhum ambiente complexo, basta copiar e executar.

Diferente de clicar no desktop app, gerenciar marketplaces no CLI usa o grupo de subcomandos codex plugin marketplace — são comandos de terminal, não comandos com barra dentro de uma sessão, não confunda.

Passo 1: adicionar um marketplace

O mais comum é adicionar via GitHub. Substitua owner/repo pelo nome real do repositório no GitHub:

codex plugin marketplace add owner/repo

A documentação oficial também suporta outras fontes e parâmetros:

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-root

As fontes podem ser abreviação GitHub (owner/repo ou owner/repo@ref), URL Git HTTP/HTTPS, URL Git SSH ou diretório raiz de marketplace local. --ref fixa uma ref Git específica; --sparse PATH faz o repositório GitHub usar checkout esparso, e só é válido para fontes Git.

Esperado: o Codex registra este marketplace; a partir daí ele se torna uma fonte disponível no diretório de plugins. Nesta etapa nenhum plugin foi instalado — apenas tornou visível este "prateleira".

Passo 2: ver quais marketplaces estão registrados agora

codex plugin marketplace list

Esperado: lista cada marketplace que o Codex está considerando, junto com o caminho raiz resolvido — incluindo o marketplace padrão local e snapshots dos marketplaces configurados. Ver o marketplace que você acabou de adicionar na lista = foi adicionado corretamente.

Reconheça também alguns outros comandos de gerenciamento (memorize para usar quando necessário):

codex plugin marketplace upgrade                 # Atualizar todos os marketplaces
codex plugin marketplace upgrade marketplace-name # Atualizar um marketplace específico
codex plugin marketplace remove marketplace-name  # Remover um marketplace específico

Passo 3: abrir o navegador de plugins e instalar um plugin

Inicie uma sessão e abra o navegador de plugins:

codex
/plugins

Esperado: o navegador de plugins agrupado por marketplace aparece; use as guias de marketplace para ir ao marketplace que você acabou de adicionar. Clique em um plugin para ver os detalhes e selecione Install plugin para instalar.

Passo 4: chamar o plugin com @

A documentação oficial é explícita — após instalar o plugin, abra um novo thread e então use o Codex com ele. Em seguida, na caixa de entrada descreva a tarefa diretamente ou digite @ para apontar para este plugin / uma de suas skills:

@<nome-do-plugin-ou-sua-skill>

Esperado: o Codex chama a capacidade correspondente a este plugin. Se ele contém apps ou MCP, pode solicitar que você faça autorização ou autenticação primeiro no ChatGPT — siga as instruções para concluir, e poderá usar.

Completando esses passos, você verificou pessoalmente a cadeia completa de "adicionar marketplace → instalar plugin → chamar". No futuro, instalar qualquer plugin é essencialmente este fluxo; o desktop app apenas transforma esses passos em cliques na interface gráfica.

⚠️ Se após instalar o @ não funcionar, primeiro confirme que você abriu um novo thread antes de chamá-lo (o oficial exige novo thread após instalação); com apps/MCP confirme se o passo de autorização / autenticação foi concluído.

💡 Resumo em uma frase: adicionar marketplace pelo CLI usa codex plugin marketplace add (comando de terminal), instalar plugin seleciona Install em /plugins, chamada inicia novo thread para descrever a tarefa ou @ para apontar — verificar pessoalmente esta cadeia completa uma vez vale mais do que memorizar dez comandos.

---

06 Quer criar o seu? Conheça primeiro a estrutura do diretório de um plugin

Tudo antes foi "usar plugins de outros" — mas eventualmente você vai querer "será que consigo empacotar minhas próprias skills e configurações MCP em um plugin". Esta seção não ensina você a criar um plugin de nível de publicação do zero (isso é material separado), apenas te faz reconhecer como é a estrutura de um diretório de plugin, para que você entenda ao ver e tenha uma ideia.

Primeiro, o caminho mais fácil: a documentação oficial tem uma skill @plugin-creator integrada, especificamente para montar o scaffolding de plugins — pode gerar o manifesto .codex-plugin/plugin.json necessário, e também ajudar a gerar uma entrada de marketplace local para testes. Se você já tem uma pasta de plugin, pode usá-la para conectar o plugin ao marketplace local. Para começar, é mais rápido por ela.

Manualmente, um plugin tem essencialmente duas partes: um manifesto de "carteira de identidade" + pastas de componentes.

A carteira de identidade é .codex-plugin/plugin.json, na forma mínima:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

O mais importante é name — é o identificador do plugin e o namespace dos componentes; a documentação oficial exige usar kebab-case (letras minúsculas e hifens, como my-first-plugin) para um nome estável. Os campos skills, mcpServers, apps, hooks apontam para os componentes correspondentes incluídos, com caminhos relativos à raiz do plugin começando com ./.

As pastas de componentes ficam no diretório raiz do plugin, organizadas por tipo. Organizei as convenções de estrutura oficiais em uma tabela:

O que você quer adicionar	Onde colocar	Campo correspondente no manifesto
skill	skills/<nome>/SKILL.md	skills
hook de ciclo de vida	hooks/hooks.json	hooks (pode omitir se usar caminho padrão)
configuração de MCP server	.mcp.json na raiz	mcpServers
app / conector	.app.json na raiz	apps
ícone, capturas de tela e outros ativos	em ./assets/	referenciado em interface

O plugin completo fica mais ou menos assim:

my-first-plugin/
├── .codex-plugin/
│   └── plugin.json        ← Carteira de identidade, apenas ela aqui
├── skills/
│   └── hello/
│       └── SKILL.md
├── .mcp.json              ← Configuração MCP, na raiz
├── .app.json             ← Integração de app, na raiz
└── hooks/
    └── hooks.json

Aqui há um erro enfatizado explicitamente pela documentação oficial que iniciantes inevitavelmente cometem — vou destacar:

Apenas o plugin.json fica dentro de .codex-plugin/. Coloque skills/, hooks/, assets/, .mcp.json e .app.json todos no nível raiz do plugin.

Em outras palavras: dentro da pasta .codex-plugin/ só pode ficar o plugin.json, todas as outras pastas de componentes ficam no diretório raiz do plugin, no mesmo nível que .codex-plugin/. Este erro é muito fácil de cometer no primeiro empacotamento — uma vez que skills/ acaba dentro de .codex-plugin/, o plugin pode carregar mas as skills nunca aparecem, e você fica diagnosticando por um bom tempo antes de perceber que o local estava errado.

Dois padrões convenientes para memorizar:

• Hooks com caminho padrão não precisam do campo. Se seu hook está em ./hooks/hooks.json, não precisa escrever o campo hooks no manifesto — o Codex verifica automaticamente este arquivo padrão.
• Manifesto de publicação é muito mais rico. Plugins que serão realmente publicados geralmente têm author, homepage, license, e um objeto interface (controlando nome de exibição, descrição, ícone, cor de marca, prompts iniciais — esses são "informações de vitrine"). Esses campos são opcionais; apenas jogar para você mesmo usar o manifesto mínimo basta.

Você provavelmente notou que esta estrutura de diretório é quase idêntica ao diretório de skills do artigo 22 e ao .mcp.json do MCP mencionado anteriormente. Isso não é coincidência — plugins são essencialmente "reunir essas configurações espalhadas em uma pasta independente com o mesmo formato". Por isso a documentação diz "ainda iterando em um repositório, use skills locais; para compartilhar, empacote como plugin" — os formatos são compatíveis, apenas mova.

💡 Resumo em uma frase: plugin = .codex-plugin/plugin.json (carteira de identidade, name em kebab-case define o namespace) + pastas de componentes no diretório raiz; memorize a regra de ferro — .codex-plugin/ só pode ter plugin.json, skills / hooks / .mcp.json / .app.json todos ficam na raiz; para começar, use @plugin-creator para scaffolding.

---

07 Verificação de confiança: plugins podem executar código, hooks precisam da sua aprovação individual

Esta é a seção mais importante de todo o artigo, e o lugar onde iniciantes mais facilmente ficam descuidados. Todas as conveniências anteriores são construídas sobre uma premissa: você confia na fonte deste plugin.

Lembre-se do julgamento de segurança do artigo 16 — as habilidades daquele artigo se aplicam igualmente aqui. A razão é direta: um plugin pode trazer integrações de apps (pode ler e escrever nas suas contas externas), MCP servers (ferramentas externas disponíveis automaticamente) e hooks de ciclo de vida (scripts que rodam automaticamente em eventos específicos). Uma vez habilitados, eles operam dentro dos seus limites de permissão.

Mas o Codex tem um design aqui que merece muito elogio — hooks não são automaticamente confiáveis apenas por você instalar e habilitar o plugin. Traduzindo as palavras oficiais:

(Paráfrase do original oficial) Instalar ou habilitar um plugin não confia automaticamente nos seus hooks. Os hooks que um plugin empacota são hooks não gerenciados (non-managed), portanto o Codex os ignora até que o usuário revise e confie na definição atual dos hooks.

Por que isso é importante? Significa que mesmo se você instalar acidentalmente um plugin com hooks maliciosos, aqueles hooks não rodam imediatamente — o Codex vai pausar, esperar você revisar pessoalmente essas definições de hook e confirmar que confia nelas antes de prosseguir. Este "bloqueio de confiança que funciona mesmo após instalar" é a camada mais crítica de segurança dos plugins. Quanto ao mecanismo de eventos de hook e revisão de confiança, o próximo artigo 24 · Regras e Hooks vai detalhar isso completamente; aqui apenas memorize a conclusão "os hooks de plugins não são confiáveis por padrão".

Analogia: receber uma caixa de alto-falante inteligente de um desconhecido — conectar na tomada não é o mesmo que conectar à internet. Você recebe um alto-falante inteligente de uma marca desconhecida, conecta na tomada e ele acende (plugin instalado, skills disponíveis), mas para ele se conectar ao seu Wi-Fi e acessar suas contas, você precisa aprovar um item por um no App — sem aprovar, é apenas uma caixa que acende, sem acesso à sua rede e dados. Os hooks de plugins têm essa natureza: entrou, mas "deixar rodar automaticamente" é sua aprovação separada.

Três itens de verificação para "antes de instalar plugins de terceiros" — vale tratá-los como regras rígidas:

Item de verificação	O que fazer
A fonte é confiável?	Prefira a área de seleção OpenAI; para compartilhados no workspace, veja quem compartilhou; para repositórios públicos desconhecidos, se tiver dúvidas, não adicione o marketplace
O que ele contém?	Antes de instalar, veja nos detalhes do plugin se tem apps / MCP / hooks — cada um representa diferentes níveis de permissão
Os hooks foram revisados?	Para plugins com hooks, quando o Codex solicitar revisão de confiança, leia cada hook com cuidado antes de confiar — não aprove cegamente

Alguns designs oficiais que podem te dar um pouco mais de tranquilidade: plugins compartilhados no workspace ficam dentro dos limites do workspace e organização — contas não registradas neste workspace não conseguem acessar; hooks não são confiáveis por padrão — você precisa revisar antes de rodar; instalar plugin não contorna suas configurações de aprovação existentes. Mas esses recursos não substituem seu próprio julgamento — o fundamental ainda é "instale apenas de fontes em que você confia".

Por fim, um comentário sobre o estado atual (sujeito a mudanças com as versões — siga a documentação oficial): a documentação oficial menciona explicitamente que adicionar plugins ao diretório público oficial e gerenciamento de autopublicação atualmente ainda é "em breve (coming soon)". Isso significa que atualmente plugins de terceiros são distribuídos principalmente pelos dois caminhos de "marketplace de repositório" e "compartilhamento no workspace" — o que na verdade torna as fontes relativamente controladas. O que você instala é geralmente de sua própria equipe ou de partes em quem você claramente confia, não de um mar aberto.

💡 Resumo em uma frase: plugins podem trazer apps, MCP e hooks para dentro dos seus limites de permissão, mas o Codex tem uma barreira crítica — os hooks de um plugin não são confiáveis por padrão, apenas rodam após você revisá-los; antes de instalar terceiros verifique três itens (fonte, o que contém, hooks foram revisados), seleção OpenAI é a mais confiável, fontes desconhecidas é melhor não instalar.

---

08 Resumo

Este artigo cobriu os "plugins" do Codex de conceito até prática — sua essência é empacotar skills, integrações de apps e MCP servers dispersos em uma caixa de conjunto que pode ser instalada, distribuída e versionada como um todo.

Revisão dos pontos-chave:

O que você quer fazer	Usar o quê	Ponto-chave
Entender o que é um plugin	plugin = conjunto de skills + apps + MCP	Fluxo de trabalho único, use skill; para compartilhar/empacotar/versionar, use plugin
Pegar plugins de outros	Diretório de plugins	Três áreas: seleção OpenAI / compartilhados com você / criados por você
Navegar e instalar	Painel Plugins do app / /plugins no CLI	Adicionar marketplace no CLI usa codex plugin marketplace add
Chamar plugin	Descreva a tarefa ou @ para apontar	Após instalar abra novo thread para usar; app/MCP pode precisar de autorização primeiro
Desativar um plugin	config.toml	[plugins."nome@marketplace"] enabled = false então reinicie
Criar seu próprio	.codex-plugin/plugin.json + pastas de componentes	.codex-plugin/ só pode ter plugin.json; use @plugin-creator para scaffolding
Instalar de terceiros	Verificação de três itens de confiança	Pode trazer app/MCP/hook; hooks não são confiáveis por padrão, somente após revisão

A imagem abaixo reúne as duas linhas principais deste artigo: à esquerda, o fluxo de uso "adicionar marketplace → instalar plugin → chamar"; à direita, os três tipos de componentes que uma caixa de plugin empacota mais hooks, e suas "formas de entrada" após instalação.

O que esta imagem mostra: a fileira superior é o fluxo de quatro passos de "usuário" do marketplace até chamar; a fileira inferior é o que está dentro de uma caixa de plugin — três tipos de componentes mais hooks, cada um com seu nível de acesso indicado, para entender de um olhar "qual fica disponível imediatamente após instalar, qual ainda requer que você aprove mais uma etapa".

Você agora deve ser capaz de: entender como escolher entre plugin e skill avulsa; usar "adicionar marketplace → instalar plugin → chamar com @" para obter capacidades prontas do diretório de plugins; entender o nível de autorização de cada app/MCP/hook ao instalar um plugin; reconhecer a estrutura de diretório de um plugin, e saber a verificação de confiança necessária antes de instalar plugins de terceiros e confiar em seus hooks. Esse conjunto de capacidades permite que você não precise configurar tudo do zero — use conjuntos prontos do marketplace diretamente.

Do AGENTS.md do artigo 11, ao MCP, à skill do artigo 22, e agora a este artigo usando plugins para gerenciá-los todos — as "capacitações" que você instalou para o Codex estão basicamente completas.

---

O próximo artigo 24 "Regras e Hooks" — neste artigo mencionei repetidamente "os hooks de um plugin não são confiáveis por padrão, só rodam após você revisá-los", mas o que são hooks em si, em quais eventos podem funcionar, e como é essa "revisão de confiança", ainda não foi explicado. O próximo artigo trata especificamente disso: como adicionar "pontos de verificação automáticos" ao Codex — intervindo automaticamente quando ele lê arquivos, executa comandos e inicia sessões, transformando as regras de "depender da consciência dele" para "imposição pela máquina". Pense: se toda vez antes de commitar pudesse rodar automaticamente uma verificação, sem precisar você lembrar — não seria mais tranquilo?

---

Leitura recomendada

• Tabela de referência de comandos e configuração
• Codex Cloud: jogue o trabalho na nuvem e espere o resultado tomando café
• Integração Slack / Linear e SDK: invocar o Codex de outros lugares e incorporá-lo ao seu produto