Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Este é um guia de contribuição para desenvolvedores do núcleo do OpenClaw. Se você está criando um plugin externo, consulte Criando plugins em vez disso. Para a referência aprofundada de arquitetura (modelo de capacidades, propriedade, pipeline de carregamento, auxiliares de tempo de execução), consulte Detalhes internos de Plugin.
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