​

Manifesto do Plugin (openclaw.plugin.json)

• Bundle do Codex: .codex-plugin/plugin.json
• Bundle do Claude: .claude-plugin/plugin.json ou o layout padrão de componente do Claude sem manifesto
• Bundle do Cursor: .cursor-plugin/plugin.json

​

O que este arquivo faz

• identidade do plugin
• validação de configuração
• metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o tempo de execução do plugin
• dicas de ativação leves que as superfícies do plano de controle podem inspecionar antes de o tempo de execução ser carregado
• descritores de configuração leves que as superfícies de configuração/onboarding podem inspecionar antes de o tempo de execução ser carregado
• metadados de alias e autoativação que devem ser resolvidos antes de o tempo de execução do plugin ser carregado
• metadados abreviados de propriedade de família de modelos que devem autoativar o plugin antes de o tempo de execução ser carregado
• snapshots estáticos de propriedade de capacidade usados para a integração de compatibilidade agrupada e cobertura de contrato
• metadados leves do executor de QA que o host compartilhado openclaw qa pode inspecionar antes de o tempo de execução do plugin ser carregado
• metadados de configuração específicos de canal que devem ser mesclados às superfícies de catálogo e validação sem carregar o tempo de execução
• dicas de UI de configuração

• registrar comportamento de tempo de execução
• declarar entrypoints de código
• metadados de instalação do npm

​

Exemplo mínimo

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

​

Exemplo completo

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Plugin de provedor OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "providerEndpoints": [
    {
      "endpointClass": "xai-native",
      "hosts": ["api.x.ai"]
    }
  ],
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "Chave de API do OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "Chave de API do OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "Chave de API",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

Referência dos campos de nível superior

​

Referência de providerAuthChoices

​

Referência de commandAliases

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

​

Referência de activation

​

Referência de qaRunners

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Executa a faixa de QA ao vivo do Matrix com suporte de Docker em um homeserver descartável"
    }
  ]
}

{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}

• o planejamento da CLI acionado por comando usa como fallback commandAliases[].cliCommand ou commandAliases[].name legados
• o planejamento de configuração/canal acionado por canal usa como fallback a propriedade legada channels[] quando faltam metadados explícitos de ativação de canal
• o planejamento de configuração/tempo de execução acionado por provedor usa como fallback a propriedade legada providers[] e cliBackends[] de nível superior quando faltam metadados explícitos de ativação de provedor

​

Referência de setup

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

​

Referência de setup.providers

​

Campos de setup

​

Referência de uiHints

{
  "uiHints": {
    "apiKey": {
      "label": "Chave de API",
      "help": "Usada para solicitações do OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

Referência de contracts

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

​

Referência de mediaUnderstandingProviderMetadata

{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"]
    }
  }
}

​

Referência de channelConfigs

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "URL do homeserver",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Conexão com homeserver Matrix",
      "preferOver": ["matrix-legacy"]
    }
  }
}

​

Referência de modelSupport

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

• referências explícitas provider/model usam os metadados de manifesto providers do proprietário
• modelPatterns têm precedência sobre modelPrefixes
• se um plugin não agrupado e um plugin agrupado corresponderem, o plugin não agrupado vence
• a ambiguidade restante é ignorada até que o usuário ou a configuração especifique um provedor

​

Manifesto versus package.json

• se o OpenClaw precisar conhecê-lo antes de carregar o código do plugin, coloque-o em openclaw.plugin.json
• se ele for sobre empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em package.json

​

Campos de package.json que afetam a descoberta

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}

​

Precedência de descoberta (IDs de plugin duplicados)

1. Selecionado pela configuração — um caminho fixado explicitamente em plugins.entries.<id>
2. Agrupado — plugins enviados com o OpenClaw
3. Instalação global — plugins instalados na raiz global de plugins do OpenClaw
4. Workspace — plugins descobertos em relação ao workspace atual

• Uma cópia bifurcada ou desatualizada de um plugin agrupado que esteja no workspace não substituirá a versão agrupada.
• Para realmente substituir um plugin agrupado por um local, fixe-o via plugins.entries.<id> para que ele vença pela precedência, em vez de depender da descoberta no workspace.
• Descartes por duplicidade são registrados em log para que o Doctor e os diagnósticos de inicialização possam apontar para a cópia descartada.

​

