Gerenciamento de plug-ins

Antes de começar

Administradores do workspace podem importar um marketplace de plug-ins do GitHub e manter seus plug-ins atualizados a partir do repositório. Um marketplace é um catálogo JSON que lista os plug-ins a serem importados.

Esta página aborda a importação e a sincronização no workspace. Para configurar marketplaces diretamente em clientes locais por meio do config.toml gerenciado na nuvem ou do sistema, consulte Configurar marketplaces de plug-ins e padrões. Para ativar ou desativar plug-ins em um projeto específico, consulte Ativar ou desativar um plug-in para um repositório.

Use uma conta do GitHub com acesso de leitura ao repositório do marketplace e a todos os outros repositórios referenciados por ele. Há suporte para repositórios públicos e privados do GitHub. Antes de importar, obtenha todas as aprovações da organização no GitHub necessárias para acessar os repositórios.

Revise o conteúdo do repositório antes de importar. Novos plug-ins começam com a política de instalação Disponível e autenticação na instalação. Novos marketplaces têm a sincronização automática diária ativada. A importação processa todas as entradas válidas, e as sincronizações futuras adicionam automaticamente todos os novos plug-ins do repositório.

Configure a sincronização de um marketplace

1. Abra Administração > Plug-ins e selecione Adicionar > Importar marketplace.
2. Em Origem, insira a URL do repositório, como https://github.com/example/team-plugins. Use apenas a URL do repositório, sem incluir a URL de uma branch ou pasta.
3. Se o marketplace estiver em um subdiretório, insira esse diretório em Caminho. Por exemplo, use team-tools para team-tools/.agents/plugins/marketplace.json. Deixe Caminho vazio para usar a raiz do repositório. Não insira o nome do arquivo de manifesto.
4. Se quiser, preencha Branch, tag ou commit. Deixe esse campo vazio para usar a branch padrão do repositório. Use uma branch para receber commits futuros; um commit fixo permanece naquela revisão.
5. Selecione Importar marketplace e autorize o acesso ao GitHub quando solicitado. A importação inicial pode levar até uma hora para marketplaces muito grandes. As sincronizações diárias seguintes normalmente levam alguns minutos.
6. Revise os Resultados da importação e abra cada plug-in importado para configurar sua política de instalação e os aplicativos necessários.

Para solicitar uma atualização sem esperar pela sincronização diária, abra o marketplace em Administração > Plug-ins > Marketplaces e selecione Sincronizar agora.

Formatos compatíveis

O diretório selecionado deve conter um destes arquivos:

Em um marketplace, as entradas podem referenciar plug-ins nativos com .codex-plugin/plugin.json, plug-ins compatíveis com o Claude, pacotes Agent Plugins 1.0 ou pacotes de habilidades compatíveis.

Em um marketplace do Codex, use caminhos locais para plug-ins no mesmo repositório:

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

O caminho é relativo à raiz do marketplace selecionado, não a .agents/plugins/.

Um marketplace compatível com o Claude pode usar uma string de caminho para cada plug-in local:

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

As entradas de marketplaces do Codex também aceitam source: "url" para um plug-in na raiz de um repositório do GitHub e source: "git-subdir" para um plug-in em um subdiretório do GitHub. Por exemplo:

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

As origens Git podem selecionar uma ref ou um sha de commit completo de 40 caracteres. A conta do GitHub que autoriza o acesso deve ter acesso de leitura a todos os repositórios referenciados. Atualmente, a importação para o workspace só aceita repositórios do GitHub.

Configure o acesso no workspace

A importação e a sincronização com o GitHub não aplicam as políticas de instalação ou autenticação do repositório, incluindo AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL e ON_USE. Administradores do workspace definem essas configurações para cada plug-in. Sincronizar uma atualização ou passar um plug-in existente para o gerenciamento pelo GitHub preserva suas políticas no workspace.

Use Política de instalação para escolher Disponível ou Instalado para cada função elegível. Os aplicativos necessários também devem estar ativados, e os membros devem ter acesso ao serviço conectado. Importar um plug-in não concede acesso a aplicativos nem conecta as contas dos membros. Consulte Controles de plug-ins para saber mais sobre os controles de funções, aplicativos e ações.

