From d4c25ee082cdd46103c384dd9970f0fadc9a174e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 15:24:01 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/gateway/configuration-reference.md | 1368 +++++++-------- .../gpt54-codex-agentic-parity-maintainers.md | 174 ++ docs/pt-BR/help/gpt54-codex-agentic-parity.md | 229 +++ docs/pt-BR/plugins/architecture.md | 1540 ++++++++--------- docs/pt-BR/plugins/manifest.md | 407 ++--- docs/pt-BR/reference/rich-output-protocol.md | 60 + docs/pt-BR/tools/video-generation.md | 280 ++- 7 files changed, 2218 insertions(+), 1840 deletions(-) create mode 100644 docs/pt-BR/help/gpt54-codex-agentic-parity-maintainers.md create mode 100644 docs/pt-BR/help/gpt54-codex-agentic-parity.md create mode 100644 docs/pt-BR/reference/rich-output-protocol.md diff --git a/docs/pt-BR/gateway/configuration-reference.md b/docs/pt-BR/gateway/configuration-reference.md index c22db7c0e..d1b839639 100644 --- a/docs/pt-BR/gateway/configuration-reference.md +++ b/docs/pt-BR/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Você precisa da semântica exata da configuração em nível de campo ou dos padrões + - Você precisa de semântica exata de configuração no nível de campo ou dos valores padrão - Você está validando blocos de configuração de canal, modelo, gateway ou ferramenta summary: Referência de configuração do gateway para chaves principais do OpenClaw, padrões e links para referências dedicadas de subsistemas title: Referência de configuração x-i18n: - generated_at: "2026-04-11T02:44:19Z" + generated_at: "2026-04-11T15:16:03Z" model: gpt-5.4 provider: openai - source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 + source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c source_path: gateway/configuration-reference.md workflow: 15 --- # Referência de configuração -Referência principal de configuração para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuração](/pt-BR/gateway/configuration). +Referência principal de configuração para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuration](/pt-BR/gateway/configuration). -Esta página aborda as principais superfícies de configuração do OpenClaw e inclui links quando um subsistema tem sua própria referência mais detalhada. Ela **não** tenta incorporar em uma única página todo catálogo de comandos pertencente a canais/plugins nem todos os parâmetros profundos de memória/QMD. +Esta página cobre as principais superfícies de configuração do OpenClaw e aponta para outras páginas quando um subsistema tem sua própria referência mais detalhada. Ela **não** tenta incluir em linha todos os catálogos de comandos pertencentes a canais/plugins nem todos os parâmetros profundos de memória/QMD em uma única página. -Fonte de verdade do código: +Fonte da verdade no código: -- `openclaw config schema` imprime o JSON Schema em tempo real usado para validação e para a Control UI, com metadados de bundles/plugins/canais mesclados quando disponíveis -- `config.schema.lookup` retorna um nó de schema com escopo de caminho para ferramentas de detalhamento -- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash da linha de base da documentação de configuração em relação à superfície atual do schema +- `openclaw config schema` imprime o JSON Schema em uso para validação e para a Control UI, com metadados de bundles/plugins/canais mesclados quando disponíveis +- `config.schema.lookup` retorna um nó do schema com escopo de caminho para ferramentas de inspeção detalhada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash da baseline de documentação de configuração em relação à superfície atual do schema Referências detalhadas dedicadas: - [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de dreaming em `plugins.entries.memory-core.config.dreaming` -- [Comandos de Barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos integrados + empacotados -- páginas do canal/plugin proprietário para superfícies de comandos específicas de canal +- [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos embutidos + em bundle +- páginas do canal/plugin proprietário para superfícies de comando específicas de canal -O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos. +O formato da configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos. --- ## Canais -Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). +Cada canal é iniciado automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). ### Acesso a DM e grupos Todos os canais oferecem suporte a políticas de DM e políticas de grupo: -| Política de DM | Comportamento | -| -------------------- | ------------------------------------------------------------- | -| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar | -| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permissões por pareamento) | -| `open` | Permitir todas as DMs de entrada (exige `allowFrom: ["*"]`) | -| `disabled` | Ignorar todas as DMs de entrada | +| Política de DM | Comportamento | +| ------------------- | -------------------------------------------------------------- | +| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar | +| `allowlist` | Somente remetentes em `allowFrom` (ou no armazenamento de permissão pareado) | +| `open` | Permitir todas as DMs recebidas (requer `allowFrom: ["*"]`) | +| `disabled` | Ignorar todas as DMs recebidas | -| Política de grupo | Comportamento | -| ---------------------- | ------------------------------------------------------ | -| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada | -| `open` | Ignorar listas de permissões de grupo (o bloqueio por menção ainda se aplica) | -| `disabled` | Bloquear todas as mensagens de grupo/sala | +| Política de grupo | Comportamento | +| --------------------- | ------------------------------------------------------- | +| `allowlist` (padrão) | Somente grupos que correspondam à allowlist configurada | +| `open` | Ignorar allowlists de grupo (o gating por menção ainda se aplica) | +| `disabled` | Bloquear todas as mensagens de grupo/sala | -`channels.defaults.groupPolicy` define o padrão quando `groupPolicy` de um provedor não está definido. -Os códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento por DM são limitadas a **3 por canal**. -Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução recorre a `allowlist` (falha fechada) com um aviso na inicialização. +`channels.defaults.groupPolicy` define o padrão quando o `groupPolicy` de um provedor não está definido. +Os códigos de pareamento expiram após 1 hora. As solicitações pendentes de pareamento de DM são limitadas a **3 por canal**. +Se um bloco de provedor estiver ausente por completo (`channels.` ausente), a política de grupo em runtime volta para `allowlist` (fail-closed) com um aviso na inicialização. ### Substituições de modelo por canal -Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal se aplica quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida por `/model`). +Use `channels.modelByChannel` para fixar IDs específicos de canal a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal é aplicado quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`). ```json5 { @@ -105,15 +105,15 @@ Use `channels.defaults` para comportamento compartilhado de política de grupo e } ``` -- `channels.defaults.groupPolicy`: política de grupo de fallback quando `groupPolicy` em nível de provedor não está definida. -- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto citado/de thread/histórico), `allowlist` (inclui apenas contexto de remetentes permitidos), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: inclui status saudáveis de canal na saída de heartbeat. -- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída de heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderiza a saída de heartbeat em estilo compacto com indicador. +- `channels.defaults.groupPolicy`: política de grupo de fallback quando o `groupPolicy` no nível do provedor não está definido. +- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto citado/de thread/histórico), `allowlist` (inclui contexto apenas de remetentes na allowlist), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: incluir status saudáveis de canais na saída de heartbeat. +- `channels.defaults.heartbeat.showAlerts`: incluir status degradados/com erro na saída de heartbeat. +- `channels.defaults.heartbeat.useIndicator`: renderizar saída de heartbeat compacta no estilo indicador. ### WhatsApp -O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. +O WhatsApp é executado pelo canal web do gateway (Baileys Web). Ele é iniciado automaticamente quando existe uma sessão vinculada. ```json5 { @@ -124,7 +124,7 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // marcas azuis (false no modo de conversa consigo mesmo) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic } ``` -- Os comandos de saída usam por padrão a conta `default`, se presente; caso contrário, o primeiro ID de conta configurado (ordenado). -- O `channels.whatsapp.defaultAccount` opcional substitui essa seleção padrão de conta quando corresponde a um ID de conta configurado. -- O diretório legado de autenticação Baileys de conta única é migrado por `openclaw doctor` para `whatsapp/default`. +- Os comandos de saída usam a conta `default` por padrão, se ela existir; caso contrário, usam o primeiro ID de conta configurado (ordenado). +- `channels.whatsapp.defaultAccount` opcional substitui essa seleção de conta padrão de fallback quando corresponde a um ID de conta configurado. +- O diretório de autenticação legado de conta única do Baileys é migrado por `openclaw doctor` para `whatsapp/default`. - Substituições por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -185,24 +185,24 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Mantenha as respostas curtas.", + systemPrompt: "Keep answers brief.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Mantenha o foco no assunto.", + systemPrompt: "Stay on topic.", }, }, }, }, customCommands: [ - { command: "backup", description: "Backup do Git" }, - { command: "generate", description: "Criar uma imagem" }, + { command: "backup", description: "Git backup" }, + { command: "generate", description: "Create an image" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (padrão: off; ative explicitamente para evitar limites de taxa de edição de pré-visualização) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic } ``` -- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão. -- O `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (somente arquivo comum; symlinks são rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão. +- `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. - Em configurações com várias contas (2+ IDs de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento por fallback; `openclaw doctor` emite um aviso quando isso está ausente ou inválido. - `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, `/config set|unset`). -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings ACP persistentes para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). -- As pré-visualizações de streaming do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo). -- Política de nova tentativa: consulte [Política de nova tentativa](/pt-BR/concepts/retry). +- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings ACP persistentes para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- As prévias de streaming do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo). +- Política de retry: consulte [Política de retry](/pt-BR/concepts/retry). ### Discord @@ -278,7 +278,7 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Apenas respostas curtas.", + systemPrompt: "Short answers only.", }, }, }, @@ -286,7 +286,7 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress equivale a partial no Discord) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in para sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,32 +334,32 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic ``` - Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão. -- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de nova tentativa/política da conta ainda vêm da conta selecionada no snapshot ativo do runtime. -- O `channels.discord.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Use `user:` (DM) ou `channel:` (canal de guild) para destinos de entrega; IDs numéricos puros são rejeitados. -- Slugs de guild são em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild. -- Mensagens escritas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bots que mencionem o bot (as próprias mensagens continuam filtradas). -- `channels.discord.guilds..ignoreOtherMentions` (e substituições em nível de canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here). +- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo. +- `channels.discord.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Use `user:` (DM) ou `channel:` (canal de guild) para destinos de entrega; IDs numéricos sem prefixo são rejeitados. +- Slugs de guild ficam em minúsculas com espaços substituídos por `-`; as chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild. +- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bot que mencionem o bot (mensagens próprias continuam filtradas). +- `channels.discord.guilds..ignoreOtherMentions` (e substituições no nível do canal) descarta mensagens que mencionem outro usuário ou função, mas não o bot (excluindo @everyone/@here). - `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando têm menos de 2000 caracteres. -- `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord: +- `channels.discord.threadBindings` controla o roteamento vinculado a threads no Discord: - `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados) - - `idleHours`: substituição do Discord para desfoco automático por inatividade em horas (`0` desativa) - - `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desativa) - - `spawnSubagentSessions`: chave de opt-in para criação/vinculação automática de thread com `sessions_spawn({ thread: true })` -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings ACP persistentes para canais e threads (use o ID do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres Discord components v2. + - `idleHours`: substituição do Discord para desfoco automático por inatividade em horas (`0` desabilita) + - `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desabilita) + - `spawnSubagentSessions`: opção de ativação para criação/vinculação automática de threads em `sessions_spawn({ thread: true })` +- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings ACP persistentes para canais e threads (use o id do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres de componentes v2 do Discord. - `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + TTS. - `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` são repassados para as opções DAVE de `@discordjs/voice` (`true` e `24` por padrão). -- O OpenClaw também tenta adicionalmente recuperar o recebimento de voz saindo e entrando novamente em uma sessão de voz após falhas repetidas de descriptografia. -- `channels.discord.streaming` é a chave canônica do modo de streaming. Os valores legados `streamMode` e booleanos de `streaming` são migrados automaticamente. -- `channels.discord.autoPresence` mapeia a disponibilidade do runtime para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais do texto de status. -- `channels.discord.dangerouslyAllowNameMatching` reabilita a correspondência por nome/tag mutável (modo de compatibilidade break-glass). -- `channels.discord.execApprovals`: entrega nativa de aprovação de exec do Discord e autorização de aprovadores. - - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. +- O OpenClaw também tenta recuperar a recepção de voz saindo e entrando novamente em uma sessão de voz após falhas repetidas de descriptografia. +- `channels.discord.streaming` é a chave canônica de modo de streaming. As chaves legadas `streamMode` e valores booleanos de `streaming` são migrados automaticamente. +- `channels.discord.autoPresence` mapeia a disponibilidade de runtime para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status. +- `channels.discord.dangerouslyAllowNameMatching` reabilita a correspondência por nome/tag mutáveis (modo de compatibilidade break-glass). +- `channels.discord.execApprovals`: entrega nativa de aprovações de exec no Discord e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo auto, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. - `approvers`: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido. - - `agentFilter`: lista opcional de permissões de IDs de agente. Omita para encaminhar aprovações para todos os agentes. + - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs do aprovador, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos. + - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão) envia para DMs do aprovador, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos. - `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, negação ou timeout. **Modos de notificação de reação:** `off` (nenhum), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds..users` em todas as mensagens). @@ -393,9 +393,9 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic } ``` -- JSON da conta de serviço: embutido (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). -- SecretRef para conta de serviço também é compatível (`serviceAccountRef`). -- Fallbacks de ambiente: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON da conta de serviço: inline (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). +- SecretRef de conta de serviço também é suportado (`serviceAccountRef`). +- Fallbacks por env: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Use `spaces/` ou `users/` para destinos de entrega. - `channels.googlechat.dangerouslyAllowNameMatching` reabilita a correspondência por principal de email mutável (modo de compatibilidade break-glass). @@ -419,7 +419,7 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Apenas respostas curtas.", + systemPrompt: "Short answers only.", }, }, historyLimit: 50, @@ -464,35 +464,35 @@ O WhatsApp é executado por meio do canal web do gateway (Baileys Web). Ele inic } ``` -- O **modo Socket** exige `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como fallback de ambiente da conta padrão). -- O **modo HTTP** exige `botToken` mais `signingSecret` (na raiz ou por conta). +- O **modo Socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como fallback de env da conta padrão). +- O **modo HTTP** requer `botToken` mais `signingSecret` (na raiz ou por conta). - `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples ou objetos SecretRef. - Snapshots de conta do Slack expõem campos por credencial de origem/status, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que a conta está - configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu + configurada por SecretRef, mas o caminho atual de comando/runtime não pôde resolver o valor do segredo. - `configWrites: false` bloqueia gravações de configuração iniciadas pelo Slack. -- O `channels.slack.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- `channels.slack.streaming.mode` é a chave canônica do modo de streaming do Slack. `channels.slack.streaming.nativeTransport` controla o transporte nativo de streaming do Slack. Os valores legados `streamMode`, booleanos de `streaming` e `nativeStreaming` são migrados automaticamente. +- `channels.slack.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.slack.streaming.mode` é a chave canônica do modo de streaming do Slack. `channels.slack.streaming.nativeTransport` controla o transporte nativo de streaming do Slack. As chaves legadas `streamMode`, `streaming` booleano e `nativeStreaming` são migradas automaticamente. - Use `user:` (DM) ou `channel:` para destinos de entrega. **Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`). **Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado em todo o canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads. -- O streaming nativo do Slack, junto com o status de thread em estilo assistente do Slack "is typing...", exige um destino de resposta em thread. DMs de nível superior permanecem fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da pré-visualização em estilo thread. -- `typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto uma resposta está em execução e a remove ao concluir. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega nativa de aprovação de exec do Slack e autorização de aprovadores. Mesmo schema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`). +- Streaming nativo do Slack mais o status de thread “is typing...” no estilo assistente do Slack exigem um destino de resposta em thread. DMs de nível superior permanecem fora de thread por padrão, portanto usam `typingReaction` ou entrega normal em vez da prévia no estilo thread. +- `typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto uma resposta está em execução e depois a remove na conclusão. Use um shortcode de emoji do Slack como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega nativa de aprovações de exec no Slack e autorização de aprovadores. Mesmo schema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`). -| Grupo de ações | Padrão | Observações | -| -------------- | -------- | ---------------------- | -| reactions | habilitado | Reagir + listar reações | -| messages | habilitado | Ler/enviar/editar/excluir | -| pins | habilitado | Fixar/desafixar/listar | -| memberInfo | habilitado | Informações do membro | -| emojiList | habilitado | Lista de emojis personalizados | +| Grupo de ações | Padrão | Observações | +| -------------- | -------- | ------------------------- | +| reactions | enabled | Reagir + listar reações | +| messages | enabled | Ler/enviar/editar/excluir | +| pins | enabled | Fixar/desafixar/listar | +| memberInfo | enabled | Informações de membro | +| emojiList | enabled | Lista de emojis personalizados | ### Mattermost @@ -516,7 +516,7 @@ O Mattermost é distribuído como plugin: `openclaw plugins install @openclaw/ma native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // URL explícita opcional para implantações com proxy reverso/públicas + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +526,23 @@ O Mattermost é distribuído como plugin: `openclaw plugins install @openclaw/ma } ``` -Modos de chat: `oncall` (responde em @-mention, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com o prefixo de acionamento). +Modos de chat: `oncall` (responde em @menção, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com o prefixo de gatilho). Quando os comandos nativos do Mattermost estão habilitados: - `commands.callbackPath` deve ser um caminho (por exemplo `/api/channels/mattermost/command`), não uma URL completa. - `commands.callbackUrl` deve resolver para o endpoint do gateway do OpenClaw e estar acessível a partir do servidor Mattermost. -- Callbacks nativos de slash são autenticados com os tokens por comando retornados - pelo Mattermost durante o registro do slash command. Se o registro falhar ou - nenhum comando for ativado, o OpenClaw rejeitará callbacks com +- Callbacks nativos de slash são autenticados com os tokens por comando + retornados pelo Mattermost durante o registro do slash command. Se o registro falhar ou nenhum + comando for ativado, o OpenClaw rejeitará callbacks com `Unauthorized: invalid command token.` -- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que - `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio do callback. +- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir + que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio do callback. Use valores de host/domínio, não URLs completas. -- `channels.mattermost.configWrites`: permite ou nega gravações de configuração iniciadas pelo Mattermost. -- `channels.mattermost.requireMention`: exige `@mention` antes de responder em canais. -- `channels.mattermost.groups..requireMention`: substituição de bloqueio por menção por canal (`"*"` para o padrão). -- O `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.mattermost.configWrites`: permitir ou negar gravações de configuração iniciadas pelo Mattermost. +- `channels.mattermost.requireMention`: exigir `@mention` antes de responder em canais. +- `channels.mattermost.groups..requireMention`: substituição de gating por menção por canal (`"*"` para o padrão). +- `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### Signal @@ -551,7 +551,7 @@ Quando os comandos nativos do Mattermost estão habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // vínculo de conta opcional + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -565,13 +565,13 @@ Quando os comandos nativos do Mattermost estão habilitados: **Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`). -- `channels.signal.account`: fixa a inicialização do canal em uma identidade específica de conta do Signal. +- `channels.signal.account`: fixa a inicialização do canal a uma identidade de conta específica do Signal. - `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal. -- O `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### BlueBubbles -BlueBubbles é o caminho recomendado para iMessage (com suporte de plugin, configurado em `channels.bluebubbles`). +BlueBubbles é o caminho recomendado para iMessage (com suporte por plugin, configurado em `channels.bluebubbles`). ```json5 { @@ -586,14 +586,14 @@ BlueBubbles é o caminho recomendado para iMessage (com suporte de plugin, confi } ``` -- Caminhos de chave principais abordados aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- O `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador BlueBubbles ou string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). +- Caminhos de chave principais cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador BlueBubbles ou string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). - A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles). ### iMessage -O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é necessário. +O OpenClaw inicia `imsg rpc` (JSON-RPC por stdio). Nenhum daemon ou porta é necessário. ```json5 { @@ -617,15 +617,15 @@ O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é n } ``` -- O `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Requer Acesso Total ao Disco ao banco de dados do Messages. +- Requer Full Disk Access ao banco de dados do Messages. - Prefira destinos `chat_id:`. Use `imsg chats --limit 20` para listar conversas. -- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para busca de anexos via SCP. -- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`). -- O SCP usa verificação estrita de chave de host, portanto garanta que a chave do host de relay já exista em `~/.ssh/known_hosts`. +- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos por SCP. +- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos de entrada (padrão: `/Users/*/Library/Messages/Attachments`). +- O SCP usa verificação estrita de chave do host, portanto garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: permite ou nega gravações de configuração iniciadas pelo iMessage. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou destino explícito de conversa (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). +- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou destino explícito de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -O Matrix tem suporte de extensão e é configurado em `channels.matrix`. +Matrix tem suporte por extensão e é configurado em `channels.matrix`. ```json5 { @@ -670,23 +670,23 @@ O Matrix tem suporte de extensão e é configurado em `channels.matrix`. - A autenticação por token usa `accessToken`; a autenticação por senha usa `userId` + `password`. - `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e este opt-in de rede são controles independentes. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa ativação de rede são controles independentes. - `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas. -- `channels.matrix.autoJoin` usa `off` por padrão, então salas convidadas e novos convites no estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega nativa de aprovação de exec do Matrix e autorização de aprovadores. - - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers`: IDs de usuário do Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de exec. - - `agentFilter`: lista opcional de permissões de IDs de agente. Omita para encaminhar aprovações para todos os agentes. +- `channels.matrix.autoJoin` tem padrão `off`, então salas convidadas e novos convites no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega nativa de aprovações de exec no Matrix e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo auto, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. + - `approvers`: IDs de usuário Matrix (por exemplo `@owner:example.org`) autorizados a aprovar solicitações de exec. + - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. + - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. - Substituições por conta: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha por par roteado, enquanto `per-room` isola cada sala de DM. -- Sondas de status do Matrix e pesquisas em diretório ao vivo usam a mesma política de proxy do tráfego de runtime. +- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha por peer roteado, enquanto `per-room` isola cada sala de DM. +- Sondas de status do Matrix e buscas no diretório ao vivo usam a mesma política de proxy do tráfego de runtime. - A configuração completa do Matrix, regras de direcionamento e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix). ### Microsoft Teams -Microsoft Teams tem suporte de extensão e é configurado em `channels.msteams`. +Microsoft Teams tem suporte por extensão e é configurado em `channels.msteams`. ```json5 { @@ -701,12 +701,12 @@ Microsoft Teams tem suporte de extensão e é configurado em `channels.msteams`. } ``` -- Caminhos de chave principais abordados aqui: `channels.msteams`, `channels.msteams.configWrites`. +- Caminhos de chave principais cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. - A configuração completa do Teams (credenciais, webhook, política de DM/grupo, substituições por equipe/por canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams). ### IRC -IRC tem suporte de extensão e é configurado em `channels.irc`. +IRC tem suporte por extensão e é configurado em `channels.irc`. ```json5 { @@ -727,9 +727,9 @@ IRC tem suporte de extensão e é configurado em `channels.irc`. } ``` -- Caminhos de chave principais abordados aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- O `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissões/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc). +- Caminhos de chave principais cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/gating por menção) está documentada em [IRC](/pt-BR/channels/irc). ### Várias contas (todos os canais) @@ -741,11 +741,11 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): telegram: { accounts: { default: { - name: "Bot principal", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "Bot de alertas", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -756,26 +756,26 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): - `default` é usado quando `accountId` é omitido (CLI + roteamento). - Tokens de ambiente se aplicam apenas à conta **default**. -- As configurações base do canal se aplicam a todas as contas, a menos que sejam substituídas por conta. +- Configurações base do canal se aplicam a todas as contas, a menos que sejam substituídas por conta. - Use `bindings[].match.accountId` para rotear cada conta para um agente diferente. -- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no nível superior, o OpenClaw primeiro promove valores de conta única com escopo de conta do nível superior para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels..accounts.default`; o Matrix pode preservar um destino nomeado/default existente correspondente. -- Bindings existentes apenas de canal (sem `accountId`) continuam correspondendo à conta padrão; bindings com escopo de conta continuam opcionais. -- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única com escopo de conta do nível superior para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um destino nomeado/default existente correspondente. +- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no nível superior, o OpenClaw primeiro promove os valores de conta única com escopo de conta do nível superior para o mapa de contas do canal para que a conta original continue funcionando. A maioria dos canais os move para `channels..accounts.default`; o Matrix pode preservar um destino nomeado/padrão correspondente existente. +- Bindings existentes somente de canal (sem `accountId`) continuam correspondendo à conta padrão; bindings com escopo de conta permanecem opcionais. +- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única com escopo de conta do nível superior para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um destino nomeado/padrão correspondente existente. ### Outros canais de extensão -Muitos canais de extensão são configurados como `channels.` e documentados em suas páginas dedicadas de canal (por exemplo, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). -Veja o índice completo de canais: [Canais](/pt-BR/channels). +Muitos canais de extensão são configurados como `channels.` e documentados em suas páginas de canal dedicadas (por exemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Consulte o índice completo de canais: [Channels](/pt-BR/channels). -### Bloqueio por menção em chat em grupo +### Gating por menção em chat de grupo -Mensagens em grupo, por padrão, **exigem menção** (menção nos metadados ou padrões regex seguros). Aplica-se a grupos do WhatsApp, Telegram, Discord, Google Chat e iMessage. +Mensagens de grupo exigem **menção obrigatória** por padrão (menção em metadados ou padrões regex seguros). Aplica-se a chats em grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de menção:** -- **Menções nos metadados**: menções nativas com @ da plataforma. Ignoradas no modo de conversa consigo mesmo do WhatsApp. +- **Menções em metadados**: @menções nativas da plataforma. Ignoradas no modo self-chat do WhatsApp. - **Padrões de texto**: padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetições aninhadas inseguras são ignorados. -- O bloqueio por menção só é aplicado quando a detecção é possível (menções nativas ou pelo menos um padrão). +- O gating por menção é aplicado apenas quando a detecção é possível (menções nativas ou ao menos um padrão). ```json5 { @@ -788,7 +788,7 @@ Mensagens em grupo, por padrão, **exigem menção** (menção nos metadados ou } ``` -`messages.groupChat.historyLimit` define o padrão global. Os canais podem substituir com `channels..historyLimit` (ou por conta). Defina `0` para desativar. +`messages.groupChat.historyLimit` define o padrão global. Canais podem substituir com `channels..historyLimit` (ou por conta). Defina `0` para desabilitar. #### Limites de histórico de DM @@ -805,13 +805,13 @@ Mensagens em grupo, por padrão, **exigem menção** (menção nos metadados ou } ``` -Resolução: substituição por DM → padrão do provedor → sem limite (tudo retido). +Resolução: substituição por DM → padrão do provedor → sem limite (tudo é mantido). -Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Suportado: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Modo de conversa consigo mesmo +#### Modo self-chat -Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa consigo mesmo (ignora menções nativas com @, responde apenas a padrões de texto): +Inclua seu próprio número em `allowFrom` para habilitar o modo self-chat (ignora @menções nativas, responde apenas a padrões de texto): ```json5 { @@ -837,16 +837,16 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con ```json5 { commands: { - native: "auto", // registra comandos nativos quando compatível - nativeSkills: "auto", // registra comandos nativos de Skills quando compatível - text: true, // interpreta /commands em mensagens de chat - bash: false, // permite ! (alias: /bash) + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // permite /config - mcp: false, // permite /mcp - plugins: false, // permite /plugins - debug: false, // permite /debug - restart: true, // permite /restart + ferramenta de reinicialização do gateway + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,38 +861,38 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con -- Este bloco configura superfícies de comando. Para o catálogo atual de comandos integrados + empacotados, consulte [Comandos de Barra](/pt-BR/tools/slash-commands). -- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice`, estão documentados em suas páginas de canal/plugin e em [Comandos de Barra](/pt-BR/tools/slash-commands). +- Este bloco configura superfícies de comando. Para o catálogo atual de comandos embutidos + em bundle, consulte [Slash Commands](/pt-BR/tools/slash-commands). +- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice`, estão documentados em suas páginas de canal/plugin e também em [Slash Commands](/pt-BR/tools/slash-commands). - Comandos de texto devem ser mensagens **independentes** com `/` no início. -- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém o Slack desativado. -- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém o Slack desativado. -- Substituição por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. -- Substitua o registro de Skills nativas por canal com `channels..commands.nativeSkills`. +- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém Slack desativado. +- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém Slack desativado. +- Substituição por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` remove comandos registrados anteriormente. +- Substitua o registro nativo de Skills por canal com `channels..commands.nativeSkills`. - `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram. -- `bash: true` habilita `! ` para o shell do host. Exige `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do gateway, gravações persistentes com `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes normais do operador com escopo de gravação. -- `mcp: true` habilita `/mcp` para configuração de servidores MCP gerenciados pelo OpenClaw em `mcp.servers`. -- `plugins: true` habilita `/plugins` para descoberta de plugins, instalação e controles de habilitar/desabilitar. +- `bash: true` habilita `! ` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. +- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do gateway, gravações persistentes com `/config set|unset` também exigem `operator.admin`; a opção somente leitura `/config show` continua disponível para clientes normais do operador com escopo de gravação. +- `mcp: true` habilita `/mcp` para configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. +- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de ativação/desativação de plugins. - `channels..configWrites` controla mutações de configuração por canal (padrão: true). -- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações direcionadas a essa conta (por exemplo, `/allowlist --config --account ` ou `/config set channels..accounts....`). -- `restart: false` desativa `/restart` e ações da ferramenta de reinicialização do gateway. Padrão: `true`. -- `ownerAllowFrom` é a lista explícita de permissões do proprietário para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`. -- `ownerDisplay: "hash"` aplica hash aos IDs do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hash. -- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissões/pareamento do canal e `useAccessGroups` são ignorados). +- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações que têm essa conta como destino (por exemplo `/allowlist --config --account ` ou `/config set channels..accounts....`). +- `restart: false` desabilita `/restart` e ações da ferramenta de reinicialização do gateway. Padrão: `true`. +- `ownerAllowFrom` é a allowlist explícita do proprietário para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`. +- `ownerDisplay: "hash"` aplica hash aos ids do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hash. +- `allowFrom` é por provedor. Quando definido, ele é a **única** fonte de autorização (allowlists/pareamento do canal e `useAccessGroups` são ignorados). - `useAccessGroups: false` permite que comandos ignorem políticas de grupo de acesso quando `allowFrom` não está definido. - Mapa da documentação de comandos: - - catálogo integrado + empacotado: [Comandos de Barra](/pt-BR/tools/slash-commands) - - superfícies de comando específicas de canal: [Canais](/pt-BR/channels) + - catálogo embutido + em bundle: [Slash Commands](/pt-BR/tools/slash-commands) + - superfícies de comando específicas de canal: [Channels](/pt-BR/channels) - comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot) - - comandos de pareamento: [Pareamento](/pt-BR/channels/pairing) - - comando de cartão do LINE: [LINE](/pt-BR/channels/line) + - comandos de pareamento: [Pairing](/pt-BR/channels/pairing) + - comando de card do LINE: [LINE](/pt-BR/channels/line) - dreaming de memória: [Dreaming](/pt-BR/concepts/dreaming) --- -## Padrões do agente +## Padrões de agente ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ Padrão: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente percorrendo para cima a partir do workspace. +Raiz opcional do repositório mostrada na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente percorrendo para cima a partir do workspace. ```json5 { @@ -916,7 +916,7 @@ Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se ### `agents.defaults.skills` -Lista opcional padrão de permissões de Skills para agentes que não definem +Allowlist padrão opcional de Skills para agentes que não definem `agents.list[].skills`. ```json5 @@ -935,12 +935,12 @@ Lista opcional padrão de permissões de Skills para agentes que não definem - Omita `agents.defaults.skills` para Skills irrestritas por padrão. - Omita `agents.list[].skills` para herdar os padrões. - Defina `agents.list[].skills: []` para nenhuma Skill. -- Uma lista não vazia em `agents.list[].skills` é o conjunto final para esse agente; ela - não é mesclada com os padrões. +- Uma lista não vazia em `agents.list[].skills` é o conjunto final desse agente; + ela não é mesclada com os padrões. ### `agents.defaults.skipBootstrap` -Desativa a criação automática de arquivos de bootstrap do workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Desabilita a criação automática de arquivos bootstrap do workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -950,9 +950,9 @@ Desativa a criação automática de arquivos de bootstrap do workspace (`AGENTS. ### `agents.defaults.contextInjection` -Controla quando arquivos de bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. +Controla quando os arquivos bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. -- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de heartbeat e novas tentativas após compactação ainda recompõem o contexto. +- `"continuation-skip"`: turnos seguros de continuação (após uma resposta concluída do assistente) ignoram a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de heartbeat e novas tentativas após compactação ainda recompõem o contexto. ```json5 { @@ -962,7 +962,7 @@ Controla quando arquivos de bootstrap do workspace são injetados no prompt do s ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por arquivo de bootstrap do workspace antes do truncamento. Padrão: `20000`. +Máximo de caracteres por arquivo bootstrap do workspace antes de truncamento. Padrão: `20000`. ```json5 { @@ -972,7 +972,7 @@ Máximo de caracteres por arquivo de bootstrap do workspace antes do truncamento ### `agents.defaults.bootstrapTotalMaxChars` -Máximo total de caracteres injetados em todos os arquivos de bootstrap do workspace. Padrão: `150000`. +Máximo total de caracteres injetados em todos os arquivos bootstrap do workspace. Padrão: `150000`. ```json5 { @@ -982,7 +982,7 @@ Máximo total de caracteres injetados em todos os arquivos de bootstrap do works ### `agents.defaults.bootstrapPromptTruncationWarning` -Controla o texto de aviso visível ao agente quando o contexto de bootstrap é truncado. +Controla o texto de aviso visível ao agente quando o contexto bootstrap é truncado. Padrão: `"once"`. - `"off"`: nunca injeta texto de aviso no prompt do sistema. @@ -997,11 +997,11 @@ Padrão: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Tamanho máximo em pixels do lado mais longo da imagem em blocos de imagem do histórico/ferramenta antes das chamadas ao provedor. +Tamanho máximo em pixels do lado mais longo da imagem em blocos de imagem de transcrição/ferramenta antes das chamadas ao provedor. Padrão: `1200`. -Valores mais baixos normalmente reduzem o uso de tokens de visão e o tamanho da carga útil da requisição em execuções com muitas capturas de tela. -Valores mais altos preservam mais detalhes visuais. +Valores menores normalmente reduzem o uso de tokens de visão e o tamanho da carga da requisição em execuções com muitas capturas de tela. +Valores maiores preservam mais detalhes visuais. ```json5 { @@ -1011,7 +1011,7 @@ Valores mais altos preservam mais detalhes visuais. ### `agents.defaults.userTimezone` -Fuso horário para o contexto do prompt do sistema (não para timestamps de mensagens). Usa o fuso horário do host como fallback. +Fuso horário para o contexto do prompt do sistema (não para os carimbos de data/hora das mensagens). Usa o fuso horário do host como fallback. ```json5 { @@ -1059,7 +1059,7 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // parâmetros padrão globais do provedor + params: { cacheRetention: "long" }, // parâmetros globais padrão do provedor embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1079,40 +1079,40 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). ``` - `model`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - A forma em string define apenas o modelo principal. - - A forma em objeto define o principal mais modelos de failover ordenados. + - A forma string define apenas o modelo principal. + - A forma objeto define o principal mais modelos ordenados de failover. - `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pelo caminho da ferramenta `image` como configuração do modelo de visão. - - Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem. + - Usado pelo caminho da ferramenta `image` como sua configuração de modelo de visão. + - Também usado como roteamento de fallback quando o modelo selecionado/padrão não pode aceitar entrada de imagem. - `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - Usado pela capacidade compartilhada de geração de imagem e por qualquer futura superfície de ferramenta/plugin que gere imagens. - - Valores típicos: `google/gemini-3.1-flash-image-preview` para geração de imagens nativa do Gemini, `fal/fal-ai/flux/dev` para fal, ou `openai/gpt-image-1` para OpenAI Images. - - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor (por exemplo, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). - - Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de imagem registrados na ordem de ID do provedor. + - Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagem do Gemini, `fal/fal-ai/flux/dev` para fal, ou `openai/gpt-image-1` para OpenAI Images. + - Se você selecionar diretamente um provedor/modelo, configure também a autenticação/chave de API correspondente do provedor (por exemplo `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). + - Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de imagem registrados em ordem de id do provedor. - `musicGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de música e pela ferramenta integrada `music_generate`. + - Usado pela capacidade compartilhada de geração de música e pela ferramenta embutida `music_generate`. - Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.5+`. - - Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de música registrados na ordem de ID do provedor. - - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor. + - Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de música registrados em ordem de id do provedor. + - Se você selecionar diretamente um provedor/modelo, configure também a autenticação/chave de API correspondente do provedor. - `videoGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta integrada `video_generate`. + - Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta embutida `video_generate`. - Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`. - - Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de vídeo registrados na ordem de ID do provedor. - - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor. - - O provedor empacotado de geração de vídeo Qwen oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções em nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. + - Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de vídeo registrados em ordem de id do provedor. + - Se você selecionar diretamente um provedor/modelo, configure também a autenticação/chave de API correspondente do provedor. + - O provedor em bundle de geração de vídeo Qwen oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções no nível do provedor para `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. - `pdfModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - Usado pela ferramenta `pdf` para roteamento de modelo. - - Se omitido, a ferramenta PDF recorre a `imageModel` e depois ao modelo resolvido da sessão/padrão. + - Se omitido, a ferramenta PDF usa `imageModel` como fallback e depois o modelo resolvido da sessão/padrão. - `pdfMaxBytesMb`: limite padrão de tamanho de PDF para a ferramenta `pdf` quando `maxBytesMb` não é passado no momento da chamada. - `pdfMaxPages`: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`. -- `verboseDefault`: nível verbose padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. +- `verboseDefault`: nível padrão de verbose para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. - `elevatedDefault`: nível padrão de saída elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Padrão: `"on"`. -- `model.primary`: formato `provider/model` (por exemplo `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência exclusiva de provedor configurado para esse ID exato de modelo e só então recorre ao provedor padrão configurado (comportamento de compatibilidade obsoleto, então prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provider/model configurado em vez de exibir um padrão obsoleto de provedor removido. -- `models`: o catálogo de modelos configurado e a lista de permissões para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parâmetros padrão globais do provedor aplicados a todos os modelos. Defina em `agents.defaults.params` (por exemplo `{ cacheRetention: "long" }`). -- Precedência de mesclagem de `params` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), e depois `agents.list[].params` (ID de agente correspondente) substitui por chave. Consulte [Cache de Prompt](/pt-BR/reference/prompt-caching) para detalhes. -- `embeddedHarness`: política padrão de runtime embutido de baixo nível do agente. Use `runtime: "auto"` para permitir que harnesses de plugin registrados assumam modelos compatíveis, `runtime: "pi"` para forçar o harness PI integrado, ou um ID de harness registrado, como `runtime: "codex"`. Defina `fallback: "none"` para desativar o fallback automático para PI. -- Gravadores de configuração que alteram esses campos (por exemplo `/models set`, `/models set-image` e comandos add/remove de fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível. +- `model.primary`: formato `provider/model` (por exemplo `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse id exato de modelo e só então volta para o provedor padrão configurado (comportamento de compatibilidade obsoleto, então prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw volta para o primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido. +- `models`: o catálogo de modelos configurado e a allowlist para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Defina em `agents.defaults.params` (por exemplo `{ cacheRetention: "long" }`). +- Precedência de mesclagem de `params` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), depois `agents.list[].params` (id de agente correspondente) substitui por chave. Consulte [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. +- `embeddedHarness`: política padrão de runtime embutido de baixo nível para agentes. Use `runtime: "auto"` para permitir que harnesses de plugin registrados assumam modelos compatíveis, `runtime: "pi"` para forçar o harness PI embutido, ou um id de harness registrado, como `runtime: "codex"`. Defina `fallback: "none"` para desabilitar o fallback automático para PI. +- Gravadores de configuração que alteram esses campos (por exemplo `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível. - `maxConcurrent`: máximo de execuções paralelas de agentes entre sessões (cada sessão ainda é serializada). Padrão: 4. ### `agents.defaults.embeddedHarness` @@ -1120,7 +1120,7 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). `embeddedHarness` controla qual executor de baixo nível executa turnos de agentes embutidos. A maioria das implantações deve manter o padrão `{ runtime: "auto", fallback: "pi" }`. Use-o quando um plugin confiável fornecer um harness nativo, como o harness -do app-server Codex empacotado. +de app-server Codex em bundle. ```json5 { @@ -1136,13 +1136,13 @@ do app-server Codex empacotado. } ``` -- `runtime`: `"auto"`, `"pi"` ou um ID de harness de plugin registrado. O plugin Codex empacotado registra `codex`. -- `fallback`: `"pi"` ou `"none"`. `"pi"` mantém o harness PI integrado como fallback de compatibilidade. `"none"` faz com que seleção ausente ou incompatível de harness de plugin falhe em vez de usar silenciosamente o PI. -- Substituições por ambiente: `OPENCLAW_AGENT_RUNTIME=` substitui `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desativa o fallback para PI nesse processo. +- `runtime`: `"auto"`, `"pi"` ou um id de harness de plugin registrado. O plugin Codex em bundle registra `codex`. +- `fallback`: `"pi"` ou `"none"`. `"pi"` mantém o harness PI embutido como fallback de compatibilidade. `"none"` faz com que a seleção de harness de plugin ausente ou incompatível falhe em vez de usar PI silenciosamente. +- Substituições por ambiente: `OPENCLAW_AGENT_RUNTIME=` substitui `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desabilita o fallback para PI nesse processo. - Para implantações somente com Codex, defina `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. -- Isso controla apenas o harness de chat embutido. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provider/model. +- Isso controla apenas o harness de chat embutido. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provedor/modelo. -**Atalhos de alias integrados** (aplicam-se apenas quando o modelo está em `agents.defaults.models`): +**Atalhos de alias embutidos** (só se aplicam quando o modelo está em `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1155,11 +1155,11 @@ do app-server Codex empacotado. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Seus aliases configurados sempre prevalecem sobre os padrões. +Seus aliases configurados sempre têm prioridade sobre os padrões. -Modelos Z.AI GLM-4.x habilitam automaticamente o modo thinking, a menos que você defina `--thinking off` ou defina `agents.defaults.models["zai/"].params.thinking` manualmente. -Modelos Z.AI habilitam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desativá-lo. -Modelos Anthropic Claude 4.6 usam `adaptive` thinking por padrão quando nenhum nível explícito de thinking é definido. +Modelos Z.AI GLM-4.x ativam automaticamente o modo thinking, a menos que você defina `--thinking off` ou defina `agents.defaults.models["zai/"].params.thinking` por conta própria. +Modelos Z.AI ativam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desativá-lo. +Modelos Anthropic Claude 4.6 usam `adaptive` como padrão para thinking quando nenhum nível explícito de thinking está definido. ### `agents.defaults.cliBackends` @@ -1191,19 +1191,19 @@ Backends opcionais de CLI para execuções de fallback somente texto (sem chamad } ``` -- Backends de CLI são voltados primeiro para texto; ferramentas estão sempre desativadas. -- Sessões são compatíveis quando `sessionArg` está definido. -- Passagem direta de imagem é compatível quando `imageArg` aceita caminhos de arquivo. +- Backends de CLI são voltados para texto; ferramentas são sempre desabilitadas. +- Sessões são suportadas quando `sessionArg` está definido. +- Passagem de imagens é suportada quando `imageArg` aceita caminhos de arquivo. ### `agents.defaults.systemPromptOverride` -Substitui todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou contendo apenas espaços é ignorado. Útil para experimentos controlados de prompt. +Substitui todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou apenas com espaços é ignorado. Útil para experimentos controlados de prompt. ```json5 { agents: { defaults: { - systemPromptOverride: "Você é um assistente útil.", + systemPromptOverride: "You are a helpful assistant.", }, }, } @@ -1218,17 +1218,17 @@ Execuções periódicas de heartbeat. agents: { defaults: { heartbeat: { - every: "30m", // 0m desativa + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // padrão: true; false omite a seção Heartbeat do prompt do sistema - lightContext: false, // padrão: false; true mantém apenas HEARTBEAT.md dos arquivos bootstrap do workspace - isolatedSession: false, // padrão: false; true executa cada heartbeat em uma sessão nova (sem histórico de conversa) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (padrão) | block - target: "none", // padrão: none | opções: last | whatsapp | telegram | discord | ... - prompt: "Leia HEARTBEAT.md se ele existir...", + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, timeoutSeconds: 45, @@ -1238,15 +1238,15 @@ Execuções periódicas de heartbeat. } ``` -- `every`: string de duração (ms/s/m/h). Padrão: `30m` (autenticação por chave de API) ou `1h` (autenticação OAuth). Defina `0m` para desativar. -- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt do sistema e pula a injeção de `HEARTBEAT.md` no contexto de bootstrap. Padrão: `true`. -- `suppressToolErrorWarnings`: quando true, suprime cargas úteis de aviso de erro de ferramenta durante execuções de heartbeat. +- `every`: string de duração (ms/s/m/h). Padrão: `30m` (autenticação por chave de API) ou `1h` (autenticação OAuth). Defina `0m` para desabilitar. +- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt do sistema e pula a injeção de `HEARTBEAT.md` no contexto bootstrap. Padrão: `true`. +- `suppressToolErrorWarnings`: quando true, suprime payloads de aviso de erro de ferramenta durante execuções de heartbeat. - `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de heartbeat antes de ser abortado. Deixe sem definir para usar `agents.defaults.timeoutSeconds`. -- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega com destino direto. `block` suprime entrega com destino direto e emite `reason=dm-blocked`. +- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para alvo direto. `block` suprime entrega para alvo direto e emite `reason=dm-blocked`. - `lightContext`: quando true, execuções de heartbeat usam contexto bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos bootstrap do workspace. -- `isolatedSession`: quando true, cada heartbeat é executado em uma sessão nova sem histórico de conversa anterior. Mesmo padrão de isolamento de cron `sessionTarget: "isolated"`. Reduz o custo por heartbeat de ~100K para ~2-5K tokens. +- `isolatedSession`: quando true, cada execução de heartbeat roda em uma sessão nova, sem histórico prévio de conversa. Mesmo padrão de isolamento de cron `sessionTarget: "isolated"`. Reduz o custo de tokens por heartbeat de ~100K para ~2-5K tokens. - Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **somente esses agentes** executam heartbeats. -- Heartbeats executam turnos completos de agente — intervalos menores consomem mais tokens. +- Heartbeats executam turnos completos de agente — intervalos mais curtos consomem mais tokens. ### `agents.defaults.compaction` @@ -1256,13 +1256,13 @@ Execuções periódicas de heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id de um plugin de provedor de compactação registrado (opcional) + provider: "my-provider", // id de um plugin provedor de compactação registrado (opcional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // usado quando identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] desativa a reinjeção - model: "openrouter/anthropic/claude-sonnet-4-6", // substituição opcional de modelo somente para compactação + postCompactionSections: ["Session Startup", "Red Lines"], // [] desabilita reinjeção + model: "openrouter/anthropic/claude-sonnet-4-6", // substituição opcional de modelo apenas para compactação notifyUser: true, // envia um aviso breve quando a compactação começa (padrão: false) memoryFlush: { enabled: true, @@ -1276,19 +1276,19 @@ Execuções periódicas de heartbeat. } ``` -- `mode`: `default` ou `safeguard` (sumarização em blocos para históricos longos). Consulte [Compactação](/pt-BR/concepts/compaction). -- `provider`: ID de um plugin de provedor de compactação registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização LLM integrada. Em caso de falha, recorre ao integrado. Definir um provedor força `mode: "safeguard"`. Consulte [Compactação](/pt-BR/concepts/compaction). +- `mode`: `default` ou `safeguard` (sumarização em blocos para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction). +- `provider`: id de um plugin provedor de compactação registrado. Quando definido, `summarize()` do provedor é chamado em vez da sumarização LLM embutida. Em caso de falha, volta para a embutida. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction). - `timeoutSeconds`: máximo de segundos permitidos para uma única operação de compactação antes de o OpenClaw abortá-la. Padrão: `900`. -- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` adiciona instruções integradas de retenção de identificadores opacos durante a sumarização da compactação. -- `identifierInstructions`: texto personalizado opcional de preservação de identificadores usado quando `identifierPolicy=custom`. -- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após a compactação. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desativar a reinjeção. Quando não definido ou definido explicitamente como esse par padrão, os cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado. -- `model`: substituição opcional `provider/model-id` somente para a sumarização da compactação. Use isso quando a sessão principal deve manter um modelo, mas os resumos de compactação devem usar outro; quando não definido, a compactação usa o modelo principal da sessão. -- `notifyUser`: quando `true`, envia um aviso breve ao usuário quando a compactação começa (por exemplo, "Compactando contexto..."). Desativado por padrão para manter a compactação silenciosa. +- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` prefixa orientação embutida de retenção de identificadores opacos durante a sumarização da compactação. +- `identifierInstructions`: texto opcional personalizado de preservação de identificadores usado quando `identifierPolicy=custom`. +- `postCompactionSections`: nomes opcionais de seções H2/H3 do AGENTS.md para reinjetar após a compactação. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desabilitar a reinjeção. Quando não definido ou explicitamente definido para esse par padrão, cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado. +- `model`: substituição opcional `provider/model-id` apenas para a sumarização de compactação. Use isso quando a sessão principal deve manter um modelo, mas os resumos de compactação devem usar outro; quando não definido, a compactação usa o modelo principal da sessão. +- `notifyUser`: quando `true`, envia um aviso breve ao usuário quando a compactação começa (por exemplo, "Compacting context..."). Desabilitado por padrão para manter a compactação silenciosa. - `memoryFlush`: turno agentivo silencioso antes da compactação automática para armazenar memórias duráveis. Ignorado quando o workspace é somente leitura. ### `agents.defaults.contextPruning` -Remove **resultados antigos de ferramentas** do contexto em memória antes de enviar ao LLM. **Não** modifica o histórico da sessão em disco. +Remove **resultados antigos de ferramentas** do contexto em memória antes do envio ao LLM. **Não** modifica o histórico da sessão em disco. ```json5 { @@ -1312,25 +1312,25 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en -- `mode: "cache-ttl"` habilita passagens de remoção. -- `ttl` controla com que frequência a remoção pode ser executada novamente (após o último toque de cache). -- A remoção primeiro faz soft-trim de resultados de ferramentas grandes demais e depois faz hard-clear em resultados mais antigos, se necessário. +- `mode: "cache-ttl"` habilita passagens de poda. +- `ttl` controla com que frequência a poda pode ser executada novamente (após o último toque no cache). +- A poda primeiro faz soft-trim de resultados de ferramenta grandes demais e depois faz hard-clear de resultados de ferramenta mais antigos, se necessário. -**Soft-trim** mantém o começo + o fim e insere `...` no meio. +**Soft-trim** mantém o início + fim e insere `...` no meio. -**Hard-clear** substitui todo o resultado da ferramenta pelo marcador. +**Hard-clear** substitui todo o resultado da ferramenta pelo placeholder. Observações: -- Blocos de imagem nunca são truncados/removidos. +- Blocos de imagem nunca são podados/apagados. - As proporções são baseadas em caracteres (aproximadas), não em contagens exatas de tokens. -- Se existirem menos de `keepLastAssistants` mensagens do assistente, a remoção será ignorada. +- Se existirem menos de `keepLastAssistants` mensagens do assistente, a poda é ignorada. -Consulte [Limpeza de sessão](/pt-BR/concepts/session-pruning) para detalhes de comportamento. +Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes do comportamento. -### Streaming em bloco +### Streaming em blocos ```json5 { @@ -1347,10 +1347,10 @@ Consulte [Limpeza de sessão](/pt-BR/concepts/session-pruning) para detalhes de ``` - Canais que não sejam Telegram exigem `*.blockStreaming: true` explícito para habilitar respostas em bloco. -- Substituições por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam por padrão `minChars: 1500`. +- Substituições por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam `minChars: 1500` por padrão. - `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`. -Consulte [Streaming](/pt-BR/concepts/streaming) para comportamento + detalhes de fragmentação. +Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + fragmentação. ### Indicadores de digitação @@ -1365,10 +1365,10 @@ Consulte [Streaming](/pt-BR/concepts/streaming) para comportamento + detalhes de } ``` -- Padrões: `instant` para chats diretos/menções, `message` para chats em grupo sem menção. +- Padrões: `instant` para chats diretos/menções, `message` para chats de grupo sem menção. - Substituições por sessão: `session.typingMode`, `session.typingIntervalSeconds`. -Consulte [Indicadores de digitação](/pt-BR/concepts/typing-indicators). +Consulte [Typing Indicators](/pt-BR/concepts/typing-indicators). @@ -1420,7 +1420,7 @@ Sandboxing opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / conteúdo embutido também são compatíveis: + // SecretRefs / conteúdo inline também são suportados: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1473,11 +1473,11 @@ Sandboxing opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway **Backend:** -- `docker`: runtime Docker local (padrão) -- `ssh`: runtime remoto genérico com suporte de SSH +- `docker`: runtime local do Docker (padrão) +- `ssh`: runtime remoto genérico com suporte por SSH - `openshell`: runtime OpenShell -Quando `backend: "openshell"` é selecionado, as configurações específicas do runtime vão para +Quando `backend: "openshell"` é selecionado, as configurações específicas do runtime são movidas para `plugins.entries.openshell.config`. **Configuração do backend SSH:** @@ -1485,23 +1485,23 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas do - `target`: destino SSH no formato `user@host[:port]` - `command`: comando do cliente SSH (padrão: `ssh`) - `workspaceRoot`: raiz remota absoluta usada para workspaces por escopo -- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados ao OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: conteúdo embutido ou SecretRefs que o OpenClaw materializa em arquivos temporários em tempo de execução -- `strictHostKeyChecking` / `updateHostKeys`: parâmetros de política de chave de host do OpenSSH +- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes repassados ao OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: conteúdos inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime +- `strictHostKeyChecking` / `updateHostKeys`: controles de política de chave de host do OpenSSH **Precedência de autenticação SSH:** - `identityData` tem prioridade sobre `identityFile` - `certificateData` tem prioridade sobre `certificateFile` - `knownHostsData` tem prioridade sobre `knownHostsFile` -- Valores `*Data` com suporte de SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão sandbox +- Valores `*Data` com suporte por SecretRef são resolvidos a partir do snapshot de runtime de segredos ativo antes de a sessão sandbox começar **Comportamento do backend SSH:** -- inicializa o workspace remoto uma vez após criar ou recriar +- semeia o workspace remoto uma vez após criação ou recriação - depois mantém o workspace SSH remoto como canônico - roteia `exec`, ferramentas de arquivo e caminhos de mídia por SSH -- não sincroniza alterações remotas de volta ao host automaticamente +- não sincroniza automaticamente alterações remotas de volta para o host - não oferece suporte a contêineres de navegador do sandbox **Acesso ao workspace:** @@ -1531,7 +1531,7 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas do remoteAgentWorkspaceDir: "/agent", gateway: "lab", // opcional gatewayEndpoint: "https://lab.example", // opcional - policy: "strict", // ID opcional de política OpenShell + policy: "strict", // id opcional de política do OpenShell providers: ["openai"], // opcional autoProviders: true, timeoutSeconds: 120, @@ -1544,28 +1544,28 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas do **Modo OpenShell:** -- `mirror`: inicializa o remoto a partir do local antes de `exec`, sincroniza de volta após `exec`; o workspace local permanece canônico -- `remote`: inicializa o remoto uma vez quando o sandbox é criado, depois mantém o workspace remoto como canônico +- `mirror`: semeia o remoto a partir do local antes de `exec`, sincroniza de volta após `exec`; o workspace local permanece canônico +- `remote`: semeia o remoto uma vez quando o sandbox é criado, depois mantém o workspace remoto como canônico -No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa de inicialização. -O transporte é SSH para o sandbox OpenShell, mas o plugin controla o ciclo de vida do sandbox e a sincronização opcional em modo espelho. +No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa de semeadura. +O transporte é SSH para dentro do sandbox OpenShell, mas o plugin é responsável pelo ciclo de vida do sandbox e pela sincronização opcional no modo mirror. -**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Precisa de saída de rede, raiz gravável e usuário root. +**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Requer saída de rede, raiz gravável e usuário root. **Os contêineres usam `network: "none"` por padrão** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. `"host"` é bloqueado. `"container:"` é bloqueado por padrão, a menos que você defina explicitamente `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Anexos de entrada** são preparados em `media/inbound/*` no workspace ativo. +**Anexos recebidos** são preparados em `media/inbound/*` no workspace ativo. -**`docker.binds`** monta diretórios adicionais do host; bindings globais e por agente são mesclados. +**`docker.binds`** monta diretórios adicionais do host; binds globais e por agente são mesclados. **Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. A URL do noVNC é injetada no prompt do sistema. Não exige `browser.enabled` em `openclaw.json`. -O acesso de observador via noVNC usa autenticação VNC por padrão, e o OpenClaw emite uma URL com token de curta duração (em vez de expor a senha na URL compartilhada). +O acesso de observador no noVNC usa autenticação VNC por padrão, e o OpenClaw emite uma URL com token de curta duração (em vez de expor a senha na URL compartilhada). -- `allowHostControl: false` (padrão) bloqueia sessões em sandbox de direcionarem para o navegador do host. -- `network` usa por padrão `openclaw-sandbox-browser` (rede bridge dedicada). Defina `bridge` apenas quando você quiser explicitamente conectividade global da bridge. -- `cdpSourceRange` restringe opcionalmente a entrada CDP na borda do contêiner a um intervalo CIDR (por exemplo `172.21.0.1/32`). +- `allowHostControl: false` (padrão) bloqueia sessões em sandbox de direcionar para o navegador do host. +- `network` usa `openclaw-sandbox-browser` por padrão (rede bridge dedicada). Defina `bridge` apenas quando você quiser explicitamente conectividade global de bridge. +- `cdpSourceRange` restringe opcionalmente a entrada de CDP na borda do contêiner a um intervalo CIDR (por exemplo `172.21.0.1/32`). - `sandbox.browser.binds` monta diretórios adicionais do host apenas no contêiner do navegador em sandbox. Quando definido (inclusive `[]`), substitui `docker.binds` para o contêiner do navegador. - Os padrões de inicialização são definidos em `scripts/sandbox-browser-entrypoint.sh` e ajustados para hosts em contêiner: - `--remote-debugging-address=127.0.0.1` @@ -1586,19 +1586,19 @@ O acesso de observador via noVNC usa autenticação VNC por padrão, e o OpenCla - `--metrics-recording-only` - `--disable-extensions` (habilitado por padrão) - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` são - habilitados por padrão e podem ser desativados com + habilitados por padrão e podem ser desabilitados com `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir isso. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se o seu fluxo de trabalho depender delas. - `--renderer-process-limit=2` pode ser alterado com `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; defina `0` para usar o - limite de processos padrão do Chromium. + limite padrão de processos do Chromium. - além de `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` está habilitado. - - Os padrões são a linha de base da imagem do contêiner; use uma imagem de navegador personalizada com um entrypoint personalizado para alterar os padrões do contêiner. + - Os padrões são a baseline da imagem do contêiner; use uma imagem de navegador personalizada com um entrypoint personalizado para alterar os padrões do contêiner. -O sandbox do navegador e `sandbox.docker.binds` são compatíveis apenas com Docker. +O sandboxing do navegador e `sandbox.docker.binds` são exclusivos do Docker. Criar imagens: @@ -1616,16 +1616,16 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador { id: "main", default: true, - name: "Agente principal", + name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // ou { primary, fallbacks } - thinkingDefault: "high", // substituição por agente para nível de thinking - reasoningDefault: "on", // substituição por agente para visibilidade de reasoning - fastModeDefault: false, // substituição por agente para fast mode + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // substitui por chave os params correspondentes de defaults.models - skills: ["docs-search"], // substitui agents.defaults.skills quando definido + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1656,27 +1656,27 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador } ``` -- `id`: ID estável do agente (obrigatório). -- `default`: quando vários são definidos, o primeiro prevalece (aviso registrado). Se nenhum for definido, a primeira entrada da lista é o padrão. -- `model`: a forma em string substitui apenas `primary`; a forma em objeto `{ primary, fallbacks }` substitui ambos (`[]` desativa fallbacks globais). Jobs de cron que substituem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`. -- `params`: params de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isso para substituições específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar o catálogo inteiro de modelos. -- `skills`: lista opcional de permissões de Skills por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa nenhuma Skill. -- `thinkingDefault`: nível padrão opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Substitui `agents.defaults.thinkingDefault` para esse agente quando nenhuma substituição por mensagem ou sessão está definida. -- `reasoningDefault`: visibilidade padrão opcional de reasoning por agente (`on | off | stream`). Aplica-se quando nenhuma substituição de reasoning por mensagem ou sessão está definida. -- `fastModeDefault`: padrão opcional por agente para fast mode (`true | false`). Aplica-se quando nenhuma substituição de fast mode por mensagem ou sessão está definida. -- `embeddedHarness`: substituição opcional por agente para a política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback PI padrão. +- `id`: id estável do agente (obrigatório). +- `default`: quando vários estão definidos, o primeiro vence (um aviso é registrado). Se nenhum estiver definido, a primeira entrada da lista é o padrão. +- `model`: a forma string substitui apenas `primary`; a forma objeto `{ primary, fallbacks }` substitui ambos (`[]` desabilita fallbacks globais). Jobs de cron que substituem apenas `primary` ainda herdam os fallbacks padrão, a menos que você defina `fallbacks: []`. +- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isso para substituições específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar o catálogo completo de modelos. +- `skills`: allowlist opcional de Skills por agente. Se omitido, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa nenhuma Skill. +- `thinkingDefault`: substituição opcional por agente do nível padrão de thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Substitui `agents.defaults.thinkingDefault` para esse agente quando não houver substituição por mensagem ou sessão. +- `reasoningDefault`: substituição opcional por agente da visibilidade padrão de reasoning (`on | off | stream`). Aplica-se quando não houver substituição de reasoning por mensagem ou sessão. +- `fastModeDefault`: padrão opcional por agente para modo rápido (`true | false`). Aplica-se quando não houver substituição de modo rápido por mensagem ou sessão. +- `embeddedHarness`: substituição opcional por agente da política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente exclusivo de Codex, enquanto outros agentes mantêm o fallback padrão para PI. - `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar por padrão sessões de harness ACP. - `identity.avatar`: caminho relativo ao workspace, URL `http(s)` ou URI `data:`. - `identity` deriva padrões: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`. -- `subagents.allowAgents`: lista de permissões de IDs de agente para `sessions_spawn` (`["*"]` = qualquer; padrão: somente o mesmo agente). -- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita destinos que seriam executados fora de sandbox. +- `subagents.allowAgents`: allowlist de ids de agente para `sessions_spawn` (`["*"]` = qualquer um; padrão: somente o mesmo agente). +- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita alvos que seriam executados sem sandbox. - `subagents.requireAgentId`: quando true, bloqueia chamadas de `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false). --- -## Roteamento de vários agentes +## Roteamento multiagente -Execute vários agentes isolados dentro de um Gateway. Consulte [Vários Agentes](/pt-BR/concepts/multi-agent). +Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/pt-BR/concepts/multi-agent). ```json5 { @@ -1693,13 +1693,13 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Vários Agentes } ``` -### Campos de correspondência do binding +### Campos de correspondência de binding -- `type` (opcional): `route` para roteamento normal (tipo ausente usa `route` como padrão), `acp` para bindings persistentes de conversa ACP. +- `type` (opcional): `route` para roteamento normal (tipo ausente usa route por padrão), `acp` para bindings persistentes de conversa ACP. - `match.channel` (obrigatório) - `match.accountId` (opcional; `*` = qualquer conta; omitido = conta padrão) - `match.peer` (opcional; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (opcional; específico do canal) +- `match.guildId` / `match.teamId` (opcional; específicos de canal) - `acp` (opcional; apenas para entradas `type: "acp"`): `{ mode, label, cwd, backend }` **Ordem determinística de correspondência:** @@ -1708,12 +1708,12 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Vários Agentes 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (exato, sem peer/guild/team) -5. `match.accountId: "*"` (em todo o canal) +5. `match.accountId: "*"` (canal inteiro) 6. Agente padrão -Dentro de cada nível, a primeira entrada correspondente em `bindings` prevalece. +Dentro de cada nível, a primeira entrada correspondente em `bindings` vence. -Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem por níveis de binding de rota acima. +Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de binding de rota acima. ### Perfis de acesso por agente @@ -1810,7 +1810,7 @@ Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da convers -Consulte [Sandbox e Ferramentas para Vários Agentes](/pt-BR/tools/multi-agent-sandbox-tools) para detalhes de precedência. +Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) para detalhes de precedência. --- @@ -1836,20 +1836,20 @@ Consulte [Sandbox e Ferramentas para Vários Agentes](/pt-BR/tools/multi-agent-s }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // ignora fork de thread pai acima dessa contagem de tokens (0 desativa) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duração ou false - maxDiskBytes: "500mb", // orçamento rígido opcional - highWaterBytes: "400mb", // destino opcional de limpeza + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // desfoco automático padrão por inatividade em horas (`0` desativa) - maxAgeHours: 0, // idade máxima rígida padrão em horas (`0` desativa) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, mainKey: "main", // legado (o runtime sempre usa "main") agentToAgent: { maxPingPongTurns: 5 }, @@ -1865,33 +1865,33 @@ Consulte [Sandbox e Ferramentas para Vários Agentes](/pt-BR/tools/multi-agent-s - **`scope`**: estratégia base de agrupamento de sessão para contextos de chat em grupo. - `per-sender` (padrão): cada remetente recebe uma sessão isolada dentro de um contexto de canal. - - `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use apenas quando o contexto compartilhado for intencional). + - `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use apenas quando contexto compartilhado for intencional). - **`dmScope`**: como as DMs são agrupadas. - `main`: todas as DMs compartilham a sessão principal. - - `per-peer`: isola por ID do remetente entre canais. + - `per-peer`: isola por id do remetente entre canais. - `per-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada com vários usuários). - `per-account-channel-peer`: isola por conta + canal + remetente (recomendado para várias contas). -- **`identityLinks`**: mapeia IDs canônicos para peers com prefixo de provedor para compartilhamento de sessão entre canais. -- **`reset`**: política principal de redefinição. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, o que expirar primeiro prevalece. +- **`identityLinks`**: mapeia ids canônicos para peers com prefixo de provedor para compartilhamento de sessão entre canais. +- **`reset`**: política principal de redefinição. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, vale o que expirar primeiro. - **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O legado `dm` é aceito como alias para `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread derivada (padrão `100000`). - - Se `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico da transcrição da sessão pai. - - Defina `0` para desativar essa proteção e sempre permitir a derivação da sessão pai. +- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread bifurcada (padrão `100000`). + - Se `totalTokens` do pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico da transcrição da sessão pai. + - Defina `0` para desabilitar essa proteção e sempre permitir bifurcação da sessão pai. - **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de chat direto. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta entre agentes durante trocas entre agentes (inteiro, intervalo: `0`–`5`). `0` desativa o encadeamento ping-pong. -- **`sendPolicy`**: corresponde por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira regra de negação prevalece. -- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessão. +- **`agentToAgent.maxPingPongTurns`**: máximo de turnos de resposta entre agentes durante trocas agente a agente (inteiro, intervalo: `0`–`5`). `0` desabilita encadeamento ping-pong. +- **`sendPolicy`**: corresponde por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira regra de negação vence. +- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessões. - `mode`: `warn` emite apenas avisos; `enforce` aplica a limpeza. - - `pruneAfter`: corte de idade para entradas obsoletas (padrão `30d`). + - `pruneAfter`: limite de idade para entradas obsoletas (padrão `30d`). - `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). - - `rotateBytes`: rotaciona `sessions.json` quando ultrapassa esse tamanho (padrão `10mb`). - - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. O padrão é `pruneAfter`; defina `false` para desativar. + - `rotateBytes`: gira `sessions.json` quando excede esse tamanho (padrão `10mb`). + - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Usa `pruneAfter` por padrão; defina `false` para desabilitar. - `maxDiskBytes`: orçamento opcional de disco para o diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos. - - `highWaterBytes`: destino opcional após a limpeza por orçamento. O padrão é `80%` de `maxDiskBytes`. + - `highWaterBytes`: alvo opcional após limpeza por orçamento. Usa `80%` de `maxDiskBytes` por padrão. - **`threadBindings`**: padrões globais para recursos de sessão vinculados a thread. - `enabled`: chave mestra padrão (provedores podem substituir; o Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: desfoco automático padrão por inatividade em horas (`0` desativa; provedores podem substituir) - - `maxAgeHours`: idade máxima rígida padrão em horas (`0` desativa; provedores podem substituir) + - `idleHours`: padrão de desfoco automático por inatividade em horas (`0` desabilita; provedores podem substituir) + - `maxAgeHours`: padrão de idade máxima rígida em horas (`0` desabilita; provedores podem substituir) @@ -1902,7 +1902,7 @@ Consulte [Sandbox e Ferramentas para Vários Agentes](/pt-BR/tools/multi-agent-s ```json5 { messages: { - responsePrefix: "🦞", // ou "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1917,7 +1917,7 @@ Consulte [Sandbox e Ferramentas para Vários Agentes](/pt-BR/tools/multi-agent-s }, }, inbound: { - debounceMs: 2000, // 0 desativa + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1931,34 +1931,34 @@ Consulte [Sandbox e Ferramentas para Vários Agentes](/pt-BR/tools/multi-agent-s Substituições por canal/conta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Resolução (o mais específico prevalece): conta → canal → global. `""` desativa e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. +Resolução (o mais específico vence): conta → canal → global. `""` desabilita e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. **Variáveis de template:** -| Variável | Descrição | Exemplo | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | Nome curto do modelo | `claude-opus-4-6` | +| Variável | Descrição | Exemplo | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Nome curto do modelo | `claude-opus-4-6` | | `{modelFull}` | Identificador completo do modelo | `anthropic/claude-opus-4-6` | -| `{provider}` | Nome do provedor | `anthropic` | +| `{provider}` | Nome do provedor | `anthropic` | | `{thinkingLevel}` | Nível atual de thinking | `high`, `low`, `off` | -| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) | +| `{identity.name}` | Nome de identidade do agente | (igual a `"auto"`) | As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias para `{thinkingLevel}`. ### Reação de confirmação -- O padrão é `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desativar. +- Usa por padrão `identity.emoji` do agente ativo, caso contrário `"👀"`. Defina `""` para desabilitar. - Substituições por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. - Ordem de resolução: conta → canal → `messages.ackReaction` → fallback de identidade. - Escopo: `group-mentions` (padrão), `group-all`, `direct`, `all`. - `removeAckAfterReply`: remove a confirmação após a resposta no Slack, Discord e Telegram. -- `messages.statusReactions.enabled`: habilita reações de status do ciclo de vida no Slack, Discord e Telegram. - No Slack e no Discord, deixar sem definir mantém as reações de status habilitadas quando as reações de confirmação estão ativas. - No Telegram, defina explicitamente como `true` para habilitar reações de status do ciclo de vida. +- `messages.statusReactions.enabled`: habilita reações de status de ciclo de vida no Slack, Discord e Telegram. + No Slack e no Discord, se não definido, mantém reações de status habilitadas quando reações de confirmação estão ativas. + No Telegram, defina explicitamente como `true` para habilitar reações de status de ciclo de vida. ### Debounce de entrada -Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno do agente. Mídia/anexos descarregam imediatamente. Comandos de controle ignoram o debounce. +Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno de agente. Mídia/anexos fazem flush imediatamente. Comandos de controle ignoram o debounce. ### TTS (texto para fala) @@ -2001,12 +2001,12 @@ Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno do } ``` -- `auto` controla o modo padrão de TTS automático: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo. +- `auto` controla o modo padrão de auto-TTS: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo. - `summaryModel` substitui `agents.defaults.model.primary` para resumo automático. -- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` por padrão (opt-in). +- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` por padrão (ativação explícita). - As chaves de API usam `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY` como fallback. - `openai.baseUrl` substitui o endpoint TTS da OpenAI. A ordem de resolução é configuração, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. -- Quando `openai.baseUrl` aponta para um endpoint que não seja da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e flexibiliza a validação de modelo/voz. +- Quando `openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e flexibiliza a validação de modelo/voz. --- @@ -2036,36 +2036,36 @@ Padrões para o modo Talk (macOS/iOS/Android). } ``` -- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Talk estiverem configurados. -- Chaves legadas simples de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) são apenas de compatibilidade e são migradas automaticamente para `talk.providers.`. +- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores Talk estiverem configurados. +- Chaves Talk planas legadas (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) são apenas para compatibilidade e são migradas automaticamente para `talk.providers.`. - IDs de voz usam `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID` como fallback. - `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef. -- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Talk está configurada. +- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API Talk está configurada. - `providers.*.voiceAliases` permite que diretivas de Talk usem nomes amigáveis. -- `silenceTimeoutMs` controla quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Se não definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). +- `silenceTimeoutMs` controla quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Quando não definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). --- ## Ferramentas -### Perfis de ferramenta +### Perfis de ferramentas -`tools.profile` define uma lista básica de permissões antes de `tools.allow`/`tools.deny`: +`tools.profile` define uma allowlist base antes de `tools.allow`/`tools.deny`: -No onboarding local, novas configurações locais passam a usar por padrão `tools.profile: "coding"` quando não definido (perfis explícitos existentes são preservados). +O onboarding local define novas configurações locais como `tools.profile: "coding"` por padrão quando não definido (perfis explícitos existentes são preservados). -| Perfil | Inclui | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | apenas `session_status` | +| Perfil | Inclui | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | somente `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Sem restrição (igual a não definido) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Sem restrição (igual a não definido) | ### Grupos de ferramentas | Grupo | Ferramentas | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias para `exec`) | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias de `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | @@ -2076,11 +2076,11 @@ No onboarding local, novas configurações locais passam a usar por padrão `too | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas as ferramentas integradas (exclui plugins de provedor) | +| `group:openclaw` | Todas as ferramentas embutidas (exclui plugins de provedor) | ### `tools.allow` / `tools.deny` -Política global de permitir/negar ferramentas (negação prevalece). Não diferencia maiúsculas de minúsculas e oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. +Política global de permitir/negar ferramentas (negação tem prioridade). Não diferencia maiúsculas de minúsculas e oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. ```json5 { @@ -2090,7 +2090,7 @@ Política global de permitir/negar ferramentas (negação prevalece). Não difer ### `tools.byProvider` -Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permitir/negar. +Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → allow/deny. ```json5 { @@ -2106,7 +2106,7 @@ Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: ### `tools.elevated` -Controla acesso elevado de `exec` fora do sandbox: +Controla acesso elevado a `exec` fora do sandbox: ```json5 { @@ -2148,7 +2148,7 @@ Controla acesso elevado de `exec` fora do sandbox: ### `tools.loopDetection` -As verificações de segurança de loop de ferramenta ficam **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. +As verificações de segurança contra loops de ferramenta ficam **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`. ```json5 @@ -2170,12 +2170,12 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e su } ``` -- `historySize`: máximo de histórico de chamadas de ferramenta retido para análise de loop. +- `historySize`: máximo de histórico de chamadas de ferramenta mantido para análise de loop. - `warningThreshold`: limite de padrão repetido sem progresso para avisos. - `criticalThreshold`: limite repetido mais alto para bloquear loops críticos. -- `globalCircuitBreakerThreshold`: limite de interrupção total para qualquer execução sem progresso. +- `globalCircuitBreakerThreshold`: limite rígido de parada para qualquer execução sem progresso. - `detectors.genericRepeat`: avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos. -- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas de polling conhecidas (`process.poll`, `command_status` etc.). +- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas de poll conhecidas sem progresso (`process.poll`, `command_status` etc.). - `detectors.pingPong`: avisa/bloqueia padrões alternados em pares sem progresso. - Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, a validação falha. @@ -2187,14 +2187,14 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e su web: { search: { enabled: true, - apiKey: "brave_api_key", // ou env BRAVE_API_KEY + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // opcional; omita para detecção automática + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2211,7 +2211,7 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e su ### `tools.media` -Configura a compreensão de mídia recebida (imagem/áudio/vídeo): +Configura o entendimento de mídia recebida (imagem/áudio/vídeo): ```json5 { @@ -2219,7 +2219,7 @@ Configura a compreensão de mídia recebida (imagem/áudio/vídeo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: envia música/vídeo assíncronos concluídos diretamente para o canal + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2243,32 +2243,32 @@ Configura a compreensão de mídia recebida (imagem/áudio/vídeo): } ``` - + **Entrada de provedor** (`type: "provider"` ou omitido): -- `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq` etc.) -- `model`: substituição do ID do modelo -- `profile` / `preferredProfile`: seleção de perfil de `auth-profiles.json` +- `provider`: id do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq` etc.) +- `model`: substituição do id do modelo +- `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json` **Entrada de CLI** (`type: "cli"`): - `command`: executável a ser executado -- `args`: argumentos com template (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) +- `args`: argumentos com template (suporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) **Campos comuns:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Padrões: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: substituições por entrada. -- Falhas recorrem à próxima entrada. +- Falhas passam para a próxima entrada. A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → variáveis de ambiente → `models.providers.*.apiKey`. **Campos de conclusão assíncrona:** -- `asyncCompletion.directSend`: quando `true`, tarefas concluídas de `music_generate` - e `video_generate` tentam primeiro entrega direta ao canal. Padrão: `false` - (caminho legado de ativação da sessão solicitante/entrega pelo modelo). +- `asyncCompletion.directSend`: quando `true`, tarefas assíncronas concluídas de `music_generate` + e `video_generate` tentam primeiro a entrega direta ao canal. Padrão: `false` + (caminho legado de ativação de sessão solicitante/entrega por modelo). @@ -2289,7 +2289,7 @@ A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → var Controla quais sessões podem ser direcionadas pelas ferramentas de sessão (`sessions_list`, `sessions_history`, `sessions_send`). -Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes). +Padrão: `tree` (sessão atual + sessões criadas por ela, como subagentes). ```json5 { @@ -2304,11 +2304,11 @@ Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes). Observações: -- `self`: apenas a chave da sessão atual. -- `tree`: sessão atual + sessões geradas pela sessão atual (subagentes). -- `agent`: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo ID de agente). +- `self`: somente a chave da sessão atual. +- `tree`: sessão atual + sessões criadas pela sessão atual (subagentes). +- `agent`: qualquer sessão pertencente ao id do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo id de agente). - `all`: qualquer sessão. O direcionamento entre agentes ainda exige `tools.agentToAgent`. -- Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree`, mesmo que `tools.sessions.visibility="all"`. +- Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo se `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2319,11 +2319,11 @@ Controla o suporte a anexos inline para `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: defina true para permitir anexos de arquivo inline - maxTotalBytes: 5242880, // 5 MB no total entre todos os arquivos + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, - maxFileBytes: 1048576, // 1 MB por arquivo - retainOnSessionKeep: false, // mantém anexos quando cleanup="keep" + maxFileBytes: 1048576, // 1 MB per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2332,22 +2332,22 @@ Controla o suporte a anexos inline para `sessions_spawn`. Observações: -- Anexos são compatíveis apenas com `runtime: "subagent"`. O runtime ACP os rejeita. +- Anexos são suportados apenas para `runtime: "subagent"`. O runtime ACP os rejeita. - Os arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. -- O conteúdo do anexo é automaticamente redigido na persistência da transcrição. -- Entradas em Base64 são validadas com verificações rígidas de alfabeto/preenchimento e proteção de tamanho antes da decodificação. -- Permissões de arquivo são `0700` para diretórios e `0600` para arquivos. +- O conteúdo dos anexos é automaticamente redigido da persistência da transcrição. +- Entradas em Base64 são validadas com verificações estritas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação. +- As permissões de arquivo são `0700` para diretórios e `0600` para arquivos. - A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os mantém apenas quando `retainOnSessionKeep: true`. ### `tools.experimental` -Sinalizadores experimentais de ferramentas integradas. Padrão desativado, a menos que se aplique uma regra de autoativação estritamente agentiva para GPT-5. +Flags experimentais de ferramentas embutidas. Desativadas por padrão, a menos que uma regra de ativação automática estrita para GPT-5 agentic se aplique. ```json5 { tools: { experimental: { - planTool: true, // habilita update_plan experimental + planTool: true, // enable experimental update_plan }, }, } @@ -2355,9 +2355,9 @@ Sinalizadores experimentais de ferramentas integradas. Padrão desativado, a men Observações: -- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhamento de trabalho não trivial em várias etapas. -- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções GPT-5 estritamente agentivas. -- Quando habilitada, o prompt do sistema também adiciona orientação de uso para que o modelo a use apenas em trabalho substancial e mantenha no máximo uma etapa `in_progress`. +- `planTool`: habilita a ferramenta estruturada experimental `update_plan` para rastreamento de trabalho não trivial em várias etapas. +- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções estritas com GPT-5 agentic. +- Quando habilitada, o prompt do sistema também adiciona orientações de uso para que o modelo a utilize apenas em trabalhos substanciais e mantenha no máximo uma etapa `in_progress`. ### `agents.defaults.subagents` @@ -2377,8 +2377,8 @@ Observações: } ``` -- `model`: modelo padrão para subagentes gerados. Se omitido, os subagentes herdam o modelo do chamador. -- `allowAgents`: lista de permissões padrão de IDs de agente de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer; padrão: somente o mesmo agente). +- `model`: modelo padrão para subagentes criados. Se omitido, os subagentes herdam o modelo do chamador. +- `allowAgents`: allowlist padrão de ids de agente de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: somente o mesmo agente). - `runTimeoutSeconds`: timeout padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem timeout. - Política de ferramentas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. @@ -2386,12 +2386,12 @@ Observações: ## Provedores personalizados e URLs base -O OpenClaw usa o catálogo integrado de modelos. Adicione provedores personalizados via `models.providers` na configuração ou `~/.openclaw/agents//agent/models.json`. +O OpenClaw usa o catálogo embutido de modelos. Adicione provedores personalizados via `models.providers` na configuração ou `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (padrão) | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2415,50 +2415,50 @@ O OpenClaw usa o catálogo integrado de modelos. Adicione provedores personaliza } ``` -- Use `authHeader: true` + `headers` para necessidades de autenticação personalizadas. +- Use `authHeader: true` + `headers` para necessidades de autenticação personalizada. - Substitua a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente). -- Precedência de mesclagem para IDs de provedor correspondentes: - - Valores não vazios de `baseUrl` em `models.json` do agente prevalecem. - - Valores não vazios de `apiKey` do agente prevalecem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de config/perfil de autenticação. - - Valores de `apiKey` de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos. - - Valores de cabeçalho de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec). - - `apiKey`/`baseUrl` do agente vazios ou ausentes recorrem a `models.providers` na configuração. - - `contextWindow`/`maxTokens` do modelo correspondente usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo. - - `contextTokens` do modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo. +- Precedência de mesclagem para ids de provedor correspondentes: + - Valores `baseUrl` não vazios em `models.json` do agente têm prioridade. + - Valores `apiKey` não vazios do agente têm prioridade apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação. + - Valores `apiKey` de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec) em vez de persistirem segredos resolvidos. + - Valores de cabeçalho de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec). + - `apiKey`/`baseUrl` do agente vazios ou ausentes usam `models.providers` da configuração como fallback. + - `contextWindow`/`maxTokens` de modelos correspondentes usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo. + - `contextTokens` de modelos correspondentes preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo. - Use `models.mode: "replace"` quando quiser que a configuração reescreva completamente `models.json`. - - A persistência de marcadores é autoritativa pela origem: os marcadores são gravados a partir do snapshot ativo da configuração de origem (pré-resolução), não a partir de valores secretos resolvidos em runtime. + - A persistência de marcadores segue a fonte autoritativa: os marcadores são gravados a partir do snapshot ativo de configuração de origem (pré-resolução), não a partir de valores secretos resolvidos em runtime. ### Detalhes dos campos do provedor - `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`). -- `models.providers`: mapa de provedores personalizados indexado por ID do provedor. -- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). -- `models.providers.*.apiKey`: credencial do provedor (prefira substituição por SecretRef/ambiente). +- `models.providers`: mapa de provedores personalizados com chave por id do provedor. +- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc). +- `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição por env). - `models.providers.*.auth`: estratégia de autenticação (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas requisições (padrão: `true`). - `models.providers.*.authHeader`: força o transporte da credencial no cabeçalho `Authorization` quando necessário. - `models.providers.*.baseUrl`: URL base da API upstream. -- `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento de proxy/tenant. -- `models.providers.*.request`: substituições de transporte para requisições HTTP do provedor de modelo. +- `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento por proxy/tenant. +- `models.providers.*.request`: substituições de transporte para requisições HTTP do provedor de modelos. - `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Os valores aceitam SecretRef. - - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). - - `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto opcional `tls`. + - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação embutida do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value` e `prefix` opcional). + - `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional. - `request.tls`: substituição de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para intervalos privados, CGNAT ou semelhantes, via a proteção SSRF de fetch HTTP do provedor (opt-in do operador para endpoints OpenAI-compatíveis confiáveis e auto-hospedados). O WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa barreira SSRF do fetch. Padrão `false`. + - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para faixas privadas, CGNAT ou semelhantes, por meio da proteção SSRF de fetch HTTP do provedor (opt-in do operador para endpoints compatíveis com OpenAI autohospedados e confiáveis). O WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa proteção SSRF do fetch. Padrão `false`. - `models.providers.*.models`: entradas explícitas do catálogo de modelos do provedor. -- `models.providers.*.models.*.contextWindow`: metadados da janela nativa de contexto do modelo. -- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isso quando quiser um orçamento efetivo de contexto menor que o `contextWindow` nativo do modelo. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não nativa e não vazia (host diferente de `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat OpenAI-compatíveis que aceitam apenas string. Quando `true`, o OpenClaw achata arrays `messages[].content` puramente textuais em strings simples antes de enviar a requisição. +- `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. +- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isso quando quiser um orçamento efetivo de contexto menor que `contextWindow` nativo do modelo. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não vazio e não nativo (host diferente de `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas strings. Quando `true`, o OpenClaw converte arrays puramente textuais em `messages[].content` para strings simples antes de enviar a requisição. - `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de descoberta automática do Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa a descoberta implícita. -- `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para descoberta. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de ID de provedor para descoberta direcionada. +- `plugins.entries.amazon-bedrock.config.discovery.region`: região da AWS para descoberta. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de id do provedor para descoberta direcionada. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização da descoberta. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto de fallback para modelos descobertos. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída de fallback para modelos descobertos. -### Exemplos de provedores +### Exemplos de provedor @@ -2531,8 +2531,8 @@ Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use referências `opencod Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `openclaw onboard --auth-choice zai-api-key`. - Endpoint geral: `https://api.z.ai/api/paas/v4` -- Endpoint de código (padrão): `https://api.z.ai/api/coding/paas/v4` -- Para o endpoint geral, defina um provedor personalizado com a substituição de URL base. +- Endpoint de coding (padrão): `https://api.z.ai/api/coding/paas/v4` +- Para o endpoint geral, defina um provedor personalizado com substituição de URL base. @@ -2573,9 +2573,9 @@ Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `opencla Para o endpoint da China: `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`. -Endpoints nativos do Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado -`openai-completions`, e o OpenClaw se baseia nessas capacidades do endpoint -em vez de apenas no ID integrado do provedor. +Os endpoints nativos do Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado +`openai-completions`, e o OpenClaw baseia isso nas capacidades do endpoint +em vez de apenas no id do provedor embutido. @@ -2593,7 +2593,7 @@ em vez de apenas no ID integrado do provedor. } ``` -Compatível com Anthropic, provedor integrado. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. +Compatível com Anthropic, provedor embutido. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2675,9 +2675,9 @@ A URL base deve omitir `/v1` (o cliente Anthropic a acrescenta). Atalho: `opencl Defina `MINIMAX_API_KEY`. Atalhos: `openclaw onboard --auth-choice minimax-global-api` ou `openclaw onboard --auth-choice minimax-cn-api`. -O catálogo de modelos usa por padrão apenas M2.7. -No caminho de streaming compatível com Anthropic, o OpenClaw desativa o thinking do MiniMax -por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou +O catálogo de modelos usa somente M2.7 por padrão. +No caminho de streaming compatível com Anthropic, o OpenClaw desabilita o thinking do MiniMax +por padrão, a menos que você defina explicitamente `thinking`. `/fast on` ou `params.fastMode: true` reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`. @@ -2685,7 +2685,7 @@ por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou -Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um modelo local grande via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. +Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um grande modelo local via LM Studio Responses API em hardware robusto; mantenha modelos hospedados mesclados para fallback. @@ -2706,7 +2706,7 @@ Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um model }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // ou string em texto simples + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2716,13 +2716,13 @@ Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um model } ``` -- `allowBundled`: lista opcional de permissões apenas para Skills empacotadas (Skills gerenciadas/do workspace não são afetadas). -- `load.extraDirs`: raízes extras de Skills compartilhadas (menor precedência). -- `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está +- `allowBundled`: allowlist opcional apenas para Skills em bundle (Skills gerenciadas/do workspace não são afetadas). +- `load.extraDirs`: raízes extras compartilhadas de Skills (menor precedência). +- `install.preferBrew`: quando true, prefere instaladores do Homebrew quando `brew` está disponível antes de recorrer a outros tipos de instalador. - `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desativa uma Skill mesmo que esteja empacotada/instalada. +- `entries..enabled: false` desabilita uma Skill mesmo se ela estiver em bundle/instalada. - `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente principal (string em texto simples ou objeto SecretRef). --- @@ -2751,38 +2751,38 @@ Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um model } ``` -- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions`, mais `plugins.load.paths`. -- A descoberta aceita plugins nativos do OpenClaw, além de bundles compatíveis do Codex e bundles do Claude, incluindo bundles do Claude sem manifesto no layout padrão. -- **Alterações de configuração exigem reinicialização do gateway.** -- `allow`: lista opcional de permissões (somente os plugins listados são carregados). `deny` prevalece. -- `plugins.entries..apiKey`: campo de conveniência para chave de API no nível do plugin (quando compatível com o plugin). +- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. +- A descoberta aceita plugins nativos do OpenClaw, além de bundles compatíveis de Codex e bundles de Claude, incluindo bundles Claude sem manifesto no layout padrão. +- **Mudanças de configuração exigem reinicialização do gateway.** +- `allow`: allowlist opcional (somente plugins listados são carregados). `deny` tem prioridade. +- `plugins.entries..apiKey`: campo de conveniência para chave de API no nível do plugin (quando suportado pelo plugin). - `plugins.entries..env`: mapa de variáveis de ambiente com escopo do plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram prompt do legado `before_agent_start`, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks nativos de plugins e a diretórios de hooks fornecidos por bundles compatíveis. -- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar substituições por execução de `provider` e `model` para execuções de subagentes em segundo plano. -- `plugins.entries..subagent.allowedModels`: lista opcional de permissões de destinos canônicos `provider/model` para substituições confiáveis de subagentes. Use `"*"` apenas quando você quiser intencionalmente permitir qualquer modelo. -- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo schema nativo do plugin OpenClaw quando disponível). -- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de web-fetch do Firecrawl. - - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa `plugins.entries.firecrawl.config.webSearch.apiKey`, o legado `tools.web.fetch.firecrawl.apiKey` ou a variável de ambiente `FIRECRAWL_API_KEY` como fallback. - - `baseUrl`: URL base da API Firecrawl (padrão: `https://api.firecrawl.dev`). +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram o prompt de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de plugins nativos e a diretórios de hooks fornecidos por bundles suportados. +- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar substituições de `provider` e `model` por execução para execuções de subagente em segundo plano. +- `plugins.entries..subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` apenas quando você quiser intencionalmente permitir qualquer modelo. +- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo schema de plugin nativo do OpenClaw quando disponível). +- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de web fetch Firecrawl. + - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` legado ou a variável de ambiente `FIRECRAWL_API_KEY` como fallback. + - `baseUrl`: URL base da API do Firecrawl (padrão: `https://api.firecrawl.dev`). - `onlyMainContent`: extrai apenas o conteúdo principal das páginas (padrão: `true`). - - `maxAgeMs`: idade máxima do cache em milissegundos (padrão: `172800000` / 2 dias). + - `maxAgeMs`: idade máxima de cache em milissegundos (padrão: `172800000` / 2 dias). - `timeoutSeconds`: tempo limite da requisição de scraping em segundos (padrão: `60`). -- `plugins.entries.xai.config.xSearch`: configurações do X Search do xAI (busca na web do Grok). +- `plugins.entries.xai.config.xSearch`: configurações do X Search da xAI (busca na web do Grok). - `enabled`: habilita o provedor X Search. - - `model`: modelo Grok a usar para busca (por exemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming da memória (experimental). Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. + - `model`: modelo Grok a ser usado para busca (por exemplo `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming de memória (experimental). Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. - `enabled`: chave mestra de dreaming (padrão `false`). - - `frequency`: cadência cron para cada varredura completa de dreaming (por padrão `"0 3 * * *"`). - - política de fase e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). -- A configuração completa de memória fica em [Referência de configuração de memória](/pt-BR/reference/memory-config): + - `frequency`: cadência de cron para cada varredura completa de dreaming (padrão `"0 3 * * *"`). + - política de fases e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). +- A configuração completa de memória está em [Memory configuration reference](/pt-BR/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Plugins de bundle Claude habilitados também podem contribuir com padrões embutidos do Pi a partir de `settings.json`; o OpenClaw os aplica como configurações sanitizadas do agente, não como patches brutos de configuração do OpenClaw. -- `plugins.slots.memory`: escolhe o ID do plugin de memória ativo, ou `"none"` para desativar plugins de memória. -- `plugins.slots.contextEngine`: escolhe o ID do plugin ativo do mecanismo de contexto; o padrão é `"legacy"`, a menos que você instale e selecione outro mecanismo. +- Plugins de bundle Claude habilitados também podem contribuir com padrões embutidos de Pi a partir de `settings.json`; o OpenClaw os aplica como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. +- `plugins.slots.memory`: escolhe o id do plugin de memória ativo, ou `"none"` para desabilitar plugins de memória. +- `plugins.slots.contextEngine`: escolhe o id do plugin de mecanismo de contexto ativo; o padrão é `"legacy"` a menos que você instale e selecione outro mecanismo. - `plugins.installs`: metadados de instalação gerenciados pela CLI usados por `openclaw plugins update`. - Inclui `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - Trate `plugins.installs.*` como estado gerenciado; prefira comandos da CLI a edições manuais. @@ -2800,8 +2800,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // faça opt-in apenas para acesso confiável a rede privada - // allowPrivateNetwork: true, // alias legado + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2827,30 +2827,29 @@ Consulte [Plugins](/pt-BR/tools/plugin). } ``` -- `evaluateEnabled: false` desativa `act:evaluate` e `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado quando não definido, portanto a navegação do navegador permanece estrita por padrão. -- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando confiar intencionalmente na navegação do navegador em rede privada. -- No modo estrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta. -- `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado. +- `evaluateEnabled: false` desabilita `act:evaluate` e `wait --fn`. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desabilitado quando não definido, então a navegação do navegador permanece estrita por padrão. +- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando você confiar intencionalmente na navegação de navegador em rede privada. +- No modo estrito, endpoints remotos de perfil CDP (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de acessibilidade/descoberta. +- `ssrfPolicy.allowPrivateNetwork` continua sendo aceito como alias legado. - No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. -- Perfis remotos são somente anexação (start/stop/reset desativados). +- Perfis remotos são somente anexação (start/stop/reset desabilitados). - `profiles.*.cdpUrl` aceita `http://`, `https://`, `ws://` e `wss://`. Use HTTP(S) quando quiser que o OpenClaw descubra `/json/version`; use WS(S) - quando seu provedor fornecer uma URL direta de WebSocket do DevTools. -- Perfis `existing-session` são apenas do host e usam Chrome MCP em vez de CDP. -- Perfis `existing-session` podem definir `userDataDir` para direcionar um perfil - específico de navegador baseado em Chromium, como Brave ou Edge. -- Perfis `existing-session` mantêm os limites atuais de rota do Chrome MCP: - ações guiadas por snapshot/ref em vez de direcionamento por seletor CSS, hooks - de upload de um único arquivo, sem substituições de timeout de diálogo, sem - `wait --load networkidle`, sem `responsebody`, exportação de PDF, interceptação - de download ou ações em lote. + quando seu provedor fornecer uma URL direta de WebSocket DevTools. +- Perfis `existing-session` são somente host e usam Chrome MCP em vez de CDP. +- Perfis `existing-session` podem definir `userDataDir` para direcionar um perfil específico + de navegador baseado em Chromium, como Brave ou Edge. +- Perfis `existing-session` mantêm os limites atuais da rota Chrome MCP: + ações baseadas em snapshot/ref em vez de direcionamento por seletor CSS, hooks de upload + de arquivo único, sem substituições de timeout de diálogo, sem `wait --load networkidle`, + e sem `responsebody`, exportação de PDF, interceptação de download ou ações em lote. - Perfis locais gerenciados `openclaw` atribuem automaticamente `cdpPort` e `cdpUrl`; só defina `cdpUrl` explicitamente para CDP remoto. - Ordem de autodetecção: navegador padrão se for baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Serviço de controle: somente loopback (porta derivada de `gateway.port`, padrão `18791`). -- `extraArgs` acrescenta flags extras de inicialização ao startup local do Chromium (por exemplo - `--disable-gpu`, dimensionamento de janela ou flags de depuração). +- `extraArgs` acrescenta flags extras de inicialização à inicialização local do Chromium (por exemplo + `--disable-gpu`, tamanho da janela ou flags de depuração). --- @@ -2862,13 +2861,13 @@ Consulte [Plugins](/pt-BR/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, texto curto, URL de imagem ou data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` -- `seamColor`: cor de destaque para o chrome da UI do app nativo (matiz da bolha do modo Talk etc.). +- `seamColor`: cor de destaque para o chrome da UI nativa do app (tonalidade da bolha do Talk Mode etc.). - `assistant`: substituição de identidade da Control UI. Usa a identidade do agente ativo como fallback. --- @@ -2884,8 +2883,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // ou OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // para mode=trusted-proxy; consulte /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2902,8 +2901,10 @@ Consulte [Plugins](/pt-BR/tools/plugin). enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // obrigatório para Control UI fora de loopback - // dangerouslyAllowHostHeaderOriginFallback: false, // modo perigoso de fallback de origem por cabeçalho Host + // embedSandbox: "scripts", // strict | scripts | trusted + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2914,12 +2915,12 @@ Consulte [Plugins](/pt-BR/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Opcional. Padrão false. + // Optional. Default false. allowRealIpFallback: false, tools: { - // Negações HTTP adicionais para /tools/invoke + // Additional /tools/invoke HTTP denies deny: ["browser"], - // Remove ferramentas da lista padrão de negação HTTP + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -2936,64 +2937,64 @@ Consulte [Plugins](/pt-BR/tools/plugin). -- `mode`: `local` (executa o gateway) ou `remote` (conecta a um gateway remoto). O gateway se recusa a iniciar, a menos que esteja em `local`. +- `mode`: `local` (executar gateway) ou `remote` (conectar a um gateway remoto). O gateway se recusa a iniciar, a menos que esteja em `local`. - `port`: porta multiplexada única para WS + HTTP. Precedência: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (somente IP do Tailscale) ou `custom`. - **Aliases legados de bind**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o gateway fica inacessível. Use `--network host` ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. -- **Auth**: exigida por padrão. Binds fora de loopback exigem autenticação do gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade com `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. -- Se `gateway.auth.token` e `gateway.auth.password` estiverem ambos configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. A inicialização e fluxos de instalação/reparo de serviço falham quando ambos estão configurados e o modo não está definido. -- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações confiáveis de local loopback; isso intencionalmente não é oferecido nos prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega autenticação a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade vindos de `gateway.trustedProxies` (consulte [Autenticação com proxy confiável](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **fora de loopback**; proxies reversos em loopback no mesmo host não satisfazem a autenticação trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; eles seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token presume que o host do gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional de falhas de autenticação. Aplica-se por IP do cliente e por escopo de autenticação (segredo compartilhado e token de dispositivo são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. - - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes do registro da falha. Portanto, tentativas inválidas concorrentes do mesmo cliente podem acionar o limitador na segunda requisição, em vez de ambas passarem em paralelo como simples incompatibilidades. - - `gateway.auth.rateLimit.exemptLoopback` usa `true` por padrão; defina `false` quando quiser intencionalmente que o tráfego localhost também tenha limitação de taxa (para ambientes de teste ou implantações rigorosas com proxy). -- Tentativas de autenticação WS com origem de navegador sempre são limitadas com a isenção de loopback desativada (defesa em profundidade contra força bruta de localhost via navegador). -- Em loopback, esses bloqueios por origem de navegador são isolados por valor +- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o gateway fica inacessível. Use `--network host`, ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. +- **Auth**: exigida por padrão. Binds não-loopback exigem auth do gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade com `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. +- Se `gateway.auth.token` e `gateway.auth.password` estiverem ambos configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Os fluxos de inicialização e de instalação/reparo do serviço falham quando ambos estão configurados e o modo não está definido. +- `gateway.auth.mode: "none"`: modo explícito sem auth. Use apenas para configurações confiáveis de local loopback; isso intencionalmente não é oferecido pelos prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega auth a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade vindos de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **não-loopback**; proxies reversos loopback no mesmo host não atendem à auth por trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a auth da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa auth por cabeçalho do Tailscale; eles seguem o modo normal de auth HTTP do gateway. Esse fluxo sem token pressupõe que o host do gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional para falhas de auth. Aplica-se por IP do cliente e por escopo de auth (segredo compartilhado e token de dispositivo são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. + - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Portanto, tentativas ruins concorrentes do mesmo cliente podem acionar o limitador na segunda requisição em vez de ambas passarem por disputa como simples incompatibilidades. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` por padrão; defina `false` quando quiser intencionalmente limitar também o tráfego localhost (para configurações de teste ou implantações com proxy estrito). +- Tentativas de auth WS com origem em navegador são sempre limitadas com a isenção de loopback desativada (defesa em profundidade contra força bruta localhost baseada em navegador). +- Em loopback, esses bloqueios com origem em navegador são isolados por valor `Origin` normalizado, então falhas repetidas de uma origem localhost não - bloqueiam automaticamente outra origem. -- `tailscale.mode`: `serve` (somente tailnet, bind em loopback) ou `funnel` (público, exige autenticação). -- `controlUi.allowedOrigins`: lista explícita de permissões de origem do navegador para conexões WebSocket do Gateway. Obrigatória quando clientes de navegador forem esperados de origens fora de loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente da política de origem por cabeçalho Host. + bloqueiam automaticamente uma origem diferente. +- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, requer auth). +- `controlUi.allowedOrigins`: allowlist explícita de origem de navegador para conexões WebSocket do Gateway. Obrigatória quando clientes de navegador são esperados a partir de origens não-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem pelo cabeçalho Host para implantações que intencionalmente dependem de política de origem por Host header. - `remote.transport`: `ssh` (padrão) ou `direct` (ws/wss). Para `direct`, `remote.url` deve ser `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição break-glass no lado do cliente que permite `ws://` em texto claro para IPs confiáveis de rede privada; por padrão, texto claro continua limitado a loopback. -- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram a autenticação do gateway por si só. -- `gateway.push.apns.relay.baseUrl`: URL base HTTPS do relay APNs externo usado por builds oficiais/TestFlight do iOS depois que publicam registros com suporte de relay para o gateway. Essa URL deve corresponder à URL do relay compilada na build do iOS. -- `gateway.push.apns.relay.timeoutMs`: tempo limite de envio do gateway para o relay em milissegundos. O padrão é `10000`. -- Registros com suporte de relay são delegados a uma identidade específica do gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha uma concessão de envio com escopo de registro ao gateway. Outro gateway não pode reutilizar esse registro armazenado. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias por ambiente para a configuração de relay acima. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch somente para desenvolvimento para URLs HTTP de relay em loopback. URLs de relay em produção devem permanecer em HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo em minutos do monitor de saúde do canal. Defina `0` para desativar reinicializações do monitor de saúde globalmente. Padrão: `5`. -- `gateway.channelStaleEventThresholdMinutes`: limite em minutos para socket obsoleto. Mantenha isso maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição break-glass no lado do cliente que permite `ws://` em texto simples para IPs confiáveis de rede privada; o padrão continua sendo somente loopback para texto simples. +- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram a auth do gateway por si só. +- `gateway.push.apns.relay.baseUrl`: URL base HTTPS para o relay APNs externo usado por builds oficiais/TestFlight do iOS depois que elas publicam registros com suporte por relay no gateway. Essa URL deve corresponder à URL do relay compilada no build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout de envio do gateway para o relay em milissegundos. Padrão: `10000`. +- Registros com suporte por relay são delegados a uma identidade específica de gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha uma permissão de envio com escopo de registro para o gateway. Outro gateway não pode reutilizar esse registro armazenado. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias por env para a configuração de relay acima. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch apenas para desenvolvimento para URLs HTTP loopback do relay. URLs de relay em produção devem permanecer em HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo do monitor de saúde de canais em minutos. Defina `0` para desabilitar globalmente reinicializações do monitor de saúde. Padrão: `5`. +- `gateway.channelStaleEventThresholdMinutes`: limite de socket obsoleto em minutos. Mantenha este valor maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. - `gateway.channelMaxRestartsPerHour`: máximo de reinicializações do monitor de saúde por canal/conta em uma hora móvel. Padrão: `10`. - `channels..healthMonitor.enabled`: opt-out por canal para reinicializações do monitor de saúde, mantendo o monitor global habilitado. -- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definido, tem precedência sobre a substituição em nível de canal. -- Caminhos locais de chamada do gateway podem usar `gateway.remote.*` como fallback apenas quando `gateway.auth.*` não está definido. -- Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não resolvido, a resolução falha de forma fechada (sem fallback remoto mascarando). -- `trustedProxies`: IPs de proxy reverso que terminam TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies que você controla. Entradas de loopback continuam válidas para configurações de proxy no mesmo host/detecção local (por exemplo Tailscale Serve ou um proxy reverso local), mas **não** tornam requisições em loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: quando `true`, o gateway aceita `X-Real-IP` se `X-Forwarded-For` estiver ausente. Padrão `false` para comportamento de falha fechada. -- `gateway.tools.deny`: nomes extras de ferramentas bloqueadas para `POST /tools/invoke` HTTP (estende a lista padrão de negação). +- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definido, tem precedência sobre a substituição no nível do canal. +- Caminhos de chamada do gateway local podem usar `gateway.remote.*` como fallback apenas quando `gateway.auth.*` não está definido. +- Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não puder ser resolvido, a resolução falha de forma fechada (sem fallback remoto mascarando). +- `trustedProxies`: IPs de proxies reversos que encerram TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies que você controla. Entradas loopback ainda são válidas para configurações no mesmo host de proxy/detecção local (por exemplo Tailscale Serve ou um proxy reverso local), mas **não** tornam requisições loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: quando `true`, o gateway aceita `X-Real-IP` se `X-Forwarded-For` estiver ausente. Padrão `false` para comportamento fail-closed. +- `gateway.tools.deny`: nomes extras de ferramentas bloqueados para HTTP `POST /tools/invoke` (estende a lista padrão de negação). - `gateway.tools.allow`: remove nomes de ferramentas da lista padrão de negação HTTP. ### Endpoints compatíveis com OpenAI -- Chat Completions: desativado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. -- API Responses: `gateway.http.endpoints.responses.enabled`. -- Endurecimento de entrada por URL na Responses: +- Chat Completions: desabilitado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. +- Responses API: `gateway.http.endpoints.responses.enabled`. +- Hardening de entrada por URL em Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Listas de permissões vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false` - e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desativar busca por URL. -- Cabeçalho opcional de endurecimento de resposta: - - `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS que você controla; consulte [Autenticação com proxy confiável](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Allowlists vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false` + e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desabilitar a busca por URL. +- Cabeçalho opcional de hardening da resposta: + - `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS que você controla; consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento entre várias instâncias +### Isolamento de várias instâncias -Execute vários gateways em um mesmo host com portas e diretórios de estado exclusivos: +Execute vários gateways em um host com portas e diretórios de estado exclusivos: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3003,7 +3004,7 @@ openclaw gateway --port 19001 Flags de conveniência: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). -Consulte [Vários Gateways](/pt-BR/gateway/multiple-gateways). +Consulte [Multiple Gateways](/pt-BR/gateway/multiple-gateways). ### `gateway.tls` @@ -3022,10 +3023,10 @@ Consulte [Vários Gateways](/pt-BR/gateway/multiple-gateways). ``` - `enabled`: habilita terminação TLS no listener do gateway (HTTPS/WSS) (padrão: `false`). -- `autoGenerate`: gera automaticamente um par local de certificado/chave autoassinado quando arquivos explícitos não estão configurados; apenas para uso local/dev. +- `autoGenerate`: gera automaticamente um par local autoassinado de certificado/chave quando arquivos explícitos não estão configurados; apenas para uso local/dev. - `certPath`: caminho no sistema de arquivos para o arquivo de certificado TLS. - `keyPath`: caminho no sistema de arquivos para o arquivo de chave privada TLS; mantenha com permissões restritas. -- `caPath`: caminho opcional para bundle de CA para verificação de cliente ou cadeias de confiança personalizadas. +- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança personalizadas. ### `gateway.reload` @@ -3043,11 +3044,11 @@ Consulte [Vários Gateways](/pt-BR/gateway/multiple-gateways). - `mode`: controla como edições de configuração são aplicadas em runtime. - `"off"`: ignora edições ao vivo; alterações exigem reinicialização explícita. - - `"restart"`: sempre reinicia o processo do gateway em alteração de configuração. + - `"restart"`: sempre reinicia o processo do gateway ao mudar a configuração. - `"hot"`: aplica alterações no processo sem reiniciar. - - `"hybrid"` (padrão): tenta hot reload primeiro; recorre à reinicialização se necessário. + - `"hybrid"` (padrão): tenta hot reload primeiro; usa reinicialização como fallback quando necessário. - `debounceMs`: janela de debounce em ms antes de aplicar alterações de configuração (inteiro não negativo). -- `deferralTimeoutMs`: tempo máximo em ms para aguardar operações em andamento antes de forçar uma reinicialização (padrão: `300000` = 5 minutos). +- `deferralTimeoutMs`: tempo máximo em ms para esperar operações em andamento antes de forçar uma reinicialização (padrão: `300000` = 5 minutos). --- @@ -3087,10 +3088,10 @@ Consulte [Vários Gateways](/pt-BR/gateway/multiple-gateways). Auth: `Authorization: Bearer ` ou `x-openclaw-token: `. Tokens de hook em query string são rejeitados. -Observações de validação e segurança: +Notas de validação e segurança: -- `hooks.enabled=true` exige `hooks.token` não vazio. -- `hooks.token` deve ser **distinto** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado. +- `hooks.enabled=true` exige um `hooks.token` não vazio. +- `hooks.token` deve ser **diferente** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado. - `hooks.path` não pode ser `/`; use um subcaminho dedicado, como `/hooks`. - Se `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por exemplo `["hook:"]`). @@ -3098,21 +3099,21 @@ Observações de validação e segurança: - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` da carga útil da requisição é aceito apenas quando `hooks.allowRequestSessionKey=true` (padrão: `false`). + - `sessionKey` do payload da requisição é aceito apenas quando `hooks.allowRequestSessionKey=true` (padrão: `false`). - `POST /hooks/` → resolvido via `hooks.mappings` - + - `match.path` corresponde ao subcaminho após `/hooks` (por exemplo `/hooks/gmail` → `gmail`). -- `match.source` corresponde a um campo da carga útil para caminhos genéricos. -- Templates como `{{messages[0].subject}}` leem a partir da carga útil. +- `match.source` corresponde a um campo do payload para caminhos genéricos. +- Templates como `{{messages[0].subject}}` leem do payload. - `transform` pode apontar para um módulo JS/TS que retorna uma ação de hook. - - `transform.module` deve ser um caminho relativo e permanecer dentro de `hooks.transformsDir` (caminhos absolutos e travessia são rejeitados). -- `agentId` roteia para um agente específico; IDs desconhecidos recorrem ao padrão. -- `allowedAgentIds`: restringe o roteamento explícito (`*` ou omitido = permite todos, `[]` = nega todos). -- `defaultSessionKey`: chave de sessão fixa opcional para execuções de agente de hook sem `sessionKey` explícito. + - `transform.module` deve ser um caminho relativo e permanecer dentro de `hooks.transformsDir` (caminhos absolutos e travessia de diretório são rejeitados). +- `agentId` roteia para um agente específico; IDs desconhecidos usam o padrão como fallback. +- `allowedAgentIds`: restringe roteamento explícito (`*` ou omitido = permite todos, `[]` = nega todos). +- `defaultSessionKey`: chave de sessão fixa opcional para execuções de agente via hook sem `sessionKey` explícito. - `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` definam `sessionKey` (padrão: `false`). -- `allowedSessionKeyPrefixes`: lista opcional de permissões de prefixo para valores explícitos de `sessionKey` (requisição + mapeamento), por exemplo `["hook:"]`. +- `allowedSessionKeyPrefixes`: allowlist opcional de prefixos para valores explícitos de `sessionKey` (requisição + mapping), por exemplo `["hook:"]`. - `deliver: true` envia a resposta final para um canal; `channel` usa `last` como padrão. - `model` substitui o LLM para esta execução de hook (deve ser permitido se o catálogo de modelos estiver definido). @@ -3141,35 +3142,35 @@ Observações de validação e segurança: } ``` -- O gateway inicia automaticamente `gog gmail watch serve` na inicialização quando configurado. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desativar. +- O gateway inicia automaticamente `gog gmail watch serve` na inicialização quando configurado. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desabilitar. - Não execute um `gog gmail watch serve` separado junto com o Gateway. --- -## Host do Canvas +## Host do canvas ```json5 { canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // ou OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP sob a porta do Gateway: +- Serve HTML/CSS/JS editáveis por agente e A2UI por HTTP sob a porta do Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Somente local: mantenha `gateway.bind: "loopback"` (padrão). -- Binds fora de loopback: rotas do canvas exigem autenticação do Gateway (token/senha/trusted-proxy), igual às outras superfícies HTTP do Gateway. -- WebViews de node normalmente não enviam cabeçalhos de autenticação; depois que um node é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo do node para acesso a canvas/A2UI. -- URLs de capacidade são vinculadas à sessão WS ativa do node e expiram rapidamente. Fallback baseado em IP não é usado. +- Binds não-loopback: rotas de canvas exigem auth do Gateway (token/senha/trusted-proxy), assim como outras superfícies HTTP do Gateway. +- WebViews de Node normalmente não enviam cabeçalhos de auth; após um node ser pareado e conectado, o Gateway anuncia URLs de capability com escopo de node para acesso a canvas/A2UI. +- URLs de capability são vinculadas à sessão WS ativa do node e expiram rapidamente. Fallback por IP não é usado. - Injeta cliente de live reload no HTML servido. -- Cria automaticamente um `index.html` inicial quando vazio. +- Cria automaticamente um `index.html` inicial quando está vazio. - Também serve A2UI em `/__openclaw__/a2ui/`. - Alterações exigem reinicialização do gateway. -- Desative live reload para diretórios grandes ou erros `EMFILE`. +- Desabilite live reload para diretórios grandes ou erros `EMFILE`. --- @@ -3226,14 +3227,14 @@ Configuração: `openclaw dns setup --apply`. } ``` -- Variáveis de ambiente inline só são aplicadas se o ambiente do processo não tiver a chave. -- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum substitui variáveis existentes). +- Variáveis de ambiente inline são aplicadas apenas se o ambiente do processo não tiver a chave. +- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum deles substitui variáveis existentes). - `shellEnv`: importa chaves esperadas ausentes do perfil do seu shell de login. -- Consulte [Ambiente](/pt-BR/help/environment) para a precedência completa. +- Consulte [Environment](/pt-BR/help/environment) para a precedência completa. -### Substituição de variável de ambiente +### Substituição de variáveis de ambiente -Faça referência a variáveis de ambiente em qualquer string de configuração com `${VAR_NAME}`: +Referencie variáveis de ambiente em qualquer string de configuração com `${VAR_NAME}`: ```json5 { @@ -3243,20 +3244,20 @@ Faça referência a variáveis de ambiente em qualquer string de configuração } ``` -- Apenas nomes em maiúsculas são correspondidos: `[A-Z_][A-Z0-9_]*`. -- Variáveis ausentes/vazias geram erro no carregamento da configuração. -- Escape com `$${VAR}` para um `${VAR}` literal. +- Apenas nomes em maiúsculas correspondem: `[A-Z_][A-Z0-9_]*`. +- Variáveis ausentes/vazias geram erro ao carregar a configuração. +- Escape com `$${VAR}` para um literal `${VAR}`. - Funciona com `$include`. --- ## Segredos -Refs de segredo são aditivos: valores em texto simples continuam funcionando. +Refs de segredo são aditivas: valores em texto simples continuam funcionando. ### `SecretRef` -Use um formato único de objeto: +Use um formato de objeto: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3265,16 +3266,16 @@ Use um formato único de objeto: Validação: - padrão de `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- padrão de ID para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- padrão de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` id: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`) -- padrão de ID para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- IDs de `source: "exec"` não devem conter segmentos de caminho delimitados por `/` como `.` ou `..` (por exemplo `a/../b` é rejeitado) +- padrão de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- ids com `source: "exec"` não devem conter segmentos de caminho `.` ou `..` separados por `/` (por exemplo `a/../b` é rejeitado) -### Superfície de credencial compatível +### Superfície de credencial suportada -- Matriz canônica: [Superfície de credencial SecretRef](/pt-BR/reference/secretref-credential-surface) -- `secrets apply` direciona caminhos compatíveis de credencial em `openclaw.json`. -- Refs em `auth-profiles.json` estão incluídas na resolução em runtime e na cobertura de auditoria. +- Matriz canônica: [SecretRef Credential Surface](/pt-BR/reference/secretref-credential-surface) +- `secrets apply` direciona caminhos de credencial suportados em `openclaw.json`. +- Refs em `auth-profiles.json` são incluídas na resolução em runtime e na cobertura de auditoria. ### Configuração de provedores de segredo @@ -3282,7 +3283,7 @@ Validação: { secrets: { providers: { - default: { source: "env" }, // provedor de ambiente explícito opcional + default: { source: "env" }, // provedor env explícito opcional filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3306,13 +3307,13 @@ Validação: Observações: -- O provedor `file` é compatível com `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). -- O provedor `exec` exige um caminho absoluto em `command` e usa cargas úteis de protocolo em stdin/stdout. -- Por padrão, caminhos de comando por symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos por symlink enquanto valida o caminho do destino resolvido. +- O provedor `file` oferece suporte a `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). +- O provedor `exec` exige um caminho absoluto em `command` e usa payloads de protocolo em stdin/stdout. +- Por padrão, caminhos de comando que são symlinks são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos com symlink enquanto valida o caminho do destino resolvido. - Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho do destino resolvido. -- O ambiente filho de `exec` é mínimo por padrão; passe explicitamente variáveis necessárias com `passEnv`. -- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória, e depois os caminhos de requisição leem apenas o snapshot. -- A filtragem de superfície ativa se aplica durante a ativação: refs não resolvidas em superfícies habilitadas fazem a inicialização/reload falhar, enquanto superfícies inativas são ignoradas com diagnósticos. +- O ambiente do processo filho em `exec` é mínimo por padrão; passe variáveis necessárias explicitamente com `passEnv`. +- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória, e depois os caminhos de requisição leem apenas esse snapshot. +- A filtragem de superfícies ativas se aplica durante a ativação: refs não resolvidas em superfícies habilitadas fazem a inicialização/reload falhar, enquanto superfícies inativas são ignoradas com diagnósticos. --- @@ -3335,12 +3336,12 @@ Observações: ``` - Perfis por agente são armazenados em `/auth-profiles.json`. -- `auth-profiles.json` oferece suporte a refs no nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos estáticos de credencial. -- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não oferecem suporte a credenciais de perfil de auth com suporte de SecretRef. -- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são limpas quando descobertas. +- `auth-profiles.json` oferece suporte a refs no nível do valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática. +- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não oferecem suporte a credenciais de perfil de auth com suporte por SecretRef. +- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas estáticas legadas em `auth.json` são removidas quando encontradas. - Importações OAuth legadas de `~/.openclaw/credentials/oauth.json`. - Consulte [OAuth](/pt-BR/concepts/oauth). -- Comportamento do runtime de segredos e ferramentas `audit/configure/apply`: [Gerenciamento de segredos](/pt-BR/gateway/secrets). +- Comportamento do runtime de segredos e ferramentas `audit/configure/apply`: [Secrets Management](/pt-BR/gateway/secrets). ### `auth.cooldowns` @@ -3362,25 +3363,24 @@ Observações: } ``` -- `billingBackoffHours`: backoff base em horas quando um perfil falha por erros reais - de cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode - cair aqui mesmo em respostas `401`/`403`, mas correspondências de texto - específicas do provedor continuam limitadas ao provedor que as possui (por exemplo OpenRouter - `Key limit exceeded`). Mensagens de limite de gasto de janela de uso - ou organização/workspace em HTTP `402` passíveis de nova tentativa permanecem no caminho - `rate_limit`. -- `billingBackoffHoursByProvider`: substituições opcionais por provedor para horas de backoff de cobrança. -- `billingMaxHours`: limite em horas para o crescimento exponencial do backoff de cobrança (padrão: `24`). +- `billingBackoffHours`: backoff base em horas quando um perfil falha por erros reais de + billing/crédito insuficiente (padrão: `5`). Texto explícito de billing ainda pode + cair aqui mesmo em respostas `401`/`403`, mas correspondências de texto específicas + de provedor permanecem restritas ao provedor a que pertencem (por exemplo OpenRouter + `Key limit exceeded`). Mensagens de janela de uso `402` passível de retry ou + limite de gastos de organização/workspace permanecem no caminho `rate_limit`. +- `billingBackoffHoursByProvider`: substituições opcionais por provedor para horas de backoff de billing. +- `billingMaxHours`: limite em horas para o crescimento exponencial do backoff de billing (padrão: `24`). - `authPermanentBackoffMinutes`: backoff base em minutos para falhas `auth_permanent` de alta confiança (padrão: `10`). - `authPermanentMaxMinutes`: limite em minutos para o crescimento do backoff de `auth_permanent` (padrão: `60`). - `failureWindowHours`: janela móvel em horas usada para contadores de backoff (padrão: `24`). -- `overloadedProfileRotations`: máximo de rotações de auth-profile do mesmo provedor para erros de sobrecarga antes de mudar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado como `ModelNotReadyException` caem aqui. +- `overloadedProfileRotations`: máximo de rotações de auth-profile do mesmo provedor para erros de sobrecarga antes de mudar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado como `ModelNotReadyException` entram aqui. - `overloadedBackoffMs`: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: `0`). -- `rateLimitedProfileRotations`: máximo de rotações de auth-profile do mesmo provedor para erros de limite de taxa antes de mudar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui textos moldados pelo provedor como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `rateLimitedProfileRotations`: máximo de rotações de auth-profile do mesmo provedor para erros de limite de taxa antes de mudar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto característico do provedor como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- -## Registro em log +## Logging ```json5 { @@ -3397,12 +3397,12 @@ Observações: - Arquivo de log padrão: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Defina `logging.file` para um caminho estável. -- `consoleLevel` sobe para `debug` quando `--verbose`. -- `maxFileBytes`: tamanho máximo do arquivo de log em bytes antes que as gravações sejam suprimidas (inteiro positivo; padrão: `524288000` = 500 MB). Use rotação externa de logs para implantações em produção. +- `consoleLevel` sobe para `debug` com `--verbose`. +- `maxFileBytes`: tamanho máximo do arquivo de log em bytes antes de as gravações serem suprimidas (inteiro positivo; padrão: `524288000` = 500 MB). Use rotação de logs externa para implantações em produção. --- -## Diagnóstico +## Diagnósticos ```json5 { @@ -3436,9 +3436,9 @@ Observações: ``` - `enabled`: chave mestra para saída de instrumentação (padrão: `true`). -- `flags`: array de strings de flags que habilitam saída de log direcionada (suporta curingas como `"telegram.*"` ou `"*"`). -- `stuckSessionWarnMs`: limite de idade em ms para emitir avisos de sessão travada enquanto uma sessão permanece no estado de processamento. -- `otel.enabled`: habilita o pipeline de exportação OpenTelemetry (padrão: `false`). +- `flags`: array de strings de flag que habilitam saída de log direcionada (suporta curingas como `"telegram.*"` ou `"*"`). +- `stuckSessionWarnMs`: limite de idade em ms para emitir avisos de sessão travada enquanto uma sessão permanece em estado de processamento. +- `otel.enabled`: habilita o pipeline de exportação do OpenTelemetry (padrão: `false`). - `otel.endpoint`: URL do coletor para exportação OTel. - `otel.protocol`: `"http/protobuf"` (padrão) ou `"grpc"`. - `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com requisições de exportação OTel. @@ -3448,7 +3448,7 @@ Observações: - `otel.flushIntervalMs`: intervalo periódico de flush de telemetria em ms. - `cacheTrace.enabled`: registra snapshots de rastreamento de cache para execuções embutidas (padrão: `false`). - `cacheTrace.filePath`: caminho de saída para o JSONL de rastreamento de cache (padrão: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída do rastreamento de cache (todos usam `true` por padrão). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída de rastreamento de cache (todos com padrão: `true`). --- @@ -3470,12 +3470,12 @@ Observações: } ``` -- `channel`: canal de lançamento para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. +- `channel`: canal de release para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. - `checkOnStart`: verifica atualizações npm quando o gateway inicia (padrão: `true`). - `auto.enabled`: habilita atualização automática em segundo plano para instalações de pacote (padrão: `false`). -- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal stable (padrão: `6`; máximo: `168`). -- `auto.stableJitterHours`: janela extra em horas para distribuição gradual no canal stable (padrão: `12`; máximo: `168`). -- `auto.betaCheckIntervalHours`: frequência em horas das verificações no canal beta (padrão: `1`; máximo: `24`). +- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máximo: `168`). +- `auto.stableJitterHours`: janela extra de distribuição em horas para rollout do canal estável (padrão: `12`; máximo: `168`). +- `auto.betaCheckIntervalHours`: frequência, em horas, das verificações do canal beta (padrão: `1`; máximo: `24`). --- @@ -3508,22 +3508,22 @@ Observações: } ``` -- `enabled`: chave global do recurso ACP (padrão: `false`). -- `dispatch.enabled`: chave independente para despacho de turnos de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. -- `backend`: ID padrão do backend de runtime ACP (deve corresponder a um plugin de runtime ACP registrado). -- `defaultAgent`: ID do agente ACP de fallback quando spawns não especificam um destino explícito. -- `allowedAgents`: lista de permissões de IDs de agente permitidos para sessões de runtime ACP; vazio significa sem restrição adicional. -- `maxConcurrentSessions`: número máximo de sessões ACP ativas simultaneamente. -- `stream.coalesceIdleMs`: janela de flush por inatividade em ms para texto transmitido. -- `stream.maxChunkChars`: tamanho máximo de chunk antes de dividir a projeção do bloco transmitido. +- `enabled`: gate global do recurso ACP (padrão: `false`). +- `dispatch.enabled`: gate independente para despacho de turnos de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. +- `backend`: id do backend de runtime ACP padrão (deve corresponder a um plugin de runtime ACP registrado). +- `defaultAgent`: id do agente ACP de fallback quando criações não especificam um alvo explícito. +- `allowedAgents`: allowlist de ids de agente permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional. +- `maxConcurrentSessions`: máximo de sessões ACP ativas simultaneamente. +- `stream.coalesceIdleMs`: janela de flush por inatividade em ms para texto em streaming. +- `stream.maxChunkChars`: tamanho máximo de fragmento antes da divisão da projeção do bloco em streaming. - `stream.repeatSuppression`: suprime linhas repetidas de status/ferramenta por turno (padrão: `true`). -- `stream.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` faz buffer até eventos terminais do turno. +- `stream.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` armazena em buffer até eventos terminais do turno. - `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos ocultos de ferramenta (padrão: `"paragraph"`). - `stream.maxOutputChars`: máximo de caracteres de saída do assistente projetados por turno ACP. - `stream.maxSessionUpdateChars`: máximo de caracteres para linhas projetadas de status/atualização ACP. -- `stream.tagVisibility`: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos. -- `runtime.ttlMinutes`: TTL de inatividade em minutos para workers de sessão ACP antes de se tornarem elegíveis para limpeza. -- `runtime.installCommand`: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP. +- `stream.tagVisibility`: registro de nomes de tag para substituições booleanas de visibilidade em eventos transmitidos. +- `runtime.ttlMinutes`: TTL de inatividade em minutos para workers de sessão ACP antes de ficarem elegíveis para limpeza. +- `runtime.installCommand`: comando de instalação opcional para executar ao preparar um ambiente de runtime ACP. --- @@ -3542,8 +3542,8 @@ Observações: - `cli.banner.taglineMode` controla o estilo da tagline do banner: - `"random"` (padrão): taglines rotativas engraçadas/sazonais. - `"default"`: tagline neutra fixa (`All your chats, one OpenClaw.`). - - `"off"`: sem texto de tagline (o título/versão do banner ainda é exibido). -- Para ocultar o banner inteiro (não apenas as taglines), defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. + - `"off"`: sem texto de tagline (o título/versão do banner ainda é mostrado). +- Para ocultar o banner inteiro (não apenas as taglines), defina a env `OPENCLAW_HIDE_BANNER=1`. --- @@ -3565,17 +3565,17 @@ Metadados gravados pelos fluxos guiados de configuração da CLI (`onboard`, `co --- -## Identidade +## Identity -Consulte os campos de identidade de `agents.list` em [Padrões do agente](#agent-defaults). +Consulte os campos de identidade em `agents.list` em [Padrões de agente](#agent-defaults). --- ## Bridge (legado, removido) -As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. Chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até que sejam removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). +As compilações atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. As chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até serem removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). - + ```json { @@ -3602,7 +3602,7 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // fallback obsoleto para jobs armazenados com notify:true + webhook: "https://example.invalid/legacy", // fallback legado obsoleto para jobs armazenados com notify:true webhookToken: "replace-with-dedicated-token", // token bearer opcional para auth de webhook de saída sessionRetention: "24h", // string de duração ou false runLog: { @@ -3613,11 +3613,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke } ``` -- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções cron isoladas antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas excluídas do cron. Padrão: `24h`; defina `false` para desativar. -- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da limpeza. Padrão: `2_000_000` bytes. -- `runLog.keepLines`: linhas mais recentes retidas quando a limpeza do log de execução é acionada. Padrão: `2000`. -- `webhookToken`: token bearer usado para entrega POST de webhook do cron (`delivery.mode = "webhook"`); se omitido, nenhum cabeçalho de auth é enviado. -- `webhook`: URL obsoleta de webhook legado (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`. +- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções cron isoladas antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições cron arquivadas e excluídas. Padrão: `24h`; defina `false` para desabilitar. +- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da poda. Padrão: `2_000_000` bytes. +- `runLog.keepLines`: linhas mais recentes mantidas quando a poda do log de execução é acionada. Padrão: `2000`. +- `webhookToken`: token bearer usado para entrega por POST de webhook do cron (`delivery.mode = "webhook"`); se omitido, nenhum cabeçalho de auth é enviado. +- `webhook`: URL de webhook legada obsoleta (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`. ### `cron.retry` @@ -3633,11 +3633,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke } ``` -- `maxAttempts`: máximo de novas tentativas para jobs one-shot em erros transitórios (padrão: `3`; intervalo: `0`–`10`). -- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de repetição (padrão: `[30000, 60000, 300000]`; 1–10 entradas). -- `retryOn`: tipos de erro que acionam novas tentativas — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para repetir em todos os tipos transitórios. +- `maxAttempts`: máximo de retries para jobs one-shot em erros transitórios (padrão: `3`; intervalo: `0`–`10`). +- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de retry (padrão: `[30000, 60000, 300000]`; de 1 a 10 entradas). +- `retryOn`: tipos de erro que acionam retries — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para repetir todos os tipos transitórios. -Aplica-se apenas a jobs cron one-shot. Jobs recorrentes usam um tratamento de falha separado. +Aplica-se apenas a jobs cron one-shot. Jobs recorrentes usam tratamento de falhas separado. ### `cron.failureAlert` @@ -3656,10 +3656,10 @@ Aplica-se apenas a jobs cron one-shot. Jobs recorrentes usam um tratamento de fa ``` - `enabled`: habilita alertas de falha para jobs cron (padrão: `false`). -- `after`: falhas consecutivas antes de um alerta ser disparado (inteiro positivo, mín: `1`). -- `cooldownMs`: mínimo de milissegundos entre alertas repetidos para o mesmo job (inteiro não negativo). -- `mode`: modo de entrega — `"announce"` envia por mensagem de canal; `"webhook"` publica no webhook configurado. -- `accountId`: ID opcional de conta ou canal para delimitar a entrega do alerta. +- `after`: número de falhas consecutivas antes de um alerta disparar (inteiro positivo, mín.: `1`). +- `cooldownMs`: milissegundos mínimos entre alertas repetidos para o mesmo job (inteiro não negativo). +- `mode`: modo de entrega — `"announce"` envia por mensagem de canal; `"webhook"` faz POST para o webhook configurado. +- `accountId`: id opcional de conta ou canal para definir o escopo da entrega do alerta. ### `cron.failureDestination` @@ -3678,14 +3678,14 @@ Aplica-se apenas a jobs cron one-shot. Jobs recorrentes usam um tratamento de fa - Destino padrão para notificações de falha de cron em todos os jobs. - `mode`: `"announce"` ou `"webhook"`; usa `"announce"` por padrão quando existem dados de destino suficientes. -- `channel`: substituição de canal para entrega por announce. `"last"` reutiliza o último canal conhecido de entrega. +- `channel`: substituição de canal para entrega por announce. `"last"` reutiliza o último canal de entrega conhecido. - `to`: destino explícito de announce ou URL de webhook. Obrigatório no modo webhook. - `accountId`: substituição opcional de conta para entrega. - `delivery.failureDestination` por job substitui esse padrão global. -- Quando nem o destino global nem o por job estiverem definidos, jobs que já entregam via `announce` recorrem a esse destino principal de announce em caso de falha. -- `delivery.failureDestination` é compatível apenas com jobs `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do job seja `"webhook"`. +- Quando nem o destino global nem o destino por job de falha está definido, jobs que já entregam via `announce` usam esse destino primário de announce como fallback em caso de falha. +- `delivery.failureDestination` só é suportado para jobs com `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do job seja `"webhook"`. -Consulte [Jobs cron](/pt-BR/automation/cron-jobs). Execuções cron isoladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). +Consulte [Cron Jobs](/pt-BR/automation/cron-jobs). Execuções cron isoladas são rastreadas como [background tasks](/pt-BR/automation/tasks). --- @@ -3693,32 +3693,32 @@ Consulte [Jobs cron](/pt-BR/automation/cron-jobs). Execuções cron isoladas sã Placeholders de template expandidos em `tools.media.models[].args`: -| Variável | Descrição | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Corpo completo da mensagem recebida | +| Variável | Descrição | +| ------------------ | ------------------------------------------------ | +| `{{Body}}` | Corpo completo da mensagem recebida | | `{{RawBody}}` | Corpo bruto (sem wrappers de histórico/remetente) | -| `{{BodyStripped}}` | Corpo com menções de grupo removidas | -| `{{From}}` | Identificador do remetente | -| `{{To}}` | Identificador do destino | -| `{{MessageSid}}` | ID da mensagem do canal | -| `{{SessionId}}` | UUID da sessão atual | -| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | -| `{{MediaUrl}}` | Pseudo-URL da mídia recebida | -| `{{MediaPath}}` | Caminho local da mídia | -| `{{MediaType}}` | Tipo de mídia (image/audio/document/…) | -| `{{Transcript}}` | Transcrição de áudio | -| `{{Prompt}}` | Prompt de mídia resolvido para entradas CLI | -| `{{MaxChars}}` | Máximo de caracteres de saída resolvido para entradas CLI | -| `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | Assunto do grupo (melhor esforço) | -| `{{GroupMembers}}` | Prévia dos membros do grupo (melhor esforço) | -| `{{SenderName}}` | Nome de exibição do remetente (melhor esforço) | -| `{{SenderE164}}` | Número de telefone do remetente (melhor esforço) | -| `{{Provider}}` | Dica de provedor (whatsapp, telegram, discord etc.) | +| `{{BodyStripped}}` | Corpo com menções de grupo removidas | +| `{{From}}` | Identificador do remetente | +| `{{To}}` | Identificador de destino | +| `{{MessageSid}}` | id da mensagem do canal | +| `{{SessionId}}` | UUID da sessão atual | +| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | +| `{{MediaUrl}}` | pseudo-URL da mídia recebida | +| `{{MediaPath}}` | caminho local da mídia | +| `{{MediaType}}` | tipo de mídia (image/audio/document/…) | +| `{{Transcript}}` | transcrição de áudio | +| `{{Prompt}}` | prompt de mídia resolvido para entradas de CLI | +| `{{MaxChars}}` | máximo resolvido de caracteres de saída para entradas de CLI | +| `{{ChatType}}` | `"direct"` ou `"group"` | +| `{{GroupSubject}}` | assunto do grupo (melhor esforço) | +| `{{GroupMembers}}` | prévia dos membros do grupo (melhor esforço) | +| `{{SenderName}}` | nome de exibição do remetente (melhor esforço) | +| `{{SenderE164}}` | número de telefone do remetente (melhor esforço) | +| `{{Provider}}` | hint do provedor (whatsapp, telegram, discord etc.) | --- -## Includes de configuração (`$include`) +## Inclusões de configuração (`$include`) Divida a configuração em vários arquivos: @@ -3737,11 +3737,11 @@ Divida a configuração em vários arquivos: - Arquivo único: substitui o objeto que o contém. - Array de arquivos: mesclado profundamente em ordem (os posteriores substituem os anteriores). -- Chaves irmãs: mescladas após os includes (substituem valores incluídos). -- Includes aninhados: até 10 níveis de profundidade. -- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas apenas quando ainda resolvem dentro desse limite. -- Erros: mensagens claras para arquivos ausentes, erros de parse e includes circulares. +- Chaves irmãs: mescladas após as inclusões (substituem valores incluídos). +- Inclusões aninhadas: até 10 níveis de profundidade. +- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas apenas quando ainda se resolvem dentro desse limite. +- Erros: mensagens claras para arquivos ausentes, erros de parse e inclusões circulares. --- -_Relacionado: [Configuração](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ +_Relacionado: [Configuration](/pt-BR/gateway/configuration) · [Configuration Examples](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ diff --git a/docs/pt-BR/help/gpt54-codex-agentic-parity-maintainers.md b/docs/pt-BR/help/gpt54-codex-agentic-parity-maintainers.md new file mode 100644 index 000000000..2f26e3b8c --- /dev/null +++ b/docs/pt-BR/help/gpt54-codex-agentic-parity-maintainers.md @@ -0,0 +1,174 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:56Z" + model: gpt-5.4 + provider: openai + source_hash: 910bcf7668becf182ef48185b43728bf2fa69629d6d50189d47d47b06f807a9e + source_path: help/gpt54-codex-agentic-parity-maintainers.md + workflow: 15 +--- + +# Notas de manutenção sobre a paridade GPT-5.4 / Codex + +Esta nota explica como revisar o programa de paridade GPT-5.4 / Codex como quatro unidades de merge sem perder a arquitetura original de seis contratos. + +## Unidades de merge + +### PR A: execução agentiva estrita + +É responsável por: + +- `executionContract` +- continuidade na mesma rodada com GPT-5 em primeiro lugar +- `update_plan` como acompanhamento de progresso não terminal +- estados explícitos de bloqueio em vez de paradas silenciosas apenas no plano + +Não é responsável por: + +- classificação de falhas de autenticação/runtime +- veracidade sobre permissões +- reformulação de replay/continuação +- benchmark de paridade + +### PR B: veracidade de runtime + +É responsável por: + +- correção do escopo OAuth do Codex +- classificação tipada de falhas de provider/runtime +- veracidade sobre a disponibilidade de `/elevated full` e motivos de bloqueio + +Não é responsável por: + +- normalização do schema de ferramentas +- estado de replay/liveness +- benchmark gating + +### PR C: correção de execução + +É responsável por: + +- compatibilidade de ferramentas OpenAI/Codex de propriedade do provider +- tratamento estrito de schema sem parâmetros +- exposição de replay inválido +- visibilidade do estado de tarefas longas pausadas, bloqueadas e abandonadas + +Não é responsável por: + +- continuação autoeleita +- comportamento genérico do dialeto Codex fora dos hooks do provider +- benchmark gating + +### PR D: harness de paridade + +É responsável por: + +- primeiro pacote de cenários de GPT-5.4 vs Opus 4.6 +- documentação de paridade +- mecânica do relatório de paridade e do gate de release + +Não é responsável por: + +- mudanças de comportamento em runtime fora do QA-lab +- simulação de autenticação/proxy/DNS dentro do harness + +## Mapeamento de volta para os seis contratos originais + +| Contrato original | Unidade de merge | +| ----------------------------------------- | ---------------- | +| Correção de transporte/autenticação do provider | PR B | +| Compatibilidade de contrato/schema de ferramentas | PR C | +| Execução na mesma rodada | PR A | +| Veracidade sobre permissões | PR B | +| Correção de replay/continuação/liveness | PR C | +| Gate de benchmark/release | PR D | + +## Ordem de revisão + +1. PR A +2. PR B +3. PR C +4. PR D + +A PR D é a camada de comprovação. Ela não deve ser o motivo para atrasar PRs de correção de runtime. + +## O que observar + +### PR A + +- execuções do GPT-5 agem ou falham de forma fechada em vez de parar em comentário +- `update_plan` não parece mais progresso por si só +- o comportamento continua com GPT-5 em primeiro lugar e com escopo limitado ao Pi embarcado + +### PR B + +- falhas de autenticação/proxy/runtime deixam de ser colapsadas em um tratamento genérico de “model failed” +- `/elevated full` só é descrito como disponível quando realmente está disponível +- os motivos de bloqueio ficam visíveis tanto para o modelo quanto para o runtime voltado ao usuário + +### PR C + +- o registro estrito de ferramentas OpenAI/Codex se comporta de forma previsível +- ferramentas sem parâmetros não falham nas verificações estritas de schema +- resultados de replay e compactação preservam um estado de liveness verdadeiro + +### PR D + +- o pacote de cenários é compreensível e reproduzível +- o pacote inclui uma trilha mutável de segurança de replay, e não apenas fluxos somente leitura +- os relatórios são legíveis por humanos e automação +- as alegações de paridade são respaldadas por evidências, não anedóticas + +Artefatos esperados da PR D: + +- `qa-suite-report.md` / `qa-suite-summary.json` para cada execução de modelo +- `qa-agentic-parity-report.md` com comparação agregada e no nível de cenário +- `qa-agentic-parity-summary.json` com um veredito legível por máquina + +## Gate de release + +Não afirme paridade ou superioridade do GPT-5.4 sobre o Opus 4.6 até que: + +- PR A, PR B e PR C tenham sido mergeadas +- PR D execute o primeiro pacote de paridade sem falhas +- as suítes de regressão de veracidade de runtime permaneçam verdes +- o relatório de paridade não mostre casos de falso sucesso nem regressão no comportamento de parada + +```mermaid +flowchart LR + A["PR A-C merged"] --> B["Run GPT-5.4 parity pack"] + A --> C["Run Opus 4.6 parity pack"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["qa parity-report"] + E --> F + F --> G["Markdown report + JSON verdict"] + G --> H{"Pass?"} + H -- "yes" --> I["Parity claim allowed"] + H -- "no" --> J["Keep runtime fixes / review loop open"] +``` + +O harness de paridade não é a única fonte de evidência. Mantenha essa separação explícita na revisão: + +- a PR D é responsável pela comparação baseada em cenários entre GPT-5.4 e Opus 4.6 +- as suítes determinísticas da PR B continuam sendo responsáveis pelas evidências de autenticação/proxy/DNS e de veracidade sobre acesso total + +## Mapa de objetivo para evidência + +| Item do gate de conclusão | Responsável principal | Artefato de revisão | +| ----------------------------------------- | --------------------- | -------------------------------------------------------------------- | +| Sem travamentos apenas no plano | PR A | testes de runtime agentivo estrito e `approval-turn-tool-followthrough` | +| Sem progresso falso ou conclusão falsa de ferramenta | PR A + PR D | contagem de falsos sucessos na paridade mais detalhes do relatório no nível de cenário | +| Sem orientação falsa sobre `/elevated full` | PR B | suítes determinísticas de veracidade de runtime | +| Falhas de replay/liveness continuam explícitas | PR C + PR D | suítes de ciclo de vida/replay mais `compaction-retry-mutating-tool` | +| GPT-5.4 iguala ou supera Opus 4.6 | PR D | `qa-agentic-parity-report.md` e `qa-agentic-parity-summary.json` | + +## Atalho para revisores: antes vs depois + +| Problema visível para o usuário antes | Sinal de revisão depois | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| GPT-5.4 parava após planejar | A PR A mostra comportamento de agir-ou-bloquear em vez de conclusão apenas em comentário | +| O uso de ferramentas parecia frágil com schemas estritos do OpenAI/Codex | A PR C mantém previsível o registro de ferramentas e a invocação sem parâmetros | +| As dicas de `/elevated full` às vezes eram enganosas | A PR B vincula a orientação à capacidade real do runtime e aos motivos de bloqueio | +| Tarefas longas podiam desaparecer na ambiguidade de replay/compactação | A PR C emite estado explícito de pausado, bloqueado, abandonado e replay inválido | +| As alegações de paridade eram anedóticas | A PR D produz um relatório mais um veredito em JSON com a mesma cobertura de cenários em ambos os modelos | diff --git a/docs/pt-BR/help/gpt54-codex-agentic-parity.md b/docs/pt-BR/help/gpt54-codex-agentic-parity.md new file mode 100644 index 000000000..db17b3252 --- /dev/null +++ b/docs/pt-BR/help/gpt54-codex-agentic-parity.md @@ -0,0 +1,229 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:56Z" + model: gpt-5.4 + provider: openai + source_hash: 7ee6b925b8a0f8843693cea9d50b40544657b5fb8a9e0860e2ff5badb273acb6 + source_path: help/gpt54-codex-agentic-parity.md + workflow: 15 +--- + +# Paridade Agêntica do GPT-5.4 / Codex no OpenClaw + +O OpenClaw já funcionava bem com modelos de fronteira que usam ferramentas, mas os modelos GPT-5.4 e no estilo Codex ainda apresentavam desempenho inferior em alguns aspectos práticos: + +- podiam parar após planejar em vez de fazer o trabalho +- podiam usar incorretamente esquemas de ferramentas estritos do OpenAI/Codex +- podiam pedir `/elevated full` mesmo quando o acesso total era impossível +- podiam perder o estado de tarefas longas durante replay ou compactação +- alegações de paridade em relação ao Claude Opus 4.6 eram baseadas em relatos anedóticos em vez de cenários repetíveis + +Este programa de paridade corrige essas lacunas em quatro partes revisáveis. + +## O que mudou + +### PR A: execução agêntica estrita + +Esta parte adiciona um contrato de execução `strict-agentic` opcional para execuções do GPT-5 incorporado no Pi. + +Quando ativado, o OpenClaw deixa de aceitar turnos apenas com plano como conclusão “boa o suficiente”. Se o modelo apenas disser o que pretende fazer e não realmente usar ferramentas nem progredir, o OpenClaw tenta novamente com uma orientação para agir agora e depois falha de forma segura com um estado bloqueado explícito, em vez de encerrar a tarefa silenciosamente. + +Isso melhora a experiência com GPT-5.4 principalmente em: + +- acompanhamentos curtos como “ok, faça isso” +- tarefas de código em que a primeira etapa é óbvia +- fluxos em que `update_plan` deve servir para acompanhar progresso, e não como texto de preenchimento + +### PR B: veracidade do runtime + +Esta parte faz o OpenClaw dizer a verdade sobre duas coisas: + +- por que a chamada ao provedor/runtime falhou +- se `/elevated full` está realmente disponível + +Isso significa que o GPT-5.4 recebe sinais de runtime melhores para escopo ausente, falhas de renovação de autenticação, falhas de autenticação HTML 403, problemas de proxy, falhas de DNS ou timeout, e modos de acesso total bloqueados. O modelo fica menos propenso a inventar a remediação errada ou continuar pedindo um modo de permissão que o runtime não pode fornecer. + +### PR C: correção de execução + +Esta parte melhora dois tipos de correção: + +- compatibilidade com esquemas de ferramentas OpenAI/Codex de propriedade do provedor +- visibilidade de replay e vivacidade de tarefas longas + +O trabalho de compatibilidade com ferramentas reduz o atrito de esquema para registro estrito de ferramentas OpenAI/Codex, especialmente em torno de ferramentas sem parâmetros e expectativas estritas de objeto na raiz. O trabalho de replay/vivacidade torna tarefas longas mais observáveis, para que estados pausado, bloqueado e abandonado fiquem visíveis em vez de desaparecerem em um texto genérico de falha. + +### PR D: harness de paridade + +Esta parte adiciona o primeiro pacote de paridade do QA-lab, para que GPT-5.4 e Opus 4.6 possam ser exercitados nos mesmos cenários e comparados usando evidências compartilhadas. + +O pacote de paridade é a camada de prova. Ele não altera o comportamento do runtime por si só. + +Depois de ter dois artefatos `qa-suite-summary.json`, gere a comparação do gate de release com: + +```bash +pnpm openclaw qa parity-report \ + --repo-root . \ + --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \ + --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \ + --output-dir .artifacts/qa-e2e/parity +``` + +Esse comando grava: + +- um relatório Markdown legível por humanos +- um veredito JSON legível por máquina +- um resultado de gate explícito `pass` / `fail` + +## Por que isso melhora o GPT-5.4 na prática + +Antes deste trabalho, o GPT-5.4 no OpenClaw podia parecer menos agêntico que o Opus em sessões reais de programação porque o runtime tolerava comportamentos especialmente prejudiciais para modelos no estilo GPT-5: + +- turnos só com comentários +- atrito de esquema em torno de ferramentas +- feedback de permissão vago +- quebra silenciosa de replay ou compactação + +O objetivo não é fazer o GPT-5.4 imitar o Opus. O objetivo é dar ao GPT-5.4 um contrato de runtime que recompense progresso real, forneça semântica mais limpa para ferramentas e permissões, e transforme modos de falha em estados explícitos, legíveis por máquina e por humanos. + +Isso muda a experiência do usuário de: + +- “o modelo tinha um bom plano, mas parou” + +para: + +- “o modelo ou agiu, ou o OpenClaw mostrou o motivo exato pelo qual ele não pôde agir” + +## Antes vs. depois para usuários do GPT-5.4 + +| Antes deste programa | Depois das PRs A-D | +| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| O GPT-5.4 podia parar após um plano razoável sem dar o próximo passo com ferramenta | A PR A transforma “apenas plano” em “aja agora ou mostre um estado bloqueado” | +| Esquemas estritos de ferramentas podiam rejeitar ferramentas sem parâmetros ou no formato OpenAI/Codex de maneiras confusas | A PR C torna o registro e a invocação de ferramentas de propriedade do provedor mais previsíveis | +| A orientação sobre `/elevated full` podia ser vaga ou incorreta em runtimes bloqueados | A PR B dá ao GPT-5.4 e ao usuário dicas de runtime e permissões fiéis à realidade | +| Falhas de replay ou compactação podiam dar a sensação de que a tarefa simplesmente sumiu | A PR C mostra explicitamente resultados pausados, bloqueados, abandonados e inválidos para replay | +| “O GPT-5.4 parece pior que o Opus” era em grande parte anedótico | A PR D transforma isso no mesmo pacote de cenários, nas mesmas métricas e em um gate rígido de pass/fail | + +## Arquitetura + +```mermaid +flowchart TD + A["Solicitação do usuário"] --> B["Runtime Pi incorporado"] + B --> C["Contrato de execução agêntica estrita"] + B --> D["Compatibilidade de ferramentas de propriedade do provedor"] + B --> E["Veracidade do runtime"] + B --> F["Replay e estado de vivacidade"] + C --> G["Chamada de ferramenta ou estado bloqueado explícito"] + D --> G + E --> G + F --> G + G --> H["Pacote de paridade do QA-lab"] + H --> I["Relatório de cenário e gate de paridade"] +``` + +## Fluxo de release + +```mermaid +flowchart LR + A["Partes de runtime mescladas (PRs A-C)"] --> B["Executar pacote de paridade do GPT-5.4"] + A --> C["Executar pacote de paridade do Opus 4.6"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["openclaw qa parity-report"] + E --> F + F --> G["qa-agentic-parity-report.md"] + F --> H["qa-agentic-parity-summary.json"] + H --> I{"Gate aprovado?"} + I -- "sim" --> J["Alegação de paridade respaldada por evidências"] + I -- "não" --> K["Manter aberto o ciclo de runtime/revisão"] +``` + +## Pacote de cenários + +O pacote de paridade de primeira onda atualmente cobre cinco cenários: + +### `approval-turn-tool-followthrough` + +Verifica se o modelo não para em “vou fazer isso” após uma aprovação curta. Ele deve executar a primeira ação concreta no mesmo turno. + +### `model-switch-tool-continuity` + +Verifica se o trabalho com uso de ferramentas permanece coerente através de limites de troca de modelo/runtime, em vez de reiniciar em comentários ou perder o contexto de execução. + +### `source-docs-discovery-report` + +Verifica se o modelo consegue ler código-fonte e documentação, sintetizar conclusões e continuar a tarefa de forma agêntica, em vez de produzir um resumo superficial e parar cedo. + +### `image-understanding-attachment` + +Verifica se tarefas de modo misto que envolvem anexos permanecem acionáveis e não colapsam em uma narração vaga. + +### `compaction-retry-mutating-tool` + +Verifica se uma tarefa com uma gravação mutável real mantém a insegurança de replay explícita, em vez de parecer silenciosamente segura para replay quando a execução sofre compactação, retry ou perda de estado de resposta sob pressão. + +## Matriz de cenários + +| Cenário | O que testa | Bom comportamento do GPT-5.4 | Sinal de falha | +| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| `approval-turn-tool-followthrough` | Turnos curtos de aprovação após um plano | Inicia imediatamente a primeira ação concreta com ferramenta, em vez de repetir a intenção | acompanhamento só com plano, nenhuma atividade de ferramenta, ou turno bloqueado sem um bloqueador real | +| `model-switch-tool-continuity` | Troca de runtime/modelo durante uso de ferramentas | Preserva o contexto da tarefa e continua agindo de forma coerente | reinicia em comentários, perde o contexto de ferramenta, ou para após a troca | +| `source-docs-discovery-report` | Leitura de código + síntese + ação | Encontra fontes, usa ferramentas e produz um relatório útil sem travar | resumo superficial, trabalho com ferramentas ausente, ou parada de turno incompleta | +| `image-understanding-attachment` | Trabalho agêntico guiado por anexo | Interpreta o anexo, conecta-o às ferramentas e continua a tarefa | narração vaga, anexo ignorado, ou nenhuma próxima ação concreta | +| `compaction-retry-mutating-tool` | Trabalho mutável sob pressão de compactação | Executa uma gravação real e mantém a insegurança de replay explícita após o efeito colateral | a gravação mutável acontece, mas a segurança de replay é implícita, ausente ou contraditória | + +## Gate de release + +O GPT-5.4 só pode ser considerado em paridade ou melhor quando o runtime mesclado passa no pacote de paridade e nas regressões de veracidade do runtime ao mesmo tempo. + +Resultados obrigatórios: + +- nenhum travamento em plano apenas quando a próxima ação com ferramenta é clara +- nenhuma conclusão falsa sem execução real +- nenhuma orientação incorreta sobre `/elevated full` +- nenhum abandono silencioso por replay ou compactação +- métricas do pacote de paridade pelo menos tão fortes quanto a baseline acordada do Opus 4.6 + +Para o harness de primeira onda, o gate compara: + +- taxa de conclusão +- taxa de parada não intencional +- taxa de chamada de ferramenta válida +- contagem de sucesso falso + +A evidência de paridade é intencionalmente dividida em duas camadas: + +- a PR D comprova o comportamento do GPT-5.4 vs. Opus 4.6 nos mesmos cenários com o QA-lab +- as suítes determinísticas da PR B comprovam veracidade de autenticação, proxy, DNS e `/elevated full` fora do harness + +## Matriz objetivo-evidência + +| Item do gate de conclusão | PR responsável | Fonte de evidência | Sinal de aprovação | +| ------------------------------------------------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | +| O GPT-5.4 não trava mais após planejar | PR A | `approval-turn-tool-followthrough` mais as suítes de runtime da PR A | turnos de aprovação disparam trabalho real ou um estado bloqueado explícito | +| O GPT-5.4 não finge mais progresso nem conclusão falsa de ferramenta | PR A + PR D | resultados de cenários do relatório de paridade e contagem de sucesso falso | nenhum resultado de aprovação suspeito e nenhuma conclusão apenas com comentários | +| O GPT-5.4 não dá mais orientação falsa sobre `/elevated full` | PR B | suítes determinísticas de veracidade | razões de bloqueio e dicas de acesso total permanecem fiéis ao runtime | +| Falhas de replay/vivacidade permanecem explícitas | PR C + PR D | suítes de ciclo de vida/replay da PR C mais `compaction-retry-mutating-tool` | trabalho mutável mantém a insegurança de replay explícita, em vez de desaparecer silenciosamente | +| O GPT-5.4 iguala ou supera o Opus 4.6 nas métricas acordadas | PR D | `qa-agentic-parity-report.md` e `qa-agentic-parity-summary.json` | mesma cobertura de cenários e nenhuma regressão em conclusão, comportamento de parada ou uso válido de ferramentas | + +## Como ler o veredito de paridade + +Use o veredito em `qa-agentic-parity-summary.json` como a decisão final legível por máquina para o pacote de paridade de primeira onda. + +- `pass` significa que o GPT-5.4 cobriu os mesmos cenários que o Opus 4.6 e não regrediu nas métricas agregadas acordadas. +- `fail` significa que pelo menos um gate rígido foi acionado: conclusão mais fraca, paradas não intencionais piores, uso válido de ferramentas mais fraco, qualquer caso de sucesso falso, ou cobertura de cenários incompatível. +- “problema de CI compartilhado/base” não é, por si só, um resultado de paridade. Se ruído de CI fora da PR D bloquear uma execução, o veredito deve esperar por uma execução limpa do runtime mesclado, em vez de ser inferido a partir de logs da época do branch. +- A veracidade de autenticação, proxy, DNS e `/elevated full` continua vindo das suítes determinísticas da PR B, então a alegação final de release precisa dos dois: um veredito de paridade aprovando na PR D e cobertura de veracidade verde na PR B. + +## Quem deve ativar `strict-agentic` + +Use `strict-agentic` quando: + +- espera-se que o agente aja imediatamente quando a próxima etapa for óbvia +- modelos GPT-5.4 ou da família Codex forem o runtime principal +- você preferir estados bloqueados explícitos em vez de respostas “úteis” apenas de recapitulação + +Mantenha o contrato padrão quando: + +- você quiser o comportamento atual mais flexível +- você não estiver usando modelos da família GPT-5 +- você estiver testando prompts em vez da aplicação do runtime diff --git a/docs/pt-BR/plugins/architecture.md b/docs/pt-BR/plugins/architecture.md index 60701ac0f..490942629 100644 --- a/docs/pt-BR/plugins/architecture.md +++ b/docs/pt-BR/plugins/architecture.md @@ -3,23 +3,23 @@ read_when: - Criando ou depurando plugins nativos do OpenClaw - Entendendo o modelo de capacidades de plugins ou os limites de propriedade - Trabalhando no pipeline de carregamento de plugins ou no registro - - Implementando hooks de runtime de provedores ou plugins de canal + - Implementando hooks de runtime de provedor ou plugins de canal sidebarTitle: Internals -summary: 'Detalhes internos de plugins: modelo de capacidades, propriedade, contratos, pipeline de carregamento e helpers de runtime' -title: Detalhes internos de plugins +summary: 'Internos de plugins: modelo de capacidades, propriedade, contratos, pipeline de carregamento e auxiliares de runtime' +title: Internos de plugins x-i18n: - generated_at: "2026-04-09T01:32:55Z" + generated_at: "2026-04-11T15:16:05Z" model: gpt-5.4 provider: openai - source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 + source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 source_path: plugins/architecture.md workflow: 15 --- -# Detalhes internos de plugins +# Internos de plugins - Esta é a **referência aprofundada de arquitetura**. Para guias práticos, veja: + Esta é a **referência aprofundada de arquitetura**. Para guias práticos, consulte: - [Instalar e usar plugins](/pt-BR/tools/plugin) — guia do usuário - [Primeiros passos](/pt-BR/plugins/building-plugins) — primeiro tutorial de plugin - [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — crie um canal de mensagens @@ -27,171 +27,160 @@ x-i18n: - [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — mapa de importação e API de registro -Esta página cobre a arquitetura interna do sistema de plugins do OpenClaw. +Esta página aborda a arquitetura interna do sistema de plugins do OpenClaw. ## Modelo público de capacidades -Capacidades são o modelo público de **plugin nativo** dentro do OpenClaw. Todo -plugin nativo do OpenClaw se registra em um ou mais tipos de capacidade: +As capacidades são o modelo público de **plugin nativo** dentro do OpenClaw. Todo +plugin nativo do OpenClaw é registrado em um ou mais tipos de capacidade: -| Capacidade | Método de registro | Plugins de exemplo | -| ---------------------- | ---------------------------------------------- | ------------------------------------ | -| Inferência de texto | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend de inferência da CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Voz | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Transcrição em tempo real | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Voz em tempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Entendimento de mídia | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Geração de imagem | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Geração de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Geração de vídeo | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Busca web | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Pesquisa na web | `api.registerWebSearchProvider(...)` | `google` | -| Canal / mensagens | `api.registerChannel(...)` | `msteams`, `matrix` | +| Capacidade | Método de registro | Plugins de exemplo | +| ---------------------- | ----------------------------------------------- | ----------------------------------- | +| Inferência de texto | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend de inferência da CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Fala | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Transcrição em tempo real | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Voz em tempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Compreensão de mídia | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Geração de imagens | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Geração de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Geração de vídeo | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Busca na web | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Pesquisa na web | `api.registerWebSearchProvider(...)` | `google` | +| Canal / mensagens | `api.registerChannel(...)` | `msteams`, `matrix` | Um plugin que registra zero capacidades, mas fornece hooks, ferramentas ou -serviços, é um plugin **legado somente com hooks**. Esse padrão ainda tem -suporte completo. +serviços, é um plugin **legado somente com hooks**. Esse padrão ainda é totalmente compatível. -### Posição de compatibilidade externa +### Postura de compatibilidade externa -O modelo de capacidades já está integrado ao núcleo e é usado por plugins -nativos/integrados hoje, mas a compatibilidade com plugins externos ainda -precisa de um critério mais rigoroso do que "foi exportado, portanto está -congelado". +O modelo de capacidades já está incorporado ao core e é usado por plugins +nativos/embutidos hoje, mas a compatibilidade de plugins externos ainda precisa +de um critério mais rigoroso do que “está exportado, portanto está congelado”. Orientação atual: -- **plugins externos existentes:** mantenha integrações baseadas em hooks - funcionando; trate isso como a linha de base de compatibilidade -- **novos plugins nativos/integrados:** prefira registro explícito de - capacidades em vez de acessos específicos a fornecedores ou novos designs - somente com hooks -- **plugins externos adotando registro de capacidades:** permitido, mas trate - superfícies helper específicas de capacidade como evolutivas, a menos que a - documentação marque explicitamente um contrato como estável +- **plugins externos existentes:** mantenha as integrações baseadas em hooks funcionando; trate + isso como a linha de base de compatibilidade +- **novos plugins nativos/embutidos:** prefira registro explícito de capacidades em vez de + acessos específicos de fornecedor ou novos designs somente com hooks +- **plugins externos adotando registro de capacidades:** permitido, mas trate as + superfícies auxiliares específicas de capacidade como evolutivas, a menos que a documentação marque explicitamente + um contrato como estável Regra prática: -- APIs de registro de capacidades são a direção pretendida -- hooks legados continuam sendo o caminho mais seguro para evitar quebras em - plugins externos durante a transição -- nem todos os subcaminhos helper exportados são equivalentes; prefira o - contrato estreito documentado, não exports helper incidentais +- as APIs de registro de capacidades são a direção pretendida +- hooks legados continuam sendo o caminho mais seguro para evitar quebras em plugins externos durante + a transição +- os subcaminhos auxiliares exportados não são todos equivalentes; prefira o contrato + documentado e específico, não exportações auxiliares incidentais -### Formatos de plugin +### Formas de plugins -O OpenClaw classifica cada plugin carregado em um formato com base no seu -comportamento real de registro (não apenas metadados estáticos): +O OpenClaw classifica todo plugin carregado em uma forma com base no seu +comportamento real de registro (não apenas em metadados estáticos): -- **plain-capability** -- registra exatamente um tipo de capacidade (por - exemplo, um plugin somente de provedor como `mistral`) -- **hybrid-capability** -- registra múltiplos tipos de capacidade (por exemplo, - `openai` controla inferência de texto, voz, entendimento de mídia e geração - de imagem) +- **plain-capability** -- registra exatamente um tipo de capacidade (por exemplo, um + plugin somente de provedor, como `mistral`) +- **hybrid-capability** -- registra vários tipos de capacidade (por exemplo, + `openai` é responsável por inferência de texto, fala, compreensão de mídia e + geração de imagens) - **hook-only** -- registra apenas hooks (tipados ou personalizados), sem capacidades, ferramentas, comandos ou serviços -- **non-capability** -- registra ferramentas, comandos, serviços ou rotas, mas - não capacidades +- **non-capability** -- registra ferramentas, comandos, serviços ou rotas, mas não + capacidades -Use `openclaw plugins inspect ` para ver o formato de um plugin e o -detalhamento de capacidades. Veja [referência da CLI](/cli/plugins#inspect) -para mais detalhes. +Use `openclaw plugins inspect ` para ver a forma de um plugin e o detalhamento +de capacidades. Consulte a [referência da CLI](/cli/plugins#inspect) para mais detalhes. ### Hooks legados -O hook `before_agent_start` continua com suporte como caminho de compatibilidade -para plugins somente com hooks. Plugins reais legados ainda dependem dele. +O hook `before_agent_start` continua compatível como caminho de compatibilidade para +plugins somente com hooks. Plugins legados do mundo real ainda dependem dele. Direção: -- mantê-lo funcionando -- documentá-lo como legado -- preferir `before_model_resolve` para trabalho de substituição de modelo/provedor -- preferir `before_prompt_build` para trabalho de mutação de prompt -- remover apenas depois que o uso real cair e a cobertura de fixtures provar a - segurança da migração +- mantenha-o funcionando +- documente-o como legado +- prefira `before_model_resolve` para trabalho de substituição de modelo/provedor +- prefira `before_prompt_build` para trabalho de mutação de prompt +- remova-o apenas depois que o uso real cair e a cobertura de fixtures comprovar a segurança da migração ### Sinais de compatibilidade Quando você executa `openclaw doctor` ou `openclaw plugins inspect `, pode ver um destes rótulos: -| Sinal | Significado | -| ------------------------- | ------------------------------------------------------------ | -| **config valid** | A configuração é analisada corretamente e os plugins são resolvidos | -| **compatibility advisory** | O plugin usa um padrão suportado, mas mais antigo (ex.: `hook-only`) | -| **legacy warning** | O plugin usa `before_agent_start`, que está obsoleto | -| **hard error** | A configuração é inválida ou o plugin falhou ao carregar | +| Sinal | Significado | +| -------------------------- | ------------------------------------------------------------ | +| **config valid** | A configuração é analisada corretamente e os plugins são resolvidos | +| **compatibility advisory** | O plugin usa um padrão compatível, mas mais antigo (por exemplo, `hook-only`) | +| **legacy warning** | O plugin usa `before_agent_start`, que está obsoleto | +| **hard error** | A configuração é inválida ou o plugin falhou ao carregar | -Nem `hook-only` nem `before_agent_start` vão quebrar seu plugin hoje -- -`hook-only` é apenas informativo, e `before_agent_start` só dispara um aviso. -Esses sinais também aparecem em `openclaw status --all` e `openclaw plugins doctor`. +Nem `hook-only` nem `before_agent_start` quebrarão seu plugin hoje -- +`hook-only` é apenas informativo, e `before_agent_start` apenas dispara um aviso. Esses +sinais também aparecem em `openclaw status --all` e `openclaw plugins doctor`. ## Visão geral da arquitetura O sistema de plugins do OpenClaw tem quatro camadas: 1. **Manifesto + descoberta** - O OpenClaw encontra plugins candidatos a partir de caminhos configurados, - raízes do workspace, raízes globais de extensões e extensões integradas. A - descoberta lê primeiro manifestos nativos `openclaw.plugin.json` e - manifestos de bundle compatíveis suportados. -2. **Ativação + validação** - O núcleo decide se um plugin descoberto está ativado, desativado, bloqueado - ou selecionado para um slot exclusivo, como memória. + O OpenClaw encontra plugins candidatos em caminhos configurados, raízes de workspace, + raízes globais de extensões e extensões embutidas. A descoberta lê primeiro os + manifestos nativos `openclaw.plugin.json` e os manifestos de bundle compatíveis. +2. **Habilitação + validação** + O core decide se um plugin descoberto está habilitado, desabilitado, bloqueado ou + selecionado para um slot exclusivo, como memória. 3. **Carregamento em runtime** - Plugins nativos do OpenClaw são carregados no processo via jiti e registram + Plugins nativos do OpenClaw são carregados in-process via jiti e registram capacidades em um registro central. Bundles compatíveis são normalizados em registros do registro sem importar código de runtime. -4. **Consumo de superfícies** - O restante do OpenClaw lê o registro para expor ferramentas, canais, - configuração de provedores, hooks, rotas HTTP, comandos da CLI e serviços. +4. **Consumo da superfície** + O restante do OpenClaw lê o registro para expor ferramentas, canais, configuração + de provedor, hooks, rotas HTTP, comandos da CLI e serviços. -Especificamente para a CLI de plugins, a descoberta do comando raiz é dividida -em duas fases: +Especificamente para a CLI de plugins, a descoberta do comando raiz é dividida em duas fases: -- metadados em tempo de parsing vêm de `registerCli(..., { descriptors: [...] })` +- os metadados em tempo de parsing vêm de `registerCli(..., { descriptors: [...] })` - o módulo real da CLI do plugin pode continuar lazy e registrar na primeira invocação -Isso mantém o código da CLI pertencente ao plugin dentro do próprio plugin, -enquanto ainda permite que o OpenClaw reserve nomes de comando raiz antes do parsing. +Isso mantém o código da CLI pertencente ao plugin dentro do próprio plugin, ao mesmo tempo +que permite ao OpenClaw reservar nomes de comando raiz antes do parsing. O limite de design importante: -- descoberta + validação de configuração devem funcionar a partir de - **metadados de manifesto/schema** sem executar código do plugin +- descoberta + validação de configuração devem funcionar a partir de **metadados de manifesto/esquema** + sem executar código do plugin - o comportamento nativo em runtime vem do caminho `register(api)` do módulo do plugin -Essa divisão permite que o OpenClaw valide configuração, explique plugins -ausentes/desativados e construa dicas de UI/schema antes que o runtime completo -esteja ativo. +Essa separação permite que o OpenClaw valide configuração, explique plugins +ausentes/desabilitados e construa dicas de UI/esquema antes que o runtime completo esteja ativo. -### Plugins de canal e a ferramenta compartilhada de mensagem +### Plugins de canal e a ferramenta compartilhada de mensagens -Plugins de canal não precisam registrar uma ferramenta separada de -enviar/editar/reagir para ações normais de chat. O OpenClaw mantém uma única -ferramenta compartilhada `message` no núcleo, e os plugins de canal controlam a -descoberta e execução específicas do canal por trás dela. +Plugins de canal não precisam registrar uma ferramenta separada de enviar/editar/reagir para +ações normais de chat. O OpenClaw mantém uma única ferramenta `message` compartilhada no core, +e os plugins de canal são responsáveis pela descoberta e execução específicas do canal por trás dela. O limite atual é: -- o núcleo controla o host da ferramenta compartilhada `message`, o wiring de - prompt, a contabilidade de sessão/thread e o despacho de execução -- plugins de canal controlam descoberta de ações com escopo, descoberta de - capacidades e quaisquer fragmentos de schema específicos do canal -- plugins de canal controlam a gramática de conversa da sessão específica do - provedor, como ids de conversa codificam ids de thread ou herdam de - conversas pai -- plugins de canal executam a ação final por meio do seu adaptador de ação +- o core é responsável pelo host da ferramenta `message` compartilhada, pela integração com prompts, pelo + controle de sessão/thread e pelo despacho de execução +- plugins de canal são responsáveis pela descoberta de ações com escopo, descoberta de + capacidades e quaisquer fragmentos de esquema específicos do canal +- plugins de canal são responsáveis pela gramática de conversação de sessão específica do provedor, como + ids de conversa codificam ids de thread ou herdam de conversas pai +- plugins de canal executam a ação final por meio de seu adaptador de ações Para plugins de canal, a superfície do SDK é -`ChannelMessageActionAdapter.describeMessageTool(...)`. Essa chamada unificada -de descoberta permite que um plugin retorne suas ações visíveis, capacidades e -contribuições de schema juntas, para que essas partes não se desviem entre si. +`ChannelMessageActionAdapter.describeMessageTool(...)`. Essa chamada unificada de descoberta +permite que um plugin retorne suas ações visíveis, capacidades e contribuições de esquema em +conjunto, para que essas partes não se desalinhem. -O núcleo passa o escopo de runtime para essa etapa de descoberta. Campos -importantes incluem: +O core passa o escopo de runtime para essa etapa de descoberta. Campos importantes incluem: - `accountId` - `currentChannelId` @@ -202,138 +191,123 @@ importantes incluem: - `agentId` - `requesterSenderId` de entrada confiável -Isso importa para plugins sensíveis ao contexto. Um canal pode ocultar ou expor +Isso é importante para plugins sensíveis ao contexto. Um canal pode ocultar ou expor ações de mensagem com base na conta ativa, sala/thread/mensagem atual ou -identidade confiável de quem solicitou, sem codificar ramificações específicas -de canal na ferramenta `message` do núcleo. +identidade confiável do solicitante, sem codificar ramificações específicas do canal +na ferramenta `message` do core. -É por isso que mudanças de roteamento do embedded-runner continuam sendo -trabalho de plugin: o runner é responsável por encaminhar a identidade atual do -chat/sessão para o limite de descoberta do plugin, para que a ferramenta -compartilhada `message` exponha a superfície certa, controlada pelo canal, para -o turno atual. +É por isso que mudanças de roteamento do embedded-runner ainda são trabalho do plugin: o runner é +responsável por encaminhar a identidade atual de chat/sessão para o limite de descoberta do plugin, para que a +ferramenta `message` compartilhada exponha a superfície correta, pertencente ao canal, +para o turno atual. -Para helpers de execução controlados pelo canal, plugins integrados devem manter -o runtime de execução dentro dos seus próprios módulos de extensão. O núcleo não -controla mais os runtimes de ação de mensagem do Discord, Slack, Telegram ou -WhatsApp em `src/agents/tools`. Nós não publicamos subcaminhos separados -`plugin-sdk/*-action-runtime`, e plugins integrados devem importar seu próprio -código de runtime local diretamente de seus módulos controlados pela extensão. +Para auxiliares de execução pertencentes ao canal, plugins embutidos devem manter o runtime +de execução dentro de seus próprios módulos de extensão. O core não é mais responsável pelos +runtimes de ação de mensagem de Discord, Slack, Telegram ou WhatsApp em `src/agents/tools`. +Não publicamos subcaminhos separados `plugin-sdk/*-action-runtime`, e plugins embutidos +devem importar seu próprio código de runtime local diretamente de seus +módulos pertencentes à extensão. -O mesmo limite se aplica a seams do SDK nomeadas por provedor em geral: o -núcleo não deve importar barrels convenientes específicos de canal para Slack, -Discord, Signal, WhatsApp ou extensões semelhantes. Se o núcleo precisar de um -comportamento, ele deve consumir o barrel `api.ts` / `runtime-api.ts` do próprio -plugin integrado ou promover a necessidade para uma capacidade genérica e -estreita no SDK compartilhado. +O mesmo limite se aplica, em geral, a seams do SDK nomeadas por provedor: o core não +deve importar barrels de conveniência específicos de canal para Slack, Discord, Signal, +WhatsApp ou extensões semelhantes. Se o core precisar de um comportamento, deve consumir o +próprio barrel `api.ts` / `runtime-api.ts` do plugin embutido ou promover a necessidade +para uma capacidade genérica e específica no SDK compartilhado. Especificamente para enquetes, há dois caminhos de execução: -- `outbound.sendPoll` é a linha de base compartilhada para canais que se - encaixam no modelo comum de enquete -- `actions.handleAction("poll")` é o caminho preferido para semântica de - enquete específica de canal ou parâmetros extras de enquete +- `outbound.sendPoll` é a linha de base compartilhada para canais que se encaixam no modelo + comum de enquetes +- `actions.handleAction("poll")` é o caminho preferido para semânticas de enquete + específicas do canal ou parâmetros extras de enquete -Agora o núcleo adia o parsing compartilhado de enquete até que o despacho de -enquete do plugin recuse a ação, para que handlers de enquete controlados por -plugins possam aceitar campos de enquete específicos do canal sem serem -bloqueados primeiro pelo parser genérico de enquetes. +Agora o core adia o parsing compartilhado de enquetes até que o despacho de enquete do plugin +recuse a ação, para que tratadores de enquete pertencentes ao plugin possam aceitar +campos de enquete específicos do canal sem serem bloqueados primeiro pelo parser genérico de enquetes. -Veja [Pipeline de carregamento](#load-pipeline) para a sequência completa de inicialização. +Consulte [Pipeline de carregamento](#load-pipeline) para a sequência completa de inicialização. ## Modelo de propriedade de capacidades -O OpenClaw trata um plugin nativo como o limite de propriedade para uma -**empresa** ou uma **funcionalidade**, não como um conjunto de integrações sem -relação. +O OpenClaw trata um plugin nativo como o limite de propriedade de uma **empresa** ou um +**recurso**, não como uma coleção de integrações sem relação. Isso significa: -- um plugin de empresa normalmente deve controlar todas as superfícies do - OpenClaw voltadas para aquela empresa -- um plugin de funcionalidade normalmente deve controlar toda a superfície da - funcionalidade que ele introduz -- canais devem consumir capacidades compartilhadas do núcleo em vez de - reimplementar comportamento de provedor de forma ad hoc +- um plugin de empresa normalmente deve ser responsável por todas as superfícies do OpenClaw voltadas + para essa empresa +- um plugin de recurso normalmente deve ser responsável pela superfície completa do recurso que introduz +- canais devem consumir capacidades compartilhadas do core em vez de reimplementar comportamento + de provedor de forma ad hoc Exemplos: -- o plugin integrado `openai` controla o comportamento de provedor de modelos da - OpenAI e também o comportamento OpenAI de voz + voz em tempo real + - entendimento de mídia + geração de imagem -- o plugin integrado `elevenlabs` controla o comportamento de voz da ElevenLabs -- o plugin integrado `microsoft` controla o comportamento de voz da Microsoft -- o plugin integrado `google` controla o comportamento de provedor de modelos do - Google mais o comportamento do Google de entendimento de mídia + geração de - imagem + pesquisa na web -- o plugin integrado `firecrawl` controla o comportamento de busca web do Firecrawl -- os plugins integrados `minimax`, `mistral`, `moonshot` e `zai` controlam seus - backends de entendimento de mídia -- o plugin `voice-call` é um plugin de funcionalidade: ele controla transporte - de chamada, ferramentas, CLI, rotas e a ponte de media-stream do Twilio, mas - consome capacidades compartilhadas de voz + transcrição em tempo real + voz - em tempo real em vez de importar plugins de fornecedores diretamente +- o plugin embutido `openai` é responsável pelo comportamento de provedor de modelos da OpenAI e pelo comportamento de + fala + voz em tempo real + compreensão de mídia + geração de imagens da OpenAI +- o plugin embutido `elevenlabs` é responsável pelo comportamento de fala da ElevenLabs +- o plugin embutido `microsoft` é responsável pelo comportamento de fala da Microsoft +- o plugin embutido `google` é responsável pelo comportamento de provedor de modelos do Google, além do comportamento de + compreensão de mídia + geração de imagens + pesquisa na web do Google +- o plugin embutido `firecrawl` é responsável pelo comportamento de busca na web do Firecrawl +- os plugins embutidos `minimax`, `mistral`, `moonshot` e `zai` são responsáveis por seus + backends de compreensão de mídia +- o plugin `voice-call` é um plugin de recurso: ele é responsável por transporte de chamadas, ferramentas, + CLI, rotas e ponte de fluxo de mídia do Twilio, mas consome capacidades compartilhadas de fala + mais transcrição em tempo real e voz em tempo real, em vez de importar plugins de fornecedor diretamente O estado final pretendido é: -- OpenAI vive em um único plugin mesmo se abranger modelos de texto, voz, - imagens e vídeo no futuro -- outro fornecedor pode fazer o mesmo para sua própria área de superfície -- canais não se importam com qual plugin de fornecedor controla o provedor; eles - consomem o contrato de capacidade compartilhada exposto pelo núcleo +- A OpenAI fica em um único plugin, mesmo que abranja modelos de texto, fala, imagens e + vídeo no futuro +- outro fornecedor pode fazer o mesmo para sua própria área de atuação +- canais não se importam com qual plugin de fornecedor é responsável pelo provedor; eles consomem o + contrato de capacidade compartilhada exposto pelo core Esta é a distinção principal: - **plugin** = limite de propriedade -- **capacidade** = contrato do núcleo que múltiplos plugins podem implementar ou consumir +- **capacidade** = contrato do core que vários plugins podem implementar ou consumir -Portanto, se o OpenClaw adicionar um novo domínio como vídeo, a primeira -pergunta não é "qual provedor deve codificar o tratamento de vídeo?" A primeira -pergunta é "qual é o contrato de capacidade central de vídeo?" Quando esse -contrato existir, plugins de fornecedores poderão se registrar nele e plugins -de canal/funcionalidade poderão consumi-lo. +Portanto, se o OpenClaw adicionar um novo domínio, como vídeo, a primeira pergunta não é +“qual provedor deve codificar o tratamento de vídeo?” A primeira pergunta é “qual é +o contrato de capacidade de vídeo do core?” Quando esse contrato existir, plugins de fornecedor +poderão se registrar nele, e plugins de canal/recurso poderão consumi-lo. Se a capacidade ainda não existir, o movimento correto normalmente é: -1. definir a capacidade ausente no núcleo -2. expô-la pela API/runtime de plugins de forma tipada -3. conectar canais/funcionalidades a essa capacidade -4. deixar que plugins de fornecedores registrem implementações +1. definir a capacidade ausente no core +2. expô-la por meio da API/runtime de plugins de forma tipada +3. conectar canais/recursos a essa capacidade +4. deixar que plugins de fornecedor registrem implementações -Isso mantém a propriedade explícita ao mesmo tempo que evita comportamento do -núcleo dependente de um único fornecedor ou de um caminho de código pontual e -específico de plugin. +Isso mantém a propriedade explícita e evita comportamentos no core que dependam de um +único fornecedor ou de um caminho de código específico de um plugin isolado. ### Camadas de capacidade Use este modelo mental ao decidir onde o código deve ficar: -- **camada de capacidade do núcleo**: orquestração compartilhada, política, - fallback, regras de mesclagem de configuração, semântica de entrega e - contratos tipados -- **camada de plugin do fornecedor**: APIs específicas do fornecedor, - autenticação, catálogos de modelos, síntese de voz, geração de imagem, - futuros backends de vídeo, endpoints de uso -- **camada de plugin de canal/funcionalidade**: integração com - Slack/Discord/voice-call/etc. que consome capacidades do núcleo e as apresenta - em uma superfície +- **camada de capacidade do core**: orquestração compartilhada, política, fallback, regras + de mesclagem de configuração, semântica de entrega e contratos tipados +- **camada de plugin de fornecedor**: APIs específicas do fornecedor, autenticação, catálogos de modelos, síntese + de fala, geração de imagens, futuros backends de vídeo, endpoints de uso +- **camada de plugin de canal/recurso**: integração com Slack/Discord/voice-call/etc. + que consome capacidades do core e as apresenta em uma superfície -Por exemplo, TTS segue este formato: +Por exemplo, TTS segue esta forma: -- o núcleo controla a política de TTS no momento da resposta, ordem de fallback, - preferências e entrega por canal -- `openai`, `elevenlabs` e `microsoft` controlam implementações de síntese -- `voice-call` consome o helper de runtime de TTS de telefonia +- o core é responsável pela política de TTS no momento da resposta, ordem de fallback, preferências e entrega por canal +- `openai`, `elevenlabs` e `microsoft` são responsáveis pelas implementações de síntese +- `voice-call` consome o auxiliar de runtime de TTS para telefonia Esse mesmo padrão deve ser preferido para capacidades futuras. ### Exemplo de plugin de empresa com múltiplas capacidades -Um plugin de empresa deve parecer coeso por fora. Se o OpenClaw tiver contratos -compartilhados para modelos, voz, transcrição em tempo real, voz em tempo real, -entendimento de mídia, geração de imagem, geração de vídeo, busca web e -pesquisa na web, um fornecedor pode controlar todas as suas superfícies em um -único lugar: +Um plugin de empresa deve parecer coeso por fora. Se o OpenClaw tiver contratos compartilhados +para modelos, fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, +geração de imagens, geração de vídeo, busca na web e pesquisa na web, +um fornecedor pode ser responsável por todas as suas superfícies em um só lugar: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -348,12 +322,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // hooks de auth/catálogo de modelos/runtime + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // configuração de voz do fornecedor — implemente diretamente a interface SpeechProviderPlugin + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -378,7 +352,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // lógica de credencial + fetch + // credential + fetch logic }), ); }, @@ -387,67 +361,64 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -O que importa não são os nomes exatos dos helpers. O formato é o que importa: +O que importa não é o nome exato dos auxiliares. A forma é o que importa: -- um plugin controla a superfície do fornecedor -- o núcleo ainda controla os contratos de capacidade -- canais e plugins de funcionalidade consomem helpers `api.runtime.*`, não código do fornecedor -- testes de contrato podem verificar que o plugin registrou as capacidades que - afirma controlar +- um único plugin é responsável pela superfície do fornecedor +- o core continua responsável pelos contratos de capacidade +- plugins de canal e de recurso consomem auxiliares `api.runtime.*`, não código do fornecedor +- testes de contrato podem afirmar que o plugin registrou as capacidades das quais + afirma ser responsável -### Exemplo de capacidade: entendimento de vídeo +### Exemplo de capacidade: compreensão de vídeo -O OpenClaw já trata entendimento de imagem/áudio/vídeo como uma única +O OpenClaw já trata compreensão de imagem/áudio/vídeo como uma única capacidade compartilhada. O mesmo modelo de propriedade se aplica aqui: -1. o núcleo define o contrato de media-understanding -2. plugins de fornecedores registram `describeImage`, `transcribeAudio` e +1. o core define o contrato de compreensão de mídia +2. plugins de fornecedor registram `describeImage`, `transcribeAudio` e `describeVideo`, conforme aplicável -3. canais e plugins de funcionalidade consomem o comportamento compartilhado do - núcleo em vez de se conectar diretamente ao código do fornecedor +3. plugins de canal e de recurso consomem o comportamento compartilhado do core em vez de + se conectarem diretamente ao código do fornecedor -Isso evita embutir no núcleo as suposições de vídeo de um provedor específico. -O plugin controla a superfície do fornecedor; o núcleo controla o contrato de -capacidade e o comportamento de fallback. +Isso evita incorporar no core as suposições de vídeo de um único provedor. O plugin é responsável +pela superfície do fornecedor; o core é responsável pelo contrato de capacidade e pelo comportamento de fallback. -A geração de vídeo já usa essa mesma sequência: o núcleo controla o contrato -tipado de capacidade e o helper de runtime, e plugins de fornecedores registram +A geração de vídeo já usa essa mesma sequência: o core é responsável pelo contrato tipado de +capacidade e pelo auxiliar de runtime, e plugins de fornecedor registram implementações `api.registerVideoGenerationProvider(...)` nela. -Precisa de uma checklist concreta de rollout? Veja -[Capability Cookbook](/pt-BR/plugins/architecture). +Precisa de um checklist concreto de rollout? Consulte +[Livro de receitas de capacidades](/pt-BR/plugins/architecture). ## Contratos e aplicação A superfície da API de plugins é intencionalmente tipada e centralizada em -`OpenClawPluginApi`. Esse contrato define os pontos de registro suportados e os -helpers de runtime nos quais um plugin pode se apoiar. +`OpenClawPluginApi`. Esse contrato define os pontos de registro compatíveis e +os auxiliares de runtime nos quais um plugin pode confiar. Por que isso importa: - autores de plugins têm um padrão interno estável -- o núcleo pode rejeitar propriedade duplicada, como dois plugins registrando o - mesmo id de provedor -- a inicialização pode expor diagnósticos acionáveis para registros malformados -- testes de contrato podem aplicar propriedade de plugins integrados e impedir - desvios silenciosos +- o core pode rejeitar propriedade duplicada, como dois plugins registrando o mesmo + id de provedor +- a inicialização pode exibir diagnósticos acionáveis para registros malformados +- testes de contrato podem aplicar a propriedade de plugins embutidos e evitar desvios silenciosos Há duas camadas de aplicação: 1. **aplicação de registro em runtime** - O registro de plugins valida registros à medida que plugins são carregados. - Exemplos: ids duplicados de provedor, ids duplicados de provedor de voz e - registros malformados produzem diagnósticos de plugin em vez de comportamento - indefinido. + O registro de plugins valida os registros à medida que os plugins são carregados. Exemplos: + ids de provedor duplicados, ids de provedor de fala duplicados e registros + malformados produzem diagnósticos de plugin em vez de comportamento indefinido. 2. **testes de contrato** - Plugins integrados são capturados em registros de contrato durante execuções - de teste para que o OpenClaw possa afirmar a propriedade explicitamente. - Hoje isso é usado para provedores de modelos, provedores de voz, provedores - de pesquisa na web e propriedade de registro integrado. + Plugins embutidos são capturados em registros de contrato durante as execuções de teste para que o + OpenClaw possa afirmar explicitamente a propriedade. Hoje isso é usado para + provedores de modelos, provedores de fala, provedores de pesquisa na web e propriedade + de registro de plugins embutidos. -O efeito prático é que o OpenClaw sabe, desde o início, qual plugin controla -qual superfície. Isso permite que núcleo e canais componham perfeitamente, -porque a propriedade é declarada, tipada e testável em vez de implícita. +O efeito prático é que o OpenClaw sabe, antecipadamente, qual plugin é responsável por qual +superfície. Isso permite que o core e os canais componham sem atritos, porque a propriedade é +declarada, tipada e testável, em vez de implícita. ### O que pertence a um contrato @@ -456,165 +427,163 @@ Bons contratos de plugin são: - tipados - pequenos - específicos de capacidade -- controlados pelo núcleo -- reutilizáveis por múltiplos plugins -- consumíveis por canais/funcionalidades sem conhecimento do fornecedor +- pertencentes ao core +- reutilizáveis por vários plugins +- consumíveis por canais/recursos sem conhecimento do fornecedor -Maus contratos de plugin são: +Contratos ruins de plugin são: -- política específica de fornecedor escondida no núcleo -- válvulas de escape pontuais de plugin que contornam o registro +- política específica de fornecedor escondida no core +- rotas de escape pontuais de plugin que contornam o registro - código de canal acessando diretamente uma implementação de fornecedor -- objetos de runtime ad hoc que não fazem parte de `OpenClawPluginApi` nem de +- objetos ad hoc de runtime que não fazem parte de `OpenClawPluginApi` nem de `api.runtime` -Em caso de dúvida, eleve o nível de abstração: defina primeiro a capacidade e, -depois, deixe os plugins se conectarem a ela. +Em caso de dúvida, aumente o nível de abstração: defina primeiro a capacidade e +depois deixe os plugins se conectarem a ela. ## Modelo de execução -Plugins nativos do OpenClaw são executados **no processo** com o Gateway. Eles -não são isolados em sandbox. Um plugin nativo carregado tem o mesmo limite de -confiança em nível de processo que o código do núcleo. +Plugins nativos do OpenClaw são executados **in-process** com o Gateway. Eles não +são isolados em sandbox. Um plugin nativo carregado tem o mesmo limite de confiança +no nível de processo que o código do core. Implicações: -- um plugin nativo pode registrar ferramentas, handlers de rede, hooks e serviços -- um bug em um plugin nativo pode travar ou desestabilizar o gateway -- um plugin nativo malicioso equivale à execução arbitrária de código dentro do +- um plugin nativo pode registrar ferramentas, manipuladores de rede, hooks e serviços +- um bug em um plugin nativo pode derrubar ou desestabilizar o gateway +- um plugin nativo malicioso equivale a execução arbitrária de código dentro do processo do OpenClaw -Bundles compatíveis são mais seguros por padrão porque o OpenClaw atualmente os -trata como pacotes de metadados/conteúdo. Nas versões atuais, isso significa -principalmente Skills integradas. +Bundles compatíveis são mais seguros por padrão, porque o OpenClaw atualmente os trata +como pacotes de metadados/conteúdo. Nas versões atuais, isso significa principalmente +Skills empacotadas. -Use allowlists e caminhos explícitos de instalação/carregamento para plugins -não integrados. Trate plugins do workspace como código de tempo de -desenvolvimento, não como padrões de produção. +Use listas de permissão e caminhos explícitos de instalação/carregamento para plugins não empacotados. +Trate plugins de workspace como código de tempo de desenvolvimento, não como padrões de produção. -Para nomes de pacotes de workspace integrados, mantenha o id do plugin ancorado -no nome npm: `@openclaw/` por padrão, ou um sufixo tipado aprovado, como +Para nomes de pacotes de workspace embutidos, mantenha o id do plugin ancorado no nome npm: +`@openclaw/` por padrão, ou um sufixo tipado aprovado, como `-provider`, `-plugin`, `-speech`, `-sandbox` ou `-media-understanding`, quando -o pacote expuser intencionalmente um papel de plugin mais restrito. +o pacote expõe intencionalmente uma função de plugin mais restrita. Observação importante sobre confiança: - `plugins.allow` confia em **ids de plugin**, não na procedência da origem. -- Um plugin de workspace com o mesmo id de um plugin integrado intencionalmente - sombreia a cópia integrada quando esse plugin de workspace está - ativado/permitido na allowlist. +- Um plugin de workspace com o mesmo id de um plugin embutido intencionalmente sobrepõe + a cópia embutida quando esse plugin de workspace está habilitado/na lista de permissão. - Isso é normal e útil para desenvolvimento local, testes de patch e hotfixes. ## Limite de exportação O OpenClaw exporta capacidades, não conveniências de implementação. -Mantenha o registro de capacidades público. Remova exports helper fora de contrato: +Mantenha o registro de capacidades público. Remova exportações auxiliares fora do contrato: -- subcaminhos helper específicos de plugins integrados -- subcaminhos de plumbing de runtime não destinados a API pública -- helpers convenientes específicos de fornecedor -- helpers de setup/onboarding que são detalhes de implementação +- subcaminhos específicos de auxiliares de plugins embutidos +- subcaminhos de infraestrutura de runtime que não são destinados a ser API pública +- auxiliares de conveniência específicos de fornecedor +- auxiliares de configuração/onboarding que são detalhes de implementação -Alguns subcaminhos helper de plugins integrados ainda permanecem no mapa -gerado de exports do SDK por compatibilidade e manutenção de plugins integrados. -Exemplos atuais incluem `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, -`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e vários seams `plugin-sdk/matrix*`. -Trate-os como exports reservados de detalhe de implementação, não como o padrão -recomendado de SDK para novos plugins externos. +Alguns subcaminhos auxiliares de plugins embutidos ainda permanecem no mapa gerado de exportação do SDK +por compatibilidade e manutenção de plugins embutidos. Exemplos atuais incluem +`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +`plugin-sdk/zalo-setup` e vários seams `plugin-sdk/matrix*`. Trate-os como +exportações reservadas de detalhe de implementação, não como o padrão recomendado de SDK para +novos plugins de terceiros. ## Pipeline de carregamento Na inicialização, o OpenClaw faz aproximadamente isto: -1. descobre raízes de plugins candidatas +1. descobre raízes candidatas de plugins 2. lê manifestos nativos ou de bundles compatíveis e metadados de pacote 3. rejeita candidatos inseguros -4. normaliza a configuração do plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +4. normaliza a configuração de plugins (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. decide a ativação de cada candidato -6. carrega módulos nativos ativados via jiti -7. chama hooks nativos `register(api)` (ou `activate(api)` — um alias legado) e coleta registros no registro de plugins -8. expõe o registro para superfícies de comandos/runtime +5. decide a habilitação para cada candidato +6. carrega módulos nativos habilitados via jiti +7. chama os hooks nativos `register(api)` (ou `activate(api)` — um alias legado) e coleta os registros no registro de plugins +8. expõe o registro para comandos/superfícies de runtime -`activate` é um alias legado para `register` — o loader resolve o que estiver -presente (`def.register ?? def.activate`) e o chama no mesmo ponto. Todos os -plugins integrados usam `register`; prefira `register` para novos plugins. +`activate` é um alias legado para `register` — o carregador resolve o que estiver presente (`def.register ?? def.activate`) e o chama no mesmo ponto. Todos os plugins embutidos usam `register`; prefira `register` para novos plugins. -Os gates de segurança acontecem **antes** da execução em runtime. Candidatos são -bloqueados quando a entrada escapa da raiz do plugin, o caminho é gravável por -qualquer usuário, ou a propriedade do caminho parece suspeita para plugins não -integrados. +As barreiras de segurança acontecem **antes** da execução em runtime. Candidatos são bloqueados +quando a entrada escapa da raiz do plugin, o caminho tem permissão de escrita para todos, ou a +propriedade do caminho parece suspeita para plugins não embutidos. -### Comportamento orientado a manifesto +### Comportamento manifest-first O manifesto é a fonte de verdade do plano de controle. O OpenClaw o usa para: - identificar o plugin -- descobrir canais/Skills/schema de configuração declarados ou capacidades de bundle +- descobrir canais/Skills/esquema de configuração declarados ou capacidades de bundle - validar `plugins.entries..config` - complementar rótulos/placeholders da Control UI - mostrar metadados de instalação/catálogo +- preservar descritores baratos de ativação e configuração sem carregar o runtime do plugin -Para plugins nativos, o módulo de runtime é a parte do plano de dados. Ele -registra comportamento real, como hooks, ferramentas, comandos ou fluxos de -provedor. +Para plugins nativos, o módulo de runtime é a parte do plano de dados. Ele registra +o comportamento real, como hooks, ferramentas, comandos ou fluxos de provedor. -### O que o loader armazena em cache +Blocos opcionais `activation` e `setup` do manifesto permanecem no plano de controle. +Eles são descritores somente de metadados para planejamento de ativação e descoberta de configuração; +não substituem registro em runtime, `register(...)` nem `setupEntry`. -O OpenClaw mantém caches curtos em processo para: +### O que o carregador mantém em cache + +O OpenClaw mantém caches curtos in-process para: - resultados de descoberta - dados do registro de manifestos - registros de plugins carregados -Esses caches reduzem inicializações em rajada e a sobrecarga de comandos -repetidos. É seguro pensar neles como caches de desempenho de curta duração, -não como persistência. +Esses caches reduzem inicializações em rajadas e a sobrecarga de comandos repetidos. É seguro +pensar neles como caches de desempenho de curta duração, não como persistência. Observação de desempenho: - Defina `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` ou - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` para desativar esses caches. + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` para desabilitar esses caches. - Ajuste as janelas de cache com `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` e `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Modelo de registro -Plugins carregados não alteram diretamente globais aleatórias do núcleo. Eles -se registram em um registro central de plugins. +Plugins carregados não mutam diretamente globais aleatórios do core. Eles se registram em um +registro central de plugins. O registro acompanha: -- registros de plugins (identidade, origem, procedência, status, diagnósticos) +- registros de plugin (identidade, origem, procedência, status, diagnósticos) - ferramentas - hooks legados e hooks tipados - canais - provedores -- handlers RPC do gateway +- manipuladores de RPC do gateway - rotas HTTP - registradores da CLI - serviços em segundo plano -- comandos controlados por plugins +- comandos pertencentes ao plugin -Os recursos do núcleo então leem esse registro em vez de falar diretamente com -os módulos de plugin. Isso mantém o carregamento em uma única direção: +Recursos do core então leem esse registro em vez de falar diretamente com módulos de plugin. +Isso mantém o carregamento em um só sentido: - módulo do plugin -> registro no registro -- runtime do núcleo -> consumo do registro +- runtime do core -> consumo do registro -Essa separação importa para a manutenção. Ela significa que a maioria das -superfícies do núcleo só precisa de um ponto de integração: "ler o registro", -não "criar caso especial para cada módulo de plugin". +Essa separação é importante para a manutenção. Ela significa que a maioria das superfícies do core só +precisa de um ponto de integração: “ler o registro”, não “criar caso especial para cada +módulo de plugin”. -## Callbacks de vinculação de conversa +## Callbacks de associação de conversa -Plugins que vinculam uma conversa podem reagir quando uma aprovação é resolvida. +Plugins que associam uma conversa podem reagir quando uma aprovação é resolvida. -Use `api.onConversationBindingResolved(...)` para receber um callback depois que -uma solicitação de vinculação é aprovada ou negada: +Use `api.onConversationBindingResolved(...)` para receber um callback depois que uma solicitação de associação +for aprovada ou negada: ```ts export default { @@ -622,12 +591,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Agora existe uma vinculação para este plugin + conversa. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // A solicitação foi negada; limpe qualquer estado pendente local. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, @@ -638,23 +607,21 @@ Campos do payload do callback: - `status`: `"approved"` ou `"denied"` - `decision`: `"allow-once"`, `"allow-always"` ou `"deny"` -- `binding`: a vinculação resolvida para solicitações aprovadas +- `binding`: a associação resolvida para solicitações aprovadas - `request`: o resumo da solicitação original, dica de desanexação, id do remetente e metadados da conversa -Esse callback é apenas de notificação. Ele não altera quem tem permissão para -vincular uma conversa, e é executado depois que o tratamento de aprovação do -núcleo é concluído. +Esse callback é apenas de notificação. Ele não altera quem tem permissão para associar uma +conversa, e é executado depois que o tratamento de aprovação do core termina. -## Hooks de runtime de provedores +## Hooks de runtime de provedor -Plugins de provedor agora têm duas camadas: +Os plugins de provedor agora têm duas camadas: -- metadados de manifesto: `providerAuthEnvVars` para consulta barata de auth de - provedor via env antes do carregamento do runtime, `providerAuthAliases` para - variantes de provedor que compartilham auth, `channelEnvVars` para consulta - barata de env/setup de canal antes do carregamento do runtime, além de - `providerAuthChoices` para rótulos baratos de onboarding/escolha de auth e +- metadados do manifesto: `providerAuthEnvVars` para busca barata de autenticação do provedor por env + antes do carregamento do runtime, `providerAuthAliases` para variantes de provedor que compartilham + autenticação, `channelEnvVars` para busca barata de env/configuração de canal antes do carregamento do runtime, + além de `providerAuthChoices` para rótulos baratos de onboarding/escolha de autenticação e metadados de flags da CLI antes do carregamento do runtime - hooks em tempo de configuração: `catalog` / legado `discovery` mais `applyConfigDefaults` - hooks de runtime: `normalizeModelId`, `normalizeTransport`, @@ -677,93 +644,88 @@ Plugins de provedor agora têm duas camadas: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -O OpenClaw ainda controla o loop genérico do agente, failover, tratamento de -transcrições e política de ferramentas. Esses hooks são a superfície de -extensão para comportamento específico de provedor sem precisar de um transporte -de inferência inteiro personalizado. +O OpenClaw continua sendo responsável pelo loop genérico do agente, failover, tratamento de transcrições e +política de ferramentas. Esses hooks são a superfície de extensão para comportamento específico de provedor sem +precisar de um transporte de inferência totalmente personalizado. -Use o manifesto `providerAuthEnvVars` quando o provedor tiver credenciais -baseadas em env que caminhos genéricos de auth/status/seletor de modelo -precisem enxergar sem carregar o runtime do plugin. Use o manifesto -`providerAuthAliases` quando um id de provedor precisar reutilizar variáveis de -ambiente, perfis de auth, auth baseada em configuração e a opção de onboarding -de chave de API de outro id de provedor. Use o manifesto `providerAuthChoices` -quando superfícies de onboarding/escolha de auth da CLI precisarem conhecer o id -de escolha do provedor, rótulos de grupo e wiring simples de auth com uma única -flag sem carregar o runtime do provedor. Mantenha o `envVars` do runtime de -provedor para dicas voltadas ao operador, como rótulos de onboarding ou vars de -setup de client-id/client-secret OAuth. +Use o manifesto `providerAuthEnvVars` quando o provedor tiver credenciais baseadas em env +que caminhos genéricos de autenticação/status/seletor de modelo devam enxergar sem carregar o runtime do plugin. +Use o manifesto `providerAuthAliases` quando um id de provedor precisar reutilizar +as variáveis de ambiente, perfis de autenticação, autenticação baseada em configuração e a opção de onboarding +de chave de API de outro id de provedor. Use o manifesto `providerAuthChoices` quando superfícies da CLI +de onboarding/escolha de autenticação precisarem conhecer o id de escolha do provedor, rótulos de grupo e +ligação simples de autenticação com uma única flag sem carregar o runtime do provedor. Mantenha o `envVars` +do runtime do provedor para dicas voltadas ao operador, como rótulos de onboarding ou variáveis de +configuração de client-id/client-secret de OAuth. -Use o manifesto `channelEnvVars` quando um canal tiver auth ou setup orientado a -env que fallback genérico de shell-env, verificações de config/status ou prompts -de setup precisem enxergar sem carregar o runtime do canal. +Use o manifesto `channelEnvVars` quando um canal tiver autenticação ou configuração orientada por env que +fallback genérico para env do shell, verificações de config/status ou prompts de configuração devam enxergar +sem carregar o runtime do canal. ### Ordem e uso dos hooks -Para plugins de modelo/provedor, o OpenClaw chama hooks nesta ordem aproximada. -A coluna "Quando usar" é o guia rápido de decisão. +Para plugins de modelo/provedor, o OpenClaw chama hooks aproximadamente nesta ordem. +A coluna “Quando usar” é o guia rápido de decisão. -| # | Hook | O que faz | Quando usar | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Publica configuração do provedor em `models.providers` durante a geração de `models.json` | O provedor controla um catálogo ou padrões de base URL | -| 2 | `applyConfigDefaults` | Aplica padrões globais de configuração controlados pelo provedor durante a materialização da configuração | Os padrões dependem do modo de auth, env ou semântica de família de modelos do provedor | -| -- | _(pesquisa de modelo integrada)_ | O OpenClaw primeiro tenta o caminho normal de registro/catálogo | _(não é um hook de plugin)_ | -| 3 | `normalizeModelId` | Normaliza aliases de model-id legados ou preview antes da pesquisa | O provedor controla a limpeza de aliases antes da resolução canônica do modelo | -| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` de família de provedores antes da montagem genérica do modelo | O provedor controla a limpeza de transporte para ids de provedores personalizados na mesma família de transporte | -| 5 | `normalizeConfig` | Normaliza `models.providers.` antes da resolução de runtime/provedor | O provedor precisa de limpeza de configuração que deve viver com o plugin; helpers integrados da família Google também dão suporte a entradas de configuração Google suportadas | -| 6 | `applyNativeStreamingUsageCompat` | Aplica reescritas de compatibilidade de uso de streaming nativo a provedores de configuração | O provedor precisa de correções de metadados de uso de streaming nativo orientadas por endpoint | -| 7 | `resolveConfigApiKey` | Resolve auth baseada em marcador de env para provedores de configuração antes do carregamento de auth em runtime | O provedor tem resolução de chave de API via marcador de env controlada pelo provedor; `amazon-bedrock` também tem aqui um resolvedor integrado de marcador AWS | -| 8 | `resolveSyntheticAuth` | Expõe auth local/self-hosted ou baseada em configuração sem persistir texto simples | O provedor pode operar com um marcador de credencial sintética/local | -| 9 | `resolveExternalAuthProfiles` | Sobrepõe perfis de auth externa controlados pelo provedor; o `persistence` padrão é `runtime-only` para credenciais controladas pela CLI/app | O provedor reutiliza credenciais externas de auth sem persistir tokens de refresh copiados | -| 10 | `shouldDeferSyntheticProfileAuth` | Rebaixa placeholders sintéticos armazenados atrás de auth baseada em env/configuração | O provedor armazena perfis placeholder sintéticos que não devem ter precedência | -| 11 | `resolveDynamicModel` | Fallback síncrono para model ids controlados pelo provedor que ainda não estão no registro local | O provedor aceita model ids arbitrários do upstream | -| 12 | `prepareDynamicModel` | Aquecimento assíncrono, então `resolveDynamicModel` executa novamente | O provedor precisa de metadados de rede antes de resolver ids desconhecidos | -| 13 | `normalizeResolvedModel` | Reescrita final antes que o embedded runner use o modelo resolvido | O provedor precisa de reescritas de transporte, mas ainda usa um transporte do núcleo | -| 14 | `contributeResolvedModelCompat` | Contribui flags de compatibilidade para modelos de fornecedor atrás de outro transporte compatível | O provedor reconhece seus próprios modelos em transportes proxy sem assumir o controle do provedor | -| 15 | `capabilities` | Metadados de transcrição/ferramentas controlados pelo provedor e usados pela lógica compartilhada do núcleo | O provedor precisa de peculiaridades de transcrição/família de provedor | -| 16 | `normalizeToolSchemas` | Normaliza schemas de ferramentas antes que o embedded runner os veja | O provedor precisa de limpeza de schema de família de transporte | -| 17 | `inspectToolSchemas` | Expõe diagnósticos de schema controlados pelo provedor após a normalização | O provedor quer avisos de palavras-chave sem ensinar regras específicas de provedor ao núcleo | -| 18 | `resolveReasoningOutputMode` | Seleciona contrato de saída de raciocínio nativo vs marcado | O provedor precisa de raciocínio marcado/saída final em vez de campos nativos | -| 19 | `prepareExtraParams` | Normalização de parâmetros de requisição antes dos wrappers genéricos de opções de stream | O provedor precisa de parâmetros de requisição padrão ou limpeza por provedor | -| 20 | `createStreamFn` | Substitui completamente o caminho normal de stream por um transporte personalizado | O provedor precisa de um protocolo de wire personalizado, não apenas de um wrapper | -| 21 | `wrapStreamFn` | Wrapper de stream depois que wrappers genéricos são aplicados | O provedor precisa de wrappers de compatibilidade de headers/corpo/modelo de requisição sem um transporte personalizado | -| 22 | `resolveTransportTurnState` | Anexa headers ou metadados nativos por turno de transporte | O provedor quer que transportes genéricos enviem identidade de turno nativa do provedor | -| 23 | `resolveWebSocketSessionPolicy` | Anexa headers nativos de WebSocket ou política de resfriamento de sessão | O provedor quer que transportes WS genéricos ajustem headers de sessão ou política de fallback | -| 24 | `formatApiKey` | Formatador de perfil de auth: o perfil armazenado vira a string de `apiKey` em runtime | O provedor armazena metadados extras de auth e precisa de um formato personalizado de token em runtime | -| 25 | `refreshOAuth` | Sobrescrita de refresh OAuth para endpoints personalizados de refresh ou política de falha no refresh | O provedor não se encaixa nos refreshers compartilhados de `pi-ai` | -| 26 | `buildAuthDoctorHint` | Dica de reparo anexada quando o refresh OAuth falha | O provedor precisa de orientação de reparo de auth controlada pelo provedor após falha de refresh | -| 27 | `matchesContextOverflowError` | Correspondência controlada pelo provedor para overflow de janela de contexto | O provedor tem erros brutos de overflow que heurísticas genéricas não capturam | -| 28 | `classifyFailoverReason` | Classificação do motivo de failover controlada pelo provedor | O provedor consegue mapear erros brutos de API/transporte para rate-limit/sobrecarga/etc. | -| 29 | `isCacheTtlEligible` | Política de cache de prompt para provedores proxy/backhaul | O provedor precisa de gating de TTL de cache específico de proxy | -| 30 | `buildMissingAuthMessage` | Substituição da mensagem genérica de recuperação por auth ausente | O provedor precisa de uma dica de recuperação para auth ausente específica do provedor | -| 31 | `suppressBuiltInModel` | Supressão de modelos upstream obsoletos mais dica opcional de erro voltada ao usuário | O provedor precisa ocultar linhas upstream obsoletas ou substituí-las por uma dica do fornecedor | -| 32 | `augmentModelCatalog` | Linhas sintéticas/finais de catálogo anexadas após a descoberta | O provedor precisa de linhas sintéticas de compatibilidade futura em `models list` e seletores | -| 33 | `isBinaryThinking` | Alternância de raciocínio ligado/desligado para provedores de binary-thinking | O provedor expõe apenas raciocínio binário ligado/desligado | -| 34 | `supportsXHighThinking` | Suporte a raciocínio `xhigh` para modelos selecionados | O provedor quer `xhigh` apenas em um subconjunto de modelos | -| 35 | `resolveDefaultThinkingLevel` | Nível padrão de `/think` para uma família específica de modelos | O provedor controla a política padrão de `/think` para uma família de modelos | -| 36 | `isModernModelRef` | Correspondência de modelo moderno para filtros de perfil live e seleção de smoke | O provedor controla a correspondência de modelos preferidos em live/smoke | -| 37 | `prepareRuntimeAuth` | Troca uma credencial configurada pelo token/chave real de runtime logo antes da inferência | O provedor precisa de uma troca de token ou credencial de requisição de curta duração | -| 38 | `resolveUsageAuth` | Resolve credenciais de uso/faturamento para `/usage` e superfícies de status relacionadas | O provedor precisa de parsing personalizado de token de uso/cota ou de uma credencial de uso diferente | -| 39 | `fetchUsageSnapshot` | Busca e normaliza snapshots de uso/cota específicos do provedor depois que a auth é resolvida | O provedor precisa de um endpoint de uso específico ou de um parser de payload | -| 40 | `createEmbeddingProvider` | Constrói um adaptador de embeddings controlado pelo provedor para memória/pesquisa | O comportamento de embedding de memória pertence ao plugin do provedor | -| 41 | `buildReplayPolicy` | Retorna uma política de replay que controla o tratamento da transcrição para o provedor | O provedor precisa de uma política personalizada de transcrição (por exemplo, remoção de blocos de raciocínio) | -| 42 | `sanitizeReplayHistory` | Reescreve o histórico de replay após a limpeza genérica da transcrição | O provedor precisa de reescritas de replay específicas além dos helpers compartilhados de compactação | -| 43 | `validateReplayTurns` | Validação final ou remodelagem de turnos de replay antes do embedded runner | O transporte do provedor precisa de validação mais rígida dos turnos após a sanitização genérica | -| 44 | `onModelSelected` | Executa efeitos colaterais controlados pelo provedor após a seleção do modelo | O provedor precisa de telemetria ou estado controlado pelo provedor quando um modelo se torna ativo | +| # | Hook | O que faz | Quando usar | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | `catalog` | Publica a configuração do provedor em `models.providers` durante a geração de `models.json` | O provedor é responsável por um catálogo ou por padrões de URL base | +| 2 | `applyConfigDefaults` | Aplica padrões globais de configuração pertencentes ao provedor durante a materialização da configuração | Os padrões dependem do modo de autenticação, env ou da semântica da família de modelos do provedor | +| -- | _(built-in model lookup)_ | O OpenClaw tenta primeiro o caminho normal de registro/catálogo | _(não é um hook de plugin)_ | +| 3 | `normalizeModelId` | Normaliza aliases legados ou de preview de id de modelo antes da busca | O provedor é responsável pela limpeza de aliases antes da resolução canônica do modelo | +| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` da família de provedores antes da montagem genérica do modelo | O provedor é responsável pela limpeza de transporte para ids de provedor personalizados na mesma família de transporte | +| 5 | `normalizeConfig` | Normaliza `models.providers.` antes da resolução de runtime/provedor | O provedor precisa de limpeza de configuração que deve ficar com o plugin; auxiliares empacotados da família Google também dão suporte a entradas de configuração Google compatíveis | +| 6 | `applyNativeStreamingUsageCompat` | Aplica reescritas de compatibilidade de uso de streaming nativo a provedores de configuração | O provedor precisa de correções de metadados de uso de streaming nativo orientadas por endpoint | +| 7 | `resolveConfigApiKey` | Resolve autenticação por marcador de env para provedores de configuração antes do carregamento da autenticação de runtime | O provedor tem resolução de chave de API por marcador de env pertencente ao provedor; `amazon-bedrock` também tem aqui um resolvedor embutido de marcador de env da AWS | +| 8 | `resolveSyntheticAuth` | Expõe autenticação local/self-hosted ou baseada em configuração sem persistir texto simples | O provedor pode operar com um marcador de credencial sintético/local | +| 9 | `resolveExternalAuthProfiles` | Sobrepõe perfis de autenticação externos pertencentes ao provedor; o `persistence` padrão é `runtime-only` para credenciais pertencentes à CLI/app | O provedor reutiliza credenciais de autenticação externas sem persistir refresh tokens copiados | +| 10 | `shouldDeferSyntheticProfileAuth` | Rebaixa placeholders sintéticos armazenados em perfis atrás de autenticação baseada em env/configuração | O provedor armazena perfis placeholder sintéticos que não devem ter precedência | +| 11 | `resolveDynamicModel` | Fallback síncrono para ids de modelo pertencentes ao provedor que ainda não estão no registro local | O provedor aceita ids de modelo arbitrários do upstream | +| 12 | `prepareDynamicModel` | Aquecimento assíncrono; depois `resolveDynamicModel` é executado novamente | O provedor precisa de metadados de rede antes de resolver ids desconhecidos | +| 13 | `normalizeResolvedModel` | Reescrita final antes que o embedded runner use o modelo resolvido | O provedor precisa de reescritas de transporte, mas ainda usa um transporte do core | +| 14 | `contributeResolvedModelCompat` | Contribui com flags de compatibilidade para modelos do fornecedor atrás de outro transporte compatível | O provedor reconhece seus próprios modelos em transportes proxy sem assumir o provedor | +| 15 | `capabilities` | Metadados de transcrição/ferramentas pertencentes ao provedor, usados pela lógica compartilhada do core | O provedor precisa de particularidades de transcrição/família de provedores | +| 16 | `normalizeToolSchemas` | Normaliza esquemas de ferramentas antes que o embedded runner os veja | O provedor precisa de limpeza de esquema da família de transporte | +| 17 | `inspectToolSchemas` | Expõe diagnósticos de esquema pertencentes ao provedor após a normalização | O provedor quer avisos de palavras-chave sem ensinar ao core regras específicas do provedor | +| 18 | `resolveReasoningOutputMode` | Seleciona contrato de saída de raciocínio nativo ou com tags | O provedor precisa de saída final/de raciocínio com tags em vez de campos nativos | +| 19 | `prepareExtraParams` | Normalização de parâmetros da solicitação antes dos wrappers genéricos de opções de stream | O provedor precisa de parâmetros padrão de solicitação ou limpeza de parâmetros por provedor | +| 20 | `createStreamFn` | Substitui completamente o caminho normal de stream por um transporte personalizado | O provedor precisa de um protocolo de transporte personalizado, não apenas de um wrapper | +| 21 | `wrapStreamFn` | Wrapper de stream depois que os wrappers genéricos são aplicados | O provedor precisa de wrappers de compatibilidade de headers/corpo/modelo da solicitação sem um transporte personalizado | +| 22 | `resolveTransportTurnState` | Anexa headers ou metadados nativos por turno ao transporte | O provedor quer que transportes genéricos enviem identidade de turno nativa do provedor | +| 23 | `resolveWebSocketSessionPolicy` | Anexa headers nativos de WebSocket ou política de resfriamento de sessão | O provedor quer que transportes WS genéricos ajustem headers de sessão ou política de fallback | +| 24 | `formatApiKey` | Formatador de perfil de autenticação: o perfil armazenado se torna a string `apiKey` de runtime | O provedor armazena metadados extras de autenticação e precisa de um formato personalizado de token de runtime | +| 25 | `refreshOAuth` | Sobrescrita de atualização de OAuth para endpoints personalizados de atualização ou política de falha na atualização | O provedor não se encaixa nos atualizadores compartilhados de `pi-ai` | +| 26 | `buildAuthDoctorHint` | Dica de reparo acrescentada quando a atualização de OAuth falha | O provedor precisa de orientação de reparo de autenticação pertencente ao provedor após falha na atualização | +| 27 | `matchesContextOverflowError` | Correspondência de overflow de janela de contexto pertencente ao provedor | O provedor tem erros brutos de overflow que heurísticas genéricas deixariam passar | +| 28 | `classifyFailoverReason` | Classificação de motivo de failover pertencente ao provedor | O provedor pode mapear erros brutos de API/transporte para rate limit/sobrecarga/etc. | +| 29 | `isCacheTtlEligible` | Política de cache de prompt para provedores proxy/backhaul | O provedor precisa de controle de TTL de cache específico para proxy | +| 30 | `buildMissingAuthMessage` | Substituição para a mensagem genérica de recuperação de autenticação ausente | O provedor precisa de uma dica de recuperação de autenticação ausente específica do provedor | +| 31 | `suppressBuiltInModel` | Supressão de modelo upstream obsoleto com dica de erro opcional voltada ao usuário | O provedor precisa ocultar linhas obsoletas do upstream ou substituí-las por uma dica do fornecedor | +| 32 | `augmentModelCatalog` | Linhas sintéticas/finais de catálogo acrescentadas após a descoberta | O provedor precisa de linhas sintéticas de compatibilidade futura em `models list` e seletores | +| 33 | `isBinaryThinking` | Alternância de raciocínio ligado/desligado para provedores com raciocínio binário | O provedor expõe apenas raciocínio binário ligado/desligado | +| 34 | `supportsXHighThinking` | Suporte a raciocínio `xhigh` para modelos selecionados | O provedor quer `xhigh` apenas em um subconjunto de modelos | +| 35 | `resolveDefaultThinkingLevel` | Nível padrão de `/think` para uma família específica de modelos | O provedor é responsável pela política padrão de `/think` para uma família de modelos | +| 36 | `isModernModelRef` | Correspondência de modelo moderno para filtros de perfil live e seleção de smoke | O provedor é responsável pela correspondência de modelo preferido para live/smoke | +| 37 | `prepareRuntimeAuth` | Troca uma credencial configurada pelo token/chave real de runtime pouco antes da inferência | O provedor precisa de uma troca de token ou de uma credencial de solicitação de curta duração | +| 38 | `resolveUsageAuth` | Resolve credenciais de uso/faturamento para `/usage` e superfícies relacionadas de status | O provedor precisa de parsing personalizado de token de uso/cota ou de uma credencial de uso diferente | +| 39 | `fetchUsageSnapshot` | Busca e normaliza snapshots de uso/cota específicos do provedor depois que a autenticação é resolvida | O provedor precisa de um endpoint de uso específico do provedor ou de um parser de payload | +| 40 | `createEmbeddingProvider` | Cria um adaptador de embeddings pertencente ao provedor para memória/pesquisa | O comportamento de embeddings de memória pertence ao plugin do provedor | +| 41 | `buildReplayPolicy` | Retorna uma política de replay que controla o tratamento de transcrição para o provedor | O provedor precisa de uma política personalizada de transcrição, por exemplo, remoção de blocos de raciocínio | +| 42 | `sanitizeReplayHistory` | Reescreve o histórico de replay após a limpeza genérica de transcrição | O provedor precisa de reescritas de replay específicas do provedor além dos auxiliares compartilhados de compactação | +| 43 | `validateReplayTurns` | Validação final ou remodelagem dos turnos de replay antes do embedded runner | O transporte do provedor precisa de validação mais rígida dos turnos após a sanitização genérica | +| 44 | `onModelSelected` | Executa efeitos colaterais pós-seleção pertencentes ao provedor | O provedor precisa de telemetria ou estado pertencente ao provedor quando um modelo se torna ativo | -`normalizeModelId`, `normalizeTransport` e `normalizeConfig` primeiro verificam -o plugin de provedor correspondente, depois percorrem outros plugins de provedor -capazes de hooks até que um deles realmente altere o model id ou -transport/config. Isso mantém funcionando shims de alias/compatibilidade de -provedor sem exigir que o chamador saiba qual plugin integrado controla a -reescrita. Se nenhum hook de provedor reescrever uma entrada de configuração -compatível da família Google, o normalizador de configuração integrado do Google -ainda aplicará essa limpeza de compatibilidade. +`normalizeModelId`, `normalizeTransport` e `normalizeConfig` primeiro verificam o +plugin de provedor correspondente e depois passam por outros plugins de provedor com suporte a hooks +até que um deles realmente altere o id do modelo ou o transporte/configuração. Isso mantém +funcionando os shims de alias/provedor compatível sem exigir que o chamador saiba qual +plugin embutido é responsável pela reescrita. Se nenhum hook de provedor reescrever uma entrada de +configuração compatível da família Google, o normalizador de configuração embutido do Google ainda aplicará +essa limpeza de compatibilidade. -Se o provedor precisar de um protocolo de wire totalmente personalizado ou de um -executor de requisição personalizado, essa é uma classe diferente de extensão. -Esses hooks servem para comportamento de provedor que ainda roda no loop normal -de inferência do OpenClaw. +Se o provedor precisar de um protocolo de transporte totalmente personalizado ou de um executor de requisição personalizado, +essa é uma classe diferente de extensão. Esses hooks são para comportamento de provedor +que ainda é executado no loop normal de inferência do OpenClaw. ### Exemplo de provedor @@ -819,131 +781,119 @@ api.registerProvider({ }); ``` -### Exemplos integrados +### Exemplos embutidos - Anthropic usa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - e `wrapStreamFn` porque controla compatibilidade futura do Claude 4.6, - dicas de família de provedor, orientação de reparo de auth, integração com - endpoint de uso, elegibilidade de cache de prompt, padrões de configuração - com reconhecimento de auth, política padrão/adaptativa de thinking do Claude - e modelagem de stream específica do Anthropic para headers beta, - `/fast` / `serviceTier` e `context1m`. -- Os helpers de stream específicos do Claude da Anthropic ficam por enquanto no - seam público `api.ts` / `contract-api.ts` do próprio plugin integrado. Essa - superfície de pacote exporta `wrapAnthropicProviderStream`, - `resolveAnthropicBetas`, `resolveAnthropicFastMode`, - `resolveAnthropicServiceTier` e builders de wrapper Anthropic de nível mais - baixo, em vez de ampliar o SDK genérico em torno das regras de header beta - de um único provedor. -- OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` e `capabilities` - mais `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef` - porque controla compatibilidade futura do GPT-5.4, a normalização direta - OpenAI de `openai-completions` -> `openai-responses`, dicas de auth - conscientes de Codex, supressão do Spark, linhas sintéticas da lista OpenAI e - política de thinking / modelo live do GPT-5; a família de stream - `openai-responses-defaults` controla os wrappers compartilhados nativos do - OpenAI Responses para headers de atribuição, - `/fast`/`serviceTier`, verbosidade de texto, pesquisa web nativa do Codex, - modelagem de payload compatível com reasoning e gerenciamento de contexto do Responses. -- OpenRouter usa `catalog` mais `resolveDynamicModel` e - `prepareDynamicModel` porque o provedor é pass-through e pode expor novos - model ids antes de o catálogo estático do OpenClaw ser atualizado; também usa - `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` para manter fora do - núcleo headers de requisição, metadados de roteamento, patches de reasoning e - política de cache de prompt específicos do provedor. Sua política de replay - vem da família `passthrough-gemini`, enquanto a família de stream - `openrouter-thinking` controla a injeção de reasoning em proxy e os skips de - modelos não suportados / `auto`. + e `wrapStreamFn` porque é responsável por forward-compat do Claude 4.6, + dicas da família de provedores, orientação de reparo de autenticação, integração + com endpoint de uso, elegibilidade de cache de prompt, padrões de configuração com reconhecimento + de autenticação, política padrão/adaptativa de pensamento do Claude e modelagem de stream + específica da Anthropic para headers beta, `/fast` / `serviceTier` e `context1m`. +- Os auxiliares de stream específicos do Claude da Anthropic permanecem, por enquanto, no + próprio seam público `api.ts` / `contract-api.ts` do plugin embutido. Essa superfície do pacote + exporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e os builders de wrapper + de Anthropic de nível mais baixo, em vez de ampliar o SDK genérico em torno das regras de + headers beta de um único provedor. +- OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` e + `capabilities`, além de `buildMissingAuthMessage`, `suppressBuiltInModel`, + `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef`, + porque é responsável por forward-compat do GPT-5.4, pela normalização direta da OpenAI + de `openai-completions` -> `openai-responses`, por dicas de autenticação com reconhecimento + do Codex, supressão do Spark, linhas sintéticas da OpenAI em listas e pela política de pensamento / + modelo live do GPT-5; a família de streams `openai-responses-defaults` é responsável pelos + wrappers nativos compartilhados do OpenAI Responses para headers de atribuição, + `/fast`/`serviceTier`, verbosidade de texto, pesquisa nativa na web do Codex, + modelagem de payload de compatibilidade de raciocínio e gerenciamento de contexto do Responses. +- OpenRouter usa `catalog`, além de `resolveDynamicModel` e + `prepareDynamicModel`, porque o provedor é pass-through e pode expor novos + ids de modelo antes que o catálogo estático do OpenClaw seja atualizado; ele também usa + `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` para manter + fora do core headers de requisição específicos do provedor, metadados de roteamento, patches + de raciocínio e política de cache de prompt. Sua política de replay vem da + família `passthrough-gemini`, enquanto a família de streams `openrouter-thinking` + é responsável pela injeção de raciocínio no proxy e pelos skips de modelos não compatíveis / `auto`. - GitHub Copilot usa `catalog`, `auth`, `resolveDynamicModel` e - `capabilities` mais `prepareRuntimeAuth` e `fetchUsageSnapshot` porque - precisa de login por dispositivo controlado pelo provedor, comportamento de - fallback de modelo, peculiaridades de transcrição do Claude, uma troca de - token GitHub -> token Copilot e um endpoint de uso controlado pelo provedor. + `capabilities`, além de `prepareRuntimeAuth` e `fetchUsageSnapshot`, porque + precisa de login por dispositivo pertencente ao provedor, comportamento de fallback de modelo, + particularidades de transcrição do Claude, troca de token GitHub -> token Copilot + e um endpoint de uso pertencente ao provedor. - OpenAI Codex usa `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` e `augmentModelCatalog` mais - `prepareExtraParams`, `resolveUsageAuth` e `fetchUsageSnapshot` porque ainda - roda sobre os transportes centrais da OpenAI, mas controla sua normalização - de transporte/base URL, política de fallback de refresh OAuth, escolha padrão - de transporte, linhas sintéticas de catálogo do Codex e integração com o - endpoint de uso do ChatGPT; ele compartilha a mesma família de stream - `openai-responses-defaults` da OpenAI direta. + `normalizeResolvedModel`, `refreshOAuth` e `augmentModelCatalog`, além de + `prepareExtraParams`, `resolveUsageAuth` e `fetchUsageSnapshot`, porque + ainda é executado nos transportes OpenAI do core, mas é responsável por sua normalização + de transporte/base URL, política de fallback de refresh OAuth, escolha de transporte padrão, + linhas sintéticas de catálogo do Codex e integração com endpoint de uso do ChatGPT; ele + compartilha a mesma família de streams `openai-responses-defaults` da OpenAI direta. - Google AI Studio e Gemini CLI OAuth usam `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` e `isModernModelRef` porque a - família de replay `google-gemini` controla fallback de compatibilidade futura - do Gemini 3.1, validação nativa de replay do Gemini, sanitização de replay de - bootstrap, modo de saída de raciocínio marcado e correspondência de modelos - modernos, enquanto a família de stream `google-thinking` controla a - normalização de payload de thinking do Gemini; Gemini CLI OAuth também usa - `formatApiKey`, `resolveUsageAuth` e `fetchUsageSnapshot` para formatação de - token, parsing de token e wiring de endpoint de cota. -- Anthropic Vertex usa `buildReplayPolicy` por meio da família de replay - `anthropic-by-model`, para que a limpeza de replay específica do Claude fique - restrita a ids Claude em vez de todo transporte `anthropic-messages`. + família de replay `google-gemini` é responsável por fallback de forward-compat do Gemini 3.1, + validação nativa de replay do Gemini, sanitização de replay de bootstrap, modo + de saída de raciocínio com tags e correspondência de modelo moderno, enquanto a + família de streams `google-thinking` é responsável pela normalização do payload de pensamento do Gemini; + Gemini CLI OAuth também usa `formatApiKey`, `resolveUsageAuth` e + `fetchUsageSnapshot` para formatação de token, parsing de token e ligação + com endpoint de cota. +- Anthropic Vertex usa `buildReplayPolicy` por meio da + família de replay `anthropic-by-model`, para que a limpeza de replay específica do Claude fique + limitada a ids do Claude em vez de a todo transporte `anthropic-messages`. - Amazon Bedrock usa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` e `resolveDefaultThinkingLevel` porque controla a - classificação específica do Bedrock para erros de throttle/not-ready/overflow - de contexto em tráfego Anthropic-on-Bedrock; sua política de replay ainda - compartilha o mesmo guard específico de Claude `anthropic-by-model`. + `classifyFailoverReason` e `resolveDefaultThinkingLevel`, porque é responsável + pela classificação específica do Bedrock de erros de throttle/not-ready/context-overflow + para tráfego Anthropic-on-Bedrock; sua política de replay ainda compartilha a mesma proteção + `anthropic-by-model` exclusiva do Claude. - OpenRouter, Kilocode, Opencode e Opencode Go usam `buildReplayPolicy` - por meio da família de replay `passthrough-gemini` porque fazem proxy de - modelos Gemini via transportes compatíveis com OpenAI e precisam de - sanitização de thought-signature do Gemini sem validação nativa de replay do - Gemini nem reescritas de bootstrap. -- MiniMax usa `buildReplayPolicy` por meio da família de replay - `hybrid-anthropic-openai` porque um provedor controla tanto semântica de - mensagens Anthropic quanto semântica compatível com OpenAI; ele mantém a - remoção de blocos de thinking apenas do Claude no lado Anthropic, enquanto - substitui o modo de saída de reasoning de volta para nativo, e a família de - stream `minimax-fast-mode` controla reescritas de modelo fast-mode no caminho - de stream compartilhado. -- Moonshot usa `catalog` mais `wrapStreamFn` porque ainda usa o transporte - compartilhado da OpenAI, mas precisa de normalização de payload de thinking - controlada pelo provedor; a família de stream `moonshot-thinking` mapeia - config mais estado `/think` para seu payload nativo binário de thinking. + por meio da família de replay `passthrough-gemini`, porque fazem proxy de modelos Gemini + por transportes compatíveis com OpenAI e precisam de sanitização de assinatura de pensamento + do Gemini sem validação nativa de replay do Gemini nem reescritas de bootstrap. +- MiniMax usa `buildReplayPolicy` por meio da + família de replay `hybrid-anthropic-openai`, porque um provedor é responsável por semânticas + tanto de mensagens Anthropic quanto compatíveis com OpenAI; ele mantém a remoção de + blocos de pensamento exclusivos do Claude no lado Anthropic, enquanto substitui o modo de + saída de raciocínio de volta para nativo, e a família de streams `minimax-fast-mode` é responsável por + reescritas de modelos fast-mode no caminho de stream compartilhado. +- Moonshot usa `catalog`, além de `wrapStreamFn`, porque ainda usa o transporte + OpenAI compartilhado, mas precisa de normalização de payload de pensamento pertencente ao provedor; a + família de streams `moonshot-thinking` mapeia configuração mais estado de `/think` para seu + payload nativo de pensamento binário. - Kilocode usa `catalog`, `capabilities`, `wrapStreamFn` e - `isCacheTtlEligible` porque precisa de headers de requisição controlados pelo - provedor, normalização de payload de reasoning, dicas de transcrição do - Gemini e gating de cache-TTL do Anthropic; a família de stream - `kilocode-thinking` mantém a injeção de thinking do Kilo no caminho de stream - compartilhado do proxy, enquanto ignora `kilo/auto` e outros ids de modelo - proxy que não oferecem suporte a payloads explícitos de reasoning. + `isCacheTtlEligible`, porque precisa de headers de requisição pertencentes ao provedor, + normalização de payload de raciocínio, dicas de transcrição do Gemini e controle de TTL de cache + da Anthropic; a família de streams `kilocode-thinking` mantém a injeção de pensamento do Kilo + no caminho de stream proxy compartilhado, enquanto ignora `kilo/auto` e + outros ids de modelo proxy que não aceitam payloads explícitos de raciocínio. - Z.AI usa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` e `fetchUsageSnapshot` porque controla fallback do GLM-5, - padrões de `tool_stream`, UX de thinking binário, correspondência de modelos - modernos e tanto auth de uso quanto busca de cota; a família de stream - `tool-stream-default-on` mantém o wrapper padrão de `tool_stream` ligado fora - do glue manuscrito por provedor. + `resolveUsageAuth` e `fetchUsageSnapshot`, porque é responsável por fallback do GLM-5, + padrões de `tool_stream`, UX de pensamento binário, correspondência de modelo moderno e por + autenticação de uso + busca de cota; a família de streams `tool-stream-default-on` mantém + o wrapper de `tool_stream` ativado por padrão fora da cola manual por provedor. - xAI usa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, - `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef` - porque controla normalização nativa de transporte xAI Responses, reescritas - de alias fast-mode do Grok, `tool_stream` padrão, limpeza de strict-tool / - payload de reasoning, reutilização de auth de fallback para ferramentas - controladas por plugin, resolução de modelos Grok com compatibilidade futura e - patches de compatibilidade controlados pelo provedor, como perfil de schema de - ferramenta do xAI, palavras-chave de schema não suportadas, `web_search` - nativo e decodificação de argumentos de chamada de ferramenta com entidades HTML. -- Mistral, OpenCode Zen e OpenCode Go usam apenas `capabilities` para manter - peculiaridades de transcrição/ferramentas fora do núcleo. -- Provedores integrados somente de catálogo, como `byteplus`, - `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, + `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef`, + porque é responsável pela normalização nativa de transporte do xAI Responses, reescritas + de aliases fast-mode do Grok, `tool_stream` padrão, limpeza de ferramenta estrita / payload + de raciocínio, reutilização de autenticação fallback para ferramentas pertencentes ao plugin, resolução + de forward-compat de modelos Grok e patches de compatibilidade pertencentes ao provedor, como perfil + de esquema de ferramenta do xAI, palavras-chave de esquema não compatíveis, `web_search` nativo e + decodificação de argumentos de chamadas de ferramenta com entidades HTML. +- Mistral, OpenCode Zen e OpenCode Go usam apenas `capabilities` + para manter particularidades de transcrição/ferramentas fora do core. +- Provedores embutidos somente de catálogo, como `byteplus`, `cloudflare-ai-gateway`, + `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` e `volcengine`, usam apenas `catalog`. -- Qwen usa `catalog` para seu provedor de texto mais registros compartilhados - de media-understanding e video-generation para suas superfícies multimodais. -- MiniMax e Xiaomi usam `catalog` mais hooks de uso porque seu comportamento de - `/usage` é controlado pelo plugin, embora a inferência ainda execute pelos - transportes compartilhados. +- Qwen usa `catalog` para seu provedor de texto, além de registros compartilhados de + compreensão de mídia e geração de vídeo para suas superfícies multimodais. +- MiniMax e Xiaomi usam `catalog`, além de hooks de uso, porque seu comportamento de `/usage` + pertence ao plugin, embora a inferência ainda seja executada pelos transportes compartilhados. -## Helpers de runtime +## Auxiliares de runtime -Plugins podem acessar helpers selecionados do núcleo por meio de `api.runtime`. -Para TTS: +Plugins podem acessar auxiliares selecionados do core por meio de `api.runtime`. Para TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -964,16 +914,14 @@ const voices = await api.runtime.tts.listVoices({ Observações: -- `textToSpeech` retorna o payload normal de saída TTS do núcleo para - superfícies de arquivo/mensagem de voz. -- Usa a configuração central `messages.tts` e a seleção de provedor. -- Retorna buffer de áudio PCM + taxa de amostragem. Plugins devem reamostrar/codificar para provedores. -- `listVoices` é opcional por provedor. Use-a para seletores de voz ou fluxos de setup controlados pelo fornecedor. -- As listagens de vozes podem incluir metadados mais ricos, como localidade, - gênero e tags de personalidade para seletores conscientes do provedor. +- `textToSpeech` retorna o payload normal de saída de TTS do core para superfícies de arquivo/mensagem de voz. +- Usa a configuração `messages.tts` do core e a seleção de provedor. +- Retorna buffer de áudio PCM + sample rate. Plugins devem fazer resampling/codificação para provedores. +- `listVoices` é opcional por provedor. Use-o para seletores de voz ou fluxos de configuração pertencentes ao fornecedor. +- Listagens de voz podem incluir metadados mais ricos, como locale, gender e tags de personalidade para seletores com reconhecimento do provedor. - OpenAI e ElevenLabs oferecem suporte a telefonia hoje. Microsoft não. -Plugins também podem registrar provedores de voz via `api.registerSpeechProvider(...)`. +Plugins também podem registrar provedores de fala via `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -993,15 +941,15 @@ api.registerSpeechProvider({ Observações: -- Mantenha política de TTS, fallback e entrega de resposta no núcleo. -- Use provedores de voz para comportamento de síntese controlado pelo fornecedor. -- A entrada legada Microsoft `edge` é normalizada para o id de provedor `microsoft`. -- O modelo de propriedade preferido é orientado à empresa: um único plugin de - fornecedor pode controlar texto, voz, imagem e futuros provedores de mídia à - medida que o OpenClaw adiciona esses contratos de capacidade. +- Mantenha política de TTS, fallback e entrega de resposta no core. +- Use provedores de fala para comportamento de síntese pertencente ao fornecedor. +- A entrada legada `edge` da Microsoft é normalizada para o id de provedor `microsoft`. +- O modelo de propriedade preferido é orientado à empresa: um único plugin de fornecedor pode ser responsável por + provedores de texto, fala, imagem e mídia futura à medida que o OpenClaw adicionar esses + contratos de capacidade. -Para entendimento de imagem/áudio/vídeo, plugins registram um provedor tipado -de media-understanding em vez de um saco genérico chave/valor: +Para compreensão de imagem/áudio/vídeo, plugins registram um provedor tipado único de +compreensão de mídia em vez de um saco genérico de chave/valor: ```ts api.registerMediaUnderstandingProvider({ @@ -1015,16 +963,16 @@ api.registerMediaUnderstandingProvider({ Observações: -- Mantenha orquestração, fallback, config e wiring de canal no núcleo. +- Mantenha orquestração, fallback, configuração e integração com canais no core. - Mantenha o comportamento do fornecedor no plugin do provedor. -- A expansão aditiva deve continuar tipada: novos métodos opcionais, novos - campos opcionais de resultado, novas capacidades opcionais. +- A expansão aditiva deve permanecer tipada: novos métodos opcionais, novos campos opcionais + de resultado, novas capacidades opcionais. - A geração de vídeo já segue o mesmo padrão: - - o núcleo controla o contrato de capacidade e o helper de runtime - - plugins de fornecedores registram `api.registerVideoGenerationProvider(...)` - - plugins de funcionalidade/canal consomem `api.runtime.videoGeneration.*` + - o core é responsável pelo contrato de capacidade e pelo auxiliar de runtime + - plugins de fornecedor registram `api.registerVideoGenerationProvider(...)` + - plugins de recurso/canal consomem `api.runtime.videoGeneration.*` -Para helpers de runtime de media-understanding, plugins podem chamar: +Para auxiliares de runtime de compreensão de mídia, plugins podem chamar: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -1039,14 +987,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Para transcrição de áudio, plugins podem usar o runtime de -media-understanding ou o alias STT mais antigo: +Para transcrição de áudio, plugins podem usar o runtime de compreensão de mídia +ou o alias STT mais antigo: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Opcional quando o MIME não puder ser inferido com confiabilidade: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` @@ -1054,13 +1002,12 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Observações: - `api.runtime.mediaUnderstanding.*` é a superfície compartilhada preferida para - entendimento de imagem/áudio/vídeo. -- Usa a configuração central de áudio de media-understanding (`tools.media.audio`) e a ordem de fallback de provedores. -- Retorna `{ text: undefined }` quando nenhuma saída de transcrição é produzida - (por exemplo, entrada ignorada/não suportada). -- `api.runtime.stt.transcribeAudioFile(...)` continua como alias de compatibilidade. + compreensão de imagem/áudio/vídeo. +- Usa a configuração de áudio de compreensão de mídia do core (`tools.media.audio`) e a ordem de fallback do provedor. +- Retorna `{ text: undefined }` quando nenhuma saída de transcrição é produzida (por exemplo, entrada ignorada/não compatível). +- `api.runtime.stt.transcribeAudioFile(...)` permanece como alias de compatibilidade. -Plugins também podem iniciar execuções de subagentes em segundo plano via `api.runtime.subagent`: +Plugins também podem iniciar execuções de subagente em segundo plano por meio de `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1074,14 +1021,14 @@ const result = await api.runtime.subagent.run({ Observações: -- `provider` e `model` são sobrescritas opcionais por execução, não mudanças persistentes de sessão. -- O OpenClaw só respeita esses campos de sobrescrita para chamadores confiáveis. -- Para execuções de fallback controladas por plugins, operadores devem aderir explicitamente com `plugins.entries..subagent.allowModelOverride: true`. +- `provider` e `model` são substituições opcionais por execução, não alterações persistentes de sessão. +- O OpenClaw só respeita esses campos de substituição para chamadores confiáveis. +- Para execuções de fallback pertencentes ao plugin, operadores precisam ativar explicitamente com `plugins.entries..subagent.allowModelOverride: true`. - Use `plugins.entries..subagent.allowedModels` para restringir plugins confiáveis a alvos canônicos específicos `provider/model`, ou `"*"` para permitir explicitamente qualquer alvo. -- Execuções de subagentes de plugins não confiáveis continuam funcionando, mas solicitações de sobrescrita são rejeitadas em vez de sofrer fallback silencioso. +- Execuções de subagente de plugins não confiáveis continuam funcionando, mas solicitações de substituição são rejeitadas em vez de silenciosamente fazer fallback. -Para pesquisa na web, plugins podem consumir o helper de runtime compartilhado -em vez de acessar o wiring da ferramenta do agente: +Para pesquisa na web, plugins podem consumir o auxiliar de runtime compartilhado em vez de +acessar diretamente a integração da ferramenta do agente: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1102,12 +1049,9 @@ Plugins também podem registrar provedores de pesquisa na web via Observações: -- Mantenha seleção de provedor, resolução de credenciais e semântica de - requisição compartilhada no núcleo. -- Use provedores de pesquisa na web para transportes de busca específicos do fornecedor. -- `api.runtime.webSearch.*` é a superfície compartilhada preferida para plugins - de funcionalidade/canal que precisam de comportamento de pesquisa sem depender - do wrapper da ferramenta do agente. +- Mantenha seleção de provedor, resolução de credenciais e semântica compartilhada de requisição no core. +- Use provedores de pesquisa na web para transportes de pesquisa específicos do fornecedor. +- `api.runtime.webSearch.*` é a superfície compartilhada preferida para plugins de recurso/canal que precisam de comportamento de pesquisa sem depender do wrapper da ferramenta do agente. ### `api.runtime.imageGeneration` @@ -1145,7 +1089,7 @@ api.registerHttpRoute({ Campos da rota: - `path`: caminho da rota sob o servidor HTTP do gateway. -- `auth`: obrigatório. Use `"gateway"` para exigir auth normal do gateway, ou `"plugin"` para auth/verificação de webhook gerenciadas pelo plugin. +- `auth`: obrigatório. Use `"gateway"` para exigir a autenticação normal do gateway, ou `"plugin"` para autenticação/validação de webhook gerenciada pelo plugin. - `match`: opcional. `"exact"` (padrão) ou `"prefix"`. - `replaceExisting`: opcional. Permite que o mesmo plugin substitua seu próprio registro de rota existente. - `handler`: retorne `true` quando a rota tiver tratado a requisição. @@ -1155,24 +1099,24 @@ Observações: - `api.registerHttpHandler(...)` foi removido e causará um erro de carregamento do plugin. Use `api.registerHttpRoute(...)` em vez disso. - Rotas de plugin devem declarar `auth` explicitamente. - Conflitos exatos de `path + match` são rejeitados, a menos que `replaceExisting: true`, e um plugin não pode substituir a rota de outro plugin. -- Rotas sobrepostas com níveis de `auth` diferentes são rejeitadas. Mantenha cadeias de fallthrough `exact`/`prefix` apenas no mesmo nível de auth. -- Rotas `auth: "plugin"` **não** recebem automaticamente escopos de runtime do operador. Elas servem para webhooks/verificação de assinatura gerenciados pelo plugin, não para chamadas privilegiadas a helpers do Gateway. +- Rotas sobrepostas com diferentes níveis de `auth` são rejeitadas. Mantenha cadeias de fallthrough `exact`/`prefix` apenas no mesmo nível de autenticação. +- Rotas `auth: "plugin"` **não** recebem automaticamente escopos de runtime do operador. Elas servem para webhooks/validação de assinatura gerenciados pelo plugin, não para chamadas privilegiadas de auxiliares do Gateway. - Rotas `auth: "gateway"` são executadas dentro de um escopo de runtime de requisição do Gateway, mas esse escopo é intencionalmente conservador: - - autenticação bearer por segredo compartilhado (`gateway.auth.mode = "token"` / `"password"`) mantém escopos de runtime de rota de plugin fixados em `operator.write`, mesmo que o chamador envie `x-openclaw-scopes` + - autenticação bearer por segredo compartilhado (`gateway.auth.mode = "token"` / `"password"`) mantém os escopos de runtime de rotas de plugin fixados em `operator.write`, mesmo que o chamador envie `x-openclaw-scopes` - modos HTTP confiáveis com identidade (por exemplo, `trusted-proxy` ou `gateway.auth.mode = "none"` em uma entrada privada) respeitam `x-openclaw-scopes` apenas quando o header está explicitamente presente - - se `x-openclaw-scopes` estiver ausente nessas requisições de rota de plugin com identidade, o escopo de runtime volta para `operator.write` -- Regra prática: não presuma que uma rota de plugin com auth de gateway seja implicitamente uma superfície de administrador. Se sua rota precisar de comportamento exclusivo de admin, exija um modo de auth com identidade e documente o contrato explícito do header `x-openclaw-scopes`. + - se `x-openclaw-scopes` estiver ausente nessas requisições com identidade para rotas de plugin, o escopo de runtime volta para `operator.write` +- Regra prática: não assuma que uma rota de plugin autenticada pelo gateway é implicitamente uma superfície de administração. Se sua rota precisar de comportamento exclusivo de admin, exija um modo de autenticação com identidade e documente o contrato explícito do header `x-openclaw-scopes`. -## Caminhos de importação do Plugin SDK +## Caminhos de importação do SDK de plugins -Use subcaminhos do SDK em vez da importação monolítica `openclaw/plugin-sdk` -ao criar plugins: +Use subcaminhos do SDK em vez da importação monolítica `openclaw/plugin-sdk` ao +criar plugins: - `openclaw/plugin-sdk/plugin-entry` para primitivas de registro de plugins. - `openclaw/plugin-sdk/core` para o contrato genérico compartilhado voltado a plugins. -- `openclaw/plugin-sdk/config-schema` para o export do schema Zod da raiz - `openclaw.json` (`OpenClawSchema`). -- Primitivas estáveis de canal como `openclaw/plugin-sdk/channel-setup`, +- `openclaw/plugin-sdk/config-schema` para a exportação do esquema Zod raiz de `openclaw.json` + (`OpenClawSchema`). +- Primitivas estáveis de canal, como `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1184,17 +1128,15 @@ ao criar plugins: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` e - `openclaw/plugin-sdk/webhook-ingress` para wiring compartilhado de - setup/auth/resposta/webhook. `channel-inbound` é a casa compartilhada para - debounce, correspondência de menções, helpers de política de menção de - entrada, formatação de envelope de entrada e helpers de contexto de envelope - de entrada. - `channel-setup` é o seam estreito de setup para instalação opcional. - `setup-runtime` é a superfície de setup segura para runtime usada por - `setupEntry` / inicialização adiada, incluindo adaptadores de patch de setup - seguros para importação. - `setup-adapter-runtime` é o seam de adaptador de setup de conta sensível a env. - `setup-tools` é o pequeno seam de helper de CLI/arquivo/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` para integração compartilhada de configuração/autenticação/resposta/webhook. + `channel-inbound` é o lar compartilhado para debounce, correspondência de menções, + auxiliares de política de menção de entrada, formatação de envelope e + auxiliares de contexto de envelope de entrada. + `channel-setup` é o seam estreito de configuração de instalação opcional. + `setup-runtime` é a superfície de configuração segura para runtime usada por `setupEntry` / + inicialização adiada, incluindo os adaptadores de patch de configuração seguros para importação. + `setup-adapter-runtime` é o seam de adaptador de configuração de conta com reconhecimento de env. + `setup-tools` é o seam pequeno de auxiliares de CLI/arquivo/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Subcaminhos de domínio como `openclaw/plugin-sdk/channel-config-helpers`, @@ -1215,140 +1157,128 @@ ao criar plugins: `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` e - `openclaw/plugin-sdk/directory-runtime` para helpers compartilhados de runtime/config. - `telegram-command-config` é o seam público estreito para normalização/validação - de comandos personalizados do Telegram e continua disponível mesmo se a - superfície de contrato integrada do Telegram estiver temporariamente indisponível. + `openclaw/plugin-sdk/directory-runtime` para auxiliares compartilhados de runtime/configuração. + `telegram-command-config` é o seam público estreito para normalização/validação de comandos personalizados do Telegram e continua disponível mesmo se a superfície de contrato embutida do Telegram estiver temporariamente indisponível. `text-runtime` é o seam compartilhado de texto/markdown/logging, incluindo - remoção de texto visível ao assistente, helpers de render/chunking de markdown, - helpers de redação, helpers de tags de diretiva e utilitários de texto seguro. -- Seams de canal específicas de aprovação devem preferir um único contrato - `approvalCapability` no plugin. O núcleo então lê auth de aprovação, entrega, - renderização, roteamento nativo e comportamento lazy de handler nativo por - meio dessa única capacidade, em vez de misturar comportamento de aprovação em - campos não relacionados do plugin. + remoção de texto visível para o assistente, auxiliares de renderização/fragmentação de markdown, auxiliares de redação, + auxiliares de tags de diretiva e utilitários de texto seguro. +- Seams de canal específicos de aprovação devem preferir um único contrato `approvalCapability` + no plugin. O core então lê autenticação de aprovação, entrega, renderização, + roteamento nativo e comportamento lazy de tratador nativo por meio dessa única + capacidade, em vez de misturar comportamento de aprovação em campos não relacionados do plugin. - `openclaw/plugin-sdk/channel-runtime` está obsoleto e permanece apenas como um - shim de compatibilidade para plugins mais antigos. Código novo deve importar - as primitivas genéricas mais estreitas, e o código do repositório não deve - adicionar novas importações desse shim. -- Detalhes internos de extensões integradas continuam privados. Plugins externos - devem usar apenas subcaminhos `openclaw/plugin-sdk/*`. Código/testes do núcleo - do OpenClaw podem usar os pontos de entrada públicos do repositório sob a raiz - de pacote de um plugin, como `index.js`, `api.js`, `runtime-api.js`, - `setup-entry.js` e arquivos de escopo estreito, como `login-qr-api.js`. - Nunca importe `src/*` de um pacote de plugin a partir do núcleo ou de outra extensão. + shim de compatibilidade para plugins antigos. Código novo deve importar as primitivas + genéricas mais estreitas, e o código do repositório não deve adicionar novas importações do + shim. +- Internos de extensões embutidas permanecem privados. Plugins externos devem usar apenas + subcaminhos `openclaw/plugin-sdk/*`. Código core/de teste do OpenClaw pode usar os + pontos de entrada públicos do repositório sob a raiz de um pacote de plugin, como `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` e arquivos de escopo estreito, como + `login-qr-api.js`. Nunca importe `src/*` de um pacote de plugin a partir do core ou de + outra extensão. - Divisão de ponto de entrada do repositório: - `/api.js` é o barrel de helpers/tipos, + `/api.js` é o barrel de auxiliares/tipos, `/runtime-api.js` é o barrel somente de runtime, - `/index.js` é a entrada do plugin integrado - e `/setup-entry.js` é a entrada do plugin de setup. -- Exemplos atuais de provedores integrados: - - Anthropic usa `api.js` / `contract-api.js` para helpers de stream do Claude, - como `wrapAnthropicProviderStream`, helpers de headers beta e parsing de - `service_tier`. - - OpenAI usa `api.js` para builders de provedor, helpers de modelo padrão e + `/index.js` é a entrada do plugin embutido, + e `/setup-entry.js` é a entrada do plugin de configuração. +- Exemplos atuais de provedores embutidos: + - Anthropic usa `api.js` / `contract-api.js` para auxiliares de stream do Claude, como + `wrapAnthropicProviderStream`, auxiliares de header beta e parsing de `service_tier`. + - OpenAI usa `api.js` para builders de provedor, auxiliares de modelo padrão e builders de provedor em tempo real. - - OpenRouter usa `api.js` para seu builder de provedor mais helpers de - onboarding/configuração, enquanto `register.runtime.js` ainda pode reexportar - helpers genéricos `plugin-sdk/provider-stream` para uso local do repositório. -- Pontos de entrada públicos carregados por facade preferem o snapshot ativo de - configuração em runtime quando ele existe, e então fazem fallback para o - arquivo de configuração resolvido em disco quando o OpenClaw ainda não está - servindo um snapshot de runtime. -- Primitivas compartilhadas genéricas continuam sendo o contrato público - preferido do SDK. Ainda existe um pequeno conjunto reservado de compatibilidade - de seams helper com marca de canal integrado. Trate-os como seams de - manutenção/compatibilidade de plugins integrados, não como novos alvos de - importação de terceiros; novos contratos compartilhados entre canais ainda - devem ir para subcaminhos genéricos `plugin-sdk/*` ou para os barrels locais - `api.js` / `runtime-api.js` do plugin. + - OpenRouter usa `api.js` para seu builder de provedor, além de auxiliares de onboarding/configuração, + enquanto `register.runtime.js` ainda pode reexportar auxiliares genéricos de + `plugin-sdk/provider-stream` para uso local do repositório. +- Pontos de entrada públicos carregados por façade preferem o snapshot ativo de configuração de runtime + quando ele existe, e depois recorrem ao arquivo de configuração resolvido em disco quando o + OpenClaw ainda não está servindo um snapshot de runtime. +- Primitivas genéricas compartilhadas continuam sendo o contrato público preferido do SDK. Ainda + existe um pequeno conjunto reservado de compatibilidade de seams auxiliares com marca de canais embutidos. + Trate-os como seams de manutenção/compatibilidade embutida, não como novos alvos de importação de terceiros; novos contratos entre canais ainda devem chegar em subcaminhos genéricos `plugin-sdk/*` ou nos barrels locais do plugin `api.js` / + `runtime-api.js`. Observação de compatibilidade: - Evite o barrel raiz `openclaw/plugin-sdk` em código novo. -- Prefira primeiro as primitivas estáveis mais estreitas. Os subcaminhos mais - novos de setup/pairing/reply/feedback/contract/inbound/threading/command/ - secret-input/webhook/infra/allowlist/status/message-tool são o contrato - pretendido para novo trabalho de plugins integrados e externos. - Parsing/correspondência de alvos pertence a - `openclaw/plugin-sdk/channel-targets`. - Gates de ação de mensagem e helpers de id de mensagem de reação pertencem a +- Prefira primeiro as primitivas estáveis e estreitas. Os subcaminhos mais novos de setup/pairing/reply/ + feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool são o contrato pretendido para novos + plugins embutidos e externos. + O parsing/matching de destino pertence a `openclaw/plugin-sdk/channel-targets`. + Barreiras de ação de mensagem e auxiliares de message-id de reação pertencem a `openclaw/plugin-sdk/channel-actions`. -- Barrels helper específicos de extensões integradas não são estáveis por - padrão. Se um helper só for necessário para uma extensão integrada, mantenha-o - atrás do seam local `api.js` ou `runtime-api.js` da extensão, em vez de - promovê-lo para `openclaw/plugin-sdk/`. -- Novos seams helper compartilhados devem ser genéricos, não com marca de canal. - Parsing de alvos compartilhado pertence a - `openclaw/plugin-sdk/channel-targets`; detalhes internos específicos de canal - ficam atrás do seam local `api.js` ou `runtime-api.js` do plugin proprietário. -- Subcaminhos específicos de capacidade como `image-generation`, - `media-understanding` e `speech` existem porque plugins nativos/integrados os - usam hoje. Sua presença, por si só, não significa que todo helper exportado - seja um contrato externo congelado de longo prazo. +- Barrels de auxiliares específicos de extensões embutidas não são estáveis por padrão. Se um + auxiliar for necessário apenas para uma extensão embutida, mantenha-o atrás do + seam local `api.js` ou `runtime-api.js` da extensão em vez de promovê-lo para + `openclaw/plugin-sdk/`. +- Novos seams de auxiliares compartilhados devem ser genéricos, não com marca de canal. O parsing + compartilhado de destino pertence a `openclaw/plugin-sdk/channel-targets`; internos + específicos do canal permanecem atrás do seam local `api.js` ou `runtime-api.js` + do plugin proprietário. +- Subcaminhos específicos de capacidade, como `image-generation`, + `media-understanding` e `speech`, existem porque plugins nativos/embutidos os usam + hoje. A presença deles, por si só, não significa que todo auxiliar exportado seja um + contrato externo congelado de longo prazo. -## Schemas da ferramenta de mensagem +## Esquemas da ferramenta de mensagem -Plugins devem controlar contribuições de schema específicas do canal em -`describeMessageTool(...)`. Mantenha campos específicos de provedor no plugin, -não no núcleo compartilhado. +Plugins devem ser responsáveis pelas contribuições de esquema específicas de canal em +`describeMessageTool(...)`. Mantenha campos específicos do provedor no plugin, não no core compartilhado. -Para fragmentos de schema compartilhados e portáveis, reutilize os helpers -genéricos exportados por `openclaw/plugin-sdk/channel-actions`: +Para fragmentos de esquema portáteis compartilhados, reutilize os auxiliares genéricos exportados por +`openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` para payloads no estilo grade de botões -- `createMessageToolCardSchema()` para payloads de cartão estruturado +- `createMessageToolButtonsSchema()` para payloads em estilo grade de botões +- `createMessageToolCardSchema()` para payloads estruturados de cards -Se um formato de schema só fizer sentido para um provedor, defina-o no código -do próprio plugin em vez de promovê-lo ao SDK compartilhado. +Se um formato de esquema só fizer sentido para um provedor, defina-o no código-fonte +desse plugin em vez de promovê-lo para o SDK compartilhado. -## Resolução de alvos de canal +## Resolução de destino de canal -Plugins de canal devem controlar semânticas de alvo específicas do canal. -Mantenha o host de saída compartilhado genérico e use a superfície do adaptador -de mensagens para regras do provedor: +Plugins de canal devem ser responsáveis pela semântica de destino específica do canal. Mantenha o +host de saída compartilhado genérico e use a superfície do adaptador de mensagens para regras do provedor: -- `messaging.inferTargetChatType({ to })` decide se um alvo normalizado deve ser - tratado como `direct`, `group` ou `channel` antes da consulta ao diretório. -- `messaging.targetResolver.looksLikeId(raw, normalized)` informa ao núcleo se - uma entrada deve ir direto para resolução semelhante a id em vez de busca no diretório. +- `messaging.inferTargetChatType({ to })` decide se um destino normalizado + deve ser tratado como `direct`, `group` ou `channel` antes da busca em diretório. +- `messaging.targetResolver.looksLikeId(raw, normalized)` informa ao core se uma + entrada deve pular direto para resolução semelhante a id em vez de busca no diretório. - `messaging.targetResolver.resolveTarget(...)` é o fallback do plugin quando o - núcleo precisa de uma resolução final controlada pelo provedor após a - normalização ou após um erro de busca no diretório. -- `messaging.resolveOutboundSessionRoute(...)` controla a construção da rota de - sessão de saída específica do provedor depois que um alvo é resolvido. + core precisa de uma resolução final pertencente ao provedor após a normalização ou após + uma falha de busca no diretório. +- `messaging.resolveOutboundSessionRoute(...)` é responsável pela construção da rota de sessão + específica do provedor depois que um destino é resolvido. -Divisão recomendada: +Separação recomendada: -- Use `inferTargetChatType` para decisões de categoria que devem ocorrer antes +- Use `inferTargetChatType` para decisões de categoria que devem acontecer antes da busca por pares/grupos. -- Use `looksLikeId` para verificações do tipo "trate isto como um id de alvo explícito/nativo". -- Use `resolveTarget` para fallback de normalização específica do provedor, não - para busca ampla em diretório. -- Mantenha ids nativos do provedor, como chat ids, thread ids, JIDs, handles e - room ids dentro de valores `target` ou parâmetros específicos do provedor, não - em campos genéricos do SDK. +- Use `looksLikeId` para verificações do tipo “trate isto como um id de destino explícito/nativo”. +- Use `resolveTarget` para fallback de normalização específico do provedor, não para + busca ampla em diretório. +- Mantenha ids nativos do provedor, como ids de chat, ids de thread, JIDs, handles e ids de sala, + dentro de valores `target` ou parâmetros específicos do provedor, não em campos genéricos do SDK. ## Diretórios baseados em configuração -Plugins que derivam entradas de diretório da configuração devem manter essa -lógica no plugin e reutilizar os helpers compartilhados de +Plugins que derivam entradas de diretório a partir da configuração devem manter essa lógica no +plugin e reutilizar os auxiliares compartilhados de `openclaw/plugin-sdk/directory-runtime`. Use isso quando um canal precisar de pares/grupos baseados em configuração, como: - pares de DM orientados por allowlist -- mapas configurados de canal/grupo -- fallbacks estáticos de diretório com escopo de conta +- mapas configurados de canais/grupos +- fallbacks estáticos de diretório com escopo por conta -Os helpers compartilhados em `directory-runtime` lidam apenas com operações genéricas: +Os auxiliares compartilhados em `directory-runtime` tratam apenas operações genéricas: - filtragem de consulta - aplicação de limite -- helpers de deduplicação/normalização +- auxiliares de deduplicação/normalização - construção de `ChannelDirectoryEntry[]` -Inspeção de conta específica do canal e normalização de id devem permanecer na +Inspeção de conta e normalização de id específicas do canal devem permanecer na implementação do plugin. ## Catálogos de provedores @@ -1360,62 +1290,60 @@ Plugins de provedor podem definir catálogos de modelos para inferência com `models.providers`: - `{ provider }` para uma entrada de provedor -- `{ providers }` para múltiplas entradas de provedor +- `{ providers }` para várias entradas de provedor -Use `catalog` quando o plugin controlar model ids específicos do provedor, -padrões de base URL ou metadados de modelo condicionados por auth. +Use `catalog` quando o plugin for responsável por ids de modelo específicos do provedor, padrões +de URL base ou metadados de modelo condicionados à autenticação. -`catalog.order` controla quando o catálogo de um plugin é mesclado em relação -aos provedores implícitos integrados do OpenClaw: +`catalog.order` controla quando o catálogo de um plugin é mesclado em relação aos +provedores implícitos embutidos do OpenClaw: - `simple`: provedores simples orientados por chave de API ou env -- `profile`: provedores que aparecem quando perfis de auth existem -- `paired`: provedores que sintetizam múltiplas entradas de provedor relacionadas -- `late`: última passagem, depois dos outros provedores implícitos +- `profile`: provedores que aparecem quando existem perfis de autenticação +- `paired`: provedores que sintetizam várias entradas de provedor relacionadas +- `late`: última passagem, depois de outros provedores implícitos -Provedores posteriores vencem em colisões de chave, então plugins podem -intencionalmente sobrescrever uma entrada de provedor integrada com o mesmo id. +Provedores posteriores vencem em caso de colisão de chave, então plugins podem intencionalmente sobrescrever uma +entrada de provedor embutida com o mesmo id de provedor. Compatibilidade: - `discovery` ainda funciona como alias legado -- se `catalog` e `discovery` estiverem registrados, o OpenClaw usa `catalog` +- se `catalog` e `discovery` forem registrados, o OpenClaw usa `catalog` -## Inspeção somente leitura de canal +## Inspeção de canal somente leitura Se o seu plugin registrar um canal, prefira implementar -`plugin.config.inspectAccount(cfg, accountId)` junto com `resolveAccount(...)`. +`plugin.config.inspectAccount(cfg, accountId)` juntamente com `resolveAccount(...)`. Por quê: -- `resolveAccount(...)` é o caminho de runtime. Ele pode assumir que as - credenciais estão totalmente materializadas e falhar rapidamente quando - segredos obrigatórios estiverem ausentes. -- Caminhos de comando somente leitura, como `openclaw status`, - `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` - e fluxos de reparo do doctor/config, não devem precisar materializar - credenciais de runtime apenas para descrever a configuração. +- `resolveAccount(...)` é o caminho de runtime. Ele pode assumir que as credenciais + estão totalmente materializadas e falhar rapidamente quando segredos obrigatórios estiverem ausentes. +- Caminhos de comando somente leitura, como `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` e fluxos de doctor/reparo + de configuração, não devem precisar materializar credenciais de runtime apenas para + descrever a configuração. -Comportamento recomendado de `inspectAccount(...)`: +Comportamento recomendado para `inspectAccount(...)`: - Retorne apenas o estado descritivo da conta. - Preserve `enabled` e `configured`. -- Inclua campos de origem/status de credenciais quando relevante, como: +- Inclua campos de origem/status de credenciais quando relevantes, como: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Você não precisa retornar valores brutos de token apenas para relatar - disponibilidade em leitura. Retornar `tokenStatus: "available"` (e o campo de - origem correspondente) é suficiente para comandos de estilo status. -- Use `configured_unavailable` quando uma credencial estiver configurada via - SecretRef, mas indisponível no caminho de comando atual. +- Você não precisa retornar valores brutos de token apenas para relatar disponibilidade + somente leitura. Retornar `tokenStatus: "available"` (e o campo de origem correspondente) + já é suficiente para comandos de status. +- Use `configured_unavailable` quando uma credencial estiver configurada via SecretRef, mas + indisponível no caminho de comando atual. -Isso permite que comandos somente leitura relatem "configurado, mas -indisponível neste caminho de comando" em vez de travar ou relatar -incorretamente a conta como não configurada. +Isso permite que comandos somente leitura relatem “configurado, mas indisponível neste caminho de comando” +em vez de travar ou informar incorretamente que a conta não está configurada. -## Pacotes +## Pacotes multipack Um diretório de plugin pode incluir um `package.json` com `openclaw.extensions`: @@ -1429,70 +1357,63 @@ Um diretório de plugin pode incluir um `package.json` com `openclaw.extensions` } ``` -Cada entrada se torna um plugin. Se o pacote listar múltiplas extensões, o id do -plugin se torna `name/`. +Cada entrada se torna um plugin. Se o pacote listar várias extensões, o id do plugin +passa a ser `name/`. Se o seu plugin importar dependências npm, instale-as nesse diretório para que -`node_modules` fique disponível (`npm install` / `pnpm install`). +`node_modules` esteja disponível (`npm install` / `pnpm install`). -Proteção de segurança: toda entrada `openclaw.extensions` deve permanecer dentro -do diretório do plugin após a resolução de symlink. Entradas que escapam do -diretório do pacote são rejeitadas. +Barreira de segurança: toda entrada de `openclaw.extensions` deve permanecer dentro do diretório do plugin +após a resolução de symlink. Entradas que escaparem do diretório do pacote serão +rejeitadas. Observação de segurança: `openclaw plugins install` instala dependências de plugin com -`npm install --omit=dev --ignore-scripts` (sem scripts de ciclo de vida, sem dependências de desenvolvimento em runtime). Mantenha as -árvores de dependências de plugin como "pure JS/TS" e evite pacotes que exijam -builds em `postinstall`. +`npm install --omit=dev --ignore-scripts` (sem scripts de lifecycle, sem dependências de desenvolvimento em runtime). Mantenha as árvores de dependência do plugin em "pure JS/TS" e evite pacotes que exijam builds em `postinstall`. -Opcional: `openclaw.setupEntry` pode apontar para um módulo leve somente de -setup. Quando o OpenClaw precisa de superfícies de setup para um plugin de canal -desativado, ou quando um plugin de canal está ativado, mas ainda não -configurado, ele carrega `setupEntry` em vez da entrada completa do plugin. Isso -mantém inicialização e setup mais leves quando a entrada principal do plugin -também conecta ferramentas, hooks ou outro código somente de runtime. +Opcional: `openclaw.setupEntry` pode apontar para um módulo leve somente de configuração. +Quando o OpenClaw precisa de superfícies de configuração para um plugin de canal desabilitado, ou +quando um plugin de canal está habilitado, mas ainda não configurado, ele carrega `setupEntry` +em vez da entrada completa do plugin. Isso mantém a inicialização e a configuração mais leves +quando a entrada principal do seu plugin também registra ferramentas, hooks ou outro código exclusivo de runtime. Opcional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -pode optar por um plugin de canal no mesmo caminho `setupEntry` durante a fase -de inicialização pré-listen do gateway, mesmo quando o canal já está configurado. +pode incluir um plugin de canal no mesmo caminho de `setupEntry` durante a fase de +inicialização pré-listen do gateway, mesmo quando o canal já está configurado. -Use isso apenas quando `setupEntry` cobrir totalmente a superfície de -inicialização que precisa existir antes que o gateway comece a escutar. Na -prática, isso significa que a entrada de setup deve registrar toda capacidade -controlada pelo canal da qual a inicialização depende, como: +Use isso apenas quando `setupEntry` cobrir totalmente a superfície de inicialização que precisa existir +antes de o gateway começar a escutar. Na prática, isso significa que a entrada de configuração +deve registrar toda capacidade pertencente ao canal da qual a inicialização depende, como: - o próprio registro do canal -- quaisquer rotas HTTP que precisem estar disponíveis antes que o gateway comece a escutar +- quaisquer rotas HTTP que precisem estar disponíveis antes de o gateway começar a escutar - quaisquer métodos, ferramentas ou serviços do gateway que precisem existir durante essa mesma janela -Se sua entrada completa ainda controlar qualquer capacidade necessária de -inicialização, não ative essa flag. Mantenha o plugin no comportamento padrão e -deixe o OpenClaw carregar a entrada completa durante a inicialização. +Se sua entrada completa ainda for responsável por alguma capacidade obrigatória de inicialização, não habilite +essa flag. Mantenha o plugin no comportamento padrão e deixe o OpenClaw carregar a +entrada completa durante a inicialização. -Canais integrados também podem publicar helpers de superfície de contrato -somente de setup que o núcleo pode consultar antes que o runtime completo do -canal seja carregado. A superfície atual de promoção de setup é: +Canais embutidos também podem publicar auxiliares de superfície de contrato somente de configuração que o core +pode consultar antes que o runtime completo do canal seja carregado. A superfície atual de promoção de setup é: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -O núcleo usa essa superfície quando precisa promover uma configuração de canal -legada de conta única para `channels..accounts.*` sem carregar a entrada -completa do plugin. Matrix é o exemplo integrado atual: ele move apenas chaves -de auth/bootstrap para uma conta promovida nomeada quando contas nomeadas já -existem, e pode preservar uma chave configurada de conta padrão não canônica em -vez de sempre criar `accounts.default`. +O core usa essa superfície quando precisa promover uma configuração legada de canal de conta única +para `channels..accounts.*` sem carregar a entrada completa do plugin. +Matrix é o exemplo embutido atual: ele move apenas chaves de autenticação/bootstrap para uma +conta promovida nomeada quando contas nomeadas já existem e pode preservar uma +chave configurada de conta padrão não canônica em vez de sempre criar +`accounts.default`. -Esses adaptadores de patch de setup mantêm lazy a descoberta de superfície de -contrato integrada. O tempo de importação continua leve; a superfície de -promoção é carregada apenas no primeiro uso, em vez de reentrar na -inicialização do canal integrado na importação do módulo. +Esses adaptadores de patch de setup mantêm lazy a descoberta da superfície de contrato embutida. O tempo +de importação permanece leve; a superfície de promoção é carregada apenas no primeiro uso, em vez de +reentrar na inicialização de canal embutido na importação do módulo. -Quando essas superfícies de inicialização incluem métodos RPC do gateway, -mantenha-os em um prefixo específico do plugin. Namespaces de admin do núcleo -(`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) continuam reservados e -sempre resolvem para `operator.admin`, mesmo que um plugin solicite um escopo -mais estreito. +Quando essas superfícies de inicialização incluem métodos RPC do gateway, mantenha-os em um +prefixo específico do plugin. Namespaces administrativos do core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre são resolvidos +para `operator.admin`, mesmo que um plugin solicite um escopo mais estreito. Exemplo: @@ -1511,9 +1432,8 @@ Exemplo: ### Metadados de catálogo de canal -Plugins de canal podem anunciar metadados de setup/descoberta via `openclaw.channel` e -dicas de instalação via `openclaw.install`. Isso mantém os dados do catálogo -livres no núcleo. +Plugins de canal podem anunciar metadados de configuração/descoberta por meio de `openclaw.channel` e +dicas de instalação por meio de `openclaw.install`. Isso mantém os dados de catálogo fora do core. Exemplo: @@ -1546,36 +1466,36 @@ Campos úteis de `openclaw.channel` além do exemplo mínimo: - `detailLabel`: rótulo secundário para superfícies mais ricas de catálogo/status - `docsLabel`: substitui o texto do link para a documentação - `preferOver`: ids de plugin/canal de prioridade mais baixa que esta entrada de catálogo deve superar -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de cópia da superfície de seleção +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de cópia para superfícies de seleção - `markdownCapable`: marca o canal como compatível com markdown para decisões de formatação de saída - `exposure.configured`: oculta o canal de superfícies de listagem de canais configurados quando definido como `false` -- `exposure.setup`: oculta o canal de seletores interativos de setup/configuração quando definido como `false` +- `exposure.setup`: oculta o canal de seletores interativos de configuração/setup quando definido como `false` - `exposure.docs`: marca o canal como interno/privado para superfícies de navegação de documentação - `showConfigured` / `showInSetup`: aliases legados ainda aceitos por compatibilidade; prefira `exposure` -- `quickstartAllowFrom`: habilita o canal para o fluxo padrão de quickstart `allowFrom` -- `forceAccountBinding`: exige vinculação explícita de conta mesmo quando existe apenas uma conta -- `preferSessionLookupForAnnounceTarget`: prefere consulta de sessão ao resolver alvos de anúncio +- `quickstartAllowFrom`: inclui o canal no fluxo padrão `allowFrom` de início rápido +- `forceAccountBinding`: exige associação explícita de conta mesmo quando existe apenas uma conta +- `preferSessionLookupForAnnounceTarget`: prefere busca de sessão ao resolver destinos de anúncio -O OpenClaw também pode mesclar **catálogos externos de canais** (por exemplo, um -export de registro MPM). Coloque um arquivo JSON em um destes locais: +O OpenClaw também pode mesclar **catálogos de canais externos** (por exemplo, uma +exportação de registro MPM). Coloque um arquivo JSON em um destes locais: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Ou aponte `OPENCLAW_PLUGIN_CATALOG_PATHS` (ou `OPENCLAW_MPM_CATALOG_PATHS`) para -um ou mais arquivos JSON (delimitados por vírgula/ponto e vírgula/`PATH`). Cada -arquivo deve conter `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. O parser também aceita `"packages"` ou `"plugins"` como aliases legados para a chave `"entries"`. +um ou mais arquivos JSON (delimitados por vírgula/ponto e vírgula/`PATH`). Cada arquivo deve +conter `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. O parser também aceita `"packages"` ou `"plugins"` como aliases legados para a chave `"entries"`. ## Plugins de mecanismo de contexto -Plugins de mecanismo de contexto controlam a orquestração do contexto de sessão -para ingestão, montagem e compactação. Registre-os a partir do seu plugin com +Plugins de mecanismo de contexto são responsáveis pela orquestração do contexto de sessão para ingestão, montagem +e compactação. Registre-os a partir do seu plugin com `api.registerContextEngine(id, factory)` e então selecione o mecanismo ativo com `plugins.slots.contextEngine`. -Use isso quando seu plugin precisar substituir ou estender o pipeline padrão de -contexto em vez de apenas adicionar pesquisa de memória ou hooks. +Use isso quando seu plugin precisar substituir ou estender o pipeline de contexto padrão +em vez de apenas adicionar pesquisa de memória ou hooks. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1603,8 +1523,8 @@ export default function (api) { } ``` -Se o seu mecanismo **não** controlar o algoritmo de compactação, mantenha -`compact()` implementado e delegue-o explicitamente: +Se o seu mecanismo **não** for responsável pelo algoritmo de compactação, mantenha `compact()` +implementado e delegue explicitamente: ```ts import { @@ -1641,62 +1561,60 @@ export default function (api) { ## Adicionando uma nova capacidade -Quando um plugin precisar de comportamento que não se encaixe na API atual, não -contorne o sistema de plugins com um acesso privado direto. Adicione a -capacidade ausente. +Quando um plugin precisar de um comportamento que não se encaixe na API atual, não contorne +o sistema de plugins com um acesso privado. Adicione a capacidade ausente. Sequência recomendada: -1. defina o contrato central - Decida qual comportamento compartilhado o núcleo deve controlar: política, - fallback, mesclagem de configuração, ciclo de vida, semântica voltada para - canais e formato do helper de runtime. -2. adicione superfícies tipadas de registro/runtime de plugins - Estenda `OpenClawPluginApi` e/ou `api.runtime` com a menor superfície tipada - útil de capacidade. -3. conecte consumidores do núcleo + canal/funcionalidade - Canais e plugins de funcionalidade devem consumir a nova capacidade por meio - do núcleo, não importando diretamente uma implementação de fornecedor. -4. registre implementações de fornecedores - Plugins de fornecedores então registram seus backends nessa capacidade. +1. defina o contrato do core + Decida qual comportamento compartilhado o core deve possuir: política, fallback, mesclagem de configuração, + ciclo de vida, semântica voltada a canais e formato do auxiliar de runtime. +2. adicione superfícies tipadas de registro/runtime de plugin + Estenda `OpenClawPluginApi` e/ou `api.runtime` com a menor + superfície de capacidade tipada útil. +3. conecte consumidores do core + canal/recurso + Canais e plugins de recurso devem consumir a nova capacidade por meio do core, + não importando diretamente uma implementação de fornecedor. +4. registre implementações de fornecedor + Plugins de fornecedor então registram seus backends nessa capacidade. 5. adicione cobertura de contrato - Adicione testes para que propriedade e formato de registro continuem - explícitos ao longo do tempo. + Adicione testes para que a propriedade e o formato do registro permaneçam explícitos ao longo do tempo. -É assim que o OpenClaw permanece opinativo sem ficar codificado para a visão de -mundo de um único provedor. Veja o [Capability Cookbook](/pt-BR/plugins/architecture) -para uma checklist concreta de arquivos e um exemplo completo. +É assim que o OpenClaw permanece opinativo sem ficar codificado para a visão de mundo de um +único provedor. Consulte o [Livro de receitas de capacidades](/pt-BR/plugins/architecture) +para um checklist concreto de arquivos e um exemplo prático. ### Checklist de capacidade -Quando você adiciona uma nova capacidade, a implementação normalmente deve tocar -essas superfícies juntas: +Ao adicionar uma nova capacidade, a implementação normalmente deve tocar essas +superfícies em conjunto: -- tipos de contrato central em `src//types.ts` -- runner/helper de runtime central em `src//runtime.ts` -- superfície de registro da API de plugins em `src/plugins/types.ts` -- wiring do registro de plugins em `src/plugins/registry.ts` -- exposição de runtime de plugins em `src/plugins/runtime/*` quando plugins de funcionalidade/canal precisarem consumi-la -- helpers de captura/teste em `src/test-utils/plugin-registration.ts` +- tipos de contrato do core em `src//types.ts` +- helper de runner/runtime do core em `src//runtime.ts` +- superfície de registro da API de plugin em `src/plugins/types.ts` +- integração com o registro de plugins em `src/plugins/registry.ts` +- exposição de runtime do plugin em `src/plugins/runtime/*` quando plugins de recurso/canal + precisarem consumi-la +- auxiliares de captura/teste em `src/test-utils/plugin-registration.ts` - afirmações de propriedade/contrato em `src/plugins/contracts/registry.ts` -- documentação de operador/plugin em `docs/` +- documentação para operadores/plugins em `docs/` -Se uma dessas superfícies estiver ausente, isso normalmente é um sinal de que a -capacidade ainda não está totalmente integrada. +Se uma dessas superfícies estiver ausente, isso normalmente é um sinal de que a capacidade +ainda não está totalmente integrada. ### Modelo de capacidade Padrão mínimo: ```ts -// contrato central +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API de plugin +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1705,7 +1623,7 @@ api.registerVideoGenerationProvider({ }, }); -// helper de runtime compartilhado para plugins de funcionalidade/canal +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1720,7 +1638,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Isso mantém a regra simples: -- o núcleo controla o contrato de capacidade + orquestração -- plugins de fornecedores controlam implementações de fornecedor -- plugins de funcionalidade/canal consomem helpers de runtime +- o core é responsável pelo contrato de capacidade + orquestração +- plugins de fornecedor são responsáveis pelas implementações do fornecedor +- plugins de recurso/canal consomem auxiliares de runtime - testes de contrato mantêm a propriedade explícita diff --git a/docs/pt-BR/plugins/manifest.md b/docs/pt-BR/plugins/manifest.md index 77265fc81..1bc8652f8 100644 --- a/docs/pt-BR/plugins/manifest.md +++ b/docs/pt-BR/plugins/manifest.md @@ -1,70 +1,62 @@ --- read_when: - Você está criando um plugin do OpenClaw - - Você precisa entregar um schema de configuração de plugin ou depurar erros de validação de plugin -summary: Manifesto de plugin + requisitos do schema JSON (validação estrita de configuração) -title: Manifesto de plugin + - Você precisa fornecer um schema de configuração do plugin ou depurar erros de validação do plugin +summary: Manifesto do plugin + requisitos do schema JSON (validação estrita de configuração) +title: Manifesto do plugin x-i18n: - generated_at: "2026-04-11T02:46:02Z" + generated_at: "2026-04-11T15:16:04Z" model: gpt-5.4 provider: openai - source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88 + source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 source_path: plugins/manifest.md workflow: 15 --- -# Manifesto de plugin (`openclaw.plugin.json`) +# Manifesto do plugin (`openclaw.plugin.json`) Esta página é apenas para o **manifesto nativo de plugin do OpenClaw**. -Para layouts de bundle compatíveis, veja [Plugin bundles](/pt-BR/plugins/bundles). +Para layouts de bundle compatíveis, consulte [Bundles de plugin](/pt-BR/plugins/bundles). Formatos de bundle compatíveis usam arquivos de manifesto diferentes: - 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 Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude sem manifesto - Bundle do Cursor: `.cursor-plugin/plugin.json` -O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados -em relação ao schema de `openclaw.plugin.json` descrito aqui. +O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados em relação ao schema `openclaw.plugin.json` descrito aqui. -Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle mais as -raízes de Skill declaradas, raízes de comandos do Claude, padrões de `settings.json` do bundle do Claude, -padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde -às expectativas de runtime do OpenClaw. +Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle, além das raízes de Skills declaradas, raízes de comandos do Claude, padrões de `settings.json` do bundle do Claude, padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde às expectativas de runtime do OpenClaw. -Todo plugin nativo do OpenClaw **deve** incluir um arquivo `openclaw.plugin.json` na -**raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração -**sem executar código do plugin**. Manifestos ausentes ou inválidos são tratados como -erros de plugin e bloqueiam a validação da configuração. +Todo plugin nativo do OpenClaw **deve** fornecer um arquivo `openclaw.plugin.json` na **raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração **sem executar o código do plugin**. Manifestos ausentes ou inválidos são tratados como erros de plugin e bloqueiam a validação da configuração. -Veja o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin). +Consulte o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin). Para o modelo nativo de capacidades e a orientação atual de compatibilidade externa: [Modelo de capacidades](/pt-BR/plugins/architecture#public-capability-model). ## O que este arquivo faz -`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o -código do seu plugin. +`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o código do seu plugin. Use-o para: - identidade do plugin - validação de configuração -- metadados de auth e onboarding que devem estar disponíveis sem iniciar o runtime do plugin +- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o runtime do plugin +- dicas de ativação leves que as superfícies do plano de controle podem inspecionar antes de o runtime ser carregado +- descritores de configuração leves que as superfícies de configuração/onboarding podem inspecionar antes de o runtime ser carregado - metadados de alias e autoativação que devem ser resolvidos antes de o runtime do plugin ser carregado -- metadados abreviados de posse de família de modelos que devem autoativar o - plugin antes de o runtime ser carregado -- snapshots estáticos de posse de capacidades usados para compatibilidade de bundles e cobertura de contrato -- metadados de configuração específicos de canal que devem ser mesclados nas superfícies de catálogo e validação sem carregar o runtime +- metadados abreviados de propriedade de família de modelos que devem autoativar o plugin antes de o runtime ser carregado +- snapshots estáticos de propriedade de capacidades usados para o cabeamento de compatibilidade empacotado e cobertura de contrato +- metadados de configuração específicos de canal que devem ser mesclados em superfícies de catálogo e validação sem carregar o runtime - dicas de UI de configuração Não o use para: - registrar comportamento de runtime - declarar entrypoints de código -- metadados de instalação npm +- metadados de instalação do npm Esses pertencem ao código do seu plugin e ao `package.json`. @@ -87,7 +79,7 @@ Esses pertencem ao código do seu plugin e ao `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "Plugin de provedor OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -108,19 +100,19 @@ Esses pertencem ao código do seu plugin e ao `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Chave de API do OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Chave de API do OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Chave de API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -141,58 +133,58 @@ Esses pertencem ao código do seu plugin e ao `package.json`. | Campo | Obrigatório | Tipo | O que significa | | ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Sim | `string` | ID canônico do plugin. Esse é o ID usado em `plugins.entries.`. | -| `configSchema` | Sim | `object` | JSON Schema inline para a configuração deste plugin. | -| `enabledByDefault` | Não | `true` | Marca um plugin incluído como ativado por padrão. Omita-o ou defina qualquer valor diferente de `true` para manter o plugin desativado por padrão. | +| `id` | Sim | `string` | ID canônico do plugin. Este é o ID usado em `plugins.entries.`. | +| `configSchema` | Sim | `object` | Schema JSON inline para a configuração deste plugin. | +| `enabledByDefault` | Não | `true` | Marca um plugin empacotado como habilitado por padrão. Omita-o ou defina qualquer valor diferente de `true` para deixar o plugin desabilitado por padrão. | | `legacyPluginIds` | Não | `string[]` | IDs legados que são normalizados para este ID canônico de plugin. | -| `autoEnableWhenConfiguredProviders` | Não | `string[]` | IDs de provedores que devem autoativar este plugin quando auth, configuração ou referências de modelo os mencionarem. | +| `autoEnableWhenConfiguredProviders` | Não | `string[]` | IDs de provedores que devem autoativar este plugin quando autenticação, configuração ou referências de modelo os mencionarem. | | `kind` | Não | `"memory"` \| `"context-engine"` | Declara um tipo exclusivo de plugin usado por `plugins.slots.*`. | -| `channels` | Não | `string[]` | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração. | +| `channels` | Não | `string[]` | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração. | | `providers` | Não | `string[]` | IDs de provedores pertencentes a este plugin. | -| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos de posse do manifesto usados para carregar automaticamente o plugin antes do runtime. | +| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto usados para carregar automaticamente o plugin antes do runtime. | | `cliBackends` | Não | `string[]` | IDs de backends de inferência da CLI pertencentes a este plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração. | -| `commandAliases` | Não | `object[]` | Nomes de comandos pertencentes a este plugin que devem produzir configuração sensível ao plugin e diagnósticos de CLI antes de o runtime ser carregado. | -| `providerAuthEnvVars` | Não | `Record` | Metadados simples de env de auth do provedor que o OpenClaw pode inspecionar sem carregar código do plugin. | -| `providerAuthAliases` | Não | `Record` | IDs de provedores que devem reutilizar outro ID de provedor para busca de auth, por exemplo um provedor de coding que compartilha a chave de API do provedor base e perfis de auth. | -| `channelEnvVars` | Não | `Record` | Metadados simples de env de canal que o OpenClaw pode inspecionar sem carregar código do plugin. Use isso para superfícies de configuração ou auth de canal orientadas por env que helpers genéricos de inicialização/configuração devem enxergar. | -| `providerAuthChoices` | Não | `object[]` | Metadados simples de escolhas de auth para seletores de onboarding, resolução de provedor preferido e wiring simples de flags da CLI. | -| `contracts` | Não | `object` | Snapshot estático de capacidades de bundle para fala, transcrição em tempo real, voz em tempo real, entendimento de mídia, geração de imagem, geração de música, geração de vídeo, web-fetch, busca na web e posse de ferramentas. | -| `channelConfigs` | Não | `Record` | Metadados de configuração de canal pertencentes ao manifesto mesclados nas superfícies de descoberta e validação antes de o runtime ser carregado. | +| `commandAliases` | Não | `object[]` | Nomes de comandos pertencentes a este plugin que devem produzir diagnósticos de configuração e CLI cientes do plugin antes de o runtime ser carregado. | +| `providerAuthEnvVars` | Não | `Record` | Metadados leves de variáveis de ambiente de autenticação de provedor que o OpenClaw pode inspecionar sem carregar o código do plugin. | +| `providerAuthAliases` | Não | `Record` | IDs de provedores que devem reutilizar outro ID de provedor para busca de autenticação, por exemplo, um provedor de programação que compartilha a chave de API do provedor base e perfis de autenticação. | +| `channelEnvVars` | Não | `Record` | Metadados leves de variáveis de ambiente de canal que o OpenClaw pode inspecionar sem carregar o código do plugin. Use isso para configuração de canal orientada por env ou superfícies de autenticação que helpers genéricos de inicialização/configuração devem enxergar. | +| `providerAuthChoices` | Não | `object[]` | Metadados leves de opções de autenticação para seletores de onboarding, resolução de provedor preferido e cabeamento simples de flags de CLI. | +| `activation` | Não | `object` | Dicas leves de ativação para carregamento acionado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do plugin ainda é dono do comportamento real. | +| `setup` | Não | `object` | Descritores leves de configuração/onboarding que superfícies de descoberta e configuração podem inspecionar sem carregar o runtime do plugin. | +| `contracts` | Não | `object` | Snapshot estático de capacidades empacotadas para fala, transcrição em tempo real, voz em tempo real, media-understanding, geração de imagem, geração de música, geração de vídeo, web-fetch, busca na web e propriedade de ferramentas. | +| `channelConfigs` | Não | `Record` | Metadados de configuração de canal pertencentes ao manifesto mesclados em superfícies de descoberta e validação antes de o runtime ser carregado. | | `skills` | Não | `string[]` | Diretórios de Skills para carregar, relativos à raiz do plugin. | | `name` | Não | `string` | Nome legível do plugin. | -| `description` | Não | `string` | Resumo curto mostrado nas superfícies de plugin. | +| `description` | Não | `string` | Resumo curto mostrado em superfícies de plugin. | | `version` | Não | `string` | Versão informativa do plugin. | | `uiHints` | Não | `Record` | Rótulos de UI, placeholders e dicas de sensibilidade para campos de configuração. | ## Referência de `providerAuthChoices` -Cada entrada de `providerAuthChoices` descreve uma escolha de onboarding ou auth. +Cada entrada em `providerAuthChoices` descreve uma opção de onboarding ou autenticação. O OpenClaw lê isso antes de o runtime do provedor ser carregado. -| Campo | Obrigatório | Tipo | O que significa | -| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Sim | `string` | ID do provedor ao qual esta escolha pertence. | -| `method` | Sim | `string` | ID do método de auth para o qual encaminhar. | -| `choiceId` | Sim | `string` | ID estável da escolha de auth usado pelos fluxos de onboarding e CLI. | -| `choiceLabel` | Não | `string` | Rótulo voltado ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. | -| `choiceHint` | Não | `string` | Texto auxiliar curto para o seletor. | -| `assistantPriority` | Não | `number` | Valores menores são ordenados antes em seletores interativos orientados pelo assistente. | -| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a escolha dos seletores do assistente, mas ainda permite seleção manual pela CLI. | -| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de escolha que devem redirecionar usuários para esta escolha substituta. | -| `groupId` | Não | `string` | ID opcional de grupo para agrupar escolhas relacionadas. | -| `groupLabel` | Não | `string` | Rótulo voltado ao usuário para esse grupo. | -| `groupHint` | Não | `string` | Texto auxiliar curto para o grupo. | -| `optionKey` | Não | `string` | Chave interna de opção para fluxos simples de auth com uma única flag. | -| `cliFlag` | Não | `string` | Nome da flag da CLI, como `--openrouter-api-key`. | -| `cliOption` | Não | `string` | Formato completo da opção da CLI, como `--openrouter-api-key `. | -| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. | -| `onboardingScopes` | Não | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta escolha deve aparecer. Se omitido, o padrão é `["text-inference"]`. | +| Campo | Obrigatório | Tipo | O que significa | +| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Sim | `string` | ID do provedor ao qual esta opção pertence. | +| `method` | Sim | `string` | ID do método de autenticação para encaminhamento. | +| `choiceId` | Sim | `string` | ID estável da opção de autenticação usado por fluxos de onboarding e CLI. | +| `choiceLabel` | Não | `string` | Rótulo visível ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. | +| `choiceHint` | Não | `string` | Texto curto de ajuda para o seletor. | +| `assistantPriority` | Não | `number` | Valores menores são ordenados antes em seletores interativos conduzidos pelo assistente. | +| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a opção dos seletores do assistente, mas ainda permite seleção manual pela CLI. | +| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de opções que devem redirecionar usuários para esta opção de substituição. | +| `groupId` | Não | `string` | ID opcional de grupo para agrupar opções relacionadas. | +| `groupLabel` | Não | `string` | Rótulo visível ao usuário para esse grupo. | +| `groupHint` | Não | `string` | Texto curto de ajuda para o grupo. | +| `optionKey` | Não | `string` | Chave de opção interna para fluxos simples de autenticação com uma única flag. | +| `cliFlag` | Não | `string` | Nome da flag da CLI, como `--openrouter-api-key`. | +| `cliOption` | Não | `string` | Formato completo da opção da CLI, como `--openrouter-api-key `. | +| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. | +| `onboardingScopes` | Não | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta opção deve aparecer. Se omitido, o padrão é `["text-inference"]`. | ## Referência de `commandAliases` -Use `commandAliases` quando um plugin possui um nome de comando de runtime que os usuários podem -colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw -usa esses metadados para diagnósticos sem importar código de runtime do plugin. +Use `commandAliases` quando um plugin é dono de um nome de comando de runtime que os usuários podem colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw usa esses metadados para diagnósticos sem importar o código de runtime do plugin. ```json { @@ -206,11 +198,77 @@ usa esses metadados para diagnósticos sem importar código de runtime do plugin } ``` -| Campo | Obrigatório | Tipo | O que significa | -| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | -| `name` | Sim | `string` | Nome do comando que pertence a este plugin. | +| Campo | Obrigatório | Tipo | O que significa | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ | +| `name` | Sim | `string` | Nome do comando que pertence a este plugin. | | `kind` | Não | `"runtime-slash"` | Marca o alias como um comando de barra do chat em vez de um comando raiz da CLI. | -| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a sugerir para operações na CLI, se existir. | +| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a ser sugerido para operações de CLI, se existir. | + +## Referência de `activation` + +Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle devem ativá-lo depois. + +Este bloco contém apenas metadados. Ele não registra comportamento de runtime e não substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/plugin. + +```json +{ + "activation": { + "onProviders": ["openai"], + "onCommands": ["models"], + "onChannels": ["web"], + "onRoutes": ["gateway-webhook"], + "onCapabilities": ["provider", "tool"] + } +} +``` + +| Campo | Obrigatório | Tipo | O que significa | +| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- | +| `onProviders` | Não | `string[]` | IDs de provedores que devem ativar este plugin quando solicitados. | +| `onCommands` | Não | `string[]` | IDs de comandos que devem ativar este plugin. | +| `onChannels` | Não | `string[]` | IDs de canais que devem ativar este plugin. | +| `onRoutes` | Não | `string[]` | Tipos de rota que devem ativar este plugin. | +| `onCapabilities` | Não | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Dicas amplas de capacidade usadas pelo planejamento de ativação do plano de controle. | + +## Referência de `setup` + +Use `setup` quando superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin antes de o runtime ser carregado. + +```json +{ + "setup": { + "providers": [ + { + "id": "openai", + "authMethods": ["api-key"], + "envVars": ["OPENAI_API_KEY"] + } + ], + "cliBackends": ["openai-cli"], + "configMigrations": ["legacy-openai-auth"], + "requiresRuntime": false + } +} +``` + +O `cliBackends` de nível superior continua válido e continua descrevendo backends de inferência da CLI. `setup.cliBackends` é a superfície de descritor específica de configuração para fluxos de configuração/plano de controle que devem permanecer apenas como metadados. + +### Referência de `setup.providers` + +| Campo | Obrigatório | Tipo | O que significa | +| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- | +| `id` | Sim | `string` | ID do provedor exposto durante a configuração ou onboarding. | +| `authMethods` | Não | `string[]` | IDs de métodos de configuração/autenticação que este provedor oferece sem carregar todo o runtime. | +| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o runtime do plugin ser carregado. | + +### Campos de `setup` + +| Campo | Obrigatório | Tipo | O que significa | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------ | +| `providers` | Não | `object[]` | Descritores de configuração de provedor expostos durante a configuração e o onboarding. | +| `cliBackends` | Não | `string[]` | IDs de backend disponíveis no momento da configuração sem ativação completa do runtime. | +| `configMigrations` | Não | `string[]` | IDs de migração de configuração pertencentes à superfície de configuração deste plugin. | +| `requiresRuntime` | Não | `boolean` | Se a configuração ainda precisa da execução do runtime do plugin após a busca do descritor. | ## Referência de `uiHints` @@ -220,8 +278,8 @@ usa esses metadados para diagnósticos sem importar código de runtime do plugin { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "Chave de API", + "help": "Usada para solicitações ao OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -231,19 +289,18 @@ usa esses metadados para diagnósticos sem importar código de runtime do plugin Cada dica de campo pode incluir: -| Campo | Tipo | O que significa | -| ------------- | ---------- | -------------------------------------- | -| `label` | `string` | Rótulo do campo voltado ao usuário. | -| `help` | `string` | Texto auxiliar curto. | -| `tags` | `string[]` | Tags opcionais de UI. | -| `advanced` | `boolean` | Marca o campo como avançado. | -| `sensitive` | `boolean` | Marca o campo como secreto ou sensível. | +| Campo | Tipo | O que significa | +| ------------- | ---------- | ----------------------------------------- | +| `label` | `string` | Rótulo do campo visível ao usuário. | +| `help` | `string` | Texto curto de ajuda. | +| `tags` | `string[]` | Tags opcionais da UI. | +| `advanced` | `boolean` | Marca o campo como avançado. | +| `sensitive` | `boolean` | Marca o campo como secreto ou sensível. | | `placeholder` | `string` | Texto de placeholder para entradas de formulário. | ## Referência de `contracts` -Use `contracts` apenas para metadados estáticos de posse de capacidade que o OpenClaw pode -ler sem importar o runtime do plugin. +Use `contracts` apenas para metadados estáticos de propriedade de capacidades que o OpenClaw pode ler sem importar o runtime do plugin. ```json { @@ -263,22 +320,21 @@ ler sem importar o runtime do plugin. Cada lista é opcional: -| Campo | Tipo | O que significa | -| -------------------------------- | ---------- | --------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs de provedores de fala pertencentes a este plugin. | +| Campo | Tipo | O que significa | +| -------------------------------- | ---------- | ---------------------------------------------------------------- | +| `speechProviders` | `string[]` | IDs de provedores de fala pertencentes a este plugin. | | `realtimeTranscriptionProviders` | `string[]` | IDs de provedores de transcrição em tempo real pertencentes a este plugin. | | `realtimeVoiceProviders` | `string[]` | IDs de provedores de voz em tempo real pertencentes a este plugin. | -| `mediaUnderstandingProviders` | `string[]` | IDs de provedores de entendimento de mídia pertencentes a este plugin. | +| `mediaUnderstandingProviders` | `string[]` | IDs de provedores de media-understanding pertencentes a este plugin. | | `imageGenerationProviders` | `string[]` | IDs de provedores de geração de imagem pertencentes a este plugin. | | `videoGenerationProviders` | `string[]` | IDs de provedores de geração de vídeo pertencentes a este plugin. | -| `webFetchProviders` | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin. | -| `webSearchProviders` | `string[]` | IDs de provedores de busca na web pertencentes a este plugin. | -| `tools` | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato de bundles. | +| `webFetchProviders` | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin. | +| `webSearchProviders` | `string[]` | IDs de provedores de busca na web pertencentes a este plugin. | +| `tools` | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato empacotadas. | ## Referência de `channelConfigs` -Use `channelConfigs` quando um plugin de canal precisa de metadados baratos de configuração antes -de o runtime ser carregado. +Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o runtime ser carregado. ```json { @@ -293,12 +349,12 @@ de o runtime ser carregado. }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL do homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Conexão com homeserver Matrix", "preferOver": ["matrix-legacy"] } } @@ -307,19 +363,17 @@ de o runtime ser carregado. Cada entrada de canal pode incluir: -| Campo | Tipo | O que significa | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema para `channels.`. Obrigatório para cada entrada declarada de configuração de canal. | -| `uiHints` | `Record` | Rótulos/placeholders/dicas de sensibilidade opcionais de UI para essa seção de configuração do canal. | -| `label` | `string` | Rótulo do canal mesclado às superfícies de seletor e inspeção quando os metadados de runtime não estão prontos. | -| `description` | `string` | Descrição curta do canal para superfícies de inspeção e catálogo. | -| `preferOver` | `string[]` | IDs de plugins legados ou de menor prioridade que este canal deve superar nas superfícies de seleção. | +| Campo | Tipo | O que significa | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------ | +| `schema` | `object` | Schema JSON para `channels.`. Obrigatório para cada entrada declarada de configuração de canal. | +| `uiHints` | `Record` | Rótulos/placeholders/dicas opcionais de sensibilidade da UI para essa seção de configuração de canal. | +| `label` | `string` | Rótulo do canal mesclado em superfícies de seleção e inspeção quando os metadados de runtime não estiverem prontos. | +| `description` | `string` | Descrição curta do canal para superfícies de inspeção e catálogo. | +| `preferOver` | `string[]` | IDs de plugins legados ou de menor prioridade que este canal deve superar em superfícies de seleção. | ## Referência de `modelSupport` -Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a partir de -IDs abreviados de modelo como `gpt-5.4` ou `claude-sonnet-4.6` antes de o runtime do plugin -ser carregado. +Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a partir de IDs abreviados de modelo como `gpt-5.4` ou `claude-sonnet-4.6` antes de o runtime do plugin ser carregado. ```json { @@ -332,74 +386,58 @@ ser carregado. O OpenClaw aplica esta precedência: -- referências explícitas `provider/model` usam os metadados de manifesto `providers` do proprietário +- referências explícitas `provider/model` usam os metadados de manifesto de `providers` correspondentes - `modelPatterns` têm precedência sobre `modelPrefixes` -- se um plugin não incluído e um plugin incluído corresponderem, o plugin não incluído - vence -- ambiguidades restantes são ignoradas até que o usuário ou a configuração especifique um provedor +- se um plugin não empacotado e um plugin empacotado corresponderem, o plugin não empacotado vence +- a ambiguidade restante é ignorada até que o usuário ou a configuração especifique um provedor Campos: | Campo | Tipo | O que significa | -| --------------- | ---------- | -------------------------------------------------------------------------------- | +| --------------- | ---------- | --------------------------------------------------------------------------------- | | `modelPrefixes` | `string[]` | Prefixos comparados com `startsWith` em relação a IDs abreviados de modelo. | -| `modelPatterns` | `string[]` | Sources de regex comparados com IDs abreviados de modelo após a remoção do sufixo do perfil. | +| `modelPatterns` | `string[]` | Fontes de regex comparadas com IDs abreviados de modelo após a remoção do sufixo de perfil. | -Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para -mover `speechProviders`, `realtimeTranscriptionProviders`, -`realtimeVoiceProviders`, `mediaUnderstandingProviders`, -`imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal -do manifesto não trata mais esses campos de nível superior como -posse de capacidade. +Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal do manifesto não trata mais esses campos de nível superior como propriedade de capacidade. -## Manifesto versus `package.json` +## Manifesto versus package.json -Os dois arquivos têm funções diferentes: +Os dois arquivos servem para funções diferentes: -| Arquivo | Use para | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de escolha de auth e dicas de UI que devem existir antes de o código do plugin ser executado | -| `package.json` | Metadados npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, gating de instalação, setup ou metadados de catálogo | +| Arquivo | Use para | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de opção de autenticação e dicas de UI que precisam existir antes de o código do plugin ser executado | +| `package.json` | Metadados do npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controle de instalação, configuração ou metadados de catálogo | -Se você não tiver certeza sobre onde uma parte dos metadados deve ficar, use esta regra: +Se você não tiver certeza de onde um metadado pertence, use esta regra: -- se o OpenClaw precisar conhecê-la antes de carregar o código do plugin, coloque-a em `openclaw.plugin.json` -- se for sobre empacotamento, arquivos de entrada ou comportamento de instalação npm, coloque-a em `package.json` +- se o OpenClaw precisa conhecê-lo antes de carregar o código do plugin, coloque-o em `openclaw.plugin.json` +- se ele trata de empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json` ### Campos de `package.json` que afetam a descoberta -Alguns metadados de plugin anteriores ao runtime ficam intencionalmente em `package.json` no bloco -`openclaw` em vez de `openclaw.plugin.json`. +Alguns metadados de plugin pré-runtime ficam intencionalmente em `package.json`, dentro do bloco `openclaw`, em vez de `openclaw.plugin.json`. Exemplos importantes: | Campo | O que significa | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `openclaw.extensions` | Declara entrypoints nativos de plugin. | -| `openclaw.setupEntry` | Entrypoint leve apenas para setup usado durante onboarding e inicialização adiada de canal. | -| `openclaw.channel` | Metadados simples de catálogo de canal, como rótulos, caminhos de docs, aliases e texto de seleção. | -| `openclaw.channel.configuredState` | Metadados leves de verificador de estado configurado que podem responder "já existe configuração apenas por env?" sem carregar o runtime completo do canal. | -| `openclaw.channel.persistedAuthState` | Metadados leves de verificador de auth persistida que podem responder "já existe algo autenticado?" sem carregar o runtime completo do canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins incluídos e publicados externamente. | +| `openclaw.setupEntry` | Entrypoint leve apenas para configuração usado durante o onboarding e a inicialização adiada de canal. | +| `openclaw.channel` | Metadados leves de catálogo de canal, como rótulos, caminhos de documentação, aliases e texto de seleção. | +| `openclaw.channel.configuredState` | Metadados leves do verificador de estado configurado que podem responder "a configuração apenas por env já existe?" sem carregar o runtime completo do canal. | +| `openclaw.channel.persistedAuthState` | Metadados leves do verificador de autenticação persistida que podem responder "já existe algo autenticado?" sem carregar o runtime completo do canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins empacotados e publicados externamente. | | `openclaw.install.defaultChoice` | Caminho de instalação preferido quando várias fontes de instalação estão disponíveis. | -| `openclaw.install.minHostVersion` | Versão mínima compatível do host OpenClaw, usando um piso semver como `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Permite um caminho restrito de recuperação por reinstalação de plugin incluído quando a configuração é inválida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de setup sejam carregadas antes do plugin completo do canal durante a inicialização. | +| `openclaw.install.minHostVersion` | Versão mínima compatível do host OpenClaw, usando um piso de semver como `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Permite um caminho restrito de recuperação por reinstalação de plugin empacotado quando a configuração é inválida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de configuração sejam carregadas antes do plugin completo do canal durante a inicialização. | -`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro -de manifestos. Valores inválidos são rejeitados; valores válidos, mas mais novos, ignoram o -plugin em hosts mais antigos. +`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro de manifestos. Valores inválidos são rejeitados; valores válidos, porém mais novos, fazem o plugin ser ignorado em hosts mais antigos. -`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não -torna configurações quebradas arbitrárias instaláveis. Hoje ele só permite que fluxos de instalação -se recuperem de falhas específicas e antigas de upgrade de plugin incluído, como um -caminho ausente de plugin incluído ou uma entrada antiga `channels.` para esse mesmo -plugin incluído. Erros de configuração não relacionados ainda bloqueiam a instalação e direcionam os -operadores para `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna configurações arbitrariamente quebradas instaláveis. Hoje ele permite apenas que fluxos de instalação se recuperem de falhas específicas e antigas de upgrade de plugin empacotado, como um caminho ausente de plugin empacotado ou uma entrada `channels.` antiga para esse mesmo plugin empacotado. Erros de configuração não relacionados continuam bloqueando a instalação e encaminham operadores para `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` é metadado de pacote para um pequeno módulo -de verificação: +`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador mínimo: ```json { @@ -415,12 +453,9 @@ de verificação: } ``` -Use-o quando fluxos de setup, doctor ou estado configurado precisarem de uma -sondagem barata de auth sim/não antes de o plugin completo do canal ser carregado. O export de destino deve ser uma pequena -função que leia apenas o estado persistido; não o encaminhe pelo barrel completo de runtime do canal. +Use-o quando fluxos de configuração, Doctor ou estado configurado precisarem de uma verificação barata de autenticação sim/não antes de o plugin completo do canal ser carregado. A exportação de destino deve ser uma função pequena que leia apenas o estado persistido; não a encaminhe pelo barrel completo de runtime do canal. -`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas de -estado configurado apenas por env: +`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas de estado configurado apenas por env: ```json { @@ -436,64 +471,42 @@ estado configurado apenas por env: } ``` -Use-o quando um canal puder responder ao estado configurado a partir de env ou de outras entradas pequenas -não ligadas ao runtime. Se a verificação precisar de resolução completa de configuração ou do -runtime real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin. +Use-o quando um canal puder responder ao estado configurado a partir de env ou outras entradas pequenas fora do runtime. Se a verificação precisar da resolução completa da configuração ou do runtime real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin. ## Requisitos do JSON Schema -- **Todo plugin deve incluir um JSON Schema**, mesmo que não aceite configuração. -- Um schema vazio é aceitável (por exemplo, `{ "type": "object", "additionalProperties": false }`). +- **Todo plugin deve fornecer um JSON Schema**, mesmo que não aceite nenhuma configuração. +- Um schema vazio é aceitável, por exemplo `{ "type": "object", "additionalProperties": false }`. - Os schemas são validados no momento de leitura/gravação da configuração, não em runtime. ## Comportamento de validação -- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por - um manifesto de plugin. -- `plugins.entries.`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` - devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**. -- Se um plugin estiver instalado, mas tiver um manifesto ou schema quebrado ou ausente, - a validação falhará e o Doctor relatará o erro do plugin. -- Se a configuração do plugin existir, mas o plugin estiver **desativado**, a configuração será mantida e - um **aviso** será exibido no Doctor + logs. +- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por um manifesto de plugin. +- `plugins.entries.`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**. +- Se um plugin estiver instalado, mas tiver um manifesto ou schema ausente ou com erro, a validação falha e o Doctor informa o erro do plugin. +- Se a configuração do plugin existir, mas o plugin estiver **desabilitado**, a configuração é mantida e um **aviso** é exibido no Doctor + logs. -Veja [Referência de configuração](/pt-BR/gateway/configuration) para o schema completo de `plugins.*`. +Consulte [Referência de configuração](/pt-BR/gateway/configuration) para o schema completo de `plugins.*`. ## Observações - O manifesto é **obrigatório para plugins nativos do OpenClaw**, incluindo carregamentos locais do sistema de arquivos. -- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para - descoberta + validação. -- Manifestos nativos são analisados com JSON5, então comentários, vírgulas finais e - chaves sem aspas são aceitos, desde que o valor final continue sendo um objeto. -- Apenas os campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar - chaves personalizadas de nível superior aqui. -- `providerAuthEnvVars` é o caminho de metadados simples para sondagens de auth, validação de marcadores de env - e superfícies semelhantes de auth de provedor que não devem iniciar o runtime do plugin - apenas para inspecionar nomes de env. -- `providerAuthAliases` permite que variantes de provedor reutilizem a auth de outro - provedor, incluindo env vars de auth, perfis de auth, auth baseada em configuração e escolha de onboarding por chave de API, - sem hardcoding dessa relação no core. -- `channelEnvVars` é o caminho de metadados simples para fallback por shell-env, prompts de setup - e superfícies semelhantes de canal que não devem iniciar o runtime do plugin - apenas para inspecionar nomes de env. -- `providerAuthChoices` é o caminho de metadados simples para seletores de escolha de auth, - resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags de CLI de onboarding - antes de o runtime do provedor ser carregado. Para metadados do assistente de runtime - que exigem código do provedor, veja - [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks). +- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para descoberta + validação. +- Manifestos nativos são analisados com JSON5, então comentários, vírgulas finais e chaves sem aspas são aceitos, desde que o valor final ainda seja um objeto. +- Apenas os campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar aqui chaves personalizadas de nível superior. +- `providerAuthEnvVars` é o caminho de metadados leve 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 runtime do plugin apenas para inspecionar nomes de env. +- `providerAuthAliases` permite que variantes de provedor reutilizem variáveis de ambiente de autenticação, perfis de autenticação, autenticação baseada em configuração e a opção de onboarding por chave de API de outro provedor sem codificar rigidamente esse relacionamento no core. +- `channelEnvVars` é o caminho de metadados leve para fallback de env do shell, prompts de configuração e superfícies semelhantes de canal que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env. +- `providerAuthChoices` é o caminho de metadados leve para seletores de opção de autenticação, resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags da CLI de onboarding antes de o runtime do provedor ser carregado. Para metadados de assistente de runtime que exigem código do provedor, consulte [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks). - 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` incluído). -- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um - plugin não precisa deles. -- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer - requisitos de allowlist do gerenciador de pacotes (por exemplo, `allow-build-scripts` do pnpm - - `pnpm rebuild `). + - `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 precisa deles. +- Se 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 `. ## Relacionado -- [Criando plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins -- [Plugin Architecture](/pt-BR/plugins/architecture) — arquitetura interna -- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do Plugin SDK +- [Criando Plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins +- [Arquitetura de plugins](/pt-BR/plugins/architecture) — arquitetura interna +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de plugins diff --git a/docs/pt-BR/reference/rich-output-protocol.md b/docs/pt-BR/reference/rich-output-protocol.md new file mode 100644 index 000000000..587304a8c --- /dev/null +++ b/docs/pt-BR/reference/rich-output-protocol.md @@ -0,0 +1,60 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:56Z" + model: gpt-5.4 + provider: openai + source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035 + source_path: reference/rich-output-protocol.md + workflow: 15 +--- + +# Protocolo de Saída Rica + +A saída do assistente pode incluir um pequeno conjunto de diretivas de entrega/renderização: + +- `MEDIA:` para entrega de anexos +- `[[audio_as_voice]]` para dicas de apresentação em áudio +- `[[reply_to_current]]` / `[[reply_to:]]` para metadados de resposta +- `[embed ...]` para renderização rica na Interface de Controle + +Essas diretivas são separadas. `MEDIA:` e as tags de resposta/voz continuam sendo metadados de entrega; `[embed ...]` é o caminho de renderização rica apenas para a web. + +## `[embed ...]` + +`[embed ...]` é a única sintaxe de renderização rica voltada a agentes para a Interface de Controle. + +Exemplo autocontido: + +```text +[embed ref="cv_123" title="Status" /] +``` + +Regras: + +- `[view ...]` não é mais válido para novas saídas. +- Os shortcodes de embed são renderizados apenas na superfície de mensagens do assistente. +- Apenas embeds com URL são renderizados. Use `ref="..."` ou `url="..."`. +- Shortcodes de embed em HTML inline no formato de bloco não são renderizados. +- A interface web remove o shortcode do texto visível e renderiza o embed inline. +- `MEDIA:` não é um alias de embed e não deve ser usado para renderização rica de embeds. + +## Forma de Renderização Armazenada + +O bloco de conteúdo do assistente normalizado/armazenado é um item `canvas` estruturado: + +```json +{ + "type": "canvas", + "preview": { + "kind": "canvas", + "surface": "assistant_message", + "render": "url", + "viewId": "cv_123", + "url": "/__openclaw__/canvas/documents/cv_123/index.html", + "title": "Status", + "preferredHeight": 320 + } +} +``` + +Blocos ricos armazenados/renderizados usam diretamente esta forma `canvas`. `present_view` não é reconhecido. diff --git a/docs/pt-BR/tools/video-generation.md b/docs/pt-BR/tools/video-generation.md index a062ecb63..7e28d40ba 100644 --- a/docs/pt-BR/tools/video-generation.md +++ b/docs/pt-BR/tools/video-generation.md @@ -1,35 +1,34 @@ --- read_when: - - Gerando vídeos pelo agente - - Configurando provedores e modelos de geração de vídeo - - Entendendo os parâmetros da ferramenta video_generate -summary: Gere vídeos a partir de texto, imagens ou vídeos existentes usando 12 backends de provedor -title: Geração de vídeo + - Gerando vídeos por meio do agente + - Configurando provedores e modelos de geração de vídeos + - Entendendo os parâmetros da ferramenta `video_generate` +summary: Gere vídeos a partir de texto, imagens ou vídeos existentes usando 14 backends de provedores +title: Geração de vídeos x-i18n: - generated_at: "2026-04-11T02:47:58Z" + generated_at: "2026-04-11T15:16:05Z" model: gpt-5.4 provider: openai - source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245 + source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263 source_path: tools/video-generation.md workflow: 15 --- -# Geração de vídeo +# Geração de vídeos -Agentes do OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou vídeos existentes. Há suporte para doze backends de provedor, cada um com diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe automaticamente o provedor correto com base na sua configuração e nas chaves de API disponíveis. +Agentes OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou vídeos existentes. Há suporte para quatorze backends de provedores, cada um com diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe automaticamente o provedor certo com base na sua configuração e nas chaves de API disponíveis. -A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo está disponível. Se você não a vir nas ferramentas do seu agente, defina uma chave de API do provedor ou configure `agents.defaults.videoGenerationModel`. +A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo está disponível. Se você não a vir nas ferramentas do seu agente, defina uma chave de API de provedor ou configure `agents.defaults.videoGenerationModel`. -O OpenClaw trata a geração de vídeo como três modos de runtime: +O OpenClaw trata a geração de vídeos como três modos de execução: - `generate` para solicitações de texto para vídeo sem mídia de referência - `imageToVideo` quando a solicitação inclui uma ou mais imagens de referência - `videoToVideo` quando a solicitação inclui um ou mais vídeos de referência -Os provedores podem oferecer suporte a qualquer subconjunto desses modos. A ferramenta valida o -modo ativo antes do envio e informa os modos compatíveis em `action=list`. +Os provedores podem oferecer suporte a qualquer subconjunto desses modos. A ferramenta valida o modo ativo antes do envio e informa os modos compatíveis em `action=list`. ## Início rápido @@ -49,20 +48,20 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 > Gere um vídeo cinematográfico de 5 segundos de uma lagosta amigável surfando ao pôr do sol. -O agente chama `video_generate` automaticamente. Nenhuma allowlist de ferramenta é necessária. +O agente chama `video_generate` automaticamente. Nenhuma allowlist de ferramentas é necessária. ## O que acontece quando você gera um vídeo -A geração de vídeo é assíncrona. Quando o agente chama `video_generate` em uma sessão: +A geração de vídeos é assíncrona. Quando o agente chama `video_generate` em uma sessão: 1. O OpenClaw envia a solicitação ao provedor e retorna imediatamente um ID de tarefa. -2. O provedor processa o job em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução). -3. Quando o vídeo fica pronto, o OpenClaw reativa a mesma sessão com um evento interno de conclusão. +2. O provedor processa o trabalho em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução). +3. Quando o vídeo está pronto, o OpenClaw reativa a mesma sessão com um evento interno de conclusão. 4. O agente publica o vídeo finalizado de volta na conversa original. -Enquanto um job estiver em andamento, chamadas duplicadas de `video_generate` na mesma sessão retornam o status atual da tarefa em vez de iniciar outra geração. Use `openclaw tasks list` ou `openclaw tasks show ` para verificar o progresso pela CLI. +Enquanto um trabalho está em andamento, chamadas duplicadas de `video_generate` na mesma sessão retornam o status atual da tarefa em vez de iniciar outra geração. Use `openclaw tasks list` ou `openclaw tasks show ` para verificar o progresso pela CLI. -Fora de execuções de agente com suporte a sessão (por exemplo, invocações diretas de ferramenta), a ferramenta recorre à geração inline e retorna o caminho final da mídia no mesmo turno. +Fora de execuções de agente com suporte de sessão (por exemplo, invocações diretas da ferramenta), a ferramenta recorre à geração inline e retorna o caminho final da mídia no mesmo turno. ### Ciclo de vida da tarefa @@ -70,8 +69,8 @@ Cada solicitação `video_generate` passa por quatro estados: 1. **queued** -- tarefa criada, aguardando o provedor aceitá-la. 2. **running** -- o provedor está processando (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução). -3. **succeeded** -- vídeo pronto; o agente é reativado e o publica na conversa. -4. **failed** -- erro do provedor ou timeout; o agente é reativado com detalhes do erro. +3. **succeeded** -- vídeo pronto; o agente reativa e o publica na conversa. +4. **failed** -- erro do provedor ou tempo limite; o agente reativa com detalhes do erro. Verifique o status pela CLI: @@ -81,118 +80,138 @@ openclaw tasks show openclaw tasks cancel ``` -Prevenção de duplicatas: se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual, `video_generate` retornará o status da tarefa existente em vez de iniciar uma nova. Use `action: "status"` para verificar explicitamente sem disparar uma nova geração. +Prevenção de duplicatas: se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual, `video_generate` retorna o status da tarefa existente em vez de iniciar uma nova. Use `action: "status"` para verificar explicitamente sem acionar uma nova geração. ## Provedores compatíveis -| Provedor | Modelo padrão | Texto | Imagem ref | Vídeo ref | Chave de API | -| -------- | ------------------------------ | ----- | ----------------- | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | Sim | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | Sim | 1 imagem | Não | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Sim | 1 imagem | Não | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Sim | 1 imagem | Não | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview`| Sim | 1 imagem | 1 vídeo | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Sim | 1 imagem | Não | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Sim | 1 imagem | 1 vídeo | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Sim | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Sim | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sim | 1 imagem | Não | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Sim | 1 imagem (`kling`)| Não | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Sim | 1 imagem | 1 vídeo | `XAI_API_KEY` | +| Provedor | Modelo padrão | Texto | Imagem de referência | Vídeo de referência | Chave de API | +| --------------------- | ------------------------------- | ----- | ----------------------------------------------------- | ------------------- | ----------------------------------------- | +| Alibaba | `wan2.6-t2v` | Sim | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | Sim | Até 2 imagens (apenas modelos I2V; primeiro + último quadro) | Não | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Sim | Até 2 imagens (primeiro + último quadro via função) | Não | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Sim | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Sim | 1 imagem | Não | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Sim | 1 imagem | Não | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Sim | 1 imagem | 1 vídeo | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Sim | 1 imagem | Não | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Sim | 1 imagem | 1 vídeo | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Sim | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Sim | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sim | 1 imagem | Não | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Sim | 1 imagem (`kling`) | Não | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Sim | 1 imagem | 1 vídeo | `XAI_API_KEY` | -Alguns provedores aceitam variáveis de ambiente adicionais ou alternativas para chave de API. Consulte as [páginas de provedor](#related) individuais para obter detalhes. +Alguns provedores aceitam variáveis de ambiente adicionais ou alternativas para a chave de API. Consulte as [páginas individuais dos provedores](#related) para obter detalhes. -Execute `video_generate action=list` para inspecionar provedores, modelos e -modos de runtime disponíveis em tempo de execução. +Execute `video_generate action=list` para inspecionar os provedores, modelos e modos de execução disponíveis em tempo de execução. -### Matriz de capacidades declaradas +### Matriz de capacidades declarada -Este é o contrato explícito de modo usado por `video_generate`, testes de contrato -e a varredura live compartilhada. +Este é o contrato explícito de modo usado por `video_generate`, testes de contrato e a varredura live compartilhada. -| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Lanes live compartilhadas atualmente | -| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo remotas `http(s)` | -| BytePlus | Sim | Sim | Não | `generate`, `imageToVideo` | +| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Lanes live compartilhadas atualmente | +| -------- | ---------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor exige URLs de vídeo remotas `http(s)` | +| BytePlus | Sim | Sim | Não | `generate`, `imageToVideo` | | ComfyUI | Sim | Sim | Não | Não está na varredura compartilhada; a cobertura específica de workflow fica com os testes do Comfy | -| fal | Sim | Sim | Não | `generate`, `imageToVideo` | +| fal | Sim | Sim | Não | `generate`, `imageToVideo` | | Google | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura Gemini/Veo atual com buffer não aceita essa entrada | -| MiniMax | Sim | Sim | Não | `generate`, `imageToVideo` | -| OpenAI | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho atual de organização/entrada precisa de acesso a inpaint/remix do lado do provedor | -| Qwen | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo remotas `http(s)` | -| Runway | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` roda apenas quando o modelo selecionado é `runway/gen4_aleph` | -| Together | Sim | Sim | Não | `generate`, `imageToVideo` | +| MiniMax | Sim | Sim | Não | `generate`, `imageToVideo` | +| OpenAI | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente exige acesso a inpaint/remix do lado do provedor | +| Qwen | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor exige URLs de vídeo remotas `http(s)` | +| Runway | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` só é executado quando o modelo selecionado é `runway/gen4_aleph` | +| Together | Sim | Sim | Não | `generate`, `imageToVideo` | | Vydra | Sim | Sim | Não | `generate`; `imageToVideo` compartilhado ignorado porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL de imagem remota | -| xAI | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente precisa de uma URL MP4 remota | +| xAI | Sim | Sim | Sim | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente exige uma URL MP4 remota | ## Parâmetros da ferramenta -### Obrigatório +### Obrigatórios -| Parâmetro | Tipo | Descrição | -| --------- | ------ | ----------------------------------------------------------------------------- | -| `prompt` | string | Descrição em texto do vídeo a ser gerado (obrigatório para `action: "generate"`) | +| Parâmetro | Tipo | Descrição | +| --------- | ------ | ---------------------------------------------------------------------------- | +| `prompt` | string | Descrição em texto do vídeo a ser gerado (obrigatória para `action: "generate"`) | ### Entradas de conteúdo -| Parâmetro | Tipo | Descrição | -| --------- | -------- | ------------------------------------- | -| `image` | string | Imagem única de referência (caminho ou URL) | -| `images` | string[] | Várias imagens de referência (até 5) | -| `video` | string | Vídeo único de referência (caminho ou URL) | -| `videos` | string[] | Vários vídeos de referência (até 4) | +| Parâmetro | Tipo | Descrição | +| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `image` | string | Imagem de referência única (caminho ou URL) | +| `images` | string[] | Múltiplas imagens de referência (até 9) | +| `imageRoles`| string[] | Dicas opcionais de função por posição paralelas à lista combinada de imagens. Valores canônicos: `first_frame`, `last_frame`, `reference_image` | +| `video` | string | Vídeo de referência único (caminho ou URL) | +| `videos` | string[] | Múltiplos vídeos de referência (até 4) | +| `videoRoles`| string[] | Dicas opcionais de função por posição paralelas à lista combinada de vídeos. Valor canônico: `reference_video` | +| `audioRef` | string | Áudio de referência único (caminho ou URL). Usado, por exemplo, para música de fundo ou referência de voz quando o provedor oferece suporte a entradas de áudio | +| `audioRefs` | string[] | Múltiplos áudios de referência (até 3) | +| `audioRoles`| string[] | Dicas opcionais de função por posição paralelas à lista combinada de áudios. Valor canônico: `reference_audio` | + +As dicas de função são encaminhadas ao provedor como estão. Os valores canônicos vêm da união `VideoGenerationAssetRole`, mas os provedores podem aceitar strings de função adicionais. Os arrays `*Roles` não devem ter mais entradas do que a lista de referência correspondente; erros de contagem recebem uma mensagem clara. Use uma string vazia para deixar uma posição sem definir. ### Controles de estilo -| Parâmetro | Tipo | Descrição | -| ---------------- | ------- | ------------------------------------------------------------------------ | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | `480P`, `720P`, `768P` ou `1080P` | +| Parâmetro | Tipo | Descrição | +| ---------------- | ------- | ------------------------------------------------------------------------------------ | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` ou `adaptive` | +| `resolution` | string | `480P`, `720P`, `768P` ou `1080P` | | `durationSeconds`| number | Duração alvo em segundos (arredondada para o valor compatível mais próximo do provedor) | -| `size` | string | Dica de tamanho quando o provedor oferece suporte | -| `audio` | boolean | Habilita áudio gerado quando houver suporte | -| `watermark` | boolean | Ativa/desativa marca d'água do provedor quando houver suporte | +| `size` | string | Dica de tamanho quando o provedor oferece suporte a isso | +| `audio` | boolean | Ativa o áudio gerado na saída quando compatível. Diferente de `audioRef*` (entradas) | +| `watermark` | boolean | Ativa ou desativa a marca d'água do provedor quando compatível | + +`adaptive` é um valor sentinela específico do provedor: ele é encaminhado como está para provedores que declaram `adaptive` em suas capacidades (por exemplo, o BytePlus Seedance o usa para detectar automaticamente a proporção com base nas dimensões da imagem de entrada). Provedores que não o declaram expõem o valor por meio de `details.ignoredOverrides` no resultado da ferramenta para que a omissão fique visível. ### Avançado -| Parâmetro | Tipo | Descrição | -| --------- | ------ | -------------------------------------------------- | -| `action` | string | `"generate"` (padrão), `"status"` ou `"list"` | -| `model` | string | Substituição de provedor/modelo (por exemplo, `runway/gen4.5`) | -| `filename`| string | Dica para nome do arquivo de saída | +| Parâmetro | Tipo | Descrição | +| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `action` | string | `"generate"` (padrão), `"status"` ou `"list"` | +| `model` | string | Sobrescrita de provedor/modelo (por exemplo, `runway/gen4.5`) | +| `filename` | string | Dica de nome de arquivo de saída | +| `providerOptions`| object | Opções específicas do provedor como um objeto JSON (por exemplo, `{"seed": 42, "draft": true}`). Provedores que declaram um esquema tipado validam as chaves e os tipos; chaves desconhecidas ou incompatibilidades fazem com que o candidato seja ignorado durante o fallback. Provedores sem um esquema declarado recebem as opções como estão. Execute `video_generate action=list` para ver o que cada provedor aceita | -Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw já normaliza a duração para o valor compatível mais próximo do provedor e também remapeia dicas de geometria traduzidas, como size para aspect ratio, quando um provedor de fallback expõe uma superfície de controle diferente. Substituições realmente sem suporte são ignoradas no melhor esforço e informadas como avisos no resultado da ferramenta. Limites rígidos de capacidade, como entradas de referência em excesso, falham antes do envio. +Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw já normaliza a duração para o valor compatível mais próximo do provedor e também remapeia dicas de geometria traduzidas, como tamanho para proporção, quando um provedor de fallback expõe uma superfície de controle diferente. Sobrescritas realmente não compatíveis são ignoradas em regime de melhor esforço e relatadas como avisos no resultado da ferramenta. Limites rígidos de capacidade, como entradas de referência demais, falham antes do envio. -Os resultados da ferramenta informam as configurações aplicadas. Quando o OpenClaw remapeia duração ou geometria durante o fallback de provedor, os valores retornados de `durationSeconds`, `size`, `aspectRatio` e `resolution` refletem o que foi enviado, e `details.normalization` registra a tradução do solicitado para o aplicado. +Os resultados da ferramenta informam as configurações aplicadas. Quando o OpenClaw remapeia duração ou geometria durante o fallback do provedor, os valores retornados de `durationSeconds`, `size`, `aspectRatio` e `resolution` refletem o que foi enviado, e `details.normalization` captura a tradução do solicitado para o aplicado. -As entradas de referência também selecionam o modo de runtime: +As entradas de referência também selecionam o modo de execução: - Sem mídia de referência: `generate` - Qualquer imagem de referência: `imageToVideo` - Qualquer vídeo de referência: `videoToVideo` +- Entradas de áudio de referência não alteram o modo resolvido; elas se aplicam sobre o modo que as referências de imagem/vídeo selecionarem e só funcionam com provedores que declaram `maxInputAudios` -Referências mistas de imagem e vídeo não formam uma superfície compartilhada de capacidade estável. +Referências mistas de imagem e vídeo não são uma superfície de capacidade compartilhada estável. Prefira um tipo de referência por solicitação. +#### Fallback e opções tipadas + +Algumas verificações de capacidade são aplicadas na camada de fallback, e não no limite da ferramenta, para que uma solicitação que exceda os limites do provedor principal ainda possa ser executada em um fallback compatível: + +- Se o candidato ativo não declarar `maxInputAudios` (ou o declarar como `0`), ele será ignorado quando a solicitação contiver referências de áudio, e o próximo candidato será tentado. +- Se `maxDurationSeconds` do candidato ativo for menor que `durationSeconds` solicitado e o candidato não declarar uma lista `supportedDurationSeconds`, ele será ignorado. +- Se a solicitação contiver `providerOptions` e o candidato ativo declarar explicitamente um esquema tipado de `providerOptions`, o candidato será ignorado quando as chaves fornecidas não estiverem no esquema ou quando os tipos dos valores não corresponderem. Provedores que ainda não declararam um esquema recebem as opções como estão (pass-through compatível com versões anteriores). Um provedor pode desativar explicitamente todas as opções de provedor declarando um esquema vazio (`capabilities.providerOptions: {}`), o que causa a mesma omissão que uma incompatibilidade de tipo. + +O primeiro motivo de omissão em uma solicitação é registrado em `warn` para que os operadores vejam quando seu provedor principal foi ignorado; omissões posteriores são registradas em `debug` para manter silenciosas cadeias longas de fallback. Se todos os candidatos forem ignorados, o erro agregado inclui o motivo da omissão de cada um. + ## Ações -- **generate** (padrão) -- cria um vídeo a partir do prompt fornecido e entradas de referência opcionais. -- **status** -- verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. +- **generate** (padrão) -- cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais. +- **status** -- verifica o estado da tarefa de vídeo em andamento da sessão atual sem iniciar outra geração. - **list** -- mostra provedores, modelos e suas capacidades disponíveis. ## Seleção de modelo Ao gerar um vídeo, o OpenClaw resolve o modelo nesta ordem: -1. **Parâmetro `model` da ferramenta** -- se o agente especificar um na chamada. -2. **`videoGenerationModel.primary`** -- vindo da configuração. +1. **Parâmetro de ferramenta `model`** -- se o agente especificar um na chamada. +2. **`videoGenerationModel.primary`** -- da configuração. 3. **`videoGenerationModel.fallbacks`** -- tentados em ordem. -4. **Detecção automática** -- usa provedores que têm autenticação válida, começando pelo provedor padrão atual e depois pelos provedores restantes em ordem alfabética. +4. **Detecção automática** -- usa provedores que têm autenticação válida, começando pelo provedor padrão atual e depois os provedores restantes em ordem alfabética. Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos os candidatos falharem, o erro incluirá detalhes de cada tentativa. -Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` se você quiser -que a geração de vídeo use apenas as entradas explícitas de `model`, `primary` e `fallbacks`. +Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` se quiser que a geração de vídeos use apenas as entradas explícitas `model`, `primary` e `fallbacks`. ```json5 { @@ -207,56 +226,28 @@ que a geração de vídeo use apenas as entradas explícitas de `model`, `primar } ``` -O agente de vídeo da HeyGen no fal pode ser fixado com: - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/fal-ai/heygen/v2/video-agent", - }, - }, - }, -} -``` - -O Seedance 2.0 no fal pode ser fixado com: - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/text-to-video", - }, - }, - }, -} -``` - ## Observações sobre provedores -| Provedor | Observações | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Usa o endpoint assíncrono do DashScope/Model Studio. Imagens e vídeos de referência precisam ser URLs remotas `http(s)`. | -| BytePlus | Apenas uma imagem de referência. | -| ComfyUI | Execução local ou em nuvem orientada por workflow. Oferece suporte a texto para vídeo e imagem para vídeo por meio do grafo configurado. | -| fal | Usa fluxo com fila para jobs de longa duração. Apenas uma imagem de referência. Inclui refs de modelo HeyGen video-agent e Seedance 2.0 para texto para vídeo e imagem para vídeo. | -| Google | Usa Gemini/Veo. Oferece suporte a uma imagem ou um vídeo de referência. | -| MiniMax | Apenas uma imagem de referência. | -| OpenAI | Apenas a substituição de `size` é encaminhada. Outras substituições de estilo (`aspectRatio`, `resolution`, `audio`, `watermark`) são ignoradas com um aviso. | -| Qwen | Mesmo backend DashScope do Alibaba. Entradas de referência precisam ser URLs remotas `http(s)`; arquivos locais são rejeitados antecipadamente. | -| Runway | Oferece suporte a arquivos locais por meio de URIs de dados. Vídeo para vídeo exige `runway/gen4_aleph`. Execuções somente com texto expõem proporções `16:9` e `9:16`. | -| Together | Apenas uma imagem de referência. | -| Vydra | Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos que descartam autenticação. `veo3` é empacotado apenas como texto para vídeo; `kling` exige uma URL remota de imagem. | -| xAI | Oferece suporte a fluxos de texto para vídeo, imagem para vídeo e edição/extensão de vídeo remoto. | +| Provedor | Observações | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Usa o endpoint assíncrono do DashScope/Model Studio. Imagens e vídeos de referência devem ser URLs remotas `http(s)`. | +| BytePlus (1.0) | ID do provedor `byteplus`. Modelos: `seedance-1-0-pro-250528` (padrão), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Modelos T2V (`*-t2v-*`) não aceitam entradas de imagem; modelos I2V e modelos gerais `*-pro-*` oferecem suporte a uma única imagem de referência (primeiro quadro). Passe a imagem posicionalmente ou defina `role: "first_frame"`. IDs de modelo T2V são alternados automaticamente para a variante I2V correspondente quando uma imagem é fornecida. Chaves `providerOptions` compatíveis: `seed` (number), `draft` (boolean, força 480p), `camera_fixed` (boolean). | +| BytePlus Seedance 1.5 | Requer o plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID do provedor `byteplus-seedance15`. Modelo: `seedance-1-5-pro-251215`. Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens de entrada (`first_frame` + `last_frame`). Todas as entradas devem ser URLs remotas `https://`. Defina `role: "first_frame"` / `"last_frame"` em cada imagem ou passe as imagens posicionalmente. `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada. `audio: true` é mapeado para `generate_audio`. `providerOptions.seed` (number) é encaminhado. | +| BytePlus Seedance 2.0 | Requer o plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID do provedor `byteplus-seedance2`. Modelos: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de referência, 3 vídeos de referência e 3 áudios de referência. Todas as entradas devem ser URLs remotas `https://`. Defina `role` em cada asset — valores compatíveis: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada. `audio: true` é mapeado para `generate_audio`. `providerOptions.seed` (number) é encaminhado. | +| ComfyUI | Execução local ou na nuvem orientada por workflow. Oferece suporte a texto para vídeo e imagem para vídeo por meio do grafo configurado. | +| fal | Usa fluxo com fila para trabalhos de longa duração. Apenas uma única imagem de referência. | +| Google | Usa Gemini/Veo. Oferece suporte a uma imagem ou um vídeo de referência. | +| MiniMax | Apenas uma única imagem de referência. | +| OpenAI | Apenas a sobrescrita `size` é encaminhada. Outras sobrescritas de estilo (`aspectRatio`, `resolution`, `audio`, `watermark`) são ignoradas com um aviso. | +| Qwen | Mesmo backend DashScope do Alibaba. Entradas de referência devem ser URLs remotas `http(s)`; arquivos locais são rejeitados antecipadamente. | +| Runway | Oferece suporte a arquivos locais por meio de URIs de dados. Vídeo para vídeo requer `runway/gen4_aleph`. Execuções somente com texto expõem proporções `16:9` e `9:16`. | +| Together | Apenas uma única imagem de referência. | +| Vydra | Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos que descartam a autenticação. `veo3` vem empacotado apenas como texto para vídeo; `kling` exige uma URL de imagem remota. | +| xAI | Oferece suporte a fluxos de texto para vídeo, imagem para vídeo e edição/extensão de vídeo remoto. | ## Modos de capacidade do provedor -O contrato compartilhado de geração de vídeo agora permite que provedores declarem -capacidades específicas por modo em vez de apenas limites agregados planos. Novas -implementações de provedor devem preferir blocos explícitos por modo: +O contrato compartilhado de geração de vídeos agora permite que os provedores declarem capacidades específicas por modo em vez de apenas limites agregados fixos. Novas implementações de provedores devem preferir blocos de modo explícitos: ```typescript capabilities: { @@ -280,15 +271,11 @@ capabilities: { } ``` -Campos agregados planos como `maxInputImages` e `maxInputVideos` não -são suficientes para anunciar suporte a modo de transformação. Os provedores devem declarar -`generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes live, -testes de contrato e a ferramenta compartilhada `video_generate` possam validar o suporte a modo -de forma determinística. +Campos agregados fixos como `maxInputImages` e `maxInputVideos` não são suficientes para anunciar suporte ao modo de transformação. Os provedores devem declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes live, testes de contrato e a ferramenta compartilhada `video_generate` possam validar o suporte ao modo de forma determinística. ## Testes live -Cobertura live opt-in para os provedores empacotados compartilhados: +Cobertura live opt-in para os provedores compartilhados empacotados: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -300,22 +287,19 @@ Wrapper do repositório: pnpm test:live:media video ``` -Este arquivo live carrega variáveis de ambiente ausentes de provedor a partir de `~/.profile`, prioriza -chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa os -modos declarados que consegue exercitar com segurança com mídia local: +Este arquivo live carrega variáveis de ambiente ausentes do provedor a partir de `~/.profile`, prioriza chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa os modos declarados que consegue exercitar com segurança usando mídia local: -- `generate` para todo provedor na varredura +- `generate` para todos os provedores na varredura - `imageToVideo` quando `capabilities.imageToVideo.enabled` -- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o provedor/modelo - aceita entrada de vídeo local com buffer na varredura compartilhada +- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o provedor/modelo aceita entrada de vídeo local com buffer na varredura compartilhada -Hoje a lane live compartilhada `videoToVideo` cobre: +Atualmente, a lane live compartilhada `videoToVideo` cobre: -- `runway` apenas quando você seleciona `runway/gen4_aleph` +- `runway` somente quando você seleciona `runway/gen4_aleph` ## Configuração -Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw: +Defina o modelo padrão de geração de vídeos na sua configuração do OpenClaw: ```json5 { @@ -330,7 +314,7 @@ Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw } ``` -Ou pela CLI: +Ou via CLI: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v" @@ -339,7 +323,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Relacionado - [Visão geral das ferramentas](/pt-BR/tools) -- [Tarefas em segundo plano](/pt-BR/automation/tasks) -- rastreamento de tarefas para geração assíncrona de vídeo +- [Tarefas em segundo plano](/pt-BR/automation/tasks) -- rastreamento de tarefas para geração assíncrona de vídeos - [Alibaba Model Studio](/pt-BR/providers/alibaba) - [BytePlus](/pt-BR/concepts/model-providers#byteplus-international) - [ComfyUI](/pt-BR/providers/comfy)