Gestão de plugins

Antes de começar

Os administradores do espaço de trabalho podem importar um marketplace de plugins do GitHub e manter os respetivos plugins atualizados a partir do repositório. Um marketplace é um catálogo JSON que apresenta os plugins a importar.

Esta página aborda a importação e a sincronização do espaço de trabalho. Para configurar marketplaces diretamente nos clientes locais através de config.toml gerido na nuvem ou do sistema, consulte Configurar marketplaces de plugins e predefinições. Para ativar ou desativar plugins num projeto específico, consulte Ativar ou desativar um plugin para um repositório.

Utilize uma conta do GitHub que consiga ler o repositório do marketplace e quaisquer outros repositórios referenciados por este. São suportados repositórios do GitHub públicos e privados. Conclua qualquer aprovação da organização do GitHub necessária para aceder ao repositório antes de efetuar a importação.

Analise o conteúdo do repositório antes de o importar. Os novos plugins começam com a instalação Disponível e autenticação aquando da instalação. Os novos marketplaces têm a sincronização diária automática ativada. A importação processa todas as entradas válidas e as futuras sincronizações adicionam automaticamente quaisquer novos plugins existentes no repositório.

Configurar a sincronização de um marketplace

1. Abra Administração > Plugins e selecione Adicionar > Importar marketplace.
2. Em Origem, introduza o URL do repositório, como https://github.com/example/team-plugins. Utilize apenas o URL do repositório, sem um URL de ramo ou pasta.
3. Se o marketplace estiver num subdiretório, introduza esse diretório em Caminho. Por exemplo, utilize team-tools para team-tools/.agents/plugins/marketplace.json. Deixe Caminho vazio para utilizar a raiz do repositório. Não introduza o nome do ficheiro de manifesto.
4. Opcionalmente, introduza um Ramo, etiqueta ou commit. Deixe este campo vazio para utilizar o ramo predefinido do repositório. Utilize um ramo para receber commits futuros; um commit fixo permanece nessa revisão.
5. Selecione Importar marketplace e autorize o acesso ao GitHub quando solicitado. A importação inicial pode demorar até uma hora no caso de marketplaces muito grandes. As sincronizações diárias subsequentes demoram normalmente alguns minutos.
6. Analise os Resultados da importação e, em seguida, abra cada plugin importado para configurar a respetiva política de instalação e quaisquer aplicações necessárias.

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

Formatos suportados

O diretório selecionado tem de conter um dos seguintes ficheiros:

Num marketplace, as entradas podem referenciar plugins nativos com .codex-plugin/plugin.json, plugins compatíveis com Claude, pacotes Agent Plugins 1.0 ou pacotes de competências suportados.

Para um marketplace do Codex, utilize caminhos locais para os plugins existentes 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 selecionada do marketplace, não a .agents/plugins/.

Um marketplace compatível com Claude pode utilizar uma cadeia de caminho para cada plugin local:

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

As entradas de marketplaces do Codex também suportam source: "url" para um plugin na raiz de um repositório do GitHub e source: "git-subdir" para um plugin num 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 um ref ou um sha de commit completo com 40 carateres. A conta do GitHub que concede a autorização tem de conseguir ler todos os repositórios referenciados. Atualmente, a importação para o espaço de trabalho só suporta repositórios do GitHub.

Configurar o acesso ao espaço de trabalho

A importação e a sincronização do GitHub não aplicam políticas de instalação ou autenticação do repositório, incluindo AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL e ON_USE. Os administradores do espaço de trabalho configuram estas definições para cada plugin. A sincronização de uma atualização ou a transferência de um plugin existente para a gestão pelo GitHub preserva as respetivas políticas do espaço de trabalho.

Utilize a Política de instalação para escolher Disponível ou Instalado para cada função elegível. As aplicações necessárias também têm de estar ativadas e os membros têm de ter acesso ao serviço ligado. A importação de um plugin não concede acesso às aplicações nem liga as contas dos membros. Consulte Controlos de plugins para obter informações sobre controlos de funções, aplicações e ações.

Transferir um plugin existente para a gestão pelo GitHub