Requisitos do esquema JSON

• Todo plugin deve incluir um esquema JSON, mesmo que não aceite nenhuma configuração.
• Um esquema vazio é aceitável (por exemplo, { "type": "object", "additionalProperties": false }).
• Os esquemas são validados no momento de leitura/gravação da configuração, não em tempo de execução.

​

Comportamento de validação

• Chaves channels.* desconhecidas são erros, a menos que o ID do canal seja declarado por um manifesto de plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny e plugins.slots.* devem referenciar IDs de plugin descobertos. IDs desconhecidos são erros.
• Se um plugin estiver instalado, mas tiver um manifesto ou esquema ausente ou quebrado, a validação falhará e o Doctor reportará o erro do plugin.
• Se a configuração do plugin existir, mas o plugin estiver desabilitado, a configuração será mantida e um aviso será exibido no Doctor + logs.

​

Observações

• O manifesto é obrigatório para plugins nativos do OpenClaw, incluindo carregamentos locais do sistema de arquivos.
• O tempo de execução ainda carrega o módulo do plugin separadamente; o manifesto é apenas para descoberta + validação.
• Manifestos nativos são analisados com JSON5, então comentários, vírgulas à direita e chaves sem aspas são aceitos, desde que o valor final ainda seja um objeto.
• Apenas os campos de manifesto documentados são lidos pelo carregador de manifesto. Evite adicionar aqui chaves personalizadas de nível superior.
• providerAuthEnvVars é o caminho leve de metadados para sondagens de autenticação, validação de marcadores de env e superfícies semelhantes de autenticação de provedor que não devem iniciar o tempo de execução do plugin apenas para inspecionar nomes de env.
• providerAuthAliases permite que variantes de provedor reutilizem as variáveis de ambiente de autenticação, perfis de autenticação, autenticação baseada em configuração e escolha de onboarding de chave de API de outro provedor sem codificar rigidamente essa relação no núcleo.
• providerEndpoints permite que plugins de provedor sejam donos de metadados simples de correspondência de host/baseUrl de endpoint. Use isso apenas para classes de endpoint que o núcleo já suporta; o plugin continua sendo responsável pelo comportamento de tempo de execução.
• syntheticAuthRefs é o caminho leve de metadados para hooks de autenticação sintética pertencentes ao provedor que precisam estar visíveis para a descoberta fria de modelos antes que o registro de tempo de execução exista. Liste apenas referências cujo provedor de tempo de execução ou backend de CLI realmente implemente resolveSyntheticAuth.
• nonSecretAuthMarkers é o caminho leve de metadados para chaves de API placeholder pertencentes a plugins agrupados, como marcadores de credenciais locais, OAuth ou do ambiente. O núcleo trata isso como não segredo para exibição de autenticação e auditorias de segredos, sem codificar rigidamente o provedor proprietário.
• channelEnvVars é o caminho leve de metadados para fallback de env do shell, prompts de configuração e superfícies de canal semelhantes que não devem iniciar o tempo de execução do plugin apenas para inspecionar nomes de env. Nomes de env são metadados, não ativação por si só: status, auditoria, validação de entrega de Cron e outras superfícies somente leitura ainda aplicam a política de confiança do plugin e de ativação efetiva antes de tratar uma variável de ambiente como um canal configurado.
• providerAuthChoices é o caminho leve de metadados para seletores de escolha de autenticação, resolução de --auth-choice, mapeamento de provedor preferido e registro simples de flags de CLI de onboarding antes de o tempo de execução do provedor ser carregado. Para metadados de assistente em tempo de execução que exigem código do provedor, consulte Hooks de tempo de execução do provedor.
• Tipos exclusivos de plugin são selecionados por meio de plugins.slots.*.
  • kind: "memory" é selecionado por plugins.slots.memory.
  • kind: "context-engine" é selecionado por plugins.slots.contextEngine (padrão: legacy interno).
• channels, providers, cliBackends e skills podem ser omitidos quando um plugin não precisar deles.
• Se o seu plugin depender de módulos nativos, documente as etapas de build e quaisquer requisitos de allowlist do gerenciador de pacotes (por exemplo, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Relacionado

• Criando Plugins — primeiros passos com plugins
• Arquitetura de Plugins — arquitetura interna
• Visão geral do SDK — referência do SDK de Plugin