openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh pt-BR translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 05:57:34 +00:00
parent 498692dd0c
commit c645046941
28 changed files with 3469 additions and 3008 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

502
docs/pt-BR/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- Você precisa entender por que um job de CI foi ou não executado
- Você está depurando uma verificação com falha do GitHub Actions
- Você está coordenando uma execução ou reexecução de validação de lançamento
- Você está alterando o despacho do ClawSweeper ou o encaminhamento de atividades do GitHub
summary: Grafo de tarefas de CI, controles de escopo, agrupadores de lançamento e equivalentes de comandos locais
title: Esteira de integração contínua
- Você precisa entender por que um job de CI foi executado ou não
- Você está depurando uma verificação do GitHub Actions que está falhando
- Você está coordenando uma execução ou reexecução da validação de lançamento
- Você está alterando o acionamento do ClawSweeper ou o encaminhamento de atividades do GitHub
summary: Grafo de tarefas de CI, controles de escopo, guarda-chuvas de lançamento e equivalentes de comandos locais
title: Pipeline de CI
x-i18n:
generated_at: "2026-05-03T21:27:45Z"
generated_at: "2026-05-04T05:52:15Z"
model: gpt-5.5
provider: openai
source_hash: e07fc44aa844cb66ce529c570cbbbbf502a61bcbcbc3d9488557abb459ef7678
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
source_path: ci.md
workflow: 16
---
OpenClaw CI é executado em cada push para `main` e em cada pull request. A tarefa `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais de `workflow_dispatch` ignoram intencionalmente o escopo inteligente e expandem o grafo completo para candidatos a lançamento e validação ampla. As lanes Android permanecem opcionais por meio de `include_android`. A cobertura de Plugin exclusiva de lançamento fica no workflow separado [`Pré-lançamento de Plugin`](#plugin-prerelease) e só é executada a partir de [`Validação Completa de Lançamento`](#full-release-validation) ou de um disparo manual explícito.
A CI do OpenClaw é executada em cada push para `main` e em cada pull request. O job `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais de `workflow_dispatch` ignoram intencionalmente o escopo inteligente e expandem o grafo completo para candidatos a release e validação ampla. As lanes de Android continuam opcionais por meio de `include_android`. A cobertura de Plugins somente de release fica no workflow separado [`Plugin Prerelease`](#plugin-prerelease) e só é executada a partir de [`Full Release Validation`](#full-release-validation) ou de um disparo manual explícito.
## Visão geral do pipeline
| Tarefa | Finalidade | Quando é executada |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Detecta mudanças somente em docs, escopos alterados, extensões alteradas e gera o manifesto de CI | Sempre em pushes e PRs não rascunho |
| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs não rascunho |
| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs não rascunho |
| `security-fast` | Agregado obrigatório para as tarefas rápidas de segurança | Sempre em pushes e PRs não rascunho |
| `check-dependencies` | Passagem somente de dependências de produção do Knip mais a guarda da lista de permissões de arquivos não usados | Mudanças relevantes para Node |
| `build-artifacts` | Gera `dist/`, Control UI, verificações de artefatos gerados e artefatos downstream reutilizáveis | Mudanças relevantes para Node |
| `checks-fast-core` | Lanes rápidas de correção no Linux, como verificações de bundled/plugin-contract/protocol | Mudanças relevantes para Node |
| `checks-fast-contracts-channels` | Verificações fragmentadas de contrato de canais com um resultado agregado estável | Mudanças relevantes para Node |
| `checks-node-core-test` | Shards de teste do núcleo Node, excluindo lanes de canal, bundled, contrato e extensão | Mudanças relevantes para Node |
| `check` | Equivalente fragmentado do gate local principal: tipos prod, lint, guardas, tipos de teste e smoke estrito | Mudanças relevantes para Node |
| `check-additional` | Arquitetura, drift fragmentado de fronteira/prompt, guardas de extensão, fronteira de pacote e gateway watch | Mudanças relevantes para Node |
| `build-smoke` | Testes smoke da CLI gerada e smoke de memória de inicialização | Mudanças relevantes para Node |
| `checks` | Verificador para testes de canal de artefatos gerados | Mudanças relevantes para Node |
| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Disparo manual de CI para lançamentos |
| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alterados |
| `skills-python` | Ruff + pytest para skills com suporte em Python | Mudanças relevantes para skills Python |
| `checks-windows` | Testes de processo/caminho específicos do Windows mais regressões compartilhadas de especificadores de importação em runtime | Mudanças relevantes para Windows |
| `macos-node` | Lane de teste TypeScript no macOS usando os artefatos gerados compartilhados | Mudanças relevantes para macOS |
| `macos-swift` | Lint, build e testes Swift para o app macOS | Mudanças relevantes para macOS |
| `android` | Testes unitários Android para ambos os flavors mais um build de APK debug | Mudanças relevantes para Android |
| `test-performance-agent` | Otimização diária de testes lentos pelo Codex após atividade confiável | Sucesso da CI principal ou disparo manual |
| `openclaw-performance` | Relatórios diários/sob demanda de desempenho do runtime Kova com lanes mock-provider, deep-profile e GPT 5.4 live | Agendamento e disparo manual |
| Job | Finalidade | Quando é executado |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Detecta alterações somente de docs, escopos alterados, extensions alteradas e constrói o manifesto de CI | Sempre em pushes e PRs não rascunho |
| `security-scm-fast` | Detecção de chaves privadas e auditoria de workflow via `zizmor` | Sempre em pushes e PRs não rascunho |
| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs não rascunho |
| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs não rascunho |
| `check-dependencies` | Passagem do Knip somente para dependências de produção mais a guarda da lista de permissões de arquivos não usados | Alterações relevantes para Node |
| `build-artifacts` | Compila `dist/`, Control UI, verificações de artefatos compilados e artefatos downstream reutilizáveis | Alterações relevantes para Node |
| `checks-fast-core` | Lanes rápidas de correção no Linux, como verificações de Plugins empacotados/contratos de Plugin/protocolo | 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-core-test` | Fragmentos de testes do Node principal, excluindo lanes de canais, Plugins empacotados, contratos e extensions | Alterações relevantes para Node |
| `check` | Equivalente fragmentado do gate local principal: tipos de produção, lint, guardas, tipos de teste e smoke estrito | Alterações relevantes para Node |
| `check-additional` | Arquitetura, drift fragmentado de limites/prompts, guardas de extensions, limite de pacote e Gateway watch | Alterações relevantes para Node |
| `build-smoke` | Testes smoke da CLI compilada e smoke de memória de inicialização | Alterações relevantes para Node |
| `checks` | Verificador para testes de canal de artefatos compilados | Alterações relevantes para Node |
| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Disparo manual de CI para releases |
| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas |
| `skills-python` | Ruff + pytest para Skills apoiadas por Python | Alterações relevantes para Skills em Python |
| `checks-windows` | Testes específicos de processo/caminho no Windows mais regressões compartilhadas de especificadores de importação em runtime | 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 |
| `android` | Testes unitários de Android para ambos os flavors mais um build de APK de debug | Alterações relevantes para Android |
| `test-performance-agent` | Otimização diária de testes lentos pelo Codex após atividade confiável | Sucesso da CI principal ou disparo manual |
| `openclaw-performance` | Relatórios diários/sob demanda de performance do runtime Kova com lanes de mock-provider, deep-profile e GPT 5.4 ao vivo | Disparo agendado e manual |
## Ordem de falha rápida
1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` são etapas dentro dessa tarefa, não tarefas independentes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelas tarefas mais pesadas de matriz de artefatos e plataformas.
3. `build-artifacts` se sobrepõe às lanes rápidas do Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto.
1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` são etapas dentro deste 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 pelos jobs mais pesados de matriz de artefatos e plataformas.
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. Lanes mais pesadas de plataforma e runtime se expandem depois disso: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
O GitHub pode marcar tarefas substituídas como `cancelled` quando um push mais novo 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. Verificações agregadas de shard usam `!cancelled() && always()` para que ainda relatem falhas normais de shards, mas não entrem na fila depois que todo o workflow já foi substituído. A chave automática de concorrência da CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas da main. Execuções manuais da suíte completa usam `CI-manual-v1-*` e não cancelam execuções em andamento.
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 nova para a mesma ref também esteja falhando. Verificações agregadas de fragmentos usam `!cancelled() && always()` para que ainda relatem falhas normais de fragmentos, mas não entrem na fila depois que o workflow inteiro já tiver sido substituído. A chave de concorrência automática da CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas da main. Execuções manuais da suíte completa usam `CI-manual-v1-*` e não cancelam execuções em andamento.
## Escopo e roteamento
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 disparo manual ignora a detecção de escopo alterado e faz o manifesto de preflight agir como se todas as áreas com escopo tivessem mudado.
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 disparo manual pula a detecção de escopo alterado e faz o manifesto de preflight agir como se todas as áreas com escopo tivessem mudado.
- **Edições no workflow de CI** validam o grafo de CI Node mais o lint de workflow, mas não forçam builds nativos de Windows, Android ou macOS por si só; essas lanes de plataforma permanecem restritas a mudanças no código-fonte da plataforma.
- **Edições somente de roteamento de CI, edições selecionadas baratas de fixtures de core-test e edições estreitas em helpers/test-routing de contrato de Plugin** usam um caminho rápido de manifesto somente Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canal, shards completos do núcleo, shards de bundled-plugin e matrizes adicionais de guardas quando a mudança se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente.
- **Verificações Node no Windows** são restritas a wrappers específicos de processo/caminho do Windows, helpers de runners npm/pnpm/UI, configuração de gerenciador de pacotes e superfícies de workflow de CI que executam essa lane; mudanças não relacionadas de código-fonte, Plugin, install-smoke e somente testes permanecem nas lanes Node do Linux.
- **Edições de workflow de CI** validam o grafo de CI do Node mais linting de workflow, mas não forçam builds nativos de Windows, Android ou macOS por si só; essas lanes de plataforma permanecem escopadas a alterações de código-fonte de plataforma.
- **Edições apenas de roteamento de CI, edições selecionadas de fixtures baratas de testes do núcleo e edições estreitas de helpers/roteamento de testes de contrato de Plugin** usam um caminho rápido de manifesto somente Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canais, fragmentos completos do núcleo, fragmentos de Plugins empacotados e matrizes adicionais de guardas quando a alteração se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente.
- **Verificações de Node no Windows** são escopadas a wrappers específicos de processo/caminho do Windows, helpers de execução npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; alterações não relacionadas de código-fonte, Plugin, smoke de instalação e somente testes permanecem nas lanes de Node no Linux.
As famílias mais lentas de testes Node são divididas ou balanceadas para que cada tarefa permaneça pequena sem reservar runners em excesso: contratos de canal rodam como três shards ponderados, lanes rápidas/de suporte de unidades do núcleo rodam separadamente, infra de runtime do núcleo é dividida entre shards de estado e processo/config, auto-reply roda como workers balanceados (com a subárvore de respostas dividida em shards agent-runner, dispatch e commands/state-routing), e configurações agentic de gateway/server são divididas entre lanes chat/auth/model/http-plugin/runtime/startup em vez de esperar por artefatos gerados. Testes amplos de navegador, QA, mídia e Plugins diversos usam suas configurações Vitest dedicadas em vez do catch-all compartilhado de Plugins. Shards com padrões de inclusão registram entradas de tempo usando o nome do shard de CI, para que `.artifacts/vitest-shard-timings.json` possa distinguir uma configuração inteira de um shard filtrado. `check-additional` mantém juntos o trabalho de compilação/canary de package-boundary e separa a arquitetura de topologia de runtime da cobertura de gateway watch; a lista de guardas de fronteira é distribuída por quatro shards de matriz, cada um executando guardas independentes selecionadas simultaneamente e imprimindo tempos por verificação, incluindo `pnpm prompt:snapshots:check`, para que o drift de prompt do caminho feliz do runtime Codex fique fixado ao PR que o causou. Gateway watch, testes de canal e o shard de fronteira de suporte do núcleo rodam simultaneamente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram gerados.
As famílias mais lentas de testes Node são divididas ou balanceadas para que cada job continue pequeno sem reservar runners em excesso: contratos de canais rodam como três fragmentos ponderados, lanes rápidas/de suporte de unidade do núcleo rodam separadamente, a infraestrutura de runtime do núcleo é dividida entre fragmentos de estado e processo/configuração, auto-reply roda como workers balanceados (com a subárvore de respostas dividida em fragmentos de agent-runner, dispatch e commands/state-routing), e configurações agentic de Gateway/servidor são divididas entre lanes de chat/auth/model/http-plugin/runtime/startup em vez de esperar por artefatos compilados. Testes amplos de navegador, QA, mídia e Plugins diversos usam suas configurações Vitest dedicadas em vez do catch-all compartilhado de Plugins. Fragmentos com padrão de inclusão registram entradas de tempo usando o nome do fragmento de CI, para que `.artifacts/vitest-shard-timings.json` possa distinguir uma configuração inteira de um fragmento filtrado. `check-additional` mantém juntos o trabalho de compilação/canário de limite de pacote e separa a arquitetura de topologia de runtime da cobertura de Gateway watch; a lista de guardas de limite é distribuída em quatro fragmentos de matriz, cada um executando guardas independentes selecionadas em paralelo e imprimindo tempos por verificação, incluindo `pnpm prompt:snapshots:check`, para que drift de prompt do caminho feliz do runtime Codex fique preso ao PR que o causou. Gateway watch, testes de canais e o fragmento de limite de suporte do núcleo rodam em paralelo dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados.
A CI Android executa `testPlayDebugUnitTest` e `testThirdPartyDebugUnitTest` e então gera o APK debug Play. O flavor de terceiros não tem source set ou manifesto separado; sua lane de testes unitários ainda compila o flavor com as flags BuildConfig de SMS/call-log, evitando ao mesmo tempo uma tarefa duplicada de empacotamento de APK debug em todo push relevante para Android.
A CI de Android executa `testPlayDebugUnitTest` e `testThirdPartyDebugUnitTest` e depois compila o APK de debug Play. O flavor third-party não tem source set ou manifesto separado; sua lane de testes unitários ainda compila o flavor com as flags BuildConfig de SMS/call-log, evitando ao mesmo tempo um job duplicado de empacotamento de APK de debug em cada push relevante para Android.
O shard `check-dependencies` executa `pnpm deadcode:dependencies` (uma passagem somente de dependências de produção do Knip fixada na versão mais recente do Knip, com a idade mínima de lançamento do pnpm desativada para a instalação via `dlx`) e `pnpm deadcode:unused-files`, que compara as descobertas de arquivos de produção não usados do Knip contra `scripts/deadcode-unused-files.allowlist.mjs`. A guarda de arquivos não usados falha quando um PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na allowlist, preservando superfícies intencionais de Plugins dinâmicos, geradas, de build, testes live e bridge de pacote que o Knip não consegue resolver estaticamente.
O fragmento `check-dependencies` executa `pnpm deadcode:dependencies` (uma passagem do Knip somente para dependências de produção fixada na versão mais recente do Knip, com a idade mínima de release do pnpm desativada para a instalação `dlx`) e `pnpm deadcode:unused-files`, que compara as descobertas de arquivos de produção não usados do Knip com `scripts/deadcode-unused-files.allowlist.mjs`. A guarda de arquivos não usados falha quando um PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na lista de permissões, preservando superfícies intencionais de Plugins dinâmicos, geradas, de build, testes ao vivo e pontes de pacote que o Knip não consegue resolver estaticamente.
## Encaminhamento de atividade do ClawSweeper
`.github/workflows/clawsweeper-dispatch.yml` é a ponte do lado do destino da atividade do repositório OpenClaw para o ClawSweeper. Ele não faz checkout nem executa código não confiável de pull requests. O workflow cria um token de GitHub App a partir de `CLAWSWEEPER_APP_PRIVATE_KEY` e então dispara payloads compactos de `repository_dispatch` para `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` é a ponte do lado de destino da atividade do repositório OpenClaw para o ClawSweeper. Ele não faz checkout nem executa código não confiável de pull requests. O workflow cria um token de GitHub App a partir de `CLAWSWEEPER_APP_PRIVATE_KEY` e então dispara payloads compactos de `repository_dispatch` para `openclaw/clawsweeper`.
O workflow tem quatro lanes:
- `clawsweeper_item` para solicitações exatas de revisão de issues e pull requests;
- `clawsweeper_comment` para comandos explícitos do ClawSweeper em comentários de issues;
- `clawsweeper_commit_review` para solicitações de revisão em nível de commit em pushes para `main`;
- `clawsweeper_commit_review` para solicitações de revisão no nível de commit em pushes para `main`;
- `github_activity` para atividade geral do GitHub que o agente ClawSweeper pode inspecionar.
A lane `github_activity` encaminha apenas metadados normalizados: tipo de evento, ação, ator, repositório, número do item, URL, título, estado e trechos curtos para comentários ou revisões quando presentes. Ela evita intencionalmente encaminhar o corpo completo do webhook. O workflow receptor em `openclaw/clawsweeper` é `.github/workflows/github-activity.yml`, que publica o evento normalizado no hook do OpenClaw Gateway para o agente ClawSweeper.
A lane `github_activity` encaminha apenas metadados normalizados: tipo de evento, ação, ator, repositório, número do item, URL, título, estado e trechos curtos de comentários ou revisões quando presentes. Ela evita intencionalmente encaminhar o corpo completo do Webhook. O workflow receptor em `openclaw/clawsweeper` é `.github/workflows/github-activity.yml`, que publica o evento normalizado no hook do OpenClaw Gateway para o agente ClawSweeper.
Atividade geral é observação, não entrega por padrão. O agente ClawSweeper recebe o destino do Discord em seu prompt e deve publicar em `#clawsweeper` apenas quando o evento for surpreendente, acionável, arriscado ou operacionalmente útil. Aberturas rotineiras, edições, ruído de bots, ruído duplicado de webhook e tráfego normal de revisão devem resultar em `NO_REPLY`.
Atividade geral é observação, não entrega por padrão. O agente ClawSweeper recebe o destino do Discord no prompt e deve publicar em `#clawsweeper` somente quando o evento for surpreendente, acionável, arriscado ou operacionalmente útil. Aberturas rotineiras, edições, atividade repetitiva de bots, ruído de Webhook duplicado e tráfego normal de revisão devem resultar em `NO_REPLY`.
Trate títulos, comentários, corpos, texto de revisão, nomes de branches e mensagens de commit do GitHub como dados não confiáveis em todo esse caminho. Eles são entrada para sumarização e triagem, não instruções para o workflow ou runtime do agente.
Trate títulos, comentários, corpos, texto de revisão, nomes de branches e mensagens de commit do GitHub como dados não confiáveis em todo este caminho. Eles são entrada para sumarização e triagem, não instruções para o workflow ou o runtime do agente.
## Disparos manuais
Disparos manuais de CI executam o mesmo grafo de jobs da CI normal, mas forçam todas as lanes com escopo não Android: shards Linux Node, shards de plugins incluídos, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Python skills, Windows, macOS e i18n da Control UI. Disparos manuais independentes de CI executam somente Android com `include_android=true`; o guarda-chuva completo de release habilita Android passando `include_android=true`. Verificações estáticas de pré-lançamento de plugin, o shard `agentic-plugins` exclusivo de release, a varredura completa em lote de extensões e as lanes Docker de pré-lançamento de plugin são excluídas da CI. A suíte Docker de pré-lançamento roda somente quando `Full Release Validation` dispara o workflow separado `Plugin Prerelease` com o gate de validação de release habilitado.
Os dispatches manuais de CI executam o mesmo grafo de jobs que a CI normal, mas forçam a ativação de toda lane com escopo não Android: shards Linux Node, shards de plugins agrupados, contratos de canal, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de documentação, Skills Python, Windows, macOS e i18n da Control UI. Dispatches manuais independentes de CI executam apenas Android com `include_android=true`; o guarda-chuva completo de release habilita Android passando `include_android=true`. Verificações estáticas de pré-release de Plugin, o shard exclusivo de release `agentic-plugins`, a varredura completa em lote de extensions e as lanes Docker de pré-release de Plugin ficam excluídos da CI. A suíte Docker de pré-release é executada somente quando `Full Release Validation` dispara o workflow separado `Plugin Prerelease` com o gate de validação de release habilitado.
Execuções manuais usam um grupo de concorrência único para que uma suíte completa de candidato a release não seja cancelada por outro push ou execução de PR no mesmo ref. A entrada opcional `target_ref` permite que um chamador confiável execute esse grafo contra uma branch, tag ou SHA completo de commit enquanto usa o arquivo de workflow do ref de disparo selecionado.
Execuções manuais usam um grupo de concorrência único para que uma suíte completa de candidato a release não seja cancelada por outra execução de push ou PR na mesma ref. A entrada opcional `target_ref` permite que um chamador confiável execute esse grafo contra uma branch, tag ou SHA completo de commit usando o arquivo de workflow da ref de dispatch selecionada.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Executores
| Executor | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregados (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/incluídos, verificações fragmentadas de contratos de canais, shards de `check` exceto lint, shards e agregados de `check-additional`, verificadores agregados de testes Node, verificações de docs, Python skills, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado no GitHub para que a matriz Blacksmith possa entrar na fila mais cedo |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards de extensões de menor peso, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Linux Node, shards de testes de plugins incluídos, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível o bastante a CPU para que 8 vCPU custassem mais do que economizavam); builds Docker de install-smoke (o tempo de fila de 32 vCPU custava mais do que economizava) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks recorrem a `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks recorrem a `macos-latest` |
| Executor | Jobs |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregados (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/plugins agrupados, verificações fragmentadas de contratos de canal, shards de `check` exceto lint, shards e agregados de `check-additional`, verificadores agregados de testes Node, verificações de documentação, Skills Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards de extensions mais leves, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Linux Node, shards de testes de plugins agrupados, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU a ponto de 8 vCPU custar mais do que economizou); builds Docker de install-smoke (o tempo de fila de 32 vCPU custou mais do que economizou) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks voltam para `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks voltam para `macos-latest` |
## Equivalentes locais
@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
## Desempenho do OpenClaw
`OpenClaw Performance` é o workflow de desempenho de produto/runtime. Ele roda diariamente em `main` e pode ser disparado manualmente:
`OpenClaw Performance` é o workflow de desempenho de produto/runtime. Ele é executado diariamente em `main` e pode ser disparado manualmente:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,32 +145,25 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
O disparo manual normalmente mede o ref do workflow. Defina `target_ref` para medir uma tag de release ou outra branch com a implementação atual do workflow. Caminhos de relatórios publicados e ponteiros mais recentes são indexados pelo ref testado, e cada `index.md` registra o ref/SHA testado, ref/SHA do workflow, ref Kova, perfil, modo de autenticação da lane, modelo, contagem de repetições e filtros de cenário.
O dispatch manual normalmente mede a ref do workflow. Defina `target_ref` para medir uma tag de release ou outra branch com a implementação atual do workflow. Os caminhos de relatórios publicados e ponteiros mais recentes são indexados pela ref testada, e cada `index.md` registra a ref/SHA testada, a ref/SHA do workflow, a ref do Kova, perfil, modo de autenticação da lane, modelo, contagem de repetições e filtros de cenário.
O workflow instala OCM a partir de um release fixado e Kova de `openclaw/Kova` na entrada fixada `kova_ref`, depois executa três lanes:
O workflow instala OCM a partir de uma release fixada e Kova a partir de `openclaw/Kova` na entrada fixada `kova_ref`, depois executa três lanes:
- `mock-provider`: cenários diagnósticos Kova contra um runtime de build local com autenticação falsa determinística compatível com OpenAI.
- `mock-deep-profile`: profiling de CPU/heap/trace para hotspots de inicialização, Gateway e turnos de agente.
- `mock-provider`: cenários diagnósticos do Kova contra um runtime de build local com autenticação fake determinística compatível com OpenAI.
- `mock-deep-profile`: profiling de CPU/heap/trace para pontos críticos de inicialização, Gateway e turnos de agente.
- `live-gpt54`: um turno real de agente OpenAI `openai/gpt-5.4`, ignorado quando `OPENAI_API_KEY` não está disponível.
A lane mock-provider também executa sondas de código-fonte nativas do OpenClaw depois da passagem do Kova: tempo de boot e memória do Gateway em casos de inicialização padrão, hook e com 50 plugins; loops repetidos de hello `channel-chat-baseline` com mock de OpenAI; e comandos de inicialização da CLI contra o Gateway iniciado. O resumo Markdown da sonda de código-fonte fica em `source/index.md` no pacote de relatório, com JSON bruto ao lado.
A lane mock-provider também executa sondagens de origem nativas do OpenClaw após a passagem do Kova: tempo de inicialização e memória do Gateway nos casos de inicialização padrão, com hook e com 50 plugins; loops repetidos de hello `channel-chat-baseline` com mock-OpenAI; e comandos de inicialização da CLI contra o Gateway iniciado. O resumo Markdown da sondagem de origem fica em `source/index.md` no pacote de relatório, com JSON bruto ao lado.
Cada lane envia artefatos ao GitHub. Quando `CLAWGRIT_REPORTS_TOKEN` está configurado, o workflow também commita `report.json`, `report.md`, pacotes, `index.md` e artefatos de sonda de código-fonte em `openclaw/clawgrit-reports` sob `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. O ponteiro atual do ref testado é escrito como `openclaw-performance/<tested-ref>/latest-<lane>.json`.
Cada lane envia artefatos do GitHub. Quando `CLAWGRIT_REPORTS_TOKEN` está configurado, o workflow também faz commit de `report.json`, `report.md`, pacotes, `index.md` e artefatos de sondagem de origem em `openclaw/clawgrit-reports` sob `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. O ponteiro atual da ref testada é gravado como `openclaw-performance/<tested-ref>/latest-<lane>.json`.
## Validação Completa de Release
`Full Release Validation` é o workflow guarda-chuva manual para "executar tudo antes do release." Ele aceita uma branch, tag ou SHA completo de commit, dispara o workflow manual `CI` com esse alvo, dispara `Plugin Prerelease` para prova exclusiva de release de plugin/pacote/estática/Docker, e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes Docker do caminho de release, live/E2E, OpenWebUI, paridade do QA Lab, Matrix e lanes Telegram. Com `rerun_group=all` e `release_profile=full`, ele também executa `NPM Telegram Beta E2E` contra o artefato `release-package-under-test` das verificações de release. Depois da publicação, passe `npm_telegram_package_spec` para executar novamente a mesma lane de pacote Telegram contra o pacote npm publicado.
`Full Release Validation` é o workflow manual guarda-chuva para "executar tudo antes da release." Ele aceita uma branch, tag ou SHA completo de commit, dispara o workflow manual `CI` com esse alvo, dispara `Plugin Prerelease` para comprovação exclusiva de release de plugin/pacote/estática/Docker e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release Docker, live/E2E, OpenWebUI, paridade QA Lab, Matrix e lanes Telegram. Com `rerun_group=all` e `release_profile=full`, ele também executa `NPM Telegram Beta E2E` contra o artefato `release-package-under-test` das verificações de release. Depois da publicação, passe `npm_telegram_package_spec` para reexecutar a mesma lane de pacote Telegram contra o pacote npm publicado.
Consulte [Validação completa de release](/pt-BR/reference/full-release-validation) para a
matriz de estágios, nomes exatos de jobs de workflow, diferenças de perfil, artefatos e
identificadores de reexecução focada.
Consulte [validação completa de release](/pt-BR/reference/full-release-validation) para a matriz de estágios, nomes exatos de jobs do workflow, diferenças de perfil, artefatos e identificadores de reexecução focada.
`OpenClaw Release Publish` é o workflow manual mutável de release. Dispare-o
a partir de `release/YYYY.M.D` ou `main` depois que a tag de release existir e depois que o
preflight npm do OpenClaw tiver sido bem-sucedido. Ele verifica `pnpm plugins:sync:check`,
dispara `Plugin NPM Release` para todos os pacotes de plugins publicáveis, dispara
`Plugin ClawHub Release` para o mesmo SHA de release e só então dispara
`OpenClaw NPM Release` com o `preflight_run_id` salvo.
`OpenClaw Release Publish` é o workflow manual mutável de release. Dispare-o de `release/YYYY.M.D` ou `main` depois que a tag de release existir e depois que o preflight npm do OpenClaw tiver sido concluído com sucesso. Ele verifica `pnpm plugins:sync:check`, dispara `Plugin NPM Release` para todos os pacotes de Plugin publicáveis, dispara `Plugin ClawHub Release` para o mesmo SHA de release e só então dispara `OpenClaw NPM Release` com o `preflight_run_id` salvo.
```bash
gh workflow run openclaw-release-publish.yml \
@ -180,27 +173,97 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Para prova de commit fixado em uma branch que muda rapidamente, use o helper em vez de
`gh workflow run ... --ref main -f ref=<sha>`:
Para comprovação de commit fixado em uma branch que se move rápido, use o helper em vez de `gh workflow run ... --ref main -f ref=<sha>`:
```bash
pnpm ci:full-release --sha <full-sha>
```
Refs de disparo de workflow do GitHub devem ser branches ou tags, não SHAs brutos de commit. O
helper envia uma branch temporária `release-ci/<sha>-...` no SHA alvo,
dispara `Full Release Validation` a partir desse ref fixado, verifica se todo
`headSha` de workflow filho corresponde ao alvo e exclui a branch temporária quando a
execução termina. O verificador guarda-chuva também falha se algum workflow filho tiver rodado em um
SHA diferente.
Refs de dispatch de workflow do GitHub devem ser branches ou tags, não SHAs brutos de commit. O helper envia uma branch temporária `release-ci/<sha>-...` no SHA alvo, dispara `Full Release Validation` a partir dessa ref fixada, verifica se cada `headSha` de workflow filho corresponde ao alvo e exclui a branch temporária quando a execução termina. O verificador guarda-chuva também falha se qualquer workflow filho tiver executado em um SHA diferente.
`release_profile` controla a abrangência de live/provedor passada para as verificações de lançamento. Os
workflows manuais de lançamento usam `stable` por padrão; use `full` somente quando você
quiser intencionalmente a matriz ampla de provedores/mídia de consultoria.
`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento. Os fluxos de trabalho manuais de lançamento usam `stable` por padrão; use `full` somente quando você intencionalmente quiser a matriz ampla consultiva de provedores/mídia.
- `minimum` mantém as lanes OpenAI/núcleo críticas para lançamento mais rápidas.
- `stable` adiciona o conjunto estável de provedores/backend.
- `full` executa a matriz ampla de provedores/mídia de consultoria.
- `minimum` mantém as linhas OpenAI/núcleo críticas para lançamento mais rápidas.
- `stable` adiciona o conjunto estável de provedores/backends.
- `full` executa a matriz ampla consultiva de provedores/mídia.
O guarda-chuva registra os ids das execuções filhas disparadas, e o trabalho final `Verify full validation` verifica novamente as conclusões atuais das execuções filhas e acrescenta tabelas dos trabalhos mais lentos de cada execução filha. Se um fluxo de trabalho filho for reexecutado e ficar verde, reexecute apenas o trabalho verificador pai para atualizar o resultado guarda-chuva e o resumo de tempos.
Para recuperação, tanto `Full Release Validation` quanto `OpenClaw Release Checks` aceitam `rerun_group`. Use `all` para um candidato a lançamento, `ci` apenas para o filho de CI completo normal, `plugin-prerelease` apenas para o filho de pré-lançamento de plugins, `release-checks` para todos os filhos de lançamento, ou um grupo mais estreito: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` no guarda-chuva. Isso mantém limitada a reexecução de uma caixa de lançamento com falha após uma correção focada.
`OpenClaw Release Checks` usa a ref confiável do fluxo de trabalho para resolver a ref selecionada uma vez em um tarball `release-package-under-test`, depois passa esse artefato tanto para o fluxo de trabalho Docker live/E2E do caminho de lançamento quanto para o shard de aceitação de pacote. Isso mantém os bytes do pacote consistentes entre as caixas de lançamento e evita reempacotar o mesmo candidato em vários trabalhos filhos.
Execuções duplicadas de `Full Release Validation` para `ref=main` e `rerun_group=all` substituem o guarda-chuva mais antigo. O monitor pai cancela qualquer fluxo de trabalho filho que já tenha disparado quando o pai é cancelado, então a validação mais nova da main não fica atrás de uma execução obsoleta de duas horas de verificações de lançamento. A validação de branch/tag de lançamento e grupos de reexecução focados mantêm `cancel-in-progress: false`.
## Shards live e E2E
O filho live/E2E de lançamento mantém cobertura ampla nativa de `pnpm test:live`, mas a executa como shards nomeados por meio de `scripts/test-live-shard.mjs` em vez de um trabalho serial:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- trabalhos `native-live-src-gateway-profiles` filtrados por provedor
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
- `native-live-extensions-l-n`
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- shards de áudio/vídeo de mídia divididos e shards de música filtrados por provedor
Isso mantém a mesma cobertura de arquivos enquanto torna falhas lentas de provedores live mais fáceis de reexecutar e diagnosticar. Os nomes de shard agregados `native-live-extensions-o-z`, `native-live-extensions-media` e `native-live-extensions-media-music` continuam válidos para reexecuções manuais únicas.
Os shards nativos de mídia live executam em `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, criado pelo fluxo de trabalho `Live Media Runner Image`. Essa imagem pré-instala `ffmpeg` e `ffprobe`; os trabalhos de mídia apenas verificam os binários antes da configuração. Mantenha suítes live baseadas em Docker em runners Blacksmith normais — trabalhos em contêiner são o lugar errado para iniciar testes Docker aninhados.
Shards live de modelo/backend baseados em Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:<sha>` por commit selecionado. O fluxo de trabalho live de lançamento cria e envia essa imagem uma vez, depois os shards de modelo live Docker, Gateway divididos por provedor, backend CLI, vínculo ACP e harness Codex executam com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Shards Docker do Gateway carregam limites explícitos de `timeout` em nível de script abaixo do timeout do trabalho do fluxo de trabalho, para que um contêiner travado ou caminho de limpeza falhe rápido em vez de consumir todo o orçamento das verificações de lançamento. Se esses shards recriarem o alvo Docker de código-fonte completo independentemente, a execução de lançamento está mal configurada e desperdiçará tempo de relógio com builds duplicados de imagem.
## Aceitação de Pacote
Use `Package Acceptance` quando a pergunta for "este pacote OpenClaw instalável funciona como produto?" Ela é diferente da CI normal: a CI normal valida a árvore de código-fonte, enquanto a aceitação de pacote valida um único tarball pelo mesmo harness Docker E2E que os usuários exercitam após instalar ou atualizar.
### Trabalhos
1. `resolve_package` faz checkout de `workflow_ref`, resolve um candidato de pacote, grava `.artifacts/docker-e2e-package/openclaw-current.tgz`, grava `.artifacts/docker-e2e-package/package-candidate.json`, envia ambos como o artefato `package-under-test` e imprime a origem, ref do fluxo de trabalho, ref do pacote, versão, SHA-256 e perfil no resumo da etapa do GitHub.
2. `docker_acceptance` chama `openclaw-live-and-e2e-checks-reusable.yml` com `ref=workflow_ref` e `package_artifact_name=package-under-test`. O fluxo de trabalho reutilizável baixa esse artefato, valida o inventário do tarball, prepara imagens Docker de resumo de pacote quando necessário e executa as linhas Docker selecionadas contra esse pacote em vez de empacotar o checkout do fluxo de trabalho. Quando um perfil seleciona vários `docker_lanes` direcionados, o fluxo de trabalho reutilizável prepara o pacote e as imagens compartilhadas uma vez, depois distribui essas linhas como trabalhos Docker direcionados paralelos com artefatos únicos.
3. `package_telegram` opcionalmente chama `NPM Telegram Beta E2E`. Ele executa quando `telegram_mode` não é `none` e instala o mesmo artefato `package-under-test` quando Package Acceptance resolveu um; um disparo autônomo do Telegram ainda pode instalar uma especificação npm publicada.
4. `summary` falha o fluxo de trabalho se a resolução do pacote, a aceitação Docker ou a linha opcional do Telegram falhar.
### Origens de candidatos
- `source=npm` aceita somente `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw, como `openclaw@2026.4.27-beta.2`. Use isso para aceitação de pré-lançamento/estável publicado.
- `source=ref` empacota um branch, tag ou SHA completo de commit confiável em `package_ref`. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável pelo histórico de branches do repositório ou por uma tag de lançamento, instala dependências em uma árvore de trabalho destacada e o empacota com `scripts/package-openclaw-for-docker.mjs`.
- `source=url` baixa um `.tgz` HTTPS; `package_sha256` é obrigatório.
- `source=artifact` baixa um `.tgz` de `artifact_run_id` e `artifact_name`; `package_sha256` é opcional, mas deve ser fornecido para artefatos compartilhados externamente.
Mantenha `workflow_ref` e `package_ref` separados. `workflow_ref` é o código confiável de fluxo de trabalho/harness que executa o teste. `package_ref` é o commit de origem que é empacotado quando `source=ref`. Isso permite que o harness de teste atual valide commits de origem confiáveis mais antigos sem executar lógica antiga de fluxo de trabalho.
### Perfis de suíte
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
- `product` — `package` mais `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — blocos completos Docker do caminho de lançamento com OpenWebUI
- `custom` — `docker_lanes` exatos; obrigatório quando `suite_profile=custom`
O perfil `package` usa cobertura offline de plugins para que a validação de pacote publicado não dependa da disponibilidade live do ClawHub. A linha opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, mantendo o caminho de especificação npm publicada para disparos autônomos.
Para a política dedicada de testes de atualização e plugins, incluindo comandos locais, linhas Docker, entradas de Package Acceptance, padrões de lançamento e triagem de falhas, consulte [Testar atualizações e plugins](/pt-BR/help/testing-updates-plugins).
As verificações de lançamento chamam Package Acceptance com `source=artifact`, o artefato de pacote de lançamento preparado, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` e `telegram_mode=mock-openai`. Isso mantém a prova de migração de pacote, atualização, limpeza de dependência obsoleta de plugin, reparo de instalação de plugin configurado, plugin offline, atualização de plugin e Telegram no mesmo tarball de pacote resolvido. Defina `package_acceptance_package_spec` em Full Release Validation ou OpenClaw Release Checks para executar essa mesma matriz contra um pacote npm enviado em vez do artefato criado a partir do SHA. As verificações de lançamento entre sistemas operacionais ainda cobrem integração inicial específica de SO, instalador e comportamento de plataforma; a validação de produto de pacote/atualização deve começar com Package Acceptance. A linha Docker `published-upgrade-survivor` valida uma linha de base de pacote publicado por execução. Em Package Acceptance, o tarball `package-under-test` resolvido é sempre o candidato, e `published_upgrade_survivor_baseline` seleciona a linha de base publicada de fallback, com padrão `openclaw@latest`; comandos de reexecução de linha com falha preservam essa linha de base. Defina `published_upgrade_survivor_baselines=all-since-2026.4.23` para expandir a CI de Full Release por todos os lançamentos npm estáveis de `2026.4.23` até `latest`; `release-history` continua disponível para amostragem manual mais ampla com a âncora pré-data mais antiga. Defina `published_upgrade_survivor_scenarios=reported-issues` para expandir as mesmas linhas de base por fixtures em formato de issues para configuração do Feishu, arquivos bootstrap/persona preservados, instalações configuradas de plugin OpenClaw, caminhos de log com til e raízes obsoletas de dependência de plugins legados. O fluxo de trabalho separado `Update Migration` usa a linha Docker `update-migration` com `all-since-2026.4.23` e `plugin-deps-cleanup` quando a pergunta é limpeza exaustiva de atualização publicada, não a amplitude normal da CI de Full Release. Execuções agregadas locais podem passar especificações exatas de pacote com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, manter uma única linha com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, como `openclaw@2026.4.15`, ou definir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` para a matriz de cenários. A linha publicada configura a linha de base com uma receita incorporada de comando `openclaw config set`, registra etapas da receita em `summary.json` e sonda `/healthz`, `/readyz`, além do status RPC após o início do Gateway. As linhas frescas empacotadas e de instalador do Windows também verificam que um pacote instalado consegue importar uma substituição de controle de navegador de um caminho Windows absoluto bruto. O smoke de turno de agente OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` por padrão quando definido; caso contrário, `openai/gpt-5.4`, para que a prova de instalação e Gateway permaneça em um modelo de teste GPT-5 enquanto evita padrões GPT-4.x.
### Janelas de compatibilidade legada
Package Acceptance tem janelas limitadas de compatibilidade legada para pacotes já publicados. Pacotes até `2026.4.25`, incluindo `2026.4.25-beta.*`, podem usar o caminho de compatibilidade:
- entradas QA privadas conhecidas em `dist/postinstall-inventory.json` podem apontar para arquivos omitidos do tarball;
- `doctor-switch` pode pular o subcaso de persistência de `gateway install --wrapper` quando o pacote não expõe essa flag;
- `update-channel-switch` pode remover `pnpm.patchedDependencies` ausentes da fixture git falsa derivada do tarball e pode registrar `update.channel` persistido ausente;
- smokes de plugin podem ler locais legados de registro de instalação ou aceitar persistência ausente de registro de instalação do marketplace;
- `plugin-update` pode permitir migração de metadados de configuração enquanto ainda exige que o registro de instalação e o comportamento de não reinstalação permaneçam inalterados.
O pacote publicado `2026.4.26` também pode avisar sobre arquivos de carimbo de metadados de build local que já foram enviados. Pacotes posteriores devem satisfazer os contratos modernos; as mesmas condições falham em vez de avisar ou pular.
### Exemplos
```bash
# Validate the current beta package with product-level coverage.
@ -241,110 +304,110 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Ao depurar uma execução de aceitação de pacote com falha, comece pelo resumo `resolve_package` para confirmar a origem, a versão e o SHA-256 do pacote. Depois, inspecione a execução filha `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lanes, tempos de fase e comandos de nova execução. Prefira executar novamente o perfil de pacote com falha ou as lanes Docker exatas em vez de executar novamente a validação completa de release.
Ao depurar uma execução de aceitação de pacote com falha, comece pelo resumo de `resolve_package` para confirmar a origem do pacote, a versão e o SHA-256. Em seguida, inspecione a execução filha `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lanes, tempos de fase e comandos de reexecução. Prefira reexecutar o perfil de pacote com falha ou as lanes Docker exatas em vez de reexecutar a validação completa de lançamento.
## Smoke de instalação
O workflow separado `Install Smoke` reutiliza o mesmo script de escopo por meio do próprio job `preflight`. Ele divide a cobertura de smoke em `run_fast_install_smoke` e `run_full_install_smoke`.
O workflow separado `Install Smoke` reutiliza o mesmo script de escopo por meio do próprio job `preflight`. Ele divide a cobertura smoke em `run_fast_install_smoke` e `run_full_install_smoke`.
- **Caminho rápido** roda para pull requests que tocam superfícies de Docker/pacote, mudanças de pacote/manifesto de plugins empacotados, ou superfícies de plugin/canal/Gateway/Plugin SDK do core que os jobs de smoke Docker exercitam. Mudanças somente de código-fonte em plugins empacotados, edições somente de testes e edições somente de docs não reservam workers Docker. O caminho rápido cria a imagem do Dockerfile raiz uma vez, verifica a CLI, roda o smoke da CLI de exclusão de agents em workspace compartilhado, roda o e2e de rede do Gateway em contêiner, verifica um argumento de build de Plugin empacotado e roda o perfil Docker limitado de plugins empacotados com um tempo limite agregado de comando de 240 segundos (cada execução Docker de cenário é limitada separadamente).
- **Caminho completo** mantém a instalação de pacote QR e a cobertura Docker/de atualização do instalador para execuções noturnas agendadas, despachos manuais, verificações de release por workflow-call e pull requests que realmente tocam superfícies de instalador/pacote/Docker. No modo completo, o install-smoke prepara ou reutiliza uma imagem de smoke GHCR do Dockerfile raiz para um SHA de destino, depois roda a instalação de pacote QR, smokes do Dockerfile raiz/Gateway, smokes de instalador/atualização e o E2E Docker rápido de plugins empacotados como jobs separados para que o trabalho de instalador não espere atrás dos smokes da imagem raiz.
- **Caminho rápido** é executado para pull requests que tocam superfícies Docker/pacote, alterações em pacote/manifesto de Plugin empacotado ou superfícies centrais de Plugin/canal/Gateway/Plugin SDK exercitadas pelos jobs de smoke Docker. Alterações somente de código-fonte em Plugin empacotado, edições somente de teste e edições somente de documentação não reservam workers Docker. O caminho rápido cria a imagem do Dockerfile raiz uma vez, verifica a CLI, executa o smoke de CLI de exclusão de agentes em workspace compartilhado, executa o E2E de rede do Gateway em contêiner, verifica um argumento de build de extensão empacotada e executa o perfil Docker limitado de Plugin empacotado sob um timeout agregado de comando de 240 segundos (cada execução Docker de cenário é limitada separadamente).
- **Caminho completo** mantém a cobertura de instalação de pacote QR e Docker/atualização do instalador para execuções agendadas noturnas, disparos manuais, verificações de lançamento por chamada de workflow e pull requests que realmente tocam superfícies de instalador/pacote/Docker. No modo completo, o install-smoke prepara ou reutiliza uma imagem smoke GHCR do Dockerfile raiz para o SHA de destino e, então, executa a instalação de pacote QR, smokes do Dockerfile raiz/Gateway, smokes de instalador/atualização e o E2E Docker rápido de Plugin empacotado como jobs separados para que o trabalho de instalador não espere atrás dos smokes da imagem raiz.
Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo de mudanças pediria cobertura completa em um push, o workflow mantém o smoke Docker rápido e deixa o smoke de instalação completo para a validação noturna ou de release.
Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo de alterações solicitaria cobertura completa em um push, o workflow mantém o smoke Docker rápido e deixa o smoke completo de instalação para a validação noturna ou de lançamento.
O smoke lento do provedor de imagem de instalação global com Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele roda no agendamento noturno e a partir do workflow de verificações de release, e despachos manuais de `Install Smoke` podem optar por incluí-lo, mas pull requests e pushes para `main` não. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação.
O smoke lento de provedor de imagem com instalação global via Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele é executado na agenda noturna e a partir do workflow de verificações de lançamento, e disparos manuais de `Install Smoke` podem optar por incluí-lo, mas pull requests e pushes para `main` não. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação.
## E2E Docker local
`pnpm test:docker:all` pré-cria uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e cria duas imagens compartilhadas de `scripts/e2e/Dockerfile`:
`pnpm test:docker:all` pré-compila uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e cria duas imagens compartilhadas de `scripts/e2e/Dockerfile`:
- um runner Node/Git básico para lanes de instalador/atualização/dependência de plugin;
- um runner básico Node/Git para lanes de instalador/atualização/dependência de Plugin;
- uma imagem funcional que instala o mesmo tarball em `/app` para lanes de funcionalidade normal.
As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa somente o plano selecionado. O agendador seleciona a imagem por lane com `OPENCLAW_DOCKER_E2E_BARE_IMAGE` e `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, depois roda lanes com `OPENCLAW_SKIP_DOCKER_BUILD=1`.
As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa apenas o plano selecionado. O agendador seleciona a imagem por lane com `OPENCLAW_DOCKER_E2E_BARE_IMAGE` e `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, depois executa as lanes com `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Ajustes
### Parâmetros ajustáveis
| Variável | Padrão | Finalidade |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Contagem de slots do pool principal para lanes normais. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Contagem de slots do pool final sensível a provedores. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes live simultâneas para que os provedores não limitem a taxa. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limite de lanes simultâneas de instalação npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limite de lanes simultâneas com múltiplos serviços. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Intervalo entre inícios de lanes para evitar rajadas de criação do daemon Docker; defina `0` para não intervalar. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Tempo limite fallback por lane (120 minutos); lanes live/finais selecionadas usam limites mais rígidos. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do agendador sem executar lanes. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista de lanes exatas separadas por vírgulas; pula o smoke de limpeza para que agents possam reproduzir uma lane com falha. |
| Variável | Padrão | Finalidade |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Contagem de slots do pool principal para lanes normais. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Contagem de slots do pool final sensível a provedores. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes live concorrentes para que provedores não apliquem throttling. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limite de lanes concorrentes de instalação npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limite de lanes concorrentes com múltiplos serviços. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Intervalo escalonado entre inícios de lanes para evitar tempestades de criação no daemon Docker; defina `0` para sem escalonamento. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de fallback por lane (120 minutos); lanes live/finais selecionadas usam limites mais estritos. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do agendador sem executar lanes. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista separada por vírgulas de lanes exatas; pula o smoke de limpeza para que agentes possam reproduzir uma lane com falha. |
Uma lane mais pesada que seu limite efetivo ainda pode iniciar a partir de um pool vazio, depois roda sozinha até liberar capacidade. Os preflights agregados locais verificam Docker, removem contêineres E2E obsoletos do OpenClaw, emitem status de lanes ativas, persistem tempos de lanes para ordenação das mais longas primeiro e, por padrão, param de agendar novas lanes em pool após a primeira falha.
Uma lane mais pesada que seu limite efetivo ainda pode começar de um pool vazio e, então, roda sozinha até liberar capacidade. Os preflights agregados locais verificam o Docker, removem contêineres E2E obsoletos do OpenClaw, emitem status de lanes ativas, persistem tempos de lanes para ordenação da mais longa para a mais curta e param de agendar novas lanes em pool após a primeira falha por padrão.
### Workflow live/E2E reutilizável
O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` qual cobertura de pacote, tipo de imagem, imagem live, lane e credenciais é necessária. `scripts/docker-e2e.mjs` então converte esse plano em outputs e resumos do GitHub. Ele empacota o OpenClaw por meio de `scripts/package-openclaw-for-docker.mjs`, baixa um artefato de pacote da execução atual ou baixa um artefato de pacote de `package_artifact_run_id`; valida o inventário do tarball; cria e envia imagens GHCR Docker E2E básicas/funcionais com tag de digest do pacote por meio do cache de camadas Docker do Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` fornecidos ou imagens existentes com digest de pacote em vez de recriar. Pulls de imagens Docker são tentados novamente com um tempo limite limitado de 180 segundos por tentativa para que um stream travado de registry/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico de CI.
O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` qual pacote, tipo de imagem, imagem live, lane e cobertura de credenciais são necessários. `scripts/docker-e2e.mjs` então converte esse plano em saídas e resumos do GitHub. Ele empacota o OpenClaw por meio de `scripts/package-openclaw-for-docker.mjs`, baixa um artefato de pacote da execução atual ou baixa um artefato de pacote de `package_artifact_run_id`; valida o inventário do tarball; cria e envia imagens Docker E2E bare/funcionais GHCR marcadas com digest de pacote por meio do cache de camadas Docker do Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza entradas `docker_e2e_bare_image`/`docker_e2e_functional_image` fornecidas ou imagens existentes com digest de pacote em vez de reconstruir. Pulls de imagens Docker são repetidos com um timeout limitado de 180 segundos por tentativa para que um fluxo travado de registro/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico da CI.
### Chunks do caminho de release
### Fragmentos do caminho de lançamento
A cobertura Docker de release roda jobs menores em chunks com `OPENCLAW_SKIP_DOCKER_BUILD=1`, para que cada chunk baixe somente o tipo de imagem necessário e execute várias lanes pelo mesmo agendador ponderado:
A cobertura Docker de lançamento executa jobs menores em fragmentos com `OPENCLAW_SKIP_DOCKER_BUILD=1`, de modo que cada fragmento puxe apenas o tipo de imagem de que precisa e execute várias lanes pelo mesmo agendador ponderado:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
Os chunks Docker de release atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` e `plugins-runtime-install-a` até `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` continuam sendo aliases agregados de plugin/runtime. O alias de lane `install-e2e` continua sendo o alias agregado de nova execução manual para ambas as lanes de instalador de provedores.
Os fragmentos Docker de lançamento atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` e `plugins-runtime-install-a` até `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` permanecem aliases agregados de Plugin/runtime. O alias de lane `install-e2e` permanece o alias agregado de reexecução manual para ambas as lanes de instalador de provedor.
OpenWebUI é incorporado a `plugins-runtime-services` quando a cobertura completa de release-path o solicita, e mantém um chunk independente `openwebui` somente para despachos exclusivos do OpenWebUI. Lanes de atualização de canais empacotados tentam novamente uma vez em caso de falhas transitórias de rede npm.
OpenWebUI é incorporado em `plugins-runtime-services` quando a cobertura completa de release-path o solicita, e mantém um fragmento independente `openwebui` apenas para disparos somente do OpenWebUI. Lanes de atualização de canais empacotados tentam novamente uma vez em caso de falhas transitórias de rede npm.
Cada chunk envia `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do agendador, tabelas de lanes lentas e comandos de nova execução por lane. O input `docker_lanes` do workflow roda lanes selecionadas contra as imagens preparadas em vez dos jobs de chunk, o que mantém a depuração de lanes com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma lane selecionada for uma lane Docker live, o job direcionado cria a imagem de teste live localmente para essa nova execução. Comandos gerados de nova execução por lane no GitHub incluem `package_artifact_run_id`, `package_artifact_name` e inputs de imagem preparada quando esses valores existem, para que uma lane com falha possa reutilizar o pacote e as imagens exatos da execução com falha.
Cada fragmento faz upload de `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do agendador, tabelas de lanes lentas e comandos de reexecução por lane. A entrada `docker_lanes` do workflow executa lanes selecionadas contra as imagens preparadas em vez dos jobs de fragmento, o que mantém a depuração de lane com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma lane selecionada for uma lane Docker live, o job direcionado cria a imagem de teste live localmente para essa reexecução. Comandos gerados de reexecução por lane no GitHub incluem `package_artifact_run_id`, `package_artifact_name` e entradas de imagem preparadas quando esses valores existem, para que uma lane com falha possa reutilizar o pacote e as imagens exatos da execução com falha.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
O workflow live/E2E agendado roda diariamente a suíte Docker release-path completa.
O workflow live/E2E agendado executa diariamente a suíte Docker completa de release-path.
## Pré-release de Plugin
## Pré-lançamento de Plugin
`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, então é um workflow separado despachado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes para `main` e despachos manuais independentes de CI mantêm essa suíte desligada. Ele equilibra testes de plugins empacotados entre oito workers de extensão; esses jobs de shard de extensão rodam até dois grupos de configuração de plugins por vez, com um worker Vitest por grupo e um heap Node maior, para que lotes de plugins pesados em imports não criem jobs extras de CI. O caminho de pré-release Docker exclusivo de release agrupa lanes Docker direcionadas em pequenos grupos para evitar reservar dezenas de runners para jobs de um a três minutos.
`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, portanto é um workflow separado disparado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes para `main` e disparos manuais independentes de CI mantêm essa suíte desativada. Ele balanceia testes de Plugins empacotados entre oito workers de extensão; esses jobs de shard de extensão executam até dois grupos de configuração de Plugin por vez, com um worker Vitest por grupo e um heap Node maior para que lotes de Plugins pesados em importação não criem jobs extras de CI. O caminho Docker de pré-lançamento exclusivo de lançamento agrupa lanes Docker direcionadas em pequenos grupos para evitar reservar dezenas de runners para jobs de um a três minutos.
## QA Lab
QA Lab tem lanes dedicadas de CI fora do workflow principal com escopo inteligente. A paridade agentic fica aninhada nos harnesses amplos de QA e release, não em um workflow de PR independente. Use `Full Release Validation` com `rerun_group=qa-parity` quando a paridade deve acompanhar uma execução ampla de validação.
O QA Lab tem lanes dedicadas de CI fora do workflow principal com escopo inteligente. A paridade agêntica fica aninhada sob os harnesses amplos de QA e lançamento, não como um workflow autônomo de PR. Use `Full Release Validation` com `rerun_group=qa-parity` quando a paridade deve acompanhar uma execução ampla de validação.
- O workflow `QA-Lab - All Lanes` roda todas as noites em `main` e em despacho manual; ele distribui a lane de paridade mock, a lane Matrix live e as lanes live de Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases do Convex.
- O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e por disparo manual; ele distribui a lane de paridade mock, a lane live Matrix e as lanes live Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases Convex.
As verificações de release rodam lanes de transporte live Matrix e Telegram com o provedor mock determinístico e modelos qualificados por mock (`mock-openai/gpt-5.5` e `mock-openai/gpt-5.5-alt`), para que o contrato do canal fique isolado da latência de modelos live e da inicialização normal do plugin de provedor. O Gateway de transporte live desativa a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedores é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker.
As verificações de lançamento executam lanes de transporte live Matrix e Telegram com o provedor mock determinístico e modelos qualificados por mock (`mock-openai/gpt-5.5` e `mock-openai/gpt-5.5-alt`) para que o contrato do canal fique isolado da latência de modelos live e da inicialização normal de Plugin de provedor. O Gateway de transporte live desativa a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedores é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker.
Matrix usa `--profile fast` para gates agendados e de release, adicionando `--fail-fast` somente quando a CLI em checkout tem suporte a ele. O padrão da CLI e o input manual do workflow continuam sendo `all`; o despacho manual com `matrix_profile=all` sempre divide a cobertura Matrix completa em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`.
Matrix usa `--profile fast` para gates agendados e de lançamento, adicionando `--fail-fast` apenas quando a CLI em checkout oferece suporte a isso. O padrão da CLI e a entrada manual do workflow permanecem `all`; o disparo manual `matrix_profile=all` sempre fragmenta a cobertura Matrix completa em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`.
`OpenClaw Release Checks` também roda as lanes críticas de release do QA Lab antes da aprovação de release; seu gate de paridade de QA roda os pacotes candidato e baseline como jobs de lane paralelos, depois baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade.
`OpenClaw Release Checks` também executa as lanes críticas de lançamento do QA Lab antes da aprovação de lançamento; seu gate de paridade de QA executa os pacotes candidato e baseline como jobs de lanes paralelos e, então, baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade.
Para PRs normais, siga evidências de CI/verificações com escopo em vez de tratar paridade como um status obrigatório.
Para PRs normais, siga evidências de CI/verificações com escopo em vez de tratar a paridade como um status obrigatório.
## CodeQL
O fluxo de trabalho `CodeQL` é intencionalmente um scanner de segurança estreito de primeira passagem, não a varredura completa do repositório. Execuções diárias, manuais e de guarda de pull requests não rascunho analisam código de fluxos de trabalho do Actions mais as superfícies JavaScript/TypeScript de maior risco com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica.
O fluxo de trabalho `CodeQL` é intencionalmente um verificador de segurança inicial e estreito, não uma varredura completa do repositório. Execuções de proteção diárias, manuais e de solicitações de pull não rascunho verificam o código de fluxos de trabalho do Actions, além das superfícies JavaScript/TypeScript de maior risco, com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica.
A guarda de pull request permanece leve: ela só inicia para alterações em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança que o fluxo de trabalho agendado. O CodeQL para Android e macOS fica fora dos padrões de PR.
A proteção de solicitação de pull permanece leve: ela só inicia para alterações em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança do fluxo de trabalho agendado. CodeQL para Android e macOS fica fora dos padrões de PR.
### Categorias de segurança
| Categoria | Superfície |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Linha de base de autenticação, segredos, sandbox, cron e gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canal do núcleo mais o runtime do plugin de canal, gateway, Plugin SDK, segredos e pontos de auditoria |
| `/codeql-security-high/network-ssrf-boundary` | Superfícies de SSRF do núcleo, análise de IP, guarda de rede, web-fetch e política de SSRF do Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, auxiliares de execução de processos, entrega de saída e gates de execução de ferramentas de agentes |
| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, loader, manifesto, registro, instalação de gerenciador de pacotes, carregamento de código-fonte e contrato de pacote do Plugin SDK |
| Categoria | Superfície |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Linha de base de autenticação, segredos, sandbox, cron e Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canal do núcleo, além do runtime do plugin de canal, Gateway, Plugin SDK, segredos e pontos de auditoria |
| `/codeql-security-high/network-ssrf-boundary` | Superfícies de SSRF do núcleo, análise de IP, proteção de rede, busca web e política de SSRF do Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, auxiliares de execução de processo, entrega de saída e proteções de execução de ferramentas de agentes |
| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, carregador, manifesto, registro, instalação do gerenciador de pacotes, carregamento de código-fonte e contrato de pacote do Plugin SDK |
### Shards de segurança específicos de plataforma
- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Compila o aplicativo Android manualmente para o CodeQL no menor runner Blacksmith Linux aceito pela sanidade do fluxo de trabalho. Faz upload em `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard semanal/manual de segurança do macOS. Compila o aplicativo macOS manualmente para o CodeQL no Blacksmith macOS, filtra resultados de build de dependências para fora do SARIF enviado e faz upload em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque o build do macOS domina o tempo de execução mesmo quando está limpo.
- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Compila o aplicativo Android manualmente para o CodeQL no menor executor Linux do Blacksmith aceito pela sanidade do fluxo de trabalho. Envia em `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard semanal/manual de segurança do macOS. Compila o aplicativo macOS manualmente para o CodeQL no Blacksmith macOS, filtra resultados de compilação de dependências fora do SARIF enviado e envia em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque a compilação do macOS domina o tempo de execução mesmo quando está limpa.
### Categorias de Qualidade Crítica
### Categorias de qualidade crítica
`CodeQL Critical Quality` é o shard não relacionado a segurança correspondente. Ele executa apenas consultas de qualidade JavaScript/TypeScript sem segurança e com severidade de erro sobre superfícies estreitas de alto valor no runner Blacksmith Linux menor. Sua guarda de pull request é intencionalmente menor que o perfil agendado: PRs não rascunho só executam os shards correspondentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` e `plugin-sdk-reply-runtime` para alterações em código de execução de comando/modelo/ferramenta de agente e despacho de resposta, schema/migração/IO de configuração, código de autenticação/segredos/sandbox/segurança, runtime de canal do núcleo e de plugin de canal incluído, protocolo/método de servidor do gateway, cola de runtime/SDK de memória, MCP/processo/entrega de saída, runtime de provider/catálogo de modelos, diagnósticos de sessão/filas de entrega, loader de Plugin, contrato de pacote/Plugin SDK ou runtime de resposta do Plugin SDK. Alterações na configuração do CodeQL e no fluxo de trabalho de qualidade executam todos os doze shards de qualidade de PR.
`CodeQL Critical Quality` é o shard não relacionado a segurança correspondente. Ele executa apenas consultas de qualidade JavaScript/TypeScript sem segurança e com severidade de erro sobre superfícies estreitas de alto valor no executor Linux menor do Blacksmith. Sua proteção de solicitação de pull é intencionalmente menor que o perfil agendado: PRs não rascunho executam apenas os shards correspondentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` e `plugin-sdk-reply-runtime` para alterações em código de execução de comando/modelo/ferramenta de agente e despacho de respostas, código de esquema/migração/IO de configuração, código de autenticação/segredos/sandbox/segurança, canal do núcleo e runtime de plugin de canal empacotado, protocolo/método de servidor do Gateway, cola de runtime/SDK de memória, MCP/processo/entrega de saída, catálogo de runtime/modelos de provedores, diagnósticos de sessão/filas de entrega, carregador de Plugin, contrato de Plugin SDK/pacote ou runtime de respostas do Plugin SDK. Alterações na configuração do CodeQL e no fluxo de trabalho de qualidade executam todos os doze shards de qualidade de PR.
O despacho manual aceita:
@ -355,37 +418,37 @@ profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-run
Os perfis estreitos são ganchos de ensino/iteração para executar um shard de qualidade isoladamente.
| Categoria | Superfície |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/codeql-critical-quality/core-auth-secrets` | Código de fronteira de segurança de autenticação, segredos, sandbox, cron e gateway |
| `/codeql-critical-quality/config-boundary` | Contratos de schema, migração, normalização e IO de configuração |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schemas de protocolo do Gateway e contratos de métodos de servidor |
| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canal do núcleo e de plugin de canal incluído |
| `/codeql-critical-quality/agent-runtime-boundary` | Contratos de runtime de execução de comandos, despacho de modelo/provider, despacho e filas de resposta automática, e plano de controle ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP e pontes de ferramentas, auxiliares de supervisão de processos e contratos de entrega de saída |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK do host de memória, facades de runtime de memória, aliases de memória do Plugin SDK, cola de ativação do runtime de memória e comandos doctor de memória |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internos da fila de respostas, filas de entrega de sessão, auxiliares de vinculação/entrega de sessão de saída, superfícies de eventos diagnósticos/bundles de logs e contratos de CLI doctor de sessão |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de resposta de entrada do Plugin SDK, auxiliares de payload/fragmentação/runtime de resposta, opções de resposta de canal, filas de entrega e auxiliares de vinculação de sessão/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalização de catálogo de modelos, autenticação e descoberta de providers, registro de runtime de provider, padrões/catálogos de provider e registros web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap da UI de controle, persistência local, fluxos de controle do Gateway e contratos de runtime do plano de controle de tarefas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Contratos de runtime de fetch/search web do núcleo, IO de mídia, entendimento de mídia, geração de imagens e geração de mídia |
| `/codeql-critical-quality/plugin-boundary` | Contratos de ponto de entrada de loader, registro, superfície pública e Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do Plugin SDK no lado do pacote publicado e auxiliares de contrato de pacote de plugin |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Código de fronteira de segurança de autenticação, segredos, sandbox, cron e Gateway |
| `/codeql-critical-quality/config-boundary` | Contratos de esquema, migração, normalização e IO de configuração |
| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas do protocolo do Gateway e contratos de métodos de servidor |
| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canal do núcleo e de plugin de canal empacotado |
| `/codeql-critical-quality/agent-runtime-boundary` | Execução de comandos, despacho de modelo/provedor, despacho e filas de resposta automática e contratos de runtime do plano de controle ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP e pontes de ferramentas, auxiliares de supervisão de processo e contratos de entrega de saída |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK de host de memória, fachadas de runtime de memória, aliases de memória do Plugin SDK, cola de ativação de runtime de memória e comandos doctor de memória |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internos de fila de resposta, filas de entrega de sessão, auxiliares de vinculação/entrega de sessão de saída, superfícies de evento diagnóstico/pacote de logs e contratos de CLI doctor de sessão |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do Plugin SDK, auxiliares de payload/fragmentação/runtime de resposta, opções de resposta de canal, filas de entrega e auxiliares de vinculação de sessão/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalização de catálogo de modelos, autenticação e descoberta de provedores, registro de runtime de provedores, padrões/catálogos de provedores e registros de web/pesquisa/busca/embedding |
| `/codeql-critical-quality/ui-control-plane` | Inicialização da UI de controle, persistência local, fluxos de controle do Gateway e contratos de runtime do plano de controle de tarefas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Busca/pesquisa web do núcleo, IO de mídia, compreensão de mídia, geração de imagens e contratos de runtime de geração de mídia |
| `/codeql-critical-quality/plugin-boundary` | Contratos de carregador, registro, superfície pública e pontos de entrada do Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do Plugin SDK do lado do pacote publicado e auxiliares de contrato de pacote de plugin |
A qualidade permanece separada da segurança para que achados de qualidade possam ser agendados, medidos, desabilitados ou expandidos sem obscurecer o sinal de segurança. A expansão do CodeQL para Swift, Python e plugins incluídos deve ser adicionada de volta como trabalho de acompanhamento com escopo ou dividido em shards somente depois que os perfis estreitos tiverem tempo de execução e sinal estáveis.
Qualidade fica separada de segurança para que achados de qualidade possam ser agendados, medidos, desativados ou expandidos sem obscurecer o sinal de segurança. A expansão do CodeQL para Swift, Python e plugins empacotados deve ser adicionada de volta como trabalho de acompanhamento com escopo ou sharding apenas depois que os perfis estreitos tiverem runtime e sinal estáveis.
## Fluxos de trabalho de manutenção
### Docs Agent
O fluxo de trabalho `Docs Agent` é uma via de manutenção Codex orientada por eventos para manter a documentação existente alinhada com alterações integradas recentemente. Ele não tem agendamento puro: uma execução de CI bem-sucedida em `main` após push que não seja de bot pode acioná-lo, e o despacho manual pode executá-lo diretamente. Invocações por workflow-run são ignoradas quando `main` avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando executa, ele revisa o intervalo de commits do SHA de origem anterior não ignorado do Docs Agent até o `main` atual, de modo que uma execução horária possa cobrir todas as alterações acumuladas em main desde a última passagem de documentação.
O fluxo de trabalho `Docs Agent` é uma via de manutenção do Codex orientada por eventos para manter a documentação existente alinhada com alterações recém-integradas. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, e o despacho manual pode executá-lo diretamente. Invocações por workflow-run são ignoradas quando `main` já avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando ele executa, revisa o intervalo de commits desde o SHA de origem anterior não ignorado do Docs Agent até o `main` atual, então uma execução horária pode cobrir todas as alterações em main acumuladas desde a última passagem de documentação.
### Test Performance Agent
O fluxo de trabalho `Test Performance Agent` é uma via de manutenção Codex orientada por eventos para testes lentos. Ele não tem agendamento puro: uma execução de CI bem-sucedida em `main` após push que não seja de bot pode acioná-lo, mas ele é ignorado se outra invocação por workflow-run já executou ou está executando naquele dia UTC. O despacho manual ignora esse gate diário de atividade. A via constrói um relatório de performance Vitest agrupado de suíte completa, permite que o Codex faça apenas pequenas correções de performance de testes que preservem a cobertura em vez de refatorações amplas, depois executa novamente o relatório de suíte completa e rejeita alterações que reduzam a contagem de testes aprovados da linha de base. Se a linha de base tiver testes falhando, o Codex pode corrigir apenas falhas óbvias, e o relatório de suíte completa após o agente precisa passar antes que qualquer coisa seja commitada. Quando `main` avança antes do push do bot ser integrado, a via aplica rebase ao patch validado, executa novamente `pnpm check:changed` e tenta o push de novo; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado pelo GitHub para que a action do Codex possa manter a mesma postura de segurança drop-sudo do agente de documentação.
O fluxo de trabalho `Test Performance Agent` é uma via de manutenção do Codex orientada por eventos para testes lentos. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, mas ele é ignorado se outra invocação por workflow-run já foi executada ou está em execução naquele dia UTC. O despacho manual ignora essa proteção de atividade diária. A via cria um relatório de desempenho agrupado de Vitest da suíte completa, permite que o Codex faça apenas pequenas correções de desempenho de testes que preservem a cobertura, em vez de refatorações amplas, depois reexecuta o relatório da suíte completa e rejeita alterações que reduzam a contagem de testes aprovados da linha de base. Se a linha de base tiver testes falhando, o Codex pode corrigir apenas falhas óbvias, e o relatório da suíte completa pós-agente deve passar antes de qualquer coisa ser commitada. Quando `main` avança antes que o push do bot seja integrado, a via faz rebase do patch validado, reexecuta `pnpm check:changed` e tenta o push novamente; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado no GitHub para que a ação do Codex possa manter a mesma postura de segurança drop-sudo do agente de documentação.
### PRs duplicados após merge
O fluxo de trabalho `Duplicate PRs After Merge` é um fluxo de trabalho manual de mantenedor para limpeza de duplicatas após integração. Ele usa dry-run por padrão e só fecha PRs listados explicitamente quando `apply=true`. Antes de modificar o GitHub, ele verifica que o PR integrado recebeu merge e que cada duplicado tem uma issue referenciada em comum ou hunks alterados sobrepostos.
O fluxo de trabalho `Duplicate PRs After Merge` é um fluxo de trabalho manual de mantenedor para limpeza de duplicatas pós-integração. Ele usa dry-run por padrão e só fecha PRs explicitamente listados quando `apply=true`. Antes de alterar o GitHub, ele verifica se o PR integrado foi mesclado e se cada duplicata tem um problema referenciado compartilhado ou hunks alterados sobrepostos.
```bash
gh workflow run duplicate-after-merge.yml \
@ -394,40 +457,117 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Gates de verificação local e roteamento de alterações
## Proteções de verificação local e roteamento de alterações
A lógica local de changed-lane fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate de verificação local é mais rígido quanto a fronteiras de arquitetura do que o escopo amplo da plataforma de CI:
A lógica local de changed-lane vive em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Essa proteção de verificação local é mais estrita sobre fronteiras de arquitetura do que o escopo amplo da plataforma de CI:
- alterações de produção no núcleo executam typecheck de produção do núcleo e testes do núcleo mais lint/guardas do núcleo;
- alterações somente de teste no núcleo executam apenas typecheck de testes do núcleo mais lint do núcleo;
- alterações de produção em extensão executam typecheck de produção e de testes de extensão mais lint de extensão;
- alterações somente de teste em extensão executam typecheck de testes de extensão mais lint de extensão;
- alterações públicas no Plugin SDK ou no contrato de plugin expandem para typecheck de extensões porque as extensões dependem desses contratos do núcleo (varreduras Vitest de extensões permanecem como trabalho de teste explícito);
- incrementos de versão somente em metadados de release executam verificações direcionadas de versão/configuração/dependências raiz;
- alterações desconhecidas em raiz/configuração falham com segurança para todas as vias de verificação.
- alterações de produção do núcleo executam typecheck de produção do núcleo e de testes do núcleo, além de lint/proteções do núcleo;
- alterações apenas em testes do núcleo executam somente typecheck de testes do núcleo, além de lint do núcleo;
- alterações de produção de extensão executam typecheck de produção e de testes de extensão, além de lint de extensão;
- alterações apenas em testes de extensão executam typecheck de testes de extensão, além de lint de extensão;
- alterações no Plugin SDK público ou no contrato de plugins expandem para typecheck de extensões porque extensões dependem desses contratos do núcleo (varreduras de extensão do Vitest continuam sendo trabalho explícito de teste);
- bumps de versão somente de metadados de release executam verificações direcionadas de versão/configuração/dependência raiz;
- alterações desconhecidas de raiz/configuração falham de modo seguro para todas as vias de verificação.
O roteamento local de changed-test fica em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de testes executam os próprios testes, edições de código-fonte preferem mapeamentos explícitos, depois testes irmãos e dependentes do grafo de importação. A configuração compartilhada de entrega de sala de grupo é um dos mapeamentos explícitos: alterações na configuração de resposta visível para grupo, modo de entrega de resposta de origem ou prompt de sistema da ferramenta de mensagem passam pelos testes de resposta do núcleo mais regressões de entrega do Discord e Slack, de modo que uma alteração compartilhada de padrão falhe antes do primeiro push de PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável.
O roteamento local de changed-test vive em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de testes executam a si mesmas, edições de código-fonte preferem mapeamentos explícitos, depois testes irmãos e dependentes do grafo de importação. A configuração compartilhada de entrega em salas de grupo é um dos mapeamentos explícitos: alterações na configuração de resposta visível de grupo, no modo de entrega de resposta de origem ou no prompt de sistema da ferramenta de mensagens passam pelos testes de resposta do núcleo, além de regressões de entrega do Discord e Slack, para que uma alteração de padrão compartilhado falhe antes do primeiro push de PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` apenas quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável.
## Validação no Testbox
## Validação Testbox
Execute o Testbox a partir da raiz do repositório e prefira uma box nova e aquecida para validação ampla. Antes de gastar uma verificação lenta em uma box que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute `pnpm testbox:sanity` dentro da box primeiro.
Execute o Testbox a partir da raiz do repositório e prefira uma box recém-aquecida para comprovação ampla. Antes de gastar um gate lento em uma box que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute `pnpm testbox:sanity` dentro da box primeiro.
A verificação de sanidade falha rapidamente quando arquivos obrigatórios da raiz, como `pnpm-lock.yaml`, desaparecem ou quando `git status --short` mostra pelo menos 200 exclusões rastreadas. Isso geralmente significa que o estado de sincronização remota não é uma cópia confiável do PR; pare essa box e aqueça uma nova em vez de depurar a falha do teste do produto. Para PRs intencionais com muitas exclusões, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade.
A verificação de sanidade falha rapidamente quando arquivos obrigatórios da raiz, como `pnpm-lock.yaml`, desapareceram ou quando `git status --short` mostra pelo menos 200 exclusões rastreadas. Isso normalmente significa que o estado da sincronização remota não é uma cópia confiável do PR; pare essa box e aqueça uma nova em vez de depurar a falha do teste do produto. Para PRs com grandes exclusões intencionais, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade.
`pnpm testbox:run` também encerra uma invocação local da Blacksmith CLI que permanece na fase de sincronização por mais de cinco minutos sem saída pós-sincronização. Defina `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desativar essa proteção, ou use um valor maior em milissegundos para diffs locais excepcionalmente grandes.
`pnpm testbox:run` também encerra uma invocação local da CLI do Blacksmith que permanece na fase de sincronização por mais de cinco minutos sem saída pós-sincronização. Defina `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desativar essa proteção, ou use um valor maior em milissegundos para diffs locais incomumente grandes.
Crabbox é o segundo caminho de box remota de propriedade do repositório para validação em Linux quando o Blacksmith está indisponível ou quando a capacidade de nuvem própria é preferível. Aqueça uma box, hidrate-a pelo workflow do projeto e então execute comandos pela Crabbox CLI:
Crabbox é o wrapper de box remota mantido pelo repositório para comprovação Linux de mantenedores. Use-o quando uma verificação for ampla demais para um ciclo local de edição, quando a paridade com CI for importante ou quando a comprovação precisar de segredos, Docker, lanes de pacote, boxes reutilizáveis ou logs remotos. O backend normal do OpenClaw é `blacksmith-testbox`; a capacidade própria em AWS/Hetzner é uma alternativa para indisponibilidades do Blacksmith, problemas de cota ou testes explícitos em capacidade própria.
Antes de uma primeira execução, verifique o wrapper a partir da raiz do repositório:
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id>
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id>
pnpm crabbox:run -- --help | sed -n '1,120p'
```
`.crabbox.yaml` controla os padrões de provedor, sincronização e hidratação do GitHub Actions. Ele exclui o `.git` local para que o checkout hidratado do Actions mantenha seus próprios metadados Git remotos em vez de sincronizar remotos e armazenamentos de objetos locais do mantenedor, e exclui artefatos locais de runtime/build que nunca devem ser transferidos. `.github/workflows/crabbox-hydrate.yml` controla o checkout, a configuração de Node/pnpm, o fetch de `origin/main` e o repasse de ambiente não secreto que comandos posteriores de `crabbox run --id <cbx_id>` carregam.
O wrapper do repositório recusa um binário Crabbox obsoleto que não anuncia `blacksmith-testbox`. Passe o provider explicitamente, mesmo que `.crabbox.yaml` tenha padrões de nuvem própria.
## Relacionado
Gate de alterações:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
--blacksmith-org openclaw \
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
--blacksmith-job check \
--blacksmith-ref main \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
--shell -- \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
```
Reexecução de teste focado:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
--blacksmith-org openclaw \
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
--blacksmith-job check \
--blacksmith-ref main \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
--shell -- \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
```
Suíte completa:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
--blacksmith-org openclaw \
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
--blacksmith-job check \
--blacksmith-ref main \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
--shell -- \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
Leia o resumo JSON final. Os campos úteis são `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` e `totalMs`. Execuções Crabbox únicas com suporte do Blacksmith devem parar o Testbox automaticamente; se uma execução for interrompida ou a limpeza não estiver clara, inspecione as boxes ativas e pare somente as boxes que você criou:
```bash
blacksmith testbox list
blacksmith testbox stop --id <tbx_id>
```
Use reutilização somente quando você precisar intencionalmente de vários comandos na mesma box hidratada:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
Se o Crabbox for a camada quebrada, mas o próprio Blacksmith funcionar, use o Blacksmith direto como alternativa restrita:
```bash
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
blacksmith testbox stop --id <tbx_id>
```
Escalone para capacidade própria do Crabbox somente quando o Blacksmith estiver indisponível, limitado por cota, sem o ambiente necessário ou quando a capacidade própria for explicitamente o objetivo:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` controla os padrões de provider, sincronização e hidratação do GitHub Actions para lanes de nuvem própria. Ele exclui o `.git` local para que o checkout hidratado do Actions mantenha seus próprios metadados Git remotos em vez de sincronizar remotos e armazenamentos de objetos locais dos mantenedores, e exclui artefatos locais de runtime/build que nunca devem ser transferidos. `.github/workflows/crabbox-hydrate.yml` controla o checkout, a configuração do Node/pnpm, o fetch de `origin/main` e a transferência de ambiente sem segredos para comandos `crabbox run --id <cbx_id>` em nuvem própria.
## Relacionados
- [Visão geral da instalação](/pt-BR/install)
- [Canais de desenvolvimento](/pt-BR/install/development-channels)

194
docs/pt-BR/cli/plugins.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Você deseja instalar ou gerenciar Plugins do Gateway ou pacotes compatíveis
- Você quer depurar falhas de carregamento de Plugin
- Você quer instalar ou gerenciar plugins do Gateway ou pacotes compatíveis
- Você quer depurar falhas no carregamento de Plugin
sidebarTitle: Plugins
summary: Referência da CLI para `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: Plugins
x-i18n:
generated_at: "2026-05-03T21:29:10Z"
generated_at: "2026-05-04T05:52:01Z"
model: gpt-5.5
provider: openai
source_hash: d854d052b0a012a86f9c775775676a9a8fe8ae86b2c38a18118f1abf0732174c
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
source_path: cli/plugins.md
workflow: 16
---
@ -17,19 +17,19 @@ x-i18n:
Gerencie plugins do Gateway, pacotes de hooks e bundles compatíveis.
<CardGroup cols={2}>
<Card title="Plugin system" href="/pt-BR/tools/plugin">
<Card title="Sistema de Plugin" href="/pt-BR/tools/plugin">
Guia do usuário final para instalar, habilitar e solucionar problemas de plugins.
</Card>
<Card title="Manage plugins" href="/pt-BR/plugins/manage-plugins">
<Card title="Gerenciar plugins" href="/pt-BR/plugins/manage-plugins">
Exemplos rápidos para instalar, listar, atualizar, desinstalar e publicar.
</Card>
<Card title="Plugin bundles" href="/pt-BR/plugins/bundles">
<Card title="Bundles de Plugin" href="/pt-BR/plugins/bundles">
Modelo de compatibilidade de bundles.
</Card>
<Card title="Plugin manifest" href="/pt-BR/plugins/manifest">
<Card title="Manifesto de Plugin" href="/pt-BR/plugins/manifest">
Campos do manifesto e esquema de configuração.
</Card>
<Card title="Security" href="/pt-BR/gateway/security">
<Card title="Segurança" href="/pt-BR/gateway/security">
Reforço de segurança para instalações de plugins.
</Card>
</CardGroup>
@ -63,18 +63,18 @@ openclaw plugins marketplace list <marketplace> --json
```
Para investigar instalações, inspeções, desinstalações ou atualizações de registro lentas, execute o
comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O trace grava tempos por fase
comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O rastreamento grava os tempos das fases
em stderr e mantém a saída JSON analisável. Consulte [Depuração](/pt-BR/help/debugging#plugin-lifecycle-trace).
<Note>
Plugins integrados são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelos integrados, provedores de fala integrados e o Plugin de navegador integrado); outros exigem `plugins enable`.
Plugins incluídos são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelo incluídos, provedores de fala incluídos e o plugin de navegador incluído); outros exigem `plugins enable`.
Plugins OpenClaw nativos devem distribuir `openclaw.plugin.json` com um JSON Schema inline (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.
Plugins nativos do OpenClaw devem distribuir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.
`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de lista/informações também mostra o subtipo de bundle (`codex`, `claude` ou `cursor`) e os recursos de bundle detectados.
`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo de bundle (`codex`, `claude` ou `cursor`) mais os recursos de bundle detectados.
</Note>
### Instalação
### Instalar
```bash
openclaw plugins search "calendar" # search ClawHub plugins
@ -93,69 +93,69 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
Nomes de pacote simples são instalados do npm por padrão durante a transição de lançamento. Use `clawhub:<package>` para ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
Nomes de pacote simples instalam a partir do npm por padrão durante a transição de lançamento. Use `clawhub:<package>` para ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
</Warning>
`plugins search` consulta o ClawHub em busca de pacotes de plugins instaláveis e imprime
nomes de pacotes prontos para instalação. Ele pesquisa pacotes de code-plugin e bundle-plugin,
nomes de pacotes prontos para instalação. Ele pesquisa pacotes de plugins de código e de bundles,
não Skills. Use `openclaw skills search` para Skills do ClawHub.
<Note>
ClawHub é a superfície principal de distribuição e descoberta para a maioria dos plugins. O npm
continua sendo um fallback e caminho de instalação direta compatível. Pacotes de plugins
`@openclaw/*` mantidos pelo OpenClaw voltaram a ser publicados no npm; veja a lista atual
ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. O npm
continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de plugins
`@openclaw/*` pertencentes ao OpenClaw são publicados no npm novamente; veja a lista atual
em [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) ou no
[inventário de plugins](/pt-BR/plugins/plugin-inventory). Instalações estáveis usam `latest`.
Instalações e atualizações do canal beta preferem a dist-tag `beta` do npm quando essa tag
está disponível e, em seguida, fazem fallback para `latest`.
está disponível, depois retornam para `latest`.
</Note>
<AccordionGroup>
<Accordion title="Config includes and invalid-config repair">
Se sua seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` grava nesse arquivo incluído e deixa `openclaw.json` intacto. Includes raiz, arrays de includes e includes com substituições irmãs falham fechados em vez de serem achatados. Consulte [includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis.
<Accordion title="Includes de configuração e reparo de configuração inválida">
Se a seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` grava nesse arquivo incluído e deixa `openclaw.json` intacto. Includes raiz, arrays de include e includes com sobrescritas irmãs falham de forma fechada em vez de nivelar. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis.
Se a configuração for inválida durante a instalação, `plugins install` normalmente falha fechado e informa que você deve executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e recarregamento a quente, uma configuração de Plugin inválida falha fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar em quarentena a entrada de Plugin inválida. A única exceção documentada em tempo de instalação é um caminho estreito de recuperação de Plugin integrado para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`.
Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e informa que você deve executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração de plugin inválida falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar em quarentena a entrada de plugin inválida. A única exceção documentada no momento da instalação é um caminho restrito de recuperação de plugins incluídos para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`.
</Accordion>
<Accordion title="--force and reinstall vs update">
`--force` reutiliza o destino de instalação existente e sobrescreve no lugar um Plugin ou pacote de hooks já instalado. Use quando você estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo compactado, pacote ClawHub ou artefato npm. Para atualizações rotineiras de um Plugin npm já rastreado, prefira `openclaw plugins update <id-or-npm-spec>`.
<Accordion title="--force e reinstalar versus atualizar">
`--force` reutiliza o destino de instalação existente e sobrescreve no local um plugin ou pacote de hooks já instalado. Use quando você estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo compactado, pacote do ClawHub ou artefato do npm. Para upgrades rotineiros de um plugin npm já rastreado, prefira `openclaw plugins update <id-or-npm-spec>`.
Se você executar `plugins install` para um id de Plugin que já está instalado, o OpenClaw interrompe e indica `plugins update <id-or-npm-spec>` para uma atualização normal, ou `plugins install <package> --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
Se você executar `plugins install` para um id de plugin que já está instalado, o OpenClaw interrompe e aponta para `plugins update <id-or-npm-spec>` para um upgrade normal, ou para `plugins install <package> --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
</Accordion>
<Accordion title="--pin scope">
`--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma ref git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de origem do marketplace em vez de uma spec npm.
<Accordion title="Escopo de --pin">
`--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma referência git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` é uma opção de contingência para falsos positivos no verificador integrado de código perigoso. Ela permite que a instalação continue mesmo quando o verificador integrado relata achados `critical`, mas **não** ignora bloqueios de política do hook `before_install` do Plugin e **não** ignora falhas de verificação.
`--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no scanner interno de código perigoso. Ela permite que a instalação continue mesmo quando o scanner interno relata achados `critical`, mas **não** ignora bloqueios de política do hook `before_install` do plugin e **não** ignora falhas de varredura.
Essa flag de CLI se aplica aos fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub.
Essa flag da CLI se aplica a fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub.
Se um Plugin que você publicou no ClawHub for bloqueado por uma verificação de registro, use as etapas de publicador em [ClawHub](/pt-BR/tools/clawhub).
Se um plugin que você publicou no ClawHub for bloqueado por uma varredura do registro, use as etapas de publicador em [ClawHub](/pt-BR/tools/clawhub).
</Accordion>
<Accordion title="Hook packs and npm specs">
<Accordion title="Pacotes de hooks e especificações npm">
`plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacotes.
Specs npm são **apenas de registro** (nome do pacote + **versão exata** ou **dist-tag** opcional). Specs Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências são executadas localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação npm.
Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências são executadas localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação npm.
Use `npm:<package>` quando quiser tornar explícita a resolução npm. Specs de pacote simples também são instaladas diretamente do npm durante a transição de lançamento.
Use `npm:<package>` quando quiser explicitar a resolução por npm. Especificações simples de pacote também instalam diretamente do npm durante a transição de lançamento.
Specs simples e `@latest` permanecem na trilha estável. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw interrompe e pede que você opte explicitamente por uma tag de pré-versão, como `@beta`/`@rc`, ou por uma versão de pré-lançamento exata, como `@1.2.3-beta.4`.
Especificações simples e `@latest` permanecem na trilha estável. Versões de correção datadas do OpenClaw, como `2026.5.3-1`, são versões estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw interrompe e pede que você opte explicitamente por uma tag de pré-versão, como `@beta`/`@rc`, ou uma versão de pré-lançamento exata, como `@1.2.3-beta.4`.
Se uma spec simples de instalação corresponder a um id de Plugin oficial (por exemplo, `diffs`), o OpenClaw instala a entrada de catálogo diretamente. Para instalar um pacote npm com o mesmo nome, use uma spec com escopo explícito (por exemplo, `@scope/diffs`).
Se uma especificação simples de instalação corresponder a um id de plugin oficial (por exemplo, `diffs`), o OpenClaw instala diretamente a entrada do catálogo. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícita (por exemplo, `@scope/diffs`).
</Accordion>
<Accordion title="Git repositories">
Use `git:<repo>` para instalar diretamente de um repositório git. Formatos compatíveis incluem `git:github.com/owner/repo`, `git:owner/repo`, URLs completas `https://`, `ssh://`, `git://`, `file://` e URLs de clone `git@host:owner/repo.git`. Adicione `@<ref>` ou `#<ref>` para fazer checkout de um branch, tag ou commit antes da instalação.
<Accordion title="Repositórios Git">
Use `git:<repo>` para instalar diretamente de um repositório git. Formatos compatíveis incluem URLs de clone `git:github.com/owner/repo`, `git:owner/repo`, `https://` completo, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git`. Adicione `@<ref>` ou `#<ref>` para fazer checkout de uma branch, tag ou commit antes da instalação.
Instalações git clonam para um diretório temporário, fazem checkout da ref solicitada quando presente e depois usam o instalador normal de diretório de Plugin. Isso significa que validação de manifesto, verificação de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como em instalações npm. Instalações git registradas incluem a URL/ref de origem e o commit resolvido para que `openclaw plugins update` possa resolver a origem novamente depois.
Instalações git clonam em um diretório temporário, fazem checkout da referência solicitada quando presente e então usam o instalador normal de diretório de plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a origem depois.
Depois de instalar a partir do git, use `openclaw plugins inspect <id> --runtime --json` para verificar registros em runtime, como métodos do Gateway e comandos de CLI. Se o Plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`.
Depois de instalar a partir do git, use `openclaw plugins inspect <id> --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos da CLI. Se o plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Archives">
Arquivos compactados compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos compactados de plugins OpenClaw nativos devem conter um `openclaw.plugin.json` válido na raiz extraída do Plugin; arquivos compactados que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação.
<Accordion title="Arquivos compactados">
Arquivos compactados compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos compactados de plugins nativos do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do plugin; arquivos compactados que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação.
Instalações do marketplace do Claude também são compatíveis.
@ -169,25 +169,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Specs de Plugin seguras para npm e sem prefixo instalam do npm por padrão durante a transição de lançamento:
Especificações simples de plugins seguras para npm instalam a partir do npm por padrão durante a transição de lançamento:
```bash
openclaw plugins install openclaw-codex-app-server
```
Use `npm:` para tornar explícita a resolução somente por npm:
Use `npm:` para explicitar a resolução somente por npm:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
O OpenClaw verifica a API de Plugin anunciada / compatibilidade mínima do Gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado gerado por npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato e então o instala pelo caminho normal de arquivo compactado. Versões mais antigas do ClawHub sem metadados ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo compactado de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest ClawPack para atualizações posteriores.
Instalações não versionadas do ClawHub mantêm uma spec registrada não versionada para que `openclaw plugins update` possa acompanhar lançamentos mais recentes do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados nesse seletor.
O OpenClaw verifica a API de plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo compactado. Versões mais antigas do ClawHub sem metadados ClawPack ainda instalam pelo caminho legado de verificação de arquivo compactado de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações futuras.
Instalações não versionadas do ClawHub mantêm uma especificação registrada sem versão para que `openclaw plugins update` possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados nesse seletor.
#### Abreviação de marketplace
#### Atalho de marketplace
Use a abreviação `plugin@marketplace` quando o nome do marketplace existir no cache de registro local do Claude em `~/.claude/plugins/known_marketplaces.json`:
Use o atalho `plugin@marketplace` quando o nome do marketplace existir no cache de registro local do Claude em `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
@ -204,28 +204,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="Fontes do Marketplace">
<Tab title="Fontes de marketplace">
- um nome de marketplace conhecido do Claude em `~/.claude/plugins/known_marketplaces.json`
- uma raiz de marketplace local ou caminho `marketplace.json`
- um atalho de repositório do GitHub, como `owner/repo`
- uma URL de repositório do GitHub, como `https://github.com/owner/repo`
- uma raiz de marketplace local ou caminho de `marketplace.json`
- uma abreviação de repositório GitHub, como `owner/repo`
- uma URL de repositório GitHub, como `https://github.com/owner/repo`
- uma URL git
</Tab>
<Tab title="Regras de marketplace remoto">
Para marketplaces remotos carregados do GitHub ou git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. O OpenClaw aceita origens de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras origens de Plugin que não sejam caminhos em manifestos remotos.
Para marketplaces remotos carregados do GitHub ou por git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminho absoluto, git, GitHub e outras fontes de Plugin que não sejam caminhos em manifestos remotos.
</Tab>
</Tabs>
Para caminhos locais e arquivos, o OpenClaw detecta automaticamente:
Para caminhos e arquivos locais, OpenClaw detecta automaticamente:
- Plugins nativos do OpenClaw (`openclaw.plugin.json`)
- plugins nativos do OpenClaw (`openclaw.plugin.json`)
- pacotes compatíveis com Codex (`.codex-plugin/plugin.json`)
- pacotes compatíveis com Claude (`.claude-plugin/plugin.json` ou o layout padrão de componentes do Claude)
- pacotes compatíveis com Cursor (`.cursor-plugin/plugin.json`)
<Note>
Pacotes compatíveis são instalados na raiz normal de Plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte para Skills de pacote, Skills de comando do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifesto, Skills de comando do Cursor e diretórios de hooks compatíveis com Codex; outros recursos de pacote detectados aparecem em diagnósticos/informações, mas ainda não estão conectados à execução em runtime.
Pacotes compatíveis são instalados na raiz normal de plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, command-skills do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hooks compatíveis do Codex; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime.
</Note>
### Listar
@ -241,30 +241,30 @@ openclaw plugins search <query> --json
```
<ParamField path="--enabled" type="boolean">
Mostra apenas Plugins habilitados.
Mostra apenas plugins habilitados.
</ParamField>
<ParamField path="--verbose" type="boolean">
Alterna da visualização em tabela para linhas de detalhes por Plugin com metadados de origem/proveniência/versão/ativação.
Alterna da visualização em tabela para linhas de detalhes por Plugin com metadados de fonte/origem/versão/ativação.
</ParamField>
<ParamField path="--json" type="boolean">
Inventário legível por máquina mais diagnósticos do registro e estado de instalação de dependências do pacote.
Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacotes.
</ParamField>
<Note>
`plugins list` lê primeiro o registro local persistido de Plugins, com um fallback derivado apenas do manifesto quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, habilitado e visível para o planejamento de inicialização fria, mas não é uma sondagem de runtime ao vivo de um processo Gateway que já está em execução. Depois de alterar código do Plugin, habilitação, política de hook ou `plugins.load.paths`, reinicie o Gateway que atende ao canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de `openclaw gateway run`, não apenas um processo wrapper.
`plugins list` lê primeiro o registro local persistido de plugins, com um fallback derivado apenas do manifesto quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, habilitado e visível para o planejamento de inicialização fria, mas não é uma sondagem de runtime ao vivo de um processo Gateway já em execução. Depois de alterar código de Plugin, habilitação, política de hook ou `plugins.load.paths`, reinicie o Gateway que atende ao canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho `openclaw gateway run` real, não apenas um processo wrapper.
`plugins list --json` inclui o `dependencyStatus` de cada Plugin a partir de `dependencies` e `optionalDependencies` de `package.json`. O OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de consulta de `node_modules` do Node para o Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.
`plugins list --json` inclui o `dependencyStatus` de cada Plugin a partir de `dependencies` e `optionalDependencies` em `package.json`. OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de busca `node_modules` do Node para o Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.
</Note>
`plugins search` é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não modifica config, não instala pacotes nem carrega código de runtime do Plugin. Os resultados da busca incluem o nome do pacote ClawHub, família, canal, versão, resumo e uma dica de instalação, como `openclaw plugins install clawhub:<package>`.
`plugins search` é uma consulta remota ao catálogo ClawHub. Ela não inspeciona o estado local, não altera configuração, não instala pacotes nem carrega código de runtime de Plugin. Os resultados da busca incluem o nome do pacote ClawHub, família, canal, versão, resumo e uma dica de instalação como `openclaw plugins install clawhub:<package>`.
Para trabalho em Plugin integrado dentro de uma imagem Docker empacotada, monte com bind o diretório de origem do Plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. O OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, para que instalações empacotadas normais ainda usem o dist compilado.
Para trabalho em Plugin incluído dentro de uma imagem Docker empacotada, monte o diretório de origem do Plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, então instalações empacotadas normais ainda usam o dist compilado.
Para depuração de hooks em runtime:
- `openclaw plugins inspect <id> --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com o módulo carregado. A inspeção em runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado de dependências legado ou instalar Plugins baixáveis configurados que estejam ausentes.
- `openclaw gateway status --deep --require-rpc` confirma o Gateway acessível, dicas de serviço/processo, caminho de config e integridade de RPC.
- Hooks de conversa não integrados (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) exigem `plugins.entries.<id>.hooks.allowConversationAccess=true`.
- `openclaw plugins inspect <id> --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção em runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou instalar plugins baixáveis configurados ausentes.
- `openclaw gateway status --deep --require-rpc` confirma o Gateway alcançável, dicas de serviço/processo, caminho de configuração e saúde do RPC.
- Hooks de conversa não incluídos (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) exigem `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Use `--link` para evitar copiar um diretório local (adiciona a `plugins.load.paths`):
@ -273,16 +273,16 @@ openclaw plugins install -l ./my-plugin
```
<Note>
`--force` não é compatível com `--link`, porque instalações vinculadas reutilizam o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.
`--force` não é compatível com `--link` porque instalações vinculadas reutilizam o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.
Use `--pin` em instalações npm para salvar o spec exato resolvido (`name@version`) no índice de Plugins gerenciados, mantendo o comportamento padrão sem pin.
Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de plugins gerenciados, mantendo o comportamento padrão sem fixação.
</Note>
### Índice de Plugins
### Índice de Plugin
Metadados de instalação de Plugins são estado gerenciado por máquina, não config do usuário. Instalações e atualizações os gravam em `plugins/installs.json` dentro do diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável de metadados de instalação, incluindo registros para manifestos de Plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado do manifesto. O arquivo inclui um aviso de não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e pelo registro frio de Plugins.
Metadados de instalação de Plugin são estado gerenciado por máquina, não configuração de usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável de metadados de instalação, incluindo registros de manifestos de Plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado do manifesto. O arquivo inclui um aviso de não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e o registro frio de plugins.
Quando o OpenClaw encontra registros legados enviados em `plugins.installs` na config, ele os move para o índice de Plugins e remove a chave de config; se qualquer gravação falhar, os registros de config são mantidos para que os metadados de instalação não sejam perdidos.
Quando OpenClaw encontra registros legados enviados em `plugins.installs` na configuração, ele os move para o índice de Plugin e remove a chave de configuração; se qualquer gravação falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos.
### Desinstalar
@ -292,10 +292,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` remove registros de Plugin de `plugins.entries`, do índice persistido de Plugins, de entradas de lista de permissão/negação de Plugins e de entradas vinculadas de `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório de instalação gerenciado rastreado quando ele está dentro da raiz de extensões de Plugins do OpenClaw. Para Plugins de memória ativa, o slot de memória é redefinido para `memory-core`.
`uninstall` remove registros de Plugin de `plugins.entries`, do índice persistido de plugins, de entradas de lista de permissão/bloqueio de plugins e de entradas vinculadas em `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório rastreado de instalação gerenciada quando ele está dentro da raiz de extensões de Plugin do OpenClaw. Para plugins de Active Memory, o slot de memória é redefinido para `memory-core`.
<Note>
`--keep-config` é compatível como alias obsoleto para `--keep-files`.
`--keep-config` é compatível como alias obsoleto de `--keep-files`.
</Note>
### Atualizar
@ -308,29 +308,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Atualizações se aplicam a instalações de Plugins rastreadas no índice de Plugins gerenciados e a instalações de hook-packs rastreadas em `hooks.internal.installs`.
Atualizações se aplicam a instalações de Plugin rastreadas no índice gerenciado de plugins e a instalações de hook-pack rastreadas em `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Resolução de id de Plugin vs spec npm">
Quando você passa um id de Plugin, o OpenClaw reutiliza o spec de instalação registrado para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões exatas fixadas continuam a ser usadas em execuções posteriores de `update <id>`.
<Accordion title="Resolvendo id de Plugin vs especificação npm">
Quando você passa um id de Plugin, OpenClaw reutiliza a especificação de instalação registrada para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões fixadas exatas continuam sendo usadas em execuções posteriores de `update <id>`.
Para instalações npm, você também pode passar um spec explícito de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse Plugin instalado e registra o novo spec npm para futuras atualizações baseadas em id.
Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse Plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id.
Passar o nome do pacote npm sem uma versão ou tag também resolve de volta para o registro de Plugin rastreado. Use isso quando um Plugin foi fixado a uma versão exata e você quer movê-lo de volta para a linha de lançamento padrão do registro.
Passar o nome do pacote npm sem versão ou tag também resolve de volta para o registro de Plugin rastreado. Use isso quando um Plugin tiver sido fixado em uma versão exata e você quiser movê-lo de volta para a linha de lançamento padrão do registro.
</Accordion>
<Accordion title="Atualizações do canal beta">
`openclaw plugins update` reutiliza o spec de Plugin rastreado, a menos que você passe um novo spec. `openclaw update` também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e depois fazem fallback para o spec padrão/latest registrado se não existir uma versão beta do Plugin. Versões exatas e tags explícitas permanecem fixadas nesse seletor.
`openclaw plugins update` reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal ativo de atualização do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e depois voltam para a especificação padrão/latest registrada se não existir lançamento beta do Plugin. Versões exatas e tags explícitas permanecem fixadas nesse seletor.
</Accordion>
<Accordion title="Verificações de versão e desvio de integridade">
Antes de uma atualização npm ao vivo, o OpenClaw verifica a versão do pacote instalado contra os metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já corresponderem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`.
Antes de uma atualização npm ao vivo, OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrado já corresponderem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`.
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e pede confirmação antes de prosseguir. Auxiliares de atualização não interativos falham de forma fechada, a menos que o chamador forneça uma política explícita de continuação.
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e pede confirmação antes de prosseguir. Auxiliares de atualização não interativos falham de forma fechada, a menos que o chamador forneça uma política explícita de continuação.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install em update">
`--dangerously-force-unsafe-install` também está disponível em `plugins update` como um override de emergência para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugins. Ele ainda não contorna bloqueios de política `before_install` do Plugin nem bloqueios por falha de varredura, e se aplica apenas a atualizações de Plugins, não a atualizações de hook-packs.
<Accordion title="--dangerously-force-unsafe-install na atualização">
`--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição emergencial para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugin. Ele ainda não contorna bloqueios de política `before_install` de Plugin nem bloqueio por falha de varredura, e se aplica apenas a atualizações de Plugin, não a atualizações de hook-pack.
</Accordion>
</AccordionGroup>
@ -342,21 +342,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect mostra identidade, estado de carregamento, origem, recursos do manifesto, flags de política, diagnósticos, metadados de instalação, recursos de pacote e qualquer suporte detectado a servidores MCP ou LSP sem importar o runtime do Plugin por padrão. Adicione `--runtime` para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção em runtime informa dependências ausentes do Plugin diretamente; instalações e reparos ficam em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
A inspeção mostra identidade, status de carregamento, fonte, recursos do manifesto, flags de política, diagnósticos, metadados de instalação, recursos de pacote e qualquer suporte detectado a servidor MCP ou LSP, sem importar runtime de Plugin por padrão. Adicione `--runtime` para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção em runtime relata diretamente dependências ausentes de Plugin; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
Comandos CLI pertencentes a Plugins são instalados como grupos de comandos raiz de `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw <command> ...`; por exemplo, um Plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`.
Comandos de CLI pertencentes a Plugin são instalados como grupos de comandos raiz de `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw <command> ...`; por exemplo, um Plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`.
Cada Plugin é classificado pelo que ele realmente registra em runtime:
- **plain-capability** — um tipo de recurso (por exemplo, um Plugin somente de provedor)
- **plain-capability** — um tipo de recurso (por exemplo, um Plugin apenas de provedor)
- **hybrid-capability** — vários tipos de recurso (por exemplo, texto + fala + imagens)
- **hook-only** — apenas hooks, sem recursos ou superfícies
- **non-capability** — ferramentas/comandos/serviços, mas sem recursos
Consulte [Formatos de Plugin](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de recursos.
Veja [Formatos de Plugin](/pt-BR/plugins/architecture#plugin-shapes) para mais sobre o modelo de recursos.
<Note>
A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de recurso, avisos de compatibilidade, recursos de pacote e resumo de hooks. `info` é um alias para `inspect`.
A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de recurso, avisos de compatibilidade, recursos de pacote e resumo de hooks. `info` é um alias de `inspect`.
</Note>
### Doctor
@ -365,11 +365,11 @@ A flag `--json` gera um relatório legível por máquina adequado para scripts e
openclaw plugins doctor
```
`doctor` relata erros de carregamento de Plugins, diagnósticos de manifesto/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.`
`doctor` relata erros de carregamento de Plugin, diagnósticos de manifesto/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.`
Se um Plugin configurado está presente no disco, mas bloqueado pelas verificações de segurança de caminho do carregador, a validação de config mantém a entrada do Plugin e a relata como `present but blocked`. Corrija o diagnóstico anterior de Plugin bloqueado, como propriedade do caminho ou permissões graváveis por todos, em vez de remover a config `plugins.entries.<id>` ou `plugins.allow`.
Se um Plugin configurado estiver presente em disco, mas bloqueado pelas verificações de segurança de caminho do carregador, a validação de configuração mantém a entrada do Plugin e a relata como `present but blocked`. Corrija o diagnóstico anterior de Plugin bloqueado, como propriedade do caminho ou permissões graváveis por todos, em vez de remover a configuração `plugins.entries.<id>` ou `plugins.allow`.
Para falhas de formato de módulo, como exports `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato de exports na saída de diagnóstico.
Para falhas de formato de módulo, como exports `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato dos exports na saída de diagnóstico.
### Registro
@ -379,12 +379,12 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
O registro local de Plugins é o modelo de leitura fria persistido do OpenClaw para identidade de Plugins instalados, habilitação, metadados de origem e propriedade de contribuições. A inicialização normal, a consulta de proprietário de provedor, a classificação de configuração de canal e o inventário de Plugins podem lê-lo sem importar módulos de runtime de Plugins.
O registro local de plugins é o modelo de leitura fria persistido do OpenClaw para identidade de Plugin instalado, habilitação, metadados de fonte e propriedade de contribuições. Inicialização normal, busca de proprietário de provedor, classificação de configuração de canal e inventário de Plugin podem lê-lo sem importar módulos de runtime de Plugin.
Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice de plugins persistido, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução.
Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice de Plugin persistido, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma chave de compatibilidade break-glass obsoleta para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback de env é apenas para recuperação emergencial da inicialização enquanto a migração é implementada.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é um interruptor de compatibilidade emergencial obsoleto para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por variável de ambiente é apenas para recuperação emergencial de inicialização enquanto a migração é distribuída.
</Warning>
### Marketplace
@ -394,10 +394,10 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
A listagem do Marketplace aceita um caminho local de marketplace, um caminho `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. `--json` imprime o rótulo da origem resolvida, além do manifesto de marketplace analisado e das entradas de Plugin.
A listagem do Marketplace aceita um caminho de Marketplace local, um caminho de `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. `--json` imprime o rótulo da origem resolvida, além do manifesto do Marketplace analisado e das entradas de Plugin.
## Relacionados
## Relacionado
- [Criando plugins](/pt-BR/plugins/building-plugins)
- [Como criar Plugins](/pt-BR/plugins/building-plugins)
- [Referência da CLI](/pt-BR/cli)
- [Plugins da comunidade](/pt-BR/plugins/community)

47
docs/pt-BR/cli/proxy.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Você precisa validar o roteamento de proxy gerenciado pelo operador antes da implantação
- É necessário capturar o tráfego de transporte do OpenClaw localmente para depuração
- Você quer inspecionar sessões de proxy de depuração, blobs ou predefinições de consulta integradas
summary: Referência da CLI para `openclaw proxy`, incluindo a validação de proxy gerenciado pelo operador e o inspetor de capturas do proxy de depuração local
- Você precisa capturar o tráfego de transporte do OpenClaw localmente para depuração
- Você quer inspecionar sessões do proxy de depuração, blobs ou predefinições de consulta integradas
summary: Referência da CLI para `openclaw proxy`, incluindo validação de proxy gerenciado pelo operador e o inspetor local de captura do proxy de depuração
title: Proxy
x-i18n:
generated_at: "2026-05-01T05:55:18Z"
generated_at: "2026-05-04T05:52:05Z"
model: gpt-5.5
provider: openai
source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
source_path: cli/proxy.md
workflow: 16
---
@ -19,11 +19,11 @@ x-i18n:
Valide o roteamento de proxy gerenciado pelo operador ou execute o proxy de depuração explícito local
e inspecione o tráfego capturado.
Use `validate` para fazer uma verificação prévia de um proxy de encaminhamento gerenciado pelo operador antes de habilitar
Use `validate` para verificar previamente um proxy de encaminhamento gerenciado pelo operador antes de habilitar
o roteamento de proxy do OpenClaw. Os outros comandos são ferramentas de depuração para
investigação em nível de transporte: eles podem iniciar um proxy local, executar um comando filho
investigação no nível de transporte: eles podem iniciar um proxy local, executar um comando filho
com captura habilitada, listar sessões de captura, consultar padrões comuns de tráfego, ler
blobs capturados e limpar dados de captura locais.
blobs capturados e limpar dados locais de captura.
## Comandos
@ -38,27 +38,27 @@ openclaw proxy blob --id <blobId>
openclaw proxy purge
```
## Validar
## Validação
`openclaw proxy validate` verifica a URL efetiva do proxy gerenciado pelo operador a partir de
`--proxy-url`, da configuração ou de `OPENCLAW_PROXY_URL`. Ele relata um problema de configuração quando
nenhum proxy está habilitado e configurado; use `--proxy-url` para uma verificação prévia pontual
antes de alterar a configuração. Por padrão, ele verifica se um destino público tem sucesso
por meio do proxy e se o proxy não consegue acessar um canário temporário de loopback.
Destinos negados personalizados falham fechados: respostas HTTP e falhas de transporte
ambíguas falham, a menos que você consiga verificar separadamente um sinal de negação específico
da implantação.
antes de alterar a configuração. Por padrão, ele verifica se um destino público funciona
por meio do proxy e se o proxy não consegue alcançar um canário de loopback temporário.
Destinos negados personalizados falham fechados: respostas HTTP e falhas ambíguas de
transporte também falham, a menos que você possa verificar separadamente um sinal de negação
específico da implantação.
Opções:
- `--json`: imprime JSON legível por máquina.
- `--proxy-url <url>`: valida esta URL de proxy em vez da configuração ou do env.
- `--allowed-url <url>`: adiciona um destino que deve ter sucesso por meio do proxy. Repita para verificar vários destinos.
- `--denied-url <url>`: adiciona um destino que deve ser bloqueado pelo proxy. Repita para verificar vários destinos.
- `--proxy-url <url>`: valida esta URL de proxy em vez da configuração ou do ambiente.
- `--allowed-url <url>`: adiciona um destino esperado para funcionar por meio do proxy. Repita para verificar vários destinos.
- `--denied-url <url>`: adiciona um destino esperado para ser bloqueado pelo proxy. Repita para verificar vários destinos.
- `--timeout-ms <ms>`: tempo limite por solicitação em milissegundos.
Consulte [Proxy de rede](/pt-BR/security/network-proxy) para orientação de implantação e semântica de
negação.
Consulte [Proxy de rede](/pt-BR/security/network-proxy) para orientações de implantação e semântica
de negação.
## Predefinições de consulta
@ -74,11 +74,12 @@ negação.
## Observações
- `start` usa `127.0.0.1` por padrão, a menos que `--host` seja definido.
- `run` inicia um proxy de depuração local e depois executa o comando após `--`.
- `validate` sai com o código 1 quando a configuração do proxy ou as verificações de destino falham.
- As capturas são dados de depuração locais; use `openclaw proxy purge` quando terminar.
- `run` inicia um proxy de depuração local e então executa o comando após `--`.
- O encaminhamento direto para upstream do proxy de depuração abre sockets upstream para diagnósticos. Quando o modo de proxy gerenciado do OpenClaw está ativo, o encaminhamento direto para solicitações de proxy e túneis CONNECT fica desabilitado por padrão; defina `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` apenas para diagnósticos locais aprovados.
- `validate` sai com código 1 quando a configuração do proxy ou as verificações de destino falham.
- Capturas são dados de depuração locais; use `openclaw proxy purge` quando terminar.
## Relacionado
## Relacionados
- [Referência da CLI](/pt-BR/cli)
- [Proxy de rede](/pt-BR/security/network-proxy)

399
docs/pt-BR/concepts/mantis.md
View File

@ -1,78 +1,58 @@
---
read_when:
- Criar ou executar QA visual ao vivo para bugs do OpenClaw
- Adição de verificação antes e depois para uma solicitação de pull
- Adicionando cenários de transporte em tempo real do Discord, Slack, WhatsApp ou outros
- Depuração de execuções de garantia de qualidade que precisam de capturas de tela, automação de navegador ou acesso VNC
summary: Mantis é o sistema de verificação visual de ponta a ponta para reproduzir bugs do OpenClaw em transportes ativos, capturar evidências antes e depois e anexar artefatos a solicitações de integração.
- Criar ou executar garantia de qualidade visual ao vivo para erros do OpenClaw
- Adicionar verificação antes e depois para uma solicitação de pull
- Como adicionar cenários de transporte em tempo real do Discord, Slack, WhatsApp ou outros
- Depuração de execuções de QA que precisam de capturas de tela, automação de navegador ou acesso VNC
summary: Mantis é o sistema visual de verificação de ponta a ponta para reproduzir bugs do OpenClaw em transportes ao vivo, capturar evidências de antes e depois e anexar artefatos a PRs.
title: Louva-a-deus
x-i18n:
generated_at: "2026-05-04T02:22:55Z"
generated_at: "2026-05-04T05:52:16Z"
model: gpt-5.5
provider: openai
source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d
source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164
source_path: concepts/mantis.md
workflow: 16
---
Mantis é o sistema de verificação ponta a ponta do OpenClaw para erros que precisam de um
ambiente de execução real, um transporte real e prova visível. Ele executa um cenário contra uma ref
sabidamente ruim, captura evidências, executa o mesmo cenário contra uma ref candidata e
publica a comparação como artefatos que um mantenedor pode inspecionar a partir de um PR ou
de um comando local.
Mantis é o sistema de verificação ponta a ponta do OpenClaw para bugs que precisam de um runtime real, um transporte real e prova visível. Ele executa um cenário contra uma ref sabidamente ruim, captura evidências, executa o mesmo cenário contra uma ref candidata e publica a comparação como artefatos que um mantenedor pode inspecionar a partir de um PR ou de um comando local.
Mantis começa com Discord porque Discord nos dá uma primeira linha de alto valor:
autenticação real de bot, canais reais de guilda, reações, threads, comandos nativos e uma
UI de navegador em que humanos podem confirmar visualmente o que o transporte mostrou.
Mantis começa com Discord porque Discord nos dá uma primeira faixa de alto valor: autenticação real de bot, canais reais de guilda, reações, threads, comandos nativos e uma interface de navegador onde humanos podem confirmar visualmente o que o transporte mostrou.
## Objetivos
- Reproduzir um erro de uma issue ou PR do GitHub com o mesmo formato de transporte que os usuários
veem.
- Reproduzir um bug de uma issue ou PR do GitHub com o mesmo formato de transporte que os usuários veem.
- Capturar um artefato **antes** na ref de linha de base antes de aplicar a correção.
- Capturar um artefato **depois** na ref candidata depois de aplicar a correção.
- Usar um oráculo determinístico sempre que possível, como uma leitura de reação via REST do Discord
ou verificação de transcrição do canal.
- Capturar capturas de tela quando o erro tiver uma superfície de UI visível.
- Usar um oráculo determinístico sempre que possível, como uma leitura de reação via REST do Discord ou uma verificação de transcrição do canal.
- Capturar screenshots quando o bug tiver uma superfície de UI visível.
- Executar localmente a partir de uma CLI controlada por agente e remotamente a partir do GitHub.
- Preservar estado de máquina suficiente para resgate via VNC quando login, automação de navegador ou
autenticação de provedor travar.
- Publicar status conciso em um canal Discord de operadores quando a execução estiver bloqueada,
precisar de ajuda manual via VNC ou terminar.
- Preservar estado de máquina suficiente para resgate via VNC quando login, automação de navegador ou autenticação de provedor travar.
- Postar status conciso em um canal Discord de operador quando a execução estiver bloqueada, precisar de ajuda manual via VNC ou terminar.
## Não Objetivos
## Fora do escopo
- Mantis não substitui testes unitários. Uma execução do Mantis normalmente deve virar
um teste de regressão menor depois que a correção for entendida.
- Mantis não é o gate normal de CI rápida. Ele é mais lento, usa credenciais reais e
é reservado para erros em que o ambiente real importa.
- Mantis não deve exigir um humano para operação normal. VNC manual é um caminho de resgate,
não o caminho feliz.
- Mantis não armazena segredos brutos em artefatos, logs, capturas de tela, relatórios Markdown
ou comentários de PR.
- Mantis não substitui testes unitários. Uma execução do Mantis normalmente deve virar um teste de regressão menor depois que a correção for entendida.
- Mantis não é o gate rápido normal de CI. Ele é mais lento, usa credenciais ao vivo e é reservado para bugs em que o ambiente ao vivo importa.
- Mantis não deve exigir um humano para operação normal. VNC manual é um caminho de resgate, não o caminho ideal.
- Mantis não armazena segredos brutos em artefatos, logs, screenshots, relatórios Markdown ou comentários de PR.
## Propriedade
Mantis vive na pilha de QA do OpenClaw.
- OpenClaw é responsável pelo runtime de cenário, adaptadores de transporte, esquema de evidências e
CLI local em `pnpm openclaw qa mantis`.
- QA Lab é responsável pelas partes do harness de transporte real, auxiliares de captura de navegador e
gravadores de artefatos.
- Crabbox é responsável por máquinas Linux aquecidas quando uma VM remota é necessária.
- GitHub Actions é responsável pelo ponto de entrada do workflow remoto e pela retenção de artefatos.
- ClawSweeper é responsável pelo roteamento de comentários do GitHub: analisar comandos de mantenedores,
despachar o workflow e publicar o comentário final no PR.
- Agentes OpenClaw conduzem Mantis por meio do Codex quando um cenário precisa de configuração agentica,
depuração ou relatório de estado travado.
- OpenClaw é dono do runtime de cenários, adaptadores de transporte, esquema de evidências e CLI local sob `pnpm openclaw qa mantis`.
- QA Lab é dono das partes do harness de transporte ao vivo, helpers de captura de navegador e gravadores de artefatos.
- Crabbox é dono das máquinas Linux aquecidas quando uma VM remota é necessária.
- GitHub Actions é dono do ponto de entrada do workflow remoto e da retenção de artefatos.
- ClawSweeper é dono do roteamento de comentários do GitHub: análise de comandos de mantenedor, disparo do workflow e postagem do comentário final no PR.
- Agentes OpenClaw conduzem Mantis por meio do Codex quando um cenário precisa de configuração agêntica, depuração ou relatório de estado travado.
Esse limite mantém o conhecimento de transporte no OpenClaw, o agendamento de máquinas no
Crabbox e a cola do workflow de mantenedores no ClawSweeper.
Esse limite mantém o conhecimento de transporte no OpenClaw, o agendamento de máquinas no Crabbox e a cola do workflow de mantenedores no ClawSweeper.
## Formato Do Comando
## Formato dos comandos
O primeiro comando local verifica o bot Discord, guilda, canal, envio de mensagem,
envio de reação e caminho de artefato:
O primeiro comando local verifica o bot do Discord, guilda, canal, envio de mensagem, envio de reação e caminho de artefatos:
```bash
pnpm openclaw qa mantis discord-smoke \
@ -90,60 +70,71 @@ pnpm openclaw qa mantis run \
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
```
O executor cria worktrees destacadas de linha de base e candidata sob o diretório de saída,
instala dependências, compila cada ref, executa o cenário com
`--allow-failures`, depois escreve `baseline/`, `candidate/`, `comparison.json`,
e `mantis-report.md`. Para o primeiro cenário Discord, uma verificação bem-sucedida
significa que o status da linha de base é `fail` e o status da candidata é `pass`.
O executor cria worktrees destacados de linha de base e candidata sob o diretório de saída, instala dependências, compila cada ref, executa o cenário com `--allow-failures` e então grava `baseline/`, `candidate/`, `comparison.json` e `mantis-report.md`. Para o primeiro cenário de Discord, uma verificação bem-sucedida significa que o status da linha de base é `fail` e o status da candidata é `pass`.
O primeiro primitivo de VM/navegador é o smoke de desktop:
A primeira primitiva de VM/navegador é o smoke de desktop:
```bash
pnpm openclaw qa mantis desktop-browser-smoke \
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
```
Ele aluga ou reutiliza uma máquina desktop Crabbox, inicia um navegador visível dentro da
sessão VNC, captura o desktop, puxa artefatos de volta para o diretório de saída local
e escreve o comando de reconexão no relatório. O comando usa por padrão o provedor
Hetzner porque ele é o primeiro provedor com cobertura funcional de desktop/VNC
na linha Mantis. Sobrescreva com `--provider`, `--crabbox-bin` ou
`OPENCLAW_MANTIS_CRABBOX_PROVIDER` ao executar contra outra frota Crabbox.
Ele aluga ou reutiliza uma máquina desktop Crabbox, inicia um navegador visível dentro da sessão VNC, captura o desktop, traz os artefatos de volta para o diretório de saída local e grava o comando de reconexão no relatório. O comando usa por padrão o provedor Hetzner porque ele é o primeiro provedor com cobertura desktop/VNC funcionando na faixa do Mantis. Substitua-o com `--provider`, `--crabbox-bin` ou `OPENCLAW_MANTIS_CRABBOX_PROVIDER` ao executar contra outra frota Crabbox.
Flags úteis do smoke de desktop:
- `--lease-id <cbx_...>` ou `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` reutiliza um desktop aquecido.
- `--browser-url <url>` altera a página aberta no navegador visível.
- `--html-file <path>` renderiza um artefato HTML local do repo no navegador visível. Mantis usa isso para capturar a linha do tempo gerada de reações de status do Discord por meio de um desktop Crabbox real.
- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` mantém um lease recém-criado e aprovado aberto para inspeção via VNC. Execuções com falha mantêm o lease por padrão quando um foi criado, para que um operador possa se reconectar.
- `--class`, `--idle-timeout` e `--ttl` ajustam o tamanho da máquina e a duração do lease.
- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` mantém aberto um lease recém-criado e aprovado para inspeção via VNC. Execuções com falha mantêm o lease por padrão quando um foi criado para que um operador possa se reconectar.
- `--class`, `--idle-timeout` e `--ttl` ajustam o tamanho da máquina e o tempo de vida do lease.
O workflow de smoke do GitHub é `Mantis Discord Smoke`. O workflow GitHub de antes e depois
para o primeiro cenário real é `Mantis Discord Status Reactions`. Ele aceita:
A primeira primitiva completa de transporte desktop é o smoke de desktop do Slack:
- `baseline_ref`: a ref esperada para reproduzir comportamento somente em fila.
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
--output-dir .artifacts/qa-e2e/mantis/slack-desktop \
--gateway-setup \
--scenario slack-canary \
--keep-lease
```
Ele aluga ou reutiliza uma máquina desktop Crabbox, sincroniza o checkout atual para a VM, executa `pnpm openclaw qa slack` dentro dessa VM, abre Slack Web no navegador VNC, captura o desktop visível e copia tanto os artefatos de QA do Slack quanto a screenshot do VNC de volta para o diretório de saída local. Este é o primeiro formato do Mantis em que o Gateway OpenClaw SUT e o navegador vivem ambos dentro da mesma VM desktop Linux.
Com `--gateway-setup`, o comando prepara uma home OpenClaw descartável persistente em `$HOME/.openclaw-mantis/slack-openclaw`, ajusta a configuração do Slack Socket Mode para o canal selecionado, inicia `openclaw gateway run` na porta `38973` e mantém o Chrome em execução na sessão VNC. Este é o modo "deixe-me um desktop Linux com Slack e um claw em execução"; a faixa de QA Slack bot-para-bot permanece o padrão quando `--gateway-setup` é omitido.
Entradas obrigatórias para `--credential-source env`:
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
- `OPENCLAW_LIVE_OPENAI_KEY` para a faixa de modelo remota. Se apenas `OPENAI_API_KEY` estiver definido localmente, Mantis o mapeia para `OPENCLAW_LIVE_OPENAI_KEY` antes de invocar o Crabbox para que o encaminhamento de env `OPENCLAW_*` do Crabbox possa levá-lo para dentro da VM.
Flags úteis de desktop do Slack:
- `--lease-id <cbx_...>` reexecuta contra uma máquina em que um operador já fez login no Slack Web por VNC.
- `--gateway-setup` inicia um Gateway Slack OpenClaw persistente na VM em vez de apenas executar a faixa de QA bot-para-bot.
- `--slack-url <url>` abre uma URL específica do Slack Web. Sem isso, Mantis deriva `https://app.slack.com/client/<team>/<channel>` a partir de `auth.test` do Slack quando o token do bot SUT está disponível.
- `--slack-channel-id <id>` controla a allowlist de canais Slack usada pela configuração do Gateway.
- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` controla o perfil persistente do Chrome dentro da VM. O padrão é `$HOME/.config/openclaw-mantis/slack-chrome-profile`, então um login manual no Slack Web sobrevive a reexecuções no mesmo lease.
- `--credential-source convex --credential-role ci` usa o pool de credenciais compartilhado em vez de tokens Slack diretos via env.
- `--provider-mode`, `--model`, `--alt-model` e `--fast` são repassados para a faixa ao vivo do Slack.
O workflow smoke do GitHub é `Mantis Discord Smoke`. O workflow GitHub de antes e depois para o primeiro cenário real é `Mantis Discord Status Reactions`. Ele aceita:
- `baseline_ref`: a ref esperada para reproduzir comportamento apenas enfileirado.
- `candidate_ref`: a ref esperada para mostrar `queued -> thinking -> done`.
Ele faz checkout da ref do harness do workflow, compila worktrees separadas de linha de base e candidata,
executa `discord-status-reactions-tool-only` contra cada worktree e
envia `baseline/`, `candidate/`, `comparison.json` e `mantis-report.md` como
artefatos do Actions. Ele também renderiza o HTML de linha do tempo de cada linha em um navegador
desktop Crabbox e publica essas capturas de tela VNC ao lado dos PNGs determinísticos
de linha do tempo no comentário do PR. O workflow compila a CLI Crabbox a partir de
`openclaw/crabbox` main para poder usar as flags atuais de lease de desktop/navegador
antes que a próxima versão binária do Crabbox seja lançada.
Ele faz checkout da ref do harness do workflow, compila worktrees separados de linha de base e candidata, executa `discord-status-reactions-tool-only` contra cada worktree e faz upload de `baseline/`, `candidate/`, `comparison.json` e `mantis-report.md` como artefatos do Actions. Ele também renderiza o HTML da linha do tempo de cada faixa em um navegador desktop Crabbox e publica essas screenshots VNC ao lado dos PNGs determinísticos da linha do tempo no comentário do PR. O workflow compila a CLI do Crabbox a partir de `openclaw/crabbox` main para poder usar as flags atuais de lease desktop/navegador antes do próximo release binário do Crabbox ser cortado.
Você também pode acionar a execução de reações de status diretamente a partir de um comentário de PR:
Você também pode disparar a execução de reações de status diretamente a partir de um comentário no PR:
```text
@Mantis discord status reactions
```
O gatilho de comentário é intencionalmente estreito. Ele só é executado em comentários de pull request
de usuários com acesso de escrita, manutenção ou administração, e só reconhece
solicitações de reações de status do Discord. Por padrão, ele usa a ref de linha de base
sabidamente ruim e o SHA atual do head do PR como candidato. Mantenedores podem sobrescrever qualquer uma das
refs:
O gatilho por comentário é intencionalmente estreito. Ele só executa em comentários de pull request de usuários com acesso write, maintain ou admin, e só reconhece solicitações de reação de status do Discord. Por padrão, ele usa a ref de linha de base sabidamente ruim e o SHA atual do head do PR como candidata. Mantenedores podem substituir qualquer uma das refs:
```text
@Mantis discord status reactions baseline=origin/main candidate=HEAD
@ -156,48 +147,42 @@ Exemplos de comandos do ClawSweeper:
@clawsweeper verify e2e discord
```
O primeiro comando é explícito e focado no cenário. O segundo pode futuramente mapear um PR
ou issue para cenários Mantis recomendados a partir de labels, arquivos alterados e
achados de revisão do ClawSweeper.
O primeiro comando é explícito e focado em cenário. O segundo pode, futuramente, mapear um PR ou issue para cenários Mantis recomendados a partir de labels, arquivos alterados e achados de revisão do ClawSweeper.
## Ciclo De Vida Da Execução
## Ciclo de vida da execução
1. Obter credenciais.
1. Adquirir credenciais.
2. Alocar ou reutilizar uma VM.
3. Preparar o perfil de desktop/navegador quando o cenário precisar de evidência de UI.
4. Preparar um checkout limpo para a ref de linha de base.
5. Instalar dependências e compilar apenas o que o cenário precisa.
6. Iniciar um Gateway OpenClaw filho com um diretório de estado isolado.
7. Configurar o transporte real, provedor, modelo e perfil de navegador.
8. Executar o cenário e capturar evidências da linha de base.
9. Parar o gateway e preservar logs.
7. Configurar o transporte ao vivo, provedor, modelo e perfil de navegador.
8. Executar o cenário e capturar evidência da linha de base.
9. Parar o Gateway e preservar logs.
10. Preparar a ref candidata na mesma VM.
11. Executar o mesmo cenário e capturar evidências da candidata.
12. Comparar os resultados do oráculo e as evidências visuais.
13. Escrever Markdown, JSON, logs, capturas de tela e artefatos opcionais de rastreamento.
14. Enviar artefatos do GitHub Actions.
15. Publicar uma mensagem concisa de status no PR ou no Discord.
11. Executar o mesmo cenário e capturar evidência da candidata.
12. Comparar os resultados do oráculo e a evidência visual.
13. Gravar Markdown, JSON, logs, screenshots e artefatos opcionais de trace.
14. Fazer upload de artefatos do GitHub Actions.
15. Postar uma mensagem concisa de status no PR ou Discord.
O cenário deve poder falhar de duas formas diferentes:
O cenário deve ser capaz de falhar de duas formas diferentes:
- **Erro reproduzido**: a linha de base falhou da forma esperada.
- **Falha do harness**: configuração de ambiente, credenciais, API do Discord, navegador ou
provedor falhou antes que o oráculo do erro fosse significativo.
- **Bug reproduzido**: a linha de base falhou da forma esperada.
- **Falha do harness**: configuração de ambiente, credenciais, API do Discord, navegador ou provedor falhou antes que o oráculo do bug fosse significativo.
O relatório final deve separar esses casos para que mantenedores não confundam um ambiente
instável com comportamento do produto.
O relatório final deve separar esses casos para que mantenedores não confundam um ambiente instável com comportamento do produto.
## MVP Do Discord
## MVP do Discord
O primeiro cenário deve mirar reações de status do Discord em canais de guilda em que
o modo de entrega da resposta de origem é `message_tool_only`.
O primeiro cenário deve mirar reações de status do Discord em canais de guilda onde o modo de entrega de resposta da origem é `message_tool_only`.
Por que ele é uma boa semente para o Mantis:
- Ele é visível no Discord como reações na mensagem disparadora.
- Ele tem um oráculo REST forte por meio do estado de reação da mensagem do Discord.
- Ele exercita um Gateway OpenClaw real, autenticação de bot Discord, despacho de mensagem,
modo de entrega da resposta de origem, estado de reação de status e ciclo de vida de turno do modelo.
- Ele é visível no Discord como reações na mensagem acionadora.
- Ele tem um oráculo REST forte por meio do estado de reações de mensagem do Discord.
- Ele exercita um Gateway OpenClaw real, autenticação de bot Discord, despacho de mensagens, modo de entrega de resposta da origem, estado de reação de status e ciclo de vida de turno do modelo.
- Ele é estreito o suficiente para manter a primeira implementação honesta.
Formato esperado do cenário:
@ -231,12 +216,9 @@ evidence:
screenshotMessageRow: true
```
As evidências da linha de base devem mostrar a reação de confirmação em fila, mas nenhuma
transição de ciclo de vida no modo somente ferramenta. As evidências da candidata devem mostrar reações de status
de ciclo de vida rodando quando `messages.statusReactions.enabled` está explicitamente
true.
A evidência da linha de base deve mostrar a reação de reconhecimento enfileirada, mas nenhuma transição de ciclo de vida no modo apenas ferramentas. A evidência candidata deve mostrar reações de status do ciclo de vida em execução quando `messages.statusReactions.enabled` estiver explicitamente `true`.
A primeira fatia executável é o cenário QA Discord real opt-in:
O primeiro recorte executável é o cenário de QA ao vivo do Discord com opt-in:
```bash
pnpm openclaw qa discord \
@ -248,34 +230,34 @@ pnpm openclaw qa discord \
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
```
Ele configura o SUT com tratamento de guilda sempre ativo, `visibleReplies:
"message_tool"`, `ackReaction: "👀"` e reações de status explícitas. O oráculo
sonda a mensagem disparadora real do Discord e espera a sequência observada
Ele configura o SUT com tratamento de guild sempre ativo, `visibleReplies:
"message_tool"`, `ackReaction: "👀"` e reações de status explícitas. O oracle
consulta a mensagem real de acionamento no Discord e espera a sequência observada
`👀 -> 🤔 -> 👍`. Os artefatos incluem `discord-qa-reaction-timelines.json`,
`discord-status-reactions-tool-only-timeline.html` e
`discord-status-reactions-tool-only-timeline.png`.
## Peças De QA Existentes
## Peças de QA Existentes
Mantis deve se apoiar na pilha privada de QA existente em vez de começar do
O Mantis deve se basear na pilha privada de QA existente em vez de começar do
zero:
- `pnpm openclaw qa discord` já executa uma linha Discord real com bots de driver e
- `pnpm openclaw qa discord` já executa uma faixa live do Discord com bots de driver e
SUT.
- O executor de transporte real já escreve relatórios e artefatos de mensagens observadas
sob `.artifacts/qa-e2e/`.
- Leases de credenciais Convex já fornecem acesso exclusivo a credenciais compartilhadas de
transporte real.
- O serviço de controle de navegador já oferece suporte a capturas de tela, snapshots,
- O runner de transporte live já grava relatórios e artefatos de mensagens
observadas em `.artifacts/qa-e2e/`.
- Os leases de credenciais do Convex já fornecem acesso exclusivo a credenciais
compartilhadas de transporte live.
- O serviço de controle do navegador já oferece suporte a capturas de tela, snapshots,
perfis gerenciados headless e perfis CDP remotos.
- QA Lab já tem uma UI de depuração e barramento para testes no formato de transporte.
- O QA Lab já tem uma UI de depuração e um barramento para testes no formato de transporte.
A primeira implementação do Mantis pode ser um executor fino de antes/depois sobre essas
peças, mais uma camada de evidência visual.
A primeira implementação do Mantis pode ser um runner fino de antes/depois sobre essas
peças, além de uma camada de evidência visual.
## Modelo De Evidências
## Modelo de Evidência
Toda execução escreve um diretório estável de artefatos:
Cada execução grava um diretório estável de artefatos:
```text
.artifacts/qa-e2e/mantis/<run-id>/
@ -296,76 +278,76 @@ Toda execução escreve um diretório estável de artefatos:
```
`mantis-summary.json` deve ser a fonte da verdade legível por máquina. O
relatório Markdown é para comentários de PR e revisão humana.
relatório em Markdown é para comentários em PRs e revisão humana.
O resumo deve incluir:
- refs e SHAs testados
- transporte e id do cenário
- provedor da máquina e id da máquina ou id do lease
- fonte de credencial sem valores secretos
- resultado da linha de base
- resultado da candidata
- se o erro foi reproduzido na linha de base
- se a candidata o corrigiu
- fonte das credenciais sem valores secretos
- resultado da baseline
- resultado do candidate
- se o bug foi reproduzido na baseline
- se o candidate o corrigiu
- caminhos dos artefatos
- problemas sanitizados de configuração ou limpeza
Capturas de tela são evidências, não segredos. Elas ainda precisam de disciplina de redação:
nomes de canais privados, nomes de usuários ou conteúdo de mensagens podem aparecer. Para PRs públicos,
prefira links de artefatos do GitHub Actions em vez de imagens inline até que a história de redação
esteja mais forte.
Capturas de tela são evidências, não segredos. Ainda assim, elas precisam de disciplina
de redação: nomes de canais privados, nomes de usuários ou conteúdo de mensagens podem
aparecer. Para PRs públicos, prefira links de artefatos do GitHub Actions em vez de
imagens inline até que a estratégia de redação esteja mais forte.
## Navegador E VNC
## Navegador e VNC
A linha de navegador tem dois modos:
A faixa do navegador tem dois modos:
- **Automação headless**: padrão para CI. Chrome roda com CDP habilitado, e
Playwright ou o controle de navegador do OpenClaw captura screenshots.
- **Resgate via VNC**: habilitado na mesma VM quando login, MFA, anti-automação do Discord,
ou depuração visual precisa de um humano.
- **Automação headless**: padrão para CI. O Chrome roda com CDP habilitado, e
Playwright ou o controle de navegador do OpenClaw captura capturas de tela.
- **Resgate por VNC**: habilitado na mesma VM quando login, MFA, anti-automação do Discord
ou depuração visual exigem uma pessoa.
O perfil de navegador do observador do Discord deve ser persistente o suficiente para evitar
login a cada execução, mas isolado do estado do navegador pessoal. Um perfil
O perfil do navegador observador do Discord deve ser persistente o suficiente para evitar
login em toda execução, mas isolado do estado pessoal do navegador. Um perfil
pertence ao pool de máquinas do Mantis, não a um laptop de desenvolvedor.
Quando o Mantis fica preso, ele publica uma mensagem de status no Discord com:
Quando o Mantis fica travado, ele publica uma mensagem de status no Discord com:
- id da execução
- id do cenário
- provedor da máquina
- diretório de artefatos
- instruções de conexão VNC ou noVNC, se disponíveis
- texto curto do bloqueio
- texto curto do bloqueador
A primeira implantação privada pode publicar essas mensagens no canal de operadores
existente e migrar para um canal dedicado do Mantis mais tarde.
A primeira implantação privada pode publicar essas mensagens no canal de operadores existente
e migrar para um canal dedicado do Mantis depois.
## Máquinas
O Mantis deve preferir AWS por meio do Crabbox na primeira implementação remota.
O Crabbox nos dá máquinas aquecidas, rastreamento de concessões, hidratação, logs, resultados e
limpeza. Se a capacidade da AWS estiver lenta demais ou indisponível, adicione um provedor Hetzner
por trás da mesma interface de máquina.
O Mantis deve preferir AWS por meio do Crabbox para a primeira implementação remota.
O Crabbox nos dá máquinas aquecidas, rastreamento de leases, hidratação, logs, resultados e
limpeza. Se a capacidade da AWS for lenta demais ou estiver indisponível, adicione um provedor
Hetzner por trás da mesma interface de máquina.
Requisitos mínimos da VM:
- Linux com instalação do Chrome ou Chromium com suporte a desktop
- Linux com instalação do Chrome ou Chromium capaz de desktop
- acesso CDP para automação do navegador
- VNC ou noVNC para resgate
- Node 22 e pnpm
- checkout do OpenClaw e cache de dependências
- cache do navegador Chromium do Playwright quando o Playwright for usado
- cache do navegador Chromium do Playwright quando Playwright for usado
- CPU e memória suficientes para um OpenClaw Gateway, um navegador e uma execução de modelo
- acesso de saída ao Discord, GitHub, provedores de modelo e ao broker de credenciais
A VM não deve manter segredos brutos de longa duração fora dos armazenamentos esperados de credenciais ou
perfil de navegador.
perfil do navegador.
## Segredos
Segredos ficam em segredos de organização ou repositório do GitHub para execuções remotas, e em
um arquivo de segredos local controlado pelo operador para execuções locais.
Segredos ficam em segredos da organização ou do repositório no GitHub para execuções remotas, e em
um arquivo secreto local controlado pelo operador para execuções locais.
Nomes de segredos recomendados:
@ -375,22 +357,22 @@ Nomes de segredos recomendados:
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` para uploads públicos de artefatos no GitHub
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` para uploads públicos de artefatos do GitHub
- `OPENCLAW_QA_CONVEX_SITE_URL`
- `OPENCLAW_QA_CONVEX_SECRET_CI`
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
No longo prazo, o pool de credenciais do Convex deve continuar sendo a fonte normal de credenciais
de transporte ao vivo. Segredos do GitHub inicializam o broker e as pistas de fallback.
O fluxo de trabalho de reações de status do Discord mapeia os segredos do Mantis Crabbox de volta para
No longo prazo, o pool de credenciais do Convex deve continuar sendo a fonte normal para credenciais de
transporte live. Segredos do GitHub inicializam o broker e as faixas de fallback.
O workflow de reações de status do Discord mapeia os segredos Crabbox do Mantis de volta para
as variáveis de ambiente `CRABBOX_COORDINATOR` e `CRABBOX_COORDINATOR_TOKEN`
que a CLI do Crabbox espera. Os nomes simples de segredos do GitHub `CRABBOX_*` continuam
aceitos como fallback de compatibilidade.
O executor do Mantis nunca deve imprimir:
O runner do Mantis nunca deve imprimir:
- tokens de bot do Discord
- tokens de bots do Discord
- chaves de API de provedores
- cookies do navegador
- conteúdo de perfis de autenticação
@ -398,29 +380,28 @@ O executor do Mantis nunca deve imprimir:
- payloads brutos de credenciais
Uploads públicos de artefatos também devem redigir metadados de destino do Discord, como ids de bot,
guild, canal e mensagem. O fluxo de trabalho smoke do GitHub habilita
guild, canal e mensagem. O workflow de smoke do GitHub habilita
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` por esse motivo.
Se um token for colado acidentalmente em uma issue, PR, chat ou log, faça a rotação dele
Se um token for acidentalmente colado em uma issue, PR, chat ou log, faça rotação dele
depois que o novo segredo tiver sido armazenado.
## Artefatos do GitHub e comentários em PRs
## Artefatos do GitHub e Comentários em PRs
Os fluxos de trabalho do Mantis devem fazer upload do pacote completo de evidências como um artefato de Actions
de curta duração. Quando o fluxo de trabalho for executado para um relatório de bug ou PR de correção, ele também deve
publicar as capturas de tela PNG redigidas no branch `qa-artifacts` e atualizar ou inserir um
comentário nesse bug ou PR de correção com capturas de tela antes/depois embutidas. Não publique
a prova principal apenas em um PR genérico de automação de QA. Logs brutos, mensagens observadas
e outras evidências volumosas ficam no artefato de Actions.
Workflows do Mantis devem fazer upload do pacote completo de evidências como um artefato do Actions
de curta duração. Quando o workflow for executado para um relatório de bug ou PR de correção, ele também deve
publicar as capturas de tela PNG redigidas no branch `qa-artifacts` e fazer upsert de um
comentário nesse bug ou PR de correção com capturas de tela inline de antes/depois. Não publique
a prova principal somente em um PR genérico de automação de QA. Logs brutos, mensagens observadas
e outras evidências volumosas ficam no artefato do Actions.
Fluxos de trabalho de produção devem publicar esses comentários com o GitHub App do Mantis, não
com `github-actions[bot]`. Armazene o id do app e a chave privada como segredos
`MANTIS_GITHUB_APP_ID` e `MANTIS_GITHUB_APP_PRIVATE_KEY` do GitHub Actions.
O fluxo de trabalho usa um marcador oculto como chave de atualização/inserção, atualiza esse
comentário quando o token pode editá-lo e cria um novo comentário de propriedade do Mantis quando
um marcador mais antigo de propriedade do bot não pode ser editado.
Workflows de produção devem publicar esses comentários com o GitHub App do Mantis, não
com `github-actions[bot]`. Armazene o id do app e a chave privada como segredos do GitHub Actions
`MANTIS_GITHUB_APP_ID` e `MANTIS_GITHUB_APP_PRIVATE_KEY`. O workflow usa um marcador oculto
como chave de upsert, atualiza esse comentário quando o token consegue editá-lo e cria um novo
comentário de propriedade do Mantis quando um marcador antigo de propriedade de bot não pode ser editado.
O comentário no PR deve ser curto e visual:
O comentário do PR deve ser curto e visual:
```md
Mantis Discord Status Reactions QA
@ -440,73 +421,73 @@ candidate showed the expected queued -> thinking -> done sequence.
| <inline screenshot> | <inline screenshot> |
```
Quando a execução falhar porque o harness falhou, o comentário deve dizer isso em vez
de sugerir que o candidato falhou.
Quando a execução falhar porque o harness falhou, o comentário deve dizer isso em vez de
dar a entender que o candidate falhou.
## Notas de implantação privada
## Notas de Implantação Privada
Uma implantação privada talvez já tenha uma aplicação Discord do Mantis. Reutilize essa
aplicação em vez de criar outro app quando ela tiver as permissões de bot corretas
e puder passar por rotação com segurança.
e puder ter rotação feita com segurança.
Defina o canal inicial de notificação de operadores por meio de segredos ou configuração de implantação.
Ele pode apontar primeiro para um canal existente de mantenedores ou operações
e depois migrar para um canal dedicado do Mantis quando um existir.
Defina o canal inicial de notificações de operadores por meio de segredos ou configuração de implantação.
Ele pode apontar primeiro para um canal existente de mantenedores ou operações, depois migrar para um
canal dedicado do Mantis quando um existir.
Não coloque ids de guild, ids de canal, tokens de bot, cookies de navegador ou senhas de VNC
Não coloque ids de guild, ids de canal, tokens de bot, cookies do navegador ou senhas de VNC
neste documento. Armazene-os em segredos do GitHub, no broker de credenciais ou no
armazenamento local de segredos do operador.
## Adicionando um cenário
## Adicionando um Cenário
Um cenário do Mantis deve declarar:
- id e título
- transporte
- credenciais obrigatórias
- política de ref de baseline
- política de ref de candidato
- credenciais necessárias
- política de ref da baseline
- política de ref do candidate
- patch de configuração do OpenClaw
- etapas de setup
- etapas de configuração
- estímulo
- oráculo esperado de baseline
- oráculo esperado de candidato
- oracle esperado da baseline
- oracle esperado do candidate
- alvos de captura visual
- orçamento de timeout
- etapas de limpeza
Cenários devem preferir oráculos pequenos e tipados:
Cenários devem preferir oracles pequenos e tipados:
- estado de reação do Discord para bugs de reação
- estado de reações do Discord para bugs de reações
- referências de mensagens do Discord para bugs de threading
- ts da thread do Slack e estado da API de reação para bugs do Slack
- ts de thread do Slack e estado da API de reações para bugs do Slack
- ids e cabeçalhos de mensagens de email para bugs de email
- capturas de tela do navegador quando a UI for o único observável confiável
- capturas de tela do navegador quando a UI é o único observável confiável
Verificações por visão devem ser aditivas. Se uma API da plataforma puder provar o bug, use a
API como oráculo de aprovação/falha e mantenha as capturas de tela para confiança humana.
Verificações de visão devem ser aditivas. Se uma API de plataforma puder provar o bug, use a
API como oracle de aprovação/falha e mantenha capturas de tela para confiança humana.
## Expansão de provedores
## Expansão de Provedores
Depois do Discord, o mesmo executor pode adicionar:
Depois do Discord, o mesmo runner pode adicionar:
- Slack: reações, threads, menções ao app, modais, uploads de arquivos.
- Email: autenticação do Gmail e threading de mensagens usando `gog` onde conectores não forem
- Email: autenticação do Gmail e threading de mensagens usando `gog` onde os conectores não forem
suficientes.
- WhatsApp: login por QR, reidentificação, entrega de mensagens, mídia, reações.
- Telegram: bloqueio por menção em grupo, comandos, reações quando disponíveis.
- Telegram: controle de menções em grupo, comandos, reações onde disponíveis.
- Matrix: salas criptografadas, relações de thread ou resposta, retomada após reinício.
Cada transporte deve ter um cenário smoke barato e um ou mais cenários de classe de bug.
Cada transporte deve ter um cenário smoke barato e um ou mais cenários por classe de bug.
Cenários visuais caros devem permanecer opt-in.
## Perguntas em aberto
## Perguntas em Aberto
- Qual bot do Discord deve ser o driver, e qual deve ser o SUT, quando o
- Qual bot do Discord deve ser o driver e qual deve ser o SUT quando o
bot existente do Mantis for reutilizado?
- O login do navegador observador deve usar uma conta humana do Discord, uma conta de teste
ou apenas evidência REST legível por bot para a primeira fase?
ou apenas evidência REST legível por bot na primeira fase?
- Por quanto tempo o GitHub deve reter artefatos do Mantis para PRs?
- Quando o ClawSweeper deve recomendar automaticamente o Mantis em vez de esperar por um
comando de mantenedor?
- As capturas de tela devem ser redigidas ou cortadas antes do upload para PRs públicos?
- As capturas de tela devem ser redigidas ou recortadas antes do upload para PRs públicos?

197
docs/pt-BR/concepts/progress-drafts.md
View File

@ -1,23 +1,27 @@
---
read_when:
- Configurando atualizações de progresso visíveis para turnos de chat de longa duração
- Escolhendo entre os modos de transmissão parcial, em bloco e de progresso
- Configurando atualizações visíveis de progresso para turnos de chat de longa duração
- Escolha entre os modos de streaming parcial, em bloco e de progresso
- Explicando como o OpenClaw atualiza uma mensagem de canal enquanto o trabalho está em andamento
- Solução de problemas de rascunhos de progresso, mensagens de progresso independentes ou mecanismo de contingência de finalização
- Solução de problemas de rascunhos de progresso, mensagens de progresso independentes ou alternativa de finalização
summary: 'Rascunhos de progresso: uma mensagem visível de trabalho em andamento que é atualizada enquanto um agente é executado'
title: Rascunhos de progresso
x-i18n:
generated_at: "2026-05-04T02:23:06Z"
generated_at: "2026-05-04T05:52:06Z"
model: gpt-5.5
provider: openai
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
source_hash: f78c07866cd7f613012a80a40413e5866c1dd2edd477088f9fc141347f5f3788
source_path: concepts/progress-drafts.md
workflow: 16
---
Rascunhos de progresso fazem turnos de agentes de longa duração parecerem ativos no chat sem transformar a conversa em uma pilha de respostas temporárias de status.
Rascunhos de progresso fazem turnos longos de agente parecerem vivos no chat sem transformar
a conversa em uma pilha de respostas temporárias de status.
Quando os rascunhos de progresso estão habilitados, o OpenClaw cria uma única mensagem visível de trabalho em andamento somente depois que o turno comprova que está fazendo trabalho real, atualiza essa mensagem enquanto o agente lê, planeja, chama ferramentas ou aguarda aprovação e, então, transforma esse rascunho na resposta final quando o canal consegue fazer isso com segurança.
Quando rascunhos de progresso estão habilitados, o OpenClaw cria uma mensagem
visível de trabalho em andamento somente depois que o turno prova que está fazendo trabalho real,
atualiza-a enquanto o agente lê, planeja, chama ferramentas ou aguarda aprovação, e então
transforma esse rascunho na resposta final quando o canal pode fazer isso com segurança.
```text
Shelling...
@ -26,7 +30,8 @@ Shelling...
🛠️ Exec: run tests
```
Use rascunhos de progresso quando você quiser uma única mensagem de status organizada durante trabalhos com muitas ferramentas e a resposta final quando o turno terminar.
Use rascunhos de progresso quando quiser uma única mensagem organizada de status durante trabalho
intensivo em ferramentas e a resposta final quando o turno terminar.
## Início Rápido
@ -44,42 +49,58 @@ Habilite rascunhos de progresso por canal com `streaming.mode: "progress"`:
}
```
Isso geralmente é suficiente. O OpenClaw escolherá um rótulo automático de uma palavra, aguardará até que o trabalho dure pelo menos cinco segundos ou emita um segundo evento de trabalho, adicionará linhas compactas de progresso enquanto trabalho útil acontece e suprimirá mensagens independentes duplicadas de progresso nesse turno.
Isso geralmente é suficiente. O OpenClaw escolherá um rótulo automático de uma palavra, aguardará
até que o trabalho dure pelo menos cinco segundos ou emita um segundo evento de trabalho, adicionará
linhas compactas de progresso enquanto trabalho útil acontece e suprimirá conversas de progresso
avulsas duplicadas nesse turno.
## O Que os Usuários Veem
## O Que Os Usuários Veem
Um rascunho de progresso tem duas partes:
| Parte | Finalidade |
| ------------------- | ----------------------------------------------------------------------------- |
| Rótulo | Um título curto, como `Thinking...` ou `Shelling...`. |
| Linhas de progresso | Atualizações compactas de execução usando os mesmos rótulos e ícones da saída detalhada. |
| Parte | Finalidade |
| ------------------- | --------------------------------------------------------------------------------- |
| Rótulo | Um título curto, como `Thinking...` ou `Shelling...`. |
| Linhas de progresso | Atualizações compactas de execução usando os mesmos rótulos e ícones de ferramentas da saída detalhada. |
O rótulo aparece depois que o agente inicia trabalho significativo e continua ocupado por cinco segundos ou emite um segundo evento de trabalho. Respostas somente em texto simples não mostram um rascunho de progresso. Linhas de progresso são adicionadas somente quando o agente emite atualizações úteis de trabalho, por exemplo `🛠️ Exec`, `🔎 Web Search` ou `✍️ Write: to /tmp/file`. Por padrão, elas usam o mesmo modo de explicação compacto de `/verbose`; defina `agents.defaults.toolProgressDetail: "raw"` ao depurar e também quiser comandos/detalhes brutos anexados.
A resposta final substitui o rascunho quando possível; caso contrário, o OpenClaw envia a resposta final normalmente e limpa ou para de atualizar o rascunho de acordo com o transporte do canal.
O rótulo aparece depois que o agente inicia um trabalho significativo e continua ocupado
por cinco segundos ou emite um segundo evento de trabalho. Respostas somente em texto simples não
mostram um rascunho de progresso. Linhas de progresso são adicionadas apenas quando o agente emite
atualizações úteis de trabalho, por exemplo `🛠️ Exec`, `🔎 Web Search` ou `✍️ Write: to /tmp/file`.
Por padrão, elas usam o mesmo modo explicativo compacto de `/verbose`; defina
`agents.defaults.toolProgressDetail: "raw"` ao depurar e também quiser comandos/detalhes brutos
anexados.
A resposta final substitui o rascunho quando possível; caso contrário,
o OpenClaw envia a resposta final normalmente e limpa ou para de atualizar o
rascunho de acordo com o transporte do canal.
## Escolher Um Modo
## Escolha Um Modo
`channels.<channel>.streaming.mode` controla o comportamento visível de andamento:
`channels.<channel>.streaming.mode` controla o comportamento visível em andamento:
| Modo | Melhor para | O que aparece no chat |
| ---------- | ----------------------------------- | --------------------------------------------------- |
| `off` | Canais silenciosos | Somente a resposta final. |
| `partial` | Ver o texto da resposta aparecer | Um rascunho editado com o texto mais recente da resposta. |
| `block` | Trechos maiores de prévia da resposta | Uma prévia atualizada ou anexada em trechos maiores. |
| `progress` | Turnos com muitas ferramentas ou longa duração | Um rascunho de status e, depois, a resposta final. |
| Modo | Melhor para | O que aparece no chat |
| ---------- | -------------------------------- | ---------------------------------------------------- |
| `off` | Canais silenciosos | Apenas a resposta final. |
| `partial` | Ver o texto da resposta aparecer | Um rascunho editado com o texto mais recente da resposta. |
| `block` | Blocos maiores de prévia da resposta | Uma prévia atualizada ou anexada em blocos maiores. |
| `progress` | Turnos intensivos em ferramentas ou de longa duração | Um rascunho de status, depois a resposta final. |
Escolha `progress` quando os usuários se importam mais com "o que está acontecendo" do que com ver o texto da resposta ser transmitido token por token.
Escolha `progress` quando os usuários se importam mais com "o que está acontecendo" do que em ver
o texto da resposta ser transmitido token por token.
Escolha `partial` quando a própria resposta é o sinal de progresso.
Escolha `partial` quando a própria resposta for o sinal de progresso.
Escolha `block` quando você quiser atualizações de prévia em rascunho em trechos maiores de texto. No Discord e no Telegram, `streaming.mode: "block"` ainda é streaming de prévia, não entrega normal em blocos. Use `streaming.block.enabled` ou o legado `blockStreaming` quando quiser respostas normais em bloco.
Escolha `block` quando quiser atualizações de prévia do rascunho em blocos maiores de texto. No
Discord e no Telegram, `streaming.mode: "block"` ainda é streaming de prévia, não
entrega normal em blocos. Use `streaming.block.enabled` ou o legado
`blockStreaming` quando quiser respostas normais em blocos.
## Configurar Rótulos
## Configure Rótulos
Rótulos de progresso ficam em `channels.<channel>.streaming.progress`.
O rótulo padrão é `auto`, que escolhe a partir do conjunto integrado do OpenClaw de rótulos de uma palavra com reticências:
O rótulo padrão é `auto`, que escolhe do conjunto integrado do OpenClaw de
rótulos de uma palavra com reticências:
```text
Thinking...
@ -139,7 +160,7 @@ Use seu próprio conjunto automático de rótulos:
}
```
Oculte o rótulo e mostre somente as linhas de progresso:
Oculte o rótulo e mostre apenas linhas de progresso:
```json5
{
@ -156,9 +177,11 @@ Oculte o rótulo e mostre somente as linhas de progresso:
}
```
## Controlar Linhas de Progresso
## Controle Linhas de Progresso
Linhas de progresso são habilitadas por padrão no modo de progresso. Elas vêm de eventos reais de execução: inícios de ferramentas, atualizações de itens, planos de tarefas, aprovações, saída de comandos, resumos de patches e atividades semelhantes do agente.
Linhas de progresso são habilitadas por padrão no modo de progresso. Elas vêm de eventos reais de
execução: inícios de ferramentas, atualizações de itens, planos de tarefas, aprovações, saída de
comandos, resumos de patches e atividades semelhantes do agente.
O OpenClaw usa o mesmo formatador para rascunhos de progresso e `/verbose`:
@ -172,13 +195,16 @@ O OpenClaw usa o mesmo formatador para rascunhos de progresso e `/verbose`:
}
```
`"explain"` é o padrão e mantém os rascunhos estáveis com rótulos concisos como `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` anexa o comando/detalhe subjacente quando disponível, o que é útil durante a depuração, mas deixa o chat mais ruidoso.
`"explain"` é o padrão e mantém os rascunhos estáveis com rótulos concisos como
`🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` anexa o comando/detalhe
subjacente quando disponível, o que é útil durante a depuração, mas mais ruidoso no
chat.
Por exemplo, o mesmo comando aparece de forma diferente dependendo do modo de detalhe:
| Modo | Linha de progresso |
| --------- | -------------------------------------------------------------------- |
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
| Modo | Linha de progresso |
| --------- | ------------------------------------------------------------------ |
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
Limite quantas linhas permanecem visíveis:
@ -198,6 +224,33 @@ Limite quantas linhas permanecem visíveis:
}
```
Linhas de progresso são compactadas automaticamente para reduzir o refluxo do balão de chat enquanto o rascunho é editado.
O OpenClaw trunca linhas longas de progresso por padrão para que edições repetidas do rascunho não
quebrem linha de forma diferente a cada atualização. O prefixo continua legível, e detalhes longos
como caminhos ou comandos brutos são encurtados com reticências.
O Slack pode renderizar linhas de progresso como campos estruturados do Block Kit em vez de um
único corpo de texto:
```json5
{
channels: {
slack: {
streaming: {
mode: "progress",
progress: {
render: "rich",
},
},
},
},
}
```
A renderização rica mantém o mesmo fallback de texto simples para que canais e clientes que
não dão suporte ao formato mais rico ainda possam mostrar o texto compacto de progresso.
Mantenha o único rascunho de progresso, mas oculte linhas de ferramentas e tarefas:
```json5
@ -215,60 +268,80 @@ Mantenha o único rascunho de progresso, mas oculte linhas de ferramentas e tare
}
```
Com `toolProgress: false`, o OpenClaw ainda suprime as mensagens independentes antigas de progresso de ferramentas nesse turno. O canal permanece visualmente silencioso até a resposta final, exceto pelo rótulo se um estiver configurado.
Com `toolProgress: false`, o OpenClaw ainda suprime as mensagens avulsas mais antigas
de progresso de ferramentas nesse turno. O canal permanece visualmente silencioso até a
resposta final, exceto pelo rótulo se um estiver configurado.
## Comportamento do Canal
## Comportamento Do Canal
Cada canal usa o transporte mais limpo compatível:
Cada canal usa o transporte mais limpo a que dá suporte:
| Canal | Transporte de progresso | Observações |
| --------------- | --------------------------------------- | --------------------------------------------------------------------- |
| Discord | Envia uma mensagem e depois a edita. | O texto final é editado no lugar quando cabe em uma mensagem segura de prévia. |
| Matrix | Envia um evento e depois o edita. | A configuração de streaming em nível de conta controla rascunhos em nível de conta. |
| Microsoft Teams | Stream nativo do Teams em chats pessoais. | `streaming.mode: "block"` mapeia para entrega em bloco do Teams. |
| Slack | Stream nativo ou publicação de rascunho editável. | A disponibilidade de thread afeta se o streaming nativo pode ser usado. |
| Telegram | Envia uma mensagem e depois a edita. | Rascunhos visíveis mais antigos podem ser substituídos para manter carimbos de data/hora finais úteis. |
| Mattermost | Publicação de rascunho editável. | A atividade de ferramentas é integrada à mesma publicação em estilo de rascunho. |
| Canal | Transporte de progresso | Observações |
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
| Discord | Envia uma mensagem e depois a edita. | O texto final é editado no lugar quando cabe em uma mensagem de prévia segura. |
| Matrix | Envia um evento e depois o edita. | A configuração de streaming em nível de conta controla rascunhos em nível de conta. |
| Microsoft Teams | Stream nativo do Teams em chats pessoais. | `streaming.mode: "block"` é mapeado para entrega em blocos do Teams. |
| Slack | Stream nativo ou publicação de rascunho editável. | A disponibilidade de threads afeta se o streaming nativo pode ser usado. |
| Telegram | Envia uma mensagem e depois a edita. | Rascunhos visíveis mais antigos podem ser substituídos para que timestamps finais continuem úteis. |
| Mattermost | Publicação de rascunho editável. | A atividade de ferramentas é incorporada à mesma publicação no estilo de rascunho. |
Canais sem suporte seguro a edição geralmente recorrem a indicadores de digitação ou entrega somente final.
Canais sem suporte seguro a edição geralmente fazem fallback para indicadores de digitação ou
entrega apenas final.
## Finalização
Quando a resposta final está pronta, o OpenClaw tenta manter o chat limpo:
- Se o rascunho puder se tornar a resposta final com segurança, o OpenClaw o edita no lugar.
- Se o canal usa streaming de progresso nativo, o OpenClaw finaliza esse stream quando o transporte nativo aceita o texto final.
- Se a resposta final tiver mídia, um prompt de aprovação, um alvo de resposta explícito, blocos demais ou uma edição/envio com falha, o OpenClaw envia a resposta final pelo caminho normal de entrega do canal.
- Se o canal usa streaming nativo de progresso, o OpenClaw finaliza esse stream
quando o transporte nativo aceita o texto final.
- Se a resposta final tiver mídia, um prompt de aprovação, um destino explícito de resposta,
chunks demais ou uma edição/envio com falha, o OpenClaw envia a resposta final pelo
caminho normal de entrega do canal.
O caminho de fallback é intencional. É melhor enviar uma nova resposta final do que perder texto, encadear uma resposta na thread errada ou sobrescrever um rascunho com um payload que o canal não consegue representar com segurança.
O caminho de fallback é intencional. É melhor enviar uma resposta final nova do que
perder texto, encadear uma resposta incorretamente ou sobrescrever um rascunho com uma carga que o canal
não consegue representar com segurança.
## Solução de Problemas
## Solução De Problemas
**Vejo somente a resposta final.**
**Vejo apenas a resposta final.**
Verifique se `channels.<channel>.streaming.mode` está definido como `progress` para a conta ou o canal que processou a mensagem. Alguns caminhos de grupo ou resposta com citação podem desabilitar prévias de rascunho para um turno quando o canal não consegue editar a mensagem certa com segurança.
Verifique se `channels.<channel>.streaming.mode` está definido como `progress` para a
conta ou canal que tratou a mensagem. Alguns caminhos de grupo ou resposta com citação podem
desabilitar prévias de rascunho em um turno quando o canal não consegue editar com segurança a
mensagem correta.
**Vejo o rótulo, mas nenhuma linha de ferramenta.**
Verifique `streaming.progress.toolProgress`. Se for `false`, o OpenClaw mantém o comportamento de rascunho único, mas oculta linhas de progresso de ferramentas e tarefas.
Verifique `streaming.progress.toolProgress`. Se estiver como `false`, o OpenClaw mantém o
comportamento de rascunho único, mas oculta linhas de progresso de ferramentas e tarefas.
**Vejo uma nova mensagem final em vez de um rascunho editado.**
Isso é um fallback de segurança. Pode acontecer para respostas com mídia, respostas longas, alvos de resposta explícitos, rascunhos antigos do Telegram, alvos de thread ausentes no Slack, mensagens de prévia excluídas ou falha na finalização de stream nativo.
Esse é um fallback de segurança. Isso pode acontecer para respostas com mídia, respostas longas,
destinos explícitos de resposta, rascunhos antigos do Telegram, destinos de thread ausentes no Slack,
mensagens de prévia excluídas ou falha na finalização do stream nativo.
**Ainda vejo mensagens independentes de progresso.**
**Ainda vejo mensagens avulsas de progresso.**
O modo de progresso suprime mensagens padrão independentes de progresso de ferramentas quando um rascunho está ativo. Se mensagens independentes ainda aparecerem, verifique se o turno está realmente usando o modo de progresso e não `streaming.mode: "off"` ou um caminho de canal que não consegue criar um rascunho para essa mensagem.
O modo de progresso suprime mensagens avulsas padrão de progresso de ferramentas quando um rascunho
está ativo. Se mensagens avulsas ainda aparecerem, verifique se o turno está realmente
usando o modo de progresso e não `streaming.mode: "off"` ou um caminho de canal que
não consegue criar um rascunho para essa mensagem.
**O Teams se comporta de forma diferente do Discord ou do Telegram.**
**O Teams se comporta de forma diferente do Discord ou Telegram.**
O Microsoft Teams usa um stream nativo em chats pessoais em vez do transporte genérico de prévia por envio e edição. O Teams também trata `streaming.mode: "block"` como entrega em bloco do Teams porque não tem o mesmo modo de bloco de prévia em rascunho usado pelo Discord e pelo Telegram.
O Microsoft Teams usa um stream nativo em chats pessoais em vez do transporte genérico
de prévia por envio e edição. O Teams também trata `streaming.mode: "block"` como
entrega em blocos do Teams porque não tem o mesmo modo de blocos de prévia de rascunho
usado pelo Discord e Telegram.
## Relacionado
- [Streaming e divisão em blocos](/pt-BR/concepts/streaming)
- [Streaming e chunking](/pt-BR/concepts/streaming)
- [Mensagens](/pt-BR/concepts/messages)
- [Configuração de canais](/pt-BR/gateway/config-channels)
- [Configuração de canal](/pt-BR/gateway/config-channels)
- [Discord](/pt-BR/channels/discord)
- [Matrix](/pt-BR/channels/matrix)
- [Microsoft Teams](/pt-BR/channels/msteams)

415
docs/pt-BR/concepts/qa-e2e-automation.md
View File

@ -1,67 +1,68 @@
---
read_when:
- Compreendendo como a pilha de QA se encaixa
- Estendendo qa-lab, qa-channel ou um adaptador de transporte
- Adicionando cenários de QA baseados em repositório
- Criando automação de QA de maior realismo em torno do painel do Gateway
summary: 'Visão geral da pilha de QA: qa-lab, qa-channel, cenários baseados no repositório, faixas de transporte ao vivo, adaptadores de transporte e relatórios.'
title: Visão geral da garantia de qualidade
- Entendendo como a pilha de QA se encaixa
- Estendendo o qa-lab, o qa-channel ou um adaptador de transporte
- Adicionar cenários de QA baseados no repositório
- Criando automação de QA de maior realismo em torno do dashboard do Gateway
summary: 'Visão geral da pilha de QA: qa-lab, qa-channel, cenários baseados no repositório, faixas de transporte ao vivo, adaptadores de transporte e geração de relatórios.'
title: Visão geral de QA
x-i18n:
generated_at: "2026-05-03T21:30:46Z"
generated_at: "2026-05-04T05:52:10Z"
model: gpt-5.5
provider: openai
source_hash: 6a1446fddb00855634d34662a0a47be1e5054a9e7bfed5bc9ae21185d87094d8
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
A pilha privada de QA serve para exercitar o OpenClaw de uma forma mais realista,
moldada por canal, do que um único teste unitário consegue.
A stack privada de QA foi pensada para exercitar o OpenClaw de uma forma mais realista,
moldada por canais, do que um único teste unitário consegue.
Peças atuais:
Componentes atuais:
- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM,
canal, thread, reação, edição e exclusão.
- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição,
injetar mensagens de entrada e exportar um relatório em Markdown.
- `extensions/qa-matrix`, plugins executores futuros: adaptadores de transporte ao vivo que
conduzem um canal real dentro de um Gateway de QA filho.
- `qa/`: assets iniciais mantidos no repo para a tarefa de kickoff e cenários
baseline de QA.
controlam um canal real dentro de um Gateway de QA filho.
- `qa/`: ativos de semente respaldados pelo repositório para a tarefa inicial e cenários
de QA de linha de base.
- [Mantis](/pt-BR/concepts/mantis): verificação ao vivo antes e depois para bugs que
precisam de transportes reais, capturas de tela do navegador, estado de VM e evidências de PR.
precisam de transportes reais, capturas de tela do navegador, estado da VM e evidências de PR.
## Superfície de comandos
Todo fluxo de QA roda em `pnpm openclaw qa <subcommand>`. Muitos têm aliases de script `pnpm qa:*`;
ambas as formas são suportadas.
Todo fluxo de QA é executado em `pnpm openclaw qa <subcommand>`. Muitos têm aliases de script `pnpm qa:*`;
ambas as formas são compatíveis.
| Comando | Finalidade |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Autoverificação de QA incluída; grava um relatório em Markdown. |
| `qa suite` | Executa cenários mantidos no repo contra a faixa do Gateway de QA. Aliases: `pnpm openclaw qa suite --runner multipass` para uma VM Linux descartável. |
| `qa coverage` | Imprime o inventário de cobertura de cenários em markdown (`--json` para saída de máquina). |
| `qa parity-report` | Compara dois arquivos `qa-suite-summary.json` e grava o relatório de paridade agentic. |
| `qa character-eval` | Executa o cenário de QA de personagem em vários modelos ao vivo com um relatório julgado. Veja [Relatórios](#reporting). |
| `qa manual` | Executa um prompt único contra a faixa do provedor/modelo selecionado. |
| `qa ui` | Inicia a UI de depuração de QA e o barramento local de QA (alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Cria a imagem Docker de QA pré-preparada. |
| `qa docker-scaffold` | Grava um scaffold de docker-compose para o painel de QA + faixa do Gateway. |
| `qa up` | Cria o site de QA, inicia a pilha com Docker e imprime a URL (alias: `pnpm qa:lab:up`; a variante `:fast` adiciona `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Inicia apenas o servidor do provedor AIMock. |
| `qa mock-openai` | Inicia apenas o servidor do provedor `mock-openai` ciente de cenários. |
| `qa credentials doctor` / `add` / `list` / `remove` | Gerencia o pool compartilhado de credenciais do Convex. |
| `qa matrix` | Faixa de transporte ao vivo contra um homeserver Tuwunel descartável. Veja [QA do Matrix](/pt-BR/concepts/qa-matrix). |
| `qa telegram` | Faixa de transporte ao vivo contra um grupo privado real do Telegram. |
| `qa discord` | Faixa de transporte ao vivo contra um canal real de guild privada do Discord. |
| `qa mantis` | Executor de verificação antes e depois para bugs de transporte ao vivo, com o primeiro cenário de reações de status do Discord. Veja [Mantis](/pt-BR/concepts/mantis). |
| Comando | Finalidade |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Autoverificação de QA incluída; grava um relatório em Markdown. |
| `qa suite` | Executa cenários respaldados pelo repositório contra a faixa do Gateway de QA. Aliases: `pnpm openclaw qa suite --runner multipass` para uma VM Linux descartável. |
| `qa coverage` | Imprime o inventário markdown de cobertura de cenários (`--json` para saída de máquina). |
| `qa parity-report` | Compara dois arquivos `qa-suite-summary.json` e grava o relatório de paridade agêntica. |
| `qa character-eval` | Executa o cenário de QA de personagem em vários modelos ao vivo com um relatório julgado. Consulte [Relatórios](#reporting). |
| `qa manual` | Executa um prompt avulso contra a faixa de provedor/modelo selecionada. |
| `qa ui` | Inicia a UI de depuração de QA e o barramento local de QA (alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Compila a imagem Docker pré-preparada de QA. |
| `qa docker-scaffold` | Grava um scaffold docker-compose para o painel de QA + faixa do Gateway. |
| `qa up` | Compila o site de QA, inicia a stack apoiada por Docker e imprime a URL (alias: `pnpm qa:lab:up`; a variante `:fast` adiciona `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Inicia apenas o servidor do provedor AIMock. |
| `qa mock-openai` | Inicia apenas o servidor do provedor `mock-openai` ciente de cenários. |
| `qa credentials doctor` / `add` / `list` / `remove` | Gerencia o pool compartilhado de credenciais do Convex. |
| `qa matrix` | Faixa de transporte ao vivo contra um homeserver Tuwunel descartável. Consulte [QA do Matrix](/pt-BR/concepts/qa-matrix). |
| `qa telegram` | Faixa de transporte ao vivo contra um grupo privado real do Telegram. |
| `qa discord` | Faixa de transporte ao vivo contra um canal real de guild privada do Discord. |
| `qa slack` | Faixa de transporte ao vivo contra um canal privado real do Slack. |
| `qa mantis` | Executor de verificação antes e depois para bugs de transporte ao vivo, com evidências de reações de status no Discord, smoke de desktop/navegador Crabbox e smoke de Slack em VNC. Consulte [Mantis](/pt-BR/concepts/mantis). |
## Fluxo do operador
O fluxo atual do operador de QA é um site de QA em dois painéis:
O fluxo atual do operador de QA é um site de QA com dois painéis:
- Esquerda: painel do Gateway (Control UI) com o agente.
- Direita: QA Lab, mostrando a transcrição parecida com Slack e o plano de cenário.
- Esquerda: painel do Gateway (UI de Controle) com o agente.
- Direita: QA Lab, mostrando a transcrição estilo Slack e o plano do cenário.
Execute com:
@ -69,13 +70,13 @@ Execute com:
pnpm qa:lab:up
```
Isso cria o site de QA, inicia a faixa do Gateway com Docker e expõe a
página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma
missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou
Isso compila o site de QA, inicia a faixa do Gateway apoiada por Docker e expõe a
página do QA Lab onde um operador ou loop de automação pode dar ao agente uma missão
de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou
permaneceu bloqueado.
Para uma iteração mais rápida da UI do QA Lab sem recriar a imagem Docker a cada vez,
inicie a pilha com um bundle do QA Lab montado por bind:
Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker a cada vez,
inicie a stack com um pacote do QA Lab montado por bind:
```bash
pnpm openclaw qa docker-build-image
@ -84,10 +85,10 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-criada e monta por bind
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e monta por bind
`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch`
recria esse bundle quando há alterações, e o navegador recarrega automaticamente quando o hash dos assets do QA Lab
muda.
recompila esse pacote em mudanças, e o navegador recarrega automaticamente quando o hash
do ativo do QA Lab muda.
Para um smoke local de trace do OpenTelemetry, execute:
@ -96,18 +97,18 @@ pnpm qa:otel:smoke
```
Esse script inicia um receptor local de trace OTLP/HTTP, executa o cenário de QA
`otel-trace-smoke` com o plugin `diagnostics-otel` habilitado, depois
decodifica os spans protobuf exportados e valida o formato crítico para release:
`otel-trace-smoke` com o plugin `diagnostics-otel` habilitado, depois decodifica os spans
protobuf exportados e verifica o formato crítico para release:
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
`openclaw.context.assembled` e `openclaw.message.delivery` devem estar presentes;
chamadas de modelo não devem exportar `StreamAbandoned` em turnos bem-sucedidos; IDs diagnósticos brutos e
atributos `openclaw.content.*` devem ficar fora do trace. Ele grava
atributos `openclaw.content.*` devem permanecer fora do trace. Ele grava
`otel-smoke-summary.json` ao lado dos artefatos da suíte de QA.
A QA de observabilidade permanece apenas para checkout do código-fonte. O tarball npm omite intencionalmente
o QA Lab, então as faixas de release Docker de pacote não executam comandos `qa`. Use
`pnpm qa:otel:smoke` a partir de um checkout de código-fonte compilado ao alterar a instrumentação de
diagnósticos.
QA de observabilidade permanece restrito ao checkout do código-fonte. O tarball npm omite intencionalmente
o QA Lab, então as faixas de release Docker do pacote não executam comandos `qa`. Use
`pnpm qa:otel:smoke` a partir de um checkout de código-fonte compilado ao alterar a instrumentação
de diagnósticos.
Para uma faixa de smoke do Matrix com transporte real, execute:
@ -115,16 +116,34 @@ Para uma faixa de smoke do Matrix com transporte real, execute:
pnpm openclaw qa matrix --profile fast --fail-fast
```
A referência completa da CLI, o catálogo de perfis/cenários, as env vars e o layout de artefatos dessa faixa ficam em [QA do Matrix](/pt-BR/concepts/qa-matrix). Em resumo: ela provisiona um homeserver Tuwunel descartável no Docker, registra usuários temporários de driver/SUT/observer, executa o plugin real do Matrix dentro de um Gateway de QA filho escopado para esse transporte (sem `qa-channel`), depois grava um relatório em Markdown, resumo JSON, artefato de eventos observados e log de saída combinado em `.artifacts/qa-e2e/matrix-<timestamp>/`.
A referência completa da CLI, catálogo de perfis/cenários, vars de env e layout de artefatos desta faixa ficam em [QA do Matrix](/pt-BR/concepts/qa-matrix). Em resumo: ela provisiona um homeserver Tuwunel descartável em Docker, registra usuários temporários de driver/SUT/observer, executa o plugin real do Matrix dentro de um Gateway de QA filho escopado para esse transporte (sem `qa-channel`), depois grava um relatório em Markdown, resumo JSON, artefato de eventos observados e log de saída combinado em `.artifacts/qa-e2e/matrix-<timestamp>/`.
Para faixas de smoke do Telegram e Discord com transporte real:
Para faixas de smoke com transporte real de Telegram, Discord e Slack:
```bash
pnpm openclaw qa telegram
pnpm openclaw qa discord
pnpm openclaw qa slack
```
Ambas miram um canal real preexistente com dois bots (driver + SUT). Env vars obrigatórias, listas de cenários, artefatos de saída e o pool de credenciais do Convex estão documentados na [referência de QA do Telegram e Discord](#telegram-and-discord-qa-reference) abaixo.
Elas miram um canal real pré-existente com dois bots (driver + SUT). Vars de env obrigatórias, listas de cenários, artefatos de saída e o pool de credenciais do Convex estão documentados na [referência de QA para Telegram, Discord e Slack](#telegram-discord-and-slack-qa-reference) abaixo.
Para uma execução completa de VM desktop do Slack com resgate por VNC, execute:
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
--gateway-setup \
--scenario slack-canary \
--keep-lease
```
Esse comando aluga uma máquina desktop/navegador Crabbox, executa a faixa ao vivo do Slack
dentro da VM, abre o Slack Web no navegador VNC, captura o desktop e copia
`slack-qa/` mais `slack-desktop-smoke.png` de volta para o diretório de artefatos do Mantis.
Reutilize `--lease-id <cbx_...>` depois de fazer login no Slack Web manualmente
pelo VNC. Com `--gateway-setup`, o Mantis deixa um Gateway Slack persistente do OpenClaw
em execução dentro da VM na porta `38973`; sem isso, o comando executa a
faixa normal de QA Slack bot a bot e sai após a captura de artefatos.
Antes de usar credenciais ao vivo em pool, execute:
@ -132,63 +151,65 @@ Antes de usar credenciais ao vivo em pool, execute:
pnpm openclaw qa credentials doctor
```
O doctor verifica o ambiente do broker Convex, valida configurações de endpoint e verifica a acessibilidade de admin/list quando o segredo de mantenedor está presente. Ele relata apenas o status definido/ausente para segredos.
O doctor verifica o env do broker Convex, valida configurações de endpoint e verifica a acessibilidade de admin/list quando o segredo de mantenedor está presente. Ele relata apenas o status definido/ausente dos segredos.
## Cobertura de transporte ao vivo
As faixas de transporte ao vivo compartilham um contrato em vez de cada uma inventar seu próprio formato de lista de cenários. `qa-channel` é a ampla suíte sintética de comportamento de produto e não faz parte da matriz de cobertura de transporte ao vivo.
As faixas de transporte ao vivo compartilham um contrato em vez de cada uma inventar seu próprio formato de lista de cenários. `qa-channel` é a suíte ampla de comportamento de produto sintético e não faz parte da matriz de cobertura de transporte ao vivo.
| Faixa | Canary | Controle por menção | Bot para bot | Bloqueio de allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento de thread | Isolamento de thread | Observação de reação | Comando de ajuda | Registro de comando nativo |
| -------- | ------ | ------------------- | ------------ | --------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Faixa | Canary | Gating de menção | Bot a bot | Bloqueio por lista de permissões | Resposta de nível superior | Retomada após reinício | Continuação de thread | Isolamento de thread | Observação de reação | Comando de ajuda | Registro de comando nativo |
| -------- | ------ | ---------------- | --------- | -------------------------------- | -------------------------- | ---------------------- | --------------------- | -------------------- | -------------------- | ---------------- | -------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
Isso mantém `qa-channel` como a ampla suíte de comportamento de produto, enquanto Matrix,
Telegram e futuros transportes ao vivo compartilham uma checklist explícita de contrato de transporte.
Isso mantém `qa-channel` como a suíte ampla de comportamento de produto, enquanto Matrix,
Telegram e transportes ao vivo futuros compartilham uma checklist explícita de contrato
de transporte.
Para uma faixa de VM Linux descartável sem trazer o Docker para o caminho de QA, execute:
Para uma faixa de VM Linux descartável sem levar Docker para o caminho de QA, execute:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Isso inicializa um guest Multipass novo, instala dependências, compila o OpenClaw
dentro do guest, executa `qa suite` e depois copia o relatório e o
resumo normais de QA de volta para `.artifacts/qa-e2e/...` no host.
dentro do guest, executa `qa suite` e então copia o relatório de QA normal e o
resumo de volta para `.artifacts/qa-e2e/...` no host.
Ele reutiliza o mesmo comportamento de seleção de cenários que `qa suite` no host.
Execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo
com workers isolados de Gateway por padrão. `qa-channel` usa concorrência padrão
4, limitada pela contagem de cenários selecionados. Use `--concurrency <count>` para ajustar
a contagem de workers, ou `--concurrency 1` para execução serial.
As execuções das suítes no host e no Multipass executam vários cenários selecionados em paralelo
com workers de Gateway isolados por padrão. `qa-channel` usa concorrência
4 por padrão, limitada pela quantidade de cenários selecionados. Use `--concurrency <count>` para ajustar
a quantidade de workers, ou `--concurrency 1` para execução serial.
O comando sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando
quiser artefatos sem um código de saída de falha.
Execuções ao vivo encaminham as entradas de autenticação de QA suportadas que são práticas para o
guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ao vivo de QA e
`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repo para que o guest
possa gravar de volta pelo workspace montado.
você quiser artefatos sem um código de saída com falha.
Execuções live encaminham as entradas de autenticação de QA compatíveis que são práticas para o
guest: chaves de provedores baseadas em env, o caminho da configuração do provedor live de QA e
`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest
possa escrever de volta pelo workspace montado.
## Referência de QA do Telegram e Discord
## Referência de QA do Telegram, Discord e Slack
Matrix tem uma [página dedicada](/pt-BR/concepts/qa-matrix) por causa de sua contagem de cenários e provisionamento de homeserver com Docker. Telegram e Discord são menores — um punhado de cenários cada, sem sistema de perfis, contra canais reais preexistentes — então a referência deles fica aqui.
Matrix tem uma [página dedicada](/pt-BR/concepts/qa-matrix) por causa da sua quantidade de cenários e do provisionamento de homeserver apoiado por Docker. Telegram, Discord e Slack são menores — alguns cenários cada, sem sistema de perfis, contra canais reais preexistentes — então a referência deles fica aqui.
### Flags compartilhadas da CLI
### Flags de CLI compartilhadas
Ambas as faixas são registradas por meio de `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` e aceitam as mesmas flags:
Essas lanes são registradas por meio de `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` e aceitam as mesmas flags:
| Sinalizador | Padrão | Descrição |
| ------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Execute apenas este cenário. Repetível. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord}-<timestamp>` | Onde relatórios/resumo/mensagens observadas e o log de saída são gravados. Caminhos relativos são resolvidos em relação a `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Raiz do repositório ao invocar de um cwd neutro. |
| `--sut-account <id>` | `sut` | ID temporário da conta dentro da configuração do Gateway de QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` legado ainda funciona). |
| `--model <ref>` / `--alt-model <ref>` | padrão do provedor | Refs do modelo primário/alternativo. |
| `--fast` | desativado | Modo rápido do provedor onde houver suporte. |
| `--credential-source <env\|convex>` | `env` | Veja [pool de credenciais do Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` em CI, caso contrário `maintainer` | Papel usado quando `--credential-source convex`. |
| Flag | Padrão | Descrição |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Executa somente este cenário. Repetível. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Onde os relatórios/resumo/mensagens observadas e o log de saída são gravados. Caminhos relativos são resolvidos em relação a `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Raiz do repositório ao invocar a partir de um cwd neutro. |
| `--sut-account <id>` | `sut` | ID temporário da conta dentro da configuração do Gateway de QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` legado ainda funciona). |
| `--model <ref>` / `--alt-model <ref>` | padrão do provedor | Refs do modelo primário/alternativo. |
| `--fast` | desativado | Modo rápido do provedor quando compatível. |
| `--credential-source <env\|convex>` | `env` | Consulte [pool de credenciais Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` em CI, `maintainer` caso contrário | Papel usado quando `--credential-source convex`. |
Ambos saem com código diferente de zero em qualquer cenário com falha. `--allow-failures` grava artefatos sem definir um código de saída com falha.
Cada lane sai com código diferente de zero em qualquer cenário com falha. `--allow-failures` grava artefatos sem definir um código de saída com falha.
### QA do Telegram
@ -196,7 +217,7 @@ Ambos saem com código diferente de zero em qualquer cenário com falha. `--allo
pnpm openclaw qa telegram
```
Tem como alvo um grupo privado real do Telegram com dois bots distintos (driver + SUT). O bot SUT precisa ter um nome de usuário do Telegram; a observação bot a bot funciona melhor quando ambos os bots têm o **Bot-to-Bot Communication Mode** habilitado em `@BotFather`.
Tem como alvo um grupo privado real do Telegram com dois bots distintos (driver + SUT). O bot SUT deve ter um nome de usuário do Telegram; a observação bot-a-bot funciona melhor quando ambos os bots têm **Bot-to-Bot Communication Mode** habilitado no `@BotFather`.
Env obrigatório quando `--credential-source env`:
@ -206,7 +227,7 @@ Env obrigatório quando `--credential-source env`:
Opcional:
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas (o padrão redige).
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas (o padrão é redigir).
Cenários (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
@ -222,7 +243,7 @@ Cenários (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime
Artefatos de saída:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — inclui RTT por resposta (envio do driver → resposta SUT observada) começando pelo canário.
- `telegram-qa-summary.json` — inclui RTT por resposta (envio do driver → resposta SUT observada), começando pelo canary.
- `telegram-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
### QA do Discord
@ -231,7 +252,7 @@ Artefatos de saída:
pnpm openclaw qa discord
```
Tem como alvo um canal de guilda privado real do Discord com dois bots: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Discord incluído. Verifica o tratamento de menções no canal, se o bot SUT registrou o comando nativo `/help` no Discord e cenários opcionais de evidência do Mantis.
Tem como alvo um canal real de guilda privada do Discord com dois bots: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Discord empacotado. Verifica o tratamento de menções de canal, que o bot SUT registrou o comando nativo `/help` com o Discord, e cenários de evidência Mantis opcionais.
Env obrigatório quando `--credential-source env`:
@ -250,9 +271,9 @@ Cenários (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.t
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — cenário opcional do Mantis. Executa sozinho porque alterna o SUT para respostas de guilda sempre ativas e apenas por ferramentas com `messages.statusReactions.enabled=true`; em seguida, captura uma linha do tempo de reações REST mais um artefato visual HTML/PNG.
- `discord-status-reactions-tool-only` — cenário Mantis opcional. Executa sozinho porque muda o SUT para respostas de guilda sempre ativas e somente por ferramenta com `messages.statusReactions.enabled=true`, e então captura uma linha do tempo de reações REST mais um artefato visual HTML/PNG.
Execute o cenário de reações de status do Mantis explicitamente:
Execute explicitamente o cenário de reações de status do Mantis:
```bash
pnpm openclaw qa discord \
@ -268,30 +289,60 @@ Artefatos de saída:
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
- `discord-qa-reaction-timelines.json` e `discord-status-reactions-tool-only-timeline.png` quando o cenário de reações de status é executado.
- `discord-qa-reaction-timelines.json` e `discord-status-reactions-tool-only-timeline.png` quando o cenário de reação de status é executado.
### Pool de credenciais do Convex
### QA do Slack
As lanes do Telegram e do Discord podem alugar credenciais de um pool Convex compartilhado em vez de ler as env vars acima. Passe `--credential-source convex` (ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); o QA Lab adquire uma locação exclusiva, envia Heartbeat para ela durante a execução e a libera no desligamento. Os tipos de pool são `"telegram"` e `"discord"`.
```bash
pnpm openclaw qa slack
```
Tem como alvo um canal privado real do Slack com dois bots distintos: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Slack empacotado.
Env obrigatório quando `--credential-source env`:
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
Opcional:
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas.
Cenários (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`):
- `slack-canary`
- `slack-mention-gating`
Artefatos de saída:
- `slack-qa-report.md`
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
### Pool de credenciais Convex
As lanes do Telegram, Discord e Slack podem alugar credenciais de um pool Convex compartilhado em vez de ler as variáveis de env acima. Passe `--credential-source convex` (ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); o QA Lab adquire uma locação exclusiva, envia heartbeats durante a execução e a libera no desligamento. Os tipos de pool são `"telegram"`, `"discord"` e `"slack"`.
Formatos de payload que o broker valida em `admin/add`:
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` deve ser uma string de chat-id numérica.
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` deve ser uma string de ID numérico de chat.
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
As env vars operacionais e o contrato do endpoint do broker Convex ficam em [Testes → Credenciais compartilhadas do Telegram via Convex](/pt-BR/help/testing#shared-telegram-credentials-via-convex-v1) (o nome da seção é anterior ao suporte ao Discord; a semântica do broker é idêntica para ambos os tipos).
As variáveis de env operacionais e o contrato do endpoint do broker Convex ficam em [Testes → Credenciais compartilhadas do Telegram via Convex](/pt-BR/help/testing#shared-telegram-credentials-via-convex-v1) (o nome da seção é anterior ao suporte ao Discord; a semântica do broker é idêntica para ambos os tipos).
## Seeds baseadas em repositório
## Seeds apoiados pelo repositório
Os ativos de seed ficam em `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
Eles estão intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
Eles ficam intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
agente.
`qa-lab` deve permanecer um runner genérico de markdown. Cada arquivo de cenário em markdown é
`qa-lab` deve continuar sendo um executor genérico de markdown. Cada arquivo markdown de cenário é
a fonte da verdade para uma execução de teste e deve definir:
- metadados do cenário
@ -301,24 +352,24 @@ a fonte da verdade para uma execução de teste e deve definir:
- patch opcional de configuração do Gateway
- o `qa-flow` executável
A superfície reutilizável de runtime que sustenta o `qa-flow` pode permanecer genérica
e transversal. Por exemplo, cenários em markdown podem combinar helpers do lado do transporte
com helpers do lado do navegador que controlam a Control UI incorporada por meio do
seam `browser.request` do Gateway sem adicionar um runner de caso especial.
A superfície de runtime reutilizável que sustenta `qa-flow` pode continuar genérica
e transversal. Por exemplo, cenários markdown podem combinar auxiliares do lado do transporte
com auxiliares do lado do navegador que conduzem a Control UI incorporada por meio da
seam `browser.request` do Gateway sem adicionar um runner especial.
Os arquivos de cenário devem ser agrupados por capacidade do produto, não por pasta da árvore
de código-fonte. Mantenha os IDs dos cenários estáveis quando arquivos forem movidos; use `docsRefs` e `codeRefs`
Os arquivos de cenário devem ser agrupados por capacidade de produto, em vez de pasta
da árvore de código-fonte. Mantenha os IDs de cenário estáveis quando arquivos forem movidos; use `docsRefs` e `codeRefs`
para rastreabilidade da implementação.
A lista de baseline deve permanecer ampla o bastante para cobrir:
A lista de base deve permanecer ampla o suficiente para cobrir:
- DM e chat de canal
- comportamento de thread
- ciclo de vida de ação de mensagem
- callbacks Cron
- recuperação de memória
- chat por DM e canal
- comportamento de threads
- ciclo de vida de ações de mensagem
- callbacks de cron
- recall de memória
- troca de modelo
- handoff de subagente
- handoff para subagente
- leitura de repositório e leitura de docs
- uma pequena tarefa de build, como Lobster Invaders
@ -326,78 +377,78 @@ A lista de baseline deve permanecer ampla o bastante para cobrir:
`qa suite` tem duas lanes locais de mock de provedor:
- `mock-openai` é o mock do OpenClaw consciente de cenários. Ele permanece como a lane de mock
determinística padrão para QA baseada em repositório e gates de paridade.
- `aimock` inicia um servidor de provedor baseado em AIMock para cobertura experimental de protocolo,
fixture, gravação/replay e caos. Ele é aditivo e não
- `mock-openai` é o mock do OpenClaw ciente de cenários. Ele continua sendo a lane de mock determinística
padrão para QA apoiado pelo repositório e gates de paridade.
- `aimock` inicia um servidor de provedor apoiado pelo AIMock para cobertura experimental de protocolo,
fixture, gravação/reprodução e caos. Ele é aditivo e não
substitui o dispatcher de cenários `mock-openai`.
A implementação de lanes de provedor fica em `extensions/qa-lab/src/providers/`.
Cada provedor possui seus padrões, inicialização de servidor local, configuração de modelo do Gateway,
necessidades de staging de perfil de autenticação e flags de capacidade live/mock. O código compartilhado de suíte e
Gateway deve rotear pelo registro de provedores em vez de fazer branching por
necessidades de preparação de perfil de autenticação e flags de capacidade live/mock. O código compartilhado da suíte e do
Gateway deve rotear pelo registro de provedores em vez de ramificar por
nomes de provedores.
## Adaptadores de transporte
`qa-lab` possui um seam genérico de transporte para cenários de QA em markdown. `qa-channel` é o primeiro adaptador nesse seam, mas o alvo de design é mais amplo: canais reais ou sintéticos futuros devem se conectar ao mesmo runner de suíte em vez de adicionar um runner de QA específico de transporte.
`qa-lab` possui uma seam de transporte genérica para cenários de QA em markdown. `qa-channel` é o primeiro adaptador nessa seam, mas o alvo de design é mais amplo: canais reais ou sintéticos futuros devem se conectar ao mesmo runner de suíte em vez de adicionar um runner de QA específico para transporte.
No nível de arquitetura, a divisão é:
- `qa-lab` possui execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios.
- O adaptador de transporte possui configuração do Gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado.
- Arquivos de cenário em markdown sob `qa/scenarios/` definem a execução do teste; `qa-lab` fornece a superfície reutilizável de runtime que os executa.
- Arquivos de cenário markdown em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa.
### Adicionando um canal
Adicionar um canal ao sistema de QA em markdown requer exatamente duas coisas:
Adicionar um canal ao sistema de QA em markdown exige exatamente duas coisas:
1. Um adaptador de transporte para o canal.
2. Um pacote de cenários que exercita o contrato do canal.
2. Um pacote de cenários que exercite o contrato do canal.
Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder possuir o fluxo.
Não adicione uma nova raiz de comando de QA de nível superior quando o host `qa-lab` compartilhado puder ser dono do fluxo.
`qa-lab` possui a mecânica do host compartilhado:
`qa-lab` é responsável pela mecânica compartilhada do host:
- a raiz de comando `openclaw qa`
- inicialização e teardown da suíte
- a raiz do comando `openclaw qa`
- inicialização e encerramento da suíte
- concorrência de workers
- gravação de artefatos
- geração de relatório
- geração de relatórios
- execução de cenários
- aliases de compatibilidade para cenários `qa-channel` antigos
- aliases de compatibilidade para cenários `qa-channel` mais antigos
Plugins de runner possuem o contrato de transporte:
Os plugins executores são responsáveis pelo contrato de transporte:
- como `openclaw qa <runner>` é montado sob a raiz compartilhada `qa`
- como o Gateway é configurado para esse transporte
- como `openclaw qa <runner>` é montado abaixo da raiz `qa` compartilhada
- como o gateway é configurado para esse transporte
- como a prontidão é verificada
- como eventos de entrada são injetados
- como mensagens de saída são observadas
- como transcripts e estado de transporte normalizado são expostos
- como ações baseadas em transporte são executadas
- como reset ou limpeza específica do transporte é tratado
- como transcrições e o estado normalizado do transporte são expostos
- como ações respaldadas pelo transporte são executadas
- como redefinições ou limpezas específicas do transporte são tratadas
A barra mínima de adoção para um novo canal:
O nível mínimo de adoção para um novo canal:
1. Mantenha `qa-lab` como proprietário da raiz compartilhada `qa`.
2. Implemente o runner de transporte no seam do host compartilhado `qa-lab`.
3. Mantenha mecânicas específicas do transporte dentro do Plugin de runner ou harness do canal.
4. Monte o runner como `openclaw qa <runner>` em vez de registrar um comando raiz concorrente. Plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. Mantenha `runtime-api.ts` leve; CLI lazy e execução de runner devem ficar atrás de entrypoints separados.
5. Crie ou adapte cenários em markdown nos diretórios temáticos `qa/scenarios/`.
6. Use os helpers genéricos de cenário para novos cenários.
7. Mantenha aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional.
1. Mantenha `qa-lab` como responsável pela raiz `qa` compartilhada.
2. Implemente o executor de transporte na interface compartilhada de host do `qa-lab`.
3. Mantenha a mecânica específica de transporte dentro do plugin executor ou do harness de canal.
4. Monte o executor como `openclaw qa <runner>` em vez de registrar um comando raiz concorrente. Plugins executores devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. Mantenha `runtime-api.ts` leve; a CLI preguiçosa e a execução do executor devem ficar atrás de pontos de entrada separados.
5. Crie ou adapte cenários Markdown nos diretórios temáticos `qa/scenarios/`.
6. Use os auxiliares genéricos de cenário para novos cenários.
7. Mantenha os aliases de compatibilidade existentes funcionando, a menos que o repo esteja fazendo uma migração intencional.
A regra de decisão é estrita:
- Se o comportamento puder ser expresso uma vez em `qa-lab`, coloque-o em `qa-lab`.
- Se o comportamento depender de um transporte de canal, mantenha-o nesse Plugin de runner ou harness de Plugin.
- Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de um branch específico de canal em `suite.ts`.
- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico do transporte e explicite isso no contrato do cenário.
- Se o comportamento depender de um transporte de canal, mantenha-o nesse plugin executor ou harness de plugin.
- Se um cenário precisar de um novo recurso que mais de um canal possa usar, adicione um auxiliar genérico em vez de uma ramificação específica de canal em `suite.ts`.
- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico de transporte e deixe isso explícito no contrato do cenário.
### Nomes de helpers de cenário
### Nomes dos auxiliares de cenário
Helpers genéricos preferidos para novos cenários:
Auxiliares genéricos preferidos para novos cenários:
- `waitForTransportReady`
- `waitForChannelReady`
@ -412,11 +463,11 @@ Helpers genéricos preferidos para novos cenários:
- `formatTransportTranscript`
- `resetTransport`
Aliases de compatibilidade continuam disponíveis para cenários existentes — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mas a criação de novos cenários deve usar os nomes genéricos. Os aliases existem para evitar uma migração de uma só vez, não como o modelo daqui em diante.
Aliases de compatibilidade continuam disponíveis para cenários existentes — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mas a criação de novos cenários deve usar os nomes genéricos. Os aliases existem para evitar uma migração completa de uma só vez, não como o modelo daqui em diante.
## Relatórios
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada do bus.
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada do barramento.
O relatório deve responder:
- O que funcionou
@ -424,10 +475,10 @@ O relatório deve responder:
- O que permaneceu bloqueado
- Quais cenários de acompanhamento valem a pena adicionar
Para o inventário dos cenários disponíveis — útil ao dimensionar trabalho de acompanhamento ou conectar um novo transporte — execute `pnpm openclaw qa coverage` (adicione `--json` para saída legível por máquina).
Para o inventário de cenários disponíveis — útil ao dimensionar trabalho de acompanhamento ou conectar um novo transporte — execute `pnpm openclaw qa coverage` (adicione `--json` para saída legível por máquina).
Para verificações de personagem e estilo, execute o mesmo cenário em vários refs de modelos
ao vivo e escreva um relatório julgado em Markdown:
Para verificações de personagem e estilo, execute o mesmo cenário em várias refs de modelos ao vivo
e grave um relatório julgado em Markdown:
```bash
pnpm openclaw qa character-eval \
@ -446,31 +497,31 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
O comando executa processos filhos do Gateway de QA local, não Docker. Cenários de avaliação de personagem
devem definir a persona por meio de `SOUL.md` e então executar turnos comuns de usuário,
como chat, ajuda no workspace e pequenas tarefas de arquivo. O modelo candidato não deve
ser informado de que está sendo avaliado. O comando preserva cada transcrição completa,
registra estatísticas básicas da execução e então pede aos modelos juízes, em modo rápido com
raciocínio `xhigh` quando houver suporte, que classifiquem as execuções por naturalidade, tom e humor.
O comando executa processos filhos locais do Gateway de QA, não Docker. Cenários de avaliação de personagem
devem definir a persona por meio de `SOUL.md` e depois executar turnos comuns de usuário,
como chat, ajuda no workspace e pequenas tarefas de arquivo. O modelo candidato
não deve ser informado de que está sendo avaliado. O comando preserva cada
transcrição completa, registra estatísticas básicas de execução e depois pede aos modelos juízes em modo rápido com
raciocínio `xhigh`, quando houver suporte, para classificar as execuções por naturalidade, vibe e humor.
Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe
cada transcrição e status de execução, mas refs candidatos são substituídos por
rótulos neutros como `candidate-01`; o relatório mapeia as classificações de volta aos refs reais após
o parsing.
As execuções candidatas usam `high` thinking por padrão, com `medium` para GPT-5.5 e `xhigh`
para refs de avaliação mais antigos da OpenAI que têm suporte. Sobrescreva um candidato específico inline com
todas as transcrições e estados de execução, mas as refs candidatas são substituídas por
rótulos neutros como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após
a análise.
Execuções candidatas usam `high` thinking por padrão, com `medium` para GPT-5.5 e `xhigh`
para refs de avaliação OpenAI mais antigas que oferecem suporte. Substitua um candidato específico em linha com
`--model provider/model,thinking=<level>`. `--thinking <level>` ainda define um
fallback global, e a forma antiga `--model-thinking <provider/model=level>` é
fallback global, e a forma mais antiga `--model-thinking <provider/model=level>` é
mantida para compatibilidade.
Refs candidatos da OpenAI usam modo rápido por padrão para que o processamento prioritário seja usado quando
o provedor tiver suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um
único candidato ou juiz precisar de uma sobrescrita. Passe `--fast` somente quando quiser
Refs candidatas OpenAI usam modo rápido por padrão para que o processamento prioritário seja usado onde
o provedor oferece suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` em linha quando um
único candidato ou juiz precisar de uma substituição. Passe `--fast` somente quando quiser
forçar o modo rápido para todos os modelos candidatos. As durações de candidatos e juízes são
registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente
para não classificar por velocidade.
As execuções de modelos candidatos e juízes usam concorrência 16 por padrão. Reduza
`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no Gateway
local tornarem uma execução ruidosa demais.
Quando nenhum `--model` candidato é passado, a avaliação de personagem usa por padrão
Execuções dos modelos candidatos e juízes usam concorrência 16 por padrão. Reduza
`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão local do Gateway
tornarem uma execução ruidosa demais.
Quando nenhum candidato `--model` é passado, a avaliação de personagem usa por padrão
`openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
`moonshot/kimi-k2.5` e
@ -481,7 +532,7 @@ Quando nenhum `--judge-model` é passado, os juízes usam por padrão
## Documentos relacionados
- [Matriz de QA](/pt-BR/concepts/qa-matrix)
- [QA de matriz](/pt-BR/concepts/qa-matrix)
- [Canal de QA](/pt-BR/channels/qa-channel)
- [Testes](/pt-BR/help/testing)
- [Painel](/pt-BR/web/dashboard)
- [Dashboard](/pt-BR/web/dashboard)

441
docs/pt-BR/gateway/config-agents.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Ajustando os padrões do agente (modelos, raciocínio, área de trabalho, Heartbeat, mídia, Skills)
- Configurando o roteamento e as vinculações multiagente
- Ajustando o comportamento de sessão, entrega de mensagens e modo de fala
summary: Padrões de agente, roteamento multiagente, sessão, mensagens e configuração de conversa
- Ajustando as configurações padrão do agente (modelos, raciocínio, área de trabalho, Heartbeat, mídia, Skills)
- Configurando roteamento multiagente e vinculações
- Ajustando o comportamento da sessão, da entrega de mensagens e do modo de conversa
summary: Valores padrão do agente, roteamento multiagente, sessão, mensagens e configuração de talk
title: Configuração — agentes
x-i18n:
generated_at: "2026-05-03T05:48:39Z"
generated_at: "2026-05-04T05:52:08Z"
model: gpt-5.5
provider: openai
source_hash: b25371c34b9f8b0cacce021879e43e6a65b86d626dc87d5bfa05dcae80ac32e4
source_hash: 9d339b82b8b3b82e55820ca6568b3ed569fe64135e698515fa7f316c3afbbfd9
source_path: gateway/config-agents.md
workflow: 16
---
Chaves de configuração com escopo de agente em `agents.*`, `multiAgent.*`, `session.*`,
`messages.*` e `talk.*`. Para canais, ferramentas, runtime do Gateway e outras
chaves de nível superior, consulte a [referência de configuração](/pt-BR/gateway/configuration-reference).
chaves de nível superior, consulte a [Referência de configuração](/pt-BR/gateway/configuration-reference).
## Padrões dos agentes
## Padrões de agente
### `agents.defaults.workspace`
@ -32,7 +32,7 @@ Padrão: `~/.openclaw/workspace`.
### `agents.defaults.repoRoot`
Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se não for definida, o OpenClaw detecta automaticamente percorrendo os diretórios acima a partir do workspace.
Raiz de repositório opcional exibida na linha Runtime do prompt do sistema. Se não definida, o OpenClaw detecta automaticamente percorrendo para cima a partir do workspace.
```json5
{
@ -42,7 +42,7 @@ Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se
### `agents.defaults.skills`
Lista de permissão padrão opcional de Skills para agentes que não definem
Allowlist padrão opcional de Skills para agentes que não definem
`agents.list[].skills`.
```json5
@ -60,13 +60,13 @@ Lista de permissão padrão opcional de Skills para agentes que não definem
- Omita `agents.defaults.skills` para Skills irrestritas por padrão.
- Omita `agents.list[].skills` para herdar os padrões.
- Defina `agents.list[].skills: []` para nenhuma Skills.
- Uma lista `agents.list[].skills` não vazia é o conjunto final para esse agente; ela
- Defina `agents.list[].skills: []` para nenhuma Skill.
- Uma lista `agents.list[].skills` não vazia é o conjunto final desse agente; ela
não é mesclada com os padrões.
### `agents.defaults.skipBootstrap`
Desativa a criação automática dos arquivos de bootstrap do workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
Desativa a criação automática de arquivos de bootstrap do workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@ -76,7 +76,7 @@ Desativa a criação automática dos arquivos de bootstrap do workspace (`AGENTS
### `agents.defaults.skipOptionalBootstrapFiles`
Ignora a criação de arquivos opcionais selecionados do workspace enquanto ainda grava os arquivos de bootstrap obrigatórios. Valores válidos: `SOUL.md`, `USER.md`, `HEARTBEAT.md` e `IDENTITY.md`.
Ignora a criação de arquivos opcionais selecionados do workspace, enquanto ainda grava os arquivos de bootstrap obrigatórios. Valores válidos: `SOUL.md`, `USER.md`, `HEARTBEAT.md` e `IDENTITY.md`.
```json5
{
@ -92,8 +92,8 @@ Ignora a criação de arquivos opcionais selecionados do workspace enquanto aind
Controla quando os arquivos de bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`.
- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas pós-Compaction ainda reconstroem o contexto.
- `"never"`: desativa o bootstrap do workspace e a injeção de arquivos de contexto em todos os turnos. Use isto apenas para agentes que controlam totalmente seu ciclo de vida de prompt (mecanismos de contexto personalizados, runtimes nativos que constroem seu próprio contexto ou workflows especializados sem bootstrap). Turnos de Heartbeat e de recuperação de Compaction também pulam a injeção.
- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) ignoram a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas pós-Compaction ainda reconstroem o contexto.
- `"never"`: desativa o bootstrap do workspace e a injeção de arquivos de contexto em todos os turnos. Use isto apenas para agentes que controlam totalmente o ciclo de vida do próprio prompt (mecanismos de contexto personalizados, runtimes nativos que constroem o próprio contexto ou fluxos especializados sem bootstrap). Turnos de Heartbeat e de recuperação de Compaction também ignoram a injeção.
```json5
{
@ -123,12 +123,16 @@ Máximo total de caracteres injetados em todos os arquivos de bootstrap do works
### `agents.defaults.bootstrapPromptTruncationWarning`
Controla o texto de aviso visível para o agente quando o contexto de bootstrap é truncado.
Controla o aviso no prompt do sistema visível para o agente quando o contexto de bootstrap é truncado.
Padrão: `"once"`.
- `"off"`: nunca injeta texto de aviso no prompt do sistema.
- `"once"`: injeta o aviso uma vez por assinatura de truncamento exclusiva (recomendado).
- `"always"`: injeta o aviso em toda execução quando houver truncamento.
- `"off"`: nunca injeta texto de aviso de truncamento no prompt do sistema.
- `"once"`: injeta um aviso conciso uma vez por assinatura de truncamento única (recomendado).
- `"always"`: injeta um aviso conciso em todas as execuções quando há truncamento.
Contagens brutas/injetadas detalhadas e campos de ajuste de configuração permanecem em diagnósticos como
relatórios de contexto/status e logs; o contexto rotineiro de usuário/runtime do WebChat recebe apenas
o aviso conciso de recuperação.
```json5
{
@ -139,34 +143,33 @@ Padrão: `"once"`.
### Mapa de propriedade do orçamento de contexto
O OpenClaw tem vários orçamentos de prompt/contexto de alto volume, e eles são
intencionalmente divididos por subsistema em vez de passarem todos por uma única
opção genérica.
intencionalmente separados por subsistema em vez de passarem todos por um único
controle genérico.
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`:
injeção normal de bootstrap do workspace.
- `agents.defaults.startupContext.*`:
preâmbulo de execução do modelo em redefinição/inicialização de uso único, incluindo arquivos
`memory/*.md` diários recentes. Os comandos de chat simples `/new` e `/reset` são
prelúdio de execução única do modelo em redefinição/inicialização, incluindo arquivos recentes diários
`memory/*.md`. Comandos de chat simples `/new` e `/reset` são
confirmados sem invocar o modelo.
- `skills.limits.*`:
a lista compacta de Skills injetada no prompt do sistema.
- `agents.defaults.contextLimits.*`:
trechos de runtime limitados e blocos injetados pertencentes ao runtime.
trechos limitados de runtime e blocos injetados pertencentes ao runtime.
- `memory.qmd.limits.*`:
dimensionamento de trecho de busca de memória indexada e de injeção.
trecho de pesquisa de memória indexada e dimensionamento de injeção.
Use a substituição por agente correspondente apenas quando um agente precisar de um
orçamento diferente:
Use a substituição correspondente por agente apenas quando um agente precisar de um orçamento diferente:
- `agents.list[].skillsLimits.maxSkillsPromptChars`
- `agents.list[].contextLimits.*`
#### `agents.defaults.startupContext`
Controla o preâmbulo de inicialização do primeiro turno injetado em execuções do modelo de redefinição/inicialização.
Controla o prelúdio de inicialização do primeiro turno injetado em execuções do modelo de redefinição/inicialização.
Comandos de chat simples `/new` e `/reset` confirmam a redefinição sem invocar
o modelo, portanto não carregam este preâmbulo.
o modelo, portanto não carregam este prelúdio.
```json5
{
@ -187,7 +190,7 @@ o modelo, portanto não carregam este preâmbulo.
#### `agents.defaults.contextLimits`
Padrões compartilhados para superfícies de contexto de runtime limitadas.
Padrões compartilhados para superfícies limitadas de contexto de runtime.
```json5
{
@ -204,18 +207,18 @@ Padrões compartilhados para superfícies de contexto de runtime limitadas.
}
```
- `memoryGetMaxChars`: limite padrão de trecho de `memory_get` antes que metadados
de truncamento e aviso de continuação sejam adicionados.
- `memoryGetMaxChars`: limite padrão do trecho de `memory_get` antes que
metadados de truncamento e aviso de continuação sejam adicionados.
- `memoryGetDefaultLines`: janela de linhas padrão de `memory_get` quando `lines` é
omitido.
- `toolResultMaxChars`: limite de resultado de ferramenta ao vivo usado para resultados persistidos e
recuperação de excedente.
- `postCompactionMaxChars`: limite de trecho de AGENTS.md usado durante a injeção de
recuperação de estouro.
- `postCompactionMaxChars`: limite do trecho de AGENTS.md usado durante a injeção de
atualização pós-Compaction.
#### `agents.list[].contextLimits`
Substituição por agente para as opções compartilhadas de `contextLimits`. Campos omitidos herdam
Substituição por agente para os controles compartilhados de `contextLimits`. Campos omitidos herdam
de `agents.defaults.contextLimits`.
```json5
@ -300,7 +303,7 @@ Fuso horário para o contexto do prompt do sistema (não para carimbos de data/h
### `agents.defaults.timeFormat`
Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO).
Formato de hora no prompt do sistema. Padrão: `auto` (preferência do sistema operacional).
```json5
{
@ -346,6 +349,7 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO).
pdfMaxPages: 20,
thinkingDefault: "low",
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
timeoutSeconds: 600,
@ -358,58 +362,55 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO).
```
- `model`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- A forma em string define apenas o modelo primário.
- A forma em objeto define o primário mais os modelos de failover ordenados.
- A forma de string define apenas o modelo primário.
- A forma de objeto define o primário mais os modelos de failover ordenados.
- `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo caminho da ferramenta `image` como sua configuração de modelo de visão.
- Também usado como roteamento de fallback quando o modelo selecionado/padrão não consegue aceitar entrada de imagem.
- Prefira referências explícitas `provider/model`. IDs simples são aceitos por compatibilidade; se um ID simples corresponder de forma única a uma entrada configurada com suporte a imagens em `models.providers.*.models`, o OpenClaw o qualifica para esse provedor. Correspondências configuradas ambíguas exigem um prefixo de provedor explícito.
- Prefira referências explícitas `provider/model`. IDs simples são aceitos por compatibilidade; se um ID simples corresponder exclusivamente a uma entrada configurada com capacidade de imagem em `models.providers.*.models`, o OpenClaw o qualifica para esse provedor. Correspondências configuradas ambíguas exigem um prefixo de provedor explícito.
- `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo recurso compartilhado de geração de imagens e por qualquer superfície futura de ferramenta/Plugin que gere imagens.
- Valores típicos: `google/gemini-3.1-flash-image-preview` para geração de imagens nativa do Gemini, `fal/fal-ai/flux/dev` para fal, `openai/gpt-image-2` para OpenAI Images ou `openai/gpt-image-1.5` para saída OpenAI PNG/WebP com fundo transparente.
- Usado pela capacidade compartilhada de geração de imagens e por qualquer superfície futura de ferramenta/Plugin que gere imagens.
- Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagens do Gemini, `fal/fal-ai/flux/dev` para fal, `openai/gpt-image-2` para OpenAI Images ou `openai/gpt-image-1.5` para saída PNG/WebP da OpenAI com fundo transparente.
- Se você selecionar um provedor/modelo diretamente, configure também a autenticação correspondente do provedor (por exemplo, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` ou OpenAI Codex OAuth para `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` para `fal/*`).
- Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores restantes registrados para geração de imagens em ordem de ID do provedor.
- Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e, em seguida, os demais provedores de geração de imagem registrados em ordem de ID de provedor.
- `musicGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo recurso compartilhado de geração de música e pela ferramenta integrada `music_generate`.
- Usado pela capacidade compartilhada de geração de música e pela ferramenta integrada `music_generate`.
- Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.6`.
- Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores restantes registrados para geração de música em ordem de ID do provedor.
- Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e, em seguida, os demais provedores de geração de música registrados em ordem de ID de provedor.
- Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor.
- `videoGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo recurso compartilhado de geração de vídeo e pela ferramenta integrada `video_generate`.
- Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta integrada `video_generate`.
- Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`.
- Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores restantes registrados para geração de vídeo em ordem de ID do provedor.
- Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e, em seguida, os demais provedores de geração de vídeo registrados em ordem de ID de provedor.
- Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor.
- O provedor integrado de geração de vídeo Qwen aceita até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções em nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`.
- O provedor integrado de geração de vídeo Qwen oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções em nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`.
- `pdfModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pela ferramenta `pdf` para roteamento de modelo.
- Se omitido, a ferramenta PDF recorre a `imageModel` e depois ao modelo resolvido da sessão/padrão.
- `pdfMaxBytesMb`: limite padrão de tamanho de PDF para a ferramenta `pdf` quando `maxBytesMb` não é passado no momento da chamada.
- `pdfMaxPages`: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`.
- `verboseDefault`: nível detalhado padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`.
- `reasoningDefault`: visibilidade padrão de raciocínio para agentes. Valores: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` por agente substitui esse padrão. Padrões de raciocínio configurados só são aplicados para proprietários, remetentes autorizados ou contextos de gateway de administrador-operador quando nenhuma substituição de raciocínio por mensagem ou sessão está definida.
- `verboseDefault`: nível verboso padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`.
- `toolProgressDetail`: modo de detalhe para resumos de ferramentas `/verbose` e linhas de ferramenta em rascunho de progresso. Valores: `"explain"` (padrão, rótulos humanos compactos) ou `"raw"` (anexa comando/detalhe bruto quando disponível). `agents.list[].toolProgressDetail` por agente substitui esse padrão.
- `reasoningDefault`: visibilidade padrão de raciocínio para agentes. Valores: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` por agente substitui esse padrão. Padrões de raciocínio configurados só são aplicados a proprietários, remetentes autorizados ou contextos de Gateway de operador-admin quando nenhuma substituição de raciocínio por mensagem ou sessão está definida.
- `elevatedDefault`: nível padrão de saída elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Padrão: `"on"`.
- `model.primary`: formato `provider/model` (por exemplo, `openai/gpt-5.5` para acesso por chave de API ou `openai-codex/gpt-5.5` para Codex OAuth). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID de modelo exato e só então recorre ao provedor padrão configurado (comportamento de compatibilidade obsoleto; portanto, prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido.
- `models`: o catálogo de modelos configurado e a lista de permissões para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Edições seguras: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` para adicionar entradas. `config set` recusa substituições que removeriam entradas existentes da lista de permissões, a menos que você passe `--replace`.
- Fluxos de configuração/onboarding com escopo de provedor mesclam os modelos selecionados do provedor nesse mapa e preservam provedores não relacionados já configurados.
- Para modelos OpenAI Responses diretos, a Compaction do lado do servidor é habilitada automaticamente. Use `params.responsesServerCompaction: false` para parar de injetar `context_management`, ou `params.responsesCompactThreshold` para substituir o limite. Consulte [Compaction do lado do servidor da OpenAI](/pt-BR/providers/openai#server-side-compaction-responses-api).
- `params`: parâmetros padrão globais do provedor aplicados a todos os modelos. Definidos em `agents.defaults.params` (por exemplo, `{ cacheRetention: "long" }`).
- Precedência de mesclagem de `params` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), depois `agents.list[].params` (ID de agente correspondente) substitui por chave. Consulte [Cache de prompts](/pt-BR/reference/prompt-caching) para detalhes.
- `params.extra_body`/`params.extraBody`: JSON avançado de repasse mesclado nos corpos de solicitação `api: "openai-completions"` para proxies compatíveis com OpenAI. Se colidir com chaves de solicitação geradas, o corpo extra vence; rotas de completions não nativas ainda removem `store` exclusivo da OpenAI depois.
- `params.chat_template_kwargs`: argumentos de template de chat compatíveis com vLLM/OpenAI mesclados nos corpos de solicitação `api: "openai-completions"` de nível superior. Para `vllm/nemotron-3-*` com thinking desativado, o Plugin vLLM integrado envia automaticamente `enable_thinking: false` e `force_nonempty_content: true`; `chat_template_kwargs` explícito substitui padrões gerados, e `extra_body.chat_template_kwargs` ainda tem precedência final. Para controles de thinking do Qwen no vLLM, defina `params.qwenThinkingFormat` como `"chat-template"` ou `"top-level"` nessa entrada de modelo.
- `compat.supportedReasoningEfforts`: lista de esforço de raciocínio compatível com OpenAI por modelo. Inclua `"xhigh"` para endpoints personalizados que realmente o aceitam; então o OpenClaw expõe `/think xhigh` em menus de comando, linhas de sessão do Gateway, validação de patch de sessão, validação da CLI de agente e validação de `llm-task` para esse provedor/modelo configurado. Use `compat.reasoningEffortMap` quando o backend quiser um valor específico do provedor para um nível canônico.
- `params.preserveThinking`: opção opt-in exclusiva da Z.AI para thinking preservado. Quando habilitado e o thinking está ativado, o OpenClaw envia `thinking.clear_thinking: false` e reproduz `reasoning_content` anterior; consulte [thinking e thinking preservado da Z.AI](/pt-BR/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: política padrão de runtime de agente de baixo nível. ID omitido usa OpenClaw Pi como padrão. Use `id: "pi"` para forçar o harness PI integrado, `id: "auto"` para permitir que harnesses de Plugin registrados reivindiquem modelos compatíveis e usem PI quando nenhum corresponder, um ID de harness registrado como `id: "codex"` para exigir esse harness, ou um alias de backend de CLI compatível como `id: "claude-cli"`. Runtimes explícitos de Plugin falham de modo fechado quando o harness está indisponível ou falha. Mantenha referências de modelo canônicas como `provider/model`; selecione Codex, Claude CLI, Gemini CLI e outros backends de execução por meio da configuração de runtime em vez de prefixos legados de provedor de runtime. Consulte [Runtimes de agente](/pt-BR/concepts/agent-runtimes) para entender como isso difere da seleção de provedor/modelo.
- Gravadores de configuração que alteram estes campos (por exemplo, `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível.
- `maxConcurrent`: máximo de execuções paralelas de agente entre sessões (cada sessão ainda é serializada). Padrão: 4.
- `model.primary`: formato `provider/model` (por exemplo, `openai/gpt-5.5` para acesso por chave de API ou `openai-codex/gpt-5.5` para Codex OAuth). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência exclusiva de provedor configurado para esse ID de modelo exato, e só então recorre ao provedor padrão configurado (comportamento de compatibilidade obsoleto, portanto prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido.
- `models`: o catálogo de modelos configurado e a allowlist para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específico do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Edições seguras: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` para adicionar entradas. `config set` recusa substituições que removeriam entradas existentes da allowlist, a menos que você passe `--replace`.
- Fluxos de configuração/onboarding com escopo de provedor mesclam os modelos de provedor selecionados nesse mapa e preservam provedores não relacionados já configurados.
- Para modelos OpenAI Responses diretos, a Compaction no lado do servidor é ativada automaticamente. Use `params.responsesServerCompaction: false` para parar de injetar `context_management`, ou `params.responsesCompactThreshold` para substituir o limite. Veja [Compaction no lado do servidor da OpenAI](/pt-BR/providers/openai#server-side-compaction-responses-api).
- `params`: parâmetros globais padrão de provedor aplicados a todos os modelos. Definidos em `agents.defaults.params` (por exemplo, `{ cacheRetention: "long" }`).
- Precedência de mesclagem de `params` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), depois `agents.list[].params` (ID de agente correspondente) substitui por chave. Veja [Cache de Prompt](/pt-BR/reference/prompt-caching) para detalhes.
- `params.extra_body`/`params.extraBody`: JSON avançado de passagem direta mesclado em corpos de solicitação `api: "openai-completions"` para proxies compatíveis com OpenAI. Se houver colisão com chaves de solicitação geradas, o corpo extra prevalece; rotas de completions não nativas ainda removem `store` exclusivo da OpenAI depois.
- `params.chat_template_kwargs`: argumentos de modelo de chat compatíveis com vLLM/OpenAI mesclados em corpos de solicitação de nível superior `api: "openai-completions"`. Para `vllm/nemotron-3-*` com pensamento desativado, o Plugin vLLM integrado envia automaticamente `enable_thinking: false` e `force_nonempty_content: true`; `chat_template_kwargs` explícito substitui os padrões gerados, e `extra_body.chat_template_kwargs` ainda tem precedência final. Para controles de pensamento Qwen do vLLM, defina `params.qwenThinkingFormat` como `"chat-template"` ou `"top-level"` nessa entrada de modelo.
- `compat.supportedReasoningEfforts`: lista de esforço de raciocínio compatível com OpenAI por modelo. Inclua `"xhigh"` para endpoints personalizados que realmente o aceitam; então o OpenClaw expõe `/think xhigh` em menus de comando, linhas de sessão do Gateway, validação de patch de sessão, validação de CLI de agente e validação de `llm-task` para esse provedor/modelo configurado. Use `compat.reasoningEffortMap` quando o backend exigir um valor específico do provedor para um nível canônico.
- `params.preserveThinking`: opt-in exclusivo da Z.AI para pensamento preservado. Quando ativado e o pensamento está ligado, o OpenClaw envia `thinking.clear_thinking: false` e reproduz `reasoning_content` anterior; veja [pensamento e pensamento preservado da Z.AI](/pt-BR/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: política padrão de runtime de agente de baixo nível. ID omitido usa OpenClaw Pi por padrão. Use `id: "pi"` para forçar o harness PI integrado, `id: "auto"` para permitir que harnesses de Plugin registrados reivindiquem modelos compatíveis e usem PI quando nenhum corresponder, um ID de harness registrado como `id: "codex"` para exigir esse harness, ou um alias de backend de CLI compatível como `id: "claude-cli"`. Runtimes de Plugin explícitos falham fechados quando o harness está indisponível ou falha. Mantenha referências de modelo canônicas como `provider/model`; selecione Codex, Claude CLI, Gemini CLI e outros backends de execução por meio da configuração de runtime em vez de prefixos legados de provedor de runtime. Veja [Runtimes de agente](/pt-BR/concepts/agent-runtimes) para saber como isso difere da seleção de provedor/modelo.
- Gravadores de configuração que alteram esses campos (por exemplo, `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível.
- `maxConcurrent`: máximo de execuções paralelas de agentes entre sessões (cada sessão ainda serializada). Padrão: 4.
### `agents.defaults.agentRuntime`
`agentRuntime` controla qual executor de baixo nível executa turnos de agente. A maioria das
implantações deve manter o runtime OpenClaw Pi padrão. Use-o quando um
Plugin confiável fornecer um harness nativo, como o harness app-server Codex integrado,
ou quando você quiser um backend de CLI compatível, como Claude CLI. Para o modelo
mental, consulte [Runtimes de agente](/pt-BR/concepts/agent-runtimes).
`agentRuntime` controla qual executor de baixo nível executa turnos de agente. A maioria das implantações deve manter o runtime padrão OpenClaw Pi. Use-o quando um Plugin confiável fornece um harness nativo, como o harness de servidor de aplicativo Codex integrado, ou quando você quer um backend de CLI compatível como Claude CLI. Para o modelo mental, veja [Runtimes de agente](/pt-BR/concepts/agent-runtimes).
```json5
{
@ -425,21 +426,21 @@ mental, consulte [Runtimes de agente](/pt-BR/concepts/agent-runtimes).
```
- `id`: `"auto"`, `"pi"`, um ID de harness de Plugin registrado ou um alias de backend de CLI compatível. O Plugin Codex integrado registra `codex`; o Plugin Anthropic integrado fornece o backend de CLI `claude-cli`.
- `id: "auto"` permite que harnesses de Plugin registrados reivindiquem turnos compatíveis e usa PI quando nenhum harness corresponde. Um runtime explícito de Plugin como `id: "codex"` exige esse harness e falha de modo fechado se ele estiver indisponível ou falhar.
- `id: "auto"` permite que harnesses de Plugin registrados reivindiquem turnos compatíveis e usa PI quando nenhum harness corresponde. Um runtime de Plugin explícito como `id: "codex"` exige esse harness e falha fechado se ele estiver indisponível ou falhar.
- Substituição de ambiente: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` substitui `id` para esse processo.
- Para implantações somente Codex, defina `model: "openai/gpt-5.5"` e `agentRuntime.id: "codex"`.
- Para implantações Claude CLI, prefira `model: "anthropic/claude-opus-4-7"` mais `agentRuntime.id: "claude-cli"`. Referências legadas de modelo `claude-cli/claude-opus-4-7` ainda funcionam por compatibilidade, mas novas configurações devem manter a seleção de provedor/modelo canônica e colocar o backend de execução em `agentRuntime.id`.
- Chaves mais antigas de política de runtime são reescritas para `agentRuntime` por `openclaw doctor --fix`.
- A escolha do harness é fixada por ID de sessão após a primeira execução incorporada. Alterações de configuração/env afetam sessões novas ou redefinidas, não uma transcrição existente. Sessões legadas com histórico de transcrição, mas sem pin registrado, são tratadas como fixadas em PI. `/status` relata o runtime efetivo, por exemplo `Runtime: OpenClaw Pi Default` ou `Runtime: OpenAI Codex`.
- Para implantações somente com Codex, defina `model: "openai/gpt-5.5"` e `agentRuntime.id: "codex"`.
- Para implantações com Claude CLI, prefira `model: "anthropic/claude-opus-4-7"` mais `agentRuntime.id: "claude-cli"`. Referências de modelo legadas `claude-cli/claude-opus-4-7` ainda funcionam por compatibilidade, mas novas configurações devem manter a seleção de provedor/modelo canônica e colocar o backend de execução em `agentRuntime.id`.
- Chaves antigas de política de runtime são reescritas para `agentRuntime` por `openclaw doctor --fix`.
- A escolha de harness é fixada por ID de sessão após a primeira execução embutida. Mudanças de configuração/ambiente afetam sessões novas ou redefinidas, não uma transcrição existente. Sessões legadas com histórico de transcrição, mas sem pin registrado, são tratadas como fixadas em PI. `/status` informa o runtime efetivo, por exemplo `Runtime: OpenClaw Pi Default` ou `Runtime: OpenAI Codex`.
- Isso controla apenas a execução de turnos de agente de texto. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provedor/modelo.
**Atalhos de alias integrados** (aplicam-se apenas quando o modelo está em `agents.defaults.models`):
**Atalhos de alias integrados** (aplicam-se somente quando o modelo está em `agents.defaults.models`):
| Alias | Modelo |
| ------------------- | ------------------------------------------ |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` |
| `gpt` | `openai/gpt-5.5` ou `openai-codex/gpt-5.5` |
| `gpt-mini` | `openai/gpt-5.4-mini` |
| `gpt-nano` | `openai/gpt-5.4-nano` |
| `gemini` | `google/gemini-3.1-pro-preview` |
@ -450,11 +451,11 @@ Seus aliases configurados sempre prevalecem sobre os padrões.
Os modelos Z.AI GLM-4.x ativam automaticamente o modo de pensamento, a menos que você defina `--thinking off` ou defina `agents.defaults.models["zai/<model>"].params.thinking` por conta própria.
Os modelos Z.AI ativam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/<model>"].params.tool_stream` como `false` para desativá-lo.
Os modelos Anthropic Claude 4.6 usam pensamento `adaptive` por padrão quando nenhum nível de pensamento explícito é definido.
Os modelos Anthropic Claude 4.6 usam pensamento `adaptive` por padrão quando nenhum nível de pensamento explícito está definido.
### `agents.defaults.cliBackends`
Backends de CLI opcionais para execuções alternativas somente texto (sem chamadas de ferramenta). Útil como backup quando provedores de API falham.
Backends de CLI opcionais para execuções de fallback somente texto (sem chamadas de ferramenta). Úteis como backup quando provedores de API falham.
```json5
{
@ -483,13 +484,13 @@ Backends de CLI opcionais para execuções alternativas somente texto (sem chama
}
```
- Backends de CLI priorizam texto; ferramentas são sempre desativadas.
- Backends de CLI priorizam texto; ferramentas estão sempre desativadas.
- Sessões são compatíveis quando `sessionArg` está definido.
- A passagem de imagens é compatível quando `imageArg` aceita caminhos de arquivo.
- Repasse de imagem é compatível quando `imageArg` aceita caminhos de arquivo.
### `agents.defaults.systemPromptOverride`
Substitua todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou composto apenas por espaços em branco é ignorado. Útil para experimentos controlados de prompt.
Substitui todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou somente com espaços em branco é ignorado. Útil para experimentos controlados de prompt.
```json5
{
@ -503,7 +504,7 @@ Substitua todo o prompt de sistema montado pelo OpenClaw por uma string fixa. De
### `agents.defaults.promptOverlays`
Sobreposições de prompt independentes de provedor aplicadas por família de modelos. IDs de modelos da família GPT-5 recebem o contrato de comportamento compartilhado entre provedores; `personality` controla apenas a camada amigável de estilo de interação.
Sobreposições de prompt independentes de provedor aplicadas por família de modelo. IDs de modelos da família GPT-5 recebem o contrato de comportamento compartilhado entre provedores; `personality` controla somente a camada de estilo de interação amigável.
```json5
{
@ -519,9 +520,9 @@ Sobreposições de prompt independentes de provedor aplicadas por família de mo
}
```
- `"friendly"` (padrão) e `"on"` ativam a camada amigável de estilo de interação.
- `"off"` desativa apenas a camada amigável; o contrato de comportamento GPT-5 marcado permanece ativado.
- O `plugins.entries.openai.config.personality` legado ainda é lido quando esta configuração compartilhada não está definida.
- `"friendly"` (padrão) e `"on"` ativam a camada de estilo de interação amigável.
- `"off"` desativa somente a camada amigável; o contrato de comportamento GPT-5 marcado permanece ativado.
- O `plugins.entries.openai.config.personality` legado ainda é lido quando essa configuração compartilhada não está definida.
### `agents.defaults.heartbeat`
@ -554,14 +555,14 @@ Execuções periódicas de Heartbeat.
```
- `every`: string de duração (ms/s/m/h). Padrão: `30m` (autenticação por chave de API) ou `1h` (autenticação OAuth). Defina como `0m` para desativar.
- `includeSystemPromptSection`: quando falso, omite a seção Heartbeat do prompt de sistema e ignora a injeção de `HEARTBEAT.md` no contexto de bootstrap. Padrão: `true`.
- `suppressToolErrorWarnings`: quando verdadeiro, suprime payloads de aviso de erro de ferramenta durante execuções de Heartbeat.
- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes que ele seja abortado. Deixe indefinido para usar `agents.defaults.timeoutSeconds`.
- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para destino direto. `block` suprime a entrega para destino direto e emite `reason=dm-blocked`.
- `lightContext`: quando verdadeiro, 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 de conversa anterior. Mesmo padrão de isolamento que cron `sessionTarget: "isolated"`. Reduz o custo de tokens por Heartbeat de ~100K para ~2-5K tokens.
- `skipWhenBusy`: quando verdadeiro, execuções de Heartbeat são adiadas em faixas extras ocupadas: trabalho de subagente ou comando aninhado. Faixas de Cron sempre adiam Heartbeats, mesmo sem esta flag.
- Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **apenas esses agentes** executam Heartbeats.
- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt de sistema e pula a injeção de `HEARTBEAT.md` no contexto de bootstrap. Padrão: `true`.
- `suppressToolErrorWarnings`: quando true, suprime payloads de aviso de erro de ferramenta durante execuções de Heartbeat.
- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes de ser abortado. Deixe indefinido para usar `agents.defaults.timeoutSeconds`.
- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para alvo direto. `block` suprime entrega para alvo direto e emite `reason=dm-blocked`.
- `lightContext`: quando true, execuções de Heartbeat usam contexto de bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos de bootstrap do workspace.
- `isolatedSession`: quando true, cada Heartbeat é executado em uma sessão nova sem histórico de conversa anterior. Mesmo padrão de isolamento que o Cron `sessionTarget: "isolated"`. Reduz o custo de tokens por Heartbeat de ~100K para ~2-5K tokens.
- `skipWhenBusy`: quando true, execuções de Heartbeat são adiadas em lanes ocupadas extras: trabalho de subagente ou comando aninhado. Lanes de Cron sempre adiam Heartbeats, mesmo sem esta flag.
- Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **somente esses agentes** executam Heartbeats.
- Heartbeats executam turnos completos de agente — intervalos mais curtos consomem mais tokens.
### `agents.defaults.compaction`
@ -598,23 +599,23 @@ Execuções periódicas de Heartbeat.
}
```
- `mode`: `default` ou `safeguard` (resumo em blocos para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction).
- `provider`: ID de um Plugin provedor de Compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez do resumo por LLM integrado. Recua para o integrado em caso de falha. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction).
- `mode`: `default` ou `safeguard` (sumarização em partes para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction).
- `provider`: id de um Plugin provedor de Compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização LLM integrada. Em caso de falha, volta para a opção integrada. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction).
- `timeoutSeconds`: máximo de segundos permitido para uma única operação de Compaction antes que o OpenClaw a aborte. Padrão: `900`.
- `keepRecentTokens`: orçamento de ponto de corte do Pi para manter literalmente a cauda mais recente da transcrição. `/compact` manual honra isto quando definido explicitamente; caso contrário, a Compaction manual é um checkpoint rígido.
- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` antepõe orientação integrada de retenção de identificadores opacos durante o resumo de Compaction.
- `keepRecentTokens`: orçamento de ponto de corte do Pi para manter literalmente a cauda mais recente da transcrição. `/compact` manual respeita isso quando definido explicitamente; caso contrário, a Compaction manual é um checkpoint rígido.
- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` antepõe orientações integradas de retenção de identificadores opacos durante a sumarização de Compaction.
- `identifierInstructions`: texto personalizado opcional de preservação de identificadores usado quando `identifierPolicy=custom`.
- `qualityGuard`: verificações de nova tentativa em saída malformada para resumos safeguard. Ativado por padrão no modo safeguard; defina `enabled: false` para ignorar a auditoria.
- `midTurnPrecheck`: verificação opcional de pressão do loop de ferramentas do Pi. Quando `enabled: true`, o OpenClaw verifica a pressão de contexto depois que resultados de ferramentas são anexados e antes da próxima chamada de modelo. Se o contexto não couber mais, ele aborta a tentativa atual antes de enviar o prompt e reutiliza o caminho de recuperação de pré-verificação existente para truncar resultados de ferramentas ou compactar e tentar novamente. Funciona com os modos de Compaction `default` e `safeguard`. Padrão: desativado.
- `qualityGuard`: verificações de nova tentativa em saída malformada para resumos safeguard. Ativado por padrão no modo safeguard; defina `enabled: false` para pular a auditoria.
- `midTurnPrecheck`: verificação opcional de pressão do loop de ferramentas do Pi. Quando `enabled: true`, o OpenClaw verifica a pressão de contexto depois que os resultados de ferramentas são anexados e antes da próxima chamada de modelo. Se o contexto não couber mais, ele aborta a tentativa atual antes de enviar o prompt e reutiliza o caminho de recuperação de pré-verificação existente para truncar resultados de ferramentas ou compactar e tentar novamente. Funciona com os modos de Compaction `default` e `safeguard`. Padrão: desativado.
- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após a Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desativar a reinjeção. Quando indefinido ou definido explicitamente para esse par padrão, os títulos antigos `Every Session`/`Safety` também são aceitos como fallback legado.
- `model`: substituição opcional `provider/model-id` apenas para resumo de Compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem executar em outro; quando indefinido, a Compaction usa o modelo primário da sessão.
- `maxActiveTranscriptBytes`: limite opcional em bytes (`number` ou strings como `"20mb"`) que aciona a Compaction local normal antes de uma execução quando o JSONL ativo cresce além do limite. Exige `truncateAfterCompaction` para que uma Compaction bem-sucedida possa rotacionar para uma transcrição sucessora menor. Desativado quando indefinido ou `0`.
- `notifyUser`: quando `true`, envia avisos breves ao usuário quando a Compaction começa e quando termina (por exemplo, "Compactando contexto..." e "Compaction concluída"). Desativado por padrão para manter a Compaction silenciosa.
- `memoryFlush`: turno agentic silencioso antes da Compaction automática para armazenar memórias duráveis. Defina `model` para um provedor/modelo exato, como `ollama/qwen3:8b`, quando este turno de manutenção deve permanecer em um modelo local; a substituição não herda a cadeia de fallback da sessão ativa. Ignorado quando o workspace é somente leitura.
- `model`: substituição opcional `provider/model-id` somente para sumarização de Compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem rodar em outro; quando indefinido, a Compaction usa o modelo primário da sessão.
- `maxActiveTranscriptBytes`: limite opcional em bytes (`number` ou strings como `"20mb"`) que aciona a Compaction local normal antes de uma execução quando o JSONL ativo ultrapassa o limite. Exige `truncateAfterCompaction` para que a Compaction bem-sucedida possa rotacionar para uma transcrição sucessora menor. Desativado quando indefinido ou `0`.
- `notifyUser`: quando `true`, envia avisos breves ao usuário quando a Compaction começa e quando é concluída (por exemplo, "Compactando contexto..." e "Compaction concluída"). Desativado por padrão para manter a Compaction silenciosa.
- `memoryFlush`: turno agentic silencioso antes da Compaction automática para armazenar memórias duráveis. Defina `model` como um provedor/modelo exato, como `ollama/qwen3:8b`, quando este turno de manutenção deve permanecer em um modelo local; a substituição não herda a cadeia de fallback da sessão ativa. Ignorado quando o workspace é somente leitura.
### `agents.defaults.contextPruning`
Remove **resultados antigos de ferramentas** do contexto em memória antes de enviar para a LLM. **Não** modifica o histórico de sessão no disco.
Remove **resultados antigos de ferramentas** do contexto em memória antes de enviar ao LLM. **Não** modifica o histórico da sessão em disco.
```json5
{
@ -639,8 +640,8 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en
<Accordion title="comportamento do modo cache-ttl">
- `mode: "cache-ttl"` ativa passagens de remoção.
- `ttl` controla com que frequência a remoção pode executar novamente (após o último toque no cache).
- A remoção primeiro faz soft-trim de resultados de ferramentas grandes demais e depois hard-clear em resultados de ferramentas mais antigos, se necessário.
- `ttl` controla com que frequência a remoção pode ser executada novamente (após o último toque no cache).
- A remoção primeiro faz soft-trim em resultados de ferramenta grandes demais, depois hard-clear em resultados de ferramenta mais antigos se necessário.
**Soft-trim** mantém o início + fim e insere `...` no meio.
@ -648,9 +649,9 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en
Observações:
- Blocos de imagem nunca são aparados/removidos.
- Blocos de imagem nunca são aparados/limpos.
- Proporções são baseadas em caracteres (aproximadas), não em contagens exatas de tokens.
- Se houver menos de `keepLastAssistants` mensagens de assistente, a remoção é ignorada.
- Se houver menos de `keepLastAssistants` mensagens do assistente, a remoção é ignorada.
</Accordion>
@ -676,7 +677,7 @@ Consulte [Remoção de Sessão](/pt-BR/concepts/session-pruning) para detalhes d
- Substituições por canal: `channels.<channel>.blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam `minChars: 1500` por padrão.
- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`.
Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + divisão em blocos.
Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + divisão em chunks.
### Indicadores de digitação
@ -691,7 +692,7 @@ Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento +
}
```
- Padrões: `instant` para chats diretos/menções, `message` para chats em grupo sem menção.
- Padrões: `instant` para conversas diretas/menções, `message` para conversas em grupo sem menção.
- Substituições por sessão: `session.typingMode`, `session.typingIntervalSeconds`.
Consulte [Indicadores de digitação](/pt-BR/concepts/typing-indicators).
@ -700,7 +701,7 @@ Consulte [Indicadores de digitação](/pt-BR/concepts/typing-indicators).
### `agents.defaults.sandbox`
Sandboxing opcional para o agente incorporado. Consulte [Sandboxing](/pt-BR/gateway/sandboxing) para o guia completo.
Isolamento em sandbox opcional para o agente incorporado. Consulte [Isolamento em sandbox](/pt-BR/gateway/sandboxing) para o guia completo.
```json5
{
@ -795,52 +796,52 @@ Sandboxing opcional para o agente incorporado. Consulte [Sandboxing](/pt-BR/gate
}
```
<Accordion title="Detalhes do sandbox">
<Accordion title="Sandbox details">
**Backend:**
**Mecanismo:**
- `docker`: runtime Docker local (padrão)
- `docker`: runtime local do Docker (padrão)
- `ssh`: runtime remoto genérico baseado em SSH
- `openshell`: runtime OpenShell
Quando `backend: "openshell"` é selecionado, as configurações específicas do runtime passam para
`plugins.entries.openshell.config`.
**Configuração do backend SSH:**
**Configuração do mecanismo SSH:**
- `target`: destino SSH no formato `user@host[:port]`
- `command`: comando do cliente SSH (padrão: `ssh`)
- `workspaceRoot`: raiz remota absoluta usada para workspaces por escopo
- `workspaceRoot`: raiz remota absoluta usada para espaços de trabalho por escopo
- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados para o OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: conteúdos inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime
- `strictHostKeyChecking` / `updateHostKeys`: controles de política de chave de host do OpenSSH
**Precedência de autenticação SSH:**
- `identityData` tem prioridade sobre `identityFile`
- `certificateData` tem prioridade sobre `certificateFile`
- `knownHostsData` tem prioridade sobre `knownHostsFile`
- Valores `*Data` baseados em SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão de sandbox
- `identityData` prevalece sobre `identityFile`
- `certificateData` prevalece sobre `certificateFile`
- `knownHostsData` prevalece sobre `knownHostsFile`
- Valores `*Data` baseados em SecretRef são resolvidos do snapshot ativo do runtime de segredos antes do início da sessão de sandbox
**Comportamento do backend SSH:**
**Comportamento do mecanismo SSH:**
- inicializa o workspace remoto uma vez após criar ou recriar
- depois mantém o workspace SSH remoto como canônico
- semeia o espaço de trabalho remoto uma vez após criação ou recriação
- depois mantém o espaço de trabalho SSH remoto como canônico
- roteia `exec`, ferramentas de arquivo e caminhos de mídia por SSH
- não sincroniza alterações remotas de volta para o host automaticamente
- não sincroniza automaticamente alterações remotas de volta para o host
- não oferece suporte a contêineres de navegador em sandbox
**Acesso ao workspace:**
**Acesso ao espaço de trabalho:**
- `none`: workspace de sandbox por escopo em `~/.openclaw/sandboxes`
- `ro`: workspace de sandbox em `/workspace`, workspace do agente montado como somente leitura em `/agent`
- `rw`: workspace do agente montado como leitura/gravação em `/workspace`
- `none`: espaço de trabalho de sandbox por escopo em `~/.openclaw/sandboxes`
- `ro`: espaço de trabalho de sandbox em `/workspace`, espaço de trabalho do agente montado como somente leitura em `/agent`
- `rw`: espaço de trabalho do agente montado como leitura/gravação em `/workspace`
**Escopo:**
- `session`: contêiner + workspace por sessão
- `agent`: um contêiner + workspace por agente (padrão)
- `shared`: contêiner e workspace compartilhados (sem isolamento entre sessões)
- `session`: contêiner + espaço de trabalho por sessão
- `agent`: um contêiner + espaço de trabalho por agente (padrão)
- `shared`: contêiner e espaço de trabalho compartilhados (sem isolamento entre sessões)
**Configuração do Plugin OpenShell:**
@ -870,29 +871,29 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas do
**Modo OpenShell:**
- `mirror`: inicializa o remoto a partir do local antes de exec, sincroniza de volta após exec; o workspace local permanece canônico
- `remote`: inicializa o remoto uma vez quando o sandbox é criado e depois mantém o workspace remoto como canônico
- `mirror`: semeia o remoto a partir do local antes de exec, sincroniza de volta após exec; o espaço de trabalho local permanece canônico
- `remote`: semeia o remoto uma vez quando a sandbox é criada e, depois, mantém o espaço de trabalho remoto como canônico
No modo `remote`, edições locais do host feitas fora do OpenClaw não são sincronizadas para o sandbox automaticamente após a etapa de inicialização.
O transporte é SSH para o sandbox OpenShell, mas o Plugin controla o ciclo de vida do sandbox e a sincronização espelhada opcional.
No modo `remote`, edições locais do host feitas fora do OpenClaw não são sincronizadas automaticamente para a sandbox após a etapa de semeadura.
O transporte é SSH para a sandbox OpenShell, mas o Plugin é responsável pelo ciclo de vida da sandbox e pela sincronização opcional de espelhamento.
**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Exige saída de rede, raiz gravável e usuário root.
**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Precisa de saída de rede, raiz gravável e usuário root.
**Contêineres usam `network: "none"` por padrão** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso externo.
**Contêineres usam `network: "none"` por padrão** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída.
`"host"` é bloqueado. `"container:<id>"` é bloqueado por padrão, a menos que você defina explicitamente
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (uso emergencial).
**Anexos de entrada** são preparados em `media/inbound/*` no workspace ativo.
**Anexos de entrada** são preparados em `media/inbound/*` no espaço de trabalho ativo.
**`docker.binds`** monta diretórios adicionais do host; montagens globais e por agente são mescladas.
**Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. URL noVNC injetada no prompt do sistema. Não exige `browser.enabled` em `openclaw.json`.
O acesso de observador noVNC usa autenticação VNC por padrão e o OpenClaw emite uma URL com token de curta duração (em vez de expor a senha na URL compartilhada).
**Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. URL noVNC injetada no prompt do sistema. Não requer `browser.enabled` em `openclaw.json`.
O acesso de observador noVNC usa autenticação VNC por padrão, e o OpenClaw emite uma URL com token de curta duração (em vez de expor a senha na URL compartilhada).
- `allowHostControl: false` (padrão) impede que sessões em sandbox tenham como alvo o navegador do host.
- `allowHostControl: false` (padrão) impede que sessões em sandbox apontem para o navegador do host.
- `network` usa `openclaw-sandbox-browser` por padrão (rede bridge dedicada). Defina como `bridge` somente quando você quiser explicitamente conectividade bridge global.
- `cdpSourceRange` opcionalmente restringe a entrada CDP na borda do contêiner a um intervalo CIDR (por exemplo, `172.21.0.1/32`).
- `sandbox.browser.binds` monta diretórios adicionais do host somente no contêiner do navegador em sandbox. Quando definido (incluindo `[]`), substitui `docker.binds` para o contêiner do navegador.
- `cdpSourceRange` restringe opcionalmente a entrada CDP na borda do contêiner a um intervalo CIDR (por exemplo, `172.21.0.1/32`).
- `sandbox.browser.binds` monta diretórios adicionais do host somente no contêiner do navegador em sandbox. Quando definido (incluindo `[]`), ele substitui `docker.binds` para o contêiner do navegador.
- Os padrões de inicialização são definidos em `scripts/sandbox-browser-entrypoint.sh` e ajustados para hosts de contêiner:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
@ -910,22 +911,22 @@ O acesso de observador noVNC usa autenticação VNC por padrão e o OpenClaw emi
- `--renderer-process-limit=2`
- `--no-zygote`
- `--metrics-recording-only`
- `--disable-extensions` (ativado por padrão)
- `--disable-extensions` (habilitado por padrão)
- `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` são
ativados por padrão e podem ser desativados com
habilitados por padrão e podem ser desabilitados com
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reativa extensões se o seu fluxo de trabalho
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se o seu fluxo de trabalho
depender delas.
- `--renderer-process-limit=2` pode ser alterado com
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; defina `0` para usar o
limite de processos padrão do Chromium.
- mais `--no-sandbox` quando `noSandbox` estiver ativado.
- Os padrões são a base da imagem do contêiner; use uma imagem de navegador personalizada com um
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; defina `0` para usar o limite de processos
padrão do Chromium.
- além de `--no-sandbox` quando `noSandbox` estiver habilitado.
- Os padrões são a linha de base da imagem do contêiner; use uma imagem de navegador personalizada com um
entrypoint personalizado para alterar os padrões do contêiner.
</Accordion>
Sandboxing de navegador e `sandbox.docker.binds` são exclusivos do Docker.
O isolamento do navegador em sandbox e `sandbox.docker.binds` são exclusivos do Docker.
Crie imagens (a partir de um checkout do código-fonte):
@ -934,15 +935,15 @@ scripts/sandbox-setup.sh # main sandbox image
scripts/sandbox-browser-setup.sh # optional browser image
```
Para instalações npm sem um checkout do código-fonte, consulte [Sandboxing § Imagens e configuração](/pt-BR/gateway/sandboxing#images-and-setup) para comandos `docker build` inline.
Para instalações npm sem um checkout do código-fonte, consulte [Isolamento em sandbox § Imagens e configuração](/pt-BR/gateway/sandboxing#images-and-setup) para comandos inline `docker build`.
### `agents.list` (substituições por agente)
Use `agents.list[].tts` para fornecer a um agente seu próprio provedor de TTS, voz, modelo,
estilo ou modo de TTS automático. O bloco do agente faz deep merge sobre
`messages.tts`, então credenciais compartilhadas podem permanecer em um só lugar enquanto agentes
individuais substituem apenas os campos de voz ou provedor de que precisam. A substituição do agente
ativo se aplica a respostas faladas automáticas, `/tts audio`, `/tts status` e
Use `agents.list[].tts` para dar a um agente seu próprio provedor de TTS, voz, modelo,
estilo ou modo de TTS automático. O bloco do agente faz merge profundo sobre
`messages.tts` global, para que credenciais compartilhadas possam ficar em um só lugar enquanto agentes individuais
substituem apenas os campos de voz ou provedor de que precisam. A substituição do agente ativo
se aplica a respostas faladas automáticas, `/tts audio`, `/tts status` e
à ferramenta de agente `tts`. Consulte [Texto para fala](/pt-BR/tools/tts#per-agent-voice-overrides)
para exemplos de provedores e precedência.
@ -999,21 +1000,21 @@ para exemplos de provedores e precedência.
```
- `id`: id estável do agente (obrigatório).
- `default`: quando vários são definidos, o primeiro prevalece (aviso registrado). Se nenhum for definido, a primeira entrada da lista será o padrão.
- `model`: a forma em string define um primário estrito por agente, sem fallback de modelo; a forma de objeto `{ primary }` também é estrita, a menos que você adicione `fallbacks`. Use `{ primary, fallbacks: [...] }` para habilitar fallback nesse agente, ou `{ primary, fallbacks: [] }` para tornar explícito o comportamento estrito. Tarefas Cron que sobrescrevem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`.
- `default`: quando vários são definidos, o primeiro vence (aviso registrado). Se nenhum for definido, a primeira entrada da lista será o padrão.
- `model`: a forma de string define um primário estrito por agente sem fallback de modelo; a forma de objeto `{ primary }` também é estrita, a menos que você adicione `fallbacks`. Use `{ primary, fallbacks: [...] }` para habilitar fallback para esse agente, ou `{ primary, fallbacks: [] }` para tornar o comportamento estrito explícito. Trabalhos Cron que sobrescrevem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`.
- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isto para sobrescritas específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar todo o catálogo de modelos.
- `tts`: sobrescritas opcionais de conversão de texto em fala por agente. O bloco faz mesclagem profunda sobre `messages.tts`; portanto, mantenha credenciais compartilhadas de provedor e política de fallback em `messages.tts` e defina aqui apenas valores específicos da persona, como provedor, voz, modelo, estilo ou modo automático.
- `skills`: lista de permissões opcional de habilidades por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa sem habilidades.
- `thinkingDefault`: nível de pensamento padrão opcional por agente (`off | minimal | low | medium | high | xhigh | adaptive | max`). Sobrescreve `agents.defaults.thinkingDefault` para este agente quando nenhuma sobrescrita por mensagem ou sessão está definida. O perfil de provedor/modelo selecionado controla quais valores são válidos; para Google Gemini, `adaptive` mantém o pensamento dinâmico controlado pelo provedor (`thinkingLevel` omitido no Gemini 3/3.1, `thinkingBudget: -1` no Gemini 2.5).
- `tts`: sobrescritas opcionais de texto para fala por agente. O bloco faz uma mesclagem profunda sobre `messages.tts`, portanto mantenha credenciais compartilhadas do provedor e política de fallback em `messages.tts` e defina aqui apenas valores específicos da persona, como provedor, voz, modelo, estilo ou modo automático.
- `skills`: allowlist opcional de Skills por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa sem Skills.
- `thinkingDefault`: nível de pensamento padrão opcional por agente (`off | minimal | low | medium | high | xhigh | adaptive | max`). Sobrescreve `agents.defaults.thinkingDefault` para este agente quando nenhuma sobrescrita por mensagem ou sessão está definida. O perfil do provedor/modelo selecionado controla quais valores são válidos; para Google Gemini, `adaptive` mantém o pensamento dinâmico de propriedade do provedor (`thinkingLevel` omitido no Gemini 3/3.1, `thinkingBudget: -1` no Gemini 2.5).
- `reasoningDefault`: visibilidade de raciocínio padrão opcional por agente (`on | off | stream`). Sobrescreve `agents.defaults.reasoningDefault` para este agente quando nenhuma sobrescrita de raciocínio por mensagem ou sessão está definida.
- `fastModeDefault`: padrão opcional por agente para modo rápido (`true | false`). Aplica-se quando nenhuma sobrescrita de modo rápido por mensagem ou sessão está definida.
- `agentRuntime`: sobrescrita opcional de política de runtime de baixo nível por agente. Use `{ id: "codex" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback PI padrão no modo `auto`.
- `fastModeDefault`: padrão opcional por agente para o modo rápido (`true | false`). Aplica-se quando nenhuma sobrescrita de modo rápido por mensagem ou sessão está definida.
- `agentRuntime`: sobrescrita opcional por agente da política de runtime de baixo nível. Use `{ id: "codex" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback padrão de PI no modo `auto`.
- `runtime`: descritor de runtime opcional por agente. Use `type: "acp"` com padrões de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar sessões do harness ACP por padrão.
- `identity.avatar`: caminho relativo ao workspace, URL `http(s)` ou URI `data:`.
- `identity` deriva padrões: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`.
- `subagents.allowAgents`: lista de permissões de ids de agente para destinos explícitos de `sessions_spawn.agentId` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). Inclua o id do solicitante quando chamadas de `agentId` direcionadas a si mesmo devem ser permitidas.
- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita destinos que seriam executados sem sandbox.
- `subagents.requireAgentId`: quando verdadeiro, bloqueia chamadas `sessions_spawn` que omitem `agentId` (força a seleção explícita de perfil; padrão: falso).
- `subagents.allowAgents`: allowlist de ids de agentes para alvos explícitos de `sessions_spawn.agentId` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). Inclua o id do solicitante quando chamadas `agentId` direcionadas a si mesmo devem ser permitidas.
- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita alvos que seriam executados sem sandbox.
- `subagents.requireAgentId`: quando true, bloqueia chamadas `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false).
---
@ -1036,27 +1037,27 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multiagente](/p
}
```
### Campos de correspondência de binding
### Campos de correspondência de vínculo
- `type` (opcional): `route` para roteamento normal (tipo ausente usa route por padrão), `acp` para bindings persistentes de conversa ACP.
- `type` (opcional): `route` para roteamento normal (tipo ausente usa route como padrão), `acp` para vínculos persistentes de conversa ACP.
- `match.channel` (obrigatório)
- `match.accountId` (opcional; `*` = qualquer conta; omitido = conta padrão)
- `match.peer` (opcional; `{ kind: direct|group|channel, id }`)
- `match.guildId` / `match.teamId` (opcional; específico do canal)
- `acp` (opcional; apenas para `type: "acp"`): `{ mode, label, cwd, backend }`
- `acp` (opcional; somente para `type: "acp"`): `{ mode, label, cwd, backend }`
**Ordem de correspondência determinística:**
**Ordem determinística de correspondência:**
1. `match.peer`
2. `match.guildId`
3. `match.teamId`
4. `match.accountId` (exato, sem peer/guild/team)
5. `match.accountId: "*"` (em todo o canal)
5. `match.accountId: "*"` (para todo o canal)
6. Agente padrão
Dentro de cada nível, a primeira entrada correspondente em `bindings` prevalece.
Dentro de cada nível, a primeira entrada correspondente em `bindings` vence.
Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de binding de rota acima.
Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de vínculo de rota acima.
### Perfis de acesso por agente
@ -1204,34 +1205,34 @@ Consulte [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-to
<Accordion title="Detalhes dos campos de sessão">
- **`scope`**: estratégia base de agrupamento de sessões para contextos de chat em grupo.
- **`scope`**: estratégia básica de agrupamento de sessões para contextos de conversa em grupo.
- `per-sender` (padrão): cada remetente recebe uma sessão isolada dentro de um contexto de canal.
- `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use somente quando o contexto compartilhado for intencional).
- **`dmScope`**: como DMs são agrupadas.
- `main`: todas as DMs compartilham a sessão principal.
- `per-peer`: isola por id de remetente entre canais.
- `per-peer`: isola por ID do remetente entre canais.
- `per-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada multiusuário).
- `per-account-channel-peer`: isola por conta + canal + remetente (recomendado para múltiplas contas).
- **`identityLinks`**: mapeia ids canônicos para pares com prefixo de provedor para compartilhamento de sessão entre canais. Comandos de acoplamento como `/dock_discord` usam o mesmo mapa para trocar a rota de resposta da sessão ativa para outro par de canal vinculado; consulte [Acoplamento de canais](/pt-BR/concepts/channel-docking).
- **`reset`**: política principal de redefinição. `daily` redefine às `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estiverem configurados, vence o que expirar primeiro. O frescor da redefinição diária usa o `sessionStartedAt` da linha da sessão; o frescor da redefinição por inatividade usa `lastInteractionAt`. Gravações de eventos em segundo plano/sistema, como Heartbeat, despertares de Cron, notificações de exec e escrituração do Gateway, podem atualizar `updatedAt`, mas não mantêm sessões diárias/por inatividade atualizadas.
- **`identityLinks`**: mapeia IDs canônicos para pares com prefixo de provedor para compartilhamento de sessão entre canais. Comandos Dock, como `/dock_discord`, usam o mesmo mapa para alternar a rota de resposta da sessão ativa para outro par de canal vinculado; consulte [Acoplamento de canais](/pt-BR/concepts/channel-docking).
- **`reset`**: política principal de redefinição. `daily` redefine às `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, vence o que expirar primeiro. O frescor de redefinição diária usa o `sessionStartedAt` da linha de sessão; o frescor de redefinição por inatividade usa `lastInteractionAt`. Gravações de eventos de segundo plano/sistema, como Heartbeat, despertares de Cron, notificações de execução e escrituração do Gateway, podem atualizar `updatedAt`, mas não mantêm sessões diárias/por inatividade atualizadas.
- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O `dm` legado é aceito como alias de `direct`.
- **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de chat direto.
- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta entre agentes durante trocas agente-para-agente (inteiro, intervalo: `0`–`5`). `0` desativa o encadeamento de pingue-pongue.
- **`sendPolicy`**: corresponde por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação vence.
- **`maintenance`**: limpeza do armazenamento de sessões + controles de retenção.
- **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de conversa direta.
- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta de volta entre agentes durante trocas agente-para-agente (inteiro, intervalo: `0`–`5`). `0` desativa o encadeamento pingue-pongue.
- **`sendPolicy`**: correspondência por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação vence.
- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessões.
- `mode`: `warn` emite apenas avisos; `enforce` aplica a limpeza.
- `pruneAfter`: limite de idade para entradas obsoletas (padrão `30d`).
- `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). O runtime grava a limpeza em lote com uma pequena margem de nível alto para limites de tamanho de produção; `openclaw sessions cleanup --enforce` aplica o limite imediatamente.
- `rotateBytes`: obsoleto e ignorado; `openclaw doctor --fix` o remove de configurações antigas.
- `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). O runtime grava a limpeza em lote com um pequeno buffer de marca alta para limites de tamanho de produção; `openclaw sessions cleanup --enforce` aplica o limite imediatamente.
- `rotateBytes`: obsoleto e ignorado; `openclaw doctor --fix` o remove de configurações mais antigas.
- `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.<timestamp>`. O padrão é `pruneAfter`; defina como `false` para desativar.
- `maxDiskBytes`: orçamento de disco opcional para o diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos.
- `maxDiskBytes`: orçamento opcional de disco do diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos.
- `highWaterBytes`: alvo opcional após a limpeza de orçamento. O padrão é `80%` de `maxDiskBytes`.
- **`threadBindings`**: padrões globais para recursos de sessão vinculada a thread.
- `enabled`: chave mestra padrão (provedores podem substituir; Discord usa `channels.discord.threadBindings.enabled`)
- `idleHours`: desenfoque automático padrão por inatividade em horas (`0` desativa; provedores podem substituir)
- `enabled`: chave padrão mestre (provedores podem substituir; Discord usa `channels.discord.threadBindings.enabled`)
- `idleHours`: desfoco automático padrão por inatividade em horas (`0` desativa; provedores podem substituir)
- `maxAgeHours`: idade máxima rígida padrão em horas (`0` desativa; provedores podem substituir)
- `spawnSessions`: gate padrão para criar sessões de trabalho vinculadas a thread a partir de `sessions_spawn` e spawns de thread ACP. O padrão é `true` quando vínculos de thread estão ativados; provedores/contas podem substituir.
- `defaultSpawnContext`: contexto padrão de subagente nativo para spawns vinculados a thread (`"fork"` ou `"isolated"`). O padrão é `"fork"`.
- `spawnSessions`: porta padrão para criar sessões de trabalho vinculadas a thread a partir de `sessions_spawn` e spawns de thread ACP. O padrão é `true` quando vínculos de thread estão habilitados; provedores/contas podem substituir.
- `defaultSpawnContext`: contexto nativo padrão de subagente para spawns vinculados a thread (`"fork"` ou `"isolated"`). O padrão é `"fork"`.
</Accordion>
@ -1271,34 +1272,34 @@ Consulte [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-to
Substituições por canal/conta: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
Resolução (a mais específica vence): conta → canal → global. `""` desativa e interrompe a cascata. `"auto"` deriva de `[{identity.name}]`.
Resolução (o mais específico vence): conta → canal → global. `""` desativa e interrompe a cascata. `"auto"` deriva `[{identity.name}]`.
**Variáveis de modelo:**
| Variável | Descrição | Exemplo |
| ----------------- | -------------------------- | --------------------------- |
| `{model}` | Nome curto do modelo | `claude-opus-4-6` |
| `{modelFull}` | Identificador completo do modelo | `anthropic/claude-opus-4-6` |
| `{provider}` | Nome do provedor | `anthropic` |
| `{thinkingLevel}` | Nível de raciocínio atual | `high`, `low`, `off` |
| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) |
| Variável | Descrição | Exemplo |
| ----------------- | --------------------------------- | --------------------------- |
| `{model}` | Nome curto do modelo | `claude-opus-4-6` |
| `{modelFull}` | Identificador completo do modelo | `anthropic/claude-opus-4-6` |
| `{provider}` | Nome do provedor | `anthropic` |
| `{thinkingLevel}` | Nível de raciocínio atual | `high`, `low`, `off` |
| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) |
As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias para `{thinkingLevel}`.
As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias de `{thinkingLevel}`.
### Reação de confirmação
- O padrão é `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina como `""` para desativar.
- Substituições por canal: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback da identidade.
- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback de identidade.
- Escopo: `group-mentions` (padrão), `group-all`, `direct`, `all`.
- `removeAckAfterReply`: remove a confirmação após a resposta em canais compatíveis com reações, como Slack, Discord, Telegram, WhatsApp e BlueBubbles.
- `messages.statusReactions.enabled`: habilita reações de status do ciclo de vida no Slack, Discord e Telegram.
No Slack e no Discord, deixar indefinido mantém as reações de status habilitadas quando as reações de confirmação estão ativas.
No Telegram, defina explicitamente como `true` para habilitar reações de status do ciclo de vida.
- `messages.statusReactions.enabled`: ativa reações de status do ciclo de vida no Slack, Discord e Telegram.
No Slack e no Discord, deixar sem definir mantém as reações de status ativadas quando as reações de confirmação estão ativas.
No Telegram, defina explicitamente como `true` para ativar reações de status do ciclo de vida.
### Debounce de entrada
Agrupa mensagens rápidas somente de texto do mesmo remetente em uma única vez do agente. Mídias/anexos são enviados imediatamente. Comandos de controle ignoram o debounce.
Agrupa mensagens rápidas somente de texto do mesmo remetente em uma única vez do agente. Mídia/anexos são processados imediatamente. Comandos de controle ignoram o debounce.
### TTS (texto para fala)
@ -1348,19 +1349,19 @@ Agrupa mensagens rápidas somente de texto do mesmo remetente em uma única vez
}
```
- `auto` controla o modo automático padrão de TTS: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo.
- `summaryModel` substitui `agents.defaults.model.primary` para o resumo automático.
- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` por padrão (adesão opcional).
- As chaves de API usam fallback para `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`.
- Provedores de fala incluídos são de propriedade do Plugin. Se `plugins.allow` estiver definido, inclua cada Plugin de provedor de TTS que você deseja usar, por exemplo `microsoft` para Edge TTS. O id legado de provedor `edge` é aceito como alias para `microsoft`.
- `auto` controla o modo auto-TTS padrão: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo.
- `summaryModel` substitui `agents.defaults.model.primary` para resumo automático.
- `modelOverrides` é ativado por padrão; `modelOverrides.allowProvider` usa `false` como padrão (participação explícita).
- Chaves de API usam fallback para `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`.
- Os provedores de fala incluídos são de propriedade do Plugin. Se `plugins.allow` estiver definido, inclua cada Plugin provedor de TTS que você quer usar, por exemplo `microsoft` para Edge TTS. O id legado do provedor `edge` é aceito como alias de `microsoft`.
- `providers.openai.baseUrl` substitui o endpoint de TTS da OpenAI. A ordem de resolução é configuração, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`.
- Quando `providers.openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor de TTS compatível com OpenAI e relaxa a validação de modelo/voz.
---
## Fala
## Talk
Padrões para o modo Fala (macOS/iOS/Android).
Padrões do modo Talk (macOS/iOS/Android).
```json5
{
@ -1389,20 +1390,20 @@ Padrões para o modo Fala (macOS/iOS/Android).
}
```
- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Fala estão configurados.
- Chaves legadas planas de Fala (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) existem apenas para compatibilidade e são migradas automaticamente para `talk.providers.<provider>`.
- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Talk estiverem configurados.
- Chaves planas legadas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) existem apenas por compatibilidade e são migradas automaticamente para `talk.providers.<provider>`.
- IDs de voz usam fallback para `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`.
- `providers.*.apiKey` aceita strings em texto claro ou objetos SecretRef.
- O fallback `ELEVENLABS_API_KEY` se aplica somente quando nenhuma chave de API de Fala está configurada.
- `providers.*.voiceAliases` permite que diretivas de Fala usem nomes amigáveis.
- `providers.mlx.modelId` seleciona o repositório do Hugging Face usado pelo helper MLX local do macOS. Se omitido, o macOS usa `mlx-community/Soprano-80M-bf16`.
- A reprodução de MLX no macOS é executada pelo helper `openclaw-mlx-tts` incluído quando presente, ou por um executável no `PATH`; `OPENCLAW_MLX_TTS_BIN` substitui o caminho do helper para desenvolvimento.
- `speechLocale` define o id de localidade BCP 47 usado pelo reconhecimento de fala de Fala no iOS/macOS. Deixe indefinido para usar o padrão do dispositivo.
- `silenceTimeoutMs` controla por quanto tempo o modo Fala espera após o silêncio do usuário antes de enviar a transcrição. Deixar indefinido mantém a janela de pausa padrão da plataforma (`700 ms on macOS and Android, 900 ms on iOS`).
- `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef.
- O fallback `ELEVENLABS_API_KEY` se aplica somente quando nenhuma chave de API de Talk está configurada.
- `providers.*.voiceAliases` permite que diretivas de Talk usem nomes amigáveis.
- `providers.mlx.modelId` seleciona o repositório do Hugging Face usado pelo auxiliar local MLX do macOS. Se omitido, o macOS usa `mlx-community/Soprano-80M-bf16`.
- A reprodução MLX no macOS é executada pelo auxiliar incluído `openclaw-mlx-tts` quando presente, ou por um executável em `PATH`; `OPENCLAW_MLX_TTS_BIN` substitui o caminho do auxiliar para desenvolvimento.
- `speechLocale` define o id de localidade BCP 47 usado pelo reconhecimento de fala do Talk no iOS/macOS. Deixe sem definir para usar o padrão do dispositivo.
- `silenceTimeoutMs` controla por quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Sem definir, mantém a janela de pausa padrão da plataforma (`700 ms on macOS and Android, 900 ms on iOS`).
---
## Relacionados
## Relacionado
- [Referência de configuração](/pt-BR/gateway/configuration-reference) — todas as outras chaves de configuração
- [Configuração](/pt-BR/gateway/configuration) — tarefas comuns e configuração rápida

281
docs/pt-BR/gateway/config-channels.md
View File

@ -1,56 +1,56 @@
---
read_when:
- Configurando um Plugin de canal (autenticação, controle de acesso, várias contas)
- Solução de problemas de chaves de configuração por canal
- Auditoria da política de DM, da política de grupos ou do controle de menções
summary: 'Configuração de canais: controle de acesso, pareamento, chaves por canal no Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e mais'
- Configuração de um Plugin de canal (autenticação, controle de acesso, várias contas)
- Solução de problemas das chaves de configuração por canal
- Auditoria de política de DM, política de grupo ou controle de menções
summary: 'Configuração de canais: controle de acesso, pareamento, chaves por canal no Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e outros'
title: Configuração — canais
x-i18n:
generated_at: "2026-05-03T21:31:16Z"
generated_at: "2026-05-04T05:52:01Z"
model: gpt-5.5
provider: openai
source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c
source_hash: 57dcc0b5148324ea6fdee51b7b6e97ec7bd7dc3ca89518ab0816fe4172feefbc
source_path: gateway/config-channels.md
workflow: 16
---
Chaves de configuração por canal em `channels.*`. Abrange acesso por DM e em grupos,
configurações de várias contas, controle por menção e chaves por canal para Slack, Discord,
Chaves de configuração por canal em `channels.*`. Abrange acesso por DM e grupos,
configurações multi-conta, controle por menção e chaves por canal para Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage e os outros plugins de canal incluídos.
Para agentes, ferramentas, runtime do gateway e outras chaves de nível superior, consulte
Para agentes, ferramentas, runtime do Gateway e outras chaves de nível superior, consulte
[Referência de configuração](/pt-BR/gateway/configuration-reference).
## Canais
Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`).
### Acesso por DM e em grupos
### Acesso por DM e grupos
Todos os canais aceitam políticas de DM e políticas de grupo:
Todos os canais oferecem suporte a políticas de DM e políticas de grupo:
| Política de DM | Comportamento |
| ------------------- | -------------------------------------------------------------- |
| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar |
| `allowlist` | Somente remetentes em `allowFrom` (ou no armazenamento de permissões pareado) |
| `open` | Permite todas as DMs de entrada (requer `allowFrom: ["*"]`) |
| `disabled` | Ignora todas as DMs de entrada |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (default) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar |
| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permissões pareado) |
| `open` | Permite todas as DMs de entrada (requer `allowFrom: ["*"]`) |
| `disabled` | Ignora todas as DMs de entrada |
| Política de grupo | Comportamento |
| --------------------- | -------------------------------------------------------- |
| `allowlist` (padrão) | Somente grupos que correspondem à lista de permissões configurada |
| `open` | Ignora listas de permissões de grupo (controle por menção ainda se aplica) |
| `disabled` | Bloqueia todas as mensagens de grupo/sala |
| Política de grupo | Comportamento |
| --------------------- | ------------------------------------------------------ |
| `allowlist` (default) | Apenas grupos que correspondem à lista de permissões configurada |
| `open` | Ignora listas de permissões de grupo (o controle por menção ainda se aplica) |
| `disabled` | Bloqueia todas as mensagens de grupo/sala |
<Note>
`channels.defaults.groupPolicy` define o padrão quando o `groupPolicy` de um provedor não está definido.
Os códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento por DM são limitadas a **3 por canal**.
Se um bloco de provedor estiver totalmente ausente (`channels.<provider>` ausente), a política de grupo em runtime volta para `allowlist` (falha fechada) com um aviso na inicialização.
Códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento por DM são limitadas a **3 por canal**.
Se um bloco de provedor estiver totalmente ausente (`channels.<provider>` ausente), a política de grupo em runtime volta para `allowlist` (falha fechada) com um aviso de inicialização.
</Note>
### Substituições de modelo por canal
Use `channels.modelByChannel` para fixar IDs de canais específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal se aplica quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`).
Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal é aplicado quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`).
```json5
{
@ -73,7 +73,7 @@ Use `channels.modelByChannel` para fixar IDs de canais específicos a um modelo.
### Padrões de canal e Heartbeat
Use `channels.defaults` para comportamento compartilhado de política de grupo e Heartbeat entre provedores:
Use `channels.defaults` para políticas de grupo e comportamento de Heartbeat compartilhados entre provedores:
```json5
{
@ -92,14 +92,14 @@ Use `channels.defaults` para comportamento compartilhado de política de grupo e
```
- `channels.defaults.groupPolicy`: política de grupo de fallback quando um `groupPolicy` no nível do provedor não está definido.
- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto citado/de thread/histórico), `allowlist` (inclui apenas contexto de remetentes na lista de permissões), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: inclui status de canais saudáveis na saída de Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída de Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderiza saída de Heartbeat compacta em estilo de indicador.
- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto de citações/threads/histórico), `allowlist` (inclui apenas contexto de remetentes permitidos), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: inclui status de canais saudáveis na saída de heartbeat.
- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/de erro na saída de heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderiza saída de heartbeat compacta em estilo de indicador.
### WhatsApp
WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada.
O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada.
```json5
{
@ -137,7 +137,7 @@ WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticament
}
```
<Accordion title="WhatsApp com várias contas">
<Accordion title="WhatsApp multi-conta">
```json5
{
@ -155,8 +155,8 @@ WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticament
}
```
- Comandos de saída usam a conta `default` por padrão, se presente; caso contrário, o primeiro id de conta configurado (ordenado).
- `channels.whatsapp.defaultAccount` opcional substitui essa seleção de conta padrão de fallback quando corresponde a um id de conta configurado.
- Comandos de saída usam a conta `default` por padrão, se ela existir; caso contrário, usam o primeiro ID de conta configurado (ordenado).
- `channels.whatsapp.defaultAccount` opcional substitui essa seleção de conta padrão de fallback quando corresponde a um ID de conta configurado.
- O diretório de autenticação legado de conta única do Baileys é migrado por `openclaw doctor` para `whatsapp/default`.
- Substituições por conta: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
@ -218,13 +218,13 @@ WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticament
```
- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão.
- `apiRoot` é apenas a raiz da Telegram Bot API. Use `https://api.telegram.org` ou sua raiz auto-hospedada/proxy, não `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` remove um sufixo final acidental `/bot<TOKEN>`.
- `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um id de conta configurado.
- Em configurações de várias contas (2+ ids de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento de fallback; `openclaw doctor` avisa quando isso está ausente ou inválido.
- `apiRoot` é apenas a raiz da API Bot do Telegram. Use `https://api.telegram.org` ou sua raiz auto-hospedada/de proxy, não `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` remove um sufixo `/bot<TOKEN>` acidental ao final.
- `channels.telegram.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado.
- Em configurações multi-conta (2+ IDs de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento de fallback; `openclaw doctor` avisa quando isso está ausente ou inválido.
- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, `/config set|unset`).
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para tópicos de fórum (use o `chatId:topic:topicId` canônico em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#persistent-channel-bindings).
- Pré-visualizações de stream do Telegram usam `sendMessage` + `editMessageText` (funciona em conversas diretas e grupos).
- Política de repetição: consulte [Política de repetição](/pt-BR/concepts/retry).
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#persistent-channel-bindings).
- Pré-visualizações de stream do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo).
- Política de nova tentativa: consulte [Política de nova tentativa](/pt-BR/concepts/retry).
### Discord
@ -332,38 +332,38 @@ WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticament
- Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão.
- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de nova tentativa/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo.
- `channels.discord.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
- Use `user:<id>` (DM) ou `channel:<id>` (canal da guilda) para destinos de entrega; IDs numéricos sem prefixo são rejeitados.
- Use `user:<id>` (DM) ou `channel:<id>` (canal de guilda) para destinos de entrega; IDs numéricos sem prefixo são rejeitados.
- Slugs de guilda ficam em minúsculas, com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guilda.
- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar somente mensagens de bots que mencionem o bot (mensagens próprias ainda são filtradas).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (e substituições de canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here).
- `channels.discord.mentionAliases` mapeia texto `@handle` estável de saída para IDs de usuários do Discord antes do envio, para que colegas conhecidos possam ser mencionados de forma determinística mesmo quando o cache transitório de diretório estiver vazio. Substituições por conta ficam em `channels.discord.accounts.<accountId>.mentionAliases`.
- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bots que mencionem o bot (as próprias mensagens ainda são filtradas).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (e substituições por canal) descarta mensagens que mencionam outro usuário ou função, mas não o bot (excluindo @everyone/@here).
- `channels.discord.mentionAliases` mapeia texto `@handle` estável de saída para IDs de usuário do Discord antes do envio, para que colegas de equipe conhecidos possam ser mencionados de forma determinística mesmo quando o cache transitório de diretório estiver vazio. Substituições por conta ficam em `channels.discord.accounts.<accountId>.mentionAliases`.
- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando estão abaixo de 2000 caracteres.
- `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord:
- `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados)
- `idleHours`: substituição do Discord para desfocar automaticamente por inatividade em horas (`0` desabilita)
- `idleHours`: substituição do Discord para auto-unfocus por inatividade em horas (`0` desabilita)
- `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desabilita)
- `spawnSessions`: alternância para `sessions_spawn({ thread: true })` e criação/vinculação automática de thread por ACP thread-spawn (padrão: `true`)
- `spawnSessions`: alternância para `sessions_spawn({ thread: true })` e criação/vinculação automática de thread em ACP thread-spawn (padrão: `true`)
- `defaultSpawnContext`: contexto nativo de subagente para spawns vinculados a thread (`"fork"` por padrão)
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para canais e threads (use o id do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#persistent-channel-bindings).
- `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres v2 de componentes do Discord.
- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + LLM + TTS. Configurações do Discord somente texto deixam voz desativada por padrão; defina `channels.discord.voice.enabled=true` para optar por habilitar.
- `channels.discord.voice.model` substitui opcionalmente o modelo LLM usado para respostas em canais de voz do Discord.
- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de autoentrada + LLM + TTS. Configurações do Discord somente texto deixam voz desativada por padrão; defina `channels.discord.voice.enabled=true` para optar por ativar.
- `channels.discord.voice.model` substitui opcionalmente o modelo LLM usado para respostas de canal de voz do Discord.
- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` são repassados para as opções DAVE de `@discordjs/voice` (`true` e `24` por padrão).
- `channels.discord.voice.connectTimeoutMs` controla a espera inicial por Ready de `@discordjs/voice` para tentativas de `/vc join` e entrada automática (`30000` por padrão).
- `channels.discord.voice.reconnectGraceMs` controla quanto tempo uma sessão de voz desconectada pode levar para entrar em sinalização de reconexão antes que o OpenClaw a destrua (`15000` por padrão).
- O OpenClaw também tenta recuperar recebimento de voz saindo e entrando novamente em uma sessão de voz após falhas repetidas de descriptografia.
- `channels.discord.streaming` é a chave canônica do modo de stream. Valores legados `streamMode` e booleanos `streaming` são migrados automaticamente.
- `channels.discord.voice.connectTimeoutMs` controla a espera inicial Ready de `@discordjs/voice` para `/vc join` e tentativas de autoentrada (`30000` por padrão).
- `channels.discord.voice.reconnectGraceMs` controla por quanto tempo uma sessão de voz desconectada pode levar para entrar em sinalização de reconexão antes que o OpenClaw a destrua (`15000` por padrão).
- O OpenClaw também tenta recuperar o recebimento de voz saindo/reentrando em uma sessão de voz após falhas repetidas de descriptografia.
- `channels.discord.streaming` é a chave canônica do modo de stream. Valores legados de `streamMode` e `streaming` booleano são migrados automaticamente.
- `channels.discord.autoPresence` mapeia a disponibilidade de runtime para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status.
- `channels.discord.dangerouslyAllowNameMatching` reabilita correspondência mutável por nome/tag (modo de compatibilidade de emergência).
- `channels.discord.dangerouslyAllowNameMatching` reabilita correspondência mutável de nome/tag (modo de compatibilidade break-glass).
- `channels.discord.execApprovals`: entrega de aprovação de exec nativa do Discord e autorização de aprovadores.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando aprovadores podem ser resolvidos de `approvers` ou `commands.ownerAllowFrom`.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo auto, aprovações de exec são ativadas quando aprovadores podem ser resolvidos de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuários do Discord autorizados a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido.
- `agentFilter`: lista de permissões opcional de IDs de agentes. Omita para encaminhar aprovações para todos os agentes.
- `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex).
- `target`: para onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs dos aprovadores, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos.
- `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, negação ou timeout.
**Modos de notificação de reação:** `off` (nenhuma), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds.<id>.users` em todas as mensagens).
**Modos de notificação por reação:** `off` (nenhuma), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds.<id>.users` em todas as mensagens).
### Google Chat
@ -398,7 +398,7 @@ WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticament
- SecretRef de conta de serviço também é compatível (`serviceAccountRef`).
- Fallbacks de env: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Use `spaces/<spaceId>` ou `users/<userId>` para destinos de entrega.
- `channels.googlechat.dangerouslyAllowNameMatching` reabilita correspondência mutável por principal de e-mail (modo de compatibilidade de emergência).
- `channels.googlechat.dangerouslyAllowNameMatching` reabilita correspondência mutável de principal de e-mail (modo de compatibilidade break-glass).
### Slack
@ -470,44 +470,35 @@ WhatsApp roda pelo canal web do gateway (Baileys Web). Ele inicia automaticament
}
```
- **Modo Socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback de env da conta padrão).
- **Modo HTTP** requer `botToken` mais `signingSecret` (na raiz ou por conta).
- `socketMode` repassa o ajuste de transporte do Socket Mode do SDK do Slack para a API pública do receiver Bolt. Use somente ao investigar timeout de ping/pong ou comportamento de websocket obsoleto.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples
ou objetos SecretRef.
- Snapshots de conta do Slack expõem campos de origem/status por credencial, como
`botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP,
`signingSecretStatus`. `configured_unavailable` significa que a conta está
configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu
resolver o valor do segredo.
- **Modo socket** exige `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback de env da conta padrão).
- **Modo HTTP** exige `botToken` mais `signingSecret` (na raiz ou por conta).
- `socketMode` repassa ajustes de transporte Socket Mode do SDK do Slack para a API pública do receptor Bolt. Use apenas ao investigar timeout de ping/pong ou comportamento de websocket obsoleto.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto puro ou objetos SecretRef.
- Snapshots de conta Slack expõem campos de origem/status por credencial, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que a conta está configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo.
- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Slack.
- `channels.slack.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Valores legados `streamMode`, booleanos `streaming` e `nativeStreaming` são migrados automaticamente.
- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Valores legados de `streamMode`, `streaming` booleano e `nativeStreaming` são migrados automaticamente.
- Use `user:<id>` (DM) ou `channel:<id>` para destinos de entrega.
**Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
**Modos de notificação por reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
**Isolamento de sessão de thread:** `thread.historyScope` é por thread (padrão) ou compartilhado no canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads.
**Isolamento de sessão de thread:** `thread.historyScope` é por thread (padrão) ou compartilhado pelo canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads.
- Streaming nativo do Slack mais o status de thread no estilo assistente do Slack "está digitando..." exigem um destino de thread de resposta. DMs de nível superior permanecem fora de threads por padrão, então ainda podem transmitir por meio de prévias de rascunho publicar-e-editar do Slack em vez de mostrar a prévia nativa de stream/status no estilo thread.
- `typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto uma resposta está em execução, depois a remove ao concluir. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo esquema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuários do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`).
- Streaming nativo do Slack mais o status de thread "is typing..." no estilo do assistente do Slack exigem um destino de thread de resposta. DMs de nível superior ficam fora de thread por padrão, então ainda podem transmitir por prévias de rascunho postar-e-editar do Slack em vez de mostrar a prévia de stream/status nativa no estilo de thread.
- `typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto uma resposta está em execução, depois a remove ao concluir. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo schema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`).
| Grupo de ações | Padrão | Observações |
| -------------- | ------ | ----------------------- |
| reactions | habilitado | Reagir + listar reações |
| Grupo de ações | Padrão | Observações |
| -------------- | --------- | ------------------------ |
| reactions | habilitado | Reagir + listar reações |
| messages | habilitado | Ler/enviar/editar/excluir |
| pins | habilitado | Fixar/desafixar/listar |
| memberInfo | habilitado | Informações do membro |
| emojiList | habilitado | Lista de emojis personalizados |
| pins | habilitado | Fixar/desafixar/listar |
| memberInfo | habilitado | Informações de membro |
| emojiList | habilitado | Lista de emojis customizados |
### Mattermost
O Mattermost é distribuído como um Plugin incluído nas versões atuais do OpenClaw. Builds mais antigos ou
personalizados podem instalar um pacote npm atual com
`openclaw plugins install @openclaw/mattermost`. Consulte
[npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost)
para ver as dist-tags atuais antes de fixar uma versão.
Mattermost é enviado como um plugin empacotado nas versões atuais do OpenClaw. Builds mais antigos ou customizados podem instalar um pacote npm atual com `openclaw plugins install @openclaw/mattermost`. Confira [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) para as dist-tags atuais antes de fixar uma versão.
```json5
{
@ -537,23 +528,23 @@ para ver as dist-tags atuais antes de fixar uma versão.
}
```
Modos de chat: `oncall` (responde em @-menção, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com prefixo de acionamento).
Modos de chat: `oncall` (responde a @-menção, padrão), `onmessage` (toda mensagem), `onchar` (mensagens iniciadas com prefixo de acionamento).
Quando comandos nativos do Mattermost estão habilitados:
Quando os comandos nativos do Mattermost estão habilitados:
- `commands.callbackPath` deve ser um caminho (por exemplo, `/api/channels/mattermost/command`), não uma URL completa.
- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e ser acessível pelo servidor Mattermost.
- Callbacks slash nativos são autenticados com os tokens por comando retornados
pelo Mattermost durante o registro de comandos slash. Se o registro falhar ou nenhum
- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e estar acessível a partir do servidor Mattermost.
- Callbacks nativos de barra são autenticados com os tokens por comando retornados
pelo Mattermost durante o registro do comando de barra. Se o registro falhar ou nenhum
comando for ativado, o OpenClaw rejeita callbacks com
`Unauthorized: invalid command token.`
- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que
`ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio de callback.
Use valores de host/domínio, não URLs completas.
- `channels.mattermost.configWrites`: permite ou nega gravações de configuração iniciadas pelo Mattermost.
- `channels.mattermost.requireMention`: exige `@menção` antes de responder em canais.
- `channels.mattermost.requireMention`: exige `@mention` antes de responder em canais.
- `channels.mattermost.groups.<channelId>.requireMention`: substituição por canal do controle por menção (`"*"` para o padrão).
- `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- O `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
### Signal
@ -578,7 +569,7 @@ Quando comandos nativos do Mattermost estão habilitados:
- `channels.signal.account`: fixa a inicialização do canal a uma identidade de conta específica do Signal.
- `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal.
- `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- O `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
### BlueBubbles
@ -597,8 +588,8 @@ BlueBubbles é o caminho recomendado para iMessage (baseado em Plugin, configura
}
```
- Principais caminhos de chave abordados aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Caminhos de chaves principais abordados aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- O `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Entradas de nível superior `bindings[]` com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador do BlueBubbles ou uma string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#persistent-channel-bindings).
- A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles).
@ -628,13 +619,13 @@ O OpenClaw inicia `imsg rpc` (JSON-RPC por stdio). Nenhum daemon ou porta é nec
}
```
- `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- O `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Requer Full Disk Access ao banco de dados do Messages.
- Requer Acesso Total ao Disco ao banco de dados do Messages.
- Prefira destinos `chat_id:<id>`. Use `imsg chats --limit 20` para listar chats.
- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos via SCP.
- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`).
- O SCP usa verificação rigorosa de chave de host, portanto garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`.
- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos de entrada (padrão: `/Users/*/Library/Messages/Attachments`).
- O SCP usa verificação rigorosa de chave de host, então garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: permite ou nega gravações de configuração iniciadas pelo iMessage.
- Entradas de nível superior `bindings[]` com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou um destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#persistent-channel-bindings).
@ -682,17 +673,17 @@ Matrix é baseado em Plugin e configurado em `channels.matrix`.
- Autenticação por token usa `accessToken`; autenticação por senha usa `userId` + `password`.
- `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e esta adesão de rede são controles independentes.
- `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com múltiplas contas.
- `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas.
- `channels.matrix.autoJoin` usa `off` como padrão, então salas convidadas e novos convites no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`.
- `channels.matrix.execApprovals`: entrega de aprovação de execução nativa do Matrix e autorização de aprovadores.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de execução são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de execução.
- `channels.matrix.execApprovals`: entrega de aprovações de execução nativa do Matrix e autorização de aprovadores.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de execução são ativadas quando aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário do Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de execução.
- `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex).
- `target`: para onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`.
- Substituições por conta: `channels.matrix.accounts.<id>.execApprovals`.
- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha por peer roteado, enquanto `per-room` isola cada sala de DM.
- Sondagens de status do Matrix e consultas de diretório ao vivo usam a mesma política de proxy que o tráfego em tempo de execução.
- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha pelo par roteado, enquanto `per-room` isola cada sala de DM.
- Sondas de status do Matrix e consultas de diretório ao vivo usam a mesma política de proxy do tráfego em tempo de execução.
- A configuração completa do Matrix, regras de direcionamento e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix).
### Microsoft Teams
@ -712,7 +703,7 @@ Microsoft Teams é baseado em Plugin e configurado em `channels.msteams`.
}
```
- Principais caminhos de chave abordados aqui: `channels.msteams`, `channels.msteams.configWrites`.
- Caminhos de chaves principais abordados aqui: `channels.msteams`, `channels.msteams.configWrites`.
- A configuração completa do Teams (credenciais, Webhook, política de DM/grupo, substituições por equipe/por canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams).
### IRC
@ -738,13 +729,13 @@ IRC é baseado em Plugin e configurado em `channels.irc`.
}
```
- Principais caminhos de chave abordados aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Caminhos de chaves principais abordados aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- O `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/controle por menção) está documentada em [IRC](/pt-BR/channels/irc).
### Múltiplas contas (todos os canais)
### Várias contas (todos os canais)
Execute múltiplas contas por canal (cada uma com seu próprio `accountId`):
Execute várias contas por canal (cada uma com seu próprio `accountId`):
```json5
{
@ -766,12 +757,12 @@ Execute múltiplas contas por canal (cada uma com seu próprio `accountId`):
```
- `default` é usado quando `accountId` é omitido (CLI + roteamento).
- Tokens de ambiente se aplicam apenas à conta **default**.
- Configurações básicas do canal se aplicam a todas as contas, a menos que sejam substituídas por conta.
- Tokens de env se aplicam apenas à conta **padrão**.
- Configurações base do canal se aplicam a todas as contas, a menos que sejam substituídas por conta.
- Use `bindings[].match.accountId` para rotear cada conta para um agente diferente.
- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de nível superior com uma única conta, o OpenClaw primeiro promove valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels.<channel>.accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Vinculações existentes somente de canal (sem `accountId`) continuam correspondendo à conta padrão; vinculações com escopo de conta permanecem opcionais.
- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Se você adicionar uma conta que não seja a padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de nível superior com uma única conta, o OpenClaw primeiro promove os valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels.<channel>.accounts.default`; o Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Vinculações existentes apenas de canal (sem `accountId`) continuam correspondendo à conta padrão; vinculações com escopo de conta permanecem opcionais.
- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um destino nomeado/padrão correspondente existente.
### Outros canais de Plugin
@ -780,19 +771,25 @@ Veja o índice completo de canais: [Canais](/pt-BR/channels).
### Controle por menção em chats de grupo
Mensagens de grupo usam como padrão **exigir menção** (menção por metadados ou padrões regex seguros). Aplica-se a chats de grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage.
Mensagens de grupo usam por padrão **exigir menção** (menção de metadados ou padrões regex seguros). Aplica-se a chats de grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage.
Respostas visíveis são controladas separadamente. Salas de grupo/canal usam `messages.groupChat.visibleReplies: "message_tool"` como padrão: o OpenClaw ainda processa a interação, mas respostas finais normais permanecem privadas e a saída visível na sala exige `message(action=send)`. Defina `"automatic"` somente quando quiser o comportamento legado em que respostas normais são publicadas de volta na sala. Para aplicar o mesmo comportamento de resposta visível somente por ferramenta também a chats diretos, defina `messages.visibleReplies: "message_tool"`; o harness do Codex também usa esse comportamento somente por ferramenta como padrão não definido para chats diretos.
Respostas visíveis são controladas separadamente. Salas de grupo/canal usam por padrão `messages.groupChat.visibleReplies: "message_tool"`: o OpenClaw ainda processa o turno, mas respostas finais normais permanecem privadas e a saída visível na sala exige `message(action=send)`. Defina `"automatic"` apenas quando você quiser o comportamento legado em que respostas normais são publicadas de volta na sala. Para aplicar o mesmo comportamento de resposta visível apenas por ferramenta também a chats diretos, defina `messages.visibleReplies: "message_tool"`; o harness do Codex também usa esse comportamento apenas por ferramenta como padrão indefinido para chats diretos.
Se a ferramenta de mensagem estiver indisponível sob a política de ferramentas ativa, o OpenClaw recorre a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. `openclaw doctor` avisa sobre essa incompatibilidade.
Respostas visíveis apenas por ferramenta exigem um modelo/runtime que chame ferramentas de forma confiável. Se
o log da sessão mostra texto do assistente com `didSendViaMessagingTool: false`, o
modelo produziu uma resposta final privada em vez de chamar a ferramenta de mensagens.
Mude para um modelo mais forte em chamada de ferramentas para esse canal, ou defina
`messages.groupChat.visibleReplies: "automatic"` para restaurar as respostas finais visíveis legadas.
O Gateway recarrega a configuração de `messages` a quente depois que o arquivo é salvo. Reinicie somente quando a observação de arquivos ou o recarregamento de configuração estiver desabilitado na implantação.
Se a ferramenta de mensagens estiver indisponível sob a política de ferramentas ativa, o OpenClaw recorre a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. `openclaw doctor` avisa sobre essa incompatibilidade.
O Gateway recarrega a configuração `messages` a quente depois que o arquivo é salvo. Reinicie apenas quando o monitoramento de arquivos ou a recarga de configuração estiver desativado na implantação.
**Tipos de menção:**
- **Menções por metadados**: @menções nativas da plataforma. Ignoradas no modo de autochat do WhatsApp.
- **Menções de metadados**: menções com @ nativas da plataforma. Ignoradas no modo de chat consigo mesmo do WhatsApp.
- **Padrões de texto**: padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetição aninhada insegura são ignorados.
- O controle por menção é aplicado somente quando a detecção é possível (menções nativas ou pelo menos um padrão).
- A exigência por menção é aplicada somente quando a detecção é possível (menções nativas ou pelo menos um padrão).
```json5
{
@ -809,9 +806,9 @@ O Gateway recarrega a configuração de `messages` a quente depois que o arquivo
}
```
`messages.groupChat.historyLimit` define o padrão global. Os canais podem substituir com `channels.<channel>.historyLimit` (ou por conta). Defina `0` para desativar.
`messages.groupChat.historyLimit` define o padrão global. Os canais podem substituir com `channels.<channel>.historyLimit` (ou por conta). Defina como `0` para desativar.
`messages.visibleReplies` é o padrão global de turno de origem; `messages.groupChat.visibleReplies` o substitui para turnos de origem em grupo/canal. Quando `messages.visibleReplies` não está definido, um harness pode fornecer seu próprio padrão direto/de origem; o harness Codex usa `message_tool` como padrão. As listas de permissão de canais e o controle por menção ainda decidem se um turno é processado.
`messages.visibleReplies` é o padrão global para turnos de origem; `messages.groupChat.visibleReplies` o substitui para turnos de origem de grupo/canal. Quando `messages.visibleReplies` não está definido, um harness pode fornecer seu próprio padrão direto/de origem; o harness Codex usa `message_tool` por padrão. Listas de permissões de canal e exigência por menção ainda decidem se um turno é processado.
#### Limites de histórico de DM
@ -830,11 +827,11 @@ O Gateway recarrega a configuração de `messages` a quente depois que o arquivo
Resolução: substituição por DM → padrão do provedor → sem limite (tudo retido).
Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
Compatível: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Modo de conversa consigo mesmo
#### Modo de chat consigo mesmo
Inclua seu próprio número em `allowFrom` para ativar o modo de conversa consigo mesmo (ignora @menções nativas, responde apenas a padrões de texto):
Inclua seu próprio número em `allowFrom` para ativar o modo de chat consigo mesmo (ignora menções com @ nativas, responde apenas a padrões de texto):
```json5
{
@ -884,32 +881,32 @@ Inclua seu próprio número em `allowFrom` para ativar o modo de conversa consig
<Accordion title="Detalhes dos comandos">
- Este bloco configura superfícies de comando. Para o catálogo atual de comandos integrados + empacotados, consulte [Comandos de barra](/pt-BR/tools/slash-commands).
- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memória `/dreaming`, controle de telefone `/phone` e Talk `/voice`, estão documentados nas páginas de seus canais/plugins mais [Comandos de barra](/pt-BR/tools/slash-commands).
- Comandos de texto devem ser mensagens **independentes** com `/` inicial.
- Este bloco configura superfícies de comando. Para o catálogo atual de comandos integrados + empacotados, consulte [Comandos Slash](/pt-BR/tools/slash-commands).
- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, emparelhamento de dispositivos `/pair`, memória `/dreaming`, controle de telefone `/phone` e Talk `/voice`, são documentados nas páginas dos respectivos canais/plugins e em [Comandos Slash](/pt-BR/tools/slash-commands).
- Comandos de texto devem ser mensagens **independentes** com `/` no início.
- `native: "auto"` ativa comandos nativos para Discord/Telegram, deixa Slack desativado.
- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram, deixa Slack desativado.
- Substitua por canal: `channels.discord.commands.native` (bool ou `"auto"`). Para Discord, `false` ignora o registro e a limpeza de comandos nativos durante a inicialização.
- Substitua o registro de Skills nativas por canal com `channels.<provider>.commands.nativeSkills`.
- `channels.telegram.customCommands` adiciona entradas extras ao menu do bot Telegram.
- `bash: true` ativa `! <cmd>` para o shell do host. Exige `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.<channel>`.
- `config: true` ativa `/config` (lê/grava `openclaw.json`). Para clientes Gateway `chat.send`, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes operadores normais com escopo de gravação.
- `mcp: true` ativa `/mcp` para a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`.
- `plugins: true` ativa `/plugins` para descoberta, instalação e controles de ativação/desativação de plugins.
- `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram.
- `bash: true` ativa `! <cmd>` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.<channel>`.
- `config: true` ativa `/config` (lê/grava `openclaw.json`). Para clientes Gateway `chat.send`, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes operadores normais com escopo de escrita.
- `mcp: true` ativa `/mcp` para configuração de servidor MCP gerenciado pelo OpenClaw em `mcp.servers`.
- `plugins: true` ativa `/plugins` para descoberta, instalação e controles de ativar/desativar plugins.
- `channels.<provider>.configWrites` controla mutações de configuração por canal (padrão: true).
- Para canais de múltiplas contas, `channels.<provider>.accounts.<id>.configWrites` também controla gravações direcionadas a essa conta (por exemplo, `/allowlist --config --account <id>` ou `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` desativa `/restart` e ações da ferramenta de reinicialização do Gateway. Padrão: `true`.
- `ownerAllowFrom` é a lista de permissão explícita de proprietários para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`.
- `ownerDisplay: "hash"` aplica hash aos ids de proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing.
- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissão/pareamento do canal e `useAccessGroups` são ignorados).
- `useAccessGroups: false` permite que comandos ignorem políticas de grupos de acesso quando `allowFrom` não está definido.
- Para canais com várias contas, `channels.<provider>.accounts.<id>.configWrites` também controla gravações direcionadas a essa conta (por exemplo, `/allowlist --config --account <id>` ou `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` desativa `/restart` e ações da ferramenta de reinício do Gateway. Padrão: `true`.
- `ownerAllowFrom` é a lista de permissões explícita do proprietário para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`.
- `ownerDisplay: "hash"` gera hash dos ids de proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hash.
- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissões/emparelhamento de canal e `useAccessGroups` são ignorados).
- `useAccessGroups: false` permite que comandos contornem políticas de grupos de acesso quando `allowFrom` não está definido.
- Mapa da documentação de comandos:
- catálogo integrado + empacotado: [Comandos de barra](/pt-BR/tools/slash-commands)
- catálogo integrado + empacotado: [Comandos Slash](/pt-BR/tools/slash-commands)
- superfícies de comando específicas de canal: [Canais](/pt-BR/channels)
- comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot)
- comandos de pareamento: [Pareamento](/pt-BR/channels/pairing)
- comando de card LINE: [LINE](/pt-BR/channels/line)
- Dreaming da memória: [Dreaming](/pt-BR/concepts/dreaming)
- comandos de emparelhamento: [Emparelhamento](/pt-BR/channels/pairing)
- comando de cartão LINE: [LINE](/pt-BR/channels/line)
- Dreaming de memória: [Dreaming](/pt-BR/concepts/dreaming)
</Accordion>

41
docs/pt-BR/gateway/configuration-examples.md
View File

@ -3,18 +3,18 @@ read_when:
- Aprendendo a configurar o OpenClaw
- Procurando exemplos de configuração
- Configurando o OpenClaw pela primeira vez
summary: Exemplos de configuração compatíveis com o schema para configurações comuns do OpenClaw
summary: Exemplos de configuração precisos em relação ao esquema para configurações comuns do OpenClaw
title: Exemplos de configuração
x-i18n:
generated_at: "2026-04-30T09:47:39Z"
generated_at: "2026-05-04T05:52:46Z"
model: gpt-5.5
provider: openai
source_hash: 8bc1f8877bc635d6e3aafd911852d61e71fa08de9144751209542fd67c70f0ba
source_hash: 60c8c2d731f8dce93c4d14657041d72043bc36e3d71ab6cb13c02993ba90dbe3
source_path: gateway/configuration-examples.md
workflow: 16
---
Os exemplos abaixo estão alinhados ao esquema de configuração atual. Para a referência completa e observações por campo, consulte [Configuração](/pt-BR/gateway/configuration).
Os exemplos abaixo estão alinhados ao schema de configuração atual. Para a referência exaustiva e observações por campo, consulte [Configuração](/pt-BR/gateway/configuration).
## Início rápido
@ -27,9 +27,9 @@ Os exemplos abaixo estão alinhados ao esquema de configuração atual. Para a r
}
```
Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma DM para o bot a partir desse número.
Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma mensagem direta ao bot a partir desse número.
### Configuração inicial recomendada
### Ponto de partida recomendado
```json5
{
@ -59,7 +59,7 @@ Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma DM para o bot a
## Exemplo expandido (principais opções)
> JSON5 permite usar comentários e vírgulas finais. JSON normal também funciona.
> JSON5 permite usar comentários e vírgulas finais. JSON comum também funciona.
```json5
{
@ -256,6 +256,7 @@ Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma DM para o bot a
skills: ["github", "weather"], // inherited by agents that omit list[].skills
thinkingDefault: "low",
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
blockStreamingDefault: "off",
@ -472,7 +473,7 @@ Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma DM para o bot a
## Padrões comuns
### Linha de base de Skills compartilhada com uma substituição
### Linha de base compartilhada de skill com uma substituição
```json5
{
@ -491,7 +492,7 @@ Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma DM para o bot a
- `agents.defaults.skills` é a linha de base compartilhada.
- `agents.list[].skills` substitui essa linha de base para um agente.
- Use `skills: []` quando um agente não deve ver Skills.
- Use `skills: []` quando um agente não deve ver nenhuma Skills.
### Configuração multiplataforma
@ -514,11 +515,11 @@ Salve em `~/.openclaw/openclaw.json` e você poderá enviar uma DM para o bot a
}
```
### Aprovação automática de rede de nós confiáveis
### Aprovação automática de rede de Node confiável
Mantenha o pareamento de dispositivos manual, a menos que você controle o caminho da rede. Para um
laboratório dedicado ou uma sub-rede tailnet, você pode optar pela aprovação automática
de dispositivos de nó na primeira vez com CIDRs ou IPs exatos:
Mantenha o emparelhamento de dispositivos manual, a menos que você controle o caminho de rede. Para um laboratório dedicado
ou uma sub-rede tailnet, você pode optar pela aprovação automática de dispositivos Node
na primeira vez com CIDRs ou IPs exatos:
```json5
{
@ -532,13 +533,13 @@ de dispositivos de nó na primeira vez com CIDRs ou IPs exatos:
}
```
Isso permanece desativado quando não configurado. Aplica-se apenas a pareamentos `role: node` novos, sem
escopos solicitados. Clientes operadores/navegador e upgrades de função, escopo, metadados ou
Isso permanece desativado quando não configurado. Aplica-se apenas a emparelhamentos novos com `role: node`
sem escopos solicitados. Clientes operador/navegador e upgrades de função, escopo, metadados ou
chave pública ainda exigem aprovação manual.
### Modo DM seguro (caixa de entrada compartilhada / DMs multiusuário)
### Modo de DM seguro (caixa de entrada compartilhada / DMs multiusuário)
Se mais de uma pessoa puder enviar DM para o seu bot (várias entradas em `allowFrom`, aprovações de pareamento para várias pessoas ou `dmPolicy: "open"`), ative o **modo DM seguro** para que DMs de remetentes diferentes não compartilhem um contexto por padrão:
Se mais de uma pessoa puder enviar DM para seu bot (várias entradas em `allowFrom`, aprovações de emparelhamento para várias pessoas ou `dmPolicy: "open"`), ative o **modo de DM seguro** para que DMs de remetentes diferentes não compartilhem um contexto por padrão:
```json5
{
@ -563,9 +564,9 @@ Se mais de uma pessoa puder enviar DM para o seu bot (várias entradas em `allow
```
Para Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC, a autorização do remetente é baseada em ID por padrão.
Ative a correspondência direta por nome/e-mail/apelido mutável com `dangerouslyAllowNameMatching: true` de cada canal somente se você aceitar explicitamente esse risco.
Ative a correspondência direta mutável por nome/e-mail/apelido com `dangerouslyAllowNameMatching: true` de cada canal somente se você aceitar explicitamente esse risco.
### Chave de API da Anthropic + fallback MiniMax
### Chave de API da Anthropic + fallback do MiniMax
```json5
{
@ -659,7 +660,7 @@ Ative a correspondência direta por nome/e-mail/apelido mutável com `dangerousl
## Dicas
- Se você definir `dmPolicy: "open"`, a lista `allowFrom` correspondente deve incluir `"*"`.
- IDs de provedores variam (números de telefone, IDs de usuário, IDs de canal). Use a documentação do provedor para confirmar o formato.
- IDs de provedores diferem (números de telefone, IDs de usuário, IDs de canal). Use a documentação do provedor para confirmar o formato.
- Seções opcionais para adicionar depois: `web`, `browser`, `ui`, `discovery`, `canvasHost`, `talk`, `signal`, `imessage`.
- Consulte [Provedores](/pt-BR/providers) e [Solução de problemas](/pt-BR/gateway/troubleshooting) para notas de configuração mais detalhadas.

152
docs/pt-BR/gateway/opentelemetry.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Você quer enviar métricas de uso do modelo, de fluxo de mensagens ou de sessão do OpenClaw para um coletor OpenTelemetry
- Você está integrando traces, métricas ou logs ao Grafana, Datadog, Honeycomb, New Relic, Tempo ou outro backend OTLP
- Você precisa dos nomes exatos das métricas, dos nomes dos spans ou das estruturas de atributos para criar painéis ou alertas
- Você quer enviar o uso do modelo, o fluxo de mensagens ou as métricas de sessão do OpenClaw para um coletor OpenTelemetry
- Você está integrando traces, métricas ou registros ao Grafana, Datadog, Honeycomb, New Relic, Tempo ou outro backend OTLP
- Você precisa dos nomes exatos das métricas, dos nomes dos spans ou dos formatos dos atributos para criar painéis ou alertas
summary: Exporte diagnósticos do OpenClaw para qualquer coletor OpenTelemetry por meio do Plugin diagnostics-otel (OTLP/HTTP)
title: Exportação do OpenTelemetry
x-i18n:
generated_at: "2026-05-03T21:32:34Z"
generated_at: "2026-05-04T05:53:10Z"
model: gpt-5.5
provider: openai
source_hash: c8091aa633a3e10593681f94913a858587a5dc69d9947e0c0d4132f6e897b00b
source_hash: d0b5be99b29fe5f13132b03cfeaf3ce978ee16f29e307aa76769bc414b5ca35f
source_path: gateway/opentelemetry.md
workflow: 16
---
OpenClaw exporta diagnósticos por meio do plugin oficial `diagnostics-otel`
usando **OTLP/HTTP (protobuf)**. Qualquer coletor ou backend que aceite OTLP/HTTP
funciona sem alterações de código. Para logs em arquivo locais e como lê-los, consulte
[Logging](/pt-BR/logging).
funciona sem alterações de código. Para logs de arquivo locais e como lê-los, consulte
[Registro de logs](/pt-BR/logging).
## Como tudo se encaixa
## Como tudo funciona em conjunto
- **Eventos de diagnóstico** são registros estruturados, em processo, emitidos pelo
Gateway e pelos plugins incluídos para execuções de modelo, fluxo de mensagens, sessões, filas
e exec.
- O **plugin `diagnostics-otel`** assina esses eventos e os exporta como
**métricas**, **traces** e **logs** do OpenTelemetry por OTLP/HTTP.
- **Chamadas de provedor** recebem um cabeçalho W3C `traceparent` do contexto de span
confiável de chamada de modelo do OpenClaw quando o transporte do provedor aceita cabeçalhos
- **Chamadas de provedor** recebem um cabeçalho W3C `traceparent` do contexto
de span confiável de chamada de modelo do OpenClaw quando o transporte do provedor aceita cabeçalhos
personalizados. O contexto de trace emitido por plugin não é propagado.
- Exportadores só são anexados quando a superfície de diagnósticos e o plugin estão
- Exportadores só são anexados quando tanto a superfície de diagnósticos quanto o plugin estão
habilitados, então o custo em processo permanece próximo de zero por padrão.
## Início rápido
@ -72,19 +72,19 @@ openclaw plugins enable diagnostics-otel
```
<Note>
No momento, `protocol` aceita apenas `http/protobuf`. `grpc` é ignorado.
`protocol` atualmente oferece suporte apenas a `http/protobuf`. `grpc` é ignorado.
</Note>
## Sinais exportados
| Sinal | O que entra nele |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Métricas** | Contadores e histogramas para uso de tokens, custo, duração da execução, fluxo de mensagens, pistas de fila, estado de sessão, exec e pressão de memória. |
| **Traces** | Spans para uso de modelo, chamadas de modelo, ciclo de vida do harness, execução de ferramenta, exec, processamento de webhook/mensagem, montagem de contexto e loops de ferramentas. |
| **Logs** | Registros estruturados de `logging.file` exportados por OTLP quando `diagnostics.otel.logs` está habilitado. |
| Sinal | O que entra nele |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Métricas** | Contadores e histogramas de uso de tokens, custo, duração de execução, fluxo de mensagens, vias de fila, estado de sessão, exec e pressão de memória. |
| **Traces** | Spans de uso de modelo, chamadas de modelo, ciclo de vida do harness, execução de ferramentas, exec, processamento de webhook/mensagens, montagem de contexto e loops de ferramentas. |
| **Logs** | Registros estruturados `logging.file` exportados por OTLP quando `diagnostics.otel.logs` está habilitado. |
Alterne `traces`, `metrics` e `logs` de forma independente. Todos os três ficam ativados por padrão
quando `diagnostics.otel.enabled` é verdadeiro.
Alterne `traces`, `metrics` e `logs` independentemente. Os três ficam ativados por padrão
quando `diagnostics.otel.enabled` é true.
## Referência de configuração
@ -121,30 +121,30 @@ quando `diagnostics.otel.enabled` é verdadeiro.
### Variáveis de ambiente
| Variável | Finalidade |
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Sobrescreve `diagnostics.otel.endpoint`. Se o valor já contiver `/v1/traces`, `/v1/metrics` ou `/v1/logs`, ele será usado como está. |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Sobrescritas de endpoint específicas por sinal, usadas quando a chave de configuração `diagnostics.otel.*Endpoint` correspondente não está definida. A configuração específica por sinal vence o env específico por sinal, que vence o endpoint compartilhado. |
| `OTEL_SERVICE_NAME` | Sobrescreve `diagnostics.otel.serviceName`. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Sobrescreve o protocolo de transporte (hoje, apenas `http/protobuf` é respeitado). |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Defina como `gen_ai_latest_experimental` para emitir o atributo experimental mais recente de span GenAI (`gen_ai.provider.name`) em vez do legado `gen_ai.system`. Métricas GenAI sempre usam atributos semânticos limitados e de baixa cardinalidade, independentemente disso. |
| `OPENCLAW_OTEL_PRELOADED` | Defina como `1` quando outro preload ou processo host já tiver registrado o SDK global do OpenTelemetry. O plugin então pula seu próprio ciclo de vida do NodeSDK, mas ainda conecta listeners de diagnóstico e respeita `traces`/`metrics`/`logs`. |
| Variável | Finalidade |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Substitui `diagnostics.otel.endpoint`. Se o valor já contiver `/v1/traces`, `/v1/metrics` ou `/v1/logs`, ele será usado como está. |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Substituições de endpoint específicas por sinal usadas quando a chave de configuração `diagnostics.otel.*Endpoint` correspondente não está definida. A configuração específica por sinal vence o env específico por sinal, que vence o endpoint compartilhado. |
| `OTEL_SERVICE_NAME` | Substitui `diagnostics.otel.serviceName`. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Substitui o protocolo de transmissão (somente `http/protobuf` é respeitado hoje). |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Defina como `gen_ai_latest_experimental` para emitir o atributo de span GenAI experimental mais recente (`gen_ai.provider.name`) em vez do legado `gen_ai.system`. Métricas GenAI sempre usam atributos semânticos limitados e de baixa cardinalidade, independentemente disso. |
| `OPENCLAW_OTEL_PRELOADED` | Defina como `1` quando outro preload ou processo host já tiver registrado o SDK global do OpenTelemetry. O plugin então ignora seu próprio ciclo de vida NodeSDK, mas ainda conecta ouvintes de diagnóstico e respeita `traces`/`metrics`/`logs`. |
## Privacidade e captura de conteúdo
Conteúdo bruto de modelo/ferramenta **não** é exportado por padrão. Spans carregam identificadores
limitados (canal, provedor, modelo, categoria de erro, ids de solicitação apenas com hash)
limitados (canal, provedor, modelo, categoria de erro, ids de requisição somente por hash)
e nunca incluem texto de prompt, texto de resposta, entradas de ferramenta, saídas de ferramenta ou
chaves de sessão.
Solicitações de modelo de saída podem incluir um cabeçalho W3C `traceparent`. Esse cabeçalho é
gerado apenas a partir do contexto de trace de diagnóstico pertencente ao OpenClaw para a chamada de modelo
ativa. Cabeçalhos `traceparent` existentes fornecidos pelo chamador são substituídos, então plugins ou
opções personalizadas de provedor não conseguem falsificar ancestralidade de trace entre serviços.
Requisições de modelo de saída podem incluir um cabeçalho W3C `traceparent`. Esse cabeçalho é
gerado somente a partir do contexto de trace de diagnóstico pertencente ao OpenClaw para a chamada de modelo
ativa. Cabeçalhos `traceparent` fornecidos pelo chamador são substituídos, então plugins ou
opções personalizadas de provedor não podem falsificar ancestralidade de trace entre serviços.
Defina `diagnostics.otel.captureContent.*` como `true` somente quando seu coletor e
sua política de retenção forem aprovados para texto de prompt, resposta, ferramenta ou prompt de sistema.
Cada subchave é opcional de forma independente:
Defina `diagnostics.otel.captureContent.*` como `true` somente quando seu coletor e sua
política de retenção estiverem aprovados para texto de prompt, resposta, ferramenta ou prompt de sistema.
Cada subchave é opcional independentemente:
- `inputMessages` — conteúdo do prompt do usuário.
- `outputMessages` — conteúdo da resposta do modelo.
@ -152,7 +152,7 @@ Cada subchave é opcional de forma independente:
- `toolOutputs` — payloads de resultados de ferramenta.
- `systemPrompt` — prompt de sistema/desenvolvedor montado.
Quando qualquer subchave está habilitada, spans de modelo e ferramenta recebem atributos
Quando qualquer subchave é habilitada, spans de modelo e ferramenta recebem atributos
`openclaw.content.*` limitados e redigidos apenas para essa classe.
## Amostragem e flush
@ -160,17 +160,17 @@ Quando qualquer subchave está habilitada, spans de modelo e ferramenta recebem
- **Traces:** `diagnostics.otel.sampleRate` (somente span raiz, `0.0` descarta tudo,
`1.0` mantém tudo).
- **Métricas:** `diagnostics.otel.flushIntervalMs` (mínimo `1000`).
- **Logs:** logs OTLP respeitam `logging.level` (nível de log de arquivo). Eles usam o
caminho de redação de registros de log de diagnóstico, não a formatação do console. Instalações de
alto volume devem preferir amostragem/filtragem no coletor OTLP em vez de amostragem local.
- **Correlação de logs em arquivo:** logs de arquivo JSONL incluem `traceId`,
- **Logs:** logs OTLP respeitam `logging.level` (nível do log de arquivo). Eles usam o
caminho de redação de registro de log de diagnóstico, não a formatação do console. Instalações de alto volume
devem preferir amostragem/filtragem do coletor OTLP em vez de amostragem local.
- **Correlação de logs de arquivo:** logs de arquivo JSONL incluem `traceId`,
`spanId`, `parentSpanId` e `traceFlags` no nível superior quando a chamada de log carrega um contexto
válido de trace de diagnóstico, o que permite que processadores de log associem linhas de log locais a
de trace de diagnóstico válido, o que permite que processadores de log juntem linhas de log locais com
spans exportados.
- **Correlação de solicitações:** solicitações HTTP do Gateway e frames WebSocket criam um
escopo interno de trace de solicitação. Logs e eventos de diagnóstico dentro desse escopo
herdam o trace da solicitação por padrão, enquanto spans de execução de agente e chamada de modelo são
criados como filhos para que cabeçalhos `traceparent` do provedor permaneçam no mesmo trace.
- **Correlação de requisição:** requisições HTTP do Gateway e frames WebSocket criam um
escopo de trace de requisição interno. Logs e eventos de diagnóstico dentro desse escopo
herdam o trace da requisição por padrão, enquanto spans de execução de agente e chamada de modelo são
criados como filhos para que os cabeçalhos `traceparent` do provedor permaneçam no mesmo trace.
## Métricas exportadas
@ -181,9 +181,9 @@ Quando qualquer subchave está habilitada, spans de modelo e ferramenta recebem
- `openclaw.run.duration_ms` (histograma, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
- `openclaw.context.tokens` (histograma, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
- `gen_ai.client.token.usage` (histograma, métrica de convenções semânticas GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
- `gen_ai.client.operation.duration` (histograma, segundos, métrica de convenções semânticas GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, `error.type` opcional)
- `gen_ai.client.operation.duration` (histograma, segundos, métrica de convenções semânticas GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, opcional `error.type`)
- `openclaw.model_call.duration_ms` (histograma, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, mais `openclaw.errorCategory` e `openclaw.failureKind` em erros classificados)
- `openclaw.model_call.request_bytes` (histograma, tamanho em bytes UTF-8 do payload final de solicitação ao modelo; sem conteúdo bruto do payload)
- `openclaw.model_call.request_bytes` (histograma, tamanho em bytes UTF-8 do payload final da requisição de modelo; sem conteúdo bruto do payload)
- `openclaw.model_call.response_bytes` (histograma, tamanho em bytes UTF-8 de eventos de resposta de modelo transmitidos por streaming; sem conteúdo bruto da resposta)
- `openclaw.model_call.time_to_first_byte_ms` (histograma, tempo decorrido antes do primeiro evento de resposta transmitido por streaming)
@ -205,14 +205,14 @@ Quando qualquer subchave está habilitada, spans de modelo e ferramenta recebem
- `openclaw.queue.depth` (histograma, attrs: `openclaw.lane` ou `openclaw.channel=heartbeat`)
- `openclaw.queue.wait_ms` (histograma, attrs: `openclaw.lane`)
- `openclaw.session.state` (contador, attrs: `openclaw.state`, `openclaw.reason`)
- `openclaw.session.stuck` (contador, attrs: `openclaw.state`; emitido apenas para bookkeeping de sessão obsoleta sem trabalho ativo)
- `openclaw.session.stuck_age_ms` (histograma, attrs: `openclaw.state`; emitido apenas para bookkeeping de sessão obsoleta sem trabalho ativo)
- `openclaw.session.stuck` (contador, attrs: `openclaw.state`; emitido somente para bookkeeping de sessão obsoleta sem trabalho ativo)
- `openclaw.session.stuck_age_ms` (histograma, attrs: `openclaw.state`; emitido somente para bookkeeping de sessão obsoleta sem trabalho ativo)
- `openclaw.run.attempt` (contador, attrs: `openclaw.attempt`)
### Telemetria de atividade de sessão
`diagnostics.stuckSessionWarnMs` é o limite de idade sem progresso para diagnósticos
de atividade de sessão. Uma sessão `processing` não avança em direção a esse limite
de atividade de sessão. Uma sessão `processing` não envelhece em direção a esse limite
enquanto o OpenClaw observa progresso de resposta, ferramenta, status, bloco ou runtime ACP.
Keepalives de digitação não contam como progresso, então um modelo ou harness silencioso ainda pode
ser detectado.
@ -220,26 +220,26 @@ ser detectado.
OpenClaw classifica sessões pelo trabalho que ainda consegue observar:
- `session.long_running`: trabalho incorporado ativo, chamadas de modelo ou chamadas de ferramenta
ainda estão progredindo.
ainda estão avançando.
- `session.stalled`: há trabalho ativo, mas a execução ativa não relatou
progresso recente. Execuções incorporadas paralisadas permanecem inicialmente somente observação e depois
abortam e drenam após pelo menos 10 minutos e 5x `diagnostics.stuckSessionWarnMs`
sem progresso, para que turnos enfileirados atrás da lane possam retomar.
- `session.stuck`: controle de sessão obsoleto sem trabalho ativo. Isso libera
progresso recente. Execuções incorporadas paradas permanecem inicialmente apenas em observação e depois
fazem abort-drain após pelo menos 10 minutos e 5x `diagnostics.stuckSessionWarnMs`
sem progresso, para que turnos enfileirados atrás da lane possam continuar.
- `session.stuck`: escrituração de sessão obsoleta sem trabalho ativo. Isso libera
a lane da sessão afetada imediatamente.
Somente `session.stuck` emite o contador `openclaw.session.stuck`, o
histograma `openclaw.session.stuck_age_ms` e o span `openclaw.session.stuck`.
Diagnósticos repetidos de `session.stuck` fazem backoff enquanto a sessão permanece
inalterada, então dashboards devem alertar sobre aumentos sustentados, e não sobre cada
tick de Heartbeat. Para o seletor de configuração e os padrões, consulte
Diagnósticos repetidos de `session.stuck` recuam enquanto a sessão permanece
inalterada, portanto dashboards devem alertar sobre aumentos sustentados, em vez de cada
tick de Heartbeat. Para o controle de configuração e os padrões, consulte
[Referência de configuração](/pt-BR/gateway/configuration-reference#diagnostics).
### Ciclo de vida do harness
- `openclaw.harness.duration_ms` (histograma, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` em erros)
### Exec
### Execução
- `openclaw.exec.duration_ms` (histograma, attrs: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`)
@ -256,12 +256,12 @@ tick de Heartbeat. Para o seletor de configuração e os padrões, consulte
- `openclaw.model.usage`
- `openclaw.channel`, `openclaw.provider`, `openclaw.model`
- `openclaw.tokens.*` (input/output/cache_read/cache_write/total)
- `gen_ai.system` por padrão, ou `gen_ai.provider.name` quando as convenções semânticas mais recentes de GenAI são habilitadas
- `gen_ai.system` por padrão, ou `gen_ai.provider.name` quando as convenções semânticas GenAI mais recentes são habilitadas
- `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*`
- `openclaw.run`
- `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory`
- `openclaw.model.call`
- `gen_ai.system` por padrão, ou `gen_ai.provider.name` quando as convenções semânticas mais recentes de GenAI são habilitadas
- `gen_ai.system` por padrão, ou `gen_ai.provider.name` quando as convenções semânticas GenAI mais recentes são habilitadas
- `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`
- `openclaw.errorCategory` e `openclaw.failureKind` opcional em erros
- `openclaw.model_call.request_bytes`, `openclaw.model_call.response_bytes`, `openclaw.model_call.time_to_first_byte_ms`
@ -275,11 +275,11 @@ tick de Heartbeat. Para o seletor de configuração e os padrões, consulte
- `openclaw.exec`
- `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`, `openclaw.exec.command_length`, `openclaw.exec.exit_code`, `openclaw.exec.timed_out`
- `openclaw.webhook.processed`
- `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId`
- `openclaw.channel`, `openclaw.webhook`
- `openclaw.webhook.error`
- `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId`, `openclaw.error`
- `openclaw.channel`, `openclaw.webhook`, `openclaw.error`
- `openclaw.message.processed`
- `openclaw.channel`, `openclaw.outcome`, `openclaw.chatId`, `openclaw.messageId`, `openclaw.reason`
- `openclaw.channel`, `openclaw.outcome`, `openclaw.reason`
- `openclaw.message.delivery`
- `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`, `openclaw.delivery.result_count`
- `openclaw.session.stuck`
@ -292,18 +292,18 @@ tick de Heartbeat. Para o seletor de configuração e os padrões, consulte
- `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes`
Quando a captura de conteúdo é explicitamente habilitada, spans de modelo e ferramenta também podem
incluir atributos `openclaw.content.*` limitados e redigidos para as classes
de conteúdo específicas que você habilitou.
incluir atributos `openclaw.content.*` limitados e redigidos para as classes de
conteúdo específicas que você optou por incluir.
## Catálogo de eventos de diagnóstico
Os eventos abaixo dão suporte às métricas e spans acima. Plugins também podem assinar
Os eventos abaixo sustentam as métricas e spans acima. Plugins também podem assinar
esses eventos diretamente sem exportação OTLP.
**Uso do modelo**
- `model.usage` — tokens, custo, duração, contexto, provedor/modelo/canal,
ids de sessão. `usage` é a contabilidade de provedor/turno para custo e telemetria;
ids de sessão. `usage` é a contabilidade por provedor/turno para custo e telemetria;
`context.used` é o snapshot atual de prompt/contexto e pode ser menor que
`usage.total` do provedor quando entrada em cache ou chamadas de loop de ferramentas estão envolvidas.
@ -324,21 +324,21 @@ esses eventos diretamente sem exportação OTLP.
- `harness.run.started` / `harness.run.completed` / `harness.run.error` —
ciclo de vida por execução para o harness do agente. Inclui `harnessId`, `pluginId`
opcional, provedor/modelo/canal e id da execução. A conclusão adiciona
opcional, provedor/modelo/canal e id de execução. A conclusão adiciona
`durationMs`, `outcome`, `resultClassification` opcional, `yieldDetected`
e contagens de `itemLifecycle`. Erros adicionam `phase`
(`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` e
`cleanupFailed` opcional.
**Exec**
**Execução**
- `exec.process.completed` — resultado terminal, duração, destino, modo, código
de saída e tipo de falha. O texto do comando e diretórios de trabalho não são
de saída e tipo de falha. Texto do comando e diretórios de trabalho não são
incluídos.
## Sem um exportador
Você pode manter eventos de diagnóstico disponíveis para plugins ou coletores personalizados sem
Você pode manter eventos de diagnóstico disponíveis para plugins ou sinks personalizados sem
executar `diagnostics-otel`:
```json5
@ -348,7 +348,7 @@ executar `diagnostics-otel`:
```
Para saída de depuração direcionada sem aumentar `logging.level`, use flags de diagnóstico.
As flags não diferenciam maiúsculas de minúsculas e oferecem suporte a curingas (por exemplo, `telegram.*` ou
Flags não diferenciam maiúsculas de minúsculas e aceitam curingas (por exemplo, `telegram.*` ou
`*`):
```json5
@ -363,7 +363,7 @@ Ou como uma substituição de env pontual:
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
```
A saída das flags vai para o arquivo de log padrão (`logging.file`) e ainda é
A saída de flags vai para o arquivo de log padrão (`logging.file`) e ainda é
redigida por `logging.redactSensitive`. Guia completo:
[Flags de diagnóstico](/pt-BR/diagnostics/flags).
@ -380,8 +380,8 @@ Você também pode deixar `diagnostics-otel` fora de `plugins.allow` ou executar
## Relacionado
- [Logging](/pt-BR/logging) — logs em arquivo, saída do console, acompanhamento pela CLI e a aba Logs da Control UI
- [Logging](/pt-BR/logging) — logs em arquivo, saída no console, tailing pela CLI e a aba Logs da Control UI
- [Internos de logging do Gateway](/pt-BR/gateway/logging) — estilos de log WS, prefixos de subsistema e captura de console
- [Flags de diagnóstico](/pt-BR/diagnostics/flags) — flags de log de depuração direcionadas
- [Flags de diagnóstico](/pt-BR/diagnostics/flags) — flags direcionadas de log de depuração
- [Exportação de diagnóstico](/pt-BR/gateway/diagnostics) — ferramenta de pacote de suporte para operadores (separada da exportação OTEL)
- [Referência de configuração](/pt-BR/gateway/configuration-reference#diagnostics) — referência completa dos campos `diagnostics.*`

101
docs/pt-BR/gateway/operator-scopes.md
View File

@ -1,57 +1,57 @@
---
read_when:
- Depuração de erros de escopo de operador ausente
- Revisão de aprovações de emparelhamento de dispositivo ou Node
- Adicionar ou classificar métodos RPC do Gateway
summary: Funções, escopos e verificações no momento da aprovação para clientes do Gateway
- Revisão das aprovações de pareamento de dispositivos ou Node
- Adição ou classificação de métodos RPC do Gateway
summary: Papéis, escopos e verificações no momento da aprovação do operador para clientes do Gateway
title: Escopos de operador
x-i18n:
generated_at: "2026-05-03T05:49:05Z"
generated_at: "2026-05-04T05:53:47Z"
model: gpt-5.5
provider: openai
source_hash: 48f59f96b41333af9124ad4083ac5442eedb2d6cebdfff74e3ba256f06d36add
source_hash: f05d6bdbf9bdad2aef1c9664bb7ebb4b6241334b8aefac7993104e9977e40450
source_path: gateway/operator-scopes.md
workflow: 16
---
Os escopos de operador definem o que um cliente Gateway pode fazer depois de se autenticar.
Eles são uma proteção de plano de controle dentro de um domínio confiável de operador Gateway,
não isolamento multi-tenant hostil. Se você precisa de separação forte entre
Os escopos de operador definem o que um cliente do Gateway pode fazer depois de se autenticar.
Eles são uma proteção do plano de controle dentro de um domínio confiável de operador do Gateway,
não isolamento multi-inquilino hostil. Se você precisa de separação forte entre
pessoas, equipes ou máquinas, execute Gateways separados sob usuários do SO ou
hosts separados.
Relacionado: [Segurança](/pt-BR/gateway/security), [protocolo do Gateway](/pt-BR/gateway/protocol),
[pareamento do Gateway](/pt-BR/gateway/pairing), [CLI de dispositivos](/pt-BR/cli/devices).
Relacionado: [Segurança](/pt-BR/gateway/security), [Protocolo do Gateway](/pt-BR/gateway/protocol),
[Emparelhamento do Gateway](/pt-BR/gateway/pairing), [CLI de dispositivos](/pt-BR/cli/devices).
## Funções
Clientes WebSocket do Gateway se conectam com uma função:
- `operator`: clientes de plano de controle, como CLI, Interface de controle, automação e
- `operator`: clientes do plano de controle, como CLI, Control UI, automação e
processos auxiliares confiáveis.
- `node`: hosts de capacidade, como macOS, iOS, Android ou nós sem interface gráfica que
expõem comandos por meio de `node.invoke`.
- `node`: hosts de capacidade, como macOS, iOS, Android ou nodes sem interface
gráfica que expõem comandos por meio de `node.invoke`.
Os métodos RPC de operador exigem a função `operator`. Métodos originados no nó
Métodos RPC de operador exigem a função `operator`. Métodos originados por Node
exigem a função `node`.
## Níveis de escopo
| Escopo | Significado |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operator.read` | Status somente leitura, listas, catálogo, logs, leituras de sessão e outras chamadas de plano de controle que não fazem mutação. |
| `operator.write` | Ações normais de operador que fazem mutação, como enviar mensagens, invocar ferramentas, atualizar configurações de fala/voz e retransmissão de comandos de nó. Também satisfaz `operator.read`. |
| Escopo | Significado |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `operator.read` | Status somente leitura, listas, catálogo, logs, leituras de sessão e outras chamadas do plano de controle que não fazem mutação. |
| `operator.write` | Ações normais de operador que fazem mutação, como enviar mensagens, invocar ferramentas, atualizar configurações de fala/voz e retransmissão de comandos de Node. Também satisfaz `operator.read`. |
| `operator.admin` | Acesso administrativo ao plano de controle. Satisfaz todos os escopos `operator.*`. Exigido para mutação de configuração, atualizações, hooks nativos, namespaces reservados sensíveis e aprovações de alto risco. |
| `operator.pairing` | Gerenciamento de pareamento de dispositivos e nós, incluindo listar, aprovar, rejeitar, remover, rotacionar e revogar registros de pareamento ou tokens de dispositivo. |
| `operator.approvals` | APIs de aprovação de exec e Plugin. |
| `operator.talk.secrets` | Leitura da configuração do Talk com segredos incluídos. |
| `operator.pairing` | Gerenciamento de emparelhamento de dispositivos e Node, incluindo listar, aprovar, rejeitar, remover, rotacionar e revogar registros de emparelhamento ou tokens de dispositivo. |
| `operator.approvals` | APIs de aprovação de exec e Plugin. |
| `operator.talk.secrets` | Leitura da configuração do Talk com segredos incluídos. |
Escopos `operator.*` futuros desconhecidos exigem uma correspondência exata, a menos que o chamador tenha
`operator.admin`.
## O escopo do método é apenas o primeiro gate
## O escopo do método é apenas a primeira barreira
Cada RPC do Gateway tem um escopo de método de privilégio mínimo. Esse escopo de método decide
Cada RPC do Gateway tem um escopo de método de menor privilégio. Esse escopo de método decide
se a solicitação pode chegar ao manipulador. Alguns manipuladores então aplicam verificações mais estritas
no momento da aprovação com base no item concreto que está sendo aprovado ou modificado.
@ -59,59 +59,60 @@ Exemplos:
- `device.pair.approve` é acessível com `operator.pairing`, mas aprovar um
dispositivo operador só pode emitir ou preservar escopos que o chamador já possui.
- `node.pair.approve` é acessível com `operator.pairing`, depois deriva escopos
extras de aprovação a partir da lista de comandos pendentes do nó.
- `node.pair.approve` é acessível com `operator.pairing` e, em seguida, deriva escopos
de aprovação extras da lista de comandos de Node pendente.
- `chat.send` normalmente é um método com escopo de escrita, mas `/config set`
e `/config unset` persistentes exigem `operator.admin` no nível do comando.
Isso permite que operadores com escopo mais baixo realizem ações de pareamento de baixo risco sem tornar
todas as aprovações de pareamento exclusivas de administradores.
Isso permite que operadores com escopo mais baixo realizem ações de emparelhamento de baixo risco sem tornar
todas as aprovações de emparelhamento exclusivas de admin.
## Aprovações de pareamento de dispositivos
## Aprovações de emparelhamento de dispositivo
Registros de pareamento de dispositivos são a fonte durável de funções e escopos aprovados.
Dispositivos já pareados não recebem acesso mais amplo silenciosamente: reconexões que pedem
uma função mais ampla ou escopos mais amplos criam uma nova solicitação pendente de upgrade.
Registros de emparelhamento de dispositivo são a fonte durável de funções e escopos aprovados.
Dispositivos já emparelhados não recebem acesso mais amplo silenciosamente: reconexões que solicitam
uma função mais ampla ou escopos mais amplos criam uma nova solicitação de upgrade pendente.
Ao aprovar uma solicitação de dispositivo:
- Uma solicitação sem função de operador não precisa de aprovação de escopo de token de operador.
- Uma solicitação para `operator.read`, `operator.write`, `operator.approvals`,
`operator.pairing` ou `operator.talk.secrets` exige que o chamador tenha
`operator.pairing` ou `operator.talk.secrets` exige que o chamador possua
esses escopos ou `operator.admin`.
- Uma solicitação para `operator.admin` exige `operator.admin`.
- Uma solicitação de reparo sem escopos explícitos pode herdar os escopos de token
de operador existentes. Se esse token existente tiver escopo de administrador, a aprovação ainda exigirá
- Uma solicitação de reparo sem escopos explícitos pode herdar os escopos de token de operador
existentes. Se esse token existente tiver escopo de admin, a aprovação ainda exige
`operator.admin`.
Para sessões de token de dispositivo pareado, o gerenciamento é autoescopado, a menos que o chamador
também tenha `operator.admin`: chamadores que não são administradores só podem rotacionar, revogar ou remover
sua própria entrada de dispositivo.
Para sessões de token de dispositivo emparelhado, o gerenciamento é autoescopado, a menos que o chamador
também tenha `operator.admin`: chamadores não admin veem apenas suas próprias entradas de emparelhamento,
podem aprovar ou rejeitar apenas sua própria solicitação pendente e podem rotacionar, revogar ou
remover apenas sua própria entrada de dispositivo.
## Aprovações de pareamento de Node
## Aprovações de emparelhamento de Node
O `node.pair.*` legado usa um armazenamento de pareamento de nós separado, pertencente ao Gateway. Nós WS
usam pareamento de dispositivo com `role: node`, mas o mesmo vocabulário em nível de aprovação
O `node.pair.*` legado usa um armazenamento separado de emparelhamento de Node pertencente ao Gateway. Nodes WS
usam emparelhamento de dispositivo com `role: node`, mas o mesmo vocabulário de nível de aprovação
se aplica.
`node.pair.approve` usa a lista de comandos da solicitação pendente para derivar escopos
adicionais exigidos:
necessários adicionais:
- Solicitação sem comando: `operator.pairing`
- Comandos de nó que não são exec: `operator.pairing` + `operator.write`
- Solicitação sem comandos: `operator.pairing`
- Comandos de Node não exec: `operator.pairing` + `operator.write`
- `system.run`, `system.run.prepare` ou `system.which`:
`operator.pairing` + `operator.admin`
O pareamento de nós estabelece identidade e confiança. Ele não substitui a política
própria de aprovação de exec `system.run` do nó.
O emparelhamento de Node estabelece identidade e confiança. Ele não substitui a política
própria de aprovação de exec `system.run` do Node.
## Autenticação por segredo compartilhado
A autenticação por token/senha compartilhada do Gateway é tratada como acesso confiável de operador para
Autenticação por token/senha compartilhados do gateway é tratada como acesso de operador confiável para
esse Gateway. Superfícies HTTP compatíveis com OpenAI e `/tools/invoke` restauram o
conjunto normal completo de escopos padrão de operador para autenticação bearer por segredo compartilhado, mesmo que um
conjunto padrão normal completo de escopos de operador para autenticação bearer por segredo compartilhado, mesmo que um
chamador envie escopos declarados mais restritos.
Modos com identidade, como autenticação por proxy confiável ou `none` de ingresso privado,
ainda podem honrar escopos declarados explícitos. Use Gateways separados para separação real de
limites de confiança.
Modos com identidade, como autenticação por proxy confiável ou `none` em ingresso privado,
ainda podem respeitar escopos declarados explícitos. Use Gateways separados para separação real de
fronteiras de confiança.

90
docs/pt-BR/install/updating.md
View File

@ -2,13 +2,13 @@
read_when:
- Atualizando o OpenClaw
- Algo para de funcionar após uma atualização
summary: Atualizando o OpenClaw com segurança (instalação global ou a partir do código-fonte), além da estratégia de reversão
summary: Atualizando o OpenClaw com segurança (instalação global ou pelo código-fonte), além da estratégia de reversão
title: Atualização
x-i18n:
generated_at: "2026-05-03T21:35:12Z"
generated_at: "2026-05-04T05:53:33Z"
model: gpt-5.5
provider: openai
source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1
source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714
source_path: install/updating.md
workflow: 16
---
@ -17,13 +17,13 @@ Mantenha o OpenClaw atualizado.
## Recomendado: `openclaw update`
A maneira mais rápida de atualizar. Ele detecta seu tipo de instalação (npm ou git), busca a versão mais recente, executa `openclaw doctor` e reinicia o Gateway.
A forma mais rápida de atualizar. Ele detecta seu tipo de instalação (npm ou git), busca a versão mais recente, executa `openclaw doctor` e reinicia o Gateway.
```bash
openclaw update
```
Para trocar de canal ou mirar uma versão específica:
Para trocar de canal ou direcionar uma versão específica:
```bash
openclaw update --channel beta
@ -33,13 +33,13 @@ openclaw update --dry-run # preview without applying
```
`openclaw update` não aceita `--verbose`. Para diagnósticos de atualização, use
`--dry-run` para pré-visualizar as ações planejadas, `--json` para resultados estruturados, ou
`--dry-run` para visualizar as ações planejadas, `--json` para resultados estruturados, ou
`openclaw update status --json` para inspecionar o estado do canal e da disponibilidade. O
instalador tem sua própria flag `--verbose`, mas essa flag não faz parte de
`openclaw update`.
`--channel beta` prefere beta, mas o runtime recorre a stable/latest quando
a tag beta está ausente ou é mais antiga que a versão estável mais recente. Use `--tag beta`
`--channel beta` prefere beta, mas o runtime volta para stable/latest quando
a tag beta está ausente ou é mais antiga do que a versão stable mais recente. Use `--tag beta`
se você quiser a dist-tag beta bruta do npm para uma atualização pontual do pacote.
Consulte [Canais de desenvolvimento](/pt-BR/install/development-channels) para a semântica dos canais.
@ -47,8 +47,8 @@ Consulte [Canais de desenvolvimento](/pt-BR/install/development-channels) para a
## Alternar entre instalações npm e git
Use canais quando quiser alterar o tipo de instalação. O atualizador mantém seu
estado, configuração, credenciais e workspace em `~/.openclaw`; ele apenas altera
qual instalação do código do OpenClaw a CLI e o Gateway usam.
estado, configuração, credenciais e workspace em `~/.openclaw`; ele altera apenas
qual instalação de código do OpenClaw a CLI e o Gateway usam.
```bash
# npm package install -> editable git checkout
@ -58,15 +58,15 @@ openclaw update --channel dev
openclaw update --channel stable
```
Execute com `--dry-run` primeiro para pré-visualizar a troca exata do modo de instalação:
Execute primeiro com `--dry-run` para visualizar a troca exata de modo de instalação:
```bash
openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run
```
O canal `dev` garante um checkout git, compila-o e instala a CLI global
a partir desse checkout. Os canais `stable` e `beta` usam instalações de pacote. Se o
O canal `dev` garante um checkout git, compila esse checkout e instala a CLI global
a partir dele. Os canais `stable` e `beta` usam instalações de pacote. Se o
Gateway já estiver instalado, `openclaw update` atualiza os metadados do serviço
e o reinicia, a menos que você passe `--no-restart`.
@ -81,8 +81,8 @@ instalador, passe `--install-method git --no-onboard` ou
`--install-method npm --no-onboard`.
Se `openclaw update` falhar após a fase de instalação do pacote npm, execute novamente o
instalador. O instalador não chama o atualizador antigo; ele executa a instalação global do
pacote diretamente e pode recuperar uma instalação npm parcialmente atualizada.
instalador. O instalador não chama o atualizador antigo; ele executa a instalação do pacote
global diretamente e pode recuperar uma instalação npm parcialmente atualizada.
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
@ -100,12 +100,18 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --ve
npm i -g openclaw@latest
```
Quando `openclaw update` gerencia uma instalação npm global, ele instala o alvo em
um prefixo npm temporário primeiro, verifica o inventário `dist` empacotado e então troca
a árvore limpa do pacote para o prefixo global real. Isso evita que o npm sobreponha um
Prefira `openclaw update` para instalações supervisionadas porque ele pode coordenar a
troca de pacote com o serviço Gateway em execução. Se você atualizar manualmente enquanto um
Gateway gerenciado estiver em execução, reinicie o Gateway imediatamente após o gerenciador de
pacotes terminar para que o processo antigo não continue servindo a partir de arquivos de pacote
substituídos.
Quando `openclaw update` gerencia uma instalação npm global, ele primeiro instala o alvo em
um prefixo npm temporário, verifica o inventário `dist` empacotado e então troca
a árvore de pacote limpa para o prefixo global real. Isso evita que o npm sobreponha um
novo pacote a arquivos obsoletos do pacote antigo. Se o comando de instalação falhar,
o OpenClaw tenta novamente uma vez com `--omit=optional`. Essa nova tentativa ajuda hosts em que dependências opcionais
nativas não conseguem compilar, mantendo a falha original visível
o OpenClaw tenta novamente uma vez com `--omit=optional`. Essa nova tentativa ajuda hosts em que dependências
opcionais nativas não conseguem compilar, mantendo a falha original visível
se o fallback também falhar.
```bash
@ -120,9 +126,9 @@ bun add -g openclaw@latest
<AccordionGroup>
<Accordion title="Árvore de pacote somente leitura">
O OpenClaw trata instalações globais empacotadas como somente leitura em runtime, mesmo quando o diretório global do pacote é gravável pelo usuário atual. Instalações de pacotes de Plugin ficam em raízes npm/git pertencentes ao OpenClaw sob o diretório de configuração do usuário, e a inicialização do Gateway não modifica a árvore de pacotes do OpenClaw.
O OpenClaw trata instalações globais empacotadas como somente leitura em runtime, mesmo quando o diretório global do pacote é gravável pelo usuário atual. Instalações de pacotes de Plugin ficam em raízes npm/git pertencentes ao OpenClaw sob o diretório de configuração do usuário, e a inicialização do Gateway não modifica a árvore de pacote do OpenClaw.
Algumas configurações npm do Linux instalam pacotes globais em diretórios pertencentes ao root, como `/usr/lib/node_modules/openclaw`. O OpenClaw oferece suporte a esse layout porque comandos de instalação/atualização de Plugin escrevem fora desse diretório global de pacotes.
Algumas configurações npm no Linux instalam pacotes globais em diretórios pertencentes ao root, como `/usr/lib/node_modules/openclaw`. O OpenClaw oferece suporte a esse layout porque comandos de instalação/atualização de Plugin gravam fora desse diretório global de pacote.
</Accordion>
<Accordion title="Unidades systemd reforçadas">
@ -133,14 +139,14 @@ bun add -g openclaw@latest
```
</Accordion>
<Accordion title="Verificação preliminar de espaço em disco">
Antes de atualizações de pacote e instalações explícitas de Plugin, o OpenClaw tenta uma verificação de espaço em disco de melhor esforço para o volume de destino. Pouco espaço gera um aviso com o caminho verificado, mas não bloqueia a atualização porque cotas de sistema de arquivos, snapshots e volumes de rede podem mudar após a verificação. A instalação real pelo gerenciador de pacotes e a verificação pós-instalação continuam sendo autoritativas.
<Accordion title="Pré-verificação de espaço em disco">
Antes de atualizações de pacote e instalações explícitas de Plugin, o OpenClaw tenta uma verificação de espaço em disco de melhor esforço para o volume alvo. Pouco espaço gera um aviso com o caminho verificado, mas não bloqueia a atualização porque cotas de sistema de arquivos, snapshots e volumes de rede podem mudar após a verificação. A instalação real pelo gerenciador de pacotes e a verificação pós-instalação continuam sendo autoritativas.
</Accordion>
</AccordionGroup>
## Atualizador automático
O atualizador automático fica desativado por padrão. Ative-o em `~/.openclaw/openclaw.json`:
O atualizador automático vem desativado por padrão. Ative-o em `~/.openclaw/openclaw.json`:
```json5
{
@ -156,21 +162,21 @@ O atualizador automático fica desativado por padrão. Ative-o em `~/.openclaw/o
}
```
| Canal | Comportamento |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `stable` | Aguarda `stableDelayHours`, depois aplica com jitter determinístico em `stableJitterHours` (implantação distribuída). |
| `beta` | Verifica a cada `betaCheckIntervalHours` (padrão: a cada hora) e aplica imediatamente. |
| `dev` | Sem aplicação automática. Use `openclaw update` manualmente. |
| Canal | Comportamento |
| -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `stable` | Aguarda `stableDelayHours` e então aplica com jitter determinístico ao longo de `stableJitterHours` (implantação gradual). |
| `beta` | Verifica a cada `betaCheckIntervalHours` (padrão: a cada hora) e aplica imediatamente. |
| `dev` | Sem aplicação automática. Use `openclaw update` manualmente. |
O Gateway também registra uma dica de atualização na inicialização (desative com `update.checkOnStart: false`).
Para downgrade ou recuperação de incidente, defina `OPENCLAW_NO_AUTO_UPDATE=1` no ambiente do Gateway para bloquear aplicações automáticas mesmo quando `update.auto.enabled` estiver configurado. Dicas de atualização na inicialização ainda podem ser executadas, a menos que `update.checkOnStart` também esteja desativado.
Para downgrade ou recuperação de incidente, defina `OPENCLAW_NO_AUTO_UPDATE=1` no ambiente do Gateway para bloquear aplicações automáticas mesmo quando `update.auto.enabled` estiver configurado. As dicas de atualização na inicialização ainda podem ser executadas, a menos que `update.checkOnStart` também esteja desativado.
Atualizações por gerenciador de pacotes solicitadas pelo handler do plano de controle do Gateway ao vivo
forçam uma reinicialização de atualização sem adiamento e sem cooldown após a troca do pacote. Isso
evita deixar um processo antigo em memória por tempo suficiente para carregar preguiçosamente chunks
de uma árvore de pacote que já foi substituída. O `openclaw update` pelo shell
continua sendo o caminho preferido para instalações supervisionadas porque ele pode parar e
reiniciar o serviço em torno da atualização.
Atualizações de gerenciador de pacotes solicitadas pelo manipulador live do plano de controle do Gateway
forçam uma reinicialização de atualização sem adiamento e sem cooldown após a troca de pacote. Isso
evita deixar um processo antigo em memória por tempo suficiente para carregar chunks sob demanda
de uma árvore de pacote que já foi substituída. O `openclaw update` em shell
continua sendo o caminho preferido para instalações supervisionadas porque pode parar e
reiniciar o serviço durante a atualização.
## Após atualizar
@ -221,17 +227,17 @@ pnpm install && pnpm build
openclaw gateway restart
```
Para voltar à mais recente: `git checkout main && git pull`.
Para retornar para a versão mais recente: `git checkout main && git pull`.
## Se você estiver travado
- Execute `openclaw doctor` novamente e leia a saída com atenção.
- Para `openclaw update --channel dev` em checkouts de código-fonte, o atualizador inicializa automaticamente o `pnpm` quando necessário. Se você vir um erro de bootstrap do pnpm/corepack, instale o `pnpm` manualmente (ou reative o `corepack`) e execute a atualização novamente.
- Confira: [Solução de problemas](/pt-BR/gateway/troubleshooting)
- Para `openclaw update --channel dev` em checkouts de código-fonte, o atualizador inicializa automaticamente o `pnpm` quando necessário. Se você vir um erro de bootstrap de pnpm/corepack, instale o `pnpm` manualmente (ou reative o `corepack`) e execute a atualização novamente.
- Verifique: [Solução de problemas](/pt-BR/gateway/troubleshooting)
- Pergunte no Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
## Relacionados
## Relacionado
- [Visão geral da instalação](/pt-BR/install): todos os métodos de instalação.
- [Doctor](/pt-BR/gateway/doctor): verificações de saúde após atualizações.
- [Migração](/pt-BR/install/migrating): guias de migração de versões principais.
- [Migração](/pt-BR/install/migrating): guias de migração de versão principal.

216
docs/pt-BR/plugins/building-plugins.md
View File

@ -1,37 +1,37 @@
---
read_when:
- Você quer criar um novo Plugin do OpenClaw
- Você deseja criar um novo Plugin do OpenClaw
- Você precisa de um guia de início rápido para desenvolvimento de Plugin
- Você está adicionando um novo canal, provedor, ferramenta ou outra capacidade ao OpenClaw
- Você está adicionando um novo canal, provedor, ferramenta ou outro recurso ao OpenClaw
sidebarTitle: Getting Started
summary: Crie seu primeiro Plugin do OpenClaw em minutos
title: Criando plugins
x-i18n:
generated_at: "2026-05-02T20:50:03Z"
generated_at: "2026-05-04T05:54:01Z"
model: gpt-5.5
provider: openai
source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1
source_hash: 3e6c55c551629da54b3f150ce6299694186fe4434cfd7978a2d43d175d33a5d9
source_path: plugins/building-plugins.md
workflow: 16
---
Plugins estendem o OpenClaw com novos recursos: canais, provedores de modelos,
Plugins estendem o OpenClaw com novos recursos: canais, provedores de modelo,
fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração
de imagens, geração de vídeo, busca de conteúdo na web, pesquisa na web, ferramentas de agente ou qualquer
de imagem, geração de vídeo, busca de conteúdo na web, pesquisa na web, ferramentas de agente ou qualquer
combinação.
Você não precisa adicionar seu Plugin ao repositório do OpenClaw. Publique no
[ClawHub](/pt-BR/tools/clawhub) e os usuários instalam com
`openclaw plugins install clawhub:<package-name>`. Especificações de pacotes simples ainda
`openclaw plugins install clawhub:<package-name>`. Especificações de pacote simples ainda
instalam a partir do npm durante a transição de lançamento.
## Pré-requisitos
- Node >= 22 e um gerenciador de pacotes (npm ou pnpm)
- Familiaridade com TypeScript (ESM)
- Para Plugins no repositório: repositório clonado e `pnpm install` concluído. O desenvolvimento
de Plugins a partir do checkout do código-fonte usa somente pnpm porque o OpenClaw carrega Plugins
incluídos a partir dos pacotes de workspace `extensions/*`.
- Para Plugins no repositório: repositório clonado e `pnpm install` concluído. O desenvolvimento de Plugins
em checkout de código-fonte usa somente pnpm porque o OpenClaw carrega Plugins agrupados
a partir dos pacotes de workspace `extensions/*`.
## Que tipo de Plugin?
@ -42,16 +42,16 @@ instalam a partir do npm durante a transição de lançamento.
<Card title="Plugin de provedor" icon="cpu" href="/pt-BR/plugins/sdk-provider-plugins">
Adicione um provedor de modelo (LLM, proxy ou endpoint personalizado)
</Card>
<Card title="Plugin de ferramenta / gancho" icon="wrench" href="/pt-BR/plugins/hooks">
Registre ferramentas de agente, ganchos de evento ou serviços — continue abaixo
<Card title="Plugin de ferramenta / hook" icon="wrench" href="/pt-BR/plugins/hooks">
Registre ferramentas de agente, hooks de evento ou serviços — continue abaixo
</Card>
</CardGroup>
Para um Plugin de canal cuja instalação não é garantida quando a integração/configuração
é executada, use `createOptionalChannelSetupSurface(...)` de
Para um Plugin de canal cuja instalação não seja garantida quando onboarding/configuração
executar, use `createOptionalChannelSetupSurface(...)` de
`openclaw/plugin-sdk/channel-setup`. Ele produz um par adaptador de configuração + assistente
que anuncia o requisito de instalação e falha de forma fechada em gravações reais de configuração
até que o Plugin seja instalado.
até que o Plugin esteja instalado.
## Início rápido: Plugin de ferramenta
@ -99,11 +99,11 @@ e provedor têm guias dedicados vinculados acima.
```
</CodeGroup>
Todo Plugin precisa de um manifesto, mesmo sem configuração. Ferramentas registradas em tempo de execução
Todo Plugin precisa de um manifesto, mesmo sem configuração. Ferramentas registradas em runtime
devem ser listadas em `contracts.tools` para que o OpenClaw possa descobrir o Plugin
proprietário sem carregar todo runtime de Plugin. Plugins também devem declarar
`activation.onStartup` intencionalmente. Este exemplo o define como `true`. Consulte
[Manifesto](/pt-BR/plugins/manifest) para ver o esquema completo. Os snippets canônicos de publicação no ClawHub
proprietário sem carregar todos os runtimes de Plugin. Plugins também devem declarar
`activation.onStartup` intencionalmente. Este exemplo o define como `true`. Veja
[Manifesto](/pt-BR/plugins/manifest) para o schema completo. Os snippets canônicos de publicação do ClawHub
ficam em `docs/snippets/plugin-publish/`.
</Step>
@ -133,8 +133,8 @@ e provedor têm guias dedicados vinculados acima.
```
`definePluginEntry` é para Plugins que não são de canal. Para canais, use
`defineChannelPluginEntry` — consulte [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins).
Para todas as opções de ponto de entrada, consulte [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints).
`defineChannelPluginEntry` — veja [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins).
Para opções completas de ponto de entrada, veja [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints).
</Step>
@ -148,10 +148,10 @@ e provedor têm guias dedicados vinculados acima.
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
Especificações de pacotes simples como `@myorg/openclaw-my-plugin` instalam a partir do npm durante
Especificações de pacote simples como `@myorg/openclaw-my-plugin` instalam a partir do npm durante
a transição de lançamento. Use `clawhub:` quando quiser resolução pelo ClawHub.
**Plugins no repositório:** coloque sob a árvore de workspace de Plugins incluídos — descoberto automaticamente.
**Plugins no repositório:** coloque sob a árvore de workspace de Plugins agrupados — descoberto automaticamente.
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
@ -160,70 +160,70 @@ e provedor têm guias dedicados vinculados acima.
</Step>
</Steps>
## Recursos de Plugin
## Capacidades de Plugin
Um único Plugin pode registrar qualquer número de recursos pelo objeto `api`:
Um único Plugin pode registrar qualquer número de capacidades por meio do objeto `api`:
| Recurso | Método de registro | Guia detalhado |
| Capacidade | Método de registro | Guia detalhado |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| Inferência de texto (LLM) | `api.registerProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) |
| Backend de inferência da CLI | `api.registerCliBackend(...)` | [Backends da CLI](/pt-BR/gateway/cli-backends) |
| Canal / mensagens | `api.registerChannel(...)` | [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) |
| Fala (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Inferência de texto (LLM) | `api.registerProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) |
| Backend de inferência da CLI | `api.registerCliBackend(...)` | [Backends de CLI](/pt-BR/gateway/cli-backends) |
| Canal / mensagens | `api.registerChannel(...)` | [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) |
| Fala (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Transcrição em tempo real | `api.registerRealtimeTranscriptionProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Voz em tempo real | `api.registerRealtimeVoiceProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Compreensão de mídia | `api.registerMediaUnderstandingProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Geração de imagens | `api.registerImageGenerationProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Geração de música | `api.registerMusicGenerationProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Voz em tempo real | `api.registerRealtimeVoiceProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Compreensão de mídia | `api.registerMediaUnderstandingProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Geração de imagem | `api.registerImageGenerationProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Geração de música | `api.registerMusicGenerationProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Geração de vídeo | `api.registerVideoGenerationProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Busca de conteúdo na web | `api.registerWebFetchProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Pesquisa na web | `api.registerWebSearchProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Busca de conteúdo na web | `api.registerWebFetchProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Pesquisa na web | `api.registerWebSearchProvider(...)` | [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Middleware de resultado de ferramenta | `api.registerAgentToolResultMiddleware(...)` | [Visão geral do SDK](/pt-BR/plugins/sdk-overview#registration-api) |
| Ferramentas de agente | `api.registerTool(...)` | Abaixo |
| Comandos personalizados | `api.registerCommand(...)` | [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) |
| Ganchos de Plugin | `api.on(...)` | [Ganchos de Plugin](/pt-BR/plugins/hooks) |
| Ganchos de eventos internos | `api.registerHook(...)` | [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) |
| Rotas HTTP | `api.registerHttpRoute(...)` | [Internos](/pt-BR/plugins/architecture-internals#gateway-http-routes) |
| Subcomandos da CLI | `api.registerCli(...)` | [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) |
| Ferramentas de agente | `api.registerTool(...)` | Abaixo |
| Comandos personalizados | `api.registerCommand(...)` | [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) |
| Hooks de Plugin | `api.on(...)` | [Hooks de Plugin](/pt-BR/plugins/hooks) |
| Hooks de evento internos | `api.registerHook(...)` | [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) |
| Rotas HTTP | `api.registerHttpRoute(...)` | [Detalhes internos](/pt-BR/plugins/architecture-internals#gateway-http-routes) |
| Subcomandos da CLI | `api.registerCli(...)` | [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) |
Para a API de registro completa, consulte [Visão geral do SDK](/pt-BR/plugins/sdk-overview#registration-api).
Para a API de registro completa, veja [Visão geral do SDK](/pt-BR/plugins/sdk-overview#registration-api).
Plugins incluídos podem usar `api.registerAgentToolResultMiddleware(...)` quando
precisarem reescrever resultados de ferramentas de forma assíncrona antes que o modelo veja a saída. Declare os
runtimes de destino em `contracts.agentToolResultMiddleware`, por exemplo
`["pi", "codex"]`. Esta é uma interface confiável para Plugins incluídos; Plugins externos
devem preferir ganchos regulares de Plugin do OpenClaw, a menos que o OpenClaw desenvolva uma
política de confiança explícita para esse recurso.
Plugins agrupados podem usar `api.registerAgentToolResultMiddleware(...)` quando
precisam reescrever resultados de ferramentas de forma assíncrona antes que o modelo veja a saída. Declare os
runtimes direcionados em `contracts.agentToolResultMiddleware`, por exemplo
`["pi", "codex"]`. Esta é uma interface confiável de Plugin agrupado; Plugins
externos devem preferir hooks regulares de Plugin do OpenClaw, a menos que o OpenClaw adicione uma
política de confiança explícita para essa capacidade.
Se seu Plugin registrar métodos RPC personalizados do Gateway, mantenha-os em um
prefixo específico do Plugin. Namespaces administrativos centrais (`config.*`,
prefixo específico do Plugin. Namespaces administrativos do núcleo (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre resolvem para
`operator.admin`, mesmo se um Plugin pedir um escopo mais restrito.
`operator.admin`, mesmo que um Plugin solicite um escopo mais restrito.
Semânticas de guarda de ganchos para lembrar:
Semânticas de guarda de hook a lembrar:
- `before_tool_call`: `{ block: true }` é terminal e interrompe handlers de prioridade mais baixa.
- `before_tool_call`: `{ block: false }` é tratado como nenhuma decisão.
- `before_tool_call`: `{ requireApproval: true }` pausa a execução do agente e solicita aprovação ao usuário pelo overlay de aprovação de exec, botões do Telegram, interações do Discord ou o comando `/approve` em qualquer canal.
- `before_install`: `{ block: true }` é terminal e interrompe handlers de prioridade mais baixa.
- `before_install`: `{ block: false }` é tratado como nenhuma decisão.
- `message_sending`: `{ cancel: true }` é terminal e interrompe handlers de prioridade mais baixa.
- `message_sending`: `{ cancel: false }` é tratado como nenhuma decisão.
- `before_tool_call`: `{ block: true }` é terminal e interrompe handlers de menor prioridade.
- `before_tool_call`: `{ block: false }` é tratado como ausência de decisão.
- `before_tool_call`: `{ requireApproval: true }` pausa a execução do agente e solicita aprovação ao usuário por meio da sobreposição de aprovação de exec, botões do Telegram, interações do Discord ou o comando `/approve` em qualquer canal.
- `before_install`: `{ block: true }` é terminal e interrompe handlers de menor prioridade.
- `before_install`: `{ block: false }` é tratado como ausência de decisão.
- `message_sending`: `{ cancel: true }` é terminal e interrompe handlers de menor prioridade.
- `message_sending`: `{ cancel: false }` é tratado como ausência de decisão.
- `message_received`: prefira o campo tipado `threadId` quando precisar de roteamento de thread/tópico de entrada. Mantenha `metadata` para extras específicos do canal.
- `message_sending`: prefira os campos de roteamento tipados `replyToId` / `threadId` em vez de chaves de metadados específicas do canal.
O comando `/approve` lida com aprovações de exec e de Plugin com fallback limitado: quando um id de aprovação de exec não é encontrado, o OpenClaw tenta novamente o mesmo id por meio das aprovações de Plugin. O encaminhamento de aprovação de Plugin pode ser configurado independentemente por `approvals.plugin` na configuração.
O comando `/approve` lida com aprovações de exec e Plugin com fallback limitado: quando um id de aprovação de exec não é encontrado, o OpenClaw tenta novamente o mesmo id por aprovações de Plugin. O encaminhamento de aprovação de Plugin pode ser configurado independentemente por meio de `approvals.plugin` na configuração.
Se o encanamento de aprovação personalizado precisar detectar esse mesmo caso de fallback limitado,
prefira `isApprovalNotFoundError` de `openclaw/plugin-sdk/error-runtime`
em vez de comparar manualmente strings de expiração de aprovação.
em vez de comparar strings de expiração de aprovação manualmente.
Consulte [Ganchos de Plugin](/pt-BR/plugins/hooks) para exemplos e a referência de ganchos.
Veja [Hooks de Plugin](/pt-BR/plugins/hooks) para exemplos e a referência de hooks.
## Registro de ferramentas de agente
## Registrando ferramentas de agente
Ferramentas são funções tipadas que o LLM pode chamar. Elas podem ser obrigatórias (sempre
disponíveis) ou opcionais (adesão do usuário):
disponíveis) ou opcionais (opt-in do usuário):
```typescript
register(api) {
@ -259,16 +259,24 @@ manifesto do Plugin:
{
"contracts": {
"tools": ["my_tool", "workflow_tool"]
},
"toolMetadata": {
"workflow_tool": {
"optional": true
}
}
}
```
O OpenClaw captura e armazena em cache o descritor validado da ferramenta registrada,
então Plugins não duplicam `description` ou dados de esquema no manifesto. O
contrato do manifesto apenas declara propriedade e descoberta; a execução ainda chama
a implementação viva da ferramenta registrada.
OpenClaw captura e armazena em cache o descritor validado da ferramenta registrada,
para que os plugins não dupliquem `description` nem dados de esquema no manifesto. O
contrato do manifesto declara apenas propriedade e descoberta; a execução ainda chama
a implementação ativa da ferramenta registrada.
Defina `toolMetadata.<tool>.optional: true` para ferramentas registradas com
`api.registerTool(..., { optional: true })` para que o OpenClaw possa evitar carregar esse
runtime de plugin até que a ferramenta seja explicitamente incluída na lista de permissões.
Usuários habilitam ferramentas opcionais na configuração:
Os usuários habilitam ferramentas opcionais na configuração:
```json5
{
@ -276,16 +284,16 @@ Usuários habilitam ferramentas opcionais na configuração:
}
```
- Os nomes das ferramentas não devem entrar em conflito com ferramentas principais (conflitos são ignorados)
- Ferramentas com objetos de registro malformados, incluindo `parameters` ausente, são ignoradas e relatadas nos diagnósticos do plugin em vez de interromper execuções do agente
- Use `optional: true` para ferramentas com efeitos colaterais ou requisitos extras de binário
- Os nomes das ferramentas não devem conflitar com ferramentas centrais (conflitos são ignorados)
- Ferramentas com objetos de registro malformados, incluindo `parameters` ausente, são ignoradas e relatadas nos diagnósticos do plugin em vez de interromper execuções de agentes
- Use `optional: true` para ferramentas com efeitos colaterais ou requisitos binários extras
- Os usuários podem habilitar todas as ferramentas de um plugin adicionando o id do plugin a `tools.allow`
## Registrando comandos da CLI
Plugins podem adicionar grupos de comandos raiz `openclaw` com `api.registerCli`. Forneça
`descriptors` para cada raiz de comando de nível superior para que o OpenClaw possa mostrar e rotear
o comando sem carregar antecipadamente todo runtime de plugin.
o comando sem carregar antecipadamente todos os runtimes de plugin.
```typescript
register(api) {
@ -324,7 +332,7 @@ openclaw demo-plugin ping
## Convenções de importação
Sempre importe de caminhos focados `openclaw/plugin-sdk/<subpath>`:
Sempre importe de caminhos `openclaw/plugin-sdk/<subpath>` focados:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -337,68 +345,68 @@ import { ... } from "openclaw/plugin-sdk";
Para a referência completa de subcaminhos, consulte [Visão geral do SDK](/pt-BR/plugins/sdk-overview).
Dentro do seu plugin, use arquivos barrel locais (`api.ts`, `runtime-api.ts`) para
importações internas — nunca importe seu próprio plugin por meio do caminho do SDK dele.
importações internas — nunca importe seu próprio plugin por meio do caminho SDK dele.
Para plugins de provedor, mantenha helpers específicos do provedor nesses barrels na raiz do pacote,
a menos que a seam seja realmente genérica. Exemplos empacotados atuais:
Para plugins de provedor, mantenha auxiliares específicos do provedor nesses barrels
da raiz do pacote, a menos que a interface seja realmente genérica. Exemplos integrados atuais:
- Anthropic: wrappers de stream do Claude e helpers de `service_tier` / beta
- OpenAI: builders de provedor, helpers de modelo padrão, provedores em tempo real
- OpenRouter: builder de provedor mais helpers de onboarding/configuração
- Anthropic: wrappers de stream do Claude e auxiliares de `service_tier` / beta
- OpenAI: construtores de provedor, auxiliares de modelo padrão, provedores em tempo real
- OpenRouter: construtor de provedor mais auxiliares de integração/configuração
Se um helper só for útil dentro de um pacote de provedor empacotado, mantenha-o nessa
seam da raiz do pacote em vez de promovê-lo para `openclaw/plugin-sdk/*`.
Se um auxiliar só for útil dentro de um pacote de provedor integrado, mantenha-o nessa
interface da raiz do pacote em vez de promovê-lo para `openclaw/plugin-sdk/*`.
Algumas seams helper geradas `openclaw/plugin-sdk/<bundled-id>` ainda existem para
manutenção de plugins empacotados quando têm uso rastreado pelo owner. Trate-as como
superfícies reservadas, não como o padrão padrão para novos plugins de terceiros.
Algumas interfaces auxiliares geradas `openclaw/plugin-sdk/<bundled-id>` ainda existem para
manutenção de plugins integrados quando têm uso rastreado pelo proprietário. Trate-as como
superfícies reservadas, não como o padrão para novos plugins de terceiros.
## Checklist pré-envio
## Lista de verificação antes do envio
<Check>**package.json** tem metadados `openclaw` corretos</Check>
<Check>O manifesto **openclaw.plugin.json** está presente e válido</Check>
<Check>O ponto de entrada usa `defineChannelPluginEntry` ou `definePluginEntry`</Check>
<Check>Todas as importações usam caminhos focados `plugin-sdk/<subpath>`</Check>
<Check>Todas as importações usam caminhos `plugin-sdk/<subpath>` focados</Check>
<Check>Importações internas usam módulos locais, não autoimportações do SDK</Check>
<Check>Os testes passam (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
<Check>`pnpm check` passa (plugins no repositório)</Check>
<Check>Testes passam (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
<Check>`pnpm check` passa (plugins dentro do repositório)</Check>
## Testes de versão beta
## Testes de lançamento beta
1. Acompanhe tags de release do GitHub em [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) e assine via `Watch` > `Releases`. Tags beta se parecem com `v2026.3.N-beta.1`. Você também pode ativar notificações para a conta oficial do OpenClaw no X [@openclaw](https://x.com/openclaw) para anúncios de release.
2. Teste seu plugin contra a tag beta assim que ela aparecer. A janela antes da estável geralmente é de apenas algumas horas.
3. Publique no thread do seu plugin no canal Discord `plugin-forum` depois dos testes com `all good` ou com o que quebrou. Se você ainda não tiver um thread, crie um.
1. Acompanhe tags de lançamento do GitHub em [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) e assine via `Watch` > `Releases`. Tags beta são parecidas com `v2026.3.N-beta.1`. Você também pode ativar notificações para a conta oficial do OpenClaw no X [@openclaw](https://x.com/openclaw) para anúncios de lançamento.
2. Teste seu plugin contra a tag beta assim que ela aparecer. A janela antes da versão estável geralmente é de apenas algumas horas.
3. Publique no thread do seu plugin no canal `plugin-forum` do Discord após testar com `all good` ou o que quebrou. Se ainda não tiver um thread, crie um.
4. Se algo quebrar, abra ou atualize uma issue intitulada `Beta blocker: <plugin-name> - <summary>` e aplique o rótulo `beta-blocker`. Coloque o link da issue no seu thread.
5. Abra um PR para `main` intitulado `fix(<plugin-id>): beta blocker - <summary>` e vincule a issue tanto no PR quanto no seu thread do Discord. Colaboradores não podem rotular PRs, então o título é o sinal do lado do PR para mantenedores e automação. Bloqueadores com PR são mesclados; bloqueadores sem PR podem ser enviados mesmo assim. Mantenedores acompanham esses threads durante os testes beta.
6. Silêncio significa verde. Se você perder a janela, sua correção provavelmente entrará no próximo ciclo.
5. Abra um PR para `main` intitulado `fix(<plugin-id>): beta blocker - <summary>` e vincule a issue tanto no PR quanto no seu thread do Discord. Colaboradores não podem rotular PRs, então o título é o sinal do lado do PR para mantenedores e automação. Bloqueadores com um PR são mesclados; bloqueadores sem um podem ser enviados mesmo assim. Mantenedores acompanham esses threads durante os testes beta.
6. Silêncio significa verde. Se você perder a janela, sua correção provavelmente entra no próximo ciclo.
## Próximos passos
<CardGroup cols={2}>
<Card title="Plugins de Canal" icon="messages-square" href="/pt-BR/plugins/sdk-channel-plugins">
<Card title="Plugins de canal" icon="messages-square" href="/pt-BR/plugins/sdk-channel-plugins">
Crie um plugin de canal de mensagens
</Card>
<Card title="Plugins de Provedor" icon="cpu" href="/pt-BR/plugins/sdk-provider-plugins">
<Card title="Plugins de provedor" icon="cpu" href="/pt-BR/plugins/sdk-provider-plugins">
Crie um plugin de provedor de modelo
</Card>
<Card title="Visão geral do SDK" icon="book-open" href="/pt-BR/plugins/sdk-overview">
Mapa de importação e referência da API de registro
</Card>
<Card title="Helpers de Runtime" icon="settings" href="/pt-BR/plugins/sdk-runtime">
<Card title="Auxiliares de runtime" icon="settings" href="/pt-BR/plugins/sdk-runtime">
TTS, busca, subagente via api.runtime
</Card>
<Card title="Testes" icon="test-tubes" href="/pt-BR/plugins/sdk-testing">
Utilitários e padrões de teste
</Card>
<Card title="Manifesto do Plugin" icon="file-json" href="/pt-BR/plugins/manifest">
<Card title="Manifesto do plugin" icon="file-json" href="/pt-BR/plugins/manifest">
Referência completa do esquema do manifesto
</Card>
</CardGroup>
## Relacionados
## Relacionado
- [Arquitetura de Plugin](/pt-BR/plugins/architecture) — aprofundamento na arquitetura interna
- [Arquitetura de plugins](/pt-BR/plugins/architecture) — aprofundamento na arquitetura interna
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de Plugin
- [Manifesto](/pt-BR/plugins/manifest) — formato do manifesto do plugin
- [Plugins de Canal](/pt-BR/plugins/sdk-channel-plugins) — criando plugins de canal
- [Plugins de Provedor](/pt-BR/plugins/sdk-provider-plugins) — criando plugins de provedor
- [Manifesto](/pt-BR/plugins/manifest) — formato do manifesto de plugin
- [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — criação de plugins de canal
- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — criação de plugins de provedor

1023
docs/pt-BR/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

205
docs/pt-BR/plugins/memory-wiki.md
View File

@ -1,81 +1,82 @@
---
read_when:
- Você quer conhecimento persistente além de simples notas em MEMORY.md
- Você quer conhecimento persistente além de simples anotações em MEMORY.md
- Você está configurando o Plugin memory-wiki incluído
- Você quer entender wiki_search, wiki_get ou o modo ponte
summary: 'memory-wiki: cofre de conhecimento compilado com proveniência, declarações, painéis e modo de ponte'
- Você quer entender `wiki_search`, `wiki_get` ou o modo bridge
summary: 'memory-wiki: cofre de conhecimento compilado com proveniência, afirmações, painéis e modo de ponte'
title: Wiki de memória
x-i18n:
generated_at: "2026-04-30T10:00:23Z"
generated_at: "2026-05-04T05:54:17Z"
model: gpt-5.5
provider: openai
source_hash: 744d569f8b0c9b668ea54dc057f808544359eaae87d5557de2e6acd1b31acd89
source_hash: b070177b7c1217e9102bc57680b4009265e3584ede7ad6dc3ba7b6393260fefe
source_path: plugins/memory-wiki.md
workflow: 16
---
`memory-wiki` é um Plugin incluído que transforma memória durável em um cofre de conhecimento compilado.
`memory-wiki` é um Plugin incluído que transforma memória durável em um
cofre de conhecimento compilado.
Ele **não** substitui o Plugin de Active Memory. O Plugin de Active Memory ainda
é responsável por recall, promoção, indexação e Dreaming. `memory-wiki` fica ao lado dele
controla recuperação, promoção, indexação e dreaming. `memory-wiki` fica ao lado dele
e compila conhecimento durável em uma wiki navegável com páginas determinísticas,
declarações estruturadas, proveniência, painéis e resumos legíveis por máquina.
Use-o quando quiser que a memória se comporte mais como uma camada de conhecimento mantida e
Use quando você quiser que a memória se comporte mais como uma camada de conhecimento mantida e
menos como uma pilha de arquivos Markdown.
## O que ele adiciona
- Um cofre wiki dedicado com layout de página determinístico
- Um cofre de wiki dedicado com layout de páginas determinístico
- Metadados estruturados de declarações e evidências, não apenas prosa
- Proveniência, confiança, contradições e perguntas em aberto no nível da página
- Resumos compilados para consumidores de agente/runtime
- Ferramentas nativas da wiki para busca/obtenção/aplicação/lint
- Modo de ponte opcional que importa artefatos públicos do Plugin de Active Memory
- Modo de renderização compatível com Obsidian e integração com CLI opcionais
- Ferramentas nativas da wiki para buscar/obter/aplicar/verificar
- Modo ponte opcional que importa artefatos públicos do Plugin de Active Memory
- Modo de renderização opcional amigável ao Obsidian e integração com CLI
## Como ele se encaixa com a memória
Pense na divisão assim:
| Camada | Responsável por |
| Camada | Controla |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Plugin de Active Memory (`memory-core`, QMD, Honcho, etc.) | Recall, busca semântica, promoção, Dreaming, runtime de memória |
| `memory-wiki` | Páginas wiki compiladas, sínteses ricas em proveniência, painéis, busca/obtenção/aplicação específicas da wiki |
| Plugin de Active Memory (`memory-core`, QMD, Honcho etc.) | Recuperação, busca semântica, promoção, dreaming, runtime de memória |
| `memory-wiki` | Páginas de wiki compiladas, sínteses ricas em proveniência, painéis, busca/get/apply específicos da wiki |
Se o Plugin de Active Memory expuser artefatos de recall compartilhados, o OpenClaw pode pesquisar
Se o Plugin de Active Memory expuser artefatos de recuperação compartilhados, o OpenClaw pode pesquisar
as duas camadas em uma única passagem com `memory_search corpus=all`.
Quando você precisar de ranqueamento específico da wiki, proveniência ou acesso direto à página, use as
Quando você precisar de ranqueamento específico da wiki, proveniência ou acesso direto a páginas, use as
ferramentas nativas da wiki.
## Padrão híbrido recomendado
Um bom padrão inicial para configurações local-first é:
- QMD como backend de Active Memory para recall e busca semântica ampla
- `memory-wiki` em modo `bridge` para páginas de conhecimento sintetizado duráveis
- QMD como backend de Active Memory para recuperação e busca semântica ampla
- `memory-wiki` em modo `bridge` para páginas duráveis de conhecimento sintetizado
Essa divisão funciona bem porque cada camada permanece focada:
- QMD mantém notas brutas, exportações de sessão e coleções extras pesquisáveis
- `memory-wiki` compila entidades, declarações, painéis e páginas-fonte estáveis
- O QMD mantém notas brutas, exportações de sessão e coleções extras pesquisáveis
- `memory-wiki` compila entidades estáveis, declarações, painéis e páginas de origem
Regra prática:
- use `memory_search` quando quiser uma única passagem ampla de recall pela memória
- use `wiki_search` e `wiki_get` quando quiser resultados de wiki atentos à proveniência
- use `memory_search` quando quiser uma passagem ampla de recuperação pela memória
- use `wiki_search` e `wiki_get` quando quiser resultados da wiki cientes de proveniência
- use `memory_search corpus=all` quando quiser que a busca compartilhada abranja as duas camadas
Se o modo de ponte relatar zero artefatos exportados, o Plugin de Active Memory não está
Se o modo ponte relatar zero artefatos exportados, o Plugin de Active Memory não está
expondo entradas públicas de ponte no momento. Execute `openclaw wiki doctor` primeiro,
depois confirme que o Plugin de Active Memory oferece suporte a artefatos públicos.
depois confirme se o Plugin de Active Memory oferece suporte a artefatos públicos.
Quando o modo de ponte está ativo e `bridge.readMemoryArtifacts` está habilitado,
Quando o modo ponte está ativo e `bridge.readMemoryArtifacts` está habilitado,
`openclaw wiki status`, `openclaw wiki doctor` e `openclaw wiki bridge
import` leem pelo Gateway em execução. Isso mantém as verificações de ponte da CLI alinhadas
com o contexto do Plugin de memória em runtime. Se a ponte estiver desabilitada ou as leituras de artefato
estiverem desativadas, esses comandos mantêm seu comportamento local/offline.
import` leem por meio do Gateway em execução. Isso mantém as verificações de ponte da CLI alinhadas
com o contexto do Plugin de memória em runtime. Se a ponte estiver desativada ou as leituras de artefatos
estiverem desligadas, esses comandos mantêm seu comportamento local/offline.
## Modos de cofre
@ -85,17 +86,17 @@ estiverem desativadas, esses comandos mantêm seu comportamento local/offline.
Cofre próprio, fontes próprias, sem dependência de `memory-core`.
Use isto quando quiser que a wiki seja seu próprio armazenamento de conhecimento curado.
Use quando quiser que a wiki seja seu próprio repositório curado de conhecimento.
### `bridge`
Lê artefatos públicos de memória e eventos de memória do Plugin de Active Memory
por meio de pontos públicos do SDK de Plugin.
por meio de interfaces públicas do SDK de Plugin.
Use isto quando quiser que a wiki compile e organize os artefatos exportados do Plugin de memória
sem acessar componentes internos privados do Plugin.
Use quando quiser que a wiki compile e organize os artefatos exportados pelo Plugin de memória
sem acessar partes internas privadas do Plugin.
O modo de ponte pode indexar:
O modo ponte pode indexar:
- artefatos de memória exportados
- relatórios de sonho
@ -105,11 +106,11 @@ O modo de ponte pode indexar:
### `unsafe-local`
Saída de emergência explícita de mesma máquina para caminhos privados locais.
Saída de emergência explícita na mesma máquina para caminhos locais privados.
Este modo é intencionalmente experimental e não portável. Use-o apenas quando você
Esse modo é intencionalmente experimental e não portátil. Use apenas quando você
entender o limite de confiança e precisar especificamente de acesso ao sistema de arquivos local que
o modo de ponte não consegue fornecer.
o modo ponte não consegue fornecer.
## Layout do cofre
@ -138,7 +139,7 @@ Os principais grupos de páginas são:
- `sources/` para material bruto importado e páginas apoiadas por ponte
- `entities/` para coisas, pessoas, sistemas, projetos e objetos duráveis
- `concepts/` para ideias, abstrações, padrões e políticas
- `syntheses/` para resumos compilados e consolidações mantidas
- `syntheses/` para resumos compilados e agregações mantidas
- `reports/` para painéis gerados
## Declarações estruturadas e evidências
@ -166,13 +167,13 @@ Entradas de evidência podem incluir:
- `note`
- `updatedAt`
É isso que faz a wiki agir mais como uma camada de crenças do que como um despejo passivo
de notas. Declarações podem ser rastreadas, pontuadas, contestadas e resolvidas de volta às fontes.
Isso é o que faz a wiki agir mais como uma camada de crenças do que como um despejo passivo de notas.
As declarações podem ser rastreadas, pontuadas, contestadas e resolvidas de volta às fontes.
## Metadados de entidade voltados ao agente
## Metadados de entidade voltados para agentes
Páginas de entidade também podem carregar metadados de roteamento para uso do agente. Isto é
frontmatter genérico, então funciona para pessoas, equipes, sistemas, projetos ou qualquer outro
Páginas de entidade também podem carregar metadados de roteamento para uso por agentes. Isso é frontmatter
genérico, então funciona para pessoas, equipes, sistemas, projetos ou qualquer outro
tipo de entidade.
Campos comuns incluem:
@ -182,13 +183,13 @@ Campos comuns incluem:
- `aliases`: nomes, identificadores ou rótulos que devem resolver para a mesma página
- `privacyTier`: `public`, `local-private`, `sensitive` ou `confirm-before-use`
- `bestUsedFor` / `notEnoughFor`: dicas compactas de roteamento
- `lastRefreshedAt`: timestamp de atualização da fonte separado do horário de edição da página
- `personCard`: cartão de roteamento opcional específico de pessoa com identificadores, redes sociais,
emails, fuso horário, área, pedir-por, evitar-pedir-por, confiança e privacidade
- `relationships`: arestas tipadas para páginas relacionadas com destino, tipo, peso,
confiança, tipo de evidência, nível de privacidade e observação
- `lastRefreshedAt`: carimbo de data/hora de atualização de fonte separado do horário de edição da página
- `personCard`: cartão opcional de roteamento específico de pessoa com identificadores, redes sociais,
emails, fuso horário, trilha, pedir-sobre, evitar-pedir-sobre, confiança e privacidade
- `relationships`: arestas tipadas para páginas relacionadas com alvo, tipo, peso,
confiança, tipo de evidência, nível de privacidade e nota
Para uma wiki de pessoas, o agente geralmente deve começar com
Para uma wiki de pessoas, o agente normalmente deve começar com
`reports/person-agent-directory.md`, depois abrir a página da pessoa com `wiki_get`
antes de usar detalhes de contato ou fatos inferidos.
@ -242,23 +243,23 @@ claims:
## Pipeline de compilação
A etapa de compilação lê páginas wiki, normaliza resumos e emite artefatos estáveis
voltados à máquina em:
A etapa de compilação lê páginas da wiki, normaliza resumos e emite artefatos estáveis
voltados para máquina em:
- `.openclaw-wiki/cache/agent-digest.json`
- `.openclaw-wiki/cache/claims.jsonl`
Esses resumos existem para que agentes e código de runtime não precisem extrair Markdown
das páginas.
Esses resumos existem para que agentes e código de runtime não precisem raspar páginas
Markdown.
A saída compilada também alimenta:
- indexação inicial da wiki para fluxos de busca/obtenção
- lookup de id de declaração de volta às páginas proprietárias
- indexação inicial da wiki para fluxos de search/get
- busca de id de declaração de volta para as páginas proprietárias
- suplementos compactos de prompt
- geração de relatórios/painéis
## Painéis e relatórios de integridade
## Painéis e relatórios de saúde
Quando `render.createDashboards` está habilitado, a compilação mantém painéis em
`reports/`.
@ -277,8 +278,8 @@ Relatórios integrados incluem:
Esses relatórios acompanham coisas como:
- agrupamentos de notas de contradição
- agrupamentos de declarações concorrentes
- clusters de notas de contradição
- clusters de declarações concorrentes
- declarações sem evidência estruturada
- páginas e declarações de baixa confiança
- atualização obsoleta ou desconhecida
@ -292,8 +293,8 @@ Esses relatórios acompanham coisas como:
`memory-wiki` oferece suporte a dois backends de busca:
- `shared`: usa o fluxo de busca de memória compartilhada quando disponível
- `local`: pesquisa a wiki localmente
- `shared`: use o fluxo compartilhado de busca de memória quando disponível
- `local`: pesquise a wiki localmente
Ele também oferece suporte a três corpora:
@ -304,32 +305,32 @@ Ele também oferece suporte a três corpora:
Comportamento importante:
- `wiki_search` e `wiki_get` usam resumos compilados como primeira passagem quando possível
- ids de declaração podem resolver de volta para a página proprietária
- declarações contestadas/obsoletas/recentes influenciam o ranqueamento
- ids de declarações podem resolver de volta para a página proprietária
- declarações contestadas/obsoletas/frescas influenciam o ranqueamento
- rótulos de proveniência podem sobreviver nos resultados
- o modo de busca pode enviesar o ranqueamento para lookup de pessoas, roteamento de perguntas, evidência
de fonte ou declarações brutas
- o modo de busca pode enviesar o ranqueamento para busca de pessoa, roteamento de perguntas, evidência de
origem ou declarações brutas
Regra prática:
- use `memory_search corpus=all` para uma única passagem ampla de recall
- use `memory_search corpus=all` para uma passagem ampla de recuperação
- use `wiki_search` + `wiki_get` quando você se importar com ranqueamento específico da wiki,
proveniência ou estrutura de crença no nível da página
proveniência ou estrutura de crenças no nível da página
Modos de busca:
- `auto`: padrão equilibrado
- `find-person`: impulsiona entidades semelhantes a pessoas, aliases, identificadores, redes sociais e
- `find-person`: prioriza entidades semelhantes a pessoas, aliases, identificadores, redes sociais e
IDs canônicos
- `route-question`: impulsiona cartões de agente, dicas de pedir-por, dicas de melhor-uso-para e
- `route-question`: prioriza cartões de agentes, dicas de ask-for, dicas de best-used-for e
contexto de relacionamento
- `source-evidence`: impulsiona páginas-fonte e metadados de evidência estruturada
- `raw-claim`: impulsiona declarações estruturadas correspondentes e retorna metadados de declaração/evidência
- `source-evidence`: prioriza páginas de origem e metadados de evidência estruturada
- `raw-claim`: prioriza declarações estruturadas correspondentes e retorna metadados de declaração/evidência
nos resultados
Quando um resultado corresponde a uma declaração estruturada, `wiki_search` pode retornar
`matchedClaimId`, `matchedClaimStatus`, `matchedClaimConfidence`,
`evidenceKinds` e `evidenceSourceIds` em seu payload de detalhes. A saída em texto
`evidenceKinds` e `evidenceSourceIds` em sua carga de detalhes. A saída em texto
também inclui linhas compactas `Claim:` e `Evidence:` quando disponíveis.
## Ferramentas de agente
@ -344,32 +345,31 @@ O Plugin registra estas ferramentas:
O que elas fazem:
- `wiki_status`: modo de cofre atual, integridade, disponibilidade da CLI do Obsidian
- `wiki_search`: pesquisa páginas wiki e, quando configurado, corpora de memória compartilhada;
aceita `mode` para lookup de pessoas, roteamento de perguntas, evidência de fonte ou drilldown de
declaração bruta
- `wiki_get`: lê uma página wiki por id/caminho ou faz fallback para corpus de memória compartilhada
- `wiki_apply`: mutações estreitas de síntese/metadados sem cirurgia livre de página
- `wiki_status`: modo atual do cofre, saúde, disponibilidade da CLI do Obsidian
- `wiki_search`: pesquisa páginas da wiki e, quando configurado, corpora de memória compartilhada;
aceita `mode` para busca de pessoa, roteamento de perguntas, evidência de origem ou aprofundamento em declaração bruta
- `wiki_get`: lê uma página da wiki por id/caminho ou recorre ao corpus de memória compartilhada
- `wiki_apply`: mutações estreitas de síntese/metadados sem cirurgia livre na página
- `wiki_lint`: verificações estruturais, lacunas de proveniência, contradições, perguntas em aberto
O Plugin também registra um suplemento não exclusivo de corpus de memória, para que
`memory_search` e `memory_get` compartilhados possam alcançar a wiki quando o Plugin de Active Memory
oferece suporte à seleção de corpus.
O Plugin também registra um suplemento de corpus de memória não exclusivo, para que
`memory_search` e `memory_get` compartilhados possam acessar a wiki quando o Plugin de Active Memory
oferecer suporte à seleção de corpus.
## Comportamento de prompt e contexto
Quando `context.includeCompiledDigestPrompt` está habilitado, seções de prompt de memória
anexam um snapshot compilado compacto de `agent-digest.json`.
anexam um instantâneo compilado compacto de `agent-digest.json`.
Esse snapshot é intencionalmente pequeno e de alto sinal:
Esse instantâneo é intencionalmente pequeno e de alto sinal:
- apenas páginas principais
- apenas declarações principais
- contagem de contradições
- contagem de perguntas
- qualificadores de confiança/atualidade
- qualificadores de confiança/atualização
Isto é opt-in porque altera o formato do prompt e é útil principalmente para mecanismos de contexto
Isso é opt-in porque altera o formato do prompt e é principalmente útil para mecanismos de contexto
ou montagem legada de prompt que consomem explicitamente suplementos de memória.
## Configuração
@ -430,23 +430,26 @@ Alternâncias principais:
- `vaultMode`: `isolated`, `bridge`, `unsafe-local`
- `vault.renderMode`: `native` ou `obsidian`
- `bridge.readMemoryArtifacts`: importar artefatos públicos do plugin de memória ativa
- `bridge.readMemoryArtifacts`: importar artefatos públicos do Plugin de Active Memory
- `bridge.followMemoryEvents`: incluir logs de eventos no modo bridge
- `search.backend`: `shared` ou `local`
- `search.corpus`: `wiki`, `memory` ou `all`
- `context.includeCompiledDigestPrompt`: anexar uma captura compacta do resumo às seções de prompt de memória
- `context.includeCompiledDigestPrompt`: anexar instantâneo compacto de resumo às seções de prompt de memória
- `render.createBacklinks`: gerar blocos relacionados determinísticos
- `render.createDashboards`: gerar páginas de painel
### Exemplo: QMD + modo bridge
Use isto quando quiser o QMD para recuperação e `memory-wiki` para uma camada de
conhecimento mantida:
Use isto quando quiser QMD para recuperação e `memory-wiki` para uma camada
de conhecimento mantida:
```json5
{
memory: {
backend: "qmd",
},
plugins: {
entries: {
"memory-wiki": {
enabled: true,
config: {
@ -473,11 +476,11 @@ conhecimento mantida:
}
```
Isto mantém:
Isso mantém:
- o QMD responsável pela recuperação de memória ativa
- QMD responsável pela recuperação de Active Memory
- `memory-wiki` focado em páginas compiladas e painéis
- o formato do prompt inalterado até que você ative intencionalmente os prompts de resumo compilado
- o formato do prompt inalterado até você habilitar intencionalmente prompts de resumo compilado
## CLI
@ -501,30 +504,30 @@ Consulte [CLI: wiki](/pt-BR/cli/wiki) para a referência completa de comandos.
## Suporte ao Obsidian
Quando `vault.renderMode` é `obsidian`, o plugin grava Markdown amigável ao
Obsidian e pode opcionalmente usar a CLI oficial `obsidian`.
Quando `vault.renderMode` é `obsidian`, o Plugin grava Markdown compatível com
Obsidian e pode, opcionalmente, usar a CLI oficial `obsidian`.
Os fluxos de trabalho compatíveis incluem:
- sondagem de status
- busca no vault
- busca no cofre
- abertura de uma página
- invocação de um comando do Obsidian
- salto para a nota diária
Isto é opcional. A wiki ainda funciona no modo nativo sem o Obsidian.
Isso é opcional. A wiki ainda funciona no modo nativo sem Obsidian.
## Fluxo de trabalho recomendado
1. Mantenha seu plugin de memória ativa para recuperação/promoção/dreaming.
2. Ative `memory-wiki`.
3. Comece com o modo `isolated`, a menos que você queira explicitamente o modo bridge.
4. Use `wiki_search` / `wiki_get` quando a proveniência for importante.
1. Mantenha seu Plugin de Active Memory para recuperação/promoção/Dreaming.
2. Habilite `memory-wiki`.
3. Comece com o modo `isolated`, a menos que queira explicitamente o modo bridge.
4. Use `wiki_search` / `wiki_get` quando a procedência for importante.
5. Use `wiki_apply` para sínteses restritas ou atualizações de metadados.
6. Execute `wiki_lint` após alterações significativas.
7. Ative painéis se quiser visibilidade de itens obsoletos/contradições.
7. Ative painéis se quiser visibilidade sobre itens obsoletos/contradições.
## Documentação relacionada
## Documentos relacionados
- [Visão geral de memória](/pt-BR/concepts/memory)
- [CLI: memory](/pt-BR/cli/memory)

335
docs/pt-BR/plugins/voice-call.md
View File

@ -1,38 +1,38 @@
---
read_when:
- Você quer fazer uma chamada de voz de saída pelo OpenClaw
- Você está configurando ou desenvolvendo o Plugin de chamadas de voz
- Você está configurando ou desenvolvendo o plugin de chamada de voz
- Você precisa de voz em tempo real ou transcrição por streaming em telefonia
sidebarTitle: Voice call
summary: Faça chamadas de voz de saída e aceite chamadas de voz de entrada via Twilio, Telnyx ou Plivo, com voz em tempo real e transcrição em fluxo contínuo opcionais
summary: Faça chamadas de voz de saída e receba chamadas de voz de entrada via Twilio, Telnyx ou Plivo, com voz em tempo real opcional e transcrição em streaming
title: Plugin de chamada de voz
x-i18n:
generated_at: "2026-05-02T22:21:34Z"
generated_at: "2026-05-04T05:54:28Z"
model: gpt-5.5
provider: openai
source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a
source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857
source_path: plugins/voice-call.md
workflow: 16
---
Chamadas de voz para OpenClaw por meio de um plugin. Compatível com notificações de saída,
conversas de múltiplos turnos, voz em tempo real full-duplex, transcrição
por streaming e chamadas recebidas com políticas de allowlist.
Chamadas de voz para OpenClaw via um Plugin. Compatível com notificações de saída,
conversas de vários turnos, voz em tempo real full-duplex, transcrição por
streaming e chamadas recebidas com políticas de lista de permissões.
**Provedores atuais:** `twilio` (Programmable Voice + Media Streams),
`telnyx` (Call Control v2), `plivo` (Voice API + transferência XML + fala GetInput
), `mock` (desenvolvimento/sem rede).
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
speech), `mock` (desenvolvimento/sem rede).
<Note>
O plugin Voice Call roda **dentro do processo do Gateway**. Se você usa um
Gateway remoto, instale e configure o plugin na máquina que executa
o Gateway e depois reinicie o Gateway para carregá-lo.
O Plugin Voice Call é executado **dentro do processo do Gateway**. Se você usa um
Gateway remoto, instale e configure o Plugin na máquina que executa
o Gateway e reinicie o Gateway para carregá-lo.
</Note>
## Início rápido
<Steps>
<Step title="Instale o plugin">
<Step title="Instale o Plugin">
<Tabs>
<Tab title="Do npm">
```bash
@ -48,17 +48,17 @@ o Gateway e depois reinicie o Gateway para carregá-lo.
</Tab>
</Tabs>
Use o pacote sem versão para acompanhar a tag oficial de lançamento atual. Fixe uma
Use o pacote sem versão para acompanhar a tag de lançamento oficial atual. Fixe uma
versão exata somente quando precisar de uma instalação reproduzível.
Reinicie o Gateway depois para que o plugin seja carregado.
Depois, reinicie o Gateway para que o Plugin seja carregado.
</Step>
<Step title="Configure o provedor e o webhook">
Defina a configuração em `plugins.entries.voice-call.config` (veja
[Configuração](#configuration) abaixo para a estrutura completa). No mínimo:
`provider`, credenciais do provedor, `fromNumber` e uma URL de webhook
acessível publicamente.
<Step title="Configure o provedor e o Webhook">
Defina a configuração em `plugins.entries.voice-call.config` (consulte
[Configuração](#configuration) abaixo para ver a estrutura completa). No mínimo:
`provider`, credenciais do provedor, `fromNumber` e uma URL de Webhook
publicamente acessível.
</Step>
<Step title="Verifique a configuração">
```bash
@ -66,19 +66,19 @@ o Gateway e depois reinicie o Gateway para carregá-lo.
```
A saída padrão é legível em logs de chat e terminais. Ela verifica
a habilitação do plugin, credenciais do provedor, exposição do webhook e se
a ativação do Plugin, as credenciais do provedor, a exposição do Webhook e se
apenas um modo de áudio (`streaming` ou `realtime`) está ativo. Use
`--json` para scripts.
</Step>
<Step title="Teste básico">
<Step title="Teste de fumaça">
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
```
Ambos são execuções simuladas por padrão. Adicione `--yes` para realmente fazer uma chamada
curta de notificação de saída:
Ambos são simulações por padrão. Adicione `--yes` para realmente fazer uma breve
chamada de notificação de saída:
```bash
openclaw voicecall smoke --to "+15555550123" --yes
@ -88,21 +88,21 @@ o Gateway e depois reinicie o Gateway para carregá-lo.
</Steps>
<Warning>
Para Twilio, Telnyx e Plivo, a configuração deve resolver para uma **URL de webhook pública**.
Para Twilio, Telnyx e Plivo, a configuração deve resolver para uma **URL de Webhook pública**.
Se `publicUrl`, a URL do túnel, a URL do Tailscale ou o fallback de serviço
resolver para loopback ou espaço de rede privada, a configuração falha em vez de
iniciar um provedor que não consegue receber webhooks de operadora.
iniciar um provedor que não consegue receber webhooks de operadoras.
</Warning>
## Configuração
Se `enabled: true`, mas o provedor selecionado não tiver credenciais,
a inicialização do Gateway registra um aviso de configuração incompleta com as chaves ausentes e
pula a inicialização do runtime. Comandos, chamadas RPC e ferramentas de agente ainda
ignora a inicialização do runtime. Comandos, chamadas RPC e ferramentas de agente ainda
retornam a configuração exata ausente do provedor quando usados.
<Note>
As credenciais do Voice Call aceitam SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` e `plugins.entries.voice-call.config.tts.providers.*.apiKey` são resolvidos pela superfície padrão de SecretRef; veja [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface).
As credenciais do voice-call aceitam SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` e `plugins.entries.voice-call.config.tts.providers.*.apiKey` são resolvidos pela superfície SecretRef padrão; consulte [superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface).
</Note>
```json5
@ -176,25 +176,25 @@ As credenciais do Voice Call aceitam SecretRefs. `plugins.entries.voice-call.con
<AccordionGroup>
<Accordion title="Notas de exposição e segurança do provedor">
- Twilio, Telnyx e Plivo exigem uma URL de webhook **acessível publicamente**.
- Twilio, Telnyx e Plivo exigem uma URL de Webhook **publicamente acessível**.
- `mock` é um provedor local de desenvolvimento (sem chamadas de rede).
- Telnyx exige `telnyx.publicKey` (ou `TELNYX_PUBLIC_KEY`), a menos que `skipSignatureVerification` seja true.
- `skipSignatureVerification` é somente para testes locais.
- No nível gratuito do ngrok, defina `publicUrl` como a URL exata do ngrok; a verificação de assinatura é sempre aplicada.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` permite webhooks da Twilio com assinaturas inválidas **somente** quando `tunnel.provider="ngrok"` e `serve.bind` é loopback (agente local do ngrok). Somente desenvolvimento local.
- URLs do nível gratuito do ngrok podem mudar ou adicionar comportamento intersticial; se `publicUrl` divergir, as assinaturas da Twilio falharão. Produção: prefira um domínio estável ou um funnel do Tailscale.
- No plano gratuito do ngrok, defina `publicUrl` como a URL exata do ngrok; a verificação de assinatura é sempre aplicada.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` permite Webhooks do Twilio com assinaturas inválidas **somente** quando `tunnel.provider="ngrok"` e `serve.bind` é loopback (agente local do ngrok). Somente desenvolvimento local.
- URLs do plano gratuito do Ngrok podem mudar ou adicionar comportamento intersticial; se `publicUrl` divergir, as assinaturas do Twilio falham. Produção: prefira um domínio estável ou um funnel do Tailscale.
</Accordion>
<Accordion title="Limites de conexão de streaming">
- `streaming.preStartTimeoutMs` fecha sockets que nunca enviam um quadro `start` válido.
- `streaming.preStartTimeoutMs` fecha sockets que nunca enviam um frame `start` válido.
- `streaming.maxPendingConnections` limita o total de sockets pré-início não autenticados.
- `streaming.maxPendingConnectionsPerIp` limita sockets pré-início não autenticados por IP de origem.
- `streaming.maxConnections` limita o total de sockets abertos de stream de mídia (pendentes + ativos).
- `streaming.maxConnections` limita o total de sockets de stream de mídia abertos (pendentes + ativos).
</Accordion>
<Accordion title="Migrações de configuração legadas">
Configurações antigas que usam `provider: "log"`, `twilio.from` ou chaves
OpenAI legadas em `streaming.*` são reescritas por `openclaw doctor --fix`.
Configurações antigas que usam `provider: "log"`, `twilio.from` ou chaves OpenAI
`streaming.*` legadas são reescritas por `openclaw doctor --fix`.
O fallback de runtime ainda aceita as chaves antigas do voice-call por enquanto, mas
o caminho de reescrita é `openclaw doctor --fix` e o shim de compatibilidade é
temporário.
@ -215,13 +215,13 @@ As credenciais do Voice Call aceitam SecretRefs. `plugins.entries.voice-call.con
Por padrão, o Voice Call usa `sessionScope: "per-phone"` para que chamadas repetidas do
mesmo chamador mantenham a memória da conversa. Defina `sessionScope: "per-call"` quando
cada chamada da operadora deve começar com contexto novo, por exemplo recepção,
reservas, IVR ou fluxos de ponte do Google Meet em que o mesmo número de telefone pode
agendamento, IVR ou fluxos de ponte do Google Meet em que o mesmo número de telefone pode
representar reuniões diferentes.
## Conversas de voz em tempo real
`realtime` seleciona um provedor de voz em tempo real full-duplex para áudio
de chamada ao vivo. Ele é separado de `streaming`, que apenas encaminha áudio para
`realtime` seleciona um provedor de voz em tempo real full-duplex para áudio de chamada
ao vivo. Ele é separado de `streaming`, que apenas encaminha áudio para
provedores de transcrição em tempo real.
<Warning>
@ -232,31 +232,34 @@ modo de áudio por chamada.
Comportamento atual do runtime:
- `realtime.enabled` é compatível com Twilio Media Streams.
- `realtime.provider` é opcional. Se não for definido, o Voice Call usa o primeiro provedor de voz em tempo real registrado.
- Provedores de voz em tempo real incluídos: Google Gemini Live (`google`) e OpenAI (`openai`), registrados por seus plugins de provedor.
- `realtime.provider` é opcional. Se não estiver definido, o Voice Call usa o primeiro provedor de voz em tempo real registrado.
- Provedores de voz em tempo real incluídos: Google Gemini Live (`google`) e OpenAI (`openai`), registrados por seus Plugins de provedor.
- A configuração bruta pertencente ao provedor fica em `realtime.providers.<providerId>`.
- O Voice Call expõe a ferramenta em tempo real compartilhada `openclaw_agent_consult` por padrão. O modelo em tempo real pode chamá-la quando o chamador pedir raciocínio mais aprofundado, informações atuais ou ferramentas normais do OpenClaw.
- `realtime.fastContext.enabled` fica desativado por padrão. Quando ativado, o Voice Call primeiro pesquisa contexto de memória/sessão indexado para a pergunta de consulta e retorna esses trechos ao modelo em tempo real dentro de `realtime.fastContext.timeoutMs`, antes de recorrer ao agente de consulta completo somente se `realtime.fastContext.fallbackToConsult` for true.
- Se `realtime.provider` apontar para um provedor não registrado, ou se nenhum provedor de voz em tempo real estiver registrado, o Voice Call registra um aviso e ignora a mídia em tempo real em vez de falhar o plugin inteiro.
- As chaves de sessão de consulta reutilizam a sessão de chamada armazenada quando disponível e depois recorrem ao `sessionScope` configurado (`per-phone` por padrão, ou `per-call` para chamadas isoladas).
- O Voice Call expõe a ferramenta compartilhada em tempo real `openclaw_agent_consult` por padrão. O modelo em tempo real pode chamá-la quando o chamador pede raciocínio mais profundo, informações atuais ou ferramentas normais do OpenClaw.
- `realtime.fastContext.enabled` fica desativado por padrão. Quando ativado, o Voice Call primeiro pesquisa memória indexada/contexto de sessão para a pergunta de consulta e retorna esses trechos ao modelo em tempo real dentro de `realtime.fastContext.timeoutMs` antes de recorrer ao agente de consulta completo somente se `realtime.fastContext.fallbackToConsult` for true.
- Se `realtime.provider` apontar para um provedor não registrado, ou se nenhum provedor de voz em tempo real estiver registrado, o Voice Call registra um aviso e ignora a mídia em tempo real em vez de fazer todo o Plugin falhar.
- As chaves de sessão de consulta reutilizam a sessão de chamada armazenada quando disponível e, em seguida, recorrem ao `sessionScope` configurado (`per-phone` por padrão, ou `per-call` para chamadas isoladas).
### Política de ferramenta
### Política de ferramentas
`realtime.toolPolicy` controla a execução da consulta:
`realtime.toolPolicy` controla a execução de consulta:
| Política | Comportamento |
| Política | Comportamento |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | Expõe a ferramenta de consulta e limita o agente regular a `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` e `memory_get`. |
| `owner` | Expõe a ferramenta de consulta e permite que o agente regular use a política normal de ferramentas do agente. |
| `none` | Não expõe a ferramenta de consulta. `realtime.tools` personalizadas ainda são repassadas ao provedor em tempo real. |
| `none` | Não expõe a ferramenta de consulta. `realtime.tools` customizadas ainda são repassadas ao provedor em tempo real. |
### Exemplos de provedor em tempo real
### Exemplos de provedores em tempo real
<Tabs>
<Tab title="Google Gemini Live">
Padrões: chave de API de `realtime.providers.google.apiKey`,
`GEMINI_API_KEY` ou `GOOGLE_GENERATIVE_AI_API_KEY`; modelo
`gemini-2.5-flash-native-audio-preview-12-2025`; voz `Kore`.
`sessionResumption` e `contextWindowCompression` ficam ativados por padrão para chamadas mais longas
e reconectáveis. Use `silenceDurationMs`, `startSensitivity` e
`endSensitivity` para ajustar turnos de fala mais rápidos em áudio telefônico.
```json5
{
@ -277,6 +280,8 @@ Comportamento atual do runtime:
apiKey: "${GEMINI_API_KEY}",
model: "gemini-2.5-flash-native-audio-preview-12-2025",
voice: "Kore",
silenceDurationMs: 500,
startSensitivity: "high",
},
},
},
@ -319,13 +324,13 @@ específicas do provedor.
`streaming` seleciona um provedor de transcrição em tempo real para áudio de chamada ao vivo.
Comportamento atual do runtime:
Comportamento atual em runtime:
- `streaming.provider` é opcional. Se não definido, Voice Call usa o primeiro provedor de transcrição em tempo real registrado.
- `streaming.provider` é opcional. Se não for definido, o Voice Call usa o primeiro provedor de transcrição em tempo real registrado.
- Provedores de transcrição em tempo real incluídos: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) e xAI (`xai`), registrados por seus plugins de provedor.
- A configuração bruta pertencente ao provedor fica em `streaming.providers.<providerId>`.
- Depois que o Twilio envia uma mensagem `start` de stream aceita, Voice Call registra o stream imediatamente, enfileira a mídia recebida por meio do provedor de transcrição enquanto o provedor se conecta e inicia a saudação inicial somente depois que a transcrição em tempo real está pronta.
- Se `streaming.provider` apontar para um provedor não registrado, ou se nenhum estiver registrado, Voice Call registra um aviso e ignora o streaming de mídia em vez de fazer o Plugin inteiro falhar.
- A configuração bruta de propriedade do provedor fica em `streaming.providers.<providerId>`.
- Depois que a Twilio envia uma mensagem `start` de stream aceita, o Voice Call registra o stream imediatamente, enfileira mídia de entrada pelo provedor de transcrição enquanto o provedor se conecta e inicia a saudação inicial somente depois que a transcrição em tempo real está pronta.
- Se `streaming.provider` apontar para um provedor não registrado, ou nenhum estiver registrado, o Voice Call registra um aviso e ignora o streaming de mídia em vez de fazer o plugin inteiro falhar.
### Exemplos de provedor de streaming
@ -397,9 +402,9 @@ Comportamento atual do runtime:
## TTS para chamadas
Voice Call usa a configuração central `messages.tts` para streaming de
fala em chamadas. Você pode substituí-la na configuração do Plugin com o
**mesmo formato** — ela é mesclada recursivamente com `messages.tts`.
O Voice Call usa a configuração central `messages.tts` para fala por streaming
em chamadas. Você pode sobrescrevê-la na configuração do plugin com o
**mesmo formato** — ela é mesclada em profundidade com `messages.tts`.
```json5
{
@ -422,16 +427,16 @@ o transporte atual da Microsoft não expõe saída PCM de telefonia.
Notas de comportamento:
- Chaves legadas `tts.<provider>` dentro da configuração do Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) são reparadas por `openclaw doctor --fix`; a configuração commitada deve usar `tts.providers.<provider>`.
- O TTS central é usado quando o streaming de mídia do Twilio está habilitado; caso contrário, as chamadas recorrem às vozes nativas do provedor.
- Se um stream de mídia do Twilio já estiver ativo, Voice Call não recorre ao TwiML `<Say>`. Se o TTS de telefonia estiver indisponível nesse estado, a solicitação de reprodução falha em vez de misturar dois caminhos de reprodução.
- Quando o TTS de telefonia recorre a um provedor secundário, Voice Call registra um aviso com a cadeia de provedores (`from`, `to`, `attempts`) para depuração.
- Quando a interrupção por fala ou o encerramento do stream do Twilio limpa a fila de TTS pendente, as solicitações de reprodução enfileiradas são resolvidas em vez de deixar chamadores aguardando indefinidamente a conclusão da reprodução.
- Chaves legadas `tts.<provider>` dentro da configuração do plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) são reparadas por `openclaw doctor --fix`; a configuração confirmada deve usar `tts.providers.<provider>`.
- O TTS central é usado quando o streaming de mídia da Twilio está ativado; caso contrário, as chamadas recorrem às vozes nativas do provedor.
- Se um stream de mídia da Twilio já estiver ativo, o Voice Call não recorre a `<Say>` do TwiML. Se TTS de telefonia estiver indisponível nesse estado, a solicitação de reprodução falha em vez de misturar dois caminhos de reprodução.
- Quando o TTS de telefonia recorre a um provedor secundário, o Voice Call registra um aviso com a cadeia de provedores (`from`, `to`, `attempts`) para depuração.
- Quando a interrupção por fala ou o encerramento de stream da Twilio limpa a fila pendente de TTS, as solicitações de reprodução enfileiradas são concluídas em vez de deixar chamadores aguardando a conclusão da reprodução.
### Exemplos de TTS
<Tabs>
<Tab title="Core TTS only">
<Tab title="Somente TTS central">
```json5
{
messages: {
@ -445,7 +450,7 @@ Notas de comportamento:
}
```
</Tab>
<Tab title="Override to ElevenLabs (calls only)">
<Tab title="Sobrescrever para ElevenLabs (somente chamadas)">
```json5
{
plugins: {
@ -469,7 +474,7 @@ Notas de comportamento:
}
```
</Tab>
<Tab title="OpenAI model override (deep-merge)">
<Tab title="Sobrescrita de modelo OpenAI (mesclagem profunda)">
```json5
{
plugins: {
@ -495,7 +500,7 @@ Notas de comportamento:
## Chamadas recebidas
A política de chamadas recebidas usa `disabled` como padrão. Para habilitar chamadas recebidas, defina:
A política de entrada tem `disabled` como padrão. Para ativar chamadas recebidas, defina:
```json5
{
@ -506,33 +511,33 @@ A política de chamadas recebidas usa `disabled` como padrão. Para habilitar ch
```
<Warning>
`inboundPolicy: "allowlist"` é uma verificação de ID de chamador de baixa garantia. O
Plugin normaliza o valor `From` fornecido pelo provedor e o compara com
`allowFrom`. A verificação de Webhook autentica a entrega pelo provedor e
a integridade do payload, mas **não** comprova a titularidade do número
do chamador PSTN/VoIP. Trate `allowFrom` como filtragem por ID de chamador,
não como identidade forte do chamador.
`inboundPolicy: "allowlist"` é uma triagem de ID do chamador de baixa garantia. O
plugin normaliza o valor `From` fornecido pelo provedor e o compara com
`allowFrom`. A verificação de Webhook autentica a entrega do provedor e
a integridade do payload, mas **não** comprova a propriedade do número do
chamador PSTN/VoIP. Trate `allowFrom` como filtragem de ID do chamador, não como
identidade forte do chamador.
</Warning>
Respostas automáticas usam o sistema de agentes. Ajuste com `responseModel`,
Respostas automáticas usam o sistema de agente. Ajuste com `responseModel`,
`responseSystemPrompt` e `responseTimeoutMs`.
### Roteamento por número
Use `numbers` quando um Plugin Voice Call recebe chamadas para vários números
de telefone e cada número deve se comportar como uma linha diferente. Por exemplo, um
Use `numbers` quando um plugin Voice Call recebe chamadas para vários números de telefone
e cada número deve se comportar como uma linha diferente. Por exemplo, um
número pode usar um assistente pessoal casual enquanto outro usa uma persona
comercial, um agente de resposta diferente e uma voz TTS diferente.
As rotas são selecionadas a partir do número discado `To` fornecido pelo provedor. As chaves devem ser
números E.164. Quando uma chamada chega, Voice Call resolve a rota correspondente uma vez,
números E.164. Quando uma chamada chega, o Voice Call resolve a rota correspondente uma vez,
armazena a rota correspondente no registro da chamada e reutiliza essa configuração efetiva
para a saudação, o caminho clássico de resposta automática, o caminho de consulta em tempo real e a reprodução
TTS. Se nenhuma rota corresponder, a configuração global do Voice Call é usada.
Chamadas de saída não usam `numbers`; passe o destino de saída, a mensagem e a
sessão explicitamente ao iniciar a chamada.
TTS. Se nenhuma rota corresponder, a configuração global do Voice Call será usada.
Chamadas de saída não usam `numbers`; passe o destino de saída, a mensagem e
a sessão explicitamente ao iniciar a chamada.
As substituições de rota atualmente aceitam:
Atualmente, sobrescritas de rota aceitam:
- `inboundGreeting`
- `tts`
@ -541,8 +546,8 @@ As substituições de rota atualmente aceitam:
- `responseSystemPrompt`
- `responseTimeoutMs`
O valor de rota `tts` é mesclado recursivamente sobre a configuração global `tts` do Voice Call, então
geralmente você pode substituir apenas a voz do provedor:
O valor de rota `tts` é mesclado em profundidade sobre a configuração global `tts` do Voice Call, então
geralmente você pode sobrescrever apenas a voz do provedor:
```json5
{
@ -570,50 +575,50 @@ geralmente você pode substituir apenas a voz do provedor:
### Contrato de saída falada
Para respostas automáticas, Voice Call acrescenta um contrato estrito de saída falada ao
Para respostas automáticas, o Voice Call acrescenta um contrato estrito de saída falada ao
prompt do sistema:
```text
{"spoken":"..."}
```
Voice Call extrai o texto de fala de forma defensiva:
O Voice Call extrai texto de fala defensivamente:
- Ignora payloads marcados como conteúdo de raciocínio/erro.
- Analisa JSON direto, JSON cercado por fences ou chaves `"spoken"` inline.
- Recorre a texto simples e remove parágrafos iniciais que provavelmente sejam de planejamento/meta.
- Analisa JSON direto, JSON cercado ou chaves `"spoken"` inline.
- Recorre a texto simples e remove prováveis parágrafos iniciais de planejamento/metadados.
Isso mantém a reprodução falada focada no texto voltado ao chamador e evita
Isso mantém a reprodução falada focada em texto voltado ao chamador e evita
vazar texto de planejamento para o áudio.
### Comportamento de início de conversa
Para chamadas `conversation` de saída, o tratamento da primeira mensagem é vinculado ao estado de reprodução
ao vivo:
Para chamadas `conversation` de saída, o tratamento da primeira mensagem está vinculado ao estado de
reprodução ao vivo:
- A limpeza da fila por interrupção de fala e a resposta automática são suprimidas somente enquanto a saudação inicial está sendo falada ativamente.
- Se a reprodução inicial falhar, a chamada retorna para `listening` e a mensagem inicial permanece enfileirada para nova tentativa.
- A reprodução inicial para streaming do Twilio começa na conexão do stream sem atraso extra.
- A interrupção por fala aborta a reprodução ativa e limpa entradas TTS do Twilio enfileiradas, mas ainda não em reprodução. Entradas limpas são resolvidas como ignoradas, para que a lógica de resposta seguinte possa continuar sem esperar por áudio que nunca será reproduzido.
- Conversas de voz em tempo real usam o próprio turno de abertura do stream em tempo real. Voice Call **não** publica uma atualização TwiML `<Say>` legada para essa mensagem inicial, então sessões `<Connect><Stream>` de saída permanecem anexadas.
- Se a reprodução inicial falhar, a chamada volta para `listening` e a mensagem inicial permanece enfileirada para nova tentativa.
- A reprodução inicial para streaming da Twilio começa na conexão do stream, sem atraso extra.
- A interrupção por fala aborta a reprodução ativa e limpa entradas TTS da Twilio enfileiradas, mas ainda não em reprodução. As entradas limpas são resolvidas como ignoradas, então a lógica de resposta subsequente pode continuar sem esperar por áudio que nunca será reproduzido.
- Conversas de voz em tempo real usam o próprio turno inicial do stream em tempo real. O Voice Call **não** publica uma atualização TwiML legada `<Say>` para essa mensagem inicial, então sessões de saída `<Connect><Stream>` permanecem anexadas.
### Período de tolerância de desconexão do stream do Twilio
### Carência de desconexão de stream da Twilio
Quando um stream de mídia do Twilio desconecta, Voice Call aguarda **2000 ms** antes de
Quando um stream de mídia da Twilio desconecta, o Voice Call espera **2000 ms** antes de
encerrar a chamada automaticamente:
- Se o stream reconectar durante essa janela, o encerramento automático é cancelado.
- Se nenhum stream se registrar novamente após o período de tolerância, a chamada é encerrada para evitar chamadas ativas travadas.
- Se nenhum stream for registrado novamente após o período de carência, a chamada é encerrada para evitar chamadas ativas presas.
## Coletor de chamadas obsoletas
Use `staleCallReaperSeconds` para encerrar chamadas que nunca recebem um Webhook
terminal (por exemplo, chamadas em modo de notificação que nunca completam). O padrão
é `0` (desabilitado).
terminal (por exemplo, chamadas em modo de notificação que nunca são concluídas). O padrão
é `0` (desativado).
Intervalos recomendados:
- **Produção:** `120`–`300` segundos para fluxos no estilo de notificação.
- **Produção:** `120`–`300` segundos para fluxos do tipo notificação.
- Mantenha esse valor **maior que `maxDurationSeconds`** para que chamadas normais possam terminar. Um bom ponto de partida é `maxDurationSeconds + 30–60` segundos.
```json5
@ -633,26 +638,26 @@ Intervalos recomendados:
## Segurança de Webhook
Quando um proxy ou túnel fica na frente do Gateway, o Plugin
Quando um proxy ou túnel fica na frente do Gateway, o plugin
reconstrói a URL pública para verificação de assinatura. Estas opções
controlam quais cabeçalhos encaminhados são confiáveis:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
Hosts da lista de permissões a partir de cabeçalhos de encaminhamento.
Hosts permitidos a partir de cabeçalhos de encaminhamento.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
Confiar em cabeçalhos encaminhados sem uma lista de permissões.
Confia em cabeçalhos encaminhados sem uma lista de permissão.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
Confiar em cabeçalhos encaminhados somente quando o IP remoto da solicitação corresponder à lista.
Confia em cabeçalhos encaminhados somente quando o IP remoto da solicitação corresponde à lista.
</ParamField>
Proteções adicionais:
- A **proteção contra repetição** de Webhook é habilitada para Twilio e Plivo. Solicitações válidas de Webhook repetidas são reconhecidas, mas ignoradas para efeitos colaterais.
- Turnos de conversa do Twilio incluem um token por turno em callbacks `<Gather>`, então callbacks de fala obsoletos/repetidos não podem satisfazer um turno de transcrição pendente mais recente.
- A **proteção contra repetição** de Webhook está ativada para Twilio e Plivo. Solicitações de Webhook válidas repetidas são reconhecidas, mas ignoradas quanto a efeitos colaterais.
- Turnos de conversa da Twilio incluem um token por turno em callbacks `<Gather>`, então callbacks de fala obsoletos/repetidos não podem satisfazer um turno de transcrição pendente mais recente.
- Solicitações de Webhook não autenticadas são rejeitadas antes da leitura do corpo quando os cabeçalhos de assinatura exigidos pelo provedor estão ausentes.
- O Webhook do voice-call usa o perfil compartilhado de corpo de pré-autenticação (64 KB / 5 segundos), além de um limite em andamento por IP antes da verificação de assinatura.
- O Webhook voice-call usa o perfil de corpo pré-autenticação compartilhado (64 KB / 5 segundos), além de um limite de solicitações em andamento por IP antes da verificação de assinatura.
Exemplo com um host público estável:
@ -688,21 +693,21 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
Quando o Gateway já está em execução, comandos operacionais `voicecall` delegam
para o runtime de voice-call pertencente ao Gateway, para que a CLI não vincule um segundo
servidor de Webhook. Se nenhum Gateway estiver acessível, os comandos recorrem a um
runtime independente da CLI.
Quando o Gateway já está em execução, os comandos operacionais `voicecall` delegam
ao runtime de chamada de voz pertencente ao Gateway para que a CLI não vincule um
segundo servidor de webhook. Se nenhum Gateway estiver acessível, os comandos recorrem
a um runtime autônomo da CLI.
`latency` lê `calls.jsonl` no caminho padrão de armazenamento de chamadas de voz.
Use `--file <path>` para apontar para um log diferente e `--last <n>` para limitar
a análise aos últimos N registros (padrão 200). A saída inclui p50/p90/p99
para latência de turno e tempos de espera por escuta.
a análise aos últimos N registros (padrão: 200). A saída inclui p50/p90/p99
para a latência de turnos e tempos de espera de escuta.
## Ferramenta do agente
Nome da ferramenta: `voice_call`.
| Ação | Args |
| Ação | Argumentos |
| --------------- | ------------------------------------------ |
| `initiate_call` | `message`, `to?`, `mode?`, `dtmfSequence?` |
| `continue_call` | `callId`, `message` |
@ -711,26 +716,26 @@ Nome da ferramenta: `voice_call`.
| `end_call` | `callId` |
| `get_status` | `callId` |
Este repositório inclui uma documentação de skill correspondente em `skills/voice-call/SKILL.md`.
Este repositório fornece um documento de skill correspondente em `skills/voice-call/SKILL.md`.
## RPC do Gateway
| Método | Args |
| ------------------- | ------------------------------------------ |
| Método | Argumentos |
| -------------------- | ------------------------------------------ |
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
`dtmfSequence` só é válido com `mode: "conversation"`. Chamadas no modo de notificação
devem usar `voicecall.dtmf` depois que a chamada existir se precisarem de
dígitos pós-conexão.
`dtmfSequence` só é válido com `mode: "conversation"`. Chamadas em modo de notificação
devem usar `voicecall.dtmf` depois que a chamada existir se precisarem de dígitos
após a conexão.
## Solução de problemas
### A configuração falha na exposição do Webhook
### A configuração falha na exposição do webhook
Execute a configuração no mesmo ambiente que executa o Gateway:
@ -740,18 +745,18 @@ openclaw voicecall setup --json
```
Para `twilio`, `telnyx` e `plivo`, `webhook-exposure` deve estar verde. Uma
`publicUrl` configurada ainda falha quando aponta para um espaço de rede local
ou privada, porque a operadora não consegue chamar de volta esses endereços. Não use
`publicUrl` configurada ainda falha quando aponta para uma rede local ou privada,
porque a operadora não consegue chamar de volta esses endereços. Não use
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
`192.168.x`, `169.254.x`, `fc00::/7` ou `fd00::/8` como `publicUrl`.
Chamadas de saída no modo de notificação do Twilio enviam o `<Say>` TwiML inicial diretamente na
solicitação de criação da chamada, então a primeira mensagem falada não depende de o Twilio
buscar o Webhook TwiML. Um Webhook público ainda é obrigatório para callbacks de status,
chamadas de conversa, DTMF pré-conexão, streams em tempo real e controle de chamada
pós-conexão.
Chamadas de saída no modo de notificação da Twilio enviam o TwiML `<Say>` inicial diretamente na
solicitação de criação de chamada, então a primeira mensagem falada não depende de a Twilio
buscar o TwiML do webhook. Um webhook público ainda é obrigatório para retornos de status,
chamadas de conversa, DTMF antes da conexão, streams em tempo real e controle de chamada
após a conexão.
Use um caminho de exposição pública:
Use um caminho de exposição público:
```json5
{
@ -771,7 +776,7 @@ Use um caminho de exposição pública:
}
```
Depois de alterar a configuração, reinicie ou recarregue o Gateway e então execute:
Depois de alterar a configuração, reinicie ou recarregue o Gateway e execute:
```bash
openclaw voicecall setup
@ -782,7 +787,7 @@ openclaw voicecall smoke
### As credenciais do provedor falham
Confira o provedor selecionado e os campos de credenciais obrigatórios:
Verifique o provedor selecionado e os campos de credenciais obrigatórios:
- Twilio: `twilio.accountSid`, `twilio.authToken` e `fromNumber`, ou
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` e `TWILIO_FROM_NUMBER`.
@ -791,18 +796,18 @@ Confira o provedor selecionado e os campos de credenciais obrigatórios:
- Plivo: `plivo.authId`, `plivo.authToken` e `fromNumber`.
As credenciais devem existir no host do Gateway. Editar um perfil de shell local
não afeta um Gateway que já está em execução até que ele reinicie ou recarregue
seu ambiente.
não afeta um Gateway que já está em execução até que ele reinicie ou recarregue seu
ambiente.
### As chamadas iniciam, mas os Webhooks do provedor não chegam
### As chamadas iniciam, mas os webhooks do provedor não chegam
Confirme se o console do provedor aponta para a URL pública exata do Webhook:
Confirme que o console do provedor aponta para a URL pública exata do webhook:
```text
https://voice.example.com/voice/webhook
```
Em seguida, inspecione o estado de runtime:
Em seguida, inspecione o estado do runtime:
```bash
openclaw voicecall status --call-id <id>
@ -813,77 +818,77 @@ openclaw logs --follow
Causas comuns:
- `publicUrl` aponta para um caminho diferente de `serve.path`.
- A URL do túnel mudou depois que o Gateway iniciou.
- A URL do túnel mudou depois que o Gateway foi iniciado.
- Um proxy encaminha a solicitação, mas remove ou reescreve cabeçalhos de host/proto.
- O firewall ou DNS roteia o hostname público para algum lugar diferente do Gateway.
- Firewall ou DNS roteia o hostname público para outro lugar que não o Gateway.
- O Gateway foi reiniciado sem o Plugin Voice Call habilitado.
Quando um proxy reverso ou túnel está na frente do Gateway, defina
Quando um proxy reverso ou túnel estiver na frente do Gateway, defina
`webhookSecurity.allowedHosts` como o hostname público ou use
`webhookSecurity.trustedProxyIPs` para um endereço de proxy conhecido. Use
`webhookSecurity.trustForwardingHeaders` apenas quando o limite do proxy estiver sob
`webhookSecurity.trustForwardingHeaders` somente quando o limite do proxy estiver sob
seu controle.
### A verificação de assinatura falha
As assinaturas do provedor são verificadas contra a URL pública que o OpenClaw reconstrói
As assinaturas do provedor são verificadas em relação à URL pública que o OpenClaw reconstrói
a partir da solicitação recebida. Se as assinaturas falharem:
- Confirme se a URL do Webhook do provedor corresponde exatamente a `publicUrl`, incluindo
- Confirme que a URL do webhook do provedor corresponde exatamente a `publicUrl`, incluindo
esquema, host e caminho.
- Para URLs do plano gratuito do ngrok, atualize `publicUrl` quando o hostname do túnel mudar.
- Para URLs do nível gratuito do ngrok, atualize `publicUrl` quando o hostname do túnel mudar.
- Garanta que o proxy preserve os cabeçalhos originais de host e proto, ou configure
`webhookSecurity.allowedHosts`.
- Não habilite `skipSignatureVerification` fora de testes locais.
### Entradas do Google Meet pelo Twilio falham
### As entradas da Twilio no Google Meet falham
O Google Meet usa este Plugin para entradas por discagem do Twilio. Primeiro verifique o Voice Call:
O Google Meet usa este Plugin para entradas por discagem da Twilio. Primeiro, verifique o Voice Call:
```bash
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
```
Em seguida, verifique o transporte do Google Meet explicitamente:
Depois, verifique explicitamente o transporte do Google Meet:
```bash
openclaw googlemeet setup --transport twilio
```
Se o Voice Call estiver verde, mas o participante do Meet nunca entrar, confira o número
Se o Voice Call estiver verde, mas o participante do Meet nunca entrar, verifique o número
de discagem do Meet, o PIN e `--dtmf-sequence`. A chamada telefônica pode estar íntegra enquanto
a reunião rejeita ou ignora uma sequência DTMF incorreta.
O Google Meet passa a sequência DTMF do Meet e o texto de introdução para `voicecall.start`.
Para chamadas do Twilio, o Voice Call serve o TwiML de DTMF primeiro, redireciona de volta para o
Webhook e então abre o stream de mídia em tempo real para que a introdução salva seja gerada
depois que o participante por telefone tiver entrado na reunião.
Para chamadas da Twilio, o Voice Call serve primeiro o TwiML de DTMF, redireciona de volta para o
webhook e depois abre o stream de mídia em tempo real para que a introdução salva seja gerada
depois que o participante por telefone entrar na reunião.
Use `openclaw logs --follow` para o rastreamento da fase ao vivo. Uma entrada saudável do Twilio no Meet
Use `openclaw logs --follow` para o rastreamento da fase ao vivo. Uma entrada saudável da Twilio no Meet
registra esta ordem:
- O Google Meet delega a entrada pelo Twilio ao Voice Call.
- O Voice Call armazena o TwiML de DTMF pré-conexão.
- O TwiML inicial do Twilio é consumido e servido antes do tratamento em tempo real.
- O Voice Call serve TwiML em tempo real para a chamada do Twilio.
- O Google Meet delega a entrada da Twilio ao Voice Call.
- O Voice Call armazena o TwiML de DTMF antes da conexão.
- O TwiML inicial da Twilio é consumido e servido antes do tratamento em tempo real.
- O Voice Call serve o TwiML em tempo real para a chamada da Twilio.
- A ponte em tempo real inicia com a saudação inicial enfileirada.
`openclaw voicecall tail` ainda mostra registros de chamadas persistidos; ele é útil para
estado de chamadas e transcrições, mas nem toda transição de Webhook/tempo real aparece
estado de chamadas e transcrições, mas nem toda transição de webhook/tempo real aparece
ali.
### A chamada em tempo real não tem fala
Confirme se apenas um modo de áudio está habilitado. `realtime.enabled` e
`streaming.enabled` não podem ser ambos true.
Confirme que apenas um modo de áudio está habilitado. `realtime.enabled` e
`streaming.enabled` não podem ser ambos verdadeiros.
Para chamadas do Twilio em tempo real, verifique também:
Para chamadas Twilio em tempo real, verifique também:
- Um Plugin de provedor em tempo real está carregado e registrado.
- Um Plugin provedor em tempo real está carregado e registrado.
- `realtime.provider` não está definido ou nomeia um provedor registrado.
- A chave de API do provedor está disponível para o processo do Gateway.
- `openclaw logs --follow` mostra TwiML em tempo real servido, a ponte em tempo real
- `openclaw logs --follow` mostra o TwiML em tempo real servido, a ponte em tempo real
iniciada e a saudação inicial enfileirada.
## Relacionados

156
docs/pt-BR/providers/google.md
View File

@ -1,19 +1,19 @@
---
read_when:
- Você quer usar modelos do Google Gemini com o OpenClaw
- Você deseja usar modelos Google Gemini com o OpenClaw
- Você precisa da chave de API ou do fluxo de autenticação OAuth
summary: Configuração do Google Gemini (chave de API + OAuth, geração de imagens, compreensão de mídia, TTS, pesquisa na web)
title: Google (Gemini)
x-i18n:
generated_at: "2026-05-02T05:54:18Z"
generated_at: "2026-05-04T05:54:21Z"
model: gpt-5.5
provider: openai
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908
source_path: providers/google.md
workflow: 16
---
O Plugin Google fornece acesso a modelos Gemini por meio do Google AI Studio, além de
O Plugin do Google fornece acesso aos modelos Gemini por meio do Google AI Studio, além de
geração de imagens, compreensão de mídia (imagem/áudio/vídeo), conversão de texto em fala e pesquisa na web via
Gemini Grounding.
@ -21,7 +21,7 @@ Gemini Grounding.
- Autenticação: `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
- API: Google Gemini API
- Opção de runtime: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
reutiliza o OAuth da Gemini CLI enquanto mantém as referências de modelo canônicas como `google/*`.
reutiliza o OAuth da Gemini CLI enquanto mantém as refs de modelo canônicas como `google/*`.
## Primeiros passos
@ -29,15 +29,15 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
<Tabs>
<Tab title="Chave de API">
**Melhor para:** acesso padrão à API Gemini por meio do Google AI Studio.
**Ideal para:** acesso padrão à Gemini API por meio do Google AI Studio.
<Steps>
<Step title="Executar onboarding">
<Step title="Executar integração">
```bash
openclaw onboard --auth-choice gemini-api-key
```
Ou passe a chave diretamente:
Ou informe a chave diretamente:
```bash
openclaw onboard --non-interactive \
@ -65,13 +65,13 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
</Steps>
<Tip>
As variáveis de ambiente `GEMINI_API_KEY` e `GOOGLE_API_KEY` são aceitas. Use a que você já tiver configurada.
As variáveis de ambiente `GEMINI_API_KEY` e `GOOGLE_API_KEY` são aceitas. Use a que você já tiver configurado.
</Tip>
</Tab>
<Tab title="Gemini CLI (OAuth)">
**Melhor para:** reutilizar um login existente da Gemini CLI via OAuth PKCE em vez de uma chave de API separada.
**Ideal para:** reutilizar um login existente da Gemini CLI via PKCE OAuth em vez de uma chave de API separada.
<Warning>
O provedor `google-gemini-cli` é uma integração não oficial. Alguns usuários
@ -90,10 +90,10 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
npm install -g @google/gemini-cli
```
O OpenClaw oferece suporte a instalações via Homebrew e instalações globais via npm, incluindo
O OpenClaw oferece suporte tanto a instalações via Homebrew quanto a instalações globais via npm, incluindo
layouts comuns de Windows/npm.
</Step>
<Step title="Entrar via OAuth">
<Step title="Fazer login via OAuth">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
@ -109,7 +109,7 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
- Runtime: `google-gemini-cli`
- Alias: `gemini-cli`
O id do modelo Gemini API do Gemini 3.1 Pro é `gemini-3.1-pro-preview`. O OpenClaw aceita o `google/gemini-3.1-pro` mais curto como um alias de conveniência e o normaliza antes das chamadas ao provedor.
O ID do modelo Gemini API do Gemini 3.1 Pro é `gemini-3.1-pro-preview`. O OpenClaw aceita o `google/gemini-3.1-pro` mais curto como um alias de conveniência e o normaliza antes das chamadas ao provedor.
**Variáveis de ambiente:**
@ -119,25 +119,25 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
(Ou as variantes `GEMINI_CLI_*`.)
<Note>
Se as solicitações OAuth da Gemini CLI falharem após o login, defina `GOOGLE_CLOUD_PROJECT` ou
Se as solicitações de OAuth da Gemini CLI falharem após o login, defina `GOOGLE_CLOUD_PROJECT` ou
`GOOGLE_CLOUD_PROJECT_ID` no host do Gateway e tente novamente.
</Note>
<Note>
Se o login falhar antes do início do fluxo no navegador, verifique se o comando local `gemini`
Se o login falhar antes do início do fluxo no navegador, confirme se o comando local `gemini`
está instalado e no `PATH`.
</Note>
Referências de modelo `google-gemini-cli/*` são aliases de compatibilidade legada. Novas
configurações devem usar referências de modelo `google/*` mais o runtime `google-gemini-cli`
quando quiserem execução local pela Gemini CLI.
Refs de modelo `google-gemini-cli/*` são aliases de compatibilidade legada. Novas
configurações devem usar refs de modelo `google/*` mais o runtime `google-gemini-cli`
quando quiserem execução local da Gemini CLI.
</Tab>
</Tabs>
## Recursos
## Capacidades
| Recurso | Compatível |
| Capacidade | Compatível |
| ---------------------- | ----------------------------- |
| Conclusões de chat | Sim |
| Geração de imagens | Sim |
@ -147,15 +147,15 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
| Compreensão de imagens | Sim |
| Transcrição de áudio | Sim |
| Compreensão de vídeo | Sim |
| Pesquisa na web (Grounding) | Sim |
| Pesquisa na web (Grounding) | Sim |
| Pensamento/raciocínio | Sim (Gemini 2.5+ / Gemini 3+) |
| Modelos Gemma 4 | Sim |
## Pesquisa na web
O provedor de pesquisa na web `gemini` incluído usa o grounding do Gemini Google Search.
O provedor de pesquisa na web `gemini` incluído usa grounding da Pesquisa Google do Gemini.
Configure uma chave de pesquisa dedicada em `plugins.entries.google.config.webSearch`,
ou deixe que ele reutilize `models.providers.google.apiKey` após `GEMINI_API_KEY`:
ou permita que ele reutilize `models.providers.google.apiKey` após `GEMINI_API_KEY`:
```json5
{
@ -182,10 +182,10 @@ a pesquisa na web do Gemini reutiliza `models.providers.google.baseUrl`. Consult
[Pesquisa Gemini](/pt-BR/tools/gemini-search) para o comportamento da ferramenta específico do provedor.
<Tip>
Os modelos Gemini 3 usam `thinkingLevel` em vez de `thinkingBudget`. O OpenClaw mapeia
os controles de raciocínio de alias Gemini 3, Gemini 3.1 e `gemini-*-latest` para
`thinkingLevel`, para que execuções padrão/de baixa latência não enviem valores
`thinkingBudget` desativados.
Modelos Gemini 3 usam `thinkingLevel` em vez de `thinkingBudget`. O OpenClaw mapeia
controles de raciocínio de aliases Gemini 3, Gemini 3.1 e `gemini-*-latest` para
`thinkingLevel` para que execuções padrão/de baixa latência não enviem valores
`thinkingBudget` desabilitados.
`/think adaptive` mantém a semântica de pensamento dinâmico do Google em vez de escolher
um nível fixo do OpenClaw. Gemini 3 e Gemini 3.1 omitem um `thinkingLevel` fixo para que
@ -193,22 +193,22 @@ o Google possa escolher o nível; Gemini 2.5 envia o sentinela dinâmico do Goog
`thinkingBudget: -1`.
Modelos Gemma 4 (por exemplo, `gemma-4-26b-a4b-it`) oferecem suporte ao modo de pensamento. O OpenClaw
reescreve `thinkingBudget` para um `thinkingLevel` do Google compatível para Gemma 4.
Definir pensamento como `off` preserva o pensamento desativado em vez de mapear para
reescreve `thinkingBudget` para um `thinkingLevel` compatível do Google para Gemma 4.
Definir o pensamento como `off` preserva o pensamento desabilitado em vez de mapear para
`MINIMAL`.
</Tip>
## Geração de imagens
O provedor de geração de imagens `google` incluído usa como padrão
O provedor de geração de imagens `google` incluído usa por padrão
`google/gemini-3.1-flash-image-preview`.
- Também oferece suporte a `google/gemini-3-pro-image-preview`
- Gerar: até 4 imagens por solicitação
- Modo de edição: ativado, até 5 imagens de entrada
- Modo de edição: habilitado, até 5 imagens de entrada
- Controles de geometria: `size`, `aspectRatio` e `resolution`
Para usar o Google como provedor de imagem padrão:
Para usar o Google como provedor padrão de imagens:
```json5
{
@ -232,11 +232,11 @@ O Plugin `google` incluído também registra geração de vídeo por meio da fer
`video_generate`.
- Modelo de vídeo padrão: `google/veo-3.1-fast-generate-preview`
- Modos: fluxos de texto para vídeo, imagem para vídeo e referência de vídeo único
- Modos: texto para vídeo, imagem para vídeo e fluxos de referência de vídeo único
- Oferece suporte a `aspectRatio`, `resolution` e `audio`
- Limite de duração atual: **4 a 8 segundos**
Para usar o Google como provedor de vídeo padrão:
Para usar o Google como provedor padrão de vídeo:
```json5
{
@ -264,9 +264,9 @@ O Plugin `google` incluído também registra geração de música por meio da fe
- Controles de prompt: `lyrics` e `instrumental`
- Formato de saída: `mp3` por padrão, além de `wav` em `google/lyria-3-pro-preview`
- Entradas de referência: até 10 imagens
- Execuções respaldadas por sessão se destacam por meio do fluxo compartilhado de tarefa/status, incluindo `action: "status"`
- Execuções com respaldo de sessão se destacam por meio do fluxo compartilhado de tarefa/status, incluindo `action: "status"`
Para usar o Google como provedor de música padrão:
Para usar o Google como provedor padrão de música:
```json5
{
@ -286,13 +286,13 @@ Consulte [Geração de música](/pt-BR/tools/music-generation) para parâmetros
## Conversão de texto em fala
O provedor de fala `google` incluído usa o caminho TTS da Gemini API com
O provedor de fala `google` incluído usa o caminho de TTS da Gemini API com
`gemini-3.1-flash-tts-preview`.
- Voz padrão: `Kore`
- Autenticação: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
- Saída: WAV para anexos TTS regulares, Opus para destinos de notas de voz, PCM para Talk/telefonia
- Saída de nota de voz: o PCM do Google é empacotado como WAV e transcodificado para Opus de 48 kHz com `ffmpeg`
- Saída: WAV para anexos TTS regulares, Opus para destinos de nota de voz, PCM para Talk/telefonia
- Saída de nota de voz: o PCM do Google é encapsulado como WAV e transcodificado para Opus a 48 kHz com `ffmpeg`
Para usar o Google como provedor TTS padrão:
@ -314,12 +314,12 @@ Para usar o Google como provedor TTS padrão:
}
```
A TTS da Gemini API usa prompting em linguagem natural para controle de estilo. Defina
A TTS da Gemini API usa prompts em linguagem natural para controle de estilo. Defina
`audioProfile` para prefixar um prompt de estilo reutilizável antes do texto falado. Defina
`speakerName` quando o texto do prompt se referir a um locutor nomeado.
`speakerName` quando o texto do seu prompt se referir a uma pessoa nomeada.
A TTS da Gemini API também aceita tags de áudio expressivas entre colchetes no texto,
como `[whispers]` ou `[laughs]`. Para manter tags fora da resposta visível no chat
como `[whispers]` ou `[laughs]`. Para manter as tags fora da resposta visível do chat
enquanto as envia para TTS, coloque-as dentro de um bloco `[[tts:text]]...[[/tts:text]]`:
```text
@ -338,20 +338,22 @@ provedor. Este não é o caminho separado da Cloud Text-to-Speech API.
O Plugin `google` incluído registra um provedor de voz em tempo real respaldado pela
Gemini Live API para pontes de áudio de backend, como Voice Call e Google Meet.
| Configuração | Caminho de configuração | Padrão |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Modelo | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| Voz | `...google.voice` | `Kore` |
| Temperatura | `...google.temperature` | (não definido) |
| Sensibilidade inicial de VAD | `...google.startSensitivity` | (não definido) |
| Sensibilidade final de VAD | `...google.endSensitivity` | (não definido) |
| Duração do silêncio | `...google.silenceDurationMs` | (não definido) |
| Tratamento de atividade | `...google.activityHandling` | Padrão do Google, `start-of-activity-interrupts` |
| Cobertura de turno | `...google.turnCoverage` | Padrão do Google, `only-activity` |
| Desativar VAD automático | `...google.automaticActivityDetectionDisabled` | `false` |
| Chave de API | `...google.apiKey` | Usa como fallback `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` |
| Configuração | Caminho da configuração | Padrão |
| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Modelo | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| Voz | `...google.voice` | `Kore` |
| Temperatura | `...google.temperature` | (não definido) |
| Sensibilidade de início VAD | `...google.startSensitivity` | (não definido) |
| Sensibilidade de fim VAD | `...google.endSensitivity` | (não definido) |
| Duração do silêncio | `...google.silenceDurationMs` | (não definido) |
| Tratamento de atividade | `...google.activityHandling` | Padrão do Google, `start-of-activity-interrupts` |
| Cobertura do turno | `...google.turnCoverage` | Padrão do Google, `only-activity` |
| Desativar VAD automático | `...google.automaticActivityDetectionDisabled` | `false` |
| Retomada de sessão | `...google.sessionResumption` | `true` |
| Compressão de contexto | `...google.contextWindowCompression` | `true` |
| Chave de API | `...google.apiKey` | Usa como fallback `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` |
Exemplo de configuração em tempo real do Voice Call:
Exemplo de configuração em tempo real de Chamada de Voz:
```json5
{
@ -380,39 +382,39 @@ Exemplo de configuração em tempo real do Voice Call:
```
<Note>
A API Google Live usa áudio bidirecional e chamadas de função por um WebSocket.
O OpenClaw adapta áudio de telefonia/ponte do Meet ao fluxo da API Live PCM do Gemini e
mantém as chamadas de ferramentas no contrato de voz em tempo real compartilhado. Deixe `temperature`
não definido, a menos que você precise de alterações de amostragem; o OpenClaw omite valores não positivos
A Google Live API usa áudio bidirecional e chamadas de função por um WebSocket.
O OpenClaw adapta o áudio da ponte de telefonia/Meet ao stream PCM Live API do Gemini e
mantém as chamadas de ferramenta no contrato de voz em tempo real compartilhado. Deixe `temperature`
sem definir, a menos que você precise de alterações de amostragem; o OpenClaw omite valores não positivos
porque o Google Live pode retornar transcrições sem áudio para `temperature: 0`.
A transcrição da API Gemini é habilitada sem `languageCodes`; o SDK atual do Google
A transcrição da Gemini API é habilitada sem `languageCodes`; o SDK atual do Google
rejeita dicas de código de idioma nesse caminho de API.
</Note>
<Note>
O Talk da Control UI oferece suporte a sessões do Google Live no navegador com
tokens restritos de uso único. Provedores de voz em tempo real somente de backend também podem executar pelo transporte
genérico de relay do Gateway, que mantém as credenciais do provedor no Gateway.
O Talk da UI de controle oferece suporte a sessões do navegador do Google Live com tokens
restritos de uso único. Provedores de voz em tempo real somente de backend também podem executar pelo transporte
de relay genérico do Gateway, que mantém as credenciais do provedor no Gateway.
</Note>
Para verificação ao vivo por mantenedores, execute
Para verificação live de mantenedor, execute
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`.
A etapa do Google emite o mesmo formato de token restrito da API Live usado pelo Talk da Control
UI, abre o endpoint WebSocket do navegador, envia a carga inicial de configuração
e aguarda `setupComplete`.
A etapa do Google emite o mesmo formato de token restrito da Live API usado pelo Talk da UI de controle,
abre o endpoint WebSocket do navegador, envia a carga inicial de configuração
e aguarda por `setupComplete`.
## Configuração avançada
<AccordionGroup>
<Accordion title="Reuso direto do cache do Gemini">
Para execuções diretas da API Gemini (`api: "google-generative-ai"`), o OpenClaw
<Accordion title="Reutilização direta de cache do Gemini">
Para execuções diretas da Gemini API (`api: "google-generative-ai"`), o OpenClaw
passa um identificador `cachedContent` configurado para as solicitações do Gemini.
- Configure parâmetros por modelo ou globais com
`cachedContent` ou o legado `cached_content`
- Se ambos estiverem presentes, `cachedContent` prevalece
- Se ambos estiverem presentes, `cachedContent` vence
- Valor de exemplo: `cachedContents/prebuilt-context`
- O uso de acerto de cache do Gemini é normalizado no OpenClaw `cacheRead` a partir de
- O uso de cache-hit do Gemini é normalizado para `cacheRead` do OpenClaw a partir de
`cachedContentTokenCount` upstream
```json5
@ -439,15 +441,15 @@ e aguarda `setupComplete`.
- O texto da resposta vem do campo `response` do JSON da CLI.
- O uso usa `stats` como fallback quando a CLI deixa `usage` vazio.
- `stats.cached` é normalizado no OpenClaw `cacheRead`.
- Se `stats.input` estiver ausente, o OpenClaw deriva os tokens de entrada de
- `stats.cached` é normalizado para `cacheRead` do OpenClaw.
- Se `stats.input` estiver ausente, o OpenClaw deriva tokens de entrada de
`stats.input_tokens - stats.cached`.
</Accordion>
<Accordion title="Configuração de ambiente e daemon">
Se o Gateway for executado como daemon (launchd/systemd), verifique se `GEMINI_API_KEY`
está disponível para esse processo (por exemplo, em `~/.openclaw/.env` ou via
Se o Gateway executar como um daemon (launchd/systemd), confirme que `GEMINI_API_KEY`
esteja disponível para esse processo (por exemplo, em `~/.openclaw/.env` ou via
`env.shellEnv`).
</Accordion>
</AccordionGroup>
@ -456,9 +458,9 @@ e aguarda `setupComplete`.
<CardGroup cols={2}>
<Card title="Seleção de modelo" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, referências de modelo e comportamento de failover.
Escolha de provedores, refs de modelo e comportamento de failover.
</Card>
<Card title="Geração de imagens" href="/pt-BR/tools/image-generation" icon="image">
<Card title="Geração de imagem" href="/pt-BR/tools/image-generation" icon="image">
Parâmetros compartilhados da ferramenta de imagem e seleção de provedor.
</Card>
<Card title="Geração de vídeo" href="/pt-BR/tools/video-generation" icon="video">

163
docs/pt-BR/providers/openrouter.md
View File

@ -4,32 +4,31 @@ read_when:
- Você quer executar modelos via OpenRouter no OpenClaw
- Você quer usar o OpenRouter para geração de imagens
- Você quer usar o OpenRouter para geração de vídeo
summary: Use a API unificada do OpenRouter para acessar muitos modelos no OpenClaw
summary: Use a API unificada da OpenRouter para acessar vários modelos no OpenClaw
title: OpenRouter
x-i18n:
generated_at: "2026-05-02T21:03:20Z"
generated_at: "2026-05-04T05:54:34Z"
model: gpt-5.5
provider: openai
source_hash: e98b8b540265b6d11681390c02cb68312f33625bf223823a2dbca17e877c0422
source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
source_path: providers/openrouter.md
workflow: 16
---
OpenRouter fornece uma **API unificada** que roteia solicitações para muitos modelos por trás de um único
endpoint e chave de API. Ele é compatível com OpenAI, então a maioria dos SDKs da OpenAI funciona ao trocar a URL base.
OpenRouter fornece uma **API unificada** que roteia solicitações para muitos modelos por trás de um único endpoint e uma única chave de API. Ela é compatível com a OpenAI, então a maioria dos SDKs da OpenAI funciona ao trocar a URL base.
## Primeiros passos
<Steps>
<Step title="Obtenha sua chave de API">
<Step title="Get your API key">
Crie uma chave de API em [openrouter.ai/keys](https://openrouter.ai/keys).
</Step>
<Step title="Execute o onboarding">
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice openrouter-api-key
```
</Step>
<Step title="(Opcional) Mude para um modelo específico">
<Step title="(Optional) Switch to a specific model">
O onboarding usa `openrouter/auto` por padrão. Escolha um modelo concreto depois:
```bash
@ -52,23 +51,23 @@ endpoint e chave de API. Ele é compatível com OpenAI, então a maioria dos SDK
}
```
## Referências de modelo
## Referências de modelos
<Note>
As referências de modelo seguem o padrão `openrouter/<provider>/<model>`. Para a lista completa de
Refs de modelo seguem o padrão `openrouter/<provider>/<model>`. Para a lista completa de
provedores e modelos disponíveis, consulte [/concepts/model-providers](/pt-BR/concepts/model-providers).
</Note>
Exemplos de fallback incluídos:
| Referência de modelo | Observações |
| --------------------------------- | ------------------------------------- |
| `openrouter/auto` | Roteamento automático do OpenRouter |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 via MoonshotAI |
| Ref. do modelo | Observações |
| --------------------------------- | ---------------------------- |
| `openrouter/auto` | Roteamento automático do OpenRouter |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 via MoonshotAI |
## Geração de imagens
OpenRouter também pode fornecer suporte para a ferramenta `image_generate`. Use um modelo de imagem do OpenRouter em `agents.defaults.imageGenerationModel`:
OpenRouter também pode respaldar a ferramenta `image_generate`. Use um modelo de imagem do OpenRouter em `agents.defaults.imageGenerationModel`:
```json5
{
@ -84,11 +83,11 @@ OpenRouter também pode fornecer suporte para a ferramenta `image_generate`. Use
}
```
OpenClaw envia solicitações de imagem para a API de imagens de conclusões de chat do OpenRouter com `modalities: ["image", "text"]`. Modelos de imagem Gemini recebem dicas compatíveis de `aspectRatio` e `resolution` por meio do `image_config` do OpenRouter. Use `agents.defaults.imageGenerationModel.timeoutMs` para modelos de imagem do OpenRouter mais lentos; o parâmetro `timeoutMs` por chamada da ferramenta `image_generate` ainda prevalece.
O OpenClaw envia solicitações de imagem para a API de imagens de conclusões de chat do OpenRouter com `modalities: ["image", "text"]`. Modelos de imagem Gemini recebem dicas compatíveis de `aspectRatio` e `resolution` por meio do `image_config` do OpenRouter. Use `agents.defaults.imageGenerationModel.timeoutMs` para modelos de imagem mais lentos do OpenRouter; o parâmetro `timeoutMs` por chamada da ferramenta `image_generate` ainda tem precedência.
## Geração de vídeos
## Geração de vídeo
OpenRouter também pode fornecer suporte para a ferramenta `video_generate` por meio de sua API assíncrona `/videos`. Use um modelo de vídeo do OpenRouter em `agents.defaults.videoGenerationModel`:
OpenRouter também pode respaldar a ferramenta `video_generate` por meio de sua API assíncrona `/videos`. Use um modelo de vídeo do OpenRouter em `agents.defaults.videoGenerationModel`:
```json5
{
@ -103,20 +102,20 @@ OpenRouter também pode fornecer suporte para a ferramenta `video_generate` por
}
```
OpenClaw envia tarefas de texto para vídeo e imagem para vídeo ao OpenRouter, consulta
o `polling_url` retornado e baixa o vídeo concluído a partir dos
`unsigned_urls` do OpenRouter ou do endpoint documentado de conteúdo da tarefa.
Imagens de referência são enviadas como imagens de primeiro/último quadro por padrão; imagens
marcadas com `reference_image` são enviadas como referências de entrada do OpenRouter. O
padrão incluído `google/veo-3.1-fast` anuncia as durações de 4/6/8
segundos atualmente compatíveis, resoluções `720P`/`1080P` e proporções de aspecto
`16:9`/`9:16`. Vídeo para vídeo não é registrado para OpenRouter porque a API
upstream de geração de vídeo atualmente aceita texto e referências de imagem.
O OpenClaw envia trabalhos de texto para vídeo e imagem para vídeo ao OpenRouter, consulta
a `polling_url` retornada e baixa o vídeo concluído de
`unsigned_urls` do OpenRouter ou do endpoint documentado de conteúdo do trabalho.
Imagens de referência são enviadas como imagens do primeiro/último quadro por padrão; imagens
marcadas com `reference_image` são enviadas como referências de entrada do OpenRouter. O padrão
incluído `google/veo-3.1-fast` anuncia as durações atualmente compatíveis de 4/6/8
segundos, resoluções `720P`/`1080P` e proporções de aspecto `16:9`/`9:16`.
Vídeo para vídeo não é registrado para o OpenRouter porque a API upstream
de geração de vídeo atualmente aceita texto e referências de imagem.
## Texto para fala
OpenRouter também pode ser usado como provedor de TTS por meio de seu endpoint
`/audio/speech` compatível com OpenAI.
`/audio/speech` compatível com a OpenAI.
```json5
{
@ -141,77 +140,111 @@ Se `messages.tts.providers.openrouter.apiKey` for omitido, o TTS reutiliza
## Autenticação e cabeçalhos
OpenRouter usa internamente um token Bearer com sua chave de API.
OpenRouter usa um token Bearer com sua chave de API internamente.
Em solicitações reais ao OpenRouter (`https://openrouter.ai/api/v1`), OpenClaw também adiciona
Em solicitações reais ao OpenRouter (`https://openrouter.ai/api/v1`), o OpenClaw também adiciona
os cabeçalhos documentados de atribuição de app do OpenRouter:
| Cabeçalho | Valor |
| ------------------------- | --------------------- |
| `HTTP-Referer` | `https://openclaw.ai` |
| `X-OpenRouter-Title` | `OpenClaw` |
| `X-OpenRouter-Categories` | `cli-agent` |
| Cabeçalho | Valor |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `HTTP-Referer` | `https://openclaw.ai` |
| `X-OpenRouter-Title` | `OpenClaw` |
| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` |
<Warning>
Se você redirecionar o provedor OpenRouter para outro proxy ou URL base, OpenClaw
Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, o OpenClaw
**não** injeta esses cabeçalhos específicos do OpenRouter nem marcadores de cache da Anthropic.
</Warning>
## Configuração avançada
<AccordionGroup>
<Accordion title="Marcadores de cache da Anthropic">
Em rotas verificadas do OpenRouter, referências de modelo Anthropic mantêm os
marcadores `cache_control` específicos da Anthropic no OpenRouter que o OpenClaw usa para
melhorar a reutilização do cache de prompts em blocos de prompt de sistema/desenvolvedor.
<Accordion title="Response caching">
O cache de respostas do OpenRouter é opcional. Habilite-o por modelo do OpenRouter com
parâmetros de modelo:
```json5
{
agents: {
defaults: {
models: {
"openrouter/auto": {
params: {
responseCache: true,
responseCacheTtlSeconds: 300,
},
},
},
},
},
}
```
O OpenClaw envia `X-OpenRouter-Cache: true` e, quando configurado,
`X-OpenRouter-Cache-TTL`. `responseCacheClear: true` força uma atualização para
a solicitação atual e armazena a resposta substituta. Aliases em snake_case
(`response_cache`, `response_cache_ttl_seconds` e
`response_cache_clear`) também são aceitos.
Isso é separado do cache de prompt do provedor e dos marcadores
Anthropic `cache_control` do OpenRouter. Ele é aplicado apenas em rotas
`openrouter.ai` verificadas, não em URLs base de proxy personalizadas.
</Accordion>
<Accordion title="Preenchimento inicial de raciocínio da Anthropic">
Em rotas verificadas do OpenRouter, referências de modelo Anthropic com raciocínio ativado
removem turnos finais de preenchimento inicial do assistente antes que a solicitação chegue ao OpenRouter,
atendendo ao requisito da Anthropic de que conversas com raciocínio terminem com um turno do usuário.
<Accordion title="Anthropic cache markers">
Em rotas verificadas do OpenRouter, refs de modelo Anthropic mantêm os
marcadores Anthropic `cache_control` específicos do OpenRouter que o OpenClaw usa para
melhor reutilização do cache de prompt em blocos de prompt de sistema/desenvolvedor.
</Accordion>
<Accordion title="Injeção de pensamento / raciocínio">
Em rotas não `auto` compatíveis, OpenClaw mapeia o nível de pensamento selecionado para
<Accordion title="Anthropic reasoning prefill">
Em rotas verificadas do OpenRouter, refs de modelo Anthropic com raciocínio habilitado
removem turnos finais de preenchimento prévio do assistente antes que a solicitação chegue ao OpenRouter,
correspondendo à exigência da Anthropic de que conversas de raciocínio terminem com um
turno do usuário.
</Accordion>
<Accordion title="Thinking / reasoning injection">
Em rotas não `auto` compatíveis, o OpenClaw mapeia o nível de pensamento selecionado para
payloads de raciocínio do proxy OpenRouter. Dicas de modelo não compatíveis e
`openrouter/auto` ignoram essa injeção de raciocínio. Hunter Alpha também ignora
raciocínio via proxy para referências de modelo configuradas obsoletas porque OpenRouter poderia
retornar texto da resposta final em campos de raciocínio para essa rota desativada.
o raciocínio de proxy para refs de modelo configuradas obsoletas porque o OpenRouter poderia
retornar texto de resposta final em campos de raciocínio para essa rota descontinuada.
</Accordion>
<Accordion title="Reprodução de raciocínio do DeepSeek V4">
<Accordion title="DeepSeek V4 reasoning replay">
Em rotas verificadas do OpenRouter, `openrouter/deepseek/deepseek-v4-flash` e
`openrouter/deepseek/deepseek-v4-pro` preenchem `reasoning_content` ausente em
turnos de assistente reproduzidos para que conversas de pensamento/ferramentas mantenham o
formato de acompanhamento exigido pelo DeepSeek V4.
turnos de assistente reproduzidos para que conversas com pensamento/ferramentas mantenham o formato
de acompanhamento exigido pelo DeepSeek V4.
</Accordion>
<Accordion title="Formatação de solicitação exclusiva da OpenAI">
OpenRouter ainda passa pelo caminho compatível com OpenAI em estilo proxy, então
formatações de solicitação nativas e exclusivas da OpenAI, como `serviceTier`, `store` de Responses,
payloads compatíveis com raciocínio da OpenAI e dicas de cache de prompt não são encaminhadas.
<Accordion title="OpenAI-only request shaping">
OpenRouter ainda passa pelo caminho compatível com OpenAI no estilo proxy, então
a modelagem de solicitação nativa apenas da OpenAI, como `serviceTier`, `store` de Responses,
payloads compatíveis com raciocínio da OpenAI e dicas de cache de prompt, não é encaminhada.
</Accordion>
<Accordion title="Rotas com suporte Gemini">
Referências OpenRouter com suporte Gemini permanecem no caminho proxy-Gemini: OpenClaw mantém
a higienização de assinaturas de pensamento do Gemini ali, mas não ativa a validação de reprodução
nativa do Gemini nem reescritas de bootstrap.
<Accordion title="Gemini-backed routes">
Refs do OpenRouter respaldadas por Gemini permanecem no caminho proxy-Gemini: o OpenClaw mantém
a sanitização de assinatura de pensamento Gemini lá, mas não habilita a validação nativa de reprodução
Gemini nem reescritas de bootstrap.
</Accordion>
<Accordion title="Metadados de roteamento de provedor">
Se você passar roteamento de provedor do OpenRouter em parâmetros de modelo, OpenClaw o encaminha
<Accordion title="Provider routing metadata">
Se você passar roteamento de provedor do OpenRouter em parâmetros de modelo, o OpenClaw o encaminha
como metadados de roteamento do OpenRouter antes que os wrappers de stream compartilhados sejam executados.
</Accordion>
</AccordionGroup>
## Relacionados
## Relacionado
<CardGroup cols={2}>
<Card title="Seleção de modelos" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, referências de modelo e comportamento de failover.
<Card title="Model selection" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, refs de modelo e comportamento de failover.
</Card>
<Card title="Referência de configuração" href="/pt-BR/gateway/configuration-reference" icon="gear">
<Card title="Configuration reference" href="/pt-BR/gateway/configuration-reference" icon="gear">
Referência completa de configuração para agentes, modelos e provedores.
</Card>
</CardGroup>

116
docs/pt-BR/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Você quer defesa em profundidade contra ataques de SSRF e de religação de DNS
- Configurando um proxy de encaminhamento externo para o tráfego de tempo de execução do OpenClaw
summary: Como rotear o tráfego HTTP e WebSocket de tempo de execução do OpenClaw por meio de um proxy de filtragem gerenciado pelo operador
- Você quer defesa em profundidade contra ataques de SSRF e de revinculação de DNS
- Configuração de um proxy direto externo para o tráfego em tempo de execução do OpenClaw
summary: Como rotear o tráfego HTTP e WebSocket do runtime do OpenClaw por meio de um proxy de filtragem gerenciado pelo operador
title: Proxy de rede
x-i18n:
generated_at: "2026-05-01T05:58:58Z"
generated_at: "2026-05-04T05:55:11Z"
model: gpt-5.5
provider: openai
source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
source_path: security/network-proxy.md
workflow: 16
---
# Proxy de rede
# Proxy de Rede
O OpenClaw pode rotear tráfego HTTP e WebSocket de runtime por meio de um proxy direto gerenciado pelo operador. Essa é uma defesa opcional em profundidade para implantações que querem controle central de saída, proteção mais forte contra SSRF e melhor auditabilidade de rede.
O OpenClaw pode rotear tráfego HTTP e WebSocket em tempo de execução por meio de um proxy de encaminhamento gerenciado pelo operador. Esta é uma defesa opcional em profundidade para implantações que desejam controle central de saída, proteção SSRF mais forte e melhor auditabilidade de rede.
O OpenClaw não inclui, baixa, inicia, configura nem certifica um proxy. Você executa a tecnologia de proxy adequada ao seu ambiente, e o OpenClaw roteia clientes HTTP e WebSocket normais, locais ao processo, por meio dele.
O OpenClaw não fornece, baixa, inicia, configura nem certifica um proxy. Você executa a tecnologia de proxy adequada ao seu ambiente, e o OpenClaw roteia clientes HTTP e WebSocket locais ao processo por meio dela.
## Por que usar um proxy?
## Por Que Usar um Proxy?
Um proxy dá aos operadores um ponto único de controle de rede para tráfego HTTP e WebSocket de saída. Isso pode ser útil mesmo fora do endurecimento contra SSRF:
Um proxy dá aos operadores um ponto único de controle de rede para tráfego HTTP e WebSocket de saída. Isso pode ser útil mesmo fora do reforço contra SSRF:
- Política central: mantenha uma política de saída em vez de depender de cada ponto de chamada HTTP da aplicação para acertar as regras de rede.
- Política central: mantenha uma única política de saída em vez de depender de cada ponto de chamada HTTP da aplicação para aplicar as regras de rede corretamente.
- Verificações no momento da conexão: avalie o destino após a resolução DNS e imediatamente antes de o proxy abrir a conexão upstream.
- Defesa contra DNS rebinding: reduza a lacuna entre uma verificação DNS no nível da aplicação e a conexão de saída real.
- Defesa contra religação DNS: reduza a lacuna entre uma verificação DNS no nível da aplicação e a conexão de saída real.
- Cobertura JavaScript mais ampla: roteie clientes comuns como `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch e similares pelo mesmo caminho.
- Auditabilidade: registre destinos permitidos e negados no limite de saída.
- Controle operacional: aplique regras de destino, segmentação de rede, limites de taxa ou listas de permissão de saída sem recompilar o OpenClaw.
- Controle operacional: imponha regras de destino, segmentação de rede, limites de taxa ou listas de permissões de saída sem reconstruir o OpenClaw.
O roteamento por proxy é uma proteção no nível do processo para saída HTTP e WebSocket normal. Ele dá aos operadores um caminho fail-closed para rotear clientes HTTP JavaScript compatíveis por seu próprio proxy de filtragem, mas não é um sandbox de rede no nível do sistema operacional e não faz o OpenClaw certificar a política de destino do proxy.
O roteamento por proxy é uma proteção no nível do processo para saída HTTP e WebSocket normal. Ele dá aos operadores um caminho que falha fechado para rotear clientes HTTP JavaScript compatíveis por meio de seu próprio proxy de filtragem, mas não é uma sandbox de rede no nível do sistema operacional e não faz o OpenClaw certificar a política de destino do proxy.
## Como o OpenClaw roteia tráfego
## Como o OpenClaw Roteia Tráfego
Quando `proxy.enabled=true` e uma URL de proxy está configurada, processos de runtime protegidos como `openclaw gateway run`, `openclaw node run` e `openclaw agent --local` roteiam a saída HTTP e WebSocket normal pelo proxy configurado:
Quando `proxy.enabled=true` e uma URL de proxy está configurada, processos protegidos em tempo de execução, como `openclaw gateway run`, `openclaw node run` e `openclaw agent --local`, roteiam a saída HTTP e WebSocket normal pelo proxy configurado:
```text
OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
O contrato público é o comportamento de roteamento, não os hooks internos do Node usados para implementá-lo. Clientes WebSocket do plano de controle do OpenClaw Gateway usam um caminho direto estreito para tráfego RPC do Gateway de local loopback quando a URL do Gateway usa `localhost` ou um IP literal de loopback, como `127.0.0.1` ou `[::1]`. Esse caminho do plano de controle precisa conseguir alcançar Gateways de loopback mesmo quando o proxy do operador bloqueia destinos de loopback. Requisições HTTP e WebSocket normais de runtime ainda usam o proxy configurado.
O contrato público é o comportamento de roteamento, não os hooks internos do Node usados para implementá-lo. Os clientes WebSocket do plano de controle do OpenClaw Gateway usam um caminho direto restrito para tráfego RPC local loopback do Gateway quando a URL do Gateway usa `localhost` ou um IP literal de loopback, como `127.0.0.1` ou `[::1]`. Esse caminho do plano de controle precisa conseguir alcançar Gateways de loopback mesmo quando o proxy do operador bloqueia destinos de loopback. As solicitações HTTP e WebSocket normais em tempo de execução ainda usam o proxy configurado.
Internamente, o OpenClaw usa dois hooks de roteamento no nível do processo para este recurso:
- O roteamento do dispatcher do Undici cobre `fetch`, clientes baseados em undici e transportes que fornecem seu próprio dispatcher do undici.
- O roteamento do `global-agent` cobre chamadores do núcleo do Node `node:http` e `node:https`, incluindo muitas bibliotecas construídas sobre `http.request`, `https.request`, `http.get` e `https.get`. O modo de proxy gerenciado força esse agente global para que agentes HTTP explícitos do Node não contornem acidentalmente o proxy do operador.
- O roteamento do `global-agent` cobre chamadores do núcleo do Node `node:http` e `node:https`, incluindo muitas bibliotecas em camadas sobre `http.request`, `https.request`, `http.get` e `https.get`. O modo de proxy gerenciado força esse agente global para que agentes HTTP explícitos do Node não contornem acidentalmente o proxy do operador.
Alguns plugins possuem transportes personalizados que precisam de configuração explícita de proxy mesmo quando existe roteamento no nível do processo. Por exemplo, o transporte da Bot API do Telegram usa seu próprio dispatcher HTTP/1 do undici e, portanto, respeita o ambiente de proxy do processo mais o fallback gerenciado `OPENCLAW_PROXY_URL` nesse caminho de transporte específico do proprietário.
A própria URL do proxy precisa usar `http://`. Destinos HTTPS ainda são compatíveis por meio do proxy com `CONNECT` HTTP; isso significa apenas que o OpenClaw espera um listener de proxy direto HTTP simples, como `http://127.0.0.1:3128`.
A própria URL do proxy deve usar `http://`. Destinos HTTPS ainda são compatíveis por meio do proxy com HTTP `CONNECT`; isso significa apenas que o OpenClaw espera um listener de proxy de encaminhamento HTTP simples, como `http://127.0.0.1:3128`.
Enquanto o proxy está ativo, o OpenClaw limpa `no_proxy`, `NO_PROXY` e `GLOBAL_AGENT_NO_PROXY`. Essas listas de bypass são baseadas em destino, então deixar `localhost` ou `127.0.0.1` nelas permitiria que alvos SSRF de alto risco pulassem o proxy de filtragem.
Enquanto o proxy está ativo, o OpenClaw limpa `no_proxy`, `NO_PROXY` e `GLOBAL_AGENT_NO_PROXY`. Essas listas de desvio são baseadas em destino, portanto deixar `localhost` ou `127.0.0.1` nelas permitiria que alvos SSRF de alto risco pulassem o proxy de filtragem.
No desligamento, o OpenClaw restaura o ambiente de proxy anterior e redefine o estado de roteamento de processo em cache.
No encerramento, o OpenClaw restaura o ambiente de proxy anterior e redefine o estado de roteamento de processo em cache.
## Termos relacionados a proxy
## Termos de Proxy Relacionados
- `proxy.enabled` / `proxy.proxyUrl`: roteamento por proxy direto de saída para egresso de runtime do OpenClaw. Esta página documenta esse recurso.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso de entrada, ciente de identidade, para acesso ao Gateway. Consulte [autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
- `proxy.enabled` / `proxy.proxyUrl`: roteamento de proxy de encaminhamento de saída para o tráfego de saída em tempo de execução do OpenClaw. Esta página documenta esse recurso.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso de entrada ciente de identidade para acesso ao Gateway. Consulte [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
- `openclaw proxy`: proxy local de depuração e inspetor de captura para desenvolvimento e suporte. Consulte [openclaw proxy](/pt-BR/cli/proxy).
- Configurações de proxy específicas de canal ou provedor: substituições específicas do proprietário para um transporte específico. Prefira o proxy de rede gerenciado quando o objetivo for controle central de saída em todo o runtime.
- Configurações de proxy específicas de canal ou provedor: substituições específicas do proprietário para um transporte específico. Prefira o proxy de rede gerenciado quando o objetivo for controle central de saída em todo o tempo de execução.
## Configuração
@ -73,7 +73,7 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
Você também pode fornecer a URL pelo ambiente, mantendo `proxy.enabled=true` na configuração:
Você também pode fornecer a URL por meio do ambiente, mantendo `proxy.enabled=true` na configuração:
```bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
@ -83,7 +83,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
Se `enabled=true`, mas nenhuma URL de proxy válida estiver configurada, os comandos protegidos falham na inicialização em vez de voltar para acesso direto à rede.
Para serviços de gateway gerenciados iniciados com `openclaw gateway start`, prefira armazenar a URL na configuração:
Para serviços de Gateway gerenciados iniciados com `openclaw gateway start`, prefira armazenar a URL na configuração:
```bash
openclaw config set proxy.enabled true
@ -92,51 +92,51 @@ openclaw gateway install --force
openclaw gateway start
```
O fallback de ambiente é melhor para execuções em primeiro plano. Se você usá-lo com um serviço instalado, coloque `OPENCLAW_PROXY_URL` no ambiente durável do serviço, como `$OPENCLAW_STATE_DIR/.env` ou `~/.openclaw/.env`, depois reinstale o serviço para que launchd, systemd ou Tarefas Agendadas iniciem o gateway com esse valor.
O fallback de ambiente é melhor para execuções em primeiro plano. Se você o usar com um serviço instalado, coloque `OPENCLAW_PROXY_URL` no ambiente durável do serviço, como `$OPENCLAW_STATE_DIR/.env` ou `~/.openclaw/.env`, e então reinstale o serviço para que launchd, systemd ou Tarefas Agendadas iniciem o gateway com esse valor.
Para comandos `openclaw --container ...`, o OpenClaw encaminha `OPENCLAW_PROXY_URL` para a CLI filha direcionada ao contêiner quando ela está definida. A URL precisa ser alcançável de dentro do contêiner; `127.0.0.1` refere-se ao próprio contêiner, não ao host. O OpenClaw rejeita URLs de proxy de loopback para comandos direcionados ao contêiner, a menos que você substitua explicitamente essa verificação de segurança.
Para comandos `openclaw --container ...`, o OpenClaw encaminha `OPENCLAW_PROXY_URL` para a CLI filha destinada ao contêiner quando ele está definido. A URL precisa ser acessível de dentro do contêiner; `127.0.0.1` se refere ao próprio contêiner, não ao host. O OpenClaw rejeita URLs de proxy de loopback para comandos destinados a contêiner, a menos que você substitua explicitamente essa verificação de segurança.
## Requisitos do proxy
## Requisitos do Proxy
A política do proxy é o limite de segurança. O OpenClaw não consegue verificar se o proxy bloqueia os alvos corretos.
Configure o proxy para:
- Vincular-se apenas ao loopback ou a uma interface privada confiável.
- Vincular apenas a loopback ou a uma interface privada confiável.
- Restringir o acesso para que apenas o processo, host, contêiner ou conta de serviço do OpenClaw possa usá-lo.
- Resolver os destinos por conta própria e bloquear IPs de destino após a resolução DNS.
- Aplicar a política no momento da conexão tanto para requisições HTTP simples quanto para túneis `CONNECT` HTTPS.
- Rejeitar bypasses baseados em destino para intervalos de loopback, privados, link-local, metadados, multicast, reservados ou de documentação.
- Evitar listas de permissão de nomes de host, a menos que você confie totalmente no caminho de resolução DNS.
- Registrar destino, decisão, status e motivo sem registrar corpos de requisição, cabeçalhos de autorização, cookies ou outros segredos.
- Resolver destinos por conta própria e bloquear IPs de destino após a resolução DNS.
- Aplicar política no momento da conexão tanto para solicitações HTTP simples quanto para túneis HTTPS `CONNECT`.
- Rejeitar desvios baseados em destino para faixas de loopback, privadas, link-local, metadados, multicast, reservadas ou de documentação.
- Evitar listas de permissões de hostname, a menos que você confie totalmente no caminho de resolução DNS.
- Registrar destino, decisão, status e motivo sem registrar corpos de solicitação, cabeçalhos de autorização, cookies ou outros segredos.
- Manter a política do proxy sob controle de versão e revisar alterações como configuração sensível à segurança.
## Destinos bloqueados recomendados
## Destinos Recomendados para Bloqueio
Use esta denylist como ponto de partida para qualquer proxy direto, firewall ou política de saída.
Use esta lista de negação como ponto de partida para qualquer proxy de encaminhamento, firewall ou política de saída.
A lógica de classificação no nível da aplicação do OpenClaw fica em `src/infra/net/ssrf.ts` e `src/shared/net/ip.ts`. Os hooks de paridade relevantes são `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` e o tratamento de sentinela IPv4 embutido para NAT64, 6to4, Teredo, ISATAP e formas mapeadas em IPv4. Esses arquivos são referências úteis ao manter uma política de proxy externa, mas o OpenClaw não exporta nem aplica automaticamente essas regras no seu proxy.
A lógica de classificação no nível da aplicação do OpenClaw fica em `src/infra/net/ssrf.ts` e `src/shared/net/ip.ts`. Os hooks de paridade relevantes são `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` e o tratamento de sentinela IPv4 embutido para NAT64, 6to4, Teredo, ISATAP e formas IPv4 mapeadas. Esses arquivos são referências úteis ao manter uma política de proxy externa, mas o OpenClaw não exporta nem impõe automaticamente essas regras no seu proxy.
| Intervalo ou host | Por que bloquear |
| Faixa ou host | Por que bloquear |
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | loopback IPv4 |
| `::1/128` | loopback IPv6 |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
| `::1/128` | Loopback IPv6 |
| `0.0.0.0/8`, `::/128` | Endereços não especificados e desta rede |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Redes privadas RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Endereços link-local e caminhos comuns de metadados de nuvem |
| `169.254.169.254`, `metadata.google.internal` | Serviços de metadados de nuvem |
| `100.64.0.0/10` | Espaço de endereços compartilhado de NAT carrier-grade |
| `198.18.0.0/15`, `2001:2::/48` | Intervalos de benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Intervalos de uso especial e documentação |
| `100.64.0.0/10` | Espaço de endereço compartilhado de NAT de operadora |
| `198.18.0.0/15`, `2001:2::/48` | Faixas de benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Faixas de uso especial e documentação |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reservado |
| `fc00::/7`, `fec0::/10` | Intervalos locais/privados IPv6 |
| `100::/64`, `2001:20::/28` | Intervalos IPv6 discard e ORCHIDv2 |
| `fc00::/7`, `fec0::/10` | Faixas IPv6 locais/privadas |
| `100::/64`, `2001:20::/28` | Faixas IPv6 de descarte e ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefixos NAT64 com IPv4 embutido |
| `2002::/16`, `2001::/32` | 6to4 e Teredo com IPv4 embutido |
| `::/96`, `::ffff:0:0/96` | IPv6 compatível com IPv4 e IPv6 mapeado em IPv4 |
| `::/96`, `::ffff:0:0/96` | IPv6 compatível com IPv4 e IPv6 mapeado para IPv4 |
Se seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou intervalos reservados adicionais, adicione-os também.
Se seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou faixas reservadas adicionais, adicione-os também.
## Validação
@ -146,9 +146,9 @@ Valide o proxy a partir do mesmo host, contêiner ou conta de serviço que execu
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
Por padrão, quando nenhum destino personalizado é fornecido, o comando verifica se `https://example.com/` tem sucesso e inicia um canário temporário de loopback que o proxy não deve alcançar. A verificação negada padrão passa quando o proxy retorna uma resposta de negação não 2xx ou bloqueia o canário com uma falha de transporte; ela falha se uma resposta bem-sucedida alcançar o canário. Se nenhum proxy estiver habilitado e configurado, a validação relata um problema de configuração; use `--proxy-url` para um preflight único antes de alterar a configuração. Use `--allowed-url` e `--denied-url` para testar expectativas específicas da implantação. Destinos negados personalizados são fail-closed: qualquer resposta HTTP significa que o destino estava alcançável pelo proxy, e qualquer erro de transporte é relatado como inconclusivo porque o OpenClaw não consegue provar que o proxy bloqueou uma origem alcançável. Em falha de validação, o comando sai com código 1.
Por padrão, quando nenhum destino personalizado é fornecido, o comando verifica se `https://example.com/` tem sucesso e inicia um canário temporário de loopback que o proxy não deve alcançar. A verificação negada padrão passa quando o proxy retorna uma resposta de negação não 2xx ou bloqueia o canário com uma falha de transporte; ela falha se uma resposta bem-sucedida alcançar o canário. Se nenhum proxy estiver habilitado e configurado, a validação relata um problema de configuração; use `--proxy-url` para uma pré-verificação pontual antes de alterar a configuração. Use `--allowed-url` e `--denied-url` para testar expectativas específicas da implantação. Destinos negados personalizados falham fechados: qualquer resposta HTTP significa que o destino era alcançável por meio do proxy, e qualquer erro de transporte é relatado como inconclusivo porque o OpenClaw não consegue provar que o proxy bloqueou uma origem alcançável. Em caso de falha de validação, o comando sai com código 1.
Use `--json` para automação. A saída JSON contém o resultado geral, a fonte efetiva da configuração de proxy, quaisquer erros de configuração e cada verificação de destino. Credenciais da URL do proxy são redigidas na saída de texto e JSON:
Use `--json` para automação. A saída JSON contém o resultado geral, a origem efetiva da configuração do proxy, quaisquer erros de configuração e cada verificação de destino. Credenciais de URL de proxy são redigidas na saída de texto e JSON:
```json
{
@ -178,7 +178,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
A requisição pública deve ter êxito. As requisições de loopback e metadados devem ser bloqueadas pelo proxy. Para `openclaw proxy validate`, o canário de loopback integrado consegue distinguir uma negação do proxy de uma origem alcançável. Verificações personalizadas com `--denied-url` não têm esse canário, então trate tanto respostas HTTP quanto falhas de transporte ambíguas como falhas de validação, a menos que seu proxy exponha um sinal de negação específico da implantação que você possa verificar separadamente.
A solicitação pública deve ser bem-sucedida. As solicitações de loopback e metadados devem ser bloqueadas pelo proxy. Para `openclaw proxy validate`, o canário de loopback integrado consegue distinguir uma negação do proxy de uma origem alcançável. Verificações personalizadas de `--denied-url` não têm esse canário, portanto trate tanto respostas HTTP quanto falhas ambíguas de transporte como falhas de validação, a menos que seu proxy exponha um sinal de negação específico da implantação que você possa verificar separadamente.
Em seguida, habilite o roteamento de proxy do OpenClaw:
@ -198,9 +198,11 @@ proxy:
## Limites
- O proxy melhora a cobertura para clientes HTTP e WebSocket JavaScript locais ao processo, mas não é um sandbox de rede em nível de sistema operacional.
- Soquetes brutos `net`, `tls` e `http2`, addons nativos e processos filhos podem contornar o roteamento de proxy no nível do Node, a menos que herdem e respeitem variáveis de ambiente de proxy.
- WebUIs locais do usuário e servidores de modelo locais devem ser incluídos na lista de permissões na política de proxy do operador quando necessário; o OpenClaw não expõe um bypass geral de rede local para eles.
- O bypass de proxy do plano de controle do Gateway é intencionalmente limitado a `localhost` e URLs de IP de loopback literais. Use `ws://127.0.0.1:18789`, `ws://[::1]:18789` ou `ws://localhost:18789` para conexões diretas locais ao plano de controle do Gateway; outros nomes de host são roteados como tráfego comum baseado em nome de host.
- O proxy melhora a cobertura para clientes HTTP e WebSocket JavaScript locais ao processo, mas não é um sandbox de rede no nível do SO.
- Sockets `net`, `tls` e `http2` brutos, addons nativos e processos filho podem contornar o roteamento de proxy no nível do Node, a menos que herdem e respeitem variáveis de ambiente de proxy.
- IRC é um canal TCP/TLS bruto fora do roteamento pelo proxy de encaminhamento gerenciado pelo operador. Em implantações que exigem que toda a saída passe por esse proxy de encaminhamento, defina `channels.irc.enabled=false`, a menos que a saída direta por IRC seja explicitamente aprovada.
- O proxy local de depuração é uma ferramenta de diagnóstico, e seu encaminhamento direto upstream para solicitações de proxy e túneis CONNECT fica desabilitado por padrão enquanto o modo de proxy gerenciado está ativo; habilite o encaminhamento direto somente para diagnósticos locais aprovados.
- WebUIs locais do usuário e servidores de modelo locais devem ser incluídos na lista de permissões na política de proxy do operador quando necessário; o OpenClaw não expõe um desvio geral de rede local para eles.
- O desvio de proxy do plano de controle do Gateway é intencionalmente limitado a `localhost` e URLs de IP de loopback literais. Use `ws://127.0.0.1:18789`, `ws://[::1]:18789` ou `ws://localhost:18789` para conexões locais diretas ao plano de controle do Gateway; outros nomes de host são roteados como tráfego comum baseado em nome de host.
- O OpenClaw não inspeciona, testa nem certifica sua política de proxy.
- Trate alterações na política de proxy como mudanças operacionais sensíveis à segurança.
- Trate alterações de política de proxy como alterações operacionais sensíveis à segurança.

65
docs/pt-BR/tools/llm-task.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Você quer uma etapa de LLM somente em JSON dentro de fluxos de trabalho
- Você precisa de saída de LLM validada por schema para automação
summary: Tarefas de LLM somente em JSON para fluxos de trabalho (ferramenta opcional de Plugin)
- Você quer uma etapa de LLM somente JSON dentro de fluxos de trabalho
- Você precisa de saída de LLM validada por esquema para automação
summary: Tarefas de LLM somente em JSON para fluxos de trabalho (ferramenta de Plugin opcional)
title: Tarefa de LLM
x-i18n:
generated_at: "2026-04-24T06:17:09Z"
model: gpt-5.4
generated_at: "2026-05-04T05:55:25Z"
model: gpt-5.5
provider: openai
source_hash: 613aefd1bac5b9675821a118c11130c8bfaefb1673d0266f14ff4e91b47fed8b
source_hash: 9cdc5d4feef17fb6d6d90d819d4c92d26a4ec43e4f5364c6acbaad1934a89269
source_path: tools/llm-task.md
workflow: 15
workflow: 16
---
`llm-task` é uma **ferramenta opcional de Plugin** que executa uma tarefa de LLM somente em JSON e
retorna saída estruturada (opcionalmente validada por JSON Schema).
`llm-task` é uma **ferramenta de Plugin opcional** que executa uma tarefa de LLM somente em JSON e
retorna saída estruturada (opcionalmente validada contra JSON Schema).
Isso é ideal para mecanismos de workflow como o Lobster: você pode adicionar uma única etapa de LLM
sem escrever código personalizado do OpenClaw para cada workflow.
Isso é ideal para mecanismos de workflow como Lobster: você pode adicionar uma única etapa de LLM
sem escrever código OpenClaw personalizado para cada workflow.
## Habilitar o Plugin
## Habilite o Plugin
1. Habilite o Plugin:
@ -33,21 +33,18 @@ sem escrever código personalizado do OpenClaw para cada workflow.
}
```
2. Coloque a ferramenta na lista de permissão (ela é registrada com `optional: true`):
2. Permita a ferramenta opcional:
```json
{
"agents": {
"list": [
{
"id": "main",
"tools": { "allow": ["llm-task"] }
}
]
"tools": {
"alsoAllow": ["llm-task"]
}
}
```
Use `tools.allow` somente quando quiser o modo de lista de permissões restritiva.
## Configuração (opcional)
```json
@ -70,30 +67,30 @@ sem escrever código personalizado do OpenClaw para cada workflow.
}
```
`allowedModels` é uma lista de permissão de strings `provider/model`. Se definida, qualquer solicitação
`allowedModels` é uma lista de permissões de strings `provider/model`. Se definida, qualquer solicitação
fora da lista é rejeitada.
## Parâmetros da ferramenta
- `prompt` (string, obrigatório)
- `input` (qualquer tipo, opcional)
- `input` (qualquer, opcional)
- `schema` (objeto, JSON Schema opcional)
- `provider` (string, opcional)
- `model` (string, opcional)
- `thinking` (string, opcional)
- `authProfileId` (string, opcional)
- `temperature` (number, opcional)
- `maxTokens` (number, opcional)
- `timeoutMs` (number, opcional)
- `temperature` (número, opcional)
- `maxTokens` (número, opcional)
- `timeoutMs` (número, opcional)
`thinking` aceita os presets padrão de raciocínio do OpenClaw, como `low` ou `medium`.
`thinking` aceita as predefinições padrão de raciocínio do OpenClaw, como `low` ou `medium`.
## Saída
Retorna `details.json` contendo o JSON analisado (e valida em relação a
Retorna `details.json` contendo o JSON analisado (e valida contra
`schema` quando fornecido).
## Exemplo: etapa de workflow no Lobster
## Exemplo: etapa de workflow do Lobster
```lobster
openclaw.invoke --tool llm-task --action json --args-json '{
@ -117,14 +114,14 @@ openclaw.invoke --tool llm-task --action json --args-json '{
## Observações de segurança
- A ferramenta é **somente JSON** e instrui o modelo a retornar apenas JSON (sem
code fences, sem comentários).
- Nenhuma ferramenta é exposta ao modelo nesta execução.
- A ferramenta é **somente JSON** e instrui o modelo a gerar apenas JSON (sem
cercas de código, sem comentários).
- Nenhuma ferramenta é exposta ao modelo para esta execução.
- Trate a saída como não confiável, a menos que você valide com `schema`.
- Coloque aprovações antes de qualquer etapa com efeito colateral (send, post, exec).
- Coloque aprovações antes de qualquer etapa com efeitos colaterais (enviar, postar, executar).
## Relacionado
- [Níveis de thinking](/pt-BR/tools/thinking)
- [Níveis de raciocínio](/pt-BR/tools/thinking)
- [Subagentes](/pt-BR/tools/subagents)
- [Comandos de barra](/pt-BR/tools/slash-commands)
- [Comandos slash](/pt-BR/tools/slash-commands)

106
docs/pt-BR/tools/lobster.md
View File

@ -1,52 +1,52 @@
---
read_when:
- Você quer fluxos de trabalho determinísticos com várias etapas e aprovações explícitas
- Você quer fluxos de trabalho determinísticos de várias etapas com aprovações explícitas
- Você precisa retomar um fluxo de trabalho sem executar novamente as etapas anteriores
summary: Ambiente de execução tipado para fluxos de trabalho do OpenClaw com pontos de aprovação retomáveis.
summary: Ambiente de execução de fluxo de trabalho tipado para o OpenClaw com controles de aprovação retomáveis.
title: Lagosta
x-i18n:
generated_at: "2026-04-30T10:12:13Z"
generated_at: "2026-05-04T05:55:19Z"
model: gpt-5.5
provider: openai
source_hash: 1700bcfdbcf4558cb908935834e9059221d0d26ad78ed6f9e2158f7e0b83edbd
source_hash: 67f5145b11f2d6e07e9d78a44a389ae5f236c85ec8c287ab0f217a18b622ece0
source_path: tools/lobster.md
workflow: 16
---
Lobster é um shell de fluxo de trabalho que permite que o OpenClaw execute sequências de ferramentas de várias etapas como uma única operação determinística, com pontos de verificação de aprovação explícitos.
O Lobster é um shell de workflow que permite ao OpenClaw executar sequências de ferramentas em várias etapas como uma única operação determinística, com pontos de aprovação explícitos.
Lobster é uma camada de autoria acima do trabalho em segundo plano desconectado. Para orquestração de fluxos acima de tarefas individuais, consulte [Task Flow](/pt-BR/automation/taskflow) (`openclaw tasks flow`). Para o registro de atividades de tarefas, consulte [`openclaw tasks`](/pt-BR/automation/tasks).
O Lobster é uma camada de autoria acima do trabalho em segundo plano desacoplado. Para orquestração de fluxos acima de tarefas individuais, consulte [Task Flow](/pt-BR/automation/taskflow) (`openclaw tasks flow`). Para o registro de atividades de tarefas, consulte [`openclaw tasks`](/pt-BR/automation/tasks).
## Gancho
## Hook
Seu assistente pode criar as ferramentas que gerenciam a si mesmo. Peça um fluxo de trabalho e, 30 minutos depois, você terá uma CLI mais pipelines que rodam como uma única chamada. Lobster é a peça que faltava: pipelines determinísticos, aprovações explícitas e estado retomável.
Seu assistente pode criar as ferramentas que gerenciam a si mesmo. Peça um workflow e, 30 minutos depois, você terá uma CLI com pipelines que rodam como uma única chamada. O Lobster é a peça que faltava: pipelines determinísticos, aprovações explícitas e estado retomável.
## Por quê
Hoje, fluxos de trabalho complexos exigem muitas chamadas de ferramenta de ida e volta. Cada chamada consome tokens, e o LLM precisa orquestrar cada etapa. Lobster move essa orquestração para um runtime tipado:
Hoje, workflows complexos exigem muitas chamadas de ferramenta de ida e volta. Cada chamada custa tokens, e o LLM precisa orquestrar cada etapa. O Lobster move essa orquestração para um runtime tipado:
- **Uma chamada em vez de muitas**: o OpenClaw executa uma chamada de ferramenta Lobster e recebe um resultado estruturado.
- **Aprovações integradas**: efeitos colaterais (enviar email, postar comentário) interrompem o fluxo de trabalho até serem aprovados explicitamente.
- **Retomável**: fluxos de trabalho interrompidos retornam um token; aprove e retome sem reexecutar tudo.
- **Aprovações integradas**: efeitos colaterais (enviar email, publicar comentário) pausam o workflow até serem aprovados explicitamente.
- **Retomável**: workflows pausados retornam um token; aprove e retome sem executar tudo de novo.
## Por que uma DSL em vez de programas simples?
Lobster é intencionalmente pequeno. O objetivo não é "uma nova linguagem", mas uma especificação de pipeline previsível e amigável para IA, com aprovações de primeira classe e tokens de retomada.
O Lobster é intencionalmente pequeno. O objetivo não é "uma nova linguagem", mas uma especificação de pipeline previsível e amigável para IA, com aprovações de primeira classe e tokens de retomada.
- **Aprovar/retomar é integrado**: um programa normal pode solicitar uma ação humana, mas não consegue _pausar e retomar_ com um token durável sem que você invente esse runtime.
- **Aprovar/retomar é integrado**: um programa normal pode solicitar a intervenção de uma pessoa, mas não consegue _pausar e retomar_ com um token durável sem que você crie esse runtime por conta própria.
- **Determinismo + auditabilidade**: pipelines são dados, então são fáceis de registrar, comparar, reproduzir e revisar.
- **Superfície restrita para IA**: uma gramática pequena + encadeamento JSON reduzem caminhos de código “criativos” e tornam a validação realista.
- **Política de segurança incorporada**: timeouts, limites de saída, verificações de sandbox e listas de permissão são aplicados pelo runtime, não por cada script.
- **Superfície restrita para IA**: uma gramática pequena + passagem de JSON reduz caminhos de código “criativos” e torna a validação realista.
- **Política de segurança embutida**: timeouts, limites de saída, verificações de sandbox e listas de permissões são aplicados pelo runtime, não por cada script.
- **Ainda programável**: cada etapa pode chamar qualquer CLI ou script. Se quiser JS/TS, gere arquivos `.lobster` a partir de código.
## Como funciona
O OpenClaw executa fluxos de trabalho Lobster **in-process** usando um executor incorporado. Nenhum subprocesso de CLI externo é iniciado; o mecanismo de fluxo de trabalho executa dentro do processo do gateway e retorna um envelope JSON diretamente.
O OpenClaw executa workflows Lobster **no processo** usando um runner embutido. Nenhum subprocesso de CLI externo é iniciado; o mecanismo de workflow executa dentro do processo do gateway e retorna um envelope JSON diretamente.
Se o pipeline pausar para aprovação, a ferramenta retorna um `resumeToken` para que você possa continuar depois.
## Padrão: CLI pequena + pipes JSON + aprovações
Crie comandos pequenos que falam JSON e encadeie-os em uma única chamada Lobster. (Os nomes de comandos abaixo são exemplos — substitua pelos seus.)
Crie comandos pequenos que falem JSON e depois encadeie-os em uma única chamada Lobster. (Nomes de comandos de exemplo abaixo — substitua pelos seus.)
```bash
inbox list --json
@ -72,7 +72,7 @@ Se o pipeline solicitar aprovação, retome com o token:
}
```
A IA aciona o fluxo de trabalho; Lobster executa as etapas. Portões de aprovação mantêm os efeitos colaterais explícitos e auditáveis.
A IA aciona o workflow; o Lobster executa as etapas. Gates de aprovação mantêm efeitos colaterais explícitos e auditáveis.
Exemplo: mapear itens de entrada para chamadas de ferramenta:
@ -81,11 +81,9 @@ gog.gmail.search --query 'newer_than:1d' \
| openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
```
## Etapas LLM somente JSON (llm-task)
## Etapas LLM somente em JSON (llm-task)
Para fluxos de trabalho que precisam de uma **etapa LLM estruturada**, habilite a ferramenta Plugin opcional
`llm-task` e chame-a a partir do Lobster. Isso mantém o fluxo de trabalho
determinístico, enquanto ainda permite classificar/resumir/rascunhar com um modelo.
Para workflows que precisam de uma **etapa LLM estruturada**, habilite a ferramenta opcional de plugin `llm-task` e chame-a a partir do Lobster. Isso mantém o workflow determinístico e, ao mesmo tempo, permite classificar/resumir/rascunhar com um modelo.
Habilite a ferramenta:
@ -100,14 +98,14 @@ Habilite a ferramenta:
"list": [
{
"id": "main",
"tools": { "allow": ["llm-task"] }
"tools": { "alsoAllow": ["llm-task"] }
}
]
}
}
```
Use-a em um pipeline:
Use em um pipeline:
```lobster
openclaw.invoke --tool llm-task --action json --args-json '{
@ -128,9 +126,9 @@ openclaw.invoke --tool llm-task --action json --args-json '{
Consulte [LLM Task](/pt-BR/tools/llm-task) para detalhes e opções de configuração.
## Arquivos de fluxo de trabalho (.lobster)
## Arquivos de workflow (.lobster)
Lobster pode executar arquivos de fluxo de trabalho YAML/JSON com os campos `name`, `args`, `steps`, `env`, `condition` e `approval`. Em chamadas de ferramenta do OpenClaw, defina `pipeline` como o caminho do arquivo.
O Lobster pode executar arquivos de workflow YAML/JSON com campos `name`, `args`, `steps`, `env`, `condition` e `approval`. Em chamadas de ferramenta do OpenClaw, defina `pipeline` como o caminho do arquivo.
```yaml
name: inbox-triage
@ -156,17 +154,17 @@ steps:
Observações:
- `stdin: $step.stdout` e `stdin: $step.json` passam a saída de uma etapa anterior.
- `condition` (ou `when`) pode condicionar etapas em `$step.approved`.
- `condition` (ou `when`) pode condicionar etapas a `$step.approved`.
## Instalar Lobster
## Instalar o Lobster
Fluxos de trabalho Lobster incluídos rodam in-process; nenhum binário `lobster` separado é necessário. O executor incorporado é distribuído com o Plugin Lobster.
Workflows Lobster agrupados rodam no processo; nenhum binário `lobster` separado é necessário. O runner embutido é distribuído com o plugin Lobster.
Se precisar da CLI Lobster independente para desenvolvimento ou pipelines externos, instale-a a partir do [repositório Lobster](https://github.com/openclaw/lobster) e garanta que `lobster` esteja no `PATH`.
Se você precisar da CLI standalone do Lobster para desenvolvimento ou pipelines externos, instale-a a partir do [repositório Lobster](https://github.com/openclaw/lobster) e garanta que `lobster` esteja no `PATH`.
## Habilitar a ferramenta
Lobster é uma ferramenta Plugin **opcional** (não habilitada por padrão).
O Lobster é uma ferramenta de plugin **opcional** (não habilitada por padrão).
Recomendado (aditivo, seguro):
@ -195,10 +193,10 @@ Ou por agente:
}
```
Evite usar `tools.allow: ["lobster"]`, a menos que você pretenda executar em modo restritivo de lista de permissão.
Evite usar `tools.allow: ["lobster"]` a menos que pretenda executar em modo restritivo de lista de permissões.
<Note>
Listas de permissão são opt-in para Plugins opcionais. Se a sua lista de permissão nomear apenas ferramentas de Plugin (como `lobster`), o OpenClaw mantém as ferramentas principais habilitadas. Para restringir ferramentas principais, inclua também as ferramentas ou grupos principais que você quer na lista de permissão.
Allow lists são opcionais para plugins opcionais. `alsoAllow` habilita apenas as ferramentas dos plugins opcionais nomeados, preservando o conjunto normal de ferramentas principais. Para restringir as ferramentas principais, use `tools.allow` com as ferramentas ou grupos principais desejados.
</Note>
## Exemplo: triagem de email
@ -242,7 +240,7 @@ Retorna um envelope JSON (truncado):
}
```
Usuário aprova → retomar:
O usuário aprova → retomar:
```json
{
@ -258,7 +256,7 @@ Um fluxo de trabalho. Determinístico. Seguro.
### `run`
Execute um pipeline em modo de ferramenta.
Execute um pipeline no modo de ferramenta.
```json
{
@ -282,7 +280,7 @@ Execute um arquivo de fluxo de trabalho com argumentos:
### `resume`
Continue um fluxo de trabalho interrompido após aprovação.
Continue um fluxo de trabalho interrompido após a aprovação.
```json
{
@ -294,17 +292,17 @@ Continue um fluxo de trabalho interrompido após aprovação.
### Entradas opcionais
- `cwd`: diretório de trabalho relativo para o pipeline (deve permanecer dentro do diretório de trabalho do gateway).
- `timeoutMs`: aborta o fluxo de trabalho se ele exceder essa duração (padrão: 20000).
- `maxStdoutBytes`: aborta o fluxo de trabalho se a saída exceder esse tamanho (padrão: 512000).
- `argsJson`: string JSON passada para `lobster run --args-json` (somente arquivos de fluxo de trabalho).
- `cwd`: Diretório de trabalho relativo para o pipeline (deve permanecer dentro do diretório de trabalho do gateway).
- `timeoutMs`: Aborta o fluxo de trabalho se ele exceder essa duração (padrão: 20000).
- `maxStdoutBytes`: Aborta o fluxo de trabalho se a saída exceder esse tamanho (padrão: 512000).
- `argsJson`: String JSON passada para `lobster run --args-json` (apenas arquivos de fluxo de trabalho).
## Envelope de saída
Lobster retorna um envelope JSON com um de três status:
O Lobster retorna um envelope JSON com um de três status:
- `ok` → concluído com sucesso
- `needs_approval` → pausado; `requiresApproval.resumeToken` é necessário para retomar
- `needs_approval` → pausado; `requiresApproval.resumeToken` é obrigatório para retomar
- `cancelled` → negado ou cancelado explicitamente
A ferramenta expõe o envelope tanto em `content` (JSON formatado) quanto em `details` (objeto bruto).
@ -316,40 +314,40 @@ Se `requiresApproval` estiver presente, inspecione o prompt e decida:
- `approve: true` → retomar e continuar os efeitos colaterais
- `approve: false` → cancelar e finalizar o fluxo de trabalho
Use `approve --preview-from-stdin --limit N` para anexar uma prévia JSON a solicitações de aprovação sem cola personalizada de jq/heredoc. Tokens de retomada agora são compactos: Lobster armazena o estado de retomada do fluxo de trabalho em seu diretório de estado e devolve uma pequena chave de token.
Use `approve --preview-from-stdin --limit N` para anexar uma prévia JSON às solicitações de aprovação sem cola personalizada de jq/heredoc. Os tokens de retomada agora são compactos: o Lobster armazena o estado de retomada do fluxo de trabalho em seu diretório de estado e retorna uma pequena chave de token.
## OpenProse
OpenProse combina bem com Lobster: use `/prose` para orquestrar a preparação multiagente e depois execute um pipeline Lobster para aprovações determinísticas. Se um programa Prose precisar do Lobster, permita a ferramenta `lobster` para subagentes via `tools.subagents.tools`. Consulte [OpenProse](/pt-BR/prose).
OpenProse combina bem com Lobster: use `/prose` para orquestrar a preparação multiagente e, em seguida, execute um pipeline Lobster para aprovações determinísticas. Se um programa Prose precisar do Lobster, permita a ferramenta `lobster` para subagentes via `tools.subagents.tools`. Consulte [OpenProse](/pt-BR/prose).
## Segurança
- **Somente local in-process** — fluxos de trabalho executam dentro do processo do gateway; nenhuma chamada de rede parte do próprio Plugin.
- **Sem segredos** — Lobster não gerencia OAuth; ele chama ferramentas do OpenClaw que fazem isso.
- **Apenas local no processo** — os fluxos de trabalho são executados dentro do processo do gateway; não há chamadas de rede pelo próprio plugin.
- **Sem segredos** — o Lobster não gerencia OAuth; ele chama ferramentas do OpenClaw que fazem isso.
- **Ciente de sandbox** — desabilitado quando o contexto da ferramenta está em sandbox.
- **Endurecido** — timeouts e limites de saída são aplicados pelo executor incorporado.
- **Reforçado** — timeouts e limites de saída aplicados pelo runner embutido.
## Solução de problemas
- **`lobster timed out`** → aumente `timeoutMs` ou divida um pipeline longo.
- **`lobster output exceeded maxStdoutBytes`** → aumente `maxStdoutBytes` ou reduza o tamanho da saída.
- **`lobster returned invalid JSON`** → garanta que o pipeline rode em modo de ferramenta e imprima somente JSON.
- **`lobster failed`** → verifique os logs do gateway para detalhes do erro do executor incorporado.
- **`lobster returned invalid JSON`** → garanta que o pipeline seja executado no modo de ferramenta e imprima apenas JSON.
- **`lobster failed`** → verifique os logs do gateway para obter os detalhes do erro do runner embutido.
## Saiba mais
- [Plugins](/pt-BR/tools/plugin)
- [Autoria de ferramentas Plugin](/pt-BR/plugins/building-plugins#registering-agent-tools)
- [Criação de ferramentas de Plugin](/pt-BR/plugins/building-plugins#registering-agent-tools)
## Estudo de caso: fluxos de trabalho da comunidade
Um exemplo público: uma CLI de “segundo cérebro” + pipelines Lobster que gerenciam três cofres Markdown (pessoal, parceiro, compartilhado). A CLI emite JSON para estatísticas, listagens de caixa de entrada e varreduras de itens obsoletos; Lobster encadeia esses comandos em fluxos de trabalho como `weekly-review`, `inbox-triage`, `memory-consolidation` e `shared-task-sync`, cada um com portões de aprovação. A IA lida com julgamento (categorização) quando disponível e recorre a regras determinísticas quando não está.
Um exemplo público: uma CLI de “segundo cérebro” + pipelines Lobster que gerenciam três cofres Markdown (pessoal, parceiro, compartilhado). A CLI emite JSON para estatísticas, listagens de caixa de entrada e varreduras de itens obsoletos; o Lobster encadeia esses comandos em fluxos de trabalho como `weekly-review`, `inbox-triage`, `memory-consolidation` e `shared-task-sync`, cada um com barreiras de aprovação. A IA lida com julgamento (categorização) quando disponível e recorre a regras determinísticas quando não.
- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
- Repositório: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
## Relacionado
- [Automação e tarefas](/pt-BR/automation) — agendamento de fluxos de trabalho Lobster
- [Visão geral de automação](/pt-BR/automation) — todos os mecanismos de automação
- [Visão geral de ferramentas](/pt-BR/tools) — todas as ferramentas de agente disponíveis
- [Visão geral da automação](/pt-BR/automation) — todos os mecanismos de automação
- [Visão geral das ferramentas](/pt-BR/tools) — todas as ferramentas de agente disponíveis

269
docs/pt-BR/tools/slash-commands.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Como usar ou configurar comandos de chat
- Usando ou configurando comandos de chat
- Depuração de roteamento de comandos ou permissões
sidebarTitle: Slash commands
summary: 'Comandos de barra: texto vs. nativos, configuração e comandos compatíveis'
summary: 'Comandos de barra: texto versus nativo, configuração e comandos compatíveis'
title: Comandos de barra
x-i18n:
generated_at: "2026-05-03T21:39:17Z"
generated_at: "2026-05-04T05:55:26Z"
model: gpt-5.5
provider: openai
source_hash: 9fbdd76ccd43159cabfbc3f15f7bddd2a7ada07fcd6eea2e169d2d88df18f28c
source_hash: 49eb41674c8d0a01dbd28a2df783eb9aba3dde18d8425951a266cede825e9a84
source_path: tools/slash-commands.md
workflow: 16
---
Os comandos são tratados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **independente** que começa com `/`. O comando de chat bash exclusivo do host usa `! <cmd>` (com `/bash <cmd>` como alias).
Os comandos são gerenciados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **independente** que começa com `/`. O comando de chat bash somente do host usa `! <cmd>` (com `/bash <cmd>` como alias).
Quando uma conversa ou thread está vinculada a uma sessão ACP, o texto normal de acompanhamento é roteado para esse harness ACP. Os comandos de gerenciamento do Gateway continuam locais: `/acp ...` sempre chega ao manipulador de comandos ACP do OpenClaw, e `/status` mais `/unfocus` permanecem locais sempre que o tratamento de comandos está habilitado para a superfície.
Quando uma conversa ou thread está vinculada a uma sessão ACP, o texto normal de acompanhamento é roteado para esse harness ACP. Os comandos de gerenciamento do Gateway ainda permanecem locais: `/acp ...` sempre chega ao manipulador de comandos ACP do OpenClaw, e `/status` mais `/unfocus` permanecem locais sempre que o gerenciamento de comandos está habilitado para a superfície.
Há dois sistemas relacionados:
<AccordionGroup>
<Accordion title="Commands">
<Accordion title="Comandos">
Mensagens `/...` independentes.
</Accordion>
<Accordion title="Directives">
<Accordion title="Diretivas">
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
- As diretivas são removidas da mensagem antes que o modelo a veja.
- Em mensagens normais de chat (não apenas diretivas), elas são tratadas como "dicas embutidas" e **não** persistem as configurações da sessão.
- Em mensagens somente com diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação.
- As diretivas são aplicadas somente para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele é a única lista de permissões usada; caso contrário, a autorização vem das listas de permissões/emparelhamento do canal mais `commands.useAccessGroups`. Remetentes não autorizados veem as diretivas tratadas como texto simples.
- Em mensagens normais de chat (não apenas diretivas), elas são tratadas como "dicas inline" e **não** persistem as configurações da sessão.
- Em mensagens somente de diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação.
- As diretivas só são aplicadas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele é a única lista de permissões usada; caso contrário, a autorização vem das listas de permissões/pareamento do canal mais `commands.useAccessGroups`. Remetentes não autorizados veem as diretivas tratadas como texto simples.
</Accordion>
<Accordion title="Inline shortcuts">
Apenas remetentes na lista de permissões/autorizados: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
<Accordion title="Atalhos inline">
Apenas remetentes em lista de permissões/autorizados: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
Eles são executados imediatamente, são removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal.
@ -69,20 +69,20 @@ Há dois sistemas relacionados:
```
<ParamField path="commands.text" type="boolean" default="true">
Habilita a análise de `/...` em mensagens de chat. Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), comandos de texto ainda funcionam mesmo que você defina isso como `false`.
Habilita a análise de `/...` em mensagens de chat. Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), comandos de texto ainda funcionam mesmo se você definir isto como `false`.
</ParamField>
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
Registra comandos nativos. Automático: ativado para Discord/Telegram; desativado para Slack (até você adicionar comandos de barra); ignorado para provedores sem suporte nativo. Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para substituir por provedor (booleano ou `"auto"`). No Discord, `false` ignora o registro e a limpeza de comandos de barra durante a inicialização; comandos registrados anteriormente podem permanecer visíveis até você removê-los do app do Discord. Comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente.
Registra comandos nativos. Auto: ativado para Discord/Telegram; desativado para Slack (até você adicionar comandos de barra); ignorado para provedores sem suporte nativo. Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para sobrescrever por provedor (bool ou `"auto"`). No Discord, `false` ignora o registro de comandos de barra e a limpeza durante a inicialização; comandos registrados anteriormente podem permanecer visíveis até você removê-los do app do Discord. Comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente.
</ParamField>
No Discord, especificações de comandos nativos podem incluir `descriptionLocalizations`, que o OpenClaw publica como `description_localizations` do Discord e inclui nas comparações de reconciliação.
No Discord, as especificações de comandos nativos podem incluir `descriptionLocalizations`, que o OpenClaw publica como `description_localizations` do Discord e inclui nas comparações de reconciliação.
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
Registra comandos de **skill** nativamente quando houver suporte. Automático: ativado para Discord/Telegram; desativado para Slack (o Slack exige a criação de um comando de barra por skill). Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para substituir por provedor (booleano ou `"auto"`).
Registra comandos de **skill** nativamente quando houver suporte. Auto: ativado para Discord/Telegram; desativado para Slack (o Slack exige a criação de um comando de barra por skill). Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para sobrescrever por provedor (bool ou `"auto"`).
</ParamField>
<ParamField path="commands.bash" type="boolean" default="false">
Habilita `! <cmd>` para executar comandos de shell do host (`/bash <cmd>` é um alias; requer listas de permissões de `tools.elevated`).
Habilita `! <cmd>` para executar comandos de shell do host (`/bash <cmd>` é um alias; requer listas de permissões `tools.elevated`).
</ParamField>
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
Controla por quanto tempo o bash espera antes de alternar para o modo em segundo plano (`0` envia para segundo plano imediatamente).
Controla por quanto tempo o bash espera antes de alternar para o modo em segundo plano (`0` envia imediatamente para segundo plano).
</ParamField>
<ParamField path="commands.config" type="boolean" default="false">
Habilita `/config` (lê/grava `openclaw.json`).
@ -91,19 +91,19 @@ No Discord, especificações de comandos nativos podem incluir `descriptionLocal
Habilita `/mcp` (lê/grava a configuração MCP gerenciada pelo OpenClaw em `mcp.servers`).
</ParamField>
<ParamField path="commands.plugins" type="boolean" default="false">
Habilita `/plugins` (descoberta/status de plugins mais controles de instalação e habilitar/desabilitar).
Habilita `/plugins` (descoberta/status de Plugin mais controles de instalação e ativação/desativação).
</ParamField>
<ParamField path="commands.debug" type="boolean" default="false">
Habilita `/debug` (substituições somente em tempo de execução).
Habilita `/debug` (sobrescritas somente em runtime).
</ParamField>
<ParamField path="commands.restart" type="boolean" default="true">
Habilita `/restart` mais ações de ferramenta para reiniciar o gateway.
Habilita `/restart` mais ações de ferramenta para reiniciar o Gateway.
</ParamField>
<ParamField path="commands.ownerAllowFrom" type="string[]">
Define a lista de permissões explícita do proprietário para superfícies de comandos/ferramentas exclusivas do proprietário. Esta é a conta do operador humano que pode aprovar ações perigosas e executar comandos como `/diagnostics`, `/export-trajectory` e `/config`. Ela é separada de `commands.allowFrom` e do acesso por emparelhamento de DM.
Define a lista explícita de permissões de proprietário para superfícies de comando/ferramenta somente de proprietário. Esta é a conta do operador humano que pode aprovar ações perigosas e executar comandos como `/diagnostics`, `/export-trajectory` e `/config`. Ela é separada de `commands.allowFrom` e do acesso por pareamento de DM.
</ParamField>
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
Por canal: faz com que comandos exclusivos do proprietário exijam **identidade de proprietário** para serem executados nessa superfície. Quando `true`, o remetente deve corresponder a um candidato de proprietário resolvido (por exemplo, uma entrada em `commands.ownerAllowFrom` ou metadados de proprietário nativos do provedor) ou ter o escopo interno `operator.admin` em um canal interno de mensagens. Uma entrada curinga em `allowFrom` do canal, ou uma lista vazia/não resolvida de candidatos de proprietário, **não** é suficiente — comandos exclusivos do proprietário falham de forma fechada nesse canal. Deixe isso desativado se quiser que comandos exclusivos do proprietário sejam protegidos apenas por `ownerAllowFrom` e pelas listas de permissões padrão de comandos.
Por canal: faz com que comandos somente de proprietário exijam **identidade de proprietário** para serem executados nessa superfície. Quando `true`, o remetente deve corresponder a um candidato de proprietário resolvido (por exemplo, uma entrada em `commands.ownerAllowFrom` ou metadados de proprietário nativos do provedor) ou ter escopo interno `operator.admin` em um canal interno de mensagens. Uma entrada curinga em `allowFrom` do canal, ou uma lista vazia/não resolvida de candidatos a proprietário, **não** é suficiente — comandos somente de proprietário falham de forma fechada nesse canal. Deixe isto desativado se você quiser que comandos somente de proprietário sejam protegidos apenas por `ownerAllowFrom` e pelas listas de permissões padrão de comandos.
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
Controla como ids de proprietário aparecem no prompt do sistema.
@ -112,126 +112,125 @@ No Discord, especificações de comandos nativos podem incluir `descriptionLocal
Opcionalmente define o segredo HMAC usado quando `commands.ownerDisplay="hash"`.
</ParamField>
<ParamField path="commands.allowFrom" type="object">
Lista de permissões por provedor para autorização de comandos. Quando configurada, é a única fonte de autorização para comandos e diretivas (listas de permissões/emparelhamento do canal e `commands.useAccessGroups` são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor o substituem.
Lista de permissões por provedor para autorização de comandos. Quando configurada, ela é a única fonte de autorização para comandos e diretivas (listas de permissões/pareamento de canal e `commands.useAccessGroups` são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor o sobrescrevem.
</ParamField>
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
Impõe listas de permissões/políticas para comandos quando `commands.allowFrom` não está definido.
Aplica listas de permissões/políticas para comandos quando `commands.allowFrom` não está definido.
</ParamField>
## Lista de comandos
Fonte da verdade atual:
- comandos integrados do núcleo vêm de `src/auto-reply/commands-registry.shared.ts`
- comandos gerados de dock vêm de `src/auto-reply/commands-registry.data.ts`
- comandos de plugins vêm de chamadas `registerCommand()` de plugins
- a disponibilidade real no seu gateway ainda depende de flags de configuração, superfície do canal e plugins instalados/habilitados
- comandos integrados principais vêm de `src/auto-reply/commands-registry.shared.ts`
- comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts`
- comandos de Plugin vêm de chamadas `registerCommand()` de Plugin
- a disponibilidade real no seu gateway ainda depende de flags de configuração, superfície de canal e Plugins instalados/habilitados
### Comandos integrados do núcleo
### Comandos integrados principais
<AccordionGroup>
<Accordion title="Sessions and runs">
<Accordion title="Sessões e execuções">
- `/new [model]` inicia uma nova sessão; `/reset` é o alias de redefinição.
- A Control UI intercepta `/new` digitado para criar e alternar para uma nova sessão de painel; `/reset` digitado ainda executa a redefinição no local do Gateway.
- `/reset soft [message]` mantém a transcrição atual, descarta ids de sessão reutilizados do backend da CLI e executa novamente o carregamento de inicialização/prompt do sistema no local.
- A Control UI intercepta `/new` digitado para criar e alternar para uma nova sessão de dashboard; `/reset` digitado ainda executa a redefinição in-place do Gateway.
- `/reset soft [message]` mantém a transcrição atual, descarta ids de sessão reutilizados do backend CLI e executa novamente o carregamento de inicialização/prompt do sistema in-place.
- `/compact [instructions]` compacta o contexto da sessão. Consulte [Compaction](/pt-BR/concepts/compaction).
- `/stop` aborta a execução atual.
- `/session idle <duration|off>` e `/session max-age <duration|off>` gerenciam a expiração do vínculo de thread.
- `/session idle <duration|off>` e `/session max-age <duration|off>` gerenciam a expiração de vínculo de thread.
- `/export-session [path]` exporta a sessão atual para HTML. Alias: `/export`.
- `/export-trajectory [path]` solicita aprovação de execução e então exporta um [pacote de trajetória](/pt-BR/tools/trajectory) JSONL para a sessão atual. Use quando precisar da linha do tempo de prompt, ferramenta e transcrição de uma sessão do OpenClaw. Em chats em grupo, o prompt de aprovação e o resultado da exportação vão para o proprietário em privado. Alias: `/trajectory`.
- `/export-trajectory [path]` solicita aprovação de exec e depois exporta um [pacote de trajetória](/pt-BR/tools/trajectory) JSONL para a sessão atual. Use quando precisar da linha do tempo de prompt, ferramenta e transcrição para uma sessão do OpenClaw. Em chats de grupo, o prompt de aprovação e o resultado da exportação vão para o proprietário em privado. Alias: `/trajectory`.
</Accordion>
<Accordion title="Model and run controls">
- `/think <level>` define o nível de raciocínio. As opções vêm do perfil de provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou o binário `on` somente onde houver suporte. Aliases: `/thinking`, `/t`.
<Accordion title="Controles de modelo e execução">
- `/think <level>` define o nível de pensamento. As opções vêm do perfil de provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou binário `on` apenas onde houver suporte. Aliases: `/thinking`, `/t`.
- `/verbose on|off|full` alterna a saída detalhada. Alias: `/v`.
- `/trace on|off` alterna a saída de rastreamento de plugins para a sessão atual.
- `/trace on|off` alterna a saída de trace de Plugin para a sessão atual.
- `/fast [status|on|off]` mostra ou define o modo rápido.
- `/reasoning [on|off|stream]` alterna a visibilidade do raciocínio. Alias: `/reason`.
- `/elevated [on|off|ask|full]` alterna o modo elevado. Alias: `/elev`.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra ou define os padrões de execução.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra ou define os padrões de exec.
- `/model [name|#|status]` mostra ou define o modelo.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lista provedores configurados/disponíveis por autenticação ou modelos de um provedor; adicione `all` para navegar pelo catálogo completo desse provedor.
- `/queue <mode>` gerencia o comportamento da fila (`steer`, `queue` legado, `followup`, `collect`, `steer-backlog`, `interrupt`) mais opções como `debounce:0.5s cap:25 drop:summarize`; `/queue default` ou `/queue reset` limpa a substituição da sessão. Consulte [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering).
- `/queue <mode>` gerencia o comportamento da fila (`steer`, `queue` legado, `followup`, `collect`, `steer-backlog`, `interrupt`) mais opções como `debounce:0.5s cap:25 drop:summarize`; `/queue default` ou `/queue reset` limpa a sobrescrita da sessão. Consulte [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering).
- `/steer <message>` injeta orientação na execução ativa para a sessão atual, independentemente do modo `/queue`. Ele não inicia uma nova execução quando a sessão está ociosa. Alias: `/tell`. Consulte [Steer](/pt-BR/tools/steer).
</Accordion>
<Accordion title="Discovery and status">
<Accordion title="Descoberta e status">
- `/help` mostra o resumo curto de ajuda.
- `/commands` mostra o catálogo de comandos gerado.
- `/tools [compact|verbose]` mostra o que o agente atual pode usar agora.
- `/status` mostra o status de execução/tempo de execução, incluindo rótulos `Execution`/`Runtime` e uso/cota do provedor quando disponível.
- `/diagnostics [note]` é o fluxo de relatório de suporte exclusivo do proprietário para bugs do Gateway e execuções do harness Codex. Ele solicita aprovação explícita de execução todas as vezes antes de executar `openclaw gateway diagnostics export --json`; não aprove diagnósticos com uma regra de permitir tudo. Após a aprovação, envia um relatório colável com o caminho do pacote local, resumo do manifesto, notas de privacidade e ids de sessão relevantes. Em chats em grupo, o prompt de aprovação e o relatório vão para o proprietário em privado. Quando a sessão ativa usa o harness OpenAI Codex, a mesma aprovação também envia feedback relevante do Codex para servidores da OpenAI, e a resposta concluída lista os ids de sessão do OpenClaw, ids de thread do Codex e comandos `codex resume <thread-id>`. Consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics).
- `/crestodian <request>` executa o auxiliar de configuração e reparo do Crestodian a partir de uma DM do proprietário.
- `/tasks` lista tarefas em segundo plano ativas/recentes da sessão atual.
- `/status` mostra o status de execução/runtime, incluindo rótulos `Execution`/`Runtime` e uso/cota de provedor quando disponível.
- `/diagnostics [note]` é o fluxo de relatório de suporte somente de proprietário para bugs do Gateway e execuções do harness Codex. Ele solicita aprovação explícita de exec todas as vezes antes de executar `openclaw gateway diagnostics export --json`; não aprove diagnósticos com uma regra allow-all. Após a aprovação, ele envia um relatório colável com o caminho do pacote local, resumo do manifesto, notas de privacidade e ids de sessão relevantes. Em chats de grupo, o prompt de aprovação e o relatório vão para o proprietário em privado. Quando a sessão ativa usa o harness OpenAI Codex, a mesma aprovação também envia feedback relevante do Codex para servidores da OpenAI e a resposta concluída lista os ids de sessão do OpenClaw, ids de thread do Codex e comandos `codex resume <thread-id>`. Consulte [Exportação de Diagnósticos](/pt-BR/gateway/diagnostics).
- `/crestodian <request>` executa o auxiliar de configuração e reparo Crestodian a partir de uma DM do proprietário.
- `/tasks` lista tarefas em segundo plano ativas/recentes para a sessão atual.
- `/context [list|detail|json]` explica como o contexto é montado.
- `/whoami` mostra seu id de remetente. Alias: `/id`.
- `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo de custo local.
- `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo local de custos.
</Accordion>
<Accordion title="Skills, allowlists, approvals">
<Accordion title="Skills, listas de permissões, aprovações">
- `/skill <name> [input]` executa uma skill pelo nome.
- `/allowlist [list|add|remove] ...` gerencia entradas da lista de permissões. Somente texto.
- `/approve <id> <decision>` resolve prompts de aprovação de execução.
- `/approve <id> <decision>` resolve prompts de aprovação de exec.
- `/btw <question>` faz uma pergunta paralela sem alterar o contexto futuro da sessão. Alias: `/side`. Consulte [BTW](/pt-BR/tools/btw).
</Accordion>
<Accordion title="Subagentes e ACP">
- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes da sessão atual.
- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes para a sessão atual.
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gerencia sessões ACP e opções de runtime.
- `/focus <target>` vincula a thread atual do Discord ou o tópico/conversa do Telegram a um destino de sessão.
- `/unfocus` remove o vínculo atual.
- `/agents` lista agentes vinculados à thread para a sessão atual.
- `/kill <id|#|all>` aborta um ou todos os subagentes em execução.
- `/steer <id|#> <message>` envia direcionamento para um subagente em execução. Alias: `/tell`.
- `/subagents steer <id|#> <message>` envia orientação para um subagente em execução. Consulte [Orientar](/pt-BR/tools/steer).
</Accordion>
<Accordion title="Gravações somente pelo proprietário e administração">
- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente proprietário. Requer `commands.config: true`.
- `/mcp show|get|set|unset` lê ou grava a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente proprietário. Requer `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado de plugins. `/plugin` é um alias. Somente proprietário para gravações. Requer `commands.plugins: true`.
- `/debug show|set|unset|reset` gerencia substituições de configuração apenas de runtime. Somente proprietário. Requer `commands.debug: true`.
<Accordion title="Gravações somente pelo owner e administração">
- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente pelo owner. Requer `commands.config: true`.
- `/mcp show|get|set|unset` lê ou grava a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente pelo owner. Requer `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado de plugins. `/plugin` é um alias. Somente pelo owner para gravações. Requer `commands.plugins: true`.
- `/debug show|set|unset|reset` gerencia substituições de configuração somente de runtime. Somente pelo owner. Requer `commands.debug: true`.
- `/restart` reinicia o OpenClaw quando habilitado. Padrão: habilitado; defina `commands.restart: false` para desabilitar.
- `/send on|off|inherit` define a política de envio. Somente proprietário.
- `/send on|off|inherit` define a política de envio. Somente pelo owner.
</Accordion>
<Accordion title="Voz, TTS, controle de canal">
<Accordion title="Voz, TTS e controle de canal">
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` controla TTS. Consulte [TTS](/pt-BR/tools/tts).
- `/activation mention|always` define o modo de ativação em grupo.
- `/bash <command>` executa um comando de shell no host. Somente texto. Alias: `! <command>`. Requer `commands.bash: true` mais listas de permissão de `tools.elevated`.
- `!poll [sessionId]` verifica uma tarefa bash em segundo plano.
- `!stop [sessionId]` interrompe uma tarefa bash em segundo plano.
- `/bash <command>` executa um comando shell no host. Somente texto. Alias: `! <command>`. Requer `commands.bash: true` mais allowlists de `tools.elevated`.
- `!poll [sessionId]` verifica um job bash em segundo plano.
- `!stop [sessionId]` interrompe um job bash em segundo plano.
</Accordion>
</AccordionGroup>
### Comandos de dock gerados
### Comandos dock gerados
Comandos de dock alternam a rota de resposta da sessão atual para outro canal
vinculado. Consulte [Ancoragem de canais](/pt-BR/concepts/channel-docking) para configuração,
exemplos e solução de problemas.
Comandos dock alternam a rota de resposta da sessão atual para outro canal vinculado. Consulte [Ancoragem de canal](/pt-BR/concepts/channel-docking) para configuração, exemplos e solução de problemas.
Comandos de dock são gerados a partir de plugins de canal com suporte a comandos nativos. Conjunto integrado atual:
Comandos dock são gerados a partir de plugins de canal com suporte a comandos nativos. Conjunto integrado atual:
- `/dock-discord` (alias: `/dock_discord`)
- `/dock-mattermost` (alias: `/dock_mattermost`)
- `/dock-slack` (alias: `/dock_slack`)
- `/dock-telegram` (alias: `/dock_telegram`)
Use comandos de dock em um chat direto para alternar a rota de resposta da sessão atual para outro canal vinculado. O agente mantém o mesmo contexto de sessão, mas as respostas futuras dessa sessão são entregues ao par de canal selecionado.
Use comandos dock em um chat direto para alternar a rota de resposta da sessão atual para outro canal vinculado. O agente mantém o mesmo contexto de sessão, mas respostas futuras dessa sessão são entregues ao par de canal selecionado.
Comandos de dock exigem `session.identityLinks`. O remetente de origem e o par de destino devem estar no mesmo grupo de identidade, por exemplo `["telegram:123", "discord:456"]`. Se um usuário do Telegram com id `123` enviar `/dock_discord`, o OpenClaw armazena `lastChannel: "discord"` e `lastTo: "456"` na sessão ativa. Se o remetente não estiver vinculado a um par do Discord, o comando responde com uma dica de configuração em vez de cair no chat normal.
Comandos dock exigem `session.identityLinks`. O remetente de origem e o par de destino devem estar no mesmo grupo de identidade, por exemplo `["telegram:123", "discord:456"]`. Se um usuário do Telegram com id `123` enviar `/dock_discord`, o OpenClaw armazena `lastChannel: "discord"` e `lastTo: "456"` na sessão ativa. Se o remetente não estiver vinculado a um par do Discord, o comando responde com uma dica de configuração em vez de cair no chat normal.
A ancoragem altera apenas a rota da sessão ativa. Ela não cria contas de canal, concede acesso, contorna listas de permissão de canal nem move o histórico da transcrição para outra sessão. Use `/dock-telegram`, `/dock-slack`, `/dock-mattermost` ou outro comando de dock gerado para alternar a rota novamente.
A ancoragem altera apenas a rota da sessão ativa. Ela não cria contas de canal, concede acesso, contorna allowlists de canal nem move o histórico de transcrição para outra sessão. Use `/dock-telegram`, `/dock-slack`, `/dock-mattermost` ou outro comando dock gerado para alternar a rota novamente.
### Comandos de plugin integrados
### Comandos de plugins integrados
Plugins integrados podem adicionar mais comandos de barra. Comandos integrados atuais neste repositório:
Plugins integrados podem adicionar mais comandos de barra. Comandos integrados atuais neste repo:
- `/dreaming [on|off|status|help]` alterna o dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de pareamento/configuração de dispositivos. Consulte [Pareamento](/pt-BR/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporariamente comandos de nó de telefone de alto risco.
- `/voice status|list [limit]|set <voiceId|name>` gerencia a configuração de voz Talk. No Discord, o nome do comando nativo é `/talkvoice`.
- `/card ...` envia presets de cartões ricos do LINE. Consulte [LINE](/pt-BR/channels/line).
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspeciona e controla o harness de servidor de app Codex integrado. Consulte [Harness Codex](/pt-BR/plugins/codex-harness).
- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de pareamento/configuração de dispositivo. Consulte [Pareamento](/pt-BR/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporariamente comandos de node de telefone de alto risco.
- `/voice status|list [limit]|set <voiceId|name>` gerencia a configuração de voz do Talk. No Discord, o nome do comando nativo é `/talkvoice`.
- `/card ...` envia predefinições de rich card do LINE. Consulte [LINE](/pt-BR/channels/line).
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspeciona e controla o harness app-server integrado do Codex. Consulte [Harness do Codex](/pt-BR/plugins/codex-harness).
- Comandos somente do QQBot:
- `/bot-ping`
- `/bot-version`
@ -239,67 +238,67 @@ Plugins integrados podem adicionar mais comandos de barra. Comandos integrados a
- `/bot-upgrade`
- `/bot-logs`
### Comandos dinâmicos de Skills
### Comandos de skill dinâmicos
Skills invocáveis pelo usuário também são expostas como comandos de barra:
- `/skill <name> [input]` sempre funciona como o ponto de entrada genérico.
- Skills também podem aparecer como comandos diretos como `/prose` quando a skill/plugin os registra.
- o registro de comandos nativos de skill é controlado por `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
- especificações de comando podem fornecer `descriptionLocalizations` para superfícies nativas que oferecem suporte a descrições localizadas, incluindo Discord.
- skills também podem aparecer como comandos diretos, como `/prose`, quando a skill/plugin os registra.
- o registro nativo de comandos de skill é controlado por `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
- especificações de comando podem fornecer `descriptionLocalizations` para superfícies nativas que aceitam descrições localizadas, incluindo Discord.
<AccordionGroup>
<Accordion title="Observações sobre argumentos e parser">
<Accordion title="Notas de argumentos e parser">
- Comandos aceitam um `:` opcional entre o comando e os argumentos (por exemplo, `/think: high`, `/send: on`, `/help:`).
- `/new <model>` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência aproximada); se não houver correspondência, o texto é tratado como o corpo da mensagem.
- Para a análise completa de uso por provedor, use `openclaw status --usage`.
- `/new <model>` aceita um alias de modelo, `provider/model` ou um nome de provider (correspondência aproximada); se não houver correspondência, o texto será tratado como o corpo da mensagem.
- Para uma análise completa de uso por provider, use `openclaw status --usage`.
- `/allowlist add|remove` exige `commands.config=true` e respeita `configWrites` do canal.
- Em canais com várias contas, `/allowlist --account <id>` direcionado à configuração e `/config set channels.<provider>.accounts.<id>...` também respeitam o `configWrites` da conta de destino.
- `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo de custo local a partir dos logs de sessão do OpenClaw.
- `/restart` é habilitado por padrão; defina `commands.restart: false` para desabilitar.
- `/plugins install <spec>` aceita as mesmas especificações de plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm, `git:<repo>` ou `clawhub:<pkg>`, depois solicita uma reinicialização do Gateway porque os módulos de origem do plugin mudaram.
- `/plugins enable|disable` atualiza a configuração de plugin e aciona o recarregamento de plugins do Gateway para novos turnos do agente.
- `/restart` é habilitado por padrão; defina `commands.restart: false` para desabilitá-lo.
- `/plugins install <spec>` aceita as mesmas especificações de plugin que `openclaw plugins install`: caminho local/archive, pacote npm, `git:<repo>` ou `clawhub:<pkg>`, depois solicita uma reinicialização do Gateway porque os módulos de origem do plugin mudaram.
- `/plugins enable|disable` atualiza a configuração de plugin e aciona o recarregamento de plugin do Gateway para novas interações de agente.
</Accordion>
<Accordion title="Comportamento específico de canal">
- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (não disponível como texto). `join` exige um servidor e um canal de voz/palco selecionado. Requer `channels.discord.voice` e comandos nativos.
- Comandos de vínculo de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que vínculos efetivos de thread estejam habilitados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`).
- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (não disponível como texto). `join` exige uma guilda e um canal de voz/palco selecionado. Requer `channels.discord.voice` e comandos nativos.
- Comandos de vinculação de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que vínculos efetivos de thread estejam habilitados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`).
- Referência de comandos ACP e comportamento de runtime: [Agentes ACP](/pt-BR/tools/acp-agents).
</Accordion>
<Accordion title="Segurança de verbose / trace / fast / reasoning">
- `/verbose` é destinado a depuração e visibilidade extra; mantenha-o **desativado** no uso normal.
- `/trace` é mais restrito que `/verbose`: ele revela apenas linhas de trace/debug pertencentes ao plugin e mantém desativado o ruído verbose normal de ferramentas.
- `/fast on|off` persiste uma substituição de sessão. Use a opção `inherit` da UI Sessions para limpá-la e voltar aos padrões de configuração.
- `/fast` é específico do provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints Responses nativos, enquanto solicitações públicas diretas da Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic).
- Resumos de falhas de ferramentas ainda são exibidos quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`.
- `/reasoning`, `/verbose` e `/trace` são arriscados em configurações de grupo: eles podem revelar raciocínio interno, saída de ferramenta ou diagnósticos de plugin que você não pretendia expor. Prefira deixá-los desativados, especialmente em chats em grupo.
- `/verbose` é destinado a depuração e visibilidade extra; mantenha **desligado** no uso normal.
- `/trace` é mais restrito que `/verbose`: revela apenas linhas de trace/debug pertencentes a plugins e mantém desligado o ruído verbose normal de ferramentas.
- `/fast on|off` persiste uma substituição de sessão. Use a opção `inherit` da UI de Sessões para limpá-la e voltar aos padrões de configuração.
- `/fast` é específico do provider: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos de Responses, enquanto solicitações públicas diretas à Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic).
- Resumos de falhas de ferramenta ainda são exibidos quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`.
- `/reasoning`, `/verbose` e `/trace` são arriscados em configurações de grupo: podem revelar raciocínio interno, saída de ferramentas ou diagnósticos de plugin que você não pretendia expor. Prefira mantê-los desligados, especialmente em chats em grupo.
</Accordion>
<Accordion title="Troca de modelo">
- `/model` persiste o novo modelo da sessão imediatamente.
- Se o agente estiver ocioso, a próxima execução o usa imediatamente.
- Se uma execução já estiver ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia no novo modelo em um ponto limpo de nova tentativa.
- Se atividade de ferramenta ou saída de resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou o próximo turno do usuário.
- Na TUI local, `/crestodian [request]` retorna da TUI normal do agente para Crestodian. Isso é separado do modo de resgate de canal de mensagem e não concede autoridade remota de configuração.
- Se a atividade de ferramenta ou a saída de resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou até o próximo turno do usuário.
- Na TUI local, `/crestodian [request]` retorna da TUI normal do agente para o Crestodian. Isso é separado do modo de resgate de canal de mensagens e não concede autoridade remota de configuração.
</Accordion>
<Accordion title="Caminho rápido e atalhos inline">
- **Caminho rápido:** mensagens somente com comando de remetentes na lista de permissão são tratadas imediatamente (contornam fila + modelo).
- **Controle de menção em grupo:** mensagens somente com comando de remetentes na lista de permissão contornam requisitos de menção.
- **Atalhos inline (somente remetentes na lista de permissão):** certos comandos também funcionam quando incorporados em uma mensagem normal e são removidos antes que o modelo veja o texto restante.
- **Caminho rápido:** mensagens somente de comando de remetentes na allowlist são tratadas imediatamente (contornam fila + modelo).
- **Gate por menção em grupo:** mensagens somente de comando de remetentes na allowlist contornam requisitos de menção.
- **Atalhos inline (somente remetentes na allowlist):** certos comandos também funcionam quando incorporados em uma mensagem normal e são removidos antes que o modelo veja o texto restante.
- Exemplo: `hey /status` aciona uma resposta de status, e o texto restante continua pelo fluxo normal.
- Atualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
- Mensagens somente com comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples.
- Mensagens somente de comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples.
</Accordion>
<Accordion title="Comandos de Skills e argumentos nativos">
- **Comandos de Skills:** Skills `user-invocable` são expostas como comandos de barra. Nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`).
- `/skill <name> [input]` executa uma skill pelo nome (útil quando limites de comandos nativos impedem comandos por skill).
<Accordion title="Comandos de skill e argumentos nativos">
- **Comandos de skill:** skills `user-invocable` são expostas como comandos de barra. Nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`).
- `/skill <name> [input]` executa uma skill pelo nome (útil quando limites de comando nativo impedem comandos por skill).
- Por padrão, comandos de skill são encaminhados ao modelo como uma solicitação normal.
- Skills podem declarar opcionalmente `command-dispatch: tool` para rotear o comando diretamente para uma ferramenta (determinístico, sem modelo).
- Exemplo: `/prose` (plugin OpenProse) — consulte [OpenProse](/pt-BR/prose).
- **Argumentos de comandos nativos:** Discord usa autocomplete para opções dinâmicas (e menus de botões quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botões quando um comando oferece suporte a escolhas e você omite o argumento. Escolhas dinâmicas são resolvidas em relação ao modelo da sessão de destino, então opções específicas do modelo, como níveis de `/think`, seguem a substituição de `/model` dessa sessão.
- **Argumentos de comando nativo:** Discord usa autocomplete para opções dinâmicas (e menus de botão quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botão quando um comando aceita escolhas e você omite o argumento. Escolhas dinâmicas são resolvidas em relação ao modelo da sessão de destino, então opções específicas de modelo, como níveis de `/think`, seguem a substituição de `/model` dessa sessão.
</Accordion>
</AccordionGroup>
@ -310,17 +309,17 @@ Skills invocáveis pelo usuário também são expostas como comandos de barra:
- O `/tools` padrão é compacto e otimizado para leitura rápida.
- `/tools verbose` adiciona descrições curtas.
- Superfícies de comandos nativos que oferecem suporte a argumentos expõem a mesma alternância de modo como `compact|verbose`.
- Os resultados têm escopo de sessão, então mudar agente, canal, thread, autorização do remetente ou modelo pode alterar a saída.
- `/tools` inclui ferramentas que são realmente acessíveis em runtime, incluindo ferramentas principais, ferramentas de plugins conectados e ferramentas pertencentes ao canal.
- Superfícies de comando nativo que aceitam argumentos expõem o mesmo seletor de modo que `compact|verbose`.
- Os resultados têm escopo de sessão, portanto alterar agente, canal, thread, autorização do remetente ou modelo pode alterar a saída.
- `/tools` inclui ferramentas realmente acessíveis em runtime, incluindo ferramentas core, ferramentas de plugins conectados e ferramentas pertencentes ao canal.
Para edição de perfis e substituições, use o painel Tools da Control UI ou superfícies de configuração/catálogo em vez de tratar `/tools` como um catálogo estático.
Para edição de perfil e substituições, use o painel Tools da Control UI ou superfícies de configuração/catálogo em vez de tratar `/tools` como um catálogo estático.
## Superfícies de uso (o que aparece onde)
- **Uso/cota do provedor** (exemplo: "Claude 80% restante") aparece em `/status` para o provedor de modelo atual quando o rastreamento de uso está ativado. O OpenClaw normaliza as janelas do provedor para `% restante`; para MiniMax, campos percentuais apenas de restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano marcado com o modelo.
- **Linhas de token/cache** em `/status` podem recorrer à entrada de uso mais recente da transcrição quando o snapshot da sessão ativa é escasso. Valores ativos não zero existentes ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado a prompt quando os totais armazenados estiverem ausentes ou forem menores.
- **Execução vs runtime:** `/status` relata `Execution` para o caminho efetivo do sandbox e `Runtime` para quem está realmente executando a sessão: `OpenClaw Pi Default`, `OpenAI Codex`, um backend CLI ou um backend ACP.
- **Uso/cota do provedor** (exemplo: "Claude 80% restante") aparece em `/status` para o provedor de modelo atual quando o rastreamento de uso está habilitado. OpenClaw normaliza as janelas do provedor para `% restante`; para MiniMax, campos percentuais somente de restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano marcado com o modelo.
- **Linhas de tokens/cache** em `/status` podem recorrer à entrada de uso mais recente da transcrição quando o instantâneo da sessão ao vivo está esparso. Valores ao vivo existentes e diferentes de zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado a prompt quando os totais armazenados estão ausentes ou menores.
- **Execução vs runtime:** `/status` relata `Execution` para o caminho efetivo do sandbox e `Runtime` para quem está realmente executando a sessão: `OpenClaw Pi Default`, `OpenAI Codex`, um backend de CLI ou um backend de ACP.
- **Tokens/custo por resposta** é controlado por `/usage off|tokens|full` (anexado às respostas normais).
- `/model status` trata de **modelos/autenticação/endpoints**, não de uso.
@ -342,13 +341,13 @@ Exemplos:
Observações:
- `/model` e `/model list` mostram um seletor compacto e numerado (família do modelo + provedores disponíveis).
- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo, além de uma etapa Submit.
- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo, além de uma etapa de envio.
- `/model <#>` seleciona a partir desse seletor (e prefere o provedor atual quando possível).
- `/model status` mostra a visualização detalhada, incluindo endpoint do provedor configurado (`baseUrl`) e modo de API (`api`) quando disponíveis.
- `/model status` mostra a visualização detalhada, incluindo o endpoint do provedor configurado (`baseUrl`) e o modo de API (`api`) quando disponíveis.
## Substituições de depuração
`/debug` permite definir substituições de configuração **apenas de runtime** (memória, não disco). Somente proprietário. Desativado por padrão; ative com `commands.debug: true`.
`/debug` permite definir substituições de configuração **somente em runtime** (memória, não disco). Somente proprietário. Desabilitado por padrão; habilite com `commands.debug: true`.
Exemplos:
@ -366,7 +365,7 @@ As substituições se aplicam imediatamente a novas leituras de configuração,
## Saída de rastreamento de Plugin
`/trace` permite alternar **linhas de rastreamento/depuração de Plugin com escopo de sessão** sem ativar o modo totalmente detalhado.
`/trace` permite alternar **linhas de rastreamento/depuração de Plugin com escopo de sessão** sem ativar o modo detalhado completo.
Exemplos:
@ -378,16 +377,16 @@ Exemplos:
Observações:
- `/trace` sem argumento mostra o estado atual de rastreamento da sessão.
- `/trace on` ativa linhas de rastreamento de Plugin para a sessão atual.
- `/trace off` as desativa novamente.
- `/trace` sem argumento mostra o estado de rastreamento da sessão atual.
- `/trace on` habilita linhas de rastreamento de Plugin para a sessão atual.
- `/trace off` as desabilita novamente.
- Linhas de rastreamento de Plugin podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
- `/trace` não substitui `/debug`; `/debug` ainda gerencia substituições de configuração apenas de runtime.
- `/trace` não substitui `/verbose`; a saída detalhada normal de ferramenta/status ainda pertence a `/verbose`.
- `/trace` não substitui `/debug`; `/debug` ainda gerencia substituições de configuração somente em runtime.
- `/trace` não substitui `/verbose`; a saída detalhada normal de ferramentas/status ainda pertence a `/verbose`.
## Atualizações de configuração
`/config` grava na sua configuração em disco (`openclaw.json`). Somente proprietário. Desativado por padrão; ative com `commands.config: true`.
`/config` grava na sua configuração em disco (`openclaw.json`). Somente proprietário. Desabilitado por padrão; habilite com `commands.config: true`.
Exemplos:
@ -405,7 +404,7 @@ A configuração é validada antes da gravação; alterações inválidas são r
## Atualizações de MCP
`/mcp` grava definições de servidores MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desativado por padrão; ative com `commands.mcp: true`.
`/mcp` grava definições de servidores MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desabilitado por padrão; habilite com `commands.mcp: true`.
Exemplos:
@ -417,12 +416,12 @@ Exemplos:
```
<Note>
`/mcp` armazena a configuração na configuração do OpenClaw, não nas configurações de projeto de propriedade do Pi. Adaptadores de runtime decidem quais transportes são realmente executáveis.
`/mcp` armazena a configuração na configuração do OpenClaw, não em configurações de projeto pertencentes ao Pi. Adaptadores de runtime decidem quais transportes são realmente executáveis.
</Note>
## Atualizações de Plugin
`/plugins` permite que operadores inspecionem Plugins descobertos e alternem a habilitação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desativado por padrão; ative com `commands.plugins: true`.
`/plugins` permite que operadores inspecionem Plugins descobertos e alternem a habilitação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desabilitado por padrão; habilite com `commands.plugins: true`.
Exemplos:
@ -435,10 +434,10 @@ Exemplos:
```
<Note>
- `/plugins list` e `/plugins show` usam descoberta real de Plugins no workspace atual mais a configuração em disco.
- `/plugins install` instala a partir de ClawHub, npm, git, diretórios locais e arquivos.
- `/plugins enable|disable` atualiza apenas a configuração do Plugin; não instala nem desinstala Plugins.
- Alterações de ativação e desativação recarregam a quente as superfícies de runtime de Plugin do Gateway para novas interações do agente; a instalação solicita uma reinicialização do Gateway porque os módulos de origem do Plugin mudaram.
- `/plugins list` e `/plugins show` usam descoberta real de Plugin no workspace atual mais a configuração em disco.
- `/plugins install` instala a partir de ClawHub, npm, git, diretórios locais e arquivos compactados.
- `/plugins enable|disable` atualiza apenas a configuração do Plugin; ele não instala nem desinstala Plugins.
- Alterações de habilitação e desabilitação recarregam a quente as superfícies de runtime de Plugin do Gateway para novas rodadas de agente; a instalação solicita uma reinicialização do Gateway porque os módulos-fonte do Plugin mudaram.
</Note>
@ -455,7 +454,7 @@ Exemplos:
</Accordion>
<Accordion title="Especificidades do Slack">
`channels.slack.slashCommand` ainda é compatível com um único comando no estilo `/openclaw`. Se você ativar `commands.native`, deverá criar um comando de barra do Slack para cada comando integrado (os mesmos nomes de `/help`). Menus de argumentos de comando para Slack são entregues como botões efêmeros do Block Kit.
`channels.slack.slashCommand` ainda é compatível com um único comando no estilo `/openclaw`. Se você habilitar `commands.native`, deverá criar um comando de barra do Slack por comando integrado (mesmos nomes de `/help`). Menus de argumentos de comando para Slack são entregues como botões efêmeros do Block Kit.
Exceção nativa do Slack: registre `/agentstatus` (não `/status`) porque o Slack reserva `/status`. O texto `/status` ainda funciona em mensagens do Slack.
@ -466,15 +465,15 @@ Exemplos:
`/btw` é uma **pergunta paralela** rápida sobre a sessão atual. `/side` é um alias.
Ao contrário do chat normal:
Diferente do chat normal:
- usa a sessão atual como contexto de fundo,
- é executada como uma chamada separada de disparo único **sem ferramentas**,
- executa como uma chamada única separada **sem ferramentas**,
- não altera o contexto futuro da sessão,
- não é gravada no histórico de transcrições,
- não é gravado no histórico de transcrição,
- é entregue como um resultado paralelo ao vivo em vez de uma mensagem normal do assistente.
Isso torna `/btw` útil quando você quer um esclarecimento temporário enquanto a tarefa principal continua.
Isso torna `/btw` útil quando você quer um esclarecimento temporário enquanto a tarefa principal continua em andamento.
Exemplo:
@ -483,10 +482,10 @@ Exemplo:
/side what changed while the main run continued?
```
Veja [Perguntas Paralelas BTW](/pt-BR/tools/btw) para o comportamento completo e os detalhes de UX do cliente.
Consulte [Perguntas paralelas BTW](/pt-BR/tools/btw) para ver o comportamento completo e os detalhes de UX do cliente.
## Relacionado
- [Criando Skills](/pt-BR/tools/creating-skills)
- [Criação de Skills](/pt-BR/tools/creating-skills)
- [Skills](/pt-BR/tools/skills)
- [Configuração de Skills](/pt-BR/tools/skills-config)

85
docs/pt-BR/tools/steer.md Normal file
View File

@ -0,0 +1,85 @@
---
read_when:
- Usando /steer ou /tell enquanto um agente já está em execução
- Comparando /steer com /queue steer
- Decidindo se deve orientar a execução atual, um subagente ou uma sessão ACP
sidebarTitle: Steer
summary: Oriente uma execução ativa sem alterar o modo de fila
title: Direcionar
x-i18n:
generated_at: "2026-05-04T05:55:27Z"
model: gpt-5.5
provider: openai
source_hash: 71e1c80c0eea86d5c3c29513d3ed0675c04779fc9c6ee3b8a76c4bedaa264d22
source_path: tools/steer.md
workflow: 16
---
`/steer` envia orientação para uma execução já ativa. Ele é para momentos de "ajustar esta
execução enquanto ela ainda está trabalhando", não para iniciar um novo turno.
## Sessão atual
Use `/steer` de nível superior para direcionar a execução ativa da sessão atual:
```text
/steer prefer the smaller patch and keep the tests focused
/tell summarize before making the next tool call
```
Comportamento:
- Direciona somente a execução ativa da sessão atual.
- Funciona independentemente do modo `/queue` da sessão.
- Não inicia uma nova execução quando a sessão está ociosa.
- Responde com um aviso quando não há execução ativa para direcionar.
- Usa o caminho de direcionamento do runtime ativo, portanto o modelo vê a orientação no
próximo limite de runtime compatível.
## Direcionar vs fila
`/queue steer` altera como mensagens de entrada normais se comportam quando chegam
enquanto uma execução está ativa. `/steer <message>` é um comando explícito que tenta
injetar a mensagem desse comando na execução ativa no próximo limite de runtime
compatível, independentemente da configuração `/queue` armazenada.
Use:
- `/steer <message>` quando quiser orientar a execução ativa agora.
- `/queue steer` quando quiser que futuras mensagens normais direcionem execuções ativas por
padrão.
- `/queue collect` ou `/queue followup` quando novas mensagens devem aguardar um
turno posterior em vez de direcionar a execução ativa.
Para modos de fila e comportamento de fallback, consulte [Fila de comandos](/pt-BR/concepts/queue) e
[Fila de direcionamento](/pt-BR/concepts/queue-steering).
## Subagentes
Use `/subagents steer` quando o alvo for uma execução filha:
```text
/subagents steer 2 focus only on the API surface
```
`/steer` de nível superior não seleciona um subagente por id ou índice de lista. Ele sempre
direciona a execução ativa da sessão atual. Consulte [Subagentes](/pt-BR/tools/subagents) para
ids, rótulos e comandos de controle de subagentes.
## Sessões ACP
Use `/acp steer` quando o alvo for uma sessão de harness ACP:
```text
/acp steer --session agent:main:acp:codex tighten the repro
```
Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para seleção de sessão ACP e comportamento de
runtime.
## Relacionado
- [Comandos de barra](/pt-BR/tools/slash-commands)
- [Fila de comandos](/pt-BR/concepts/queue)
- [Fila de direcionamento](/pt-BR/concepts/queue-steering)
- [Subagentes](/pt-BR/tools/subagents)

327
docs/pt-BR/tools/subagents.md
View File

@ -1,47 +1,47 @@
---
read_when:
- Você quer trabalho em segundo plano ou paralelo por meio do agente
- Você está alterando a política de sessions_spawn ou da ferramenta de subagente
- Você está implementando ou solucionando problemas de sessões de subagentes vinculadas à thread
- Você quer trabalho em segundo plano ou em paralelo por meio do agente
- Você está alterando sessions_spawn ou a política da ferramenta de subagente
- Você está implementando ou solucionando problemas de sessões de subagente vinculadas a threads
sidebarTitle: Sub-agents
summary: Gere execuções isoladas de agentes em segundo plano que anunciam os resultados de volta no chat do solicitante
summary: Inicie execuções isoladas de agentes em segundo plano que anunciam os resultados de volta ao chat do solicitante
title: Subagentes
x-i18n:
generated_at: "2026-05-02T21:07:08Z"
generated_at: "2026-05-04T05:55:41Z"
model: gpt-5.5
provider: openai
source_hash: 0e964df543bd19435daf94f2c85a34b9d32e07662405d2eac7635935f1e7bf64
source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8
source_path: tools/subagents.md
workflow: 16
---
Subagentes são execuções de agentes em segundo plano geradas a partir de uma execução de agente existente.
Subagentes são execuções de agente em segundo plano geradas a partir de uma execução de agente existente.
Eles são executados em sua própria sessão (`agent:<agentId>:subagent:<uuid>`) e,
quando terminam, **anunciam** seu resultado de volta ao canal de chat
solicitante. Cada execução de subagente é rastreada como uma
quando terminam, **anunciam** o resultado de volta ao canal de chat
do solicitante. Cada execução de subagente é rastreada como uma
[tarefa em segundo plano](/pt-BR/automation/tasks).
Objetivos principais:
- Paralelizar trabalho de "pesquisa / tarefa longa / ferramenta lenta" sem bloquear a execução principal.
- Manter subagentes isolados por padrão (separação de sessão + sandboxing opcional).
- Manter subagentes isolados por padrão (separação de sessão + sandbox opcional).
- Manter a superfície de ferramentas difícil de usar incorretamente: subagentes **não** recebem ferramentas de sessão por padrão.
- Dar suporte a profundidade de aninhamento configurável para padrões de orquestrador.
<Note>
**Observação de custo:** cada subagente tem seu próprio contexto e uso de tokens por
padrão. Para tarefas pesadas ou repetitivas, defina um modelo mais barato para subagentes
e mantenha seu agente principal em um modelo de maior qualidade. Configure via
e mantenha seu agente principal em um modelo de qualidade mais alta. Configure via
`agents.defaults.subagents.model` ou substituições por agente. Quando um filho
realmente precisa da transcrição atual do solicitante, o agente pode solicitar
`context: "fork"` nessa geração específica. Sessões de subagente vinculadas a thread usam por padrão
`context: "fork"` porque ramificam a conversa atual em uma
`context: "fork"` nessa geração específica. Sessões de subagente vinculadas a thread usam
`context: "fork"` por padrão porque ramificam a conversa atual em uma
thread de acompanhamento.
</Note>
## Comando slash
## Comando de barra
Use `/subagents` para inspecionar ou controlar execuções de subagente da **sessão
Use `/subagents` para inspecionar ou controlar execuções de subagentes para a **sessão
atual**:
```text
@ -54,14 +54,16 @@ atual**:
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
```
Use [`/steer <message>`](/pt-BR/tools/steer) no nível superior para orientar a execução ativa da sessão solicitante atual. Use `/subagents steer <id|#> <message>` quando o alvo for uma execução filha.
`/subagents info` mostra metadados da execução (status, carimbos de data/hora, id da sessão,
caminho da transcrição, limpeza). Use `sessions_history` para uma visão de recuperação limitada
caminho da transcrição, limpeza). Use `sessions_history` para uma visualização de recordação limitada
e filtrada por segurança; inspecione o caminho da transcrição em disco quando você
precisar da transcrição completa bruta.
precisar da transcrição bruta completa.
### Controles de vinculação de thread
Esses comandos funcionam em canais que dão suporte a vinculações persistentes de thread.
Estes comandos funcionam em canais que dão suporte a vinculações persistentes de thread.
Veja [Canais com suporte a thread](#thread-supporting-channels) abaixo.
```text
@ -74,76 +76,77 @@ Veja [Canais com suporte a thread](#thread-supporting-channels) abaixo.
### Comportamento de geração
`/subagents spawn` inicia um subagente em segundo plano como um comando do usuário (não um
reencaminhamento interno) e envia uma atualização final de conclusão de volta ao
chat solicitante quando a execução termina.
`/subagents spawn` inicia um subagente em segundo plano como um comando de usuário (não um
encaminhamento interno) e envia uma atualização final de conclusão de volta ao
chat do solicitante quando a execução termina.
<AccordionGroup>
<Accordion title="Non-blocking, push-based completion">
- O comando de geração não bloqueia; ele retorna um id de execução imediatamente.
- Ao concluir, o subagente anuncia uma mensagem de resumo/resultado de volta ao canal de chat solicitante.
- A conclusão é baseada em push. Depois de gerar, **não** consulte `/subagents list`, `sessions_list` ou `sessions_history` em loop apenas para esperar que termine; inspecione o status somente sob demanda para depuração ou intervenção.
- Ao concluir, o OpenClaw faz o melhor esforço para fechar abas/processos do navegador rastreados que foram abertos por essa sessão de subagente antes que o fluxo de limpeza do anúncio continue.
- Ao concluir, o subagente anuncia uma mensagem de resumo/resultado de volta ao canal de chat do solicitante.
- A conclusão é baseada em push. Depois de gerado, **não** consulte `/subagents list`, `sessions_list` ou `sessions_history` em loop apenas para esperar que ele termine; inspecione o status somente sob demanda para depuração ou intervenção.
- Ao concluir, o OpenClaw faz o melhor esforço para fechar abas/processos de navegador rastreados abertos por essa sessão de subagente antes que o fluxo de limpeza do anúncio continue.
</Accordion>
<Accordion title="Manual-spawn delivery resilience">
- O OpenClaw tenta primeiro a entrega direta por `agent` com uma chave de idempotência estável.
- Se a entrega direta falhar, ele recorre ao roteamento por fila.
- Se o roteamento por fila ainda não estiver disponível, o anúncio é tentado novamente com um breve backoff exponencial antes da desistência final.
- A entrega de conclusão mantém a rota resolvida do solicitante: rotas de conclusão vinculadas a thread ou vinculadas à conversa prevalecem quando disponíveis; se a origem da conclusão fornece apenas um canal, o OpenClaw preenche o destino/conta ausente a partir da rota resolvida da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que a entrega direta ainda funcione.
- O OpenClaw tenta primeiro a entrega direta para `agent` com uma chave de idempotência estável.
- Se o turno de conclusão do agente solicitante falhar, não produzir saída visível ou retornar um prefixo obviamente incompleto do resultado filho capturado, o OpenClaw recorre à entrega direta da conclusão a partir do resultado filho capturado.
- Se a entrega direta não puder ser usada, ele recorre ao roteamento por fila.
- Se o roteamento por fila ainda não estiver disponível, o anúncio é tentado novamente com um recuo exponencial curto antes da desistência final.
- A entrega da conclusão mantém a rota resolvida do solicitante: rotas de conclusão vinculadas a thread ou vinculadas a conversa vencem quando disponíveis; se a origem da conclusão fornece apenas um canal, o OpenClaw preenche o alvo/conta ausente a partir da rota resolvida da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que a entrega direta ainda funcione.
</Accordion>
<Accordion title="Completion handoff metadata">
A passagem de conclusão para a sessão solicitante é contexto interno gerado em tempo de execução
A transferência de conclusão para a sessão solicitante é um contexto interno gerado em tempo de execução
(não texto criado pelo usuário) e inclui:
- `Result` — o texto da resposta `assistant` visível mais recente; caso contrário, o texto sanitizado mais recente de tool/toolResult. Execuções terminais com falha não reutilizam texto de resposta capturado.
- `Result` — texto da resposta `assistant` visível mais recente; caso contrário, texto de ferramenta/toolResult mais recente higienizado. Execuções terminais com falha não reutilizam texto de resposta capturado.
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
- Estatísticas compactas de tempo de execução/tokens.
- Uma instrução de entrega dizendo ao agente solicitante para reescrever em voz normal de assistente (não encaminhar metadados internos brutos).
- Estatísticas compactas de runtime/tokens.
- Uma instrução de entrega dizendo ao agente solicitante para reescrever na voz normal de assistente (não encaminhar metadados internos brutos).
</Accordion>
<Accordion title="Modes and ACP runtime">
- `--model` e `--thinking` substituem os padrões dessa execução específica.
- `--model` e `--thinking` substituem os padrões para essa execução específica.
- Use `info`/`log` para inspecionar detalhes e saída após a conclusão.
- `/subagents spawn` é modo de execução única (`mode: "run"`). Para sessões persistentes vinculadas a thread, use `sessions_spawn` com `thread: true` e `mode: "session"`.
- Para sessões de harness ACP (Claude Code, Gemini CLI, OpenCode ou Codex ACP/acpx explícito), use `sessions_spawn` com `runtime: "acp"` quando a ferramenta anunciar esse runtime. Veja [modelo de entrega ACP](/pt-BR/tools/acp-agents#delivery-model) ao depurar conclusões ou loops de agente para agente. Quando o plugin `codex` estiver habilitado, o controle de chat/thread do Codex deve preferir `/codex ...` em vez de ACP, a menos que o usuário peça explicitamente ACP/acpx.
- O OpenClaw oculta `runtime: "acp"` até que ACP esteja habilitado, o solicitante não esteja em sandbox e um plugin de backend como `acpx` esteja carregado. `runtime: "acp"` espera um id externo de harness ACP ou uma entrada `agents.list[]` com `runtime.type="acp"`; use o runtime padrão de subagente para agentes normais de configuração do OpenClaw a partir de `agents_list`.
- `/subagents spawn` é modo de disparo único (`mode: "run"`). Para sessões persistentes vinculadas a thread, use `sessions_spawn` com `thread: true` e `mode: "session"`.
- Para sessões de harness ACP (Claude Code, Gemini CLI, OpenCode ou Codex ACP/acpx explícito), use `sessions_spawn` com `runtime: "acp"` quando a ferramenta anunciar esse runtime. Veja [Modelo de entrega ACP](/pt-BR/tools/acp-agents#delivery-model) ao depurar conclusões ou loops de agente para agente. Quando o plugin `codex` estiver habilitado, o controle de chat/thread do Codex deve preferir `/codex ...` em vez de ACP, a menos que o usuário peça explicitamente ACP/acpx.
- O OpenClaw oculta `runtime: "acp"` até que o ACP esteja habilitado, o solicitante não esteja em sandbox e um plugin de backend como `acpx` esteja carregado. `runtime: "acp"` espera um id de harness ACP externo, ou uma entrada `agents.list[]` com `runtime.type="acp"`; use o runtime padrão de subagente para agentes normais de configuração do OpenClaw em `agents_list`.
</Accordion>
</AccordionGroup>
## Modos de contexto
Subagentes nativos começam isolados, a menos que o chamador peça explicitamente para ramificar
Subagentes nativos começam isolados, a menos que o chamador peça explicitamente para bifurcar
a transcrição atual.
| Modo | Quando usar | Comportamento |
| Modo | Quando usar | Comportamento |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | Pesquisa nova, implementação independente, trabalho com ferramenta lenta ou qualquer coisa que possa ser instruída no texto da tarefa | Cria uma transcrição filha limpa. Este é o padrão e mantém o uso de tokens mais baixo. |
| `fork` | Trabalho que depende da conversa atual, resultados anteriores de ferramentas ou instruções sutis já presentes na transcrição do solicitante | Ramifica a transcrição do solicitante para a sessão filha antes do início do filho. |
| `isolated` | Pesquisa nova, implementação independente, trabalho de ferramenta lenta ou qualquer coisa que possa ser resumida no texto da tarefa | Cria uma transcrição filha limpa. Este é o padrão e mantém o uso de tokens menor. |
| `fork` | Trabalho que depende da conversa atual, de resultados anteriores de ferramentas ou de instruções nuances já presentes na transcrição do solicitante | Ramifica a transcrição do solicitante na sessão filha antes que o filho comece. |
Use `fork` com moderação. Ele é para delegação sensível ao contexto, não um
substituto para escrever um prompt de tarefa claro.
## Ferramenta: `sessions_spawn`
Inicia uma execução de subagente com `deliver: false` na faixa global `subagent`,
depois executa uma etapa de anúncio e publica a resposta de anúncio no canal de chat
solicitante.
Inicia uma execução de subagente com `deliver: false` na lane global `subagent`,
depois executa uma etapa de anúncio e publica a resposta do anúncio no canal de chat
do solicitante.
A disponibilidade depende da política efetiva de ferramentas do chamador. Os perfis `coding` e
`full` expõem `sessions_spawn` por padrão. O perfil `messaging`
não expõe; adicione `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]` ou use `tools.profile: "coding"` para agentes que devem delegar
trabalho. Políticas de canal/grupo, provedor, sandbox e allow/deny por agente ainda podem
remover a ferramenta após a etapa de perfil. Use `/tools` da mesma
trabalho. Políticas de canal/grupo, provedor, sandbox e permissões/negações por agente ainda podem
remover a ferramenta após a etapa de perfil. Use `/tools` na mesma
sessão para confirmar a lista efetiva de ferramentas.
**Padrões:**
- **Modelo:** herda do chamador, a menos que você defina `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` por agente); um `sessions_spawn.model` explícito ainda prevalece.
- **Thinking:** herda do chamador, a menos que você defina `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` por agente); um `sessions_spawn.thinking` explícito ainda prevalece.
- **Modelo:** herda do chamador, a menos que você defina `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` por agente); um `sessions_spawn.model` explícito ainda vence.
- **Thinking:** herda do chamador, a menos que você defina `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` por agente); um `sessions_spawn.thinking` explícito ainda vence.
- **Tempo limite da execução:** se `sessions_spawn.runTimeoutSeconds` for omitido, o OpenClaw usa `agents.defaults.subagents.runTimeoutSeconds` quando definido; caso contrário, recorre a `0` (sem tempo limite).
### Parâmetros da ferramenta
@ -152,28 +155,28 @@ sessão para confirmar a lista efetiva de ferramentas.
A descrição da tarefa para o subagente.
</ParamField>
<ParamField path="label" type="string">
Rótulo opcional legível por humanos.
Rótulo legível opcional.
</ParamField>
<ParamField path="agentId" type="string">
Gerar sob outro id de agente quando permitido por `subagents.allowAgents`.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
`acp` é apenas para harnesses ACP externos (`claude`, `droid`, `gemini`, `opencode` ou Codex ACP/acpx explicitamente solicitado) e para entradas `agents.list[]` cujo `runtime.type` é `acp`.
`acp` é somente para harnesses ACP externos (`claude`, `droid`, `gemini`, `opencode` ou Codex ACP/acpx explicitamente solicitado) e para entradas `agents.list[]` cujo `runtime.type` é `acp`.
</ParamField>
<ParamField path="resumeSessionId" type="string">
Somente ACP. Retoma uma sessão de harness ACP existente quando `runtime: "acp"`; ignorado para gerações nativas de subagente.
Somente ACP. Retoma uma sessão existente de harness ACP quando `runtime: "acp"`; ignorado para gerações de subagente nativas.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
Somente ACP. Transmite a saída da execução ACP para a sessão pai quando `runtime: "acp"`; omita para gerações nativas de subagente.
Somente ACP. Transmite a saída da execução ACP para a sessão pai quando `runtime: "acp"`; omita para gerações de subagente nativas.
</ParamField>
<ParamField path="model" type="string">
Substitui o modelo do subagente. Valores inválidos são ignorados e o subagente é executado no modelo padrão com um aviso no resultado da ferramenta.
Substitui o modelo do subagente. Valores inválidos são ignorados e o subagente roda no modelo padrão com um aviso no resultado da ferramenta.
</ParamField>
<ParamField path="thinking" type="string">
Substitui o nível de thinking da execução do subagente.
Substitui o nível de thinking para a execução do subagente.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
Usa como padrão `agents.defaults.subagents.runTimeoutSeconds` quando definido; caso contrário, `0`. Quando definido, a execução do subagente é abortada após N segundos.
O padrão é `agents.defaults.subagents.runTimeoutSeconds` quando definido; caso contrário, `0`. Quando definido, a execução do subagente é abortada após N segundos.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
Quando `true`, solicita vinculação de thread de canal para esta sessão de subagente.
@ -188,7 +191,7 @@ sessão para confirmar a lista efetiva de ferramentas.
`require` rejeita a geração, a menos que o runtime filho de destino esteja em sandbox.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
`fork` ramifica a transcrição atual do solicitante para a sessão filha. Somente subagentes nativos. Gerações vinculadas a thread usam `fork` por padrão; gerações sem thread usam `isolated` por padrão.
`fork` ramifica a transcrição atual do solicitante na sessão filha. Somente subagentes nativos. Gerações vinculadas a thread usam `fork` por padrão; gerações sem thread usam `isolated` por padrão.
</ParamField>
<Warning>
@ -205,10 +208,10 @@ mesma sessão de subagente.
### Canais com suporte a thread
**Discord** atualmente é o único canal compatível. Ele oferece suporte a
**Discord** é atualmente o único canal com suporte. Ele dá suporte a
sessões persistentes de subagente vinculadas a thread (`sessions_spawn` com
`thread: true`), controles manuais de thread (`/focus`, `/unfocus`, `/agents`,
`/session idle`, `/session max-age`) e chaves de adaptador
`/session idle`, `/session max-age`) e chaves do adaptador
`channels.discord.threadBindings.enabled`,
`channels.discord.threadBindings.idleHours`,
`channels.discord.threadBindings.maxAgeHours` e
@ -227,7 +230,7 @@ sessões persistentes de subagente vinculadas a thread (`sessions_spawn` com
Respostas e mensagens de acompanhamento nessa thread são roteadas para a sessão vinculada.
</Step>
<Step title="Inspect timeouts">
Use `/session idle` para inspecionar/atualizar o auto-desfoque por inatividade e
Use `/session idle` para inspecionar/atualizar o desfoco automático por inatividade e
`/session max-age` para controlar o limite rígido.
</Step>
<Step title="Detach">
@ -239,57 +242,57 @@ sessões persistentes de subagente vinculadas a thread (`sessions_spawn` com
| Comando | Efeito |
| ------------------ | --------------------------------------------------------------------- |
| `/focus <target>` | Vincula o tópico atual (ou cria um) a um destino de subagente/sessão |
| `/unfocus` | Remove o vínculo do tópico vinculado atual |
| `/agents` | Lista execuções ativas e o estado do vínculo (`thread:<id>` ou `unbound`) |
| `/session idle` | Inspeciona/atualiza o auto-desfoque por inatividade (somente tópicos vinculados em foco) |
| `/session max-age` | Inspeciona/atualiza o limite rígido (somente tópicos vinculados em foco) |
| `/focus <target>` | Vincula a thread atual (ou cria uma) a um destino de subagente/sessão |
| `/unfocus` | Remove o vínculo da thread vinculada atual |
| `/agents` | Lista execuções ativas e o estado de vínculo (`thread:<id>` ou `unbound`) |
| `/session idle` | Inspeciona/atualiza o desfoco automático por inatividade (somente threads vinculadas em foco) |
| `/session max-age` | Inspeciona/atualiza o limite rígido (somente threads vinculadas em foco) |
### Chaves de configuração
- **Padrão global:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
- **Chaves de substituição por canal e vínculo automático ao criar** são específicas do adaptador. Consulte [Canais com suporte a tópicos](#thread-supporting-channels) acima.
- **Substituição por canal e chaves de vinculação automática no spawn** são específicas do adaptador. Veja [Canais compatíveis com threads](#thread-supporting-channels) acima.
Consulte a [Referência de configuração](/pt-BR/gateway/configuration-reference) e
[Comandos de barra](/pt-BR/tools/slash-commands) para detalhes atuais dos adaptadores.
Veja [Referência de configuração](/pt-BR/gateway/configuration-reference) e
[comandos de barra](/pt-BR/tools/slash-commands) para detalhes atuais dos adaptadores.
### Lista de permissões
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
Lista de ids de agente que podem ser direcionados via `agentId` explícito (`["*"]` permite qualquer um). Padrão: somente o agente solicitante. Se você definir uma lista e ainda quiser que o solicitante crie a si mesmo com `agentId`, inclua o id do solicitante na lista.
Lista de IDs de agentes que podem ser direcionados via `agentId` explícito (`["*"]` permite qualquer um). Padrão: somente o agente solicitante. Se você definir uma lista e ainda quiser que o solicitante crie a si mesmo com `agentId`, inclua o ID do solicitante na lista.
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
Lista de permissões padrão de agente-alvo usada quando o agente solicitante não define seu próprio `subagents.allowAgents`.
Lista de permissões padrão de agentes de destino usada quando o agente solicitante não define seu próprio `subagents.allowAgents`.
</ParamField>
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
Bloqueia chamadas `sessions_spawn` que omitem `agentId` (força a seleção explícita de perfil). Substituição por agente: `agents.list[].subagents.requireAgentId`.
</ParamField>
Se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita alvos
Se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeitará destinos
que seriam executados sem sandbox.
### Descoberta
Use `agents_list` para ver quais ids de agente estão atualmente permitidos para
Use `agents_list` para ver quais IDs de agentes estão atualmente permitidos para
`sessions_spawn`. A resposta inclui o modelo efetivo de cada agente listado
e metadados de runtime incorporados para que chamadores possam distinguir PI, o servidor de app Codex
e outros runtimes nativos configurados.
e metadados de runtime incorporados para que os chamadores possam distinguir PI,
servidor de aplicativo Codex e outros runtimes nativos configurados.
### Arquivamento automático
- Sessões de subagentes são arquivadas automaticamente após `agents.defaults.subagents.archiveAfterMinutes` (padrão `60`).
- Sessões de subagente são arquivadas automaticamente após `agents.defaults.subagents.archiveAfterMinutes` (padrão `60`).
- O arquivamento usa `sessions.delete` e renomeia a transcrição para `*.deleted.<timestamp>` (mesma pasta).
- `cleanup: "delete"` arquiva imediatamente após o anúncio (ainda mantém a transcrição via renomeação).
- O arquivamento automático é de melhor esforço; timers pendentes são perdidos se o Gateway reiniciar.
- `runTimeoutSeconds` **não** arquiva automaticamente; ele apenas interrompe a execução. A sessão permanece até o arquivamento automático.
- O arquivamento automático se aplica igualmente a sessões de profundidade 1 e profundidade 2.
- A limpeza do navegador é separada da limpeza de arquivamento: abas/processos de navegador rastreados são fechados em melhor esforço quando a execução termina, mesmo que o registro de transcrição/sessão seja mantido.
- A limpeza do navegador é separada da limpeza de arquivamento: abas/processos de navegador rastreados são fechados em melhor esforço quando a execução termina, mesmo que a transcrição/registro da sessão seja mantido.
## Subagentes aninhados
Por padrão, subagentes não podem criar seus próprios subagentes
(`maxSpawnDepth: 1`). Defina `maxSpawnDepth: 2` para habilitar um nível de
aninhamento — o **padrão de orquestrador**: principal → subagente orquestrador →
aninhamento — o **padrão orquestrador**: principal → subagente orquestrador →
sub-subagentes trabalhadores.
```json5
@ -309,31 +312,31 @@ sub-subagentes trabalhadores.
### Níveis de profundidade
| Profundidade | Formato da chave de sessão | Função | Pode criar? |
| Profundidade | Formato da chave de sessão | Função | Pode criar? |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Agente principal | Sempre |
| 0 | `agent:<id>:main` | Agente principal | Sempre |
| 1 | `agent:<id>:subagent:<uuid>` | Subagente (orquestrador quando profundidade 2 é permitida) | Somente se `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-subagente (trabalhador folha) | Nunca |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-subagente (trabalhador folha) | Nunca |
### Cadeia de anúncios
### Cadeia de anúncio
Os resultados fluem de volta pela cadeia:
1. O trabalhador de profundidade 2 termina → anuncia para seu pai (orquestrador de profundidade 1).
2. O orquestrador de profundidade 1 recebe o anúncio, sintetiza os resultados, termina → anuncia para o principal.
3. O agente principal recebe o anúncio e entrega ao usuário.
1. Trabalhador de profundidade 2 termina → anuncia ao seu pai (orquestrador de profundidade 1).
2. Orquestrador de profundidade 1 recebe o anúncio, sintetiza resultados, termina → anuncia ao principal.
3. Agente principal recebe o anúncio e entrega ao usuário.
Cada nível vê apenas anúncios de seus filhos diretos.
<Note>
**Orientação operacional:** inicie o trabalho filho uma vez e aguarde eventos
de conclusão em vez de criar loops de sondagem em torno de `sessions_list`,
`sessions_history`, `/subagents list` ou comandos `exec` de suspensão.
`sessions_list` e `/subagents list` mantêm os relacionamentos de sessões filhas
focados no trabalho ativo — filhos ativos permanecem anexados, filhos finalizados ficam
visíveis por uma janela recente curta, e links de filhos obsoletos existentes apenas no armazenamento são
ignorados depois de sua janela de atualização. Isso impede que metadados antigos de `spawnedBy` /
`parentSessionKey` ressuscitem filhos fantasmas após
de conclusão em vez de criar loops de polling em torno de `sessions_list`,
`sessions_history`, `/subagents list` ou comandos `exec` de sleep.
`sessions_list` e `/subagents list` mantêm relações de sessão filha
focadas no trabalho ativo — filhos ativos permanecem anexados, filhos encerrados ficam
visíveis por uma janela recente curta, e links de filhos antigos apenas no armazenamento são
ignorados após sua janela de frescor. Isso impede que metadados antigos de `spawnedBy` /
`parentSessionKey` ressuscitem filhos fantasma após
reinicialização. Se um evento de conclusão de filho chegar depois que você já enviou a
resposta final, o acompanhamento correto é o token silencioso exato
`NO_REPLY` / `no_reply`.
@ -341,77 +344,78 @@ resposta final, o acompanhamento correto é o token silencioso exato
### Política de ferramentas por profundidade
- A função e o escopo de controle são gravados nos metadados da sessão no momento da criação. Isso impede que chaves de sessão planas ou restauradas recuperem privilégios de orquestrador acidentalmente.
- A função e o escopo de controle são gravados nos metadados da sessão no momento do spawn. Isso impede que chaves de sessão planas ou restauradas recuperem acidentalmente privilégios de orquestrador.
- **Profundidade 1 (orquestrador, quando `maxSpawnDepth >= 2`):** recebe `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` para poder gerenciar seus filhos. Outras ferramentas de sessão/sistema permanecem negadas.
- **Profundidade 1 (folha, quando `maxSpawnDepth == 1`):** nenhuma ferramenta de sessão (comportamento padrão atual).
- **Profundidade 2 (trabalhador folha):** nenhuma ferramenta de sessão — `sessions_spawn` é sempre negado na profundidade 2. Não pode criar mais filhos.
### Limite de criação por agente
### Limite de spawn por agente
Cada sessão de agente (em qualquer profundidade) pode ter no máximo `maxChildrenPerAgent`
(padrão `5`) filhos ativos ao mesmo tempo. Isso impede expansão descontrolada
a partir de um único orquestrador.
(padrão `5`) filhos ativos por vez. Isso evita fan-out descontrolado
de um único orquestrador.
### Interrupção em cascata
### Parada em cascata
Interromper um orquestrador de profundidade 1 interrompe automaticamente todos os seus filhos de profundidade 2:
Interromper um orquestrador de profundidade 1 interrompe automaticamente todos os seus filhos
de profundidade 2:
- `/stop` no chat principal interrompe todos os agentes de profundidade 1 e faz cascata para seus filhos de profundidade 2.
- `/subagents kill <id>` interrompe um subagente específico e faz cascata para seus filhos.
- `/subagents kill all` interrompe todos os subagentes do solicitante e faz cascata.
- `/stop` no chat principal interrompe todos os agentes de profundidade 1 e propaga para seus filhos de profundidade 2.
- `/subagents kill <id>` interrompe um subagente específico e propaga para seus filhos.
- `/subagents kill all` interrompe todos os subagentes do solicitante e propaga.
## Autenticação
A autenticação de subagente é resolvida por **id do agente**, não por tipo de sessão:
A autenticação de subagente é resolvida por **ID do agente**, não por tipo de sessão:
- A chave de sessão do subagente é `agent:<agentId>:subagent:<uuid>`.
- O armazenamento de autenticação é carregado a partir do `agentDir` desse agente.
- Os perfis de autenticação do agente principal são mesclados como **fallback**; perfis de agente substituem perfis principais em conflitos.
- O armazenamento de autenticação é carregado do `agentDir` desse agente.
- Os perfis de autenticação do agente principal são mesclados como **fallback**; perfis do agente substituem perfis principais em conflitos.
A mesclagem é aditiva, então perfis principais estão sempre disponíveis como
A mesclagem é aditiva, então os perfis principais estão sempre disponíveis como
fallbacks. Autenticação totalmente isolada por agente ainda não é compatível.
## Anúncio
Subagentes retornam relatórios por meio de uma etapa de anúncio:
Subagentes reportam de volta por meio de uma etapa de anúncio:
- A etapa de anúncio é executada dentro da sessão do subagente (não da sessão solicitante).
- Se o subagente responder exatamente `ANNOUNCE_SKIP`, nada é publicado.
- Se o texto mais recente do assistente for o token silencioso exato `NO_REPLY` / `no_reply`, a saída do anúncio é suprimida mesmo que tenha havido progresso visível anterior.
- Se o subagente responder exatamente `ANNOUNCE_SKIP`, nada será postado.
- Se o texto mais recente do assistente for o token silencioso exato `NO_REPLY` / `no_reply`, a saída de anúncio será suprimida mesmo que tenha havido progresso visível anterior.
A entrega depende da profundidade do solicitante:
- Sessões solicitantes de nível superior usam uma chamada `agent` de acompanhamento com entrega externa (`deliver=true`).
- Sessões de subagente solicitantes aninhadas recebem uma injeção interna de acompanhamento (`deliver=false`) para que o orquestrador possa sintetizar resultados de filhos na sessão.
- Se uma sessão de subagente solicitante aninhada desapareceu, o OpenClaw recorre ao solicitante dessa sessão quando disponível.
- Sessões de subagente solicitantes aninhadas recebem uma injeção interna de acompanhamento (`deliver=false`) para que o orquestrador possa sintetizar resultados filhos na sessão.
- Se uma sessão de subagente solicitante aninhada não existir mais, o OpenClaw recorre ao solicitante dessa sessão quando disponível.
Para sessões solicitantes de nível superior, a entrega direta em modo de conclusão primeiro
resolve qualquer rota de conversa/tópico vinculada e substituição de hook, depois preenche
campos de alvo de canal ausentes a partir da rota armazenada da sessão solicitante.
Isso mantém as conclusões no chat/tópico correto mesmo quando a origem da
conclusão identifica apenas o canal.
resolve qualquer rota de conversa/thread vinculada e substituição de hook, depois preenche
campos ausentes de destino do canal a partir da rota armazenada da sessão solicitante.
Isso mantém as conclusões no chat/tópico correto mesmo quando a origem da conclusão
identifica apenas o canal.
A agregação de conclusão de filhos é limitada à execução solicitante atual ao
criar achados de conclusão aninhados, impedindo que saídas de filhos de
execuções anteriores obsoletas vazem para o anúncio atual. Respostas de anúncio preservam
o roteamento de tópico quando disponível nos adaptadores de canal.
A agregação de conclusão de filhos é escopada à execução solicitante atual ao
criar descobertas de conclusão aninhadas, impedindo que saídas de filhos de execuções
anteriores antigas vazem para o anúncio atual. Respostas de anúncio preservam
o roteamento de thread/tópico quando disponível nos adaptadores de canal.
### Contexto do anúncio
### Contexto de anúncio
O contexto do anúncio é normalizado para um bloco de evento interno estável:
O contexto de anúncio é normalizado para um bloco de evento interno estável:
| Campo | Fonte |
| Campo | Origem |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| Origem | `subagent` ou `cron` |
| Ids de sessão | Chave/id da sessão filha |
| Tipo | Tipo de anúncio + rótulo da tarefa |
| IDs de sessão | Chave/ID da sessão filha |
| Tipo | Tipo de anúncio + rótulo da tarefa |
| Status | Derivado do resultado do runtime (`success`, `error`, `timeout` ou `unknown`) — **não** inferido do texto do modelo |
| Conteúdo do resultado | Texto visível mais recente do assistente; caso contrário, texto mais recente de ferramenta/toolResult sanitizado |
| Acompanhamento | Instrução descrevendo quando responder versus permanecer em silêncio |
| Conteúdo do resultado | Texto visível mais recente do assistente; caso contrário, texto mais recente sanitizado de ferramenta/toolResult |
| Acompanhamento | Instrução descrevendo quando responder vs permanecer silencioso |
Execuções terminais com falha relatam status de falha sem reproduzir
texto de resposta capturado. Em caso de timeout, se o filho passou apenas por chamadas de ferramenta, o anúncio
pode condensar esse histórico em um resumo curto de progresso parcial em vez
Execuções terminais com falha reportam status de falha sem reproduzir o
texto de resposta capturado. Em timeout, se o filho só chegou a chamadas de ferramenta,
o anúncio pode condensar esse histórico em um breve resumo de progresso parcial em vez
de reproduzir a saída bruta da ferramenta.
### Linha de estatísticas
@ -421,27 +425,28 @@ Payloads de anúncio incluem uma linha de estatísticas no final (mesmo quando e
- Runtime (por exemplo, `runtime 5m12s`).
- Uso de tokens (entrada/saída/total).
- Custo estimado quando a precificação do modelo está configurada (`models.providers.*.models[].cost`).
- `sessionKey`, `sessionId` e caminho da transcrição para que o agente principal possa buscar o histórico via `sessions_history` ou inspecionar o arquivo no disco.
- `sessionKey`, `sessionId` e caminho da transcrição para que o agente principal possa buscar o histórico via `sessions_history` ou inspecionar o arquivo em disco.
Metadados internos são destinados apenas à orquestração; respostas voltadas ao usuário
Metadados internos servem apenas para orquestração; respostas voltadas ao usuário
devem ser reescritas na voz normal do assistente.
### Por que preferir `sessions_history`
`sessions_history` é o caminho de orquestração mais seguro:
- A recordação do assistente é normalizada primeiro: tags de raciocínio removidas; andaimes `<relevant-memories>` / `<relevant_memories>` removidos; blocos de payload XML de chamada de ferramenta em texto simples (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) removidos, incluindo payloads truncados que nunca fecham corretamente; andaimes de chamada/resultado de ferramenta rebaixados e marcadores de contexto histórico removidos; tokens de controle de modelo vazados (`<|assistant|>`, outros ASCII `<|...|>`, largura total `<｜...｜>`) removidos; XML malformado de chamada de ferramenta MiniMax removido.
- A lembrança do assistente é normalizada primeiro: tags de pensamento removidas; scaffolding `<relevant-memories>` / `<relevant_memories>` removido; blocos de payload XML em texto simples de chamadas de ferramenta (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) removidos, incluindo payloads truncados que nunca fecham corretamente; scaffolding rebaixado de chamada/resultado de ferramenta e marcadores de contexto histórico removidos; tokens de controle de modelo vazados (`<|assistant|>`, outros ASCII `<|...|>`, largura total `<｜...｜>`) removidos; XML malformado de chamada de ferramenta MiniMax removido.
- Texto semelhante a credencial/token é redigido.
- Blocos longos podem ser truncados.
- Históricos muito grandes podem descartar linhas mais antigas ou substituir uma linha superdimensionada por `[sessions_history omitted: message too large]`.
- A inspeção da transcrição bruta no disco é o fallback quando você precisa da transcrição byte a byte completa.
- Históricos muito grandes podem descartar linhas antigas ou substituir uma linha grande demais por `[sessions_history omitted: message too large]`.
- A inspeção da transcrição bruta em disco é o fallback quando você precisa da transcrição completa byte por byte.
## Política de ferramentas
Subagentes usam primeiro o mesmo perfil e pipeline de política de ferramentas do agente pai ou
alvo. Depois disso, o OpenClaw aplica a camada de restrição de subagente.
Subagentes usam primeiro o mesmo perfil e pipeline de política de ferramentas que o agente pai ou
agente de destino. Depois disso, o OpenClaw aplica a camada de restrição
de subagente.
Sem um `tools.profile` restritivo, subagentes recebem **todas as ferramentas, exceto
Sem um `tools.profile` restritivo, subagentes recebem **todas as ferramentas exceto
ferramentas de sessão** e ferramentas de sistema:
- `sessions_list`
@ -449,12 +454,12 @@ ferramentas de sessão** e ferramentas de sistema:
- `sessions_send`
- `sessions_spawn`
`sessions_history` continua sendo uma visão de recordação limitada e sanitizada também aqui — ele
`sessions_history` também permanece aqui uma visualização delimitada e sanitizada de recuperação —
não é um despejo bruto de transcrição.
Quando `maxSpawnDepth >= 2`, subagentes orquestradores de profundidade 1 também
recebem `sessions_spawn`, `subagents`, `sessions_list` e
`sessions_history` para poderem gerenciar seus filhos.
`sessions_history` para que possam gerenciar seus filhos.
### Substituição via configuração
@ -480,12 +485,12 @@ recebem `sessions_spawn`, `subagents`, `sessions_list` e
}
```
`tools.subagents.tools.allow` é um filtro final somente de permissão. Ele pode restringir
o conjunto de ferramentas já resolvido, mas não pode **readicionar** uma ferramenta removida
`tools.subagents.tools.allow` é um filtro final apenas de permissão. Ele pode restringir
o conjunto de ferramentas já resolvido, mas não pode **adicionar de volta** uma ferramenta removida
por `tools.profile`. Por exemplo, `tools.profile: "coding"` inclui
`web_search`/`web_fetch`, mas não a ferramenta `browser`. Para permitir que
sub-agentes com perfil de codificação usem automação de navegador, adicione browser na
etapa do perfil:
subagentes com perfil de codificação usem automação de navegador, adicione browser no
estágio de perfil:
```json5
{
@ -501,58 +506,58 @@ agente deve receber automação de navegador.
## Concorrência
Sub-agentes usam uma faixa dedicada de fila no processo:
Subagentes usam uma fila dedicada em processo:
- **Nome da faixa:** `subagent`
- **Nome da fila:** `subagent`
- **Concorrência:** `agents.defaults.subagents.maxConcurrent` (padrão `8`)
## Vivacidade e recuperação
O OpenClaw não trata a ausência de `endedAt` como prova permanente de que um
sub-agente ainda está ativo. Execuções não encerradas mais antigas que a janela de execução obsoleta
subagente ainda está ativo. Execuções não encerradas mais antigas que a janela de execução obsoleta
deixam de contar como ativas/pendentes em `/subagents list`, resumos de status,
bloqueio de conclusão de descendentes e verificações de concorrência por sessão.
Após uma reinicialização do Gateway, execuções restauradas obsoletas e não encerradas são podadas, a menos
que a sessão filha delas esteja marcada como `abortedLastRun: true`. Essas
Após uma reinicialização do Gateway, execuções restauradas obsoletas não encerradas são removidas, a menos que
a sessão filha esteja marcada como `abortedLastRun: true`. Essas
sessões filhas abortadas por reinicialização permanecem recuperáveis pelo fluxo de recuperação de órfãos
de sub-agentes, que envia uma mensagem sintética de retomada antes de
de subagente, que envia uma mensagem sintética de retomada antes de
limpar o marcador de abortado.
A recuperação automática por reinicialização é limitada por sessão filha. Se o mesmo
filho de sub-agente for aceito para recuperação de órfão repetidamente dentro da
janela rápida de recunhagem, o OpenClaw persiste uma lápide de recuperação nessa
sessão e deixa de retomá-la automaticamente em reinicializações posteriores. Execute
A recuperação automática após reinicialização é limitada por sessão filha. Se o mesmo
subagente filho for aceito para recuperação de órfão repetidamente dentro da
janela rápida de retravamento, o OpenClaw persiste uma lápide de recuperação nessa
sessão e para de retomá-la automaticamente em reinicializações posteriores. Execute
`openclaw tasks maintenance --apply` para reconciliar o registro da tarefa, ou
`openclaw doctor --fix` para limpar flags obsoletas de recuperação abortada em
`openclaw doctor --fix` para limpar sinalizadores obsoletos de recuperação abortada em
sessões com lápide.
<Note>
Se uma criação de sub-agente falhar com Gateway `PAIRING_REQUIRED` /
Se uma criação de subagente falhar com Gateway `PAIRING_REQUIRED` /
`scope-upgrade`, verifique o chamador RPC antes de editar o estado de pareamento.
A coordenação interna de `sessions_spawn` deve se conectar como
`client.id: "gateway-client"` com `client.mode: "backend"` por autenticação direta
de local loopback com token/senha compartilhados; esse caminho não depende da
linha de base de escopo de dispositivo pareado da CLI. Chamadores remotos,
`deviceIdentity` explícito, caminhos explícitos de token de dispositivo e clientes
browser/node ainda precisam da aprovação normal do dispositivo para upgrades de escopo.
de loopback com token compartilhado/senha; esse caminho não depende da
linha de base de escopo de dispositivo pareado da CLI. Chamadores remotos, `deviceIdentity`
explícito, caminhos explícitos de token de dispositivo e clientes de navegador/node
ainda precisam de aprovação normal de dispositivo para upgrades de escopo.
</Note>
## Interrupção
- Enviar `/stop` no chat solicitante aborta a sessão solicitante e interrompe quaisquer execuções ativas de sub-agentes criadas a partir dela, propagando para filhos aninhados.
- `/subagents kill <id>` interrompe um sub-agente específico e propaga para seus filhos.
- Enviar `/stop` no chat solicitante aborta a sessão solicitante e interrompe quaisquer execuções ativas de subagente geradas a partir dela, em cascata para filhos aninhados.
- `/subagents kill <id>` interrompe um subagente específico e aplica cascata aos seus filhos.
## Limitações
- O anúncio de sub-agente é **de melhor esforço**. Se o Gateway reiniciar, o trabalho pendente de "anunciar de volta" será perdido.
- Sub-agentes ainda compartilham os mesmos recursos do processo do Gateway; trate `maxConcurrent` como uma válvula de segurança.
- O anúncio de subagente é **de melhor esforço**. Se o Gateway reiniciar, o trabalho pendente de "anunciar de volta" será perdido.
- Subagentes ainda compartilham os mesmos recursos do processo Gateway; trate `maxConcurrent` como uma válvula de segurança.
- `sessions_spawn` é sempre não bloqueante: ele retorna `{ status: "accepted", runId, childSessionKey }` imediatamente.
- O contexto de sub-agente injeta apenas `AGENTS.md` + `TOOLS.md` (sem `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ou `BOOTSTRAP.md`).
- O contexto de subagente injeta apenas `AGENTS.md` + `TOOLS.md` (sem `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ou `BOOTSTRAP.md`).
- A profundidade máxima de aninhamento é 5 (intervalo de `maxSpawnDepth`: 1–5). A profundidade 2 é recomendada para a maioria dos casos de uso.
- `maxChildrenPerAgent` limita filhos ativos por sessão (padrão `5`, intervalo `1–20`).
## Relacionados
## Relacionado
- [Agentes ACP](/pt-BR/tools/acp-agents)
- [Envio de agente](/pt-BR/tools/agent-send)

141
docs/pt-BR/tools/thinking.md
View File

@ -1,62 +1,62 @@
---
read_when:
- Ajuste da análise ou dos padrões das diretivas thinking, fast-mode ou verbose
summary: Sintaxe de diretivas para /think, /fast, /verbose, /trace e visibilidade do raciocínio
title: Níveis de raciocínio
- Ajuste da análise de diretivas ou dos padrões de raciocínio, modo rápido ou verbosidade
summary: Sintaxe de diretiva para /think, /fast, /verbose, /trace e visibilidade do raciocínio
title: Níveis de pensamento
x-i18n:
generated_at: "2026-04-30T16:30:45Z"
generated_at: "2026-05-04T05:55:58Z"
model: gpt-5.5
provider: openai
source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
source_path: tools/thinking.md
workflow: 16
---
## O que ele faz
- Diretiva inline em qualquer corpo de entrada: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Diretiva inline em qualquer corpo recebido: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Níveis (aliases): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- high → “ultrathink” (orçamento máximo)
- xhigh → “ultrathink+” (modelos GPT-5.2+ e Codex, mais esforço do Anthropic Claude Opus 4.7)
- adaptive → raciocínio adaptativo gerenciado pelo provedor (compatível com Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e raciocínio dinâmico do Google Gemini)
- max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; Ollama mapeia isso para seu maior esforço nativo de `think`)
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` são mapeados para `xhigh`.
- `highest` é mapeado para `high`.
- minimal → “pensar”
- low → “pensar com afinco”
- medium → “pensar com mais afinco”
- high → “ultrapensar” (orçamento máximo)
- xhigh → “ultrapensar+” (modelos GPT-5.2+ e Codex, além do esforço Anthropic Claude Opus 4.7)
- adaptive → pensamento adaptativo gerenciado pelo provedor (compatível com Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e pensamento dinâmico do Google Gemini)
- max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; o Ollama mapeia isso para seu maior esforço `think` nativo)
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` mapeiam para `xhigh`.
- `highest` mapeia para `high`.
- Observações sobre provedores:
- Menus e seletores de raciocínio são orientados por perfil de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como `on` binário.
- `adaptive`, `xhigh` e `max` são anunciados apenas para perfis de provedor/modelo compatíveis. Diretivas digitadas para níveis sem suporte são rejeitadas com as opções válidas desse modelo.
- Níveis sem suporte armazenados existentes são remapeados pela classificação do perfil do provedor. `adaptive` recua para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` recuam para o maior nível não `off` compatível com o modelo selecionado.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível de raciocínio explícito é definido.
- Anthropic Claude Opus 4.7 não usa raciocínio adaptativo por padrão. O padrão de esforço da API continua sob responsabilidade do provedor, a menos que você defina explicitamente um nível de raciocínio.
- Anthropic Claude Opus 4.7 mapeia `/think xhigh` para raciocínio adaptativo mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de raciocínio e `xhigh` é a configuração de esforço do Opus 4.7.
- Anthropic Claude Opus 4.7 também expõe `/think max`; ele é mapeado para o mesmo caminho de esforço máximo pertencente ao provedor.
- Modelos DeepSeek V4 expõem `/think xhigh|max`; ambos são mapeados para DeepSeek `reasoning_effort: "max"`, enquanto níveis não `off` inferiores são mapeados para `high`.
- Modelos Ollama com capacidade de raciocínio expõem `/think low|medium|high|max`; `max` é mapeado para `think: "high"` nativo, porque a API nativa do Ollama aceita strings de esforço `low`, `medium` e `high`.
- Modelos OpenAI GPT mapeiam `/think` por meio do suporte de esforço específico do modelo na Responses API. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino é compatível; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor sem suporte.
- Entradas de catálogo personalizadas compatíveis com OpenAI podem optar por `/think xhigh` definindo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI do agente e `llm-task` concordam com o comportamento de transporte.
- Referências configuradas obsoletas do OpenRouter Hunter Alpha ignoram a injeção de raciocínio por proxy porque essa rota aposentada podia retornar texto de resposta final por campos de raciocínio.
- Google Gemini mapeia `/think adaptive` para o raciocínio dinâmico pertencente ao provedor do Gemini. Solicitações do Gemini 3 omitem um `thinkingLevel` fixo, enquanto solicitações do Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda são mapeados para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente raciocínio em parâmetros de modelo ou de solicitação. Isso evita deltas de `reasoning_content` vazados do formato de stream Anthropic não nativo do MiniMax.
- Z.AI (`zai/*`) só oferece suporte a raciocínio binário (`on`/`off`). Qualquer nível que não seja `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível que não seja `off` para `thinking: { type: "enabled" }`. Quando o raciocínio está ativado, Moonshot aceita apenas `tool_choice` `auto|none`; OpenClaw normaliza valores incompatíveis para `auto`.
- Menus e seletores de pensamento são orientados por perfis de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como o binário `on`.
- `adaptive`, `xhigh` e `max` são anunciados apenas para perfis de provedor/modelo que dão suporte a eles. Diretivas digitadas para níveis sem suporte são rejeitadas com as opções válidas desse modelo.
- Níveis sem suporte armazenados anteriormente são remapeados pela classificação do perfil do provedor. `adaptive` recua para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` recuam para o maior nível diferente de off compatível com o modelo selecionado.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de pensamento é definido.
- Anthropic Claude Opus 4.7 não usa pensamento adaptativo por padrão. O padrão de esforço da API permanece sob controle do provedor, a menos que você defina explicitamente um nível de pensamento.
- Anthropic Claude Opus 4.7 mapeia `/think xhigh` para pensamento adaptativo mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de pensamento e `xhigh` é a configuração de esforço do Opus 4.7.
- Anthropic Claude Opus 4.7 também expõe `/think max`; ele mapeia para o mesmo caminho de esforço máximo controlado pelo provedor.
- Modelos DeepSeek V4 expõem `/think xhigh|max`; ambos mapeiam para `reasoning_effort: "max"` do DeepSeek, enquanto níveis menores diferentes de off mapeiam para `high`.
- Modelos Ollama com suporte a pensamento expõem `/think low|medium|high|max`; `max` mapeia para o `think: "high"` nativo, porque a API nativa do Ollama aceita as strings de esforço `low`, `medium` e `high`.
- Modelos OpenAI GPT mapeiam `/think` por meio do suporte a esforço da Responses API específico do modelo. `/think off` envia `reasoning.effort: "none"` apenas quando o modelo de destino dá suporte a isso; caso contrário, o OpenClaw omite a carga útil de raciocínio desativado em vez de enviar um valor sem suporte.
- Entradas de catálogo personalizadas compatíveis com OpenAI podem optar por `/think xhigh` definindo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam cargas úteis de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI de agente e `llm-task` concordam com o comportamento de transporte.
- Referências obsoletas configuradas do OpenRouter Hunter Alpha ignoram a injeção de raciocínio por proxy, porque essa rota aposentada podia retornar texto da resposta final por meio de campos de raciocínio.
- Google Gemini mapeia `/think adaptive` para o pensamento dinâmico controlado pelo provedor do Gemini. Solicitações Gemini 3 omitem um `thinkingLevel` fixo, enquanto solicitações Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda mapeiam para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente pensamento nos parâmetros do modelo ou nos parâmetros da solicitação. Isso evita vazamentos de deltas `reasoning_content` do formato de stream Anthropic não nativo do MiniMax.
- Z.AI (`zai/*`) só dá suporte a pensamento binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o pensamento está ativado, o Moonshot só aceita `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`.
## Ordem de resolução
1. Diretiva inline na mensagem (aplica-se somente a essa mensagem).
2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas diretiva).
1. Diretiva inline na mensagem (aplica-se apenas a essa mensagem).
2. Substituição da sessão (definida ao enviar uma mensagem somente com diretiva).
3. Padrão por agente (`agents.list[].thinkingDefault` na configuração).
4. Padrão global (`agents.defaults.thinkingDefault` na configuração).
5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos capazes de raciocínio resolvem para `medium` ou para o nível não `off` compatível mais próximo desse modelo, e modelos sem raciocínio permanecem `off`.
5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos com capacidade de raciocínio resolvem para `medium` ou para o nível diferente de `off` compatível mais próximo para esse modelo, e modelos sem raciocínio permanecem `off`.
## Definir um padrão de sessão
## Como definir um padrão de sessão
- Envie uma mensagem que seja **apenas** a diretiva (espaços em branco permitidos), por exemplo, `/think:medium` ou `/t high`.
- Isso permanece para a sessão atual (por remetente, por padrão); limpo por `/think:off` ou redefinição por inatividade da sessão.
- Envie uma mensagem que seja **somente** a diretiva (espaços em branco permitidos), por exemplo, `/think:medium` ou `/t high`.
- Isso permanece na sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição por inatividade da sessão.
- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando será rejeitado com uma dica e o estado da sessão permanecerá inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível de raciocínio atual.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível de pensamento atual.
## Aplicação por agente
@ -65,52 +65,55 @@ x-i18n:
## Modo rápido (/fast)
- Níveis: `on|off`.
- Mensagem contendo apenas diretiva alterna uma substituição de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`.
- Mensagem somente com diretiva alterna uma substituição de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`.
- Envie `/fast` (ou `/fast status`) sem modo para ver o estado efetivo atual do modo rápido.
- OpenClaw resolve o modo rápido nesta ordem:
- O OpenClaw resolve o modo rápido nesta ordem:
1. `/fast on|off` inline/somente diretiva
2. Substituição da sessão
3. Padrão por agente (`agents.list[].fastModeDefault`)
4. Configuração por modelo: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Para `openai/*`, o modo rápido é mapeado para processamento prioritário OpenAI enviando `service_tier=priority` em solicitações Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Responses do Codex. OpenClaw mantém uma alternância `/fast` compartilhada entre os dois caminhos de autenticação.
- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido é mapeado para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `openai/*`, o modo rápido mapeia para processamento prioritário da OpenAI enviando `service_tier=priority` em solicitações Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia o mesmo sinalizador `service_tier=priority` em Codex Responses. O OpenClaw mantém uma alternância `/fast` compartilhada entre os dois caminhos de autenticação.
- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido mapeia para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `minimax/*` no caminho compatível com Anthropic, `/fast on` (ou `params.fastMode: true`) reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`.
- Parâmetros de modelo Anthropic explícitos `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos são definidos. OpenClaw ainda ignora a injeção de nível de serviço Anthropic para URLs base de proxy que não são Anthropic.
- `/status` mostra `Fast` somente quando o modo rápido está ativado.
- Parâmetros de modelo Anthropic explícitos `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos estão definidos. O OpenClaw ainda ignora a injeção de nível de serviço Anthropic para URLs base de proxy não Anthropic.
- `/status` mostra `Fast` apenas quando o modo rápido está ativado.
## Diretivas detalhadas (/verbose ou /v)
## Diretivas verbosas (/verbose ou /v)
- Níveis: `on` (mínimo) | `full` | `off` (padrão).
- Mensagem contendo apenas diretiva alterna o modo detalhado da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- Mensagem somente com diretiva alterna o modo verboso da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela UI de Sessões escolhendo `inherit`.
- Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam nos demais casos.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível detalhado atual.
- Quando o modo detalhado está ativado, agentes que emitem resultados de ferramenta estruturados (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, prefixada com `<emoji> <tool-name>: <arg>` quando disponível (caminho/comando). Esses resumos de ferramenta são enviados assim que cada ferramenta começa (balões separados), não como deltas de streaming.
- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos de detalhe de erro bruto ficam ocultos, a menos que o modo detalhado seja `on` ou `full`.
- Quando o modo detalhado é `full`, as saídas de ferramenta também são encaminhadas após a conclusão (balão separado, truncado para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução está em andamento, os balões de ferramenta subsequentes respeitarão a nova configuração.
- Diretiva inline afeta apenas essa mensagem; padrões de sessão/globais se aplicam caso contrário.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível verboso atual.
- Quando o modo verboso está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, prefixada com `<emoji> <tool-name>: <arg>` quando disponível. Esses resumos de ferramentas são enviados assim que cada ferramenta inicia (bolhas separadas), não como deltas de streaming.
- Resumos de falhas de ferramentas permanecem visíveis no modo normal, mas sufixos com detalhes de erro brutos ficam ocultos, a menos que o modo verboso esteja `on` ou `full`.
- Quando o modo verboso está `full`, as saídas de ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramentas subsequentes respeitarão a nova configuração.
- `agents.defaults.toolProgressDetail` controla o formato dos resumos de ferramentas de `/verbose` e das linhas de ferramenta de rascunho de progresso. Use `"explain"` (padrão) para rótulos humanos compactos, como `🛠️ Exec: checking JS syntax`; use `"raw"` quando também quiser o comando/detalhe bruto anexado para depuração. `agents.list[].toolProgressDetail` por agente substitui o padrão.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Diretivas de rastreamento de Plugin (/trace)
- Níveis: `on` | `off` (padrão).
- Mensagem contendo apenas diretiva alterna a saída de rastreamento de Plugin da sessão e responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam nos demais casos.
- Mensagem somente com diretiva alterna a saída de rastreamento de Plugin da sessão e responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- Diretiva inline afeta apenas essa mensagem; padrões de sessão/globais se aplicam caso contrário.
- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível de rastreamento atual.
- `/trace` é mais estreito que `/verbose`: expõe apenas linhas de rastreamento/depuração pertencentes a plugins, como resumos de depuração de Active Memory.
- `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de rastreamento/depuração pertencentes ao Plugin, como resumos de depuração do Active Memory.
- Linhas de rastreamento podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
## Visibilidade de raciocínio (/reasoning)
## Visibilidade do raciocínio (/reasoning)
- Níveis: `on|off|stream`.
- Mensagem contendo apenas diretiva alterna se blocos de raciocínio são mostrados nas respostas.
- Mensagem somente com diretiva alterna se blocos de pensamento são mostrados nas respostas.
- Quando ativado, o raciocínio é enviado como uma **mensagem separada** prefixada com `Reasoning:`.
- `stream` (somente Telegram): transmite o raciocínio para o balão de rascunho do Telegram enquanto a resposta está sendo gerada e depois envia a resposta final sem raciocínio.
- `stream` (somente Telegram): transmite o raciocínio para a bolha de rascunho do Telegram enquanto a resposta está sendo gerada e, em seguida, envia a resposta final sem raciocínio.
- Alias: `/reason`.
- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível de raciocínio atual.
- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`).
Tags de raciocínio de modelo local malformadas são tratadas de forma conservadora. Blocos fechados `<think>...</think>` permanecem ocultos em respostas normais, e raciocínio não fechado após texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e, de outra forma, seria entregue como texto vazio, OpenClaw remove a tag de abertura malformada e entrega o texto restante.
Tags de raciocínio de modelo local malformadas são tratadas de forma conservadora. Blocos fechados `<think>...</think>` permanecem ocultos em respostas normais, e raciocínio não fechado após texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e, caso contrário, fosse entregue como texto vazio, o OpenClaw remove a tag de abertura malformada e entrega o texto restante.
## Relacionado
@ -118,23 +121,23 @@ Tags de raciocínio de modelo local malformadas são tratadas de forma conservad
## Heartbeats
- O corpo da sonda de Heartbeat é o prompt de Heartbeat configurado (padrão: `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.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats).
- A entrega de Heartbeat usa por padrão apenas o payload final. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
- O corpo da sondagem de Heartbeat é o prompt de Heartbeat configurado (padrão: `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.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de heartbeats).
- A entrega de Heartbeat usa por padrão apenas a carga útil final. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
## UI de chat web
- O seletor de raciocínio do chat web espelha o nível armazenado da sessão a partir do repositório/configuração da sessão de entrada quando a página carrega.
- Selecionar outro nível grava a substituição da sessão imediatamente via `sessions.patch`; ele não espera o próximo envio e não é uma substituição única `thinkingOnce`.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do perfil de raciocínio do provedor do modelo da sessão ativa mais a mesma lógica de fallback que `/status` e `session_status` usam.
- O seletor usa `thinkingLevels` retornado pela linha/padrões da sessão do Gateway, com `thinkingOptions` mantido como uma lista legada de rótulos. A UI do navegador não mantém sua própria lista de regex de provedor; plugins possuem conjuntos de níveis específicos de modelo.
- O seletor de pensamento do chat web espelha o nível armazenado da sessão a partir do armazenamento/configuração da sessão recebida quando a página carrega.
- Escolher outro nível grava a substituição da sessão imediatamente via `sessions.patch`; ele não espera o próximo envio e não é uma substituição única `thinkingOnce`.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do perfil de pensamento do provedor do modelo da sessão ativa mais a mesma lógica de fallback usada por `/status` e `session_status`.
- O seletor usa `thinkingLevels` retornado pela linha/padrões da sessão do Gateway, com `thinkingOptions` mantido como uma lista legada de rótulos. A UI do navegador não mantém sua própria lista de regex de provedores; Plugins são donos dos conjuntos de níveis específicos de modelo.
- `/think:<level>` ainda funciona e atualiza o mesmo nível de sessão armazenado, então diretivas de chat e o seletor permanecem sincronizados.
## Perfis de provedor
- Plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis do modelo e o padrão.
- Plugins de provedor que fazem proxy de modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos diretos da Anthropic e os catálogos de proxy permaneçam alinhados.
- Plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis e o padrão do modelo.
- Plugins de provedor que fazem proxy de modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos diretos da Anthropic e de proxy permaneçam alinhados.
- Cada nível de perfil tem um `id` canônico armazenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) e pode incluir um `label` de exibição. Provedores binários usam `{ id: "low", label: "on" }`.
- Plugins de ferramenta que precisam validar uma substituição explícita de raciocínio devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` junto com `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis por provedor/modelo.
- Plugins de ferramenta com acesso a metadados configurados de modelos personalizados podem passar `catalog` para `resolveThinkingPolicy` para que adesões de `compat.supportedReasoningEfforts` sejam refletidas na validação do lado do Plugin.
- Plugins de ferramenta que precisam validar uma substituição explícita de raciocínio devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` mais `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis por provedor/modelo.
- Plugins de ferramenta com acesso a metadados configurados de modelos personalizados podem passar `catalog` para `resolveThinkingPolicy` para que adesões a `compat.supportedReasoningEfforts` sejam refletidas na validação do lado do Plugin.
- Hooks legados publicados (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) permanecem como adaptadores de compatibilidade, mas novos conjuntos de níveis personalizados devem usar `resolveThinkingProfile`.
- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes ACP/chat renderizem os mesmos ids e rótulos de perfil que a validação em tempo de execução usa.

69
docs/pt-BR/tools/web-fetch.md
View File

@ -2,15 +2,15 @@
read_when:
- Você quer buscar uma URL e extrair conteúdo legível
- Você precisa configurar web_fetch ou sua alternativa Firecrawl
- Você quer entender os limites e o cache de web_fetch
- Você quer entender os limites e o armazenamento em cache do web_fetch
sidebarTitle: Web Fetch
summary: ferramenta web_fetch -- busca HTTP com extração de conteúdo legível
title: Busca na web
title: Busca na Web
x-i18n:
generated_at: "2026-05-02T05:58:49Z"
generated_at: "2026-05-04T05:56:18Z"
model: gpt-5.5
provider: openai
source_hash: f455da77c20049f0ed0246fa53e9f49d3cf2004e65bd64a0bf871861c6e93229
source_hash: c8c3efbf4a640b2fd69cc9532dcb06a873a6830a2e8a85ab7510ab38207c8670
source_path: tools/web-fetch.md
workflow: 16
---
@ -23,8 +23,8 @@ Para sites com muito JS ou páginas protegidas por login, use o
## Início rápido
`web_fetch` é **ativado por padrão** -- nenhuma configuração é necessária. O agente pode
chamá-lo imediatamente:
`web_fetch` vem **habilitada por padrão** -- nenhuma configuração é necessária. O agente pode
chamá-la imediatamente:
```javascript
await web_fetch({ url: "https://example.com/article" });
@ -33,7 +33,7 @@ await web_fetch({ url: "https://example.com/article" });
## Parâmetros da ferramenta
<ParamField path="url" type="string" required>
URL a buscar. Apenas `http(s)`.
URL a buscar. Somente `http(s)`.
</ParamField>
<ParamField path="extractMode" type="'markdown' | 'text'" default="markdown">
@ -48,7 +48,7 @@ Trunca a saída para esta quantidade de caracteres.
<Steps>
<Step title="Buscar">
Envia um HTTP GET com um User-Agent semelhante ao Chrome e cabeçalho
Envia um HTTP GET com um User-Agent semelhante ao Chrome e o cabeçalho
`Accept-Language`. Bloqueia nomes de host privados/internos e verifica redirecionamentos novamente.
</Step>
<Step title="Extrair">
@ -79,6 +79,7 @@ Trunca a saída para esta quantidade de caracteres.
timeoutSeconds: 30,
cacheTtlMinutes: 15,
maxRedirects: 3,
useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS
readability: true, // use Readability extraction
userAgent: "Mozilla/5.0 ...", // override User-Agent
ssrfPolicy: {
@ -93,8 +94,8 @@ Trunca a saída para esta quantidade de caracteres.
## Fallback do Firecrawl
Se a extração do Readability falhar, `web_fetch` pode usar
[Firecrawl](/pt-BR/tools/firecrawl) como fallback para contorno de bots e melhor extração:
Se a extração do Readability falhar, `web_fetch` pode recorrer ao
[Firecrawl](/pt-BR/tools/firecrawl) para contorno de bots e melhor extração:
```json5
{
@ -128,26 +129,42 @@ Se a extração do Readability falhar, `web_fetch` pode usar
A configuração legada `tools.web.fetch.firecrawl.*` é migrada automaticamente por `openclaw doctor --fix`.
<Note>
Se Firecrawl estiver ativado e seu SecretRef não for resolvido sem fallback da variável de ambiente
Se o Firecrawl estiver habilitado e seu SecretRef não for resolvido sem fallback da variável de ambiente
`FIRECRAWL_API_KEY`, a inicialização do Gateway falha rapidamente.
</Note>
<Note>
Sobrescritas de `baseUrl` do Firecrawl são restritas: tráfego hospedado usa
`https://api.firecrawl.dev`; sobrescritas auto-hospedadas devem apontar para endpoints privados ou
Substituições de `baseUrl` do Firecrawl são restritas: tráfego hospedado usa
`https://api.firecrawl.dev`; substituições auto-hospedadas devem apontar para endpoints privados ou
internos, e `http://` é aceito apenas para esses destinos privados.
</Note>
Comportamento atual em tempo de execução:
- `tools.web.fetch.provider` seleciona explicitamente o provedor de fallback de busca.
- Se `provider` for omitido, OpenClaw detecta automaticamente o primeiro provedor de web-fetch
- Se `provider` for omitido, o OpenClaw detecta automaticamente o primeiro provedor de web-fetch
pronto a partir das credenciais disponíveis. `web_fetch` sem sandbox pode usar
plugins instalados que declaram `contracts.webFetchProviders` e registram um
provedor correspondente em tempo de execução. Hoje, o provedor incluído é Firecrawl.
- Chamadas `web_fetch` em sandbox permanecem limitadas aos provedores incluídos.
- Se Readability estiver desativado, `web_fetch` vai direto para o fallback do
provedor selecionado. Se nenhum provedor estiver disponível, ele falha fechado.
provedor correspondente em tempo de execução. Hoje, o provedor incluído é o Firecrawl.
- Chamadas `web_fetch` em sandbox permanecem limitadas a provedores incluídos.
- Se Readability estiver desabilitado, `web_fetch` pula direto para o fallback do
provedor selecionado. Se nenhum provedor estiver disponível, ela falha fechada.
## Proxy de ambiente confiável
Se sua implantação exigir que `web_fetch` passe por um proxy de saída
HTTP(S) confiável, defina `tools.web.fetch.useTrustedEnvProxy: true`.
Nesse modo, o OpenClaw ainda aplica verificações SSRF baseadas em nome de host antes de enviar
a solicitação, mas permite que o proxy resolva DNS em vez de fazer fixação de DNS
local. Habilite isso apenas quando o proxy for controlado pelo operador e aplicar
política de saída após a resolução de DNS.
<Note>
Se nenhuma variável de ambiente de proxy HTTP(S) estiver configurada, ou se o host de destino for excluído por
`NO_PROXY`, `web_fetch` volta para o caminho estrito normal com fixação de DNS
local.
</Note>
## Limites e segurança
@ -156,15 +173,17 @@ Comportamento atual em tempo de execução:
são truncadas com um aviso
- Nomes de host privados/internos são bloqueados
- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` e
`tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` são permissões opt-in restritas
para pilhas de proxy de IP falso confiáveis; deixe-os indefinidos a menos que seu proxy possua
`tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` são opções de adesão restritas
para pilhas de proxy de IP falso confiáveis; deixe-as indefinidas a menos que seu proxy controle
esses intervalos sintéticos e aplique sua própria política de destino
- Redirecionamentos são verificados e limitados por `maxRedirects`
- `web_fetch` funciona em regime de melhor esforço -- alguns sites precisam do [Navegador Web](/pt-BR/tools/browser)
- `useTrustedEnvProxy` é uma adesão explícita e deve ser habilitada apenas para
proxies controlados pelo operador que ainda apliquem política de saída após a resolução de DNS
- `web_fetch` funciona por melhor esforço -- alguns sites precisam do [Navegador Web](/pt-BR/tools/browser)
## Perfis de ferramentas
Se você usa perfis de ferramentas ou listas de permissão, adicione `web_fetch` ou `group:web`:
Se você usa perfis de ferramentas ou listas de permissões, adicione `web_fetch` ou `group:web`:
```json5
{
@ -177,6 +196,6 @@ Se você usa perfis de ferramentas ou listas de permissão, adicione `web_fetch`
## Relacionados
- [Pesquisa Web](/pt-BR/tools/web) -- pesquise na web com vários provedores
- [Navegador Web](/pt-BR/tools/browser) -- automação completa de navegador para sites com muito JS
- [Firecrawl](/pt-BR/tools/firecrawl) -- ferramentas de pesquisa e raspagem do Firecrawl
- [Busca Web](/pt-BR/tools/web) -- pesquise na web com múltiplos provedores
- [Navegador Web](/pt-BR/tools/browser) -- automação completa do navegador para sites com muito JS
- [Firecrawl](/pt-BR/tools/firecrawl) -- ferramentas de busca e scraping do Firecrawl

263
docs/pt-BR/web/control-ui.md
View File

@ -3,23 +3,23 @@ read_when:
- Você quer operar o Gateway a partir de um navegador
- Você quer acesso à Tailnet sem túneis SSH
sidebarTitle: Control UI
summary: Interface de controle baseada em navegador para o Gateway (bate-papo, nós, configuração)
summary: UI de controle baseada no navegador para o Gateway (chat, nós, configuração)
title: Interface de controle
x-i18n:
generated_at: "2026-05-02T21:07:05Z"
generated_at: "2026-05-04T05:56:07Z"
model: gpt-5.5
provider: openai
source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c
source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644
source_path: web/control-ui.md
workflow: 16
---
A UI de Controle é um pequeno app de página única **Vite + Lit** servido pelo Gateway:
A Interface de Controle é um pequeno aplicativo de página única **Vite + Lit** servido pelo Gateway:
- padrão: `http://<host>:18789/`
- prefixo opcional: defina `gateway.controlUi.basePath` (por exemplo, `/openclaw`)
Ela fala **diretamente com o Gateway WebSocket** na mesma porta.
Ela se comunica **diretamente com o WebSocket do Gateway** na mesma porta.
## Abertura rápida (local)
@ -29,124 +29,124 @@ Se o Gateway estiver em execução no mesmo computador, abra:
Se a página não carregar, inicie o Gateway primeiro: `openclaw gateway`.
A autenticação é fornecida durante o handshake do WebSocket via:
A autenticação é fornecida durante o handshake do WebSocket por meio de:
- `connect.params.auth.token`
- `connect.params.auth.password`
- cabeçalhos de identidade do Tailscale Serve quando `gateway.auth.allowTailscale: true`
- cabeçalhos de identidade de proxy confiável quando `gateway.auth.mode: "trusted-proxy"`
O painel de configurações do dashboard mantém um token para a sessão atual da aba do navegador e a URL do gateway selecionado; senhas não são persistidas. O onboarding geralmente gera um token de gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando `gateway.auth.mode` é `"password"`.
O painel de configurações do dashboard mantém um token para a sessão atual da aba do navegador e a URL do gateway selecionada; senhas não são persistidas. A integração inicial normalmente gera um token de gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando `gateway.auth.mode` é `"password"`.
## Pareamento de dispositivo (primeira conexão)
Quando você se conecta à UI de Controle por um novo navegador ou dispositivo, o Gateway geralmente exige uma **aprovação de pareamento única**. Essa é uma medida de segurança para impedir acesso não autorizado.
Quando você se conecta à Interface de Controle a partir de um novo navegador ou dispositivo, o Gateway geralmente exige uma **aprovação de pareamento única**. Esta é uma medida de segurança para impedir acesso não autorizado.
**O que você verá:** "desconectado (1008): pareamento necessário"
<Steps>
<Step title="Listar solicitações pendentes">
<Step title="Liste as solicitações pendentes">
```bash
openclaw devices list
```
</Step>
<Step title="Aprovar por ID da solicitação">
<Step title="Aprove pelo ID da solicitação">
```bash
openclaw devices approve <requestId>
```
</Step>
</Steps>
Se o navegador tentar parear novamente com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo `requestId` será criado. Execute `openclaw devices list` novamente antes da aprovação.
Se o navegador tentar novamente o pareamento com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo `requestId` será criado. Execute `openclaw devices list` novamente antes da aprovação.
Se o navegador já estiver pareado e você alterá-lo de acesso de leitura para acesso de escrita/administração, isso será tratado como uma atualização de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e solicita que você aprove explicitamente o novo conjunto de escopos.
Se o navegador já estiver pareado e você alterá-lo de acesso de leitura para acesso de escrita/administrador, isso será tratado como uma atualização de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e solicita que você aprove explicitamente o novo conjunto de escopos.
Depois de aprovado, o dispositivo é lembrado e não exigirá nova aprovação, a menos que você o revogue com `openclaw devices revoke --device <id> --role <role>`. Consulte [CLI de dispositivos](/pt-BR/cli/devices) para rotação e revogação de tokens.
Depois de aprovado, o dispositivo é lembrado e não exigirá nova aprovação, a menos que você o revogue com `openclaw devices revoke --device <id> --role <role>`. Consulte [CLI de Dispositivos](/pt-BR/cli/devices) para rotação e revogação de tokens.
<Note>
- Conexões diretas de navegador por local loopback (`127.0.0.1` / `localhost`) são aprovadas automaticamente.
- O Tailscale Serve pode pular a rodada de pareamento para sessões de operador da UI de Controle quando `gateway.auth.allowTailscale: true`, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo.
- Vinculações diretas de Tailnet, conexões de navegador pela LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita.
- Cada perfil de navegador gera um ID de dispositivo exclusivo, portanto trocar de navegador ou limpar dados do navegador exigirá novo pareamento.
- O Tailscale Serve pode pular a etapa de pareamento para sessões de operador da Interface de Controle quando `gateway.auth.allowTailscale: true`, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo.
- Vinculações diretas à Tailnet, conexões de navegador pela LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita.
- Cada perfil de navegador gera um ID de dispositivo único, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento.
</Note>
## Identidade pessoal (local do navegador)
A UI de Controle oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada a mensagens enviadas para atribuição em sessões compartilhadas. Ela fica no armazenamento do navegador, é limitada ao perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no lado do servidor além dos metadados normais de autoria da transcrição nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador a redefine para vazio.
A Interface de Controle oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada às mensagens enviadas para atribuição em sessões compartilhadas. Ela fica no armazenamento do navegador, é limitada ao perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no servidor além dos metadados normais de autoria da transcrição nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador redefine essa identidade para vazia.
O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway somente no navegador local e nunca fazem ida e volta por `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes não UI que escrevem o campo diretamente (como gateways com scripts ou dashboards personalizados).
O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway apenas no navegador local e nunca passam por ida e volta via `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes não UI que escrevem o campo diretamente (como gateways com scripts ou dashboards personalizados).
## Endpoint de configuração de runtime
A UI de Controle busca suas configurações de runtime em `/__openclaw/control-ui-config.json`. Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou identidade de proxy confiável.
A Interface de Controle busca suas configurações de runtime em `/__openclaw/control-ui-config.json`. Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou identidade de proxy confiável.
## Suporte a idiomas
A UI de Controle pode se localizar no primeiro carregamento com base no idioma do seu navegador. Para substituí-lo depois, abra **Visão geral -> Acesso ao Gateway -> Idioma**. O seletor de localidade fica no cartão Acesso ao Gateway, não em Aparência.
A Interface de Controle pode se localizar automaticamente no primeiro carregamento com base na localidade do seu navegador. Para substituí-la depois, abra **Visão geral -> Acesso ao Gateway -> Idioma**. O seletor de localidade fica no cartão Acesso ao Gateway, não em Aparência.
- Localidades compatíveis: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
- Traduções fora do inglês são carregadas sob demanda no navegador.
- Traduções para idiomas não ingleses são carregadas sob demanda no navegador.
- A localidade selecionada é salva no armazenamento do navegador e reutilizada em visitas futuras.
- Chaves de tradução ausentes usam o inglês como fallback.
- Chaves de tradução ausentes recorrem ao inglês.
As traduções da documentação são geradas para o mesmo conjunto de localidades fora do inglês, mas o seletor de idioma integrado do site de documentação da Mintlify é limitado aos códigos de localidade aceitos pela Mintlify. A documentação em tailandês (`th`) e persa (`fa`) ainda é gerada no repositório de publicação; ela pode não aparecer nesse seletor até que a Mintlify ofereça suporte a esses códigos.
As traduções da documentação são geradas para o mesmo conjunto de localidades não inglesas, mas o seletor de idioma integrado do site de docs do Mintlify é limitado aos códigos de localidade aceitos pelo Mintlify. A documentação em tailandês (`th`) e persa (`fa`) ainda é gerada no repositório de publicação; ela pode não aparecer nesse seletor até que o Mintlify ofereça suporte a esses códigos.
## Temas de aparência
O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra [temas tweakcn](https://tweakcn.com/themes), escolha ou crie um tema, clique em **Compartilhar** e cole o link do tema copiado em Aparência. O importador também aceita URLs de registro `https://tweakcn.com/r/themes/<id>`, URLs do editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, caminhos relativos `/themes/<id>`, IDs brutos de tema e nomes de temas padrão, como `amethyst-haze`.
O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra o [editor tweakcn](https://tweakcn.com/editor/theme), escolha ou crie um tema, clique em **Compartilhar** e cole o link de tema copiado em Aparência. O importador também aceita URLs de registro `https://tweakcn.com/r/themes/<id>`, URLs do editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, caminhos relativos `/themes/<id>`, IDs de tema brutos e nomes de tema padrão como `amethyst-haze`.
Temas importados são armazenados somente no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo muda o tema ativo de volta para Claw se o tema importado estava selecionado.
Temas importados são armazenados apenas no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo muda o tema ativo de volta para Claw se o tema importado estava selecionado.
## O que ela pode fazer (hoje)
## O que ele pode fazer (hoje)
<AccordionGroup>
<Accordion title="Chat e Conversa">
- Converse com o modelo via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- Fale por meio de sessões em tempo real do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token restrito de uso único do navegador via WebSocket, e plugins de voz em tempo real apenas de backend usam o transporte de retransmissão do Gateway. A retransmissão mantém credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por RPCs `talk.realtime.relay*` e envia chamadas de ferramenta `openclaw_agent_consult` de volta por `chat.send` para o modelo OpenClaw maior configurado.
- Transmita chamadas de ferramenta + cartões de saída de ferramenta em tempo real no Chat (eventos de agente).
- Converse por chat com o modelo via WS do Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- Converse por sessões realtime do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador limitado a um único uso via WebSocket, e plugins de voz realtime somente de backend usam o transporte de relay do Gateway. O relay mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por RPCs `talk.realtime.relay*` e envia chamadas de ferramenta `openclaw_agent_consult` de volta por `chat.send` para o modelo OpenClaw maior configurado.
- Transmita chamadas de ferramentas + cartões de saída de ferramenta ao vivo no Chat (eventos de agente).
</Accordion>
<Accordion title="Canais, instâncias, sessões, dreams">
- Canais: status de canais integrados e de plugin agrupados/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`).
- Canais: status de canais integrados e de canais de plugins incluídos/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`).
- Instâncias: lista de presença + atualização (`system-presence`).
- Sessões: lista + substituições por sessão de modelo/thinking/fast/verbose/trace/reasoning (`sessions.list`, `sessions.patch`).
- Sessões: lista + substituições por sessão de modelo/thinking/rápido/detalhado/rastreamento/raciocínio (`sessions.list`, `sessions.patch`).
- Dreams: status de dreaming, alternância de ativar/desativar e leitor do Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
</Accordion>
<Accordion title="Cron, Skills, Nodes, aprovações de exec">
- Trabalhos Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execução (`cron.*`).
<Accordion title="Cron, skills, nodes, aprovações de exec">
- Tarefas Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execução (`cron.*`).
- Skills: status, ativar/desativar, instalar, atualizações de chave de API (`skills.*`).
- Nodes: lista + capacidades (`node.list`).
- Aprovações de exec: edite allowlists do gateway ou Node + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`).
- Aprovações de exec: editar allowlists de gateway ou node + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`).
</Accordion>
<Accordion title="Configuração">
- Visualize/edite `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
- Aplique + reinicie com validação (`config.apply`) e desperte a última sessão ativa.
- Escritas incluem uma proteção de hash base para evitar sobrescrever edições simultâneas.
- Escritas (`config.set`/`config.apply`/`config.patch`) fazem preflight da resolução ativa de SecretRef para refs no payload de configuração enviado; refs ativas enviadas não resolvidas são rejeitadas antes da escrita.
- Schema + renderização de formulário (`config.schema` / `config.schema.lookup`, incluindo `title` / `description` do campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de documentação em nós aninhados de objeto/wildcard/array/composição, além de schemas de plugin + canal quando disponíveis); o editor JSON bruto fica disponível somente quando o snapshot tem uma ida e volta bruta segura.
- Se um snapshot não puder fazer ida e volta segura do texto bruto, a UI de Controle força o modo Formulário e desativa o modo Bruto para esse snapshot.
- O editor JSON bruto "Redefinir para salvo" preserva a forma criada no bruto (formatação, comentários, layout de `$include`) em vez de renderizar novamente um snapshot achatado, para que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança.
- Valores de objeto SecretRef estruturados são renderizados como somente leitura em entradas de texto de formulário para evitar corrupção acidental de objeto para string.
- Gravações incluem uma proteção por hash base para evitar sobrescrever edições concorrentes.
- Gravações (`config.set`/`config.apply`/`config.patch`) fazem uma pré-verificação da resolução de SecretRef ativa para refs no payload de configuração enviado; refs enviadas ativas não resolvidas são rejeitadas antes da gravação.
- Esquema + renderização de formulário (`config.schema` / `config.schema.lookup`, incluindo `title` / `description` de campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de docs em nós aninhados de objeto/curinga/array/composição, além de esquemas de plugin + canal quando disponíveis); o editor JSON bruto fica disponível apenas quando o snapshot tem uma ida e volta bruta segura.
- Se um snapshot não conseguir fazer ida e volta segura do texto bruto, a Interface de Controle força o modo Formulário e desativa o modo Bruto para esse snapshot.
- O editor JSON bruto "Redefinir para salvo" preserva a forma escrita em bruto (formatação, comentários, layout de `$include`) em vez de renderizar novamente um snapshot achatado, para que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança.
- Valores estruturados de objeto SecretRef são renderizados como somente leitura em entradas de texto de formulário para evitar corrupção acidental de objeto para string.
</Accordion>
<Accordion title="Depuração, logs, atualização">
- Depuração: snapshots de status/saúde/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`).
- Logs: acompanhamento ao vivo dos logs de arquivo do gateway com filtro/exportação (`logs.tail`).
- Atualização: execute uma atualização de pacote/git + reinicie (`update.run`) com um relatório de reinicialização e, em seguida, consulte `update.status` após reconectar para verificar a versão do gateway em execução.
- Depuração: snapshots de status/health/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`).
- Logs: tail ao vivo dos logs de arquivo do gateway com filtro/exportação (`logs.tail`).
- Atualização: execute uma atualização de pacote/git + reinício (`update.run`) com um relatório de reinício e, em seguida, consulte `update.status` após a reconexão para verificar a versão do gateway em execução.
</Accordion>
<Accordion title="Observações do painel de trabalhos Cron">
- Para trabalhos isolados, a entrega usa por padrão anúncio de resumo. Você pode mudar para nenhum se quiser execuções apenas internas.
- Campos de canal/destino aparecem quando anúncio está selecionado.
<Accordion title="Observações do painel de tarefas Cron">
- Para tarefas isoladas, a entrega usa anúncio de resumo por padrão. Você pode mudar para nenhuma se quiser execuções apenas internas.
- Campos de canal/destino aparecem quando anúncio é selecionado.
- O modo Webhook usa `delivery.mode = "webhook"` com `delivery.to` definido como uma URL de webhook HTTP(S) válida.
- Para trabalhos da sessão principal, os modos de entrega webhook e nenhum estão disponíveis.
- Controles de edição avançada incluem excluir após execução, limpar substituição de agente, opções de cron exato/escalonado, substituições de modelo/thinking de agente e alternâncias de entrega por melhor esforço.
- A validação de formulário é inline, com erros em nível de campo; valores inválidos desativam o botão de salvar até serem corrigidos.
- Para tarefas da sessão principal, os modos de entrega webhook e nenhuma ficam disponíveis.
- Controles avançados de edição incluem excluir após execução, limpar substituição de agente, opções cron exato/escalonado, substituições de modelo/thinking do agente e alternâncias de entrega por melhor esforço.
- A validação de formulário é inline com erros por campo; valores inválidos desativam o botão de salvar até serem corrigidos.
- Defina `cron.webhookToken` para enviar um token bearer dedicado; se omitido, o webhook é enviado sem cabeçalho de autenticação.
- Fallback obsoleto: trabalhos legados armazenados com `notify: true` ainda podem usar `cron.webhook` até serem migrados.
- Fallback obsoleto: tarefas legadas armazenadas com `notify: true` ainda podem usar `cron.webhook` até serem migradas.
</Accordion>
</AccordionGroup>
@ -156,60 +156,61 @@ Temas importados são armazenados somente no perfil atual do navegador. Eles nã
<AccordionGroup>
<Accordion title="Semântica de envio e histórico">
- `chat.send` é **não bloqueante**: confirma imediatamente com `{ runId, status: "started" }` e a resposta é transmitida por eventos `chat`.
- Envios de chat aceitam imagens mais arquivos que não sejam vídeo. Imagens mantêm o caminho de imagem nativo; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo.
- Reenviar com a mesma `idempotencyKey` retorna `{ status: "in_flight" }` enquanto estiver em execução, e `{ status: "ok" }` após a conclusão.
- Respostas de `chat.history` têm limite de tamanho para segurança da UI. Quando as entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um placeholder (`[chat.history omitted: message too large]`).
- Imagens do assistente/geradas são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, portanto recarregamentos não dependem de payloads de imagem base64 brutos permanecerem na resposta do histórico do chat.
- `chat.history` também remove tags de diretiva inline apenas de exibição do texto visível do assistente (por exemplo `[[reply_to_*]]` e `[[audio_as_voice]]`), payloads XML de chamada de ferramenta em texto puro (incluindo `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocos truncados de chamada de ferramenta), e tokens vazados de controle do modelo em ASCII/largura completa, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato `NO_REPLY` / `no_reply`.
- Durante um envio ativo e a atualização final do histórico, a visualização do chat mantém mensagens locais otimistas do usuário/assistente visíveis se `chat.history` retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway alcança o estado atual.
- `chat.inject` acrescenta uma nota do assistente à transcrição da sessão e transmite um evento `chat` para atualizações somente da UI (sem execução do agente, sem entrega de canal).
- Os seletores de modelo e pensamento do cabeçalho do chat corrigem a sessão ativa imediatamente por meio de `sessions.patch`; eles são substituições persistentes de sessão, não opções de envio válidas apenas para um turno.
- Digitar `/new` na Control UI cria e alterna para a mesma sessão nova do dashboard que New Chat. Digitar `/reset` mantém a redefinição explícita no local do Gateway para a sessão atual.
- O seletor de modelo do chat solicita a visualização de modelos configurada do Gateway. Se `agents.defaults.models` estiver presente, essa lista de permissões controla o seletor. Caso contrário, o seletor mostra entradas explícitas de `models.providers.*.models` mais provedores com autenticação utilizável. O catálogo completo permanece disponível por meio do RPC de depuração `models.list` com `view: "all"`.
- Quando relatórios recentes de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor do chat mostra um aviso de contexto e, nos níveis recomendados de Compaction, um botão compacto que executa o caminho normal de Compaction da sessão. Snapshots de tokens obsoletos ficam ocultos até que o Gateway relate uso recente novamente.
- Uploads de chat aceitam imagens e arquivos que não sejam vídeo. Imagens mantêm o caminho nativo da imagem; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo.
- Reenviar com o mesmo `idempotencyKey` retorna `{ status: "in_flight" }` enquanto estiver em execução, e `{ status: "ok" }` após a conclusão.
- As respostas de `chat.history` têm limite de tamanho para segurança da UI. Quando as entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um placeholder (`[chat.history omitted: message too large]`).
- Imagens geradas/pelo assistente são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, então recarregamentos não dependem de payloads brutos de imagem em base64 permanecerem na resposta do histórico do chat.
- `chat.history` também remove tags de diretivas inline somente de exibição do texto visível do assistente (por exemplo `[[reply_to_*]]` e `[[audio_as_voice]]`), payloads XML de chamadas de ferramenta em texto simples (incluindo `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocos truncados de chamadas de ferramenta), e tokens de controle de modelo ASCII/largura total vazados, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato `NO_REPLY` / `no_reply`.
- Durante um envio ativo e a atualização final do histórico, a visualização de chat mantém mensagens locais otimistas do usuário/assistente visíveis se `chat.history` retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway alcança o estado atual.
- Eventos `chat` ao vivo representam estado de entrega, enquanto `chat.history` é reconstruído a partir da transcrição durável da sessão. Após eventos finais de ferramenta, a Control UI recarrega o histórico e mescla apenas uma pequena cauda otimista; o limite da transcrição está documentado em [WebChat](/pt-BR/web/webchat).
- `chat.inject` anexa uma nota do assistente à transcrição da sessão e transmite um evento `chat` para atualizações somente da UI (sem execução do agente, sem entrega de canal).
- Os seletores de modelo e pensamento do cabeçalho do chat aplicam patches imediatamente na sessão ativa por meio de `sessions.patch`; eles são sobrescritas persistentes de sessão, não opções de envio válidas apenas para uma rodada.
- Digitar `/new` na Control UI cria e alterna para a mesma sessão nova de dashboard que Novo Chat. Digitar `/reset` mantém a redefinição explícita in-place do Gateway para a sessão atual.
- O seletor de modelo do chat solicita a visualização de modelos configurada do Gateway. Se `agents.defaults.models` estiver presente, essa lista de permissões orienta o seletor. Caso contrário, o seletor mostra entradas explícitas de `models.providers.*.models` e provedores com autenticação utilizável. O catálogo completo permanece disponível pelo RPC de depuração `models.list` com `view: "all"`.
- Quando relatórios novos de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor de chat mostra um aviso de contexto e, em níveis recomendados de compaction, um botão compacto que executa o caminho normal de compaction da sessão. Snapshots obsoletos de tokens ficam ocultos até o Gateway relatar uso novo novamente.
</Accordion>
<Accordion title="Modo de fala (tempo real no navegador)">
O modo de fala usa um provedor de voz em tempo real registrado. Configure OpenAI com `talk.provider: "openai"` mais `talk.providers.openai.apiKey`, ou configure Google com `talk.provider: "google"` mais `talk.providers.google.apiKey`; a configuração do provedor em tempo real de chamada de voz ainda pode ser reutilizada como fallback. O navegador nunca recebe uma chave de API padrão do provedor. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação de Live API restrito e de uso único para uma sessão WebSocket no navegador, com instruções e declarações de ferramentas bloqueadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de retransmissão do Gateway, de modo que credenciais e sockets de fornecedores permanecem no servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; `talk.realtime.session` não aceita substituições de instrução fornecidas pelo chamador.
<Accordion title="Modo de conversa (tempo real no navegador)">
O modo de conversa usa um provedor de voz em tempo real registrado. Configure a OpenAI com `talk.provider: "openai"` mais `talk.providers.openai.apiKey`, ou configure o Google com `talk.provider: "google"` mais `talk.providers.google.apiKey`; a configuração do provedor em tempo real de Chamada de Voz ainda pode ser reutilizada como fallback. O navegador nunca recebe uma chave de API padrão do provedor. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação Live API restrito de uso único para uma sessão WebSocket do navegador, com instruções e declarações de ferramentas travadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de retransmissão do Gateway, então credenciais e sockets de fornecedores ficam no lado do servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; `talk.realtime.session` não aceita sobrescritas de instrução fornecidas pelo chamador.
No compositor do Chat, o controle de fala é o botão de ondas ao lado do botão de ditado por microfone. Quando a fala começa, a linha de status do compositor mostra `Connecting Talk...`, depois `Talk live` enquanto o áudio está conectado, ou `Asking OpenClaw...` enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por meio de `chat.send`.
No compositor de Chat, o controle de Conversa é o botão de ondas ao lado do botão de ditado por microfone. Quando a Conversa inicia, a linha de status do compositor mostra `Connecting Talk...`, depois `Talk live` enquanto o áudio está conectado, ou `Asking OpenClaw...` enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por meio de `chat.send`.
Smoke ao vivo de mantenedor: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica a troca SDP do WebRTC de navegador da OpenAI, a configuração de WebSocket de navegador com token restrito do Google Live e o adaptador de navegador de retransmissão do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos.
Smoke ao vivo para mantenedores: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica a troca de SDP WebRTC do navegador da OpenAI, a configuração WebSocket do navegador com token restrito do Google Live e o adaptador de navegador de retransmissão do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos.
</Accordion>
<Accordion title="Parar e abortar">
- Clique em **Parar** (chama `chat.abort`).
- Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em **Orientar** em uma mensagem na fila para injetar esse acompanhamento no turno em execução.
- Digite `/stop` (ou frases autônomas de aborto como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora da banda.
- `chat.abort` aceita `{ sessionKey }` (sem `runId`) para abortar todas as execuções ativas dessa sessão.
- Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em **Orientar** em uma mensagem na fila para injetar esse acompanhamento na rodada em execução.
- Digite `/stop` (ou frases independentes de aborto como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora de banda.
- `chat.abort` oferece suporte a `{ sessionKey }` (sem `runId`) para abortar todas as execuções ativas dessa sessão.
</Accordion>
<Accordion title="Retenção parcial ao abortar">
- Quando uma execução é abortada, texto parcial do assistente ainda pode ser mostrado na UI.
<Accordion title="Retenção parcial de aborto">
- Quando uma execução é abortada, o texto parcial do assistente ainda pode ser mostrado na UI.
- O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando há saída em buffer.
- Entradas persistidas incluem metadados de aborto para que consumidores de transcrição possam distinguir parciais abortados da saída de conclusão normal.
- Entradas persistidas incluem metadados de aborto para que consumidores da transcrição consigam distinguir parciais de aborto da saída de conclusão normal.
</Accordion>
</AccordionGroup>
## Instalação como PWA e Web Push
## Instalação PWA e push web
A Control UI inclui um `manifest.webmanifest` e um service worker, então navegadores modernos podem instalá-la como uma PWA autônoma. Web Push permite que o Gateway desperte a PWA instalada com notificações mesmo quando a aba ou a janela do navegador não está aberta.
A Control UI inclui um `manifest.webmanifest` e um service worker, então navegadores modernos podem instalá-la como uma PWA independente. Web Push permite que o Gateway acorde a PWA instalada com notificações mesmo quando a aba ou a janela do navegador não está aberta.
| Superfície | O que faz |
| Superfície | O que faz |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | Manifesto da PWA. Navegadores oferecem "Instalar app" quando ele fica acessível. |
| `ui/public/sw.js` | Service worker que processa eventos `push` e cliques em notificações. |
| `push/vapid-keys.json` (sob o diretório de estado do OpenClaw) | Par de chaves VAPID gerado automaticamente usado para assinar payloads de Web Push. |
| `push/web-push-subscriptions.json` | Endpoints de assinatura do navegador persistidos. |
| `ui/public/manifest.webmanifest` | Manifesto PWA. Navegadores oferecem "Instalar app" quando ele fica acessível. |
| `ui/public/sw.js` | Service worker que trata eventos `push` e cliques em notificações. |
| `push/vapid-keys.json` (sob o diretório de estado do OpenClaw) | Par de chaves VAPID gerado automaticamente usado para assinar payloads Web Push. |
| `push/web-push-subscriptions.json` | Endpoints persistidos de assinatura do navegador. |
Substitua o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes):
Sobrescreva o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes):
- `OPENCLAW_VAPID_PUBLIC_KEY`
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT` (usa `mailto:openclaw@localhost` por padrão)
- `OPENCLAW_VAPID_SUBJECT` (padrão: `mailto:openclaw@localhost`)
A Control UI usa estes métodos do Gateway com escopo restrito para registrar e testar assinaturas do navegador:
A Control UI usa estes métodos do Gateway com escopo limitado para registrar e testar assinaturas do navegador:
- `push.web.vapidPublicKey` — busca a chave pública VAPID ativa.
- `push.web.subscribe` — registra um `endpoint` mais `keys.p256dh`/`keys.auth`.
@ -217,7 +218,7 @@ A Control UI usa estes métodos do Gateway com escopo restrito para registrar e
- `push.web.test` — envia uma notificação de teste para a assinatura do chamador.
<Note>
Web Push é independente do caminho de retransmissão APNS do iOS (veja [Configuração](/pt-BR/gateway/configuration) para push com retransmissão) e do método `push.test` existente, que mira o pareamento móvel nativo.
Web Push é independente do caminho de retransmissão APNS do iOS (veja [Configuração](/pt-BR/gateway/configuration) para push apoiado por retransmissão) e do método `push.test` existente, que mira o pareamento móvel nativo.
</Note>
## Embeds hospedados
@ -228,11 +229,11 @@ Mensagens do assistente podem renderizar conteúdo web hospedado inline com o sh
<Tab title="strict">
Desabilita a execução de scripts dentro de embeds hospedados.
</Tab>
<Tab title="scripts (padrão)">
Permite embeds interativos mantendo isolamento de origem; este é o padrão e normalmente basta para jogos/widgets de navegador autocontidos.
<Tab title="scripts (default)">
Permite embeds interativos enquanto mantém isolamento de origem; este é o padrão e geralmente é suficiente para jogos/widgets de navegador autossuficientes.
</Tab>
<Tab title="trusted">
Adiciona `allow-same-origin` sobre `allow-scripts` para documentos do mesmo site que precisam intencionalmente de privilégios mais fortes.
Adiciona `allow-same-origin` além de `allow-scripts` para documentos do mesmo site que intencionalmente precisam de privilégios mais fortes.
</Tab>
</Tabs>
@ -249,14 +250,14 @@ Exemplo:
```
<Warning>
Use `trusted` somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos e canvases interativos gerados por agentes, `scripts` é a escolha mais segura.
Use `trusted` somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos gerados por agente e canvases interativos, `scripts` é a escolha mais segura.
</Warning>
URLs externas absolutas de embed `http(s)` continuam bloqueadas por padrão. Se você quiser intencionalmente que `[embed url="https://..."]` carregue páginas de terceiros, defina `gateway.controlUi.allowExternalEmbedUrls: true`.
URLs externas absolutas de embed `http(s)` permanecem bloqueadas por padrão. Se você intencionalmente quiser que `[embed url="https://..."]` carregue páginas de terceiros, defina `gateway.controlUi.allowExternalEmbedUrls: true`.
## Largura da mensagem de chat
Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem substituí-la sem corrigir CSS empacotado definindo `gateway.controlUi.chatMessageMaxWidth`:
Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem sobrescrevê-la sem corrigir o CSS empacotado definindo `gateway.controlUi.chatMessageMaxWidth`:
```json5
{
@ -268,13 +269,13 @@ Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implanta
}
```
O valor é validado antes de chegar ao navegador. Valores compatíveis incluem comprimentos simples e porcentagens como `960px` ou `82%`, além de expressões de largura restritas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` e `fit-content(...)`.
O valor é validado antes de chegar ao navegador. Valores com suporte incluem comprimentos simples e porcentagens como `960px` ou `82%`, além de expressões de largura restritas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` e `fit-content(...)`.
## Acesso por tailnet (recomendado)
## Acesso à tailnet (recomendado)
<Tabs>
<Tab title="Tailscale Serve integrado (preferencial)">
Mantenha o Gateway em loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS:
Mantenha o Gateway no loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS:
```bash
openclaw gateway --tailscale serve
@ -284,9 +285,9 @@ O valor é validado antes de chegar ao navegador. Valores compatíveis incluem c
- `https://<magicdns>/` (ou seu `gateway.controlUi.basePath` configurado)
Por padrão, solicitações Serve da Control UI/WebSocket podem autenticar por meio de cabeçalhos de identidade do Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` é `true`. O OpenClaw verifica a identidade resolvendo o endereço `x-forwarded-for` com `tailscale whois` e comparando-o com o cabeçalho, e aceita isso apenas quando a solicitação atinge o loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo do navegador, esse caminho Serve verificado também pula a rodada de pareamento de dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina `gateway.auth.allowTailscale: false` se quiser exigir credenciais explícitas de segredo compartilhado mesmo para tráfego Serve. Então use `gateway.auth.mode: "token"` ou `"password"`.
Por padrão, solicitações Serve da Control UI/WebSocket podem autenticar por cabeçalhos de identidade do Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` é `true`. O OpenClaw verifica a identidade resolvendo o endereço `x-forwarded-for` com `tailscale whois` e comparando-o ao cabeçalho, e só aceita essas solicitações quando elas chegam ao loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo do navegador, esse caminho Serve verificado também pula a rodada de pareamento de dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina `gateway.auth.allowTailscale: false` se quiser exigir credenciais explícitas de segredo compartilhado mesmo para tráfego Serve. Então use `gateway.auth.mode: "token"` ou `"password"`.
Para esse caminho assíncrono de identidade Serve, tentativas de autenticação com falha para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Portanto, novas tentativas ruins concorrentes do mesmo navegador podem mostrar `retry later` na segunda solicitação em vez de duas incompatibilidades simples competindo em paralelo.
Para esse caminho assíncrono de identidade Serve, tentativas de autenticação com falha para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Novas tentativas ruins concorrentes do mesmo navegador podem, portanto, mostrar `retry later` na segunda solicitação em vez de duas incompatibilidades simples competindo em paralelo.
<Warning>
Autenticação Serve sem token pressupõe que o host do gateway é confiável. Se código local não confiável puder ser executado nesse host, exija autenticação por token/senha.
@ -309,13 +310,13 @@ O valor é validado antes de chegar ao navegador. Valores compatíveis incluem c
## HTTP inseguro
Se você abrir o dashboard por HTTP simples (`http://<lan-ip>` ou `http://<tailscale-ip>`), o navegador é executado em um **contexto não seguro** e bloqueia WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade de dispositivo.
Se você abrir o dashboard por HTTP simples (`http://<lan-ip>` ou `http://<tailscale-ip>`), o navegador executa em um **contexto não seguro** e bloqueia WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade de dispositivo.
Exceções documentadas:
- compatibilidade HTTP insegura apenas para localhost com `gateway.controlUi.allowInsecureAuth=true`
- autenticação bem-sucedida da Control UI do operador por meio de `gateway.auth.mode: "trusted-proxy"`
- emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- compatibilidade HTTP insegura somente para localhost com `gateway.controlUi.allowInsecureAuth=true`
- autenticação bem-sucedida da Control UI de operador por `gateway.auth.mode: "trusted-proxy"`
- exceção de emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**Correção recomendada:** use HTTPS (Tailscale Serve) ou abra a UI localmente:
@ -323,7 +324,7 @@ Exceções documentadas:
- `http://127.0.0.1:18789/` (no host do gateway)
<AccordionGroup>
<Accordion title="Comportamento da alternância de autenticação insegura">
<Accordion title="Insecure-auth toggle behavior">
```json5
{
gateway: {
@ -336,12 +337,12 @@ Exceções documentadas:
`allowInsecureAuth` é apenas uma alternância de compatibilidade local:
- Ela permite que sessões da Control UI em localhost prossigam sem identidade do dispositivo em contextos HTTP não seguros.
- Ela permite que sessões da Control UI no localhost prossigam sem identidade do dispositivo em contextos HTTP não seguros.
- Ela não ignora verificações de pareamento.
- Ela não flexibiliza os requisitos de identidade de dispositivo remoto (não localhost).
- Ela não relaxa os requisitos de identidade do dispositivo remoto (não localhost).
</Accordion>
<Accordion title="Somente para emergência">
<Accordion title="Break-glass only">
```json5
{
gateway: {
@ -353,42 +354,42 @@ Exceções documentadas:
```
<Warning>
`dangerouslyDisableDeviceAuth` desativa as verificações de identidade de dispositivo da Control UI e é um rebaixamento grave de segurança. Reverta rapidamente após o uso emergencial.
`dangerouslyDisableDeviceAuth` desativa as verificações de identidade do dispositivo da Control UI e é um rebaixamento grave de segurança. Reverta rapidamente após o uso emergencial.
</Warning>
</Accordion>
<Accordion title="Observação sobre proxy confiável">
- A autenticação de proxy confiável bem-sucedida pode admitir sessões **operator** da Control UI sem identidade de dispositivo.
<Accordion title="Trusted-proxy note">
- Uma autenticação bem-sucedida de proxy confiável pode admitir sessões **operator** da Control UI sem identidade do dispositivo.
- Isso **não** se estende a sessões da Control UI com função de nó.
- Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação de proxy confiável; veja [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
- Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação de proxy confiável; consulte [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
</Accordion>
</AccordionGroup>
Veja [Tailscale](/pt-BR/gateway/tailscale) para orientações de configuração de HTTPS.
Consulte [Tailscale](/pt-BR/gateway/tailscale) para orientações de configuração de HTTPS.
## Política de segurança de conteúdo
A Control UI é distribuída com uma política `img-src` restrita: somente ativos de **mesma origem**, URLs `data:` e URLs `blob:` geradas localmente são permitidos. URLs de imagem remotas `http(s)` e relativas a protocolo são rejeitadas pelo navegador e não emitem buscas de rede.
A Control UI é fornecida com uma política `img-src` restrita: somente ativos de **mesma origem**, URLs `data:` e URLs `blob:` geradas localmente são permitidos. URLs de imagem remotas `http(s)` e relativas ao protocolo são rejeitadas pelo navegador e não emitem buscas de rede.
O que isso significa na prática:
- Avatares e imagens servidos por caminhos relativos (por exemplo, `/avatars/<id>`) ainda são renderizados, incluindo rotas de avatar autenticadas que a UI busca e converte em URLs `blob:` locais.
- URLs `data:image/...` inline ainda são renderizadas (útil para payloads no protocolo).
- Avatares e imagens servidos em caminhos relativos (por exemplo, `/avatars/<id>`) ainda são renderizados, incluindo rotas de avatar autenticadas que a UI busca e converte em URLs `blob:` locais.
- URLs inline `data:image/...` ainda são renderizadas (úteis para payloads no protocolo).
- URLs `blob:` locais criadas pela Control UI ainda são renderizadas.
- URLs de avatar remotas emitidas por metadados de canal são removidas pelos auxiliares de avatar da Control UI e substituídas pelo logotipo/selo integrado, portanto um canal comprometido ou malicioso não consegue forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador.
- URLs de avatar remotas emitidas por metadados de canais são removidas pelos auxiliares de avatar da Control UI e substituídas pelo logotipo/distintivo integrado, para que um canal comprometido ou malicioso não consiga forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador.
Você não precisa alterar nada para obter esse comportamento — ele está sempre ativado e não é configurável.
Você não precisa alterar nada para obter esse comportamento — ele está sempre ativo e não é configurável.
## Autenticação da rota de avatar
Quando a autenticação do Gateway está configurada, o endpoint de avatar da Control UI exige o mesmo token do Gateway que o restante da API:
Quando a autenticação do gateway está configurada, o endpoint de avatar da Control UI exige o mesmo token do gateway que o restante da API:
- `GET /avatar/<agentId>` retorna a imagem do avatar somente para chamadores autenticados. `GET /avatar/<agentId>?meta=1` retorna os metadados do avatar sob a mesma regra.
- Solicitações não autenticadas para qualquer uma das rotas são rejeitadas (correspondendo à rota irmã de mídia do assistente). Isso impede que a rota de avatar vaze a identidade do agente em hosts que, de outra forma, estão protegidos.
- A própria Control UI encaminha o token do Gateway como cabeçalho bearer ao buscar avatares e usa URLs blob autenticadas para que a imagem ainda seja renderizada em dashboards.
- A própria Control UI encaminha o token do gateway como um cabeçalho bearer ao buscar avatares e usa URLs de blob autenticadas para que a imagem ainda seja renderizada em painéis.
Se você desativar a autenticação do Gateway (não recomendado em hosts compartilhados), a rota de avatar também se torna não autenticada, em linha com o restante do Gateway.
Se você desativar a autenticação do gateway (não recomendado em hosts compartilhados), a rota de avatar também se torna não autenticada, em linha com o restante do gateway.
## Compilando a UI
@ -398,7 +399,7 @@ O Gateway serve arquivos estáticos de `dist/control-ui`. Compile-os com:
pnpm ui:build
```
Base absoluta opcional (quando você quer URLs de ativos fixas):
Base absoluta opcional (quando você quiser URLs de ativos fixas):
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -410,24 +411,24 @@ Para desenvolvimento local (servidor de desenvolvimento separado):
pnpm ui:dev
```
Então aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`).
Depois aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`).
## Depuração/testes: servidor de desenvolvimento + Gateway remoto
A Control UI consiste em arquivos estáticos; o destino do WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento do Vite localmente, mas o Gateway é executado em outro lugar.
A Control UI é composta por arquivos estáticos; o destino do WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway é executado em outro lugar.
<Steps>
<Step title="Inicie o servidor de desenvolvimento da UI">
<Step title="Start the UI dev server">
```bash
pnpm ui:dev
```
</Step>
<Step title="Abra com gatewayUrl">
<Step title="Open with gatewayUrl">
```text
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
```
Autenticação única opcional (se necessário):
Autenticação opcional de uso único (se necessário):
```text
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
@ -437,18 +438,18 @@ A Control UI consiste em arquivos estáticos; o destino do WebSocket é configur
</Steps>
<AccordionGroup>
<Accordion title="Observações">
- `gatewayUrl` é armazenado em localStorage após o carregamento e removido da URL.
<Accordion title="Notes">
- `gatewayUrl` é armazenado no localStorage após o carregamento e removido da URL.
- Se você passar um endpoint `ws://` ou `wss://` completo via `gatewayUrl`, codifique o valor de `gatewayUrl` para URL para que o navegador analise a string de consulta corretamente.
- `token` deve ser passado pelo fragmento da URL (`#token=...`) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e no Referer. Parâmetros de consulta legados `?token=` ainda são importados uma vez por compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap.
- `token` deve ser passado pelo fragmento da URL (`#token=...`) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e Referer. Parâmetros de consulta legados `?token=` ainda são importados uma vez por compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap.
- `password` é mantido apenas na memória.
- Quando `gatewayUrl` está definido, a UI não recorre a credenciais de configuração ou ambiente. Forneça `token` (ou `password`) explicitamente. Credenciais explícitas ausentes são um erro.
- Quando `gatewayUrl` está definido, a UI não faz fallback para credenciais de configuração ou ambiente. Forneça `token` (ou `password`) explicitamente. A falta de credenciais explícitas é um erro.
- Use `wss://` quando o Gateway estiver atrás de TLS (Tailscale Serve, proxy HTTPS etc.).
- `gatewayUrl` só é aceito em uma janela de nível superior (não incorporada) para prevenir clickjacking.
- Implantações da Control UI não loopback devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações de desenvolvimento remotas.
- A inicialização do Gateway pode semear origens locais como `http://localhost:<port>` e `http://127.0.0.1:<port>` a partir do bind e da porta efetivos em runtime, mas origens de navegadores remotos ainda precisam de entradas explícitas.
- Não use `gateway.controlUi.allowedOrigins: ["*"]` exceto para testes locais rigidamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder a qualquer host que eu esteja usando."
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita o modo de fallback de origem do cabeçalho Host, mas é um modo de segurança perigoso.
- `gatewayUrl` só é aceito em uma janela de nível superior (não incorporada) para evitar clickjacking.
- Implantações da Control UI que não sejam de loopback devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações de desenvolvimento remotas.
- A inicialização do Gateway pode semear origens locais como `http://localhost:<port>` e `http://127.0.0.1:<port>` a partir do bind e da porta efetivos em tempo de execução, mas origens de navegadores remotos ainda precisam de entradas explícitas.
- Não use `gateway.controlUi.allowedOrigins: ["*"]` exceto para testes locais rigidamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder ao host que eu estiver usando."
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita o modo de fallback de origem pelo cabeçalho Host, mas é um modo de segurança perigoso.
</Accordion>
</AccordionGroup>
@ -467,9 +468,9 @@ Exemplo:
Detalhes de configuração de acesso remoto: [Acesso remoto](/pt-BR/gateway/remote).
## Relacionado
## Relacionados
- [Dashboard](/pt-BR/web/dashboard) — dashboard do gateway
- [Painel](/pt-BR/web/dashboard) — painel do gateway
- [Verificações de integridade](/pt-BR/gateway/health) — monitoramento de integridade do gateway
- [TUI](/pt-BR/web/tui) — interface de usuário de terminal
- [WebChat](/pt-BR/web/webchat) — interface de chat baseada em navegador

78
docs/pt-BR/web/webchat.md
View File

@ -1,71 +1,83 @@
---
read_when:
- Depuração ou configuração do acesso ao WebChat
summary: Host estático do WebChat de loopback e uso de WS do Gateway para interface de chat
summary: Host estático de WebChat em loopback e uso de WS do Gateway para a interface de chat
title: Chat Web
x-i18n:
generated_at: "2026-05-03T05:54:30Z"
generated_at: "2026-05-04T05:56:14Z"
model: gpt-5.5
provider: openai
source_hash: 48024e58259901c6feb67168c5c1ce32f46b8ad9b6f4511e56d2000478a3ed60
source_hash: bf435585a13a1cde5885714837017109eeeb61ffa5e33a400017706f676f57ea
source_path: web/webchat.md
workflow: 16
---
Status: a UI de chat SwiftUI do macOS/iOS conversa diretamente com o WebSocket do Gateway.
Status: a UI de chat SwiftUI para macOS/iOS fala diretamente com o WebSocket do Gateway.
## O que é
- Uma UI de chat nativa para o Gateway, sem navegador incorporado e sem servidor estático local.
- Uma UI de chat nativa para o gateway (sem navegador incorporado e sem servidor estático local).
- Usa as mesmas sessões e regras de roteamento que outros canais.
- Roteamento determinístico: as respostas sempre voltam para o WebChat.
## Início rápido
1. Inicie o Gateway.
1. Inicie o gateway.
2. Abra a UI do WebChat (app macOS/iOS) ou a aba de chat da UI de Controle.
3. Garanta que um caminho válido de autenticação do Gateway esteja configurado (segredo compartilhado por padrão,
3. Garanta que um caminho de autenticação válido do gateway esteja configurado (shared-secret por padrão,
mesmo em loopback).
## Como funciona (comportamento)
- A UI se conecta ao WebSocket do Gateway e usa `chat.history`, `chat.send` e `chat.inject`.
- `chat.history` é limitado para estabilidade: o Gateway pode truncar campos de texto longos, omitir metadados pesados e substituir entradas grandes demais por `[chat.history omitted: message too large]`.
- `chat.history` segue a ramificação ativa da transcrição para arquivos de sessão modernos somente de acréscimo, então ramificações de reescrita abandonadas e cópias de prompts substituídas não são renderizadas no WebChat.
- `chat.history` segue o ramo de transcrição ativo para arquivos de sessão modernos somente de acréscimo, portanto ramos de reescrita abandonados e cópias de prompts substituídas não são renderizados no WebChat.
- Entradas de Compaction são renderizadas como um divisor explícito de histórico compactado. O divisor explica que turnos anteriores são preservados em um checkpoint e vincula aos controles de checkpoint de Sessões, onde operadores podem ramificar ou restaurar a visualização pré-Compaction quando suas permissões permitem.
- A UI de Controle lembra o `sessionId` do Gateway retornado por `chat.history` e o inclui em chamadas seguintes de `chat.send`, então reconexões e atualizações de página continuam a mesma conversa armazenada, a menos que o usuário inicie ou redefina uma sessão.
- A UI de Controle combina envios duplicados em andamento para a mesma sessão, mensagem e anexos antes de gerar um novo id de execução de `chat.send`; o Gateway ainda elimina duplicatas de solicitações repetidas que reutilizam a mesma chave de idempotência.
- `chat.history` também é normalizado para exibição: contexto do OpenClaw somente de runtime,
wrappers de envelope de entrada, tags inline de diretiva de entrega
como `[[reply_to_*]]` e `[[audio_as_voice]]`, payloads XML de chamadas de ferramenta em texto simples
- A UI de Controle lembra o `sessionId` de Gateway subjacente retornado por `chat.history` e o inclui em chamadas `chat.send` de acompanhamento, portanto reconexões e atualizações de página continuam a mesma conversa armazenada, a menos que o usuário inicie ou redefina uma sessão.
- A UI de Controle combina envios duplicados em andamento para a mesma sessão, mensagem e anexos antes de gerar um novo id de execução de `chat.send`; o Gateway ainda desduplica solicitações repetidas que reutilizam a mesma chave de idempotência.
- Arquivos de inicialização do workspace e instruções `BOOTSTRAP.md` pendentes são fornecidos pelo Contexto do Projeto do prompt de sistema do agente, não copiados para a mensagem de usuário do WebChat. O truncamento de bootstrap só adiciona um aviso conciso de recuperação no prompt de sistema; contagens detalhadas e opções de configuração ficam nas superfícies de diagnóstico.
- `chat.history` também é normalizado para exibição: contexto OpenClaw somente de runtime,
wrappers de envelope de entrada, tags de diretiva de entrega inline
como `[[reply_to_*]]` e `[[audio_as_voice]]`, payloads XML de chamada de ferramenta em texto simples
(incluindo `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
`<function_calls>...</function_calls>` e blocos de chamadas de ferramenta truncados), e
`<function_calls>...</function_calls>` e blocos de chamada de ferramenta truncados), e
tokens de controle de modelo ASCII/largura total vazados são removidos do texto visível,
e entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato
e entradas do assistente cujo texto visível inteiro é apenas o token silencioso exato
`NO_REPLY` / `no_reply` são omitidas.
- Payloads de resposta sinalizados como raciocínio (`isReasoning: true`) são excluídos do conteúdo do assistente no WebChat, do texto de reprodução da transcrição e dos blocos de conteúdo de áudio, então payloads apenas de pensamento não aparecem como mensagens visíveis do assistente nem como áudio reproduzível.
- `chat.inject` acrescenta uma nota do assistente diretamente à transcrição e a transmite para a UI (sem execução do agente).
- Payloads de resposta marcados como raciocínio (`isReasoning: true`) são excluídos do conteúdo do assistente do WebChat, do texto de repetição da transcrição e dos blocos de conteúdo de áudio, portanto payloads apenas de pensamento não aparecem como mensagens visíveis do assistente nem como áudio reproduzível.
- `chat.inject` acrescenta uma nota do assistente diretamente à transcrição e a transmite para a UI (sem execução de agente).
- Execuções abortadas podem manter a saída parcial do assistente visível na UI.
- O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando há saída em buffer, e marca essas entradas com metadados de aborto.
- O histórico é sempre buscado no Gateway (sem observação de arquivo local).
- Se o Gateway estiver inacessível, o WebChat fica somente leitura.
- O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando existe saída em buffer, e marca essas entradas com metadados de aborto.
- O histórico é sempre buscado no gateway (sem monitoramento de arquivo local).
- Se o gateway estiver inacessível, o WebChat fica somente leitura.
### Modelo de transcrição e entrega
O WebChat tem dois caminhos de dados separados:
- O arquivo JSONL da sessão é a transcrição durável do modelo/runtime. Para execuções normais de agente, o Pi persiste mensagens `user`, `assistant` e `toolResult` visíveis ao modelo por meio do seu gerenciador de sessões. O WebChat não grava texto arbitrário de entrega, status ou auxiliar nessa transcrição.
- Eventos `ReplyPayload` do Gateway são a projeção de entrega ao vivo. Eles podem ser normalizados para exibição no WebChat/canal, streaming de blocos, tags de diretiva, incorporação de mídia, flags de TTS/áudio e comportamento de fallback da UI. Eles não são, por si só, o log canônico da sessão.
- O WebChat injeta entradas de transcrição do assistente somente quando o Gateway possui uma mensagem exibida fora de um turno normal do assistente do Pi: `chat.inject`, respostas de comando sem agente, saída parcial abortada e suplementos de transcrição de mídia gerenciados pelo WebChat.
- `chat.history` lê a transcrição da sessão armazenada e aplica a projeção de exibição do WebChat. Se texto do assistente ao vivo aparecer durante uma execução, mas desaparecer após recarregar o histórico, verifique primeiro se o JSONL bruto contém o texto do assistente, depois se a projeção de `chat.history` o removeu, e então se a mesclagem de cauda otimista da UI de Controle substituiu o estado de entrega local pelo snapshot persistido.
Respostas finais de execuções normais de agente devem ser duráveis porque o Pi grava o `message_end` do assistente. Qualquer fallback que espelhe um payload final entregue na transcrição deve primeiro evitar duplicar um turno do assistente que o Pi já gravou.
## Painel de ferramentas de agentes da UI de Controle
- O painel Ferramentas de `/agents` da UI de Controle tem duas visualizações separadas:
- **Disponível agora** usa `tools.effective(sessionKey=...)` e mostra o que a sessão atual
pode realmente usar em runtime, incluindo ferramentas principais, de Plugin e pertencentes a canais.
- **Configuração de ferramentas** usa `tools.catalog` e permanece focado em perfis, substituições e
- O painel Tools da UI de Controle em `/agents` tem duas visualizações separadas:
- **Disponível Agora** usa `tools.effective(sessionKey=...)` e mostra o que a sessão atual
pode realmente usar em runtime, incluindo ferramentas do núcleo, de Plugin e pertencentes ao canal.
- **Configuração de Ferramentas** usa `tools.catalog` e permanece focado em perfis, substituições e
semântica do catálogo.
- A disponibilidade em runtime tem escopo de sessão. Alternar sessões no mesmo agente pode alterar a lista
**Disponível agora**.
- O editor de configuração não implica disponibilidade em runtime; o acesso efetivo ainda segue a precedência de políticas
- A disponibilidade de runtime tem escopo de sessão. Trocar sessões no mesmo agente pode alterar a lista
**Disponível Agora**.
- O editor de configuração não implica disponibilidade em runtime; o acesso efetivo ainda segue a precedência de política
(`allow`/`deny`, substituições por agente e por provedor/canal).
## Uso remoto
- O modo remoto tunela o WebSocket do Gateway por SSH/Tailscale.
- O modo remoto encapsula o WebSocket do gateway por SSH/Tailscale.
- Você não precisa executar um servidor WebChat separado.
## Referência de configuração (WebChat)
@ -74,18 +86,18 @@ Configuração completa: [Configuração](/pt-BR/gateway/configuration)
Opções do WebChat:
- `gateway.webchat.chatHistoryMaxChars`: contagem máxima de caracteres para campos de texto em respostas de `chat.history`. Quando uma entrada de transcrição excede esse limite, o Gateway trunca campos de texto longos e pode substituir mensagens grandes demais por um placeholder. `maxChars` por solicitação também pode ser enviado pelo cliente para substituir esse padrão em uma única chamada de `chat.history`.
- `gateway.webchat.chatHistoryMaxChars`: contagem máxima de caracteres para campos de texto em respostas `chat.history`. Quando uma entrada de transcrição excede esse limite, o Gateway trunca campos de texto longos e pode substituir mensagens grandes demais por um placeholder. `maxChars` por solicitação também pode ser enviado pelo cliente para substituir esse padrão em uma única chamada `chat.history`.
Opções globais relacionadas:
- `gateway.port`, `gateway.bind`: host/porta do WebSocket.
- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
autenticação WebSocket por segredo compartilhado.
autenticação WebSocket shared-secret.
- `gateway.auth.allowTailscale`: a aba de chat da UI de Controle no navegador pode usar cabeçalhos de identidade do Tailscale
Serve quando habilitado.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso para clientes de navegador por trás de uma origem de proxy **não loopback** ciente de identidade (consulte [Autenticação de Proxy Confiável](/pt-BR/gateway/trusted-proxy-auth)).
- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: destino do Gateway remoto.
- `session.*`: armazenamento de sessão e padrões da chave principal.
- `gateway.auth.mode: "trusted-proxy"`: autenticação por proxy reverso para clientes de navegador atrás de uma origem de proxy **não loopback** com reconhecimento de identidade (consulte [Autenticação de Proxy Confiável](/pt-BR/gateway/trusted-proxy-auth)).
- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: alvo do gateway remoto.
- `session.*`: armazenamento de sessão e padrões de chave principal.
## Relacionado