Passe um plug-in existente para o gerenciamento pelo GitHub

Adicione pluginId à entrada do plug-in existente no marketplace:

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Abra o plug-in em Administração > Plug-ins e copie o ID após /admin/plugins/ na URL. Coloque pluginId ao lado de name e source na entrada do marketplace. O plug-in existente deve estar no mesmo workspace.

Isso passa um plug-in do workspace enviado por upload ou ainda não gerenciado para o gerenciamento pelo GitHub. O plug-in mantém seu ID, compartilhamento e políticas do workspace. As atualizações futuras vêm do GitHub; uploads de arquivos compactados não podem mais substituir o plug-in gerenciado. Não é possível assumir dessa forma o gerenciamento de um plug-in já gerenciado por outra origem do GitHub.

Plug-ins exclusivos para desktop

Qualquer plug-in importado que declare servidores MCP em mcp.json ou .mcp.json é marcado como Somente desktop e funciona apenas no aplicativo do ChatGPT para desktop. Isso inclui servidores que usam uma URL HTTPS remota. A mesma restrição se aplica a outras formas compatíveis de configuração de MCP, como declarações de servidores em linha.

Referencie um aplicativo existente com .app.json

Adicione .app.json na raiz do plug-in. O nome do arquivo inclui um ponto inicial; app.json sem o ponto não é aceito.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Substitua asdk_app_example pelo ID do aplicativo existente. Os IDs de aplicativos aceitos começam com asdk_app_, connector_ ou templated_apps_. Use o ID do aplicativo, não um ID plugin_.... Por exemplo, uma URL de plug-in que contém plugin_asdk_app_example representa o aplicativo asdk_app_example.

A chave team-tools nomeia a referência dentro deste arquivo. Defina required como true quando o plug-in depender do aplicativo. Você pode adicionar mais entradas para referenciar outros aplicativos existentes.

Para um plug-in nativo, defina apps como ./.app.json em .codex-plugin/plugin.json. Veja um manifesto completo para este exemplo:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Mantenha os arquivos nesta estrutura:

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

A referência não cria um aplicativo nem concede permissões. Administradores devem disponibilizar o aplicativo para as funções desejadas, e os membros devem concluir toda autenticação necessária. As permissões do aplicativo, os controles de ações e as regras de acesso ao serviço existentes continuam valendo.

Mantenha os plug-ins atualizados

Novos marketplaces verificam se há atualizações diariamente. Abra Administração > Plug-ins > Marketplaces, selecione o marketplace e escolha Sincronizar agora para solicitar uma atualização sem esperar pela sincronização automática.

A sincronização pode adicionar novas entradas do marketplace e atualizar plug-ins existentes. Revise as alterações no repositório antes de fazer o merge, pois a sincronização automática importará todos os novos plug-ins.

Após uma sincronização, revise o status e o relatório salvo. Concluído — N erros significa que a execução terminou, mas alguns plug-ins não puderam ser processados. Se uma atualização de um plug-in existente for inválida, sua última versão funcional será mantida. Corrija o problema relatado no GitHub e selecione Sincronizar agora para tentar novamente.

Remover uma entrada do repositório não exclui sua cópia importada no workspace. Ela é marcada como Não está mais na origem. Excluir o marketplace no ChatGPT exclui todos os plug-ins importados dele.

Reconecte ou altere o acesso ao GitHub

Para reconectar o acesso ao GitHub, primeiro confirme que a conta do GitHub usada na importação ainda tem acesso ao repositório e a todos os repositórios referenciados. O administrador que importou originalmente o marketplace deve então abrir o plug-in do GitHub no ChatGPT e reconectar sua conta, pois a sincronização do marketplace usa a conexão desse administrador com o GitHub.

Para transferir para um novo proprietário, o novo administrador do workspace deve abrir Administração > Plug-ins > Adicionar > Importar marketplace e importar o mesmo marketplace usando os mesmos valores de Origem, Caminho e Branch, tag ou commit . As sincronizações futuras usarão a conexão desse administrador com o GitHub.

Não exclua o marketplace apenas para reconectá-lo ou alterar seu proprietário: a exclusão também remove os plug-ins importados dele.