Carregue seu plugin e envie-o para revisão

Se você criou um plugin e quer compartilhá-lo com mais pessoas, o diretório de plugins ajuda os usuários a encontrá-lo e usá-lo no ChatGPT e no Codex. Seu plugin pode incluir conexões MCP, habilidades ou as duas coisas.

Carregue o pacote que você já criou como arquivo ZIP, corrija os problemas apontados nas verificações automáticas e envie o pacote para revisão. Após a aprovação, você escolhe quando publicá-lo.

Após a primeira publicação, as alterações no servidor MCP são detectadas automaticamente, e as atualizações elegíveis entram em vigor assim que passam nas verificações automáticas. Você não precisa carregar um novo ZIP do plugin nem publicar cada atualização. Alterações nos metadados ou nas habilidades do plugin ainda exigem um novo ZIP.

Antes do envio, siga o guia de criação de pacotes de plugins e leia as diretrizes para plugins. Para obter ajuda na preparação do envio, use o Plugin Creator, disponível no diretório de plugins.

Visão geral dos plugins. Na página Plug-ins, inicie um envio e acompanhe a publicação, o andamento da revisão e a configuração do MCP.

Para enviar servidores MCP remotos, escolha Com MCP e use um endpoint HTTPS público e estável. Se o plugin executar um servidor MCP local ou precisar ser executado no computador, consulte Envio de plugins exclusivos para desktop.

1. Carregue o ZIP do plugin

Confirme o acesso e a identidade de publicação

Selecione a organização e o projeto aos quais o plugin pertencerá. Os proprietários da organização podem enviar plugins. Os demais membros precisam da permissão Apps Management Write, que um proprietário pode conceder por meio das funções da organização.

Conclua a verificação de pessoa física ou jurídica nas configurações da organização para publicar em seu nome ou em nome de uma empresa.

Crie o rascunho

Se o plugin usar um servidor MCP, inclua-o no ZIP inicial. No momento, não é possível adicionar um servidor MCP a um plugin existente que contenha apenas habilidades.

1. Abra Plug-ins e selecione Carregar plugin novo ou existente.
2. Escolha sua Identidade de desenvolvedor verificada. O diretório exibe o nome associado a essa identidade.
3. Selecione Carregar plugin e escolha o arquivo ZIP.
4. Após a validação, a página de detalhes do plugin se abre com o novo rascunho.

Se a validação falhar, corrija os erros indicados no pacote e carregue-o novamente. Mantenha credenciais privadas e segredos fora do ZIP.

2. Confira as verificações e corrija os problemas

Depois que você carrega o ZIP, a página de detalhes do plugin mostra o andamento e os resultados das verificações automáticas para que você possa corrigir os problemas antes do envio para revisão. Metadados e habilidades mostra a versão do pacote carregado, e MCPs mostra o servidor conectado e as ferramentas verificadas. Essas informações ficam em seções separadas porque alterações no pacote exigem um novo ZIP, enquanto alterações nas ferramentas hospedadas são verificadas diretamente no servidor.

Confira os metadados

1. Abra Metadados e habilidades. A versão carregada mais recentemente aparece automaticamente.
2. Aguarde o término das verificações de metadados e confira se há ocorrências em Problemas.
3. Selecione Copiar problemas para usar os resultados no seu fluxo de desenvolvimento.
4. Corrija os campos afetados no pacote, selecione Carregar plugin para corrigir problemas e carregue o ZIP corrigido. Confira os novos resultados.

Dica: Peça ao Codex ou ao ChatGPT que examine o pacote e os resultados copiados, explique os problemas e sugira correções nos metadados ou nas habilidades.

Resultados da verificação de metadados. Confira os resultados da versão selecionada do pacote e carregue um ZIP corrigido.

Os detalhes do pacote são somente leitura nesta página. Edite-os no pacote de origem com a ajuda da referência dos campos do pacote. As URLs públicas devem estar acessíveis e identificar o mesmo responsável pela publicação indicado no envio.

Confira as habilidades

Se o pacote contiver habilidades, confira os problemas apontados em Metadados e habilidades. Abra cada resultado para ver a habilidade afetada e o que precisa mudar. Em seguida, atualize as instruções ou os arquivos de apoio da habilidade e carregue o ZIP corrigido. Confira os novos resultados. As verificações obrigatórias das habilidades precisam ser concluídas com sucesso antes do envio.

