chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
7c027e2e89
commit
a491ec7f19
@ -6,10 +6,10 @@ read_when:
|
||||
summary: Tarefas agendadas, webhooks e gatilhos do Gmail PubSub para o agendador do Gateway
|
||||
title: Tarefas agendadas
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:44:19Z"
|
||||
generated_at: "2026-04-12T05:33:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665
|
||||
source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f
|
||||
source_path: automation/cron-jobs.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -21,7 +21,7 @@ Cron é o agendador integrado do Gateway. Ele persiste tarefas, ativa o agente n
|
||||
## Início rápido
|
||||
|
||||
```bash
|
||||
# Add a one-shot reminder
|
||||
# Adicione um lembrete de execução única
|
||||
openclaw cron add \
|
||||
--name "Reminder" \
|
||||
--at "2026-02-01T16:00:00Z" \
|
||||
@ -30,94 +30,106 @@ openclaw cron add \
|
||||
--wake now \
|
||||
--delete-after-run
|
||||
|
||||
# Check your jobs
|
||||
# Verifique suas tarefas
|
||||
openclaw cron list
|
||||
|
||||
# See run history
|
||||
# Veja o histórico de execuções
|
||||
openclaw cron runs --id <job-id>
|
||||
```
|
||||
|
||||
## Como o cron funciona
|
||||
|
||||
- O cron é executado **dentro do processo do Gateway** (não dentro do modelo).
|
||||
- As tarefas persistem em `~/.openclaw/cron/jobs.json`, para que reinicializações não percam os agendamentos.
|
||||
- O cron é executado **dentro do processo Gateway** (não dentro do modelo).
|
||||
- As tarefas persistem em `~/.openclaw/cron/jobs.json`, então reinicializações não fazem os agendamentos se perderem.
|
||||
- Todas as execuções do cron criam registros de [tarefa em segundo plano](/pt-BR/automation/tasks).
|
||||
- Tarefas de execução única (`--at`) são excluídas automaticamente após sucesso por padrão.
|
||||
- Execuções isoladas do cron fecham, em regime best-effort, abas/processos de navegador rastreados para a sessão `cron:<jobId>` quando a execução é concluída, para que a automação de navegador destacada não deixe processos órfãos para trás.
|
||||
- Execuções isoladas do cron também protegem contra respostas de confirmação obsoletas. Se o primeiro resultado for apenas uma atualização de status provisória (`on it`, `pulling everything together` e indicações semelhantes) e nenhuma execução descendente de subagente ainda for responsável pela resposta final, o OpenClaw faz um novo prompt uma vez para obter o resultado real antes da entrega.
|
||||
- Execuções isoladas de cron fazem, em caráter best-effort, o fechamento de abas/processos de navegador rastreados para a sessão `cron:<jobId>` quando a execução é concluída, para que automações de navegador destacadas não deixem processos órfãos.
|
||||
- Execuções isoladas de cron também se protegem contra respostas de confirmação obsoletas. Se o primeiro resultado for apenas uma atualização de status intermediária (`on it`, `pulling everything together` e dicas semelhantes) e nenhuma execução descendente de subagente ainda for responsável pela resposta final, o OpenClaw faz um novo prompt uma vez para obter o resultado real antes da entrega.
|
||||
|
||||
<a id="maintenance"></a>
|
||||
|
||||
A reconciliação de tarefas para o cron é de propriedade do runtime: uma tarefa ativa de cron permanece ativa enquanto o runtime do cron ainda rastrear essa tarefa como em execução, mesmo que uma linha antiga de sessão filha ainda exista.
|
||||
Quando o runtime deixa de ser responsável pela tarefa e a janela de tolerância de 5 minutos expira, a manutenção pode marcar a tarefa como `lost`.
|
||||
A reconciliação de tarefas para o cron pertence ao runtime: uma tarefa ativa de cron permanece ativa enquanto o runtime do cron ainda rastrear essa tarefa como em execução, mesmo que uma linha antiga de sessão filha ainda exista.
|
||||
Assim que o runtime deixar de ser responsável pela tarefa e a janela de tolerância de 5 minutos expirar, a manutenção poderá marcar a tarefa como `lost`.
|
||||
|
||||
## Tipos de agendamento
|
||||
|
||||
| Tipo | Flag da CLI | Descrição |
|
||||
| ------- | ----------- | ------------------------------------------------------------- |
|
||||
| Tipo | Flag da CLI | Descrição |
|
||||
| ------- | ----------- | ---------------------------------------------------------- |
|
||||
| `at` | `--at` | Timestamp de execução única (ISO 8601 ou relativo como `20m`) |
|
||||
| `every` | `--every` | Intervalo fixo |
|
||||
| `cron` | `--cron` | Expressão cron de 5 ou 6 campos com `--tz` opcional |
|
||||
| `every` | `--every` | Intervalo fixo |
|
||||
| `cron` | `--cron` | Expressão cron de 5 campos ou 6 campos com `--tz` opcional |
|
||||
|
||||
Timestamps sem fuso horário são tratados como UTC. Adicione `--tz America/New_York` para agendamento em horário local.
|
||||
Timestamps sem fuso horário são tratados como UTC. Adicione `--tz America/New_York` para agendamento por horário local.
|
||||
|
||||
Expressões recorrentes no início da hora são automaticamente escalonadas em até 5 minutos para reduzir picos de carga. Use `--exact` para forçar temporização precisa ou `--stagger 30s` para uma janela explícita.
|
||||
|
||||
### Dia do mês e dia da semana usam lógica OR
|
||||
|
||||
As expressões cron são analisadas pelo [croner](https://github.com/Hexagon/croner). Quando os campos de dia do mês e dia da semana não são curingas, o croner faz correspondência quando **qualquer um** dos campos corresponde — não ambos. Esse é o comportamento padrão do Vixie cron.
|
||||
|
||||
```
|
||||
# Pretendido: "9h da manhã no dia 15, apenas se for uma segunda-feira"
|
||||
# Real: "9h da manhã em todo dia 15, E 9h da manhã em toda segunda-feira"
|
||||
0 9 15 * 1
|
||||
```
|
||||
|
||||
Isso dispara ~5–6 vezes por mês em vez de 0–1 vez por mês. O OpenClaw usa aqui o comportamento OR padrão do Croner. Para exigir ambas as condições, use o modificador `+` de dia da semana do Croner (`0 9 15 * +1`) ou agende com base em um campo e valide o outro no prompt ou comando da sua tarefa.
|
||||
|
||||
## Estilos de execução
|
||||
|
||||
| Estilo | Valor de `--session` | Executa em | Melhor para |
|
||||
| --------------- | -------------------- | ------------------------ | ------------------------------ |
|
||||
| Estilo | Valor de `--session` | Executa em | Melhor para |
|
||||
| --------------- | -------------------- | ------------------------ | ------------------------------- |
|
||||
| Sessão principal | `main` | Próximo turno de heartbeat | Lembretes, eventos do sistema |
|
||||
| Isolado | `isolated` | `cron:<jobId>` dedicado | Relatórios, tarefas em segundo plano |
|
||||
| Sessão atual | `current` | Vinculada no momento da criação | Trabalho recorrente com contexto |
|
||||
| Sessão personalizada | `session:custom-id` | Sessão nomeada persistente | Fluxos de trabalho que constroem sobre o histórico |
|
||||
| Isolada | `isolated` | `cron:<jobId>` dedicado | Relatórios, tarefas em segundo plano |
|
||||
| Sessão atual | `current` | Vinculada na criação | Trabalho recorrente com contexto |
|
||||
| Sessão personalizada | `session:custom-id` | Sessão nomeada persistente | Fluxos que se baseiam no histórico |
|
||||
|
||||
Tarefas da **sessão principal** enfileiram um evento do sistema e opcionalmente ativam o heartbeat (`--wake now` ou `--wake next-heartbeat`). Tarefas **isoladas** executam um turno dedicado do agente com uma sessão nova. **Sessões personalizadas** (`session:xxx`) persistem o contexto entre execuções, permitindo fluxos de trabalho como resumos diários que se baseiam em resumos anteriores.
|
||||
Tarefas da **sessão principal** enfileiram um evento do sistema e opcionalmente ativam o heartbeat (`--wake now` ou `--wake next-heartbeat`). Tarefas **isoladas** executam um turno dedicado do agente com uma sessão nova. **Sessões personalizadas** (`session:xxx`) persistem contexto entre execuções, permitindo fluxos como reuniões diárias que se baseiam em resumos anteriores.
|
||||
|
||||
Para tarefas isoladas, o encerramento do runtime agora inclui limpeza de navegador em regime best-effort para essa sessão de cron. Falhas de limpeza são ignoradas para que o resultado real do cron continue prevalecendo.
|
||||
Para tarefas isoladas, o encerramento do runtime agora inclui limpeza best-effort do navegador para essa sessão de cron. Falhas de limpeza são ignoradas para que o resultado real do cron ainda prevaleça.
|
||||
|
||||
Quando execuções isoladas do cron orquestram subagentes, a entrega também prefere a saída final descendente em vez de texto provisório obsoleto do pai. Se os descendentes ainda estiverem em execução, o OpenClaw suprime essa atualização parcial do pai em vez de anunciá-la.
|
||||
Quando execuções isoladas de cron orquestram subagentes, a entrega também prefere a saída final descendente em vez de texto intermediário obsoleto do pai. Se descendentes ainda estiverem em execução, o OpenClaw suprime essa atualização parcial do pai em vez de anunciá-la.
|
||||
|
||||
### Opções de payload para tarefas isoladas
|
||||
|
||||
- `--message`: texto do prompt (obrigatório para isolado)
|
||||
- `--model` / `--thinking`: substituições de modelo e nível de raciocínio
|
||||
- `--light-context`: pula a injeção de arquivos de bootstrap do workspace
|
||||
- `--message`: texto do prompt (obrigatório para isolada)
|
||||
- `--model` / `--thinking`: substituições de modelo e nível de thinking
|
||||
- `--light-context`: ignora a injeção do arquivo de bootstrap do workspace
|
||||
- `--tools exec,read`: restringe quais ferramentas a tarefa pode usar
|
||||
|
||||
`--model` usa o modelo permitido selecionado para essa tarefa. Se o modelo solicitado não for permitido, o cron registra um aviso e volta para a seleção de modelo do agente/padrão da tarefa. Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples de modelo sem lista explícita de fallback por tarefa não acrescenta mais o modelo primário do agente como um destino extra oculto de nova tentativa.
|
||||
`--model` usa o modelo permitido selecionado para essa tarefa. Se o modelo solicitado não for permitido, o cron registra um aviso e volta para a seleção de modelo padrão/do agente dessa tarefa. Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples de modelo sem uma lista explícita de fallback por tarefa não acrescenta mais o primário do agente como um alvo extra oculto de nova tentativa.
|
||||
|
||||
A precedência de seleção de modelo para tarefas isoladas é:
|
||||
|
||||
1. Substituição de modelo do hook do Gmail (quando a execução veio do Gmail e essa substituição é permitida)
|
||||
2. `model` do payload por tarefa
|
||||
3. Substituição de modelo da sessão de cron armazenada
|
||||
4. Seleção de modelo do agente/padrão
|
||||
3. Substituição de modelo da sessão cron armazenada
|
||||
4. Seleção de modelo padrão/do agente
|
||||
|
||||
O modo rápido também segue a seleção ativa resolvida. Se a configuração do modelo selecionado tiver `params.fastMode`, o cron isolado usará isso por padrão. Uma substituição armazenada de `fastMode` da sessão ainda prevalece sobre a configuração em qualquer direção.
|
||||
O modo rápido também segue a seleção ativa resolvida. Se a configuração do modelo selecionado tiver `params.fastMode`, o cron isolado usa isso por padrão. Uma substituição armazenada de `fastMode` da sessão ainda prevalece sobre a configuração em qualquer direção.
|
||||
|
||||
Se uma execução isolada atingir uma transferência ativa de troca de modelo, o cron tenta novamente com o provedor/modelo alterado e persiste essa seleção ativa antes de tentar novamente. Quando a troca também traz um novo perfil de autenticação, o cron persiste essa substituição de perfil de autenticação também. As novas tentativas são limitadas: após a tentativa inicial mais 2 novas tentativas de troca, o cron aborta em vez de entrar em loop infinito.
|
||||
Se uma execução isolada atingir uma transferência ativa de troca de modelo, o cron tenta novamente com o provedor/modelo trocado e persiste essa seleção ativa antes da nova tentativa. Quando a troca também traz um novo perfil de autenticação, o cron também persiste essa substituição de perfil de autenticação. As novas tentativas são limitadas: após a tentativa inicial mais 2 novas tentativas de troca, o cron aborta em vez de entrar em loop infinito.
|
||||
|
||||
## Entrega e saída
|
||||
|
||||
| Modo | O que acontece |
|
||||
| --------- | ---------------------------------------------------------- |
|
||||
| `announce` | Entrega o resumo ao canal de destino (padrão para isolado) |
|
||||
| `webhook` | Faz POST do payload do evento concluído para uma URL |
|
||||
| `none` | Apenas interno, sem entrega |
|
||||
| Modo | O que acontece |
|
||||
| --------- | -------------------------------------------------------- |
|
||||
| `announce` | Entrega o resumo ao canal de destino (padrão para isolada) |
|
||||
| `webhook` | Envia payload do evento concluído por POST para uma URL |
|
||||
| `none` | Apenas interno, sem entrega |
|
||||
|
||||
Use `--announce --channel telegram --to "-1001234567890"` para entrega em canal. Para tópicos de fórum do Telegram, use `-1001234567890:topic:123`. Destinos do Slack/Discord/Mattermost devem usar prefixos explícitos (`channel:<id>`, `user:<id>`).
|
||||
Use `--announce --channel telegram --to "-1001234567890"` para entrega em canal. Para tópicos de fórum do Telegram, use `-1001234567890:topic:123`. Destinos de Slack/Discord/Mattermost devem usar prefixos explícitos (`channel:<id>`, `user:<id>`).
|
||||
|
||||
Para tarefas isoladas de propriedade do cron, o executor é responsável pelo caminho final de entrega. O agente recebe um prompt para retornar um resumo em texto simples, e esse resumo é então enviado por `announce`, `webhook` ou mantido interno para `none`. `--no-deliver` não devolve a entrega ao agente; ele mantém a execução interna.
|
||||
Para tarefas isoladas sob responsabilidade do cron, o executor é responsável pelo caminho final de entrega. O agente recebe um prompt para retornar um resumo em texto simples, e esse resumo é então enviado por `announce`, `webhook` ou mantido internamente para `none`. `--no-deliver` não devolve a entrega ao agente; ele mantém a execução interna.
|
||||
|
||||
Se a tarefa original disser explicitamente para enviar mensagem a algum destinatário externo, o agente deve informar em sua saída quem/onde essa mensagem deve ir, em vez de tentar enviá-la diretamente.
|
||||
Se a tarefa original disser explicitamente para enviar mensagem a algum destinatário externo, o agente deve indicar em sua saída quem/onde essa mensagem deve ir em vez de tentar enviá-la diretamente.
|
||||
|
||||
As notificações de falha seguem um caminho de destino separado:
|
||||
|
||||
- `cron.failureDestination` define um padrão global para notificações de falha.
|
||||
- `job.delivery.failureDestination` substitui isso por tarefa.
|
||||
- Se nenhum dos dois estiver definido e a tarefa já fizer entrega por `announce`, as notificações de falha agora usam como fallback esse destino principal de anúncio.
|
||||
- `delivery.failureDestination` é compatível apenas com tarefas `sessionTarget="isolated"`, a menos que o modo principal de entrega seja `webhook`.
|
||||
- Se nenhum dos dois estiver definido e a tarefa já entregar via `announce`, as notificações de falha agora usam esse destino principal de anúncio como fallback.
|
||||
- `delivery.failureDestination` só é compatível com tarefas `sessionTarget="isolated"` a menos que o modo principal de entrega seja `webhook`.
|
||||
|
||||
## Exemplos de CLI
|
||||
|
||||
@ -146,7 +158,7 @@ openclaw cron add \
|
||||
--to "channel:C1234567890"
|
||||
```
|
||||
|
||||
Tarefa isolada com substituição de modelo e raciocínio:
|
||||
Tarefa isolada com substituição de modelo e thinking:
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@ -162,7 +174,7 @@ openclaw cron add \
|
||||
|
||||
## Webhooks
|
||||
|
||||
O Gateway pode expor endpoints HTTP de webhook para gatilhos externos. Habilite na configuração:
|
||||
O Gateway pode expor endpoints HTTP de webhook para gatilhos externos. Ative na configuração:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -185,7 +197,7 @@ Tokens na query string são rejeitados.
|
||||
|
||||
### POST /hooks/wake
|
||||
|
||||
Enfileira um evento do sistema para a sessão principal:
|
||||
Enfileire um evento do sistema para a sessão principal:
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:18789/hooks/wake \
|
||||
@ -199,7 +211,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \
|
||||
|
||||
### POST /hooks/agent
|
||||
|
||||
Executa um turno isolado do agente:
|
||||
Execute um turno isolado do agente:
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:18789/hooks/agent \
|
||||
@ -219,32 +231,32 @@ Nomes de hook personalizados são resolvidos por `hooks.mappings` na configuraç
|
||||
- Mantenha os endpoints de hook atrás de loopback, tailnet ou proxy reverso confiável.
|
||||
- Use um token dedicado para hooks; não reutilize tokens de autenticação do gateway.
|
||||
- Mantenha `hooks.path` em um subcaminho dedicado; `/` é rejeitado.
|
||||
- Defina `hooks.allowedAgentIds` para limitar o roteamento explícito por `agentId`.
|
||||
- Defina `hooks.allowedAgentIds` para limitar o roteamento explícito de `agentId`.
|
||||
- Mantenha `hooks.allowRequestSessionKey=false`, a menos que você precise de sessões selecionadas pelo chamador.
|
||||
- Se você habilitar `hooks.allowRequestSessionKey`, também defina `hooks.allowedSessionKeyPrefixes` para restringir os formatos permitidos de chave de sessão.
|
||||
- Os payloads de hook são encapsulados com limites de segurança por padrão.
|
||||
- Se você ativar `hooks.allowRequestSessionKey`, também defina `hooks.allowedSessionKeyPrefixes` para restringir os formatos permitidos de chave de sessão.
|
||||
- Payloads de hook são encapsulados com limites de segurança por padrão.
|
||||
|
||||
## Integração com Gmail PubSub
|
||||
|
||||
Conecte gatilhos da caixa de entrada do Gmail ao OpenClaw via Google PubSub.
|
||||
|
||||
**Pré-requisitos**: CLI `gcloud`, `gog` (gogcli), hooks do OpenClaw habilitados, Tailscale para o endpoint HTTPS público.
|
||||
**Pré-requisitos**: CLI `gcloud`, `gog` (gogcli), hooks do OpenClaw ativados, Tailscale para o endpoint HTTPS público.
|
||||
|
||||
### Configuração com assistente (recomendado)
|
||||
### Configuração pelo assistente (recomendado)
|
||||
|
||||
```bash
|
||||
openclaw webhooks gmail setup --account openclaw@gmail.com
|
||||
```
|
||||
|
||||
Isso grava a configuração `hooks.gmail`, habilita o preset do Gmail e usa o Tailscale Funnel para o endpoint de push.
|
||||
Isso grava a configuração `hooks.gmail`, ativa a predefinição do Gmail e usa Tailscale Funnel para o endpoint de push.
|
||||
|
||||
### Inicialização automática do Gateway
|
||||
|
||||
Quando `hooks.enabled=true` e `hooks.gmail.account` estiver definido, o Gateway inicia `gog gmail watch serve` na inicialização e renova automaticamente o watch. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desativar isso.
|
||||
Quando `hooks.enabled=true` e `hooks.gmail.account` está definido, o Gateway inicia `gog gmail watch serve` na inicialização e renova automaticamente o watch. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desativar isso.
|
||||
|
||||
### Configuração manual única
|
||||
|
||||
1. Selecione o projeto do GCP que é dono do cliente OAuth usado por `gog`:
|
||||
1. Selecione o projeto do GCP que possui o cliente OAuth usado por `gog`:
|
||||
|
||||
```bash
|
||||
gcloud auth login
|
||||
@ -252,7 +264,7 @@ gcloud config set project <project-id>
|
||||
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
|
||||
```
|
||||
|
||||
2. Crie o tópico e conceda ao Gmail acesso de push:
|
||||
2. Crie o tópico e conceda acesso de push do Gmail:
|
||||
|
||||
```bash
|
||||
gcloud pubsub topics create gog-gmail-watch
|
||||
@ -283,28 +295,28 @@ gog gmail watch start \
|
||||
}
|
||||
```
|
||||
|
||||
## Gerenciamento de tarefas
|
||||
## Gerenciando tarefas
|
||||
|
||||
```bash
|
||||
# List all jobs
|
||||
# Liste todas as tarefas
|
||||
openclaw cron list
|
||||
|
||||
# Edit a job
|
||||
# Edite uma tarefa
|
||||
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
|
||||
|
||||
# Force run a job now
|
||||
# Force a execução de uma tarefa agora
|
||||
openclaw cron run <jobId>
|
||||
|
||||
# Run only if due
|
||||
# Execute apenas se estiver vencida
|
||||
openclaw cron run <jobId> --due
|
||||
|
||||
# View run history
|
||||
# Veja o histórico de execuções
|
||||
openclaw cron runs --id <jobId> --limit 50
|
||||
|
||||
# Delete a job
|
||||
# Exclua uma tarefa
|
||||
openclaw cron remove <jobId>
|
||||
|
||||
# Agent selection (multi-agent setups)
|
||||
# Seleção de agente (configurações com múltiplos agentes)
|
||||
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
|
||||
openclaw cron edit <jobId> --clear-agent
|
||||
```
|
||||
@ -312,9 +324,9 @@ openclaw cron edit <jobId> --clear-agent
|
||||
Observação sobre substituição de modelo:
|
||||
|
||||
- `openclaw cron add|edit --model ...` altera o modelo selecionado da tarefa.
|
||||
- Se o modelo for permitido, exatamente esse provedor/modelo chega à execução isolada do agente.
|
||||
- Se não for permitido, o cron emite um aviso e volta para a seleção de modelo do agente/padrão da tarefa.
|
||||
- Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples com `--model` sem lista explícita de fallback por tarefa não recai mais para o primário do agente como um destino extra silencioso de nova tentativa.
|
||||
- Se o modelo for permitido, exatamente esse provedor/modelo chega à execução do agente isolado.
|
||||
- Se não for permitido, o cron emite um aviso e retorna para a seleção de modelo padrão/do agente da tarefa.
|
||||
- Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples com `--model` sem uma lista explícita de fallback por tarefa não recai mais para o modelo primário do agente como um alvo extra silencioso de nova tentativa.
|
||||
|
||||
## Configuração
|
||||
|
||||
@ -329,7 +341,7 @@ Observação sobre substituição de modelo:
|
||||
backoffMs: [60000, 120000, 300000],
|
||||
retryOn: ["rate_limit", "overloaded", "network", "server_error"],
|
||||
},
|
||||
webhookToken: "substitua-por-um-token-dedicado-para-webhook",
|
||||
webhookToken: "replace-with-dedicated-webhook-token",
|
||||
sessionRetention: "24h",
|
||||
runLog: { maxBytes: "2mb", keepLines: 2000 },
|
||||
},
|
||||
@ -338,15 +350,15 @@ Observação sobre substituição de modelo:
|
||||
|
||||
Desative o cron: `cron.enabled: false` ou `OPENCLAW_SKIP_CRON=1`.
|
||||
|
||||
**Nova tentativa para execução única**: erros transitórios (limite de taxa, sobrecarga, rede, erro de servidor) tentam novamente até 3 vezes com backoff exponencial. Erros permanentes desativam imediatamente.
|
||||
**Nova tentativa de execução única**: erros transitórios (limite de taxa, sobrecarga, rede, erro de servidor) tentam novamente até 3 vezes com backoff exponencial. Erros permanentes desativam imediatamente.
|
||||
|
||||
**Nova tentativa recorrente**: backoff exponencial (30s a 60m) entre novas tentativas. O backoff é redefinido após a próxima execução bem-sucedida.
|
||||
|
||||
**Manutenção**: `cron.sessionRetention` (padrão `24h`) remove entradas de sessão de execuções isoladas. `cron.runLog.maxBytes` / `cron.runLog.keepLines` removem automaticamente arquivos de log de execução.
|
||||
**Manutenção**: `cron.sessionRetention` (padrão `24h`) remove entradas de sessão de execuções isoladas. `cron.runLog.maxBytes` / `cron.runLog.keepLines` fazem poda automática dos arquivos de log de execução.
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
### Escada de comandos
|
||||
### Sequência de comandos
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -362,19 +374,19 @@ openclaw doctor
|
||||
### O cron não dispara
|
||||
|
||||
- Verifique `cron.enabled` e a variável de ambiente `OPENCLAW_SKIP_CRON`.
|
||||
- Confirme que o Gateway está em execução contínua.
|
||||
- Para agendamentos `cron`, verifique o fuso horário (`--tz`) em relação ao fuso do host.
|
||||
- `reason: not-due` na saída da execução significa que a execução manual foi verificada com `openclaw cron run <jobId> --due` e que a tarefa ainda não estava vencida.
|
||||
- Confirme se o Gateway está em execução contínua.
|
||||
- Para agendamentos `cron`, verifique o fuso horário (`--tz`) em relação ao fuso horário do host.
|
||||
- `reason: not-due` na saída da execução significa que a execução manual foi verificada com `openclaw cron run <jobId> --due` e a tarefa ainda não estava vencida.
|
||||
|
||||
### O cron disparou, mas não houve entrega
|
||||
|
||||
- Modo de entrega `none` significa que nenhuma mensagem externa é esperada.
|
||||
- Destino de entrega ausente/inválido (`channel`/`to`) significa que a saída foi ignorada.
|
||||
- Erros de autenticação do canal (`unauthorized`, `Forbidden`) significam que a entrega foi bloqueada pelas credenciais.
|
||||
- Se a execução isolada retornar apenas o token silencioso (`NO_REPLY` / `no_reply`), o OpenClaw suprime a entrega de saída direta e também suprime o caminho de fallback de resumo enfileirado, portanto nada é publicado de volta no chat.
|
||||
- Para tarefas isoladas de propriedade do cron, não espere que o agente use a ferramenta de mensagem como fallback. O executor é responsável pela entrega final; `--no-deliver` a mantém interna em vez de permitir um envio direto.
|
||||
- Se a execução isolada retornar apenas o token silencioso (`NO_REPLY` / `no_reply`), o OpenClaw suprime a entrega direta para saída externa e também suprime o caminho de fallback do resumo enfileirado, então nada é publicado de volta no chat.
|
||||
- Para tarefas isoladas controladas pelo cron, não espere que o agente use a ferramenta de mensagem como fallback. O executor é responsável pela entrega final; `--no-deliver` a mantém interna em vez de permitir um envio direto.
|
||||
|
||||
### Armadilhas com fuso horário
|
||||
### Cuidados com fuso horário
|
||||
|
||||
- Cron sem `--tz` usa o fuso horário do host do gateway.
|
||||
- Agendamentos `at` sem fuso horário são tratados como UTC.
|
||||
@ -382,7 +394,7 @@ openclaw doctor
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Automação e tarefas](/pt-BR/automation) — visão geral de todos os mecanismos de automação
|
||||
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — registro de tarefas para execuções do cron
|
||||
- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em um só lugar
|
||||
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — registro de tarefas para execuções de cron
|
||||
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos da sessão principal
|
||||
- [Fuso horário](/pt-BR/concepts/timezone) — configuração de fuso horário
|
||||
|
||||
@ -3,28 +3,34 @@ 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 com bloqueio controlado pelo plugin que injeta memória relevante em sessões de chat interativas
|
||||
summary: Um subagente de memória de bloqueio controlado pelo plugin que injeta memória relevante em sessões de chat interativas
|
||||
title: Memória ativa
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T05:18:06Z"
|
||||
generated_at: "2026-04-12T05:33:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e8b0e6539e09678e9e8def68795f8bcb992f98509423da3da3123eda88ec1dd5
|
||||
source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memória ativa
|
||||
|
||||
A memória ativa é um subagente de memória opcional, com bloqueio e controlado por plugin, que é executado antes da resposta principal em sessões conversacionais qualificadas.
|
||||
A memória ativa é um subagente opcional de memória de bloqueio controlado pelo plugin que é executado
|
||||
antes da resposta principal em sessões conversacionais elegíveis.
|
||||
|
||||
Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem do agente principal para decidir quando pesquisar a 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 tornado a resposta mais natural já passou.
|
||||
Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem de
|
||||
o agente principal decidir quando pesquisar a memória, ou de o usuário dizer coisas
|
||||
como "lembre-se disso" ou "pesquise na memória". Quando isso acontece, 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 à tona memória relevante antes que a resposta principal seja gerada.
|
||||
A memória ativa dá ao sistema uma chance limitada de trazer memória relevante
|
||||
antes que a resposta principal seja gerada.
|
||||
|
||||
## Cole isto no seu agente
|
||||
|
||||
Cole isto no seu agente se quiser ativar a Memória ativa com uma configuração autônoma e segura por padrão:
|
||||
Cole isto no seu agente se quiser habilitar a Memória ativa com uma
|
||||
configuração autocontida e segura por padrão:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -36,7 +42,7 @@ Cole isto no seu agente se quiser ativar a Memória ativa com uma configuração
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
modelFallback: "google/gemini-3-flash",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
@ -50,7 +56,9 @@ Cole isto no seu agente se quiser ativar a Memória ativa com uma configuração
|
||||
}
|
||||
```
|
||||
|
||||
Isso ativa o plugin para o agente `main`, mantém seu uso limitado a sessões no estilo de mensagem direta por padrão, 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.
|
||||
Isso ativa o plugin para o agente `main`, o mantém limitado a sessões
|
||||
no estilo de mensagem direta por padrão, permite que ele herde primeiro o modelo da sessão atual
|
||||
e usa o modelo de fallback configurado apenas se nenhum modelo explícito ou herdado estiver disponível.
|
||||
|
||||
Depois disso, reinicie o gateway:
|
||||
|
||||
@ -58,19 +66,19 @@ Depois disso, reinicie o gateway:
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
Para inspecioná-la ao vivo em uma conversa:
|
||||
Para inspecioná-lo ao vivo em uma conversa:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## Ativar a memória ativa
|
||||
## Ative a memória ativa
|
||||
|
||||
A configuração mais segura é:
|
||||
|
||||
1. ativar o plugin
|
||||
1. habilitar o plugin
|
||||
2. direcioná-lo para um agente conversacional
|
||||
3. manter o logging ativado apenas durante o ajuste
|
||||
3. manter o registro ativado apenas durante o ajuste
|
||||
|
||||
Comece com isto em `openclaw.json`:
|
||||
|
||||
@ -83,7 +91,7 @@ Comece com isto em `openclaw.json`:
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
modelFallback: "google/gemini-3-flash",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
@ -97,7 +105,7 @@ Comece com isto em `openclaw.json`:
|
||||
}
|
||||
```
|
||||
|
||||
Em seguida, reinicie o gateway:
|
||||
Depois reinicie o gateway:
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -106,20 +114,22 @@ openclaw gateway
|
||||
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 mensagem direta
|
||||
- se `config.model` não estiver definido, a memória ativa primeiro herda 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.agents: ["main"]` habilita memória ativa apenas para o agente `main`
|
||||
- `config.allowedChatTypes: ["direct"]` mantém a memória ativa habilitada apenas para sessões no estilo de mensagem direta por padrão
|
||||
- se `config.model` não estiver definido, a memória ativa herda primeiro o modelo da sessão atual
|
||||
- `config.modelFallback` opcionalmente fornece seu próprio provedor/modelo de fallback para recuperação
|
||||
- `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 e interativas qualificadas
|
||||
- a memória ativa ainda é executada apenas em sessões de chat interativas persistentes elegíveis
|
||||
|
||||
## 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.
|
||||
A memória ativa injeta contexto de sistema oculto 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 para a sessão de chat atual sem editar a configuração:
|
||||
Use o comando do plugin quando quiser pausar ou retomar a memória ativa para a
|
||||
sessão de chat atual sem editar a configuração:
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
@ -127,9 +137,9 @@ Use o comando do plugin quando quiser pausar ou retomar a memória ativa para a
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
Isso vale apenas para a sessão. Não altera
|
||||
`plugins.entries.active-memory.enabled`, o direcionamento por agente nem outras
|
||||
configurações globais.
|
||||
Isso é restrito à sessão. Não altera
|
||||
`plugins.entries.active-memory.enabled`, o direcionamento do agente nem outra
|
||||
configuração global.
|
||||
|
||||
Se 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:
|
||||
@ -142,7 +152,7 @@ todas as sessões, use a forma global explícita:
|
||||
|
||||
A forma global grava `plugins.entries.active-memory.config.enabled`. Ela mantém
|
||||
`plugins.entries.active-memory.enabled` ativado para que o comando continue disponível para
|
||||
reativar a memória ativa mais tarde.
|
||||
reativar a memória ativa depois.
|
||||
|
||||
Se quiser ver o que a memória ativa está fazendo em uma sessão ao vivo, ative o modo
|
||||
verbose para essa sessão:
|
||||
@ -156,11 +166,11 @@ Com o verbose 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 execução da memória ativa que alimenta o contexto
|
||||
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 do prompt.
|
||||
|
||||
Por padrão, a transcrição do subagente de memória com bloqueio é temporária e excluída
|
||||
após a conclusão da execução.
|
||||
Por padrão, a transcrição do subagente de memória de bloqueio é temporária e é excluída
|
||||
depois que a execução é concluída.
|
||||
|
||||
Fluxo de exemplo:
|
||||
|
||||
@ -180,13 +190,14 @@ Formato de resposta visível esperado:
|
||||
|
||||
## Quando ela é executada
|
||||
|
||||
A memória ativa usa duas barreiras:
|
||||
A memória ativa usa dois critérios:
|
||||
|
||||
1. **Opt-in de configuração**
|
||||
O plugin deve estar ativado, e o id do agente atual deve aparecer em
|
||||
1. **Adesão via 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 ativada e direcionada, a memória ativa só é executada em sessões de chat persistentes e interativas qualificadas.
|
||||
2. **Elegibilidade estrita em tempo de execução**
|
||||
Mesmo quando habilitada e direcionada, a memória ativa é executada apenas em
|
||||
sessões de chat interativas persistentes elegíveis.
|
||||
|
||||
A regra real é:
|
||||
|
||||
@ -202,12 +213,11 @@ eligible interactive persistent chat session
|
||||
active memory runs
|
||||
```
|
||||
|
||||
Se qualquer uma dessas condições falhar, a memória ativa não será executada.
|
||||
Se qualquer um desses falhar, a memória ativa não será executada.
|
||||
|
||||
## Tipos de sessão
|
||||
|
||||
`config.allowedChatTypes` controla quais tipos de conversa podem executar a Memória
|
||||
ativa.
|
||||
`config.allowedChatTypes` controla em que tipos de conversa a Memória ativa pode ser executada.
|
||||
|
||||
O padrão é:
|
||||
|
||||
@ -215,8 +225,8 @@ O padrão é:
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
Isso significa que a Memória ativa é executada por padrão em sessões no estilo de
|
||||
mensagem direta, mas não em sessões de grupo ou canal, a menos que você as habilite explicitamente.
|
||||
Isso significa que a Memória ativa é executada por padrão em sessões no estilo de mensagem direta, mas
|
||||
não em sessões de grupo ou canal, a menos que você as habilite explicitamente.
|
||||
|
||||
Exemplos:
|
||||
|
||||
@ -235,16 +245,16 @@ 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.
|
||||
inferência em toda a plataforma.
|
||||
|
||||
| Superfície | Executa memória ativa? |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Control UI / sessões persistentes do chat na web | Sim, se o plugin estiver ativado e o agente for direcionado |
|
||||
| Outras sessões interativas de canal no mesmo caminho de chat persistente | Sim, se o plugin estiver ativado e o agente for direcionado |
|
||||
| Execuções headless de uso único | Não |
|
||||
| Execuções de heartbeat/em segundo plano | Não |
|
||||
| Sessões persistentes da Control UI / 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 de subagente/helper interno | Não |
|
||||
| Execução de subagente/auxiliar interno | Não |
|
||||
|
||||
## Por que usá-la
|
||||
|
||||
@ -260,14 +270,14 @@ Ela funciona especialmente bem para:
|
||||
- hábitos recorrentes
|
||||
- contexto de longo prazo do usuário que deve surgir naturalmente
|
||||
|
||||
Ela é pouco adequada para:
|
||||
Ela é uma escolha ruim para:
|
||||
|
||||
- automação
|
||||
- workers internos
|
||||
- tarefas de API de uso único
|
||||
- tarefas de API avulsas
|
||||
- lugares em que personalização oculta seria surpreendente
|
||||
|
||||
## Como ela funciona
|
||||
## Como funciona
|
||||
|
||||
O formato em tempo de execução é:
|
||||
|
||||
@ -280,7 +290,7 @@ flowchart LR
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
O subagente de memória com bloqueio pode usar apenas:
|
||||
O subagente de memória de bloqueio pode usar apenas:
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
@ -289,19 +299,19 @@ Se a conexão estiver fraca, ele deve retornar `NONE`.
|
||||
|
||||
## Modos de consulta
|
||||
|
||||
`config.queryMode` controla quanto da conversa o subagente de memória com bloqueio vê.
|
||||
`config.queryMode` controla quanto da conversa o subagente de memória de bloqueio vê.
|
||||
|
||||
## Estilos de prompt
|
||||
|
||||
`config.promptStyle` controla o quão disposto ou rigoroso o subagente de memória com bloqueio é
|
||||
`config.promptStyle` controla o 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 pouquíssima interferência do contexto próximo
|
||||
- `strict`: menos disposto; melhor quando você quer pouquíssimo vazamento 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 à tona em correspondências mais suaves, mas ainda plausíveis
|
||||
- `recall-heavy`: mais disposto a trazer memória em correspondências mais leves, 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
|
||||
|
||||
@ -321,7 +331,7 @@ Exemplo:
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## Política de fallback do modelo
|
||||
## Política de fallback de modelo
|
||||
|
||||
Se `config.model` não estiver definido, a Memória ativa tenta resolver um modelo nesta ordem:
|
||||
|
||||
@ -329,32 +339,28 @@ Se `config.model` não estiver definido, a Memória ativa tenta resolver um mode
|
||||
explicit plugin model
|
||||
-> current session model
|
||||
-> agent primary model
|
||||
-> optional built-in remote fallback
|
||||
-> optional configured fallback model
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` controla a última etapa.
|
||||
`config.modelFallback` controla a etapa de fallback configurado.
|
||||
|
||||
Padrão:
|
||||
Fallback personalizado opcional:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
modelFallback: "google/gemini-3-flash"
|
||||
```
|
||||
|
||||
Outra opção:
|
||||
Se nenhum modelo explícito, herdado ou de fallback configurado puder ser resolvido, a Memória ativa
|
||||
ignora a recuperação nesse turno.
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
`config.modelFallbackPolicy` é mantido apenas como um campo de compatibilidade obsoleto
|
||||
para configurações antigas. Ele não altera mais o comportamento em tempo de execução.
|
||||
|
||||
Use `resolved-only` se quiser que a Memória ativa ignore a recordação em vez de fazer
|
||||
fallback para o padrão remoto integrado quando nenhum modelo explícito ou herdado
|
||||
estiver disponível.
|
||||
## Escapes avançados
|
||||
|
||||
## Válvulas de escape avançadas
|
||||
Estas opções intencionalmente não fazem parte da configuração recomendada.
|
||||
|
||||
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 com bloqueio:
|
||||
`config.thinking` pode substituir o nível de thinking do subagente de memória de bloqueio:
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
@ -366,8 +372,8 @@ Padrão:
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
Não ative isso por padrão. A Memória ativa é executada no caminho da resposta, então o tempo extra
|
||||
de raciocínio aumenta diretamente a latência visível para o usuário.
|
||||
Não habilite isso por padrão. A Memória ativa é executada no caminho da resposta, então tempo
|
||||
extra de thinking aumenta diretamente a latência visível para o 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:
|
||||
@ -383,22 +389,22 @@ ainda acrescenta o contexto da conversa depois:
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
A personalização de prompt não é recomendada, a menos que você esteja testando deliberadamente um
|
||||
contrato de recordação diferente. O prompt padrão é ajustado para retornar `NONE`
|
||||
ou um contexto compacto de fato do usuário para o modelo principal.
|
||||
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 contexto compacto de fatos do usuário para o modelo principal.
|
||||
|
||||
### `message`
|
||||
|
||||
Somente a mensagem mais recente do usuário é enviada.
|
||||
Apenas a mensagem mais recente do usuário é enviada.
|
||||
|
||||
```text
|
||||
Latest user message only
|
||||
```
|
||||
|
||||
Use isto quando:
|
||||
Use isso quando:
|
||||
|
||||
- você quiser o comportamento mais rápido
|
||||
- você quiser o viés mais forte em direção à recordação de preferências estáveis
|
||||
- você quiser a maior inclinação para recuperar preferências estáveis
|
||||
- turnos de acompanhamento não precisarem de contexto conversacional
|
||||
|
||||
Tempo limite recomendado:
|
||||
@ -407,7 +413,7 @@ Tempo limite recomendado:
|
||||
|
||||
### `recent`
|
||||
|
||||
A mensagem mais recente do usuário mais uma pequena cauda recente da conversa são enviadas.
|
||||
A mensagem mais recente do usuário mais um pequeno trecho recente da conversa são enviados.
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
@ -419,7 +425,7 @@ Latest user message:
|
||||
...
|
||||
```
|
||||
|
||||
Use isto quando:
|
||||
Use isso quando:
|
||||
|
||||
- você quiser um melhor equilíbrio entre velocidade e embasamento conversacional
|
||||
- perguntas de acompanhamento frequentemente dependerem dos últimos turnos
|
||||
@ -430,7 +436,7 @@ Tempo limite recomendado:
|
||||
|
||||
### `full`
|
||||
|
||||
A conversa completa é enviada ao subagente de memória com bloqueio.
|
||||
A conversa completa é enviada ao subagente de memória de bloqueio.
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
@ -440,15 +446,15 @@ user: ...
|
||||
...
|
||||
```
|
||||
|
||||
Use isto quando:
|
||||
Use isso quando:
|
||||
|
||||
- a qualidade máxima de recordação importar mais do que a latência
|
||||
- a conversa contiver uma preparação importante muito antes no tópico
|
||||
- a melhor qualidade possível de recuperação importar mais do que a latência
|
||||
- a conversa contiver preparação importante muito antes no fio
|
||||
|
||||
Tempo limite recomendado:
|
||||
|
||||
- aumente-o substancialmente em comparação com `message` ou `recent`
|
||||
- comece em torno de `15000` ms ou mais, dependendo do tamanho do tópico
|
||||
- comece em torno de `15000` ms ou mais, dependendo do tamanho do fio
|
||||
|
||||
Em geral, o tempo limite deve aumentar com o tamanho do contexto:
|
||||
|
||||
@ -456,18 +462,18 @@ Em geral, o tempo limite deve aumentar com o tamanho do contexto:
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## Persistência da transcrição
|
||||
## Persistência de transcrição
|
||||
|
||||
As execuções do subagente de memória com bloqueio da memória ativa criam uma transcrição real `session.jsonl`
|
||||
durante a chamada do subagente de memória com bloqueio.
|
||||
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 com bloqueio
|
||||
- ela é excluída imediatamente após a conclusão da execução
|
||||
- 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 quiser manter essas transcrições do subagente de memória com bloqueio em disco para depuração ou
|
||||
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
|
||||
@ -487,11 +493,11 @@ inspeção, ative a persistência explicitamente:
|
||||
}
|
||||
```
|
||||
|
||||
Quando ativada, 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 de transcrição da conversa
|
||||
do usuário.
|
||||
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, em termos conceituais, é:
|
||||
O layout padrão é conceitualmente:
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
@ -501,9 +507,9 @@ Você pode alterar o subdiretório relativo com `config.transcriptDir`.
|
||||
|
||||
Use isso com cuidado:
|
||||
|
||||
- as transcrições do subagente de memória com 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
|
||||
- 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 da conversa
|
||||
- essas transcrições contêm contexto de prompt oculto e memórias recuperadas
|
||||
|
||||
## Configuração
|
||||
|
||||
@ -517,30 +523,30 @@ Os campos mais importantes são:
|
||||
|
||||
| Chave | Tipo | Significado |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `enabled` | `boolean` | Ativa o próprio plugin |
|
||||
| `enabled` | `boolean` | Habilita o próprio plugin |
|
||||
| `config.agents` | `string[]` | IDs de agentes que podem usar memória ativa |
|
||||
| `config.model` | `string` | Referência opcional do modelo do subagente de memória com bloqueio; quando não definido, a memória ativa usa o modelo da sessão atual |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla quanto da conversa o subagente de memória com bloqueio vê |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla o quão disposto ou rigoroso o subagente de memória com bloqueio é ao decidir se deve retornar memória |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Substituição avançada de raciocínio para o subagente de memória com 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 com bloqueio |
|
||||
| `config.maxSummaryChars` | `number` | Número máximo total de caracteres permitidos no resumo da memória ativa |
|
||||
| `config.model` | `string` | Referência opcional de modelo para o subagente de memória de bloqueio; quando não definido, a memória ativa usa o modelo da sessão atual |
|
||||
| `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 o quão disposto ou rigoroso o subagente de memória de bloqueio é ao decidir se retorna memória |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Substituição avançada de thinking para o subagente de memória de bloqueio; padrão `off` por 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 acrescentadas 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` | Total máximo de caracteres permitido no resumo da memória ativa |
|
||||
| `config.logging` | `boolean` | Emite logs da memória ativa durante o ajuste |
|
||||
| `config.persistTranscripts` | `boolean` | Mantém as transcrições do subagente de memória com bloqueio em disco em vez de excluir arquivos temporários |
|
||||
| `config.transcriptDir` | `string` | Diretório relativo das transcrições do subagente de memória com bloqueio dentro da pasta de sessões do agente |
|
||||
| `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 de transcrições do subagente de memória de bloqueio dentro da pasta de sessões do agente |
|
||||
|
||||
Campos úteis para ajuste:
|
||||
|
||||
| Chave | Tipo | Significado |
|
||||
| ----------------------------- | -------- | ----------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | Número máximo total de caracteres permitidos no resumo da memória ativa |
|
||||
| Chave | Tipo | Significado |
|
||||
| ----------------------------- | -------- | --------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | Total máximo de caracteres permitido no resumo da memória ativa |
|
||||
| `config.recentUserTurns` | `number` | Turnos anteriores do usuário a incluir quando `queryMode` for `recent` |
|
||||
| `config.recentAssistantTurns` | `number` | Turnos anteriores do assistente a incluir quando `queryMode` for `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 |
|
||||
| `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
|
||||
|
||||
@ -566,25 +572,25 @@ Comece com `recent`.
|
||||
}
|
||||
```
|
||||
|
||||
Se quiser inspecionar o comportamento em tempo real durante o ajuste, use `/verbose on` na
|
||||
Se você quiser inspecionar o comportamento ao vivo durante o ajuste, use `/verbose on` na
|
||||
sessão em vez de procurar um comando de depuração separado da memória ativa.
|
||||
|
||||
Depois passe para:
|
||||
Depois, mude para:
|
||||
|
||||
- `message` se quiser menor latência
|
||||
- `full` se decidir que contexto extra vale o subagente de memória com bloqueio mais lento
|
||||
- `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á ativado em `plugins.entries.active-memory.enabled`.
|
||||
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 e interativa.
|
||||
3. Confirme que você está testando por meio de uma sessão de chat interativa persistente.
|
||||
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 mais:
|
||||
Se os resultados da memória estiverem ruidosos, ajuste:
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
@ -592,7 +598,7 @@ Se a memória ativa estiver lenta demais:
|
||||
|
||||
- reduza `queryMode`
|
||||
- reduza `timeoutMs`
|
||||
- reduza a contagem de turnos recentes
|
||||
- reduza as contagens de turnos recentes
|
||||
- reduza os limites de caracteres por turno
|
||||
|
||||
## Páginas relacionadas
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Ao editar o texto do prompt do sistema, a lista de ferramentas ou as seções de hora/heartbeat
|
||||
- Ao alterar o bootstrap do workspace ou o comportamento de injeção de Skills
|
||||
- Editar o texto do prompt do sistema, a lista de ferramentas ou as seções de hora/heartbeat
|
||||
- Alterar o comportamento de bootstrap do workspace ou da injeção de Skills
|
||||
summary: O que o prompt do sistema do OpenClaw contém e como ele é montado
|
||||
title: Prompt do sistema
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:14:23Z"
|
||||
generated_at: "2026-04-12T05:33:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a
|
||||
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,65 +19,60 @@ O OpenClaw cria um prompt do sistema personalizado para cada execução de agent
|
||||
|
||||
O prompt é montado pelo OpenClaw e injetado em cada execução de agente.
|
||||
|
||||
Plugins de provedor podem contribuir com orientações de prompt com reconhecimento de cache sem substituir
|
||||
todo o prompt de propriedade do OpenClaw. O runtime do provedor pode:
|
||||
Plugins de provedor podem contribuir com orientações de prompt compatíveis com cache sem substituir o prompt completo de propriedade do OpenClaw. O runtime do provedor pode:
|
||||
|
||||
- substituir um pequeno conjunto de seções centrais nomeadas (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- injetar um **prefixo estável** acima do limite de cache do prompt
|
||||
- injetar um **sufixo dinâmico** abaixo do limite de cache do prompt
|
||||
|
||||
Use contribuições de propriedade do provedor para ajustes específicos por família de modelos. Mantenha a mutação legada de prompt
|
||||
`before_prompt_build` para compatibilidade ou mudanças de prompt verdadeiramente globais,
|
||||
não para o comportamento normal do provedor.
|
||||
Use contribuições de propriedade do provedor para ajustes específicos de famílias de modelos. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou para mudanças de prompt realmente globais, não para o comportamento normal do provedor.
|
||||
|
||||
## Estrutura
|
||||
|
||||
O prompt é intencionalmente compacto e usa seções fixas:
|
||||
|
||||
- **Ferramentas**: lembrete estruturado da fonte de verdade das ferramentas, além de orientações de uso de ferramentas em tempo de execução.
|
||||
- **Segurança**: lembrete curto de proteção para evitar comportamento de busca por poder ou desvio de supervisão.
|
||||
- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas mais orientações de runtime para uso de ferramentas.
|
||||
- **Segurança**: lembrete curto de proteção para evitar comportamento de busca por poder ou de contorno de supervisão.
|
||||
- **Skills** (quando disponíveis): informa ao modelo como carregar instruções de skill sob demanda.
|
||||
- **Autoatualização do OpenClaw**: como inspecionar a configuração com segurança usando
|
||||
`config.schema.lookup`, corrigir a configuração com `config.patch`, substituir a configuração inteira
|
||||
com `config.apply` e executar `update.run` apenas sob solicitação explícita do usuário. A ferramenta
|
||||
`gateway`, disponível apenas para o proprietário, também se recusa a reescrever
|
||||
`config.schema.lookup`, aplicar patch na configuração com `config.patch`, substituir a configuração completa com `config.apply` e executar `update.run` apenas mediante solicitação explícita do usuário. A ferramenta `gateway`, exclusiva do proprietário, também se recusa a reescrever
|
||||
`tools.exec.ask` / `tools.exec.security`, incluindo aliases legados `tools.bash.*`
|
||||
que são normalizados para esses caminhos protegidos de exec.
|
||||
que são normalizados para esses caminhos de exec protegidos.
|
||||
- **Workspace**: diretório de trabalho (`agents.defaults.workspace`).
|
||||
- **Documentação**: caminho local para a documentação do OpenClaw (repositório ou pacote npm) e quando lê-la.
|
||||
- **Arquivos do workspace (injetados)**: indica que arquivos de bootstrap estão incluídos abaixo.
|
||||
- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos da sandbox e se exec elevado está disponível.
|
||||
- **Arquivos do workspace (injetados)**: indica que os arquivos de bootstrap estão incluídos abaixo.
|
||||
- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos do sandbox e se exec com privilégios elevados está disponível.
|
||||
- **Data e hora atuais**: hora local do usuário, fuso horário e formato de hora.
|
||||
- **Tags de resposta**: sintaxe opcional de tags de resposta para provedores compatíveis.
|
||||
- **Heartbeats**: prompt de heartbeat e comportamento de ack, quando heartbeats estão habilitados para o agente padrão.
|
||||
- **Heartbeats**: prompt de heartbeat e comportamento de confirmação, quando heartbeats estão habilitados para o agente padrão.
|
||||
- **Runtime**: host, SO, node, raiz do repositório (quando detectada), nível de raciocínio (uma linha).
|
||||
- **Raciocínio**: nível atual de visibilidade + dica para alternância com /reasoning.
|
||||
- **Raciocínio**: nível atual de visibilidade + dica do toggle `/reasoning`.
|
||||
|
||||
A seção Ferramentas também inclui orientações de runtime para trabalhos de longa duração:
|
||||
|
||||
- use cron para acompanhamentos futuros (`check back later`, lembretes, trabalho recorrente)
|
||||
em vez de loops de sleep com `exec`, truques de atraso com `yieldMs` ou sondagem repetida de `process`
|
||||
- use cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente)
|
||||
em vez de loops de sleep com `exec`, truques de atraso com `yieldMs` ou polling repetido de `process`
|
||||
- use `exec` / `process` apenas para comandos que começam agora e continuam em execução
|
||||
em segundo plano
|
||||
- quando o wake automático na conclusão estiver habilitado, inicie o comando uma vez e conte com
|
||||
o caminho de wake baseado em push quando ele emitir saída ou falhar
|
||||
- quando o wake automático por conclusão estiver habilitado, inicie o comando uma vez e confie
|
||||
no caminho de wake baseado em push quando ele emitir saída ou falhar
|
||||
- use `process` para logs, status, entrada ou intervenção quando precisar
|
||||
inspecionar um comando em execução
|
||||
- se a tarefa for maior, prefira `sessions_spawn`; a conclusão do subagente é
|
||||
- se a tarefa for maior, prefira `sessions_spawn`; a conclusão de subagentes é
|
||||
baseada em push e é anunciada automaticamente de volta ao solicitante
|
||||
- não faça polling de `subagents list` / `sessions_list` em loop apenas para esperar
|
||||
- não faça polling de `subagents list` / `sessions_list` em loop apenas para aguardar
|
||||
a conclusão
|
||||
|
||||
Quando a ferramenta experimental `update_plan` está habilitada, Ferramentas também informa ao
|
||||
modelo para usá-la apenas em trabalhos não triviais de várias etapas, manter exatamente uma
|
||||
modelo para usá-la apenas em trabalhos não triviais com múltiplas etapas, manter exatamente uma
|
||||
etapa `in_progress` e evitar repetir o plano inteiro após cada atualização.
|
||||
|
||||
As proteções de segurança no prompt do sistema são consultivas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e listas de permissão de canais para imposição rígida; operadores podem desativá-las por design.
|
||||
As proteções de segurança no prompt do sistema são consultivas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e listas de permissões de canais para imposição rígida; operadores podem desativá-las por design.
|
||||
|
||||
Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora informa ao
|
||||
agente que ele deve depender primeiro dessa interface nativa de aprovação. Ele só deve incluir um
|
||||
comando manual `/approve` quando o resultado da ferramenta disser que aprovações no chat não estão disponíveis ou
|
||||
agente para depender primeiro dessa UI de aprovação nativa. Ele só deve incluir um comando manual
|
||||
`/approve` quando o resultado da ferramenta disser que aprovações no chat não estão disponíveis ou
|
||||
que a aprovação manual é o único caminho.
|
||||
|
||||
## Modos de prompt
|
||||
@ -90,14 +85,14 @@ O OpenClaw pode renderizar prompts do sistema menores para subagentes. O runtime
|
||||
**Mensagens**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**,
|
||||
Workspace, Sandbox, Data e hora atuais (quando conhecidas), Runtime e contexto
|
||||
injetado continuam disponíveis.
|
||||
- `none`: retorna apenas a linha base de identidade.
|
||||
- `none`: retorna apenas a linha de identidade base.
|
||||
|
||||
Quando `promptMode=minimal`, prompts extras injetados são rotulados como **Contexto do subagente**
|
||||
em vez de **Contexto do chat em grupo**.
|
||||
|
||||
## Injeção de bootstrap do workspace
|
||||
|
||||
Arquivos de bootstrap são recortados e anexados em **Contexto do projeto** para que o modelo veja o contexto de identidade e perfil sem precisar de leituras explícitas:
|
||||
Os arquivos de bootstrap são aparados e anexados em **Contexto do projeto** para que o modelo veja o contexto de identidade e perfil sem precisar fazer leituras explícitas:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -106,18 +101,19 @@ Arquivos de bootstrap são recortados e anexados em **Contexto do projeto** para
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (apenas em workspaces totalmente novos)
|
||||
- `MEMORY.md` quando presente; caso contrário, `memory.md` como fallback em minúsculas
|
||||
- `MEMORY.md` quando presente, caso contrário `memory.md` como fallback em minúsculas
|
||||
|
||||
Todos esses arquivos são **injetados na janela de contexto** em cada turno, a menos que
|
||||
uma regra específica do arquivo se aplique. `HEARTBEAT.md` é omitido em execuções normais quando
|
||||
heartbeats estão desabilitados para o agente padrão ou
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos
|
||||
injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a
|
||||
uso de contexto inesperadamente alto e compactação mais frequente.
|
||||
se aplique um gate específico do arquivo. `HEARTBEAT.md` é omitido em execuções normais quando
|
||||
heartbeats estão desabilitados para o agente padrão ou quando
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a uso de contexto inesperadamente alto e compactação mais frequente.
|
||||
|
||||
> **Observação:** arquivos diários `memory/*.md` **não** são injetados automaticamente. Eles
|
||||
> são acessados sob demanda por meio das ferramentas `memory_search` e `memory_get`, portanto
|
||||
> não contam contra a janela de contexto, a menos que o modelo os leia explicitamente.
|
||||
> **Observação:** arquivos diários `memory/*.md` **não** fazem parte do bootstrap normal de
|
||||
> Contexto do projeto. Em turnos comuns, eles são acessados sob demanda por meio das
|
||||
> ferramentas `memory_search` e `memory_get`, portanto não contam contra a janela de
|
||||
> contexto, a menos que o modelo os leia explicitamente. Turnos simples de `/new` e
|
||||
> `/reset` são a exceção: o runtime pode prependar memória diária recente
|
||||
> como um bloco único de contexto de inicialização para esse primeiro turno.
|
||||
|
||||
Arquivos grandes são truncados com um marcador. O tamanho máximo por arquivo é controlado por
|
||||
`agents.defaults.bootstrapMaxChars` (padrão: 20000). O conteúdo total de bootstrap injetado
|
||||
@ -130,22 +126,22 @@ padrão: `once`).
|
||||
Sessões de subagente injetam apenas `AGENTS.md` e `TOOLS.md` (os outros arquivos de bootstrap
|
||||
são filtrados para manter pequeno o contexto do subagente).
|
||||
|
||||
Hooks internos podem interceptar esta etapa via `agent:bootstrap` para mutar ou substituir
|
||||
Hooks internos podem interceptar esta etapa via `agent:bootstrap` para modificar ou substituir
|
||||
os arquivos de bootstrap injetados (por exemplo, trocando `SOUL.md` por uma persona alternativa).
|
||||
|
||||
Se você quiser tornar o agente menos genérico, comece com o
|
||||
Se você quiser fazer o agente soar menos genérico, comece com
|
||||
[Guia de personalidade do SOUL.md](/pt-BR/concepts/soul).
|
||||
|
||||
Para inspecionar quanto cada arquivo injetado contribui (bruto vs. injetado, truncamento, além do overhead de schema de ferramenta), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context).
|
||||
Para inspecionar quanto cada arquivo injetado contribui (bruto vs. injetado, truncamento, além da sobrecarga do schema de ferramentas), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context).
|
||||
|
||||
## Tratamento de hora
|
||||
## Tratamento de tempo
|
||||
|
||||
O prompt do sistema inclui uma seção dedicada **Data e hora atuais** quando o
|
||||
fuso horário do usuário é conhecido. Para manter a estabilidade do cache do prompt, ele agora inclui apenas
|
||||
o **fuso horário** (sem relógio dinâmico nem formato de hora).
|
||||
fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ele inclui apenas o
|
||||
**fuso horário** (sem relógio dinâmico nem formato de hora).
|
||||
|
||||
Use `session_status` quando o agente precisar da hora atual; o cartão de status
|
||||
inclui uma linha de timestamp. A mesma ferramenta pode opcionalmente definir uma substituição
|
||||
inclui uma linha de timestamp. A mesma ferramenta também pode opcionalmente definir uma substituição
|
||||
de modelo por sessão (`model=default` a limpa).
|
||||
|
||||
Configure com:
|
||||
@ -153,18 +149,18 @@ Configure com:
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
Consulte [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento.
|
||||
Veja [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento.
|
||||
|
||||
## Skills
|
||||
|
||||
Quando há Skills elegíveis, o OpenClaw injeta uma **lista compacta de Skills disponíveis**
|
||||
Quando existem skills elegíveis, o OpenClaw injeta uma **lista compacta de skills disponíveis**
|
||||
(`formatSkillsForPrompt`) que inclui o **caminho do arquivo** de cada skill. O
|
||||
prompt instrui o modelo a usar `read` para carregar o SKILL.md no local listado
|
||||
(workspace, gerenciado ou empacotado). Se nenhuma skill for elegível, a seção
|
||||
(workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a seção
|
||||
Skills é omitida.
|
||||
|
||||
A elegibilidade inclui regras de metadados da skill, verificações de ambiente/configuração de runtime
|
||||
e a lista de permissão efetiva de skills do agente quando `agents.defaults.skills` ou
|
||||
A elegibilidade inclui gates de metadados da skill, verificações de ambiente/configuração de runtime
|
||||
e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou
|
||||
`agents.list[].skills` está configurado.
|
||||
|
||||
```
|
||||
@ -177,13 +173,13 @@ e a lista de permissão efetiva de skills do agente quando `agents.defaults.skil
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Isso mantém o prompt base pequeno, ao mesmo tempo em que ainda permite uso direcionado de skills.
|
||||
Isso mantém o prompt base pequeno, ao mesmo tempo que ainda permite uso direcionado de skills.
|
||||
|
||||
## Documentação
|
||||
|
||||
Quando disponível, o prompt do sistema inclui uma seção **Documentação** que aponta para o
|
||||
diretório local da documentação do OpenClaw (seja `docs/` no workspace do repositório ou a
|
||||
documentação empacotada do pacote npm) e também menciona o espelho público, o repositório de origem, o Discord da comunidade e o
|
||||
diretório local da documentação do OpenClaw (seja `docs/` no workspace do repositório ou a documentação do
|
||||
pacote npm empacotado) e também menciona o espelho público, o repositório de origem, o Discord da comunidade e o
|
||||
ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descoberta de skills. O prompt instrui o modelo a consultar primeiro a documentação local
|
||||
para comportamento, comandos, configuração ou arquitetura do OpenClaw, e a executar
|
||||
para comportamento, comandos, configuração ou arquitetura do OpenClaw e a executar
|
||||
`openclaw status` por conta própria quando possível (pedindo ao usuário apenas quando não tiver acesso).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Você está criando um plugin do OpenClaw
|
||||
- Você precisa fornecer um schema de configuração do plugin ou depurar erros de validação do plugin
|
||||
summary: Manifesto do plugin + requisitos do schema JSON (validação estrita de configuração)
|
||||
- Você precisa fornecer um esquema de configuração do plugin ou depurar erros de validação do plugin
|
||||
summary: Manifesto do plugin + requisitos do esquema JSON (validação estrita de configuração)
|
||||
title: Manifesto do plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T15:16:04Z"
|
||||
generated_at: "2026-04-12T05:33:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4
|
||||
source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,46 +17,61 @@ x-i18n:
|
||||
|
||||
Esta página é apenas para o **manifesto nativo de plugin do OpenClaw**.
|
||||
|
||||
Para layouts de bundle compatíveis, consulte [Bundles de plugin](/pt-BR/plugins/bundles).
|
||||
Para layouts de bundle compatíveis, veja [Bundles de plugins](/pt-BR/plugins/bundles).
|
||||
|
||||
Formatos de bundle compatíveis usam arquivos de manifesto diferentes:
|
||||
|
||||
- Bundle do Codex: `.codex-plugin/plugin.json`
|
||||
- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude sem manifesto
|
||||
- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude
|
||||
sem manifesto
|
||||
- Bundle do Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados em relação ao schema `openclaw.plugin.json` descrito aqui.
|
||||
O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados
|
||||
em relação ao esquema `openclaw.plugin.json` descrito aqui.
|
||||
|
||||
Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle, além das raízes de Skills declaradas, raízes de comandos do Claude, padrões de `settings.json` do bundle do Claude, padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde às expectativas de runtime do OpenClaw.
|
||||
Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle mais as
|
||||
raízes de skill declaradas, raízes de comando do Claude, padrões `settings.json` do bundle do Claude,
|
||||
padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde
|
||||
às expectativas de runtime do OpenClaw.
|
||||
|
||||
Todo plugin nativo do OpenClaw **deve** fornecer um arquivo `openclaw.plugin.json` na **raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração **sem executar o código do plugin**. Manifestos ausentes ou inválidos são tratados como erros de plugin e bloqueiam a validação da configuração.
|
||||
Todo plugin nativo do OpenClaw **deve** fornecer um arquivo `openclaw.plugin.json` na
|
||||
**raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração
|
||||
**sem executar o código do plugin**. Manifestos ausentes ou inválidos são tratados como
|
||||
erros de plugin e bloqueiam a validação da configuração.
|
||||
|
||||
Consulte o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin).
|
||||
Veja o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin).
|
||||
Para o modelo nativo de capacidades e a orientação atual de compatibilidade externa:
|
||||
[Modelo de capacidades](/pt-BR/plugins/architecture#public-capability-model).
|
||||
|
||||
## O que este arquivo faz
|
||||
## O que esse arquivo faz
|
||||
|
||||
`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o código do seu plugin.
|
||||
`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o
|
||||
código do seu plugin.
|
||||
|
||||
Use-o para:
|
||||
|
||||
- identidade do plugin
|
||||
- validação de configuração
|
||||
- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o runtime do plugin
|
||||
- dicas de ativação leves que as superfícies do plano de controle podem inspecionar antes de o runtime ser carregado
|
||||
- descritores de configuração leves que as superfícies de configuração/onboarding podem inspecionar antes de o runtime ser carregado
|
||||
- metadados de alias e autoativação que devem ser resolvidos antes de o runtime do plugin ser carregado
|
||||
- metadados abreviados de propriedade de família de modelos que devem autoativar o plugin antes de o runtime ser carregado
|
||||
- snapshots estáticos de propriedade de capacidades usados para o cabeamento de compatibilidade empacotado e cobertura de contrato
|
||||
- metadados de configuração específicos de canal que devem ser mesclados em superfícies de catálogo e validação sem carregar o runtime
|
||||
- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o
|
||||
runtime do plugin
|
||||
- dicas baratas de ativação que superfícies do plano de controle podem inspecionar antes de o runtime
|
||||
carregar
|
||||
- descritores baratos de configuração que superfícies de configuração/onboarding podem inspecionar antes
|
||||
de o runtime carregar
|
||||
- metadados de alias e autoativação que devem ser resolvidos antes de o runtime do plugin carregar
|
||||
- metadados abreviados de propriedade de família de modelos que devem autoativar o
|
||||
plugin antes de o runtime carregar
|
||||
- snapshots estáticos de propriedade de capacidades usados para wiring de compatibilidade
|
||||
empacotada e cobertura de contrato
|
||||
- metadados de configuração específicos de canal que devem ser mesclados em superfícies
|
||||
de catálogo e validação sem carregar o runtime
|
||||
- dicas de UI de configuração
|
||||
|
||||
Não o use para:
|
||||
|
||||
- registrar comportamento de runtime
|
||||
- declarar entrypoints de código
|
||||
- metadados de instalação do npm
|
||||
- metadados de instalação npm
|
||||
|
||||
Esses pertencem ao código do seu plugin e ao `package.json`.
|
||||
|
||||
@ -129,62 +144,64 @@ Esses pertencem ao código do seu plugin e ao `package.json`.
|
||||
}
|
||||
```
|
||||
|
||||
## Referência dos campos de nível superior
|
||||
## Referência de campos de nível superior
|
||||
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `id` | Sim | `string` | ID canônico do plugin. Este é o ID usado em `plugins.entries.<id>`. |
|
||||
| `configSchema` | Sim | `object` | Schema JSON inline para a configuração deste plugin. |
|
||||
| `enabledByDefault` | Não | `true` | Marca um plugin empacotado como habilitado por padrão. Omita-o ou defina qualquer valor diferente de `true` para deixar o plugin desabilitado por padrão. |
|
||||
| `id` | Sim | `string` | ID canônico do plugin. Esse é o ID usado em `plugins.entries.<id>`. |
|
||||
| `configSchema` | Sim | `object` | Esquema JSON inline para a configuração deste plugin. |
|
||||
| `enabledByDefault` | Não | `true` | Marca um plugin empacotado como habilitado por padrão. Omita-o, ou defina qualquer valor diferente de `true`, para manter o plugin desabilitado por padrão. |
|
||||
| `legacyPluginIds` | Não | `string[]` | IDs legados que são normalizados para este ID canônico de plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Não | `string[]` | IDs de provedores que devem autoativar este plugin quando autenticação, configuração ou referências de modelo os mencionarem. |
|
||||
| `autoEnableWhenConfiguredProviders` | Não | `string[]` | IDs de provedores que devem autoativar este plugin quando autenticação, configuração ou referências de modelo os mencionarem. |
|
||||
| `kind` | Não | `"memory"` \| `"context-engine"` | Declara um tipo exclusivo de plugin usado por `plugins.slots.*`. |
|
||||
| `channels` | Não | `string[]` | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração. |
|
||||
| `channels` | Não | `string[]` | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração. |
|
||||
| `providers` | Não | `string[]` | IDs de provedores pertencentes a este plugin. |
|
||||
| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto usados para carregar automaticamente o plugin antes do runtime. |
|
||||
| `cliBackends` | Não | `string[]` | IDs de backends de inferência da CLI pertencentes a este plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração. |
|
||||
| `commandAliases` | Não | `object[]` | Nomes de comandos pertencentes a este plugin que devem produzir diagnósticos de configuração e CLI cientes do plugin antes de o runtime ser carregado. |
|
||||
| `providerAuthEnvVars` | Não | `Record<string, string[]>` | Metadados leves de variáveis de ambiente de autenticação de provedor que o OpenClaw pode inspecionar sem carregar o código do plugin. |
|
||||
| `providerAuthAliases` | Não | `Record<string, string>` | IDs de provedores que devem reutilizar outro ID de provedor para busca de autenticação, por exemplo, um provedor de programação que compartilha a chave de API do provedor base e perfis de autenticação. |
|
||||
| `channelEnvVars` | Não | `Record<string, string[]>` | Metadados leves de variáveis de ambiente de canal que o OpenClaw pode inspecionar sem carregar o código do plugin. Use isso para configuração de canal orientada por env ou superfícies de autenticação que helpers genéricos de inicialização/configuração devem enxergar. |
|
||||
| `providerAuthChoices` | Não | `object[]` | Metadados leves de opções de autenticação para seletores de onboarding, resolução de provedor preferido e cabeamento simples de flags de CLI. |
|
||||
| `activation` | Não | `object` | Dicas leves de ativação para carregamento acionado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do plugin ainda é dono do comportamento real. |
|
||||
| `setup` | Não | `object` | Descritores leves de configuração/onboarding que superfícies de descoberta e configuração podem inspecionar sem carregar o runtime do plugin. |
|
||||
| `contracts` | Não | `object` | Snapshot estático de capacidades empacotadas para fala, transcrição em tempo real, voz em tempo real, media-understanding, geração de imagem, geração de música, geração de vídeo, web-fetch, busca na web e propriedade de ferramentas. |
|
||||
| `channelConfigs` | Não | `Record<string, object>` | Metadados de configuração de canal pertencentes ao manifesto mesclados em superfícies de descoberta e validação antes de o runtime ser carregado. |
|
||||
| `skills` | Não | `string[]` | Diretórios de Skills para carregar, relativos à raiz do plugin. |
|
||||
| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto usados para autocarregar o plugin antes do runtime. |
|
||||
| `cliBackends` | Não | `string[]` | IDs de backend de inferência da CLI pertencentes a este plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração. |
|
||||
| `commandAliases` | Não | `object[]` | Nomes de comando pertencentes a este plugin que devem produzir diagnósticos de configuração e CLI com reconhecimento de plugin antes de o runtime carregar. |
|
||||
| `providerAuthEnvVars` | Não | `Record<string, string[]>` | Metadados leves de variáveis de ambiente de autenticação do provedor que o OpenClaw pode inspecionar sem carregar o código do plugin. |
|
||||
| `providerAuthAliases` | Não | `Record<string, string>` | IDs de provedores que devem reutilizar outro ID de provedor para busca de autenticação, por exemplo um provedor de código que compartilha a chave de API e os perfis de autenticação do provedor base. |
|
||||
| `channelEnvVars` | Não | `Record<string, string[]>` | Metadados leves de variáveis de ambiente de canal que o OpenClaw pode inspecionar sem carregar o código do plugin. Use isso para superfícies de configuração ou autenticação de canal baseadas em env que helpers genéricos de inicialização/configuração devem enxergar. |
|
||||
| `providerAuthChoices` | Não | `object[]` | Metadados leves de escolha de autenticação para seletores de onboarding, resolução de provedor preferencial e wiring simples de flags da CLI. |
|
||||
| `activation` | Não | `object` | Dicas leves de ativação para carregamento disparado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do plugin ainda é dono do comportamento real. |
|
||||
| `setup` | Não | `object` | Descritores leves de configuração/onboarding que superfícies de descoberta e configuração podem inspecionar sem carregar o runtime do plugin. |
|
||||
| `contracts` | Não | `object` | Snapshot estático de capacidades empacotadas para fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração de imagem, geração de música, geração de vídeo, web-fetch, pesquisa na web e propriedade de ferramentas. |
|
||||
| `channelConfigs` | Não | `Record<string, object>` | Metadados de configuração de canal pertencentes ao manifesto, mesclados em superfícies de descoberta e validação antes de o runtime carregar. |
|
||||
| `skills` | Não | `string[]` | Diretórios de Skills a carregar, relativos à raiz do plugin. |
|
||||
| `name` | Não | `string` | Nome legível do plugin. |
|
||||
| `description` | Não | `string` | Resumo curto mostrado em superfícies de plugin. |
|
||||
| `description` | Não | `string` | Resumo curto mostrado nas superfícies do plugin. |
|
||||
| `version` | Não | `string` | Versão informativa do plugin. |
|
||||
| `uiHints` | Não | `Record<string, object>` | Rótulos de UI, placeholders e dicas de sensibilidade para campos de configuração. |
|
||||
|
||||
## Referência de `providerAuthChoices`
|
||||
|
||||
Cada entrada em `providerAuthChoices` descreve uma opção de onboarding ou autenticação.
|
||||
O OpenClaw lê isso antes de o runtime do provedor ser carregado.
|
||||
Cada entrada de `providerAuthChoices` descreve uma escolha de onboarding ou autenticação.
|
||||
O OpenClaw lê isso antes de o runtime do provedor carregar.
|
||||
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Sim | `string` | ID do provedor ao qual esta opção pertence. |
|
||||
| `method` | Sim | `string` | ID do método de autenticação para encaminhamento. |
|
||||
| `choiceId` | Sim | `string` | ID estável da opção de autenticação usado por fluxos de onboarding e CLI. |
|
||||
| `choiceLabel` | Não | `string` | Rótulo visível ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. |
|
||||
| `choiceHint` | Não | `string` | Texto curto de ajuda para o seletor. |
|
||||
| `assistantPriority` | Não | `number` | Valores menores são ordenados antes em seletores interativos conduzidos pelo assistente. |
|
||||
| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a opção dos seletores do assistente, mas ainda permite seleção manual pela CLI. |
|
||||
| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de opções que devem redirecionar usuários para esta opção de substituição. |
|
||||
| `groupId` | Não | `string` | ID opcional de grupo para agrupar opções relacionadas. |
|
||||
| `groupLabel` | Não | `string` | Rótulo visível ao usuário para esse grupo. |
|
||||
| `groupHint` | Não | `string` | Texto curto de ajuda para o grupo. |
|
||||
| `optionKey` | Não | `string` | Chave de opção interna para fluxos simples de autenticação com uma única flag. |
|
||||
| `cliFlag` | Não | `string` | Nome da flag da CLI, como `--openrouter-api-key`. |
|
||||
| `cliOption` | Não | `string` | Formato completo da opção da CLI, como `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. |
|
||||
| `onboardingScopes` | Não | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta opção deve aparecer. Se omitido, o padrão é `["text-inference"]`. |
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Sim | `string` | ID do provedor ao qual esta escolha pertence. |
|
||||
| `method` | Sim | `string` | ID do método de autenticação para o qual encaminhar. |
|
||||
| `choiceId` | Sim | `string` | ID estável de escolha de autenticação usado por fluxos de onboarding e da CLI. |
|
||||
| `choiceLabel` | Não | `string` | Rótulo voltado ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. |
|
||||
| `choiceHint` | Não | `string` | Texto curto de ajuda para o seletor. |
|
||||
| `assistantPriority` | Não | `number` | Valores menores aparecem primeiro em seletores interativos conduzidos pelo assistente. |
|
||||
| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a escolha dos seletores do assistente, mas ainda permite seleção manual pela CLI. |
|
||||
| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de escolha que devem redirecionar os usuários para esta escolha de substituição. |
|
||||
| `groupId` | Não | `string` | ID de grupo opcional para agrupar escolhas relacionadas. |
|
||||
| `groupLabel` | Não | `string` | Rótulo voltado ao usuário para esse grupo. |
|
||||
| `groupHint` | Não | `string` | Texto curto de ajuda para o grupo. |
|
||||
| `optionKey` | Não | `string` | Chave interna de opção para fluxos simples de autenticação com uma única flag. |
|
||||
| `cliFlag` | Não | `string` | Nome da flag da CLI, como `--openrouter-api-key`. |
|
||||
| `cliOption` | Não | `string` | Formato completo da opção da CLI, como `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. |
|
||||
| `onboardingScopes` | Não | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta escolha deve aparecer. Se omitido, o padrão é `["text-inference"]`. |
|
||||
|
||||
## Referência de `commandAliases`
|
||||
|
||||
Use `commandAliases` quando um plugin é dono de um nome de comando de runtime que os usuários podem colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw usa esses metadados para diagnósticos sem importar o código de runtime do plugin.
|
||||
Use `commandAliases` quando um plugin é dono de um nome de comando de runtime que os usuários podem
|
||||
colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw
|
||||
usa esses metadados para diagnósticos sem importar o código de runtime do plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -198,17 +215,19 @@ Use `commandAliases` quando um plugin é dono de um nome de comando de runtime q
|
||||
}
|
||||
```
|
||||
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ |
|
||||
| `name` | Sim | `string` | Nome do comando que pertence a este plugin. |
|
||||
| `kind` | Não | `"runtime-slash"` | Marca o alias como um comando de barra do chat em vez de um comando raiz da CLI. |
|
||||
| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a ser sugerido para operações de CLI, se existir. |
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- |
|
||||
| `name` | Sim | `string` | Nome do comando que pertence a este plugin. |
|
||||
| `kind` | Não | `"runtime-slash"` | Marca o alias como um comando slash de chat em vez de um comando raiz da CLI. |
|
||||
| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a ser sugerido para operações da CLI, se existir. |
|
||||
|
||||
## Referência de `activation`
|
||||
|
||||
Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle devem ativá-lo depois.
|
||||
Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle
|
||||
devem ativá-lo depois.
|
||||
|
||||
Este bloco contém apenas metadados. Ele não registra comportamento de runtime e não substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/plugin.
|
||||
Esse bloco é apenas metadados. Ele não registra comportamento de runtime e não
|
||||
substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -232,7 +251,8 @@ Este bloco contém apenas metadados. Ele não registra comportamento de runtime
|
||||
|
||||
## Referência de `setup`
|
||||
|
||||
Use `setup` quando superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin antes de o runtime ser carregado.
|
||||
Use `setup` quando superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin
|
||||
antes de o runtime carregar.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -251,35 +271,48 @@ Use `setup` quando superfícies de configuração e onboarding precisarem de met
|
||||
}
|
||||
```
|
||||
|
||||
O `cliBackends` de nível superior continua válido e continua descrevendo backends de inferência da CLI. `setup.cliBackends` é a superfície de descritor específica de configuração para fluxos de configuração/plano de controle que devem permanecer apenas como metadados.
|
||||
O `cliBackends` de nível superior continua válido e segue descrevendo backends
|
||||
de inferência da CLI. `setup.cliBackends` é a superfície de descritor específica de configuração para
|
||||
fluxos do plano de controle/configuração que devem permanecer apenas como metadados.
|
||||
|
||||
Quando presentes, `setup.providers` e `setup.cliBackends` são a superfície preferencial
|
||||
baseada em descritores para busca de configuração. Se o descritor apenas restringir
|
||||
o plugin candidato e a configuração ainda precisar de hooks de runtime mais ricos no momento da configuração,
|
||||
defina `requiresRuntime: true` e mantenha `setup-api` como caminho de execução
|
||||
de fallback.
|
||||
|
||||
Como a busca de configuração pode executar código `setup-api` pertencente ao plugin, os valores normalizados de
|
||||
`setup.providers[].id` e `setup.cliBackends[]` devem permanecer exclusivos entre
|
||||
os plugins descobertos. Propriedade ambígua falha de forma fechada em vez de escolher
|
||||
um vencedor com base na ordem de descoberta.
|
||||
|
||||
### Referência de `setup.providers`
|
||||
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- |
|
||||
| `id` | Sim | `string` | ID do provedor exposto durante a configuração ou onboarding. |
|
||||
| `authMethods` | Não | `string[]` | IDs de métodos de configuração/autenticação que este provedor oferece sem carregar todo o runtime. |
|
||||
| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o runtime do plugin ser carregado. |
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | Sim | `string` | ID do provedor exposto durante a configuração ou onboarding. Mantenha IDs normalizados globalmente exclusivos. |
|
||||
| `authMethods` | Não | `string[]` | IDs de métodos de configuração/autenticação que este provedor oferece sem carregar o runtime completo. |
|
||||
| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o runtime do plugin carregar. |
|
||||
|
||||
### Campos de `setup`
|
||||
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------ |
|
||||
| `providers` | Não | `object[]` | Descritores de configuração de provedor expostos durante a configuração e o onboarding. |
|
||||
| `cliBackends` | Não | `string[]` | IDs de backend disponíveis no momento da configuração sem ativação completa do runtime. |
|
||||
| `configMigrations` | Não | `string[]` | IDs de migração de configuração pertencentes à superfície de configuração deste plugin. |
|
||||
| `requiresRuntime` | Não | `boolean` | Se a configuração ainda precisa da execução do runtime do plugin após a busca do descritor. |
|
||||
| Campo | Obrigatório | Tipo | O que significa |
|
||||
| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Não | `object[]` | Descritores de configuração de provedor expostos durante a configuração e o onboarding. |
|
||||
| `cliBackends` | Não | `string[]` | IDs de backend em tempo de configuração usados para busca de configuração com base em descritor primeiro. Mantenha IDs normalizados globalmente exclusivos. |
|
||||
| `configMigrations` | Não | `string[]` | IDs de migração de configuração pertencentes à superfície de configuração deste plugin. |
|
||||
| `requiresRuntime` | Não | `boolean` | Se a configuração ainda precisa da execução de `setup-api` após a busca por descritor. |
|
||||
|
||||
## Referência de `uiHints`
|
||||
|
||||
`uiHints` é um mapa de nomes de campos de configuração para pequenas dicas de renderização.
|
||||
`uiHints` é um mapa dos nomes de campos de configuração para pequenas dicas de renderização.
|
||||
|
||||
```json
|
||||
{
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "Chave de API",
|
||||
"help": "Usada para solicitações ao OpenRouter",
|
||||
"help": "Usada para solicitações do OpenRouter",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -289,18 +322,19 @@ O `cliBackends` de nível superior continua válido e continua descrevendo backe
|
||||
|
||||
Cada dica de campo pode incluir:
|
||||
|
||||
| Campo | Tipo | O que significa |
|
||||
| ------------- | ---------- | ----------------------------------------- |
|
||||
| `label` | `string` | Rótulo do campo visível ao usuário. |
|
||||
| `help` | `string` | Texto curto de ajuda. |
|
||||
| `tags` | `string[]` | Tags opcionais da UI. |
|
||||
| `advanced` | `boolean` | Marca o campo como avançado. |
|
||||
| `sensitive` | `boolean` | Marca o campo como secreto ou sensível. |
|
||||
| Campo | Tipo | O que significa |
|
||||
| ------------- | ---------- | ---------------------------------------- |
|
||||
| `label` | `string` | Rótulo do campo voltado ao usuário. |
|
||||
| `help` | `string` | Texto curto de ajuda. |
|
||||
| `tags` | `string[]` | Tags opcionais de UI. |
|
||||
| `advanced` | `boolean` | Marca o campo como avançado. |
|
||||
| `sensitive` | `boolean` | Marca o campo como secreto ou sensível. |
|
||||
| `placeholder` | `string` | Texto de placeholder para entradas de formulário. |
|
||||
|
||||
## Referência de `contracts`
|
||||
|
||||
Use `contracts` apenas para metadados estáticos de propriedade de capacidades que o OpenClaw pode ler sem importar o runtime do plugin.
|
||||
Use `contracts` apenas para metadados estáticos de propriedade de capacidades que o OpenClaw pode
|
||||
ler sem importar o runtime do plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -320,21 +354,22 @@ Use `contracts` apenas para metadados estáticos de propriedade de capacidades q
|
||||
|
||||
Cada lista é opcional:
|
||||
|
||||
| Campo | Tipo | O que significa |
|
||||
| -------------------------------- | ---------- | ---------------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | IDs de provedores de fala pertencentes a este plugin. |
|
||||
| Campo | Tipo | O que significa |
|
||||
| -------------------------------- | ---------- | ------------------------------------------------------------ |
|
||||
| `speechProviders` | `string[]` | IDs de provedores de fala pertencentes a este plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | IDs de provedores de transcrição em tempo real pertencentes a este plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | IDs de provedores de voz em tempo real pertencentes a este plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | IDs de provedores de media-understanding pertencentes a este plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | IDs de provedores de compreensão de mídia pertencentes a este plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | IDs de provedores de geração de imagem pertencentes a este plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | IDs de provedores de geração de vídeo pertencentes a este plugin. |
|
||||
| `webFetchProviders` | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin. |
|
||||
| `webSearchProviders` | `string[]` | IDs de provedores de busca na web pertencentes a este plugin. |
|
||||
| `webFetchProviders` | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin. |
|
||||
| `webSearchProviders` | `string[]` | IDs de provedores de pesquisa na web pertencentes a este plugin. |
|
||||
| `tools` | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato empacotadas. |
|
||||
|
||||
## Referência de `channelConfigs`
|
||||
|
||||
Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o runtime ser carregado.
|
||||
Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o
|
||||
runtime carregar.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -354,7 +389,7 @@ Use `channelConfigs` quando um plugin de canal precisar de metadados leves de co
|
||||
}
|
||||
},
|
||||
"label": "Matrix",
|
||||
"description": "Conexão com homeserver Matrix",
|
||||
"description": "Conexão com o homeserver Matrix",
|
||||
"preferOver": ["matrix-legacy"]
|
||||
}
|
||||
}
|
||||
@ -363,17 +398,19 @@ Use `channelConfigs` quando um plugin de canal precisar de metadados leves de co
|
||||
|
||||
Cada entrada de canal pode incluir:
|
||||
|
||||
| Campo | Tipo | O que significa |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
|
||||
| `schema` | `object` | Schema JSON para `channels.<id>`. Obrigatório para cada entrada declarada de configuração de canal. |
|
||||
| `uiHints` | `Record<string, object>` | Rótulos/placeholders/dicas opcionais de sensibilidade da UI para essa seção de configuração de canal. |
|
||||
| `label` | `string` | Rótulo do canal mesclado em superfícies de seleção e inspeção quando os metadados de runtime não estiverem prontos. |
|
||||
| `description` | `string` | Descrição curta do canal para superfícies de inspeção e catálogo. |
|
||||
| `preferOver` | `string[]` | IDs de plugins legados ou de menor prioridade que este canal deve superar em superfícies de seleção. |
|
||||
| Campo | Tipo | O que significa |
|
||||
| ------------- | ------------------------ | -------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | Esquema JSON para `channels.<id>`. Obrigatório para cada entrada declarada de configuração de canal. |
|
||||
| `uiHints` | `Record<string, object>` | Rótulos/placeholders/dicas de sensibilidade de UI opcionais para essa seção de configuração de canal. |
|
||||
| `label` | `string` | Rótulo do canal mesclado em superfícies de seletor e inspeção quando os metadados de runtime ainda não estiverem prontos. |
|
||||
| `description` | `string` | Descrição curta do canal para superfícies de inspeção e catálogo. |
|
||||
| `preferOver` | `string[]` | IDs de plugin legados ou de menor prioridade que este canal deve superar em superfícies de seleção. |
|
||||
|
||||
## Referência de `modelSupport`
|
||||
|
||||
Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a partir de IDs abreviados de modelo como `gpt-5.4` ou `claude-sonnet-4.6` antes de o runtime do plugin ser carregado.
|
||||
Use `modelSupport` quando o OpenClaw precisar inferir seu plugin de provedor a partir de
|
||||
IDs abreviados de modelo, como `gpt-5.4` ou `claude-sonnet-4.6`, antes de o runtime do plugin
|
||||
carregar.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -386,58 +423,74 @@ Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a parti
|
||||
|
||||
O OpenClaw aplica esta precedência:
|
||||
|
||||
- referências explícitas `provider/model` usam os metadados de manifesto de `providers` correspondentes
|
||||
- referências explícitas `provider/model` usam os metadados de manifesto `providers` do plugin proprietário
|
||||
- `modelPatterns` têm precedência sobre `modelPrefixes`
|
||||
- se um plugin não empacotado e um plugin empacotado corresponderem, o plugin não empacotado vence
|
||||
- se um plugin não empacotado e um plugin empacotado corresponderem ao mesmo tempo, o plugin não empacotado
|
||||
vence
|
||||
- a ambiguidade restante é ignorada até que o usuário ou a configuração especifique um provedor
|
||||
|
||||
Campos:
|
||||
|
||||
| Campo | Tipo | O que significa |
|
||||
| --------------- | ---------- | --------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Prefixos comparados com `startsWith` em relação a IDs abreviados de modelo. |
|
||||
| `modelPatterns` | `string[]` | Fontes de regex comparadas com IDs abreviados de modelo após a remoção do sufixo de perfil. |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Prefixos correspondidos com `startsWith` em IDs abreviados de modelo. |
|
||||
| `modelPatterns` | `string[]` | Fontes de regex correspondidas em IDs abreviados de modelo após a remoção do sufixo de perfil. |
|
||||
|
||||
Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal do manifesto não trata mais esses campos de nível superior como propriedade de capacidade.
|
||||
Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para
|
||||
mover `speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`,
|
||||
`webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal
|
||||
do manifesto não trata mais esses campos de nível superior como propriedade
|
||||
de capacidades.
|
||||
|
||||
## Manifesto versus package.json
|
||||
|
||||
Os dois arquivos servem para funções diferentes:
|
||||
Os dois arquivos têm funções diferentes:
|
||||
|
||||
| Arquivo | Use para |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de opção de autenticação e dicas de UI que precisam existir antes de o código do plugin ser executado |
|
||||
| `package.json` | Metadados do npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controle de instalação, configuração ou metadados de catálogo |
|
||||
| Arquivo | Use para |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de escolha de autenticação e dicas de UI que devem existir antes de o código do plugin executar |
|
||||
| `package.json` | Metadados npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controle de instalação, configuração ou metadados de catálogo |
|
||||
|
||||
Se você não tiver certeza de onde um metadado pertence, use esta regra:
|
||||
|
||||
- se o OpenClaw precisa conhecê-lo antes de carregar o código do plugin, coloque-o em `openclaw.plugin.json`
|
||||
- se ele trata de empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json`
|
||||
- se for sobre empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json`
|
||||
|
||||
### Campos de `package.json` que afetam a descoberta
|
||||
|
||||
Alguns metadados de plugin pré-runtime ficam intencionalmente em `package.json`, dentro do bloco `openclaw`, em vez de `openclaw.plugin.json`.
|
||||
Alguns metadados de plugin pré-runtime intencionalmente ficam em `package.json` no bloco
|
||||
`openclaw`, em vez de `openclaw.plugin.json`.
|
||||
|
||||
Exemplos importantes:
|
||||
|
||||
| Campo | O que significa |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Declara entrypoints nativos de plugin. |
|
||||
| `openclaw.setupEntry` | Entrypoint leve apenas para configuração usado durante o onboarding e a inicialização adiada de canal. |
|
||||
| Campo | O que significa |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Declara entrypoints de plugin nativo. |
|
||||
| `openclaw.setupEntry` | Entrypoint leve apenas de configuração usado durante onboarding e inicialização adiada de canal. |
|
||||
| `openclaw.channel` | Metadados leves de catálogo de canal, como rótulos, caminhos de documentação, aliases e texto de seleção. |
|
||||
| `openclaw.channel.configuredState` | Metadados leves do verificador de estado configurado que podem responder "a configuração apenas por env já existe?" sem carregar o runtime completo do canal. |
|
||||
| `openclaw.channel.configuredState` | Metadados leves do verificador de estado configurado que podem responder "já existe configuração somente por env?" sem carregar o runtime completo do canal. |
|
||||
| `openclaw.channel.persistedAuthState` | Metadados leves do verificador de autenticação persistida que podem responder "já existe algo autenticado?" sem carregar o runtime completo do canal. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins empacotados e publicados externamente. |
|
||||
| `openclaw.install.defaultChoice` | Caminho de instalação preferido quando várias fontes de instalação estão disponíveis. |
|
||||
| `openclaw.install.minHostVersion` | Versão mínima compatível do host OpenClaw, usando um piso de semver como `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Permite um caminho restrito de recuperação por reinstalação de plugin empacotado quando a configuração é inválida. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de configuração sejam carregadas antes do plugin completo do canal durante a inicialização. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins empacotados e publicados externamente. |
|
||||
| `openclaw.install.defaultChoice` | Caminho de instalação preferido quando várias fontes de instalação estão disponíveis. |
|
||||
| `openclaw.install.minHostVersion` | Versão mínima suportada do host OpenClaw, usando um piso semver como `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Permite um caminho restrito de recuperação por reinstalação de plugin empacotado quando a configuração é inválida. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de configuração carreguem antes do plugin de canal completo durante a inicialização. |
|
||||
|
||||
`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro de manifestos. Valores inválidos são rejeitados; valores válidos, porém mais novos, fazem o plugin ser ignorado em hosts mais antigos.
|
||||
`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro
|
||||
de manifestos. Valores inválidos são rejeitados; valores válidos, mas mais novos, ignoram o
|
||||
plugin em hosts mais antigos.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna configurações arbitrariamente quebradas instaláveis. Hoje ele permite apenas que fluxos de instalação se recuperem de falhas específicas e antigas de upgrade de plugin empacotado, como um caminho ausente de plugin empacotado ou uma entrada `channels.<id>` antiga para esse mesmo plugin empacotado. Erros de configuração não relacionados continuam bloqueando a instalação e encaminham operadores para `openclaw doctor --fix`.
|
||||
`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna
|
||||
instaláveis configurações arbitrariamente quebradas. Hoje, ele apenas permite que fluxos de instalação
|
||||
se recuperem de falhas específicas e obsoletas de atualização de plugin empacotado, como um
|
||||
caminho ausente do plugin empacotado ou uma entrada `channels.<id>` obsoleta para esse mesmo
|
||||
plugin empacotado. Erros de configuração não relacionados ainda bloqueiam a instalação e enviam os
|
||||
operadores para `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador mínimo:
|
||||
`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador
|
||||
mínimo:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -453,9 +506,13 @@ Exemplos importantes:
|
||||
}
|
||||
```
|
||||
|
||||
Use-o quando fluxos de configuração, Doctor ou estado configurado precisarem de uma verificação barata de autenticação sim/não antes de o plugin completo do canal ser carregado. A exportação de destino deve ser uma função pequena que leia apenas o estado persistido; não a encaminhe pelo barrel completo de runtime do canal.
|
||||
Use isso quando fluxos de configuração, doctor ou estado configurado precisarem de uma sondagem barata
|
||||
de autenticação sim/não antes de o plugin completo do canal carregar. A exportação de destino deve ser uma função
|
||||
pequena que leia apenas o estado persistido; não a encaminhe pelo barrel completo do runtime do
|
||||
canal.
|
||||
|
||||
`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas de estado configurado apenas por env:
|
||||
`openclaw.channel.configuredState` segue o mesmo formato para verificações leves de estado
|
||||
configurado somente por env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -471,42 +528,64 @@ Use-o quando fluxos de configuração, Doctor ou estado configurado precisarem d
|
||||
}
|
||||
```
|
||||
|
||||
Use-o quando um canal puder responder ao estado configurado a partir de env ou outras entradas pequenas fora do runtime. Se a verificação precisar da resolução completa da configuração ou do runtime real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin.
|
||||
Use isso quando um canal puder responder ao estado configurado a partir de env ou de outras entradas
|
||||
mínimas não ligadas ao runtime. Se a verificação precisar da resolução completa da configuração ou do runtime
|
||||
real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin.
|
||||
|
||||
## Requisitos do JSON Schema
|
||||
## Requisitos do esquema JSON
|
||||
|
||||
- **Todo plugin deve fornecer um JSON Schema**, mesmo que não aceite nenhuma configuração.
|
||||
- Um schema vazio é aceitável, por exemplo `{ "type": "object", "additionalProperties": false }`.
|
||||
- Os schemas são validados no momento de leitura/gravação da configuração, não em runtime.
|
||||
- **Todo plugin deve fornecer um esquema JSON**, mesmo que não aceite configuração.
|
||||
- Um esquema vazio é aceitável (por exemplo, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Os esquemas são validados no momento de leitura/gravação da configuração, não em runtime.
|
||||
|
||||
## Comportamento de validação
|
||||
|
||||
- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por um manifesto de plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**.
|
||||
- Se um plugin estiver instalado, mas tiver um manifesto ou schema ausente ou com erro, a validação falha e o Doctor informa o erro do plugin.
|
||||
- Se a configuração do plugin existir, mas o plugin estiver **desabilitado**, a configuração é mantida e um **aviso** é exibido no Doctor + logs.
|
||||
- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por
|
||||
um manifesto de plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` e `plugins.slots.*`
|
||||
devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**.
|
||||
- Se um plugin estiver instalado, mas tiver um manifesto ou esquema ausente ou quebrado,
|
||||
a validação falhará e o Doctor reportará o erro do plugin.
|
||||
- Se existir configuração de plugin, mas o plugin estiver **desabilitado**, a configuração será mantida e
|
||||
um **aviso** será exibido no Doctor + logs.
|
||||
|
||||
Consulte [Referência de configuração](/pt-BR/gateway/configuration) para o schema completo de `plugins.*`.
|
||||
Veja [Referência de configuração](/pt-BR/gateway/configuration) para o esquema completo de `plugins.*`.
|
||||
|
||||
## Observações
|
||||
|
||||
- O manifesto é **obrigatório para plugins nativos do OpenClaw**, incluindo carregamentos locais do sistema de arquivos.
|
||||
- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para descoberta + validação.
|
||||
- Manifestos nativos são analisados com JSON5, então comentários, vírgulas finais e chaves sem aspas são aceitos, desde que o valor final ainda seja um objeto.
|
||||
- Apenas os campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar aqui chaves personalizadas de nível superior.
|
||||
- `providerAuthEnvVars` é o caminho de metadados leve para sondagens de autenticação, validação de marcadores de env e superfícies semelhantes de autenticação de provedor que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env.
|
||||
- `providerAuthAliases` permite que variantes de provedor reutilizem variáveis de ambiente de autenticação, perfis de autenticação, autenticação baseada em configuração e a opção de onboarding por chave de API de outro provedor sem codificar rigidamente esse relacionamento no core.
|
||||
- `channelEnvVars` é o caminho de metadados leve para fallback de env do shell, prompts de configuração e superfícies semelhantes de canal que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env.
|
||||
- `providerAuthChoices` é o caminho de metadados leve para seletores de opção de autenticação, resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags da CLI de onboarding antes de o runtime do provedor ser carregado. Para metadados de assistente de runtime que exigem código do provedor, consulte [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks).
|
||||
- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para
|
||||
descoberta + validação.
|
||||
- Manifestos nativos são analisados com JSON5, então comentários, vírgulas à direita e
|
||||
chaves sem aspas são aceitos, contanto que o valor final continue sendo um objeto.
|
||||
- Apenas campos documentados do manifesto são lidos pelo carregador de manifestos. Evite adicionar
|
||||
chaves personalizadas de nível superior aqui.
|
||||
- `providerAuthEnvVars` é o caminho leve de metadados para sondagens de autenticação, validação de marcadores de env
|
||||
e superfícies semelhantes de autenticação de provedor que não devem iniciar o runtime do plugin
|
||||
apenas para inspecionar nomes de env.
|
||||
- `providerAuthAliases` permite que variantes de provedor reutilizem as variáveis de ambiente de autenticação de outro provedor,
|
||||
perfis de autenticação, autenticação baseada em configuração e escolha de onboarding de chave de API
|
||||
sem codificar esse relacionamento no core.
|
||||
- `channelEnvVars` é o caminho leve de metadados para fallback de env do shell, prompts de configuração
|
||||
e superfícies semelhantes de canal que não devem iniciar o runtime do plugin
|
||||
apenas para inspecionar nomes de env.
|
||||
- `providerAuthChoices` é o caminho leve de metadados para seletores de escolha de autenticação,
|
||||
resolução de `--auth-choice`, mapeamento de provedor preferencial e registro simples
|
||||
de flags de CLI de onboarding antes de o runtime do provedor carregar. Para metadados
|
||||
de assistente de runtime que exigem código do provedor, veja
|
||||
[Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks).
|
||||
- Tipos exclusivos de plugin são selecionados por meio de `plugins.slots.*`.
|
||||
- `kind: "memory"` é selecionado por `plugins.slots.memory`.
|
||||
- `kind: "context-engine"` é selecionado por `plugins.slots.contextEngine` (padrão: `legacy` interno).
|
||||
- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um plugin não precisa deles.
|
||||
- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer requisitos de allowlist do gerenciador de pacotes, por exemplo pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`.
|
||||
- `kind: "context-engine"` é selecionado por `plugins.slots.contextEngine`
|
||||
(padrão: `legacy` embutido).
|
||||
- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um
|
||||
plugin não precisar deles.
|
||||
- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer
|
||||
requisitos de allowlist do gerenciador de pacotes (por exemplo, pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`).
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Criando Plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins
|
||||
- [Arquitetura de plugins](/pt-BR/plugins/architecture) — arquitetura interna
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de plugins
|
||||
- [Criando Plugins](/pt-BR/plugins/building-plugins) — introdução a plugins
|
||||
- [Arquitetura de Plugins](/pt-BR/plugins/architecture) — arquitetura interna
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de Plugins
|
||||
|
||||
@ -4,59 +4,64 @@ read_when:
|
||||
summary: Modelo de workspace para AGENTS.md
|
||||
title: Modelo de AGENTS.md
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:47:24Z"
|
||||
generated_at: "2026-04-12T05:33:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4
|
||||
source_hash: b7a68a1f0b4b837298bfe6edf8ce855d6ef6902ea8e7277b0d9a8442b23daf54
|
||||
source_path: reference/templates/AGENTS.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# AGENTS.md - Seu workspace
|
||||
# AGENTS.md - Seu Workspace
|
||||
|
||||
Esta pasta é a sua casa. Trate-a assim.
|
||||
Esta pasta é sua casa. Trate-a como tal.
|
||||
|
||||
## Primeira execução
|
||||
|
||||
Se `BOOTSTRAP.md` existir, essa é a sua certidão de nascimento. Siga-o, descubra quem você é e depois exclua-o. Você não vai precisar dele novamente.
|
||||
Se `BOOTSTRAP.md` existir, essa é a sua certidão de nascimento. Siga-o, descubra quem você é e então exclua-o. Você não vai precisar dele novamente.
|
||||
|
||||
## Início da sessão
|
||||
## Inicialização da sessão
|
||||
|
||||
Antes de fazer qualquer outra coisa:
|
||||
Use primeiro o contexto de inicialização fornecido pelo runtime.
|
||||
|
||||
1. Leia `SOUL.md` — isso é quem você é
|
||||
2. Leia `USER.md` — isso é quem você está ajudando
|
||||
3. Leia `memory/YYYY-MM-DD.md` (hoje + ontem) para contexto recente
|
||||
4. **Se estiver na SESSÃO PRINCIPAL** (chat direto com seu humano): leia também `MEMORY.md`
|
||||
Esse contexto talvez já inclua:
|
||||
|
||||
Não peça permissão. Apenas faça.
|
||||
- `AGENTS.md`, `SOUL.md` e `USER.md`
|
||||
- memória diária recente, como `memory/YYYY-MM-DD.md`
|
||||
- `MEMORY.md` quando esta for a sessão principal
|
||||
|
||||
Não releia manualmente os arquivos de inicialização, a menos que:
|
||||
|
||||
1. O usuário peça explicitamente
|
||||
2. Falte no contexto fornecido algo de que você precisa
|
||||
3. Você precise fazer uma leitura complementar mais profunda além do contexto de inicialização fornecido
|
||||
|
||||
## Memória
|
||||
|
||||
Você acorda do zero em cada sessão. Estes arquivos são a sua continuidade:
|
||||
Você desperta renovado a cada sessão. Estes arquivos são a sua continuidade:
|
||||
|
||||
- **Notas diárias:** `memory/YYYY-MM-DD.md` (crie `memory/` se necessário) — logs brutos do que aconteceu
|
||||
- **Notas diárias:** `memory/YYYY-MM-DD.md` (crie `memory/` se necessário) — registros brutos do que aconteceu
|
||||
- **Longo prazo:** `MEMORY.md` — suas memórias curadas, como a memória de longo prazo de um humano
|
||||
|
||||
Registre o que importa. Decisões, contexto, coisas para lembrar. Pule os segredos, a menos que peçam para guardá-los.
|
||||
Registre o que importa. Decisões, contexto, coisas para lembrar. Ignore segredos, a menos que peçam para guardá-los.
|
||||
|
||||
### 🧠 MEMORY.md - Sua memória de longo prazo
|
||||
|
||||
- **Carregue APENAS na sessão principal** (chats diretos com seu humano)
|
||||
- **Carregue SOMENTE na sessão principal** (conversas diretas com seu humano)
|
||||
- **NÃO carregue em contextos compartilhados** (Discord, chats em grupo, sessões com outras pessoas)
|
||||
- Isso é por **segurança** — contém contexto pessoal que não deve vazar para estranhos
|
||||
- Isto é por **segurança** — contém contexto pessoal que não deve vazar para estranhos
|
||||
- Você pode **ler, editar e atualizar** `MEMORY.md` livremente em sessões principais
|
||||
- Escreva eventos significativos, pensamentos, decisões, opiniões e lições aprendidas
|
||||
- Esta é a sua memória curada — a essência destilada, não logs brutos
|
||||
- Com o tempo, revise seus arquivos diários e atualize `MEMORY.md` com o que vale a pena guardar
|
||||
- Escreva eventos, pensamentos, decisões, opiniões e lições significativos
|
||||
- Esta é sua memória curada — a essência destilada, não registros brutos
|
||||
- Com o tempo, revise seus arquivos diários e atualize `MEMORY.md` com o que vale a pena manter
|
||||
|
||||
### 📝 Anote - Nada de "notas mentais"!
|
||||
|
||||
- **A memória é limitada** — se você quiser lembrar de algo, ESCREVA EM UM ARQUIVO
|
||||
- "Notas mentais" não sobrevivem ao reinício da sessão. Arquivos sobrevivem.
|
||||
- **A memória é limitada** — se você quiser se lembrar de algo, ESCREVA EM UM ARQUIVO
|
||||
- "Notas mentais" não sobrevivem a reinicializações de sessão. Arquivos sim.
|
||||
- Quando alguém disser "lembre-se disso" → atualize `memory/YYYY-MM-DD.md` ou o arquivo relevante
|
||||
- Quando você aprender uma lição → atualize AGENTS.md, TOOLS.md ou a skill relevante
|
||||
- Quando você cometer um erro → documente para que você do futuro não o repita
|
||||
- Quando aprender uma lição → atualize AGENTS.md, TOOLS.md ou a skill relevante
|
||||
- Quando cometer um erro → documente-o para que seu eu do futuro não o repita
|
||||
- **Texto > Cérebro** 📝
|
||||
|
||||
## Linhas vermelhas
|
||||
@ -68,7 +73,7 @@ Registre o que importa. Decisões, contexto, coisas para lembrar. Pule os segred
|
||||
|
||||
## Externo vs interno
|
||||
|
||||
**Seguro fazer livremente:**
|
||||
**Seguro para fazer livremente:**
|
||||
|
||||
- Ler arquivos, explorar, organizar, aprender
|
||||
- Pesquisar na web, verificar calendários
|
||||
@ -76,13 +81,13 @@ Registre o que importa. Decisões, contexto, coisas para lembrar. Pule os segred
|
||||
|
||||
**Pergunte antes:**
|
||||
|
||||
- Enviar e-mails, tweets, posts públicos
|
||||
- Enviar emails, tweets, posts públicos
|
||||
- Qualquer coisa que saia da máquina
|
||||
- Qualquer coisa sobre a qual você não tenha certeza
|
||||
- Qualquer coisa sobre a qual você esteja em dúvida
|
||||
|
||||
## Chats em grupo
|
||||
|
||||
Você tem acesso às coisas do seu humano. Isso não significa que você _compartilha_ as coisas dele. Em grupos, você é um participante — não a voz dele, nem o representante dele. Pense antes de falar.
|
||||
Você tem acesso às coisas do seu humano. Isso não significa que você _compartilha_ as coisas dele. Em grupos, você é um participante — não a voz dele, não o representante dele. Pense antes de falar.
|
||||
|
||||
### 💬 Saiba quando falar!
|
||||
|
||||
@ -91,87 +96,87 @@ Em chats em grupo nos quais você recebe todas as mensagens, seja **inteligente
|
||||
**Responda quando:**
|
||||
|
||||
- Você for mencionado diretamente ou receber uma pergunta
|
||||
- Você puder agregar valor genuíno (informação, insight, ajuda)
|
||||
- Você puder agregar valor real (informação, insight, ajuda)
|
||||
- Algo espirituoso/divertido se encaixar naturalmente
|
||||
- For preciso corrigir uma desinformação importante
|
||||
- For preciso corrigir desinformação importante
|
||||
- Pedirem um resumo
|
||||
|
||||
**Fique em silêncio (`HEARTBEAT_OK`) quando:**
|
||||
|
||||
- For apenas conversa casual entre humanos
|
||||
- For só conversa casual entre humanos
|
||||
- Alguém já tiver respondido à pergunta
|
||||
- Sua resposta seria só "sim" ou "boa"
|
||||
- Sua resposta seria apenas "sim" ou "boa"
|
||||
- A conversa estiver fluindo bem sem você
|
||||
- Adicionar uma mensagem interromperia o clima
|
||||
|
||||
**A regra humana:** Humanos em chats em grupo não respondem a cada mensagem. Você também não deve. Qualidade > quantidade. Se você não enviaria isso em um chat real com amigos, não envie.
|
||||
**A regra humana:** Humanos em chats em grupo não respondem a cada mensagem. Você também não deve responder. Qualidade > quantidade. Se você não enviaria isso em um chat em grupo real com amigos, não envie.
|
||||
|
||||
**Evite o triplo toque:** Não responda várias vezes à mesma mensagem com reações diferentes. Uma resposta pensada vale mais do que três fragmentos.
|
||||
**Evite o triplo toque:** Não responda várias vezes à mesma mensagem com reações diferentes. Uma resposta cuidadosa é melhor do que três fragmentos.
|
||||
|
||||
Participe, não domine.
|
||||
|
||||
### 😊 Reaja como um humano!
|
||||
|
||||
Em plataformas com suporte a reações (Discord, Slack), use reações com emoji de forma natural:
|
||||
Em plataformas que suportam reações (Discord, Slack), use reações com emoji de forma natural:
|
||||
|
||||
**Reaja quando:**
|
||||
|
||||
- Você aprecia algo, mas não precisa responder (👍, ❤️, 🙌)
|
||||
- Algo fez você rir (😂, 💀)
|
||||
- Você achou interessante ou instigante (🤔, 💡)
|
||||
- Você quer reconhecer algo sem interromper o fluxo
|
||||
- É uma situação simples de sim/não ou aprovação (✅, 👀)
|
||||
- Você quer reconhecer sem interromper o fluxo
|
||||
- For uma situação simples de sim/não ou aprovação (✅, 👀)
|
||||
|
||||
**Por que isso importa:**
|
||||
Reações são sinais sociais leves. Humanos as usam o tempo todo — elas dizem "eu vi isso, reconheço você" sem poluir o chat. Você também deveria.
|
||||
Reações são sinais sociais leves. Humanos as usam o tempo todo — elas dizem "eu vi isso, eu reconheço você" sem poluir o chat. Você também deve fazer isso.
|
||||
|
||||
**Não exagere:** no máximo uma reação por mensagem. Escolha a que melhor se encaixar.
|
||||
**Não exagere:** No máximo uma reação por mensagem. Escolha a que melhor se encaixar.
|
||||
|
||||
## Ferramentas
|
||||
|
||||
As Skills fornecem suas ferramentas. Quando precisar de uma, verifique o `SKILL.md` dela. Mantenha notas locais (nomes de câmera, detalhes de SSH, preferências de voz) em `TOOLS.md`.
|
||||
As Skills fornecem suas ferramentas. Quando precisar de uma, consulte o `SKILL.md` dela. Mantenha notas locais (nomes de câmera, detalhes de SSH, preferências de voz) em `TOOLS.md`.
|
||||
|
||||
**🎭 Narração por voz:** Se você tiver `sag` (TTS da ElevenLabs), use voz para histórias, resumos de filmes e momentos de "hora da história"! É muito mais envolvente do que paredes de texto. Surpreenda as pessoas com vozes engraçadas.
|
||||
**🎭 Narração por voz:** Se você tiver `sag` (ElevenLabs TTS), use voz para histórias, resumos de filmes e momentos de "hora da história"! Muito mais envolvente do que muralhas de texto. Surpreenda as pessoas com vozes engraçadas.
|
||||
|
||||
**📝 Formatação por plataforma:**
|
||||
|
||||
- **Discord/WhatsApp:** Sem tabelas em markdown! Use listas com marcadores
|
||||
- **Links no Discord:** Envolva vários links em `<>` para suprimir embeds: `<https://example.com>`
|
||||
- **WhatsApp:** Sem cabeçalhos — use **negrito** ou MAIÚSCULAS para dar ênfase
|
||||
- **Discord/WhatsApp:** Nada de tabelas em markdown! Use listas com marcadores
|
||||
- **Links no Discord:** Coloque vários links entre `<>` para suprimir embeds: `<https://example.com>`
|
||||
- **WhatsApp:** Sem cabeçalhos — use **negrito** ou CAIXA ALTA para dar ênfase
|
||||
|
||||
## 💓 Heartbeats - Seja proativo!
|
||||
|
||||
Quando você receber um heartbeat poll (mensagem correspondente ao prompt de heartbeat configurado), não responda apenas `HEARTBEAT_OK` toda vez. Use os heartbeats de forma produtiva!
|
||||
Quando você receber uma sondagem de heartbeat (mensagem que corresponde ao prompt de heartbeat configurado), não responda apenas `HEARTBEAT_OK` toda vez. Use heartbeats de forma produtiva!
|
||||
|
||||
Você pode editar livremente `HEARTBEAT.md` com uma lista curta de verificação ou lembretes. Mantenha pequeno para limitar o gasto de tokens.
|
||||
Você pode editar livremente `HEARTBEAT.md` com uma pequena checklist ou lembretes. Mantenha-o pequeno para limitar o consumo de tokens.
|
||||
|
||||
### Heartbeat vs Cron: quando usar cada um
|
||||
|
||||
**Use heartbeat quando:**
|
||||
|
||||
- Várias verificações puderem ser agrupadas (caixa de entrada + calendário + notificações em um só turno)
|
||||
- Várias verificações puderem ser agrupadas (caixa de entrada + calendário + notificações em um turno)
|
||||
- Você precisar de contexto conversacional de mensagens recentes
|
||||
- O timing puder variar um pouco (a cada ~30 min está bom, não precisa ser exato)
|
||||
- O horário puder variar um pouco (a cada ~30 min está bom, não precisa ser exato)
|
||||
- Você quiser reduzir chamadas de API combinando verificações periódicas
|
||||
|
||||
**Use cron quando:**
|
||||
|
||||
- O horário exato importar ("9:00 em ponto toda segunda-feira")
|
||||
- O horário exato importar ("às 9:00 em ponto toda segunda-feira")
|
||||
- A tarefa precisar de isolamento do histórico da sessão principal
|
||||
- Você quiser um modelo diferente ou outro nível de raciocínio para a tarefa
|
||||
- Quiser lembretes pontuais ("me lembre em 20 minutos")
|
||||
- A saída precisar ser entregue diretamente a um canal sem envolver a sessão principal
|
||||
- Forem lembretes pontuais ("me lembre em 20 minutos")
|
||||
- A saída deva ser entregue diretamente a um canal sem envolver a sessão principal
|
||||
|
||||
**Dica:** Agrupe verificações periódicas semelhantes em `HEARTBEAT.md` em vez de criar vários jobs cron. Use cron para agendas precisas e tarefas independentes.
|
||||
|
||||
**Coisas para verificar (rode entre elas, de 2 a 4 vezes por dia):**
|
||||
**Coisas para verificar (altere entre elas, 2 a 4 vezes por dia):**
|
||||
|
||||
- **E-mails** - Há mensagens urgentes não lidas?
|
||||
- **Emails** - Há mensagens não lidas urgentes?
|
||||
- **Calendário** - Há eventos próximos nas próximas 24-48h?
|
||||
- **Menções** - Notificações de Twitter/redes sociais?
|
||||
- **Clima** - Relevante se seu humano puder sair?
|
||||
- **Menções** - Notificações no Twitter/redes sociais?
|
||||
- **Clima** - É relevante caso seu humano vá sair?
|
||||
|
||||
**Acompanhe suas verificações** em `memory/heartbeat-state.json`:
|
||||
**Registre suas verificações** em `memory/heartbeat-state.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -185,12 +190,12 @@ Você pode editar livremente `HEARTBEAT.md` com uma lista curta de verificação
|
||||
|
||||
**Quando entrar em contato:**
|
||||
|
||||
- Chegou um e-mail importante
|
||||
- Chegou um email importante
|
||||
- Um evento do calendário está próximo (<2h)
|
||||
- Você encontrou algo interessante
|
||||
- Faz >8h desde a última vez que você falou algo
|
||||
- Faz >8h desde a última vez que você disse algo
|
||||
|
||||
**Quando ficar quieto (`HEARTBEAT_OK`):**
|
||||
**Quando ficar em silêncio (`HEARTBEAT_OK`):**
|
||||
|
||||
- Tarde da noite (23:00-08:00), a menos que seja urgente
|
||||
- O humano esteja claramente ocupado
|
||||
@ -203,21 +208,21 @@ Você pode editar livremente `HEARTBEAT.md` com uma lista curta de verificação
|
||||
- Verificar projetos (git status etc.)
|
||||
- Atualizar documentação
|
||||
- Fazer commit e push das suas próprias alterações
|
||||
- **Revisar e atualizar MEMORY.md** (veja abaixo)
|
||||
- **Revisar e atualizar `MEMORY.md`** (veja abaixo)
|
||||
|
||||
### 🔄 Manutenção de memória (durante heartbeats)
|
||||
### 🔄 Manutenção da memória (durante heartbeats)
|
||||
|
||||
Periodicamente (a cada poucos dias), use um heartbeat para:
|
||||
|
||||
1. Ler os arquivos recentes `memory/YYYY-MM-DD.md`
|
||||
2. Identificar eventos significativos, lições ou insights que valham a pena manter no longo prazo
|
||||
1. Ler arquivos recentes `memory/YYYY-MM-DD.md`
|
||||
2. Identificar eventos, lições ou insights significativos que valham a pena manter no longo prazo
|
||||
3. Atualizar `MEMORY.md` com aprendizados destilados
|
||||
4. Remover informações desatualizadas de `MEMORY.md` que não sejam mais relevantes
|
||||
4. Remover de `MEMORY.md` informações desatualizadas que não sejam mais relevantes
|
||||
|
||||
Pense nisso como um humano revendo seu diário e atualizando seu modelo mental. Os arquivos diários são notas brutas; `MEMORY.md` é sabedoria curada.
|
||||
Pense nisso como um humano revisando seu diário e atualizando seu modelo mental. Os arquivos diários são notas brutas; `MEMORY.md` é sabedoria curada.
|
||||
|
||||
O objetivo: ser útil sem ser incômodo. Verifique algumas vezes por dia, faça trabalho útil em segundo plano, mas respeite os momentos de silêncio.
|
||||
|
||||
## Faça do seu jeito
|
||||
## Deixe com a sua cara
|
||||
|
||||
Este é um ponto de partida. Adicione suas próprias convenções, estilo e regras à medida que descobrir o que funciona.
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
read_when:
|
||||
- Explicando uso de tokens, custos ou janelas de contexto
|
||||
- Depurando crescimento de contexto ou comportamento de compactação
|
||||
summary: Como o OpenClaw monta o contexto do prompt e relata uso de tokens + custos
|
||||
- Explicando o uso de tokens, custos ou janelas de contexto
|
||||
- Depurando o crescimento do contexto ou o comportamento de compactação
|
||||
summary: Como o OpenClaw monta o contexto do prompt e informa o uso de tokens + custos
|
||||
title: Uso de tokens e custos
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T05:31:38Z"
|
||||
generated_at: "2026-04-12T05:33:21Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9
|
||||
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
|
||||
source_path: reference/token-use.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Uso de tokens e custos
|
||||
|
||||
O OpenClaw rastreia **tokens**, não caracteres. Os tokens são específicos de cada modelo, mas a maioria
|
||||
dos modelos no estilo OpenAI tem média de ~4 caracteres por token em texto em inglês.
|
||||
O OpenClaw rastreia **tokens**, não caracteres. Os tokens são específicos de cada modelo, mas a maioria dos
|
||||
modelos no estilo OpenAI tem uma média de ~4 caracteres por token em texto em inglês.
|
||||
|
||||
## Como o prompt do sistema é montado
|
||||
|
||||
@ -25,105 +25,105 @@ O OpenClaw monta seu próprio prompt do sistema em cada execução. Ele inclui:
|
||||
- Lista de ferramentas + descrições curtas
|
||||
- Lista de Skills (somente metadados; as instruções são carregadas sob demanda com `read`)
|
||||
- Instruções de autoatualização
|
||||
- Workspace + arquivos de bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novos, além de `MEMORY.md` quando presente ou `memory.md` como fallback em minúsculas). Arquivos grandes são truncados por `agents.defaults.bootstrapMaxChars` (padrão: 20000), e a injeção total de bootstrap é limitada por `agents.defaults.bootstrapTotalMaxChars` (padrão: 150000). Arquivos `memory/*.md` são sob demanda via ferramentas de memória e não são injetados automaticamente.
|
||||
- Arquivos de workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novo, além de `MEMORY.md` quando presente ou `memory.md` como fallback em minúsculas). Arquivos grandes são truncados por `agents.defaults.bootstrapMaxChars` (padrão: 20000), e a injeção total de bootstrap é limitada por `agents.defaults.bootstrapTotalMaxChars` (padrão: 150000). Arquivos diários `memory/*.md` não fazem parte do prompt bootstrap normal; eles permanecem sob demanda por meio de ferramentas de memória em turnos comuns, mas `/new` e `/reset` sem nenhum argumento podem prefixar um bloco único de contexto de inicialização com memória diária recente para esse primeiro turno. Esse prelúdio de inicialização é controlado por `agents.defaults.startupContext`.
|
||||
- Hora (UTC + fuso horário do usuário)
|
||||
- Tags de resposta + comportamento de heartbeat
|
||||
- Metadados de runtime (host/OS/model/thinking)
|
||||
|
||||
Consulte a decomposição completa em [Prompt do sistema](/pt-BR/concepts/system-prompt).
|
||||
Veja o detalhamento completo em [Prompt do sistema](/pt-BR/concepts/system-prompt).
|
||||
|
||||
## O que conta na janela de contexto
|
||||
|
||||
Tudo o que o modelo recebe conta para o limite de contexto:
|
||||
|
||||
- Prompt do sistema (todas as seções listadas acima)
|
||||
- Histórico da conversa (mensagens do usuário + do assistente)
|
||||
- Chamadas de ferramenta e resultados de ferramenta
|
||||
- Histórico da conversa (mensagens do usuário + assistente)
|
||||
- Chamadas de ferramentas e resultados de ferramentas
|
||||
- Anexos/transcrições (imagens, áudio, arquivos)
|
||||
- Resumos de compactação e artefatos de poda
|
||||
- Wrappers do provedor ou cabeçalhos de segurança (não visíveis, mas ainda contam)
|
||||
- Wrappers do provedor ou cabeçalhos de segurança (não visíveis, mas ainda contabilizados)
|
||||
|
||||
Para imagens, o OpenClaw reduz o tamanho de payloads de imagem de transcript/ferramenta antes das chamadas ao provedor.
|
||||
Para imagens, o OpenClaw reduz a escala das cargas de imagens de transcrição/ferramentas antes das chamadas ao provedor.
|
||||
Use `agents.defaults.imageMaxDimensionPx` (padrão: `1200`) para ajustar isso:
|
||||
|
||||
- Valores menores normalmente reduzem o uso de vision-tokens e o tamanho do payload.
|
||||
- Valores maiores preservam mais detalhes visuais para OCR/capturas de tela pesadas em UI.
|
||||
- Valores menores geralmente reduzem o uso de vision tokens e o tamanho da carga.
|
||||
- Valores maiores preservam mais detalhes visuais para OCR/capturas de tela com muita interface.
|
||||
|
||||
Para uma decomposição prática (por arquivo injetado, ferramentas, Skills e tamanho do prompt do sistema), use `/context list` ou `/context detail`. Consulte [Contexto](/pt-BR/concepts/context).
|
||||
Para uma análise prática (por arquivo injetado, ferramentas, Skills e tamanho do prompt do sistema), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context).
|
||||
|
||||
## Como ver o uso atual de tokens
|
||||
|
||||
Use estes comandos no chat:
|
||||
|
||||
- `/status` → **cartão de status rico em emoji** com o modelo da sessão, uso de contexto,
|
||||
- `/status` → **cartão de status rico em emojis** com o modelo da sessão, uso de contexto,
|
||||
tokens de entrada/saída da última resposta e **custo estimado** (somente chave de API).
|
||||
- `/usage off|tokens|full` → acrescenta um **rodapé de uso por resposta** a cada resposta.
|
||||
- `/usage off|tokens|full` → adiciona um **rodapé de uso por resposta** a cada resposta.
|
||||
- Persiste por sessão (armazenado como `responseUsage`).
|
||||
- Auth OAuth **oculta custo** (somente tokens).
|
||||
- Autenticação OAuth **oculta o custo** (somente tokens).
|
||||
- `/usage cost` → mostra um resumo local de custos a partir dos logs de sessão do OpenClaw.
|
||||
|
||||
Outras superfícies:
|
||||
|
||||
- **TUI/Web TUI:** `/status` + `/usage` são compatíveis.
|
||||
- **CLI:** `openclaw status --usage` e `openclaw channels list` mostram
|
||||
janelas de cota normalizadas do provedor (`X% left`, não custos por resposta).
|
||||
Provedores atuais de janela de uso: Anthropic, GitHub Copilot, Gemini CLI,
|
||||
janelas de cota normalizadas do provedor (`X% restantes`, não custos por resposta).
|
||||
Provedores atuais com janela de uso: Anthropic, GitHub Copilot, Gemini CLI,
|
||||
OpenAI Codex, MiniMax, Xiaomi e z.ai.
|
||||
|
||||
As superfícies de uso normalizam aliases comuns de campos nativos do provedor antes da exibição.
|
||||
Para tráfego Responses da família OpenAI, isso inclui tanto `input_tokens` /
|
||||
`output_tokens` quanto `prompt_tokens` / `completion_tokens`, para que nomes de campo
|
||||
específicos de transporte não alterem `/status`, `/usage` ou resumos de sessão.
|
||||
O uso JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e
|
||||
Para tráfego OpenAI-family Responses, isso inclui tanto `input_tokens` /
|
||||
`output_tokens` quanto `prompt_tokens` / `completion_tokens`, para que nomes de campos
|
||||
específicos do transporte não alterem `/status`, `/usage` ou resumos de sessão.
|
||||
O uso de JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e
|
||||
`stats.cached` é mapeado para `cacheRead`, com `stats.input_tokens - stats.cached`
|
||||
usado quando a CLI omite um campo explícito `stats.input`.
|
||||
Para tráfego Responses nativo da família OpenAI, aliases de uso WebSocket/SSE são
|
||||
Para tráfego nativo OpenAI-family Responses, aliases de uso em WebSocket/SSE são
|
||||
normalizados da mesma forma, e os totais usam como fallback entrada + saída normalizadas quando
|
||||
`total_tokens` está ausente ou é `0`.
|
||||
Quando o snapshot da sessão atual é escasso, `/status` e `session_status` também podem
|
||||
recuperar contadores de token/cache e o rótulo do modelo de runtime ativo do
|
||||
log de uso mais recente do transcript. Valores live existentes e diferentes de zero ainda têm
|
||||
precedência sobre valores de fallback do transcript, e totais maiores orientados por prompt
|
||||
do transcript podem prevalecer quando os totais armazenados estiverem ausentes ou menores.
|
||||
A auth de uso para janelas de cota do provedor vem de hooks específicos do provedor quando
|
||||
disponíveis; caso contrário, o OpenClaw usa como fallback credenciais OAuth/chave de API correspondentes
|
||||
de perfis auth, env ou config.
|
||||
Quando o snapshot da sessão atual é esparso, `/status` e `session_status` também podem
|
||||
recuperar contadores de tokens/cache e o rótulo do modelo de runtime ativo do log de uso
|
||||
da transcrição mais recente. Valores ativos não zero existentes ainda têm precedência sobre
|
||||
valores de fallback da transcrição, e totais maiores da transcrição orientados a prompt
|
||||
podem prevalecer quando os totais armazenados estão ausentes ou são menores.
|
||||
A autenticação de uso para janelas de cota do provedor vem de hooks específicos do provedor quando
|
||||
disponíveis; caso contrário, o OpenClaw usa como fallback a correspondência de credenciais OAuth/chave de API
|
||||
de perfis de autenticação, env ou config.
|
||||
|
||||
## Estimativa de custo (quando mostrada)
|
||||
## Estimativa de custo (quando exibida)
|
||||
|
||||
Os custos são estimados a partir da sua configuração de preços do modelo:
|
||||
Os custos são estimados a partir da configuração de preços do seu modelo:
|
||||
|
||||
```
|
||||
models.providers.<provider>.models[].cost
|
||||
```
|
||||
|
||||
Esses valores são em **USD por 1M tokens** para `input`, `output`, `cacheRead` e
|
||||
`cacheWrite`. Se não houver preços, o OpenClaw mostra apenas tokens. Tokens OAuth
|
||||
Esses valores são **USD por 1M de tokens** para `input`, `output`, `cacheRead` e
|
||||
`cacheWrite`. Se o preço estiver ausente, o OpenClaw mostrará apenas os tokens. Tokens OAuth
|
||||
nunca mostram custo em dólar.
|
||||
|
||||
## Impacto do TTL de cache e da poda
|
||||
## Impacto de TTL de cache e poda
|
||||
|
||||
O cache de prompt do provedor só se aplica dentro da janela de TTL do cache. O OpenClaw pode
|
||||
executar opcionalmente **poda de cache-ttl**: ele poda a sessão quando o TTL do cache
|
||||
expira e depois redefine a janela de cache para que solicitações subsequentes possam reutilizar o
|
||||
contexto recém-colocado em cache, em vez de recachear todo o histórico. Isso mantém os custos
|
||||
de gravação de cache mais baixos quando uma sessão fica ociosa além do TTL.
|
||||
executar opcionalmente a **poda por cache-ttl**: ele poda a sessão assim que o TTL do cache
|
||||
expira e, em seguida, redefine a janela de cache para que solicitações subsequentes possam reutilizar o
|
||||
contexto recém-cacheado em vez de colocar todo o histórico em cache novamente. Isso mantém os custos
|
||||
de escrita em cache mais baixos quando uma sessão fica ociosa além do TTL.
|
||||
|
||||
Configure isso em [Configuração do gateway](/pt-BR/gateway/configuration) e veja os
|
||||
Configure isso em [Configuração do Gateway](/pt-BR/gateway/configuration) e veja os
|
||||
detalhes do comportamento em [Poda de sessão](/pt-BR/concepts/session-pruning).
|
||||
|
||||
O heartbeat pode manter o cache **aquecido** durante intervalos de inatividade. Se o TTL do cache do seu modelo
|
||||
for `1h`, definir o intervalo de heartbeat um pouco abaixo disso (por exemplo, `55m`) pode evitar
|
||||
recachear o prompt completo, reduzindo custos de gravação de cache.
|
||||
Heartbeat pode manter o cache **aquecido** durante intervalos de inatividade. Se o TTL do cache
|
||||
do seu modelo for `1h`, definir o intervalo de heartbeat logo abaixo disso (por exemplo, `55m`) pode evitar
|
||||
recolocar todo o prompt em cache, reduzindo os custos de escrita em cache.
|
||||
|
||||
Em configurações com vários agentes, você pode manter uma configuração de modelo compartilhada e ajustar o comportamento do cache
|
||||
por agente com `agents.list[].params.cacheRetention`.
|
||||
Em configurações multiagente, você pode manter uma configuração de modelo compartilhada e ajustar o comportamento
|
||||
de cache por agente com `agents.list[].params.cacheRetention`.
|
||||
|
||||
Para um guia completo, opção por opção, consulte [Prompt Caching](/pt-BR/reference/prompt-caching).
|
||||
Para um guia completo de cada ajuste, veja [Prompt Caching](/pt-BR/reference/prompt-caching).
|
||||
|
||||
Para preços da API Anthropic, leituras de cache são significativamente mais baratas do que
|
||||
tokens de entrada, enquanto gravações de cache são cobradas com um multiplicador mais alto. Consulte os
|
||||
preços de prompt caching da Anthropic para as taxas e multiplicadores de TTL mais recentes:
|
||||
tokens de entrada, enquanto gravações em cache são cobradas com um multiplicador maior. Veja os preços
|
||||
de prompt caching da Anthropic para as taxas e multiplicadores de TTL mais recentes:
|
||||
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
|
||||
|
||||
### Exemplo: manter cache de 1h aquecido com heartbeat
|
||||
@ -159,16 +159,16 @@ agents:
|
||||
every: "55m" # mantém o cache longo aquecido para sessões profundas
|
||||
- id: "alerts"
|
||||
params:
|
||||
cacheRetention: "none" # evita gravações de cache para notificações em rajada
|
||||
cacheRetention: "none" # evita gravações em cache para notificações intermitentes
|
||||
```
|
||||
|
||||
`agents.list[].params` é mesclado sobre os `params` do modelo selecionado, então você pode
|
||||
`agents.list[].params` é mesclado sobre `params` do modelo selecionado, então você pode
|
||||
substituir apenas `cacheRetention` e herdar os outros padrões do modelo sem alterações.
|
||||
|
||||
### Exemplo: ativar o cabeçalho beta de contexto 1M da Anthropic
|
||||
### Exemplo: habilitar o cabeçalho beta de contexto 1M da Anthropic
|
||||
|
||||
A janela de contexto de 1M da Anthropic atualmente é controlada por beta. O OpenClaw pode injetar o
|
||||
valor `anthropic-beta` necessário quando você ativa `context1m` em modelos Opus
|
||||
valor `anthropic-beta` necessário quando você habilita `context1m` em modelos Opus
|
||||
ou Sonnet compatíveis.
|
||||
|
||||
```yaml
|
||||
@ -185,7 +185,7 @@ Isso é mapeado para o cabeçalho beta `context-1m-2025-08-07` da Anthropic.
|
||||
Isso só se aplica quando `context1m: true` está definido nessa entrada de modelo.
|
||||
|
||||
Requisito: a credencial deve ser elegível para uso de contexto longo. Caso contrário,
|
||||
a Anthropic responde com um erro de limite de taxa no lado do provedor para essa solicitação.
|
||||
a Anthropic responde com um erro de limite de taxa do lado do provedor para essa solicitação.
|
||||
|
||||
Se você autenticar a Anthropic com tokens OAuth/assinatura (`sk-ant-oat-*`),
|
||||
o OpenClaw ignora o cabeçalho beta `context-1m-*` porque a Anthropic atualmente
|
||||
@ -194,9 +194,9 @@ rejeita essa combinação com HTTP 401.
|
||||
## Dicas para reduzir a pressão de tokens
|
||||
|
||||
- Use `/compact` para resumir sessões longas.
|
||||
- Reduza saídas grandes de ferramentas em seus fluxos de trabalho.
|
||||
- Diminua `agents.defaults.imageMaxDimensionPx` em sessões com muitas capturas de tela.
|
||||
- Corte saídas grandes de ferramentas nos seus fluxos de trabalho.
|
||||
- Reduza `agents.defaults.imageMaxDimensionPx` para sessões com muitas capturas de tela.
|
||||
- Mantenha descrições de Skills curtas (a lista de Skills é injetada no prompt).
|
||||
- Prefira modelos menores para trabalho verboso e exploratório.
|
||||
- Prefira modelos menores para trabalho exploratório e verboso.
|
||||
|
||||
Consulte [Skills](/pt-BR/tools/skills) para a fórmula exata de sobrecarga da lista de Skills.
|
||||
Veja [Skills](/pt-BR/tools/skills) para a fórmula exata de overhead da lista de Skills.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user