Português

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.

Competência de criação de plugins no ChatGPT

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.

Como invocar a competência plugin-creator

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:

  1. Abra o ChatGPT.
  2. Abra Definições.
  3. Selecione Segurança e início de sessão.
  4. Ative o Modo de programador.

Em seguida, crie a aplicação no modo de programador:

  1. Abra Definições → Plugins ou a página Plugins.
  2. Selecione o botão de adição.
  3. Preencha a janela modal para criar uma aplicação em modo de programador para o seu servidor MCP.
  4. 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:

  1. Reveja .app.json e confirme que aponta para o ID plugin_asdk_app... correto.
  2. Reveja .codex-plugin/plugin.json e certifique-se de que o respetivo campo apps aponta para ./.app.json.
  3. Adicione quaisquer competências incluídas em skills/ se o plugin tiver de incluir fluxos de trabalho repetíveis juntamente com a aplicação.
  4. 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.

Marketplace local personalizado no Diretório de Plugins

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

As 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-name

codex 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.

  1. Crie uma pasta de plugin com um manifesto em .codex-plugin/plugin.json.
mkdir -p my-first-plugin/.codex-plugin

my-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.

  1. Adicione uma competência em skills/<skill-name>/SKILL.md.
mkdir -p my-first-plugin/skills/hello

my-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.
  1. Adicione o plugin a um marketplace. Utilize @plugin-creator para 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-plugin
Passo 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-plugin
Passo 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.

  1. Abra Plugins na aplicação ChatGPT para computador.
  2. Aceda a Criados por si e abra a página de detalhes do plugin.
  3. Selecione Partilhar.
  4. Adicione membros ou grupos do espaço de trabalho, ou copie uma ligação de partilha.
  5. 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 = false

Metadados 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 name ao nível superior para identificar o marketplace.
  • Utilize interface.displayName para o título do marketplace apresentado na aplicação ChatGPT para computador.
  • Adicione um objeto por plugin em plugins para criar uma lista selecionada que a aplicação apresenta sob esse título do marketplace.
  • Aponte o source.path de 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.path relativo à raiz do marketplace, comece-o com ./ e mantenha-o dentro dessa raiz.
  • Para entradas locais, source também pode ser um caminho como cadeia de texto simples, por exemplo "./plugins/my-plugin".
  • Inclua sempre policy.installation, policy.authentication e category em cada entrada de plugin.
  • Utilize valores de policy.installation como AVAILABLE, INSTALLED_BY_DEFAULT ou NOT_AVAILABLE.
  • Utilize policy.authentication para 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, screenshots

Apenas 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, version e description identificam o plugin.
  • author, homepage, repository, license e keywords fornecem metadados do editor e de descoberta.
  • skills, mcpServers, apps e hooks apontam para componentes incluídos relativamente à raiz do plugin.
  • interface controla 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, shortDescription e longDescription controlam o título e o texto descritivo.
  • developerName, category e capabilities adicionam metadados do editor e das capacidades.
  • websiteURL, privacyPolicyURL e termsOfServiceURL fornecem ligações externas.
  • defaultPrompt, brandColor, composerIcon, logo e screenshots controlam 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, logo e screenshots em ./assets/ sempre que possível.
  • Utilize skills para pastas de competências incluídas, apps para .app.json, mcpServers para .mcp.json e hooks para 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 entrada hooks em .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.