Adicionando capacidades (guia do colaborador)

Use isto quando o OpenClaw precisar de um novo domínio compartilhado, como geração de imagens, geração de vídeo ou alguma futura área de recursos apoiada por fornecedor.

A regra:

• plugin = limite de propriedade
• capacidade = contrato compartilhado do núcleo

Não comece conectando um fornecedor diretamente a um canal ou a uma ferramenta. Comece definindo a capacidade.

# Quando criar uma capacidade

Crie uma nova capacidade quando todas estas condições forem verdadeiras:

1. Mais de um fornecedor poderia implementá-la de forma plausível.
2. Canais, ferramentas ou plugins de recursos devem consumi-la sem se importar com o fornecedor.
3. O núcleo precisa ser responsável por fallback, política, configuração ou comportamento de entrega.

Se o trabalho for exclusivo de fornecedor e ainda não existir um contrato compartilhado, pare e defina o contrato primeiro.

# A sequência padrão

1. Defina o contrato tipado do núcleo.
2. Adicione o registro de plugin para esse contrato.
3. Adicione um auxiliar compartilhado de tempo de execução.
4. Conecte um plugin de fornecedor real como prova.
5. Mova consumidores de recursos/canais para o auxiliar de tempo de execução.
6. Adicione testes de contrato.
7. Documente a configuração voltada ao operador e o modelo de propriedade.

# O que fica onde

Núcleo:

• Tipos de solicitação/resposta.
• Registro de provedores + resolução.
• Comportamento de fallback.
• Esquema de configuração com metadados de documentação title / description propagados em nós de objeto aninhado, curinga, item de array e composição.
• Superfície do auxiliar de tempo de execução.

Plugin de fornecedor:

• Chamadas de API do fornecedor.
• Tratamento de autenticação do fornecedor.
• Normalização de solicitação específica do fornecedor.
• Registro da implementação da capacidade.

Plugin de recurso/canal:

• Chama api.runtime.* ou o auxiliar plugin-sdk/*-runtime correspondente.
• Nunca chama diretamente uma implementação de fornecedor.

# Seams de provedor e harness

Use hooks de provedor quando o comportamento pertencer ao contrato do provedor de modelo, e não ao loop genérico do agente. Exemplos incluem parâmetros de solicitação específicos do provedor após a seleção de transporte, preferência de perfil de autenticação, sobreposições de prompt e roteamento de fallback de acompanhamento após failover de modelo/perfil.

Use hooks de harness de agente quando o comportamento pertencer ao tempo de execução que está executando um turno. Harnesses podem classificar resultados de tentativa bem-sucedidos, mas inutilizáveis, como respostas vazias, somente de raciocínio ou somente de planejamento, para que a política externa de fallback de modelo possa tomar a decisão de nova tentativa.

Mantenha ambos os seams estreitos:

• O núcleo é responsável pela política de nova tentativa/fallback.
• Plugins de provedor são responsáveis por dicas específicas de solicitação/autenticação/roteamento do provedor.
• Plugins de harness são responsáveis pela classificação de tentativa específica do tempo de execução.
• Plugins de terceiros retornam dicas, não mutações diretas do estado do núcleo.

# Checklist de arquivos

Para uma nova capacidade, espere tocar nestas áreas:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• Um ou mais pacotes de plugins incluídos.
• Configuração, documentação, testes.

# Exemplo trabalhado: geração de imagens

A geração de imagens segue o formato padrão:

1. O núcleo define ImageGenerationProvider.
2. O núcleo expõe registerImageGenerationProvider(...).
3. O núcleo expõe runtime.imageGeneration.generate(...).
4. Os plugins openai, google, fal e minimax registram implementações apoiadas por fornecedores.
5. Fornecedores futuros registram o mesmo contrato sem alterar canais/ferramentas.

A chave de configuração é intencionalmente separada do roteamento de análise de visão:

• agents.defaults.imageModel analisa imagens.
• agents.defaults.imageGenerationModel gera imagens.

Mantenha essas opções separadas para que fallback e política permaneçam explícitos.

# Checklist de revisão

Antes de entregar uma nova capacidade, verifique:

• Nenhum canal/ferramenta importa código de fornecedor diretamente.
• O auxiliar de tempo de execução é o caminho compartilhado.
• Pelo menos um teste de contrato afirma a propriedade incluída.
• A documentação de configuração nomeia o novo modelo/chave de configuração.
• A documentação de Plugin explica o limite de propriedade.

Se um PR pular a camada de capacidade e codificar rigidamente o comportamento do fornecedor em um canal/ferramenta, devolva-o e defina o contrato primeiro.

# Relacionados

• Detalhes internos de Plugin — modelo de capacidades, propriedade, pipeline de carregamento, auxiliares de tempo de execução.
• Criando plugins — tutorial do primeiro plugin.
• Visão geral do SDK — mapa de importação e referência da API de registro.
• Criando Skills — superfície complementar para contribuidores.