Conecte e verifique o servidor MCP

O pacote pode declarar vários servidores MCP, mas cada plugin só pode ter um servidor MCP conectado. Siga as etapas abaixo na primeira vez que conectar esse servidor. Use Reconectar se houver algum problema na conexão. Para alterações nas ferramentas, siga as instruções em Verifique as alterações mais recentes.

1. Abra MCPs e selecione o servidor que deseja conectar.
2. Selecione Conectar para abrir Conectar servidor MCP.
3. Confira a URL do servidor MCP, a Autenticação e as configurações aplicáveis.
4. Conclua o desafio de verificação do domínio exibido no portal. Depois, conecte o servidor e conclua a autenticação, se necessário.
5. Aguarde o término da verificação automática das ferramentas e examine as ferramentas encontradas. Abra Problemas para consultar os resultados.
6. Corrija os problemas de conexão ou os problemas identificados no servidor. Depois, use Reconectar ou Verificar novamente, conforme o caso, e confira os novos resultados.

Conexão MCP e verificação do domínio. Conecte o servidor e conclua a verificação do domínio antes de conferir as ferramentas encontradas.

Para um plugin MCP local aprovado, escolha Somente habilidades e siga as instruções de envio para plugins exclusivos para desktop.

O portal salva o envio como rascunho enquanto você preenche o formulário.

Se a conexão ou a verificação falhar, confira a disponibilidade do endpoint e a autenticação. Depois, reconecte o servidor ou execute a verificação novamente. Antes do envio, resolva as pendências indicadas em Concluir configuração do MCP e corrija as falhas de conexão. Consulte as diretrizes para plugins para ver os requisitos de URL do servidor MCP, autenticação, metadados das ferramentas e interface do usuário.

Configure a autenticação para o envio

O portal lê as configurações avançadas de autenticação do arquivo mcp.json do pacote. Configure o método de autenticação, o registro do cliente OAuth, os endpoints e os escopos seguindo a referência de autenticação MCP. O painel de conexão exibe essas configurações, mas não oferece um editor de configurações avançadas de OAuth.

Para alterar a configuração, atualize mcp.json, selecione Carregar nova versão e confira as configurações salvas em MCPs antes de conectar o servidor. Um registro de cliente existente pode impedir a alteração das credenciais. Confira a conexão salva, pois o upload pode não substituir o cliente existente.

Para OAuth, escolha um método de registro compatível com o seu provedor:

Para um cliente registrado:

1. Registre no provedor OAuth a URL de callback usada pelo fluxo de conexão.
2. Abra MCPs, selecione o servidor e escolha Conectar.
3. Preencha Segredo do cliente OAuth se o cliente exigir um segredo. O campo aparece para um cliente OAuth fornecido, exceto quando tokenEndpointAuthMethod é "none".
4. Conclua a verificação do domínio, se necessário, selecione Conectar e autorize a conta usada para conectar e verificar o servidor.
5. Aguarde o término da verificação e resolva os problemas apontados na conexão ou nas ferramentas.

Não coloque o segredo do cliente em mcp.json. O manifesto rejeita clientSecret. O segredo do cliente autentica seu aplicativo OAuth. Ele é diferente da senha da conta, de um token de acesso e das credenciais de login da equipe de revisão.

Se a descoberta OAuth não fornecer os endpoints necessários, defina valores explícitos para authorizationUrl e tokenUrl em mcp.json. Confira se o ID do cliente, o método de autenticação do endpoint de token, os escopos e a URL de callback correspondem à configuração do provedor.

Limitações de autenticação

O formulário de conexão do portal aceita acesso sem autenticação, acesso com OAuth e acesso misto, que combina os dois. Embora o schema do manifesto aceite autenticação por chave de API, o portal não oferece um fluxo de conexão por chave de API nem um campo para inserir um token bearer. Essa limitação também se aplica a declarações de chave de API com autenticação Basic ou cabeçalho personalizado. Apenas carregar uma declaração de chave de API não conclui a configuração do MCP. Entre em contato com a OpenAI se o envio exigir esse método de autenticação.

Não inclua um token nos headers do servidor para contornar essa limitação. O envio para o diretório público rejeita cabeçalhos de servidor que não estejam vazios. Não configure um servidor protegido como type: "none".