Adicione pluginId à entrada do marketplace do plugin existente:

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

Abra o plugin em Administração > Plugins e copie o ID após /admin/plugins/ no respetivo URL. Coloque pluginId junto de name e source na entrada do marketplace. O plugin existente tem de pertencer ao mesmo espaço de trabalho.

Esta ação transfere um plugin do espaço de trabalho carregado ou não gerido de outra forma para a gestão pelo GitHub. O plugin mantém o seu ID, a partilha e as políticas do espaço de trabalho. As futuras atualizações provêm do GitHub; os carregamentos de ficheiros compactados já não podem substituir o plugin gerido. Um plugin que já seja gerido por outra origem do GitHub não pode ser assumido desta forma.

Plugins exclusivos para computador

Qualquer plugin importado que declare MCP servers em mcp.json ou .mcp.json é marcado como Exclusivo para computador e só funciona na aplicação ChatGPT para computador. Isto inclui servidores que utilizem um URL HTTPS remoto. A mesma restrição aplica-se a outras formas de configuração MCP suportadas, como declarações de servidores inline.

Referenciar uma aplicação existente com .app.json

Adicione .app.json à raiz do plugin. O nome do ficheiro inclui um ponto inicial; app.json sem o ponto não é suportado.

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

Substitua asdk_app_example pelo ID da aplicação existente. Os ID de aplicações suportados começam por asdk_app_, connector_ ou templated_apps_. Utilize o ID da aplicação, não um ID plugin_.... Por exemplo, o URL de um plugin que contenha plugin_asdk_app_example representa a aplicação asdk_app_example.

A chave team-tools atribui um nome à referência neste ficheiro. Defina required como true quando o plugin depender da aplicação. Pode adicionar mais entradas para referenciar outras aplicações existentes.

Para um plugin nativo, defina apps como ./.app.json em .codex-plugin/plugin.json. Segue-se 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 ficheiros nesta estrutura:

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

A referência não cria uma aplicação nem concede permissões. Os administradores têm de disponibilizar a aplicação às funções pretendidas e os membros têm de concluir qualquer autenticação necessária. Continuam a aplicar-se as permissões da aplicação, os controlos de ações e o acesso ao serviço existentes.

Manter os plugins atualizados

Os novos marketplaces procuram atualizações diariamente. Abra Administração > Plugins > Marketplaces, selecione o marketplace e escolha Sincronizar agora para solicitar uma atualização sem aguardar pela sincronização automática.

A sincronização pode adicionar novas entradas do marketplace e atualizar plugins existentes. Analise as alterações ao repositório antes de as intercalar, uma vez que a sincronização automática importará todos os novos plugins.

Depois de uma sincronização, analise o estado e o relatório guardado. Concluído — N erros significa que a execução terminou, mas não foi possível processar alguns plugins. Se uma atualização de um plugin existente for inválida, é mantida a última versão funcional. Corrija o problema comunicado no GitHub e, em seguida, selecione Sincronizar agora para tentar novamente.

Remover uma entrada do repositório não elimina a respetiva cópia importada no espaço de trabalho. Esta é marcada como Já não está na origem. A eliminação do marketplace no ChatGPT elimina todos os plugins importados a partir dele.

Voltar a ligar ou alterar o acesso ao GitHub

Para voltar a ligar o acesso ao GitHub, confirme primeiro se a conta do GitHub utilizada para a importação ainda tem acesso ao repositório e a quaisquer repositórios referenciados. Em seguida, o administrador que importou originalmente o marketplace deve abrir o plugin do GitHub no ChatGPT e voltar a ligar a respetiva conta, uma vez que a sincronização do marketplace utiliza a ligação ao GitHub desse administrador.

Para transferir para um novo proprietário, o novo administrador do espaço de trabalho deve abrir Administração > Plugins > Adicionar > Importar marketplace e importar o mesmo marketplace utilizando os mesmos valores de Origem, Caminho e Ramo, etiqueta ou commit. As futuras sincronizações utilizarão a respetiva ligação ao GitHub.

Não elimine o marketplace apenas para voltar a ligá-lo ou alterar o proprietário: a eliminação também remove os plugins importados.