chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
cc86147848
commit
5c69ae7bec
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Inspecionando trabalho em segundo plano em andamento ou concluído recentemente
|
||||
- Depurando falhas de entrega para execuções destacadas de agentes
|
||||
- Depurando falhas de entrega para execuções de agentes desanexadas
|
||||
- Entendendo como execuções em segundo plano se relacionam com sessões, cron e heartbeat
|
||||
summary: Rastreamento de tarefas em segundo plano para execuções ACP, subagentes, trabalhos cron isolados e operações da CLI
|
||||
title: Tarefas em Segundo Plano
|
||||
summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, trabalhos cron isolados e operações da CLI
|
||||
title: Tarefas em segundo plano
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:40Z"
|
||||
generated_at: "2026-04-10T05:34:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
|
||||
source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
|
||||
source_path: automation/tasks.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Tarefas em Segundo Plano
|
||||
# Tarefas em segundo plano
|
||||
|
||||
> **Procurando agendamento?** Consulte [Automação e Tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página cobre o **rastreamento** do trabalho em segundo plano, não o agendamento dele.
|
||||
> **Está procurando agendamento?** Veja [Automação e Tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página cobre o **rastreamento** de trabalho em segundo plano, não o agendamento.
|
||||
|
||||
As tarefas em segundo plano rastreiam trabalho que é executado **fora da sua sessão principal de conversa**:
|
||||
execuções ACP, inicializações de subagentes, execuções isoladas de trabalhos cron e operações iniciadas pela CLI.
|
||||
As tarefas em segundo plano rastreiam trabalhos executados **fora da sua sessão principal de conversa**:
|
||||
execuções do ACP, inicializações de subagentes, execuções isoladas de trabalhos cron e operações iniciadas pela CLI.
|
||||
|
||||
As tarefas **não** substituem sessões, trabalhos cron ou heartbeats — elas são o **registro de atividade** que registra qual trabalho destacado aconteceu, quando aconteceu e se foi bem-sucedido.
|
||||
As tarefas **não** substituem sessões, trabalhos cron ou heartbeats — elas são o **registro de atividade** que documenta que trabalho desanexado aconteceu, quando aconteceu e se foi bem-sucedido.
|
||||
|
||||
<Note>
|
||||
Nem toda execução de agente cria uma tarefa. Turnos de heartbeat e chat interativo normal não criam. Todas as execuções cron, inicializações ACP, inicializações de subagentes e comandos de agente da CLI criam.
|
||||
Nem toda execução de agente cria uma tarefa. Turnos de heartbeat e chat interativo normal não criam. Todas as execuções cron, inicializações do ACP, inicializações de subagentes e comandos de agente da CLI criam.
|
||||
</Note>
|
||||
|
||||
## Resumo rápido
|
||||
@ -32,41 +32,45 @@ Nem toda execução de agente cria uma tarefa. Turnos de heartbeat e chat intera
|
||||
- Tarefas são **registros**, não agendadores — cron e heartbeat decidem _quando_ o trabalho é executado, as tarefas rastreiam _o que aconteceu_.
|
||||
- ACP, subagentes, todos os trabalhos cron e operações da CLI criam tarefas. Turnos de heartbeat não criam.
|
||||
- Cada tarefa passa por `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost).
|
||||
- As tarefas cron permanecem ativas enquanto o runtime cron ainda for responsável pelo trabalho; tarefas da CLI com suporte de chat permanecem ativas apenas enquanto seu contexto de execução proprietário ainda estiver ativo.
|
||||
- A conclusão é orientada por envio: o trabalho destacado pode notificar diretamente ou despertar a sessão solicitante/heartbeat quando termina, então loops de polling de status geralmente não são o formato correto.
|
||||
- Execuções cron isoladas e conclusões de subagentes limpam por melhor esforço abas/processos de navegador rastreados para sua sessão filha antes da contabilidade final de limpeza.
|
||||
- A entrega de cron isolado suprime respostas intermediárias obsoletas do pai enquanto o trabalho de subagentes descendentes ainda está sendo drenado, e prefere a saída final descendente quando ela chega antes da entrega.
|
||||
- Notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo heartbeat.
|
||||
- Tarefas cron permanecem ativas enquanto o runtime do cron ainda possuir o trabalho; tarefas da CLI com suporte de chat permanecem ativas apenas enquanto seu contexto de execução proprietário ainda estiver ativo.
|
||||
- A conclusão é orientada por push: o trabalho desanexado pode notificar diretamente ou despertar a
|
||||
sessão/heartbeat solicitante quando terminar, então laços de polling de status
|
||||
geralmente não são o formato certo.
|
||||
- Execuções cron isoladas e conclusões de subagentes fazem uma limpeza best-effort de abas/processos rastreados do navegador para sua sessão filha antes da limpeza final de bookkeeping.
|
||||
- A entrega de cron isolado suprime respostas intermediárias obsoletas do pai enquanto
|
||||
o trabalho de subagentes descendentes ainda estiver sendo drenado, e prefere a saída final do descendente
|
||||
quando ela chega antes da entrega.
|
||||
- As notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo heartbeat.
|
||||
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` exibe problemas.
|
||||
- Registros terminais são mantidos por 7 dias e depois removidos automaticamente.
|
||||
|
||||
## Início rápido
|
||||
|
||||
```bash
|
||||
# Lista todas as tarefas (mais recentes primeiro)
|
||||
# Liste todas as tarefas (mais novas primeiro)
|
||||
openclaw tasks list
|
||||
|
||||
# Filtra por runtime ou status
|
||||
# Filtre por runtime ou status
|
||||
openclaw tasks list --runtime acp
|
||||
openclaw tasks list --status running
|
||||
|
||||
# Mostra detalhes de uma tarefa específica (por ID, ID de execução ou chave de sessão)
|
||||
# Mostre detalhes de uma tarefa específica (por ID, ID de execução ou chave de sessão)
|
||||
openclaw tasks show <lookup>
|
||||
|
||||
# Cancela uma tarefa em execução (mata a sessão filha)
|
||||
# Cancele uma tarefa em execução (encerra a sessão filha)
|
||||
openclaw tasks cancel <lookup>
|
||||
|
||||
# Altera a política de notificação de uma tarefa
|
||||
# Altere a política de notificação de uma tarefa
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
|
||||
# Executa uma auditoria de integridade
|
||||
# Execute uma auditoria de integridade
|
||||
openclaw tasks audit
|
||||
|
||||
# Visualiza ou aplica manutenção
|
||||
# Visualize ou aplique manutenção
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
|
||||
# Inspeciona o estado do Task Flow
|
||||
# Inspecione o estado do TaskFlow
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
@ -74,23 +78,23 @@ openclaw tasks flow cancel <lookup>
|
||||
|
||||
## O que cria uma tarefa
|
||||
|
||||
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
|
||||
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
|
||||
| ---------------------- | --------------- | ----------------------------------------------------- | ------------------------------ |
|
||||
| Execuções em segundo plano do ACP | `acp` | Ao iniciar uma sessão filha do ACP | `done_only` |
|
||||
| Orquestração de subagentes | `subagent` | Ao iniciar um subagente via `sessions_spawn` | `done_only` |
|
||||
| Trabalhos cron (todos os tipos) | `cron` | Toda execução cron (sessão principal e isolada) | `silent` |
|
||||
| Operações da CLI | `cli` | Comandos `openclaw agent` executados por meio do gateway | `silent` |
|
||||
| Trabalhos cron (todos os tipos) | `cron` | Em cada execução cron (sessão principal e isolada) | `silent` |
|
||||
| Operações da CLI | `cli` | Comandos `openclaw agent` executados pelo gateway | `silent` |
|
||||
| Trabalhos de mídia do agente | `cli` | Execuções `video_generate` com suporte de sessão | `silent` |
|
||||
|
||||
Tarefas cron da sessão principal usam a política de notificação `silent` por padrão — elas criam registros para rastreamento, mas não geram notificações. Tarefas cron isoladas também usam `silent` por padrão, mas são mais visíveis porque são executadas na própria sessão.
|
||||
As tarefas cron da sessão principal usam a política de notificação `silent` por padrão — elas criam registros para rastreamento, mas não geram notificações. Tarefas cron isoladas também usam `silent` por padrão, mas são mais visíveis porque são executadas na própria sessão.
|
||||
|
||||
Execuções `video_generate` com suporte de sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um wake interno para que o agente possa escrever a mensagem de acompanhamento e anexar ele mesmo o vídeo finalizado. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta ao canal antes de recorrer ao caminho de wake da sessão solicitante.
|
||||
Execuções `video_generate` com suporte de sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um despertar interno para que o agente possa escrever a mensagem de acompanhamento e anexar o vídeo concluído por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta ao canal antes de recorrer ao caminho de despertar da sessão solicitante.
|
||||
|
||||
Enquanto uma tarefa `video_generate` com suporte de sessão ainda estiver ativa, a ferramenta também atua como um guardrail: chamadas repetidas de `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status do lado do agente.
|
||||
Enquanto uma tarefa `video_generate` com suporte de sessão ainda estiver ativa, a ferramenta também atua como proteção: chamadas repetidas de `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status pelo lado do agente.
|
||||
|
||||
**O que não cria tarefas:**
|
||||
|
||||
- Turnos de heartbeat — sessão principal; consulte [Heartbeat](/pt-BR/gateway/heartbeat)
|
||||
- Turnos de heartbeat — sessão principal; veja [Heartbeat](/pt-BR/gateway/heartbeat)
|
||||
- Turnos normais de chat interativo
|
||||
- Respostas diretas de `/command`
|
||||
|
||||
@ -111,21 +115,21 @@ stateDiagram-v2
|
||||
| Status | O que significa |
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| `queued` | Criada, aguardando o agente iniciar |
|
||||
| `running` | O turno do agente está em execução ativa |
|
||||
| `running` | O turno do agente está sendo executado ativamente |
|
||||
| `succeeded` | Concluída com sucesso |
|
||||
| `failed` | Concluída com erro |
|
||||
| `failed` | Concluída com um erro |
|
||||
| `timed_out` | Excedeu o tempo limite configurado |
|
||||
| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` |
|
||||
| `lost` | O runtime perdeu o estado de suporte autoritativo após um período de carência de 5 minutos |
|
||||
| `lost` | O runtime perdeu o estado de suporte autoritativo após um período de tolerância de 5 minutos |
|
||||
|
||||
As transições acontecem automaticamente — quando a execução do agente associada termina, o status da tarefa é atualizado para corresponder.
|
||||
|
||||
`lost` depende do runtime:
|
||||
`lost` é sensível ao runtime:
|
||||
|
||||
- Tarefas ACP: os metadados da sessão filha do ACP de suporte desapareceram.
|
||||
- Tarefas do ACP: os metadados de suporte da sessão filha do ACP desapareceram.
|
||||
- Tarefas de subagente: a sessão filha de suporte desapareceu do armazenamento do agente de destino.
|
||||
- Tarefas cron: o runtime cron não rastreia mais o trabalho como ativo.
|
||||
- Tarefas da CLI: tarefas isoladas de sessão filha usam a sessão filha; tarefas da CLI com suporte de chat usam o contexto de execução ativo em vez disso, então linhas persistentes de sessão de canal/grupo/direta não as mantêm ativas.
|
||||
- Tarefas cron: o runtime do cron não rastreia mais o trabalho como ativo.
|
||||
- Tarefas da CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas da CLI com suporte de chat usam o contexto de execução ativo no lugar, então linhas persistentes de sessão de canal/grupo/direta não as mantêm ativas.
|
||||
|
||||
## Entrega e notificações
|
||||
|
||||
@ -133,23 +137,25 @@ Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois
|
||||
|
||||
**Entrega direta** — se a tarefa tiver um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai diretamente para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagentes, o OpenClaw também preserva o roteamento vinculado de thread/tópico quando disponível e pode preencher um `to` / conta ausente a partir da rota armazenada da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de desistir da entrega direta.
|
||||
|
||||
**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo heartbeat.
|
||||
**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento do sistema na sessão do solicitante e aparece no próximo heartbeat.
|
||||
|
||||
<Tip>
|
||||
A conclusão da tarefa aciona um wake imediato do heartbeat para que você veja o resultado rapidamente — você não precisa esperar o próximo tick agendado do heartbeat.
|
||||
A conclusão da tarefa aciona um despertar imediato do heartbeat para que você veja o resultado rapidamente — você não precisa esperar pelo próximo tick agendado do heartbeat.
|
||||
</Tip>
|
||||
|
||||
Isso significa que o fluxo de trabalho usual é baseado em envio: inicie o trabalho destacado uma vez e depois deixe o runtime despertar ou notificar você na conclusão. Faça polling do estado da tarefa apenas quando precisar de depuração, intervenção ou uma auditoria explícita.
|
||||
Isso significa que o fluxo de trabalho usual é orientado por push: inicie o trabalho desanexado uma vez e depois deixe
|
||||
o runtime despertar ou notificar você quando ele terminar. Faça polling do estado da tarefa apenas quando
|
||||
precisar de depuração, intervenção ou uma auditoria explícita.
|
||||
|
||||
### Políticas de notificação
|
||||
|
||||
Controle o quanto você recebe de informação sobre cada tarefa:
|
||||
Controle quanto você quer ouvir sobre cada tarefa:
|
||||
|
||||
| Política | O que é entregue |
|
||||
| --------------------- | ------------------------------------------------------------------------ |
|
||||
| Política | O que é entregue |
|
||||
| --------------------- | ----------------------------------------------------------------------- |
|
||||
| `done_only` (padrão) | Apenas o estado terminal (succeeded, failed etc.) — **este é o padrão** |
|
||||
| `state_changes` | Toda transição de estado e atualização de progresso |
|
||||
| `silent` | Nada |
|
||||
| `state_changes` | Toda transição de estado e atualização de progresso |
|
||||
| `silent` | Nada |
|
||||
|
||||
Altere a política enquanto uma tarefa estiver em execução:
|
||||
|
||||
@ -165,7 +171,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
|
||||
Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID de execução, Sessão filha, Resumo.
|
||||
Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID da execução, Sessão filha, Resumo.
|
||||
|
||||
### `tasks show`
|
||||
|
||||
@ -173,7 +179,7 @@ Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID de execução, Sessã
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
O token de lookup aceita um ID de tarefa, ID de execução ou chave de sessão. Mostra o registro completo, incluindo tempo, estado de entrega, erro e resumo terminal.
|
||||
O token de lookup aceita um ID de tarefa, ID de execução ou chave de sessão. Mostra o registro completo, incluindo tempo, estado da entrega, erro e resumo terminal.
|
||||
|
||||
### `tasks cancel`
|
||||
|
||||
@ -181,7 +187,7 @@ O token de lookup aceita um ID de tarefa, ID de execução ou chave de sessão.
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
Para tarefas ACP e de subagente, isso mata a sessão filha. O status passa para `cancelled` e uma notificação de entrega é enviada.
|
||||
Para tarefas do ACP e de subagentes, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há um identificador de runtime filho separado). O status muda para `cancelled` e uma notificação de entrega é enviada quando aplicável.
|
||||
|
||||
### `tasks notify`
|
||||
|
||||
@ -195,16 +201,16 @@ openclaw tasks notify <lookup> <done_only|state_changes|silent>
|
||||
openclaw tasks audit [--json]
|
||||
```
|
||||
|
||||
Exibe problemas operacionais. As descobertas também aparecem em `openclaw status` quando problemas são detectados.
|
||||
Exibe problemas operacionais. Os achados também aparecem em `openclaw status` quando problemas são detectados.
|
||||
|
||||
| Descoberta | Severidade | Gatilho |
|
||||
| Achado | Severidade | Gatilho |
|
||||
| ------------------------- | ---------- | ---------------------------------------------------- |
|
||||
| `stale_queued` | warn | Em fila por mais de 10 minutos |
|
||||
| `stale_running` | error | Em execução por mais de 30 minutos |
|
||||
| `lost` | error | A propriedade da tarefa com suporte de runtime desapareceu |
|
||||
| `delivery_failed` | warn | A entrega falhou e a política de notificação não é `silent` |
|
||||
| `missing_cleanup` | warn | Tarefa terminal sem timestamp de limpeza |
|
||||
| `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de iniciar) |
|
||||
| `missing_cleanup` | warn | Tarefa terminal sem carimbo de data/hora de limpeza |
|
||||
| `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de começar) |
|
||||
|
||||
### `tasks maintenance`
|
||||
|
||||
@ -213,20 +219,22 @@ openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
Use isto para visualizar ou aplicar reconciliação, marcação de limpeza e remoção para tarefas e estado do Task Flow.
|
||||
Use isso para visualizar ou aplicar reconciliação, marcação de limpeza e remoção para
|
||||
tarefas e estado do Task Flow.
|
||||
|
||||
A reconciliação depende do runtime:
|
||||
A reconciliação é sensível ao runtime:
|
||||
|
||||
- Tarefas ACP/subagente verificam sua sessão filha de suporte.
|
||||
- Tarefas cron verificam se o runtime cron ainda é responsável pelo trabalho.
|
||||
- Tarefas da CLI com suporte de chat verificam o contexto de execução ativo proprietário, não apenas a linha de sessão de chat.
|
||||
- Tarefas do ACP/subagente verificam sua sessão filha de suporte.
|
||||
- Tarefas cron verificam se o runtime do cron ainda possui o trabalho.
|
||||
- Tarefas da CLI com suporte de chat verificam o contexto de execução ativo proprietário, não apenas a linha da sessão de chat.
|
||||
|
||||
A limpeza de conclusão também depende do runtime:
|
||||
A limpeza de conclusão também é sensível ao runtime:
|
||||
|
||||
- A conclusão de subagente fecha por melhor esforço abas/processos de navegador rastreados para a sessão filha antes de a limpeza do anúncio continuar.
|
||||
- A conclusão de cron isolado fecha por melhor esforço abas/processos de navegador rastreados para a sessão cron antes de a execução ser totalmente encerrada.
|
||||
- A entrega de cron isolado espera o acompanhamento descendente de subagentes quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
|
||||
- A entrega de conclusão de subagente prefere o texto visível mais recente do assistente; se ele estiver vazio, recorre ao texto sanitizado mais recente de tool/toolResult, e execuções de chamada de ferramenta apenas com timeout podem ser reduzidas a um breve resumo de progresso parcial.
|
||||
- A conclusão de subagente fecha, em best-effort, abas/processos rastreados do navegador para a sessão filha antes que a limpeza do anúncio continue.
|
||||
- A conclusão de cron isolado fecha, em best-effort, abas/processos rastreados do navegador para a sessão cron antes que a execução seja totalmente desmontada.
|
||||
- A entrega de cron isolado espera o acompanhamento de subagentes descendentes quando necessário e
|
||||
suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
|
||||
- A entrega de conclusão de subagente prefere o texto visível mais recente do assistente; se estiver vazio, recorre ao texto mais recente saneado de tool/toolResult, e execuções apenas com chamada de ferramenta por timeout podem ser condensadas em um resumo curto de progresso parcial.
|
||||
- Falhas de limpeza não mascaram o resultado real da tarefa.
|
||||
|
||||
### `tasks flow list|show|cancel`
|
||||
@ -237,19 +245,22 @@ openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
Use estes comandos quando o Task Flow de orquestração for aquilo com que você se importa, em vez de um registro individual de tarefa em segundo plano.
|
||||
Use esses comandos quando o Task Flow de orquestração for a coisa com a qual você se importa
|
||||
em vez de um registro individual de tarefa em segundo plano.
|
||||
|
||||
## Painel de tarefas no chat (`/tasks`)
|
||||
|
||||
Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O painel mostra tarefas ativas e concluídas recentemente com runtime, status, tempo e detalhes de progresso ou erro.
|
||||
Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O painel mostra
|
||||
tarefas ativas e concluídas recentemente com runtime, status, tempo e detalhes de progresso ou erro.
|
||||
|
||||
Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre a contagens de tarefas locais do agente para que você ainda tenha uma visão geral sem expor detalhes de outras sessões.
|
||||
Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre a contagens de tarefas locais do agente
|
||||
para que você ainda tenha uma visão geral sem expor detalhes de outras sessões.
|
||||
|
||||
Para o registro completo do operador, use a CLI: `openclaw tasks list`.
|
||||
|
||||
## Integração com status (pressão de tarefas)
|
||||
## Integração de status (pressão de tarefas)
|
||||
|
||||
`openclaw status` inclui um resumo rápido das tarefas:
|
||||
`openclaw status` inclui um resumo rápido de tarefas:
|
||||
|
||||
```
|
||||
Tasks: 3 queued · 2 running · 1 issues
|
||||
@ -261,27 +272,29 @@ O resumo informa:
|
||||
- **failures** — contagem de `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — detalhamento por `acp`, `subagent`, `cron`, `cli`
|
||||
|
||||
Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas têm prioridade, linhas concluídas obsoletas ficam ocultas, e falhas recentes só aparecem quando não resta trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
|
||||
Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas têm
|
||||
preferência, linhas concluídas obsoletas são ocultadas e falhas recentes só aparecem quando não resta
|
||||
trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
|
||||
|
||||
## Armazenamento e manutenção
|
||||
|
||||
### Onde as tarefas ficam
|
||||
|
||||
Os registros de tarefas persistem no SQLite em:
|
||||
Os registros de tarefa persistem em SQLite em:
|
||||
|
||||
```
|
||||
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
|
||||
```
|
||||
|
||||
O registro é carregado na memória na inicialização do gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações.
|
||||
O registro é carregado em memória na inicialização do gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações.
|
||||
|
||||
### Manutenção automática
|
||||
|
||||
Um varredor é executado a cada **60 segundos** e cuida de três coisas:
|
||||
Um processo de varredura é executado a cada **60 segundos** e lida com três coisas:
|
||||
|
||||
1. **Reconciliação** — verifica se tarefas ativas ainda têm suporte autoritativo de runtime. Tarefas ACP/subagente usam o estado da sessão filha, tarefas cron usam a propriedade do trabalho ativo, e tarefas da CLI com suporte de chat usam o contexto de execução proprietário. Se esse estado de suporte desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
|
||||
2. **Marcação de limpeza** — define um timestamp `cleanupAfter` em tarefas terminais (`endedAt` + 7 dias).
|
||||
3. **Remoção** — exclui registros que passaram da data `cleanupAfter`.
|
||||
1. **Reconciliação** — verifica se tarefas ativas ainda têm suporte autoritativo do runtime. Tarefas do ACP/subagente usam o estado da sessão filha, tarefas cron usam a propriedade do trabalho ativo e tarefas da CLI com suporte de chat usam o contexto de execução proprietário. Se esse estado de suporte desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
|
||||
2. **Marcação de limpeza** — define um timestamp `cleanupAfter` em tarefas terminais (`endedAt + 7 days`).
|
||||
3. **Remoção** — exclui registros após a data `cleanupAfter`.
|
||||
|
||||
**Retenção**: registros de tarefas terminais são mantidos por **7 dias** e depois removidos automaticamente. Nenhuma configuração é necessária.
|
||||
|
||||
@ -289,25 +302,25 @@ Um varredor é executado a cada **60 segundos** e cuida de três coisas:
|
||||
|
||||
### Tarefas e Task Flow
|
||||
|
||||
[Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxo acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo de orquestração.
|
||||
[Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxos acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo de orquestração.
|
||||
|
||||
Consulte [Task Flow](/pt-BR/automation/taskflow) para mais detalhes.
|
||||
Veja [Task Flow](/pt-BR/automation/taskflow) para mais detalhes.
|
||||
|
||||
### Tarefas e cron
|
||||
|
||||
Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`. **Toda** execução cron cria um registro de tarefa — tanto principal quanto isolada. Tarefas cron da sessão principal usam a política de notificação `silent` por padrão para rastrear sem gerar notificações.
|
||||
Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`. **Toda** execução cron cria um registro de tarefa — tanto na sessão principal quanto em execução isolada. Tarefas cron da sessão principal usam a política de notificação `silent` por padrão, para rastrear sem gerar notificações.
|
||||
|
||||
Consulte [Trabalhos Cron](/pt-BR/automation/cron-jobs).
|
||||
Veja [Trabalhos cron](/pt-BR/automation/cron-jobs).
|
||||
|
||||
### Tarefas e heartbeat
|
||||
|
||||
Execuções de heartbeat são turnos da sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um wake do heartbeat para que você veja o resultado rapidamente.
|
||||
Execuções de heartbeat são turnos da sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um despertar do heartbeat para que você veja o resultado prontamente.
|
||||
|
||||
Consulte [Heartbeat](/pt-BR/gateway/heartbeat).
|
||||
Veja [Heartbeat](/pt-BR/gateway/heartbeat).
|
||||
|
||||
### Tarefas e sessões
|
||||
|
||||
Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem o iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade sobre esse contexto.
|
||||
Uma tarefa pode referenciar um `childSessionKey` (onde o trabalho é executado) e um `requesterSessionKey` (quem a iniciou). Sessões são o contexto da conversa; tarefas são o rastreamento de atividade sobre esse contexto.
|
||||
|
||||
### Tarefas e execuções de agente
|
||||
|
||||
@ -315,8 +328,8 @@ O `runId` de uma tarefa se vincula à execução do agente que está realizando
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Automação e Tarefas](/pt-BR/automation) — todos os mecanismos de automação em um relance
|
||||
- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas
|
||||
- [Tarefas Agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
|
||||
- [Automação e Tarefas](/pt-BR/automation) — todos os mecanismos de automação em resumo
|
||||
- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxos acima das tarefas
|
||||
- [Tarefas agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
|
||||
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos da sessão principal
|
||||
- [CLI: Tarefas](/cli/index#tasks) — referência de comandos da CLI
|
||||
|
||||
616
docs/pt-BR/concepts/active-memory.md
Normal file
616
docs/pt-BR/concepts/active-memory.md
Normal file
@ -0,0 +1,616 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer entender para que serve a memória ativa
|
||||
- Você quer ativar a memória ativa para um agente conversacional
|
||||
- Você quer ajustar o comportamento da memória ativa sem ativá-la em todos os lugares
|
||||
summary: Um subagente de memória de bloqueio, pertencente ao plugin, que injeta memória relevante em sessões de chat interativas
|
||||
title: Memória ativa
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T05:34:14Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memória ativa
|
||||
|
||||
A memória ativa é um subagente opcional de memória de bloqueio, pertencente ao plugin, que é executado
|
||||
antes da resposta principal em sessões conversacionais qualificadas.
|
||||
|
||||
Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem
|
||||
do agente principal para decidir quando pesquisar na memória, ou do usuário para dizer coisas
|
||||
como "lembre-se disso" ou "pesquise na memória". Nessa altura, o momento em que a memória teria
|
||||
feito a resposta parecer natural já passou.
|
||||
|
||||
A memória ativa dá ao sistema uma chance limitada de trazer memória relevante
|
||||
antes de a resposta principal ser gerada.
|
||||
|
||||
## Cole isto no seu agente
|
||||
|
||||
Cole isto no seu agente se você quiser habilitar a Memória ativa com uma
|
||||
configuração autocontida e segura por padrão:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Isso ativa o plugin para o agente `main`, o mantém limitado por padrão a
|
||||
sessões no estilo de mensagens diretas, permite que ele herde primeiro o modelo da
|
||||
sessão atual e ainda permite o fallback remoto integrado caso nenhum modelo explícito
|
||||
ou herdado esteja disponível.
|
||||
|
||||
Depois disso, reinicie o gateway:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Para inspecioná-lo ao vivo em uma conversa:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## Ativar a memória ativa
|
||||
|
||||
A configuração mais segura é:
|
||||
|
||||
1. habilitar o plugin
|
||||
2. direcioná-lo para um agente conversacional
|
||||
3. manter o logging ativado apenas durante o ajuste fino
|
||||
|
||||
Comece com isto em `openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Depois reinicie o gateway:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
O que isso significa:
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` ativa o plugin
|
||||
- `config.agents: ["main"]` habilita a memória ativa apenas para o agente `main`
|
||||
- `config.allowedChatTypes: ["direct"]` mantém a memória ativa habilitada por padrão apenas para sessões no estilo de mensagens diretas
|
||||
- se `config.model` não estiver definido, a memória ativa herda primeiro o modelo da sessão atual
|
||||
- `config.modelFallbackPolicy: "default-remote"` mantém o fallback remoto integrado como padrão quando nenhum modelo explícito ou herdado está disponível
|
||||
- `config.promptStyle: "balanced"` usa o estilo de prompt padrão de uso geral para o modo `recent`
|
||||
- a memória ativa ainda é executada apenas em sessões de chat persistentes interativas qualificadas
|
||||
|
||||
## Como vê-la
|
||||
|
||||
A memória ativa injeta contexto oculto de sistema para o modelo. Ela não expõe
|
||||
tags brutas `<active_memory_plugin>...</active_memory_plugin>` ao cliente.
|
||||
|
||||
## Alternância por sessão
|
||||
|
||||
Use o comando do plugin quando quiser pausar ou retomar a memória ativa na
|
||||
sessão de chat atual sem editar a configuração:
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
/active-memory off
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
Isso é aplicado no escopo da sessão. Não altera
|
||||
`plugins.entries.active-memory.enabled`, o direcionamento por agente nem outras
|
||||
configurações globais.
|
||||
|
||||
Se você quiser que o comando grave a configuração e pause ou retome a memória ativa para
|
||||
todas as sessões, use a forma global explícita:
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
/active-memory off --global
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
A forma global grava `plugins.entries.active-memory.config.enabled`. Ela deixa
|
||||
`plugins.entries.active-memory.enabled` ativado para que o comando continue disponível
|
||||
para reativar a memória ativa depois.
|
||||
|
||||
Se você quiser ver o que a memória ativa está fazendo em uma sessão ao vivo, ative o
|
||||
modo detalhado para essa sessão:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
Com o modo detalhado ativado, o OpenClaw pode mostrar:
|
||||
|
||||
- uma linha de status da memória ativa como `Active Memory: ok 842ms recent 34 chars`
|
||||
- um resumo de depuração legível como `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
|
||||
Essas linhas são derivadas da mesma passagem de memória ativa que alimenta o contexto
|
||||
oculto do sistema, mas são formatadas para humanos em vez de expor marcação bruta
|
||||
de prompt.
|
||||
|
||||
Por padrão, a transcrição do subagente de memória de bloqueio é temporária e excluída
|
||||
após a conclusão da execução.
|
||||
|
||||
Fluxo de exemplo:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
what wings should i order?
|
||||
```
|
||||
|
||||
Formato de resposta visível esperado:
|
||||
|
||||
```text
|
||||
...normal assistant reply...
|
||||
|
||||
🧩 Active Memory: ok 842ms recent 34 chars
|
||||
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
|
||||
```
|
||||
|
||||
## Quando ela é executada
|
||||
|
||||
A memória ativa usa dois critérios:
|
||||
|
||||
1. **Opt-in de configuração**
|
||||
O plugin deve estar habilitado, e o id do agente atual deve aparecer em
|
||||
`plugins.entries.active-memory.config.agents`.
|
||||
2. **Qualificação estrita em tempo de execução**
|
||||
Mesmo quando habilitada e direcionada, a memória ativa só é executada em
|
||||
sessões de chat persistentes interativas qualificadas.
|
||||
|
||||
A regra real é:
|
||||
|
||||
```text
|
||||
plugin enabled
|
||||
+
|
||||
agent id targeted
|
||||
+
|
||||
allowed chat type
|
||||
+
|
||||
eligible interactive persistent chat session
|
||||
=
|
||||
active memory runs
|
||||
```
|
||||
|
||||
Se qualquer um deles falhar, a memória ativa não será executada.
|
||||
|
||||
## Tipos de sessão
|
||||
|
||||
`config.allowedChatTypes` controla quais tipos de conversas podem executar a Memória
|
||||
ativa de qualquer forma.
|
||||
|
||||
O padrão é:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
Isso significa que a Memória ativa é executada por padrão em sessões no estilo de
|
||||
mensagens diretas, mas não em sessões de grupo ou canal, a menos que você as habilite
|
||||
explicitamente.
|
||||
|
||||
Exemplos:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## Onde ela é executada
|
||||
|
||||
A memória ativa é um recurso de enriquecimento conversacional, não um recurso de
|
||||
inferência para toda a plataforma.
|
||||
|
||||
| Superfície | Executa memória ativa? |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Sessões persistentes da UI de controle / chat web | Sim, se o plugin estiver habilitado e o agente for direcionado |
|
||||
| Outras sessões de canal interativas no mesmo caminho de chat persistente | Sim, se o plugin estiver habilitado e o agente for direcionado |
|
||||
| Execuções avulsas sem interface | Não |
|
||||
| Execuções de heartbeat/background | Não |
|
||||
| Caminhos internos genéricos de `agent-command` | Não |
|
||||
| Execução interna de subagente/helper | Não |
|
||||
|
||||
## Por que usá-la
|
||||
|
||||
Use a memória ativa quando:
|
||||
|
||||
- a sessão for persistente e voltada ao usuário
|
||||
- o agente tiver memória de longo prazo significativa para pesquisar
|
||||
- continuidade e personalização importarem mais do que o determinismo bruto do prompt
|
||||
|
||||
Ela funciona especialmente bem para:
|
||||
|
||||
- preferências estáveis
|
||||
- hábitos recorrentes
|
||||
- contexto de longo prazo do usuário que deve surgir naturalmente
|
||||
|
||||
Ela é pouco adequada para:
|
||||
|
||||
- automação
|
||||
- workers internos
|
||||
- tarefas de API de execução única
|
||||
- lugares em que a personalização oculta seria surpreendente
|
||||
|
||||
## Como ela funciona
|
||||
|
||||
O formato em tempo de execução é:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["User Message"] --> Q["Build Memory Query"]
|
||||
Q --> R["Active Memory Blocking Memory Sub-Agent"]
|
||||
R -->|NONE or empty| M["Main Reply"]
|
||||
R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
O subagente de memória de bloqueio pode usar apenas:
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
Se a conexão estiver fraca, ele deve retornar `NONE`.
|
||||
|
||||
## Modos de consulta
|
||||
|
||||
`config.queryMode` controla quanto da conversa o subagente de memória de bloqueio vê.
|
||||
|
||||
## Estilos de prompt
|
||||
|
||||
`config.promptStyle` controla quão disposto ou rigoroso o subagente de memória de bloqueio é
|
||||
ao decidir se deve retornar memória.
|
||||
|
||||
Estilos disponíveis:
|
||||
|
||||
- `balanced`: padrão de uso geral para o modo `recent`
|
||||
- `strict`: menos disposto; melhor quando você quer muito pouca interferência do contexto próximo
|
||||
- `contextual`: mais favorável à continuidade; melhor quando o histórico da conversa deve importar mais
|
||||
- `recall-heavy`: mais disposto a trazer memória em correspondências mais sutis, mas ainda plausíveis
|
||||
- `precision-heavy`: prefere agressivamente `NONE`, a menos que a correspondência seja óbvia
|
||||
- `preference-only`: otimizado para favoritos, hábitos, rotinas, gostos e fatos pessoais recorrentes
|
||||
|
||||
Mapeamento padrão quando `config.promptStyle` não está definido:
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
Se você definir `config.promptStyle` explicitamente, essa substituição prevalece.
|
||||
|
||||
Exemplo:
|
||||
|
||||
```json5
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## Política de fallback de modelo
|
||||
|
||||
Se `config.model` não estiver definido, a Memória ativa tenta resolver um modelo nesta ordem:
|
||||
|
||||
```text
|
||||
explicit plugin model
|
||||
-> current session model
|
||||
-> agent primary model
|
||||
-> optional built-in remote fallback
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` controla a última etapa.
|
||||
|
||||
Padrão:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
```
|
||||
|
||||
Outra opção:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
|
||||
Use `resolved-only` se quiser que a Memória ativa ignore a recuperação em vez de usar
|
||||
o padrão remoto integrado como fallback quando nenhum modelo explícito ou herdado
|
||||
estiver disponível.
|
||||
|
||||
## Escapes avançados
|
||||
|
||||
Essas opções intencionalmente não fazem parte da configuração recomendada.
|
||||
|
||||
`config.thinking` pode substituir o nível de raciocínio do subagente de memória de bloqueio:
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
```
|
||||
|
||||
Padrão:
|
||||
|
||||
```json5
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
Não habilite isso por padrão. A Memória ativa é executada no caminho da resposta, então tempo
|
||||
extra de raciocínio aumenta diretamente a latência percebida pelo usuário.
|
||||
|
||||
`config.promptAppend` adiciona instruções extras do operador após o prompt padrão da
|
||||
Memória ativa e antes do contexto da conversa:
|
||||
|
||||
```json5
|
||||
promptAppend: "Prefer stable long-term preferences over one-off events."
|
||||
```
|
||||
|
||||
`config.promptOverride` substitui o prompt padrão da Memória ativa. O OpenClaw
|
||||
ainda anexa o contexto da conversa em seguida:
|
||||
|
||||
```json5
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
A personalização do prompt não é recomendada, a menos que você esteja testando
|
||||
deliberadamente um contrato de recuperação diferente. O prompt padrão é ajustado para
|
||||
retornar `NONE` ou um contexto compacto de fatos do usuário para o modelo principal.
|
||||
|
||||
### `message`
|
||||
|
||||
Apenas a mensagem mais recente do usuário é enviada.
|
||||
|
||||
```text
|
||||
Latest user message only
|
||||
```
|
||||
|
||||
Use isso quando:
|
||||
|
||||
- você quiser o comportamento mais rápido
|
||||
- você quiser o viés mais forte em direção à recuperação de preferências estáveis
|
||||
- turnos de acompanhamento não precisarem de contexto conversacional
|
||||
|
||||
Tempo limite recomendado:
|
||||
|
||||
- comece em torno de `3000` a `5000` ms
|
||||
|
||||
### `recent`
|
||||
|
||||
A mensagem mais recente do usuário, mais uma pequena cauda recente da conversa, são enviadas.
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
|
||||
Latest user message:
|
||||
...
|
||||
```
|
||||
|
||||
Use isso quando:
|
||||
|
||||
- você quiser um melhor equilíbrio entre velocidade e contextualização conversacional
|
||||
- perguntas de acompanhamento frequentemente dependerem dos últimos turnos
|
||||
|
||||
Tempo limite recomendado:
|
||||
|
||||
- comece em torno de `15000` ms
|
||||
|
||||
### `full`
|
||||
|
||||
A conversa completa é enviada ao subagente de memória de bloqueio.
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
...
|
||||
```
|
||||
|
||||
Use isso quando:
|
||||
|
||||
- a melhor qualidade de recuperação for mais importante do que a latência
|
||||
- a conversa contiver preparação importante muito antes na thread
|
||||
|
||||
Tempo limite recomendado:
|
||||
|
||||
- aumente-o substancialmente em comparação com `message` ou `recent`
|
||||
- comece em torno de `15000` ms ou mais, dependendo do tamanho da thread
|
||||
|
||||
Em geral, o tempo limite deve aumentar com o tamanho do contexto:
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## Persistência de transcrições
|
||||
|
||||
As execuções do subagente de memória de bloqueio da memória ativa criam uma transcrição real
|
||||
`session.jsonl` durante a chamada do subagente de memória de bloqueio.
|
||||
|
||||
Por padrão, essa transcrição é temporária:
|
||||
|
||||
- ela é gravada em um diretório temporário
|
||||
- ela é usada apenas para a execução do subagente de memória de bloqueio
|
||||
- ela é excluída imediatamente após o término da execução
|
||||
|
||||
Se você quiser manter essas transcrições do subagente de memória de bloqueio em disco para depuração ou
|
||||
inspeção, ative a persistência explicitamente:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
persistTranscripts: true,
|
||||
transcriptDir: "active-memory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Quando habilitada, a memória ativa armazena transcrições em um diretório separado dentro da
|
||||
pasta de sessões do agente de destino, e não no caminho principal da transcrição da conversa
|
||||
do usuário.
|
||||
|
||||
O layout padrão é conceitualmente:
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
Você pode alterar o subdiretório relativo com `config.transcriptDir`.
|
||||
|
||||
Use isso com cuidado:
|
||||
|
||||
- as transcrições do subagente de memória de bloqueio podem se acumular rapidamente em sessões movimentadas
|
||||
- o modo de consulta `full` pode duplicar muito contexto de conversa
|
||||
- essas transcrições contêm contexto oculto de prompt e memórias recuperadas
|
||||
|
||||
## Configuração
|
||||
|
||||
Toda a configuração da memória ativa fica em:
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
Os campos mais importantes são:
|
||||
|
||||
| Chave | Tipo | Significado |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `enabled` | `boolean` | Habilita o próprio plugin |
|
||||
| `config.agents` | `string[]` | IDs de agente que podem usar memória ativa |
|
||||
| `config.model` | `string` | Referência opcional de modelo do subagente de memória de bloqueio; quando não definido, a memória ativa usa o modelo atual da sessão |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla quanto da conversa o subagente de memória de bloqueio vê |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla quão disposto ou rigoroso o subagente de memória de bloqueio é ao decidir se deve retornar memória |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Substituição avançada do nível de raciocínio para o subagente de memória de bloqueio; padrão `off` para velocidade |
|
||||
| `config.promptOverride` | `string` | Substituição avançada completa do prompt; não recomendada para uso normal |
|
||||
| `config.promptAppend` | `string` | Instruções extras avançadas anexadas ao prompt padrão ou substituído |
|
||||
| `config.timeoutMs` | `number` | Tempo limite rígido para o subagente de memória de bloqueio |
|
||||
| `config.maxSummaryChars` | `number` | Máximo de caracteres totais permitidos no resumo da memória ativa |
|
||||
| `config.logging` | `boolean` | Emite logs da memória ativa durante o ajuste fino |
|
||||
| `config.persistTranscripts` | `boolean` | Mantém em disco as transcrições do subagente de memória de bloqueio em vez de excluir arquivos temporários |
|
||||
| `config.transcriptDir` | `string` | Diretório relativo das transcrições do subagente de memória de bloqueio dentro da pasta de sessões do agente |
|
||||
|
||||
Campos úteis para ajuste fino:
|
||||
|
||||
| Chave | Tipo | Significado |
|
||||
| ----------------------------- | -------- | ------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | Máximo de caracteres totais permitidos no resumo da memória ativa |
|
||||
| `config.recentUserTurns` | `number` | Turnos anteriores do usuário a incluir quando `queryMode` é `recent` |
|
||||
| `config.recentAssistantTurns` | `number` | Turnos anteriores do assistente a incluir quando `queryMode` é `recent` |
|
||||
| `config.recentUserChars` | `number` | Máximo de caracteres por turno recente do usuário |
|
||||
| `config.recentAssistantChars` | `number` | Máximo de caracteres por turno recente do assistente |
|
||||
| `config.cacheTtlMs` | `number` | Reutilização de cache para consultas idênticas repetidas |
|
||||
|
||||
## Configuração recomendada
|
||||
|
||||
Comece com `recent`.
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Se você quiser inspecionar o comportamento ao vivo durante o ajuste fino, use `/verbose on` na
|
||||
sessão em vez de procurar um comando de depuração separado da memória ativa.
|
||||
|
||||
Depois passe para:
|
||||
|
||||
- `message` se quiser menor latência
|
||||
- `full` se decidir que o contexto extra vale o subagente de memória de bloqueio mais lento
|
||||
|
||||
## Depuração
|
||||
|
||||
Se a memória ativa não estiver aparecendo onde você espera:
|
||||
|
||||
1. Confirme que o plugin está habilitado em `plugins.entries.active-memory.enabled`.
|
||||
2. Confirme que o id do agente atual está listado em `config.agents`.
|
||||
3. Confirme que você está testando por meio de uma sessão de chat persistente interativa.
|
||||
4. Ative `config.logging: true` e observe os logs do gateway.
|
||||
5. Verifique se a própria pesquisa de memória funciona com `openclaw memory status --deep`.
|
||||
|
||||
Se os resultados de memória estiverem ruidosos, ajuste:
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
Se a memória ativa estiver lenta demais:
|
||||
|
||||
- reduza `queryMode`
|
||||
- reduza `timeoutMs`
|
||||
- reduza as contagens de turnos recentes
|
||||
- reduza os limites de caracteres por turno
|
||||
|
||||
## Páginas relacionadas
|
||||
|
||||
- [Pesquisa de memória](/pt-BR/concepts/memory-search)
|
||||
- [Referência de configuração de memória](/pt-BR/reference/memory-config)
|
||||
- [Configuração do Plugin SDK](/pt-BR/plugins/sdk-setup)
|
||||
@ -1,29 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer entender como o memory_search funciona
|
||||
- Você quer entender como `memory_search` funciona
|
||||
- Você quer escolher um provedor de embeddings
|
||||
- Você quer ajustar a qualidade da busca
|
||||
summary: Como o Memory Search encontra notas relevantes usando embeddings e recuperação híbrida
|
||||
title: Memory Search
|
||||
summary: Como a busca de memória encontra notas relevantes usando embeddings e recuperação híbrida
|
||||
title: Busca de memória
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:33Z"
|
||||
generated_at: "2026-04-10T05:34:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
|
||||
source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
|
||||
source_path: concepts/memory-search.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memory Search
|
||||
# Busca de memória
|
||||
|
||||
`memory_search` encontra notas relevantes nos seus arquivos de memória, mesmo quando a
|
||||
redação difere do texto original. Ele funciona indexando a memória em pequenos
|
||||
trechos e pesquisando neles usando embeddings, palavras-chave ou ambos.
|
||||
`memory_search` encontra notas relevantes dos seus arquivos de memória, mesmo quando a formulação difere do texto original. Ela funciona indexando a memória em pequenos blocos e pesquisando neles usando embeddings, palavras-chave ou ambos.
|
||||
|
||||
## Início rápido
|
||||
|
||||
Se você tiver uma chave de API do OpenAI, Gemini, Voyage ou Mistral configurada, o Memory
|
||||
Search funciona automaticamente. Para definir um provedor explicitamente:
|
||||
Se você tiver uma chave de API da OpenAI, Gemini, Voyage ou Mistral configurada, a busca de memória funciona automaticamente. Para definir um provedor explicitamente:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -37,20 +34,19 @@ Search funciona automaticamente. Para definir um provedor explicitamente:
|
||||
}
|
||||
```
|
||||
|
||||
Para embeddings locais sem chave de API, use `provider: "local"` (requer
|
||||
node-llama-cpp).
|
||||
Para embeddings locais sem chave de API, use `provider: "local"` (requer `node-llama-cpp`).
|
||||
|
||||
## Provedores compatíveis
|
||||
|
||||
| Provedor | ID | Precisa de chave de API | Observações |
|
||||
| -------- | --------- | ----------------------- | ----------------------------------------------------- |
|
||||
| OpenAI | `openai` | Sim | Detectado automaticamente, rápido |
|
||||
| Gemini | `gemini` | Sim | Suporta indexação de imagem/áudio |
|
||||
| Gemini | `gemini` | Sim | Oferece suporte a indexação de imagem/áudio |
|
||||
| Voyage | `voyage` | Sim | Detectado automaticamente |
|
||||
| Mistral | `mistral` | Sim | Detectado automaticamente |
|
||||
| Bedrock | `bedrock` | Não | Detectado automaticamente quando a cadeia de credenciais da AWS é resolvida |
|
||||
| Bedrock | `bedrock` | Não | Detectado automaticamente quando a cadeia de credenciais AWS é resolvida |
|
||||
| Ollama | `ollama` | Não | Local, deve ser definido explicitamente |
|
||||
| Local | `local` | Não | Modelo GGUF, download de ~0.6 GB |
|
||||
| Local | `local` | Não | Modelo GGUF, download de ~0,6 GB |
|
||||
|
||||
## Como a busca funciona
|
||||
|
||||
@ -67,36 +63,30 @@ flowchart LR
|
||||
M --> R["Top Results"]
|
||||
```
|
||||
|
||||
- **Busca vetorial** encontra notas com significado semelhante ("gateway host" corresponde a
|
||||
"a máquina que executa o OpenClaw").
|
||||
- **Busca por palavra-chave BM25** encontra correspondências exatas (IDs, strings de erro, chaves de
|
||||
configuração).
|
||||
- **Busca vetorial** encontra notas com significado semelhante ("gateway host" corresponde a "a máquina que executa o OpenClaw").
|
||||
- **Busca por palavra-chave com BM25** encontra correspondências exatas (IDs, strings de erro, chaves de configuração).
|
||||
|
||||
Se apenas um caminho estiver disponível (sem embeddings ou sem FTS), o outro será executado sozinho.
|
||||
|
||||
## Melhorando a qualidade da busca
|
||||
|
||||
Dois recursos opcionais ajudam quando você tem um grande histórico de notas:
|
||||
Dois recursos opcionais ajudam quando você tem um histórico grande de notas:
|
||||
|
||||
### Decaimento temporal
|
||||
|
||||
Notas antigas perdem gradualmente peso no ranking, para que as informações recentes apareçam primeiro.
|
||||
Com a meia-vida padrão de 30 dias, uma nota do mês passado pontua com 50% do
|
||||
seu peso original. Arquivos perenes como `MEMORY.md` nunca sofrem decaimento.
|
||||
Notas antigas perdem peso gradualmente no ranqueamento para que informações recentes apareçam primeiro.
|
||||
Com a meia-vida padrão de 30 dias, uma nota do mês passado recebe 50% do seu peso original. Arquivos permanentes como `MEMORY.md` nunca sofrem decaimento.
|
||||
|
||||
<Tip>
|
||||
Ative o decaimento temporal se o seu agente tiver meses de notas diárias e informações
|
||||
desatualizadas continuarem superando o contexto recente no ranking.
|
||||
Ative o decaimento temporal se o seu agente tiver meses de notas diárias e informações desatualizadas continuarem superando o contexto recente.
|
||||
</Tip>
|
||||
|
||||
### MMR (diversidade)
|
||||
|
||||
Reduz resultados redundantes. Se cinco notas mencionarem a mesma configuração de roteador, o MMR
|
||||
garante que os principais resultados cubram tópicos diferentes em vez de se repetirem.
|
||||
Reduz resultados redundantes. Se cinco notas mencionam a mesma configuração de roteador, o MMR garante que os principais resultados cubram tópicos diferentes em vez de repetir o mesmo conteúdo.
|
||||
|
||||
<Tip>
|
||||
Ative o MMR se o `memory_search` continuar retornando trechos quase duplicados de
|
||||
notas diárias diferentes.
|
||||
Ative o MMR se `memory_search` continuar retornando trechos quase duplicados de notas diárias diferentes.
|
||||
</Tip>
|
||||
|
||||
### Ativar ambos
|
||||
@ -120,30 +110,22 @@ notas diárias diferentes.
|
||||
|
||||
## Memória multimodal
|
||||
|
||||
Com Gemini Embedding 2, você pode indexar imagens e arquivos de áudio junto com
|
||||
Markdown. As consultas de busca continuam sendo texto, mas correspondem a conteúdo visual e de áudio.
|
||||
Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config) para
|
||||
a configuração.
|
||||
Com o Gemini Embedding 2, você pode indexar imagens e arquivos de áudio junto com Markdown. As consultas de busca continuam sendo texto, mas correspondem ao conteúdo visual e de áudio. Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config) para saber como configurar.
|
||||
|
||||
## Busca na memória de sessão
|
||||
## Busca na memória da sessão
|
||||
|
||||
Opcionalmente, você pode indexar transcrições de sessão para que o `memory_search` possa recuperar
|
||||
conversas anteriores. Isso é opt-in via
|
||||
`memorySearch.experimental.sessionMemory`. Consulte a
|
||||
[referência de configuração](/pt-BR/reference/memory-config) para detalhes.
|
||||
Opcionalmente, você pode indexar transcrições de sessão para que `memory_search` consiga recuperar conversas anteriores. Isso é opcional via `memorySearch.experimental.sessionMemory`. Consulte a [referência de configuração](/pt-BR/reference/memory-config) para mais detalhes.
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
**Sem resultados?** Execute `openclaw memory status` para verificar o índice. Se estiver vazio, execute
|
||||
`openclaw memory index --force`.
|
||||
**Sem resultados?** Execute `openclaw memory status` para verificar o índice. Se estiver vazio, execute `openclaw memory index --force`.
|
||||
|
||||
**Apenas correspondências por palavra-chave?** Seu provedor de embeddings pode não estar configurado. Verifique
|
||||
`openclaw memory status --deep`.
|
||||
**Apenas correspondências por palavra-chave?** Seu provedor de embeddings pode não estar configurado. Verifique com `openclaw memory status --deep`.
|
||||
|
||||
**Texto CJK não encontrado?** Reconstrua o índice FTS com
|
||||
`openclaw memory index --force`.
|
||||
**Texto em CJK não encontrado?** Reconstrua o índice FTS com `openclaw memory index --force`.
|
||||
|
||||
## Leitura adicional
|
||||
|
||||
- [Memory](/pt-BR/concepts/memory) -- layout de arquivos, backends, ferramentas
|
||||
- [referência de configuração de memória](/pt-BR/reference/memory-config) -- todos os parâmetros de configuração
|
||||
- [Memória ativa](/pt-BR/concepts/active-memory) -- memória de subagente para sessões de chat interativas
|
||||
- [Memória](/pt-BR/concepts/memory) -- layout de arquivos, backends, ferramentas
|
||||
- [Referência de configuração de memória](/pt-BR/reference/memory-config) -- todas as opções de configuração
|
||||
|
||||
@ -1,37 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- Ao estender qa-lab ou qa-channel
|
||||
- Ao adicionar cenários de QA com suporte do repositório
|
||||
- Ao criar uma automação de QA mais realista em torno do Dashboard do Gateway
|
||||
summary: Estrutura privada de automação de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo
|
||||
- Estendendo qa-lab ou qa-channel
|
||||
- Adicionando cenários de QA com suporte do repositório
|
||||
- Criando automação de QA com maior realismo em torno do painel do Gateway
|
||||
summary: Formato privado de automação de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo
|
||||
title: Automação E2E de QA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:38Z"
|
||||
generated_at: "2026-04-10T05:34:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
|
||||
source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automação E2E de QA
|
||||
|
||||
A stack privada de QA foi projetada para exercitar o OpenClaw de uma forma mais realista,
|
||||
com formato de canal, do que um único teste de unidade consegue.
|
||||
A pilha privada de QA foi projetada para exercitar o OpenClaw de uma forma mais realista,
|
||||
no formato de canal, do que um único teste unitário consegue.
|
||||
|
||||
Componentes atuais:
|
||||
Peças 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,
|
||||
- `extensions/qa-lab`: interface de depuração e barramento de QA para observar a transcrição,
|
||||
injetar mensagens de entrada e exportar um relatório em Markdown.
|
||||
- `qa/`: recursos seed com suporte do repositório para a tarefa inicial e cenários
|
||||
- `qa/`: ativos de seed com suporte do repositório para a tarefa inicial e cenários
|
||||
básicos de QA.
|
||||
|
||||
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: Dashboard do Gateway (Control UI) com o agente.
|
||||
- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano do cenário.
|
||||
- Esquerda: painel do Gateway (Control UI) com o agente.
|
||||
- Direita: QA Lab, mostrando a transcrição no estilo do Slack e o plano de cenário.
|
||||
|
||||
Execute com:
|
||||
|
||||
@ -39,13 +39,13 @@ Execute com:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Isso compila o site de QA, inicia a lane do gateway com suporte do 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 com suporte do 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 na UI do QA Lab sem recompilar a imagem Docker a cada vez,
|
||||
inicie a stack com um bundle do QA Lab montado por bind:
|
||||
inicie a pilha com um bundle do QA Lab montado por bind:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -56,32 +56,47 @@ pnpm qa:lab:watch
|
||||
|
||||
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind-mount de
|
||||
`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch`
|
||||
recompila esse bundle quando há alterações, e o navegador recarrega automaticamente quando o hash
|
||||
dos recursos do QA Lab muda.
|
||||
recompila esse bundle quando há mudanças, e o navegador recarrega automaticamente quando o hash
|
||||
do ativo do QA Lab muda.
|
||||
|
||||
Para uma faixa descartável em VM Linux sem colocar o Docker no caminho do QA, execute:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Isso inicializa um guest novo do Multipass, instala as dependências, compila o OpenClaw
|
||||
dentro do guest, executa `qa suite` e depois copia o relatório normal de QA e o
|
||||
resumo de volta para `.artifacts/qa-e2e/...` no host.
|
||||
Ele reutiliza o mesmo comportamento de seleção de cenário que `qa suite` no host.
|
||||
Execuções ao vivo encaminham as entradas de autenticação de QA compatíveis que são práticas para o
|
||||
guest: chaves de provedor baseadas em ambiente, o caminho de configuração do provedor ao vivo de QA e
|
||||
`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest
|
||||
possa gravar de volta por meio do workspace montado.
|
||||
|
||||
## Seeds com suporte do repositório
|
||||
|
||||
Os recursos seed ficam em `qa/`:
|
||||
Os ativos de seed ficam em `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
|
||||
Eles ficam intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
|
||||
Eles estão intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
|
||||
agente. A lista básica deve permanecer ampla o suficiente para cobrir:
|
||||
|
||||
- conversa por DM e em canal
|
||||
- chat em DM e em canal
|
||||
- comportamento de thread
|
||||
- ciclo de vida das ações de mensagem
|
||||
- ciclo de vida de ações de mensagem
|
||||
- callbacks de cron
|
||||
- recuperação de memória
|
||||
- troca de modelo
|
||||
- handoff para subagente
|
||||
- leitura do repositório e da documentação
|
||||
- uma pequena tarefa de compilação, como Lobster Invaders
|
||||
- leitura do repositório e leitura da documentação
|
||||
- uma pequena tarefa de build, como Lobster Invaders
|
||||
|
||||
## Relatórios
|
||||
|
||||
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado.
|
||||
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento.
|
||||
O relatório deve responder:
|
||||
|
||||
- O que funcionou
|
||||
@ -89,7 +104,7 @@ O relatório deve responder:
|
||||
- O que permaneceu bloqueado
|
||||
- Quais cenários de acompanhamento valem a pena adicionar
|
||||
|
||||
Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelo reais
|
||||
Para verificações de personalidade e estilo, execute o mesmo cenário em várias refs de modelo ao vivo
|
||||
e escreva um relatório em Markdown avaliado:
|
||||
|
||||
```bash
|
||||
@ -109,31 +124,31 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
O comando executa processos filho locais do gateway de QA, não Docker. Os cenários de avaliação de caráter
|
||||
O comando executa processos filhos locais do gateway de QA, não Docker. Os cenários de avaliação de personalidade
|
||||
devem definir a persona por meio de `SOUL.md` e depois executar turnos normais de usuário,
|
||||
como conversa, ajuda no workspace e pequenas tarefas com arquivos. Não se deve dizer ao modelo
|
||||
candidato que ele 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 fast com
|
||||
raciocínio `xhigh` que classifiquem as execuções por naturalidade, vibe e humor.
|
||||
Use `--blind-judge-models` ao comparar providers: o prompt do juiz ainda recebe
|
||||
cada transcrição e status da 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 o
|
||||
parse.
|
||||
As execuções dos candidatos usam `high` thinking por padrão, com `xhigh` para modelos OpenAI que
|
||||
oferecem suporte a isso. Substitua um candidato específico inline com
|
||||
como chat, ajuda com o workspace e pequenas tarefas em arquivos. Não se deve informar ao
|
||||
modelo candidato que ele 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` 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 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.
|
||||
As execuções candidatas usam `high` thinking por padrão, com `xhigh` para modelos OpenAI que
|
||||
o suportam. Substitua um candidato específico inline com
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` ainda define um
|
||||
fallback global, e o formato antigo `--model-thinking <provider/model=level>` é
|
||||
mantido por compatibilidade.
|
||||
As refs candidatas da OpenAI usam modo fast por padrão para que o processamento prioritário seja usado quando
|
||||
o provider oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um
|
||||
único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser
|
||||
forçar o modo fast para todos os modelos candidatos. As durações dos candidatos e dos 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 dos modelos candidatos e juízes usam simultaneidade 16 por padrão. Reduza
|
||||
`--concurrency` ou `--judge-concurrency` quando limites do provider ou pressão no gateway local
|
||||
As refs candidatas da OpenAI usam o modo rápido por padrão para que o processamento prioritário seja usado onde
|
||||
o provedor o suportar. Adicione `,fast`, `,no-fast` ou `,fast=false` inline 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 comparativa, mas os prompts dos juízes dizem explicitamente
|
||||
para não classificar por velocidade.
|
||||
As execuções de modelos candidatos e juízes usam simultaneidade 16 por padrão. Reduza
|
||||
`--concurrency` ou `--judge-concurrency` quando os limites do provedor ou a pressão no gateway local
|
||||
tornarem uma execução barulhenta demais.
|
||||
Quando nenhum `--model` candidato é passado, a avaliação de caráter usa por padrão
|
||||
Quando nenhum candidato `--model` é passado, a avaliação de personalidade usa por padrão
|
||||
`openai/gpt-5.4`, `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
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,83 +1,94 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer configurar provedores de busca em memória ou modelos de embedding
|
||||
- Você quer configurar provedores de pesquisa de memória ou modelos de embedding
|
||||
- Você quer configurar o backend QMD
|
||||
- Você quer ajustar busca híbrida, MMR ou decaimento temporal
|
||||
- Você quer ativar indexação de memória multimodal
|
||||
summary: Todos os ajustes de configuração para busca em memória, provedores de embedding, QMD, busca híbrida e indexação multimodal
|
||||
- Você quer ajustar a pesquisa híbrida, MMR ou o decaimento temporal
|
||||
- Você quer habilitar a indexação de memória multimodal
|
||||
summary: Todos os parâmetros de configuração para pesquisa de memória, provedores de embedding, QMD, pesquisa híbrida e indexação multimodal
|
||||
title: Referência de configuração de memória
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:12:13Z"
|
||||
generated_at: "2026-04-10T05:34:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
|
||||
source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Referência de configuração de memória
|
||||
|
||||
Esta página lista todos os ajustes de configuração para a busca em memória do OpenClaw. Para
|
||||
visões gerais conceituais, consulte:
|
||||
Esta página lista todos os parâmetros de configuração para a pesquisa de memória do OpenClaw. Para visões conceituais gerais, consulte:
|
||||
|
||||
- [Visão geral da memória](/pt-BR/concepts/memory) -- como a memória funciona
|
||||
- [Mecanismo builtin](/pt-BR/concepts/memory-builtin) -- backend SQLite padrão
|
||||
- [Mecanismo integrado](/pt-BR/concepts/memory-builtin) -- backend SQLite padrão
|
||||
- [Mecanismo QMD](/pt-BR/concepts/memory-qmd) -- sidecar local-first
|
||||
- [Busca em memória](/pt-BR/concepts/memory-search) -- pipeline de busca e ajuste
|
||||
- [Pesquisa de memória](/pt-BR/concepts/memory-search) -- pipeline de pesquisa e ajuste
|
||||
- [Memória ativa](/pt-BR/concepts/active-memory) -- como habilitar o subagente de memória para sessões interativas
|
||||
|
||||
Todas as configurações de busca em memória ficam em `agents.defaults.memorySearch` no
|
||||
`openclaw.json`, salvo indicação em contrário.
|
||||
Todas as configurações de pesquisa de memória ficam em `agents.defaults.memorySearch` no `openclaw.json`, salvo indicação em contrário.
|
||||
|
||||
Se você estiver procurando a alternância de recurso de **memória ativa** e a configuração do subagente,
|
||||
ela fica em `plugins.entries.active-memory` em vez de `memorySearch`.
|
||||
|
||||
A memória ativa usa um modelo de duas etapas:
|
||||
|
||||
1. o plugin deve estar habilitado e apontar para o ID do agente atual
|
||||
2. a solicitação deve ser uma sessão de chat interativa persistente elegível
|
||||
|
||||
Consulte [Memória ativa](/pt-BR/concepts/active-memory) para ver o modelo de ativação,
|
||||
a configuração pertencente ao plugin, a persistência de transcrição e o padrão de implantação segura.
|
||||
|
||||
---
|
||||
|
||||
## Seleção de provedor
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------- | --------- | -------------- | --------------------------------------------------------------------------------------------- |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------- | --------- | --------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | detectado automaticamente | ID do adaptador de embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `model` | `string` | padrão do provedor | Nome do modelo de embedding |
|
||||
| `fallback` | `string` | `"none"` | ID do adaptador de fallback quando o primário falha |
|
||||
| `enabled` | `boolean` | `true` | Ativa ou desativa a busca em memória |
|
||||
| `model` | `string` | padrão do provedor | Nome do modelo de embedding |
|
||||
| `fallback` | `string` | `"none"` | ID do adaptador de fallback quando o principal falha |
|
||||
| `enabled` | `boolean` | `true` | Habilita ou desabilita a pesquisa de memória |
|
||||
|
||||
### Ordem de detecção automática
|
||||
|
||||
Quando `provider` não está definido, o OpenClaw seleciona o primeiro disponível:
|
||||
Quando `provider` não é definido, o OpenClaw seleciona o primeiro disponível:
|
||||
|
||||
1. `local` -- se `memorySearch.local.modelPath` estiver configurado e o arquivo existir.
|
||||
2. `openai` -- se uma chave OpenAI puder ser resolvida.
|
||||
3. `gemini` -- se uma chave Gemini puder ser resolvida.
|
||||
4. `voyage` -- se uma chave Voyage puder ser resolvida.
|
||||
5. `mistral` -- se uma chave Mistral puder ser resolvida.
|
||||
6. `bedrock` -- se a cadeia de credenciais do SDK da AWS puder ser resolvida (role de instância, chaves de acesso, profile, SSO, web identity ou configuração compartilhada).
|
||||
6. `bedrock` -- se a cadeia de credenciais padrão do AWS SDK for resolvida (função da instância, chaves de acesso, perfil, SSO, web identity ou configuração compartilhada).
|
||||
|
||||
`ollama` é compatível, mas não é detectado automaticamente (defina-o explicitamente).
|
||||
|
||||
### Resolução de chave de API
|
||||
|
||||
Embeddings remotos exigem uma chave de API. O Bedrock usa a cadeia padrão de
|
||||
credenciais do SDK da AWS em vez disso (roles de instância, SSO, chaves de acesso).
|
||||
Embeddings remotos exigem uma chave de API. O Bedrock usa a cadeia de
|
||||
credenciais padrão do AWS SDK no lugar disso (funções de instância, SSO, chaves de acesso).
|
||||
|
||||
| Provedor | Variável env | Chave de configuração |
|
||||
| -------- | ----------------------------- | ---------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | cadeia de credenciais AWS | Nenhuma chave de API necessária |
|
||||
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
|
||||
| Provedor | Variável de ambiente | Chave de configuração |
|
||||
| -------- | ----------------------------- | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | cadeia de credenciais AWS | Nenhuma chave de API necessária |
|
||||
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
|
||||
|
||||
O OAuth do Codex cobre apenas chat/completions e não atende requisições de embedding.
|
||||
O OAuth do Codex cobre apenas chat/completions e não atende a solicitações
|
||||
de embedding.
|
||||
|
||||
---
|
||||
|
||||
## Configuração de endpoint remoto
|
||||
|
||||
Para endpoints custom compatíveis com OpenAI ou para substituir padrões do provedor:
|
||||
Para endpoints compatíveis com OpenAI personalizados ou para substituir os padrões do provedor:
|
||||
|
||||
| Chave | Tipo | Descrição |
|
||||
| ---------------- | -------- | --------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | Base URL custom da API |
|
||||
| `remote.apiKey` | `string` | Substitui a chave de API |
|
||||
| Chave | Tipo | Descrição |
|
||||
| ---------------- | -------- | ------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | URL base da API personalizada |
|
||||
| `remote.apiKey` | `string` | Substitui a chave de API |
|
||||
| `remote.headers` | `object` | Cabeçalhos HTTP extras (mesclados com os padrões do provedor) |
|
||||
|
||||
```json5
|
||||
@ -101,21 +112,21 @@ Para endpoints custom compatíveis com OpenAI ou para substituir padrões do pro
|
||||
|
||||
## Configuração específica do Gemini
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------- |
|
||||
| `model` | `string` | `gemini-embedding-001` | Também oferece suporte a `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Para Embedding 2: 768, 1536 ou 3072 |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------- | -------- | ---------------------- | -------------------------------------------- |
|
||||
| `model` | `string` | `gemini-embedding-001` | Também é compatível com `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Para Embedding 2: 768, 1536 ou 3072 |
|
||||
|
||||
<Warning>
|
||||
Alterar `model` ou `outputDimensionality` dispara uma reindexação completa automática.
|
||||
Alterar o modelo ou `outputDimensionality` aciona automaticamente uma reindexação completa.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Configuração de embedding do Bedrock
|
||||
|
||||
O Bedrock usa a cadeia padrão de credenciais do SDK da AWS -- nenhuma chave de API é necessária.
|
||||
Se o OpenClaw estiver sendo executado no EC2 com uma role de instância habilitada para Bedrock, basta definir o
|
||||
O Bedrock usa a cadeia de credenciais padrão do AWS SDK -- nenhuma chave de API é necessária.
|
||||
Se o OpenClaw estiver em execução no EC2 com uma função de instância habilitada para Bedrock, basta definir o
|
||||
provedor e o modelo:
|
||||
|
||||
```json5
|
||||
@ -131,35 +142,35 @@ provedor e o modelo:
|
||||
}
|
||||
```
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------- | -------- | ------------------------------ | ---------------------------------- |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------- | -------- | ----------------------------- | ------------------------------------ |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualquer ID de modelo de embedding do Bedrock |
|
||||
| `outputDimensionality` | `number` | padrão do modelo | Para Titan V2: 256, 512 ou 1024 |
|
||||
| `outputDimensionality` | `number` | padrão do modelo | Para Titan V2: 256, 512 ou 1024 |
|
||||
|
||||
### Modelos compatíveis
|
||||
|
||||
Os seguintes modelos são compatíveis (com detecção de família e dimensões
|
||||
padrão):
|
||||
Os modelos a seguir são compatíveis (com detecção de família e padrões de
|
||||
dimensão):
|
||||
|
||||
| ID do modelo | Provedor | Dims padrão | Dims configuráveis |
|
||||
| ------------------------------------------- | ---------- | ----------- | --------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
| ID do modelo | Provedor | Dims padrão | Dims configuráveis |
|
||||
| ------------------------------------------ | ---------- | ----------- | -------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
|
||||
Variantes com sufixo de throughput (por exemplo, `amazon.titan-embed-text-v1:2:8k`) herdam
|
||||
a configuração do modelo base.
|
||||
|
||||
### Autenticação
|
||||
|
||||
A autenticação do Bedrock usa a ordem padrão de resolução de credenciais do SDK da AWS:
|
||||
A autenticação do Bedrock usa a ordem padrão de resolução de credenciais do AWS SDK:
|
||||
|
||||
1. Variáveis de ambiente (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
2. Cache de token SSO
|
||||
@ -167,12 +178,12 @@ A autenticação do Bedrock usa a ordem padrão de resolução de credenciais do
|
||||
4. Arquivos compartilhados de credenciais e configuração
|
||||
5. Credenciais de metadados ECS ou EC2
|
||||
|
||||
A região é resolvida a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, da
|
||||
`baseUrl` do provedor `amazon-bedrock` ou assume o padrão `us-east-1`.
|
||||
A região é resolvida a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, do
|
||||
`baseUrl` do provedor `amazon-bedrock` ou, por padrão, `us-east-1`.
|
||||
|
||||
### Permissões IAM
|
||||
|
||||
A role ou usuário IAM precisa de:
|
||||
A função ou o usuário IAM precisa de:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -182,7 +193,7 @@ A role ou usuário IAM precisa de:
|
||||
}
|
||||
```
|
||||
|
||||
Para privilégio mínimo, limite `InvokeModel` ao modelo específico:
|
||||
Para privilégio mínimo, restrinja `InvokeModel` ao modelo específico:
|
||||
|
||||
```
|
||||
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
@ -198,33 +209,33 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
| `local.modelCacheDir` | `string` | padrão do node-llama-cpp | Diretório de cache para modelos baixados |
|
||||
|
||||
Modelo padrão: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, baixado automaticamente).
|
||||
Exige build nativa: `pnpm approve-builds` e depois `pnpm rebuild node-llama-cpp`.
|
||||
Exige build nativo: `pnpm approve-builds` e depois `pnpm rebuild node-llama-cpp`.
|
||||
|
||||
---
|
||||
|
||||
## Configuração de busca híbrida
|
||||
## Configuração de pesquisa híbrida
|
||||
|
||||
Tudo em `memorySearch.query.hybrid`:
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| --------------------- | --------- | ------ | -------------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Ativa a busca híbrida BM25 + vetorial |
|
||||
| `enabled` | `boolean` | `true` | Habilita a pesquisa híbrida BM25 + vetorial |
|
||||
| `vectorWeight` | `number` | `0.7` | Peso para pontuações vetoriais (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Peso para pontuações BM25 (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Multiplicador do tamanho do pool de candidatos |
|
||||
| `candidateMultiplier` | `number` | `4` | Multiplicador do tamanho do conjunto de candidatos |
|
||||
|
||||
### MMR (diversidade)
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------- | --------- | ------ | ---------------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | Ativa reclassificação MMR |
|
||||
| `mmr.enabled` | `boolean` | `false` | Habilita a reclassificação MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = diversidade máxima, 1 = relevância máxima |
|
||||
|
||||
### Decaimento temporal (recência)
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------------- | --------- | ------ | --------------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Ativa impulso de recência |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------------- | --------- | ------ | ---------------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Habilita o impulso por recência |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | A pontuação cai pela metade a cada N dias |
|
||||
|
||||
Arquivos perenes (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem decaimento.
|
||||
@ -254,8 +265,8 @@ Arquivos perenes (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem deca
|
||||
|
||||
## Caminhos de memória adicionais
|
||||
|
||||
| Chave | Tipo | Descrição |
|
||||
| ------------ | ---------- | ----------------------------------------- |
|
||||
| Chave | Tipo | Descrição |
|
||||
| ----------- | ---------- | ------------------------------------------- |
|
||||
| `extraPaths` | `string[]` | Diretórios ou arquivos adicionais para indexar |
|
||||
|
||||
```json5
|
||||
@ -271,18 +282,18 @@ Arquivos perenes (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem deca
|
||||
```
|
||||
|
||||
Os caminhos podem ser absolutos ou relativos ao workspace. Diretórios são varridos
|
||||
recursivamente em busca de arquivos `.md`. O tratamento de symlink depende do backend ativo:
|
||||
o mecanismo builtin ignora symlinks, enquanto o QMD segue o comportamento subjacente
|
||||
do scanner do QMD.
|
||||
recursivamente em busca de arquivos `.md`. O tratamento de symlinks depende do backend ativo:
|
||||
o mecanismo integrado ignora symlinks, enquanto o QMD segue o comportamento do scanner
|
||||
QMD subjacente.
|
||||
|
||||
Para busca de transcrições entre agentes com escopo de agente, use
|
||||
Para pesquisa de transcrições entre agentes com escopo por agente, use
|
||||
`agents.list[].memorySearch.qmd.extraCollections` em vez de `memory.qmd.paths`.
|
||||
Essas coleções extras seguem o mesmo formato `{ path, name, pattern? }`, mas
|
||||
são mescladas por agente e podem preservar nomes compartilhados explícitos quando o caminho
|
||||
aponta para fora do workspace atual.
|
||||
Se o mesmo caminho resolvido aparecer em `memory.qmd.paths` e
|
||||
Se o mesmo caminho resolvido aparecer tanto em `memory.qmd.paths` quanto em
|
||||
`memorySearch.qmd.extraCollections`, o QMD mantém a primeira entrada e ignora a
|
||||
duplicada.
|
||||
duplicata.
|
||||
|
||||
---
|
||||
|
||||
@ -290,13 +301,13 @@ duplicada.
|
||||
|
||||
Indexe imagens e áudio junto com Markdown usando Gemini Embedding 2:
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------- | ---------- | ---------- | ------------------------------------------ |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Ativa indexação multimodal |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Tamanho máximo de arquivo para indexação |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------- | ---------- | ---------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Habilita a indexação multimodal |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Tamanho máximo de arquivo para indexação |
|
||||
|
||||
Aplica-se apenas a arquivos em `extraPaths`. As raízes de memória padrão continuam apenas com Markdown.
|
||||
Aplica-se apenas a arquivos em `extraPaths`. As raízes de memória padrão continuam sendo somente Markdown.
|
||||
Exige `gemini-embedding-2-preview`. `fallback` deve ser `"none"`.
|
||||
|
||||
Formatos compatíveis: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
@ -306,117 +317,117 @@ Formatos compatíveis: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif
|
||||
|
||||
## Cache de embedding
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------ | --------- | ------ | ---------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Armazena embeddings de chunks em cache no SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings em cache |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------ | --------- | ------ | ------------------------------------ |
|
||||
| `cache.enabled` | `boolean` | `false` | Armazena em cache embeddings de chunks no SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings em cache |
|
||||
|
||||
Evita refazer embeddings de texto inalterado durante reindexação ou atualizações de transcrição.
|
||||
Evita recalcular embeddings de texto inalterado durante reindexação ou atualizações de transcrição.
|
||||
|
||||
---
|
||||
|
||||
## Indexação em lote
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ----------------------------- | --------- | ------ | --------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Ativa API de embedding em lote |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Trabalhos em lote paralelos |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Aguarda a conclusão do lote |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de polling |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Timeout do lote |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ----------------------------- | --------- | ------ | ------------------------------ |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Habilita a API de embedding em lote |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Trabalhos em lote paralelos |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Aguarda a conclusão do lote |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de polling |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Tempo limite do lote |
|
||||
|
||||
Disponível para `openai`, `gemini` e `voyage`. O lote do OpenAI normalmente é
|
||||
o mais rápido e barato para grandes preenchimentos retroativos.
|
||||
Disponível para `openai`, `gemini` e `voyage`. O lote do OpenAI geralmente é o
|
||||
mais rápido e barato para grandes preenchimentos retroativos.
|
||||
|
||||
---
|
||||
|
||||
## Busca em memória de sessão (experimental)
|
||||
## Pesquisa de memória de sessão (experimental)
|
||||
|
||||
Indexe transcrições de sessão e exponha-as via `memory_search`:
|
||||
Indexe transcrições de sessão e as exponha via `memory_search`:
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| --------------------------- | ---------- | ------------ | ------------------------------------------ |
|
||||
| `experimental.sessionMemory`| `boolean` | `false` | Ativa indexação de sessão |
|
||||
| `sources` | `string[]` | `["memory"]` | Adicione `"sessions"` para incluir transcrições |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Limite de bytes para reindexação |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Limite de mensagens para reindexação |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ----------------------------- | ---------- | ------------ | ---------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Habilita a indexação de sessão |
|
||||
| `sources` | `string[]` | `["memory"]` | Adicione `"sessions"` para incluir transcrições |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Limite de bytes para reindexação |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Limite de mensagens para reindexação |
|
||||
|
||||
A indexação de sessão é opt-in e é executada de forma assíncrona. Os resultados podem estar
|
||||
ligeiramente desatualizados. Os logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos como o
|
||||
limite de confiança.
|
||||
A indexação de sessão é opt-in e é executada de forma assíncrona. Os resultados podem ficar
|
||||
ligeiramente desatualizados. Os logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos
|
||||
como o limite de confiança.
|
||||
|
||||
---
|
||||
|
||||
## Aceleração vetorial SQLite (sqlite-vec)
|
||||
## Aceleração vetorial do SQLite (sqlite-vec)
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ---------------------------- | --------- | ------- | ---------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec para consultas vetoriais |
|
||||
| `store.vector.extensionPath` | `string` | empacotado | Substitui o caminho do sqlite-vec |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| -------------------------- | --------- | ------ | ------------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec para consultas vetoriais |
|
||||
| `store.vector.extensionPath` | `string` | bundled | Substitui o caminho do sqlite-vec |
|
||||
|
||||
Quando o sqlite-vec não está disponível, o OpenClaw recorre automaticamente à
|
||||
similaridade de cosseno em processo.
|
||||
|
||||
---
|
||||
|
||||
## Armazenamento do índice
|
||||
## Armazenamento de índice
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------- | -------- | ------------------------------------ | ---------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Localização do índice (oferece suporte ao token `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` ou `trigram`) |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| --------------------- | -------- | ------------------------------------ | --------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Local do índice (compatível com o token `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizador FTS5 (`unicode61` ou `trigram`) |
|
||||
|
||||
---
|
||||
|
||||
## Configuração do backend QMD
|
||||
|
||||
Defina `memory.backend = "qmd"` para ativar. Todas as configurações do QMD ficam em
|
||||
Defina `memory.backend = "qmd"` para habilitar. Todas as configurações de QMD ficam em
|
||||
`memory.qmd`:
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------ | --------- | -------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Caminho do executável QMD |
|
||||
| `searchMode` | `string` | `search` | Comando de busca: `search`, `vsearch`, `query` |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------ | --------- | -------- | ---------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Caminho do executável do QMD |
|
||||
| `searchMode` | `string` | `search` | Comando de pesquisa: `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Indexa automaticamente `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Caminhos extras: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indexa transcrições de sessão |
|
||||
| `sessions.retentionDays` | `number` | -- | Retenção de transcrições |
|
||||
| `sessions.exportDir` | `string` | -- | Diretório de exportação |
|
||||
| `paths[]` | `array` | -- | Caminhos extras: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indexa transcrições de sessão |
|
||||
| `sessions.retentionDays` | `number` | -- | Retenção de transcrições |
|
||||
| `sessions.exportDir` | `string` | -- | Diretório de exportação |
|
||||
|
||||
O OpenClaw prefere os formatos atuais de coleção do QMD e de consulta MCP, mas mantém
|
||||
releases mais antigos do QMD funcionando ao recorrer às flags legadas de coleção `--mask`
|
||||
e a nomes antigos de ferramentas MCP quando necessário.
|
||||
O OpenClaw prefere os formatos atuais de coleção QMD e de consulta MCP, mas mantém
|
||||
lançamentos mais antigos do QMD funcionando ao recorrer a flags legadas de coleção `--mask`
|
||||
e nomes mais antigos de ferramentas MCP quando necessário.
|
||||
|
||||
As substituições de modelo do QMD ficam do lado do QMD, não na configuração do OpenClaw. Se você precisar
|
||||
As substituições de modelo do QMD ficam no lado do QMD, não na configuração do OpenClaw. Se você precisar
|
||||
substituir os modelos do QMD globalmente, defina variáveis de ambiente como
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` no ambiente de
|
||||
runtime do gateway.
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` no ambiente de execução
|
||||
do gateway.
|
||||
|
||||
### Agenda de atualização
|
||||
### Agendamento de atualização
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------- | --------- | ------- | ---------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Intervalo de atualização |
|
||||
| `update.debounceMs` | `number` | `15000` | Debounce de alterações de arquivo |
|
||||
| `update.onBoot` | `boolean` | `true` | Atualiza na inicialização |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Bloqueia a inicialização até a atualização terminar |
|
||||
| `update.embedInterval` | `string` | -- | Cadência separada de embeddings |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Timeout para comandos QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Timeout para operações `qmd update` |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Timeout para operações `qmd embed` |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------- | --------- | ------ | ----------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Intervalo de atualização |
|
||||
| `update.debounceMs` | `number` | `15000` | Debounce para alterações de arquivos |
|
||||
| `update.onBoot` | `boolean` | `true` | Atualiza na inicialização |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Bloqueia a inicialização até a atualização ser concluída |
|
||||
| `update.embedInterval` | `string` | -- | Cadência separada para embeddings |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Tempo limite para comandos QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Tempo limite para operações de atualização do QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Tempo limite para operações de embedding do QMD |
|
||||
|
||||
### Limites
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ------------------------- | -------- | ------ | ------------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | Máximo de resultados de busca |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Limita o tamanho do trecho |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Limita o total de caracteres injetados |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Timeout da busca |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ----------------------- | -------- | ------ | ----------------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | Máximo de resultados de pesquisa |
|
||||
| `limits.maxSnippetChars`| `number` | -- | Limita o tamanho do trecho |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Limita o total de caracteres injetados |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Tempo limite de pesquisa |
|
||||
|
||||
### Escopo
|
||||
|
||||
Controla quais sessões podem receber resultados de busca do QMD. Mesmo schema de
|
||||
Controla quais sessões podem receber resultados de pesquisa do QMD. Mesmo esquema de
|
||||
[`session.sendPolicy`](/pt-BR/gateway/configuration-reference#session):
|
||||
|
||||
```json5
|
||||
@ -432,17 +443,17 @@ Controla quais sessões podem receber resultados de busca do QMD. Mesmo schema d
|
||||
}
|
||||
```
|
||||
|
||||
O padrão é apenas DM. `match.keyPrefix` corresponde à chave de sessão normalizada;
|
||||
`match.rawKeyPrefix` corresponde à chave bruta incluindo `agent:<id>:`.
|
||||
O padrão é somente DM. `match.keyPrefix` corresponde à chave de sessão normalizada;
|
||||
`match.rawKeyPrefix` corresponde à chave bruta, incluindo `agent:<id>:`.
|
||||
|
||||
### Citações
|
||||
|
||||
`memory.citations` aplica-se a todos os backends:
|
||||
`memory.citations` se aplica a todos os backends:
|
||||
|
||||
| Valor | Comportamento |
|
||||
| ---------------- | ----------------------------------------------------- |
|
||||
| `auto` (padrão) | Inclui rodapé `Source: <path#line>` nos trechos |
|
||||
| `on` | Sempre inclui o rodapé |
|
||||
| Valor | Comportamento |
|
||||
| ---------------- | ------------------------------------------------- |
|
||||
| `auto` (padrão) | Inclui o rodapé `Source: <path#line>` nos trechos |
|
||||
| `on` | Sempre inclui o rodapé |
|
||||
| `off` | Omite o rodapé (o caminho ainda é passado internamente ao agente) |
|
||||
|
||||
### Exemplo completo de QMD
|
||||
@ -470,20 +481,20 @@ O padrão é apenas DM. `match.keyPrefix` corresponde à chave de sessão normal
|
||||
|
||||
## Dreaming (experimental)
|
||||
|
||||
Dreaming é configurado em `plugins.entries.memory-core.config.dreaming`,
|
||||
O Dreaming é configurado em `plugins.entries.memory-core.config.dreaming`,
|
||||
não em `agents.defaults.memorySearch`.
|
||||
|
||||
O Dreaming é executado como uma única varredura agendada e usa fases internas light/deep/REM como
|
||||
detalhe de implementação.
|
||||
um detalhe de implementação.
|
||||
|
||||
Para comportamento conceitual e comandos slash, consulte [Dreaming](/concepts/dreaming).
|
||||
Para comportamento conceitual e comandos de barra, consulte [Dreaming](/pt-BR/concepts/dreaming).
|
||||
|
||||
### Configurações do usuário
|
||||
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ----------- | --------- | ----------- | ---------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Ativa ou desativa totalmente o dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Cadência cron opcional para a varredura completa de dreaming |
|
||||
| Chave | Tipo | Padrão | Descrição |
|
||||
| ----------- | --------- | ----------- | ------------------------------------------------ |
|
||||
| `enabled` | `boolean` | `false` | Habilita ou desabilita completamente o Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Cadência cron opcional para a varredura completa do Dreaming |
|
||||
|
||||
### Exemplo
|
||||
|
||||
@ -507,5 +518,5 @@ Para comportamento conceitual e comandos slash, consulte [Dreaming](/concepts/dr
|
||||
Observações:
|
||||
|
||||
- O Dreaming grava o estado da máquina em `memory/.dreams/`.
|
||||
- O Dreaming grava a saída narrativa legível por humanos em `DREAMS.md` (ou em um `dreams.md` existente).
|
||||
- A política e os limites das fases light/deep/REM são comportamento interno, não configuração voltada ao usuário.
|
||||
- O Dreaming grava saída narrativa legível por humanos em `DREAMS.md` (ou no `dreams.md` existente).
|
||||
- A política de fases light/deep/REM e os limites são comportamentos internos, não configurações voltadas ao usuário.
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Adicionando automação de navegador controlada pelo agente
|
||||
- Adicionando automação do navegador controlada pelo agente
|
||||
- Depurando por que o openclaw está interferindo no seu próprio Chrome
|
||||
- Implementando configurações + ciclo de vida do navegador no app macOS
|
||||
summary: Serviço integrado de controle de navegador + comandos de ação
|
||||
- Implementando configurações e ciclo de vida do navegador no app para macOS
|
||||
summary: Serviço integrado de controle do navegador + comandos de ação
|
||||
title: Navegador (gerenciado pelo OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:55:29Z"
|
||||
generated_at: "2026-04-10T05:34:15Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a
|
||||
source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,24 +18,24 @@ x-i18n:
|
||||
|
||||
O OpenClaw pode executar um **perfil dedicado de Chrome/Brave/Edge/Chromium** que o agente controla.
|
||||
Ele é isolado do seu navegador pessoal e é gerenciado por meio de um pequeno
|
||||
serviço local de controle dentro do Gateway (somente loopback).
|
||||
serviço local de controle dentro do Gateway (apenas loopback).
|
||||
|
||||
Visão para iniciantes:
|
||||
|
||||
- Pense nele como um **navegador separado, só para o agente**.
|
||||
- O perfil `openclaw` **não** toca no seu perfil pessoal do navegador.
|
||||
- O agente pode **abrir abas, ler páginas, clicar e digitar** em uma faixa segura.
|
||||
- O perfil `user` integrado se conecta à sua sessão real do Chrome já autenticada via Chrome MCP.
|
||||
- Pense nele como um **navegador separado, apenas para o agente**.
|
||||
- O perfil `openclaw` **não** toca no perfil do seu navegador pessoal.
|
||||
- O agente pode **abrir abas, ler páginas, clicar e digitar** em um ambiente seguro.
|
||||
- O perfil integrado `user` se conecta à sua sessão real do Chrome autenticada por meio do Chrome MCP.
|
||||
|
||||
## O que você recebe
|
||||
|
||||
- Um perfil de navegador separado chamado **openclaw** (com destaque laranja por padrão).
|
||||
- Um perfil de navegador separado chamado **openclaw** (destaque laranja por padrão).
|
||||
- Controle determinístico de abas (listar/abrir/focar/fechar).
|
||||
- Ações do agente (clicar/digitar/arrastar/selecionar), snapshots, capturas de tela, PDFs.
|
||||
- Ações do agente (clicar/digitar/arrastar/selecionar), snapshots, capturas de tela e PDFs.
|
||||
- Suporte opcional a vários perfis (`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
Este navegador **não** é o seu navegador do dia a dia. É uma superfície segura e isolada para
|
||||
automação e verificação por agente.
|
||||
Este navegador **não** é o que você usa no dia a dia. Ele é uma superfície segura e isolada para
|
||||
automação e verificação pelo agente.
|
||||
|
||||
## Início rápido
|
||||
|
||||
@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
Se aparecer “Browser disabled”, habilite-o na configuração (veja abaixo) e reinicie o
|
||||
Se você receber “Navegador desativado”, ative-o na configuração (veja abaixo) e reinicie o
|
||||
Gateway.
|
||||
|
||||
Se `openclaw browser` estiver completamente ausente, ou se o agente disser que a ferramenta de navegador
|
||||
está indisponível, vá para [Missing browser command or tool](/tools/browser#missing-browser-command-or-tool).
|
||||
Se `openclaw browser` estiver totalmente ausente, ou se o agente disser que a ferramenta de navegador
|
||||
não está disponível, vá para [Comando ou ferramenta de navegador ausente](/pt-BR/tools/browser#missing-browser-command-or-tool).
|
||||
|
||||
## Controle por plugin
|
||||
|
||||
A ferramenta padrão `browser` agora é um plugin empacotado que já vem habilitado por
|
||||
padrão. Isso significa que você pode desativá-lo ou substituí-lo sem remover o restante do
|
||||
A ferramenta `browser` padrão agora é um plugin integrado que é distribuído ativado por
|
||||
padrão. Isso significa que você pode desativá-la ou substituí-la sem remover o restante do
|
||||
sistema de plugins do OpenClaw:
|
||||
|
||||
```json5
|
||||
@ -70,33 +70,33 @@ sistema de plugins do OpenClaw:
|
||||
}
|
||||
```
|
||||
|
||||
Desative o plugin empacotado antes de instalar outro plugin que ofereça o
|
||||
mesmo nome de ferramenta `browser`. A experiência padrão de navegador precisa de ambos:
|
||||
Desative o plugin integrado antes de instalar outro plugin que forneça o
|
||||
mesmo nome de ferramenta `browser`. A experiência padrão do navegador precisa de ambos:
|
||||
|
||||
- `plugins.entries.browser.enabled` não desabilitado
|
||||
- `plugins.entries.browser.enabled` não desativado
|
||||
- `browser.enabled=true`
|
||||
|
||||
Se você desativar apenas o plugin, a CLI de navegador empacotada (`openclaw browser`),
|
||||
o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle
|
||||
do navegador desaparecem juntos. Sua configuração `browser.*` permanece intacta para que um
|
||||
Se você desativar apenas o plugin, a CLI de navegador integrada (`openclaw browser`),
|
||||
o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle do navegador
|
||||
desaparecem juntos. Sua configuração `browser.*` permanece intacta para que um
|
||||
plugin substituto a reutilize.
|
||||
|
||||
O plugin empacotado de navegador agora também é dono da implementação de runtime do navegador.
|
||||
O núcleo mantém apenas helpers compartilhados do Plugin SDK mais reexports de compatibilidade para
|
||||
caminhos internos antigos de importação. Na prática, remover ou substituir o pacote do plugin de navegador
|
||||
remove o conjunto de recursos do navegador em vez de deixar um segundo runtime
|
||||
pertencente ao núcleo.
|
||||
O plugin integrado do navegador também agora é responsável pela implementação de runtime do navegador.
|
||||
O núcleo mantém apenas auxiliares compartilhados do Plugin SDK, além de reexports de compatibilidade para
|
||||
caminhos de importação internos mais antigos. Na prática, remover ou substituir o pacote do plugin do navegador
|
||||
remove o conjunto de recursos do navegador, em vez de deixar um segundo runtime de propriedade do
|
||||
núcleo para trás.
|
||||
|
||||
Alterações na configuração do navegador ainda exigem reinício do Gateway para que o plugin empacotado
|
||||
Alterações na configuração do navegador ainda exigem reiniciar o Gateway para que o plugin integrado
|
||||
possa registrar novamente seu serviço de navegador com as novas configurações.
|
||||
|
||||
## Comando ou ferramenta de navegador ausente
|
||||
|
||||
Se `openclaw browser` de repente virar um comando desconhecido após uma atualização, ou
|
||||
se o agente relatar que a ferramenta de navegador está ausente, a causa mais comum é uma
|
||||
lista restritiva `plugins.allow` que não inclui `browser`.
|
||||
Se `openclaw browser` de repente se tornar um comando desconhecido após uma atualização, ou
|
||||
se o agente informar que a ferramenta de navegador está ausente, a causa mais comum é uma
|
||||
lista restritiva em `plugins.allow` que não inclui `browser`.
|
||||
|
||||
Exemplo de configuração quebrada:
|
||||
Exemplo de configuração com problema:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -106,7 +106,7 @@ Exemplo de configuração quebrada:
|
||||
}
|
||||
```
|
||||
|
||||
Corrija adicionando `browser` à allowlist de plugins:
|
||||
Corrija adicionando `browser` à lista de permissões de plugins:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -116,30 +116,30 @@ Corrija adicionando `browser` à allowlist de plugins:
|
||||
}
|
||||
```
|
||||
|
||||
Observações importantes:
|
||||
Notas importantes:
|
||||
|
||||
- `browser.enabled=true` não basta sozinho quando `plugins.allow` está definido.
|
||||
- `plugins.entries.browser.enabled=true` também não basta sozinho quando `plugins.allow` está definido.
|
||||
- `tools.alsoAllow: ["browser"]` **não** carrega o plugin empacotado de navegador. Apenas ajusta a política de ferramentas depois que o plugin já foi carregado.
|
||||
- Se você não precisa de uma allowlist restritiva de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador empacotado.
|
||||
- `browser.enabled=true` não é suficiente por si só quando `plugins.allow` está definido.
|
||||
- `plugins.entries.browser.enabled=true` também não é suficiente por si só quando `plugins.allow` está definido.
|
||||
- `tools.alsoAllow: ["browser"]` **não** carrega o plugin integrado do navegador. Ele apenas ajusta a política da ferramenta depois que o plugin já foi carregado.
|
||||
- Se você não precisa de uma lista restritiva de permissões de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador integrado.
|
||||
|
||||
Sintomas típicos:
|
||||
|
||||
- `openclaw browser` é um comando desconhecido.
|
||||
- `browser.request` está ausente.
|
||||
- O agente relata a ferramenta de navegador como indisponível ou ausente.
|
||||
- O agente informa que a ferramenta de navegador está indisponível ou ausente.
|
||||
|
||||
## Perfis: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: navegador gerenciado e isolado (não requer extensão).
|
||||
- `user`: perfil embutido de conexão Chrome MCP para sua **sessão real do Chrome já autenticada**.
|
||||
- `openclaw`: navegador gerenciado e isolado (nenhuma extensão necessária).
|
||||
- `user`: perfil integrado de conexão via Chrome MCP para sua **sessão real do Chrome autenticada**.
|
||||
|
||||
Para chamadas da ferramenta de navegador pelo agente:
|
||||
Para chamadas da ferramenta de navegador do agente:
|
||||
|
||||
- Padrão: use o navegador isolado `openclaw`.
|
||||
- Prefira `profile="user"` quando sessões já autenticadas existentes importarem e o usuário
|
||||
- Prefira `profile="user"` quando sessões autenticadas já existentes importarem e o usuário
|
||||
estiver no computador para clicar/aprovar qualquer prompt de conexão.
|
||||
- `profile` é o override explícito quando você quer um modo específico de navegador.
|
||||
- `profile` é a substituição explícita quando você quer um modo de navegador específico.
|
||||
|
||||
Defina `browser.defaultProfile: "openclaw"` se quiser o modo gerenciado por padrão.
|
||||
|
||||
@ -152,14 +152,14 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`.
|
||||
browser: {
|
||||
enabled: true, // padrão: true
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: true, // modo padrão de rede confiável
|
||||
dangerouslyAllowPrivateNetwork: true, // modo trusted-network padrão
|
||||
// allowPrivateNetwork: true, // alias legado
|
||||
// hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
// allowedHostnames: ["localhost"],
|
||||
},
|
||||
// cdpUrl: "http://127.0.0.1:18792", // override legado de perfil único
|
||||
remoteCdpTimeoutMs: 1500, // timeout HTTP remoto do CDP (ms)
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // timeout do handshake WebSocket remoto do CDP (ms)
|
||||
// cdpUrl: "http://127.0.0.1:18792", // substituição legada de perfil único
|
||||
remoteCdpTimeoutMs: 1500, // tempo limite de HTTP do CDP remoto (ms)
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // tempo limite do handshake WebSocket do CDP remoto (ms)
|
||||
defaultProfile: "openclaw",
|
||||
color: "#FF4500",
|
||||
headless: false,
|
||||
@ -186,36 +186,36 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`.
|
||||
}
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- O serviço de controle do navegador faz bind em loopback em uma porta derivada de `gateway.port`
|
||||
- O serviço de controle do navegador se vincula ao loopback em uma porta derivada de `gateway.port`
|
||||
(padrão: `18791`, que é gateway + 2).
|
||||
- Se você sobrescrever a porta do Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
|
||||
- Se você substituir a porta do Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
|
||||
as portas derivadas do navegador mudam para permanecer na mesma “família”.
|
||||
- `cdpUrl` assume por padrão a porta CDP local gerenciada quando não definido.
|
||||
- `remoteCdpTimeoutMs` se aplica a verificações de alcance de CDP remoto (não loopback).
|
||||
- `cdpUrl` usa por padrão a porta CDP local gerenciada quando não está definido.
|
||||
- `remoteCdpTimeoutMs` se aplica a verificações de alcance do CDP remoto (não loopback).
|
||||
- `remoteCdpHandshakeTimeoutMs` se aplica a verificações de alcance do handshake WebSocket do CDP remoto.
|
||||
- Navegação/abertura de aba no navegador é protegida contra SSRF antes da navegação e verificada novamente, no melhor esforço, na URL final `http(s)` após a navegação.
|
||||
- No modo estrito de SSRF, descoberta/sondas de endpoint CDP remoto (`cdpUrl`, incluindo buscas em `/json/version`) também são verificadas.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` tem padrão `true` (modelo de rede confiável). Defina como `false` para navegação pública estrita.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado para compatibilidade.
|
||||
- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução.”
|
||||
- `color` + `color` por perfil tingem a UI do navegador para que você veja qual perfil está ativo.
|
||||
- A navegação/abertura de aba do navegador é protegida contra SSRF antes da navegação e verificada novamente, no melhor esforço, na URL final `http(s)` após a navegação.
|
||||
- No modo SSRF estrito, a descoberta/sondagem de endpoints CDP remotos (`cdpUrl`, incluindo buscas em `/json/version`) também é verificada.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` por padrão (modelo de rede confiável). Defina como `false` para navegação estrita apenas pública.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` continua com suporte como alias legado por compatibilidade.
|
||||
- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução”.
|
||||
- `color` + `color` por perfil tingem a interface do navegador para que você possa ver qual perfil está ativo.
|
||||
- O perfil padrão é `openclaw` (navegador independente gerenciado pelo OpenClaw). Use `defaultProfile: "user"` para optar pelo navegador autenticado do usuário.
|
||||
- Ordem de autodetecção: navegador padrão do sistema se for baseado em Chromium; caso contrário Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- Perfis locais `openclaw` atribuem automaticamente `cdpPort`/`cdpUrl` — defina-os apenas para CDP remoto.
|
||||
- Perfis `openclaw` locais atribuem automaticamente `cdpPort`/`cdpUrl` — defina esses valores apenas para CDP remoto.
|
||||
- `driver: "existing-session"` usa Chrome DevTools MCP em vez de CDP bruto. Não
|
||||
defina `cdpUrl` para esse driver.
|
||||
- Defina `browser.profiles.<name>.userDataDir` quando um perfil existing-session
|
||||
deve se conectar a um perfil de usuário Chromium não padrão, como Brave ou Edge.
|
||||
|
||||
## Use Brave (ou outro navegador baseado em Chromium)
|
||||
## Usar Brave (ou outro navegador baseado em Chromium)
|
||||
|
||||
Se o seu navegador **padrão do sistema** for baseado em Chromium (Chrome/Brave/Edge/etc),
|
||||
o OpenClaw o usa automaticamente. Defina `browser.executablePath` para sobrescrever a
|
||||
o OpenClaw o usa automaticamente. Defina `browser.executablePath` para substituir a
|
||||
autodetecção:
|
||||
|
||||
Exemplo via CLI:
|
||||
Exemplo na CLI:
|
||||
|
||||
```bash
|
||||
openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
@ -247,48 +247,48 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
## Controle local vs remoto
|
||||
|
||||
- **Controle local (padrão):** o Gateway inicia o serviço de controle em loopback e pode iniciar um navegador local.
|
||||
- **Controle remoto (node host):** execute um node host na máquina que tem o navegador; o Gateway faz proxy das ações do navegador para ele.
|
||||
- **Controle remoto (host de nó):** execute um host de nó na máquina que tem o navegador; o Gateway encaminha as ações do navegador para ele.
|
||||
- **CDP remoto:** defina `browser.profiles.<name>.cdpUrl` (ou `browser.cdpUrl`) para
|
||||
se conectar a um navegador remoto baseado em Chromium. Nesse caso, o OpenClaw não iniciará um navegador local.
|
||||
|
||||
O comportamento ao parar difere por modo de perfil:
|
||||
O comportamento de parada difere por modo de perfil:
|
||||
|
||||
- perfis gerenciados locais: `openclaw browser stop` para o processo do navegador que
|
||||
- perfis locais gerenciados: `openclaw browser stop` interrompe o processo do navegador que
|
||||
o OpenClaw iniciou
|
||||
- perfis attach-only e CDP remoto: `openclaw browser stop` fecha a sessão ativa de
|
||||
controle e libera overrides de emulação Playwright/CDP (viewport,
|
||||
- perfis somente de conexão e CDP remoto: `openclaw browser stop` fecha a sessão de controle ativa
|
||||
e libera as substituições de emulação do Playwright/CDP (viewport,
|
||||
esquema de cores, localidade, fuso horário, modo offline e estado semelhante), mesmo
|
||||
que nenhum processo de navegador tenha sido iniciado pelo OpenClaw
|
||||
|
||||
URLs CDP remotas podem incluir autenticação:
|
||||
URLs de CDP remoto podem incluir autenticação:
|
||||
|
||||
- Tokens em query (por exemplo, `https://provider.example?token=<token>`)
|
||||
- Tokens de query (por exemplo, `https://provider.example?token=<token>`)
|
||||
- Autenticação HTTP Basic (por exemplo, `https://user:pass@provider.example`)
|
||||
|
||||
O OpenClaw preserva a autenticação ao chamar endpoints `/json/*` e ao se conectar
|
||||
ao WebSocket CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para
|
||||
tokens em vez de gravá-los em arquivos de configuração.
|
||||
ao WebSocket do CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para
|
||||
tokens em vez de confirmá-los em arquivos de configuração.
|
||||
|
||||
## Proxy de navegador por node (padrão zero-config)
|
||||
## Proxy de navegador do nó (padrão sem configuração)
|
||||
|
||||
Se você executar um **node host** na máquina que tem seu navegador, o OpenClaw pode
|
||||
rotear automaticamente chamadas da ferramenta de navegador para esse node sem nenhuma configuração extra de navegador.
|
||||
Esse é o caminho padrão para gateways remotos.
|
||||
Se você executar um **host de nó** na máquina que tem o navegador, o OpenClaw pode
|
||||
rotear automaticamente chamadas da ferramenta de navegador para esse nó sem nenhuma configuração extra de navegador.
|
||||
Este é o caminho padrão para gateways remotos.
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- O node host expõe seu servidor local de controle de navegador por meio de um **comando proxy**.
|
||||
- Os perfis vêm da própria configuração `browser.profiles` do node (igual ao local).
|
||||
- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe vazio para o comportamento legado/padrão: todos os perfis configurados continuam acessíveis pelo proxy, incluindo rotas de criação/exclusão de perfil.
|
||||
- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw o trata como um limite de menor privilégio: apenas perfis na allowlist podem ser direcionados, e rotas persistentes de criação/exclusão de perfil são bloqueadas na superfície do proxy.
|
||||
- O host de nó expõe seu servidor local de controle de navegador por meio de um **comando proxy**.
|
||||
- Os perfis vêm da própria configuração `browser.profiles` do nó (igual à local).
|
||||
- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe vazio para o comportamento legado/padrão: todos os perfis configurados permanecem acessíveis por meio do proxy, incluindo rotas de criação/exclusão de perfil.
|
||||
- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw trata isso como um limite de menor privilégio: apenas perfis na lista de permissões podem ser direcionados, e rotas persistentes de criação/exclusão de perfil são bloqueadas na superfície do proxy.
|
||||
- Desative se não quiser isso:
|
||||
- No node: `nodeHost.browserProxy.enabled=false`
|
||||
- No nó: `nodeHost.browserProxy.enabled=false`
|
||||
- No gateway: `gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless (CDP remoto hospedado)
|
||||
|
||||
[Browserless](https://browserless.io) é um serviço Chromium hospedado que expõe
|
||||
URLs de conexão CDP por HTTPS e WebSocket. O OpenClaw pode usar qualquer formato, mas
|
||||
[Browserless](https://browserless.io) é um serviço hospedado de Chromium que expõe
|
||||
URLs de conexão CDP por HTTPS e WebSocket. O OpenClaw pode usar qualquer uma das formas, mas
|
||||
para um perfil de navegador remoto a opção mais simples é a URL WebSocket direta
|
||||
da documentação de conexão do Browserless.
|
||||
|
||||
@ -311,21 +311,21 @@ Exemplo:
|
||||
}
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- Substitua `<BROWSERLESS_API_KEY>` pelo seu token real do Browserless.
|
||||
- Escolha o endpoint de região que corresponda à sua conta Browserless (veja a documentação deles).
|
||||
- Escolha o endpoint de região que corresponda à sua conta do Browserless (veja a documentação deles).
|
||||
- Se o Browserless fornecer uma URL base HTTPS, você pode convertê-la para
|
||||
`wss://` para uma conexão CDP direta ou manter a URL HTTPS e deixar que o OpenClaw
|
||||
descubra `/json/version`.
|
||||
`wss://` para uma conexão CDP direta ou manter a URL HTTPS e deixar o OpenClaw
|
||||
descobrir `/json/version`.
|
||||
|
||||
## Provedores CDP WebSocket diretos
|
||||
|
||||
Alguns serviços de navegador hospedado expõem um endpoint **WebSocket direto** em vez de
|
||||
descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw suporta ambos:
|
||||
Alguns serviços hospedados de navegador expõem um endpoint **WebSocket direto** em vez da
|
||||
descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw oferece suporte a ambos:
|
||||
|
||||
- **Endpoints HTTP(S)** — o OpenClaw chama `/json/version` para descobrir a
|
||||
URL WebSocket do depurador e então se conecta.
|
||||
URL do depurador WebSocket e então se conecta.
|
||||
- **Endpoints WebSocket** (`ws://` / `wss://`) — o OpenClaw se conecta diretamente,
|
||||
ignorando `/json/version`. Use isso para serviços como
|
||||
[Browserless](https://browserless.io),
|
||||
@ -335,7 +335,7 @@ descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw suporta amb
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com) é uma plataforma em nuvem para executar
|
||||
navegadores headless com resolução de CAPTCHA integrada, modo stealth e
|
||||
navegadores headless com resolução de CAPTCHA integrada, modo furtivo e
|
||||
proxies residenciais.
|
||||
|
||||
```json5
|
||||
@ -355,59 +355,59 @@ proxies residenciais.
|
||||
}
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- [Cadastre-se](https://www.browserbase.com/sign-up) e copie sua **API Key**
|
||||
do [dashboard Overview](https://www.browserbase.com/overview).
|
||||
- Substitua `<BROWSERBASE_API_KEY>` pela sua chave de API real do Browserbase.
|
||||
- O Browserbase cria automaticamente uma sessão de navegador ao conectar o WebSocket, então
|
||||
não é necessária nenhuma etapa manual de criação de sessão.
|
||||
- O nível gratuito permite uma sessão concorrente e uma hora de navegador por mês.
|
||||
Consulte [pricing](https://www.browserbase.com/pricing) para limites dos planos pagos.
|
||||
- Consulte a [documentação do Browserbase](https://docs.browserbase.com) para a
|
||||
do [painel Overview](https://www.browserbase.com/overview).
|
||||
- Substitua `<BROWSERBASE_API_KEY>` pela sua API key real do Browserbase.
|
||||
- O Browserbase cria automaticamente uma sessão de navegador na conexão WebSocket, portanto
|
||||
nenhuma etapa manual de criação de sessão é necessária.
|
||||
- O plano gratuito permite uma sessão simultânea e uma hora de navegador por mês.
|
||||
Veja os [preços](https://www.browserbase.com/pricing) para os limites dos planos pagos.
|
||||
- Veja a [documentação do Browserbase](https://docs.browserbase.com) para a
|
||||
referência completa da API, guias de SDK e exemplos de integração.
|
||||
|
||||
## Segurança
|
||||
|
||||
Ideias principais:
|
||||
|
||||
- O controle do navegador é somente loopback; o acesso flui pela autenticação do Gateway ou pelo pareamento do node.
|
||||
- A API HTTP independente de navegador em loopback usa **somente autenticação por segredo compartilhado**:
|
||||
autenticação bearer do token do gateway, `x-openclaw-password`, ou HTTP Basic auth com a
|
||||
- O controle do navegador é apenas por loopback; o acesso flui pela autenticação do Gateway ou pelo emparelhamento de nó.
|
||||
- A API HTTP independente do navegador em loopback usa **apenas autenticação por segredo compartilhado**:
|
||||
bearer auth com token do gateway, `x-openclaw-password`, ou autenticação HTTP Basic com a
|
||||
senha configurada do gateway.
|
||||
- Cabeçalhos de identidade do Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **não**
|
||||
autenticam essa API independente de navegador em loopback.
|
||||
- Se o controle do navegador estiver habilitado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw
|
||||
autenticam esta API independente do navegador em loopback.
|
||||
- Se o controle do navegador estiver ativado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw
|
||||
gera automaticamente `gateway.auth.token` na inicialização e o persiste na configuração.
|
||||
- O OpenClaw **não** gera automaticamente esse token quando `gateway.auth.mode` já for
|
||||
- O OpenClaw **não** gera automaticamente esse token quando `gateway.auth.mode` já é
|
||||
`password`, `none` ou `trusted-proxy`.
|
||||
- Mantenha o Gateway e quaisquer node hosts em uma rede privada (Tailscale); evite exposição pública.
|
||||
- Trate URLs/tokens CDP remotos como segredos; prefira variáveis de ambiente ou um gerenciador de segredos.
|
||||
- Mantenha o Gateway e quaisquer hosts de nó em uma rede privada (Tailscale); evite exposição pública.
|
||||
- Trate URLs/tokens remotos de CDP como segredos; prefira variáveis de ambiente ou um gerenciador de segredos.
|
||||
|
||||
Dicas para CDP remoto:
|
||||
|
||||
- Prefira endpoints criptografados (HTTPS ou WSS) e tokens de curta duração sempre que possível.
|
||||
- Prefira endpoints criptografados (HTTPS ou WSS) e tokens de curta duração quando possível.
|
||||
- Evite incorporar tokens de longa duração diretamente em arquivos de configuração.
|
||||
|
||||
## Perfis (múltiplos navegadores)
|
||||
## Perfis (vários navegadores)
|
||||
|
||||
O OpenClaw oferece suporte a vários perfis nomeados (configurações de roteamento). Os perfis podem ser:
|
||||
|
||||
- **gerenciados pelo openclaw**: uma instância dedicada de navegador baseado em Chromium com seu próprio diretório de dados de usuário + porta CDP
|
||||
- **remotos**: uma URL CDP explícita (navegador baseado em Chromium rodando em outro lugar)
|
||||
- **sessão existente**: seu perfil existente do Chrome por conexão automática do Chrome DevTools MCP
|
||||
- **remoto**: uma URL CDP explícita (navegador baseado em Chromium em execução em outro lugar)
|
||||
- **sessão existente**: seu perfil atual do Chrome via conexão automática do Chrome DevTools MCP
|
||||
|
||||
Padrões:
|
||||
|
||||
- O perfil `openclaw` é criado automaticamente se estiver ausente.
|
||||
- O perfil `user` é embutido para conexão existing-session do Chrome MCP.
|
||||
- Perfis existing-session são opt-in além do `user`; crie-os com `--driver existing-session`.
|
||||
- Portas CDP locais são alocadas por padrão em **18800–18899**.
|
||||
- O perfil `user` é integrado para conexão de sessão existente do Chrome MCP.
|
||||
- Perfis de sessão existente são opt-in além de `user`; crie-os com `--driver existing-session`.
|
||||
- As portas CDP locais são alocadas de **18800–18899** por padrão.
|
||||
- Excluir um perfil move seu diretório de dados local para a Lixeira.
|
||||
|
||||
Todos os endpoints de controle aceitam `?profile=<name>`; a CLI usa `--browser-profile`.
|
||||
|
||||
## Existing-session via Chrome DevTools MCP
|
||||
## Sessão existente via Chrome DevTools MCP
|
||||
|
||||
O OpenClaw também pode se conectar a um perfil de navegador baseado em Chromium já em execução por meio do
|
||||
servidor oficial Chrome DevTools MCP. Isso reutiliza as abas e o estado de login
|
||||
@ -418,19 +418,19 @@ Referências oficiais de contexto e configuração:
|
||||
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
|
||||
Perfil embutido:
|
||||
Perfil integrado:
|
||||
|
||||
- `user`
|
||||
|
||||
Opcional: crie seu próprio perfil existing-session personalizado se quiser um
|
||||
nome, cor ou diretório de dados do navegador diferentes.
|
||||
Opcional: crie seu próprio perfil personalizado de sessão existente se quiser um
|
||||
nome, cor ou diretório de dados do navegador diferente.
|
||||
|
||||
Comportamento padrão:
|
||||
|
||||
- O perfil `user` embutido usa conexão automática Chrome MCP, que mira o
|
||||
- O perfil integrado `user` usa conexão automática do Chrome MCP, que mira o
|
||||
perfil local padrão do Google Chrome.
|
||||
|
||||
Use `userDataDir` para Brave, Edge, Chromium ou um perfil não padrão do Chrome:
|
||||
Use `userDataDir` para Brave, Edge, Chromium ou um perfil Chrome não padrão:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -450,16 +450,16 @@ Use `userDataDir` para Brave, Edge, Chromium ou um perfil não padrão do Chrome
|
||||
Então, no navegador correspondente:
|
||||
|
||||
1. Abra a página de inspeção desse navegador para depuração remota.
|
||||
2. Habilite a depuração remota.
|
||||
2. Ative a depuração remota.
|
||||
3. Mantenha o navegador em execução e aprove o prompt de conexão quando o OpenClaw se conectar.
|
||||
|
||||
Páginas de inspeção comuns:
|
||||
Páginas comuns de inspeção:
|
||||
|
||||
- Chrome: `chrome://inspect/#remote-debugging`
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
Teste rápido de conexão ativa:
|
||||
Teste rápido de conexão ao vivo:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -473,63 +473,64 @@ Como é o sucesso:
|
||||
- `status` mostra `driver: existing-session`
|
||||
- `status` mostra `transport: chrome-mcp`
|
||||
- `status` mostra `running: true`
|
||||
- `tabs` lista suas abas já abertas no navegador
|
||||
- `tabs` lista as abas do navegador que já estavam abertas
|
||||
- `snapshot` retorna refs da aba ativa selecionada
|
||||
|
||||
O que verificar se a conexão não funcionar:
|
||||
|
||||
- o navegador-alvo baseado em Chromium está na versão `144+`
|
||||
- a depuração remota está habilitada na página de inspeção desse navegador
|
||||
- o navegador mostrou e você aceitou o prompt de consentimento da conexão
|
||||
- `openclaw doctor` migra configuração antiga de navegador baseada em extensão e verifica se
|
||||
o Chrome está instalado localmente para perfis padrão de conexão automática, mas ele não consegue
|
||||
habilitar a depuração remota no lado do navegador para você
|
||||
- o navegador baseado em Chromium de destino está na versão `144+`
|
||||
- a depuração remota está ativada na página de inspeção desse navegador
|
||||
- o navegador exibiu o prompt de consentimento de conexão e você o aceitou
|
||||
- `openclaw doctor` migra a configuração antiga de navegador baseada em extensão e verifica se
|
||||
o Chrome está instalado localmente para perfis padrão de conexão automática, mas não pode
|
||||
ativar a depuração remota no lado do navegador para você
|
||||
|
||||
Uso pelo agente:
|
||||
|
||||
- Use `profile="user"` quando precisar do estado do navegador autenticado do usuário.
|
||||
- Se você usa um perfil existing-session personalizado, passe esse nome de perfil explícito.
|
||||
- Escolha esse modo apenas quando o usuário estiver no computador para aprovar o
|
||||
- Se você usa um perfil personalizado de sessão existente, passe esse nome de perfil explícito.
|
||||
- Só escolha esse modo quando o usuário estiver no computador para aprovar o
|
||||
prompt de conexão.
|
||||
- o Gateway ou node host pode iniciar `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
- o Gateway ou host de nó pode iniciar `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- Esse caminho é de risco mais alto do que o perfil isolado `openclaw`, porque ele pode
|
||||
- Esse caminho tem mais risco do que o perfil isolado `openclaw` porque pode
|
||||
agir dentro da sua sessão autenticada do navegador.
|
||||
- O OpenClaw não inicia o navegador para esse driver; ele se conecta apenas a uma
|
||||
sessão existente.
|
||||
- O OpenClaw usa aqui o fluxo oficial `--autoConnect` do Chrome DevTools MCP. Se
|
||||
`userDataDir` estiver definido, o OpenClaw o repassa para mirar esse diretório
|
||||
explícito de dados de usuário do Chromium.
|
||||
- Capturas de tela em existing-session suportam capturas da página e capturas de elemento com `--ref`
|
||||
a partir de snapshots, mas não seletores CSS `--element`.
|
||||
- Capturas de tela de página em existing-session funcionam sem Playwright via Chrome MCP.
|
||||
`userDataDir` estiver definido, o OpenClaw o repassa para mirar esse diretório explícito
|
||||
de dados de usuário Chromium.
|
||||
- Capturas de tela de sessão existente oferecem suporte a capturas de página e capturas de elemento com `--ref`
|
||||
a partir de snapshots, mas não a seletores CSS `--element`.
|
||||
- Capturas de tela de página de sessão existente funcionam sem Playwright por meio do Chrome MCP.
|
||||
Capturas de elemento baseadas em ref (`--ref`) também funcionam ali, mas `--full-page`
|
||||
não pode ser combinado com `--ref` nem com `--element`.
|
||||
- Ações em existing-session ainda são mais limitadas do que no caminho de navegador gerenciado:
|
||||
não pode ser combinado com `--ref` ou `--element`.
|
||||
- Ações de sessão existente ainda são mais limitadas do que no caminho do navegador
|
||||
gerenciado:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` exigem
|
||||
refs de snapshot em vez de seletores CSS
|
||||
- `click` é somente com botão esquerdo (sem overrides de botão ou modificadores)
|
||||
- `type` não suporta `slowly=true`; use `fill` ou `press`
|
||||
- `press` não suporta `delayMs`
|
||||
- `click` é apenas com botão esquerdo (sem substituições de botão ou modificadores)
|
||||
- `type` não oferece suporte a `slowly=true`; use `fill` ou `press`
|
||||
- `press` não oferece suporte a `delayMs`
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` e `evaluate` não
|
||||
suportam overrides de timeout por chamada
|
||||
- `select` atualmente suporta apenas um único valor
|
||||
- Existing-session `wait --url` suporta padrões exatos, substring e glob
|
||||
oferecem suporte a substituições de tempo limite por chamada
|
||||
- `select` atualmente oferece suporte apenas a um único valor
|
||||
- `wait --url` para sessão existente oferece suporte a padrões exatos, de substring e glob
|
||||
como outros drivers de navegador. `wait --load networkidle` ainda não é compatível.
|
||||
- Hooks de upload em existing-session exigem `ref` ou `inputRef`, suportam um arquivo
|
||||
por vez e não suportam direcionamento CSS `element`.
|
||||
- Hooks de diálogo em existing-session não suportam overrides de timeout.
|
||||
- Alguns recursos ainda exigem o caminho de navegador gerenciado, incluindo
|
||||
ações em lote, exportação de PDF, interceptação de download e `responsebody`.
|
||||
- Existing-session é local ao host. Se o Chrome estiver em outra máquina ou em outro
|
||||
namespace de rede, use CDP remoto ou um node host.
|
||||
- Hooks de upload em sessão existente exigem `ref` ou `inputRef`, oferecem suporte a um arquivo
|
||||
por vez e não oferecem suporte ao direcionamento por `element` CSS.
|
||||
- Hooks de diálogo em sessão existente não oferecem suporte a substituições de tempo limite.
|
||||
- Alguns recursos ainda exigem o caminho de navegador gerenciado, incluindo ações em lote,
|
||||
exportação em PDF, interceptação de download e `responsebody`.
|
||||
- Sessão existente é local ao host. Se o Chrome estiver em outra máquina ou em um
|
||||
namespace de rede diferente, use CDP remoto ou um host de nó.
|
||||
|
||||
## Garantias de isolamento
|
||||
|
||||
- **Diretório de dados de usuário dedicado**: nunca toca no seu perfil pessoal do navegador.
|
||||
- **Portas dedicadas**: evita `9222` para impedir colisões com fluxos de desenvolvimento.
|
||||
- **Diretório de dados de usuário dedicado**: nunca toca no perfil do seu navegador pessoal.
|
||||
- **Portas dedicadas**: evita `9222` para prevenir colisões com fluxos de trabalho de desenvolvimento.
|
||||
- **Controle determinístico de abas**: mira abas por `targetId`, não pela “última aba”.
|
||||
|
||||
## Seleção do navegador
|
||||
@ -542,21 +543,21 @@ Ao iniciar localmente, o OpenClaw escolhe o primeiro disponível:
|
||||
4. Chromium
|
||||
5. Chrome Canary
|
||||
|
||||
Você pode sobrescrever com `browser.executablePath`.
|
||||
Você pode substituir isso com `browser.executablePath`.
|
||||
|
||||
Plataformas:
|
||||
|
||||
- macOS: verifica `/Applications` e `~/Applications`.
|
||||
- Linux: procura `google-chrome`, `brave`, `microsoft-edge`, `chromium` etc.
|
||||
- Linux: procura `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
|
||||
- Windows: verifica locais comuns de instalação.
|
||||
|
||||
## API de controle (opcional)
|
||||
|
||||
Apenas para integrações locais, o Gateway expõe uma pequena API HTTP em loopback:
|
||||
|
||||
- Status/start/stop: `GET /`, `POST /start`, `POST /stop`
|
||||
- Status/iniciar/parar: `GET /`, `POST /start`, `POST /stop`
|
||||
- Abas: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
|
||||
- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`
|
||||
- Snapshot/captura de tela: `GET /snapshot`, `POST /screenshot`
|
||||
- Ações: `POST /navigate`, `POST /act`
|
||||
- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`
|
||||
- Downloads: `POST /download`, `POST /wait/download`
|
||||
@ -569,21 +570,42 @@ Apenas para integrações locais, o Gateway expõe uma pequena API HTTP em loopb
|
||||
|
||||
Todos os endpoints aceitam `?profile=<name>`.
|
||||
|
||||
Se a autenticação por segredo compartilhado do gateway estiver configurada, as rotas HTTP do navegador também exigirão autenticação:
|
||||
Se a autenticação do gateway por segredo compartilhado estiver configurada, as rotas HTTP do navegador também exigirão autenticação:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` ou HTTP Basic auth com essa senha
|
||||
- `x-openclaw-password: <gateway password>` ou autenticação HTTP Basic com essa senha
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- Esta API independente de navegador em loopback **não** consome cabeçalhos de identidade de trusted-proxy nem
|
||||
de Tailscale Serve.
|
||||
- Se `gateway.auth.mode` for `none` ou `trusted-proxy`, estas rotas de navegador em loopback
|
||||
não herdam esses modos com identidade; mantenha-as somente em loopback.
|
||||
- Esta API independente do navegador em loopback **não** consome cabeçalhos de identidade de trusted-proxy ou
|
||||
Tailscale Serve.
|
||||
- Se `gateway.auth.mode` for `none` ou `trusted-proxy`, essas rotas de navegador em loopback
|
||||
não herdam esses modos com identidade; mantenha-as apenas em loopback.
|
||||
|
||||
### Exigência do Playwright
|
||||
### Contrato de erro de `/act`
|
||||
|
||||
Alguns recursos (`navigate`/`act`/snapshot AI/role snapshot, screenshots de elemento,
|
||||
`POST /act` usa uma resposta de erro estruturada para validação no nível da rota e
|
||||
falhas de política:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
```
|
||||
|
||||
Valores atuais de `code`:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind` está ausente ou não é reconhecido.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): a carga da ação falhou na normalização ou validação.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` foi usado com um tipo de ação não compatível.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (ou `wait --fn`) está desativado por configuração.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` de nível superior ou em lote entra em conflito com o alvo da solicitação.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): a ação não é compatível com perfis de sessão existente.
|
||||
|
||||
Outras falhas de runtime ainda podem retornar `{ "error": "<message>" }` sem um
|
||||
campo `code`.
|
||||
|
||||
### Requisito do Playwright
|
||||
|
||||
Alguns recursos (navigate/act/AI snapshot/role snapshot, capturas de tela de elementos,
|
||||
PDF) exigem Playwright. Se o Playwright não estiver instalado, esses endpoints retornam
|
||||
um erro 501 claro.
|
||||
|
||||
@ -591,58 +613,58 @@ O que ainda funciona sem Playwright:
|
||||
|
||||
- Snapshots ARIA
|
||||
- Capturas de tela de página para o navegador gerenciado `openclaw` quando um WebSocket
|
||||
CDP por aba estiver disponível
|
||||
CDP por aba está disponível
|
||||
- Capturas de tela de página para perfis `existing-session` / Chrome MCP
|
||||
- Capturas de tela `--ref` baseadas em existing-session a partir da saída de snapshot
|
||||
- Capturas de tela baseadas em ref (`--ref`) para `existing-session` a partir da saída de snapshot
|
||||
|
||||
O que ainda precisa do Playwright:
|
||||
O que ainda exige Playwright:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
- Snapshots AI / role snapshots
|
||||
- Snapshots AI / snapshots de função
|
||||
- Capturas de tela de elemento por seletor CSS (`--element`)
|
||||
- Exportação completa de PDF do navegador
|
||||
|
||||
Capturas de tela de elemento também rejeitam `--full-page`; a rota retorna `fullPage is
|
||||
not supported for element screenshots`.
|
||||
|
||||
Se você vir `Playwright is not available in this gateway build`, instale o pacote
|
||||
completo do Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale
|
||||
o OpenClaw com suporte a navegador.
|
||||
Se você vir `Playwright is not available in this gateway build`, instale o pacote completo
|
||||
do Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale o
|
||||
OpenClaw com suporte a navegador.
|
||||
|
||||
#### Instalação do Playwright no Docker
|
||||
|
||||
Se o Gateway estiver rodando em Docker, evite `npx playwright` (conflitos de override do npm).
|
||||
Use a CLI empacotada em vez disso:
|
||||
Se o seu Gateway roda em Docker, evite `npx playwright` (conflitos de override do npm).
|
||||
Use a CLI incluída em vez disso:
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli \
|
||||
node /app/node_modules/playwright-core/cli.js install chromium
|
||||
```
|
||||
|
||||
Para persistir downloads de navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo,
|
||||
`/home/node/.cache/ms-playwright`) e garanta que `/home/node` seja persistido via
|
||||
`OPENCLAW_HOME_VOLUME` ou um bind mount. Consulte [Docker](/pt-BR/install/docker).
|
||||
Para persistir downloads do navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo,
|
||||
`/home/node/.cache/ms-playwright`) e garanta que `/home/node` seja persistido por meio de
|
||||
`OPENCLAW_HOME_VOLUME` ou de um bind mount. Veja [Docker](/pt-BR/install/docker).
|
||||
|
||||
## Como funciona (internamente)
|
||||
|
||||
Fluxo de alto nível:
|
||||
|
||||
- Um pequeno **servidor de controle** aceita requisições HTTP.
|
||||
- Ele se conecta a navegadores baseados em Chromium (Chrome/Brave/Edge/Chromium) via **CDP**.
|
||||
- Para ações avançadas (clicar/digitar/snapshot/PDF), usa **Playwright** por cima
|
||||
do CDP.
|
||||
- Quando o Playwright está ausente, apenas operações sem Playwright ficam disponíveis.
|
||||
- Ele se conecta a navegadores baseados em Chromium (Chrome/Brave/Edge/Chromium) por meio de **CDP**.
|
||||
- Para ações avançadas (clicar/digitar/snapshot/PDF), ele usa **Playwright** sobre
|
||||
o CDP.
|
||||
- Quando o Playwright está ausente, apenas operações que não usam Playwright ficam disponíveis.
|
||||
|
||||
Esse design mantém o agente em uma interface estável e determinística, ao mesmo tempo que permite
|
||||
trocar navegadores/perfis locais ou remotos.
|
||||
Esse design mantém o agente em uma interface estável e determinística, ao mesmo tempo em que permite
|
||||
trocar navegadores e perfis locais/remotos.
|
||||
|
||||
## Referência rápida da CLI
|
||||
|
||||
Todos os comandos aceitam `--browser-profile <name>` para mirar um perfil específico.
|
||||
Todos os comandos aceitam `--browser-profile <name>` para direcionar um perfil específico.
|
||||
Todos os comandos também aceitam `--json` para saída legível por máquina (payloads estáveis).
|
||||
|
||||
Noções básicas:
|
||||
Básico:
|
||||
|
||||
- `openclaw browser status`
|
||||
- `openclaw browser start`
|
||||
@ -671,11 +693,11 @@ Inspeção:
|
||||
- `openclaw browser snapshot --frame "iframe#main" --interactive`
|
||||
- `openclaw browser console --level error`
|
||||
|
||||
Observação sobre ciclo de vida:
|
||||
Observação sobre o ciclo de vida:
|
||||
|
||||
- Para perfis attach-only e CDP remoto, `openclaw browser stop` ainda é o
|
||||
comando correto de limpeza após testes. Ele fecha a sessão ativa de controle e
|
||||
limpa overrides temporários de emulação em vez de encerrar o navegador
|
||||
- Para perfis somente de conexão e CDP remoto, `openclaw browser stop` continua sendo o
|
||||
comando de limpeza correto após os testes. Ele fecha a sessão de controle ativa e
|
||||
limpa substituições temporárias de emulação em vez de encerrar o navegador
|
||||
subjacente.
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
@ -725,62 +747,62 @@ Estado:
|
||||
- `openclaw browser set locale en-US`
|
||||
- `openclaw browser set device "iPhone 14"`
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- `upload` e `dialog` são chamadas de **preparo**; execute-as antes do click/press
|
||||
que dispara o seletor/diálogo.
|
||||
- Caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw:
|
||||
- `upload` e `dialog` são chamadas de **preparação**; execute-as antes do clique/tecla
|
||||
que aciona o seletor de arquivos/caixa de diálogo.
|
||||
- Os caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw:
|
||||
- traces: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`)
|
||||
- downloads: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- Caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw:
|
||||
- Os caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw:
|
||||
- uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` também pode definir inputs de arquivo diretamente via `--input-ref` ou `--element`.
|
||||
- `upload` também pode definir diretamente entradas de arquivo por meio de `--input-ref` ou `--element`.
|
||||
- `snapshot`:
|
||||
- `--format ai` (padrão quando o Playwright está instalado): retorna um snapshot AI com refs numéricos (`aria-ref="<n>"`).
|
||||
- `--format aria`: retorna a árvore de acessibilidade (sem refs; apenas inspeção).
|
||||
- `--efficient` (ou `--mode efficient`): preset compacto de role snapshot (interactive + compact + depth + maxChars menor).
|
||||
- Padrão de configuração (somente ferramenta/CLI): defina `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes quando o chamador não passar um modo (consulte [Gateway configuration](/pt-BR/gateway/configuration-reference#browser)).
|
||||
- Opções de role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em papel com refs como `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita role snapshots a um iframe (combina com refs de role como `e12`).
|
||||
- `--interactive` gera uma lista plana e fácil de escolher de elementos interativos (melhor para conduzir ações).
|
||||
- `--labels` adiciona uma captura de tela somente do viewport com rótulos de ref sobrepostos (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc exigem um `ref` de `snapshot` (numérico `12` ou role ref `e12`).
|
||||
Seletores CSS são intencionalmente não suportados para ações.
|
||||
- `--efficient` (ou `--mode efficient`): preset compacto de snapshot por função (interativo + compacto + profundidade + `maxChars` menor).
|
||||
- Padrão de configuração (apenas ferramenta/CLI): defina `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes quando quem chama não passar um modo (veja [Configuração do Gateway](/pt-BR/gateway/configuration-reference#browser)).
|
||||
- Opções de snapshot por função (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em função com refs como `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita snapshots por função a um iframe (combina com refs por função como `e12`).
|
||||
- `--interactive` gera uma lista simples e fácil de escolher de elementos interativos (melhor para conduzir ações).
|
||||
- `--labels` adiciona uma captura de tela apenas da viewport com rótulos de ref sobrepostos (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc exigem um `ref` de `snapshot` (seja numérico `12` ou ref por função `e12`).
|
||||
Seletores CSS intencionalmente não têm suporte para ações.
|
||||
|
||||
## Snapshots e refs
|
||||
|
||||
O OpenClaw suporta dois estilos de “snapshot”:
|
||||
O OpenClaw oferece suporte a dois estilos de “snapshot”:
|
||||
|
||||
- **AI snapshot (refs numéricos)**: `openclaw browser snapshot` (padrão; `--format ai`)
|
||||
- **Snapshot AI (refs numéricos)**: `openclaw browser snapshot` (padrão; `--format ai`)
|
||||
- Saída: um snapshot em texto que inclui refs numéricos.
|
||||
- Ações: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Internamente, o ref é resolvido via `aria-ref` do Playwright.
|
||||
|
||||
- **Role snapshot (refs de role como `e12`)**: `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Saída: uma lista/árvore baseada em papel com `[ref=e12]` (e opcionalmente `[nth=1]`).
|
||||
- **Snapshot por função (refs por função como `e12`)**: `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Saída: uma lista/árvore baseada em função com `[ref=e12]` (e opcionalmente `[nth=1]`).
|
||||
- Ações: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Internamente, o ref é resolvido via `getByRole(...)` (mais `nth()` para duplicados).
|
||||
- Adicione `--labels` para incluir uma captura do viewport com rótulos `e12` sobrepostos.
|
||||
- Internamente, o ref é resolvido via `getByRole(...)` (mais `nth()` para duplicatas).
|
||||
- Adicione `--labels` para incluir uma captura de tela da viewport com rótulos `e12` sobrepostos.
|
||||
|
||||
Comportamento dos refs:
|
||||
|
||||
- Refs **não são estáveis entre navegações**; se algo falhar, execute novamente `snapshot` e use um ref novo.
|
||||
- Se o role snapshot foi tirado com `--frame`, os refs de role ficam limitados àquele iframe até o próximo role snapshot.
|
||||
- Refs **não são estáveis entre navegações**; se algo falhar, execute `snapshot` novamente e use um ref novo.
|
||||
- Se o snapshot por função foi obtido com `--frame`, os refs por função ficam limitados a esse iframe até o próximo snapshot por função.
|
||||
|
||||
## Melhorias de espera
|
||||
## Recursos avançados de espera
|
||||
|
||||
Você pode esperar mais do que apenas tempo/texto:
|
||||
Você pode esperar por mais do que apenas tempo/texto:
|
||||
|
||||
- Esperar por URL (globs suportados pelo Playwright):
|
||||
- Esperar por URL (globs compatíveis com Playwright):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
- Esperar por estado de carregamento:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- Esperar por um predicado JS:
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- Esperar um seletor ficar visível:
|
||||
- Esperar por um seletor ficar visível:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Esses itens podem ser combinados:
|
||||
Esses recursos podem ser combinados:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -792,10 +814,10 @@ openclaw browser wait "#main" \
|
||||
|
||||
## Fluxos de depuração
|
||||
|
||||
Quando uma ação falha (por exemplo “not visible”, “strict mode violation”, “covered”):
|
||||
Quando uma ação falhar (por exemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Use `click <ref>` / `type <ref>` (prefira refs de role no modo interativo)
|
||||
2. Use `click <ref>` / `type <ref>` (prefira refs por função no modo interativo)
|
||||
3. Se ainda falhar: `openclaw browser highlight <ref>` para ver o que o Playwright está mirando
|
||||
4. Se a página se comportar de forma estranha:
|
||||
- `openclaw browser errors --clear`
|
||||
@ -818,17 +840,17 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
Role snapshots em JSON incluem `refs` mais um pequeno bloco `stats` (linhas/chars/refs/interactive) para que ferramentas possam raciocinar sobre tamanho e densidade do payload.
|
||||
Snapshots por função em JSON incluem `refs` além de um pequeno bloco `stats` (linhas/chars/refs/interactive) para que ferramentas possam analisar tamanho e densidade do payload.
|
||||
|
||||
## Controles de estado e ambiente
|
||||
## Ajustes de estado e ambiente
|
||||
|
||||
Eles são úteis para fluxos “faça o site se comportar como X”:
|
||||
Eles são úteis para fluxos de trabalho do tipo “faça o site se comportar como X”:
|
||||
|
||||
- Cookies: `cookies`, `cookies set`, `cookies clear`
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
- Offline: `set offline on|off`
|
||||
- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (o legado `set headers --json '{"X-Debug":"1"}'` continua compatível)
|
||||
- HTTP basic auth: `set credentials user pass` (ou `--clear`)
|
||||
- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (o legado `set headers --json '{"X-Debug":"1"}'` continua com suporte)
|
||||
- Autenticação HTTP basic: `set credentials user pass` (ou `--clear`)
|
||||
- Geolocalização: `set geo <lat> <lon> --origin "https://example.com"` (ou `--clear`)
|
||||
- Mídia: `set media dark|light|no-preference|none`
|
||||
- Fuso horário / localidade: `set timezone ...`, `set locale ...`
|
||||
@ -838,15 +860,15 @@ Eles são úteis para fluxos “faça o site se comportar como X”:
|
||||
|
||||
## Segurança e privacidade
|
||||
|
||||
- O perfil de navegador openclaw pode conter sessões autenticadas; trate-o como sensível.
|
||||
- O perfil de navegador openclaw pode conter sessões autenticadas; trate-o como algo sensível.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` e `wait --fn`
|
||||
executam JavaScript arbitrário no contexto da página. Prompt injection pode
|
||||
conduzir isso. Desabilite com `browser.evaluateEnabled=false` se você não precisar.
|
||||
- Para observações sobre logins e anti-bot (X/Twitter etc.), consulte [Browser login + X/Twitter posting](/tools/browser-login).
|
||||
- Mantenha o Gateway/node host privado (somente loopback ou tailnet).
|
||||
executam JavaScript arbitrário no contexto da página. Injeção de prompt pode conduzir
|
||||
isso. Desative com `browser.evaluateEnabled=false` se você não precisar disso.
|
||||
- Para logins e observações sobre anti-bot (X/Twitter etc.), veja [Login no navegador + postagem no X/Twitter](/pt-BR/tools/browser-login).
|
||||
- Mantenha o Gateway/host de nó privado (apenas loopback ou tailnet).
|
||||
- Endpoints CDP remotos são poderosos; faça túnel e proteja-os.
|
||||
|
||||
Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
Exemplo de modo estrito (bloquear destinos privados/internos por padrão):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -854,7 +876,7 @@ Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: false,
|
||||
hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
allowedHostnames: ["localhost"], // allow exato opcional
|
||||
allowedHostnames: ["localhost"], // permissão exata opcional
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -862,34 +884,34 @@ Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
Para problemas específicos de Linux (especialmente Chromium via snap), consulte
|
||||
[Browser troubleshooting](/tools/browser-linux-troubleshooting).
|
||||
Para problemas específicos de Linux (especialmente Chromium via snap), veja
|
||||
[Solução de problemas do navegador](/pt-BR/tools/browser-linux-troubleshooting).
|
||||
|
||||
Para configurações divididas WSL2 Gateway + Windows Chrome em hosts diferentes, consulte
|
||||
[WSL2 + Windows + remote Chrome CDP troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
Para configurações com Gateway no WSL2 + Chrome no Windows em hosts separados, veja
|
||||
[Solução de problemas de WSL2 + Windows + CDP remoto do Chrome](/pt-BR/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
## Ferramentas do agente + como o controle funciona
|
||||
|
||||
O agente recebe **uma ferramenta** para automação de navegador:
|
||||
O agente recebe **uma ferramenta** para automação do navegador:
|
||||
|
||||
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
Como isso é mapeado:
|
||||
Como isso se mapeia:
|
||||
|
||||
- `browser snapshot` retorna uma árvore de UI estável (AI ou ARIA).
|
||||
- `browser act` usa os IDs `ref` do snapshot para clicar/digitar/arrastar/selecionar.
|
||||
- `browser screenshot` captura pixels (página inteira ou elemento).
|
||||
- `browser` aceita:
|
||||
- `profile` para escolher um perfil nomeado de navegador (openclaw, chrome ou CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) para selecionar onde o navegador vive.
|
||||
- Em sessões sandboxed, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` for omitido: sessões sandboxed usam `sandbox` por padrão, sessões sem sandbox usam `host` por padrão.
|
||||
- Se um node com capacidade de navegador estiver conectado, a ferramenta pode rotear automaticamente para ele, a menos que você fixe `target="host"` ou `target="node"`.
|
||||
- `profile` para escolher um perfil nomeado do navegador (openclaw, chrome ou CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) para selecionar onde o navegador está.
|
||||
- Em sessões em sandbox, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` for omitido: sessões em sandbox usam `sandbox` por padrão, sessões sem sandbox usam `host` por padrão.
|
||||
- Se um nó com capacidade de navegador estiver conectado, a ferramenta poderá ser roteada automaticamente para ele, a menos que você fixe `target="host"` ou `target="node"`.
|
||||
|
||||
Isso mantém o agente determinístico e evita seletores frágeis.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Tools Overview](/tools) — todas as ferramentas de agente disponíveis
|
||||
- [Sandboxing](/pt-BR/gateway/sandboxing) — controle de navegador em ambientes sandboxed
|
||||
- [Security](/pt-BR/gateway/security) — riscos e endurecimento do controle de navegador
|
||||
- [Visão geral das ferramentas](/pt-BR/tools) — todas as ferramentas disponíveis para o agente
|
||||
- [Sandboxing](/pt-BR/gateway/sandboxing) — controle do navegador em ambientes em sandbox
|
||||
- [Segurança](/pt-BR/gateway/security) — riscos e fortalecimento do controle do navegador
|
||||
|
||||
Loading…
Reference in New Issue
Block a user