O schema aceita private_key_jwt para um cliente OAuth fornecido, mas esse valor, por si só, não configura as chaves de assinatura. Este guia do portal não descreve o procedimento para configurar essas chaves. Confirme a configuração necessária com a OpenAI antes de usar esse método no envio.

Detalhes da verificação do domínio

Para verificar o domínio, hospede o token exato do desafio como texto simples na URL exibida no portal:

https://<challenge-base-host>/.well-known/openai-apps-challenge

Retorne apenas o token exato, sem usar JSON nem uma lista de tokens. A base do desafio deve ser uma origem HTTPS no nome de host do servidor MCP ou em um domínio pai elegível. Os caminhos são ignorados. Se outro plugin usar a mesma URL de desafio, use uma origem permitida em um domínio pai ou um nome de host diferente para preservar o token do outro plugin. Entre em contato com o suporte se nenhuma dessas opções for possível.

3. Envie para revisão

Depois de conferir os resultados das verificações automáticas, preencha as informações de que a equipe de revisão precisa para testar o plugin e envie o rascunho selecionado. Primeiro, conclua a configuração obrigatória e corrija os erros de validação. Os demais problemas apontados nas verificações automáticas podem ser encaminhados à equipe de revisão para avaliação.

Preencha as informações para revisão

Plugins com conexões MCP precisam incluir informações para que a equipe de revisão possa testar a integração. Você pode incluir casos de teste positivos e negativos, a URL do vídeo de demonstração e as notas da versão em plugin.json para que sejam importados com o ZIP. Consulte a referência dos campos de revisão e publicação e os exemplos completos de metadados. O Plugin Creator, disponível no diretório de plugins, pode ajudar a preparar essas informações. Insira as credenciais da equipe de revisão separadamente em Detalhes da revisão. Prepare os seguintes itens:

• Credenciais para revisão, se for necessário fazer login. Forneça uma conta exclusiva para testes, a URL de login, os detalhes do espaço de trabalho ou do tenant e as instruções de login. Use dados de exemplo. Não use a conta de um usuário real. A conta precisa ter as permissões e os dados exigidos pelos casos de teste e deve funcionar de imediato, sem exigir aprovação de MFA, códigos por e-mail ou SMS, links mágicos ou acesso a uma rede privada.
• Cinco casos de teste positivos. Inclua o cenário, o prompt do usuário, as ferramentas que devem ser acionadas e o resultado esperado. Execute cada caso com a conta de teste antes do envio.
• Três casos de teste negativos. Inclua um prompt ou cenário em que o plugin não deva agir, o motivo pelo qual ele não deve atender à solicitação e a resposta esperada, seja uma recusa, um pedido de esclarecimento ou uma alternativa segura.
• Um vídeo de demonstração. Demonstre os casos de teste e as funcionalidades do plugin e forneça uma URL acessível para a gravação.
• Notas da versão. Resuma a versão do pacote que está sendo enviada e descreva o que mudou.

Em Metadados e habilidades, abra Informações para revisão → Detalhes da revisão para conferir os materiais importados e inserir as credenciais da equipe de revisão. Preencha os campos editáveis e selecione Salvar detalhes. Para campos identificados como gerenciados pelo ZIP do plugin, adicione ou altere as informações no pacote e carregue-o novamente. Você também pode informar a disponibilidade por país e as traduções nos metadados do pacote. Confira as configurações importadas quando aplicável. Consulte Preencha automaticamente as informações de envio e revisão para saber quais campos são aceitos e como funciona a importação.

Detalhes da revisão. Confira os casos de teste e os materiais de apoio importados do ZIP e insira separadamente as credenciais privadas da equipe de revisão.

As credenciais ficam fora do pacote público. Mantenha a conta de teste e os dados de exemplo disponíveis para revisões futuras. Se as credenciais ou as etapas de login mudarem, envie um rascunho atualizado com os novos detalhes.

Envie o rascunho

Selecione o rascunho, escolha Enviar para revisão e confirme as declarações obrigatórias de conformidade com as políticas. Após o envio, acompanhe o andamento em Status da revisão na página Plug-ins. A equipe de revisão envia o parecer por e-mail.

Envio para revisão. Confirme as declarações obrigatórias e envie o rascunho selecionado para revisão.

