From 7e561b75681f3311c70fbfee15f70af0bfe862e3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 18 Apr 2026 05:33:04 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/concepts/agent-workspace.md | 165 +- docs/pt-BR/concepts/context.md | 146 +- docs/pt-BR/concepts/qa-e2e-automation.md | 198 +-- docs/pt-BR/concepts/system-prompt.md | 144 +- docs/pt-BR/gateway/configuration-reference.md | 1412 ++++++++--------- docs/pt-BR/gateway/protocol.md | 506 +++--- docs/pt-BR/help/testing.md | 716 ++++----- docs/pt-BR/platforms/macos.md | 134 +- docs/pt-BR/plugins/sdk-channel-plugins.md | 273 ++-- docs/pt-BR/plugins/sdk-overview.md | 576 +++---- docs/pt-BR/refactor/qa.md | 230 +-- 11 files changed, 2212 insertions(+), 2288 deletions(-) diff --git a/docs/pt-BR/concepts/agent-workspace.md b/docs/pt-BR/concepts/agent-workspace.md index 950618cc6..799002b49 100644 --- a/docs/pt-BR/concepts/agent-workspace.md +++ b/docs/pt-BR/concepts/agent-workspace.md @@ -1,34 +1,34 @@ --- read_when: - - Você precisa explicar o workspace do agente ou seu layout de arquivos - - Você quer fazer backup ou migrar um workspace de agente -summary: 'Workspace do agente: localização, layout e estratégia de backup' -title: Workspace do agente + - Você precisa explicar o espaço de trabalho do agente ou seu layout de arquivos + - Você quer fazer backup ou migrar um espaço de trabalho do agente +summary: 'Espaço de trabalho do agente: local, layout e estratégia de backup' +title: Espaço de trabalho do agente x-i18n: - generated_at: "2026-04-05T12:39:17Z" + generated_at: "2026-04-18T05:24:44Z" model: gpt-5.4 provider: openai - source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a + source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e source_path: concepts/agent-workspace.md workflow: 15 --- -# Workspace do agente +# Espaço de trabalho do agente -O workspace é a casa do agente. É o único diretório de trabalho usado para -ferramentas de arquivo e para o contexto do workspace. Mantenha-o privado e trate-o como memória. +O espaço de trabalho é a casa do agente. É o único diretório de trabalho usado para +ferramentas de arquivo e para o contexto do espaço de trabalho. Mantenha-o privado e trate-o como memória. Isso é separado de `~/.openclaw/`, que armazena configuração, credenciais e sessões. -**Importante:** o workspace é o **cwd padrão**, não um sandbox rígido. As ferramentas -resolvem caminhos relativos em relação ao workspace, mas caminhos absolutos ainda podem alcançar -outros locais no host, a menos que o sandboxing esteja habilitado. Se você precisar de isolamento, use -[`agents.defaults.sandbox`](/gateway/sandboxing) (e/ou configuração de sandbox por agente). -Quando o sandboxing está habilitado e `workspaceAccess` não é `"rw"`, as ferramentas operam -dentro de um workspace em sandbox em `~/.openclaw/sandboxes`, e não no workspace do seu host. +**Importante:** o espaço de trabalho é o **cwd padrão**, não um sandbox rígido. As ferramentas +resolvem caminhos relativos em relação ao espaço de trabalho, mas caminhos absolutos ainda podem alcançar +outras partes do host, a menos que o sandboxing esteja ativado. Se você precisar de isolamento, use +[`agents.defaults.sandbox`](/pt-BR/gateway/sandboxing) (e/ou a configuração de sandbox por agente). +Quando o sandboxing está ativado e `workspaceAccess` não é `"rw"`, as ferramentas operam +dentro de um espaço de trabalho em sandbox em `~/.openclaw/sandboxes`, e não no seu espaço de trabalho do host. -## Localização padrão +## Local padrão - Padrão: `~/.openclaw/workspace` - Se `OPENCLAW_PROFILE` estiver definido e não for `"default"`, o padrão passa a ser @@ -44,43 +44,42 @@ dentro de um workspace em sandbox em `~/.openclaw/sandboxes`, e não no workspac ``` `openclaw onboard`, `openclaw configure` ou `openclaw setup` criarão o -workspace e semearão os arquivos de bootstrap se estiverem ausentes. -Cópias de semente de sandbox aceitam apenas arquivos regulares dentro do workspace; aliases de symlink/hardlink -que resolvem fora do workspace de origem são ignorados. +espaço de trabalho e preencherão os arquivos de bootstrap se eles estiverem ausentes. +Cópias de seed de sandbox aceitam apenas arquivos regulares dentro do espaço de trabalho; aliases de symlink/hardlink +que resolvem para fora do espaço de trabalho de origem são ignorados. -Se você já gerencia os arquivos do workspace por conta própria, pode desabilitar -a criação de arquivos de bootstrap: +Se você já gerencia os arquivos do espaço de trabalho por conta própria, pode desativar a criação de arquivos de bootstrap: ```json5 { agent: { skipBootstrap: true } } ``` -## Pastas extras de workspace +## Pastas extras de espaço de trabalho -Instalações mais antigas podem ter criado `~/openclaw`. Manter vários diretórios de workspace -pode causar divergência confusa de autenticação ou estado, porque apenas um -workspace fica ativo por vez. +Instalações mais antigas podem ter criado `~/openclaw`. Manter vários diretórios de espaço de trabalho +pode causar deriva confusa de autenticação ou estado, porque apenas um +espaço de trabalho fica ativo por vez. -**Recomendação:** mantenha um único workspace ativo. Se você não usa mais as +**Recomendação:** mantenha um único espaço de trabalho ativo. Se você não usa mais as pastas extras, arquive-as ou mova-as para a Lixeira (por exemplo `trash ~/openclaw`). -Se você intencionalmente mantém vários workspaces, verifique se -`agents.defaults.workspace` aponta para o que está ativo. +Se você intencionalmente mantém vários espaços de trabalho, certifique-se de que +`agents.defaults.workspace` aponte para o ativo. -`openclaw doctor` avisa quando detecta diretórios extras de workspace. +`openclaw doctor` avisa quando detecta diretórios extras de espaço de trabalho. -## Mapa de arquivos do workspace (o que cada arquivo significa) +## Mapa de arquivos do espaço de trabalho (o que cada arquivo significa) -Estes são os arquivos padrão que o OpenClaw espera dentro do workspace: +Estes são os arquivos padrão que o OpenClaw espera dentro do espaço de trabalho: - `AGENTS.md` - Instruções operacionais para o agente e como ele deve usar a memória. - - Carregado no início de cada sessão. - - Bom lugar para regras, prioridades e detalhes de "como se comportar". + - Carregado no início de toda sessão. + - Bom lugar para regras, prioridades e detalhes de “como se comportar”. - `SOUL.md` - Persona, tom e limites. - Carregado em toda sessão. - - Guia: [Guia de personalidade do SOUL.md](/concepts/soul) + - Guia: [Guia de personalidade do SOUL.md](/pt-BR/concepts/soul) - `USER.md` - Quem é o usuário e como se dirigir a ele. @@ -91,72 +90,72 @@ Estes são os arquivos padrão que o OpenClaw espera dentro do workspace: - Criado/atualizado durante o ritual de bootstrap. - `TOOLS.md` - - Observações sobre suas ferramentas locais e convenções. + - Notas sobre suas ferramentas locais e convenções. - Não controla a disponibilidade de ferramentas; é apenas orientação. - `HEARTBEAT.md` - - Pequena checklist opcional para execuções de heartbeat. - - Mantenha-a curta para evitar gasto de tokens. + - Pequeno checklist opcional para execuções de Heartbeat. + - Mantenha-o curto para evitar consumo de tokens. - `BOOT.md` - - Checklist opcional de inicialização executada na reinicialização do gateway quando hooks internos estão habilitados. - - Mantenha-a curta; use a ferramenta de mensagem para envios de saída. + - Checklist opcional de inicialização executado na reinicialização do gateway quando hooks internos estão ativados. + - Mantenha-o curto; use a ferramenta de mensagem para envios de saída. - `BOOTSTRAP.md` - Ritual único da primeira execução. - - Só é criado para um workspace totalmente novo. - - Exclua-o depois que o ritual for concluído. + - Criado apenas para um espaço de trabalho totalmente novo. + - Exclua-o depois que o ritual estiver concluído. - `memory/YYYY-MM-DD.md` - Log diário de memória (um arquivo por dia). - - Recomenda-se ler hoje + ontem no início da sessão. + - Recomenda-se ler o de hoje + o de ontem no início da sessão. - `MEMORY.md` (opcional) - Memória de longo prazo curada. - Carregue apenas na sessão principal e privada (não em contextos compartilhados/de grupo). -Consulte [Memória](/concepts/memory) para o fluxo de trabalho e o flush automático de memória. +Consulte [Memória](/pt-BR/concepts/memory) para o fluxo de trabalho e o flush automático de memória. - `skills/` (opcional) - - Skills específicas do workspace. - - Local de Skills com maior precedência para esse workspace. - - Substitui Skills de agente do projeto, Skills pessoais do agente, Skills gerenciadas, Skills incluídas e `skills.load.extraDirs` quando há colisão de nomes. + - Skills específicos do espaço de trabalho. + - Local de Skills com maior precedência para esse espaço de trabalho. + - Sobrescreve skills de agente do projeto, skills de agente pessoais, skills gerenciados, skills empacotados e `skills.load.extraDirs` quando os nomes entram em conflito. - `canvas/` (opcional) - - Arquivos de UI de canvas para exibições de nós (por exemplo `canvas/index.html`). + - Arquivos da UI Canvas para exibições de Node (por exemplo `canvas/index.html`). -Se qualquer arquivo de bootstrap estiver ausente, o OpenClaw injeta um marcador de "arquivo ausente" na +Se algum arquivo de bootstrap estiver ausente, o OpenClaw injeta um marcador de “arquivo ausente” na sessão e continua. Arquivos grandes de bootstrap são truncados quando injetados; -ajuste os limites com `agents.defaults.bootstrapMaxChars` (padrão: 20000) e -`agents.defaults.bootstrapTotalMaxChars` (padrão: 150000). -`openclaw setup` pode recriar padrões ausentes sem sobrescrever arquivos -existentes. +ajuste os limites com `agents.defaults.bootstrapMaxChars` (padrão: 12000) e +`agents.defaults.bootstrapTotalMaxChars` (padrão: 60000). +`openclaw setup` pode recriar padrões ausentes sem sobrescrever +arquivos existentes. -## O que NÃO está no workspace +## O que NÃO está no espaço de trabalho -Estes ficam em `~/.openclaw/` e NÃO devem ser commitados no repositório do workspace: +Estes ficam em `~/.openclaw/` e NÃO devem ser versionados no repositório do espaço de trabalho: - `~/.openclaw/openclaw.json` (configuração) - `~/.openclaw/agents//agent/auth-profiles.json` (perfis de autenticação de modelo: OAuth + chaves de API) -- `~/.openclaw/credentials/` (estado de canal/provedor mais dados legados de importação de OAuth) +- `~/.openclaw/credentials/` (estado de canal/provedor mais dados legados de importação OAuth) - `~/.openclaw/agents//sessions/` (transcrições de sessão + metadados) -- `~/.openclaw/skills/` (Skills gerenciadas) +- `~/.openclaw/skills/` (skills gerenciados) Se você precisar migrar sessões ou configuração, copie-as separadamente e mantenha-as fora do controle de versão. ## Backup com Git (recomendado, privado) -Trate o workspace como memória privada. Coloque-o em um repositório git **privado** para que ele tenha +Trate o espaço de trabalho como memória privada. Coloque-o em um repositório git **privado** para que tenha backup e possa ser recuperado. -Execute estas etapas na máquina em que o Gateway é executado (é lá que o -workspace fica). +Execute estas etapas na máquina em que o Gateway roda (é lá que o +espaço de trabalho fica). ### 1) Inicialize o repositório -Se o git estiver instalado, workspaces totalmente novos são inicializados automaticamente. Se este -workspace ainda não for um repositório, execute: +Se o git estiver instalado, espaços de trabalho totalmente novos são inicializados automaticamente. Se este +espaço de trabalho ainda não for um repositório, execute: ```bash cd ~/.openclaw/workspace @@ -165,14 +164,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "Add agent workspace" ``` -### 2) Adicione um remoto privado (opções amigáveis para iniciantes) +### 2) Adicione um remote privado (opções amigáveis para iniciantes) Opção A: interface web do GitHub 1. Crie um novo repositório **privado** no GitHub. 2. Não inicialize com um README (evita conflitos de merge). -3. Copie a URL remota HTTPS. -4. Adicione o remoto e faça push: +3. Copie a URL HTTPS do remote. +4. Adicione o remote e faça o push: ```bash git branch -M main @@ -191,8 +190,8 @@ Opção C: interface web do GitLab 1. Crie um novo repositório **privado** no GitLab. 2. Não inicialize com um README (evita conflitos de merge). -3. Copie a URL remota HTTPS. -4. Adicione o remoto e faça push: +3. Copie a URL HTTPS do remote. +4. Adicione o remote e faça o push: ```bash git branch -M main @@ -209,16 +208,16 @@ git commit -m "Update memory" git push ``` -## Não faça commit de segredos +## Não versione segredos -Mesmo em um repositório privado, evite armazenar segredos no workspace: +Mesmo em um repositório privado, evite armazenar segredos no espaço de trabalho: - Chaves de API, tokens OAuth, senhas ou credenciais privadas. - Qualquer coisa em `~/.openclaw/`. - Dumps brutos de chats ou anexos sensíveis. -Se você precisar armazenar referências sensíveis, use placeholders e mantenha o -segredo real em outro lugar (gerenciador de senhas, variáveis de ambiente ou `~/.openclaw/`). +Se você precisar armazenar referências sensíveis, use placeholders e mantenha o segredo real em outro lugar +(gerenciador de senhas, variáveis de ambiente ou `~/.openclaw/`). Sugestão de `.gitignore` inicial: @@ -230,24 +229,24 @@ Sugestão de `.gitignore` inicial: **/secrets* ``` -## Movendo o workspace para uma nova máquina +## Movendo o espaço de trabalho para uma nova máquina -1. Clone o repositório no caminho desejado (padrão `~/.openclaw/workspace`). +1. Clone o repositório para o caminho desejado (o padrão é `~/.openclaw/workspace`). 2. Defina `agents.defaults.workspace` para esse caminho em `~/.openclaw/openclaw.json`. -3. Execute `openclaw setup --workspace ` para semear qualquer arquivo ausente. -4. Se precisar de sessões, copie `~/.openclaw/agents//sessions/` da +3. Execute `openclaw setup --workspace ` para preencher quaisquer arquivos ausentes. +4. Se você precisar das sessões, copie `~/.openclaw/agents//sessions/` da máquina antiga separadamente. -## Observações avançadas +## Notas avançadas -- O roteamento de múltiplos agentes pode usar workspaces diferentes por agente. Consulte - [Roteamento de canal](/channels/channel-routing) para configuração de roteamento. -- Se `agents.defaults.sandbox` estiver habilitado, sessões que não sejam a principal podem usar - workspaces por sessão em sandbox em `agents.defaults.sandbox.workspaceRoot`. +- O roteamento multiagente pode usar diferentes espaços de trabalho por agente. Consulte + [Roteamento de canais](/pt-BR/channels/channel-routing) para a configuração de roteamento. +- Se `agents.defaults.sandbox` estiver ativado, sessões que não sejam a principal podem usar + espaços de trabalho em sandbox por sessão em `agents.defaults.sandbox.workspaceRoot`. ## Relacionados -- [Standing Orders](/automation/standing-orders) — instruções persistentes em arquivos do workspace -- [Heartbeat](/gateway/heartbeat) — arquivo de workspace HEARTBEAT.md -- [Sessão](/concepts/session) — caminhos de armazenamento de sessão -- [Sandboxing](/gateway/sandboxing) — acesso ao workspace em ambientes com sandbox +- [Standing Orders](/pt-BR/automation/standing-orders) — instruções persistentes em arquivos do espaço de trabalho +- [Heartbeat](/pt-BR/gateway/heartbeat) — arquivo `HEARTBEAT.md` do espaço de trabalho +- [Sessão](/pt-BR/concepts/session) — caminhos de armazenamento de sessão +- [Sandboxing](/pt-BR/gateway/sandboxing) — acesso ao espaço de trabalho em ambientes com sandbox diff --git a/docs/pt-BR/concepts/context.md b/docs/pt-BR/concepts/context.md index f1a7d0b10..170a5426e 100644 --- a/docs/pt-BR/concepts/context.md +++ b/docs/pt-BR/concepts/context.md @@ -1,40 +1,40 @@ --- read_when: - Você quer entender o que “contexto” significa no OpenClaw - - Você está depurando por que o modelo “sabe” algo (ou se esqueceu disso) - - Você quer reduzir a sobrecarga de contexto (/context, /status, /compact) -summary: 'Contexto: o que o modelo vê, como ele é construído e como inspecioná-lo' + - Você está depurando por que o modelo “sabe” algo (ou esqueceu) + - Você quer reduzir a sobrecarga de contexto (`/context`, `/status`, `/compact`) +summary: 'Contexto: o que o modelo vê, como ele é criado e como inspecioná-lo' title: Contexto x-i18n: - generated_at: "2026-04-12T23:28:01Z" + generated_at: "2026-04-18T05:24:45Z" model: gpt-5.4 provider: openai - source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d + source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9 source_path: concepts/context.md workflow: 15 --- # Contexto -“Contexto” é **tudo o que o OpenClaw envia ao modelo para uma execução**. Ele é limitado pela **janela de contexto** do modelo (limite de tokens). +“Contexto” é **tudo o que o OpenClaw envia ao modelo em uma execução**. Ele é limitado pela **janela de contexto** do modelo (limite de tokens). Modelo mental para iniciantes: -- **Prompt do sistema** (construído pelo OpenClaw): regras, ferramentas, lista de Skills, tempo/runtime e arquivos do workspace injetados. +- **Prompt de sistema** (criado pelo OpenClaw): regras, ferramentas, lista de Skills, hora/runtime e arquivos do workspace injetados. - **Histórico da conversa**: suas mensagens + as mensagens do assistente nesta sessão. - **Chamadas/resultados de ferramentas + anexos**: saída de comandos, leituras de arquivos, imagens/áudio etc. -Contexto _não é a mesma coisa_ que “memória”: a memória pode ser armazenada em disco e recarregada depois; contexto é o que está dentro da janela atual do modelo. +Contexto _não é a mesma coisa_ que “memória”: a memória pode ser armazenada em disco e recarregada depois; o contexto é o que está dentro da janela atual do modelo. -## Início rápido (inspecionar o contexto) +## Início rápido (inspecionar contexto) - `/status` → visão rápida de “quão cheia está minha janela?” + configurações da sessão. -- `/context list` → o que está sendo injetado + tamanhos aproximados (por arquivo + totais). -- `/context detail` → detalhamento mais profundo: por arquivo, tamanhos de schema de ferramenta, tamanhos de entrada por skill e tamanho do prompt do sistema. +- `/context list` → o que é injetado + tamanhos aproximados (por arquivo + totais). +- `/context detail` → detalhamento mais profundo: tamanhos por arquivo, por schema de ferramenta, por entrada de Skill e tamanho do prompt de sistema. - `/usage tokens` → adiciona um rodapé de uso por resposta às respostas normais. -- `/compact` → resume o histórico antigo em uma entrada compacta para liberar espaço na janela. +- `/compact` → resume o histórico mais antigo em uma entrada compacta para liberar espaço na janela. -Veja também: [Comandos de barra](/pt-BR/tools/slash-commands), [Uso de tokens e custos](/pt-BR/reference/token-use), [Compaction](/pt-BR/concepts/compaction). +Veja também: [Comandos slash](/pt-BR/tools/slash-commands), [Uso de tokens e custos](/pt-BR/reference/token-use), [Compaction](/pt-BR/concepts/compaction). ## Exemplo de saída @@ -45,23 +45,23 @@ Os valores variam conforme o modelo, provedor, política de ferramentas e o que ``` 🧠 Detalhamento do contexto Workspace: -Bootstrap máx./arquivo: 20,000 chars +Bootstrap máx./arquivo: 12,000 caracteres Sandbox: mode=non-main sandboxed=false -Prompt do sistema (execução): 38,412 chars (~9,603 tok) (Contexto do projeto 23,901 chars (~5,976 tok)) +Prompt de sistema (execução): 38,412 caracteres (~9,603 tok) (Contexto do Projeto 23,901 caracteres (~5,976 tok)) Arquivos do workspace injetados: -- AGENTS.md: OK | bruto 1,742 chars (~436 tok) | injetado 1,742 chars (~436 tok) -- SOUL.md: OK | bruto 912 chars (~228 tok) | injetado 912 chars (~228 tok) -- TOOLS.md: TRUNCADO | bruto 54,210 chars (~13,553 tok) | injetado 20,962 chars (~5,241 tok) -- IDENTITY.md: OK | bruto 211 chars (~53 tok) | injetado 211 chars (~53 tok) -- USER.md: OK | bruto 388 chars (~97 tok) | injetado 388 chars (~97 tok) +- AGENTS.md: OK | bruto 1,742 caracteres (~436 tok) | injetado 1,742 caracteres (~436 tok) +- SOUL.md: OK | bruto 912 caracteres (~228 tok) | injetado 912 caracteres (~228 tok) +- TOOLS.md: TRUNCADO | bruto 54,210 caracteres (~13,553 tok) | injetado 20,962 caracteres (~5,241 tok) +- IDENTITY.md: OK | bruto 211 caracteres (~53 tok) | injetado 211 caracteres (~53 tok) +- USER.md: OK | bruto 388 caracteres (~97 tok) | injetado 388 caracteres (~97 tok) - HEARTBEAT.md: AUSENTE | bruto 0 | injetado 0 -- BOOTSTRAP.md: OK | bruto 0 chars (~0 tok) | injetado 0 chars (~0 tok) +- BOOTSTRAP.md: OK | bruto 0 caracteres (~0 tok) | injetado 0 caracteres (~0 tok) -Lista de Skills (texto do prompt do sistema): 2,184 chars (~546 tok) (12 skills) +Lista de Skills (texto do prompt de sistema): 2,184 caracteres (~546 tok) (12 Skills) Ferramentas: read, edit, write, exec, process, browser, message, sessions_send, … -Lista de ferramentas (texto do prompt do sistema): 1,032 chars (~258 tok) -Schemas de ferramentas (JSON): 31,988 chars (~7,997 tok) (contam para o contexto; não mostrados como texto) +Lista de ferramentas (texto do prompt de sistema): 1,032 caracteres (~258 tok) +Schemas das ferramentas (JSON): 31,988 caracteres (~7,997 tok) (contam para o contexto; não exibidos como texto) Ferramentas: (mesmas acima) Tokens da sessão (em cache): 14,250 total / ctx=32,000 @@ -72,14 +72,14 @@ Tokens da sessão (em cache): 14,250 total / ctx=32,000 ``` 🧠 Detalhamento do contexto (detalhado) … -Principais skills (tamanho da entrada no prompt): -- frontend-design: 412 chars (~103 tok) -- oracle: 401 chars (~101 tok) -… (+10 mais skills) +Principais Skills (tamanho da entrada no prompt): +- frontend-design: 412 caracteres (~103 tok) +- oracle: 401 caracteres (~101 tok) +… (+10 mais Skills) Principais ferramentas (tamanho do schema): -- browser: 9,812 chars (~2,453 tok) -- exec: 6,240 chars (~1,560 tok) +- browser: 9,812 caracteres (~2,453 tok) +- exec: 6,240 caracteres (~1,560 tok) … (+N mais ferramentas) ``` @@ -87,27 +87,27 @@ Principais ferramentas (tamanho do schema): Tudo o que o modelo recebe conta, incluindo: -- Prompt do sistema (todas as seções). +- Prompt de sistema (todas as seções). - Histórico da conversa. - Chamadas de ferramentas + resultados de ferramentas. - Anexos/transcrições (imagens/áudio/arquivos). -- Resumos de compaction e artefatos de pruning. +- Resumos de Compaction e artefatos de pruning. - “Wrappers” do provedor ou cabeçalhos ocultos (não visíveis, mas ainda contam). -## Como o OpenClaw constrói o prompt do sistema +## Como o OpenClaw cria o prompt de sistema -O prompt do sistema é **de propriedade do OpenClaw** e reconstruído a cada execução. Ele inclui: +O prompt de sistema é **de propriedade do OpenClaw** e reconstruído a cada execução. Ele inclui: - Lista de ferramentas + descrições curtas. -- Lista de Skills (apenas metadados; veja abaixo). -- Local do workspace. -- Hora (UTC + hora do usuário convertida, se configurada). +- Lista de Skills (somente metadados; veja abaixo). +- Localização do workspace. +- Hora (UTC + hora convertida do usuário, se configurada). - Metadados de runtime (host/OS/modelo/thinking). -- Arquivos bootstrap do workspace injetados em **Contexto do projeto**. +- Arquivos bootstrap do workspace injetados em **Contexto do Projeto**. -Detalhamento completo: [Prompt do sistema](/pt-BR/concepts/system-prompt). +Detalhamento completo: [Prompt de sistema](/pt-BR/concepts/system-prompt). -## Arquivos do workspace injetados (Contexto do projeto) +## Arquivos do workspace injetados (Contexto do Projeto) Por padrão, o OpenClaw injeta um conjunto fixo de arquivos do workspace (se presentes): @@ -117,69 +117,71 @@ Por padrão, o OpenClaw injeta um conjunto fixo de arquivos do workspace (se pre - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (apenas na primeira execução) +- `BOOTSTRAP.md` (somente na primeira execução) -Arquivos grandes são truncados por arquivo usando `agents.defaults.bootstrapMaxChars` (padrão `20000` chars). O OpenClaw também impõe um limite total de injeção de bootstrap entre os arquivos com `agents.defaults.bootstrapTotalMaxChars` (padrão `150000` chars). `/context` mostra os tamanhos **bruto vs injetado** e se houve truncamento. +Arquivos grandes são truncados por arquivo usando `agents.defaults.bootstrapMaxChars` (padrão `12000` caracteres). O OpenClaw também aplica um limite total de injeção de bootstrap entre arquivos com `agents.defaults.bootstrapTotalMaxChars` (padrão `60000` caracteres). `/context` mostra os tamanhos **bruto vs injetado** e se houve truncamento. -Quando ocorre truncamento, o runtime pode injetar um bloco de aviso dentro do prompt em Contexto do projeto. Configure isso com `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; padrão `once`). +Quando ocorre truncamento, o runtime pode injetar um bloco de aviso no prompt em Contexto do Projeto. Configure isso com `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; padrão `once`). ## Skills: injetadas vs carregadas sob demanda -O prompt do sistema inclui uma **lista de Skills** compacta (nome + descrição + local). Essa lista tem uma sobrecarga real. +O prompt de sistema inclui uma **lista de Skills** compacta (nome + descrição + localização). Essa lista tem sobrecarga real. -As instruções de Skill _não_ são incluídas por padrão. Espera-se que o modelo use `read` no `SKILL.md` da skill **somente quando necessário**. +As instruções da Skill _não_ são incluídas por padrão. Espera-se que o modelo use `read` no `SKILL.md` da Skill **somente quando necessário**. ## Ferramentas: há dois custos -As ferramentas afetam o contexto de duas formas: +As ferramentas afetam o contexto de duas maneiras: -1. **Texto da lista de ferramentas** no prompt do sistema (o que você vê como “Tooling”). +1. **Texto da lista de ferramentas** no prompt de sistema (o que você vê como “Tooling”). 2. **Schemas de ferramentas** (JSON). Eles são enviados ao modelo para que ele possa chamar ferramentas. Eles contam para o contexto mesmo que você não os veja como texto simples. `/context detail` detalha os maiores schemas de ferramentas para que você possa ver o que mais pesa. ## Comandos, diretivas e "atalhos inline" -Os comandos de barra são tratados pelo Gateway. Existem alguns comportamentos diferentes: +Os comandos slash são tratados pelo Gateway. Há alguns comportamentos diferentes: -- **Comandos autônomos**: uma mensagem que contém apenas `/...` é executada como comando. -- **Diretivas**: `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` são removidos antes que o modelo veja a mensagem. - - Mensagens com apenas diretivas persistem as configurações da sessão. +- **Comandos independentes**: uma mensagem que contém apenas `/...` é executada como comando. +- **Diretivas**: `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` são removidas antes que o modelo veja a mensagem. + - Mensagens compostas apenas por diretivas persistem as configurações da sessão. - Diretivas inline em uma mensagem normal funcionam como dicas por mensagem. -- **Atalhos inline** (apenas remetentes permitidos): certos tokens `/...` dentro de uma mensagem normal podem ser executados imediatamente (exemplo: “hey /status”) e são removidos antes que o modelo veja o texto restante. +- **Atalhos inline** (somente remetentes permitidos): certos tokens `/...` dentro de uma mensagem normal podem ser executados imediatamente (exemplo: “hey /status”) e são removidos antes que o modelo veja o texto restante. -Detalhes: [Comandos de barra](/pt-BR/tools/slash-commands). +Detalhes: [Comandos slash](/pt-BR/tools/slash-commands). -## Sessões, compaction e pruning (o que persiste) +## Sessões, Compaction e pruning (o que persiste) O que persiste entre mensagens depende do mecanismo: -- **Histórico normal** persiste na transcrição da sessão até ser compactado/removido pela política. +- **Histórico normal** persiste na transcrição da sessão até ser compactado/removido por política. - **Compaction** persiste um resumo na transcrição e mantém intactas as mensagens recentes. -- **Pruning** remove resultados antigos de ferramentas do prompt _em memória_ de uma execução, mas não reescreve a transcrição. +- **Pruning** remove resultados antigos de ferramentas do prompt _em memória_ para uma execução, mas não reescreve a transcrição. -Documentação: [Sessão](/pt-BR/concepts/session), [Compaction](/pt-BR/concepts/compaction), [Session pruning](/pt-BR/concepts/session-pruning). +Docs: [Sessão](/pt-BR/concepts/session), [Compaction](/pt-BR/concepts/compaction), [Session pruning](/pt-BR/concepts/session-pruning). Por padrão, o OpenClaw usa o mecanismo de contexto `legacy` integrado para montagem e -compaction. Se você instalar um plugin que fornece `kind: "context-engine"` e -selecioná-lo com `plugins.slots.contextEngine`, o OpenClaw delega a montagem do contexto, `/compact` e hooks relacionados ao ciclo de vida do contexto de subagentes a esse -mecanismo. `ownsCompaction: false` não faz fallback automático para o -mecanismo legado; o mecanismo ativo ainda precisa implementar `compact()` corretamente. Veja -[Context Engine](/pt-BR/concepts/context-engine) para a interface conectável completa, -hooks de ciclo de vida e configuração. +Compaction. Se você instalar um Plugin que forneça `kind: "context-engine"` e +selecioná-lo com `plugins.slots.contextEngine`, o OpenClaw delegará a montagem +de contexto, `/compact` e hooks relacionados do ciclo de vida do contexto de +subagentes para esse mecanismo. `ownsCompaction: false` não faz fallback +automático para o mecanismo legado; o mecanismo ativo ainda precisa implementar +`compact()` corretamente. Veja +[Context Engine](/pt-BR/concepts/context-engine) para a interface conectável +completa, hooks de ciclo de vida e configuração. ## O que `/context` realmente informa -`/context` prefere o relatório mais recente do prompt do sistema **construído na execução**, quando disponível: +`/context` prefere o relatório mais recente do prompt de sistema **criado na execução**, quando disponível: -- `System prompt (run)` = capturado da última execução embutida (com suporte a ferramentas) e persistido no armazenamento da sessão. -- `System prompt (estimate)` = calculado dinamicamente quando não existe relatório de execução (ou ao executar por um backend de CLI que não gera o relatório). +- `System prompt (run)` = capturado da última execução incorporada (com capacidade de ferramenta) e persistido no armazenamento da sessão. +- `System prompt (estimate)` = calculado em tempo real quando não existe relatório de execução (ou ao executar por um backend de CLI que não gera o relatório). -De qualquer forma, ele informa tamanhos e principais contribuintes; ele **não** exibe o prompt do sistema completo nem os schemas das ferramentas. +De qualquer forma, ele informa tamanhos e os principais contribuintes; ele **não** mostra o prompt de sistema completo nem os schemas das ferramentas. -## Relacionado +## Relacionados -- [Context Engine](/pt-BR/concepts/context-engine) — injeção de contexto personalizada via plugins -- [Compaction](/pt-BR/concepts/compaction) — resumindo conversas longas -- [Prompt do sistema](/pt-BR/concepts/system-prompt) — como o prompt do sistema é construído -- [Agent Loop](/pt-BR/concepts/agent-loop) — o ciclo completo de execução do agente +- [Context Engine](/pt-BR/concepts/context-engine) — injeção de contexto personalizada via Plugins +- [Compaction](/pt-BR/concepts/compaction) — resumo de conversas longas +- [Prompt de sistema](/pt-BR/concepts/system-prompt) — como o prompt de sistema é criado +- [Loop do agente](/pt-BR/concepts/agent-loop) — o ciclo completo de execução do agente diff --git a/docs/pt-BR/concepts/qa-e2e-automation.md b/docs/pt-BR/concepts/qa-e2e-automation.md index 3d2931d0b..0c6f7c6dc 100644 --- a/docs/pt-BR/concepts/qa-e2e-automation.md +++ b/docs/pt-BR/concepts/qa-e2e-automation.md @@ -2,36 +2,32 @@ read_when: - Estendendo o qa-lab ou o qa-channel - Adicionando cenários de QA com suporte do repositório - - Criando uma automação de QA com maior realismo em torno do painel do Gateway -summary: Forma da automação privada de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo + - Criando automação de QA com maior realismo em torno do painel do Gateway +summary: Formato privado de automação de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo title: Automação E2E de QA x-i18n: - generated_at: "2026-04-17T05:36:09Z" + generated_at: "2026-04-18T05:24:45Z" model: gpt-5.4 provider: openai - source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 + source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automação E2E de QA -A stack privada de QA foi feita para exercitar o OpenClaw de uma forma mais realista, -no formato de canais, do que um único teste unitário consegue. +A pilha privada de QA foi projetada para exercitar o OpenClaw de uma forma mais realista e com formato de canal do que um único teste unitário consegue. Peças atuais: -- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, - reação, edição e exclusão. -- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, - injetar mensagens recebidas e exportar um relatório em Markdown. -- `qa/`: recursos seed com suporte do repositório para a tarefa inicial e cenários - básicos de QA. +- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, reação, edição e exclusão. +- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, injetar mensagens de entrada e exportar um relatório em Markdown. +- `qa/`: recursos com seed mantidos no repositório para a tarefa inicial e cenários básicos de QA. O fluxo atual do operador de QA é um site de QA com dois painéis: - Esquerda: painel do Gateway (Control UI) com o agente. -- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano de cenário. +- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano do cenário. Execute com: @@ -39,13 +35,9 @@ Execute com: pnpm qa:lab:up ``` -Isso compila o site de QA, inicia a lane do gateway com suporte de Docker e expõe a -página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma -missão de QA, observar o comportamento real do canal e registrar o que funcionou, -falhou ou permaneceu bloqueado. +Isso compila o site de QA, inicia a lane do Gateway com Docker e expõe a página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou permaneceu bloqueado. -Para uma iteração mais rápida da UI do QA Lab sem reconstruir a imagem Docker a cada vez, -inicie a stack com um bundle do QA Lab montado por bind mount: +Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker a cada vez, inicie a pilha com um bundle do QA Lab montado por bind: ```bash pnpm openclaw qa docker-build-image @@ -54,144 +46,108 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind mount de -`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` -recompila esse bundle quando há mudanças, e o navegador recarrega automaticamente quando o hash -do recurso do QA Lab muda. +`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e monta por bind `extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` recompila esse bundle a cada alteração, e o navegador recarrega automaticamente quando o hash de recursos do QA Lab muda. -Para uma lane de smoke do Matrix com transporte real, execute: +Para uma lane de smoke real de transporte com Matrix, execute: ```bash pnpm openclaw qa matrix ``` -Essa lane provisiona um homeserver Tuwunel descartável no Docker, registra usuários -temporários de driver, SUT e observador, cria uma sala privada e então executa -o Plugin real do Matrix dentro de um filho de gateway de QA. A lane de transporte ao vivo mantém -a configuração do filho restrita ao transporte em teste, então o Matrix roda sem -`qa-channel` na configuração do filho. Ela grava os artefatos do relatório estruturado e -um log combinado de stdout/stderr no diretório de saída de QA do Matrix selecionado. Para -capturar também a saída externa de compilação/launcher de `scripts/run-node.mjs`, defina -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` para um arquivo de log local ao repositório. +Essa lane provisiona um homeserver Tuwunel descartável no Docker, registra usuários temporários de driver, SUT e observador, cria uma sala privada e então executa o Plugin real do Matrix dentro de um processo filho de Gateway de QA. A lane de transporte ao vivo mantém a configuração filha restrita ao transporte em teste, para que o Matrix seja executado sem `qa-channel` na configuração filha. Ela grava os artefatos estruturados do relatório e um log combinado de stdout/stderr no diretório de saída de Matrix QA selecionado. Para capturar também a saída externa de compilação/inicialização de `scripts/run-node.mjs`, defina `OPENCLAW_RUN_NODE_OUTPUT_LOG=` para um arquivo de log local ao repositório. -Para uma lane de smoke do Telegram com transporte real, execute: +Para uma lane de smoke real de transporte com Telegram, execute: ```bash pnpm openclaw qa telegram ``` -Essa lane usa um grupo privado real do Telegram em vez de provisionar um -servidor descartável. Ela exige `OPENCLAW_QA_TELEGRAM_GROUP_ID`, -`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, além de dois bots distintos no mesmo -grupo privado. O bot SUT precisa ter um nome de usuário no Telegram, e a -observação bot-para-bot funciona melhor quando ambos os bots têm o Bot-to-Bot Communication Mode -ativado no `@BotFather`. +Essa lane mira em um grupo privado real do Telegram em vez de provisionar um servidor descartável. Ela requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, além de dois bots distintos no mesmo grupo privado. O bot SUT precisa ter um nome de usuário no Telegram, e a observação entre bots funciona melhor quando ambos os bots têm o Bot-to-Bot Communication Mode habilitado em `@BotFather`. -As lanes de transporte ao vivo agora compartilham um contrato menor em vez de cada uma -inventar o próprio formato de lista de cenários. +As lanes de transporte ao vivo agora compartilham um contrato menor em vez de cada uma inventar seu próprio formato de lista de cenários: -`qa-channel` continua sendo a suíte ampla de comportamento sintético do produto e não faz parte -da matriz de cobertura de transporte ao vivo. +`qa-channel` continua sendo a suíte ampla de comportamento sintético do produto e não faz parte da matriz de cobertura de transporte ao vivo. -| Lane | Canary | Bloqueio por menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Bloqueio por menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Continuação em thread | Isolamento de thread | Observação de reação | Comando de ajuda | +| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | -------------------- | -------------------- | -------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Isso mantém `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix, -Telegram e futuros transportes ao vivo compartilham uma checklist explícita de contrato de transporte. +Isso mantém o `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix, Telegram e futuros transportes ao vivo compartilham uma lista explícita de verificação do contrato de transporte. -Para uma lane de VM Linux descartável sem colocar Docker no caminho de QA, execute: +Para uma lane com VM Linux descartável sem trazer Docker para o fluxo de QA, execute: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Isso inicializa um guest novo do Multipass, instala dependências, compila o OpenClaw -dentro do guest, executa `qa suite` e então copia o relatório e -resumo normais de QA de volta para `.artifacts/qa-e2e/...` no host. -Isso reutiliza o mesmo comportamento de seleção de cenário de `qa suite` no host. -As execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo -com workers de gateway isolados por padrão, até 64 workers ou a contagem de cenários -selecionados. Use `--concurrency ` para ajustar a quantidade de workers, ou -`--concurrency 1` para execução serial. -As execuções ao vivo encaminham as entradas de autenticação de QA suportadas que são práticas para o -guest: chaves de provider via variável de ambiente, o caminho de configuração do provider ao vivo de QA e -`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest -possa gravar de volta pelo workspace montado. +Isso inicializa um guest novo do Multipass, instala dependências, compila o OpenClaw dentro do guest, executa `qa suite` e então copia o relatório e o resumo normais de QA de volta para `.artifacts/qa-e2e/...` no host. +Ele reutiliza o mesmo comportamento de seleção de cenários de `qa suite` no host. +Execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo com workers isolados de Gateway por padrão, até 64 workers ou a contagem de cenários selecionada. Use `--concurrency ` para ajustar a quantidade de workers, ou `--concurrency 1` para execução serial. +Execuções ao vivo encaminham as entradas compatíveis de autenticação de QA que são práticas para o guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ao vivo de QA e `CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest possa gravar de volta por meio do workspace montado. -## Seeds com suporte do repositório +## Seeds mantidos no repositório -Os recursos seed ficam em `qa/`: +Os recursos com seed ficam em `qa/`: - `qa/scenarios/index.md` -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` -Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos -quanto para o agente. +Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o agente. -`qa-lab` deve permanecer um executor genérico de Markdown. Cada arquivo Markdown de cenário é -a fonte da verdade para uma execução de teste e deve definir: +O `qa-lab` deve continuar sendo um executor genérico de Markdown. Cada arquivo Markdown de cenário é a fonte da verdade para uma execução de teste e deve definir: - metadados do cenário -- referências de docs e código -- requisitos opcionais de plugin -- patch opcional de configuração do gateway +- metadados opcionais de categoria, capacidade, lane e risco +- referências de documentação e código +- requisitos opcionais de Plugin +- patch opcional de configuração do Gateway - o `qa-flow` executável -A superfície de runtime reutilizável que dá suporte ao `qa-flow` pode permanecer genérica -e transversal. Por exemplo, cenários em Markdown podem combinar helpers do lado do transporte -com helpers do lado do navegador que controlam a Control UI embutida por meio da -superfície `browser.request` do Gateway sem adicionar um executor com caso especial. +A superfície de runtime reutilizável que dá suporte ao `qa-flow` pode continuar genérica e transversal. Por exemplo, cenários em Markdown podem combinar helpers do lado do transporte com helpers do lado do navegador que dirigem a Control UI incorporada por meio da interface `browser.request` do Gateway sem adicionar um executor com caso especial. + +Os arquivos de cenário devem ser agrupados por capacidade do produto, e não pela pasta da árvore de código-fonte. Mantenha os IDs de cenário estáveis quando os arquivos forem movidos; use `docsRefs` e `codeRefs` para rastreabilidade de implementação. A lista básica deve permanecer ampla o suficiente para cobrir: -- chat em DM e em canal +- chat em DM e canal - comportamento de thread - ciclo de vida de ações de mensagem - callbacks de Cron - recuperação de memória - troca de modelo - handoff para subagente -- leitura do repositório e de docs +- leitura do repositório e da documentação - uma pequena tarefa de compilação, como Lobster Invaders -## Lanes de mock de provider +## Lanes de mock de provedor -`qa suite` tem duas lanes locais de mock de provider: +`qa suite` tem duas lanes locais de mock de provedor: -- `mock-openai` é o mock do OpenClaw sensível ao cenário. Ele continua sendo a - lane de mock determinística padrão para QA com suporte do repositório e gates de paridade. -- `aimock` inicia um servidor de provider com suporte do AIMock para cobertura experimental de protocolo, - fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o dispatcher - de cenários do `mock-openai`. +- `mock-openai` é o mock do OpenClaw sensível ao cenário. Ele continua sendo a lane de mock determinística padrão para QA com suporte do repositório e gates de paridade. +- `aimock` inicia um servidor de provedor baseado em AIMock para cobertura experimental de protocolo, fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o despachante de cenários de `mock-openai`. -A implementação da lane de provider fica em `extensions/qa-lab/src/providers/`. -Cada provider é dono dos próprios padrões, inicialização do servidor local, configuração -de modelo do gateway, necessidades de preparação de perfil de autenticação e flags de capacidade -ao vivo/mock. O código compartilhado da suíte e do gateway deve rotear pelo registro de providers em vez de -ramificar com base em nomes de providers. +A implementação da lane de provedor fica em `extensions/qa-lab/src/providers/`. +Cada provedor é responsável por seus padrões, inicialização de servidor local, configuração de modelo do Gateway, necessidades de preparação de perfil de autenticação e flags de capacidade de live/mock. O código compartilhado de suíte e Gateway deve rotear pelo registro de provedores em vez de ramificar pelos nomes dos provedores. ## Adaptadores de transporte -`qa-lab` é dono de uma superfície genérica de transporte para cenários de QA em Markdown. -`qa-channel` é o primeiro adaptador nessa superfície, mas o objetivo do design é mais amplo: -canais futuros, reais ou sintéticos, devem se conectar ao mesmo executor de suíte em vez de -adicionar um executor de QA específico para cada transporte. +O `qa-lab` é responsável por uma interface genérica de transporte para cenários de QA em Markdown. +`qa-channel` é o primeiro adaptador nessa interface, mas o objetivo do design é mais amplo: +canais futuros, reais ou sintéticos, devem se conectar ao mesmo executor de suíte em vez de adicionar um executor de QA específico de transporte. -No nível de arquitetura, a divisão é: +No nível da arquitetura, a divisão é: -- `qa-lab` é dono da execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios. -- o adaptador de transporte é dono da configuração do gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado. -- arquivos de cenário em Markdown em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa. +- `qa-lab` é responsável pela execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios. +- o adaptador de transporte é responsável pela configuração do Gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado. +- os arquivos de cenário em Markdown sob `qa/scenarios/` definem a execução de teste; o `qa-lab` fornece a superfície de runtime reutilizável que os executa. -A orientação de adoção voltada para maintainers para novos adaptadores de canal está em +A orientação de adoção voltada a mantenedores para novos adaptadores de canal está em [Testing](/pt-BR/help/testing#adding-a-channel-to-qa). ## Relatórios -`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado. +O `qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento. O relatório deve responder: - O que funcionou @@ -199,8 +155,7 @@ O relatório deve responder: - O que permaneceu bloqueado - Quais cenários de acompanhamento valem a pena adicionar -Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelos ao vivo -e grave um relatório em Markdown avaliado: +Para verificações de personalidade e estilo, execute o mesmo cenário em várias refs de modelo ao vivo e grave um relatório em Markdown avaliado: ```bash pnpm openclaw qa character-eval \ @@ -219,40 +174,21 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -O comando executa processos filhos locais do gateway de QA, não Docker. Cenários de avaliação de caráter -devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário -como chat, ajuda sobre o workspace e pequenas tarefas em arquivos. O modelo candidato -não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição -completa, registra estatísticas básicas da execução e então pede que os modelos juízes, em modo fast com -raciocínio `xhigh`, classifiquem as execuções por naturalidade, vibe e humor. -Use `--blind-judge-models` ao comparar providers: o prompt do juiz ainda recebe -cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos neutros -como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após -o parsing. -As execuções dos candidatos usam por padrão `high` thinking, com `xhigh` para modelos OpenAI que -oferecem suporte. Substitua um candidato específico inline com -`--model provider/model,thinking=`. `--thinking ` ainda define um fallback -global, e o formato mais antigo `--model-thinking ` é -mantido por compatibilidade. -As refs candidatas da OpenAI usam o modo fast por padrão para que o processamento prioritário seja usado -quando o provider oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando -um único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser -forçar o modo fast para todos os modelos candidatos. As durações de candidatos e juízes são -registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente -para não classificar com base em velocidade. -As execuções dos modelos candidatos e dos juízes usam concorrência 16 por padrão. Reduza -`--concurrency` ou `--judge-concurrency` quando limites do provider ou pressão no gateway local -tornarem uma execução muito ruidosa. -Quando nenhum `--model` candidato é passado, a avaliação de caráter usa por padrão +O comando executa processos filhos locais de Gateway de QA, não Docker. Os cenários de avaliação de personalidade devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário, como chat, ajuda com workspace e pequenas tarefas em arquivos. O modelo candidato não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição completa, registra estatísticas básicas da execução e depois solicita aos modelos juízes, em modo fast, com raciocínio `xhigh`, que classifiquem as execuções por naturalidade, vibe e humor. +Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe cada transcrição e status de execução, mas as refs dos candidatos são substituídas por rótulos neutros como `candidate-01`; o relatório remapeia as classificações para as refs reais após o parsing. +As execuções candidatas usam `high` thinking por padrão, com `xhigh` para modelos OpenAI que oferecem suporte. Substitua um candidato específico inline com `--model provider/model,thinking=`. `--thinking ` ainda define um fallback global, e o formato mais antigo `--model-thinking ` é mantido por compatibilidade. +As refs candidatas de OpenAI usam modo fast por padrão para que o processamento prioritário seja usado quando o provedor oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um único candidato ou juiz precisar de substituição. Passe `--fast` apenas quando quiser forçar o modo fast para todos os modelos candidatos. As durações de candidatos e juízes são registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente para não classificar por velocidade. +As execuções de modelos candidatos e juízes usam concorrência 16 por padrão. Reduza `--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no Gateway local tornarem uma execução muito ruidosa. +Quando nenhum `--model` candidato é informado, a avaliação de personalidade usa por padrão `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` e -`google/gemini-3.1-pro-preview` quando nenhum `--model` é passado. -Quando nenhum `--judge-model` é passado, os juízes usam por padrão +`google/gemini-3.1-pro-preview` quando nenhum `--model` é informado. +Quando nenhum `--judge-model` é informado, os juízes usam por padrão `openai/gpt-5.4,thinking=xhigh,fast` e `anthropic/claude-opus-4-6,thinking=high`. -## Docs relacionadas +## Documentação relacionada - [Testing](/pt-BR/help/testing) - [QA Channel](/pt-BR/channels/qa-channel) diff --git a/docs/pt-BR/concepts/system-prompt.md b/docs/pt-BR/concepts/system-prompt.md index 3561646e4..fa580fe16 100644 --- a/docs/pt-BR/concepts/system-prompt.md +++ b/docs/pt-BR/concepts/system-prompt.md @@ -1,98 +1,98 @@ --- read_when: - - Editando o texto do prompt de sistema, a lista de ferramentas ou as seções de hora/Heartbeat - - Alterando o bootstrap do workspace ou o comportamento de injeção de Skills -summary: O que o prompt de sistema do OpenClaw contém e como ele é montado -title: Prompt de sistema + - 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 de 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-15T19:41:35Z" + generated_at: "2026-04-18T05:24:44Z" model: gpt-5.4 provider: openai - source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 + source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab source_path: concepts/system-prompt.md workflow: 15 --- -# Prompt de sistema +# Prompt do sistema -O OpenClaw monta um prompt de sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-agent. +O OpenClaw cria um prompt do sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-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 sensíveis ao cache sem substituir todo o prompt de propriedade do OpenClaw. O runtime do provedor pode: -- substituir um pequeno conjunto de seções centrais nomeadas (`interaction_style`, +- substituir um pequeno conjunto de seções principais 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 de famílias de modelos. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou mudanças de prompt realmente globais, não para o comportamento normal do provedor. +Use contribuições de propriedade do provedor para ajustes específicos por família de modelo. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou mudanças de prompt realmente globais, e não para comportamento normal de provedor. ## Estrutura O prompt é intencionalmente compacto e usa seções fixas: -- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas, além de orientações de uso de ferramentas em runtime. -- **Segurança**: lembrete curto de proteção para evitar comportamento de busca de poder ou desvio de supervisão. +- **Ferramentas**: lembrete da fonte da verdade para ferramentas estruturadas, 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. - **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`, aplicar patch na configuração com `config.patch`, substituir toda a - configuração com `config.apply` e executar `update.run` somente mediante solicitação explícita do usuário. A ferramenta `gateway`, restrita ao 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 sob 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. - **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 os arquivos de bootstrap estão incluídos abaixo. -- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos do sandbox e se exec elevado está disponível. +- **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 confirmação, quando heartbeats estão habilitados para o agente padrão. +- **Heartbeats**: prompt de heartbeat e comportamento de ack, 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 de alternância com /reasoning. +- **Raciocínio**: nível atual de visibilidade + dica do alternador `/reasoning`. -A seção Ferramentas também inclui orientações de runtime para trabalhos de longa duração: +A seção Ferramentas também inclui orientações de runtime para trabalho de longa duração: -- use Cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente) - em vez de loops de `exec` com sleep, truques de atraso com `yieldMs` ou polling repetido de `process` -- use `exec` / `process` apenas para comandos que começam agora e continuam rodando +- use cron para acompanhamento futuro (`verifique novamente mais tarde`, 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 despertar automático na conclusão estiver habilitado, inicie o comando uma vez e confie no caminho de despertar baseado em push quando ele emitir saída ou falhar +- quando a ativação automática por conclusão estiver habilitada, inicie o comando uma vez e confie + no caminho de ativação 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 de subagentes é - baseada em push e anunciada automaticamente de volta ao solicitante +- se a tarefa for maior, prefira `sessions_spawn`; a conclusão de subagente é + baseada em push e se anuncia automaticamente de volta ao solicitante - não faça polling de `subagents list` / `sessions_list` em loop apenas para esperar - a conclusão + pela 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 -etapa `in_progress` e evitar repetir o plano inteiro após cada atualização. +modelo para usá-la apenas em trabalho não trivial com várias 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 de sistema são orientativas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e allowlists de canais para imposição rígida; operadores podem desabilitar isso 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 ferramenta, aprovações de exec, sandboxing e listas de permissão de canal para imposição rígida; operadores podem desabilitá-las por design. -Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora instrui o -agente a confiar primeiro nessa interface nativa de aprovação. Ele só deve incluir um comando manual -`/approve` quando o resultado da ferramenta informar que aprovações no chat não estão disponíveis ou -que aprovação manual é o único caminho. +Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora informa ao +agente para confiar primeiro nessa UI 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 +que a aprovação manual é o único caminho. ## Modos de prompt -O OpenClaw pode renderizar prompts de sistema menores para subagentes. O runtime define um +O OpenClaw pode renderizar prompts do sistema menores para subagentes. O runtime define um `promptMode` para cada execução (não é uma configuração voltada ao usuário): - `full` (padrão): inclui todas as seções acima. -- `minimal`: usado para subagentes; omite **Skills**, **Recordação de Memória**, **Autoatualização do OpenClaw**, **Aliases de modelos**, **Identidade do usuário**, **Tags de resposta**, - **Mensageria**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**, +- `minimal`: usado para subagentes; omite **Skills**, **Recuperação de memória**, **Autoatualização do OpenClaw**, **Aliases de modelo**, **Identidade do usuário**, **Tags de resposta**, + **Mensagens**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**, Workspace, Sandbox, Data e hora atuais (quando conhecidas), Runtime e contexto - injetado continuam disponíveis. + injetado permanecem disponíveis. - `none`: retorna apenas a linha base de identidade. Quando `promptMode=minimal`, prompts extras injetados são rotulados como **Contexto do subagente** -em vez de **Contexto de chat em grupo**. +em vez de **Contexto do chat em grupo**. ## Injeção de bootstrap do workspace -Os 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: +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 de leituras explícitas: - `AGENTS.md` - `SOUL.md` @@ -100,49 +100,49 @@ Os arquivos de bootstrap são recortados e anexados em **Contexto do projeto** p - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (somente em workspaces totalmente novos) -- `MEMORY.md` quando presente, caso contrário `memory.md` como fallback em minúsculas +- `BOOTSTRAP.md` (apenas em workspaces totalmente novos) +- `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 toda rodada, a menos que -se aplique um bloqueio específico do arquivo. `HEARTBEAT.md` é omitido em execuções normais quando +Todos esses arquivos são **injetados na janela de contexto** em cada turno, a menos que +um bloqueio específico 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 compaction mais frequente. -> **Observação:** arquivos diários `memory/*.md` **não** fazem parte do Contexto do projeto -> normal do bootstrap. Em rodadas 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. Rodadas simples de `/new` e -> `/reset` são a exceção: o runtime pode antepor memória diária recente -> como um bloco único de contexto inicial para essa primeira rodada. +> **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`, então não contam contra a +> janela de contexto a menos que o modelo os leia explicitamente. Turnos simples `/new` e +> `/reset` são a exceção: o runtime pode prefixar 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 -entre arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars` -(padrão: 150000). Arquivos ausentes injetam um marcador curto de arquivo ausente. Quando ocorre truncamento, -o OpenClaw pode injetar um bloco de aviso em Contexto do projeto; controle isso com +`agents.defaults.bootstrapMaxChars` (padrão: 12000). O conteúdo total de bootstrap injetado +entre os arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars` +(padrão: 60000). Arquivos ausentes injetam um marcador curto de arquivo ausente. Quando ocorre +truncamento, o OpenClaw pode injetar um bloco de aviso em Contexto do projeto; controle isso com `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; padrão: `once`). -Sessões de subagentes injetam apenas `AGENTS.md` e `TOOLS.md` (outros arquivos de bootstrap +Sessões de subagente injetam apenas `AGENTS.md` e `TOOLS.md` (outros arquivos de bootstrap são filtrados para manter pequeno o contexto do subagente). -Hooks internos podem interceptar esta etapa por meio de `agent:bootstrap` para mutar ou substituir -os arquivos de bootstrap injetados (por exemplo, trocando `SOUL.md` por uma persona alternativa). +Hooks internos podem interceptar esta etapa via `agent:bootstrap` para mutar ou substituir +os arquivos de bootstrap injetados (por exemplo, trocar `SOUL.md` por uma persona alternativa). 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 da sobrecarga do schema da 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 de sistema inclui uma seção dedicada **Data e hora atuais** quando o -fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ela inclui apenas o -**fuso horário** (sem relógio dinâmico nem formato de hora). +O prompt do sistema inclui uma seção dedicada **Data e hora atuais** quando o +fuso horário do usuário é conhecido. Para manter o cache do prompt estável, ele agora 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 também pode opcionalmente definir uma substituição -de modelo por sessão (`model=default` a remove). +inclui uma linha de timestamp. A mesma ferramenta pode opcionalmente definir uma substituição de modelo por sessão +(`model=default` a limpa). Configure com: @@ -154,12 +154,12 @@ Veja [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento. ## Skills 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 +(`formatSkillsForPrompt`) que inclui o **caminho do arquivo** para cada skill. O prompt instrui o modelo a usar `read` para carregar o SKILL.md no local listado (workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a seção Skills é omitida. -A elegibilidade inclui bloqueios de metadados da skill, verificações de ambiente/configuração de runtime +A elegibilidade inclui bloqueios de metadados da skill, verificações de ambiente/configuração em runtime e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou `agents.list[].skills` está configurado. @@ -173,26 +173,26 @@ e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou ``` -Isso mantém o prompt base pequeno enquanto ainda permite uso direcionado de skills. +Isso mantém pequeno o prompt base e ainda possibilita uso direcionado de skills. O orçamento da lista de skills pertence ao subsistema de skills: - Padrão global: `skills.limits.maxSkillsPromptChars` -- Sobrescrita por agente: `agents.list[].skillsLimits.maxSkillsPromptChars` +- Substituição por agente: `agents.list[].skillsLimits.maxSkillsPromptChars` Trechos genéricos limitados de runtime usam uma superfície diferente: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Essa separação mantém o dimensionamento de skills separado do dimensionamento de leitura/injeção de runtime, como +Essa divisão mantém o dimensionamento de skills separado do dimensionamento de leitura/injeção do runtime, como `memory_get`, resultados de ferramentas ao vivo e atualizações de `AGENTS.md` após compaction. ## Documentação -Quando disponível, o prompt de 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 do -pacote npm empacotado) e também menciona o espelho público, o repositório de origem, o Discord da comunidade e o +Quando disponível, o prompt do sistema inclui uma seção **Documentação** que aponta para o +diretório local de 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-fonte, 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 -`openclaw status` por conta própria quando possível (pedindo ao usuário apenas quando não tiver acesso). +`openclaw status` por conta própria quando possível (perguntando ao usuário apenas quando não tiver acesso). diff --git a/docs/pt-BR/gateway/configuration-reference.md b/docs/pt-BR/gateway/configuration-reference.md index 8141c79c6..19244d4ef 100644 --- a/docs/pt-BR/gateway/configuration-reference.md +++ b/docs/pt-BR/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - Você precisa da semântica exata ou dos padrões de configuração em nível de campo + - Você precisa da semântica exata de configuração no nível de campo ou dos valores padrão - Você está validando blocos de configuração de canal, modelo, Gateway ou ferramenta -summary: Referência de configuração do Gateway para chaves principais do OpenClaw, padrões e links para referências dedicadas de subsistemas +summary: Referência de configuração do Gateway para chaves principais do OpenClaw, valores padrão e links para referências dedicadas de subsistemas title: Referência de configuração x-i18n: - generated_at: "2026-04-15T19:41:36Z" + generated_at: "2026-04-18T05:24:44Z" model: gpt-5.4 provider: openai - source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d + source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,54 +17,54 @@ x-i18n: Referência principal de configuração para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuration](/pt-BR/gateway/configuration). -Esta página cobre as principais superfícies de configuração do OpenClaw e aponta para outras referências quando um subsistema tem sua própria documentação mais aprofundada. Ela **não** tenta incorporar em uma única página todo catálogo de comandos pertencente a canal/Plugin nem todos os ajustes avançados de memória/QMD. +Esta página cobre as principais superfícies de configuração do OpenClaw e aponta para outras referências quando um subsistema tem sua própria documentação mais detalhada. Ela **não** tenta incluir em linha todos os catálogos de comandos pertencentes a canais/plugins nem todos os parâmetros profundos de memória/QMD em uma única página. Fonte de verdade do código: -- `openclaw config schema` imprime o JSON Schema em tempo real usado para validação e pela Control UI, com metadados agrupados de bundles/plugins/canais quando disponíveis -- `config.schema.lookup` retorna um nó do schema limitado a um caminho para ferramentas de exploração detalhada -- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash da linha de base da documentação de configuração em relação à superfície atual do schema +- `openclaw config schema` imprime o JSON Schema em tempo real usado para validação e para a Control UI, com metadados de plugins/canais/bundled mesclados quando disponíveis +- `config.schema.lookup` retorna um único nó do schema com escopo de caminho para ferramentas de exploração detalhada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash da baseline da documentação de configuração em relação à superfície atual do schema -Referências aprofundadas dedicadas: +Referências detalhadas dedicadas: -- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e a configuração de dreaming em `plugins.entries.memory-core.config.dreaming` -- [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos internos + agrupados -- páginas do canal/Plugin responsável para superfícies de comando específicas de canal +- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de Dreaming em `plugins.entries.memory-core.config.dreaming` +- [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos internos + bundled +- páginas do canal/plugin responsável para superfícies de comando específicas de canal -O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos. +O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa valores padrão seguros quando omitidos. --- ## Canais -Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). +Cada canal é iniciado automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). ### Acesso por DM e grupo Todos os canais oferecem suporte a políticas de DM e políticas de grupo: -| Política de DM | Comportamento | -| -------------------- | -------------------------------------------------------------- | -| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar | -| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permissões pareado) | -| `open` | Permitir todas as DMs recebidas (requer `allowFrom: ["*"]`) | -| `disabled` | Ignorar todas as DMs recebidas | +| Política de DM | Comportamento | +| ------------------- | -------------------------------------------------------------- | +| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar | +| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permissão pareado) | +| `open` | Permitir todas as DMs recebidas (requer `allowFrom: ["*"]`) | +| `disabled` | Ignorar todas as DMs recebidas | -| Política de grupo | Comportamento | -| ---------------------- | ----------------------------------------------------- | -| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada | -| `open` | Ignorar listas de permissão de grupo (o bloqueio por menção ainda se aplica) | -| `disabled` | Bloquear todas as mensagens de grupo/sala | +| Política de grupo | Comportamento | +| --------------------- | ------------------------------------------------------ | +| `allowlist` (padrão) | Apenas grupos que correspondem à allowlist configurada | +| `open` | Ignorar as allowlists de grupo (a exigência de menção ainda se aplica) | +| `disabled` | Bloquear todas as mensagens de grupo/sala | `channels.defaults.groupPolicy` define o padrão quando o `groupPolicy` de um provedor não está definido. -Os códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento por DM são limitadas a **3 por canal**. -Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução usa `allowlist` como padrão (fail-closed), com um aviso na inicialização. +Os códigos de pareamento expiram após 1 hora. As solicitações pendentes de pareamento por DM são limitadas a **3 por canal**. +Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução usa `allowlist` como fallback (fail-closed), com um aviso na inicialização. -### Substituições de modelo por canal +### Sobrescritas de modelo por canal -Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal se aplica quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`). +Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento por canal é aplicado quando uma sessão ainda não tem uma sobrescrita de modelo (por exemplo, definida via `/model`). ```json5 { @@ -87,7 +87,7 @@ Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. ### Padrões de canal e Heartbeat -Use `channels.defaults` para compartilhar comportamento de política de grupo e Heartbeat entre provedores: +Use `channels.defaults` para o comportamento compartilhado de política de grupo e Heartbeat entre provedores: ```json5 { @@ -105,15 +105,15 @@ Use `channels.defaults` para compartilhar comportamento de política de grupo e } ``` -- `channels.defaults.groupPolicy`: política de grupo de fallback quando o `groupPolicy` em nível de provedor não está definido. -- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto citado/em thread/no histórico), `allowlist` (inclui apenas contexto de remetentes permitidos), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: incluir status saudáveis de canal na saída do Heartbeat. -- `channels.defaults.heartbeat.showAlerts`: incluir status degradados/com erro na saída do Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderizar saída do Heartbeat compacta no estilo indicador. +- `channels.defaults.groupPolicy`: política de grupo de fallback quando um `groupPolicy` no nível do provedor não está definido. +- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto citado/thread/histórico), `allowlist` (inclui apenas contexto de remetentes na allowlist), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Sobrescrita por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: inclui status saudáveis de canais na saída do Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída do Heartbeat. +- `channels.defaults.heartbeat.useIndicator`: renderiza uma saída de Heartbeat compacta em estilo de indicador. ### WhatsApp -O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. +O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. ```json5 { @@ -124,7 +124,7 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // confirmações azuis (false no modo de conversa consigo mesmo) groups: { "*": { requireMention: true }, }, @@ -165,9 +165,9 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati ``` - Os comandos de saída usam por padrão a conta `default`, se presente; caso contrário, o primeiro ID de conta configurado (ordenado). -- `channels.whatsapp.defaultAccount` opcional substitui essa seleção padrão de conta quando corresponde a um ID de conta configurado. -- O diretório legado de autenticação Baileys de conta única é migrado por `openclaw doctor` para `whatsapp/default`. -- Substituições por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- `channels.whatsapp.defaultAccount` opcional sobrescreve essa seleção padrão de conta de fallback quando corresponde a um ID de conta configurado. +- O diretório legado de autenticação Baileys de conta única é migrado pelo `openclaw doctor` para `whatsapp/default`. +- Sobrescritas por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (padrão: off; ative explicitamente para evitar limites de taxa de edição de visualização) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,12 +225,12 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati } ``` -- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão. -- `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Em configurações com várias contas (2+ IDs de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento por fallback; `openclaw doctor` emite um aviso quando isso está ausente ou inválido. +- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks são rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão. +- `channels.telegram.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Em configurações com várias contas (2+ IDs de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento por fallback; `openclaw doctor` emite um aviso quando isso está ausente ou é inválido. - `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, `/config set|unset`). -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings persistentes de ACP para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). -- As prévias de stream do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo). +- Entradas `bindings[]` no nível superior com `type: "acp"` configuram associações ACP persistentes para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- As prévias de streaming no Telegram usam `sendMessage` + `editMessageText` (funciona em conversas diretas e em grupo). - Política de retry: consulte [Política de retry](/pt-BR/concepts/retry). ### Discord @@ -286,7 +286,7 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress corresponde a partial no Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in para sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,33 +334,33 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati ``` - Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão. -- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token na chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo em tempo de execução. -- `channels.discord.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Use `user:` (DM) ou `channel:` (canal de guild) para alvos de entrega; IDs numéricos sem prefixo são rejeitados. -- Slugs de guild são em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild. -- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bot que mencionem o bot (mensagens próprias ainda são filtradas). -- `channels.discord.guilds..ignoreOtherMentions` (e substituições no nível de canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here). +- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo do runtime. +- `channels.discord.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Use `user:` (DM) ou `channel:` (canal de guild) para destinos de entrega; IDs numéricos sem prefixo são rejeitados. +- Slugs de guild são em minúsculas com espaços substituídos por `-`; as chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild. +- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bots que mencionem o bot (as próprias mensagens ainda são filtradas). +- `channels.discord.guilds..ignoreOtherMentions` (e sobrescritas por canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here). - `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando têm menos de 2000 caracteres. - `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord: - - `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados) - - `idleHours`: substituição do Discord para desfoco automático por inatividade em horas (`0` desabilita) - - `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desabilita) - - `spawnSubagentSessions`: chave de ativação para criação/vinculação automática de thread em `sessions_spawn({ thread: true })` -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings persistentes de ACP para canais e threads (use o id do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). + - `enabled`: sobrescrita do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados) + - `idleHours`: sobrescrita do Discord para desfoco automático por inatividade em horas (`0` desabilita) + - `maxAgeHours`: sobrescrita do Discord para idade máxima rígida em horas (`0` desabilita) + - `spawnSubagentSessions`: chave de opt-in para criação/vinculação automática de thread em `sessions_spawn({ thread: true })` +- Entradas `bindings[]` no nível superior com `type: "acp"` configuram associações ACP persistentes para canais e threads (use o id do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres de componentes v2 do Discord. -- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + TTS. +- `channels.discord.voice` habilita conversas em canais de voz do Discord e sobrescritas opcionais de entrada automática + TTS. - `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` são repassados para as opções DAVE de `@discordjs/voice` (`true` e `24` por padrão). -- O OpenClaw também tenta recuperar o recebimento de voz saindo e entrando novamente em uma sessão de voz após falhas repetidas de descriptografia. -- `channels.discord.streaming` é a chave canônica do modo de stream. Os valores legados `streamMode` e booleanos `streaming` são migrados automaticamente. -- `channels.discord.autoPresence` mapeia a disponibilidade em tempo de execução para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status. +- O OpenClaw também tenta recuperar a recepção de voz saindo e reentrando em uma sessão de voz após falhas repetidas de descriptografia. +- `channels.discord.streaming` é a chave canônica do modo de streaming. Os valores legados `streamMode` e booleanos de `streaming` são migrados automaticamente. +- `channels.discord.autoPresence` mapeia a disponibilidade em runtime para a presença do bot (saudável => online, degradado => idle, esgotado => dnd) e permite sobrescritas opcionais de texto de status. - `channels.discord.dangerouslyAllowNameMatching` reabilita a correspondência por nome/tag mutável (modo de compatibilidade break-glass). -- `channels.discord.execApprovals`: entrega de aprovação de exec nativa do Discord e autorização de aprovadores. - - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. +- `channels.discord.execApprovals`: entrega nativa de aprovações de exec no Discord e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. - `approvers`: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido. - - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. + - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações de todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs dos aprovadores, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o alvo inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos. - - `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, recusa ou timeout. + - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão) envia para as DMs do aprovador, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos. + - `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, negação ou timeout. **Modos de notificação de reação:** `off` (nenhum), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds..users` em todas as mensagens). @@ -393,11 +393,11 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati } ``` -- JSON da conta de serviço: embutido (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). +- JSON da conta de serviço: em linha (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). - SecretRef para conta de serviço também é compatível (`serviceAccountRef`). - Fallbacks de ambiente: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Use `spaces/` ou `users/` para alvos de entrega. -- `channels.googlechat.dangerouslyAllowNameMatching` reabilita a correspondência mutável de principal de e-mail (modo de compatibilidade break-glass). +- Use `spaces/` ou `users/` para destinos de entrega. +- `channels.googlechat.dangerouslyAllowNameMatching` reabilita a correspondência por principal de email mutável (modo de compatibilidade break-glass). ### Slack @@ -449,7 +449,7 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // use Slack native streaming API when mode=partial + nativeTransport: true, // usa a API nativa de streaming do Slack quando mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -466,37 +466,32 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati - **Modo socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como fallback de ambiente da conta padrão). - **Modo HTTP** requer `botToken` mais `signingSecret` (na raiz ou por conta). -- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings - em texto simples ou objetos SecretRef. -- Snapshots de conta do Slack expõem campos por credencial de origem/status, como - `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, - `signingSecretStatus`. `configured_unavailable` significa que a conta está - configurada por SecretRef, mas o caminho atual de comando/runtime não pôde - resolver o valor do segredo. +- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples ou objetos SecretRef. +- Snapshots de conta do Slack expõem campos por credencial de origem/status, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que a conta está configurada via SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo. - `configWrites: false` bloqueia gravações de configuração iniciadas pelo Slack. -- `channels.slack.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Os valores legados `streamMode`, booleanos `streaming` e `nativeStreaming` são migrados automaticamente. -- Use `user:` (DM) ou `channel:` para alvos de entrega. +- `channels.slack.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.slack.streaming.mode` é a chave canônica do modo de streaming do Slack. `channels.slack.streaming.nativeTransport` controla o transporte nativo de streaming do Slack. Os valores legados `streamMode`, booleanos de `streaming` e `nativeStreaming` são migrados automaticamente. +- Use `user:` (DM) ou `channel:` para destinos de entrega. **Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`). -**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado pelo canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads. +**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado no canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads. -- O streaming nativo do Slack mais o status de thread no estilo “is typing...” do assistente do Slack exigem um alvo de resposta em thread. DMs de nível superior permanecem fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da prévia no estilo thread. -- `typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto uma resposta está em execução, e a remove ao concluir. Use um shortcode de emoji do Slack como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo schema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`). +- Streaming nativo do Slack, junto com o status em thread no estilo “is typing...” do assistente do Slack, requer um destino de resposta em thread. DMs de nível superior permanecem fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da prévia em estilo thread. +- `typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto uma resposta está em execução e depois a remove na conclusão. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega nativa de aprovações de exec no Slack e autorização de aprovadores. Mesmo schema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`). -| Grupo de ações | Padrão | Observações | -| -------------- | -------- | ----------------------- | -| reactions | enabled | Reagir + listar reações | -| messages | enabled | Ler/enviar/editar/excluir | -| pins | enabled | Fixar/desafixar/listar | -| memberInfo | enabled | Informações do membro | -| emojiList | enabled | Lista de emojis personalizados | +| Grupo de ação | Padrão | Observações | +| ------------- | ------- | ---------------------- | +| reactions | enabled | Reagir + listar reações | +| messages | enabled | Ler/enviar/editar/excluir | +| pins | enabled | Fixar/desafixar/listar | +| memberInfo | enabled | Informações do membro | +| emojiList | enabled | Lista de emojis personalizados | ### Mattermost -O Mattermost é distribuído como um Plugin: `openclaw plugins install @openclaw/mattermost`. +O Mattermost é distribuído como Plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -516,7 +511,7 @@ O Mattermost é distribuído como um Plugin: `openclaw plugins install @openclaw native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // URL explícita opcional para implantações com proxy reverso/públicas callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +521,18 @@ O Mattermost é distribuído como um Plugin: `openclaw plugins install @openclaw } ``` -Modos de chat: `oncall` (responde a menção com @, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com um prefixo de gatilho). +Modos de chat: `oncall` (responde em @-mention, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com prefixo de gatilho). Quando os comandos nativos do Mattermost estão habilitados: - `commands.callbackPath` deve ser um caminho (por exemplo `/api/channels/mattermost/command`), não uma URL completa. -- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e ser acessível a partir do servidor Mattermost. -- Callbacks nativos de slash são autenticados com os tokens por comando retornados - pelo Mattermost durante o registro do comando de barra. Se o registro falhar ou - nenhum comando for ativado, o OpenClaw rejeita callbacks com - `Unauthorized: invalid command token.` -- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que - `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio do callback. - Use valores de host/domínio, não URLs completas. +- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e deve ser acessível a partir do servidor Mattermost. +- Callbacks nativos de slash são autenticados com os tokens por comando retornados pelo Mattermost durante o registro do slash command. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeita callbacks com `Unauthorized: invalid command token.` +- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio de callback. Use valores de host/domínio, não URLs completas. - `channels.mattermost.configWrites`: permitir ou negar gravações de configuração iniciadas pelo Mattermost. - `channels.mattermost.requireMention`: exigir `@mention` antes de responder em canais. -- `channels.mattermost.groups..requireMention`: substituição de bloqueio por menção por canal (`"*"` para padrão). -- `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.mattermost.groups..requireMention`: sobrescrita por canal para exigência de menção (`"*"` como padrão). +- `channels.mattermost.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. ### Signal @@ -551,7 +541,7 @@ Quando os comandos nativos do Mattermost estão habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // vínculo de conta opcional dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -565,13 +555,13 @@ Quando os comandos nativos do Mattermost estão habilitados: **Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`). -- `channels.signal.account`: fixa a inicialização do canal em uma identidade específica de conta do Signal. +- `channels.signal.account`: fixa a inicialização do canal em uma identidade de conta específica do Signal. - `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal. -- `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.signal.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. ### BlueBubbles -BlueBubbles é o caminho recomendado para iMessage (com Plugin de suporte, configurado em `channels.bluebubbles`). +BlueBubbles é o caminho recomendado para iMessage (com suporte por Plugin, configurado em `channels.bluebubbles`). ```json5 { @@ -579,16 +569,16 @@ BlueBubbles é o caminho recomendado para iMessage (com Plugin de suporte, confi bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl, password, webhookPath, controles de grupo e ações avançadas: + // consulte /channels/bluebubbles }, }, } ``` -- Caminhos de chave principais cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões persistentes de ACP. Use um identificador ou string de destino do BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- Caminhos de chave principal cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Entradas `bindings[]` no nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador ou string de destino do BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). - A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles). ### iMessage @@ -617,15 +607,15 @@ O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é n } ``` -- `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.imessage.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. - Requer Full Disk Access ao banco de dados do Messages. -- Prefira alvos `chat_id:`. Use `imsg chats --limit 20` para listar chats. -- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos por SCP. +- Prefira destinos `chat_id:`. Use `imsg chats --limit 20` para listar chats. +- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos via SCP. - `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`). -- SCP usa verificação estrita de chave de host, então certifique-se de que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`. +- O SCP usa verificação estrita de chave de host, então garanta que a chave do host de relay já exista em `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: permite ou nega gravações de configuração iniciadas pelo iMessage. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões persistentes de ACP. Use um identificador normalizado ou alvo explícito de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- Entradas `bindings[]` no nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou um destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). @@ -638,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix tem suporte por extensão e é configurado em `channels.matrix`. +O Matrix tem suporte por extensão e é configurado em `channels.matrix`. ```json5 { @@ -670,23 +660,23 @@ Matrix tem suporte por extensão e é configurado em `channels.matrix`. - A autenticação por token usa `accessToken`; a autenticação por senha usa `userId` + `password`. - `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem sobrescrevê-lo com `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa ativação de rede são controles independentes. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e esse opt-in de rede são controles independentes. - `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas. -- `channels.matrix.autoJoin` usa `off` por padrão, então salas convidadas e novos convites no estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega de aprovação de exec nativa do Matrix e autorização de aprovadores. - - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers`: IDs de usuário do Matrix (por exemplo `@owner:example.org`) autorizados a aprovar solicitações de exec. - - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. +- `channels.matrix.autoJoin` tem como padrão `off`, então salas convidadas e convites novos no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega nativa de aprovações de exec no Matrix e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. + - `approvers`: IDs de usuário Matrix (por exemplo `@owner:example.org`) autorizados a aprovar solicitações de exec. + - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações de todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. - - Substituições por conta: `channels.matrix.accounts..execApprovals`. + - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. + - Sobrescritas por conta: `channels.matrix.accounts..execApprovals`. - `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha por peer roteado, enquanto `per-room` isola cada sala de DM. -- Sondas de status do Matrix e consultas ao diretório ativo usam a mesma política de proxy do tráfego em tempo de execução. -- A configuração completa do Matrix, regras de direcionamento e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix). +- Sondas de status do Matrix e pesquisas em diretório ao vivo usam a mesma política de proxy do tráfego em runtime. +- A configuração completa do Matrix, regras de destino e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix). ### Microsoft Teams -Microsoft Teams tem suporte por extensão e é configurado em `channels.msteams`. +O Microsoft Teams tem suporte por extensão e é configurado em `channels.msteams`. ```json5 { @@ -694,19 +684,19 @@ Microsoft Teams tem suporte por extensão e é configurado em `channels.msteams` msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, políticas de equipe/canal: + // consulte /channels/msteams }, }, } ``` -- Caminhos de chave principais cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. -- A configuração completa do Teams (credenciais, Webhook, política de DM/grupo, substituições por equipe/por canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams). +- Caminhos de chave principal cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. +- A configuração completa do Teams (credenciais, webhook, política de DM/grupo, sobrescritas por equipe/canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams). ### IRC -IRC tem suporte por extensão e é configurado em `channels.irc`. +O IRC tem suporte por extensão e é configurado em `channels.irc`. ```json5 { @@ -727,9 +717,9 @@ IRC tem suporte por extensão e é configurado em `channels.irc`. } ``` -- Caminhos de chave principais cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissão/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc). +- Caminhos de chave principal cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/exigência de menção) está documentada em [IRC](/pt-BR/channels/irc). ### Várias contas (todos os canais) @@ -741,11 +731,11 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): telegram: { accounts: { default: { - name: "Primary bot", + name: "Bot principal", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "Bot de alertas", botToken: "987654:XYZ...", }, }, @@ -756,26 +746,26 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): - `default` é usado quando `accountId` é omitido (CLI + roteamento). - Tokens de ambiente se aplicam apenas à conta **default**. -- Configurações base do canal se aplicam a todas as contas, a menos que sejam substituídas por conta. +- As configurações base do canal se aplicam a todas as contas, a menos que sejam sobrescritas por conta. - Use `bindings[].match.accountId` para rotear cada conta para um agente diferente. -- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no nível superior, o OpenClaw primeiro promove os valores de conta única no nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels..accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente. -- Bindings existentes apenas de canal (sem `accountId`) continuam correspondendo à conta padrão; bindings com escopo de conta continuam opcionais. -- `openclaw doctor --fix` também corrige formatos mistos movendo valores de conta única no nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente. +- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no nível superior, o OpenClaw primeiro promove os valores de conta única no nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais move esses valores para `channels..accounts.default`; o Matrix pode preservar um destino nomeado/default correspondente já existente. +- Associações existentes apenas de canal (sem `accountId`) continuam correspondendo à conta padrão; associações com escopo de conta continuam opcionais. +- `openclaw doctor --fix` também corrige formatos mistos movendo valores de conta única no nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um destino nomeado/default correspondente já existente. ### Outros canais de extensão -Muitos canais de extensão são configurados como `channels.` e documentados em suas páginas dedicadas de canal (por exemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Muitos canais de extensão são configurados como `channels.` e documentados em suas páginas de canal dedicadas (por exemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). Consulte o índice completo de canais: [Channels](/pt-BR/channels). -### Bloqueio por menção em chat de grupo +### Exigência de menção em conversas em grupo -Mensagens de grupo, por padrão, **exigem menção** (menção nos metadados ou padrões regex seguros). Aplica-se a chats de grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. +As mensagens de grupo, por padrão, **exigem menção** (menção em metadados ou padrões regex seguros). Aplica-se a conversas em grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de menção:** -- **Menções de metadados**: menções nativas com @ da plataforma. Ignoradas no modo de conversa consigo mesmo do WhatsApp. +- **Menções em metadados**: @-mentions nativas da plataforma. Ignoradas no modo de conversa consigo mesmo do WhatsApp. - **Padrões de texto**: padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetições aninhadas inseguras são ignorados. -- O bloqueio por menção só é aplicado quando a detecção é possível (menções nativas ou pelo menos um padrão). +- A exigência de menção só é aplicada quando a detecção é possível (menções nativas ou pelo menos um padrão). ```json5 { @@ -805,13 +795,13 @@ Mensagens de grupo, por padrão, **exigem menção** (menção nos metadados ou } ``` -Resolução: substituição por DM → padrão do provedor → sem limite (tudo é mantido). +Resolução: sobrescrita por DM → padrão do provedor → sem limite (tudo retido). Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Modo de conversa consigo mesmo -Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa consigo mesmo (ignora menções nativas com @, responde apenas a padrões de texto): +Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa consigo mesmo (ignora @-mentions nativas, responde apenas a padrões de texto): ```json5 { @@ -832,21 +822,21 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con } ``` -### Comandos (tratamento de comandos no chat) +### Comandos (tratamento de comandos de chat) ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // registra comandos nativos quando compatível + nativeSkills: "auto", // registra comandos nativos de Skills quando compatível + text: true, // analisa /commands em mensagens de chat + bash: false, // permite ! (alias: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // permite /config + mcp: false, // permite /mcp + plugins: false, // permite /plugins + debug: false, // permite /debug + restart: true, // permite /restart + ferramenta de reinicialização do gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,27 +851,27 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con -- Este bloco configura as superfícies de comando. Para o catálogo atual de comandos internos + agrupados, consulte [Slash Commands](/pt-BR/tools/slash-commands). -- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/Plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice`, estão documentados em suas páginas de canal/Plugin e em [Slash Commands](/pt-BR/tools/slash-commands). +- Este bloco configura superfícies de comando. Para o catálogo atual de comandos internos + bundled, consulte [Slash Commands](/pt-BR/tools/slash-commands). +- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice`, estão documentados em suas páginas de canal/plugin e também em [Slash Commands](/pt-BR/tools/slash-commands). - Comandos de texto devem ser mensagens **independentes** com `/` no início. -- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém Slack desativado. -- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém Slack desativado. -- Substituição por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. -- Substitua o registro nativo de Skills por canal com `channels..commands.nativeSkills`. +- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém o Slack desativado. +- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém o Slack desativado. +- Sobrescrita por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. +- Sobrescreva o registro nativo de Skills por canal com `channels..commands.nativeSkills`. - `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram. - `bash: true` habilita `! ` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes de gateway `chat.send`, gravações persistentes com `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes normais de operador com escopo de gravação. -- `mcp: true` habilita `/mcp` para configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. -- `plugins: true` habilita `/plugins` para descoberta de Plugin, instalação e controles de ativação/desativação. +- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do Gateway, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes operadores normais com escopo de gravação. +- `mcp: true` habilita `/mcp` para a configuração de servidores MCP gerenciados pelo OpenClaw em `mcp.servers`. +- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de habilitar/desabilitar plugins. - `channels..configWrites` controla mutações de configuração por canal (padrão: true). -- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações que têm essa conta como alvo (por exemplo `/allowlist --config --account ` ou `/config set channels..accounts....`). -- `restart: false` desabilita `/restart` e ações da ferramenta de reinício do gateway. Padrão: `true`. -- `ownerAllowFrom` é a allowlist explícita de proprietários para comandos/ferramentas exclusivos do proprietário. É separada de `allowFrom`. +- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações direcionadas àquela conta (por exemplo `/allowlist --config --account ` ou `/config set channels..accounts....`). +- `restart: false` desabilita `/restart` e ações da ferramenta de reinicialização do Gateway. Padrão: `true`. +- `ownerAllowFrom` é a allowlist explícita de proprietários para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`. - `ownerDisplay: "hash"` aplica hash aos IDs do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing. -- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (as allowlists/pareamento do canal e `useAccessGroups` são ignorados). -- `useAccessGroups: false` permite que comandos ignorem políticas de grupo de acesso quando `allowFrom` não está definido. +- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (allowlists/pareamento de canal e `useAccessGroups` são ignorados). +- `useAccessGroups: false` permite que os comandos ignorem políticas de grupos de acesso quando `allowFrom` não está definido. - Mapa da documentação de comandos: - - catálogo interno + agrupado: [Slash Commands](/pt-BR/tools/slash-commands) + - catálogo interno + bundled: [Slash Commands](/pt-BR/tools/slash-commands) - superfícies de comando específicas de canal: [Channels](/pt-BR/channels) - comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot) - comandos de pareamento: [Pairing](/pt-BR/channels/pairing) @@ -906,7 +896,7 @@ Padrão: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente caminhando para cima a partir do workspace. +Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente subindo a partir do workspace. ```json5 { @@ -924,9 +914,9 @@ Allowlist padrão opcional de Skills para agentes que não definem agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // herda github, weather + { id: "docs", skills: ["docs-search"] }, // substitui os padrões + { id: "locked-down", skills: [] }, // sem Skills ], }, } @@ -935,8 +925,7 @@ Allowlist padrão opcional de Skills para agentes que não definem - Omita `agents.defaults.skills` para Skills irrestritas por padrão. - Omita `agents.list[].skills` para herdar os padrões. - Defina `agents.list[].skills: []` para nenhuma Skill. -- Uma lista não vazia em `agents.list[].skills` é o conjunto final desse agente; ela - não é mesclada com os padrões. +- Uma lista não vazia em `agents.list[].skills` é o conjunto final para aquele agente; ela não é mesclada com os padrões. ### `agents.defaults.skipBootstrap` @@ -950,9 +939,9 @@ Desabilita a criação automática de arquivos bootstrap do workspace (`AGENTS.m ### `agents.defaults.contextInjection` -Controla quando arquivos bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. +Controla quando os arquivos bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. -- `"continuation-skip"`: turnos seguros de continuação (após uma resposta concluída do assistente) ignoram a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e tentativas após Compaction ainda recriam o contexto. +- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e retries após Compaction ainda recompõem o contexto. ```json5 { @@ -962,21 +951,21 @@ Controla quando arquivos bootstrap do workspace são injetados no prompt do sist ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por arquivo bootstrap do workspace antes de truncamento. Padrão: `20000`. +Máximo de caracteres por arquivo bootstrap do workspace antes de truncamento. Padrão: `12000`. ```json5 { - agents: { defaults: { bootstrapMaxChars: 20000 } }, + agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` -Máximo total de caracteres injetados em todos os arquivos bootstrap do workspace. Padrão: `150000`. +Máximo total de caracteres injetados em todos os arquivos bootstrap do workspace. Padrão: `60000`. ```json5 { - agents: { defaults: { bootstrapTotalMaxChars: 150000 } }, + agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` @@ -998,23 +987,23 @@ Padrão: `"once"`. ### Mapa de propriedade do orçamento de contexto O OpenClaw tem vários orçamentos de prompt/contexto de alto volume, e eles são -intencionalmente divididos por subsistema em vez de todos passarem por um único -ajuste genérico. +intencionalmente divididos por subsistema em vez de passarem todos por um único +parâmetro genérico. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: injeção normal de bootstrap do workspace. - `agents.defaults.startupContext.*`: - prelúdio de inicialização de uso único em `/new` e `/reset`, incluindo arquivos - recentes `memory/*.md` diários. + prelúdio inicial de uso único para `/new` e `/reset`, incluindo arquivos + recentes `memory/*.md` do dia. - `skills.limits.*`: a lista compacta de Skills injetada no prompt do sistema. - `agents.defaults.contextLimits.*`: - trechos limitados em tempo de execução e blocos injetados pertencentes ao runtime. + trechos limitados em runtime e blocos injetados pertencentes ao runtime. - `memory.qmd.limits.*`: - indexação de trechos de pesquisa de memória e dimensionamento de injeção. + dimensionamento de trechos e injeções de busca de memória indexada. -Use a substituição correspondente por agente apenas quando um agente precisar de +Use a sobrescrita correspondente por agente apenas quando um agente precisar de um orçamento diferente: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1022,8 +1011,7 @@ um orçamento diferente: #### `agents.defaults.startupContext` -Controla o prelúdio de inicialização do primeiro turno injetado em execuções -simples de `/new` e `/reset`. +Controla o prelúdio inicial de primeira interação injetado em execuções simples de `/new` e `/reset`. ```json5 { @@ -1044,7 +1032,7 @@ simples de `/new` e `/reset`. #### `agents.defaults.contextLimits` -Padrões compartilhados para superfícies de contexto limitadas em tempo de execução. +Padrões compartilhados para superfícies de contexto limitadas em runtime. ```json5 { @@ -1061,19 +1049,14 @@ Padrões compartilhados para superfícies de contexto limitadas em tempo de exec } ``` -- `memoryGetMaxChars`: limite padrão de trecho de `memory_get` antes que metadados - de truncamento e aviso de continuação sejam adicionados. -- `memoryGetDefaultLines`: janela padrão de linhas de `memory_get` quando `lines` é - omitido. -- `toolResultMaxChars`: limite de resultado de ferramenta em tempo real usado para - resultados persistidos e recuperação de overflow. -- `postCompactionMaxChars`: limite de trecho de `AGENTS.md` usado durante injeção - de atualização pós-Compaction. +- `memoryGetMaxChars`: limite padrão de trecho de `memory_get` antes que metadados de truncamento e aviso de continuação sejam adicionados. +- `memoryGetDefaultLines`: janela padrão de linhas de `memory_get` quando `lines` é omitido. +- `toolResultMaxChars`: limite em tempo real do resultado de ferramenta usado para resultados persistidos e recuperação de overflow. +- `postCompactionMaxChars`: limite de trecho de AGENTS.md usado durante a injeção de atualização após Compaction. #### `agents.list[].contextLimits` -Substituição por agente para os ajustes compartilhados de `contextLimits`. Campos omitidos herdam -de `agents.defaults.contextLimits`. +Sobrescrita por agente para os parâmetros compartilhados de `contextLimits`. Campos omitidos herdam de `agents.defaults.contextLimits`. ```json5 { @@ -1114,7 +1097,7 @@ não afeta a leitura de arquivos `SKILL.md` sob demanda. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Substituição por agente para o orçamento de prompt de Skills. +Sobrescrita por agente para o orçamento de prompt de Skills. ```json5 { @@ -1133,10 +1116,10 @@ Substituição por agente para o orçamento de prompt de Skills. ### `agents.defaults.imageMaxDimensionPx` -Tamanho máximo em pixels do maior lado da imagem em blocos de imagem de transcrição/ferramenta antes de chamadas ao provedor. +Tamanho máximo em pixels do lado mais longo da imagem em blocos de imagem de transcrição/ferramenta antes de chamadas ao provedor. Padrão: `1200`. -Valores menores normalmente reduzem o uso de tokens de visão e o tamanho da carga da requisição em execuções com muitas capturas de tela. +Valores menores geralmente reduzem o uso de tokens de visão e o tamanho do payload da requisição em execuções com muitas capturas de tela. Valores maiores preservam mais detalhes visuais. ```json5 @@ -1147,7 +1130,7 @@ Valores maiores preservam mais detalhes visuais. ### `agents.defaults.userTimezone` -Fuso horário para o contexto do prompt do sistema (não para timestamps de mensagens). Usa como fallback o fuso horário do host. +Fuso horário para o contexto do prompt do sistema (não para timestamps de mensagens). Usa o fuso horário do host como fallback. ```json5 { @@ -1195,9 +1178,9 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // parâmetros globais padrão do provedor embeddedHarness: { - runtime: "auto", // auto | pi | registered harness id, e.g. codex + runtime: "auto", // auto | pi | id registrado do harness, por exemplo codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1215,48 +1198,48 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). ``` - `model`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - A forma string define apenas o modelo principal. - - A forma objeto define o principal mais modelos de failover ordenados. + - A forma de string define apenas o modelo principal. + - A forma de objeto define o principal mais modelos ordenados de failover. - `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pelo caminho da ferramenta `image` como configuração de modelo de visão. + - Usado pelo caminho da ferramenta `image` como sua configuração de modelo de visão. - Também usado como roteamento de fallback quando o modelo selecionado/padrão não pode aceitar entrada de imagem. - `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de imagem e por qualquer futura superfície de ferramenta/Plugin que gere imagens. - - Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagem do Gemini, `fal/fal-ai/flux/dev` para fal, ou `openai/gpt-image-1` para OpenAI Images. - - Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor (por exemplo `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). - - Se omitido, `image_generate` ainda pode inferir um provedor padrão com autenticação configurada. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de imagem registrados, na ordem do ID do provedor. + - Usado pela capacidade compartilhada de geração de imagens e por qualquer futura superfície de ferramenta/plugin que gere imagens. + - Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagens do Gemini, `fal/fal-ai/flux/dev` para fal, ou `openai/gpt-image-1` para OpenAI Images. + - Se você selecionar um provider/model diretamente, configure também a autenticação/chave de API correspondente do provedor (por exemplo `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). + - Se omitido, `image_generate` ainda pode inferir um provedor padrão com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de imagem em ordem de ID do provedor. - `musicGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - Usado pela capacidade compartilhada de geração de música e pela ferramenta interna `music_generate`. - Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.5+`. - - Se omitido, `music_generate` ainda pode inferir um provedor padrão com autenticação configurada. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de música registrados, na ordem do ID do provedor. - - Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor. + - Se omitido, `music_generate` ainda pode inferir um provedor padrão com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de música em ordem de ID do provedor. + - Se você selecionar um provider/model diretamente, configure também a autenticação/chave de API correspondente do provedor. - `videoGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta interna `video_generate`. - Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`. - - Se omitido, `video_generate` ainda pode inferir um provedor padrão com autenticação configurada. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de vídeo registrados, na ordem do ID do provedor. - - Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor. - - O provedor agrupado de geração de vídeo Qwen oferece suporte a no máximo 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções em nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. + - Se omitido, `video_generate` ainda pode inferir um provedor padrão com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de vídeo em ordem de ID do provedor. + - Se você selecionar um provider/model diretamente, configure também a autenticação/chave de API correspondente do provedor. + - O provedor bundled de geração de vídeo Qwen oferece suporte a no máximo 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções no nível do provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. - `pdfModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - Usado pela ferramenta `pdf` para roteamento de modelo. - - Se omitido, a ferramenta PDF usa `imageModel` como fallback e, depois, o modelo resolvido da sessão/padrão. + - Se omitido, a ferramenta PDF usa `imageModel` como fallback e depois o modelo resolvido da sessão/padrão. - `pdfMaxBytesMb`: limite padrão de tamanho de PDF para a ferramenta `pdf` quando `maxBytesMb` não é passado no momento da chamada. - `pdfMaxPages`: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`. -- `verboseDefault`: nível verbose padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. +- `verboseDefault`: nível detalhado padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. - `elevatedDefault`: nível padrão de saída elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Padrão: `"on"`. -- `model.primary`: formato `provider/model` (por exemplo `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID exato de modelo e só então usa o provedor padrão configurado como fallback (comportamento de compatibilidade obsoleto, então prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw usa o primeiro provedor/modelo configurado como fallback em vez de expor um padrão obsoleto de provedor removido. +- `model.primary`: formato `provider/model` (ex.: `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para aquele ID exato de modelo e só então usa o provedor padrão configurado como fallback (comportamento legado de compatibilidade, portanto prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw usa como fallback o primeiro provider/model configurado em vez de expor um padrão obsoleto de provedor removido. - `models`: o catálogo de modelos configurado e a allowlist para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Defina em `agents.defaults.params` (por exemplo `{ cacheRetention: "long" }`). +- `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Definidos em `agents.defaults.params` (ex.: `{ cacheRetention: "long" }`). - Precedência de mesclagem de `params` (config): `agents.defaults.params` (base global) é sobrescrito por `agents.defaults.models["provider/model"].params` (por modelo), depois `agents.list[].params` (ID de agente correspondente) sobrescreve por chave. Consulte [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. -- `embeddedHarness`: política padrão de runtime de agente embutido de baixo nível. Use `runtime: "auto"` para permitir que harnesses de Plugin registrados assumam modelos compatíveis, `runtime: "pi"` para forçar o harness PI interno, ou um ID de harness registrado, como `runtime: "codex"`. Defina `fallback: "none"` para desabilitar o fallback automático para PI. -- Gravadores de configuração que alteram esses campos (por exemplo `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível. +- `embeddedHarness`: política padrão de runtime de agente incorporado de baixo nível. Use `runtime: "auto"` para permitir que harnesses de plugins registrados reivindiquem modelos compatíveis, `runtime: "pi"` para forçar o harness PI interno ou um ID de harness registrado, como `runtime: "codex"`. Defina `fallback: "none"` para desabilitar o fallback automático para PI. +- Gravadores de configuração que alteram esses campos (por exemplo `/models set`, `/models set-image` e comandos add/remove de fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível. - `maxConcurrent`: máximo de execuções paralelas de agentes entre sessões (cada sessão ainda é serializada). Padrão: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` controla qual executor de baixo nível executa turnos de agentes embutidos. +`embeddedHarness` controla qual executor de baixo nível executa interações de agentes incorporados. A maioria das implantações deve manter o padrão `{ runtime: "auto", fallback: "pi" }`. -Use-o quando um Plugin confiável fornecer um harness nativo, como o harness -agrupado do servidor de app Codex. +Use-o quando um plugin confiável fornecer um harness nativo, como o harness bundled +do servidor de aplicativos Codex. ```json5 { @@ -1272,11 +1255,11 @@ agrupado do servidor de app Codex. } ``` -- `runtime`: `"auto"`, `"pi"` ou um ID de harness de Plugin registrado. O Plugin agrupado Codex registra `codex`. -- `fallback`: `"pi"` ou `"none"`. `"pi"` mantém o harness PI interno como fallback de compatibilidade. `"none"` faz com que a seleção ausente ou incompatível de harness de Plugin falhe em vez de usar PI silenciosamente. -- Substituições por ambiente: `OPENCLAW_AGENT_RUNTIME=` sobrescreve `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desabilita o fallback para PI nesse processo. +- `runtime`: `"auto"`, `"pi"` ou um ID de harness de plugin registrado. O plugin bundled Codex registra `codex`. +- `fallback`: `"pi"` ou `"none"`. `"pi"` mantém o harness PI interno como fallback de compatibilidade. `"none"` faz com que a seleção de harness de plugin ausente ou incompatível falhe em vez de usar PI silenciosamente. +- Sobrescritas por ambiente: `OPENCLAW_AGENT_RUNTIME=` sobrescreve `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desabilita o fallback para PI nesse processo. - Para implantações somente com Codex, defina `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. -- Isso controla apenas o harness de chat embutido. Geração de mídia, visão, PDF, música, vídeo e TTS continuam usando suas configurações de provedor/modelo. +- Isso controla apenas o harness de chat incorporado. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provider/model. **Atalhos de alias internos** (aplicam-se apenas quando o modelo está em `agents.defaults.models`): @@ -1291,15 +1274,15 @@ agrupado do servidor de app Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Seus aliases configurados sempre têm prioridade sobre os padrões. +Seus aliases configurados sempre prevalecem sobre os padrões. -Modelos Z.AI GLM-4.x habilitam automaticamente o modo thinking, a menos que você defina `--thinking off` ou configure `agents.defaults.models["zai/"].params.thinking` manualmente. -Modelos Z.AI habilitam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desabilitá-lo. -Modelos Anthropic Claude 4.6 usam `adaptive` como padrão para thinking quando nenhum nível explícito de thinking é definido. +Os modelos Z.AI GLM-4.x ativam automaticamente o modo thinking, a menos que você defina `--thinking off` ou configure `agents.defaults.models["zai/"].params.thinking` manualmente. +Os modelos Z.AI ativam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desabilitá-lo. +Os modelos Anthropic Claude 4.6 usam por padrão thinking `adaptive` quando nenhum nível explícito de thinking é definido. ### `agents.defaults.cliBackends` -Backends opcionais de CLI para execuções de fallback somente texto (sem chamadas de ferramenta). Úteis como backup quando provedores de API falham. +Backends CLI opcionais para execuções de fallback somente texto (sem chamadas de ferramenta). Útil como backup quando provedores de API falham. ```json5 { @@ -1327,13 +1310,13 @@ Backends opcionais de CLI para execuções de fallback somente texto (sem chamad } ``` -- Backends de CLI são voltados a texto; ferramentas são sempre desabilitadas. +- Backends CLI são voltados primeiro para texto; ferramentas são sempre desabilitadas. - Sessões são compatíveis quando `sessionArg` está definido. -- Repasse de imagem é compatível quando `imageArg` aceita caminhos de arquivo. +- Passagem de imagens é compatível quando `imageArg` aceita caminhos de arquivo. ### `agents.defaults.systemPromptOverride` -Substitui todo o prompt do sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou apenas com espaços em branco é ignorado. Útil para experimentos controlados de prompt. +Substitui todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou apenas com espaços é ignorado. Útil para experimentos controlados de prompt. ```json5 { @@ -1354,17 +1337,17 @@ Execuções periódicas de Heartbeat. agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m desabilita model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // padrão: true; false omite a seção Heartbeat do prompt do sistema + lightContext: false, // padrão: false; true mantém apenas HEARTBEAT.md dos arquivos bootstrap do workspace + isolatedSession: false, // padrão: false; true executa cada Heartbeat em uma sessão nova (sem histórico de conversa) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + directPolicy: "allow", // allow (padrão) | block + target: "none", // padrão: none | opções: last | whatsapp | telegram | discord | ... + prompt: "Leia HEARTBEAT.md se ele existir...", ackMaxChars: 300, suppressToolErrorWarnings: false, timeoutSeconds: 45, @@ -1375,14 +1358,14 @@ Execuções periódicas de Heartbeat. ``` - `every`: string de duração (ms/s/m/h). Padrão: `30m` (autenticação por chave de API) ou `1h` (autenticação OAuth). Defina `0m` para desabilitar. -- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt do sistema e ignora a injeção de `HEARTBEAT.md` no contexto bootstrap. Padrão: `true`. -- `suppressToolErrorWarnings`: quando true, suprime cargas de aviso de erro de ferramenta durante execuções de Heartbeat. -- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes de ser abortado. Deixe sem definir para usar `agents.defaults.timeoutSeconds`. -- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega com alvo direto. `block` suprime entrega com alvo direto e emite `reason=dm-blocked`. -- `lightContext`: quando true, execuções de Heartbeat usam contexto bootstrap leve e mantêm apenas `HEARTBEAT.md` entre os arquivos bootstrap do workspace. +- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt do sistema e pula a injeção de `HEARTBEAT.md` no contexto bootstrap. Padrão: `true`. +- `suppressToolErrorWarnings`: quando true, suprime payloads de aviso de erro de ferramenta durante execuções de Heartbeat. +- `timeoutSeconds`: tempo máximo em segundos permitido para uma interação de agente de Heartbeat antes de ela ser abortada. Deixe sem definir para usar `agents.defaults.timeoutSeconds`. +- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para destino direto. `block` suprime entrega para destino direto e emite `reason=dm-blocked`. +- `lightContext`: quando true, execuções de Heartbeat usam contexto bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos bootstrap do workspace. - `isolatedSession`: quando true, cada Heartbeat é executado em uma sessão nova, sem histórico anterior de conversa. Mesmo padrão de isolamento de Cron `sessionTarget: "isolated"`. Reduz o custo de tokens por Heartbeat de ~100K para ~2-5K tokens. -- Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **apenas esses agentes** executam Heartbeat. -- Heartbeats executam turnos completos de agente — intervalos menores consomem mais tokens. +- Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **somente esses agentes** executam Heartbeats. +- Heartbeats executam interações completas de agente — intervalos menores consomem mais tokens. ### `agents.defaults.compaction` @@ -1392,19 +1375,19 @@ Execuções periódicas de Heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // id de um Plugin provedor de Compaction registrado (opcional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Preserve exatamente IDs de implantação, IDs de tickets e pares host:porta.", // usado quando identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] desabilita reinjeção + model: "openrouter/anthropic/claude-sonnet-4-6", // sobrescrita opcional de modelo apenas para Compaction + notifyUser: true, // envia um aviso breve quando a Compaction começa (padrão: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Sessão próxima de Compaction. Armazene memórias duráveis agora.", + prompt: "Escreva quaisquer notas duradouras em memory/YYYY-MM-DD.md; responda com o token silencioso exato NO_REPLY se não houver nada para armazenar.", }, }, }, @@ -1413,18 +1396,18 @@ Execuções periódicas de Heartbeat. ``` - `mode`: `default` ou `safeguard` (sumarização em blocos para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction). -- `provider`: id de um Plugin de provedor de Compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização interna por LLM. Em caso de falha, usa o interno como fallback. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction). -- `timeoutSeconds`: máximo de segundos permitidos para uma única operação de Compaction antes de o OpenClaw abortá-la. Padrão: `900`. +- `provider`: id de um Plugin provedor de Compaction registrado. Quando definido, `summarize()` do provedor é chamado em vez da sumarização LLM interna. Em caso de falha, usa a implementação interna como fallback. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction). +- `timeoutSeconds`: máximo de segundos permitidos para uma única operação de Compaction antes que o OpenClaw a aborte. Padrão: `900`. - `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` adiciona orientação interna de retenção de identificadores opacos durante a sumarização de Compaction. - `identifierInstructions`: texto opcional personalizado de preservação de identificadores usado quando `identifierPolicy=custom`. -- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após a Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desabilitar a reinjeção. Quando não definido ou explicitamente definido para esse par padrão, os títulos antigos `Every Session`/`Safety` também são aceitos como fallback legado. -- `model`: substituição opcional `provider/model-id` apenas para sumarização de Compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem usar outro; quando não definido, a Compaction usa o modelo principal da sessão. -- `notifyUser`: quando `true`, envia um aviso breve ao usuário quando a Compaction começa (por exemplo, "Compacting context..."). Desabilitado por padrão para manter a Compaction silenciosa. +- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após a Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desabilitar a reinjeção. Quando não definido ou explicitamente definido com esse par padrão, os cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado. +- `model`: sobrescrita opcional `provider/model-id` apenas para sumarização de Compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem executar em outro; quando não definido, a Compaction usa o modelo principal da sessão. +- `notifyUser`: quando `true`, envia um aviso breve ao usuário quando a Compaction começa (por exemplo, "Compactando contexto..."). Desabilitado por padrão para manter a Compaction silenciosa. - `memoryFlush`: turno agentivo silencioso antes da Compaction automática para armazenar memórias duráveis. Ignorado quando o workspace é somente leitura. ### `agents.defaults.contextPruning` -Remove **resultados antigos de ferramentas** do contexto em memória antes do envio ao LLM. **Não** modifica o histórico da sessão em disco. +Remove **resultados antigos de ferramentas** do contexto em memória antes de enviar para o LLM. **Não** modifica o histórico da sessão em disco. ```json5 { @@ -1432,13 +1415,13 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes do en defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // duração (ms/s/m/h), unidade padrão: minutos keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Conteúdo antigo de resultado de ferramenta removido]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1448,25 +1431,25 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes do en -- `mode: "cache-ttl"` habilita passagens de remoção. -- `ttl` controla com que frequência a remoção pode ser executada novamente (após o último toque de cache). -- A remoção primeiro faz truncamento leve de resultados de ferramenta superdimensionados, depois limpa integralmente resultados de ferramenta mais antigos, se necessário. +- `mode: "cache-ttl"` habilita passagens de poda. +- `ttl` controla com que frequência a poda pode ser executada novamente (após o último toque no cache). +- A poda primeiro faz soft-trim de resultados de ferramentas superdimensionados e depois faz hard-clear de resultados mais antigos, se necessário. -**Truncamento leve** mantém o começo + fim e insere `...` no meio. +**Soft-trim** mantém o início + o fim e insere `...` no meio. -**Limpeza integral** substitui todo o resultado da ferramenta pelo placeholder. +**Hard-clear** substitui todo o resultado da ferramenta pelo placeholder. Observações: -- Blocos de imagem nunca são truncados/limpos. +- Blocos de imagem nunca são reduzidos/removidos. - As proporções são baseadas em caracteres (aproximadas), não em contagens exatas de tokens. -- Se existirem menos de `keepLastAssistants` mensagens do assistente, a remoção é ignorada. +- Se existirem menos de `keepLastAssistants` mensagens do assistente, a poda é ignorada. -Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes do comportamento. +Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de comportamento. -### Streaming em blocos +### Streaming em bloco ```json5 { @@ -1483,10 +1466,10 @@ Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes do com ``` - Canais que não sejam Telegram exigem `*.blockStreaming: true` explícito para habilitar respostas em bloco. -- Substituições por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam `minChars: 1500` por padrão. -- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`. +- Sobrescritas por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam por padrão `minChars: 1500`. +- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Sobrescrita por agente: `agents.list[].humanDelay`. -Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + fragmentação. +Consulte [Streaming](/pt-BR/concepts/streaming) para comportamento e detalhes de fragmentação. ### Indicadores de digitação @@ -1502,7 +1485,7 @@ Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + ``` - Padrões: `instant` para chats diretos/menções, `message` para chats em grupo sem menção. -- Substituições por sessão: `session.typingMode`, `session.typingIntervalSeconds`. +- Sobrescritas por sessão: `session.typingMode`, `session.typingIntervalSeconds`. Consulte [Typing Indicators](/pt-BR/concepts/typing-indicators). @@ -1510,7 +1493,7 @@ Consulte [Typing Indicators](/pt-BR/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandbox opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sandboxing) para o guia completo. +Sandbox opcional para o agente incorporado. Consulte [Sandboxing](/pt-BR/gateway/sandboxing) para o guia completo. ```json5 { @@ -1556,7 +1539,7 @@ Sandbox opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sa identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // SecretRefs / conteúdos inline também são compatíveis: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1610,7 +1593,7 @@ Sandbox opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sa **Backend:** - `docker`: runtime local do Docker (padrão) -- `ssh`: runtime remoto genérico com suporte via SSH +- `ssh`: runtime remoto genérico com suporte por SSH - `openshell`: runtime OpenShell Quando `backend: "openshell"` é selecionado, as configurações específicas de runtime passam para @@ -1618,33 +1601,33 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de **Configuração do backend SSH:** -- `target`: alvo SSH no formato `user@host[:port]` +- `target`: destino SSH no formato `user@host[:port]` - `command`: comando do cliente SSH (padrão: `ssh`) - `workspaceRoot`: raiz remota absoluta usada para workspaces por escopo - `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados ao OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: conteúdos embutidos ou SecretRefs que o OpenClaw materializa em arquivos temporários em tempo de execução -- `strictHostKeyChecking` / `updateHostKeys`: ajustes de política de chave de host do OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: conteúdos inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime +- `strictHostKeyChecking` / `updateHostKeys`: parâmetros de política de chave de host do OpenSSH **Precedência de autenticação SSH:** -- `identityData` tem prioridade sobre `identityFile` -- `certificateData` tem prioridade sobre `certificateFile` -- `knownHostsData` tem prioridade sobre `knownHostsFile` -- Valores `*Data` com suporte de SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão do sandbox +- `identityData` prevalece sobre `identityFile` +- `certificateData` prevalece sobre `certificateFile` +- `knownHostsData` prevalece sobre `knownHostsFile` +- Valores `*Data` com suporte por SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão sandbox **Comportamento do backend SSH:** -- semeia o workspace remoto uma vez após criação ou recriação +- semeia o workspace remoto uma vez após criar ou recriar - depois mantém o workspace SSH remoto como canônico -- roteia `exec`, ferramentas de arquivo e caminhos de mídia por SSH -- não sincroniza automaticamente alterações remotas de volta para o host -- não oferece suporte a contêineres de navegador do sandbox +- roteia `exec`, ferramentas de arquivo e caminhos de mídia via SSH +- não sincroniza automaticamente mudanças remotas de volta para o host +- não oferece suporte a contêineres de navegador sandbox **Acesso ao workspace:** -- `none`: workspace do sandbox por escopo em `~/.openclaw/sandboxes` -- `ro`: workspace do sandbox em `/workspace`, workspace do agente montado como somente leitura em `/agent` -- `rw`: workspace do agente montado com leitura/gravação em `/workspace` +- `none`: workspace sandbox por escopo em `~/.openclaw/sandboxes` +- `ro`: workspace sandbox em `/workspace`, workspace do agente montado como somente leitura em `/agent` +- `rw`: workspace do agente montado em `/workspace` com leitura/gravação **Escopo:** @@ -1665,10 +1648,10 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // opcional + gatewayEndpoint: "https://lab.example", // opcional + policy: "strict", // id de política OpenShell opcional + providers: ["openai"], // opcional autoProviders: true, timeoutSeconds: 120, }, @@ -1680,30 +1663,30 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de **Modo OpenShell:** -- `mirror`: semeia o remoto a partir do local antes de `exec`, sincroniza de volta após `exec`; o workspace local permanece canônico +- `mirror`: semeia o remoto a partir do local antes do exec, sincroniza de volta após o exec; o workspace local permanece canônico - `remote`: semeia o remoto uma vez quando o sandbox é criado e depois mantém o workspace remoto como canônico -No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente com o sandbox após a etapa inicial de semeadura. -O transporte é feito por SSH para o sandbox OpenShell, mas o Plugin é o responsável pelo ciclo de vida do sandbox e pela sincronização opcional em espelho. +No modo `remote`, edições locais do host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa inicial. +O transporte é SSH para o sandbox OpenShell, mas o Plugin controla o ciclo de vida do sandbox e a sincronização espelho opcional. -**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Requer saída de rede, raiz gravável e usuário root. +**`setupCommand`** executa uma vez após a criação do contêiner (via `sh -lc`). Requer saída de rede, raiz gravável e usuário root. -**Contêineres usam `network: "none"` por padrão** — defina `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. +**Por padrão, os contêineres usam `network: "none"`** — defina `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. `"host"` é bloqueado. `"container:"` é bloqueado por padrão, a menos que você defina explicitamente -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (modo break-glass). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Anexos recebidos** são preparados em `media/inbound/*` no workspace ativo. +**Anexos de entrada** são preparados em `media/inbound/*` no workspace ativo. **`docker.binds`** monta diretórios adicionais do host; binds globais e por agente são mesclados. **Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. A URL do noVNC é injetada no prompt do sistema. Não requer `browser.enabled` em `openclaw.json`. O acesso de observador via noVNC usa autenticação VNC por padrão e o OpenClaw emite uma URL com token de curta duração (em vez de expor a senha na URL compartilhada). -- `allowHostControl: false` (padrão) impede que sessões em sandbox tenham como alvo o navegador do host. -- `network` usa `openclaw-sandbox-browser` como padrão (rede bridge dedicada). Defina `bridge` apenas quando quiser explicitamente conectividade global de bridge. -- `cdpSourceRange` restringe opcionalmente a entrada do CDP na borda do contêiner a um intervalo CIDR (por exemplo `172.21.0.1/32`). -- `sandbox.browser.binds` monta diretórios adicionais do host apenas no contêiner do navegador em sandbox. Quando definido (incluindo `[]`), substitui `docker.binds` para o contêiner do navegador. -- Os padrões de inicialização são definidos em `scripts/sandbox-browser-entrypoint.sh` e ajustados para hosts com contêineres: +- `allowHostControl: false` (padrão) bloqueia sessões em sandbox de segmentarem o navegador do host. +- `network` usa por padrão `openclaw-sandbox-browser` (rede bridge dedicada). Defina `bridge` apenas quando você quiser explicitamente conectividade global de bridge. +- `cdpSourceRange` restringe opcionalmente a entrada CDP na borda do contêiner a um intervalo CIDR (por exemplo `172.21.0.1/32`). +- `sandbox.browser.binds` monta diretórios adicionais do host apenas no contêiner do navegador em sandbox. Quando definido (inclusive `[]`), substitui `docker.binds` para o contêiner do navegador. +- Os padrões de inicialização são definidos em `scripts/sandbox-browser-entrypoint.sh` e ajustados para hosts de contêiner: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1724,26 +1707,27 @@ O acesso de observador via noVNC usa autenticação VNC por padrão e o OpenClaw - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` são habilitados por padrão e podem ser desabilitados com `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir isso. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se seu fluxo de trabalho + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se o seu fluxo de trabalho depender delas. - `--renderer-process-limit=2` pode ser alterado com `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; defina `0` para usar o limite padrão de processos do Chromium. - - além de `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` está habilitado. - - Os padrões são a linha de base da imagem do contêiner; use uma imagem de navegador personalizada com um entrypoint personalizado para alterar os padrões do contêiner. + - mais `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` estiver habilitado. + - Os padrões são a baseline da imagem do contêiner; use uma imagem de navegador personalizada com um + entrypoint personalizado para alterar os padrões do contêiner. -Sandbox de navegador e `sandbox.docker.binds` são compatíveis apenas com Docker. +O sandbox de navegador e `sandbox.docker.binds` são exclusivos do Docker. -Criar imagens: +Crie as imagens: ```bash scripts/sandbox-setup.sh # imagem principal do sandbox scripts/sandbox-browser-setup.sh # imagem opcional do navegador ``` -### `agents.list` (substituições por agente) +### `agents.list` (sobrescritas por agente) ```json5 { @@ -1755,13 +1739,13 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // ou { primary, fallbacks } + thinkingDefault: "high", // sobrescrita por agente do nível de thinking + reasoningDefault: "on", // sobrescrita por agente da visibilidade de reasoning + fastModeDefault: false, // sobrescrita por agente do modo rápido embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // sobrescreve agents.defaults.models params correspondentes por chave + skills: ["docs-search"], // substitui agents.defaults.skills quando definido identity: { name: "Samantha", theme: "helpful sloth", @@ -1793,24 +1777,24 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador ``` - `id`: ID estável do agente (obrigatório). -- `default`: quando vários são definidos, o primeiro vence (um aviso é registrado). Se nenhum for definido, a primeira entrada da lista é a padrão. -- `model`: a forma string substitui apenas `primary`; a forma objeto `{ primary, fallbacks }` substitui ambos (`[]` desabilita fallbacks globais). Jobs de Cron que substituem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`. -- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isso para substituições específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar todo o catálogo de modelos. +- `default`: quando vários estão definidos, o primeiro prevalece (um aviso é registrado). Se nenhum estiver definido, a primeira entrada da lista é o padrão. +- `model`: a forma de string sobrescreve apenas `primary`; a forma de objeto `{ primary, fallbacks }` sobrescreve ambos (`[]` desabilita fallbacks globais). Tarefas de Cron que sobrescrevem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`. +- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isto para sobrescritas específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar todo o catálogo de modelos. - `skills`: allowlist opcional de Skills por agente. Se omitido, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa nenhuma Skill. -- `thinkingDefault`: nível padrão opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Substitui `agents.defaults.thinkingDefault` para esse agente quando não há substituição por mensagem ou sessão. -- `reasoningDefault`: visibilidade padrão opcional de reasoning por agente (`on | off | stream`). Aplica-se quando não há substituição de reasoning por mensagem ou sessão. -- `fastModeDefault`: padrão opcional por agente para fast mode (`true | false`). Aplica-se quando não há substituição de fast mode por mensagem ou sessão. -- `embeddedHarness`: substituição opcional por agente da política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback PI padrão. -- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões em `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar sessões de harness ACP por padrão. +- `thinkingDefault`: sobrescrita opcional por agente do nível padrão de thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Sobrescreve `agents.defaults.thinkingDefault` para esse agente quando nenhuma sobrescrita por mensagem ou sessão estiver definida. +- `reasoningDefault`: sobrescrita opcional por agente da visibilidade padrão de reasoning (`on | off | stream`). Aplica-se quando nenhuma sobrescrita de reasoning por mensagem ou sessão estiver definida. +- `fastModeDefault`: padrão opcional por agente para o modo rápido (`true | false`). Aplica-se quando nenhuma sobrescrita de modo rápido por mensagem ou sessão estiver definida. +- `embeddedHarness`: sobrescrita opcional por agente da política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente exclusivo de Codex enquanto outros agentes mantêm o fallback padrão para PI. +- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar por padrão sessões de harness ACP. - `identity.avatar`: caminho relativo ao workspace, URL `http(s)` ou URI `data:`. - `identity` deriva padrões: `ackReaction` a partir de `emoji`, `mentionPatterns` a partir de `name`/`emoji`. -- `subagents.allowAgents`: allowlist de IDs de agente para `sessions_spawn` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). -- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita alvos que seriam executados sem sandbox. +- `subagents.allowAgents`: allowlist de IDs de agente para `sessions_spawn` (`["*"]` = qualquer; padrão: apenas o mesmo agente). +- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita destinos que executariam sem sandbox. - `subagents.requireAgentId`: quando true, bloqueia chamadas `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false). --- -## Roteamento de vários agentes +## Roteamento multiagente Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/pt-BR/concepts/multi-agent). @@ -1831,7 +1815,7 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/p ### Campos de correspondência de binding -- `type` (opcional): `route` para roteamento normal (a ausência de type usa route como padrão), `acp` para bindings persistentes de conversa ACP. +- `type` (opcional): `route` para roteamento normal (tipo ausente usa `route` por padrão), `acp` para bindings persistentes de conversa ACP. - `match.channel` (obrigatório) - `match.accountId` (opcional; `*` = qualquer conta; omitido = conta padrão) - `match.peer` (opcional; `{ kind: direct|group|channel, id }`) @@ -1843,13 +1827,13 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/p 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exata, sem peer/guild/team) -5. `match.accountId: "*"` (em todo o canal) +4. `match.accountId` (exato, sem peer/guild/team) +5. `match.accountId: "*"` (para o canal inteiro) 6. Agente padrão -Dentro de cada nível, a primeira entrada correspondente em `bindings` vence. +Dentro de cada nível, a primeira entrada correspondente em `bindings` prevalece. -Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de bindings de rota acima. +Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de binding de rota acima. ### Perfis de acesso por agente @@ -1900,7 +1884,7 @@ Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da convers - + ```json5 { @@ -1972,22 +1956,22 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // ignora fork da thread pai acima dessa contagem de tokens (0 desabilita) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // duração ou false + maxDiskBytes: "500mb", // orçamento rígido opcional + highWaterBytes: "400mb", // alvo opcional de limpeza }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // padrão de desfoco automático por inatividade em horas (`0` desabilita) + maxAgeHours: 0, // padrão de idade máxima rígida em horas (`0` desabilita) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // legado (o runtime sempre usa "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1999,35 +1983,35 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p -- **`scope`**: estratégia base de agrupamento de sessão para contextos de chat em grupo. +- **`scope`**: estratégia base de agrupamento de sessão para contextos de conversa em grupo. - `per-sender` (padrão): cada remetente recebe uma sessão isolada dentro de um contexto de canal. - `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use apenas quando o contexto compartilhado for intencional). -- **`dmScope`**: como DMs são agrupadas. +- **`dmScope`**: como as DMs são agrupadas. - `main`: todas as DMs compartilham a sessão principal. - `per-peer`: isola por ID do remetente entre canais. - - `per-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada com vários usuários). + - `per-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada multiusuário). - `per-account-channel-peer`: isola por conta + canal + remetente (recomendado para várias contas). - **`identityLinks`**: mapeia IDs canônicos para peers com prefixo de provedor para compartilhamento de sessão entre canais. -- **`reset`**: política principal de reset. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, o primeiro a expirar vence. -- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O legado `dm` é aceito como alias para `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread derivada (padrão `100000`). - - Se `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico de transcrição da sessão pai. - - Defina `0` para desabilitar essa proteção e sempre permitir a derivação da sessão pai. +- **`reset`**: política principal de reset. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, o que expirar primeiro prevalece. +- **`resetByType`**: sobrescritas por tipo (`direct`, `group`, `thread`). O valor legado `dm` é aceito como alias para `direct`. +- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread bifurcada (padrão `100000`). + - Se o `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma sessão de thread nova em vez de herdar o histórico de transcrição da sessão pai. + - Defina `0` para desabilitar essa proteção e sempre permitir bifurcação da sessão pai. - **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de chat direto. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta de volta entre agentes durante trocas agente-a-agente (inteiro, intervalo: `0`–`5`). `0` desabilita o encadeamento ping-pong. -- **`sendPolicy`**: correspondência por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação vence. -- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessões. +- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta de volta entre agentes durante trocas agent-to-agent (inteiro, intervalo: `0`–`5`). `0` desabilita encadeamento ping-pong. +- **`sendPolicy`**: correspondência por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação prevalece. +- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessão. - `mode`: `warn` emite apenas avisos; `enforce` aplica a limpeza. - - `pruneAfter`: corte de idade para entradas antigas (padrão `30d`). + - `pruneAfter`: limite de idade para entradas obsoletas (padrão `30d`). - `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). - - `rotateBytes`: rotaciona `sessions.json` quando excede esse tamanho (padrão `10mb`). - - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Usa `pruneAfter` como padrão; defina `false` para desabilitar. + - `rotateBytes`: rotaciona `sessions.json` quando ele excede esse tamanho (padrão `10mb`). + - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Usa `pruneAfter` por padrão; defina `false` para desabilitar. - `maxDiskBytes`: orçamento opcional de disco para o diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos. - - `highWaterBytes`: alvo opcional após a limpeza do orçamento. Usa `80%` de `maxDiskBytes` como padrão. + - `highWaterBytes`: alvo opcional após limpeza do orçamento. O padrão é `80%` de `maxDiskBytes`. - **`threadBindings`**: padrões globais para recursos de sessão vinculados a thread. - - `enabled`: chave mestra padrão (provedores podem substituir; o Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: desfoco automático padrão por inatividade em horas (`0` desabilita; provedores podem substituir) - - `maxAgeHours`: idade máxima rígida padrão em horas (`0` desabilita; provedores podem substituir) + - `enabled`: chave mestra padrão (os provedores podem sobrescrever; o Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: padrão de desfoco automático por inatividade em horas (`0` desabilita; os provedores podem sobrescrever) + - `maxAgeHours`: padrão de idade máxima rígida em horas (`0` desabilita; os provedores podem sobrescrever) @@ -2038,7 +2022,7 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // ou "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2053,7 +2037,7 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 desabilita byChannel: { whatsapp: 5000, slack: 1500, @@ -2065,36 +2049,36 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p ### Prefixo de resposta -Substituições por canal/conta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Sobrescritas por canal/conta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Resolução (a mais específica vence): conta → canal → global. `""` desabilita e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. +Resolução (a mais específica prevalece): conta → canal → global. `""` desabilita e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. **Variáveis de template:** -| Variável | Descrição | Exemplo | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Nome curto do modelo | `claude-opus-4-6` | +| Variável | Descrição | Exemplo | +| ----------------- | --------------------- | --------------------------- | +| `{model}` | Nome curto do modelo | `claude-opus-4-6` | | `{modelFull}` | Identificador completo do modelo | `anthropic/claude-opus-4-6` | -| `{provider}` | Nome do provedor | `anthropic` | -| `{thinkingLevel}` | Nível atual de thinking | `high`, `low`, `off` | -| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) | +| `{provider}` | Nome do provedor | `anthropic` | +| `{thinkingLevel}` | Nível atual de thinking | `high`, `low`, `off` | +| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) | As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias para `{thinkingLevel}`. -### Reação de confirmação +### Reação de ack -- Usa por padrão `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desabilitar. -- Substituições por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Usa por padrão `identity.emoji` do agente ativo ou `"👀"` caso contrário. Defina `""` para desabilitar. +- Sobrescritas por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. - Ordem de resolução: conta → canal → `messages.ackReaction` → fallback da identidade. - Escopo: `group-mentions` (padrão), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: remove a confirmação após a resposta no Slack, Discord e Telegram. +- `removeAckAfterReply`: remove o ack após a resposta no Slack, Discord e Telegram. - `messages.statusReactions.enabled`: habilita reações de status de ciclo de vida no Slack, Discord e Telegram. - No Slack e no Discord, se não definido, mantém reações de status habilitadas quando reações de confirmação estão ativas. + No Slack e no Discord, quando não definido, mantém as reações de status habilitadas quando reações de ack estão ativas. No Telegram, defina explicitamente como `true` para habilitar reações de status de ciclo de vida. ### Debounce de entrada -Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno de agente. Mídia/anexos são descarregados imediatamente. Comandos de controle ignoram o debounce. +Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno de agente. Mídia/anexos são descarregados imediatamente. Comandos de controle ignoram o debounce. ### TTS (texto para fala) @@ -2137,12 +2121,12 @@ Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno de } ``` -- `auto` controla o modo padrão de TTS automático: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo. -- `summaryModel` substitui `agents.defaults.model.primary` para resumo automático. -- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` como padrão (ativação opcional). -- Chaves de API usam como fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` substitui o endpoint de TTS da OpenAI. A ordem de resolução é configuração, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. -- Quando `openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e relaxa a validação de modelo/voz. +- `auto` controla o modo padrão de auto-TTS: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode sobrescrever preferências locais, e `/tts status` mostra o estado efetivo. +- `summaryModel` sobrescreve `agents.defaults.model.primary` para resumo automático. +- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` como padrão (opt-in). +- As chaves de API usam como fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. +- `openai.baseUrl` sobrescreve o endpoint TTS da OpenAI. A ordem de resolução é config, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. +- Quando `openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e flexibiliza a validação de modelo/voz. --- @@ -2173,12 +2157,12 @@ Padrões para o modo Talk (macOS/iOS/Android). ``` - `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Talk estiverem configurados. -- Chaves planas legadas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) são apenas para compatibilidade e são migradas automaticamente para `talk.providers.`. +- Chaves legadas planas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) são apenas para compatibilidade e são migradas automaticamente para `talk.providers.`. - IDs de voz usam como fallback `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`. - `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef. -- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Talk está configurada. +- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Talk estiver configurada. - `providers.*.voiceAliases` permite que diretivas de Talk usem nomes amigáveis. -- `silenceTimeoutMs` controla quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Se não definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). +- `silenceTimeoutMs` controla quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Quando não definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). --- @@ -2188,35 +2172,35 @@ Padrões para o modo Talk (macOS/iOS/Android). `tools.profile` define uma allowlist base antes de `tools.allow`/`tools.deny`: -O onboarding local define novas configurações locais com `tools.profile: "coding"` quando não definido (perfis explícitos existentes são preservados). +O onboarding local define novas configurações locais por padrão como `tools.profile: "coding"` quando não definido (perfis explícitos existentes são preservados). -| Perfil | Inclui | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `minimal` | apenas `session_status` | +| Perfil | Inclui | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | apenas `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Sem restrição (igual a não definir) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Sem restrição (igual a não definido) | ### Grupos de ferramentas -| Grupo | Ferramentas | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grupo | Ferramentas | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias para `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas as ferramentas internas (exclui Plugins de provedor) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Todas as ferramentas internas (exclui plugins de provedor) | ### `tools.allow` / `tools.deny` -Política global de permitir/negar ferramentas (negação vence). Não diferencia maiúsculas de minúsculas, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. +Política global de permitir/negar ferramentas (negação prevalece). Não diferencia maiúsculas de minúsculas, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. ```json5 { @@ -2242,7 +2226,7 @@ Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: ### `tools.elevated` -Controla acesso elevado de `exec` fora do sandbox: +Controla acesso elevado de exec fora do sandbox: ```json5 { @@ -2258,9 +2242,9 @@ Controla acesso elevado de `exec` fora do sandbox: } ``` -- A substituição por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais. +- A sobrescrita por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais. - `/elevated on|off|ask|full` armazena estado por sessão; diretivas inline se aplicam a uma única mensagem. -- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o alvo de exec é `node`). +- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o destino de exec é `node`). ### `tools.exec` @@ -2306,13 +2290,13 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e so } ``` -- `historySize`: máximo de histórico de chamadas de ferramenta mantido para análise de loop. +- `historySize`: máximo de histórico de chamadas de ferramenta retido para análise de loop. - `warningThreshold`: limite de padrão repetitivo sem progresso para avisos. - `criticalThreshold`: limite repetitivo mais alto para bloquear loops críticos. - `globalCircuitBreakerThreshold`: limite de parada rígida para qualquer execução sem progresso. - `detectors.genericRepeat`: avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos. -- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas de polling conhecidas (`process.poll`, `command_status` etc.). -- `detectors.pingPong`: avisa/bloqueia padrões alternados de pares sem progresso. +- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas conhecidas de polling (`process.poll`, `command_status` etc.). +- `detectors.pingPong`: avisa/bloqueia padrões alternados de par sem progresso. - Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, a validação falha. ### `tools.web` @@ -2323,14 +2307,14 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e so web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // ou variável de ambiente BRAVE_API_KEY maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // opcional; omita para detecção automática maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2347,7 +2331,7 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e so ### `tools.media` -Configura o entendimento de mídia recebida (imagem/áudio/vídeo): +Configura compreensão de mídia de entrada (imagem/áudio/vídeo): ```json5 { @@ -2355,7 +2339,7 @@ Configura o entendimento de mídia recebida (imagem/áudio/vídeo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: envia música/vídeo assíncronos concluídos diretamente ao canal }, audio: { enabled: true, @@ -2384,27 +2368,27 @@ Configura o entendimento de mídia recebida (imagem/áudio/vídeo): **Entrada de provedor** (`type: "provider"` ou omitido): - `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq` etc.) -- `model`: substituição de ID de modelo -- `profile` / `preferredProfile`: seleção de perfil de `auth-profiles.json` +- `model`: sobrescrita do ID do modelo +- `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json` -**Entrada de CLI** (`type: "cli"`): +**Entrada CLI** (`type: "cli"`): - `command`: executável a ser executado -- `args`: argumentos com template (oferece suporte a `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) +- `args`: argumentos com template (suporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) **Campos comuns:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Padrões: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: substituições por entrada. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: sobrescritas por entrada. - Falhas usam a próxima entrada como fallback. A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → variáveis de ambiente → `models.providers.*.apiKey`. **Campos de conclusão assíncrona:** -- `asyncCompletion.directSend`: quando `true`, tarefas assíncronas concluídas de `music_generate` - e `video_generate` tentam primeiro a entrega direta ao canal. Padrão: `false` - (caminho legado de despertar sessão solicitante/entrega por modelo). +- `asyncCompletion.directSend`: quando `true`, tarefas concluídas de `music_generate` + e `video_generate` tentam primeiro entrega direta ao canal. Padrão: `false` + (caminho legado de ativação de sessão solicitante/entrega por modelo). @@ -2423,7 +2407,7 @@ A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → var ### `tools.sessions` -Controla quais sessões podem ser alvo das ferramentas de sessão (`sessions_list`, `sessions_history`, `sessions_send`). +Controla quais sessões podem ser direcionadas pelas ferramentas de sessão (`sessions_list`, `sessions_history`, `sessions_send`). Padrão: `tree` (sessão atual + sessões iniciadas por ela, como subagentes). @@ -2443,23 +2427,23 @@ Observações: - `self`: apenas a chave da sessão atual. - `tree`: sessão atual + sessões iniciadas pela sessão atual (subagentes). - `agent`: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo ID de agente). -- `all`: qualquer sessão. O direcionamento entre agentes ainda exige `tools.agentToAgent`. -- Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo que `tools.sessions.visibility="all"`. +- `all`: qualquer sessão. O direcionamento entre agentes ainda requer `tools.agentToAgent`. +- Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo se `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Controla o suporte a anexos inline para `sessions_spawn`. +Controla suporte a anexos inline para `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: defina true para permitir anexos de arquivo inline + maxTotalBytes: 5242880, // 5 MB no total entre todos os arquivos maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 MB por arquivo + retainOnSessionKeep: false, // mantém anexos quando cleanup="keep" }, }, }, @@ -2468,22 +2452,22 @@ Controla o suporte a anexos inline para `sessions_spawn`. Observações: -- Anexos só são compatíveis com `runtime: "subagent"`. O runtime ACP os rejeita. -- Arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. +- Anexos são compatíveis apenas com `runtime: "subagent"`. O runtime ACP os rejeita. +- Os arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. - O conteúdo dos anexos é automaticamente redigido da persistência da transcrição. -- Entradas em Base64 são validadas com verificações estritas de alfabeto/preenchimento e proteção de tamanho antes da decodificação. +- Entradas em Base64 são validadas com verificações rígidas de alfabeto/padding e uma proteção de tamanho antes da decodificação. - As permissões de arquivo são `0700` para diretórios e `0600` para arquivos. - A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os retém apenas quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flags experimentais de ferramentas internas. Desligadas por padrão, a menos que uma regra de autoativação strict-agentic GPT-5 se aplique. +Flags experimentais de ferramentas internas. Padrão desativado, a menos que uma regra de autoativação estrita agentic GPT-5 se aplique. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // habilita o experimental update_plan }, }, } @@ -2491,9 +2475,9 @@ Flags experimentais de ferramentas internas. Desligadas por padrão, a menos que Observações: -- `planTool`: habilita a ferramenta estruturada experimental `update_plan` para rastreamento de trabalho não trivial em várias etapas. -- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desabilitada mesmo em execuções strict-agentic GPT-5. -- Quando habilitada, o prompt do sistema também adiciona orientações de uso para que o modelo só a use em trabalho substancial e mantenha no máximo uma etapa `in_progress`. +- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhamento de trabalho não trivial em várias etapas. +- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma sobrescrita por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ativação da ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções GPT-5 strict-agentic. +- Quando habilitado, o prompt do sistema também adiciona orientação de uso para que o modelo a utilize apenas em trabalho substancial e mantenha no máximo uma etapa `in_progress`. ### `agents.defaults.subagents` @@ -2514,7 +2498,7 @@ Observações: ``` - `model`: modelo padrão para subagentes iniciados. Se omitido, os subagentes herdam o modelo do chamador. -- `allowAgents`: allowlist padrão de IDs de agente de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). +- `allowAgents`: allowlist padrão de IDs de agente de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer; padrão: apenas o mesmo agente). - `runTimeoutSeconds`: timeout padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem timeout. - Política de ferramenta por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. @@ -2527,7 +2511,7 @@ O OpenClaw usa o catálogo interno de modelos. Adicione provedores personalizado ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (padrão) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2552,49 +2536,49 @@ O OpenClaw usa o catálogo interno de modelos. Adicione provedores personalizado ``` - Use `authHeader: true` + `headers` para necessidades de autenticação personalizadas. -- Substitua a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente). +- Sobrescreva a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente). - Precedência de mesclagem para IDs de provedor correspondentes: - - Valores não vazios de `baseUrl` em `models.json` do agente têm prioridade. - - Valores não vazios de `apiKey` do agente têm prioridade apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de config/perfil de autenticação. + - Valores `baseUrl` não vazios em `models.json` do agente prevalecem. + - Valores `apiKey` não vazios do agente prevalecem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação. - Valores `apiKey` de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos. - Valores de cabeçalho de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec). - - `apiKey`/`baseUrl` do agente vazios ou ausentes usam como fallback `models.providers` na configuração. - - `contextWindow`/`maxTokens` do modelo correspondente usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo. - - `contextTokens` do modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar metadados nativos do modelo. - - Use `models.mode: "replace"` quando quiser que a configuração reescreva completamente `models.json`. - - A persistência de marcadores é autoritativa pela origem: os marcadores são gravados a partir do snapshot ativo da configuração de origem (pré-resolução), não a partir dos valores secretos resolvidos em runtime. + - `apiKey`/`baseUrl` do agente vazios ou ausentes usam `models.providers` da configuração como fallback. + - `contextWindow`/`maxTokens` de modelo correspondente usam o maior valor entre a configuração explícita e os valores implícitos do catálogo. + - `contextTokens` de modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar metadados nativos do modelo. + - Use `models.mode: "replace"` quando quiser que a configuração reescreva totalmente `models.json`. + - A persistência de marcadores é autoritativa em relação à origem: os marcadores são gravados a partir do snapshot ativo da configuração de origem (pré-resolução), não a partir dos valores secretos resolvidos em runtime. ### Detalhes dos campos do provedor - `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`). - `models.providers`: mapa de provedores personalizados indexado por ID do provedor. -- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc). +- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). - `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição por ambiente). - `models.providers.*.auth`: estratégia de autenticação (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas requisições (padrão: `true`). - `models.providers.*.authHeader`: força o transporte da credencial no cabeçalho `Authorization` quando necessário. - `models.providers.*.baseUrl`: URL base da API upstream. -- `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento por proxy/tenant. -- `models.providers.*.request`: substituições de transporte para requisições HTTP do provedor de modelos. +- `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento de proxy/tenant. +- `models.providers.*.request`: sobrescritas de transporte para requisições HTTP do model-provider. - `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Os valores aceitam SecretRef. - - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação interna do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). - - `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional. - - `request.tls`: substituição de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para faixas privadas, CGNAT ou similares, via a proteção SSRF de fetch HTTP do provedor (ativação do operador para endpoints confiáveis autohospedados compatíveis com OpenAI). WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa barreira SSRF de fetch. Padrão `false`. + - `request.auth`: sobrescrita da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação interna do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value` e `prefix` opcional). + - `request.proxy`: sobrescrita de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional. + - `request.tls`: sobrescrita de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para intervalos privados, CGNAT ou similares, por meio da proteção de fetch HTTP do provedor (opt-in do operador para endpoints compatíveis com OpenAI self-hosted confiáveis). O WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa proteção SSRF de fetch. Padrão `false`. - `models.providers.*.models`: entradas explícitas do catálogo de modelos do provedor. -- `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. +- `models.providers.*.models.*.contextWindow`: metadados nativos da janela de contexto do modelo. - `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isto quando quiser um orçamento de contexto efetivo menor que o `contextWindow` nativo do modelo. - `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não vazio e não nativo (host diferente de `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas string. Quando `true`, o OpenClaw achata arrays `messages[].content` compostos apenas por texto em strings simples antes de enviar a requisição. -- `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de autodiscovery do Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa o discovery implícito. -- `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de ID de provedor para discovery direcionado. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização do discovery. +- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas string. Quando `true`, o OpenClaw achata arrays puramente textuais de `messages[].content` em strings simples antes de enviar a requisição. +- `plugins.entries.amazon-bedrock.config.discovery`: raiz de configurações de autodescoberta do Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa descoberta implícita. +- `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para descoberta. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de ID de provedor para descoberta direcionada. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização da descoberta. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto de fallback para modelos descobertos. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída de fallback para modelos descobertos. -### Exemplos de provedores +### Exemplos de provedor @@ -2647,7 +2631,7 @@ Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI direto. } ``` -Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use referências `opencode/...` para o catálogo Zen ou `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. +Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use refs `opencode/...` para o catálogo Zen ou refs `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. @@ -2667,8 +2651,8 @@ Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use referências `opencod Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `openclaw onboard --auth-choice zai-api-key`. - Endpoint geral: `https://api.z.ai/api/paas/v4` -- Endpoint de codificação (padrão): `https://api.z.ai/api/coding/paas/v4` -- Para o endpoint geral, defina um provedor personalizado com substituição da URL base. +- Endpoint de coding (padrão): `https://api.z.ai/api/coding/paas/v4` +- Para o endpoint geral, defina um provedor personalizado com a sobrescrita de URL base. @@ -2709,9 +2693,9 @@ Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `opencla Para o endpoint da China: `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`. -Endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado +Os endpoints nativos do Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado `openai-completions`, e o OpenClaw baseia isso nas capacidades do endpoint -em vez de apenas no ID interno do provedor. +em vez de apenas no ID do provedor interno. @@ -2768,7 +2752,7 @@ Compatível com Anthropic, provedor interno. Atalho: `openclaw onboard --auth-ch } ``` -A URL base deve omitir `/v1` (o cliente Anthropic a acrescenta). Atalho: `openclaw onboard --auth-choice synthetic-api-key`. +A URL base deve omitir `/v1` (o cliente Anthropic o acrescenta). Atalho: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2811,7 +2795,7 @@ A URL base deve omitir `/v1` (o cliente Anthropic a acrescenta). Atalho: `opencl Defina `MINIMAX_API_KEY`. Atalhos: `openclaw onboard --auth-choice minimax-global-api` ou `openclaw onboard --auth-choice minimax-cn-api`. -O catálogo de modelos usa apenas M2.7 por padrão. +O catálogo de modelos usa por padrão apenas M2.7. No caminho de streaming compatível com Anthropic, o OpenClaw desabilita o thinking do MiniMax por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou `params.fastMode: true` reescreve `MiniMax-M2.7` para @@ -2821,7 +2805,7 @@ por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou -Consulte [Local Models](/pt-BR/gateway/local-models). Em resumo: execute um grande modelo local via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. +Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um grande modelo local via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. @@ -2842,7 +2826,7 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Em resumo: execute um gran }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // ou string em texto simples env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2852,14 +2836,14 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Em resumo: execute um gran } ``` -- `allowBundled`: allowlist opcional apenas para Skills agrupadas (Skills gerenciadas/do workspace não são afetadas). +- `allowBundled`: allowlist opcional apenas para Skills bundled (Skills gerenciadas/do workspace não são afetadas). - `load.extraDirs`: raízes extras compartilhadas de Skills (menor precedência). - `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está - disponível, antes de recorrer a outros tipos de instalador. -- `install.nodeManager`: preferência de instalador Node para especificações - `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desabilita uma Skill mesmo que esteja agrupada/instalada. -- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string em texto simples ou objeto SecretRef). + disponível antes de recorrer a outros tipos de instalador. +- `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` desabilita uma Skill mesmo que esteja bundled/instalada. +- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente principal (string em texto simples ou objeto SecretRef). --- @@ -2887,38 +2871,38 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Em resumo: execute um gran } ``` -- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions`, além de `plugins.load.paths`. -- O discovery aceita Plugins nativos do OpenClaw, além de bundles compatíveis do Codex e do Claude, incluindo bundles do Claude sem manifesto no layout padrão. -- **Mudanças de configuração exigem reinicialização do gateway.** -- `allow`: allowlist opcional (apenas Plugins listados são carregados). `deny` vence. -- `plugins.entries..apiKey`: campo de conveniência de chave de API em nível de Plugin (quando compatível com o Plugin). -- `plugins.entries..env`: mapa de variáveis de ambiente com escopo do Plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o núcleo bloqueia `before_prompt_build` e ignora campos que modificam prompt do legado `before_agent_start`, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks nativos de Plugin e a diretórios de hooks fornecidos por bundle compatíveis. -- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste Plugin para solicitar substituições por execução de `provider` e `model` em execuções de subagente em segundo plano. -- `plugins.entries..subagent.allowedModels`: allowlist opcional de alvos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` apenas quando quiser intencionalmente permitir qualquer modelo. -- `plugins.entries..config`: objeto de configuração definido pelo Plugin (validado pelo schema de Plugin nativo do OpenClaw quando disponível). -- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor Firecrawl para web fetch. +- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. +- A descoberta aceita plugins nativos do OpenClaw e também bundles compatíveis do Codex e bundles do Claude, incluindo bundles do Claude sem manifesto no layout padrão. +- **Alterações de configuração exigem reinicialização do gateway.** +- `allow`: allowlist opcional (somente os plugins listados são carregados). `deny` prevalece. +- `plugins.entries..apiKey`: campo de conveniência de chave de API no nível do plugin (quando compatível com o plugin). +- `plugins.entries..env`: mapa de variáveis de ambiente com escopo do plugin. +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram prompt de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks nativos de plugin e diretórios de hook fornecidos por bundle compatíveis. +- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar sobrescritas por execução de `provider` e `model` para execuções em segundo plano de subagente. +- `plugins.entries..subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para sobrescritas confiáveis de subagente. Use `"*"` apenas quando você quiser intencionalmente permitir qualquer modelo. +- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo schema do plugin nativo do OpenClaw quando disponível). +- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de web-fetch Firecrawl. - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa como fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, o legado `tools.web.fetch.firecrawl.apiKey` ou a variável de ambiente `FIRECRAWL_API_KEY`. - - `baseUrl`: URL base da API do Firecrawl (padrão: `https://api.firecrawl.dev`). + - `baseUrl`: URL base da API Firecrawl (padrão: `https://api.firecrawl.dev`). - `onlyMainContent`: extrai apenas o conteúdo principal das páginas (padrão: `true`). - `maxAgeMs`: idade máxima de cache em milissegundos (padrão: `172800000` / 2 dias). - `timeoutSeconds`: timeout da requisição de scraping em segundos (padrão: `60`). -- `plugins.entries.xai.config.xSearch`: configurações do X Search da xAI (busca web do Grok). +- `plugins.entries.xai.config.xSearch`: configurações de X Search do xAI (busca web do Grok). - `enabled`: habilita o provedor X Search. - - `model`: modelo Grok a usar para busca (por exemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. - - `enabled`: chave mestra de dreaming (padrão `false`). - - `frequency`: cadência Cron para cada varredura completa de dreaming (`"0 3 * * *"` por padrão). - - política de fase e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). -- A configuração completa de memória está em [Memory configuration reference](/pt-BR/reference/memory-config): + - `model`: modelo Grok a ser usado para busca (ex.: `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: configurações de Dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. + - `enabled`: chave mestra de Dreaming (padrão `false`). + - `frequency`: cadência do Cron para cada varredura completa de Dreaming (padrão `"0 3 * * *"`). + - política de fases e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). +- A configuração completa de memória está em [Referência de configuração de memória](/pt-BR/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Plugins de bundle Claude habilitados também podem contribuir com padrões embutidos de Pi a partir de `settings.json`; o OpenClaw os aplica como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. -- `plugins.slots.memory`: escolhe o ID do Plugin de memória ativo, ou `"none"` para desabilitar Plugins de memória. -- `plugins.slots.contextEngine`: escolhe o ID do Plugin de mecanismo de contexto ativo; usa `"legacy"` como padrão até que você instale e selecione outro mecanismo. +- Plugins de bundle Claude habilitados também podem contribuir com padrões incorporados de Pi a partir de `settings.json`; o OpenClaw os aplica como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. +- `plugins.slots.memory`: escolhe o ID do plugin de memória ativo, ou `"none"` para desabilitar plugins de memória. +- `plugins.slots.contextEngine`: escolhe o ID do plugin de mecanismo de contexto ativo; usa por padrão `"legacy"` a menos que você instale e selecione outro mecanismo. - `plugins.installs`: metadados de instalação gerenciados pela CLI usados por `openclaw plugins update`. - Inclui `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - Trate `plugins.installs.*` como estado gerenciado; prefira comandos da CLI em vez de edições manuais. @@ -2927,7 +2911,7 @@ Consulte [Plugins](/pt-BR/tools/plugin). --- -## Navegador +## Browser ```json5 { @@ -2936,8 +2920,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // faça opt-in apenas para acesso confiável à rede privada + // allowPrivateNetwork: true, // alias legado // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2964,25 +2948,24 @@ Consulte [Plugins](/pt-BR/tools/plugin). ``` - `evaluateEnabled: false` desabilita `act:evaluate` e `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desabilitado quando não definido, então a navegação do navegador permanece estrita por padrão. -- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando confiar intencionalmente na navegação do navegador em rede privada. -- No modo estrito, endpoints remotos de perfil CDP (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/discovery. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desabilitado quando não definido, então a navegação do browser permanece estrita por padrão. +- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando você confiar intencionalmente na navegação de browser em rede privada. +- No modo estrito, endpoints remotos de perfil CDP (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta. - `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado. - No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. -- Perfis remotos são somente attach (iniciar/parar/redefinir desabilitados). +- Perfis remotos são apenas de anexação (iniciar/parar/redefinir desabilitados). - `profiles.*.cdpUrl` aceita `http://`, `https://`, `ws://` e `wss://`. Use HTTP(S) quando quiser que o OpenClaw descubra `/json/version`; use WS(S) quando seu provedor fornecer uma URL WebSocket direta do DevTools. -- Perfis `existing-session` funcionam apenas no host e usam Chrome MCP em vez de CDP. -- Perfis `existing-session` podem definir `userDataDir` para apontar para um perfil específico - de navegador baseado em Chromium, como Brave ou Edge. -- Perfis `existing-session` mantêm os limites atuais da rota Chrome MCP: - ações baseadas em snapshot/ref em vez de direcionamento por seletor CSS, hooks - de upload de um único arquivo, sem substituições de timeout de diálogo, sem - `wait --load networkidle`, e sem `responsebody`, exportação de PDF, interceptação - de download ou ações em lote. -- Perfis locais gerenciados `openclaw` atribuem automaticamente `cdpPort` e `cdpUrl`; só - defina `cdpUrl` explicitamente para CDP remoto. +- Perfis `existing-session` são apenas para host e usam Chrome MCP em vez de CDP. +- Perfis `existing-session` podem definir `userDataDir` para segmentar um perfil específico de navegador + baseado em Chromium, como Brave ou Edge. +- Perfis `existing-session` mantêm os limites atuais de rota do Chrome MCP: + ações guiadas por snapshot/ref em vez de segmentação por seletor CSS, hooks de upload + de um único arquivo, sem sobrescritas de timeout de diálogo, sem `wait --load networkidle`, + e sem `responsebody`, exportação de PDF, interceptação de download ou ações em lote. +- Perfis locais gerenciados `openclaw` atribuem automaticamente `cdpPort` e `cdpUrl`; defina + `cdpUrl` explicitamente apenas para CDP remoto. - Ordem de autodetecção: navegador padrão se for baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Serviço de controle: apenas loopback (porta derivada de `gateway.port`, padrão `18791`). - `extraArgs` acrescenta flags extras de inicialização ao Chromium local (por exemplo @@ -2998,14 +2981,14 @@ Consulte [Plugins](/pt-BR/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji, texto curto, URL de imagem ou URI data }, }, } ``` - `seamColor`: cor de destaque para o chrome da UI do app nativo (matiz da bolha do modo Talk etc.). -- `assistant`: substituição de identidade da Control UI. Usa como fallback a identidade do agente ativo. +- `assistant`: sobrescrita de identidade da Control UI. Usa a identidade do agente ativo como fallback. --- @@ -3020,8 +3003,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // ou OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // para mode=trusted-proxy; consulte /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3039,9 +3022,9 @@ Consulte [Plugins](/pt-BR/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // perigoso: permite URLs absolutas externas http(s) de embed + // allowedOrigins: ["https://control.example.com"], // obrigatório para Control UI fora de loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // modo perigoso de fallback de origem por cabeçalho Host // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3052,12 +3035,12 @@ Consulte [Plugins](/pt-BR/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // Opcional. Padrão false. allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // Negações HTTP adicionais em /tools/invoke deny: ["browser"], - // Remove tools from the default HTTP deny list + // Remove ferramentas da lista padrão de negação HTTP allow: ["gateway"], }, push: { @@ -3074,45 +3057,45 @@ Consulte [Plugins](/pt-BR/tools/plugin). -- `mode`: `local` (executa o gateway) ou `remote` (conecta a um gateway remoto). O Gateway se recusa a iniciar a menos que esteja em `local`. +- `mode`: `local` (executa o gateway) ou `remote` (conecta a um gateway remoto). O gateway se recusa a iniciar a menos que esteja em `local`. - `port`: porta multiplexada única para WS + HTTP. Precedência: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (apenas IP do Tailscale) ou `custom`. +- `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (somente IP do Tailscale) ou `custom`. - **Aliases legados de bind**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o gateway fica inacessível. Use `--network host`, ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. -- **Auth**: exigida por padrão. Binds fora de loopback exigem auth do gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade usando `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. -- Se `gateway.auth.token` e `gateway.auth.password` estiverem ambos configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. A inicialização e os fluxos de instalação/reparo do serviço falham quando ambos estão configurados e o modo não está definido. -- `gateway.auth.mode: "none"`: modo explícito sem auth. Use apenas para configurações confiáveis de local loopback; isso intencionalmente não é oferecido pelos prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega auth a um proxy reverso com reconhecimento de identidade e confia nos cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **fora de loopback**; proxies reversos loopback no mesmo host não satisfazem a auth trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a auth da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa auth por cabeçalho do Tailscale; eles seguem o modo normal de auth HTTP do gateway. Esse fluxo sem token presume que o host do gateway é confiável. Usa `true` como padrão quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional de falhas de auth. Aplica-se por IP do cliente e por escopo de auth (segredo compartilhado e token de dispositivo são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. - - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Assim, tentativas ruins concorrentes do mesmo cliente podem disparar o limitador na segunda requisição em vez de ambas passarem em paralelo como incompatibilidades simples. - - `gateway.auth.rateLimit.exemptLoopback` usa `true` como padrão; defina `false` quando quiser intencionalmente limitar também o tráfego localhost (para ambientes de teste ou implantações estritas com proxy). -- Tentativas de auth WS com origem de navegador são sempre limitadas, com isenção de loopback desabilitada (defesa em profundidade contra força bruta de localhost baseada em navegador). -- Em loopback, esses bloqueios de origem de navegador são isolados por valor +- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o gateway fica inacessível. Use `--network host` ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. +- **Autenticação**: obrigatória por padrão. Binds fora de loopback exigem autenticação do gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade com `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. +- Se `gateway.auth.token` e `gateway.auth.password` estiverem ambos configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Os fluxos de inicialização e de instalação/reparo do serviço falham quando ambos estão configurados e o modo não está definido. +- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações locais confiáveis de local loopback; isso intencionalmente não é oferecido pelos prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega autenticação a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade vindos de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **fora de loopback**; proxies reversos em loopback no mesmo host não satisfazem a autenticação trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer autenticação da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; eles seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token presume que o host do gateway é confiável. Usa `true` por padrão quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional para falhas de autenticação. Aplica-se por IP do cliente e por escopo de autenticação (segredo compartilhado e token de dispositivo são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. + - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Portanto, tentativas simultâneas inválidas do mesmo cliente podem acionar o limitador na segunda requisição em vez de ambas passarem como simples incompatibilidades. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` por padrão; defina `false` quando você quiser intencionalmente que o tráfego localhost também seja limitado (para ambientes de teste ou implantações estritas com proxy). +- Tentativas de autenticação WS originadas do browser são sempre limitadas com a isenção de loopback desabilitada (defesa em profundidade contra força bruta localhost via navegador). +- Em loopback, esses bloqueios para origens de browser são isolados por valor `Origin` normalizado, então falhas repetidas de uma origem localhost não bloqueiam automaticamente uma origem diferente. -- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, requer auth). -- `controlUi.allowedOrigins`: allowlist explícita de origem de navegador para conexões WebSocket do Gateway. Obrigatória quando se espera clientes de navegador a partir de origens fora de loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem pelo cabeçalho Host para implantações que dependem intencionalmente da política de origem baseada em Host header. +- `tailscale.mode`: `serve` (somente tailnet, bind em loopback) ou `funnel` (público, requer autenticação). +- `controlUi.allowedOrigins`: allowlist explícita de origem do browser para conexões WebSocket do Gateway. Obrigatória quando se espera clientes de browser vindos de origens fora de loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente de política de origem baseada em cabeçalho Host. - `remote.transport`: `ssh` (padrão) ou `direct` (ws/wss). Para `direct`, `remote.url` deve ser `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição break-glass no lado do cliente que permite `ws://` em texto puro para IPs confiáveis de rede privada; o padrão continua sendo texto puro apenas para loopback. -- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram a auth do gateway por si só. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay APNs externo usado por builds oficiais/TestFlight do iOS após publicarem registros com relay para o gateway. Essa URL deve corresponder à URL do relay compilada no build do iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout de envio do gateway para o relay em milissegundos. Padrão: `10000`. -- Registros com relay são delegados a uma identidade específica de gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha uma permissão de envio com escopo de registro ao gateway. Outro gateway não pode reutilizar esse registro armazenado. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias por ambiente para a configuração de relay acima. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch apenas para desenvolvimento para URLs HTTP de relay em loopback. URLs de relay em produção devem permanecer em HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo, em minutos, do monitor de integridade de canal. Defina `0` para desabilitar globalmente reinicializações pelo monitor de integridade. Padrão: `5`. -- `gateway.channelStaleEventThresholdMinutes`: limite, em minutos, para socket obsoleto. Mantenha este valor maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. -- `gateway.channelMaxRestartsPerHour`: máximo de reinicializações por monitor de integridade por canal/conta em uma hora móvel. Padrão: `10`. -- `channels..healthMonitor.enabled`: desativação opcional por canal para reinicializações do monitor de integridade, mantendo o monitor global habilitado. -- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definido, tem precedência sobre a substituição em nível de canal. -- Caminhos de chamada do gateway local podem usar `gateway.remote.*` como fallback apenas quando `gateway.auth.*` não está definido. -- Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não resolvido, a resolução falha em modo fechado (sem fallback remoto encobrindo). -- `trustedProxies`: IPs de proxies reversos que terminam TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies sob seu controle. Entradas loopback ainda são válidas para configurações de detecção local/proxy no mesmo host (por exemplo Tailscale Serve ou um proxy reverso local), mas elas **não** tornam requisições loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: sobrescrita break-glass do lado do cliente que permite `ws://` em texto claro para IPs confiáveis de rede privada; o padrão continua sendo apenas loopback para texto claro. +- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram autenticação do gateway por si só. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay APNs externo usado por builds oficiais/TestFlight do iOS depois que eles publicam registros com suporte por relay para o gateway. Essa URL deve corresponder à URL do relay compilada no build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout em milissegundos para envio do gateway ao relay. O padrão é `10000`. +- Registros com suporte por relay são delegados a uma identidade específica do gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha uma permissão de envio com escopo do registro ao gateway. Outro gateway não pode reutilizar esse registro armazenado. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: sobrescritas temporárias por ambiente para a configuração de relay acima. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch apenas para desenvolvimento para URLs HTTP de relay em loopback. URLs de relay de produção devem permanecer em HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo do monitor de saúde de canais em minutos. Defina `0` para desabilitar globalmente reinicializações do monitor de saúde. Padrão: `5`. +- `gateway.channelStaleEventThresholdMinutes`: limite de socket obsoleto em minutos. Mantenha isso maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. +- `gateway.channelMaxRestartsPerHour`: máximo de reinicializações por monitor de saúde por canal/conta em uma hora móvel. Padrão: `10`. +- `channels..healthMonitor.enabled`: opt-out por canal para reinicializações do monitor de saúde, mantendo o monitor global habilitado. +- `channels..accounts..healthMonitor.enabled`: sobrescrita por conta para canais com várias contas. Quando definido, tem precedência sobre a sobrescrita no nível do canal. +- Caminhos locais de chamada do gateway podem usar `gateway.remote.*` como fallback apenas quando `gateway.auth.*` não está definido. +- Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não resolvido, a resolução falha em modo fail-closed (sem mascaramento por fallback remoto). +- `trustedProxies`: IPs de proxy reverso que encerram TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies sob seu controle. Entradas de loopback ainda são válidas para configurações de proxy no mesmo host/detecção local (por exemplo Tailscale Serve ou um proxy reverso local), mas **não** tornam requisições de loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: quando `true`, o gateway aceita `X-Real-IP` se `X-Forwarded-For` estiver ausente. Padrão `false` para comportamento fail-closed. - `gateway.tools.deny`: nomes extras de ferramentas bloqueadas para HTTP `POST /tools/invoke` (estende a lista padrão de negação). -- `gateway.tools.allow`: remove nomes de ferramentas da lista padrão de negação HTTP. +- `gateway.tools.allow`: remove nomes de ferramenta da lista padrão de negação HTTP. @@ -3120,18 +3103,18 @@ Consulte [Plugins](/pt-BR/tools/plugin). - Chat Completions: desabilitado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. - API Responses: `gateway.http.endpoints.responses.enabled`. -- Endurecimento de entrada por URL em Responses: +- Endurecimento de entrada por URL da Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Allowlists vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false` - e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desabilitar a busca por URL. + e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desabilitar busca por URL. - Cabeçalho opcional de endurecimento de resposta: - `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS sob seu controle; consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento de várias instâncias +### Isolamento entre várias instâncias -Execute vários gateways em um único host com portas e diretórios de estado exclusivos: +Execute vários gateways em um host com portas e diretórios de estado exclusivos: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3159,11 +3142,11 @@ Consulte [Multiple Gateways](/pt-BR/gateway/multiple-gateways). } ``` -- `enabled`: habilita terminação TLS no listener do gateway (HTTPS/WSS) (padrão: `false`). -- `autoGenerate`: gera automaticamente um par local de certificado/chave autoassinado quando arquivos explícitos não estão configurados; apenas para uso local/dev. -- `certPath`: caminho no sistema de arquivos para o arquivo do certificado TLS. -- `keyPath`: caminho no sistema de arquivos para o arquivo da chave privada TLS; mantenha permissões restritas. -- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança personalizadas. +- `enabled`: habilita encerramento TLS no listener do gateway (HTTPS/WSS) (padrão: `false`). +- `autoGenerate`: gera automaticamente um par local certificado/chave autoassinado quando arquivos explícitos não estão configurados; apenas para uso local/dev. +- `certPath`: caminho no sistema de arquivos para o arquivo de certificado TLS. +- `keyPath`: caminho no sistema de arquivos para o arquivo de chave privada TLS; mantenha com permissões restritas. +- `caPath`: caminho opcional do bundle CA para verificação de cliente ou cadeias de confiança personalizadas. ### `gateway.reload` @@ -3180,11 +3163,11 @@ Consulte [Multiple Gateways](/pt-BR/gateway/multiple-gateways). ``` - `mode`: controla como edições de configuração são aplicadas em runtime. - - `"off"`: ignora edições em tempo real; mudanças exigem reinicialização explícita. - - `"restart"`: sempre reinicia o processo do gateway em caso de mudança de configuração. - - `"hot"`: aplica mudanças no processo sem reinicializar. + - `"off"`: ignora edições ao vivo; alterações exigem reinicialização explícita. + - `"restart"`: sempre reinicia o processo do gateway em mudança de configuração. + - `"hot"`: aplica mudanças no processo sem reiniciar. - `"hybrid"` (padrão): tenta hot reload primeiro; usa reinicialização como fallback se necessário. -- `debounceMs`: janela de debounce em ms antes de aplicar mudanças de configuração (inteiro não negativo). +- `debounceMs`: janela de debounce em ms antes que alterações de configuração sejam aplicadas (inteiro não negativo). - `deferralTimeoutMs`: tempo máximo em ms para esperar operações em andamento antes de forçar uma reinicialização (padrão: `300000` = 5 minutos). --- @@ -3227,7 +3210,7 @@ Tokens de hook em query string são rejeitados. Observações de validação e segurança: -- `hooks.enabled=true` exige `hooks.token` não vazio. +- `hooks.enabled=true` requer `hooks.token` não vazio. - `hooks.token` deve ser **diferente** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado. - `hooks.path` não pode ser `/`; use um subcaminho dedicado, como `/hooks`. - Se `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por exemplo `["hook:"]`). @@ -3236,23 +3219,23 @@ Observações de validação e segurança: - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` da carga da requisição é aceito apenas quando `hooks.allowRequestSessionKey=true` (padrão: `false`). + - `sessionKey` do payload da requisição é aceito apenas quando `hooks.allowRequestSessionKey=true` (padrão: `false`). - `POST /hooks/` → resolvido via `hooks.mappings` - `match.path` corresponde ao subcaminho após `/hooks` (por exemplo `/hooks/gmail` → `gmail`). -- `match.source` corresponde a um campo da carga para caminhos genéricos. -- Templates como `{{messages[0].subject}}` leem a partir da carga. +- `match.source` corresponde a um campo do payload para caminhos genéricos. +- Templates como `{{messages[0].subject}}` leem do payload. - `transform` pode apontar para um módulo JS/TS que retorna uma ação de hook. - `transform.module` deve ser um caminho relativo e permanecer dentro de `hooks.transformsDir` (caminhos absolutos e travessia são rejeitados). -- `agentId` roteia para um agente específico; IDs desconhecidos usam o agente padrão como fallback. +- `agentId` roteia para um agente específico; IDs desconhecidos usam o padrão como fallback. - `allowedAgentIds`: restringe roteamento explícito (`*` ou omitido = permite todos, `[]` = nega todos). - `defaultSessionKey`: chave de sessão fixa opcional para execuções de agente por hook sem `sessionKey` explícito. - `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` definam `sessionKey` (padrão: `false`). - `allowedSessionKeyPrefixes`: allowlist opcional de prefixos para valores explícitos de `sessionKey` (requisição + mapeamento), por exemplo `["hook:"]`. -- `deliver: true` envia a resposta final para um canal; `channel` usa `last` como padrão. -- `model` substitui o LLM para esta execução de hook (deve ser permitido se o catálogo de modelos estiver definido). +- `deliver: true` envia a resposta final para um canal; `channel` usa `last` por padrão. +- `model` sobrescreve o LLM para essa execução de hook (deve ser permitido se o catálogo de modelos estiver definido). @@ -3291,22 +3274,22 @@ Observações de validação e segurança: canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // ou OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP na porta do Gateway: +- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP sob a porta do Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Apenas local: mantenha `gateway.bind: "loopback"` (padrão). -- Binds fora de loopback: rotas de canvas exigem auth do Gateway (token/senha/trusted-proxy), assim como outras superfícies HTTP do Gateway. -- Normalmente, Node WebViews não enviam cabeçalhos de auth; depois que um node é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo do node para acesso a canvas/A2UI. -- URLs de capacidade são vinculadas à sessão WS ativa do node e expiram rapidamente. Fallback baseado em IP não é usado. +- Somente local: mantenha `gateway.bind: "loopback"` (padrão). +- Binds fora de loopback: rotas de canvas exigem autenticação do Gateway (token/senha/trusted-proxy), igual às outras superfícies HTTP do Gateway. +- Node WebViews normalmente não enviam cabeçalhos de autenticação; depois que um node é pareado e conectado, o Gateway anuncia URLs de capability com escopo de node para acesso a canvas/A2UI. +- URLs de capability ficam vinculadas à sessão WS ativa do node e expiram rapidamente. Fallback baseado em IP não é usado. - Injeta cliente de live reload no HTML servido. -- Cria automaticamente um `index.html` inicial quando vazio. +- Cria automaticamente um `index.html` inicial quando estiver vazio. - Também serve A2UI em `/__openclaw__/a2ui/`. -- Mudanças exigem reinicialização do gateway. +- Alterações exigem reinicialização do gateway. - Desabilite live reload para diretórios grandes ou erros `EMFILE`. --- @@ -3327,7 +3310,7 @@ Observações de validação e segurança: - `minimal` (padrão): omite `cliPath` + `sshPort` dos registros TXT. - `full`: inclui `cliPath` + `sshPort`. -- O hostname usa `openclaw` como padrão. Substitua com `OPENCLAW_MDNS_HOSTNAME`. +- O hostname usa `openclaw` por padrão. Sobrescreva com `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3339,7 +3322,7 @@ Observações de validação e segurança: } ``` -Grava uma zona DNS-SD unicast em `~/.openclaw/dns/`. Para discovery entre redes, combine com um servidor DNS (CoreDNS recomendado) + split DNS do Tailscale. +Grava uma zona DNS-SD unicast em `~/.openclaw/dns/`. Para descoberta entre redes, combine com um servidor DNS (CoreDNS recomendado) + split DNS do Tailscale. Configuração: `openclaw dns setup --apply`. @@ -3365,13 +3348,13 @@ Configuração: `openclaw dns setup --apply`. ``` - Variáveis de ambiente inline são aplicadas apenas se o ambiente do processo não tiver a chave. -- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum substitui variáveis existentes). -- `shellEnv`: importa chaves esperadas ausentes a partir do perfil do seu shell de login. +- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum sobrescreve variáveis existentes). +- `shellEnv`: importa chaves esperadas ausentes do perfil do seu shell de login. - Consulte [Environment](/pt-BR/help/environment) para a precedência completa. -### Substituição de variável de ambiente +### Substituição de variáveis de ambiente -Faça referência a variáveis de ambiente em qualquer string de configuração com `${VAR_NAME}`: +Referencie variáveis de ambiente em qualquer string de configuração com `${VAR_NAME}`: ```json5 { @@ -3383,12 +3366,12 @@ Faça referência a variáveis de ambiente em qualquer string de configuração - Apenas nomes em maiúsculas são correspondidos: `[A-Z_][A-Z0-9_]*`. - Variáveis ausentes/vazias geram erro no carregamento da configuração. -- Escape com `$${VAR}` para um literal `${VAR}`. +- Escape com `$${VAR}` para um `${VAR}` literal. - Funciona com `$include`. --- -## Segredos +## Secrets Refs de segredo são aditivas: valores em texto simples continuam funcionando. @@ -3406,13 +3389,13 @@ Validação: - padrão de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` id: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`) - padrão de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- IDs de `source: "exec"` não devem conter segmentos de caminho delimitados por `/` iguais a `.` ou `..` (por exemplo `a/../b` é rejeitado) +- ids de `source: "exec"` não devem conter segmentos de caminho delimitados por `/` iguais a `.` ou `..` (por exemplo `a/../b` é rejeitado) ### Superfície de credencial compatível - Matriz canônica: [SecretRef Credential Surface](/pt-BR/reference/secretref-credential-surface) -- `secrets apply` tem como alvo caminhos de credencial compatíveis em `openclaw.json`. -- Refs de `auth-profiles.json` estão incluídas na resolução em runtime e na cobertura de auditoria. +- `secrets apply` segmenta caminhos de credencial compatíveis em `openclaw.json`. +- Refs em `auth-profiles.json` estão incluídas na resolução em runtime e na cobertura de auditoria. ### Configuração de provedores de segredo @@ -3420,7 +3403,7 @@ Validação: { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // provedor explícito opcional de ambiente filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3444,17 +3427,17 @@ Validação: Observações: -- O provedor `file` aceita `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). -- O provedor `exec` exige um caminho `command` absoluto e usa cargas do protocolo em stdin/stdout. -- Por padrão, caminhos de comando symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos symlink, validando o caminho de destino resolvido. -- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho de destino resolvido. -- O ambiente filho de `exec` é mínimo por padrão; passe explicitamente variáveis necessárias com `passEnv`. -- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória, e depois os caminhos de requisição leem apenas esse snapshot. +- O provedor `file` suporta `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). +- O provedor `exec` requer um caminho `command` absoluto e usa payloads de protocolo em stdin/stdout. +- Por padrão, caminhos de comando symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos symlink enquanto valida o caminho resolvido do destino. +- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho resolvido do destino. +- O ambiente filho de `exec` é mínimo por padrão; passe explicitamente as variáveis necessárias com `passEnv`. +- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória, e os caminhos de requisição depois leem apenas esse snapshot. - A filtragem de superfície ativa se aplica durante a ativação: refs não resolvidas em superfícies habilitadas fazem a inicialização/reload falhar, enquanto superfícies inativas são ignoradas com diagnósticos. --- -## Armazenamento de auth +## Armazenamento de autenticação ```json5 { @@ -3473,12 +3456,12 @@ Observações: ``` - Perfis por agente são armazenados em `/auth-profiles.json`. -- `auth-profiles.json` aceita refs em nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática. -- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não aceitam credenciais de perfil de auth com suporte de SecretRef. -- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são limpas quando encontradas. +- `auth-profiles.json` suporta refs no nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática. +- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não suportam credenciais de auth-profile com suporte por SecretRef. +- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são removidas quando encontradas. - Importações legadas de OAuth vêm de `~/.openclaw/credentials/oauth.json`. - Consulte [OAuth](/pt-BR/concepts/oauth). -- Comportamento do runtime de segredos e ferramentas `audit/configure/apply`: [Secrets Management](/pt-BR/gateway/secrets). +- Comportamento do runtime de Secrets e tooling `audit/configure/apply`: [Secrets Management](/pt-BR/gateway/secrets). ### `auth.cooldowns` @@ -3500,20 +3483,15 @@ Observações: } ``` -- `billingBackoffHours`: backoff base em horas quando um perfil falha por erros reais de - cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode - cair aqui mesmo em respostas `401`/`403`, mas correspondências de texto - específicas de provedor permanecem restritas ao provedor que as define (por exemplo OpenRouter - `Key limit exceeded`). Mensagens HTTP `402` retryable de janela de uso ou - limite de gasto de organização/workspace permanecem no caminho `rate_limit`. -- `billingBackoffHoursByProvider`: substituições opcionais por provedor para horas de backoff de cobrança. +- `billingBackoffHours`: backoff base em horas quando um perfil falha devido a erros reais de cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode cair aqui mesmo em respostas `401`/`403`, mas matchers de texto específicos do provedor permanecem limitados ao provedor que os possui (por exemplo OpenRouter `Key limit exceeded`). Mensagens de `402` retryable de janela de uso ou limite de gasto de organização/workspace permanecem no caminho `rate_limit`. +- `billingBackoffHoursByProvider`: sobrescritas opcionais por provedor para horas de backoff de cobrança. - `billingMaxHours`: limite em horas para crescimento exponencial do backoff de cobrança (padrão: `24`). - `authPermanentBackoffMinutes`: backoff base em minutos para falhas `auth_permanent` de alta confiança (padrão: `10`). - `authPermanentMaxMinutes`: limite em minutos para crescimento do backoff de `auth_permanent` (padrão: `60`). - `failureWindowHours`: janela móvel em horas usada para contadores de backoff (padrão: `24`). -- `overloadedProfileRotations`: máximo de rotações de perfil de auth do mesmo provedor para erros de sobrecarga antes de mudar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, caem aqui. +- `overloadedProfileRotations`: número máximo de rotações de auth-profile do mesmo provedor para erros de sobrecarga antes de alternar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, entram aqui. - `overloadedBackoffMs`: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: `0`). -- `rateLimitedProfileRotations`: máximo de rotações de perfil de auth do mesmo provedor para erros de limite de taxa antes de mudar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto com formato de provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `rateLimitedProfileRotations`: número máximo de rotações de auth-profile do mesmo provedor para erros de limite de taxa antes de alternar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto moldado pelo provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- @@ -3534,12 +3512,12 @@ Observações: - Arquivo de log padrão: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Defina `logging.file` para um caminho estável. -- `consoleLevel` sobe para `debug` quando `--verbose`. -- `maxFileBytes`: tamanho máximo do arquivo de log em bytes antes que gravações sejam suprimidas (inteiro positivo; padrão: `524288000` = 500 MB). Use rotação externa de logs para implantações de produção. +- `consoleLevel` sobe para `debug` com `--verbose`. +- `maxFileBytes`: tamanho máximo do arquivo de log em bytes antes de as gravações serem suprimidas (inteiro positivo; padrão: `524288000` = 500 MB). Use rotação externa de logs para implantações de produção. --- -## Diagnósticos +## Diagnostics ```json5 { @@ -3573,19 +3551,19 @@ Observações: ``` - `enabled`: chave mestra para saída de instrumentação (padrão: `true`). -- `flags`: array de strings de flag que habilita saída de log direcionada (oferece suporte a curingas como `"telegram.*"` ou `"*"`). -- `stuckSessionWarnMs`: limite de idade em ms para emitir avisos de sessão travada enquanto uma sessão permanece no estado de processamento. -- `otel.enabled`: habilita o pipeline de exportação do OpenTelemetry (padrão: `false`). -- `otel.endpoint`: URL do coletor para exportação OTel. +- `flags`: array de strings de flag que habilita saída de log direcionada (suporta curingas como `"telegram.*"` ou `"*"`). +- `stuckSessionWarnMs`: limite de idade em ms para emitir avisos de sessão travada enquanto uma sessão permanece em estado de processamento. +- `otel.enabled`: habilita o pipeline de exportação OpenTelemetry (padrão: `false`). +- `otel.endpoint`: URL do collector para exportação OTel. - `otel.protocol`: `"http/protobuf"` (padrão) ou `"grpc"`. -- `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com requisições de exportação OTel. +- `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com as requisições de exportação OTel. - `otel.serviceName`: nome do serviço para atributos de recurso. -- `otel.traces` / `otel.metrics` / `otel.logs`: habilitam exportação de trace, métricas ou logs. +- `otel.traces` / `otel.metrics` / `otel.logs`: habilita exportação de trace, métricas ou logs. - `otel.sampleRate`: taxa de amostragem de trace `0`–`1`. - `otel.flushIntervalMs`: intervalo periódico de flush de telemetria em ms. -- `cacheTrace.enabled`: registra snapshots de rastreamento de cache para execuções embutidas (padrão: `false`). +- `cacheTrace.enabled`: registra snapshots de rastreamento de cache para execuções incorporadas (padrão: `false`). - `cacheTrace.filePath`: caminho de saída para JSONL de rastreamento de cache (padrão: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída de rastreamento de cache (todos usam `true` como padrão). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controla o que é incluído na saída de rastreamento de cache (todos usam `true` por padrão). --- @@ -3607,12 +3585,12 @@ Observações: } ``` -- `channel`: canal de release para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. +- `channel`: canal de lançamento para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. - `checkOnStart`: verifica atualizações npm quando o gateway inicia (padrão: `true`). -- `auto.enabled`: habilita atualização automática em segundo plano para instalações por pacote (padrão: `false`). -- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máx.: `168`). -- `auto.stableJitterHours`: janela extra de distribuição de rollout do canal estável em horas (padrão: `12`; máx.: `168`). -- `auto.betaCheckIntervalHours`: frequência, em horas, das verificações no canal beta (padrão: `1`; máx.: `24`). +- `auto.enabled`: habilita atualização automática em segundo plano para instalações de pacote (padrão: `false`). +- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máximo: `168`). +- `auto.stableJitterHours`: janela extra de distribuição de rollout do canal estável em horas (padrão: `12`; máximo: `168`). +- `auto.betaCheckIntervalHours`: com que frequência verificações do canal beta são executadas em horas (padrão: `1`; máximo: `24`). --- @@ -3645,22 +3623,22 @@ Observações: } ``` -- `enabled`: chave global de recurso ACP (padrão: `false`). -- `dispatch.enabled`: chave independente para despacho de turno de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. -- `backend`: ID padrão do backend de runtime ACP (deve corresponder a um Plugin de runtime ACP registrado). -- `defaultAgent`: ID do agente ACP de fallback quando spawns não especificam um alvo explícito. +- `enabled`: feature gate global do ACP (padrão: `false`). +- `dispatch.enabled`: gate independente para despacho de turnos de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. +- `backend`: ID padrão do backend de runtime ACP (deve corresponder a um plugin de runtime ACP registrado). +- `defaultAgent`: ID de agente ACP de fallback quando spawns não especificam um destino explícito. - `allowedAgents`: allowlist de IDs de agente permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional. - `maxConcurrentSessions`: máximo de sessões ACP ativas simultaneamente. -- `stream.coalesceIdleMs`: janela de flush por inatividade em ms para texto transmitido. -- `stream.maxChunkChars`: tamanho máximo de bloco antes da divisão da projeção do bloco transmitido. +- `stream.coalesceIdleMs`: janela de flush por ociosidade em ms para texto em streaming. +- `stream.maxChunkChars`: tamanho máximo do chunk antes de dividir a projeção de bloco transmitido. - `stream.repeatSuppression`: suprime linhas repetidas de status/ferramenta por turno (padrão: `true`). - `stream.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` faz buffer até eventos terminais do turno. - `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos ocultos de ferramenta (padrão: `"paragraph"`). - `stream.maxOutputChars`: máximo de caracteres de saída do assistente projetados por turno ACP. - `stream.maxSessionUpdateChars`: máximo de caracteres para linhas projetadas de status/atualização ACP. -- `stream.tagVisibility`: registro de nomes de tag para substituições booleanas de visibilidade em eventos transmitidos. -- `runtime.ttlMinutes`: TTL de inatividade em minutos para workers de sessão ACP antes de ficarem elegíveis para limpeza. -- `runtime.installCommand`: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP. +- `stream.tagVisibility`: registro de nomes de tag para sobrescritas booleanas de visibilidade em eventos transmitidos. +- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de ficarem elegíveis para limpeza. +- `runtime.installCommand`: comando de instalação opcional para executar ao inicializar um ambiente de runtime ACP. --- @@ -3677,9 +3655,9 @@ Observações: ``` - `cli.banner.taglineMode` controla o estilo da tagline do banner: - - `"random"` (padrão): taglines rotativas engraçadas/sazonais. + - `"random"` (padrão): taglines engraçadas/sazonais rotativas. - `"default"`: tagline neutra fixa (`All your chats, one OpenClaw.`). - - `"off"`: sem texto de tagline (título/versão do banner continuam visíveis). + - `"off"`: sem texto de tagline (o título/versão do banner ainda é mostrado). - Para ocultar o banner inteiro (não apenas taglines), defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. --- @@ -3710,7 +3688,7 @@ Consulte os campos de identidade em `agents.list` em [Padrões de agente](#agent ## Bridge (legado, removido) -As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. Chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até serem removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). +As versões atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. As chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até que sejam removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). @@ -3739,22 +3717,22 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // fallback legado obsoleto para trabalhos armazenados com notify:true + webhookToken: "replace-with-dedicated-token", // token bearer opcional para autenticação de webhook de saída + sessionRetention: "24h", // string de duração ou false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // padrão 2_000_000 bytes + keepLines: 2000, // padrão 2000 }, }, } ``` -- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções isoladas de Cron antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas e excluídas de Cron. Padrão: `24h`; defina `false` para desabilitar. -- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da remoção. Padrão: `2_000_000` bytes. -- `runLog.keepLines`: linhas mais recentes mantidas quando a remoção do log de execução é disparada. Padrão: `2000`. -- `webhookToken`: token bearer usado para entrega POST de Webhook do Cron (`delivery.mode = "webhook"`); se omitido, nenhum cabeçalho de auth é enviado. -- `webhook`: URL de Webhook de fallback legada e obsoleta (http/https), usada apenas para jobs armazenados que ainda tenham `notify: true`. +- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções isoladas de Cron antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas deletadas de Cron. Padrão: `24h`; defina `false` para desabilitar. +- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da poda. Padrão: `2_000_000` bytes. +- `runLog.keepLines`: linhas mais recentes retidas quando a poda do log de execução é acionada. Padrão: `2000`. +- `webhookToken`: token bearer usado para entrega POST de webhook do Cron (`delivery.mode = "webhook"`); se omitido, nenhum cabeçalho de autenticação é enviado. +- `webhook`: URL de webhook de fallback legado obsoleta (http/https) usada apenas para trabalhos armazenados que ainda tenham `notify: true`. ### `cron.retry` @@ -3770,11 +3748,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke } ``` -- `maxAttempts`: máximo de tentativas para jobs de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`). -- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de retry (padrão: `[30000, 60000, 300000]`; 1–10 entradas). +- `maxAttempts`: máximo de retries para trabalhos pontuais em erros transitórios (padrão: `3`; intervalo: `0`–`10`). +- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de retry (padrão: `[30000, 60000, 300000]`; de 1 a 10 entradas). - `retryOn`: tipos de erro que disparam retries — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para tentar novamente todos os tipos transitórios. -Aplica-se apenas a jobs de Cron de execução única. Jobs recorrentes usam tratamento de falha separado. +Aplica-se apenas a trabalhos pontuais de Cron. Trabalhos recorrentes usam tratamento de falha separado. ### `cron.failureAlert` @@ -3792,11 +3770,11 @@ Aplica-se apenas a jobs de Cron de execução única. Jobs recorrentes usam trat } ``` -- `enabled`: habilita alertas de falha para jobs de Cron (padrão: `false`). -- `after`: falhas consecutivas antes de disparar um alerta (inteiro positivo, mín.: `1`). -- `cooldownMs`: milissegundos mínimos entre alertas repetidos para o mesmo job (inteiro não negativo). -- `mode`: modo de entrega — `"announce"` envia por mensagem de canal; `"webhook"` publica no Webhook configurado. -- `accountId`: ID opcional de conta ou canal para delimitar a entrega do alerta. +- `enabled`: habilita alertas de falha para trabalhos de Cron (padrão: `false`). +- `after`: falhas consecutivas antes que um alerta seja disparado (inteiro positivo, mín: `1`). +- `cooldownMs`: milissegundos mínimos entre alertas repetidos para o mesmo trabalho (inteiro não negativo). +- `mode`: modo de entrega — `"announce"` envia por mensagem de canal; `"webhook"` publica no webhook configurado. +- `accountId`: ID opcional de conta ou canal para definir o escopo da entrega do alerta. ### `cron.failureDestination` @@ -3813,14 +3791,14 @@ Aplica-se apenas a jobs de Cron de execução única. Jobs recorrentes usam trat } ``` -- Destino padrão para notificações de falha de Cron em todos os jobs. -- `mode`: `"announce"` ou `"webhook"`; usa `"announce"` como padrão quando existem dados de destino suficientes. -- `channel`: substituição de canal para entrega por announce. `"last"` reutiliza o último canal de entrega conhecido. -- `to`: alvo explícito de announce ou URL de Webhook. Obrigatório para o modo webhook. -- `accountId`: substituição opcional de conta para entrega. -- `delivery.failureDestination` por job substitui esse padrão global. -- Quando nem o destino global nem o destino por job de falha estão definidos, jobs que já entregam via `announce` usam como fallback esse alvo principal de announce em caso de falha. -- `delivery.failureDestination` só é compatível com jobs `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do job seja `"webhook"`. +- Destino padrão para notificações de falha de Cron em todos os trabalhos. +- `mode`: `"announce"` ou `"webhook"`; usa `"announce"` por padrão quando existem dados de destino suficientes. +- `channel`: sobrescrita de canal para entrega por anúncio. `"last"` reutiliza o último canal de entrega conhecido. +- `to`: destino explícito de anúncio ou URL de webhook. Obrigatório para modo webhook. +- `accountId`: sobrescrita opcional de conta para entrega. +- `delivery.failureDestination` por trabalho sobrescreve esse padrão global. +- Quando nem o destino global nem o por trabalho está definido, trabalhos que já entregam via `announce` usam esse destino principal de anúncio como fallback em caso de falha. +- `delivery.failureDestination` só é compatível com trabalhos `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do trabalho seja `"webhook"`. Consulte [Cron Jobs](/pt-BR/automation/cron-jobs). Execuções isoladas de Cron são rastreadas como [background tasks](/pt-BR/automation/tasks). @@ -3830,28 +3808,28 @@ Consulte [Cron Jobs](/pt-BR/automation/cron-jobs). Execuções isoladas de Cron Placeholders de template expandidos em `tools.media.models[].args`: -| Variável | Descrição | -| ------------------ | ----------------------------------------------- | -| `{{Body}}` | Corpo completo da mensagem recebida | +| Variável | Descrição | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | Corpo completo da mensagem recebida | | `{{RawBody}}` | Corpo bruto (sem wrappers de histórico/remetente) | -| `{{BodyStripped}}` | Corpo com menções de grupo removidas | -| `{{From}}` | Identificador do remetente | -| `{{To}}` | Identificador de destino | -| `{{MessageSid}}` | ID da mensagem do canal | -| `{{SessionId}}` | UUID da sessão atual | -| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | -| `{{MediaUrl}}` | pseudo-URL da mídia recebida | -| `{{MediaPath}}` | caminho local da mídia | -| `{{MediaType}}` | tipo de mídia (image/audio/document/…) | -| `{{Transcript}}` | transcrição do áudio | -| `{{Prompt}}` | prompt de mídia resolvido para entradas de CLI | -| `{{MaxChars}}` | máximo de caracteres de saída resolvido para entradas de CLI | -| `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | assunto do grupo (melhor esforço) | -| `{{GroupMembers}}` | prévia dos membros do grupo (melhor esforço) | -| `{{SenderName}}` | nome de exibição do remetente (melhor esforço) | -| `{{SenderE164}}` | número de telefone do remetente (melhor esforço) | -| `{{Provider}}` | dica de provedor (whatsapp, telegram, discord etc.) | +| `{{BodyStripped}}` | Corpo com menções de grupo removidas | +| `{{From}}` | Identificador do remetente | +| `{{To}}` | Identificador do destino | +| `{{MessageSid}}` | ID da mensagem do canal | +| `{{SessionId}}` | UUID da sessão atual | +| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | +| `{{MediaUrl}}` | pseudo-URL da mídia recebida | +| `{{MediaPath}}` | caminho local da mídia | +| `{{MediaType}}` | tipo da mídia (image/audio/document/…) | +| `{{Transcript}}` | transcrição de áudio | +| `{{Prompt}}` | prompt de mídia resolvido para entradas CLI | +| `{{MaxChars}}` | máximo de caracteres de saída resolvido para entradas CLI | +| `{{ChatType}}` | `"direct"` ou `"group"` | +| `{{GroupSubject}}` | assunto do grupo (best effort) | +| `{{GroupMembers}}` | prévia dos membros do grupo (best effort) | +| `{{SenderName}}` | nome de exibição do remetente (best effort) | +| `{{SenderE164}}` | número de telefone do remetente (best effort) | +| `{{Provider}}` | dica do provedor (whatsapp, telegram, discord etc.) | --- @@ -3873,11 +3851,11 @@ Divida a configuração em vários arquivos: **Comportamento de mesclagem:** - Arquivo único: substitui o objeto contêiner. -- Array de arquivos: mesclado profundamente em ordem (os posteriores substituem os anteriores). -- Chaves irmãs: mescladas após os includes (substituem os valores incluídos). +- Array de arquivos: mesclado profundamente em ordem (os posteriores sobrescrevem os anteriores). +- Chaves irmãs: mescladas após os includes (sobrescrevem os valores incluídos). - Includes aninhados: até 10 níveis de profundidade. -- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formatos absolutos/`../` são permitidos apenas quando ainda resolvem dentro desse limite. -- Erros: mensagens claras para arquivos ausentes, erros de parse e includes circulares. +- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas apenas quando ainda resolvem dentro desse limite. +- Erros: mensagens claras para arquivos ausentes, erros de parsing e includes circulares. --- diff --git a/docs/pt-BR/gateway/protocol.md b/docs/pt-BR/gateway/protocol.md index 285d609b8..2c601aef0 100644 --- a/docs/pt-BR/gateway/protocol.md +++ b/docs/pt-BR/gateway/protocol.md @@ -2,23 +2,23 @@ read_when: - Implementando ou atualizando clientes WS do Gateway - Depurando incompatibilidades de protocolo ou falhas de conexão - - Regenerando esquema/modelos de protocolo -summary: 'Protocolo WebSocket do Gateway: handshake, frames, controle de versão' + - Regenerando schema/modelos do protocolo +summary: 'Protocolo WebSocket do Gateway: handshake, frames, versionamento' title: Protocolo do Gateway x-i18n: - generated_at: "2026-04-16T05:37:37Z" + generated_at: "2026-04-18T05:24:49Z" model: gpt-5.4 provider: openai - source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3 + source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41 source_path: gateway/protocol.md workflow: 15 --- # Protocolo do Gateway (WebSocket) -O protocolo WS do Gateway é o **plano de controle único + transporte de nós** do -OpenClaw. Todos os clientes (CLI, interface web, app para macOS, nós iOS/Android, -nós headless) se conectam por WebSocket e declaram seu **papel** + **escopo** no +O protocolo WS do Gateway é o **plano de controle único + transporte de Node** para o +OpenClaw. Todos os clientes (CLI, interface web, app macOS, Nodes iOS/Android, +Nodes headless) se conectam por WebSocket e declaram seu **papel** + **escopo** no momento do handshake. ## Transporte @@ -26,7 +26,7 @@ momento do handshake. - WebSocket, frames de texto com payloads JSON. - O primeiro frame **deve** ser uma requisição `connect`. -## Handshake (connect) +## Handshake (`connect`) Gateway → Cliente (desafio pré-conexão): @@ -95,8 +95,22 @@ Gateway → Cliente: } ``` -`server`, `features`, `snapshot` e `policy` são todos obrigatórios pelo esquema -(`src/gateway/protocol/schema/frames.ts`). `auth` e `canvasHostUrl` são opcionais. +`server`, `features`, `snapshot` e `policy` são todos obrigatórios pelo schema +(`src/gateway/protocol/schema/frames.ts`). `canvasHostUrl` é opcional. `auth` +informa o papel/escopos negociados quando disponíveis, e inclui `deviceToken` +quando o gateway emite um. + +Quando nenhum token de dispositivo é emitido, `hello-ok.auth` ainda pode informar as +permissões negociadas: + +```json +{ + "auth": { + "role": "operator", + "scopes": ["operator.read", "operator.write"] + } +} +``` Quando um token de dispositivo é emitido, `hello-ok` também inclui: @@ -110,8 +124,8 @@ Quando um token de dispositivo é emitido, `hello-ok` também inclui: } ``` -Durante a transferência confiável de bootstrap, `hello-ok.auth` também pode incluir -entradas de papel adicionais delimitadas em `deviceTokens`: +Durante o handoff de bootstrap confiável, `hello-ok.auth` também pode incluir +entradas de papel adicionais limitadas em `deviceTokens`: ```json { @@ -130,14 +144,14 @@ entradas de papel adicionais delimitadas em `deviceTokens`: } ``` -Para o fluxo de bootstrap integrado de node/operator, o token principal do nó permanece com -`scopes: []` e qualquer token de operador transferido permanece delimitado à allowlist -do operador de bootstrap (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). As verificações de escopo do bootstrap continuam -prefixadas por papel: entradas de operador só satisfazem requisições de operador, e papéis -não operadores ainda precisam de escopos sob o prefixo do seu próprio papel. +Para o fluxo de bootstrap integrado de node/operator, o token primário do node continua com +`scopes: []` e qualquer token de operador transferido continua limitado à allowlist do +operador de bootstrap (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). As verificações de escopo de bootstrap continuam +com prefixo por papel: entradas de operador só satisfazem requisições de operador, e +papéis que não são operador ainda precisam de escopos sob o prefixo do próprio papel. -### Exemplo de nó +### Exemplo de Node ```json { @@ -178,13 +192,13 @@ não operadores ainda precisam de escopos sob o prefixo do seu próprio papel. - **Resposta**: `{type:"res", id, ok, payload|error}` - **Evento**: `{type:"event", event, payload, seq?, stateVersion?}` -Métodos com efeitos colaterais exigem **chaves de idempotência** (veja o esquema). +Métodos com efeitos colaterais exigem **chaves de idempotência** (veja o schema). ## Papéis + escopos ### Papéis -- `operator` = cliente do plano de controle (CLI/interface/automação). +- `operator` = cliente do plano de controle (CLI/UI/automação). - `node` = host de capacidades (camera/screen/canvas/system.run). ### Escopos (operator) @@ -201,70 +215,70 @@ Escopos comuns: `talk.config` com `includeSecrets: true` exige `operator.talk.secrets` (ou `operator.admin`). -Métodos RPC do Gateway registrados por Plugin podem solicitar seu próprio escopo de operator, mas -prefixos administrativos reservados do núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, +Métodos RPC do gateway registrados por Plugin podem solicitar seu próprio escopo de operador, mas +os prefixos admin centrais reservados (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) sempre são resolvidos para `operator.admin`. -O escopo do método é apenas o primeiro controle. Alguns comandos slash acessados por -`chat.send` aplicam verificações em nível de comando mais restritas além disso. Por exemplo, escritas -persistentes de `/config set` e `/config unset` exigem `operator.admin`. +O escopo do método é apenas a primeira barreira. Alguns comandos slash acessados por +`chat.send` aplicam verificações em nível de comando mais rígidas por cima. Por exemplo, +gravações persistentes com `/config set` e `/config unset` exigem `operator.admin`. -`node.pair.approve` também tem uma verificação de escopo adicional no momento da aprovação além do -escopo base do método: +`node.pair.approve` também tem uma verificação extra de escopo no momento da aprovação, +além do escopo base do método: - requisições sem comando: `operator.pairing` -- requisições com comandos de nó sem exec: `operator.pairing` + `operator.write` +- requisições com comandos de node que não são exec: `operator.pairing` + `operator.write` - requisições que incluem `system.run`, `system.run.prepare` ou `system.which`: `operator.pairing` + `operator.admin` ### Caps/commands/permissions (node) -Nós declaram reivindicações de capacidade no momento da conexão: +Nodes declaram claims de capacidade no momento da conexão: - `caps`: categorias de capacidade de alto nível. - `commands`: allowlist de comandos para invoke. - `permissions`: toggles granulares (por exemplo, `screen.record`, `camera.capture`). -O Gateway trata isso como **reivindicações** e aplica allowlists no lado do servidor. +O Gateway trata isso como **claims** e aplica allowlists no lado do servidor. ## Presença - `system-presence` retorna entradas indexadas pela identidade do dispositivo. -- As entradas de presença incluem `deviceId`, `roles` e `scopes` para que as interfaces possam mostrar uma única linha por dispositivo - mesmo quando ele se conecta como **operator** e **node** ao mesmo tempo. +- As entradas de presença incluem `deviceId`, `roles` e `scopes`, para que as UIs possam mostrar uma única linha por dispositivo + mesmo quando ele se conecta tanto como **operator** quanto como **node**. ## Famílias comuns de métodos RPC Esta página não é um dump completo gerado, mas a superfície WS pública é mais ampla -do que os exemplos de handshake/auth acima. Estas são as principais famílias de métodos que -o Gateway expõe atualmente. +do que os exemplos de handshake/autenticação acima. Estas são as principais famílias de métodos que +o Gateway expõe hoje. -`hello-ok.features.methods` é uma lista conservadora de descoberta construída a partir de -`src/gateway/server-methods-list.ts` mais as exportações de métodos de plugins/canais carregados. -Trate isso como descoberta de recursos, não como um dump gerado de todos os helpers chamáveis +`hello-ok.features.methods` é uma lista de descoberta conservadora construída a partir de +`src/gateway/server-methods-list.ts` mais exportações de métodos de plugins/canais carregados. +Trate-a como descoberta de recursos, não como um dump gerado de todos os helpers chamáveis implementados em `src/gateway/server-methods/*.ts`. ### Sistema e identidade -- `health` retorna o snapshot de saúde do gateway em cache ou recém-sondado. +- `health` retorna o snapshot de integridade do gateway em cache ou recém-verificado. - `status` retorna o resumo do gateway no estilo `/status`; campos sensíveis são - incluídos apenas para clientes operator com escopo de admin. -- `gateway.identity.get` retorna a identidade do dispositivo do gateway usada pelos fluxos de relay e - pareamento. -- `system-presence` retorna o snapshot de presença atual para dispositivos + incluídos apenas para clientes operator com escopo admin. +- `gateway.identity.get` retorna a identidade de dispositivo do gateway usada por fluxos de relay e + emparelhamento. +- `system-presence` retorna o snapshot atual de presença dos dispositivos operator/node conectados. -- `system-event` acrescenta um evento de sistema e pode atualizar/transmitir contexto +- `system-event` anexa um evento de sistema e pode atualizar/transmitir o contexto de presença. - `last-heartbeat` retorna o evento Heartbeat persistido mais recente. -- `set-heartbeats` ativa ou desativa o processamento de Heartbeat no gateway. +- `set-heartbeats` alterna o processamento de Heartbeat no gateway. ### Modelos e uso -- `models.list` retorna o catálogo de modelos permitido em tempo de execução. -- `usage.status` retorna janelas de uso do provedor/resumos de cota restante. +- `models.list` retorna o catálogo de modelos permitido em runtime. +- `usage.status` retorna resumos de janelas de uso de provider/cota restante. - `usage.cost` retorna resumos agregados de uso de custo para um intervalo de datas. - `doctor.memory.status` retorna a prontidão de memória vetorial / embeddings para o - workspace padrão ativo do agente. + workspace do agente padrão ativo. - `sessions.usage` retorna resumos de uso por sessão. - `sessions.usage.timeseries` retorna séries temporais de uso para uma sessão. - `sessions.usage.logs` retorna entradas de log de uso para uma sessão. @@ -272,76 +286,76 @@ implementados em `src/gateway/server-methods/*.ts`. ### Canais e helpers de login - `channels.status` retorna resumos de status de canais/plugins integrados + empacotados. -- `channels.logout` desconecta uma conta/canal específico quando o canal +- `channels.logout` faz logout de um canal/conta específico quando o canal oferece suporte a logout. -- `web.login.start` inicia um fluxo de login por QR/web para o provedor de canal web - atual com suporte a QR. -- `web.login.wait` aguarda a conclusão desse fluxo de login por QR/web e inicia o +- `web.login.start` inicia um fluxo de login QR/web para o provider de canal web com suporte a QR atual. +- `web.login.wait` aguarda a conclusão desse fluxo de login QR/web e inicia o canal em caso de sucesso. -- `push.test` envia um push APNs de teste para um nó iOS registrado. -- `voicewake.get` retorna os gatilhos de palavra de ativação armazenados. -- `voicewake.set` atualiza os gatilhos de palavra de ativação e transmite a alteração. +- `push.test` envia um push APNs de teste para um node iOS registrado. +- `voicewake.get` retorna os triggers de wake-word armazenados. +- `voicewake.set` atualiza os triggers de wake-word e transmite a alteração. -### Mensageria e logs +### Mensagens e logs -- `send` é o RPC direto de entrega de saída para envios direcionados por canal/conta/thread - fora do executor de chat. -- `logs.tail` retorna a cauda configurada dos logs de arquivo do gateway com cursor/limite e +- `send` é o RPC direto de entrega de saída para envios direcionados a + canal/conta/thread fora do executor de chat. +- `logs.tail` retorna o tail configurado do log de arquivo do gateway com cursor/limite e controles de bytes máximos. ### Talk e TTS -- `talk.config` retorna o payload efetivo de configuração do Talk; `includeSecrets` +- `talk.config` retorna o payload efetivo de configuração de Talk; `includeSecrets` exige `operator.talk.secrets` (ou `operator.admin`). - `talk.mode` define/transmite o estado atual do modo Talk para clientes WebChat/Control UI. -- `talk.speak` sintetiza fala por meio do provedor de fala Talk ativo. -- `tts.status` retorna o estado de ativação do TTS, provedor ativo, provedores de fallback, - e o estado de configuração do provedor. -- `tts.providers` retorna o inventário visível de provedores de TTS. +- `talk.speak` sintetiza fala por meio do provider de fala de Talk ativo. +- `tts.status` retorna o estado habilitado de TTS, provider ativo, providers de fallback + e o estado de configuração do provider. +- `tts.providers` retorna o inventário visível de providers de TTS. - `tts.enable` e `tts.disable` alternam o estado das preferências de TTS. -- `tts.setProvider` atualiza o provedor de TTS preferido. -- `tts.convert` executa conversão pontual de texto para fala. +- `tts.setProvider` atualiza o provider de TTS preferido. +- `tts.convert` executa uma conversão avulsa de texto para fala. -### Secrets, config, update e wizard +### Segredos, configuração, update e wizard -- `secrets.reload` resolve novamente os SecretRefs ativos e troca o estado de segredos em tempo de execução +- `secrets.reload` resolve novamente SecretRefs ativas e substitui o estado de segredo em runtime apenas em caso de sucesso completo. -- `secrets.resolve` resolve atribuições de segredos direcionadas a comandos para um conjunto específico - de comando/alvo. -- `config.get` retorna o snapshot e hash da configuração atual. +- `secrets.resolve` resolve atribuições de segredos de destino de comando para um + conjunto específico de comando/destino. +- `config.get` retorna o snapshot e o hash da configuração atual. - `config.set` grava um payload de configuração validado. - `config.patch` mescla uma atualização parcial de configuração. - `config.apply` valida + substitui o payload completo de configuração. -- `config.schema` retorna o payload do esquema de configuração em tempo de execução usado pela Control UI e - pelas ferramentas de CLI: esquema, `uiHints`, versão e metadados de geração, incluindo - metadados de esquema de plugins + canais quando o runtime pode carregá-los. O esquema +- `config.schema` retorna o payload do schema de configuração ativo usado pela Control UI e + por ferramentas de CLI: schema, `uiHints`, versão e metadados de geração, incluindo + metadados de schema de plugin + canal quando o runtime consegue carregá-los. O schema inclui metadados de campo `title` / `description` derivados dos mesmos rótulos - e textos de ajuda usados pela interface, incluindo ramificações aninhadas de objeto, curinga, item de array - e composição `anyOf` / `oneOf` / `allOf` quando existe documentação de campo correspondente. -- `config.schema.lookup` retorna um payload de consulta com escopo de caminho para um caminho de configuração: - caminho normalizado, um nó raso do esquema, `hint` correspondente + `hintPath`, e - resumos imediatos dos filhos para detalhamento na interface/CLI. - - Nós de esquema de consulta mantêm a documentação voltada ao usuário e campos comuns de validação: + e textos de ajuda usados pela UI, incluindo objeto aninhado, curinga, item de array + e ramificações de composição `anyOf` / `oneOf` / `allOf` quando existe + documentação de campo correspondente. +- `config.schema.lookup` retorna um payload de lookup com escopo de caminho para um + caminho de configuração: caminho normalizado, um nó de schema raso, a dica correspondente + `hintPath`, e + resumos imediatos dos filhos para drill-down de UI/CLI. + - Os nós de schema do lookup mantêm a documentação voltada ao usuário e os campos comuns de validação: `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, limites numéricos/de string/de array/de objeto e flags booleanas como `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. - - Resumos de filhos expõem `key`, `path` normalizado, `type`, `required`, - `hasChildren`, além do `hint` / `hintPath` correspondente. -- `update.run` executa o fluxo de atualização do gateway e agenda uma reinicialização apenas quando - a própria atualização foi bem-sucedida. + - Os resumos de filhos expõem `key`, `path` normalizado, `type`, `required`, + `hasChildren`, além da `hint` / `hintPath` correspondente. +- `update.run` executa o fluxo de update do gateway e agenda um reinício apenas quando + o próprio update foi bem-sucedido. - `wizard.start`, `wizard.next`, `wizard.status` e `wizard.cancel` expõem o - assistente de onboarding por WS RPC. + wizard de onboarding por RPC WS. ### Famílias principais existentes #### Helpers de agente e workspace -- `agents.list` retorna entradas de agentes configuradas. -- `agents.create`, `agents.update` e `agents.delete` gerenciam registros de agentes e - a ligação com o workspace. +- `agents.list` retorna entradas de agentes configurados. +- `agents.create`, `agents.update` e `agents.delete` gerenciam registros de agente e + o wiring do workspace. - `agents.files.list`, `agents.files.get` e `agents.files.set` gerenciam os - arquivos do workspace de bootstrap expostos para um agente. + arquivos de workspace de bootstrap expostos para um agente. - `agent.identity.get` retorna a identidade efetiva do assistente para um agente ou sessão. - `agent.wait` aguarda a conclusão de uma execução e retorna o snapshot terminal quando @@ -350,66 +364,66 @@ implementados em `src/gateway/server-methods/*.ts`. #### Controle de sessão - `sessions.list` retorna o índice atual de sessões. -- `sessions.subscribe` e `sessions.unsubscribe` ativam ou desativam assinaturas de eventos - de mudança de sessão para o cliente WS atual. -- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` ativam ou desativam - assinaturas de eventos de transcrição/mensagens para uma sessão. -- `sessions.preview` retorna prévias delimitadas da transcrição para chaves específicas - de sessão. -- `sessions.resolve` resolve ou canonicaliza um destino de sessão. +- `sessions.subscribe` e `sessions.unsubscribe` alternam inscrições em eventos de alteração de sessão + para o cliente WS atual. +- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` alternam + inscrições em eventos de transcrição/mensagem para uma sessão. +- `sessions.preview` retorna prévias de transcrição limitadas para chaves de sessão + específicas. +- `sessions.resolve` resolve ou canonicaliza um alvo de sessão. - `sessions.create` cria uma nova entrada de sessão. - `sessions.send` envia uma mensagem para uma sessão existente. -- `sessions.steer` é a variante de interrupção e redirecionamento para uma sessão ativa. +- `sessions.steer` é a variante de interromper e redirecionar para uma sessão ativa. - `sessions.abort` aborta o trabalho ativo de uma sessão. - `sessions.patch` atualiza metadados/substituições de sessão. -- `sessions.reset`, `sessions.delete` e `sessions.compact` executam manutenção - da sessão. -- `sessions.get` retorna a linha completa armazenada da sessão. +- `sessions.reset`, `sessions.delete` e `sessions.compact` executam manutenção de + sessão. +- `sessions.get` retorna a linha completa da sessão armazenada. - a execução de chat ainda usa `chat.history`, `chat.send`, `chat.abort` e `chat.inject`. -- `chat.history` é normalizado para exibição para clientes de interface: tags de diretiva inline são +- `chat.history` é normalizado para exibição para clientes de UI: tags de diretiva inline são removidas do texto visível, payloads XML de chamada de ferramenta em texto simples (incluindo `...`, `...`, `...`, `...` e - blocos truncados de chamada de ferramenta) e tokens de controle do modelo ASCII/full-width vazados - são removidos, linhas de assistente compostas apenas por tokens silenciosos, como `NO_REPLY` / + blocos truncados de chamada de ferramenta) e tokens de controle do modelo em ASCII/largura total que vazaram + são removidos, linhas do assistente compostas apenas por tokens silenciosos, como `NO_REPLY` / `no_reply` exatos, são omitidas, e linhas grandes demais podem ser substituídas por placeholders. -#### Pareamento de dispositivos e tokens de dispositivo +#### Emparelhamento de dispositivo e tokens de dispositivo -- `device.pair.list` retorna dispositivos pareados pendentes e aprovados. +- `device.pair.list` retorna dispositivos emparelhados pendentes e aprovados. - `device.pair.approve`, `device.pair.reject` e `device.pair.remove` gerenciam - registros de pareamento de dispositivos. -- `device.token.rotate` rotaciona um token de dispositivo pareado dentro dos limites - aprovados de papel e escopo. -- `device.token.revoke` revoga um token de dispositivo pareado. + registros de emparelhamento de dispositivo. +- `device.token.rotate` rotaciona um token de dispositivo emparelhado dentro dos limites aprovados de + papel e escopo. +- `device.token.revoke` revoga um token de dispositivo emparelhado. -#### Pareamento de nós, invoke e trabalho pendente +#### Emparelhamento de node, invoke e trabalho pendente - `node.pair.request`, `node.pair.list`, `node.pair.approve`, - `node.pair.reject` e `node.pair.verify` cobrem pareamento de nós e verificação - de bootstrap. -- `node.list` e `node.describe` retornam o estado conhecido/conectado dos nós. -- `node.rename` atualiza um rótulo de nó pareado. -- `node.invoke` encaminha um comando para um nó conectado. + `node.pair.reject` e `node.pair.verify` cobrem o emparelhamento de node e a + verificação de bootstrap. +- `node.list` e `node.describe` retornam o estado conhecido/conectado de nodes. +- `node.rename` atualiza um rótulo de node emparelhado. +- `node.invoke` encaminha um comando para um node conectado. - `node.invoke.result` retorna o resultado de uma requisição invoke. -- `node.event` transporta eventos originados no nó de volta para o gateway. +- `node.event` carrega eventos originados no node de volta para o gateway. - `node.canvas.capability.refresh` atualiza tokens de capacidade de canvas com escopo. -- `node.pending.pull` e `node.pending.ack` são as APIs de fila de nós conectados. +- `node.pending.pull` e `node.pending.ack` são as APIs de fila de node conectado. - `node.pending.enqueue` e `node.pending.drain` gerenciam trabalho pendente durável - para nós offline/desconectados. + para nodes offline/desconectados. #### Famílias de aprovação - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` e - `exec.approval.resolve` cobrem requisições pontuais de aprovação de exec, além de - consulta/reexecução de aprovações pendentes. + `exec.approval.resolve` cobrem requisições avulsas de aprovação de exec mais + lookup/replay de aprovação pendente. - `exec.approval.waitDecision` aguarda uma aprovação pendente de exec e retorna a decisão final (ou `null` em caso de timeout). -- `exec.approvals.get` e `exec.approvals.set` gerenciam snapshots da política de aprovação - de exec do gateway. -- `exec.approvals.node.get` e `exec.approvals.node.set` gerenciam a política local de exec - do nó via comandos de relay do nó. +- `exec.approvals.get` e `exec.approvals.set` gerenciam snapshots da política de + aprovação de exec do gateway. +- `exec.approvals.node.get` e `exec.approvals.node.set` gerenciam a política local de exec do node + por meio de comandos de relay do node. - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` e `plugin.approval.resolve` cobrem fluxos de aprovação definidos por Plugin. @@ -417,235 +431,239 @@ implementados em `src/gateway/server-methods/*.ts`. #### Outras famílias principais - automação: - - `wake` agenda uma injeção de texto imediata ou no próximo Heartbeat + - `wake` agenda uma injeção de texto de wake imediata ou no próximo Heartbeat - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` - skills/ferramentas: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective` ### Famílias comuns de eventos -- `chat`: atualizações de chat da interface, como `chat.inject` e outros eventos - de chat apenas de transcrição. +- `chat`: atualizações de chat da UI, como `chat.inject` e outros eventos de chat + apenas de transcrição. - `session.message` e `session.tool`: atualizações de transcrição/fluxo de eventos para uma - sessão assinada. -- `sessions.changed`: o índice ou os metadados da sessão mudaram. + sessão inscrita. +- `sessions.changed`: o índice de sessões ou metadados mudaram. - `presence`: atualizações do snapshot de presença do sistema. - `tick`: evento periódico de keepalive / vivacidade. -- `health`: atualização do snapshot de saúde do gateway. -- `heartbeat`: atualização do fluxo de eventos Heartbeat. -- `cron`: evento de mudança de execução/trabalho do cron. +- `health`: atualização do snapshot de integridade do gateway. +- `heartbeat`: atualização do fluxo de eventos de Heartbeat. +- `cron`: evento de alteração de execução/job do Cron. - `shutdown`: notificação de desligamento do gateway. -- `node.pair.requested` / `node.pair.resolved`: ciclo de vida do pareamento de nós. -- `node.invoke.request`: transmissão da requisição invoke de nó. -- `device.pair.requested` / `device.pair.resolved`: ciclo de vida do dispositivo pareado. -- `voicewake.changed`: a configuração do gatilho de palavra de ativação mudou. -- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida da aprovação - de exec. +- `node.pair.requested` / `node.pair.resolved`: ciclo de vida do emparelhamento de node. +- `node.invoke.request`: transmissão da requisição invoke do node. +- `device.pair.requested` / `device.pair.resolved`: ciclo de vida do dispositivo emparelhado. +- `voicewake.changed`: a configuração de triggers de wake-word mudou. +- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida da + aprovação de exec. - `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida da aprovação de Plugin. -### Métodos helper de nó +### Métodos helper de node -- Nós podem chamar `skills.bins` para buscar a lista atual de executáveis de skill +- Nodes podem chamar `skills.bins` para buscar a lista atual de executáveis de skill para verificações de auto-allow. ### Métodos helper de operator - Operators podem chamar `commands.list` (`operator.read`) para buscar o inventário de comandos em runtime para um agente. - - `agentId` é opcional; omita-o para ler o workspace padrão do agente. + - `agentId` é opcional; omita-o para ler o workspace do agente padrão. - `scope` controla qual superfície o `name` primário segmenta: - `text` retorna o token primário do comando de texto sem a `/` inicial - - `native` e o caminho padrão `both` retornam nomes nativos sensíveis ao provedor + - `native` e o caminho padrão `both` retornam nomes nativos sensíveis ao provider quando disponíveis - `textAliases` carrega aliases slash exatos, como `/model` e `/m`. - - `nativeName` carrega o nome nativo sensível ao provedor quando ele existe. - - `provider` é opcional e afeta apenas a nomenclatura nativa mais a disponibilidade - de comandos nativos de Plugin. - - `includeArgs=false` omite metadados serializados de argumentos da resposta. -- Operators podem chamar `tools.catalog` (`operator.read`) para buscar o catálogo de ferramentas em runtime para um - agente. A resposta inclui ferramentas agrupadas e metadados de procedência: + - `nativeName` carrega o nome nativo sensível ao provider quando ele existe. + - `provider` é opcional e afeta apenas a nomenclatura nativa mais a disponibilidade de + comandos nativos de Plugin. + - `includeArgs=false` omite metadados de argumentos serializados da resposta. +- Operators podem chamar `tools.catalog` (`operator.read`) para buscar o catálogo de ferramentas em runtime de um + agente. A resposta inclui ferramentas agrupadas e metadados de proveniência: - `source`: `core` ou `plugin` - - `pluginId`: proprietário do Plugin quando `source="plugin"` - - `optional`: se uma ferramenta de Plugin é opcional -- Operators podem chamar `tools.effective` (`operator.read`) para buscar o inventário efetivo de ferramentas em runtime - para uma sessão. + - `pluginId`: owner do plugin quando `source="plugin"` + - `optional`: se uma ferramenta de plugin é opcional +- Operators podem chamar `tools.effective` (`operator.read`) para buscar o inventário efetivo de ferramentas em runtime para uma + sessão. - `sessionKey` é obrigatório. - - O gateway deriva o contexto confiável de runtime do lado do servidor a partir da sessão, em vez de aceitar + - O gateway deriva contexto confiável de runtime do lado do servidor a partir da sessão, em vez de aceitar autenticação ou contexto de entrega fornecidos pelo chamador. - - A resposta tem escopo de sessão e reflete o que a conversa ativa pode usar agora, - incluindo ferramentas de core, Plugin e canal. -- Operators podem chamar `skills.status` (`operator.read`) para buscar o inventário visível - de skills para um agente. - - `agentId` é opcional; omita-o para ler o workspace padrão do agente. + - A resposta tem escopo de sessão e reflete o que a conversa ativa pode usar neste momento, + incluindo ferramentas de core, plugin e canal. +- Operators podem chamar `skills.status` (`operator.read`) para buscar o inventário visível de + Skills para um agente. + - `agentId` é opcional; omita-o para ler o workspace do agente padrão. - A resposta inclui elegibilidade, requisitos ausentes, verificações de configuração e - opções de instalação sanitizadas sem expor valores brutos de segredos. -- Operators podem chamar `skills.search` e `skills.detail` (`operator.read`) para metadados - de descoberta do ClawHub. + opções de instalação sanitizadas, sem expor valores brutos de segredos. +- Operators podem chamar `skills.search` e `skills.detail` (`operator.read`) para + metadados de descoberta do ClawHub. - Operators podem chamar `skills.install` (`operator.admin`) em dois modos: - Modo ClawHub: `{ source: "clawhub", slug, version?, force? }` instala uma - pasta de skill no diretório `skills/` do workspace padrão do agente. + pasta de skill no diretório `skills/` do workspace do agente padrão. - Modo instalador do gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` executa uma ação declarada `metadata.openclaw.install` no host do gateway. - Operators podem chamar `skills.update` (`operator.admin`) em dois modos: - - O modo ClawHub atualiza um slug rastreado ou todas as instalações do ClawHub rastreadas no - workspace padrão do agente. - - O modo Config aplica patch em valores de `skills.entries.`, como `enabled`, + - O modo ClawHub atualiza um slug rastreado ou todas as instalações rastreadas do ClawHub no + workspace do agente padrão. + - O modo Config aplica patch em valores `skills.entries.`, como `enabled`, `apiKey` e `env`. ## Aprovações de exec -- Quando uma requisição de exec precisa de aprovação, o gateway transmite `exec.approval.requested`. -- Clientes operator resolvem chamando `exec.approval.resolve` (exige escopo `operator.approvals`). +- Quando uma requisição exec precisa de aprovação, o gateway transmite `exec.approval.requested`. +- Clientes operator resolvem chamando `exec.approval.resolve` (exige o escopo `operator.approvals`). - Para `host=node`, `exec.approval.request` deve incluir `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadados de sessão canônicos). Requisições sem `systemRunPlan` são rejeitadas. -- Após a aprovação, chamadas encaminhadas de `node.invoke system.run` reutilizam esse - `systemRunPlan` canônico como o contexto autoritativo de comando/cwd/sessão. -- Se um chamador modificar `command`, `rawCommand`, `cwd`, `agentId` ou +- Após a aprovação, chamadas encaminhadas `node.invoke system.run` reutilizam esse + `systemRunPlan` canônico como contexto autoritativo de comando/cwd/sessão. +- Se um chamador alterar `command`, `rawCommand`, `cwd`, `agentId` ou `sessionKey` entre o prepare e o encaminhamento final aprovado de `system.run`, o - gateway rejeita a execução em vez de confiar no payload modificado. + gateway rejeita a execução em vez de confiar no payload alterado. ## Fallback de entrega do agente -- Requisições de `agent` podem incluir `deliver=true` para solicitar entrega de saída. -- `bestEffortDeliver=false` mantém o comportamento estrito: destinos de entrega não resolvidos ou apenas internos retornam `INVALID_REQUEST`. -- `bestEffortDeliver=true` permite fallback para execução apenas em sessão quando nenhuma rota externa entregável pode ser resolvida (por exemplo, sessões internas/webchat ou configurações ambíguas com múltiplos canais). +- Requisições `agent` podem incluir `deliver=true` para solicitar entrega de saída. +- `bestEffortDeliver=false` mantém o comportamento estrito: alvos de entrega não resolvidos ou apenas internos retornam `INVALID_REQUEST`. +- `bestEffortDeliver=true` permite fallback para execução somente em sessão quando nenhuma rota externa entregável pode ser resolvida (por exemplo, sessões internas/webchat ou configurações multicanal ambíguas). -## Controle de versão +## Versionamento - `PROTOCOL_VERSION` fica em `src/gateway/protocol/schema/protocol-schemas.ts`. - Clientes enviam `minProtocol` + `maxProtocol`; o servidor rejeita incompatibilidades. -- Esquemas + modelos são gerados a partir de definições TypeBox: +- Schemas + modelos são gerados a partir de definições TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` ### Constantes do cliente -O cliente de referência em `src/gateway/client.ts` usa estes padrões. Os valores são -estáveis no protocolo v3 e são a linha de base esperada para clientes de terceiros. +O cliente de referência em `src/gateway/client.ts` usa estes valores padrão. Os valores são +estáveis em todo o protocolo v3 e são a linha de base esperada para clientes de terceiros. -| Constante | Padrão | Origem | -| ------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------- | -| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | -| Timeout de requisição (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| Timeout de pré-autenticação / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | -| Backoff inicial de reconexão | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | -| Backoff máximo de reconexão | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| Clamp de nova tentativa rápida após fechamento por token de dispositivo | `250` ms | `src/gateway/client.ts` | -| Tolerância de parada forçada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | -| Timeout padrão de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | -| Intervalo padrão de tick (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | -| Fechamento por timeout de tick | código `4000` quando o silêncio excede `tickIntervalMs * 2` | `src/gateway/client.ts` | -| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | +| Constante | Padrão | Fonte | +| ------------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------- | +| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | +| Timeout de requisição (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | +| Timeout de pré-autenticação / desafio de conexão | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | +| Backoff inicial de reconexão | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| Backoff máximo de reconexão | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| Clamp de tentativa rápida após fechamento por token de dispositivo | `250` ms | `src/gateway/client.ts` | +| Grace de parada forçada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| Timeout padrão de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| Intervalo padrão de tick (pré `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | +| Fechamento por timeout de tick | código `4000` quando o silêncio excede `tickIntervalMs * 2` | `src/gateway/client.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | -O servidor anuncia os valores efetivos de `policy.tickIntervalMs`, `policy.maxPayload` -e `policy.maxBufferedBytes` em `hello-ok`; os clientes devem respeitar esses valores +O servidor anuncia `policy.tickIntervalMs`, `policy.maxPayload` e +`policy.maxBufferedBytes` efetivos em `hello-ok`; os clientes devem respeitar esses valores, em vez dos padrões de pré-handshake. ## Autenticação -- A autenticação do gateway por segredo compartilhado usa `connect.params.auth.token` ou +- A autenticação do gateway com segredo compartilhado usa `connect.params.auth.token` ou `connect.params.auth.password`, dependendo do modo de autenticação configurado. -- Modos que carregam identidade, como Tailscale Serve +- Modos com identidade, como Tailscale Serve (`gateway.auth.allowTailscale: true`) ou `gateway.auth.mode: "trusted-proxy"` fora de loopback, - satisfazem a verificação de autenticação de conexão a partir dos cabeçalhos da + satisfazem a verificação de autenticação do connect a partir dos headers da requisição em vez de `connect.params.auth.*`. -- `gateway.auth.mode: "none"` para ingresso privado ignora completamente a autenticação de conexão por segredo compartilhado; não exponha esse modo em ingressos públicos/não confiáveis. -- Após o pareamento, o Gateway emite um **token de dispositivo** com escopo para o papel + escopos da conexão. Ele é retornado em `hello-ok.auth.deviceToken` e deve ser persistido pelo cliente para conexões futuras. +- O modo de ingresso privado `gateway.auth.mode: "none"` ignora completamente a autenticação + de connect com segredo compartilhado; não exponha esse modo em ingressos públicos/não confiáveis. +- Após o emparelhamento, o Gateway emite um **token de dispositivo** com escopo para o + papel + escopos da conexão. Ele é retornado em `hello-ok.auth.deviceToken` e deve ser + persistido pelo cliente para conexões futuras. - Os clientes devem persistir o `hello-ok.auth.deviceToken` primário após qualquer conexão bem-sucedida. -- Ao reconectar com esse token de dispositivo **armazenado**, também deve ser reutilizado o conjunto de escopos aprovados armazenado para esse token. Isso preserva o acesso de leitura/sondagem/status - que já foi concedido e evita reduzir silenciosamente as reconexões a um - escopo implícito mais restrito apenas de admin. -- Montagem da autenticação de conexão no lado do cliente (`selectConnectAuth` em +- Ao reconectar com esse token de dispositivo **armazenado**, também deve ser reutilizado o conjunto de + escopos aprovados armazenado para esse token. Isso preserva o acesso de leitura/probe/status + que já foi concedido e evita reduzir silenciosamente as reconexões para um + escopo implícito mais estreito, apenas de admin. +- Montagem da autenticação de connect no lado do cliente (`selectConnectAuth` em `src/gateway/client.ts`): - `auth.password` é ortogonal e sempre é encaminhado quando definido. - `auth.token` é preenchido em ordem de prioridade: primeiro token compartilhado explícito, depois um `deviceToken` explícito, depois um token armazenado por dispositivo (indexado por `deviceId` + `role`). - - `auth.bootstrapToken` é enviado apenas quando nenhuma das opções acima resolve um + - `auth.bootstrapToken` é enviado apenas quando nenhum dos itens acima resolve um `auth.token`. Um token compartilhado ou qualquer token de dispositivo resolvido o suprime. - - A promoção automática de um token de dispositivo armazenado na nova tentativa pontual - `AUTH_TOKEN_MISMATCH` é limitada apenas a **endpoints confiáveis** — + - A autopromoção de um token de dispositivo armazenado na tentativa única de retry + `AUTH_TOKEN_MISMATCH` é restrita a **endpoints confiáveis apenas** — loopback, ou `wss://` com `tlsFingerprint` fixado. `wss://` público sem pinning não se qualifica. -- Entradas adicionais em `hello-ok.auth.deviceTokens` são tokens de transferência de bootstrap. - Persista-as apenas quando a conexão tiver usado autenticação de bootstrap em um transporte confiável, - como `wss://` ou loopback/pareamento local. +- Entradas adicionais em `hello-ok.auth.deviceTokens` são tokens de handoff de bootstrap. + Persista-as apenas quando a conexão usou autenticação de bootstrap em um transporte confiável, + como `wss://` ou loopback/emparelhamento local. - Se um cliente fornecer um `deviceToken` **explícito** ou `scopes` explícitos, esse conjunto de escopos solicitado pelo chamador permanece autoritativo; escopos em cache só - são reutilizados quando o cliente estiver reutilizando o token armazenado por dispositivo. + são reutilizados quando o cliente está reutilizando o token armazenado por dispositivo. - Tokens de dispositivo podem ser rotacionados/revogados via `device.token.rotate` e `device.token.revoke` (exige escopo `operator.pairing`). -- A emissão/rotação de tokens permanece limitada ao conjunto de papéis aprovados registrado - na entrada de pareamento daquele dispositivo; rotacionar um token não pode expandir o dispositivo para um - papel que a aprovação de pareamento nunca concedeu. -- Para sessões com token de dispositivo pareado, o gerenciamento de dispositivos tem escopo próprio, a menos que o - chamador também tenha `operator.admin`: chamadores que não são admin só podem remover/revogar/rotacionar - sua **própria** entrada de dispositivo. -- `device.token.rotate` também verifica o conjunto de escopos de operator solicitado em relação aos - escopos da sessão atual do chamador. Chamadores que não são admin não podem rotacionar um token para - um conjunto de escopos de operator mais amplo do que o que já possuem. +- A emissão/rotação de token permanece limitada ao conjunto aprovado de papéis registrado na + entrada de emparelhamento daquele dispositivo; rotacionar um token não pode expandir o dispositivo para um + papel que a aprovação de emparelhamento nunca concedeu. +- Para sessões de token de dispositivo emparelhado, o gerenciamento de dispositivo é autoescopado, a menos que o + chamador também tenha `operator.admin`: chamadores sem admin só podem remover/revogar/rotacionar + a entrada do **próprio** dispositivo. +- `device.token.rotate` também verifica o conjunto de escopos de operador solicitado em relação aos + escopos atuais da sessão do chamador. Chamadores sem admin não podem rotacionar um token para + um conjunto de escopos de operador mais amplo do que já possuem. - Falhas de autenticação incluem `error.details.code` mais dicas de recuperação: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Comportamento do cliente para `AUTH_TOKEN_MISMATCH`: - - Clientes confiáveis podem tentar uma nova tentativa limitada com um token por dispositivo em cache. - - Se essa nova tentativa falhar, os clientes devem interromper loops automáticos de reconexão e exibir orientações de ação para o operator. + - Clientes confiáveis podem tentar um único retry limitado com um token armazenado por dispositivo em cache. + - Se esse retry falhar, os clientes devem interromper loops automáticos de reconexão e exibir orientação para ação do operador. -## Identidade do dispositivo + pareamento +## Identidade do dispositivo + emparelhamento -- Nós devem incluir uma identidade estável de dispositivo (`device.id`) derivada da +- Nodes devem incluir uma identidade de dispositivo estável (`device.id`) derivada da impressão digital de um par de chaves. - Gateways emitem tokens por dispositivo + papel. -- Aprovações de pareamento são necessárias para novos IDs de dispositivo, a menos que a aprovação automática local +- Aprovações de emparelhamento são necessárias para novos IDs de dispositivo, a menos que a autoaprovação local esteja habilitada. -- A aprovação automática de pareamento é centrada em conexões diretas locais por loopback. -- O OpenClaw também tem um caminho restrito de autoconexão local de backend/container para +- A autoaprovação de emparelhamento é centrada em conexões diretas de loopback local. +- O OpenClaw também tem um caminho estreito de autoconexão local ao backend/container para fluxos helper confiáveis com segredo compartilhado. -- Conexões no mesmo host por tailnet ou LAN ainda são tratadas como remotas para pareamento e +- Conexões tailnet ou LAN no mesmo host ainda são tratadas como remotas para fins de emparelhamento e exigem aprovação. -- Todos os clientes WS devem incluir identidade `device` durante `connect` (operator + node). +- Todos os clientes WS devem incluir a identidade `device` durante `connect` (operator + node). A Control UI só pode omiti-la nestes modos: - `gateway.controlUi.allowInsecureAuth=true` para compatibilidade com HTTP inseguro apenas em localhost. - - autenticação bem-sucedida de operator da Control UI com `gateway.auth.mode: "trusted-proxy"`. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, grave redução de segurança). + - autenticação operator bem-sucedida da Control UI com `gateway.auth.mode: "trusted-proxy"`. + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, downgrade grave de segurança). - Todas as conexões devem assinar o nonce `connect.challenge` fornecido pelo servidor. ### Diagnósticos de migração de autenticação de dispositivo -Para clientes legados que ainda usam o comportamento de assinatura pré-desafio, `connect` agora retorna +Para clientes legados que ainda usam o comportamento de assinatura anterior ao challenge, `connect` agora retorna códigos de detalhe `DEVICE_AUTH_*` em `error.details.code` com um `error.details.reason` estável. Falhas comuns de migração: -| Mensagem | details.code | details.reason | Significado | -| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | O cliente omitiu `device.nonce` (ou o enviou em branco). | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | O cliente assinou com um nonce antigo/incorreto. | +| Mensagem | details.code | details.reason | Significado | +| --------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | O cliente omitiu `device.nonce` (ou enviou vazio). | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | O cliente assinou com um nonce antigo/incorreto. | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | O payload da assinatura não corresponde ao payload v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | O timestamp assinado está fora da defasagem permitida. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | O timestamp assinado está fora da tolerância permitida. | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` não corresponde à impressão digital da chave pública. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | O formato/canonicalização da chave pública falhou. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | O formato/canonicalização da chave pública falhou. | -Destino da migração: +Alvo da migração: - Sempre aguarde `connect.challenge`. - Assine o payload v2 que inclui o nonce do servidor. - Envie o mesmo nonce em `connect.params.device.nonce`. - O payload de assinatura preferido é `v3`, que vincula `platform` e `deviceFamily` - além dos campos device/client/role/scopes/token/nonce. -- Assinaturas legadas `v2` continuam sendo aceitas por compatibilidade, mas o pinning de metadados - do dispositivo pareado ainda controla a política de comandos na reconexão. + além dos campos de dispositivo/cliente/papel/escopos/token/nonce. +- Assinaturas legadas `v2` continuam sendo aceitas por compatibilidade, mas o pinning de + metadados de dispositivo emparelhado ainda controla a política de comandos na reconexão. ## TLS + pinning - TLS é compatível com conexões WS. -- Os clientes podem opcionalmente fixar a impressão digital do certificado do gateway (consulte a configuração `gateway.tls` - além de `gateway.remote.tlsFingerprint` ou a CLI `--tls-fingerprint`). +- Os clientes podem opcionalmente fixar a impressão digital do certificado do gateway (veja a configuração `gateway.tls` + mais `gateway.remote.tlsFingerprint` ou a CLI `--tls-fingerprint`). ## Escopo Este protocolo expõe a **API completa do gateway** (status, canais, modelos, chat, -agente, sessões, nós, aprovações etc.). A superfície exata é definida pelos -esquemas TypeBox em `src/gateway/protocol/schema.ts`. +agent, sessões, nodes, aprovações etc.). A superfície exata é definida pelos +schemas TypeBox em `src/gateway/protocol/schema.ts`. diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index 574f81e0c..63d29ff2f 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -4,12 +4,12 @@ read_when: - Adicionando regressões para bugs de modelo/provedor - Depurando o comportamento do Gateway + agente summary: 'Kit de testes: suítes unit/e2e/live, executores Docker e o que cada teste cobre' -title: Teste +title: Testes x-i18n: - generated_at: "2026-04-17T05:36:07Z" + generated_at: "2026-04-18T05:24:45Z" model: gpt-5.4 provider: openai - source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 + source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a source_path: help/testing.md workflow: 15 --- @@ -20,7 +20,7 @@ O OpenClaw tem três suítes Vitest (unit/integration, e2e, live) e um pequeno c Este documento é um guia de “como testamos”: -- O que cada suíte cobre (e o que ela deliberadamente _não_ cobre) +- O que cada suíte cobre (e o que deliberadamente _não_ cobre) - Quais comandos executar para fluxos de trabalho comuns (local, pré-push, depuração) - Como os testes live descobrem credenciais e selecionam modelos/provedores - Como adicionar regressões para problemas reais de modelo/provedor @@ -32,89 +32,90 @@ Na maioria dos dias: - Gate completo (esperado antes do push): `pnpm build && pnpm check && pnpm test` - Execução local mais rápida da suíte completa em uma máquina com bastante recurso: `pnpm test:max` - Loop direto de watch do Vitest: `pnpm test:watch` -- O direcionamento direto por arquivo agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Prefira execuções direcionadas primeiro quando estiver iterando em uma única falha. -- Site de QA com suporte Docker: `pnpm qa:lab:up` +- O direcionamento direto de arquivos agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Prefira execuções direcionadas primeiro quando estiver iterando sobre uma única falha. +- Site de QA com suporte de Docker: `pnpm qa:lab:up` - Faixa de QA com suporte de VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando você mexe em testes ou quer confiança extra: +Quando você altera testes ou quer confiança extra: - Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` Ao depurar provedores/modelos reais (requer credenciais reais): -- Suíte live (probes de modelos + Gateway ferramenta/imagem): `pnpm test:live` -- Direcionar um arquivo live em modo silencioso: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suíte live (sondagens de modelos + ferramentas/imagens do Gateway): `pnpm test:live` +- Direcione um arquivo live em modo silencioso: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Dica: quando você só precisa de um caso com falha, prefira restringir os testes live usando as variáveis de ambiente de allowlist descritas abaixo. +Dica: quando você só precisa de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo. ## Executores específicos de QA -Esses comandos ficam ao lado das principais suítes de teste quando você precisa do realismo do qa-lab: +Esses comandos ficam ao lado das suítes de teste principais quando você precisa do realismo do QA-lab: - `pnpm openclaw qa suite` - Executa cenários de QA com suporte do repositório diretamente no host. - Executa vários cenários selecionados em paralelo por padrão com workers isolados do Gateway, até 64 workers ou a contagem de cenários selecionados. Use `--concurrency ` para ajustar a contagem de workers, ou `--concurrency 1` para a faixa serial mais antiga. - - Oferece suporte aos modos de provedor `live-frontier`, `mock-openai` e `aimock`. - `aimock` inicia um servidor local de provedor com suporte AIMock para cobertura experimental de fixtures e mock de protocolo sem substituir a faixa `mock-openai` orientada por cenários. + - Suporta os modos de provedor `live-frontier`, `mock-openai` e `aimock`. + `aimock` inicia um servidor local de provedor com suporte do AIMock para cobertura experimental de fixture e simulação de protocolo sem substituir a faixa `mock-openai` sensível ao cenário. - `pnpm openclaw qa suite --runner multipass` - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável. - - Mantém o mesmo comportamento de seleção de cenários do `qa suite` no host. - - Reutiliza as mesmas flags de seleção de provedor/modelo do `qa suite`. + - Mantém o mesmo comportamento de seleção de cenários que `qa suite` no host. + - Reutiliza as mesmas flags de seleção de provedor/modelo que `qa suite`. - Execuções live encaminham as entradas de autenticação de QA suportadas que são práticas para o guest: - chaves de provedor baseadas em env, o caminho da configuração de provedor live de QA e `CODEX_HOME` quando presente. - - Os diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta através do workspace montado. + chaves de provedor baseadas em env, o caminho de configuração do provedor live de QA e `CODEX_HOME` quando presente. + - Os diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta pelo workspace montado. - Grava o relatório + resumo normais de QA, além dos logs do Multipass, em `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia o site de QA com suporte Docker para trabalho de QA em estilo de operador. + - Inicia o site de QA com suporte de Docker para trabalho de QA no estilo de operador. - `pnpm openclaw qa aimock` - - Inicia apenas o servidor local do provedor AIMock para testes diretos de fumaça de protocolo. + - Inicia apenas o servidor local de provedor AIMock para testes de fumaça diretos de protocolo. - `pnpm openclaw qa matrix` - - Executa a faixa live de QA do Matrix contra um homeserver Tuwunel descartável com suporte Docker. - - Esse host de QA atualmente é apenas para repositório/desenvolvimento. Instalações empacotadas do OpenClaw não incluem `qa-lab`, portanto não expõem `openclaw qa`. - - Checkouts do repositório carregam diretamente o executor empacotado; nenhuma etapa separada de instalação de Plugin é necessária. - - Provisiona três usuários temporários do Matrix (`driver`, `sut`, `observer`) mais uma sala privada, e então inicia um processo filho do Gateway de QA com o Plugin real do Matrix como transporte do SUT. - - Usa por padrão a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar uma imagem diferente. - - O Matrix não expõe flags compartilhadas de origem de credencial porque a faixa provisiona usuários descartáveis localmente. + - Executa a faixa de QA live do Matrix contra um homeserver Tuwunel descartável com suporte de Docker. + - Esse host de QA é apenas para repositório/dev hoje. Instalações empacotadas do OpenClaw não incluem + `qa-lab`, portanto não expõem `openclaw qa`. + - Checkouts do repositório carregam o executor empacotado diretamente; nenhuma etapa separada de instalação de Plugin é necessária. + - Provisiona três usuários Matrix temporários (`driver`, `sut`, `observer`) mais uma sala privada, depois inicia um processo filho do Gateway de QA com o Plugin Matrix real como transporte do SUT. + - Usa a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1` por padrão. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar uma imagem diferente. + - O Matrix não expõe flags compartilhadas de origem de credenciais porque a faixa provisiona usuários descartáveis localmente. - Grava um relatório de QA do Matrix, resumo, artefato de eventos observados e log combinado de stdout/stderr em `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Executa a faixa live de QA do Telegram contra um grupo privado real usando os tokens do bot driver e do bot SUT a partir de env. + - Executa a faixa de QA live do Telegram contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do env. - Requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. O id do grupo deve ser o id numérico do chat do Telegram. - - Oferece suporte a `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para aderir a leases em pool. + - Suporta `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases em pool. - Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram. - - Para observação estável de bot para bot, habilite o Modo de Comunicação Bot-to-Bot no `@BotFather` para ambos os bots e garanta que o bot driver consiga observar o tráfego de bots no grupo. + - Para observação estável de bot para bot, habilite o Modo de Comunicação Bot-to-Bot no `@BotFather` para ambos os bots e garanta que o bot driver possa observar o tráfego de bots no grupo. - Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. -As faixas de transporte live compartilham um contrato padrão para que novos transportes não saiam do alinhamento: +As faixas de transporte live compartilham um contrato padrão para que novos transportes não sofram desvios: -`qa-channel` continua sendo a ampla suíte de QA sintética e não faz parte da matriz de cobertura de transporte live. +`qa-channel` continua sendo a suíte ampla de QA sintético e não faz parte da matriz de cobertura de transporte live. -| Faixa | Canary | Controle por menção | Bloqueio de allowlist | Resposta de nível superior | Retomada após reinício | Follow-up em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ------------------- | --------------------- | -------------------------- | ---------------------- | ------------------- | -------------------- | ------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Faixa | Canary | Gating de menção | Bloco de allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | +| -------- | ------ | ---------------- | ------------------ | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenciais compartilhadas do Telegram via Convex (v1) -Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) estiver habilitado para -`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool com suporte Convex, envia Heartbeat -desse lease enquanto a faixa estiver em execução e libera o lease no encerramento. +Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para +`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool com suporte do Convex, envia Heartbeat +desse lease enquanto a faixa está em execução e libera o lease no desligamento. -Scaffold de referência do projeto Convex: +Estrutura de referência do projeto Convex: - `qa/convex-credential-broker/` Variáveis de ambiente obrigatórias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) -- Um segredo para o papel selecionado: +- Um segredo para a função selecionada: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` -- Seleção do papel da credencial: +- Seleção da função de credencial: - CLI: `--credential-role maintainer|ci` - - Padrão por env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `maintainer`) + - Padrão no env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `maintainer`) Variáveis de ambiente opcionais: @@ -124,11 +125,11 @@ Variáveis de ambiente opcionais: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (padrão `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (padrão `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreamento opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento apenas local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback apenas para desenvolvimento local. `OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. -Comandos administrativos de mantenedor (adicionar/remover/listar pool) exigem +Comandos administrativos do mantenedor (adicionar/remover/listar no pool) requerem `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. Helpers de CLI para mantenedores: @@ -141,7 +142,7 @@ pnpm openclaw qa credentials remove --credential-id Use `--json` para saída legível por máquina em scripts e utilitários de CI. -Contrato padrão do endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contrato padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Requisição: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -153,44 +154,44 @@ Contrato padrão do endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v - `POST /release` - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) -- `POST /admin/add` (somente com segredo de maintainer) +- `POST /admin/add` (apenas segredo de mantenedor) - Requisição: `{ kind, actorId, payload, note?, status? }` - Sucesso: `{ status: "ok", credential }` -- `POST /admin/remove` (somente com segredo de maintainer) +- `POST /admin/remove` (apenas segredo de mantenedor) - Requisição: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - Proteção de lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (somente com segredo de maintainer) +- `POST /admin/list` (apenas segredo de mantenedor) - Requisição: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` -Formato de payload para o tipo Telegram: +Formato do payload para o tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` deve ser uma string com o id numérico do chat do Telegram. +- `groupId` deve ser uma string numérica de id de chat do Telegram. - `admin/add` valida esse formato para `kind: "telegram"` e rejeita payloads malformados. ### Adicionando um canal ao QA -Adicionar um canal ao sistema de QA em markdown exige exatamente duas coisas: +Adicionar um canal ao sistema de QA em Markdown requer exatamente duas coisas: 1. Um adaptador de transporte para o canal. 2. Um pacote de cenários que exercite o contrato do canal. Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder -ser o dono do fluxo. +ser dono do fluxo. -`qa-lab` é o dono da mecânica compartilhada do host: +`qa-lab` é dono da mecânica compartilhada do host: - a raiz de comando `openclaw qa` -- inicialização e encerramento da suíte +- inicialização e desligamento da suíte - concorrência de workers - gravação de artefatos - geração de relatórios - execução de cenários -- aliases de compatibilidade para cenários antigos do `qa-channel` +- aliases de compatibilidade para cenários antigos de `qa-channel` -Plugins de executores são donos do contrato de transporte: +Plugins de executor são donos do contrato de transporte: - como `openclaw qa ` é montado sob a raiz compartilhada `qa` - como o Gateway é configurado para esse transporte @@ -198,27 +199,27 @@ Plugins de executores são donos do contrato de transporte: - como eventos de entrada são injetados - como mensagens de saída são observadas - como transcrições e estado normalizado do transporte são expostos -- como ações com suporte de transporte são executadas -- como reset ou limpeza específicos do transporte são tratados +- como ações com suporte do transporte são executadas +- como redefinição ou limpeza específica do transporte é tratada A barra mínima de adoção para um novo canal é: 1. Manter `qa-lab` como dono da raiz compartilhada `qa`. -2. Implementar o executor de transporte na seam compartilhada do host `qa-lab`. -3. Manter a mecânica específica de transporte dentro do Plugin do executor ou do harness do Plugin. +2. Implementar o executor de transporte na costura de host compartilhada `qa-lab`. +3. Manter a mecânica específica do transporte dentro do Plugin de executor ou do harness do Plugin. 4. Montar o executor como `openclaw qa ` em vez de registrar uma raiz de comando concorrente. - Plugins de executor devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array correspondente `qaRunnerCliRegistrations` a partir de `runtime-api.ts`. - Mantenha `runtime-api.ts` leve; a execução lazy de CLI e de executores deve ficar atrás de entrypoints separados. -5. Criar ou adaptar cenários em markdown sob `qa/scenarios/`. + Plugins de executor devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. + Mantenha `runtime-api.ts` leve; a execução lazy de CLI e de executor deve permanecer atrás de entrypoints separados. +5. Criar ou adaptar cenários Markdown nos diretórios temáticos `qa/scenarios/`. 6. Usar os helpers genéricos de cenário para novos cenários. -7. Manter os aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional. +7. Manter funcionando os aliases de compatibilidade existentes, a menos que o repositório esteja fazendo uma migração intencional. -A regra de decisão é rígida: +A regra de decisão é estrita: -- Se o comportamento puder ser expresso uma única vez em `qa-lab`, coloque-o em `qa-lab`. -- Se o comportamento depender de um transporte de canal, mantenha-o nesse Plugin de executor ou harness de Plugin. +- Se o comportamento puder ser expresso uma vez em `qa-lab`, coloque-o em `qa-lab`. +- Se o comportamento depender de um transporte de canal, mantenha-o nesse Plugin de executor ou harness do Plugin. - Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de um branch específico de canal em `suite.ts`. -- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico desse transporte e deixe isso explícito no contrato do cenário. +- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico do transporte e deixe isso explícito no contrato do cenário. Os nomes preferidos de helper genérico para novos cenários são: @@ -244,101 +245,101 @@ Aliases de compatibilidade continuam disponíveis para cenários existentes, inc - `resetBus` Novos trabalhos de canal devem usar os nomes genéricos de helper. -Os aliases de compatibilidade existem para evitar uma migração em dia marcado, não como o modelo para -criação de novos cenários. +Os aliases de compatibilidade existem para evitar uma migração em “flag day”, não como modelo para +a criação de novos cenários. ## Suítes de teste (o que roda onde) -Pense nas suítes como “realismo crescente” (e crescente instabilidade/custo): +Pense nas suítes como “realismo crescente” (e aumento de instabilidade/custo): -### Unit / integração (padrão) +### Unit / integration (padrão) - Comando: `pnpm test` - Configuração: dez execuções sequenciais de shards (`vitest.full-*.config.ts`) sobre os projetos Vitest com escopo já existentes -- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes Node em `ui` incluídos na allowlist cobertos por `vitest.unit.config.ts` +- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes node permitidos de `ui` cobertos por `vitest.unit.config.ts` - Escopo: - Testes unitários puros - - Testes de integração in-process (autenticação do Gateway, roteamento, ferramentas, parsing, config) + - Testes de integração em processo (autenticação do gateway, roteamento, ferramentas, parsing, config) - Regressões determinísticas para bugs conhecidos - Expectativas: - - Roda em CI + - Roda no CI - Não requer chaves reais - Deve ser rápido e estável - Observação sobre projetos: - - `pnpm test` sem alvo agora executa onze configurações menores de shard (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que trabalho de auto-reply/extensão prejudique suítes não relacionadas. - - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop de watch multi-shard não é prático. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` roteiam alvos explícitos de arquivo/diretório primeiro por faixas com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo total de inicialização do projeto raiz. - - `pnpm test:changed` expande caminhos alterados do git para as mesmas faixas com escopo quando o diff toca apenas arquivos de código/teste roteáveis; edições de config/setup ainda recorrem à reexecução ampla do projeto raiz. - - Testes unitários leves de importação de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes são roteados pela faixa `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado/runtime pesado permanecem nas faixas existentes. - - Arquivos-fonte auxiliares selecionados de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas faixas leves, para que edições em helpers evitem reexecutar a suíte pesada completa daquele diretório. + - `pnpm test` sem alvo agora executa onze configurações de shard menores (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensão sufoque suítes não relacionadas. + - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop watch com múltiplos shards não é prático. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham primeiro alvos explícitos de arquivo/diretório por faixas com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo completo de inicialização do projeto raiz. + - `pnpm test:changed` expande caminhos alterados no git para as mesmas faixas com escopo quando o diff toca apenas arquivos de código/teste roteáveis; edições de config/setup ainda recorrem à reexecução ampla do projeto raiz. + - Testes unitários leves de importação de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes passam pela faixa `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado pesado/runtime permanecem nas faixas existentes. + - Alguns arquivos-fonte helper de `plugin-sdk` e `commands` também mapeiam execuções no modo changed para testes irmãos explícitos nessas faixas leves, para que edições de helpers evitem reexecutar a suíte pesada completa desse diretório. - `auto-reply` agora tem três buckets dedicados: helpers core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. -- Observação sobre executor embutido: - - Quando você alterar entradas de descoberta de ferramentas de mensagem ou contexto de runtime de Compaction, +- Observação sobre o executor embutido: + - Quando você altera entradas de descoberta de ferramentas de mensagem ou o contexto de runtime de Compaction, mantenha ambos os níveis de cobertura. - Adicione regressões focadas em helpers para limites puros de roteamento/normalização. - Também mantenha saudáveis as suítes de integração do executor embutido: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Essas suítes verificam que ids com escopo e o comportamento de Compaction continuam fluindo + - Essas suítes verificam que ids com escopo e o comportamento de Compaction ainda fluem pelos caminhos reais `run.ts` / `compact.ts`; testes apenas de helper não são um substituto suficiente para esses caminhos de integração. - Observação sobre pool: - A configuração base do Vitest agora usa `threads` por padrão. - - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o executor não isolado nos projetos da raiz, nas configurações e2e e live. - - A faixa UI da raiz mantém sua configuração `jsdom` e otimizador, mas agora também roda no executor compartilhado não isolado. + - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o executor não isolado nos projetos raiz, e2e e live. + - A faixa UI da raiz mantém sua configuração e otimizador `jsdom`, mas agora também roda no executor compartilhado não isolado. - Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` da configuração compartilhada do Vitest. - - O lançador compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos Node filhos do Vitest para reduzir churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. + - O launcher compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos Node filhos do Vitest, para reduzir churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. - Observação sobre iteração local rápida: - - `pnpm test:changed` roteia por faixas com escopo quando os caminhos alterados mapeiam de forma limpa para uma suíte menor. + - `pnpm test:changed` passa por faixas com escopo quando os caminhos alterados mapeiam de forma limpa para uma suíte menor. - `pnpm test:max` e `pnpm test:changed:max` mantêm o mesmo comportamento de roteamento, apenas com um limite maior de workers. - - O autoescalonamento local de workers agora é intencionalmente conservador e também recua quando a média de carga do host já está alta, para que várias execuções simultâneas do Vitest causem menos impacto por padrão. - - A configuração base do Vitest marca os arquivos de projetos/config como `forceRerunTriggers` para que reexecuções em modo changed continuem corretas quando a fiação dos testes muda. + - O autoescalonamento local de workers agora é intencionalmente mais conservador e também recua quando a média de carga do host já está alta, para que várias execuções concorrentes do Vitest causem menos impacto por padrão. + - A configuração base do Vitest marca os arquivos de projetos/configuração como `forceRerunTriggers` para que reexecuções no modo changed permaneçam corretas quando o wiring dos testes muda. - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito para profiling direto. -- Observação sobre depuração de performance: - - `pnpm test:perf:imports` habilita relatório de duração de importação do Vitest mais saída de detalhamento de importações. - - `pnpm test:perf:imports:changed` restringe a mesma visualização de profiling a arquivos alterados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para aquele diff commitado e imprime wall time mais RSS máximo no macOS. -- `pnpm test:perf:changed:bench -- --worktree` mede a árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração Vitest da raiz. - - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para sobrecarga de inicialização e transformação do Vitest/Vite. +- Observação de depuração de performance: + - `pnpm test:perf:imports` habilita o relatório de duração de importação do Vitest mais a saída de detalhamento de importações. + - `pnpm test:perf:imports:changed` aplica a mesma visão de profiling aos arquivos alterados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado e imprime tempo total mais RSS máximo no macOS. +- `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest. + - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de inicialização e transformação do Vitest/Vite. - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do executor para a suíte unit com paralelismo de arquivos desabilitado. -### E2E (smoke do Gateway) +### E2E (teste de fumaça do gateway) - Comando: `pnpm test:e2e` - Configuração: `vitest.e2e.config.ts` - Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Padrões de runtime: - - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repositório. + - Usa `threads` do Vitest com `isolate: false`, em linha com o restante do repositório. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - - Roda em modo silencioso por padrão para reduzir a sobrecarga de I/O de console. + - Roda em modo silencioso por padrão para reduzir o overhead de I/O no console. - Substituições úteis: - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reativar a saída detalhada no console. + - `OPENCLAW_E2E_VERBOSE=1` para reabilitar a saída verbosa no console. - Escopo: - - Comportamento end-to-end de múltiplas instâncias do Gateway - - Superfícies WebSocket/HTTP, pareamento de Node e redes mais pesadas + - Comportamento end-to-end do gateway com múltiplas instâncias + - Superfícies WebSocket/HTTP, pareamento de nós e networking mais pesado - Expectativas: - - Roda em CI (quando habilitado no pipeline) + - Roda no CI (quando habilitado no pipeline) - Não requer chaves reais - - Tem mais partes móveis do que testes unitários (pode ser mais lento) + - Tem mais partes móveis que testes unitários (pode ser mais lento) -### E2E: smoke do backend OpenShell +### E2E: teste de fumaça do backend OpenShell - Comando: `pnpm test:e2e:openshell` - Arquivo: `test/openshell-sandbox.e2e.test.ts` - Escopo: - - Inicia um Gateway OpenShell isolado no host via Docker + - Inicia um gateway OpenShell isolado no host via Docker - Cria um sandbox a partir de um Dockerfile local temporário - - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` real + execução SSH - - Verifica o comportamento canônico de sistema de arquivos remoto por meio da ponte fs do sandbox + - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` real + execução por SSH + - Verifica o comportamento canônico remoto do sistema de arquivos por meio da ponte fs do sandbox - Expectativas: - - Apenas opt-in; não faz parte da execução padrão de `pnpm test:e2e` - - Requer uma CLI local `openshell` mais um daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` isolados, depois destrói o Gateway e o sandbox de teste + - Opt-in apenas; não faz parte da execução padrão de `pnpm test:e2e` + - Requer um CLI `openshell` local mais um daemon Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` isolados, depois destrói o gateway e o sandbox de teste - Substituições úteis: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI ou script wrapper fora do padrão ### Live (provedores reais + modelos reais) @@ -348,55 +349,55 @@ Pense nas suítes como “realismo crescente” (e crescente instabilidade/custo - Padrão: **habilitado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) - Escopo: - “Esse provedor/modelo realmente funciona _hoje_ com credenciais reais?” - - Captura mudanças de formato do provedor, peculiaridades de chamada de ferramenta, problemas de autenticação e comportamento de limite de taxa + - Capturar mudanças de formato do provedor, peculiaridades de chamada de ferramentas, problemas de autenticação e comportamento de rate limit - Expectativas: - - Não é estável em CI por definição (redes reais, políticas reais de provedores, cotas, indisponibilidades) - - Custa dinheiro / usa limites de taxa - - Prefira executar subconjuntos restritos em vez de “tudo” -- Execuções live obtêm `~/.profile` para captar chaves de API ausentes. -- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um home temporário de teste para que fixtures unitários não possam alterar seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando intencionalmente precisar que os testes live usem seu diretório home real. -- `pnpm test:live` agora usa por padrão um modo mais silencioso: ele mantém a saída de progresso `[live] ...`, mas oculta o aviso extra de `~/.profile` e silencia logs de bootstrap do Gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar os logs completos de inicialização. -- Rotação de chave de API (específica por provedor): defina `*_API_KEYS` com formato de vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou substituição por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. + - Não é estável em CI por definição (redes reais, políticas reais de provedor, cotas, indisponibilidades) + - Custa dinheiro / consome rate limits + - Prefira executar subconjuntos reduzidos em vez de “tudo” +- Execuções live leem `~/.profile` para obter chaves de API ausentes. +- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para uma home temporária de teste, para que fixtures unitárias não possam alterar seu `~/.openclaw` real. +- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando quiser intencionalmente que os testes live usem seu diretório home real. +- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar os logs completos de inicialização. +- Rotação de chave de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou use a substituição por live `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de rate limit. - Saída de progresso/Heartbeat: - - As suítes live agora emitem linhas de progresso para stderr para que chamadas longas ao provedor permaneçam visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa. - - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/Gateway fluam imediatamente durante execuções live. + - Suítes live agora emitem linhas de progresso em stderr para que chamadas longas de provedor permaneçam visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa. + - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/gateway sejam transmitidas imediatamente durante execuções live. - Ajuste Heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajuste Heartbeats de Gateway/probe com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajuste Heartbeats de gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Qual suíte devo executar? +## Qual suíte eu devo executar? Use esta tabela de decisão: -- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa) -- Tocando em rede do Gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` -- Depurando “meu bot caiu” / falhas específicas de provedor / chamada de ferramenta: execute um `pnpm test:live` restrito +- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou bastante coisa) +- Alterando networking do gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` +- Depurando “meu bot caiu” / falhas específicas de provedor / chamada de ferramentas: execute um `pnpm test:live` reduzido -## Live: varredura de capacidades do Node Android +## Live: varredura de capacidades de Node Android - Teste: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **todos os comandos atualmente anunciados** por um Node Android conectado e validar o comportamento do contrato de comando. +- Objetivo: invocar **todos os comandos atualmente anunciados** por um Node Android conectado e verificar o comportamento contratual dos comandos. - Escopo: - - Setup manual/com pré-condições (a suíte não instala/executa/faz pareamento do app). - - Validação `node.invoke` do Gateway comando por comando para o Node Android selecionado. -- Pré-setup obrigatório: - - App Android já conectado + pareado ao Gateway. + - Pré-condicionado/configuração manual (a suíte não instala/executa/pareia o app). + - Validação `node.invoke` do gateway comando por comando para o Node Android selecionado. +- Pré-configuração obrigatória: + - App Android já conectado + pareado ao gateway. - App mantido em primeiro plano. - Permissões/consentimento de captura concedidos para as capacidades que você espera que passem. - Substituições opcionais de alvo: - `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detalhes completos de setup do Android: [App Android](/pt-BR/platforms/android) +- Detalhes completos de configuração do Android: [App Android](/pt-BR/platforms/android) -## Live: smoke de modelo (chaves de perfil) +## Live: teste de fumaça de modelo (chaves de perfil) Os testes live são divididos em duas camadas para que possamos isolar falhas: -- “Modelo direto” nos diz se o provedor/modelo consegue responder de fato com a chave fornecida. -- “Smoke do Gateway” nos diz se o pipeline completo Gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.). +- “Modelo direto” nos informa se o provedor/modelo consegue responder com a chave informada. +- “Teste de fumaça do gateway” nos informa se o pipeline completo gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.). -### Camada 1: conclusão direta do modelo (sem Gateway) +### Camada 1: conclusão direta do modelo (sem gateway) - Teste: `src/agents/models.profiles.live.test.ts` - Objetivo: @@ -404,56 +405,56 @@ Os testes live são divididos em duas camadas para que possamos isolar falhas: - Usar `getApiKeyForModel` para selecionar modelos para os quais você tem credenciais - Executar uma pequena conclusão por modelo (e regressões direcionadas quando necessário) - Como habilitar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` ao invocar o Vitest diretamente) -- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário, ela é ignorada para manter `pnpm test:live` focado no smoke do Gateway + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) +- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário, ela é ignorada para manter `pnpm test:live` focado no teste de fumaça do gateway - Como selecionar modelos: - `OPENCLAW_LIVE_MODELS=modern` para executar a allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` é um alias para a allowlist moderna - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por vírgulas) - - As varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. + - Varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. - Como selecionar provedores: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por vírgulas) - De onde vêm as chaves: - - Por padrão: armazenamento de perfis e fallbacks por env - - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **apenas armazenamento de perfis** + - Por padrão: armazenamento de perfil e fallbacks de env + - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **apenas** o armazenamento de perfil - Por que isso existe: - - Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agente Gateway está quebrado” - - Contém regressões pequenas e isoladas (exemplo: replay de raciocínio OpenAI Responses/Codex Responses + fluxos de chamada de ferramenta) + - Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agente do gateway está quebrado” + - Contém regressões pequenas e isoladas (exemplo: replay de reasoning do OpenAI Responses/Codex Responses + fluxos de chamada de ferramenta) -### Camada 2: smoke do Gateway + agente dev (o que o "@openclaw" realmente faz) +### Camada 2: teste de fumaça do Gateway + agente dev (o que `@openclaw` realmente faz) - Teste: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Subir um Gateway in-process + - Subir um gateway em processo - Criar/atualizar uma sessão `agent:dev:*` (substituição de modelo por execução) - - Iterar por modelos com chaves e validar: + - Iterar por modelos com chaves e verificar: - resposta “significativa” (sem ferramentas) - - uma invocação real de ferramenta funciona (probe de leitura) - - probes opcionais extras de ferramenta (probe de exec+read) - - caminhos de regressão do OpenAI (somente chamada de ferramenta → follow-up) continuam funcionando -- Detalhes dos probes (para que você consiga explicar falhas rapidamente): - - probe `read`: o teste grava um arquivo nonce no workspace e pede ao agente para `read` o arquivo e ecoar o nonce de volta. - - probe `exec+read`: o teste pede ao agente para gravar um nonce com `exec` em um arquivo temporário e depois `read` de volta. - - probe de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `. + - uma invocação real de ferramenta funciona (sonda de leitura) + - sondas opcionais extras de ferramenta (sonda exec+read) + - caminhos de regressão do OpenAI (somente chamada de ferramenta → continuação) continuam funcionando +- Detalhes das sondas (para que você possa explicar falhas rapidamente): + - sonda `read`: o teste grava um arquivo nonce no workspace e pede ao agente para `read` esse arquivo e retornar o nonce. + - sonda `exec+read`: o teste pede ao agente para gravar um nonce em um arquivo temporário com `exec` e depois lê-lo de volta com `read`. + - sonda de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `. - Referência de implementação: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. - Como habilitar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` ao invocar o Vitest diretamente) + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) - Como selecionar modelos: - Padrão: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` é um alias para a allowlist moderna - Ou defina `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou lista separada por vírgulas) para restringir - - As varreduras modern/all do Gateway usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. -- Como selecionar provedores (evite “OpenRouter tudo”): + - Varreduras modern/all do gateway usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. +- Como selecionar provedores (evite “tudo do OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por vírgulas) -- Os probes de ferramenta + imagem estão sempre ativados neste teste live: - - probe `read` + probe `exec+read` (estresse de ferramenta) - - o probe de imagem roda quando o modelo anuncia suporte a entrada de imagem +- As sondas de ferramenta + imagem estão sempre ativas neste teste live: + - sonda `read` + sonda `exec+read` (estresse de ferramenta) + - a sonda de imagem roda quando o modelo anuncia suporte a entrada de imagem - Fluxo (alto nível): - - O teste gera um PNG minúsculo com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`) + - O teste gera um pequeno PNG com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`) - Envia via `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - O Gateway faz parsing dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - O agente embutido encaminha uma mensagem de usuário multimodal para o modelo - - Validação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) + - O Gateway faz o parse dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - O agente embutido encaminha uma mensagem de usuário multimodal ao modelo + - Verificação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) Dica: para ver o que você pode testar na sua máquina (e os ids exatos `provider/model`), execute: @@ -462,26 +463,26 @@ openclaw models list openclaw models list --json ``` -## Live: smoke de backend CLI (Claude, Codex, Gemini ou outras CLIs locais) +## Live: teste de fumaça do backend CLI (Claude, Codex, Gemini ou outros CLIs locais) - Teste: `src/gateway/gateway-cli-backend.live.test.ts` - Objetivo: validar o pipeline Gateway + agente usando um backend CLI local, sem tocar na sua config padrão. -- Os padrões de smoke específicos do backend ficam com a definição `cli-backend.ts` da extensão proprietária. +- Os padrões de teste de fumaça específicos do backend ficam na definição `cli-backend.ts` da extensão proprietária. - Habilitar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` ao invocar o Vitest diretamente) + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Padrões: - Provedor/modelo padrão: `claude-cli/claude-sonnet-4-6` - - Comportamento de comando/args/imagem vem dos metadados do Plugin proprietário do backend CLI. + - O comportamento de comando/args/imagem vem dos metadados do Plugin de backend CLI proprietário. - Substituições (opcionais): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar um anexo de imagem real (os caminhos são injetados no prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivos de imagem como args da CLI em vez de injeção no prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivo de imagem como args da CLI em vez de injeção no prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) para controlar como args de imagem são passados quando `IMAGE_ARG` está definido. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar um segundo turno e validar o fluxo de retomada. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desabilitar o probe padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-lo quando o modelo selecionado oferecer suporte a um alvo de troca). + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar uma segunda rodada e validar o fluxo de retomada. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desabilitar a sonda padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-la quando o modelo selecionado suportar um alvo de troca). Exemplo: @@ -497,7 +498,7 @@ Receita Docker: pnpm test:docker:live-cli-backend ``` -Receitas Docker para provedor único: +Receitas Docker de provedor único: ```bash pnpm test:docker:live-cli-backend:claude @@ -509,20 +510,20 @@ pnpm test:docker:live-cli-backend:gemini Observações: - O executor Docker fica em `scripts/test-live-cli-backend-docker.sh`. -- Ele executa o smoke live do backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. -- Ele resolve os metadados do smoke CLI a partir da extensão proprietária e depois instala o pacote Linux CLI correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável com cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil da assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele comprova `claude -p` direto no Docker e depois executa dois turnos de backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa faixa de assinatura desabilita por padrão os probes de MCP/ferramenta e imagem do Claude porque o Claude atualmente roteia o uso de apps de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. -- O smoke live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem e então chamada da ferramenta MCP `cron` validada pela CLI do Gateway. -- O smoke padrão do Claude também atualiza a sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma anotação anterior. +- Ele executa o teste de fumaça live do backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. +- Ele resolve os metadados do teste de fumaça da CLI a partir da extensão proprietária e então instala o pacote Linux CLI correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável em cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil de assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele prova `claude -p` direto no Docker, depois executa duas rodadas do backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa faixa de assinatura desabilita por padrão as sondas de ferramenta MCP e imagem do Claude porque o Claude atualmente roteia o uso de aplicativos de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. +- O teste de fumaça live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: rodada de texto, rodada de classificação de imagem e depois chamada da ferramenta MCP `cron`, verificada pela CLI do gateway. +- O teste de fumaça padrão do Claude também atualiza a sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma observação anterior. -## Live: smoke de bind do ACP (`/acp spawn ... --bind here`) +## Live: teste de fumaça de bind ACP (`/acp spawn ... --bind here`) - Teste: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar o fluxo real de conversation-bind do ACP com um agente ACP live: +- Objetivo: validar o fluxo real de bind de conversa ACP com um agente ACP live: - enviar `/acp spawn --bind here` - - vincular in place uma conversa sintética de canal de mensagem - - enviar um follow-up normal nessa mesma conversa - - verificar que o follow-up chega à transcrição da sessão ACP vinculada + - vincular in-place uma conversa sintética de canal de mensagem + - enviar uma continuação normal nessa mesma conversa + - verificar que a continuação chega na transcrição da sessão ACP vinculada - Habilitar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` @@ -538,8 +539,8 @@ Observações: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Observações: - - Essa faixa usa a superfície `chat.send` do Gateway com campos sintéticos de rota de origem apenas para admin para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro de agentes embutido do Plugin `acpx` selecionado para o agente de harness ACP. + - Essa faixa usa a superfície `chat.send` do gateway com campos sintéticos de rota de origem apenas para admin, para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro embutido de agentes do Plugin `acpx` embutido para o agente de harness ACP selecionado. Exemplo: @@ -555,7 +556,7 @@ Receita Docker: pnpm test:docker:live-acp-bind ``` -Receitas Docker para agente único: +Receitas Docker de agente único: ```bash pnpm test:docker:live-acp-bind:claude @@ -566,31 +567,31 @@ pnpm test:docker:live-acp-bind:gemini Observações sobre Docker: - O executor Docker fica em `scripts/test-live-acp-bind-docker.sh`. -- Por padrão, ele executa o smoke de bind do ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex` e depois `gemini`. +- Por padrão, ele executa o teste de fumaça de bind ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex` e depois `gemini`. - Use `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para restringir a matriz. -- Ele obtém `~/.profile`, prepara no container o material de autenticação CLI correspondente, instala `acpx` em um prefixo npm gravável e depois instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente. -- Dentro do Docker, o executor define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para a CLI filha do harness as variáveis de ambiente de provedor vindas do profile obtido. +- Ele lê `~/.profile`, prepara o material de autenticação CLI correspondente dentro do contêiner, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se ela estiver ausente. +- Dentro do Docker, o executor define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para a CLI filha do harness as variáveis de ambiente do provedor vindas do profile carregado. -## Live: smoke do harness app-server do Codex +## Live: teste de fumaça do harness app-server do Codex - Objetivo: validar o harness do Codex pertencente ao Plugin por meio do método - `agent` normal do Gateway: - - carregar o Plugin empacotado `codex` + `agent` normal do gateway: + - carregar o Plugin `codex` empacotado - selecionar `OPENCLAW_AGENT_RUNTIME=codex` - - enviar um primeiro turno de agente do Gateway para `codex/gpt-5.4` - - enviar um segundo turno para a mesma sessão do OpenClaw e verificar que a thread - do app-server consegue retomar - - executar `/codex status` e `/codex models` pelo mesmo caminho de comando - do Gateway + - enviar uma primeira rodada do agente do gateway para `codex/gpt-5.4` + - enviar uma segunda rodada para a mesma sessão OpenClaw e verificar se a thread do app-server + pode ser retomada + - executar `/codex status` e `/codex models` pelo mesmo caminho de + comando do gateway - Teste: `src/gateway/gateway-codex-harness.live.test.ts` - Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo padrão: `codex/gpt-5.4` -- Probe opcional de imagem: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Probe opcional de MCP/ferramenta: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- O smoke define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness - do Codex quebrado não passe ao cair silenciosamente de volta para o PI. -- Auth: `OPENAI_API_KEY` do shell/profile, além de opcionais - `~/.codex/auth.json` e `~/.codex/config.toml` copiados +- Sonda de imagem opcional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Sonda MCP/ferramenta opcional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- O teste de fumaça define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness Codex + quebrado não possa passar silenciosamente ao fazer fallback para PI. +- Autenticação: `OPENAI_API_KEY` do shell/profile, mais opcionais copiados + `~/.codex/auth.json` e `~/.codex/config.toml` Receita local: @@ -613,49 +614,49 @@ pnpm test:docker:live-codex-harness Observações sobre Docker: - O executor Docker fica em `scripts/test-live-codex-harness-docker.sh`. -- Ele obtém o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de auth - da CLI do Codex quando presentes, instala `@openai/codex` em um prefixo npm - montado e gravável, prepara a árvore de código-fonte e então executa apenas o teste live do harness do Codex. -- O Docker habilita por padrão os probes de imagem e MCP/ferramenta. Defina +- Ele lê o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de autenticação da CLI do Codex + quando presentes, instala `@openai/codex` em um prefixo npm montado e gravável, + prepara a árvore de código-fonte e então executa apenas o teste live do harness do Codex. +- O Docker habilita por padrão as sondas de imagem e MCP/ferramenta. Defina `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando precisar de uma execução de depuração mais restrita. -- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, correspondendo à - configuração do teste live para que fallback de `openai-codex/*` ou PI não possa ocultar uma - regressão do harness do Codex. +- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, em linha com a configuração do + teste live, para que o fallback `openai-codex/*` ou PI não possa ocultar uma regressão do + harness do Codex. ### Receitas live recomendadas -Allowlists restritas e explícitas são mais rápidas e menos instáveis: +Allowlists estreitas e explícitas são mais rápidas e menos instáveis: -- Modelo único, direto (sem Gateway): +- Modelo único, direto (sem gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modelo único, smoke do Gateway: +- Modelo único, teste de fumaça do gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Chamada de ferramenta em vários provedores: +- Chamada de ferramentas em vários provedores: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Foco em Google (chave de API Gemini + Antigravity): +- Foco em Google (chave da API Gemini + Antigravity): - Gemini (chave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Observações: - `google/...` usa a API Gemini (chave de API). -- `google-antigravity/...` usa a ponte OAuth Antigravity (endpoint de agente em estilo Cloud Code Assist). -- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (auth separada + peculiaridades próprias de tooling). +- `google-antigravity/...` usa a ponte OAuth Antigravity (endpoint de agente no estilo Cloud Code Assist). +- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (autenticação separada + peculiaridades de ferramentas). - API Gemini vs CLI Gemini: - - API: o OpenClaw chama a API Gemini hospedada do Google por HTTP (auth por chave de API / perfil); é isso que a maioria dos usuários quer dizer com “Gemini”. - - CLI: o OpenClaw faz shell out para um binário local `gemini`; ele tem auth própria e pode se comportar de forma diferente (streaming/suporte a ferramentas/defasagem de versão). + - API: o OpenClaw chama a API Gemini hospedada do Google via HTTP (autenticação por chave de API / perfil); é isso que a maioria dos usuários quer dizer com “Gemini”. + - CLI: o OpenClaw executa um binário local `gemini`; ele tem sua própria autenticação e pode se comportar de maneira diferente (streaming/suporte a ferramentas/desalinhamento de versão). ## Live: matriz de modelos (o que cobrimos) -Não existe uma “lista fixa de modelos no CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. +Não há uma “lista fixa de modelos do CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. -### Conjunto de smoke moderno (chamada de ferramenta + imagem) +### Conjunto moderno de smoke (chamada de ferramentas + imagem) -Esta é a execução de “modelos comuns” que esperamos continuar funcionando: +Esta é a execução de “modelos comuns” que esperamos manter funcionando: - OpenAI (não-Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -665,10 +666,10 @@ Esta é a execução de “modelos comuns” que esperamos continuar funcionando - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Execute smoke do Gateway com ferramentas + imagem: +Execute o teste de fumaça do gateway com ferramentas + imagem: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Linha de base: chamada de ferramenta (Read + Exec opcional) +### Baseline: chamada de ferramentas (Read + Exec opcional) Escolha pelo menos um por família de provedor: @@ -680,28 +681,28 @@ Escolha pelo menos um por família de provedor: Cobertura adicional opcional (bom ter): -- xAI: `xai/grok-4` (ou o mais recente disponível) -- Mistral: `mistral/`… (escolha um modelo com capacidade de ferramentas que você tenha habilitado) +- xAI: `xai/grok-4` (ou a mais recente disponível) +- Mistral: `mistral/`… (escolha um modelo com capacidade de `tools` que você tenha habilitado) - Cerebras: `cerebras/`… (se você tiver acesso) -- LM Studio: `lmstudio/`… (local; a chamada de ferramenta depende do modo da API) +- LM Studio: `lmstudio/`… (local; a chamada de ferramentas depende do modo da API) ### Vision: envio de imagem (anexo → mensagem multimodal) -Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes com suporte a vision do Claude/Gemini/OpenAI etc.) para exercitar o probe de imagem. +Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes com suporte a visão do Claude/Gemini/OpenAI etc.) para exercitar a sonda de imagem. ### Agregadores / gateways alternativos Se você tiver chaves habilitadas, também oferecemos suporte a testes via: -- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de ferramenta+imagem) -- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (auth via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com suporte a ferramenta+imagem) +- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (autenticação via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Mais provedores que você pode incluir na matriz live (se tiver creds/config): +Mais provedores que você pode incluir na matriz live (se tiver credenciais/config): - Embutidos: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Via `models.providers` (endpoints personalizados): `minimax` (nuvem/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) +- Via `models.providers` (endpoints personalizados): `minimax` (cloud/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) -Dica: não tente fixar “todos os modelos” na documentação. A lista autoritativa é tudo o que `discoverModels(...)` retorna na sua máquina + todas as chaves disponíveis. +Dica: não tente codificar “todos os modelos” na documentação. A lista autoritativa é tudo o que `discoverModels(...)` retornar na sua máquina + quaisquer chaves disponíveis. ## Credenciais (nunca faça commit) @@ -710,32 +711,32 @@ Os testes live descobrem credenciais da mesma forma que a CLI. Implicações pr - Se a CLI funciona, os testes live devem encontrar as mesmas chaves. - Se um teste live disser “sem credenciais”, depure da mesma forma que você depuraria `openclaw models list` / seleção de modelo. -- Perfis de auth por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) +- Perfis de autenticação por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) - Config: `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) -- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para o home live preparado quando presente, mas não é o armazenamento principal de chaves de perfil) -- Execuções live locais copiam por padrão a config ativa, arquivos `auth-profiles.json` por agente, `credentials/` legada e diretórios de auth de CLI externos compatíveis para um home temporário de teste; homes live preparados ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que os probes fiquem fora do seu workspace real do host. +- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para a home live preparada quando presente, mas não é o armazenamento principal de chaves de perfil) +- Execuções live locais copiam por padrão a configuração ativa, arquivos `auth-profiles.json` por agente, `credentials/` legados e diretórios de autenticação de CLI externa suportados para uma home temporária de teste; as homes live preparadas ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que as sondas fiquem fora do seu workspace real do host. -Se você quiser depender de chaves por env (por exemplo, exportadas no seu `~/.profile`), execute testes locais após `source ~/.profile`, ou use os executores Docker abaixo (eles podem montar `~/.profile` dentro do container). +Se quiser depender de chaves em env (por exemplo, exportadas no seu `~/.profile`), execute os testes locais após `source ~/.profile`, ou use os executores Docker abaixo (eles podem montar `~/.profile` no contêiner). ## Live do Deepgram (transcrição de áudio) - Teste: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live do plano de código BytePlus +## Live do plano de codificação do BytePlus - Teste: `src/agents/byteplus.live.test.ts` - Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Substituição opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live de mídia de fluxo de trabalho ComfyUI +## Live de mídia de workflow do ComfyUI - Teste: `extensions/comfy/comfy.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Escopo: - Exercita os caminhos empacotados de imagem, vídeo e `music_generate` do comfy - - Ignora cada capacidade a menos que `models.providers.comfy.` esteja configurado - - Útil após mudar envio de workflow do comfy, polling, downloads ou registro de Plugin + - Ignora cada capacidade, a menos que `models.providers.comfy.` esteja configurado + - Útil após alterar envio de workflow do comfy, polling, downloads ou registro do Plugin ## Live de geração de imagem @@ -744,23 +745,23 @@ Se você quiser depender de chaves por env (por exemplo, exportadas no seu `~/.p - Harness: `pnpm test:live:media image` - Escopo: - Enumera todos os Plugins de provedor de geração de imagem registrados - - Carrega variáveis de ambiente de provedor ausentes a partir do seu shell de login (`~/.profile`) antes dos probes - - Usa por padrão chaves de API live/env antes de perfis de auth armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell - - Ignora provedores sem auth/perfil/modelo utilizável + - Carrega variáveis de ambiente ausentes de provedores a partir do seu shell de login (`~/.profile`) antes de sondar + - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem autenticação/perfil/modelo utilizável - Executa as variantes padrão de geração de imagem pela capacidade compartilhada de runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Provedores empacotados atualmente cobertos: +- Provedores empacotados atuais cobertos: - `openai` - `google` - Restrição opcional: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamento opcional de auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth pelo armazenamento de perfis e ignorar substituições apenas por env +- Comportamento opcional de autenticação: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições apenas de env ## Live de geração de música @@ -770,9 +771,9 @@ Se você quiser depender de chaves por env (por exemplo, exportadas no seu `~/.p - Escopo: - Exercita o caminho compartilhado empacotado de provedor de geração de música - Atualmente cobre Google e MiniMax - - Carrega variáveis de ambiente de provedor a partir do seu shell de login (`~/.profile`) antes dos probes - - Usa por padrão chaves de API live/env antes de perfis de auth armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell - - Ignora provedores sem auth/perfil/modelo utilizável + - Carrega variáveis de ambiente de provedores do seu shell de login (`~/.profile`) antes de sondar + - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem autenticação/perfil/modelo utilizável - Executa ambos os modos de runtime declarados quando disponíveis: - `generate` com entrada apenas de prompt - `edit` quando o provedor declara `capabilities.edit.enabled` @@ -783,8 +784,8 @@ Se você quiser depender de chaves por env (por exemplo, exportadas no seu `~/.p - Restrição opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento opcional de auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth pelo armazenamento de perfis e ignorar substituições apenas por env +- Comportamento opcional de autenticação: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições apenas de env ## Live de geração de vídeo @@ -793,54 +794,54 @@ Se você quiser depender de chaves por env (por exemplo, exportadas no seu `~/.p - Harness: `pnpm test:live:media video` - Escopo: - Exercita o caminho compartilhado empacotado de provedor de geração de vídeo - - Usa por padrão o caminho de smoke seguro para release: provedores não-FAL, uma requisição text-to-video por provedor, prompt lobster de um segundo e um limite de operação por provedor vindo de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) - - Ignora FAL por padrão porque a latência da fila do lado do provedor pode dominar o tempo de release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente - - Carrega variáveis de ambiente de provedor a partir do seu shell de login (`~/.profile`) antes dos probes - - Usa por padrão chaves de API live/env antes de perfis de auth armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell - - Ignora provedores sem auth/perfil/modelo utilizável + - Usa por padrão o caminho de smoke seguro para release: provedores sem FAL, uma solicitação de texto para vídeo por provedor, prompt de lagosta de um segundo e um limite de operação por provedor a partir de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) + - Ignora FAL por padrão porque a latência da fila no lado do provedor pode dominar o tempo da release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente + - Carrega variáveis de ambiente de provedores do seu shell de login (`~/.profile`) antes de sondar + - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem autenticação/perfil/modelo utilizável - Executa apenas `generate` por padrão - Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de transformação declarados quando disponíveis: - - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de imagem com suporte de buffer na varredura compartilhada - - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de vídeo com suporte de buffer na varredura compartilhada - - Provedores `imageToVideo` atualmente declarados mas ignorados na varredura compartilhada: - - `vydra` porque o `veo3` empacotado é apenas texto e o `kling` empacotado exige uma URL remota de imagem - - Cobertura específica de provedor Vydra: + - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada de imagem local com suporte de buffer na varredura compartilhada + - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada de vídeo local com suporte de buffer na varredura compartilhada + - Provedores `imageToVideo` atualmente declarados, mas ignorados, na varredura compartilhada: + - `vydra` porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL de imagem remota + - Cobertura Vydra específica do provedor: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - esse arquivo executa `veo3` text-to-video mais uma faixa `kling` que usa por padrão uma fixture de URL remota de imagem + - esse arquivo executa `veo3` de texto para vídeo, mais uma faixa `kling` que usa por padrão uma fixture de URL de imagem remota - Cobertura live atual de `videoToVideo`: - - apenas `runway` quando o modelo selecionado é `runway/gen4_aleph` - - Provedores `videoToVideo` atualmente declarados mas ignorados na varredura compartilhada: + - `runway` apenas quando o modelo selecionado é `runway/gen4_aleph` + - Provedores `videoToVideo` atualmente declarados, mas ignorados, na varredura compartilhada: - `alibaba`, `qwen`, `xai` porque esses caminhos atualmente exigem URLs de referência remotas `http(s)` / MP4 - `google` porque a faixa compartilhada atual Gemini/Veo usa entrada local com suporte de buffer e esse caminho não é aceito na varredura compartilhada - - `openai` porque a faixa compartilhada atual não tem garantias de acesso específico de organização para inpaint/remix de vídeo + - `openai` porque a faixa compartilhada atual não garante acesso específico da organização a inpaint/remix de vídeo - Restrição opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos os provedores na varredura padrão, incluindo FAL - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reduzir o limite de operação de cada provedor em uma execução de smoke agressiva -- Comportamento opcional de auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth pelo armazenamento de perfis e ignorar substituições apenas por env +- Comportamento opcional de autenticação: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições apenas de env ## Harness live de mídia - Comando: `pnpm test:live:media` -- Objetivo: +- Finalidade: - Executa as suítes live compartilhadas de imagem, música e vídeo por um único entrypoint nativo do repositório - - Carrega automaticamente variáveis de ambiente de provedor ausentes a partir de `~/.profile` - - Restringe automaticamente cada suíte por padrão aos provedores que atualmente têm auth utilizável - - Reutiliza `scripts/test-live.mjs`, para que o comportamento de Heartbeat e modo silencioso permaneça consistente + - Carrega automaticamente variáveis de ambiente ausentes de provedores a partir de `~/.profile` + - Restringe automaticamente cada suíte aos provedores que atualmente têm autenticação utilizável por padrão + - Reutiliza `scripts/test-live.mjs`, então o comportamento de Heartbeat e modo silencioso permanece consistente - Exemplos: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Executores Docker (verificações opcionais de "funciona em Linux") +## Executores Docker (verificações opcionais de “funciona no Linux”) Esses executores Docker se dividem em dois grupos: -- Executores live-model: `test:docker:live-models` e `test:docker:live-gateway` executam apenas seu arquivo live correspondente de chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de config e workspace (e obtendo `~/.profile` se ele estiver montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. -- Os executores live do Docker usam por padrão um limite menor de smoke para que uma varredura Docker completa continue prática: +- Executores live de modelos: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o arquivo live de chave de perfil correspondente dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de config e workspace (e carregando `~/.profile` se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. +- Os executores Docker live usam por padrão um limite de smoke menor para que uma varredura Docker completa permaneça prática: `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e `test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, @@ -848,115 +849,116 @@ Esses executores Docker se dividem em dois grupos: `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando quiser explicitamente a varredura exaustiva maior. - `test:docker:all` constrói a imagem Docker live uma vez via `test:docker:live-build` e depois a reutiliza para as duas faixas Docker live. -- Executores de smoke em container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais containers reais e verificam caminhos de integração de nível mais alto. +- Executores de smoke em contêiner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto. -Os executores Docker de live-model também fazem bind-mount apenas dos homes de auth de CLI necessários (ou de todos os compatíveis quando a execução não está restringida), depois os copiam para o home do container antes da execução para que OAuth de CLI externa possa atualizar tokens sem alterar o armazenamento de auth do host: +Os executores Docker live de modelos também fazem bind-mount apenas dos homes de autenticação CLI necessários (ou de todos os suportados quando a execução não está restrita), e então os copiam para o home do contêiner antes da execução para que OAuth de CLI externa possa atualizar tokens sem alterar o armazenamento de autenticação do host: - Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke de bind do ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Smoke de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) - Smoke de backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Smoke do harness app-server do Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) - Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Assistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Rede do Gateway (dois containers, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Ponte de canal MCP (Gateway semeado + ponte stdio + smoke bruto de frame de notificação do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Networking do Gateway (dois contêineres, autenticação WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Ponte de canal MCP (Gateway inicializado com seed + ponte stdio + smoke bruto de quadro de notificação do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) - Plugins (smoke de instalação + alias `/plugin` + semântica de reinício do bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Os executores Docker de live-model também fazem bind-mount do checkout atual como somente leitura e -o preparam em um workdir temporário dentro do container. Isso mantém a imagem de runtime -enxuta, mas ainda executa Vitest exatamente contra seu código-fonte/config local. -A etapa de preparação ignora grandes caches apenas locais e saídas de build de apps, como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de `.build` do app ou -saídas do Gradle, para que execuções live no Docker não gastem minutos copiando +Os executores Docker live de modelos também fazem bind-mount do checkout atual somente leitura e +o preparam em um diretório de trabalho temporário dentro do contêiner. Isso mantém a imagem de runtime +leve e ainda assim executa o Vitest exatamente sobre seu código-fonte/config local. +A etapa de preparação ignora caches locais grandes e saídas de build de app, como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais do app `.build` ou +saídas do Gradle, para que execuções live no Docker não passem minutos copiando artefatos específicos da máquina. -Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que probes live do Gateway não iniciem -workers reais de canais Telegram/Discord/etc. dentro do container. -`test:docker:live-models` ainda executa `pnpm test:live`, então repasse -`OPENCLAW_LIVE_GATEWAY_*` também quando precisar restringir ou excluir cobertura live do Gateway dessa faixa Docker. +Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que sondas live do gateway não iniciem +workers reais de canais como Telegram/Discord/etc. dentro do contêiner. +`test:docker:live-models` ainda executa `pnpm test:live`, então também passe +`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura live +do gateway nessa faixa Docker. `test:docker:openwebui` é um smoke de compatibilidade de nível mais alto: ele inicia um -container Gateway do OpenClaw com endpoints HTTP compatíveis com OpenAI habilitados, -inicia um container Open WebUI fixado contra esse Gateway, faz login pelo -Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma -requisição de chat real pelo proxy `/api/chat/completions` do Open WebUI. +contêiner do Gateway do OpenClaw com endpoints HTTP compatíveis com OpenAI habilitados, +inicia um contêiner do Open WebUI fixado apontando para esse gateway, faz login por +meio do Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma +requisição real de chat pelo proxy `/api/chat/completions` do Open WebUI. A primeira execução pode ser visivelmente mais lenta porque o Docker pode precisar baixar a -imagem do Open WebUI e o Open WebUI pode precisar concluir seu próprio setup de cold start. -Essa faixa espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` +imagem do Open WebUI e o próprio Open WebUI pode precisar concluir sua configuração inicial. +Essa faixa espera uma chave live de modelo utilizável, e `OPENCLAW_PROFILE_FILE` (`~/.profile` por padrão) é a forma principal de fornecê-la em execuções Dockerizadas. Execuções bem-sucedidas imprimem um pequeno payload JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` é intencionalmente determinístico e não precisa de uma -conta real de Telegram, Discord ou iMessage. Ele inicializa um container -Gateway semeado, inicia um segundo container que executa `openclaw mcp serve` e então -verifica descoberta de conversa roteada, leituras de transcrição, metadados de anexos, -comportamento da fila de eventos live, roteamento de envio de saída e notificações -de canal + permissão em estilo Claude pela ponte MCP stdio real. A verificação de notificação -inspeciona diretamente os frames MCP stdio brutos, para que o smoke valide o que a +conta real de Telegram, Discord ou iMessage. Ele inicializa um contêiner de Gateway +com seed, inicia um segundo contêiner que executa `openclaw mcp serve` e então +verifica descoberta de conversa roteada, leituras de transcrição, metadados de anexo, +comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal + +permissão no estilo Claude pela ponte stdio MCP real. A verificação de notificação +inspeciona diretamente os quadros MCP brutos do stdio para que o smoke valide o que a ponte realmente emite, não apenas o que um SDK cliente específico por acaso expõe. -Smoke manual de thread ACP em linguagem simples (não CI): +Smoke manual de thread ACP em linguagem natural (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. +- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, portanto não o exclua. Variáveis de ambiente úteis: - `OPENCLAW_CONFIG_DIR=...` (padrão: `~/.openclaw`) montado em `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (padrão: `~/.openclaw/workspace`) montado em `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e obtido antes de executar os testes -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para validar apenas variáveis de ambiente obtidas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem mounts externos de auth de CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações em cache de CLI dentro do Docker -- Diretórios/arquivos de auth de CLI externos sob `$HOME` são montados como somente leitura sob `/host-auth...`, depois copiados para `/home/node/...` antes do início dos testes +- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e carregado antes de executar os testes +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem montagens de autenticação CLI externa +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações CLI em cache dentro do Docker +- Diretórios/arquivos de autenticação CLI externa sob `$HOME` são montados somente leitura em `/host-auth...` e então copiados para `/home/node/...` antes do início dos testes - Diretórios padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Execuções restritas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Execuções com provedor restrito montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Substitua manualmente com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do container +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do contêiner - `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em reexecuções que não precisam de rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não de env) -- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo Gateway para o smoke do Open WebUI +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfil (não do env) +- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo gateway para o smoke do Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI -- `OPENWEBUI_IMAGE=...` para substituir a tag fixada da imagem Open WebUI +- `OPENWEBUI_IMAGE=...` para substituir a tag de imagem fixada do Open WebUI -## Sanidade da documentação +## Verificação da documentação -Execute verificações da documentação após edições em docs: `pnpm check:docs`. -Execute a validação completa de âncoras do Mintlify quando precisar de verificações de headings na página também: `pnpm docs:check-links:anchors`. +Execute verificações da documentação após editar docs: `pnpm check:docs`. +Execute a validação completa de âncoras do Mintlify quando também precisar verificar títulos na página: `pnpm docs:check-links:anchors`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Chamada de ferramenta do Gateway (mock OpenAI, Gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistente do Gateway (WS `wizard.start`/`wizard.next`, gravação forçada de config + auth): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Chamada de ferramentas do Gateway (mock OpenAI, gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistente do Gateway (WS `wizard.start`/`wizard.next`, grava config + autenticação exigida): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Avaliações de confiabilidade do agente (Skills) +## Evals de confiabilidade do agente (Skills) -Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade do agente”: +Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade do agente”: -- Mock de chamada de ferramenta pelo loop real de Gateway + agente (`src/gateway/gateway.test.ts`). -- Fluxos end-to-end do assistente que validam fiação de sessão e efeitos de config (`src/gateway/gateway.test.ts`). +- Chamada simulada de ferramentas pelo loop real do gateway + agente (`src/gateway/gateway.test.ts`). +- Fluxos end-to-end do assistente que validam wiring de sessão e efeitos de configuração (`src/gateway/gateway.test.ts`). -O que ainda falta para Skills (consulte [Skills](/pt-BR/tools/skills)): +O que ainda falta para Skills (veja [Skills](/pt-BR/tools/skills)): - **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a Skill correta (ou evita as irrelevantes)? - **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args obrigatórios? -- **Contratos de fluxo de trabalho:** cenários multi-turn que validam ordem de ferramentas, carryover do histórico da sessão e limites do sandbox. +- **Contratos de fluxo de trabalho:** cenários de múltiplas rodadas que verificam ordem de ferramentas, continuidade do histórico da sessão e limites de sandbox. -Avaliações futuras devem permanecer determinísticas primeiro: +Evals futuros devem permanecer determinísticos primeiro: -- Um executor de cenários usando provedores mock para validar chamadas de ferramenta + ordem, leituras de arquivo de Skill e fiação de sessão. -- Uma pequena suíte de cenários focados em Skills (usar vs evitar, gating, injeção de prompt). -- Avaliações live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver pronta. +- Um executor de cenários usando provedores simulados para verificar chamadas de ferramentas + ordem, leituras de arquivos de Skill e wiring de sessão. +- Uma pequena suíte de cenários focados em Skills (usar vs evitar, gating, prompt injection). +- Evals live opcionais (opt-in, controlados por env) somente depois que a suíte segura para CI estiver pronta. ## Testes de contrato (formato de Plugin e canal) -Os testes de contrato verificam que todo Plugin e canal registrado está em conformidade com seu -contrato de interface. Eles iteram sobre todos os Plugins descobertos e executam um conjunto de -validações de formato e comportamento. A faixa unitária padrão de `pnpm test` -intencionalmente ignora esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente -quando tocar em superfícies compartilhadas de canal ou provedor. +Testes de contrato verificam que todo Plugin e canal registrado está em conformidade com seu +contrato de interface. Eles iteram sobre todos os Plugins descobertos e executam uma suíte de +verificações de formato e comportamento. A faixa unit padrão de `pnpm test` intencionalmente +ignora esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente +quando alterar superfícies compartilhadas de canal ou provedor. ### Comandos @@ -969,12 +971,12 @@ quando tocar em superfícies compartilhadas de canal ou provedor. Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Formato básico do Plugin (id, nome, capacidades) -- **setup** - Contrato do assistente de setup +- **setup** - Contrato do assistente de configuração - **session-binding** - Comportamento de vinculação de sessão - **outbound-payload** - Estrutura do payload de mensagem -- **inbound** - Manipulação de mensagem de entrada -- **actions** - Handlers de ação do canal -- **threading** - Manipulação de ID de thread +- **inbound** - Tratamento de mensagens de entrada +- **actions** - Handlers de ação de canal +- **threading** - Tratamento de ID de thread - **directory** - API de diretório/lista - **group-policy** - Aplicação de política de grupo @@ -982,39 +984,39 @@ Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: Localizados em `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probes de status de canal -- **registry** - Formato do registro de Plugin +- **status** - Sondas de status de canal +- **registry** - Formato do registro de Plugins ### Contratos de provedor Localizados em `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato de fluxo de auth -- **auth-choice** - Escolha/seleção de auth +- **auth** - Contrato de fluxo de autenticação +- **auth-choice** - Escolha/seleção de autenticação - **catalog** - API de catálogo de modelos -- **discovery** - Descoberta de Plugin -- **loader** - Carregamento de Plugin +- **discovery** - Descoberta de Plugins +- **loader** - Carregamento de Plugins - **runtime** - Runtime do provedor - **shape** - Formato/interface do Plugin -- **wizard** - Assistente de setup +- **wizard** - Assistente de configuração ### Quando executar -- Após alterar exports ou subpaths de plugin-sdk -- Após adicionar ou modificar um canal ou Plugin de provedor -- Após refatorar registro ou descoberta de Plugin +- Depois de alterar exports ou subpaths do plugin-sdk +- Depois de adicionar ou modificar um Plugin de canal ou provedor +- Depois de refatorar registro ou descoberta de Plugins -Os testes de contrato rodam em CI e não exigem chaves reais. +Os testes de contrato rodam no CI e não exigem chaves reais de API. ## Adicionando regressões (orientação) -Quando você corrigir um problema de provedor/modelo descoberto em live: +Quando você corrige um problema de provedor/modelo descoberto em live: -- Adicione uma regressão segura para CI se possível (provedor mock/stub ou capture a transformação exata do formato da requisição) -- Se for inerentemente apenas live (limites de taxa, políticas de auth), mantenha o teste live restrito e opt-in via variáveis de ambiente -- Prefira mirar na menor camada que captura o bug: - - bug de conversão/replay da requisição do provedor → teste direto de modelos - - bug de pipeline de sessão/histórico/ferramenta do Gateway → smoke live do Gateway ou teste mock do Gateway seguro para CI -- Regra de proteção de travessia de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois valida que ids de exec de segmento de travessia são rejeitados. +- Adicione uma regressão segura para CI, se possível (provedor simulado/stub, ou capture a transformação exata do formato da requisição) +- Se for inerentemente apenas live (rate limits, políticas de autenticação), mantenha o teste live restrito e opt-in via variáveis de ambiente +- Prefira atingir a menor camada que detecta o bug: + - bug de conversão/replay de requisição do provedor → teste direto de modelos + - bug no pipeline de sessão/histórico/ferramenta do gateway → smoke live do gateway ou teste mock do gateway seguro para CI +- Guardrail de travessia de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo de amostra por classe SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois verifica que ids exec de segmento de travessia são rejeitados. - Se você adicionar uma nova família de alvo SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente. diff --git a/docs/pt-BR/platforms/macos.md b/docs/pt-BR/platforms/macos.md index 0370888fc..a70114b5f 100644 --- a/docs/pt-BR/platforms/macos.md +++ b/docs/pt-BR/platforms/macos.md @@ -1,45 +1,45 @@ --- read_when: - - Ao implementar recursos do app do macOS - - Ao alterar o ciclo de vida do gateway ou a ponte de nodes no macOS -summary: App complementar do OpenClaw para macOS (barra de menus + broker do Gateway) -title: App do macOS + - Implementando recursos do aplicativo para macOS + - Alterando o ciclo de vida do Gateway ou a ponte de Node no macOS +summary: Aplicativo complementar do OpenClaw para macOS (barra de menus + corretor do Gateway) +title: Aplicativo para macOS x-i18n: - generated_at: "2026-04-05T12:48:34Z" + generated_at: "2026-04-18T05:24:46Z" model: gpt-5.4 provider: openai - source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135 + source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0 source_path: platforms/macos.md workflow: 15 --- -# Companion do OpenClaw para macOS (barra de menus + broker do Gateway) +# Companion do OpenClaw para macOS (barra de menus + corretor do Gateway) -O app do macOS é o **companion da barra de menus** do OpenClaw. Ele controla permissões, -gerencia/se conecta ao Gateway localmente (launchd ou manual) e expõe recursos do macOS +O aplicativo para macOS é o **companion da barra de menus** do OpenClaw. Ele controla permissões, +gerencia/anexa ao Gateway localmente (launchd ou manualmente) e expõe recursos do macOS ao agente como um node. ## O que ele faz -- Mostra notificações nativas e status na barra de menus. -- Controla prompts do TCC (Notificações, Acessibilidade, Gravação de Tela, Microfone, +- Exibe notificações nativas e status na barra de menus. +- Controla os prompts do TCC (Notificações, Acessibilidade, Gravação de Tela, Microfone, Reconhecimento de Fala, Automação/AppleScript). - Executa ou se conecta ao Gateway (local ou remoto). - Expõe ferramentas exclusivas do macOS (Canvas, Câmera, Gravação de Tela, `system.run`). - Inicia o serviço local de host de node no modo **remoto** (launchd) e o interrompe no modo **local**. -- Opcionalmente hospeda a **PeekabooBridge** para automação de UI. -- Instala a CLI global (`openclaw`) sob demanda via npm, pnpm ou bun (o app prefere npm, depois pnpm, depois bun; Node continua sendo o runtime recomendado para o Gateway). +- Opcionalmente hospeda o **PeekabooBridge** para automação de UI. +- Instala a CLI global (`openclaw`) sob demanda via npm, pnpm ou bun (o app prefere npm, depois pnpm, depois bun; Node continua sendo o runtime recomendado do Gateway). -## Modo local vs remoto +## Modo local vs. remoto -- **Local** (padrão): o app se conecta a um Gateway local em execução, se houver; - caso contrário, ele habilita o serviço launchd via `openclaw gateway install`. -- **Remoto**: o app se conecta a um Gateway por SSH/Tailscale e nunca inicia +- **Local** (padrão): o app se anexa a um Gateway local em execução, se presente; + caso contrário, ele ativa o serviço launchd via `openclaw gateway install`. +- **Remoto**: o app se conecta a um Gateway via SSH/Tailscale e nunca inicia um processo local. - O app inicia o **serviço local de host de node** para que o Gateway remoto possa alcançar este Mac. - O app não inicia o Gateway como um processo filho. - A descoberta do Gateway agora prefere nomes MagicDNS do Tailscale a IPs brutos da tailnet, - para que o app do Mac se recupere com mais confiabilidade quando os IPs da tailnet mudarem. + O app inicia o **serviço de host de node** local para que o Gateway remoto possa alcançar este Mac. + O app não inicia o Gateway como processo filho. + A descoberta do Gateway agora prefere nomes Tailscale MagicDNS em vez de IPs brutos da tailnet, + então o app para Mac se recupera com mais confiabilidade quando os IPs da tailnet mudam. ## Controle do launchd @@ -51,26 +51,26 @@ launchctl kickstart -k gui/$UID/ai.openclaw.gateway launchctl bootout gui/$UID/ai.openclaw.gateway ``` -Substitua o rótulo por `ai.openclaw.` ao executar com um perfil nomeado. +Substitua o rótulo por `ai.openclaw.` ao executar um perfil nomeado. -Se o LaunchAgent não estiver instalado, habilite-o pelo app ou execute +Se o LaunchAgent não estiver instalado, ative-o pelo app ou execute `openclaw gateway install`. -## Recursos do node (Mac) +## Recursos do node (mac) -O app do macOS se apresenta como um node. Comandos comuns: +O app para macOS se apresenta como um node. Comandos comuns: - Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` - Câmera: `camera.snap`, `camera.clip` -- Tela: `screen.record` +- Tela: `screen.snapshot`, `screen.record` - Sistema: `system.run`, `system.notify` -O node informa um mapa `permissions` para que os agentes possam decidir o que é permitido. +O node relata um mapa `permissions` para que agentes possam decidir o que é permitido. Serviço de node + IPC do app: -- Quando o serviço headless de host de node está em execução (modo remoto), ele se conecta ao WS do Gateway como um node. -- `system.run` é executado no app do macOS (contexto de UI/TCC) por um socket Unix local; prompts + saída permanecem no app. +- Quando o serviço headless de host de node está em execução (modo remoto), ele se conecta ao Gateway WS como um node. +- `system.run` é executado no app para macOS (contexto UI/TCC) por um socket Unix local; prompts + saída permanecem no app. Diagrama (SCI): @@ -83,8 +83,8 @@ Gateway -> Node Service (WS) ## Aprovações de execução (`system.run`) -`system.run` é controlado por **aprovações de execução** no app do macOS (Configurações → Aprovações de execução). -Segurança + pergunta + allowlist são armazenados localmente no Mac em: +`system.run` é controlado por **Aprovações de execução** no app para macOS (Ajustes → Aprovações de execução). +Segurança + perguntar + allowlist são armazenados localmente no Mac em: ``` ~/.openclaw/exec-approvals.json @@ -111,12 +111,12 @@ Exemplo: Observações: -- Entradas de `allowlist` são padrões glob para caminhos de binários resolvidos. +- Entradas de `allowlist` são padrões glob para caminhos resolvidos de binários. - Texto bruto de comando shell que contém sintaxe de controle ou expansão do shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) é tratado como ausência na allowlist e exige aprovação explícita (ou inclusão do binário do shell na allowlist). - Escolher “Sempre permitir” no prompt adiciona esse comando à allowlist. -- Substituições de ambiente de `system.run` são filtradas (remove `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) e depois mescladas com o ambiente do app. -- Para wrappers de shell (`bash|sh|zsh ... -c/-lc`), as substituições de ambiente no escopo da solicitação são reduzidas a uma pequena allowlist explícita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -- Para decisões de sempre permitir no modo allowlist, wrappers de despacho conhecidos (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistem caminhos do executável interno em vez dos caminhos do wrapper. Se o desembrulho não for seguro, nenhuma entrada de allowlist é persistida automaticamente. +- As substituições de ambiente de `system.run` são filtradas (remove `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) e então mescladas com o ambiente do app. +- Para wrappers de shell (`bash|sh|zsh ... -c/-lc`), as substituições de ambiente com escopo de solicitação são reduzidas a uma pequena allowlist explícita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +- Para decisões de sempre permitir no modo allowlist, wrappers de despacho conhecidos (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistem os caminhos internos do executável em vez dos caminhos do wrapper. Se o desembrulho não for seguro, nenhuma entrada de allowlist será persistida automaticamente. ## Links profundos @@ -124,9 +124,9 @@ O app registra o esquema de URL `openclaw://` para ações locais. ### `openclaw://agent` -Aciona uma solicitação `agent` do Gateway. +Dispara uma solicitação `agent` do Gateway. __OC_I18N_900004__ -Parâmetros da query: +Parâmetros de consulta: - `message` (obrigatório) - `sessionKey` (opcional) @@ -143,18 +143,18 @@ Segurança: ## Fluxo de onboarding (típico) -1. Instale e execute o **OpenClaw.app**. +1. Instale e abra o **OpenClaw.app**. 2. Conclua a checklist de permissões (prompts do TCC). 3. Garanta que o modo **Local** esteja ativo e que o Gateway esteja em execução. 4. Instale a CLI se quiser acesso pelo terminal. -## Localização do diretório de estado (macOS) +## Posicionamento do diretório de estado (macOS) -Evite colocar seu diretório de estado do OpenClaw no iCloud ou em outras pastas sincronizadas pela nuvem. -Caminhos com sincronização em segundo plano podem adicionar latência e ocasionalmente causar condições de corrida de bloqueio de arquivo/sincronização para +Evite colocar seu diretório de estado do OpenClaw no iCloud ou em outras pastas sincronizadas com a nuvem. +Caminhos com sincronização podem adicionar latência e ocasionalmente causar condições de corrida de bloqueio de arquivo/sincronização para sessões e credenciais. -Prefira um caminho de estado local sem sincronização, como: +Prefira um caminho de estado local não sincronizado, como: __OC_I18N_900005__ Se `openclaw doctor` detectar estado em: @@ -163,60 +163,60 @@ Se `openclaw doctor` detectar estado em: ele emitirá um aviso e recomendará voltar para um caminho local. -## Workflow de build e desenvolvimento (nativo) +## Fluxo de build e desenvolvimento (nativo) - `cd apps/macos && swift build` - `swift run OpenClaw` (ou Xcode) -- Empacotar o app: `scripts/package-mac-app.sh` +- Empacotar app: `scripts/package-mac-app.sh` -## Depurar conectividade com o Gateway (CLI do macOS) +## Depurar conectividade do Gateway (CLI do macOS) -Use a CLI de depuração para exercitar o mesmo handshake WebSocket do Gateway e a mesma lógica de descoberta -que o app do macOS usa, sem iniciar o app. +Use a CLI de depuração para exercitar o mesmo handshake e a mesma lógica de descoberta do Gateway WebSocket +que o app para macOS usa, sem abrir o app. __OC_I18N_900006__ Opções de conexão: - `--url `: substitui a configuração - `--mode `: resolve a partir da configuração (padrão: configuração ou local) -- `--probe`: força uma sondagem de integridade nova +- `--probe`: força uma nova sondagem de saúde - `--timeout `: tempo limite da solicitação (padrão: `15000`) -- `--json`: saída estruturada para comparação +- `--json`: saída estruturada para diff Opções de descoberta: - `--include-local`: inclui gateways que seriam filtrados como “locais” -- `--timeout `: janela geral de descoberta (padrão: `2000`) -- `--json`: saída estruturada para comparação +- `--timeout `: janela total de descoberta (padrão: `2000`) +- `--json`: saída estruturada para diff Dica: compare com `openclaw gateway discover --json` para ver se o -pipeline de descoberta do app do macOS (`local.` mais o domínio de longa distância configurado, com -fallbacks de longa distância e Tailscale Serve) difere do -descobrimento baseado em `dns-sd` da CLI em Node. +pipeline de descoberta do app para macOS (`local.` mais o domínio de área ampla configurado, com +fallbacks de área ampla e Tailscale Serve) difere da +descoberta baseada em `dns-sd` da CLI do Node. -## Infraestrutura de conexão remota (túneis SSH) +## Infraestrutura da conexão remota (túneis SSH) -Quando o app do macOS é executado no modo **Remoto**, ele abre um túnel SSH para que componentes locais de UI -possam conversar com um Gateway remoto como se ele estivesse em localhost. +Quando o app para macOS é executado no modo **Remoto**, ele abre um túnel SSH para que componentes locais da UI +possam se comunicar com um Gateway remoto como se ele estivesse no localhost. ### Túnel de controle (porta WebSocket do Gateway) -- **Objetivo:** verificações de integridade, status, Chat Web, configuração e outras chamadas do plano de controle. +- **Finalidade:** verificações de integridade, status, Web Chat, configuração e outras chamadas do plano de controle. - **Porta local:** a porta do Gateway (padrão `18789`), sempre estável. - **Porta remota:** a mesma porta do Gateway no host remoto. - **Comportamento:** sem porta local aleatória; o app reutiliza um túnel íntegro existente - ou o reinicia se necessário. -- **Formato do SSH:** `ssh -N -L :127.0.0.1:` com BatchMode + - ExitOnForwardFailure + opções de keepalive. -- **Relato de IP:** o túnel SSH usa loopback, então o gateway verá o IP do node - como `127.0.0.1`. Use o transporte **Direct (ws/wss)** se quiser que o IP real do cliente - apareça (consulte [acesso remoto no macOS](/platforms/mac/remote)). + ou o reinicia, se necessário. +- **Formato do SSH:** `ssh -N -L :127.0.0.1:` com opções BatchMode + + ExitOnForwardFailure + keepalive. +- **Relato de IP:** o túnel SSH usa loopback, então o gateway verá o + IP do node como `127.0.0.1`. Use o transporte **Direct (ws/wss)** se quiser que o IP real do cliente + apareça (veja [acesso remoto no macOS](/pt-BR/platforms/mac/remote)). -Para as etapas de configuração, consulte [acesso remoto no macOS](/platforms/mac/remote). Para detalhes -do protocolo, consulte [protocolo do Gateway](/pt-BR/gateway/protocol). +Para etapas de configuração, veja [acesso remoto no macOS](/pt-BR/platforms/mac/remote). Para detalhes do protocolo, +veja [protocolo do Gateway](/pt-BR/gateway/protocol). ## Documentação relacionada - [Runbook do Gateway](/pt-BR/gateway) - [Gateway (macOS)](/pt-BR/platforms/mac/bundled-gateway) -- [permissões do macOS](/platforms/mac/permissions) +- [Permissões do macOS](/pt-BR/platforms/mac/permissions) - [Canvas](/pt-BR/platforms/mac/canvas) diff --git a/docs/pt-BR/plugins/sdk-channel-plugins.md b/docs/pt-BR/plugins/sdk-channel-plugins.md index 7020e07a9..840548317 100644 --- a/docs/pt-BR/plugins/sdk-channel-plugins.md +++ b/docs/pt-BR/plugins/sdk-channel-plugins.md @@ -2,113 +2,88 @@ read_when: - Você está criando um novo Plugin de canal de mensagens - Você quer conectar o OpenClaw a uma plataforma de mensagens - - Você precisa entender a superfície do adaptador `ChannelPlugin` + - Você precisa entender a superfície do adaptador ChannelPlugin sidebarTitle: Channel Plugins -summary: Guia passo a passo para criar um Plugin de canal de mensagens para OpenClaw +summary: Guia passo a passo para criar um Plugin de canal de mensagens para o OpenClaw title: Criando Plugins de canal x-i18n: - generated_at: "2026-04-15T19:41:41Z" + generated_at: "2026-04-18T05:25:12Z" model: gpt-5.4 provider: openai - source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b + source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Criando Plugins de canal -Este guia mostra como criar um Plugin de canal que conecta o OpenClaw a uma -plataforma de mensagens. Ao final, você terá um canal funcional com segurança em DM, -emparelhamento, encadeamento de respostas e mensagens de saída. +Este guia mostra passo a passo como criar um Plugin de canal que conecta o OpenClaw a uma plataforma de mensagens. Ao final, você terá um canal funcional com segurança de DM, emparelhamento, encadeamento de respostas e mensagens de saída. - Se você ainda não criou nenhum Plugin do OpenClaw antes, leia - [Primeiros passos](/pt-BR/plugins/building-plugins) primeiro para entender a estrutura - básica do pacote e a configuração do manifesto. + Se você ainda não criou nenhum Plugin do OpenClaw, leia + [Primeiros passos](/pt-BR/plugins/building-plugins) primeiro para entender a + estrutura básica do pacote e a configuração do manifesto. ## Como os Plugins de canal funcionam -Os Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma -ferramenta `message` compartilhada no core. Seu Plugin é responsável por: +Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma ferramenta `message` compartilhada no core. Seu Plugin é responsável por: - **Configuração** — resolução de conta e assistente de configuração - **Segurança** — política de DM e listas de permissão - **Emparelhamento** — fluxo de aprovação de DM -- **Gramática de sessão** — como ids de conversa específicos do provedor são mapeados para chats base, ids de thread e fallbacks de pai +- **Gramática de sessão** — como IDs de conversa específicos do provedor são mapeados para chats-base, IDs de thread e fallbacks de pai - **Saída** — envio de texto, mídia e enquetes para a plataforma - **Encadeamento** — como as respostas são encadeadas -O core é responsável pela ferramenta de mensagem compartilhada, pela integração com o prompt, pelo formato externo da chave de sessão, -pela lógica genérica de `:thread:`, e pelo despacho. +O core é responsável pela ferramenta de mensagem compartilhada, ligação do prompt, o formato externo da chave de sessão, o controle genérico de `:thread:` e o despacho. -Se o seu canal adicionar parâmetros da ferramenta de mensagem que carregam fontes de mídia, exponha esses -nomes de parâmetro por meio de `describeMessageTool(...).mediaSourceParams`. O core usa -essa lista explícita para normalização de caminho em sandbox e política de acesso -a mídia de saída, para que os Plugins não precisem de casos especiais no core compartilhado para parâmetros específicos do provedor, -como avatar, anexo ou imagem de capa. +Se o seu canal adicionar parâmetros à ferramenta de mensagem que carreguem fontes de mídia, exponha esses nomes de parâmetros por meio de `describeMessageTool(...).mediaSourceParams`. O core usa essa lista explícita para normalização de caminhos do sandbox e para a política de acesso a mídia de saída, então os plugins não precisam de casos especiais no core compartilhado para parâmetros específicos do provedor, como avatar, anexo ou imagem de capa. Prefira retornar um mapa indexado por ação, como -`{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que ações não relacionadas não -herdem os argumentos de mídia de outra ação. Um array simples ainda funciona para parâmetros que -são intencionalmente compartilhados entre todas as ações expostas. +`{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que ações não relacionadas não herdem os argumentos de mídia de outra ação. Um array simples ainda funciona para parâmetros compartilhados intencionalmente entre todas as ações expostas. -Se a sua plataforma armazenar escopo extra dentro dos ids de conversa, mantenha essa lógica de parsing -no Plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico para mapear -`rawId` para o id da conversa base, id opcional de thread, -`baseConversationId` explícito e quaisquer `parentConversationCandidates`. -Quando você retornar `parentConversationCandidates`, mantenha-os ordenados do -pai mais específico para a conversa base/mais ampla. +Se a sua plataforma armazenar escopo extra dentro dos IDs de conversa, mantenha essa análise no plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico para mapear `rawId` para o ID da conversa-base, ID de thread opcional, `baseConversationId` explícito e quaisquer `parentConversationCandidates`. +Ao retornar `parentConversationCandidates`, mantenha-os ordenados do pai mais específico para a conversa-pai mais ampla/base. -Plugins empacotados que precisam do mesmo parsing antes de o registro de canais ser inicializado -também podem expor um arquivo de nível superior `session-key-api.ts` com uma exportação -`resolveSessionConversation(...)` correspondente. O core usa essa superfície segura para bootstrap -apenas quando o registro de Plugins em runtime ainda não está disponível. +Plugins empacotados que precisem da mesma análise antes de o registro do canal ser inicializado também podem expor um arquivo `session-key-api.ts` de nível superior com uma exportação correspondente `resolveSessionConversation(...)`. O core usa essa superfície segura para bootstrap somente quando o registro de plugins em runtime ainda não está disponível. -`messaging.resolveParentConversationCandidates(...)` continua disponível como -fallback legado de compatibilidade quando um Plugin só precisa de fallbacks de pai -sobre o id genérico/raw. Se ambos os hooks existirem, o core usa -`resolveSessionConversation(...).parentConversationCandidates` primeiro e só -recorre a `resolveParentConversationCandidates(...)` quando o hook canônico -os omite. +`messaging.resolveParentConversationCandidates(...)` continua disponível como fallback legado de compatibilidade quando um plugin só precisa de fallbacks de pai sobre o ID genérico/bruto. Se ambos os hooks existirem, o core usa primeiro `resolveSessionConversation(...).parentConversationCandidates` e só faz fallback para `resolveParentConversationCandidates(...)` quando o hook canônico os omite. ## Aprovações e capacidades do canal -A maioria dos Plugins de canal não precisa de código específico para aprovações. +A maioria dos Plugins de canal não precisa de código específico para aprovação. -- O core é responsável por `/approve` no mesmo chat, payloads compartilhados de botão de aprovação e entrega genérica de fallback. -- Prefira um único objeto `approvalCapability` no Plugin de canal quando o canal precisar de comportamento específico para aprovações. -- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/renderização/autorização nativa de aprovação em `approvalCapability`. -- `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autorização de aprovação desse objeto. -- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a superfície canônica para autorização de aprovação. -- Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autorização de aprovação no mesmo chat. -- Se o seu canal expuser aprovações nativas de execução, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autorização de aprovação no mesmo chat. O core usa esse hook específico de execução para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de execução e incluir o canal na orientação de fallback do cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum. -- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais duplicados de aprovação ou enviar indicadores de digitação antes da entrega. -- Use `approvalCapability.delivery` apenas para roteamento nativo de aprovação ou supressão de fallback. -- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa controlados pelo canal. Mantenha-o lazy em pontos de entrada críticos do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda e ainda permitir que o core monte o ciclo de vida da aprovação. +- O core é responsável por `/approve` no mesmo chat, payloads compartilhados de botão de aprovação e entrega genérica por fallback. +- Prefira um único objeto `approvalCapability` no Plugin de canal quando o canal precisar de comportamento específico de aprovação. +- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/aprovação nativa/renderização/autenticação em `approvalCapability`. +- `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autenticação de aprovação desse objeto. +- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a superfície canônica para autenticação de aprovação. +- Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autenticação de aprovação no mesmo chat. +- Se o seu canal expõe aprovações nativas de exec, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autenticação de aprovação no mesmo chat. O core usa esse hook específico de exec para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de exec e incluir o canal nas orientações de fallback do cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum. +- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamentos específicos do ciclo de vida do payload no canal, como ocultar prompts locais de aprovação duplicados ou enviar indicadores de digitação antes da entrega. +- Use `approvalCapability.delivery` apenas para roteamento de aprovação nativa ou supressão de fallback. +- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa pertencentes ao canal. Mantenha-o lazy em pontos de entrada críticos do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda enquanto ainda permite que o core monte o ciclo de vida de aprovação. - Use `approvalCapability.render` apenas quando um canal realmente precisar de payloads de aprovação personalizados em vez do renderizador compartilhado. -- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique exatamente quais opções de configuração são necessárias para habilitar aprovações nativas de execução. O hook recebe `{ channel, channelLabel, accountId }`; canais com contas nomeadas devem renderizar caminhos com escopo de conta, como `channels..accounts..execApprovals.*`, em vez de padrões de nível superior. -- Se um canal puder inferir identidades estáveis semelhantes a proprietário em DM a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core. -- Se um canal precisar de entrega nativa de aprovação, mantenha o código do canal focado em normalização de alvo mais fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal atrás de `approvalCapability.nativeRuntime`, idealmente por meio de `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e controlar filtragem de solicitações, roteamento, eliminação de duplicatas, expiração, assinatura do Gateway e avisos de roteamento para outro local. `nativeRuntime` é dividido em algumas superfícies menores: -- `availability` — se a conta está configurada e se uma solicitação deve ser tratada -- `presentation` — mapeia o modelo de visualização compartilhado de aprovação em payloads nativos pendentes/resolvidos/expirados ou ações finais -- `transport` — prepara alvos e envia/atualiza/remove mensagens nativas de aprovação +- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta no caminho desabilitado explique exatamente quais controles de configuração são necessários para habilitar aprovações nativas de exec. O hook recebe `{ channel, channelLabel, accountId }`; canais com conta nomeada devem renderizar caminhos com escopo por conta, como `channels..accounts..execApprovals.*`, em vez de padrões de nível superior. +- Se um canal puder inferir identidades de DM estáveis semelhantes a proprietário a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core. +- Se um canal precisar de entrega de aprovação nativa, mantenha o código do canal focado em normalização de destino mais fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal em `approvalCapability.nativeRuntime`, idealmente via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e ser responsável por filtragem de requisição, roteamento, deduplicação, expiração, inscrição no Gateway e avisos de roteamento alternativo. `nativeRuntime` é dividido em algumas superfícies menores: +- `availability` — se a conta está configurada e se uma requisição deve ser tratada +- `presentation` — mapeia o view model compartilhado de aprovação para payloads nativos pendentes/resolvidos/expirados ou ações finais +- `transport` — prepara destinos mais envio/atualização/exclusão de mensagens nativas de aprovação - `interactions` — hooks opcionais de bind/unbind/clear-action para botões nativos ou reações - `observe` — hooks opcionais de diagnóstico de entrega -- Se o canal precisar de objetos controlados pelo runtime, como um cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar glue de wrapper específico para aprovação. +- Se o canal precisar de objetos pertencentes ao runtime, como um client, token, app Bolt ou receptor de webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar cola wrapper específica de aprovação. - Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de nível mais baixo apenas quando a superfície orientada por capacidade ainda não for expressiva o suficiente. -- Canais com aprovação nativa devem rotear `accountId` e `approvalKind` por esses helpers. `accountId` mantém a política de aprovação multiconta restrita à conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de execução vs Plugin disponível para o canal sem ramificações codificadas no core. -- O core agora também é responsável por avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador. -- Preserve a categoria do id de aprovação entregue de ponta a ponta. Clientes nativos não devem - inferir nem reescrever o roteamento de aprovação de execução vs Plugin com base no estado local do canal. -- Diferentes tipos de aprovação podem expor intencionalmente diferentes superfícies nativas. - Exemplos atuais empacotados: - - O Slack mantém o roteamento nativo de aprovação disponível tanto para ids de execução quanto de Plugin. - - O Matrix mantém o mesmo roteamento nativo por DM/canal e a mesma UX de reação para aprovações de execução - e de Plugin, ao mesmo tempo em que ainda permite que a autorização difira por tipo de aprovação. -- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas código novo deve preferir o builder de capacidade e expor `approvalCapability` no Plugin. +- Canais de aprovação nativa devem rotear `accountId` e `approvalKind` por esses helpers. `accountId` mantém a política de aprovação multiconta no escopo da conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de exec vs plugin disponível para o canal sem ramificações hardcoded no core. +- O core agora também é responsável pelos avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo “a aprovação foi para DMs / outro canal” a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador. +- Preserve o tipo de ID de aprovação entregue de ponta a ponta. Clients nativos não devem adivinhar nem reescrever o roteamento de aprovação de exec vs plugin a partir de estado local do canal. +- Diferentes tipos de aprovação podem intencionalmente expor diferentes superfícies nativas. + Exemplos empacotados atuais: + - O Slack mantém o roteamento de aprovação nativa disponível para IDs de exec e de plugin. + - O Matrix mantém o mesmo roteamento nativo de DM/canal e a mesma UX de reação para aprovações de exec e de plugin, ao mesmo tempo em que ainda permite que a autenticação varie por tipo de aprovação. +- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas código novo deve preferir o construtor de capacidade e expor `approvalCapability` no plugin. -Para pontos de entrada críticos do canal, prefira os subcaminhos de runtime mais específicos quando você só -precisar de uma parte dessa família: +Para pontos de entrada críticos do canal, prefira os subcaminhos de runtime mais específicos quando você precisar de apenas uma parte dessa família: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -125,43 +100,34 @@ Da mesma forma, prefira `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` e -`openclaw/plugin-sdk/reply-chunking` quando você não precisar da superfície -guarda-chuva mais ampla. +`openclaw/plugin-sdk/reply-chunking` quando você não precisar da +superfície guarda-chuva mais ampla. Especificamente para setup: - `openclaw/plugin-sdk/setup-runtime` cobre os helpers de setup seguros para runtime: adaptadores de patch de setup seguros para importação (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), saída de nota de consulta, - `promptResolvedAllowFrom`, `splitSetupEntries` e os builders + `createSetupInputPresenceValidator`), saída de nota de lookup, + `promptResolvedAllowFrom`, `splitSetupEntries` e os construtores delegados de proxy de setup -- `openclaw/plugin-sdk/setup-adapter-runtime` é a superfície estreita de adaptador com reconhecimento de env - para `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` cobre os builders de setup com instalação opcional - além de algumas primitivas seguras para setup: +- `openclaw/plugin-sdk/setup-adapter-runtime` é a superfície estreita de adaptador com reconhecimento de ambiente para `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` cobre os construtores de setup de instalação opcional mais alguns primitivos seguros de setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Se o seu canal oferecer suporte a setup ou auth orientados por env e os fluxos genéricos de inicialização/configuração -precisarem conhecer esses nomes de env antes de o runtime ser carregado, declare-os no -manifesto do Plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas -para cópia voltada ao operador. +Se o seu canal oferecer suporte a setup ou autenticação orientados por ambiente e fluxos genéricos de inicialização/configuração precisarem conhecer esses nomes de variáveis de ambiente antes de o runtime ser carregado, declare-os no manifesto do plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas para cópia voltada ao operador. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` e `splitSetupEntries` -- use a superfície mais ampla `openclaw/plugin-sdk/setup` apenas quando você também precisar dos - helpers compartilhados mais pesados de setup/configuração, como +- use a superfície mais ampla `openclaw/plugin-sdk/setup` apenas quando você também precisar dos helpers compartilhados mais pesados de setup/configuração, como `moveSingleAccountChannelSectionToDefaultAccount(...)` -Se o seu canal só quiser anunciar "instale este Plugin primeiro" em superfícies -de setup, prefira `createOptionalChannelSetupSurface(...)`. O -adaptador/assistente gerado falha em modo fechado em gravações de configuração e finalização, e reutiliza -a mesma mensagem de instalação obrigatória em validação, finalização e cópia -de link da documentação. +Se o seu canal quiser apenas anunciar “instale este plugin primeiro” em +superfícies de setup, prefira `createOptionalChannelSetupSurface(...)`. O +adaptador/assistente gerado falha de forma fechada em gravações de configuração e finalização, e reutiliza a mesma mensagem de instalação obrigatória em validação, finalização e cópia de link de documentação. -Para outros caminhos críticos do canal, prefira os helpers específicos em vez de superfícies -legadas mais amplas: +Para outros caminhos críticos do canal, prefira os helpers estreitos em vez das superfícies legadas mais amplas: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, @@ -170,40 +136,44 @@ legadas mais amplas: fallback de conta padrão - `openclaw/plugin-sdk/inbound-envelope` e `openclaw/plugin-sdk/inbound-reply-dispatch` para rota/envelope de entrada e - integração de registro e despacho -- `openclaw/plugin-sdk/messaging-targets` para parsing/correspondência de alvos + ligação entre registro e despacho +- `openclaw/plugin-sdk/messaging-targets` para análise/correspondência de destinos - `openclaw/plugin-sdk/outbound-media` e - `openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia mais delegados - de identidade/envio de saída -- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vinculação de thread - e registro de adaptadores -- `openclaw/plugin-sdk/agent-media-payload` apenas quando um layout de campo legado de payload de agente/mídia - ainda for necessário -- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos personalizados do Telegram, validação de duplicatas/conflitos e um contrato de configuração de comando estável em fallback + `openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia mais + delegados de identidade/envio de saída +- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vínculo de thread + e registro de adaptador +- `openclaw/plugin-sdk/agent-media-payload` apenas quando um layout legado + de campo de payload de agente/mídia ainda for necessário +- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos + personalizados do Telegram, validação de duplicatas/conflitos e um contrato + de configuração de comando estável em fallback -Canais somente com auth normalmente podem ficar no caminho padrão: o core trata as aprovações e o Plugin apenas expõe capacidades de saída/auth. Canais com aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação. +Canais somente de autenticação normalmente podem parar no caminho padrão: o core trata as aprovações e o plugin apenas expõe capacidades de saída/autenticação. Canais de aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação. ## Política de menção de entrada -Mantenha o tratamento de menções de entrada dividido em duas camadas: +Mantenha o tratamento de menção de entrada dividido em duas camadas: -- coleta de evidências controlada pelo Plugin +- coleta de evidências pertencente ao plugin - avaliação de política compartilhada -Use `openclaw/plugin-sdk/channel-inbound` para a camada compartilhada. +Use `openclaw/plugin-sdk/channel-mention-gating` para decisões de política de menção. +Use `openclaw/plugin-sdk/channel-inbound` apenas quando precisar da surface mais ampla de +helpers de entrada. -Bom encaixe para lógica local do Plugin: +Bom encaixe para lógica local do plugin: - detecção de resposta ao bot - detecção de citação do bot - verificações de participação em thread - exclusões de mensagens de serviço/sistema -- caches nativos da plataforma necessários para comprovar a participação do bot +- caches nativos da plataforma necessários para comprovar participação do bot Bom encaixe para o helper compartilhado: - `requireMention` -- resultado explícito de menção +- resultado de menção explícita - lista de permissão de menção implícita - bypass de comando - decisão final de ignorar @@ -260,18 +230,23 @@ Plugins de canal empacotados que já dependem de injeção em runtime: - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Os helpers mais antigos `resolveMentionGating*` permanecem em -`openclaw/plugin-sdk/channel-inbound` apenas como exports de compatibilidade. Código novo -deve usar `resolveInboundMentionDecision({ facts, policy })`. +Se você precisar apenas de `implicitMentionKindWhen` e +`resolveInboundMentionDecision`, importe de +`openclaw/plugin-sdk/channel-mention-gating` para evitar carregar helpers de +runtime de entrada não relacionados. + +Os helpers mais antigos `resolveMentionGating*` continuam em +`openclaw/plugin-sdk/channel-inbound` apenas como exportações de compatibilidade. Código +novo deve usar `resolveInboundMentionDecision({ facts, policy })`. ## Passo a passo - Crie os arquivos padrão do Plugin. O campo `channel` em `package.json` é - o que torna este um Plugin de canal. Para a superfície completa de metadados do pacote, - veja [Setup e Configuração do Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel): + Crie os arquivos padrão do plugin. O campo `channel` em `package.json` é + o que faz deste um plugin de canal. Para a surface completa de metadados do pacote, + veja [Setup e Configuração de Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -285,7 +260,7 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Conecte o OpenClaw ao Acme Chat." + "blurb": "Connect OpenClaw to Acme Chat." } } } @@ -297,7 +272,7 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Plugin de canal do Acme Chat", + "description": "Acme Chat channel plugin", "configSchema": { "type": "object", "additionalProperties": false, @@ -320,8 +295,8 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. - - A interface `ChannelPlugin` tem muitas superfícies de adaptador opcionais. Comece com + + A interface `ChannelPlugin` tem muitas surfaces de adaptador opcionais. Comece com o mínimo — `id` e `setup` — e adicione adaptadores conforme necessário. Crie `src/channel.ts`: @@ -419,14 +394,14 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. Em vez de implementar manualmente interfaces de adaptador de baixo nível, você passa - opções declarativas e o builder as compõe: + opções declarativas e o builder faz a composição: | Opção | O que ela conecta | | --- | --- | - | `security.dm` | Resolvedor de segurança de DM com escopo a partir dos campos de configuração | - | `pairing.text` | Fluxo de emparelhamento por DM baseado em texto com troca de código | - | `threading` | Resolvedor de modo reply-to (fixo, com escopo de conta ou personalizado) | - | `outbound.attachedResults` | Funções de envio que retornam metadados do resultado (ids de mensagem) | + | `security.dm` | Resolver de segurança de DM com escopo a partir de campos de configuração | + | `pairing.text` | Fluxo de emparelhamento de DM baseado em texto com troca de código | + | `threading` | Resolver de modo de resposta (fixo, com escopo por conta ou personalizado) | + | `outbound.attachedResults` | Funções de envio que retornam metadados de resultado (IDs de mensagem) | Você também pode passar objetos de adaptador brutos em vez das opções declarativas se precisar de controle total. @@ -470,13 +445,13 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Coloque descritores de CLI controlados pelo canal em `registerCliMetadata(...)` para que o OpenClaw - possa mostrá-los na ajuda raiz sem ativar o runtime completo do canal, - enquanto carregamentos completos normais ainda capturam os mesmos descritores para o registro - real de comandos. Mantenha `registerFull(...)` para trabalho somente de runtime. + Coloque descritores de CLI pertencentes ao canal em `registerCliMetadata(...)` para que o OpenClaw + possa exibi-los na ajuda raiz sem ativar o runtime completo do canal, + enquanto carregamentos completos normais ainda usem os mesmos descritores para registro real de comandos. + Mantenha `registerFull(...)` para trabalho exclusivo de runtime. Se `registerFull(...)` registrar métodos RPC do Gateway, use um - prefixo específico do Plugin. Namespaces administrativos do core (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre + prefixo específico do plugin. Namespaces administrativos do core (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) continuam reservados e sempre resolvem para `operator.admin`. `defineChannelPluginEntry` trata automaticamente a divisão de modo de registro. Veja [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints#definechannelpluginentry) para todas as @@ -495,10 +470,10 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. ``` O OpenClaw carrega isso em vez da entrada completa quando o canal está desabilitado - ou não configurado. Isso evita puxar código pesado de runtime durante fluxos de setup. + ou não configurado. Isso evita puxar código pesado de runtime durante os fluxos de setup. Veja [Setup e Configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes. - Canais empacotados do workspace que dividem exports seguras para setup em módulos + Canais de workspace empacotados que dividem exportações seguras para setup em módulos auxiliares podem usar `defineBundledChannelSetupEntry(...)` de `openclaw/plugin-sdk/channel-entry-contract` quando também precisarem de um setter explícito de runtime em tempo de setup. @@ -506,9 +481,9 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. - Seu Plugin precisa receber mensagens da plataforma e encaminhá-las para o - OpenClaw. O padrão típico é um Webhook que verifica a solicitação e - a despacha por meio do handler de entrada do seu canal: + Seu plugin precisa receber mensagens da plataforma e encaminhá-las para o + OpenClaw. O padrão típico é um webhook que verifica a requisição e faz o + dispatch por meio do handler de entrada do seu canal: ```typescript registerFull(api) { @@ -532,16 +507,16 @@ deve usar `resolveInboundMentionDecision({ facts, policy })`. ``` - O tratamento de mensagens de entrada é específico de cada canal. Cada Plugin de canal é responsável - pelo seu próprio pipeline de entrada. Veja Plugins de canal empacotados - (por exemplo, o pacote de Plugin do Microsoft Teams ou do Google Chat) para padrões reais. + O tratamento de mensagens de entrada é específico do canal. Cada plugin de canal é responsável + pelo seu próprio pipeline de entrada. Veja plugins de canal empacotados + (por exemplo o pacote do plugin Microsoft Teams ou Google Chat) para padrões reais. -Escreva testes colocados lado a lado em `src/channel.test.ts`: +Escreva testes lado a lado em `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -579,7 +554,7 @@ Escreva testes colocados lado a lado em `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Para helpers de teste compartilhados, veja [Testes](/pt-BR/plugins/sdk-testing). + Para helpers de teste compartilhados, veja [Testing](/pt-BR/plugins/sdk-testing). @@ -592,12 +567,12 @@ Escreva testes colocados lado a lado em `src/channel.test.ts`: ├── openclaw.plugin.json # Manifesto com schema de configuração ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Exports públicos (opcional) -├── runtime-api.ts # Exports internos de runtime (opcional) +├── api.ts # Exportações públicas (opcional) +├── runtime-api.ts # Exportações internas de runtime (opcional) └── src/ ├── channel.ts # ChannelPlugin via createChatChannelPlugin ├── channel.test.ts # Testes - ├── client.ts # Cliente de API da plataforma + ├── client.ts # Client da API da plataforma └── runtime.ts # Armazenamento de runtime (se necessário) ``` @@ -605,12 +580,12 @@ Escreva testes colocados lado a lado em `src/channel.test.ts`: - Modos de resposta fixos, com escopo de conta ou personalizados + Modos de resposta fixos, com escopo por conta ou personalizados describeMessageTool e descoberta de ações - + inferTargetChatType, looksLikeId, resolveTarget @@ -619,15 +594,15 @@ Escreva testes colocados lado a lado em `src/channel.test.ts`: -Algumas superfícies auxiliares de Plugins empacotados ainda existem para manutenção de Plugins empacotados e -compatibilidade. Elas não são o padrão recomendado para novos Plugins de canal; -prefira os subcaminhos genéricos de canal/setup/resposta/runtime da superfície comum do SDK, -a menos que você esteja mantendo diretamente essa família de Plugins empacotados. +Algumas surfaces de helpers empacotados ainda existem para manutenção e +compatibilidade de plugins empacotados. Elas não são o padrão recomendado para novos Plugins de canal; +prefira os subcaminhos genéricos de canal/setup/resposta/runtime da surface comum do SDK, +a menos que você esteja mantendo diretamente essa família de plugins empacotados. ## Próximos passos -- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — se o seu Plugin também fornece modelos -- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de imports por subcaminho -- [Testes do SDK](/pt-BR/plugins/sdk-testing) — utilitários de teste e testes de contrato +- [Provider Plugins](/pt-BR/plugins/sdk-provider-plugins) — se o seu plugin também fornecer modelos +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de importação de subcaminhos +- [SDK Testing](/pt-BR/plugins/sdk-testing) — utilitários de teste e testes de contrato - [Manifesto do Plugin](/pt-BR/plugins/manifest) — schema completo do manifesto diff --git a/docs/pt-BR/plugins/sdk-overview.md b/docs/pt-BR/plugins/sdk-overview.md index 4bd746d9b..d379154a0 100644 --- a/docs/pt-BR/plugins/sdk-overview.md +++ b/docs/pt-BR/plugins/sdk-overview.md @@ -1,21 +1,21 @@ --- read_when: - Você precisa saber de qual subcaminho do SDK importar - - Você quer uma referência de todos os métodos de registro em `OpenClawPluginApi` + - Você quer uma referência para todos os métodos de registro em OpenClawPluginApi - Você está procurando uma exportação específica do SDK sidebarTitle: SDK Overview summary: Mapa de importação, referência da API de registro e arquitetura do SDK -title: Visão geral do Plugin SDK +title: Visão geral do SDK de Plugin x-i18n: - generated_at: "2026-04-17T05:36:06Z" + generated_at: "2026-04-18T05:25:18Z" model: gpt-5.4 provider: openai - source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a + source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331 source_path: plugins/sdk-overview.md workflow: 15 --- -# Visão geral do Plugin SDK +# Visão geral do SDK de Plugin O SDK de plugin é o contrato tipado entre plugins e o núcleo. Esta página é a referência para **o que importar** e **o que você pode registrar**. @@ -37,269 +37,283 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Cada subcaminho é um módulo pequeno e autocontido. Isso mantém a inicialização rápida e -evita problemas de dependência circular. Para auxiliares específicos de -entrada/construção de canal, prefira `openclaw/plugin-sdk/channel-core`; mantenha `openclaw/plugin-sdk/core` para -a superfície guarda-chuva mais ampla e auxiliares compartilhados, como +evita problemas de dependência circular. Para auxiliares de entrada/build específicos de canal, +prefira `openclaw/plugin-sdk/channel-core`; mantenha `openclaw/plugin-sdk/core` para +a superfície guarda-chuva mais ampla e helpers compartilhados, como `buildChannelConfigSchema`. -Não adicione nem dependa de seams de conveniência com nome de provedor, como +Não adicione nem dependa de interfaces de conveniência nomeadas por provedor, como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ou -seams auxiliares com marca de canal. Plugins empacotados devem compor -subcaminhos genéricos do SDK dentro de seus próprios barrels `api.ts` ou `runtime-api.ts`, e o núcleo -deve usar esses barrels locais do plugin ou adicionar um contrato genérico e restrito do SDK +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, nem de +interfaces auxiliares com marca de canal. Plugins empacotados devem compor subcaminhos genéricos +do SDK dentro de seus próprios barrels `api.ts` ou `runtime-api.ts`, e o núcleo +deve usar esses barrels locais do plugin ou adicionar um contrato genérico e estreito do SDK quando a necessidade for realmente entre canais. -O mapa de exportação gerado ainda contém um pequeno conjunto de -seams auxiliares de plugins empacotados, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +O mapa de exportação gerado ainda contém um pequeno conjunto de interfaces auxiliares de plugin empacotado, +como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Esses subcaminhos existem apenas para manutenção e compatibilidade de plugins empacotados; eles são -intencionalmente omitidos da tabela comum abaixo e não são o caminho de -importação recomendado para novos plugins de terceiros. +omitidos intencionalmente da tabela comum abaixo e não são o caminho de importação +recomendado para novos plugins de terceiros. ## Referência de subcaminhos Os subcaminhos usados com mais frequência, agrupados por finalidade. A lista completa gerada de -mais de 200 subcaminhos está em `scripts/lib/plugin-sdk-entrypoints.json`. +mais de 200 subcaminhos fica em `scripts/lib/plugin-sdk-entrypoints.json`. -Subcaminhos auxiliares reservados para plugins empacotados ainda aparecem nessa lista gerada. -Trate-os como superfícies de detalhe de implementação/compatibilidade, a menos que uma página da documentação +Subcaminhos reservados de auxílio para plugins empacotados ainda aparecem nessa lista gerada. +Trate-os como detalhes de implementação/superfícies de compatibilidade, a menos que uma página da documentação promova explicitamente um deles como público. -### Entrada do plugin +### Entrada de plugin -| Subcaminho | Principais exportações | -| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Subcaminho | Exportações principais | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | Subcaminho | Principais exportações | + | Subcaminho | Exportações principais | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Exportação do esquema Zod raiz de `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Exportação do schema Zod raiz de `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, além de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Auxiliares compartilhados do assistente de configuração, prompts de allowlist, construtores de status de configuração | + | `plugin-sdk/setup` | Helpers compartilhados de assistente de configuração, prompts de allowlist, construtores de status de configuração | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Auxiliares de gate de ação/configuração com múltiplas contas, auxiliares de fallback de conta padrão | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, auxiliares de normalização de ID de conta | - | `plugin-sdk/account-resolution` | Auxiliares de busca de conta + fallback padrão | - | `plugin-sdk/account-helpers` | Auxiliares restritos para lista de contas/ação de conta | + | `plugin-sdk/account-core` | Helpers de configuração/gate de ação para múltiplas contas, helpers de fallback para conta padrão | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalização de ID de conta | + | `plugin-sdk/account-resolution` | Helpers de busca de conta + fallback padrão | + | `plugin-sdk/account-helpers` | Helpers estreitos de lista de contas/ações de conta | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Tipos de esquema de configuração de canal | - | `plugin-sdk/telegram-command-config` | Auxiliares de normalização/validação de comandos personalizados do Telegram com fallback de contrato empacotado | + | `plugin-sdk/channel-config-schema` | Tipos de schema de configuração de canal | + | `plugin-sdk/telegram-command-config` | Helpers de normalização/validação de comandos personalizados do Telegram com fallback de contrato empacotado | + | `plugin-sdk/command-gating` | Helpers estreitos de gate de autorização de comandos | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Auxiliares compartilhados de rota de entrada + construtor de envelope | - | `plugin-sdk/inbound-reply-dispatch` | Auxiliares compartilhados de registro e despacho de entrada | - | `plugin-sdk/messaging-targets` | Auxiliares de análise/correspondência de alvos | - | `plugin-sdk/outbound-media` | Auxiliares compartilhados de carregamento de mídia de saída | - | `plugin-sdk/outbound-runtime` | Auxiliares de identidade de saída/delegação de envio | - | `plugin-sdk/thread-bindings-runtime` | Ciclo de vida de vínculo de thread e auxiliares de adaptador | - | `plugin-sdk/agent-media-payload` | Construtor legado de payload de mídia do agente | - | `plugin-sdk/conversation-runtime` | Auxiliares de vínculo de conversa/thread, pareamento e vínculo configurado | - | `plugin-sdk/runtime-config-snapshot` | Auxiliar de snapshot de configuração em runtime | - | `plugin-sdk/runtime-group-policy` | Auxiliares de resolução de política de grupo em runtime | - | `plugin-sdk/channel-status` | Auxiliares compartilhados de snapshot/resumo de status do canal | - | `plugin-sdk/channel-config-primitives` | Primitivas restritas de esquema de configuração de canal | - | `plugin-sdk/channel-config-writes` | Auxiliares de autorização de gravação de configuração de canal | - | `plugin-sdk/channel-plugin-common` | Exportações de prelúdio compartilhadas de plugin de canal | - | `plugin-sdk/allowlist-config-edit` | Auxiliares de leitura/edição de configuração de allowlist | - | `plugin-sdk/group-access` | Auxiliares compartilhados de decisão de acesso a grupo | - | `plugin-sdk/direct-dm` | Auxiliares compartilhados de autenticação/proteção de DM direta | - | `plugin-sdk/interactive-runtime` | Auxiliares de normalização/redução de payload de resposta interativa | - | `plugin-sdk/channel-inbound` | Debounce de entrada, correspondência de menção, auxiliares de política de menção e auxiliares de envelope | + | `plugin-sdk/inbound-envelope` | Helpers compartilhados de rota de entrada + construtor de envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helpers compartilhados de registrar e despachar entrada | + | `plugin-sdk/messaging-targets` | Helpers de parsing/correspondência de destino | + | `plugin-sdk/outbound-media` | Helpers compartilhados de carregamento de mídia de saída | + | `plugin-sdk/outbound-runtime` | Helpers de identidade de saída/delegação de envio | + | `plugin-sdk/poll-runtime` | Helpers estreitos de normalização de enquete | + | `plugin-sdk/thread-bindings-runtime` | Helpers de ciclo de vida e adaptador de vinculações de thread | + | `plugin-sdk/agent-media-payload` | Construtor legado de payload de mídia de agente | + | `plugin-sdk/conversation-runtime` | Helpers de vinculação de conversa/thread, pareamento e vinculação configurada | + | `plugin-sdk/runtime-config-snapshot` | Helper de snapshot de configuração de runtime | + | `plugin-sdk/runtime-group-policy` | Helpers de resolução de política de grupo em runtime | + | `plugin-sdk/channel-status` | Helpers compartilhados de snapshot/resumo de status de canal | + | `plugin-sdk/channel-config-primitives` | Primitivos estreitos de schema de configuração de canal | + | `plugin-sdk/channel-config-writes` | Helpers de autorização de gravação de configuração de canal | + | `plugin-sdk/channel-plugin-common` | Exportações compartilhadas de prelúdio de plugin de canal | + | `plugin-sdk/allowlist-config-edit` | Helpers de leitura/edição de configuração de allowlist | + | `plugin-sdk/group-access` | Helpers compartilhados de decisão de acesso a grupo | + | `plugin-sdk/direct-dm` | Helpers compartilhados de autenticação/proteção para DM direta | + | `plugin-sdk/interactive-runtime` | Helpers de normalização/redução de payload de resposta interativa | + | `plugin-sdk/channel-inbound` | Barrel de compatibilidade para debounce de entrada, correspondência de menção, helpers de política de menção e helpers de envelope | + | `plugin-sdk/channel-mention-gating` | Helpers estreitos de política de menção sem a superfície mais ampla de runtime de entrada | + | `plugin-sdk/channel-location` | Helpers de contexto e formatação de localização de canal | + | `plugin-sdk/channel-logging` | Helpers de logging de canal para descartes de entrada e falhas de digitação/ack | | `plugin-sdk/channel-send-result` | Tipos de resultado de resposta | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Auxiliares de análise/correspondência de alvos | + | `plugin-sdk/channel-targets` | Helpers de parsing/correspondência de destino | | `plugin-sdk/channel-contract` | Tipos de contrato de canal | - | `plugin-sdk/channel-feedback` | Ligação de feedback/reação | - | `plugin-sdk/channel-secret-runtime` | Auxiliares restritos de contrato de segredo, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipos de alvo de segredo | + | `plugin-sdk/channel-feedback` | Wiring de feedback/reação | + | `plugin-sdk/channel-secret-runtime` | Helpers estreitos de contrato de segredo, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipos de alvo de segredo | - | Subcaminho | Principais exportações | + | Subcaminho | Exportações principais | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Auxiliares curados de configuração de provedor local/self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Auxiliares focados de configuração de provedor self-hosted compatível com OpenAI | - | `plugin-sdk/cli-backend` | Padrões de backend da CLI + constantes de watchdog | - | `plugin-sdk/provider-auth-runtime` | Auxiliares de runtime para resolução de chave de API para plugins de provedor | - | `plugin-sdk/provider-auth-api-key` | Auxiliares de onboarding/gravação de perfil de chave de API, como `upsertApiKeyProfile` | + | `plugin-sdk/provider-setup` | Helpers curados de configuração de provedor local/self-hosted | + | `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provedor self-hosted compatível com OpenAI | + | `plugin-sdk/cli-backend` | Padrões de backend de CLI + constantes de watchdog | + | `plugin-sdk/provider-auth-runtime` | Helpers de runtime para resolução de chave de API para plugins de provedor | + | `plugin-sdk/provider-auth-api-key` | Helpers de onboarding/gravação de perfil de chave de API, como `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Construtor padrão de resultado de autenticação OAuth | - | `plugin-sdk/provider-auth-login` | Auxiliares compartilhados de login interativo para plugins de provedor | - | `plugin-sdk/provider-env-vars` | Auxiliares de busca de variáveis de ambiente de autenticação do provedor | + | `plugin-sdk/provider-auth-login` | Helpers compartilhados de login interativo para plugins de provedor | + | `plugin-sdk/provider-env-vars` | Helpers de busca de variáveis de ambiente de autenticação de provedor | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, construtores compartilhados de política de replay, auxiliares de endpoint do provedor e auxiliares de normalização de ID de modelo, como `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, construtores compartilhados de política de replay, helpers de endpoint de provedor e helpers de normalização de ID de modelo, como `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Auxiliares genéricos de HTTP/capacidade de endpoint do provedor | - | `plugin-sdk/provider-web-fetch-contract` | Auxiliares restritos de contrato de configuração/seleção de web-fetch, como `enablePluginInConfig` e `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Auxiliares de registro/cache de provedor web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Auxiliares restritos de configuração/credencial de web-search para provedores que não precisam de ligação de ativação de plugin | - | `plugin-sdk/provider-web-search-contract` | Auxiliares restritos de contrato de configuração/credencial de web-search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo | - | `plugin-sdk/provider-web-search` | Auxiliares de runtime/registro/cache de provedor web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnóstico de esquema Gemini e auxiliares de compatibilidade xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Helpers genéricos de HTTP/capacidade de endpoint de provedor | + | `plugin-sdk/provider-web-fetch-contract` | Helpers estreitos de contrato para configuração/seleção de web-fetch, como `enablePluginInConfig` e `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Helpers de registro/cache de provedor web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helpers estreitos de configuração/credencial de web-search para provedores que não precisam de wiring de habilitação de plugin | + | `plugin-sdk/provider-web-search-contract` | Helpers estreitos de contrato de configuração/credencial de web-search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo | + | `plugin-sdk/provider-web-search` | Helpers de registro/cache/runtime de provedor web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnósticos de schema Gemini e helpers de compatibilidade xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` e similares | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e auxiliares compartilhados de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Auxiliares de patch de configuração de onboarding | - | `plugin-sdk/global-singleton` | Auxiliares de singleton/mapa/cache local ao processo | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Helpers de patch de configuração de onboarding | + | `plugin-sdk/global-singleton` | Helpers de singleton/mapa/cache locais ao processo | - | Subcaminho | Principais exportações | + | Subcaminho | Exportações principais | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, auxiliares de registro de comandos, auxiliares de autorização do remetente | - | `plugin-sdk/command-status` | Construtores de mensagem de comando/ajuda, como `buildCommandsMessagePaginated` e `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Resolução de aprovador e auxiliares de autenticação de ação no mesmo chat | - | `plugin-sdk/approval-client-runtime` | Auxiliares de perfil/filtro de aprovação para execução nativa | - | `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidade/entrega de aprovação | - | `plugin-sdk/approval-gateway-runtime` | Auxiliar compartilhado de resolução de Gateway de aprovação | - | `plugin-sdk/approval-handler-adapter-runtime` | Auxiliares leves de carregamento de adaptador de aprovação nativa para entrypoints de canal de hot path | - | `plugin-sdk/approval-handler-runtime` | Auxiliares mais amplos de runtime do manipulador de aprovação; prefira os seams mais restritos de adaptador/Gateway quando forem suficientes | - | `plugin-sdk/approval-native-runtime` | Auxiliares nativos de alvo de aprovação + vínculo de conta | - | `plugin-sdk/approval-reply-runtime` | Auxiliares de payload de resposta de aprovação de execução/plugin | - | `plugin-sdk/command-auth-native` | Auxiliares nativos de autenticação de comando + alvo de sessão nativa | - | `plugin-sdk/command-detection` | Auxiliares compartilhados de detecção de comandos | - | `plugin-sdk/command-surface` | Auxiliares de normalização de corpo de comando e superfície de comando | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registro de comando, helpers de autorização de remetente | + | `plugin-sdk/command-status` | Construtores de mensagens de comando/ajuda, como `buildCommandsMessagePaginated` e `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helpers de resolução de aprovador e autenticação de ação no mesmo chat | + | `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprovação nativa de exec | + | `plugin-sdk/approval-delivery-runtime` | Adaptadores de entrega/capacidade de aprovação nativa | + | `plugin-sdk/approval-gateway-runtime` | Helper compartilhado de resolução de Gateway de aprovação | + | `plugin-sdk/approval-handler-adapter-runtime` | Helpers leves de carregamento de adaptador de aprovação nativa para entrypoints quentes de canal | + | `plugin-sdk/approval-handler-runtime` | Helpers mais amplos de runtime de manipulador de aprovação; prefira as interfaces mais estreitas de adapter/gateway quando forem suficientes | + | `plugin-sdk/approval-native-runtime` | Helpers de alvo de aprovação nativa + vinculação de conta | + | `plugin-sdk/approval-reply-runtime` | Helpers de payload de resposta para aprovação de exec/plugin | + | `plugin-sdk/command-auth-native` | Helpers de autenticação nativa de comando + helpers nativos de alvo de sessão | + | `plugin-sdk/command-detection` | Helpers compartilhados de detecção de comando | + | `plugin-sdk/command-surface` | Helpers de normalização do corpo de comando e da superfície de comando | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Auxiliares restritos de coleta de contrato de segredo para superfícies de segredo de canal/plugin | - | `plugin-sdk/secret-ref-runtime` | Auxiliares restritos de tipagem de `coerceSecretRef` e SecretRef para parsing de contrato/configuração de segredo | - | `plugin-sdk/security-runtime` | Auxiliares compartilhados de confiança, controle de DM, conteúdo externo e coleta de segredos | - | `plugin-sdk/ssrf-policy` | Auxiliares de allowlist de host e política de SSRF para rede privada | - | `plugin-sdk/ssrf-runtime` | Auxiliares de dispatcher fixado, fetch protegido contra SSRF e política de SSRF | - | `plugin-sdk/secret-input` | Auxiliares de parsing de entrada de segredo | - | `plugin-sdk/webhook-ingress` | Auxiliares de requisição/alvo de Webhook | - | `plugin-sdk/webhook-request-guards` | Auxiliares de tamanho do corpo/timeout da requisição | + | `plugin-sdk/channel-secret-runtime` | Helpers estreitos de coleta de contrato de segredo para superfícies de segredo de canal/plugin | + | `plugin-sdk/secret-ref-runtime` | Helpers estreitos de tipagem `coerceSecretRef` e SecretRef para parsing de contrato de segredo/configuração | + | `plugin-sdk/security-runtime` | Helpers compartilhados de confiança, gate de DM, conteúdo externo e coleta de segredo | + | `plugin-sdk/ssrf-policy` | Helpers de política SSRF para allowlist de host e rede privada | + | `plugin-sdk/ssrf-dispatcher` | Helpers estreitos de dispatcher fixado sem a ampla superfície de runtime de infraestrutura | + | `plugin-sdk/ssrf-runtime` | Helpers de dispatcher fixado, fetch protegido por SSRF e política SSRF | + | `plugin-sdk/secret-input` | Helpers de parsing de entrada de segredo | + | `plugin-sdk/webhook-ingress` | Helpers de requisição/alvo de Webhook | + | `plugin-sdk/webhook-request-guards` | Helpers de tamanho do corpo da requisição/timeout | - | Subcaminho | Principais exportações | + | Subcaminho | Exportações principais | | --- | --- | - | `plugin-sdk/runtime` | Auxiliares amplos de runtime/logging/backup/instalação de plugin | - | `plugin-sdk/runtime-env` | Auxiliares restritos de ambiente de runtime, logger, timeout, retry e backoff | - | `plugin-sdk/channel-runtime-context` | Auxiliares genéricos de registro e busca de contexto de runtime de canal | + | `plugin-sdk/runtime` | Helpers amplos de runtime/logging/backup/instalação de plugin | + | `plugin-sdk/runtime-env` | Helpers estreitos de env de runtime, logger, timeout, retry e backoff | + | `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro e consulta de contexto de runtime de canal | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Auxiliares compartilhados de comando/hook/http/interativo de plugin | - | `plugin-sdk/hook-runtime` | Auxiliares compartilhados de pipeline de Webhook/hook interno | - | `plugin-sdk/lazy-runtime` | Auxiliares de importação/vínculo lazy de runtime, como `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Auxiliares de execução de processo | - | `plugin-sdk/cli-runtime` | Auxiliares de formatação, espera e versão da CLI | - | `plugin-sdk/gateway-runtime` | Auxiliares de cliente Gateway e patch de status de canal | - | `plugin-sdk/config-runtime` | Auxiliares de carregamento/gravação de configuração | + | `plugin-sdk/plugin-runtime` | Helpers compartilhados de comando/hook/http/interativo de plugin | + | `plugin-sdk/hook-runtime` | Helpers compartilhados de pipeline de Webhook/hook interno | + | `plugin-sdk/lazy-runtime` | Helpers de importação/vinculação lazy de runtime, como `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helpers de execução de processo | + | `plugin-sdk/cli-runtime` | Helpers de formatação, espera e versão de CLI | + | `plugin-sdk/gateway-runtime` | Helpers de cliente Gateway e patch de status de canal | + | `plugin-sdk/config-runtime` | Helpers de carregamento/gravação de configuração | | `plugin-sdk/telegram-command-config` | Normalização de nome/descrição de comando do Telegram e verificações de duplicidade/conflito, mesmo quando a superfície de contrato empacotada do Telegram não está disponível | - | `plugin-sdk/approval-runtime` | Auxiliares de aprovação de execução/plugin, construtores de capacidade de aprovação, auxiliares de autenticação/perfil, auxiliares nativos de roteamento/runtime | - | `plugin-sdk/reply-runtime` | Auxiliares compartilhados de runtime de entrada/resposta, fragmentação, despacho, Heartbeat, planejador de resposta | - | `plugin-sdk/reply-dispatch-runtime` | Auxiliares restritos de despacho/finalização de resposta | - | `plugin-sdk/reply-history` | Auxiliares compartilhados de histórico de respostas de janela curta, como `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/text-autolink-runtime` | Detecção de autolink de referência de arquivo sem o barrel amplo `text-runtime` | + | `plugin-sdk/approval-runtime` | Helpers de aprovação de exec/plugin, construtores de capacidade de aprovação, helpers de autenticação/perfil, helpers nativos de roteamento/runtime | + | `plugin-sdk/reply-runtime` | Helpers compartilhados de runtime de entrada/resposta, chunking, dispatch, heartbeat, planejador de resposta | + | `plugin-sdk/reply-dispatch-runtime` | Helpers estreitos de dispatch/finalização de resposta | + | `plugin-sdk/reply-history` | Helpers compartilhados de histórico de resposta de janela curta, como `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Auxiliares restritos de fragmentação de texto/markdown | - | `plugin-sdk/session-store-runtime` | Auxiliares de caminho da store de sessão + updated-at | - | `plugin-sdk/state-paths` | Auxiliares de caminho de diretório de estado/OAuth | - | `plugin-sdk/routing` | Auxiliares de roteamento/chave de sessão/vínculo de conta, como `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Auxiliares compartilhados de resumo de status de canal/conta, padrões de estado de runtime e auxiliares de metadados de problema | - | `plugin-sdk/target-resolver-runtime` | Auxiliares compartilhados de resolvedor de alvo | - | `plugin-sdk/string-normalization-runtime` | Auxiliares de normalização de slug/string | - | `plugin-sdk/request-url` | Extrair URLs em string de entradas do tipo fetch/request | - | `plugin-sdk/run-command` | Executor de comandos com tempo controlado e resultados normalizados de stdout/stderr | + | `plugin-sdk/reply-chunking` | Helpers estreitos de chunking de texto/markdown | + | `plugin-sdk/session-store-runtime` | Helpers de caminho do armazenamento de sessão + updated-at | + | `plugin-sdk/state-paths` | Helpers de caminho de diretório de estado/OAuth | + | `plugin-sdk/routing` | Helpers de rota/chave de sessão/vinculação de conta, como `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helpers compartilhados de resumo de status de canal/conta, padrões de estado de runtime e helpers de metadados de problema | + | `plugin-sdk/target-resolver-runtime` | Helpers compartilhados de resolvedor de alvo | + | `plugin-sdk/string-normalization-runtime` | Helpers de normalização de slug/string | + | `plugin-sdk/request-url` | Extrair URLs em string de entradas semelhantes a fetch/request | + | `plugin-sdk/run-command` | Executor de comando temporizado com resultados normalizados de stdout/stderr | | `plugin-sdk/param-readers` | Leitores comuns de parâmetros de ferramenta/CLI | | `plugin-sdk/tool-payload` | Extrair payloads normalizados de objetos de resultado de ferramenta | - | `plugin-sdk/tool-send` | Extrair campos canônicos de alvo de envio de argumentos de ferramenta | - | `plugin-sdk/temp-path` | Auxiliares compartilhados de caminho temporário para download | - | `plugin-sdk/logging-core` | Auxiliares de logger de subsistema e redação | - | `plugin-sdk/markdown-table-runtime` | Auxiliares de modo de tabela em Markdown | - | `plugin-sdk/json-store` | Pequenos auxiliares de leitura/gravação de estado JSON | - | `plugin-sdk/file-lock` | Auxiliares de file lock reentrante | - | `plugin-sdk/persistent-dedupe` | Auxiliares de cache de deduplicação com persistência em disco | - | `plugin-sdk/acp-runtime` | Auxiliares de runtime/sessão do ACP e despacho de resposta | - | `plugin-sdk/agent-config-primitives` | Primitivas restritas de esquema de configuração de runtime de agente | + | `plugin-sdk/tool-send` | Extrair campos canônicos de destino de envio de argumentos de ferramenta | + | `plugin-sdk/temp-path` | Helpers compartilhados de caminho temporário de download | + | `plugin-sdk/logging-core` | Helpers de logger de subsistema e redação | + | `plugin-sdk/markdown-table-runtime` | Helpers de modo de tabela Markdown | + | `plugin-sdk/json-store` | Pequenos helpers de leitura/gravação de estado JSON | + | `plugin-sdk/file-lock` | Helpers de file-lock reentrante | + | `plugin-sdk/persistent-dedupe` | Helpers de cache de deduplicação em disco | + | `plugin-sdk/acp-runtime` | Helpers de runtime/sessão ACP e dispatch de resposta | + | `plugin-sdk/acp-binding-resolve-runtime` | Resolução somente leitura de vinculação ACP sem imports de inicialização de ciclo de vida | + | `plugin-sdk/agent-config-primitives` | Primitivos estreitos de schema de configuração de runtime de agente | | `plugin-sdk/boolean-param` | Leitor flexível de parâmetro booleano | - | `plugin-sdk/dangerous-name-runtime` | Auxiliares de resolução de correspondência de nomes perigosos | - | `plugin-sdk/device-bootstrap` | Auxiliares de bootstrap de dispositivo e token de pareamento | - | `plugin-sdk/extension-shared` | Primitivas auxiliares compartilhadas de canal passivo, status e proxy ambiente | - | `plugin-sdk/models-provider-runtime` | Auxiliares de resposta de provedor/comando `/models` | - | `plugin-sdk/skill-commands-runtime` | Auxiliares de listagem de comandos de Skills | - | `plugin-sdk/native-command-registry` | Auxiliares de registro/construção/serialização de comandos nativos | - | `plugin-sdk/agent-harness` | Superfície experimental de plugin confiável para harnesses de agente de baixo nível: tipos de harness, auxiliares de condução/aborto de execução ativa, auxiliares de ponte de ferramenta do OpenClaw e utilitários de resultado de tentativa | - | `plugin-sdk/provider-zai-endpoint` | Auxiliares de detecção de endpoint do Z.A.I | - | `plugin-sdk/infra-runtime` | Auxiliares de evento do sistema/Heartbeat | - | `plugin-sdk/collection-runtime` | Pequenos auxiliares de cache limitado | - | `plugin-sdk/diagnostic-runtime` | Auxiliares de flag e evento de diagnóstico | - | `plugin-sdk/error-runtime` | Grafo de erros, formatação, auxiliares compartilhados de classificação de erros, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Auxiliares de fetch encapsulado, proxy e busca fixada | - | `plugin-sdk/host-runtime` | Auxiliares de normalização de hostname e host SCP | - | `plugin-sdk/retry-runtime` | Auxiliares de configuração de retry e executor de retry | - | `plugin-sdk/agent-runtime` | Auxiliares de diretório/identidade/workspace de agente | - | `plugin-sdk/directory-runtime` | Consulta/deduplicação de diretório com base em configuração | + | `plugin-sdk/dangerous-name-runtime` | Helpers de resolução de correspondência de nome perigoso | + | `plugin-sdk/device-bootstrap` | Helpers de bootstrap de dispositivo e token de pareamento | + | `plugin-sdk/extension-shared` | Primitivos auxiliares compartilhados para canal passivo, status e proxy ambiente | + | `plugin-sdk/models-provider-runtime` | Helpers de resposta de comando `/models`/provedor | + | `plugin-sdk/skill-commands-runtime` | Helpers de listagem de comandos de Skills | + | `plugin-sdk/native-command-registry` | Helpers nativos de registro/build/serialização de comando | + | `plugin-sdk/agent-harness` | Superfície experimental de plugin confiável para harnesses de agente de baixo nível: tipos de harness, helpers de condução/aborto de execução ativa, helpers de ponte de ferramenta OpenClaw e utilitários de resultado de tentativa | + | `plugin-sdk/provider-zai-endpoint` | Helpers de detecção de endpoint Z.A.I | + | `plugin-sdk/infra-runtime` | Helpers de evento do sistema/Heartbeat | + | `plugin-sdk/collection-runtime` | Pequenos helpers de cache limitado | + | `plugin-sdk/diagnostic-runtime` | Helpers de flag e evento de diagnóstico | + | `plugin-sdk/error-runtime` | Helpers de grafo de erro, formatação, classificação compartilhada de erro, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Helpers de fetch empacotado, proxy e lookup fixado | + | `plugin-sdk/runtime-fetch` | Fetch de runtime com reconhecimento de dispatcher sem imports de proxy/fetch protegido | + | `plugin-sdk/response-limit-runtime` | Leitor limitado de corpo de resposta sem a ampla superfície de runtime de mídia | + | `plugin-sdk/session-binding-runtime` | Estado atual de vinculação de conversa sem roteamento de vinculação configurada ou armazenamentos de pareamento | + | `plugin-sdk/session-store-runtime` | Helpers de leitura do armazenamento de sessão sem imports amplos de gravação/manutenção de configuração | + | `plugin-sdk/context-visibility-runtime` | Resolução de visibilidade de contexto e filtragem de contexto suplementar sem imports amplos de configuração/segurança | + | `plugin-sdk/string-coerce-runtime` | Helpers estreitos de coerção e normalização de registro/string primitivos sem imports de markdown/logging | + | `plugin-sdk/host-runtime` | Helpers de normalização de hostname e host SCP | + | `plugin-sdk/retry-runtime` | Helpers de configuração e executor de retry | + | `plugin-sdk/agent-runtime` | Helpers de diretório/identidade/workspace de agente | + | `plugin-sdk/directory-runtime` | Consulta/deduplicação de diretório baseada em configuração | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Subcaminho | Principais exportações | + | Subcaminho | Exportações principais | | --- | --- | - | `plugin-sdk/media-runtime` | Auxiliares compartilhados de busca/transformação/armazenamento de mídia, além de construtores de payload de mídia | - | `plugin-sdk/media-generation-runtime` | Auxiliares compartilhados de failover de geração de mídia, seleção de candidatos e mensagens para modelo ausente | + | `plugin-sdk/media-runtime` | Helpers compartilhados de fetch/transform/store de mídia, além de construtores de payload de mídia | + | `plugin-sdk/media-generation-runtime` | Helpers compartilhados de failover de geração de mídia, seleção de candidatos e mensagens de modelo ausente | | `plugin-sdk/media-understanding` | Tipos de provedor de entendimento de mídia, além de exportações auxiliares voltadas ao provedor para imagem/áudio | - | `plugin-sdk/text-runtime` | Auxiliares compartilhados de texto/markdown/logging, como remoção de texto visível ao assistente, auxiliares de renderização/fragmentação/tabela em markdown, auxiliares de redação, auxiliares de tag de diretiva e utilitários de texto seguro | - | `plugin-sdk/text-chunking` | Auxiliar de fragmentação de texto de saída | - | `plugin-sdk/speech` | Tipos de provedor de fala, além de auxiliares voltados ao provedor para diretiva, registro e validação | - | `plugin-sdk/speech-core` | Tipos compartilhados de provedor de fala, auxiliares de registro, diretiva e normalização | - | `plugin-sdk/realtime-transcription` | Tipos de provedor de transcrição em tempo real e auxiliares de registro | - | `plugin-sdk/realtime-voice` | Tipos de provedor de voz em tempo real e auxiliares de registro | + | `plugin-sdk/text-runtime` | Helpers compartilhados de texto/markdown/logging, como remoção de texto visível ao assistente, helpers de render/chunking/tabela Markdown, helpers de redação, helpers de tag de diretiva e utilitários de texto seguro | + | `plugin-sdk/text-chunking` | Helper de chunking de texto de saída | + | `plugin-sdk/speech` | Tipos de provedor de fala, além de helpers voltados ao provedor para diretiva, registro e validação | + | `plugin-sdk/speech-core` | Tipos compartilhados de provedor de fala, registro, diretiva e helpers de normalização | + | `plugin-sdk/realtime-transcription` | Tipos de provedor de transcrição em tempo real e helpers de registro | + | `plugin-sdk/realtime-voice` | Tipos de provedor de voz em tempo real e helpers de registro | | `plugin-sdk/image-generation` | Tipos de provedor de geração de imagem | - | `plugin-sdk/image-generation-core` | Tipos compartilhados de geração de imagem, auxiliares de failover, autenticação e registro | + | `plugin-sdk/image-generation-core` | Tipos compartilhados de geração de imagem, helpers de failover, autenticação e registro | | `plugin-sdk/music-generation` | Tipos de provedor/requisição/resultado de geração de música | - | `plugin-sdk/music-generation-core` | Tipos compartilhados de geração de música, auxiliares de failover, busca de provedor e parsing de referência de modelo | + | `plugin-sdk/music-generation-core` | Tipos compartilhados de geração de música, helpers de failover, busca de provedor e parsing de model-ref | | `plugin-sdk/video-generation` | Tipos de provedor/requisição/resultado de geração de vídeo | - | `plugin-sdk/video-generation-core` | Tipos compartilhados de geração de vídeo, auxiliares de failover, busca de provedor e parsing de referência de modelo | - | `plugin-sdk/webhook-targets` | Registro de alvos de Webhook e auxiliares de instalação de rota | - | `plugin-sdk/webhook-path` | Auxiliares de normalização de caminho de Webhook | - | `plugin-sdk/web-media` | Auxiliares compartilhados de carregamento de mídia remota/local | - | `plugin-sdk/zod` | `zod` reexportado para consumidores do Plugin SDK | + | `plugin-sdk/video-generation-core` | Tipos compartilhados de geração de vídeo, helpers de failover, busca de provedor e parsing de model-ref | + | `plugin-sdk/webhook-targets` | Registro de alvo de Webhook e helpers de instalação de rota | + | `plugin-sdk/webhook-path` | Helpers de normalização de caminho de Webhook | + | `plugin-sdk/web-media` | Helpers compartilhados de carregamento de mídia remota/local | + | `plugin-sdk/zod` | `zod` reexportado para consumidores do SDK de plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | Subcaminho | Principais exportações | + | Subcaminho | Exportações principais | | --- | --- | - | `plugin-sdk/memory-core` | Superfície auxiliar empacotada de memory-core para auxiliares de manager/configuração/arquivo/CLI | + | `plugin-sdk/memory-core` | Superfície auxiliar empacotada `memory-core` para helpers de manager/configuração/arquivo/CLI | | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime de índice/busca de memória | - | `plugin-sdk/memory-core-host-engine-foundation` | Exportações do engine foundation do host de memória | - | `plugin-sdk/memory-core-host-engine-embeddings` | Contratos de embedding do host de memória, acesso ao registro, provedor local e auxiliares genéricos de lote/remoto | - | `plugin-sdk/memory-core-host-engine-qmd` | Exportações do engine QMD do host de memória | - | `plugin-sdk/memory-core-host-engine-storage` | Exportações do engine de armazenamento do host de memória | - | `plugin-sdk/memory-core-host-multimodal` | Auxiliares multimodais do host de memória | - | `plugin-sdk/memory-core-host-query` | Auxiliares de consulta do host de memória | - | `plugin-sdk/memory-core-host-secret` | Auxiliares de segredo do host de memória | - | `plugin-sdk/memory-core-host-events` | Auxiliares de journal de eventos do host de memória | - | `plugin-sdk/memory-core-host-status` | Auxiliares de status do host de memória | - | `plugin-sdk/memory-core-host-runtime-cli` | Auxiliares de runtime da CLI do host de memória | - | `plugin-sdk/memory-core-host-runtime-core` | Auxiliares centrais de runtime do host de memória | - | `plugin-sdk/memory-core-host-runtime-files` | Auxiliares de arquivo/runtime do host de memória | - | `plugin-sdk/memory-host-core` | Alias neutro em relação ao fornecedor para os auxiliares centrais de runtime do host de memória | - | `plugin-sdk/memory-host-events` | Alias neutro em relação ao fornecedor para os auxiliares de journal de eventos do host de memória | - | `plugin-sdk/memory-host-files` | Alias neutro em relação ao fornecedor para os auxiliares de arquivo/runtime do host de memória | - | `plugin-sdk/memory-host-markdown` | Auxiliares compartilhados de managed-markdown para plugins adjacentes à memória | + | `plugin-sdk/memory-core-host-engine-foundation` | Exportações do mecanismo base do host de memória | + | `plugin-sdk/memory-core-host-engine-embeddings` | Contratos de embeddings do host de memória, acesso ao registro, provedor local e helpers genéricos de lote/remotos | + | `plugin-sdk/memory-core-host-engine-qmd` | Exportações do mecanismo QMD do host de memória | + | `plugin-sdk/memory-core-host-engine-storage` | Exportações do mecanismo de armazenamento do host de memória | + | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodais do host de memória | + | `plugin-sdk/memory-core-host-query` | Helpers de consulta do host de memória | + | `plugin-sdk/memory-core-host-secret` | Helpers de segredo do host de memória | + | `plugin-sdk/memory-core-host-events` | Helpers de journal de eventos do host de memória | + | `plugin-sdk/memory-core-host-status` | Helpers de status do host de memória | + | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime de CLI do host de memória | + | `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime principal do host de memória | + | `plugin-sdk/memory-core-host-runtime-files` | Helpers de arquivo/runtime do host de memória | + | `plugin-sdk/memory-host-core` | Alias neutro em relação a fornecedor para helpers de runtime principal do host de memória | + | `plugin-sdk/memory-host-events` | Alias neutro em relação a fornecedor para helpers de journal de eventos do host de memória | + | `plugin-sdk/memory-host-files` | Alias neutro em relação a fornecedor para helpers de arquivo/runtime do host de memória | + | `plugin-sdk/memory-host-markdown` | Helpers compartilhados de markdown gerenciado para plugins adjacentes à memória | | `plugin-sdk/memory-host-search` | Fachada de runtime de Active Memory para acesso ao gerenciador de busca | - | `plugin-sdk/memory-host-status` | Alias neutro em relação ao fornecedor para os auxiliares de status do host de memória | - | `plugin-sdk/memory-lancedb` | Superfície auxiliar empacotada de memory-lancedb | + | `plugin-sdk/memory-host-status` | Alias neutro em relação a fornecedor para helpers de status do host de memória | + | `plugin-sdk/memory-lancedb` | Superfície auxiliar empacotada `memory-lancedb` | - + | Família | Subcaminhos atuais | Uso pretendido | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Auxiliares de suporte do Plugin de navegador empacotado (`browser-support` continua sendo o barrel de compatibilidade) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superfície auxiliar/runtime empacotada do Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superfície auxiliar/runtime empacotada do LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superfície auxiliar empacotada do IRC | - | Auxiliares específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seams de compatibilidade/auxiliares de canais empacotados | - | Auxiliares específicos de autenticação/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seams auxiliares de recursos/plugins empacotados; `plugin-sdk/github-copilot-token` atualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de suporte do plugin Browser empacotado (`browser-support` continua sendo o barrel de compatibilidade) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superfície de helper/runtime empacotada do Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superfície de helper/runtime empacotada do LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superfície de helper empacotada do IRC | + | Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Interfaces de compatibilidade/helper de canal empacotado | + | Helpers específicos de autenticação/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Interfaces auxiliares de recurso/plugin empacotado; `plugin-sdk/github-copilot-token` atualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | @@ -310,45 +324,45 @@ métodos: ### Registro de capacidades -| Método | O que ele registra | -| ------------------------------------------------ | ----------------------------------- | -| `api.registerProvider(...)` | Inferência de texto (LLM) | +| Método | O que ele registra | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | Inferência de texto (LLM) | | `api.registerAgentHarness(...)` | Executor experimental de agente de baixo nível | -| `api.registerCliBackend(...)` | Backend de inferência local da CLI | -| `api.registerChannel(...)` | Canal de mensagens | -| `api.registerSpeechProvider(...)` | Síntese de texto para fala / STT | +| `api.registerCliBackend(...)` | Backend local de inferência por CLI | +| `api.registerChannel(...)` | Canal de mensagens | +| `api.registerSpeechProvider(...)` | Síntese de texto para fala / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Transcrição em tempo real por streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sessões de voz duplex em tempo real | -| `api.registerMediaUnderstandingProvider(...)` | Análise de imagem/áudio/vídeo | -| `api.registerImageGenerationProvider(...)` | Geração de imagem | -| `api.registerMusicGenerationProvider(...)` | Geração de música | -| `api.registerVideoGenerationProvider(...)` | Geração de vídeo | -| `api.registerWebFetchProvider(...)` | Provedor de busca/scrape da web | -| `api.registerWebSearchProvider(...)` | Busca na web | +| `api.registerRealtimeVoiceProvider(...)` | Sessões de voz bidirecionais em tempo real | +| `api.registerMediaUnderstandingProvider(...)` | Análise de imagem/áudio/vídeo | +| `api.registerImageGenerationProvider(...)` | Geração de imagem | +| `api.registerMusicGenerationProvider(...)` | Geração de música | +| `api.registerVideoGenerationProvider(...)` | Geração de vídeo | +| `api.registerWebFetchProvider(...)` | Provedor de busca / raspagem na web | +| `api.registerWebSearchProvider(...)` | Busca na web | ### Ferramentas e comandos -| Método | O que ele registra | -| ------------------------------- | -------------------------------------------- | +| Método | O que ele registra | +| ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Ferramenta do agente (obrigatória ou `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizado (ignora o LLM) | +| `api.registerCommand(def)` | Comando personalizado (ignora o LLM) | ### Infraestrutura -| Método | O que ele registra | -| ---------------------------------------------- | -------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook de evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP do Gateway | -| `api.registerGatewayMethod(name, handler)` | Método RPC do Gateway | -| `api.registerCli(registrar, opts?)` | Subcomando da CLI | -| `api.registerService(service)` | Serviço em segundo plano | -| `api.registerInteractiveHandler(registration)` | Manipulador interativo | -| `api.registerMemoryPromptSupplement(builder)` | Seção de prompt aditiva adjacente à memória | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de busca/leitura de memória | +| Método | O que ele registra | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook de evento | +| `api.registerHttpRoute(params)` | Endpoint HTTP do Gateway | +| `api.registerGatewayMethod(name, handler)` | Método RPC do Gateway | +| `api.registerCli(registrar, opts?)` | Subcomando da CLI | +| `api.registerService(service)` | Serviço em segundo plano | +| `api.registerInteractiveHandler(registration)` | Manipulador interativo | +| `api.registerMemoryPromptSupplement(builder)` | Seção adicional de prompt adjacente à memória | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus adicional de busca/leitura de memória | Namespaces administrativos reservados do núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) sempre permanecem `operator.admin`, mesmo que um plugin tente atribuir um -escopo mais restrito ao método do Gateway. Prefira prefixos específicos do plugin para +`update.*`) sempre permanecem `operator.admin`, mesmo que um plugin tente atribuir +um escopo mais restrito a um método do Gateway. Prefira prefixos específicos do plugin para métodos pertencentes ao plugin. ### Metadados de registro da CLI @@ -360,7 +374,7 @@ métodos pertencentes ao plugin. roteamento e registro lazy da CLI do plugin Se você quiser que um comando de plugin permaneça com carregamento lazy no caminho normal da CLI raiz, -forneça `descriptors` que cubram toda raiz de comando de nível superior exposta por esse +forneça `descriptors` que cubram cada raiz de comando de nível superior exposta por esse registrador. ```typescript @@ -373,7 +387,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Gerencie contas do Matrix, verificação, dispositivos e estado do perfil", + description: "Gerenciar contas Matrix, verificação, dispositivos e estado do perfil", hasSubcommands: true, }, ], @@ -382,67 +396,66 @@ api.registerCli( ``` Use `commands` sozinho apenas quando você não precisar de registro lazy na CLI raiz. -Esse caminho de compatibilidade eager continua sendo compatível, mas não instala -placeholders com suporte de descritor para carregamento lazy em tempo de parsing. +Esse caminho compatível e ansioso continua com suporte, mas não instala +placeholders com suporte de descriptor para carregamento lazy em tempo de parsing. ### Registro de backend da CLI -`api.registerCliBackend(...)` permite que um plugin seja o dono da configuração padrão de um +`api.registerCliBackend(...)` permite que um plugin seja dono da configuração padrão de um backend local de CLI de IA, como `codex-cli`. - O `id` do backend se torna o prefixo do provedor em referências de modelo como `codex-cli/gpt-5`. - A `config` do backend usa o mesmo formato de `agents.defaults.cliBackends.`. -- A configuração do usuário continua tendo prioridade. O OpenClaw mescla `agents.defaults.cliBackends.` sobre o +- A configuração do usuário continua prevalecendo. O OpenClaw mescla `agents.defaults.cliBackends.` sobre o padrão do plugin antes de executar a CLI. -- Use `normalizeConfig` quando um backend precisar de reescritas de compatibilidade após a mesclagem - (por exemplo, normalizando formatos antigos de flags). +- Use `normalizeConfig` quando um backend precisar de regravações de compatibilidade após a mesclagem + (por exemplo, normalizando formatos antigos de flag). ### Slots exclusivos -| Método | O que ele registra | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Mecanismo de contexto (apenas um ativo por vez). O callback `assemble()` recebe `availableTools` e `citationsMode` para que o mecanismo adapte adições ao prompt. | -| `api.registerMemoryCapability(capability)` | Capacidade de memória unificada | -| `api.registerMemoryPromptSection(builder)` | Construtor de seção de prompt de memória | -| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plano de flush de memória | -| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memória | +| Método | O que ele registra | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Mecanismo de contexto (um ativo por vez). O callback `assemble()` recebe `availableTools` e `citationsMode` para que o mecanismo possa adaptar adições ao prompt. | +| `api.registerMemoryCapability(capability)` | Capacidade unificada de memória | +| `api.registerMemoryPromptSection(builder)` | Construtor de seção de prompt de memória | +| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plano de flush de memória | +| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memória | ### Adaptadores de embedding de memória -| Método | O que ele registra | -| ---------------------------------------------- | ------------------------------------------ | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embedding de memória para o Plugin ativo | +| Método | O que ele registra | +| ---------------------------------------------- | ---------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embedding de memória para o plugin ativo | - `registerMemoryCapability` é a API exclusiva preferida para plugin de memória. - `registerMemoryCapability` também pode expor `publicArtifacts.listArtifacts(...)` - para que plugins complementares consumam artefatos de memória exportados por meio de + para que plugins complementares possam consumir artefatos de memória exportados por meio de `openclaw/plugin-sdk/memory-host-core` em vez de acessar o layout privado de um plugin de memória específico. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` e - `registerMemoryRuntime` são APIs exclusivas de plugin de memória compatíveis com versões legadas. -- `registerMemoryEmbeddingProvider` permite que o Plugin de memória ativo registre um - ou mais IDs de adaptador de embedding (por exemplo, `openai`, `gemini` ou um ID - personalizado definido pelo plugin). -- Configurações do usuário como `agents.defaults.memorySearch.provider` e - `agents.defaults.memorySearch.fallback` são resolvidas com base nesses IDs de - adaptador registrados. + `registerMemoryRuntime` são APIs exclusivas legadas compatíveis para plugin de memória. +- `registerMemoryEmbeddingProvider` permite que o plugin de memória ativo registre um + ou mais IDs de adaptador de embedding (por exemplo `openai`, `gemini` ou um ID personalizado + definido pelo plugin). +- Configuração do usuário, como `agents.defaults.memorySearch.provider` e + `agents.defaults.memorySearch.fallback`, é resolvida com base nesses IDs de adaptador registrados. ### Eventos e ciclo de vida -| Método | O que ele faz | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | -| `api.onConversationBindingResolved(handler)` | Callback de vínculo de conversa | +| Método | O que ele faz | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | +| `api.onConversationBindingResolved(handler)` | Callback de vinculação de conversa | ### Semântica de decisão de hook -- `before_tool_call`: retornar `{ block: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados. -- `before_tool_call`: retornar `{ block: false }` é tratado como nenhuma decisão (igual a omitir `block`), não como uma substituição. -- `before_install`: retornar `{ block: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados. -- `before_install`: retornar `{ block: false }` é tratado como nenhuma decisão (igual a omitir `block`), não como uma substituição. -- `reply_dispatch`: retornar `{ handled: true, ... }` é terminal. Assim que qualquer manipulador assumir o despacho, manipuladores de menor prioridade e o caminho padrão de despacho do modelo serão ignorados. -- `message_sending`: retornar `{ cancel: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados. -- `message_sending`: retornar `{ cancel: false }` é tratado como nenhuma decisão (igual a omitir `cancel`), não como uma substituição. +- `before_tool_call`: retornar `{ block: true }` é terminal. Assim que qualquer handler definir isso, handlers de prioridade mais baixa serão ignorados. +- `before_tool_call`: retornar `{ block: false }` é tratado como nenhuma decisão (o mesmo que omitir `block`), não como sobrescrita. +- `before_install`: retornar `{ block: true }` é terminal. Assim que qualquer handler definir isso, handlers de prioridade mais baixa serão ignorados. +- `before_install`: retornar `{ block: false }` é tratado como nenhuma decisão (o mesmo que omitir `block`), não como sobrescrita. +- `reply_dispatch`: retornar `{ handled: true, ... }` é terminal. Assim que qualquer handler assumir o dispatch, handlers de prioridade mais baixa e o caminho padrão de dispatch do modelo serão ignorados. +- `message_sending`: retornar `{ cancel: true }` é terminal. Assim que qualquer handler definir isso, handlers de prioridade mais baixa serão ignorados. +- `message_sending`: retornar `{ cancel: false }` é tratado como nenhuma decisão (o mesmo que omitir `cancel`), não como sobrescrita. ### Campos do objeto da API @@ -454,61 +467,62 @@ backend local de CLI de IA, como `codex-cli`. | `api.description` | `string?` | Descrição do plugin (opcional) | | `api.source` | `string` | Caminho de origem do plugin | | `api.rootDir` | `string?` | Diretório raiz do plugin (opcional) | -| `api.config` | `OpenClawConfig` | Snapshot da configuração atual (snapshot ativo em memória no runtime quando disponível) | +| `api.config` | `OpenClawConfig` | Snapshot atual da configuração (snapshot ativo em memória do runtime quando disponível) | | `api.pluginConfig` | `Record` | Configuração específica do plugin em `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Auxiliares de runtime](/pt-BR/plugins/sdk-runtime) | +| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/pt-BR/plugins/sdk-runtime) | | `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração antes da entrada completa | -| `api.resolvePath(input)` | `(string) => string` | Resolve o caminho em relação à raiz do plugin | +| `api.resolvePath(input)` | `(string) => string` | Resolve um caminho relativo à raiz do plugin | -## Convenção de módulos internos +## Convenção de módulo interno Dentro do seu plugin, use arquivos barrel locais para importações internas: ``` my-plugin/ api.ts # Exportações públicas para consumidores externos - runtime-api.ts # Exportações de runtime somente internas + runtime-api.ts # Exportações internas de runtime index.ts # Ponto de entrada do plugin - setup-entry.ts # Entrada leve somente para configuração (opcional) + setup-entry.ts # Entrada leve apenas para configuração (opcional) ``` Nunca importe seu próprio plugin por meio de `openclaw/plugin-sdk/` - a partir de código de produção. Direcione importações internas por `./api.ts` ou + em código de produção. Direcione importações internas por `./api.ts` ou `./runtime-api.ts`. O caminho do SDK é apenas o contrato externo. -Superfícies públicas de plugins empacotados carregadas por fachada (`api.ts`, `runtime-api.ts`, +Superfícies públicas de plugin empacotado carregadas por facade (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` e arquivos públicos de entrada semelhantes) agora preferem o -snapshot ativo de configuração do runtime quando o OpenClaw já está em execução. Se ainda não existir -um snapshot de runtime, elas recorrem à configuração resolvida no arquivo em disco. +snapshot ativo de configuração de runtime quando o OpenClaw já está em execução. Se ainda não existir +um snapshot de runtime, elas recorrem ao arquivo de configuração resolvido em disco. -Plugins de provedor também podem expor um barrel de contrato local e restrito ao plugin quando um -auxiliar for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico do SDK. -Exemplo empacotado atual: o provedor Anthropic mantém seus auxiliares de stream do Claude em seu próprio -seam público `api.ts` / `contract-api.ts`, em vez de promover a lógica de cabeçalho beta do Anthropic e `service_tier` -para um contrato genérico `plugin-sdk/*`. +Plugins de provedor também podem expor um barrel de contrato local e estreito do plugin quando um +helper for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico +do SDK. Exemplo empacotado atual: o provedor Anthropic mantém seus helpers de stream Claude +em sua própria interface pública `api.ts` / `contract-api.ts`, em vez de +promover a lógica de cabeçalho beta do Anthropic e `service_tier` para um contrato genérico +`plugin-sdk/*`. Outros exemplos empacotados atuais: -- `@openclaw/openai-provider`: `api.ts` exporta construtores de provedor, - auxiliares de modelo padrão e construtores de provedor em tempo real -- `@openclaw/openrouter-provider`: `api.ts` exporta o construtor do provedor e - auxiliares de onboarding/configuração +- `@openclaw/openai-provider`: `api.ts` exporta builders de provedor, + helpers de modelo padrão e builders de provedor em tempo real +- `@openclaw/openrouter-provider`: `api.ts` exporta o builder de provedor, além de + helpers de onboarding/configuração O código de produção de extensões também deve evitar importações de `openclaw/plugin-sdk/`. - Se um auxiliar for realmente compartilhado, promova-o a um subcaminho neutro do SDK, + Se um helper for realmente compartilhado, promova-o para um subcaminho neutro do SDK, como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` ou outra - superfície orientada por capacidade, em vez de acoplar dois plugins. + superfície orientada a capacidade, em vez de acoplar dois plugins entre si. ## Relacionado - [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) — opções de `definePluginEntry` e `defineChannelPluginEntry` -- [Auxiliares de runtime](/pt-BR/plugins/sdk-runtime) — referência completa do namespace `api.runtime` -- [Configuração e setup](/pt-BR/plugins/sdk-setup) — empacotamento, manifests, esquemas de configuração +- [Helpers de runtime](/pt-BR/plugins/sdk-runtime) — referência completa do namespace `api.runtime` +- [Configuração e config](/pt-BR/plugins/sdk-setup) — empacotamento, manifests, schemas de configuração - [Testes](/pt-BR/plugins/sdk-testing) — utilitários de teste e regras de lint -- [Migração do SDK](/pt-BR/plugins/sdk-migration) — migração de superfícies descontinuadas -- [Internals de plugin](/pt-BR/plugins/architecture) — arquitetura detalhada e modelo de capacidade +- [Migração do SDK](/pt-BR/plugins/sdk-migration) — migração a partir de superfícies obsoletas +- [Internos de plugin](/pt-BR/plugins/architecture) — arquitetura profunda e modelo de capacidades diff --git a/docs/pt-BR/refactor/qa.md b/docs/pt-BR/refactor/qa.md index 393902603..c63e55a75 100644 --- a/docs/pt-BR/refactor/qa.md +++ b/docs/pt-BR/refactor/qa.md @@ -1,9 +1,9 @@ --- x-i18n: - generated_at: "2026-04-08T05:27:22Z" + generated_at: "2026-04-18T05:25:15Z" model: gpt-5.4 provider: openai - source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd + source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca source_path: refactor/qa.md workflow: 15 --- @@ -14,21 +14,21 @@ Status: migração fundamental concluída. ## Objetivo -Mover o QA do OpenClaw de um modelo de definição dividida para uma única fonte da verdade: +Mover o QA do OpenClaw de um modelo de definição dividido para uma única fonte da verdade: - metadados do cenário - prompts enviados ao modelo -- configuração e desmontagem +- setup e teardown - lógica do harness - asserções e critérios de sucesso -- artefatos e sugestões de relatório +- artifacts e dicas de relatório -O estado final desejado é um harness de QA genérico que carrega arquivos poderosos de definição de cenários em vez de codificar a maior parte do comportamento em TypeScript. +O estado final desejado é um harness de QA genérico que carregue arquivos poderosos de definição de cenário em vez de codificar a maior parte do comportamento em TypeScript. ## Estado atual -A fonte primária da verdade agora vive em `qa/scenarios/index.md` mais um arquivo por -cenário em `qa/scenarios/*.md`. +A principal fonte da verdade agora vive em `qa/scenarios/index.md` mais um arquivo por +cenário em `qa/scenarios//*.md`. Implementado: @@ -36,99 +36,99 @@ Implementado: - metadados canônicos do pacote de QA - identidade do operador - missão inicial -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` - um arquivo Markdown por cenário - metadados do cenário - associações de handlers - configuração de execução específica do cenário - `extensions/qa-lab/src/scenario-catalog.ts` - - parser do pacote Markdown + validação com zod + - parser de pacote Markdown + validação com zod - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - renderização do plano a partir do pacote Markdown - `extensions/qa-lab/src/qa-agent-workspace.ts` - - gera arquivos de compatibilidade semeados mais `QA_SCENARIOS.md` + - semeia arquivos de compatibilidade gerados mais `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - seleciona cenários executáveis por meio de associações de handlers definidas em Markdown -- protocolo do barramento de QA + UI +- Protocolo do barramento de QA + UI - anexos inline genéricos para renderização de imagem/vídeo/áudio/arquivo Superfícies divididas restantes: - `extensions/qa-lab/src/suite.ts` - - ainda concentra a maior parte da lógica executável de handlers personalizados + - ainda controla a maior parte da lógica executável de handlers personalizados - `extensions/qa-lab/src/report.ts` - - ainda deriva a estrutura do relatório a partir das saídas em tempo de execução + - ainda deriva a estrutura do relatório a partir das saídas de runtime -Portanto, a divisão da fonte da verdade foi corrigida, mas a execução ainda é majoritariamente baseada em handlers, e não totalmente declarativa. +Então a divisão da fonte da verdade foi corrigida, mas a execução ainda é em grande parte baseada em handlers, e não totalmente declarativa. ## Como é a superfície real de cenários -Ao ler a suíte atual, é possível ver algumas classes distintas de cenários. +Ler a suíte atual mostra algumas classes distintas de cenários. ### Interação simples -- linha de base de canal -- linha de base de MD +- baseline de canal +- baseline de DM - acompanhamento em thread - troca de modelo -- continuidade após aprovação +- continuidade de aprovação - reação/edição/exclusão -### Mutação de configuração e tempo de execução +### Configuração e mutação de runtime - patch de configuração para desabilitar skill -- aplicação de configuração com reativação após reinício -- inversão de capacidade após reinício da configuração -- verificação de divergência do inventário em tempo de execução +- config apply restart wake-up +- config restart capability flip +- verificação de desvio do inventário de runtime ### Asserções de sistema de arquivos e repositório -- relatório de descoberta de código/documentação -- compilar Lobster Invaders -- busca de artefato de imagem gerada +- relatório de descoberta de source/docs +- build do Lobster Invaders +- busca de artifact de imagem gerada ### Orquestração de memória - recuperação de memória - ferramentas de memória em contexto de canal -- fallback em falha de memória +- fallback de falha de memória - classificação de memória de sessão -- isolamento de memória de thread -- varredura de sonho de memória +- isolamento de memória por thread +- varredura de Dreaming da memória ### Integração de ferramentas e plugins -- chamada de plugin-tools do MCP +- chamada de plugin-tools MCP - visibilidade de skill -- instalação dinâmica de skill +- hot install de skill - geração nativa de imagem - roundtrip de imagem -- compreensão de imagem a partir de anexo +- entendimento de imagem a partir de anexo -### Vários turnos e vários atores +### Multiturno e multiautor -- transferência para subagente -- síntese com distribuição para subagentes -- fluxos no estilo recuperação após reinício +- handoff de subagente +- síntese de fanout de subagente +- fluxos no estilo de recuperação após reinício -Essas categorias são importantes porque orientam os requisitos da DSL. Uma lista simples de prompt + texto esperado não é suficiente. +Essas categorias importam porque orientam os requisitos da DSL. Uma lista plana de prompt + texto esperado não é suficiente. ## Direção ### Fonte única da verdade -Usar `qa/scenarios/index.md` mais `qa/scenarios/*.md` como a fonte da verdade -autoral. +Usar `qa/scenarios/index.md` mais `qa/scenarios//*.md` como a +fonte da verdade criada manualmente. -O pacote deve permanecer: +O pacote deve continuar sendo: -- legível para humanos em revisão -- analisável por máquina +- legível por humanos em revisão +- parseável por máquina - rico o suficiente para orientar: - execução da suíte - bootstrap do workspace de QA - metadados da UI do QA Lab - - prompts de documentação/descoberta + - prompts de docs/discovery - geração de relatórios ### Formato de autoria preferido @@ -142,9 +142,9 @@ Formato recomendado: - title - surface - tags - - refs de documentação + - refs de docs - refs de código - - substituições de modelo/provedor + - sobrescritas de modelo/provider - pré-requisitos - seções em prosa - objetivo @@ -158,7 +158,7 @@ Formato recomendado: Isso oferece: -- melhor legibilidade em PR do que um JSON gigante +- melhor legibilidade em PR do que JSON gigante - contexto mais rico do que YAML puro - parsing estrito e validação com zod @@ -171,7 +171,7 @@ Exemplo: ````md --- id: image-generation-roundtrip -title: Image generation roundtrip +title: Roundtrip de geração de imagem surface: image tags: [media, image, roundtrip] models: @@ -187,9 +187,9 @@ codeRefs: - src/gateway/chat-attachments.ts --- -# Objective +# Objetivo -Verify generated media is reattached on the follow-up turn. +Verificar se a mídia gerada é reanexada no turno de acompanhamento. # Setup @@ -210,15 +210,15 @@ Verify generated media is reattached on the follow-up turn. - action: agent.send session: agent:qa:image-roundtrip message: | - Image generation check: generate a QA lighthouse image and summarize it in one short sentence. + Verificação de geração de imagem: gere uma imagem de um farol de QA e resuma-a em uma frase curta. - action: artifact.capture kind: generated-image - promptSnippet: Image generation check + promptSnippet: Verificação de geração de imagem saveAs: lighthouseImage - action: agent.send session: agent:qa:image-roundtrip message: | - Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence. + Verificação de inspeção de roundtrip de imagem: descreva o anexo da imagem do farol gerado em uma frase curta. attachments: - fromArtifact: lighthouseImage ``` @@ -227,21 +227,21 @@ Verify generated media is reattached on the follow-up turn. ```yaml scenario.expect - assert: outbound.textIncludes - value: lighthouse + value: farol - assert: requestLog.matches where: - promptIncludes: Roundtrip image inspection check + promptIncludes: Verificação de inspeção de roundtrip de imagem imageInputCountGte: 1 - assert: artifact.exists ref: lighthouseImage ``` ```` -## Capacidades do runner que a DSL precisa cobrir +## Recursos de runner que a DSL precisa cobrir -Com base na suíte atual, o runner genérico precisa de mais do que execução de prompt. +Com base na suíte atual, o runner genérico precisa de mais do que execução de prompts. -### Ações de ambiente e configuração +### Ações de ambiente e setup - `bus.reset` - `gateway.waitHealthy` @@ -257,7 +257,7 @@ Com base na suíte atual, o runner genérico precisa de mais do que execução d - `bus.injectInbound` - `bus.injectOutbound` -### Ações de configuração e tempo de execução +### Ações de configuração e runtime - `config.get` - `config.patch` @@ -266,7 +266,7 @@ Com base na suíte atual, o runner genérico precisa de mais do que execução d - `tools.effective` - `skills.status` -### Ações de arquivo e artefato +### Ações de arquivo e artifact - `file.write` - `file.read` @@ -275,7 +275,7 @@ Com base na suíte atual, o runner genérico precisa de mais do que execução d - `artifact.captureGeneratedImage` - `artifact.capturePath` -### Ações de memória e cron +### Ações de memória e Cron - `memory.indexForce` - `memory.searchCli` @@ -305,60 +305,60 @@ Com base na suíte atual, o runner genérico precisa de mais do que execução d - `cron.managedPresent` - `artifact.exists` -## Variáveis e referências a artefatos +## Variáveis e referências de artifact -A DSL deve dar suporte a saídas salvas e referências posteriores. +A DSL precisa oferecer suporte a saídas salvas e referências posteriores. Exemplos da suíte atual: - criar uma thread e depois reutilizar `threadId` - criar uma sessão e depois reutilizar `sessionKey` -- gerar uma imagem e depois anexar o arquivo no turno seguinte -- gerar uma string de marcador de reativação e depois verificar que ela aparece mais tarde +- gerar uma imagem e depois anexar o arquivo no próximo turno +- gerar uma string de marcador de wake e depois verificar que ela aparece mais tarde -Capacidades necessárias: +Recursos necessários: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- referências tipadas para caminhos, chaves de sessão, ids de thread, marcadores e saídas de ferramentas +- referências tipadas para caminhos, chaves de sessão, ids de thread, marcadores, saídas de ferramentas -Sem suporte a variáveis, o harness continuará deixando a lógica de cenário vazar de volta para o TypeScript. +Sem suporte a variáveis, o harness continuará vazando lógica de cenário de volta para o TypeScript. ## O que deve permanecer como escape hatch -Um runner totalmente declarativo e puro não é realista na fase 1. +Um runner totalmente declarativo puro não é realista na fase 1. Alguns cenários são inerentemente pesados em orquestração: -- varredura de sonho de memória -- aplicação de configuração com reativação após reinício -- inversão de capacidade após reinício da configuração -- resolução de artefato de imagem gerada por timestamp/caminho +- varredura de Dreaming da memória +- config apply restart wake-up +- config restart capability flip +- resolução de artifact de imagem gerada por timestamp/caminho - avaliação de relatório de descoberta -Por enquanto, eles devem usar handlers personalizados explícitos. +Por enquanto, estes devem usar handlers personalizados explícitos. Regra recomendada: - 85-90% declarativo -- etapas `customHandler` explícitas para o restante mais difícil +- steps com `customHandler` explícito para o restante mais difícil - apenas handlers personalizados nomeados e documentados - nenhum código inline anônimo no arquivo de cenário -Isso mantém o mecanismo genérico limpo e ainda permite progresso. +Isso mantém o mecanismo genérico limpo e ainda permite avançar. ## Mudança de arquitetura ### Atual -O Markdown de cenário já é a fonte da verdade para: +O Markdown de cenários já é a fonte da verdade para: - execução da suíte - arquivos de bootstrap do workspace - catálogo de cenários da UI do QA Lab -- metadados do relatório -- prompts de descoberta +- metadados de relatório +- prompts de discovery Compatibilidade gerada: @@ -373,8 +373,8 @@ Compatibilidade gerada: Concluído. - adicionado `qa/scenarios/index.md` -- cenários divididos em `qa/scenarios/*.md` -- adicionado parser para conteúdo nomeado do pacote Markdown YAML +- cenários divididos em `qa/scenarios//*.md` +- adicionado parser para conteúdo nomeado de pacote Markdown YAML - validado com zod - consumidores alterados para usar o pacote parseado - removidos `qa/seed-scenarios.json` e `qa/QA_KICKOFF_TASK.md` no nível do repositório @@ -383,7 +383,7 @@ Concluído. - dividir `extensions/qa-lab/src/suite.ts` em: - loader - - mecanismo + - mechanism - registro de ações - registro de asserções - handlers personalizados @@ -396,46 +396,46 @@ Entregável: Começar com cenários que são principalmente prompt + espera + asserção: - acompanhamento em thread -- compreensão de imagem a partir de anexo +- entendimento de imagem a partir de anexo - visibilidade e invocação de skill -- linha de base de canal +- baseline de canal Entregável: -- primeiros cenários reais definidos em Markdown enviados pelo mecanismo genérico +- primeiros cenários reais definidos em Markdown sendo entregues pelo mecanismo genérico ### Fase 4: migrar cenários intermediários - roundtrip de geração de imagem - ferramentas de memória em contexto de canal - classificação de memória de sessão -- transferência para subagente -- síntese com distribuição para subagentes +- handoff de subagente +- síntese de fanout de subagente Entregável: -- variáveis, artefatos, asserções de ferramenta e asserções de log de requisição comprovados +- variáveis, artifacts, asserções de ferramenta e asserções de log de requisição comprovados ### Fase 5: manter cenários difíceis em handlers personalizados -- varredura de sonho de memória -- aplicação de configuração com reativação após reinício -- inversão de capacidade após reinício da configuração -- divergência do inventário em tempo de execução +- varredura de Dreaming da memória +- config apply restart wake-up +- config restart capability flip +- desvio de inventário de runtime Entregável: -- mesmo formato de autoria, mas com blocos de etapas personalizadas explícitas quando necessário +- mesmo formato de autoria, mas com blocos explícitos de steps personalizados quando necessário -### Fase 6: excluir o mapa de cenários codificado +### Fase 6: excluir mapa de cenários codificado -Quando a cobertura do pacote estiver boa o suficiente: +Quando a cobertura do pacote for boa o suficiente: -- remover a maior parte da ramificação TypeScript específica de cenários de `extensions/qa-lab/src/suite.ts` +- remover a maior parte do branching específico por cenário em TypeScript de `extensions/qa-lab/src/suite.ts` -## Suporte a Slack falso / rich media +## Suporte a Fake Slack / mídia rica -O barramento de QA atual é focado em texto. +O barramento de QA atual é orientado a texto. Arquivos relevantes: @@ -445,7 +445,7 @@ Arquivos relevantes: - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -Hoje, o barramento de QA oferece suporte a: +Hoje o barramento de QA oferece suporte a: - texto - reações @@ -482,36 +482,36 @@ Depois adicionar `attachments?: QaBusAttachment[]` a: ### Por que genérico primeiro -Não construir um modelo de mídia exclusivo para Slack. +Não criar um modelo de mídia exclusivo para Slack. Em vez disso: - um modelo genérico de transporte de QA -- vários renderizadores sobre ele +- múltiplos renderizadores sobre ele - chat atual do QA Lab - - futuro web de Slack falso - - qualquer outra visualização de transporte falsa + - futuro fake Slack web + - quaisquer outras visualizações de transporte fake -Isso evita lógica duplicada e permite que cenários de mídia permaneçam agnósticos ao transporte. +Isso evita lógica duplicada e permite que cenários de mídia permaneçam independentes do transporte. ### Trabalho de UI necessário Atualizar a UI de QA para renderizar: -- pré-visualização de imagem inline +- pré-visualização inline de imagem - player de áudio inline - player de vídeo inline - chip de anexo de arquivo -A UI atual já consegue renderizar threads e reações, então a renderização de anexos deve ser adicionada sobre o mesmo modelo de cartão de mensagem. +A UI atual já consegue renderizar threads e reações, então a renderização de anexos deve se sobrepor ao mesmo modelo de cartão de mensagem. ### Trabalho de cenário habilitado pelo transporte de mídia -Quando os anexos passarem pelo barramento de QA, poderemos adicionar cenários mais ricos de chat falso: +Assim que os anexos passarem pelo barramento de QA, poderemos adicionar cenários mais ricos de chat fake: -- resposta com imagem inline em Slack falso -- compreensão de anexo de áudio -- compreensão de anexo de vídeo +- resposta inline com imagem em fake Slack +- entendimento de anexo de áudio +- entendimento de anexo de vídeo - ordenação mista de anexos - resposta em thread com mídia preservada @@ -528,13 +528,13 @@ O próximo bloco de implementação deve ser: Este é o menor caminho que comprova ambos os objetivos: -- QA genérico definido por Markdown -- superfícies de mensagens falsas mais ricas +- QA genérico definido em Markdown +- superfícies mais ricas de mensagens fake ## Perguntas em aberto -- se os arquivos de cenário devem permitir templates de prompt em Markdown embutidos com interpolação de variáveis +- se os arquivos de cenário devem permitir templates de prompt em Markdown incorporados com interpolação de variáveis - se setup/cleanup devem ser seções nomeadas ou apenas listas ordenadas de ações -- se referências a artefatos devem ser fortemente tipadas no schema ou baseadas em string -- se handlers personalizados devem viver em um único registro ou em registros por superfície -- se o arquivo de compatibilidade JSON gerado deve permanecer versionado durante a migração +- se as referências de artifacts devem ser fortemente tipadas no schema ou baseadas em string +- se handlers personalizados devem ficar em um único registro ou em registros por surface +- se o arquivo de compatibilidade JSON gerado deve continuar versionado durante a migração