diff --git a/docs/pt-BR/ci.md b/docs/pt-BR/ci.md index 2101fc2b8..87f18b2ae 100644 --- a/docs/pt-BR/ci.md +++ b/docs/pt-BR/ci.md @@ -1,81 +1,82 @@ --- read_when: - - Você precisa entender por que um job de CI foi ou não foi executado - - Você está depurando verificações com falha no GitHub Actions -summary: Grafo de jobs de CI, gates de escopo e equivalentes de comandos locais + - Você precisa entender por que um job de CI foi ou não executado + - Você está depurando verificações do GitHub Actions com falha +summary: Grafo de jobs de CI, portões de escopo e equivalentes de comandos locais title: Pipeline de CI x-i18n: - generated_at: "2026-04-22T04:21:12Z" + generated_at: "2026-04-22T05:34:47Z" model: gpt-5.4 provider: openai - source_hash: ae08bad6cbd0f2eced6c88a792a11bc1c2b1a2bfb003a56f70ff328a2739d3fc + source_hash: fc7ec59123aee65634736320dbf1cf5cdfb08786a78cca82ce9596fedc68b3cc source_path: ci.md workflow: 15 --- # Pipeline de CI -A CI é executada em cada push para `main` e em todo pull request. Ela usa escopo inteligente para pular jobs caros quando apenas áreas não relacionadas foram alteradas. +A CI é executada em cada push para `main` e em cada pull request. Ela usa escopo inteligente para pular jobs caros quando apenas áreas não relacionadas foram alteradas. ## Visão geral dos jobs -| Job | Finalidade | Quando é executado | +| Job | Finalidade | Quando é executado | | -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | -| `preflight` | Detectar alterações somente em docs, escopos alterados, extensões alteradas e montar o manifesto de CI | Sempre em pushes e PRs que não são draft | -| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não são draft | -| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra advisories do npm | Sempre em pushes e PRs que não são draft | -| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não são draft | -| `build-artifacts` | Compilar `dist/` e a UI de controle uma vez, enviar artefatos reutilizáveis para jobs downstream | Alterações relevantes para Node | -| `checks-fast-core` | Lanes rápidas de verificação no Linux, como verificações de plugin incluído/contrato de plugin/protocolo | Alterações relevantes para Node | -| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canal com um resultado agregado estável | Alterações relevantes para Node | -| `checks-node-extensions` | Shards completos de teste de plugin incluído em toda a suíte de extensões | Alterações relevantes para Node | -| `checks-node-core-test` | Shards de testes centrais de Node, excluindo canais, plugins incluídos, contratos e lanes de extensões | Alterações relevantes para Node | -| `extension-fast` | Testes focados apenas nos plugins incluídos alterados | Quando alterações em extensões são detectadas | -| `check` | Equivalente principal local fragmentado: tipos de prod, lint, guardas, tipos de teste e smoke estrito | Alterações relevantes para Node | -| `check-additional` | Guardas de arquitetura, limites, superfície de extensões, limites de pacote e shards de gateway-watch | Alterações relevantes para Node | +| `preflight` | Detectar alterações somente em docs, escopos alterados, extensões alteradas e gerar o manifesto de CI | Sempre em pushes e PRs não draft | +| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs não draft | +| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs não draft | +| `security-fast` | Agregador obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs não draft | +| `build-artifacts` | Gerar `dist/` e a Control UI uma vez, enviar artefatos reutilizáveis para jobs downstream | Alterações relevantes para Node | +| `checks-fast-core` | Lanes rápidos de correção no Linux, como verificações de bundled/plugin-contract/protocol | Alterações relevantes para Node | +| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canais com um resultado agregado estável | Alterações relevantes para Node | +| `checks-node-extensions` | Shards completos de testes de plugins empacotados em toda a suíte de extensões | Alterações relevantes para Node | +| `checks-node-core-test` | Shards de testes do core em Node, excluindo lanes de canais, bundled, contratos e extensões | Alterações relevantes para Node | +| `extension-fast` | Testes focados apenas nos plugins empacotados alterados | Quando alterações em extensões são detectadas | +| `check` | Equivalente principal local fragmentado: tipos de produção, lint, guards, tipos de teste e smoke estrito | Alterações relevantes para Node | +| `check-additional` | Guards de arquitetura, boundaries, superfícies de extensões, boundary de pacotes e shards de gateway-watch | Alterações relevantes para Node | | `build-smoke` | Testes smoke da CLI compilada e smoke de memória na inicialização | Alterações relevantes para Node | -| `checks` | Lanes Linux Node restantes: testes de canal e compatibilidade Node 22 somente para push | Alterações relevantes para Node | -| `check-docs` | Formatação, lint e verificação de links quebrados na documentação | Quando docs forem alteradas | +| `checks` | Lanes Linux Node restantes: testes de canais e compatibilidade push-only com Node 22 | Alterações relevantes para Node | +| `check-docs` | Formatação, lint e verificação de links quebrados da documentação | Docs alteradas | | `skills-python` | Ruff + pytest para Skills com backend em Python | Alterações relevantes para Skills em Python | | `checks-windows` | Lanes de teste específicas do Windows | Alterações relevantes para Windows | -| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos compilados compartilhados | Alterações relevantes para macOS | -| `macos-swift` | Lint, build e testes Swift para o app macOS | Alterações relevantes para macOS | +| `macos-node` | Lane de teste TypeScript no macOS usando os artefatos compilados compartilhados | Alterações relevantes para macOS | +| `macos-swift` | Lint, build e testes em Swift para o app macOS | Alterações relevantes para macOS | | `android` | Matriz de build e testes do Android | Alterações relevantes para Android | ## Ordem de fail-fast -Os jobs são ordenados para que verificações baratas falhem antes de as caras serem executadas: +Os jobs são ordenados para que verificações baratas falhem antes da execução das mais caras: -1. `preflight` decide quais lanes existem de fato. A lógica de `docs-scope` e `changed-scope` são etapas dentro deste job, não jobs independentes. +1. `preflight` decide quais lanes existem. A lógica `docs-scope` e `changed-scope` são etapas dentro desse job, não jobs independentes. 2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar os jobs mais pesados de artefatos e matriz de plataforma. -3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto. -4. Depois disso, as lanes mais pesadas de plataforma e runtime se expandem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. +3. `build-artifacts` se sobrepõe aos lanes rápidos de Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto. +4. Depois disso, os lanes mais pesados de plataforma e runtime se distribuem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. A lógica de escopo fica em `scripts/ci-changed-scope.mjs` e é coberta por testes unitários em `src/scripts/ci-changed-scope.test.ts`. -O workflow separado `install-smoke` reutiliza o mesmo script de escopo por meio do seu próprio job `preflight`. Ele calcula `run_install_smoke` a partir do sinal mais restrito de smoke alterado, então o smoke de Docker/instalação só é executado para alterações relevantes de instalação, empacotamento e contêiner. +O workflow separado `install-smoke` reutiliza o mesmo script de escopo por meio do próprio job `preflight`. Ele calcula `run_install_smoke` a partir do sinal mais restrito `changed-smoke`, então o smoke de Docker/install só é executado para alterações relevantes de instalação, empacotamento e containers. -A lógica local de lanes alteradas fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate local é mais rigoroso quanto aos limites de arquitetura do que o amplo escopo de plataforma da CI: alterações de produção no core executam typecheck de produção do core mais testes do core, alterações somente em testes do core executam apenas typecheck/testes de testes do core, alterações de produção em extensões executam typecheck de produção de extensões mais testes de extensões, e alterações somente em testes de extensões executam apenas typecheck/testes de testes de extensões. Alterações no SDK público de Plugin ou no contrato de plugin expandem para validação de extensões porque as extensões dependem desses contratos centrais. Bumps de versão somente em metadados de release executam verificações direcionadas de versão/configuração/dependências de raiz. Alterações desconhecidas na raiz/configuração falham para o modo seguro em todas as lanes. +A lógica local de lanes alterados fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate local é mais rigoroso quanto a boundaries de arquitetura do que o escopo amplo de plataforma da CI: alterações de produção no core executam typecheck de produção do core mais testes do core, alterações apenas em testes do core executam somente typecheck/testes de teste do core, alterações de produção em extensões executam typecheck de produção de extensões mais testes de extensões, e alterações apenas em testes de extensões executam somente typecheck/testes de teste de extensões. Alterações no Plugin SDK público ou em plugin-contract expandem para validação de extensões porque as extensões dependem desses contratos do core. Bumps de versão apenas em metadados de release executam verificações direcionadas de versão/config/dependências de raiz. Alterações desconhecidas em root/config falham de forma segura para todos os lanes. -Em pushes, a matriz `checks` adiciona a lane `compat-node22`, exclusiva de push. Em pull requests, essa lane é ignorada e a matriz permanece focada nas lanes normais de teste/canal. +Em pushes, a matriz `checks` adiciona o lane `compat-node22`, exclusivo de push. Em pull requests, esse lane é ignorado e a matriz permanece focada nos lanes normais de teste/canais. -As famílias de testes Node mais lentas são divididas em shards por arquivo incluído para que cada job permaneça pequeno: contratos de canal dividem cobertura de registro e do core em oito shards ponderados cada, testes de comando de resposta de resposta automática se dividem em quatro shards por padrão de inclusão, e os outros grandes grupos de prefixo de resposta automática se dividem em dois shards cada. `check-additional` também separa trabalho de compilação/canary de limite de pacote do trabalho de topologia de runtime de gateway/arquitetura. +As famílias de testes Node mais lentas são divididas em shards por arquivo incluído para que cada job permaneça pequeno: contratos de canais dividem a cobertura de registro e core em oito shards ponderados cada, testes de comando de resposta de auto-reply são divididos em quatro shards por padrão de inclusão, e os outros grandes grupos de prefixo de resposta de auto-reply são divididos em dois shards cada. `check-additional` também separa o trabalho de compilação/canary de boundary de pacotes do trabalho de topologia de runtime de gateway/arquitetura. -O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais novo chega ao mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais recente para a mesma ref também esteja falhando. As verificações agregadas de shard destacam explicitamente esse caso de cancelamento para facilitar a distinção de uma falha de teste. +O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais recente chega no mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais recente para a mesma ref também esteja falhando. As verificações agregadas de shards destacam explicitamente esse caso de cancelamento para facilitar a distinção em relação a uma falha de teste. ## Runners -| Runner | Jobs | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, verificações Linux, verificações de docs, Skills em Python, `android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` em `openclaw/openclaw`; forks usam `macos-latest` como fallback | +| Runner | Jobs | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo | +| `blacksmith-16vcpu-ubuntu-2404` | `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, verificações Linux, verificações de docs, Skills em Python, `android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` em `openclaw/openclaw`; forks usam `macos-latest` como fallback | ## Equivalentes locais ```bash -pnpm changed:lanes # inspeciona o classificador local de lanes alteradas para origin/main...HEAD -pnpm check:changed # gate local inteligente: changed typecheck/lint/tests por lane de limite -pnpm check # gate local rápido: tsgo de produção + lint fragmentado + guardas rápidos em paralelo +pnpm changed:lanes # inspeciona o classificador local de lanes alterados para origin/main...HEAD +pnpm check:changed # gate local inteligente: typecheck/lint/testes alterados por lane de boundary +pnpm check # gate local rápido: tsgo de produção + lint fragmentado + guards rápidos em paralelo pnpm check:test-types pnpm check:timed # mesmo gate com tempos por etapa pnpm build:strict-smoke @@ -84,6 +85,6 @@ pnpm test:gateway:watch-regression pnpm test # testes vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # formatação + lint + links quebrados nas docs -pnpm build # compila dist quando as lanes de artefato/build-smoke da CI importam +pnpm check:docs # formatação + lint + links quebrados da documentação +pnpm build # gera dist quando os lanes de artefato/build-smoke da CI são relevantes ``` diff --git a/docs/pt-BR/concepts/typing-indicators.md b/docs/pt-BR/concepts/typing-indicators.md index 8b8155165..d2b86bd76 100644 --- a/docs/pt-BR/concepts/typing-indicators.md +++ b/docs/pt-BR/concepts/typing-indicators.md @@ -4,17 +4,17 @@ read_when: summary: Quando o OpenClaw mostra indicadores de digitação e como ajustá-los title: Indicadores de digitação x-i18n: - generated_at: "2026-04-05T12:40:37Z" + generated_at: "2026-04-22T05:34:46Z" model: gpt-5.4 provider: openai - source_hash: 28c8c395a135fc0745181aab66a93582177e6acd0b3496debcbb98159a4f11dc + source_hash: 2e7e8ca448b6706b6f53fcb6a582be6d4a84715c82dfde3d53abe4268af3ae0d source_path: concepts/typing-indicators.md workflow: 15 --- # Indicadores de digitação -Indicadores de digitação são enviados ao canal de chat enquanto uma execução está ativa. Use +Os indicadores de digitação são enviados para o canal de chat enquanto uma execução está ativa. Use `agents.defaults.typingMode` para controlar **quando** a digitação começa e `typingIntervalSeconds` para controlar **com que frequência** ela é atualizada. @@ -22,24 +22,25 @@ para controlar **com que frequência** ela é atualizada. Quando `agents.defaults.typingMode` está **não definido**, o OpenClaw mantém o comportamento legado: -- **Chats diretos**: a digitação começa imediatamente assim que o loop do modelo é iniciado. +- **Chats diretos**: a digitação começa imediatamente assim que o loop do modelo começa. - **Chats em grupo com uma menção**: a digitação começa imediatamente. - **Chats em grupo sem uma menção**: a digitação começa somente quando o texto da mensagem começa a ser transmitido. -- **Execuções de heartbeat**: a digitação é desativada. +- **Execuções de Heartbeat**: a digitação começa quando a execução de Heartbeat começa, se o + destino de Heartbeat resolvido for um chat com suporte a digitação e a digitação não estiver desativada. ## Modos -Defina `agents.defaults.typingMode` como um dos seguintes: +Defina `agents.defaults.typingMode` como um destes valores: - `never` — nenhum indicador de digitação, nunca. -- `instant` — começa a digitar **assim que o loop do modelo é iniciado**, mesmo que a execução +- `instant` — começa a digitar **assim que o loop do modelo começa**, mesmo que a execução depois retorne apenas o token de resposta silenciosa. -- `thinking` — começa a digitar no **primeiro delta de reasoning** (exige +- `thinking` — começa a digitar no **primeiro delta de raciocínio** (requer `reasoningLevel: "stream"` para a execução). - `message` — começa a digitar no **primeiro delta de texto não silencioso** (ignora o token silencioso `NO_REPLY`). -Ordem de “quão cedo ele dispara”: +Ordem de “quão cedo ele é acionado”: `never` → `message` → `thinking` → `instant` ## Configuração @@ -66,11 +67,16 @@ Você pode substituir o modo ou a cadência por sessão: ## Observações -- O modo `message` não mostrará digitação para respostas apenas silenciosas quando todo o - payload for exatamente o token silencioso (por exemplo `NO_REPLY` / `no_reply`, +- O modo `message` não mostrará digitação para respostas apenas silenciosas quando toda a + carga útil for exatamente o token silencioso (por exemplo `NO_REPLY` / `no_reply`, com correspondência sem diferenciar maiúsculas de minúsculas). -- `thinking` só dispara se a execução transmitir reasoning (`reasoningLevel: "stream"`). - Se o modelo não emitir deltas de reasoning, a digitação não começará. -- Heartbeats nunca mostram digitação, independentemente do modo. +- `thinking` só é acionado se a execução transmitir raciocínio (`reasoningLevel: "stream"`). + Se o modelo não emitir deltas de raciocínio, a digitação não começará. +- A digitação de Heartbeat é um sinal de atividade para o destino de entrega resolvido. Ela + começa no início da execução de Heartbeat em vez de seguir o tempo de transmissão de `message` ou `thinking`. + Defina `typingMode: "never"` para desativá-la. +- Heartbeats não mostram digitação quando `target: "none"`, quando o destino não pode + ser resolvido, quando a entrega de chat está desativada para o Heartbeat ou quando o + canal não oferece suporte a digitação. - `typingIntervalSeconds` controla a **cadência de atualização**, não o momento de início. O padrão é 6 segundos. diff --git a/docs/pt-BR/gateway/heartbeat.md b/docs/pt-BR/gateway/heartbeat.md index 29ebeb73d..43ec6171c 100644 --- a/docs/pt-BR/gateway/heartbeat.md +++ b/docs/pt-BR/gateway/heartbeat.md @@ -1,39 +1,39 @@ --- read_when: - - Ajustando a cadência ou as mensagens de heartbeat - - Decidindo entre heartbeat e cron para tarefas agendadas -summary: Mensagens de polling de heartbeat e regras de notificação + - Ajustando a cadência ou as mensagens do Heartbeat + - Decidindo entre Heartbeat e Cron para tarefas agendadas +summary: Mensagens de polling de Heartbeat e regras de notificação title: Heartbeat x-i18n: - generated_at: "2026-04-11T02:44:47Z" + generated_at: "2026-04-22T05:34:54Z" model: gpt-5.4 provider: openai - source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0 + source_hash: 13004e4e20b02b08aaf16f22cdf664d0b59da69446ecb30453db51ffdfd1d267 source_path: gateway/heartbeat.md workflow: 15 --- # Heartbeat (Gateway) -> **Heartbeat ou Cron?** Consulte [Automação e tarefas](/pt-BR/automation) para orientações sobre quando usar cada um. +> **Heartbeat vs Cron?** Veja [Automation & Tasks](/pt-BR/automation) para orientações sobre quando usar cada um. -O heartbeat executa **turnos periódicos do agente** na sessão principal para que o modelo possa -apontar qualquer coisa que precise de atenção sem enviar spam para você. +O Heartbeat executa **turnos periódicos do agente** na sessão principal para que o modelo possa +destacar qualquer coisa que precise de atenção sem te encher de mensagens. -Heartbeat é um turno agendado da sessão principal — ele **não** cria registros de [tarefas em segundo plano](/pt-BR/automation/tasks). -Os registros de tarefa são para trabalho desacoplado (execuções de ACP, subagentes, jobs cron isolados). +O Heartbeat é um turno agendado da sessão principal — ele **não** cria registros de [tarefas em segundo plano](/pt-BR/automation/tasks). +Os registros de tarefa são para trabalho desacoplado (execuções de ACP, subagentes, jobs de Cron isolados). -Solução de problemas: [Tarefas agendadas](/pt-BR/automation/cron-jobs#troubleshooting) +Solução de problemas: [Scheduled Tasks](/pt-BR/automation/cron-jobs#troubleshooting) ## Início rápido (iniciante) -1. Deixe os heartbeats ativados (o padrão é `30m`, ou `1h` para autenticação por OAuth/token da Anthropic, incluindo reutilização da Claude CLI) ou defina sua própria cadência. -2. Crie uma pequena checklist em `HEARTBEAT.md` ou um bloco `tasks:` no workspace do agente (opcional, mas recomendado). -3. Decida para onde as mensagens de heartbeat devem ir (`target: "none"` é o padrão; defina `target: "last"` para rotear para o último contato). -4. Opcional: ative a entrega do raciocínio do heartbeat para maior transparência. -5. Opcional: use um contexto de bootstrap leve se as execuções de heartbeat precisarem apenas de `HEARTBEAT.md`. +1. Deixe os heartbeats ativados (o padrão é `30m`, ou `1h` para autenticação Anthropic OAuth/token, incluindo reutilização do Claude CLI) ou defina sua própria cadência. +2. Crie um pequeno checklist em `HEARTBEAT.md` ou um bloco `tasks:` no workspace do agente (opcional, mas recomendado). +3. Decida para onde as mensagens de heartbeat devem ir (`target: "none"` é o padrão; defina `target: "last"` para encaminhar ao último contato). +4. Opcional: ative a entrega do raciocínio do heartbeat para transparência. +5. Opcional: use contexto bootstrap leve se as execuções do heartbeat precisarem apenas de `HEARTBEAT.md`. 6. Opcional: ative sessões isoladas para evitar enviar o histórico completo da conversa a cada heartbeat. -7. Opcional: restrinja os heartbeats ao horário ativo (hora local). +7. Opcional: restrinja os heartbeats a horas ativas (hora local). Exemplo de configuração: @@ -45,7 +45,7 @@ Exemplo de configuração: every: "30m", target: "last", // entrega explícita ao último contato (o padrão é "none") directPolicy: "allow", // padrão: permite destinos diretos/DM; defina "block" para suprimir - lightContext: true, // opcional: injeta apenas HEARTBEAT.md a partir dos arquivos de bootstrap + lightContext: true, // opcional: injeta apenas HEARTBEAT.md dos arquivos bootstrap isolatedSession: true, // opcional: sessão nova a cada execução (sem histórico de conversa) // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // opcional: envia também uma mensagem separada `Reasoning:` @@ -57,15 +57,15 @@ Exemplo de configuração: ## Padrões -- Intervalo: `30m` (ou `1h` quando o modo de autenticação detectado é OAuth/token da Anthropic, incluindo reutilização da Claude CLI). Defina `agents.defaults.heartbeat.every` ou `agents.list[].heartbeat.every`; use `0m` para desativar. -- Corpo do prompt (configurável em `agents.defaults.heartbeat.prompt`): +- Intervalo: `30m` (ou `1h` quando o modo de autenticação detectado for Anthropic OAuth/token, incluindo reutilização do Claude CLI). Defina `agents.defaults.heartbeat.every` ou `agents.list[].heartbeat.every` por agente; use `0m` para desativar. +- Corpo do prompt (configurável por `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- O prompt de heartbeat é enviado **literalmente** como a mensagem do usuário. O prompt - do sistema inclui uma seção “Heartbeat” somente quando os heartbeats estão ativados para o - agente padrão, e a execução é sinalizada internamente. -- Quando os heartbeats são desativados com `0m`, as execuções normais também omitem `HEARTBEAT.md` - do contexto de bootstrap para que o modelo não veja instruções exclusivas de heartbeat. -- Horário ativo (`heartbeat.activeHours`) é verificado no fuso horário configurado. +- O prompt do heartbeat é enviado **literalmente** como a mensagem do usuário. O + prompt do sistema inclui uma seção “Heartbeat” apenas quando os heartbeats estão ativados para o + agente padrão, e a execução é marcada internamente. +- Quando os heartbeats são desativados com `0m`, execuções normais também omitem `HEARTBEAT.md` + do contexto bootstrap para que o modelo não veja instruções exclusivas de heartbeat. +- As horas ativas (`heartbeat.activeHours`) são verificadas no fuso horário configurado. Fora da janela, os heartbeats são ignorados até o próximo tick dentro da janela. ## Para que serve o prompt de heartbeat @@ -73,16 +73,16 @@ Exemplo de configuração: O prompt padrão é intencionalmente amplo: - **Tarefas em segundo plano**: “Consider outstanding tasks” incentiva o agente a revisar - acompanhamentos pendentes (caixa de entrada, calendário, lembretes, trabalho enfileirado) e sinalizar qualquer coisa urgente. -- **Check-in humano**: “Checkup sometimes on your human during day time” incentiva uma - mensagem ocasional e leve de “precisa de algo?”, mas evita spam noturno - usando seu fuso horário local configurado (consulte [/concepts/timezone](/pt-BR/concepts/timezone)). + acompanhamentos pendentes (caixa de entrada, calendário, lembretes, trabalho enfileirado) e destacar qualquer item urgente. +- **Check-in humano**: “Checkup sometimes on your human during day time” incentiva + uma mensagem ocasional e leve do tipo “precisa de algo?”, mas evita spam noturno + usando seu fuso horário local configurado (veja [/concepts/timezone](/pt-BR/concepts/timezone)). -Heartbeat pode reagir a [tarefas em segundo plano](/pt-BR/automation/tasks) concluídas, mas uma execução de heartbeat em si não cria um registro de tarefa. +O Heartbeat pode reagir a [tarefas em segundo plano](/pt-BR/automation/tasks) concluídas, mas uma execução de heartbeat em si não cria um registro de tarefa. Se você quiser que um heartbeat faça algo muito específico (por exemplo, “verificar estatísticas do Gmail PubSub” ou “verificar a integridade do gateway”), defina `agents.defaults.heartbeat.prompt` (ou -`agents.list[].heartbeat.prompt`) para um corpo personalizado (enviado literalmente). +`agents.list[].heartbeat.prompt`) com um corpo personalizado (enviado literalmente). ## Contrato de resposta @@ -94,7 +94,7 @@ ou “verificar a integridade do gateway”), defina `agents.defaults.heartbeat. de forma especial. - Para alertas, **não** inclua `HEARTBEAT_OK`; retorne apenas o texto do alerta. -Fora dos heartbeats, um `HEARTBEAT_OK` solto no início/fim de uma mensagem é removido +Fora dos heartbeats, `HEARTBEAT_OK` solto no início/fim de uma mensagem é removido e registrado em log; uma mensagem que seja apenas `HEARTBEAT_OK` é descartada. ## Configuração @@ -106,14 +106,14 @@ e registrado em log; uma mensagem que seja apenas `HEARTBEAT_OK` é descartada. heartbeat: { every: "30m", // padrão: 30m (0m desativa) model: "anthropic/claude-opus-4-6", - includeReasoning: false, // padrão: false (entrega uma mensagem separada `Reasoning:` quando disponível) - lightContext: false, // padrão: false; true mantém apenas HEARTBEAT.md dos arquivos de bootstrap do workspace + includeReasoning: false, // padrão: false (entrega mensagem separada `Reasoning:` quando disponível) + 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) - target: "last", // padrão: none | opções: last | none | (core ou plugin, por exemplo "bluebubbles") - to: "+15551234567", // opcional: substituição específica de canal - accountId: "ops-bot", // opcional: id de canal com várias contas + target: "last", // padrão: none | opções: last | none | (core ou plugin, por exemplo "bluebubbles") + to: "+15551234567", // opcional: substituição específica do canal + accountId: "ops-bot", // opcional: id de canal com múltiplas contas prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", - ackMaxChars: 300, // número máximo de caracteres permitidos após HEARTBEAT_OK + ackMaxChars: 300, // máximo de caracteres permitidos após HEARTBEAT_OK }, }, }, @@ -122,17 +122,17 @@ e registrado em log; uma mensagem que seja apenas `HEARTBEAT_OK` é descartada. ### Escopo e precedência -- `agents.defaults.heartbeat` define o comportamento global de heartbeat. +- `agents.defaults.heartbeat` define o comportamento global do heartbeat. - `agents.list[].heartbeat` é mesclado por cima; se qualquer agente tiver um bloco `heartbeat`, **somente esses agentes** executarão heartbeats. -- `channels.defaults.heartbeat` define os padrões de visibilidade para todos os canais. +- `channels.defaults.heartbeat` define padrões de visibilidade para todos os canais. - `channels..heartbeat` substitui os padrões do canal. -- `channels..accounts..heartbeat` (canais com várias contas) substitui por canal. +- `channels..accounts..heartbeat` (canais com múltiplas contas) substitui por canal. ### Heartbeats por agente Se qualquer entrada de `agents.list[]` incluir um bloco `heartbeat`, **somente esses agentes** -executarão heartbeats. O bloco por agente é mesclado sobre `agents.defaults.heartbeat` -(assim você pode definir padrões compartilhados uma vez e substituir por agente). +executarão heartbeats. O bloco por agente é mesclado por cima de `agents.defaults.heartbeat` +(assim você pode definir padrões compartilhados uma vez e substituí-los por agente). Exemplo: dois agentes, apenas o segundo agente executa heartbeats. @@ -162,7 +162,7 @@ Exemplo: dois agentes, apenas o segundo agente executa heartbeats. } ``` -### Exemplo de horário ativo +### Exemplo de horas ativas Restrinja os heartbeats ao horário comercial em um fuso horário específico: @@ -184,7 +184,7 @@ Restrinja os heartbeats ao horário comercial em um fuso horário específico: } ``` -Fora dessa janela (antes das 9h ou depois das 22h no horário do Leste), os heartbeats são ignorados. O próximo tick agendado dentro da janela será executado normalmente. +Fora dessa janela (antes das 9h ou depois das 22h no horário do leste dos EUA), os heartbeats são ignorados. O próximo tick agendado dentro da janela será executado normalmente. ### Configuração 24/7 @@ -193,12 +193,12 @@ Se você quiser que os heartbeats sejam executados o dia todo, use um destes pad - Omita `activeHours` completamente (sem restrição de janela de tempo; este é o comportamento padrão). - Defina uma janela de dia inteiro: `activeHours: { start: "00:00", end: "24:00" }`. -Não defina o mesmo horário para `start` e `end` (por exemplo, `08:00` a `08:00`). -Isso é tratado como uma janela de largura zero, então os heartbeats sempre são ignorados. +Não defina `start` e `end` com o mesmo horário (por exemplo `08:00` até `08:00`). +Isso é tratado como uma janela de largura zero, então os heartbeats são sempre ignorados. -### Exemplo com várias contas +### Exemplo com múltiplas contas -Use `accountId` para direcionar a uma conta específica em canais com várias contas, como Telegram: +Use `accountId` para direcionar uma conta específica em canais com múltiplas contas, como Telegram: ```json5 { @@ -209,7 +209,7 @@ Use `accountId` para direcionar a uma conta específica em canais com várias co heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // opcional: roteia para um tópico/thread específico + to: "12345678:topic:42", // opcional: encaminha para um tópico/thread específico accountId: "ops-bot", }, }, @@ -228,30 +228,30 @@ Use `accountId` para direcionar a uma conta específica em canais com várias co ### Observações sobre os campos - `every`: intervalo do heartbeat (string de duração; unidade padrão = minutos). -- `model`: substituição opcional de modelo para execuções de heartbeat (`provider/model`). +- `model`: substituição opcional do modelo para execuções de heartbeat (`provider/model`). - `includeReasoning`: quando ativado, também entrega a mensagem separada `Reasoning:` quando disponível (mesmo formato de `/reasoning on`). -- `lightContext`: quando verdadeiro, as execuções de heartbeat usam contexto de bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos de bootstrap do workspace. -- `isolatedSession`: quando verdadeiro, cada heartbeat é executado em uma sessão nova sem histórico anterior de conversa. Usa o mesmo padrão de isolamento do cron `sessionTarget: "isolated"`. Reduz drasticamente o custo em tokens por heartbeat. Combine com `lightContext: true` para máxima economia. O roteamento de entrega ainda usa o contexto da sessão principal. +- `lightContext`: quando true, as 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. Usa o mesmo padrão de isolamento do Cron `sessionTarget: "isolated"`. Reduz drasticamente o custo de tokens por heartbeat. Combine com `lightContext: true` para a máxima economia. O roteamento de entrega ainda usa o contexto da sessão principal. - `session`: chave de sessão opcional para execuções de heartbeat. - `main` (padrão): sessão principal do agente. - Chave de sessão explícita (copie de `openclaw sessions --json` ou da [CLI de sessões](/cli/sessions)). - - Formatos de chave de sessão: consulte [Sessões](/pt-BR/concepts/session) e [Grupos](/pt-BR/channels/groups). + - Formatos de chave de sessão: veja [Sessions](/pt-BR/concepts/session) e [Groups](/pt-BR/channels/groups). - `target`: - - `last`: entrega no último canal externo usado. - - canal explícito: qualquer canal ou id de plugin configurado, por exemplo `discord`, `matrix`, `telegram` ou `whatsapp`. + - `last`: entrega ao último canal externo usado. + - canal explícito: qualquer id de canal ou plugin configurado, por exemplo `discord`, `matrix`, `telegram` ou `whatsapp`. - `none` (padrão): executa o heartbeat, mas **não entrega** externamente. - `directPolicy`: controla o comportamento de entrega direta/DM: - - `allow` (padrão): permite entrega direta/DM de heartbeat. - - `block`: suprime a entrega direta/DM (`reason=dm-blocked`). -- `to`: substituição opcional de destinatário (id específico do canal, por exemplo E.164 para WhatsApp ou id de chat do Telegram). Para tópicos/threads do Telegram, use `:topic:`. -- `accountId`: id de conta opcional para canais com várias contas. Quando `target: "last"`, o id da conta se aplica ao último canal resolvido se ele oferecer suporte a contas; caso contrário, é ignorado. Se o id da conta não corresponder a uma conta configurada para o canal resolvido, a entrega será ignorada. -- `prompt`: substitui o corpo padrão do prompt (não é mesclado). -- `ackMaxChars`: número máximo de caracteres permitidos após `HEARTBEAT_OK` antes da entrega. -- `suppressToolErrorWarnings`: quando verdadeiro, suprime payloads de aviso de erro de ferramenta durante execuções de heartbeat. + - `allow` (padrão): permite entrega de heartbeat direta/DM. + - `block`: suprime entrega direta/DM (`reason=dm-blocked`). +- `to`: substituição opcional do destinatário (id específico do canal, por exemplo E.164 para WhatsApp ou um id de chat do Telegram). Para tópicos/threads do Telegram, use `:topic:`. +- `accountId`: id de conta opcional para canais com múltiplas contas. Quando `target: "last"`, o id da conta é aplicado ao último canal resolvido se ele oferecer suporte a contas; caso contrário, é ignorado. Se o id da conta não corresponder a uma conta configurada para o canal resolvido, a entrega será ignorada. +- `prompt`: substitui o corpo do prompt padrão (não é mesclado). +- `ackMaxChars`: máximo de caracteres permitidos após `HEARTBEAT_OK` antes da entrega. +- `suppressToolErrorWarnings`: quando true, suprime payloads de aviso de erro de ferramenta durante execuções de heartbeat. - `activeHours`: restringe execuções de heartbeat a uma janela de tempo. Objeto com `start` (HH:MM, inclusivo; use `00:00` para início do dia), `end` (HH:MM exclusivo; `24:00` é permitido para fim do dia) e `timezone` opcional. - Omitido ou `"user"`: usa seu `agents.defaults.userTimezone` se definido; caso contrário, usa o fuso horário do sistema host. - `"local"`: sempre usa o fuso horário do sistema host. - - Qualquer identificador IANA (por exemplo, `America/New_York`): usado diretamente; se for inválido, recorre ao comportamento `"user"` acima. + - Qualquer identificador IANA (por exemplo `America/New_York`): usado diretamente; se for inválido, volta ao comportamento `"user"` acima. - `start` e `end` não devem ser iguais para uma janela ativa; valores iguais são tratados como largura zero (sempre fora da janela). - Fora da janela ativa, os heartbeats são ignorados até o próximo tick dentro da janela. @@ -259,19 +259,22 @@ Use `accountId` para direcionar a uma conta específica em canais com várias co - Os heartbeats são executados por padrão na sessão principal do agente (`agent::`), ou em `global` quando `session.scope = "global"`. Defina `session` para substituir por uma - sessão específica de canal (Discord/WhatsApp/etc.). + sessão de canal específica (Discord/WhatsApp/etc.). - `session` afeta apenas o contexto da execução; a entrega é controlada por `target` e `to`. - Para entregar a um canal/destinatário específico, defina `target` + `to`. Com `target: "last"`, a entrega usa o último canal externo dessa sessão. - As entregas de heartbeat permitem destinos diretos/DM por padrão. Defina `directPolicy: "block"` para suprimir envios para destinos diretos enquanto ainda executa o turno de heartbeat. - Se a fila principal estiver ocupada, o heartbeat será ignorado e tentado novamente mais tarde. -- Se `target` não resolver para nenhum destino externo, a execução ainda acontece, mas nenhuma +- Se `target` não for resolvido para nenhum destino externo, a execução ainda acontece, mas nenhuma mensagem de saída é enviada. - Se `showOk`, `showAlerts` e `useIndicator` estiverem todos desativados, a execução será ignorada antecipadamente como `reason=alerts-disabled`. -- Se apenas a entrega de alertas estiver desativada, o OpenClaw ainda poderá executar o heartbeat, atualizar timestamps de tarefas vencidas, restaurar o timestamp de inatividade da sessão e suprimir o payload de alerta externo. +- Se apenas a entrega de alertas estiver desativada, o OpenClaw ainda poderá executar o heartbeat, atualizar os carimbos de data/hora das tarefas vencidas, restaurar o carimbo de data/hora de inatividade da sessão e suprimir o payload do alerta externo. +- Se o destino de heartbeat resolvido oferecer suporte a indicador de digitação, o OpenClaw mostrará digitação enquanto + a execução do heartbeat estiver ativa. Isso usa o mesmo destino para o qual o heartbeat + enviaria a saída do chat, e é desativado por `typingMode: "never"`. - Respostas exclusivas de heartbeat **não** mantêm a sessão ativa; o último `updatedAt` é restaurado para que a expiração por inatividade se comporte normalmente. -- [Tarefas em segundo plano](/pt-BR/automation/tasks) desacopladas podem enfileirar um evento do sistema e despertar o heartbeat quando a sessão principal precisar perceber algo rapidamente. Esse despertar não faz com que a execução de heartbeat se torne uma tarefa em segundo plano. +- [Tarefas em segundo plano](/pt-BR/automation/tasks) desacopladas podem enfileirar um evento do sistema e despertar o heartbeat quando a sessão principal precisar perceber algo rapidamente. Esse despertar não faz com que a execução do heartbeat se torne uma tarefa em segundo plano. ## Controles de visibilidade @@ -295,17 +298,17 @@ channels: showAlerts: false # Suprime a entrega de alertas para esta conta ``` -Precedência: por conta → por canal → padrões do canal → padrões embutidos. +Precedência: por conta → por canal → padrões do canal → padrões internos. -### O que cada flag faz +### O que cada sinalizador faz -- `showOk`: envia uma confirmação `HEARTBEAT_OK` quando o modelo retorna uma resposta somente de OK. -- `showAlerts`: envia o conteúdo do alerta quando o modelo retorna uma resposta que não é OK. +- `showOk`: envia uma confirmação `HEARTBEAT_OK` quando o modelo retorna uma resposta apenas de OK. +- `showAlerts`: envia o conteúdo do alerta quando o modelo retorna uma resposta não-OK. - `useIndicator`: emite eventos de indicador para superfícies de status da UI. -Se **todas as três** estiverem como false, o OpenClaw ignora completamente a execução de heartbeat (sem chamada ao modelo). +Se **todos os três** forem false, o OpenClaw ignora completamente a execução do heartbeat (sem chamada ao modelo). -### Exemplos por canal versus por conta +### Exemplos por canal vs por conta ```yaml channels: @@ -335,37 +338,38 @@ channels: | Somente indicador (sem mensagens) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | | OKs em apenas um canal | `channels.telegram.heartbeat: { showOk: true }` | -## `HEARTBEAT.md` (opcional) +## HEARTBEAT.md (opcional) -Se existir um arquivo `HEARTBEAT.md` no workspace, o prompt padrão informa ao -agente para lê-lo. Pense nele como sua “checklist de heartbeat”: pequena, estável e +Se existir um arquivo `HEARTBEAT.md` no workspace, o prompt padrão instrui o +agente a lê-lo. Pense nele como sua “lista de verificação de heartbeat”: pequena, estável e segura para incluir a cada 30 minutos. Em execuções normais, `HEARTBEAT.md` só é injetado quando a orientação de heartbeat está -ativada para o agente padrão. Desativar a cadência de heartbeat com `0m` ou -definir `includeSystemPromptSection: false` o omite do contexto normal de bootstrap. +ativada para o agente padrão. Desativar a cadência do heartbeat com `0m` ou +definir `includeSystemPromptSection: false` o omite do contexto bootstrap +normal. Se `HEARTBEAT.md` existir, mas estiver efetivamente vazio (apenas linhas em branco e cabeçalhos -Markdown como `# Heading`), o OpenClaw ignora a execução de heartbeat para economizar chamadas de API. -Essa ignorada é relatada como `reason=empty-heartbeat-file`. -Se o arquivo estiver ausente, o heartbeat ainda é executado e o modelo decide o que fazer. +markdown como `# Heading`), o OpenClaw ignora a execução do heartbeat para economizar chamadas de API. +Essa ignorada é reportada como `reason=empty-heartbeat-file`. +Se o arquivo estiver ausente, o heartbeat ainda será executado e o modelo decidirá o que fazer. -Mantenha-o pequeno (checklist curta ou lembretes) para evitar inflar o prompt. +Mantenha-o pequeno (checklist curto ou lembretes) para evitar inchar o prompt. Exemplo de `HEARTBEAT.md`: ```md -# Checklist de heartbeat +# Lista de verificação de heartbeat - Verificação rápida: há algo urgente nas caixas de entrada? -- Se for durante o dia, faça um check-in leve se nada mais estiver pendente. +- Se for de dia, faça um check-in leve se não houver mais nada pendente. - Se uma tarefa estiver bloqueada, anote _o que está faltando_ e pergunte ao Peter na próxima vez. ``` ### Blocos `tasks:` -`HEARTBEAT.md` também oferece suporte a um pequeno bloco estruturado `tasks:` para verificações -baseadas em intervalo dentro do próprio heartbeat. +`HEARTBEAT.md` também oferece suporte a um pequeno bloco estruturado `tasks:` para +verificações baseadas em intervalos dentro do próprio heartbeat. Exemplo: @@ -374,10 +378,10 @@ tasks: - name: inbox-triage interval: 30m - prompt: "Verifique se há emails urgentes não lidos e sinalize qualquer coisa sensível ao tempo." + prompt: "Verifique se há emails urgentes não lidos e destaque qualquer coisa sensível ao tempo." - name: calendar-scan interval: 2h - prompt: "Verifique se há reuniões próximas que precisam de preparação ou acompanhamento." + prompt: "Verifique se há reuniões próximas que precisem de preparação ou acompanhamento." # Instruções adicionais @@ -387,16 +391,16 @@ tasks: Comportamento: -- O OpenClaw analisa o bloco `tasks:` e verifica cada tarefa em relação ao seu próprio `interval`. -- Somente as tarefas **vencidas** são incluídas no prompt de heartbeat desse tick. -- Se nenhuma tarefa estiver vencida, o heartbeat é totalmente ignorado (`reason=no-tasks-due`) para evitar uma chamada desnecessária ao modelo. -- O conteúdo que não for de tarefa em `HEARTBEAT.md` é preservado e anexado como contexto adicional após a lista de tarefas vencidas. -- Os timestamps da última execução das tarefas são armazenados no estado da sessão (`heartbeatTaskState`), então os intervalos sobrevivem a reinicializações normais. -- Os timestamps das tarefas só são avançados depois que uma execução de heartbeat completa seu fluxo normal de resposta. Execuções ignoradas por `empty-heartbeat-file` / `no-tasks-due` não marcam tarefas como concluídas. +- O OpenClaw analisa o bloco `tasks:` e verifica cada tarefa com base em seu próprio `interval`. +- Apenas tarefas **vencidas** são incluídas no prompt de heartbeat desse tick. +- Se nenhuma tarefa estiver vencida, o heartbeat será completamente ignorado (`reason=no-tasks-due`) para evitar uma chamada desnecessária ao modelo. +- Conteúdo que não seja tarefa em `HEARTBEAT.md` é preservado e anexado como contexto adicional após a lista de tarefas vencidas. +- Os carimbos de data/hora da última execução das tarefas são armazenados no estado da sessão (`heartbeatTaskState`), para que os intervalos sobrevivam a reinicializações normais. +- Os carimbos de data/hora das tarefas só avançam depois que uma execução de heartbeat conclui seu fluxo normal de resposta. Execuções ignoradas de `empty-heartbeat-file` / `no-tasks-due` não marcam tarefas como concluídas. -O modo de tarefa é útil quando você quer que um único arquivo de heartbeat contenha várias verificações periódicas sem pagar por todas elas a cada tick. +O modo de tarefas é útil quando você quer que um único arquivo de heartbeat contenha várias verificações periódicas sem pagar por todas elas a cada tick. -### O agente pode atualizar `HEARTBEAT.md`? +### O agente pode atualizar o HEARTBEAT.md? Sim — se você pedir. @@ -406,16 +410,16 @@ agente (em um chat normal) algo como: - “Atualize `HEARTBEAT.md` para adicionar uma verificação diária do calendário.” - “Reescreva `HEARTBEAT.md` para que fique mais curto e focado em acompanhamentos da caixa de entrada.” -Se você quiser que isso aconteça proativamente, também pode incluir uma linha explícita no -seu prompt de heartbeat, como: “Se a checklist ficar desatualizada, atualize `HEARTBEAT.md` +Se você quiser que isso aconteça de forma proativa, também pode incluir uma linha explícita no +seu prompt de heartbeat, como: “Se a lista de verificação ficar desatualizada, atualize HEARTBEAT.md com uma versão melhor.” Observação de segurança: não coloque segredos (chaves de API, números de telefone, tokens privados) em -`HEARTBEAT.md` — ele passa a fazer parte do contexto do prompt. +`HEARTBEAT.md` — ele se torna parte do contexto do prompt. ## Despertar manual (sob demanda) -Você pode enfileirar um evento do sistema e disparar um heartbeat imediato com: +Você pode enfileirar um evento do sistema e acionar um heartbeat imediato com: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now @@ -424,7 +428,7 @@ openclaw system event --text "Check for urgent follow-ups" --mode now Se vários agentes tiverem `heartbeat` configurado, um despertar manual executará imediatamente os heartbeats de cada um desses agentes. -Use `--mode next-heartbeat` para esperar pelo próximo tick agendado. +Use `--mode next-heartbeat` para aguardar o próximo tick agendado. ## Entrega de raciocínio (opcional) @@ -434,25 +438,25 @@ Se você quiser transparência, ative: - `agents.defaults.heartbeat.includeReasoning: true` -Quando ativado, os heartbeats também entregam uma mensagem separada prefixada com +Quando ativado, os heartbeats também entregarão uma mensagem separada prefixada com `Reasoning:` (mesmo formato de `/reasoning on`). Isso pode ser útil quando o agente -está gerenciando várias sessões/codexes e você quer ver por que ele decidiu chamar -você — mas também pode expor mais detalhes internos do que você deseja. Prefira manter -isso desativado em chats de grupo. +está gerenciando várias sessões/codexes e você quer ver por que ele decidiu te avisar +— mas também pode expor mais detalhes internos do que você deseja. Prefira manter isso +desativado em chats em grupo. -## Atenção aos custos +## Consciência de custo -Heartbeats executam turnos completos do agente. Intervalos mais curtos consomem mais tokens. Para reduzir o custo: +Os heartbeats executam turnos completos do agente. Intervalos mais curtos consomem mais tokens. Para reduzir custo: -- Use `isolatedSession: true` para evitar enviar o histórico completo da conversa (~100 mil tokens reduzidos para ~2–5 mil por execução). -- Use `lightContext: true` para limitar os arquivos de bootstrap apenas a `HEARTBEAT.md`. -- Defina um `model` mais barato (por exemplo, `ollama/llama3.2:1b`). +- Use `isolatedSession: true` para evitar enviar todo o histórico da conversa (~100 mil tokens para ~2–5 mil por execução). +- Use `lightContext: true` para limitar os arquivos bootstrap somente a `HEARTBEAT.md`. +- Defina um `model` mais barato (por exemplo `ollama/llama3.2:1b`). - Mantenha `HEARTBEAT.md` pequeno. -- Use `target: "none"` se você quiser apenas atualizações de estado internas. +- Use `target: "none"` se você quiser apenas atualizações internas de estado. ## Relacionado -- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em um relance -- [Tarefas em segundo plano](/pt-BR/automation/tasks) — como o trabalho desacoplado é rastreado -- [Fuso horário](/pt-BR/concepts/timezone) — como o fuso horário afeta o agendamento de heartbeat -- [Solução de problemas](/pt-BR/automation/cron-jobs#troubleshooting) — depuração de problemas de automação +- [Automation & Tasks](/pt-BR/automation) — todos os mecanismos de automação em um relance +- [Background Tasks](/pt-BR/automation/tasks) — como o trabalho desacoplado é rastreado +- [Timezone](/pt-BR/concepts/timezone) — como o fuso horário afeta o agendamento do heartbeat +- [Troubleshooting](/pt-BR/automation/cron-jobs#troubleshooting) — depuração de problemas de automação diff --git a/docs/pt-BR/plugins/manifest.md b/docs/pt-BR/plugins/manifest.md index 13cdd8ae0..727c38470 100644 --- a/docs/pt-BR/plugins/manifest.md +++ b/docs/pt-BR/plugins/manifest.md @@ -1,81 +1,65 @@ --- 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 de schema JSON (validação estrita de configuração) -title: Manifesto de Plugin + - Você está criando um plugin do OpenClaw + - Você precisa entregar um esquema de configuração de plugin ou depurar erros de validação de plugin +summary: Manifesto do Plugin + requisitos do esquema JSON (validação estrita de configuração) +title: Manifesto do Plugin x-i18n: - generated_at: "2026-04-22T04:23:57Z" + generated_at: "2026-04-22T05:34:47Z" model: gpt-5.4 provider: openai - source_hash: 52a52f7e2c78bbef2cc51ade6eb12b6edc950237bdfc478f6e82248374c687bf + source_hash: b80735690799682939e8c8c27b6a364caa3ceadcf6319155ddeb20eb0538c313 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**. +Esta página é apenas para o **manifesto nativo de plugin do OpenClaw**. -Para layouts de bundle compatíveis, consulte [Bundles de Plugin](/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 Codex: `.codex-plugin/plugin.json` -- Bundle Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente Claude - sem manifesto -- Bundle Cursor: `.cursor-plugin/plugin.json` +- Bundle do Codex: `.codex-plugin/plugin.json` +- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude sem manifesto +- Bundle do Cursor: `.cursor-plugin/plugin.json` -O 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. +O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados em relação ao esquema `openclaw.plugin.json` descrito aqui. -Para bundles compatíveis, o OpenClaw atualmente lê metadados do bundle mais as -raízes de skill declaradas, raízes de comandos Claude, padrões de `settings.json` do bundle Claude, -padrões de LSP do bundle 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 mais as raízes de skill declaradas, as raízes de comando do Claude, os padrões de `settings.json` do bundle do Claude, os padrões de LSP do bundle do Claude e os pacotes de hook compatíveis quando o layout corresponde às expectativas de tempo de execução 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 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. +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 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. 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). +Para o modelo nativo de capacidade e a orientação atual de compatibilidade externa: +[Modelo de capacidade](/pt-BR/plugins/architecture#public-capability-model). -## O que esse arquivo faz +## 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 +- identidade do plugin - validação de configuração -- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o - runtime do Plugin -- dicas baratas de ativação que superfícies do plano de controle podem inspecionar antes de o runtime - carregar -- descritores baratos de configuração que superfícies de setup/onboarding podem inspecionar antes de o - runtime carregar -- metadados de alias e auto-enable que devem ser resolvidos antes de o runtime do Plugin carregar -- metadados abreviados de propriedade de família de modelos que devem ativar automaticamente o - Plugin antes de o runtime carregar -- instantâneos estáticos de propriedade de capacidades usados para compat wiring bundled e - cobertura de contrato -- metadados baratos do executor de QA que o host compartilhado `openclaw qa` pode inspecionar - antes de o runtime do Plugin carregar -- 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 +- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o tempo de execução do plugin +- dicas de ativação leves que as superfícies do plano de controle podem inspecionar antes de o tempo de execução ser carregado +- descritores de configuração leves que as superfícies de configuração/onboarding podem inspecionar antes de o tempo de execução ser carregado +- metadados de alias e autoativação que devem ser resolvidos antes de o tempo de execução do plugin ser carregado +- metadados abreviados de propriedade de família de modelos que devem autoativar o plugin antes de o tempo de execução ser carregado +- snapshots estáticos de propriedade de capacidade usados para a integração de compatibilidade agrupada e cobertura de contrato +- metadados leves do executor de QA que o host compartilhado `openclaw qa` pode inspecionar antes de o tempo de execução do plugin ser carregado +- metadados de configuração específicos de canal que devem ser mesclados às superfícies de catálogo e validação sem carregar o tempo de execução - dicas de UI de configuração Não o use para: -- registrar comportamento de runtime +- registrar comportamento de tempo de execução - declarar entrypoints de código - metadados de instalação do npm -Esses pertencem ao código do seu Plugin e a `package.json`. +Esses pertencem ao código do seu plugin e ao `package.json`. ## Exemplo mínimo @@ -153,68 +137,67 @@ Esses pertencem ao código do seu Plugin e a `package.json`. } ``` -## Referência de campos de nível superior +## Referência dos campos de nível superior -| Campo | Obrigatório | Tipo | O que significa | -| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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 bundled como habilitado por padrão. Omita-o, ou defina qualquer valor diferente de `true`, para manter 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 provedor que devem habilitar automaticamente 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 canal pertencentes a este Plugin. Usado para descoberta e validação de configuração. | -| `providers` | Não | `string[]` | IDs de provedor pertencentes a este Plugin. | -| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto, usados para carregar automaticamente o Plugin antes do runtime. | -| `providerEndpoints` | Não | `object[]` | Metadados de host/baseUrl de endpoint pertencentes ao manifesto para rotas de provedor que o core precisa classificar antes de o runtime do provedor carregar. | -| `cliBackends` | Não | `string[]` | IDs de backend de inferência CLI pertencentes a este Plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração. | -| `syntheticAuthRefs` | Não | `string[]` | Referências de provedor ou backend CLI cujo hook sintético de autenticação pertencente ao Plugin deve ser sondado durante a descoberta fria de modelos antes de o runtime carregar. | -| `nonSecretAuthMarkers` | Não | `string[]` | Valores de chave de API placeholder pertencentes a Plugin bundled que representam estado não secreto de credencial local, OAuth ou ambiente. | -| `commandAliases` | Não | `object[]` | Nomes de comando pertencentes a este Plugin que devem produzir diagnósticos de configuração e CLI com reconhecimento do Plugin antes de o runtime carregar. | -| `providerAuthEnvVars` | Não | `Record` | Metadados baratos de env de autenticação de provedor que o OpenClaw pode inspecionar sem carregar o código do Plugin. | -| `providerAuthAliases` | Não | `Record` | IDs de provedor que devem reutilizar outro ID de provedor para lookup de autenticação, por exemplo um provedor de coding que compartilha a chave de API e os perfis de autenticação do provedor base. | -| `channelEnvVars` | Não | `Record` | Metadados baratos de env de canal que o OpenClaw pode inspecionar sem carregar o código do Plugin. Use isto para superfícies de setup ou autenticação de canal orientadas por env que helpers genéricos de inicialização/configuração devem enxergar. | -| `providerAuthChoices` | Não | `object[]` | Metadados baratos de escolha de autenticação para seletores de onboarding, resolução de provedor preferido e ligação simples de flags de CLI. | -| `activation` | Não | `object` | Dicas baratas de ativação para carregamento acionado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do Plugin continua sendo dono do comportamento real. | -| `setup` | Não | `object` | Descritores baratos de setup/onboarding que superfícies de descoberta e setup podem inspecionar sem carregar o runtime do Plugin. | -| `qaRunners` | Não | `object[]` | Descritores baratos de executor de QA usados pelo host compartilhado `openclaw qa` antes de o runtime do Plugin carregar. | -| `contracts` | Não | `object` | Instantâneo estático de capacidades bundled para fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração de imagens, 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 carregar. | -| `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 do 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. | +| Campo | Obrigatório | Tipo | O que significa | +| ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Sim | `string` | ID canônico do plugin. Este é o ID usado em `plugins.entries.`. | +| `configSchema` | Sim | `object` | Esquema JSON inline para a configuração deste plugin. | +| `enabledByDefault` | Não | `true` | Marca um plugin agrupado 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 habilitar automaticamente 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. | +| `providers` | Não | `string[]` | IDs de provedores pertencentes a este plugin. | +| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto usados para carregar automaticamente o plugin antes do tempo de execução. | +| `providerEndpoints` | Não | `object[]` | Metadados de host/baseUrl de endpoint pertencentes ao manifesto para rotas de provedor que o núcleo precisa classificar antes de o tempo de execução do provedor ser carregado. | +| `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 na configuração. | +| `syntheticAuthRefs` | Não | `string[]` | Referências de provedor ou backend de CLI cujo hook de autenticação sintética pertencente ao plugin deve ser verificado durante a descoberta fria de modelos antes de o tempo de execução ser carregado. | +| `nonSecretAuthMarkers` | Não | `string[]` | Valores de chave de API de placeholder pertencentes a plugins agrupados que representam estado de credencial não secreta local, OAuth ou do ambiente. | +| `commandAliases` | Não | `object[]` | Nomes de comandos pertencentes a este plugin que devem produzir configuração com reconhecimento do plugin e diagnósticos de CLI antes de o tempo de execução 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 codificaçã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 isto para superfícies de autenticação ou configuração de canal baseadas em env que auxiliares genéricos de inicialização/configuração devem ver. | +| `providerAuthChoices` | Não | `object[]` | Metadados leves de escolhas de autenticação para seletores de onboarding, resolução de provedor preferido e ligação simples de flags da CLI. | +| `activation` | Não | `object` | Dicas leves de ativação para carregamento acionado por provedor, comando, canal, rota e capacidade. Apenas metadados; o tempo de execução do plugin continua sendo responsável pelo 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 tempo de execução do plugin. | +| `qaRunners` | Não | `object[]` | Descritores leves de executores de QA usados pelo host compartilhado `openclaw qa` antes de o tempo de execução do plugin ser carregado. | +| `contracts` | Não | `object` | Snapshot estático de capacidade agrupada para fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração de imagem, geração de música, geração de vídeo, busca web, pesquisa na web e propriedade de ferramentas. | +| `mediaUnderstandingProviderMetadata` | Não | `Record` | Padrões leves de compreensão de mídia para IDs de provedores declarados em `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Não | `Record` | Metadados de configuração de canal pertencentes ao manifesto, mesclados às superfícies de descoberta e validação antes de o tempo de execução ser carregado. | +| `skills` | Não | `string[]` | Diretórios de Skills a serem carregados, relativos à raiz do plugin. | +| `name` | Não | `string` | Nome legível do plugin. | +| `description` | Não | `string` | Resumo curto exibido nas superfícies do 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 autenticação. -O OpenClaw lê isso antes de o runtime do provedor carregar. +O OpenClaw lê isso antes de o tempo de execução 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 autenticação para despacho. | -| `choiceId` | Sim | `string` | ID estável de escolha de autenticação usado por fluxos de onboarding e CLI. | -| `choiceLabel` | Não | `string` | Rótulo visível para o usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. | +| `method` | Sim | `string` | ID do método de autenticação para o qual deve encaminhar. | +| `choiceId` | Sim | `string` | ID estável da escolha de autenticação usado por 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 curto de ajuda para o seletor. | -| `assistantPriority` | Não | `number` | Valores menores são ordenados antes em seletores interativos orientados por assistente. | -| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a escolha dos seletores do assistente, ainda permitindo a seleção manual por CLI. | -| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de escolha que devem redirecionar usuários para esta escolha de substituição. | -| `groupId` | Não | `string` | ID opcional de grupo para agrupar escolhas relacionadas. | -| `groupLabel` | Não | `string` | Rótulo visível para o usuário desse grupo. | -| `groupHint` | Não | `string` | Texto curto de ajuda para o grupo. | -| `optionKey` | Não | `string` | Chave interna de opção para fluxos simples de autenticação com uma única flag. | -| `cliFlag` | Não | `string` | Nome da flag de CLI, como `--openrouter-api-key`. | -| `cliOption` | Não | `string` | Formato completo da opção de CLI, como `--openrouter-api-key `. | -| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. | +| `assistantPriority` | Não | `number` | Valores menores são ordenados primeiro 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 de substituição. | +| `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 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 escolha deve aparecer. Se omitido, o padrão é `["text-inference"]`. | ## Referência de `commandAliases` -Use `commandAliases` quando um Plugin for dono de um nome de comando em runtime que usuários podem -colocar por engano em `plugins.allow` ou tentar executar como um comando CLI de raiz. O OpenClaw -usa esses metadados para diagnósticos sem importar o código de runtime do Plugin. +Use `commandAliases` quando um plugin é dono de um nome de comando em tempo de execução que os usuários podem, por engano, colocar 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 tempo de execução do plugin. ```json { @@ -228,30 +211,26 @@ usa esses metadados para diagnósticos sem importar o código de runtime do Plug } ``` -| 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 de chat, e não como um comando CLI de raiz. | -| `cliCommand` | Não | `string` | Comando CLI de raiz relacionado a sugerir para operações de CLI, se existir. | +| 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 slash de chat em vez de um comando raiz da CLI. | +| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a sugerir para operações de CLI, se existir. | ## Referência de `activation` -Use `activation` quando o Plugin puder declarar de forma barata quais eventos do plano de controle -devem ativá-lo depois. +Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle devem ativá-lo mais tarde. ## Referência de `qaRunners` -Use `qaRunners` quando um Plugin contribuir com um ou mais executores de transporte sob -a raiz compartilhada `openclaw qa`. Mantenha esses metadados baratos e estáticos; o runtime do Plugin -continua sendo dono do registro real da CLI por meio de uma superfície leve -`runtime-api.ts` que exporta `qaRunnerCliRegistrations`. +Use `qaRunners` quando um plugin contribuir com um ou mais executores de transporte sob a raiz compartilhada `openclaw qa`. Mantenha esses metadados leves e estáticos; o tempo de execução do plugin continua sendo responsável pelo registro real da CLI por meio de uma superfície leve `runtime-api.ts` que exporta `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Executa a faixa de QA ao vivo do Matrix com Docker contra um homeserver descartável" + "description": "Executa a faixa de QA ao vivo do Matrix com suporte de Docker em um homeserver descartável" } ] } @@ -262,11 +241,7 @@ continua sendo dono do registro real da CLI por meio de uma superfície leve | `commandName` | Sim | `string` | Subcomando montado sob `openclaw qa`, por exemplo `matrix`. | | `description` | Não | `string` | Texto de ajuda de fallback usado quando o host compartilhado precisa de um comando stub. | -Esse bloco é apenas metadado. Ele não registra comportamento de runtime e não -substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/Plugin. -Consumidores atuais o usam como dica de refinamento antes de um carregamento mais amplo do Plugin, então -metadados de ativação ausentes normalmente só custam desempenho; isso não deve -alterar a correção enquanto fallbacks legados de propriedade do manifesto ainda existirem. +Este bloco contém apenas metadados. Ele não registra comportamento de tempo de execução e não substitui `register(...)`, `setupEntry` ou outros entrypoints de tempo de execução/plugin. Os consumidores atuais o usam como uma dica de refinamento antes de um carregamento mais amplo de plugins, então a ausência de metadados de ativação normalmente só custa desempenho; não deve alterar a correção enquanto os fallbacks legados de propriedade no manifesto ainda existirem. ```json { @@ -280,28 +255,23 @@ alterar a correção enquanto fallbacks legados de propriedade do manifesto aind } ``` -| Campo | Obrigatório | Tipo | O que significa | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- | -| `onProviders` | Não | `string[]` | IDs de provedor que devem ativar este Plugin quando solicitados. | -| `onCommands` | Não | `string[]` | IDs de comando que devem ativar este Plugin. | -| `onChannels` | Não | `string[]` | IDs de canal que devem ativar este Plugin. | -| `onRoutes` | Não | `string[]` | Tipos de rota que devem ativar este Plugin. | +| 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. | -Consumidores ativos atuais: +Consumidores ativos atualmente: -- o planejamento de CLI acionado por comando usa fallback para - `commandAliases[].cliCommand` ou `commandAliases[].name` legados -- o planejamento de setup/canal acionado por canal usa fallback para a propriedade - legada `channels[]` quando metadados explícitos de ativação de canal estão ausentes -- o planejamento de setup/runtime acionado por provedor usa fallback para a propriedade - legada `providers[]` e `cliBackends[]` de nível superior quando metadados explícitos de - ativação de provedor estão ausentes +- o planejamento da CLI acionado por comando usa como fallback `commandAliases[].cliCommand` ou `commandAliases[].name` legados +- o planejamento de configuração/canal acionado por canal usa como fallback a propriedade legada `channels[]` quando faltam metadados explícitos de ativação de canal +- o planejamento de configuração/tempo de execução acionado por provedor usa como fallback a propriedade legada `providers[]` e `cliBackends[]` de nível superior quando faltam metadados explícitos de ativação de provedor ## Referência de `setup` -Use `setup` quando superfícies de setup e onboarding precisarem de metadados baratos pertencentes ao Plugin -antes de o runtime carregar. +Use `setup` quando as superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin antes de o tempo de execução ser carregado. ```json { @@ -320,37 +290,28 @@ antes de o runtime carregar. } ``` -`cliBackends` de nível superior continua válido e continua descrevendo -backends de inferência CLI. `setup.cliBackends` é a superfície de descritor específica de setup para -fluxos de plano de controle/setup que devem permanecer apenas como metadados. +`cliBackends` de nível superior continua válido e segue 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. -Quando presentes, `setup.providers` e `setup.cliBackends` são a superfície -preferida de lookup baseada em descritor para descoberta de setup. Se o descritor apenas -restringir o Plugin candidato e o setup ainda precisar de hooks de runtime mais ricos no momento do setup, -defina `requiresRuntime: true` e mantenha `setup-api` como -caminho de execução de fallback. +Quando presentes, `setup.providers` e `setup.cliBackends` são a superfície preferida de busca com descritor em primeiro lugar para descoberta de configuração. Se o descritor apenas restringir o plugin candidato e a configuração ainda precisar de hooks de tempo de execução mais ricos no momento da configuração, defina `requiresRuntime: true` e mantenha `setup-api` como caminho de execução de fallback. -Como o lookup de setup pode executar código `setup-api` pertencente ao Plugin, os valores normalizados -de `setup.providers[].id` e `setup.cliBackends[]` devem permanecer únicos entre os -plugins descobertos. Propriedade ambígua falha em modo fechado em vez de escolher um -vencedor com base na ordem de descoberta. +Como a busca de configuração pode executar código `setup-api` pertencente ao plugin, os valores normalizados de `setup.providers[].id` e `setup.cliBackends[]` devem permanecer únicos entre os plugins descobertos. Propriedade ambígua falha de forma fechada em vez de escolher um vencedor pela ordem de descoberta. ### Referência de `setup.providers` -| Campo | Obrigatório | Tipo | O que significa | -| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------- | -| `id` | Sim | `string` | ID do provedor exposto durante setup ou onboarding. Mantenha IDs normalizados globalmente únicos. | -| `authMethods` | Não | `string[]` | IDs de método de setup/autenticação compatíveis com este provedor sem carregar o runtime completo. | -| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de setup/status podem verificar antes de o runtime do Plugin carregar. | +| Campo | Obrigatório | Tipo | O que significa | +| ------------- | ----------- | ---------- | ----------------------------------------------------------------------------------- | +| `id` | Sim | `string` | ID do provedor exposto durante configuração ou onboarding. Mantenha IDs normalizados globalmente únicos. | +| `authMethods` | Não | `string[]` | IDs de métodos de configuração/autenticação que este provedor suporta sem carregar o tempo de execução completo. | +| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o tempo de execução do plugin ser carregado. | ### Campos de `setup` | Campo | Obrigatório | Tipo | O que significa | | ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Não | `object[]` | Descritores de setup de provedor expostos durante setup e onboarding. | -| `cliBackends` | Não | `string[]` | IDs de backend em tempo de setup usados para lookup de setup orientado por descritor. Mantenha IDs normalizados globalmente únicos. | -| `configMigrations` | Não | `string[]` | IDs de migração de configuração pertencentes à superfície de setup deste Plugin. | -| `requiresRuntime` | Não | `boolean` | Se o setup ainda precisa executar `setup-api` após o lookup do descritor. | +| `providers` | Não | `object[]` | Descritores de configuração de provedor expostos durante configuração e onboarding. | +| `cliBackends` | Não | `string[]` | IDs de backend em tempo de configuração usados para busca com descritor em primeiro lugar. Mantenha IDs normalizados globalmente únicos. | +| `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 de `setup-api` após a busca por descritor. | ## Referência de `uiHints` @@ -371,19 +332,18 @@ vencedor com base na ordem de descoberta. Cada dica de campo pode incluir: -| Campo | Tipo | O que significa | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Rótulo do campo visível para o usuário. | -| `help` | `string` | Texto curto de ajuda. | -| `tags` | `string[]` | Tags de UI opcionais. | -| `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 voltado ao usuário. | +| `help` | `string` | Texto curto de ajuda. | +| `tags` | `string[]` | Tags opcionais de 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 propriedade de capacidades que o OpenClaw possa -ler sem importar o runtime do Plugin. +Use `contracts` apenas para metadados estáticos de propriedade de capacidade que o OpenClaw pode ler sem importar o tempo de execução do plugin. ```json { @@ -403,22 +363,55 @@ ler sem importar o runtime do Plugin. Cada lista é opcional: -| Campo | Tipo | O que significa | -| -------------------------------- | ---------- | -------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs de provedor de fala que pertencem a este Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | IDs de provedor de transcrição em tempo real que pertencem a este Plugin. | -| `realtimeVoiceProviders` | `string[]` | IDs de provedor de voz em tempo real que pertencem a este Plugin. | -| `mediaUnderstandingProviders` | `string[]` | IDs de provedor de compreensão de mídia que pertencem a este Plugin. | -| `imageGenerationProviders` | `string[]` | IDs de provedor de geração de imagem que pertencem a este Plugin. | -| `videoGenerationProviders` | `string[]` | IDs de provedor de geração de vídeo que pertencem a este Plugin. | -| `webFetchProviders` | `string[]` | IDs de provedor de web-fetch que pertencem a este Plugin. | -| `webSearchProviders` | `string[]` | IDs de provedor de busca na web que pertencem a este Plugin. | -| `tools` | `string[]` | Nomes de ferramentas de agente que pertencem a este Plugin para verificações de contrato bundled. | +| 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 compreensão de mídia 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 busca web pertencentes a este plugin. | +| `webSearchProviders` | `string[]` | IDs de provedores de pesquisa na web pertencentes a este plugin. | +| `tools` | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato agrupado. | + +## Referência de `mediaUnderstandingProviderMetadata` + +Use `mediaUnderstandingProviderMetadata` quando um provedor de compreensão de mídia tiver modelos padrão, prioridade de fallback automático de autenticação ou suporte nativo a documentos que auxiliares genéricos do núcleo precisem antes de o tempo de execução ser carregado. As chaves também devem ser declaradas em `contracts.mediaUnderstandingProviders`. + +```json +{ + "contracts": { + "mediaUnderstandingProviders": ["example"] + }, + "mediaUnderstandingProviderMetadata": { + "example": { + "capabilities": ["image", "audio"], + "defaultModels": { + "image": "example-vision-latest", + "audio": "example-transcribe-latest" + }, + "autoPriority": { + "image": 40 + }, + "nativeDocumentInputs": ["pdf"] + } + } +} +``` + +Cada entrada de provedor pode incluir: + +| Campo | Tipo | O que significa | +| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Capacidades de mídia expostas por este provedor. | +| `defaultModels` | `Record` | Padrões de capacidade para modelo usados quando a configuração não especifica um modelo. | +| `autoPriority` | `Record` | Números menores são ordenados primeiro para fallback automático de provedor com base em credenciais. | +| `nativeDocumentInputs` | `"pdf"[]` | Entradas de documento nativas compatíveis com o provedor. | ## Referência de `channelConfigs` -Use `channelConfigs` quando um Plugin de canal precisar de metadados baratos de configuração antes de -o runtime carregar. +Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o tempo de execução ser carregado. ```json { @@ -447,19 +440,17 @@ o runtime carregar. Cada entrada de canal pode incluir: -| 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 de sensibilidade opcionais de UI para essa seção de configuração de canal. | -| `label` | `string` | Rótulo do canal mesclado em superfícies de seletor e inspeção quando os metadados de runtime ainda 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 Plugin legados ou de menor prioridade que este canal deve superar em superfícies de seleção. | +| Campo | Tipo | O que significa | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| `schema` | `object` | Esquema JSON para `channels.`. Obrigatório para cada entrada declarada de configuração de canal. | +| `uiHints` | `Record` | Rótulos de UI/placeholders/dicas de sensibilidade opcionais para essa seção de configuração de canal. | +| `label` | `string` | Rótulo do canal mesclado às superfícies de seletor e inspeção quando os metadados de tempo de execução 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 nas superfícies de seleção. | ## Referência de `modelSupport` -Use `modelSupport` quando o OpenClaw precisar 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 -carregar. +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 tempo de execução do plugin ser carregado. ```json { @@ -472,86 +463,64 @@ carregar. O OpenClaw aplica esta precedência: -- referências explícitas `provider/model` usam os metadados `providers` do manifesto proprietário +- referências explícitas `provider/model` usam os metadados de manifesto `providers` do proprietário - `modelPatterns` têm precedência sobre `modelPrefixes` -- se um Plugin não bundled e um bundled corresponderem, o Plugin não bundled - vence -- ambiguidades restantes são ignoradas até que o usuário ou a configuração especifique um provedor +- se um plugin não agrupado e um plugin agrupado corresponderem, o plugin não agrupado vence +- a ambiguidade restante é ignorada até que o usuário ou a configuração especifique um provedor Campos: -| Campo | Tipo | O que significa | -| --------------- | ---------- | --------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefixos comparados com `startsWith` em IDs abreviados de modelo. | -| `modelPatterns` | `string[]` | Fontes de regex comparadas com IDs abreviados de modelo após a remoção do sufixo de perfil. | +| Campo | Tipo | O que significa | +| --------------- | ---------- | ---------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefixos correspondidos com `startsWith` em relação a IDs abreviados de modelo. | +| `modelPatterns` | `string[]` | Fontes de regex correspondidas em relação a IDs abreviados de modelo após a remoção do sufixo de perfil. | -Chaves legadas de capacidade de 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 -de manifesto não trata mais esses campos de nível superior como -propriedade de capacidade. +As chaves legadas de capacidade de 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 Os dois arquivos têm funções diferentes: -| Arquivo | Use para | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de escolha de autenticação e dicas de UI que precisam existir antes de o código do Plugin rodar | -| `package.json` | Metadados do npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controles de instalação, setup ou metadados de catálogo | +| Arquivo | Use para | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de escolha 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, bloqueio de instalação, configuração ou metadados de catálogo | -Se você não tiver certeza de onde um metadado pertence, use esta regra: +Se você não tiver certeza de onde um metadado deve ficar, use esta regra: -- se o OpenClaw precisar conhecê-lo antes de carregar o código do Plugin, coloque em `openclaw.plugin.json` -- se for sobre empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque em `package.json` +- se o OpenClaw precisar conhecê-lo antes de carregar o código do plugin, coloque-o em `openclaw.plugin.json` +- se ele for sobre empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json` ### Campos de `package.json` que afetam a descoberta -Alguns metadados de Plugin pré-runtime intencionalmente ficam em `package.json` sob o -bloco `openclaw` em vez de `openclaw.plugin.json`. +Alguns metadados de plugin pré-tempo de execução ficam intencionalmente em `package.json` sob o bloco `openclaw`, em vez de `openclaw.plugin.json`. Exemplos importantes: -| Campo | O que significa | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Declara entrypoints nativos de Plugin. Deve permanecer dentro do diretório do pacote do Plugin. | -| `openclaw.runtimeExtensions` | Declara entrypoints de runtime JavaScript compilados para pacotes instalados. Deve permanecer dentro do diretório do pacote do Plugin. | -| `openclaw.setupEntry` | Entrypoint leve apenas de setup usado durante onboarding, inicialização adiada de canal e descoberta somente leitura de status de canal/SecretRef. Deve permanecer dentro do diretório do pacote do Plugin. | -| `openclaw.runtimeSetupEntry` | Declara o entrypoint de setup JavaScript compilado para pacotes instalados. Deve permanecer dentro do diretório do pacote do Plugin. | -| `openclaw.channel` | Metadados baratos de catálogo de canal, como rótulos, caminhos de documentação, aliases e texto de seleção. | -| `openclaw.channel.configuredState` | Metadados leves de verificador de estado configurado que podem responder "já existe setup somente por env?" sem carregar o runtime completo do canal. | -| `openclaw.channel.persistedAuthState` | Metadados leves de 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 bundled 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 bundled quando a configuração é inválida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal somente de setup carreguem antes do Plugin completo do canal durante a inicialização. | +| Campo | O que significa | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.extensions` | Declara entrypoints nativos de plugin. Deve permanecer dentro do diretório do pacote do plugin. | +| `openclaw.runtimeExtensions` | Declara entrypoints de tempo de execução JavaScript compilados para pacotes instalados. Deve permanecer dentro do diretório do pacote do plugin. | +| `openclaw.setupEntry` | Entrypoint leve somente de configuração usado durante onboarding, inicialização adiada de canal e descoberta somente leitura de status de canal/SecretRef. Deve permanecer dentro do diretório do pacote do plugin. | +| `openclaw.runtimeSetupEntry` | Declara o entrypoint JavaScript compilado de configuração para pacotes instalados. Deve permanecer dentro do diretório do pacote do plugin. | +| `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 somente por env já existe?” sem carregar o tempo de execução completo do canal. | +| `openclaw.channel.persistedAuthState` | Metadados leves do verificador de autenticação persistida que podem responder “já existe algo autenticado?” sem carregar o tempo de execução completo do canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins agrupados e publicados externamente. | +| `openclaw.install.defaultChoice` | Caminho de instalação preferido quando há várias fontes de instalaçã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 agrupado quando a configuração é inválida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal somente de configuração sejam carregadas antes do plugin de canal completo durante a inicialização. | -`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do -registro de manifesto. Valores inválidos são rejeitados; valores válidos, porém 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. -Plugins de canal devem fornecer `openclaw.setupEntry` quando status, lista de canais -ou varreduras de SecretRef precisarem identificar contas configuradas sem carregar o runtime completo. -O entry de setup deve expor metadados de canal mais adaptadores seguros para setup de configuração, -status e segredos; mantenha clientes de rede, listeners do gateway e -runtimes de transporte no entrypoint principal da extensão. +Plugins de canal devem fornecer `openclaw.setupEntry` quando verificações de status, lista de canais ou SecretRef precisarem identificar contas configuradas sem carregar o tempo de execução completo. A entrada de configuração deve expor metadados do canal mais adaptadores seguros para configuração, status e segredos; mantenha clientes de rede, listeners do Gateway e tempos de execução de transporte no entrypoint principal da extensão. -Campos de entrypoint de runtime não substituem verificações de limite de pacote para campos -de entrypoint de origem. Por exemplo, `openclaw.runtimeExtensions` não pode tornar -carregável um caminho de `openclaw.extensions` que escape do pacote. +Campos de entrypoint de tempo de execução não substituem verificações de limite de pacote para campos de entrypoint de código-fonte. Por exemplo, `openclaw.runtimeExtensions` não pode tornar carregável um caminho `openclaw.extensions` que escape do pacote. -`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele -não torna configurações arbitrariamente quebradas instaláveis. Hoje ele só permite que fluxos de instalação -recuperem falhas específicas de atualização de Plugin bundled obsoleto, como um -caminho ausente de Plugin bundled ou uma entrada obsoleta `channels.` para esse mesmo -Plugin bundled. Erros de configuração não relacionados ainda bloqueiam a instalação e direcionam operators -para `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna instaláveis configurações arbitrariamente quebradas. Hoje, ele permite apenas que fluxos de instalação se recuperem de falhas específicas e obsoletas de upgrade de plugin agrupado, como um caminho ausente de plugin agrupado ou uma entrada `channels.` obsoleta para esse mesmo plugin agrupado. Erros de configuração não relacionados continuam bloqueando a instalação e encaminham os operadores para `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` é metadado de pacote para um pequeno módulo -verificador: +`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador mínimo: ```json { @@ -567,12 +536,9 @@ verificador: } ``` -Use-o quando fluxos de setup, doctor ou estado configurado precisarem de uma -sondagem barata de autenticação sim/não antes de o Plugin completo do canal carregar. O export de destino deve ser uma função pequena que leia apenas o estado persistido; não o encaminhe pelo barrel completo -de runtime do canal. +Use isso quando fluxos de configuração, doctor ou estado configurado precisarem de uma sondagem leve de autenticação sim/não antes de o plugin de canal completo 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 tempo de execução do canal. -`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas -de estado configurado somente por env: +`openclaw.channel.configuredState` segue o mesmo formato para verificações leves de estado configurado apenas por env: ```json { @@ -588,94 +554,63 @@ de estado configurado somente por env: } ``` -Use-o quando um canal puder responder ao estado configurado a partir de env ou de outras entradas pequenas -fora do 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 isso quando um canal puder responder ao estado configurado a partir de env ou outras entradas mínimas que não dependam de tempo de execução. Se a verificação precisar de resolução completa de configuração ou do tempo de execução real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin. -## Precedência de descoberta (IDs duplicados de Plugin) +## Precedência de descoberta (IDs de plugin duplicados) -O OpenClaw descobre plugins de várias raízes (bundled, instalação global, workspace, caminhos explicitamente selecionados na configuração). Se duas descobertas compartilharem o mesmo `id`, apenas o manifesto de **maior precedência** é mantido; duplicatas de menor precedência são descartadas em vez de serem carregadas lado a lado. +O OpenClaw descobre plugins a partir de várias raízes (agrupados, instalação global, workspace, caminhos explícitos selecionados na configuração). Se duas descobertas compartilharem o mesmo `id`, apenas o manifesto de **maior precedência** será mantido; duplicatas de menor precedência serão descartadas em vez de serem carregadas ao lado dele. Precedência, da maior para a menor: -1. **Selecionado na configuração** — um caminho explicitamente fixado em `plugins.entries.` -2. **Bundled** — plugins distribuídos com o OpenClaw +1. **Selecionado pela configuração** — um caminho fixado explicitamente em `plugins.entries.` +2. **Agrupado** — plugins enviados com o OpenClaw 3. **Instalação global** — plugins instalados na raiz global de plugins do OpenClaw 4. **Workspace** — plugins descobertos em relação ao workspace atual Implicações: -- Uma cópia bifurcada ou desatualizada de um Plugin bundled no workspace não vai sobrescrever a build bundled. -- Para realmente substituir um Plugin bundled por um local, fixe-o por `plugins.entries.` para que ele vença por precedência, em vez de depender da descoberta do workspace. +- Uma cópia bifurcada ou desatualizada de um plugin agrupado que esteja no workspace não substituirá a versão agrupada. +- Para realmente substituir um plugin agrupado por um local, fixe-o via `plugins.entries.` para que ele vença pela precedência, em vez de depender da descoberta no workspace. - Descartes por duplicidade são registrados em log para que o Doctor e os diagnósticos de inicialização possam apontar para a cópia descartada. -## Requisitos de JSON Schema +## Requisitos do esquema JSON -- **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 }`). -- Schemas são validados no momento de leitura/gravação da configuração, não em runtime. +- **Todo plugin deve incluir um esquema JSON**, mesmo que não aceite nenhuma configuração. +- Um esquema vazio é aceitável (por exemplo, `{ "type": "object", "additionalProperties": false }`). +- Os esquemas são validados no momento de leitura/gravação da configuração, não em tempo de execução. ## Comportamento de validação -- Chaves 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 **descobertos**. IDs desconhecidos são **erros**. -- Se um Plugin estiver instalado, mas tiver um manifesto ou schema ausente ou quebrado, - a validação falha e o Doctor relata 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. +- Chaves `channels.*` desconhecidas 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 **descobertos**. IDs desconhecidos são **erros**. +- Se um plugin estiver instalado, mas tiver um manifesto ou esquema ausente ou quebrado, a validação falhará e o Doctor reportará o erro do plugin. +- Se a configuração do plugin existir, mas o plugin estiver **desabilitado**, a configuração será mantida e um **aviso** será exibido no Doctor + logs. -Consulte [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 esquema 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 é 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 campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar - chaves personalizadas de nível superior aqui. -- `providerAuthEnvVars` é o caminho barato de metadados para sondagens de autenticação, validação - de marcadores de env e superfícies semelhantes de autenticação de provedor que não devem iniciar o runtime do Plugin - apenas para inspecionar nomes de env. -- `providerAuthAliases` permite que variantes de provedor reutilizem as variáveis de ambiente de autenticação, - perfis de autenticação, autenticação respaldada por configuração e escolha de onboarding de chave de API - de outro provedor sem codificar essa relação no core. -- `providerEndpoints` permite que plugins de provedor sejam donos de metadados simples de - correspondência de host/baseUrl de endpoint. Use-o apenas para classes de endpoint que o core já suporta; - o Plugin continua sendo dono do comportamento de runtime. -- `syntheticAuthRefs` é o caminho barato de metadados para hooks sintéticos de autenticação pertencentes ao provedor - que precisam estar visíveis para a descoberta fria de modelos antes de o registro de runtime existir. Liste apenas referências cujo provedor de runtime ou backend CLI realmente - implemente `resolveSyntheticAuth`. -- `nonSecretAuthMarkers` é o caminho barato de metadados para chaves de API placeholder pertencentes a Plugin bundled, - como marcadores de credencial local, OAuth ou ambiente. - O core trata isso como não segredo para exibição de autenticação e auditorias de segredo, sem - codificar o provedor proprietário. -- `channelEnvVars` é o caminho barato de metadados para fallback por env de shell, prompts de setup - e superfícies semelhantes de canal que não devem iniciar o runtime do Plugin - apenas para inspecionar nomes de env. Nomes de env são metadados, não ativação por - si só: status, auditoria, validação de entrega de Cron e outras superfícies somente leitura - ainda aplicam política de confiança de Plugin e ativação efetiva antes de - tratar uma variável de ambiente como canal configurado. -- `providerAuthChoices` é o caminho barato de metadados para seletores de escolha de autenticação, - resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples - de flags de CLI de onboarding antes de o runtime do provedor carregar. Para metadados de wizard - em 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 `plugins.slots.*`. +- O tempo de execução ainda carrega o módulo do plugin separadamente; o manifesto é apenas para descoberta + validação. +- Manifestos nativos são analisados com JSON5, então comentários, vírgulas à direita e chaves sem aspas são aceitos, desde que o valor final ainda seja um objeto. +- Apenas os campos de manifesto documentados são lidos pelo carregador de manifesto. Evite adicionar aqui chaves personalizadas de nível superior. +- `providerAuthEnvVars` é o caminho leve de metadados para sondagens de autenticação, validação de marcadores de env e superfícies semelhantes de autenticação de provedor que não devem iniciar o tempo de execução do plugin apenas para inspecionar nomes de env. +- `providerAuthAliases` permite que variantes de provedor reutilizem as variáveis de ambiente de autenticação, perfis de autenticação, autenticação baseada em configuração e escolha de onboarding de chave de API de outro provedor sem codificar rigidamente essa relação no núcleo. +- `providerEndpoints` permite que plugins de provedor sejam donos de metadados simples de correspondência de host/baseUrl de endpoint. Use isso apenas para classes de endpoint que o núcleo já suporta; o plugin continua sendo responsável pelo comportamento de tempo de execução. +- `syntheticAuthRefs` é o caminho leve de metadados para hooks de autenticação sintética pertencentes ao provedor que precisam estar visíveis para a descoberta fria de modelos antes que o registro de tempo de execução exista. Liste apenas referências cujo provedor de tempo de execução ou backend de CLI realmente implemente `resolveSyntheticAuth`. +- `nonSecretAuthMarkers` é o caminho leve de metadados para chaves de API placeholder pertencentes a plugins agrupados, como marcadores de credenciais locais, OAuth ou do ambiente. O núcleo trata isso como não segredo para exibição de autenticação e auditorias de segredos, sem codificar rigidamente o provedor proprietário. +- `channelEnvVars` é o caminho leve de metadados para fallback de env do shell, prompts de configuração e superfícies de canal semelhantes que não devem iniciar o tempo de execução do plugin apenas para inspecionar nomes de env. Nomes de env são metadados, não ativação por si só: status, auditoria, validação de entrega de Cron e outras superfícies somente leitura ainda aplicam a política de confiança do plugin e de ativação efetiva antes de tratar uma variável de ambiente como um canal configurado. +- `providerAuthChoices` é o caminho leve de metadados para seletores de escolha de autenticação, resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags de CLI de onboarding antes de o tempo de execução do provedor ser carregado. Para metadados de assistente em tempo de execução que exigem código do provedor, consulte [Hooks de tempo de execução do provedor](/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` integrado). -- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um - Plugin não precisar deles. -- Se o seu Plugin depender de módulos nativos, documente as etapas de build e quaisquer - requisitos de allowlist do gerenciador de pacotes (por exemplo, pnpm `allow-build-scripts` + (padrão: `legacy` interno). +- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um plugin não precisar deles. +- Se o seu plugin depender de módulos nativos, documente as etapas de build e quaisquer requisitos de allowlist do gerenciador de pacotes (por exemplo, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Relacionado - [Criando Plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins -- [Arquitetura de Plugin](/pt-BR/plugins/architecture) — arquitetura interna +- [Arquitetura de Plugins](/pt-BR/plugins/architecture) — arquitetura interna - [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de Plugin diff --git a/docs/pt-BR/plugins/sdk-channel-plugins.md b/docs/pt-BR/plugins/sdk-channel-plugins.md index 330e9fca9..918ad5b33 100644 --- a/docs/pt-BR/plugins/sdk-channel-plugins.md +++ b/docs/pt-BR/plugins/sdk-channel-plugins.md @@ -2,109 +2,117 @@ read_when: - Você está criando um novo plugin de canal de mensagens - Você quer conectar o OpenClaw a uma plataforma de mensagens - - Você precisa entender a superfície do adaptador ChannelPlugin + - Você precisa entender a superfície do adaptador `ChannelPlugin` sidebarTitle: Channel Plugins -summary: Guia passo a passo para criar um plugin de canal de mensagens para o OpenClaw -title: Criando plugins de canal +summary: Guia passo a passo para criar um plugin de canal de mensagens para OpenClaw +title: Criando Plugins de Canal x-i18n: - generated_at: "2026-04-22T04:24:23Z" + generated_at: "2026-04-22T05:34:50Z" model: gpt-5.4 provider: openai - source_hash: f08bf785cd2e16ed6ce0317f4fd55c9eccecf7476d84148ad47e7be516dd71fb + source_hash: e67d8c4be8cc4a312e5480545497b139c27bed828304de251e6258a3630dd9b5 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# Criando plugins de canal +# Criando Plugins de Canal Este guia mostra como criar um plugin de canal que conecta o OpenClaw a uma -plataforma de mensagens. Ao final, você terá um canal funcional com segurança de DM, -pairing, encadeamento de respostas e mensagens de saída. +plataforma de mensagens. Ao final, você terá um canal funcional com segurança +de DM, pareamento, encadeamento de respostas e mensagens de saída. Se você ainda não criou nenhum plugin do OpenClaw, leia - [Primeiros passos](/pt-BR/plugins/building-plugins) primeiro para entender a estrutura - básica do pacote e a configuração do manifesto. + [Primeiros passos](/pt-BR/plugins/building-plugins) primeiro para entender a + estrutura básica do pacote e a configuração do manifesto. ## Como os plugins de canal funcionam -Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma -ferramenta `message` compartilhada no core. Seu plugin é responsável por: +Os plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma ferramenta `message` compartilhada no core. Seu plugin é responsável por: -- **Configuração** — resolução de conta e assistente de setup -- **Segurança** — política de DM e listas de permissões -- **Pairing** — fluxo de aprovação de DM -- **Gramática de sessão** — como ids de conversa específicos do provedor são mapeados para chats base, ids de thread e fallbacks de pai +- **Configuração** — resolução de conta e assistente de configuração +- **Segurança** — política de DM e listas de permissão +- **Pareamento** — fluxo de aprovação de DM +- **Gramática de sessão** — como os ids de conversa específicos do provedor são mapeados para chats base, ids de thread e fallbacks de pai - **Saída** — envio de texto, mídia e enquetes para a plataforma - **Encadeamento** — como as respostas são encadeadas +- **Digitação de Heartbeat** — sinais opcionais de digitando/ocupado para destinos de entrega do Heartbeat -O core é responsável pela ferramenta de mensagem compartilhada, wiring de prompt, o formato externo da chave de sessão, -a contabilidade genérica de `:thread:` e o despacho. +O core é responsável pela ferramenta de mensagem compartilhada, pela ligação de prompts, pelo formato externo da chave de sessão, pelo controle genérico de `:thread:` e pelo despacho. -Se o seu canal adicionar parâmetros da ferramenta de mensagem que carregam fontes de mídia, exponha esses +Se o seu canal oferecer suporte a indicadores de digitação fora de respostas recebidas, exponha +`heartbeat.sendTyping(...)` no plugin de canal. O core o chama com o +destino de entrega do Heartbeat resolvido antes do início da execução do modelo de Heartbeat e +usa o ciclo de vida compartilhado de keepalive/limpeza de digitação. Adicione `heartbeat.clearTyping(...)` +quando a plataforma exigir um sinal explícito de parada. + +Se o seu canal adicionar parâmetros da ferramenta de mensagem que carreguem fontes de mídia, exponha esses nomes de parâmetro por meio de `describeMessageTool(...).mediaSourceParams`. O core usa -essa lista explícita para normalização de caminho no sandbox e política de acesso a mídia de saída, então os plugins não precisam de casos especiais no core compartilhado para parâmetros específicos do provedor, como avatar, -anexo ou imagem de capa. +essa lista explícita para normalização de caminho no sandbox e para a política +de acesso a mídia de saída, então os plugins não precisam de casos especiais no core compartilhado para parâmetros +específicos do provedor, como avatar, anexo ou imagem de capa. Prefira retornar um mapa indexado por ação, como `{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que ações não relacionadas não -herdem argumentos de mídia de outra ação. Um array simples ainda funciona para parâmetros que -são compartilhados intencionalmente entre todas as ações expostas. +herdem os argumentos de mídia de outra ação. Um array simples ainda funciona para parâmetros que +são intencionalmente compartilhados entre todas as ações expostas. Se sua plataforma armazenar escopo extra dentro de ids de conversa, mantenha essa análise -no plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico -para mapear `rawId` para o id base da conversa, id opcional de thread, +no plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico para mapear +`rawId` para o id base da conversa, id opcional da thread, `baseConversationId` explícito e quaisquer `parentConversationCandidates`. -Quando você retornar `parentConversationCandidates`, mantenha a ordem do pai -mais específico para a conversa pai/base mais ampla. +Ao retornar `parentConversationCandidates`, mantenha-os ordenados do +pai mais específico para a conversa base/mais ampla. -Plugins incluídos que precisem da mesma análise antes de o registro de canais iniciar -também podem expor um arquivo de nível superior `session-key-api.ts` com um -export correspondente `resolveSessionConversation(...)`. O core usa essa superfície segura para bootstrap +Plugins empacotados que precisem da mesma análise antes de o registro de canais iniciar +também podem expor um arquivo `session-key-api.ts` de nível superior com uma +exportação `resolveSessionConversation(...)` correspondente. O core usa essa superfície segura para bootstrap somente quando o registro de plugins em runtime ainda não está disponível. -`messaging.resolveParentConversationCandidates(...)` continua disponível como fallback legado de compatibilidade quando um plugin precisa apenas de fallbacks de pai sobre o id genérico/bruto. Se ambos os hooks existirem, o core usa +`messaging.resolveParentConversationCandidates(...)` continua disponível como +fallback legado de compatibilidade quando um plugin precisa apenas de fallbacks de pai +sobre o id genérico/bruto. Se ambos os hooks existirem, o core usará `resolveSessionConversation(...).parentConversationCandidates` primeiro e só -usa `resolveParentConversationCandidates(...)` como fallback quando o hook canônico -os omite. +recorrerá a `resolveParentConversationCandidates(...)` quando o hook canônico +os omitir. -## Aprovações e capacidades de canal +## Aprovações e capacidades do canal -A maioria dos plugins de canal não precisa de código específico de aprovação. +A maioria dos plugins de canal não precisa de código específico para aprovações. -- O core é responsável por `/approve` no mesmo chat, payloads compartilhados de botão de aprovação e entrega genérica de fallback. +- O core é responsável por `/approve` no mesmo chat, por payloads compartilhados de botão de aprovação e pela entrega genérica de fallback. - Prefira um único objeto `approvalCapability` no plugin de canal quando o canal precisar de comportamento específico de aprovação. -- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/aprovação nativa/renderização/autenticação em `approvalCapability`. +- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/renderização/autenticação/aprovação nativa em `approvalCapability`. - `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autenticação de aprovação desse objeto. -- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a seam canônica de autenticação de aprovação. +- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a interface canônica de autenticação de aprovação. - Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autenticação de aprovação no mesmo chat. -- Se o seu canal expuser aprovações nativas de exec, use `approvalCapability.getExecInitiatingSurfaceState` para o estado de superfície iniciadora/cliente nativo quando ele diferir da autenticação de aprovação no mesmo chat. O core usa esse hook específico de exec para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de exec e incluir o canal na orientação de fallback do cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum. -- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais duplicados de aprovação ou enviar indicadores de digitação antes da entrega. +- Se seu canal expuser aprovações nativas de execução, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autenticação de aprovação no mesmo chat. O core usa esse hook específico de exec para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de exec e incluir o canal na orientação de fallback do cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum. +- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais de aprovação duplicados ou enviar indicadores de digitação antes da entrega. - Use `approvalCapability.delivery` apenas para roteamento de aprovação nativa ou supressão de fallback. -- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa pertencentes ao canal. Mantenha-o lazy em entrypoints quentes de canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda enquanto ainda permite que o core monte o ciclo de vida de aprovação. +- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa pertencentes ao canal. Mantenha isso lazy em entrypoints quentes do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda enquanto ainda permite que o core monte o ciclo de vida da aprovação. - Use `approvalCapability.render` apenas quando um canal realmente precisar de payloads de aprovação personalizados em vez do renderizador compartilhado. -- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique os knobs de configuração exatos necessários para habilitar aprovações nativas de exec. O hook recebe `{ channel, channelLabel, accountId }`; canais com contas nomeadas devem renderizar caminhos com escopo de conta, como `channels..accounts..execApprovals.*`, em vez de padrões de nível superior. -- Se um canal puder inferir identidades estáveis semelhantes a proprietários em DM a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação no core. -- Se um canal precisar de entrega nativa de aprovação, mantenha o código do canal focado em normalização de alvo mais fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal por trás de `approvalCapability.nativeRuntime`, idealmente via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e ser responsável por filtragem de requisição, roteamento, deduplicação, expiração, assinatura do Gateway e avisos de roteamento alternativo. `nativeRuntime` é dividido em algumas seams menores: +- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique os controles exatos de configuração necessários para habilitar aprovações nativas de exec. O hook recebe `{ channel, channelLabel, accountId }`; canais com conta nomeada devem renderizar caminhos com escopo de conta, como `channels..accounts..execApprovals.*`, em vez de padrões de nível superior. +- Se um canal puder inferir identidades de DM estáveis semelhantes a proprietários a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core. +- Se um canal precisar de entrega de aprovação nativa, mantenha o código do canal focado em normalização de destino mais fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal atrás de `approvalCapability.nativeRuntime`, idealmente por meio de `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e ser responsável por filtragem de requisições, roteamento, deduplicação, expiração, assinatura do gateway e avisos de roteamento alternativo. `nativeRuntime` é dividido em algumas interfaces menores: - `availability` — se a conta está configurada e se uma requisição deve ser tratada -- `presentation` — mapeia o view model compartilhado de aprovação para payloads nativos pendentes/resolvidos/expirados ou ações finais -- `transport` — prepara alvos mais envio/atualização/exclusão de mensagens nativas de aprovação -- `interactions` — hooks opcionais de bind/unbind/clear-action para botões ou reações nativas -- `observe` — hooks opcionais para diagnósticos de entrega -- Se o canal precisar de objetos pertencentes ao runtime, como um cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar glue específica de aprovação. -- Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` em nível mais baixo apenas quando a seam orientada por capacidade ainda não for expressiva o suficiente. -- Canais de aprovação nativa devem rotear tanto `accountId` quanto `approvalKind` por esses helpers. `accountId` mantém a política de aprovação multi-conta com escopo na conta correta do bot, e `approvalKind` mantém disponível para o canal o comportamento de aprovação de exec vs plugin sem branches hardcoded no core. -- O core agora também é responsável por avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe que o core agregue as entregas reais antes de publicar qualquer aviso de volta no chat iniciador. -- Preserve o tipo do id de aprovação entregue de ponta a ponta. Clientes nativos não devem - adivinhar nem reescrever o roteamento de aprovação de exec vs plugin com base em estado local do canal. +- `presentation` — mapeia o modelo de view de aprovação compartilhado para payloads nativos pendentes/resolvidos/expirados ou ações finais +- `transport` — prepara destinos mais envia/atualiza/exclui mensagens nativas de aprovação +- `interactions` — hooks opcionais de bind/unbind/clear-action para botões nativos ou reações +- `observe` — hooks opcionais de diagnóstico de entrega +- Se o canal precisar de objetos controlados pelo runtime, como um cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar cola de wrapper específica de aprovação. +- Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de nível mais baixo apenas quando a interface orientada por capacidade ainda não for expressiva o suficiente. +- Canais de aprovação nativa devem rotear `accountId` e `approvalKind` por esses helpers. `accountId` mantém a política de aprovação multi-conta com escopo para a conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de exec vs plugin disponível ao canal sem ramificações codificadas no core. +- O core agora também é responsável por avisos de reroteamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha o roteamento correto de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador. +- Preserve o tipo de id de aprovação entregue de ponta a ponta. Clientes nativos não devem + adivinhar nem reescrever o roteamento de aprovação de exec vs plugin a partir do estado local do canal. - Diferentes tipos de aprovação podem expor intencionalmente diferentes superfícies nativas. - Exemplos atuais incluídos: - - O Slack mantém o roteamento de aprovação nativa disponível para ids de aprovação de exec e de plugin. - - O Matrix mantém o mesmo roteamento nativo de DM/canal e a mesma UX de reação para aprovações de exec - e de plugin, ao mesmo tempo em que permite que a autenticação difira por tipo de aprovação. -- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas código novo deve preferir o builder de capacidade e expor `approvalCapability` no plugin. + Exemplos empacotados atuais: + - O Slack mantém o roteamento de aprovação nativa disponível para ids de exec e de plugin. + - O Matrix mantém o mesmo roteamento nativo de DM/canal e UX baseada em reação para aprovações de exec + e de plugin, enquanto ainda permite que a autenticação difira por tipo de aprovação. +- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas código novo deve preferir o construtor de capacidade e expor `approvalCapability` no plugin. -Para entrypoints quentes de canal, prefira os subcaminhos de runtime mais estreitos quando você +Para entrypoints quentes do canal, prefira os subcaminhos de runtime mais específicos quando você precisar apenas de uma parte dessa família: - `openclaw/plugin-sdk/approval-auth-runtime` @@ -122,8 +130,8 @@ Da mesma forma, prefira `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` e -`openclaw/plugin-sdk/reply-chunking` quando você não precisar da -superfície guarda-chuva mais ampla. +`openclaw/plugin-sdk/reply-chunking` quando você não precisar da superfície +guarda-chuva mais ampla. Especificamente para setup: @@ -131,94 +139,101 @@ Especificamente para setup: adaptadores de patch de setup seguros para importação (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`), saída de nota de lookup, - `promptResolvedAllowFrom`, `splitSetupEntries` e os builders delegados - de proxy de setup -- `openclaw/plugin-sdk/setup-adapter-runtime` é a seam estreita e compatível com env + `promptResolvedAllowFrom`, `splitSetupEntries` e os builders + delegados de proxy de setup +- `openclaw/plugin-sdk/setup-adapter-runtime` é a interface estreita com suporte a env para `createEnvPatchedAccountSetupAdapter` - `openclaw/plugin-sdk/channel-setup` cobre os builders de setup de instalação opcional mais alguns primitivos seguros para setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Se seu canal oferecer suporte a setup ou autenticação orientados por env e fluxos genéricos de inicialização/configuração -precisarem conhecer esses nomes de env antes de o runtime carregar, declare-os no -manifesto do plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas para cópia voltada ao operador. +Se o seu canal oferecer suporte a setup ou autenticação orientados por env e os fluxos genéricos de inicialização/configuração +precisarem conhecer esses nomes de env antes do carregamento do runtime, declare-os no +manifesto do plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais +apenas para cópia voltada ao operador. -Se seu canal puder aparecer em `status`, `channels list`, `channels status` ou -varreduras de SecretRef antes de o runtime do plugin iniciar, adicione `openclaw.setupEntry` em -`package.json`. Esse entrypoint deve ser seguro para importar em caminhos de comando somente leitura -e deve retornar os metadados do canal, adaptador de configuração seguro para setup, adaptador de status e metadados de alvo secreto do canal necessários para esses resumos. Não inicie clientes, listeners ou runtimes de transporte a partir do entry de setup. +Se o seu canal puder aparecer em `status`, `channels list`, `channels status` ou +varreduras de SecretRef antes do início do runtime do plugin, adicione `openclaw.setupEntry` em +`package.json`. Esse entrypoint deve ser seguro para importação em caminhos de comando somente leitura +e deve retornar os metadados do canal, o adaptador de configuração seguro para setup, o +adaptador de status e os metadados de destino de segredo do canal necessários para esses resumos. Não +inicie clientes, listeners ou runtimes de transporte a partir da entrada de setup. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` e `splitSetupEntries` -- use a seam mais ampla `openclaw/plugin-sdk/setup` apenas quando você também precisar dos +- use a interface mais ampla `openclaw/plugin-sdk/setup` apenas quando você também precisar dos helpers compartilhados mais pesados de setup/configuração, como `moveSingleAccountChannelSectionToDefaultAccount(...)` -Se seu canal quiser apenas anunciar "instale este plugin primeiro" em superfícies -de setup, prefira `createOptionalChannelSetupSurface(...)`. O -adaptador/assistente gerado falha de forma fechada em gravações de configuração e finalização, e reutiliza a mesma mensagem de instalação obrigatória em validação, finalização e cópia de link de documentação. +Se o seu canal quiser apenas anunciar "instale este plugin primeiro" em +superfícies de setup, prefira `createOptionalChannelSetupSurface(...)`. O +adaptador/assistente gerado falha de forma fechada em gravações de configuração e finalização, e reutiliza +a mesma mensagem de instalação obrigatória em validação, finalização e cópia +de link para docs. -Para outros caminhos quentes de canal, prefira os helpers estreitos em vez de superfícies legadas mais amplas: +Para outros caminhos quentes do canal, prefira os helpers mais específicos em vez das +superfícies legadas mais amplas: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` e `openclaw/plugin-sdk/account-helpers` para configuração multi-conta e - fallback da conta padrão + fallback de conta padrão - `openclaw/plugin-sdk/inbound-envelope` e `openclaw/plugin-sdk/inbound-reply-dispatch` para rota/envelope de entrada e - wiring de registrar e despachar -- `openclaw/plugin-sdk/messaging-targets` para análise/correspondência de alvo + ligação de registrar e despachar +- `openclaw/plugin-sdk/messaging-targets` para análise/correspondência de destinos - `openclaw/plugin-sdk/outbound-media` e `openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia mais delegados de identidade/envio de saída e planejamento de payload - `buildThreadAwareOutboundSessionRoute(...)` de `openclaw/plugin-sdk/channel-core` quando uma rota de saída deve preservar um - `replyToId`/`threadId` explícito ou recuperar a sessão atual `:thread:` - depois que a chave da sessão base ainda corresponder. Plugins de provedor podem substituir - precedência, comportamento de sufixo e normalização de id de thread quando a plataforma + `replyToId`/`threadId` explícito ou recuperar a sessão `:thread:` atual + depois que a chave base da sessão ainda corresponder. Plugins de provedor podem substituir + precedência, comportamento de sufixo e normalização de id de thread quando sua plataforma tiver semântica nativa de entrega em thread. -- `openclaw/plugin-sdk/thread-bindings-runtime` para o ciclo de vida de vínculo de thread - e registro de adaptador -- `openclaw/plugin-sdk/agent-media-payload` somente quando um layout legado de - campo de payload de agente/mídia ainda for necessário -- `openclaw/plugin-sdk/telegram-command-config` para normalização de comando personalizado do Telegram, - validação de duplicidade/conflito e um contrato estável de fallback para configuração de comando +- `openclaw/plugin-sdk/thread-bindings-runtime` para o ciclo de vida de binding + de thread e registro de adaptador +- `openclaw/plugin-sdk/agent-media-payload` apenas quando ainda for necessário + um layout legado de campo de payload de agente/mídia +- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos + personalizados do Telegram, validação de duplicatas/conflitos e um contrato + de configuração de comando estável para fallback -Canais somente de autenticação normalmente podem parar no caminho padrão: o core lida com aprovações e o plugin apenas expõe capacidades de saída/autenticação. Canais com aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de criar seu próprio ciclo de vida de aprovação. +Canais somente de autenticação normalmente podem parar no caminho padrão: o core cuida das aprovações e o plugin apenas expõe capacidades de saída/autenticação. Canais com aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação. ## Política de menção de entrada -Mantenha o tratamento de menção de entrada dividido em duas camadas: +Mantenha o tratamento de menções de entrada dividido em duas camadas: - coleta de evidências pertencente ao plugin - avaliação de política compartilhada Use `openclaw/plugin-sdk/channel-mention-gating` para decisões de política de menção. -Use `openclaw/plugin-sdk/channel-inbound` somente quando precisar do barrel mais amplo -de helpers de entrada. +Use `openclaw/plugin-sdk/channel-inbound` apenas quando você precisar do barrel +mais amplo de helpers de entrada. -Casos adequados para lógica local do plugin: +Bom encaixe para lógica local do plugin: - detecção de resposta ao bot - detecção de citação do bot - verificações de participação em thread -- exclusões de mensagem de serviço/sistema +- exclusões de mensagens de serviço/sistema - caches nativos da plataforma necessários para comprovar participação do bot -Casos adequados para o helper compartilhado: +Bom encaixe para o helper compartilhado: - `requireMention` - resultado explícito de menção -- lista de permissões de menção implícita +- allowlist implícita de menção - bypass de comando - decisão final de ignorar Fluxo preferido: -1. Calcule fatos locais de menção. +1. Calcule os fatos locais de menção. 2. Passe esses fatos para `resolveInboundMentionDecision({ facts, policy })`. 3. Use `decision.effectiveWasMentioned`, `decision.shouldBypassMention` e `decision.shouldSkip` no seu gate de entrada. @@ -260,7 +275,7 @@ if (decision.shouldSkip) return; ``` `api.runtime.channel.mentions` expõe os mesmos helpers compartilhados de menção para -plugins de canal incluídos que já dependem de injeção de runtime: +plugins de canal empacotados que já dependem de injeção em runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -268,13 +283,13 @@ plugins de canal incluídos que já dependem de injeção de runtime: - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Se você só precisar de `implicitMentionKindWhen` e +Se você precisar apenas de `implicitMentionKindWhen` e `resolveInboundMentionDecision`, importe de -`openclaw/plugin-sdk/channel-mention-gating` para evitar carregar helpers -de runtime de entrada não relacionados. +`openclaw/plugin-sdk/channel-mention-gating` para evitar carregar helpers de runtime +de entrada não relacionados. Os helpers mais antigos `resolveMentionGating*` permanecem em -`openclaw/plugin-sdk/channel-inbound` apenas como exports de compatibilidade. Código novo +`openclaw/plugin-sdk/channel-inbound` apenas como exportações de compatibilidade. Código novo deve usar `resolveInboundMentionDecision({ facts, policy })`. ## Passo a passo @@ -283,8 +298,8 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. Crie os arquivos padrão do plugin. O campo `channel` em `package.json` é - o que torna este um plugin de canal. Para a superfície completa de metadados do pacote, - consulte [Setup e configuração de plugin](/pt-BR/plugins/sdk-setup#openclaw-channel): + o que torna este um plugin de canal. Para toda a superfície de metadados do pacote, + veja [Setup e Configuração de Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -335,7 +350,7 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. A interface `ChannelPlugin` tem muitas superfícies de adaptador opcionais. Comece com - o mínimo — `id` e `setup` — e adicione adaptadores conforme necessário. + o mínimo — `id` e `setup` — e adicione adaptadores conforme precisar deles. Crie `src/channel.ts`: @@ -437,8 +452,8 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. | Opção | O que ela conecta | | --- | --- | | `security.dm` | Resolvedor de segurança de DM com escopo a partir de campos de configuração | - | `pairing.text` | Fluxo de pairing de DM baseado em texto com troca de código | - | `threading` | Resolvedor do modo reply-to (fixo, com escopo de conta ou personalizado) | + | `pairing.text` | Fluxo de pareamento de DM baseado em texto com troca de código | + | `threading` | Resolvedor de modo reply-to (fixo, com escopo de conta ou personalizado) | | `outbound.attachedResults` | Funções de envio que retornam metadados de resultado (ids de mensagem) | Você também pode passar objetos de adaptador brutos em vez das opções declarativas @@ -485,19 +500,19 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. Coloque descritores de CLI pertencentes ao canal em `registerCliMetadata(...)` para que o OpenClaw possa mostrá-los na ajuda raiz sem ativar o runtime completo do canal, - enquanto carregamentos completos normais ainda capturam os mesmos descritores para registro real de comando. + enquanto carregamentos completos normais ainda capturam os mesmos descritores para o registro real de comandos. Mantenha `registerFull(...)` para trabalho somente de runtime. - Se `registerFull(...)` registrar métodos RPC do Gateway, use um - prefixo específico do plugin. Namespaces administrativos do core (`config.*`, + Se `registerFull(...)` registrar métodos RPC do gateway, use um + prefixo específico do plugin. Namespaces de administração do core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre resolvem para `operator.admin`. - `defineChannelPluginEntry` trata automaticamente a separação de modo de registro. Consulte + `defineChannelPluginEntry` trata automaticamente a divisão do modo de registro. Veja [Entrypoints](/pt-BR/plugins/sdk-entrypoints#definechannelpluginentry) para todas as opções. - + Crie `setup-entry.ts` para carregamento leve durante o onboarding: ```typescript setup-entry.ts @@ -507,18 +522,18 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. export default defineSetupPluginEntry(acmeChatPlugin); ``` - O OpenClaw carrega isso em vez do entry completo quando o canal está desabilitado + O OpenClaw carrega isso em vez da entrada completa quando o canal está desabilitado ou não configurado. Isso evita puxar código pesado de runtime durante fluxos de setup. - Consulte [Setup e configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes. + Veja [Setup e Configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes. - Canais incluídos do workspace que dividem exports seguros para setup em módulos - sidecar podem usar `defineBundledChannelSetupEntry(...)` de + Canais empacotados do workspace que dividem exportações seguras para setup em módulos + auxiliares podem usar `defineBundledChannelSetupEntry(...)` de `openclaw/plugin-sdk/channel-entry-contract` quando também precisarem de um setter explícito de runtime em tempo de setup. - + Seu plugin precisa receber mensagens da plataforma e encaminhá-las para o OpenClaw. O padrão típico é um Webhook que verifica a requisição e a despacha por meio do handler de entrada do seu canal: @@ -527,13 +542,13 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // autenticação gerenciada pelo plugin (verifique as assinaturas por conta própria) + auth: "plugin", // autenticação gerenciada pelo plugin (verifique as assinaturas você mesmo) handler: async (req, res) => { const event = parseWebhookPayload(req); // Seu handler de entrada despacha a mensagem para o OpenClaw. - // O wiring exato depende do SDK da sua plataforma — - // veja um exemplo real no pacote de plugin incluído do Microsoft Teams ou do Google Chat. + // A conexão exata depende do SDK da sua plataforma — + // veja um exemplo real no pacote de plugin empacotado do Microsoft Teams ou do Google Chat. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -545,8 +560,8 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. ``` - O tratamento de mensagens de entrada é específico de cada canal. Cada plugin de canal é responsável - pelo seu próprio pipeline de entrada. Veja plugins de canal incluídos + O tratamento de mensagens de entrada é específico do canal. Cada plugin de canal é responsável + pelo seu próprio pipeline de entrada. Veja plugins de canal empacotados (por exemplo, o pacote de plugin do Microsoft Teams ou do Google Chat) para padrões reais. @@ -554,7 +569,7 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. -Escreva testes colocados junto do código em `src/channel.test.ts`: +Escreva testes colocalizados em `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -592,7 +607,7 @@ Escreva testes colocados junto do código em `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Para helpers de teste compartilhados, consulte [Testing](/pt-BR/plugins/sdk-testing). + Para helpers de teste compartilhados, veja [Testes](/pt-BR/plugins/sdk-testing). @@ -605,12 +620,12 @@ Escreva testes colocados junto do código em `src/channel.test.ts`: ├── openclaw.plugin.json # Manifesto com schema de configuração ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Exports públicos (opcional) -├── runtime-api.ts # Exports internos de runtime (opcional) +├── api.ts # Exportações públicas (opcional) +├── runtime-api.ts # Exportações internas de runtime (opcional) └── src/ ├── channel.ts # ChannelPlugin via createChatChannelPlugin ├── channel.test.ts # Testes - ├── client.ts # Cliente de API da plataforma + ├── client.ts # Cliente da API da plataforma └── runtime.ts # Armazenamento de runtime (se necessário) ``` @@ -618,12 +633,12 @@ Escreva testes colocados junto do código em `src/channel.test.ts`: - Modos fixos de resposta, com escopo de conta ou personalizados + Modos de resposta fixos, com escopo de conta ou personalizados - describeMessageTool e descoberta de ação + describeMessageTool e descoberta de ações - + inferTargetChatType, looksLikeId, resolveTarget @@ -632,15 +647,15 @@ Escreva testes colocados junto do código em `src/channel.test.ts`: -Algumas seams de helper incluídas ainda existem para manutenção e -compatibilidade de plugins incluídos. Elas não são o padrão recomendado para novos plugins de canal; -prefira os subcaminhos genéricos de canal/setup/resposta/runtime da superfície -comum do SDK, a menos que você esteja mantendo diretamente essa família de plugins incluídos. +Algumas interfaces auxiliares empacotadas ainda existem para manutenção de plugins +empacotados e compatibilidade. Elas não são o padrão recomendado para novos plugins de canal; +prefira os subcaminhos genéricos de channel/setup/reply/runtime da superfície comum do SDK, +a menos que você esteja mantendo diretamente essa família de plugins empacotados. ## Próximos passos -- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — se o seu plugin também fornecer modelos -- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de imports por subcaminho +- [Plugins de Provedor](/pt-BR/plugins/sdk-provider-plugins) — se o seu plugin também fornecer modelos +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de importação de subcaminhos - [Testes do SDK](/pt-BR/plugins/sdk-testing) — utilitários de teste e testes de contrato -- [Manifesto de plugin](/pt-BR/plugins/manifest) — schema completo do manifesto +- [Manifesto de Plugin](/pt-BR/plugins/manifest) — schema completo do manifesto diff --git a/docs/pt-BR/providers/ollama.md b/docs/pt-BR/providers/ollama.md index b409bcc8e..2d498e75f 100644 --- a/docs/pt-BR/providers/ollama.md +++ b/docs/pt-BR/providers/ollama.md @@ -1,25 +1,25 @@ --- read_when: - - Você quer executar o OpenClaw com modelos em nuvem ou locais via Ollama - - Você precisa de orientação para configuração e setup do Ollama + - Você quer executar o OpenClaw com modelos na nuvem ou locais via Ollama + - Você precisa de orientação para configurar e usar o Ollama - Você quer modelos de visão do Ollama para compreensão de imagens -summary: Executar o OpenClaw com Ollama (modelos em nuvem e locais) +summary: Execute o OpenClaw com Ollama (modelos na nuvem e locais) title: Ollama x-i18n: - generated_at: "2026-04-22T04:26:43Z" + generated_at: "2026-04-22T05:34:49Z" model: gpt-5.4 provider: openai - source_hash: 32623b6523f22930a5987fb22d2074f1e9bb274cc01ae1ad1837825cc04ec179 + source_hash: 704beed3bf988d6c2ad50b2a1533f6dcef655e44b34f23104827d2acb71b8655 source_path: providers/ollama.md workflow: 15 --- # Ollama -O OpenClaw integra com a API nativa do Ollama (`/api/chat`) para modelos em nuvem hospedados e servidores Ollama locais/self-hosted. Você pode usar o Ollama em três modos: `Cloud + Local` por um host Ollama acessível, `Cloud only` contra `https://ollama.com`, ou `Local only` contra um host Ollama acessível. +O OpenClaw se integra com a API nativa do Ollama (`/api/chat`) para modelos hospedados na nuvem e servidores Ollama locais/autohospedados. Você pode usar o Ollama em três modos: `Cloud + Local` por meio de um host Ollama acessível, `Cloud only` em `https://ollama.com`, ou `Local only` em um host Ollama acessível. -**Usuários de Ollama remoto**: não use a URL compatível com OpenAI `/v1` (`http://host:11434/v1`) com o OpenClaw. Isso quebra o tool calling e os modelos podem gerar JSON bruto de ferramenta como texto simples. Use a URL da API nativa do Ollama: `baseUrl: "http://host:11434"` (sem `/v1`). +**Usuários de Ollama remoto**: Não use a URL compatível com OpenAI `/v1` (`http://host:11434/v1`) com o OpenClaw. Isso quebra a chamada de ferramentas e os modelos podem gerar JSON bruto de ferramentas como texto simples. Use a URL da API nativa do Ollama: `baseUrl: "http://host:11434"` (sem `/v1`). ## Primeiros passos @@ -28,7 +28,7 @@ Escolha seu método e modo de configuração preferidos. - **Melhor para:** caminho mais rápido para uma configuração funcional do Ollama local ou em nuvem. + **Melhor para:** caminho mais rápido para uma configuração funcional do Ollama na nuvem ou local. @@ -36,15 +36,15 @@ Escolha seu método e modo de configuração preferidos. openclaw onboard ``` - Selecione **Ollama** na lista de providers. + Selecione **Ollama** na lista de provedores. - - **Cloud + Local** — host Ollama local mais modelos em nuvem roteados por esse host + - **Cloud + Local** — host Ollama local mais modelos na nuvem roteados por esse host - **Cloud only** — modelos Ollama hospedados via `https://ollama.com` - **Local only** — apenas modelos locais - `Cloud only` solicita `OLLAMA_API_KEY` e sugere padrões hospedados em nuvem. `Cloud + Local` e `Local only` pedem uma base URL do Ollama, descobrem os modelos disponíveis e fazem `pull` automático do modelo local selecionado se ele ainda não estiver disponível. `Cloud + Local` também verifica se esse host Ollama está autenticado para acesso à nuvem. + `Cloud only` solicita `OLLAMA_API_KEY` e sugere padrões hospedados na nuvem. `Cloud + Local` e `Local only` pedem uma URL base do Ollama, descobrem os modelos disponíveis e fazem `pull` automaticamente do modelo local selecionado se ele ainda não estiver disponível. `Cloud + Local` também verifica se esse host Ollama está autenticado para acesso à nuvem. ```bash @@ -61,7 +61,7 @@ Escolha seu método e modo de configuração preferidos. --accept-risk ``` - Opcionalmente, especifique uma base URL ou modelo personalizado: + Opcionalmente, especifique uma URL base personalizada ou um modelo: ```bash openclaw onboard --non-interactive \ @@ -74,15 +74,15 @@ Escolha seu método e modo de configuração preferidos. - **Melhor para:** controle total sobre configuração local ou em nuvem. + **Melhor para:** controle total da configuração na nuvem ou local. - - **Cloud + Local**: instale o Ollama, autentique com `ollama signin` e roteie requisições em nuvem por esse host - - **Cloud only**: use `https://ollama.com` com um `OLLAMA_API_KEY` + - **Cloud + Local**: instale o Ollama, autentique-se com `ollama signin` e roteie solicitações da nuvem por esse host + - **Cloud only**: use `https://ollama.com` com uma `OLLAMA_API_KEY` - **Local only**: instale o Ollama em [ollama.com/download](https://ollama.com/download) - + ```bash ollama pull gemma4 # ou @@ -91,14 +91,14 @@ Escolha seu método e modo de configuração preferidos. ollama pull llama3.3 ``` - - Para `Cloud only`, use seu `OLLAMA_API_KEY` real. Para configurações baseadas em host, qualquer valor placeholder funciona: + + Para `Cloud only`, use sua `OLLAMA_API_KEY` real. Para configurações baseadas em host, qualquer valor de placeholder funciona: ```bash # Nuvem export OLLAMA_API_KEY="your-ollama-api-key" - # Somente local + # Apenas local export OLLAMA_API_KEY="ollama-local" # Ou configure no seu arquivo de configuração @@ -128,52 +128,52 @@ Escolha seu método e modo de configuração preferidos. -## Modelos em nuvem +## Modelos na nuvem - `Cloud + Local` usa um host Ollama acessível como ponto de controle tanto para modelos locais quanto em nuvem. Esse é o fluxo híbrido preferido do Ollama. + `Cloud + Local` usa um host Ollama acessível como ponto de controle para modelos locais e na nuvem. Esse é o fluxo híbrido preferido do Ollama. - Use **Cloud + Local** durante a configuração. O OpenClaw solicita a base URL do Ollama, descobre os modelos locais nesse host e verifica se o host está autenticado para acesso à nuvem com `ollama signin`. Quando o host está autenticado, o OpenClaw também sugere padrões hospedados em nuvem como `kimi-k2.5:cloud`, `minimax-m2.7:cloud` e `glm-5.1:cloud`. + Use **Cloud + Local** durante a configuração. O OpenClaw solicita a URL base do Ollama, descobre modelos locais nesse host e verifica se o host está autenticado para acesso à nuvem com `ollama signin`. Quando o host está autenticado, o OpenClaw também sugere padrões hospedados na nuvem como `kimi-k2.5:cloud`, `minimax-m2.7:cloud` e `glm-5.1:cloud`. - Se o host ainda não estiver autenticado, o OpenClaw mantém a configuração como somente local até que você execute `ollama signin`. + Se o host ainda não estiver autenticado, o OpenClaw mantém a configuração apenas local até que você execute `ollama signin`. - `Cloud only` roda contra a API hospedada do Ollama em `https://ollama.com`. + `Cloud only` é executado na API hospedada do Ollama em `https://ollama.com`. - Use **Cloud only** durante a configuração. O OpenClaw solicita `OLLAMA_API_KEY`, define `baseUrl: "https://ollama.com"` e inicializa a lista de modelos hospedados em nuvem. Esse caminho **não** requer um servidor Ollama local nem `ollama signin`. + Use **Cloud only** durante a configuração. O OpenClaw solicita `OLLAMA_API_KEY`, define `baseUrl: "https://ollama.com"` e inicializa a lista de modelos hospedados na nuvem. Esse caminho **não** requer um servidor Ollama local nem `ollama signin`. - A lista de modelos em nuvem mostrada durante `openclaw onboard` é preenchida ao vivo de `https://ollama.com/api/tags`, limitada a 500 entradas, para que o seletor reflita o catálogo hospedado atual em vez de uma lista estática. Se `ollama.com` estiver inacessível ou não retornar modelos no momento da configuração, o OpenClaw usa como fallback as sugestões hardcoded anteriores para que o onboarding ainda seja concluído. + A lista de modelos na nuvem mostrada durante `openclaw onboard` é preenchida ao vivo a partir de `https://ollama.com/api/tags`, limitada a 500 entradas, para que o seletor reflita o catálogo hospedado atual em vez de uma lista estática. Se `ollama.com` estiver inacessível ou não retornar modelos no momento da configuração, o OpenClaw volta às sugestões codificadas anteriormente para que o onboarding ainda seja concluído. - No modo somente local, o OpenClaw descobre modelos a partir da instância Ollama configurada. Esse caminho é para servidores Ollama locais ou self-hosted. + No modo apenas local, o OpenClaw descobre modelos a partir da instância Ollama configurada. Esse caminho é destinado a servidores Ollama locais ou autohospedados. - O OpenClaw atualmente sugere `gemma4` como padrão local. + Atualmente, o OpenClaw sugere `gemma4` como padrão local. -## Descoberta de modelos (provider implícito) +## Descoberta de modelos (provedor implícito) -Quando você define `OLLAMA_API_KEY` (ou um perfil de autenticação) e **não** define `models.providers.ollama`, o OpenClaw descobre modelos a partir da instância local do Ollama em `http://127.0.0.1:11434`. +Quando você define `OLLAMA_API_KEY` (ou um perfil de autenticação) e **não** define `models.providers.ollama`, o OpenClaw descobre modelos a partir da instância Ollama local em `http://127.0.0.1:11434`. -| Comportamento | Detalhe | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Consulta ao catálogo | Consulta `/api/tags` | -| Detecção de capacidades | Usa buscas best-effort em `/api/show` para ler `contextWindow` e detectar capacidades (incluindo visão) | -| Modelos de visão | Modelos com capacidade `vision` informada por `/api/show` são marcados como compatíveis com imagem (`input: ["text", "image"]`), então o OpenClaw injeta imagens automaticamente no prompt | -| Detecção de reasoning | Marca `reasoning` com uma heurística por nome de modelo (`r1`, `reasoning`, `think`) | -| Limites de token | Define `maxTokens` para o limite máximo padrão de tokens do Ollama usado pelo OpenClaw | -| Custos | Define todos os custos como `0` | +| Comportamento | Detalhe | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Consulta ao catálogo | Consulta `/api/tags` | +| Detecção de recursos | Usa consultas de melhor esforço a `/api/show` para ler `contextWindow` e detectar recursos (incluindo visão) | +| Modelos de visão | Modelos com o recurso `vision` relatado por `/api/show` são marcados como compatíveis com imagens (`input: ["text", "image"]`), então o OpenClaw injeta imagens automaticamente no prompt | +| Detecção de raciocínio | Marca `reasoning` com uma heurística baseada no nome do modelo (`r1`, `reasoning`, `think`) | +| Limites de tokens | Define `maxTokens` para o limite máximo padrão de tokens do Ollama usado pelo OpenClaw | +| Custos | Define todos os custos como `0` | -Isso evita entradas manuais de modelo e mantém o catálogo alinhado com a instância local do Ollama. +Isso evita entradas manuais de modelos enquanto mantém o catálogo alinhado com a instância Ollama local. ```bash -# Ver o que modelos estão disponíveis +# Ver o que há de modelos disponíveis ollama list openclaw models list ``` @@ -187,21 +187,21 @@ ollama pull mistral O novo modelo será descoberto automaticamente e ficará disponível para uso. -Se você definir `models.providers.ollama` explicitamente, a descoberta automática será ignorada e você precisará definir os modelos manualmente. Consulte a seção de configuração explícita abaixo. +Se você definir `models.providers.ollama` explicitamente, a descoberta automática será ignorada e você deverá definir os modelos manualmente. Veja a seção de configuração explícita abaixo. -## Visão e descrição de imagem +## Visão e descrição de imagens -O Plugin empacotado do Ollama registra o Ollama como um provider de media-understanding compatível com imagem. Isso permite que o OpenClaw roteie solicitações explícitas de descrição de imagem e padrões configurados de modelo de imagem por modelos de visão do Ollama locais ou hospedados. +O Plugin Ollama incluído registra o Ollama como um provedor de compreensão de mídia compatível com imagens. Isso permite que o OpenClaw encaminhe solicitações explícitas de descrição de imagens e padrões configurados de modelo de imagem por modelos de visão do Ollama locais ou hospedados. -Para visão local, faça pull de um modelo com suporte a imagens: +Para visão local, faça pull de um modelo compatível com imagens: ```bash ollama pull qwen2.5vl:7b export OLLAMA_API_KEY="ollama-local" ``` -Depois valide com a CLI infer: +Em seguida, verifique com a CLI de inferência: ```bash openclaw infer image describe \ @@ -210,9 +210,9 @@ openclaw infer image describe \ --json ``` -`--model` deve ser uma ref completa ``. Quando definido, `openclaw infer image describe` executa esse modelo diretamente em vez de ignorar a descrição porque o modelo oferece suporte nativo a visão. +`--model` deve ser uma referência completa ``. Quando ele é definido, `openclaw infer image describe` executa esse modelo diretamente em vez de ignorar a descrição porque o modelo oferece suporte nativo a visão. -Para tornar o Ollama o modelo padrão de compreensão de imagem para mídia de entrada, configure `agents.defaults.imageModel`: +Para tornar o Ollama o modelo padrão de compreensão de imagens para mídia recebida, configure `agents.defaults.imageModel`: ```json5 { @@ -226,7 +226,7 @@ Para tornar o Ollama o modelo padrão de compreensão de imagem para mídia de e } ``` -Se você definir `models.providers.ollama.models` manualmente, marque modelos de visão com suporte a entrada de imagem: +Se você definir `models.providers.ollama.models` manualmente, marque os modelos de visão com suporte a entrada de imagem: ```json5 { @@ -238,26 +238,26 @@ Se você definir `models.providers.ollama.models` manualmente, marque modelos de } ``` -O OpenClaw rejeita solicitações de descrição de imagem para modelos que não estejam marcados como compatíveis com imagem. Com a descoberta implícita, o OpenClaw lê isso do Ollama quando `/api/show` informa uma capacidade de visão. +O OpenClaw rejeita solicitações de descrição de imagem para modelos que não estejam marcados como compatíveis com imagem. Com descoberta implícita, o OpenClaw lê isso do Ollama quando `/api/show` relata um recurso de visão. ## Configuração - O caminho mais simples para ativação somente local é por variável de ambiente: + O caminho mais simples para habilitar o modo apenas local é por variável de ambiente: ```bash export OLLAMA_API_KEY="ollama-local" ``` - Se `OLLAMA_API_KEY` estiver definido, você pode omitir `apiKey` na entrada do provider, e o OpenClaw o preencherá para verificações de disponibilidade. + Se `OLLAMA_API_KEY` estiver definida, você pode omitir `apiKey` na entrada do provedor e o OpenClaw irá preenchê-la para verificações de disponibilidade. - Use configuração explícita quando quiser uma configuração hospedada em nuvem, quando o Ollama estiver rodando em outro host/porta, quando quiser forçar listas de modelos ou janelas de contexto específicas, ou quando quiser definições de modelo totalmente manuais. + Use configuração explícita quando quiser uma configuração de nuvem hospedada, quando o Ollama estiver em outro host/porta, quando quiser forçar janelas de contexto ou listas de modelos específicas, ou quando quiser definições de modelos totalmente manuais. ```json5 { @@ -286,8 +286,8 @@ O OpenClaw rejeita solicitações de descrição de imagem para modelos que não - - Se o Ollama estiver rodando em outro host ou porta (configuração explícita desativa descoberta automática, então defina os modelos manualmente): + + Se o Ollama estiver em execução em outro host ou porta (a configuração explícita desativa a descoberta automática, então defina os modelos manualmente): ```json5 { @@ -296,7 +296,7 @@ O OpenClaw rejeita solicitações de descrição de imagem para modelos que não ollama: { apiKey: "ollama-local", baseUrl: "http://ollama-host:11434", // Sem /v1 - use a URL da API nativa do Ollama - api: "ollama", // Defina explicitamente para garantir comportamento nativo de tool-calling + api: "ollama", // Defina explicitamente para garantir o comportamento nativo de chamada de ferramentas }, }, }, @@ -304,7 +304,7 @@ O OpenClaw rejeita solicitações de descrição de imagem para modelos que não ``` - Não adicione `/v1` à URL. O caminho `/v1` usa o modo compatível com OpenAI, em que o tool calling não é confiável. Use a URL base do Ollama sem sufixo de caminho. + Não adicione `/v1` à URL. O caminho `/v1` usa o modo compatível com OpenAI, no qual a chamada de ferramentas não é confiável. Use a URL base do Ollama sem um sufixo de caminho. @@ -312,7 +312,7 @@ O OpenClaw rejeita solicitações de descrição de imagem para modelos que não ### Seleção de modelo -Depois de configurados, todos os seus modelos Ollama ficam disponíveis: +Depois de configurar, todos os seus modelos Ollama ficam disponíveis: ```json5 { @@ -327,13 +327,13 @@ Depois de configurados, todos os seus modelos Ollama ficam disponíveis: } ``` -## Busca na web do Ollama +## Ollama Web Search -O OpenClaw oferece suporte à **Ollama Web Search** como um provider empacotado `web_search`. +O OpenClaw oferece suporte ao **Ollama Web Search** como um provedor `web_search` incluído. | Propriedade | Detalhe | | ----------- | -------------------------------------------------------------------------------------------------------------------- | -| Host | Usa o host Ollama configurado (`models.providers.ollama.baseUrl` quando definido, caso contrário `http://127.0.0.1:11434`) | +| Host | Usa seu host Ollama configurado (`models.providers.ollama.baseUrl` quando definido, caso contrário `http://127.0.0.1:11434`) | | Autenticação | Sem chave | | Requisito | O Ollama deve estar em execução e autenticado com `ollama signin` | @@ -352,7 +352,7 @@ Escolha **Ollama Web Search** durante `openclaw onboard` ou `openclaw configure ``` -Para detalhes completos de configuração e comportamento, consulte [Ollama Web Search](/pt-BR/tools/ollama-search). +Para todos os detalhes de configuração e comportamento, veja [Ollama Web Search](/pt-BR/tools/ollama-search). ## Configuração avançada @@ -360,7 +360,7 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web - **O tool calling não é confiável no modo compatível com OpenAI.** Use esse modo apenas se você precisar do formato OpenAI para um proxy e não depender do comportamento nativo de tool calling. + **A chamada de ferramentas não é confiável no modo compatível com OpenAI.** Use esse modo apenas se você precisar do formato OpenAI para um proxy e não depender do comportamento nativo de chamada de ferramentas. Se você precisar usar o endpoint compatível com OpenAI em vez disso (por exemplo, atrás de um proxy que só oferece suporte ao formato OpenAI), defina `api: "openai-completions"` explicitamente: @@ -381,9 +381,9 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web } ``` - Esse modo pode não oferecer suporte a streaming e tool calling ao mesmo tempo. Talvez seja necessário desativar o streaming com `params: { streaming: false }` na configuração do modelo. + Esse modo pode não oferecer suporte a streaming e chamada de ferramentas ao mesmo tempo. Talvez seja necessário desativar o streaming com `params: { streaming: false }` na configuração do modelo. - Quando `api: "openai-completions"` é usado com Ollama, o OpenClaw injeta `options.num_ctx` por padrão para que o Ollama não faça fallback silencioso para uma janela de contexto de 4096. Se seu proxy/upstream rejeitar campos `options` desconhecidos, desative esse comportamento: + Quando `api: "openai-completions"` é usado com Ollama, o OpenClaw injeta `options.num_ctx` por padrão para que o Ollama não volte silenciosamente para uma janela de contexto de 4096. Se o seu proxy/upstream rejeitar campos `options` desconhecidos, desative esse comportamento: ```json5 { @@ -404,9 +404,9 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web - Para modelos descobertos automaticamente, o OpenClaw usa a janela de contexto informada pelo Ollama quando disponível; caso contrário, usa como fallback a janela de contexto padrão do Ollama usada pelo OpenClaw. + Para modelos descobertos automaticamente, o OpenClaw usa a janela de contexto informada pelo Ollama quando disponível; caso contrário, usa a janela de contexto padrão do Ollama usada pelo OpenClaw. - Você pode sobrescrever `contextWindow` e `maxTokens` na configuração explícita do provider: + Você pode substituir `contextWindow` e `maxTokens` na configuração explícita do provedor: ```json5 { @@ -428,32 +428,32 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web - - O OpenClaw trata por padrão modelos com nomes como `deepseek-r1`, `reasoning` ou `think` como compatíveis com reasoning. + + O OpenClaw trata modelos com nomes como `deepseek-r1`, `reasoning` ou `think` como compatíveis com raciocínio por padrão. ```bash ollama pull deepseek-r1:32b ``` - Nenhuma configuração adicional é necessária -- o OpenClaw os marca automaticamente. + Nenhuma configuração adicional é necessária — o OpenClaw os marca automaticamente. - - O Ollama é gratuito e roda localmente, então todos os custos de modelo são definidos como $0. Isso se aplica tanto a modelos descobertos automaticamente quanto a modelos definidos manualmente. + + O Ollama é gratuito e é executado localmente, então todos os custos de modelo são definidos como $0. Isso se aplica tanto a modelos descobertos automaticamente quanto a modelos definidos manualmente. - O Plugin empacotado do Ollama registra um provider de embedding de memória para - [busca de memória](/pt-BR/concepts/memory). Ele usa a base URL - e a chave de API configuradas do Ollama. + O Plugin Ollama incluído registra um provedor de embeddings de memória para + [busca de memória](/pt-BR/concepts/memory). Ele usa a URL base e a chave de API do + Ollama configuradas. - | Propriedade | Valor | - | ------------- | ------------------ | - | Modelo padrão | `nomic-embed-text` | - | Pull automático | Sim — o modelo de embedding é baixado automaticamente se não estiver presente localmente | + | Propriedade | Valor | + | -------------- | ------------------- | + | Modelo padrão | `nomic-embed-text` | + | Pull automático | Sim — o modelo de embedding é baixado automaticamente se ainda não estiver presente localmente | - Para selecionar o Ollama como provider de embedding para busca de memória: + Para selecionar o Ollama como provedor de embedding da busca de memória: ```json5 { @@ -468,10 +468,12 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web - A integração do OpenClaw com Ollama usa por padrão a **API nativa do Ollama** (`/api/chat`), que oferece suporte completo a streaming e tool calling ao mesmo tempo. Nenhuma configuração especial é necessária. + A integração do OpenClaw com o Ollama usa a **API nativa do Ollama** (`/api/chat`) por padrão, que oferece suporte completo a streaming e chamada de ferramentas ao mesmo tempo. Nenhuma configuração especial é necessária. + + Para solicitações nativas a `/api/chat`, o OpenClaw também encaminha o controle de pensamento diretamente para o Ollama: `/think off` e `openclaw agent --thinking off` enviam `think: false` no nível superior, enquanto níveis de pensamento diferentes de `off` enviam `think: true`. - Se você precisar usar o endpoint compatível com OpenAI, consulte a seção "Modo legado compatível com OpenAI" acima. Streaming e tool calling podem não funcionar ao mesmo tempo nesse modo. + Se você precisar usar o endpoint compatível com OpenAI, veja a seção "Modo legado compatível com OpenAI" acima. Streaming e chamada de ferramentas podem não funcionar ao mesmo tempo nesse modo. @@ -496,7 +498,7 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web - Se seu modelo não estiver listado, faça pull do modelo localmente ou defina-o explicitamente em `models.providers.ollama`. + Se o seu modelo não estiver listado, faça pull do modelo localmente ou defina-o explicitamente em `models.providers.ollama`. ```bash ollama list # Veja o que está instalado @@ -508,7 +510,7 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web - Verifique se o Ollama está rodando na porta correta: + Verifique se o Ollama está em execução na porta correta: ```bash # Verifique se o Ollama está em execução @@ -525,17 +527,17 @@ Para detalhes completos de configuração e comportamento, consulte [Ollama Web Mais ajuda: [Solução de problemas](/pt-BR/help/troubleshooting) e [FAQ](/pt-BR/help/faq). -## Relacionado +## Relacionados - - Visão geral de todos os providers, refs de modelo e comportamento de failover. + + Visão geral de todos os provedores, referências de modelo e comportamento de failover. Como escolher e configurar modelos. - Detalhes completos de configuração e comportamento para busca na web com Ollama. + Todos os detalhes de configuração e comportamento da busca na web com tecnologia Ollama. Referência completa de configuração. diff --git a/docs/pt-BR/providers/tencent.md b/docs/pt-BR/providers/tencent.md new file mode 100644 index 000000000..7b117b17a --- /dev/null +++ b/docs/pt-BR/providers/tencent.md @@ -0,0 +1,97 @@ +--- +read_when: + - Você quer usar modelos Tencent Hy com OpenClaw + - Você precisa da chave de API do TokenHub ou da configuração do plano de tokens (LKEAP) +summary: Configuração do Tencent Cloud TokenHub e do plano de tokens (chaves separadas) +title: Tencent Cloud (TokenHub + plano de tokens) +x-i18n: + generated_at: "2026-04-22T05:34:48Z" + model: gpt-5.4 + provider: openai + source_hash: c0f04fcfcb6e14b17c3bc8f3c7ca3f20f8dabfaa89813a0566c0672439d4afff + source_path: providers/tencent.md + workflow: 15 +--- + +# Tencent Cloud (TokenHub + plano de tokens) + +O provedor Tencent Cloud dá acesso aos modelos Tencent Hy por meio de dois endpoints +com chaves de API separadas: + +- **TokenHub** (`tencent-tokenhub`) — chama o Hy pelo Gateway do Tencent TokenHub +- **Plano de tokens** (`tencent-token-plan`) — chama o Hy pelo endpoint de + plano de tokens do LKEAP + +Ambos os provedores usam APIs compatíveis com OpenAI. + +## Início rápido + +TokenHub: + +```bash +openclaw onboard --auth-choice tokenhub-api-key +``` + +Plano de tokens: + +```bash +openclaw onboard --auth-choice tencent-token-plan-api-key +``` + +## Exemplo não interativo + +```bash +# TokenHub +openclaw onboard --non-interactive \ + --mode local \ + --auth-choice tokenhub-api-key \ + --tokenhub-api-key "$TOKENHUB_API_KEY" \ + --skip-health \ + --accept-risk + +# Token Plan +openclaw onboard --non-interactive \ + --mode local \ + --auth-choice tencent-token-plan-api-key \ + --tencent-token-plan-api-key "$LKEAP_API_KEY" \ + --skip-health \ + --accept-risk +``` + +## Provedores e endpoints + +| Provedor | Endpoint | Caso de uso | +| -------------------- | ------------------------------------- | ----------------------- | +| `tencent-tokenhub` | `tokenhub.tencentmaas.com/v1` | Hy via Tencent TokenHub | +| `tencent-token-plan` | `api.lkeap.cloud.tencent.com/plan/v3` | Hy via plano de tokens do LKEAP | + +Cada provedor usa sua própria chave de API. A configuração registra apenas o provedor selecionado. + +## Modelos disponíveis + +### tencent-tokenhub + +- **hy3-preview** — prévia do Hy3 (contexto de 256K, raciocínio, padrão) + +### tencent-token-plan + +- **hy3-preview** — prévia do Hy3 (contexto de 256K, raciocínio, padrão) + +## Observações + +- As referências de modelo do TokenHub usam `tencent-tokenhub/`. As referências de modelo do plano de tokens + usam `tencent-token-plan/`. +- Substitua os metadados de preço e contexto em `models.providers` se necessário. + +## Observação sobre ambiente + +Se o Gateway for executado como daemon (`launchd`/`systemd`), verifique se `TOKENHUB_API_KEY` +ou `LKEAP_API_KEY` está disponível para esse processo (por exemplo, em +`~/.openclaw/.env` ou via `env.shellEnv`). + +## Documentação relacionada + +- [Configuração do OpenClaw](/pt-BR/gateway/configuration) +- [Provedores de modelos](/pt-BR/concepts/model-providers) +- [Tencent TokenHub](https://cloud.tencent.com/document/product/1823/130050) +- [API do plano de tokens da Tencent](https://cloud.tencent.com/document/product/1823/130060)