Cada plugin só pode ter uma revisão em andamento. Para substituir um pacote em revisão, aguarde a decisão ou cancele a revisão antes de carregar outro pacote. Se o pacote for rejeitado, faça as correções indicadas no parecer e envie o ZIP corrigido.

Se a equipe de revisão rejeitar o envio, consulte o motivo no e-mail de rejeição. Para recorrer, responda a esse e-mail e explique por que a decisão deve ser reconsiderada.

4. Publique o plugin aprovado

Após a aprovação do plugin, você escolhe quando disponibilizá-lo. Abra a versão aprovada do pacote e selecione Publicar plugin. A publicação de uma atualização substitui a versão anterior do pacote.

Atualize o plugin publicado

Para atualizar metadados, recursos ou habilidades incluídas no pacote, carregue um novo ZIP no plugin existente. Isso cria uma versão do pacote com verificações e resultado de revisão próprios. Alterações nas ferramentas hospedadas são tratadas separadamente nas verificações do MCP, por isso dispensam o upload de um pacote.

Se você usou o formulário de envio anterior, baixe o plugin existente como ZIP para começar. Abra o plugin, selecione a versão publicada do pacote e escolha Baixar ZIP da versão no menu …. Se você já mantém o pacote localmente, pode usar essa cópia como origem.

1. Atualize o conteúdo e o número da versão do pacote. Depois, crie um ZIP completo com todos os componentes que deseja manter.
2. Abra o plugin existente e selecione Carregar plugin para fazer alterações.
3. Confirme a versão do pacote selecionada em Metadados e habilidades. Confira os novos resultados das verificações automáticas e corrija os problemas que impedem o envio.
4. Conclua as etapas de revisão aplicáveis e publique a versão aprovada do pacote.

Use o mesmo plugin ao adicionar ou remover habilidades. Para alterar a URL de um servidor MCP existente, entre em contato com o suporte. O fluxo de atualização atual não permite alterar a URL.

Atualize o servidor MCP

Após a primeira publicação, a OpenAI verifica diariamente o servidor MCP que você hospeda. As atualizações elegíveis ficam disponíveis assim que passam nas verificações automáticas, sem exigir uma nova versão do pacote nem uma etapa separada de publicação. Você também pode solicitar uma verificação logo após implantar alterações no servidor.

Verifique as alterações mais recentes

1. Implante as alterações no servidor MCP.
2. Abra o plugin existente, selecione MCPs e escolha o servidor conectado.
3. Em Problemas, selecione Verificar novamente.
4. Aguarde o término da verificação e confira os resultados e a disponibilidade das ferramentas.

Visão geral da verificação do MCP. Execute uma nova verificação após alterar o servidor. Depois, confira os resultados e a disponibilidade de cada ferramenta.

A opção de verificar novamente pode ficar indisponível enquanto outra verificação ou um recurso estiver em andamento ou quando o plugin não estiver apto para verificação.

Identifique e corrija problemas nas ferramentas

1. Abra Problemas e selecione uma ferramenta afetada.
2. Leia Problemas encontrados e examine Atualização retida para ver quais metadados foram avaliados. Definição em uso mostra os metadados que estão em vigor.
3. Selecione Copiar problemas para usar os resultados no seu fluxo de desenvolvimento.
4. Corrija os metadados ou a implementação da ferramenta no servidor e implante as alterações.
5. Volte a Problemas, selecione Verificar novamente e confira os novos resultados.

Dica: Peça ao Codex ou ao ChatGPT que examine seu servidor MCP e o erro copiado. Peça também que explique o problema e sugira uma correção.

As alterações em cada ferramenta são avaliadas de forma independente. Um problema apontado em uma alteração não necessariamente impede outras atualizações elegíveis. Novas ferramentas ficam indisponíveis até a aprovação. Quando uma atualização é retida, as ferramentas existentes mantêm os metadados aprovados anteriormente. A remoção de ferramentas entra em vigor após uma verificação.

Mantenha o servidor MCP compatível com os schemas de ferramentas aprovados atualmente até que os metadados atualizados entrem em vigor.

Conteste o resultado de uma verificação automática

Se você acredita que um problema foi apontado por engano em uma ferramenta, selecione Recorrer e explique por que a equipe de revisão deve reconsiderar os resultados. A equipe avalia em conjunto as alterações de ferramentas retidas naquela verificação. Se o problema for válido, geralmente é mais rápido corrigi-lo no servidor e executar uma nova verificação.

Recurso sobre a verificação do MCP. Explique por que a equipe de revisão deve reconsiderar o resultado da verificação automática.

As atualizações automáticas do MCP ficam pausadas durante um recurso. Para fazer alterações, selecione Retirar recurso, atualize o servidor e execute uma nova verificação. Os recursos abrangem as alterações de ferramentas retidas. Alterações no pacote, autenticação e instruções compartilhadas do servidor ficam fora desse escopo.

Para solucionar problemas, consulte Erros de envio. Informe o ID do plugin ao entrar em contato com o suporte.

Preencha automaticamente as informações de envio e revisão

Você pode incluir no manifesto do plugin os detalhes da página no diretório, da revisão e da publicação para que sejam preenchidos ao carregar o ZIP. A referência abaixo descreve os campos aceitos, explica como seus valores são aplicados no upload e apresenta exemplos para cada formato de pacote.

No momento, não é possível enviar pacotes ZIP de plugins que contenham referências a aplicativos (apps / .app.json) ou hooks de ciclo de vida. Declare as URLs dos servidores MCP na configuração do MCP e conclua a configuração no painel.

Remova os hooks de ciclo de vida antes de enviar o plugin ao diretório público. Se o plugin depender desses hooks, distribua-o de modo que os usuários possam instalá-lo manualmente no Codex para desktop.

Exemplos completos de metadados

Os exemplos mostram o mesmo plugin fictício de anotações em cada formato. Copie o manifesto correspondente ao seu formato e substitua as informações do responsável pela publicação, as URLs, os nomes das ferramentas, os casos de teste para revisão, as traduções e a disponibilidade por país pelos valores reais. Os casos de exemplo não foram executados em um serviço real.

Inclua os arquivos referenciados pelo manifesto:

• skills/get-started/SKILL.md, com campos name e description válidos no cabeçalho YAML.
• Os quatro arquivos de ícone em assets/.
• Exatamente um servidor MCP remoto chamado notes, configurado em mcp.json para Agent Plugins ou em .mcp.json para Codex, conforme a configuração correspondente a seguir.

Use URLs próprias e acessíveis para a demonstração e os anexos de revisão. Os links de example.com ilustram o formato esperado e não levam a materiais que possam ser usados no envio. Se o plugin contiver apenas habilidades, omita review e a configuração do MCP. Omita também mcpServers do manifesto do Codex.

Use este arquivo mcp.json com o exemplo de Agent Plugins:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "notes": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}

Para o exemplo do Codex, salve o conteúdo abaixo como .mcp.json na raiz do plugin. Esse formato omite o schema de Agent Plugins:

{
  "mcpServers": {
    "notes": {
      "url": "https://example.com/mcp"
    }
  }
}

Formato Agent Plugins

Salve este manifesto completo como plugin.json na raiz do plugin:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "acme-notes",
  "version": "1.0.0",
  "description": "Search and summarize notes from your Acme workspace.",
  "author": {
    "name": "Acme",
    "email": "support@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/notes",
  "repository": "https://github.com/example/acme-notes",
  "license": "MIT",
  "keywords": ["notes", "search", "productivity"],
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Acme Notes",
        "shortDescription": "Find and summarize your notes",
        "longDescription": "Search notes in your Acme workspace, open matching notes, and summarize decisions with links to the source. Acme Notes only accesses notes available to your connected account.",
        "developerName": "Acme",
        "category": "Productivity",
        "capabilities": ["Search notes", "Read notes"],
        "websiteURL": "https://example.com/notes",
        "supportURL": "https://example.com/support",
        "privacyPolicyURL": "https://example.com/privacy",
        "termsOfServiceURL": "https://example.com/terms",
        "defaultPrompt": [
          "Find my notes about the launch.",
          "Summarize the decisions in my launch notes.",
          "Open the project kickoff notes."
        ],
        "brandColor": "#2357C6",
        "brandColorDark": "#8CB4FF",
        "composerIcon": "./assets/icon.png",
        "composerIconDark": "./assets/icon-dark.png",
        "logo": "./assets/logo.png",
        "logoDark": "./assets/logo-dark.png"
      },
      "onboardingSkill": "./skills/get-started/SKILL.md",
      "review": {
        "test_cases": {
          "positive": [
            {
              "description": "Find notes by topic",
              "prompt": "Find my notes about the launch.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Return accessible notes about the launch with source links.",
              "file_attachment_urls": [
                "https://example.com/review/launch-brief.pdf"
              ],
              "expected_output_url": "https://example.com/review/launch-results"
            },
            {
              "description": "Open a matching note",
              "prompt": "Open the project kickoff notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Find the kickoff note and return its content with a source link."
            },
            {
              "description": "Summarize decisions",
              "prompt": "Summarize decisions in my launch notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Summarize decisions from accessible notes and cite the sources."
            },
            {
              "description": "Find action items",
              "prompt": "What action items are in my kickoff notes?",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "List the action items recorded in the notes without inventing owners or deadlines."
            },
            {
              "description": "Handle no matches",
              "prompt": "Find my notes about Project Northstar.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Report that no matching notes were found in the test workspace."
            }
          ],
          "negative": [
            {
              "description": "Unsupported payment",
              "prompt": "Transfer $100 to another account."
            },
            {
              "description": "Unsupported deletion",
              "prompt": "Delete all my notes."
            },
            {
              "description": "Access outside the connected account",
              "prompt": "Show notes from a workspace I cannot access."
            }
          ]
        },
        "demo_recording_url": "https://example.com/review/acme-notes-demo",
        "commerce": false,
        "commerce_description": "This plugin does not sell products or process payments."
      },
      "publication": {
        "countries": ["US", "GB"],
        "release_notes": "Initial release with note search, reading, and summaries.",
        "translations": {
          "fr-FR": {
            "subtitle": "Retrouvez et résumez vos notes",
            "description": "Recherchez des notes dans votre espace Acme, ouvrez les résultats et résumez les décisions avec des liens vers les sources. Acme Notes accède uniquement aux notes disponibles pour votre compte connecté."
          },
          "ja-JP": {
            "subtitle": "ノートを検索して要約",
            "description": "Acmeワークスペース内のノートを検索し、該当するノートを開き、参照元へのリンク付きで決定事項を要約します。Acme Notesは、接続されたアカウントで閲覧できるノートにのみアクセスします。"
          }
        }
      }
    }
  }
}

Formato Codex

Salve este manifesto completo como .codex-plugin/plugin.json. Os campos de apresentação passam para o objeto interface na raiz. As configurações iniciais, de revisão e de publicação permanecem em extensions.com.openai:

{
  "name": "acme-notes",
  "version": "1.0.0",
  "description": "Search and summarize notes from your Acme workspace.",
  "author": {
    "name": "Acme",
    "email": "support@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/notes",
  "repository": "https://github.com/example/acme-notes",
  "license": "MIT",
  "keywords": ["notes", "search", "productivity"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Acme Notes",
    "shortDescription": "Find and summarize your notes",
    "longDescription": "Search notes in your Acme workspace, open matching notes, and summarize decisions with links to the source. Acme Notes only accesses notes available to your connected account.",
    "developerName": "Acme",
    "category": "Productivity",
    "capabilities": ["Search notes", "Read notes"],
    "websiteURL": "https://example.com/notes",
    "supportURL": "https://example.com/support",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Find my notes about the launch.",
      "Summarize the decisions in my launch notes.",
      "Open the project kickoff notes."
    ],
    "brandColor": "#2357C6",
    "brandColorDark": "#8CB4FF",
    "composerIcon": "./assets/icon.png",
    "composerIconDark": "./assets/icon-dark.png",
    "logo": "./assets/logo.png",
    "logoDark": "./assets/logo-dark.png"
  },
  "extensions": {
    "com.openai": {
      "onboardingSkill": "./skills/get-started/SKILL.md",
      "review": {
        "test_cases": {
          "positive": [
            {
              "description": "Find notes by topic",
              "prompt": "Find my notes about the launch.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Return accessible notes about the launch with source links.",
              "file_attachment_urls": [
                "https://example.com/review/launch-brief.pdf"
              ],
              "expected_output_url": "https://example.com/review/launch-results"
            },
            {
              "description": "Open a matching note",
              "prompt": "Open the project kickoff notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Find the kickoff note and return its content with a source link."
            },
            {
              "description": "Summarize decisions",
              "prompt": "Summarize decisions in my launch notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Summarize decisions from accessible notes and cite the sources."
            },
            {
              "description": "Find action items",
              "prompt": "What action items are in my kickoff notes?",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "List the action items recorded in the notes without inventing owners or deadlines."
            },
            {
              "description": "Handle no matches",
              "prompt": "Find my notes about Project Northstar.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Report that no matching notes were found in the test workspace."
            }
          ],
          "negative": [
            {
              "description": "Unsupported payment",
              "prompt": "Transfer $100 to another account."
            },
            {
              "description": "Unsupported deletion",
              "prompt": "Delete all my notes."
            },
            {
              "description": "Access outside the connected account",
              "prompt": "Show notes from a workspace I cannot access."
            }
          ]
        },
        "demo_recording_url": "https://example.com/review/acme-notes-demo",
        "commerce": false,
        "commerce_description": "This plugin does not sell products or process payments."
      },
      "publication": {
        "countries": ["US", "GB"],
        "release_notes": "Initial release with note search, reading, and summaries.",
        "translations": {
          "fr-FR": {
            "subtitle": "Retrouvez et résumez vos notes",
            "description": "Recherchez des notes dans votre espace Acme, ouvrez les résultats et résumez les décisions avec des liens vers les sources. Acme Notes accède uniquement aux notes disponibles pour votre compte connecté."
          },
          "ja-JP": {
            "subtitle": "ノートを検索して要約",
            "description": "Acmeワークスペース内のノートを検索し、該当するノートを開き、参照元へのリンク付きで決定事項を要約します。Acme Notesは、接続されたアカウントで閲覧できるノートにのみアクセスします。"
          }
        }
      }
    }
  }
}

Escolha a estrutura correspondente ao seu pacote:

Em pacotes Agent Plugins, coloque as configurações específicas da OpenAI em plugin.json, dentro de extensions.com.openai. Se esse objeto estiver presente, a OpenAI ignora as configurações de .codex-plugin/plugin.json. Os dois arquivos não são mesclados. Se o objeto estiver ausente, a OpenAI lê essas configurações de .codex-plugin/plugin.json. A identificação do pacote continua vindo do plugin.json na raiz, as habilidades de skills/ e os servidores MCP de mcp.json.

Use os exemplos completos de metadados como ponto de partida. Se o painel do desenvolvedor indicar que falta a URL da política de privacidade, a URL de suporte ou o ícone do aplicativo, consulte a referência de campos para encontrar o campo correspondente no manifesto.

Campos do manifesto

A coluna de requisitos distingue as exigências do formato do pacote das exigências de envio. Os detalhes da revisão são opcionais no ZIP, mas os materiais obrigatórios devem estar presentes antes do envio para revisão.

Identificação e componentes do pacote

Estes campos descrevem o próprio pacote. Mantenha-os na raiz do manifesto em ambos os formatos, exceto quando a tabela indicar um campo da extensão da OpenAI.

Use estas configurações adicionais em extensions.com.openai nos pacotes portáteis ou na raiz do manifesto de compatibilidade com o Codex:

Pacotes portáteis sempre detectam habilidades em skills/ e servidores MCP em mcp.json. Uma declaração de skills ou de mcpServers na extensão incorporada ou na camada de compatibilidade não pode substituir, desativar nem acrescentar componentes aos que foram detectados. Essas declarações se aplicam apenas a pacotes sem um manifesto portátil reconhecido na raiz.

Metadados da página no diretório

Coloque os campos a seguir em extensions.com.openai.interface no formato Agent Plugins ou em interface no formato Codex. Estes limites se aplicam ao envio para o diretório público. O upload do pacote pode aceitar textos mais longos no rascunho. Mesmo que o upload seja concluído, a página do plugin ainda pode precisar de ajustes antes do envio para revisão.

Para um aplicativo MCP vinculado que precise passar por revisão pública, as quatro URLs da página no diretório são obrigatórias: websiteURL, supportURL, privacyPolicyURL e termsOfServiceURL. Use URLs HTTPS sem credenciais incorporadas. A validação de metadados de plugins que contêm apenas habilidades não exige as quatro URLs. Os campos homepage e author.url do pacote não preenchem automaticamente esses campos da página no diretório.

Ícones

Inclua logo e composerIcon nos pacotes que preparar para distribuição. A validação de pacotes do Codex exige ambos. Você pode carregar um pacote portátil sem eles, mas o painel exige um ícone principal do aplicativo antes do envio para revisão. As variantes para o tema escuro são opcionais. Para resolver o aviso “Ícone do aplicativo obrigatório”, adicione logo e o respectivo arquivo de imagem ou forneça o ícone no painel.

Use caminhos relativos à raiz do plugin com o prefixo ./ e inclua todos os arquivos referenciados. Os formatos de imagem aceitos são PNG, JPEG, WebP e SVG, com até 5 MiB por arquivo. Ícones e logotipos devem ser quadrados e ter pelo menos 48 por 48 pixels. Imagens rasterizadas podem ter até 4096 pixels em cada dimensão. Para ícones SVG, forneça dimensões numéricas iguais ou um viewBox quadrado de pelo menos 48 por 48.

Configure a experiência inicial, a revisão e a publicação

Em ambos os formatos, coloque esses objetos diretamente em extensions.com.openai, no mesmo nível de interface no formato portátil. Não os coloque dentro de interface.

O campo opcional onboardingSkill oferece aos usuários um fluxo de configuração que eles podem executar após a instalação. Consulte Adicione uma habilidade de configuração inicial para ver um exemplo de manifesto, as regras de caminhos e como a configuração usa uma conversa nova ou existente.

Cada objeto em review.test_cases.positive ou review.test_cases.negative descreve um caso de teste:

A revisão inicial de um aplicativo MCP exige exatamente cinco casos positivos e três negativos. O upload aceita listas parciais, por isso complete-as antes do envio para revisão. Se houver vários servidores MCP, declare os casos separadamente para cada servidor na configuração do MCP. O campo review.test_cases no nível do plugin exige exatamente um servidor e não pode ser combinado com declarações de casos por servidor. Plugins que contêm apenas habilidades não precisam de casos de teste para revisão de aplicativos MCP nem de uma gravação de demonstração.

Os casos de teste importados são somente leitura no painel. Para alterá-los, edite o pacote e carregue-o novamente. Omitir test_cases ou defini-lo como null preserva os casos existentes. Usar test_cases: {} limpa as duas listas. Omitir os casos em um upload posterior não volta a permitir a edição pelo painel.

Para os campos escalares de revisão e para release_notes, omitir o campo ou usar null preserva o valor salvo. Uma string vazia apaga o texto. Os valores definidos explicitamente no pacote são aplicados novamente no envio para revisão. Para usar um valor editado no painel, remova a declaração escalar do pacote. Os campos de revisão compartilhados se aplicam aos rascunhos de aplicativos MCP do próprio plugin. As notas da versão de um plugin que contém apenas habilidades permanecem no pacote e não iniciam uma revisão de aplicativo.

Mantenha commerce e commerce_description em review, fora de publication. Não coloque credenciais nem instruções para a equipe de revisão no pacote. Os metadados do ZIP rejeitam test_credentials e reviewer_instructions. Forneça os dados de acesso da equipe de revisão pelo formulário seguro do painel.

Traduza os textos da página no diretório

Em ambos os formatos, adicione um objeto translations em extensions.com.openai.publication para fornecer subtítulos e descrições traduzidos. Use identificadores de localidade não vazios, como fr-FR ou ja-JP. O objeto de cada localidade pode conter subtitle, description ou ambos. Você pode omitir qualquer um desses campos ou defini-lo como null. Também pode omitir translations ou defini-lo como null.

Mantenha o texto em inglês nos campos base da página no diretório. A tradução en-US é opcional, e o importador não a gera automaticamente.

Os subtítulos traduzidos devem ocupar uma única linha de até 30 caracteres. As descrições traduzidas podem incluir quebras de linha com \n e ter até 4000 caracteres. O texto fornecido deve conter pelo menos um caractere que não seja um espaço em branco e usar apenas caracteres aceitos. Tabulações e outros caracteres de controle não aceitos são rejeitados. Os limites se aplicam ao texto exato, incluindo os espaços no início e no fim.

As traduções são validadas durante a importação e preservadas no pacote carregado, mesmo após a edição dos metadados. Por enquanto, a importação não altera o texto exibido no diretório de plugins nem nas respostas da API que fornece os dados das páginas do diretório.