chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
cfa2d9c970
commit
7e561b7568
@ -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/<agentId>/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/<agentId>/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 <path>` para semear qualquer arquivo ausente.
|
||||
4. Se precisar de sessões, copie `~/.openclaw/agents/<agentId>/sessions/` da
|
||||
3. Execute `openclaw setup --workspace <path>` para preencher quaisquer arquivos ausentes.
|
||||
4. Se você precisar das sessões, copie `~/.openclaw/agents/<agentId>/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
|
||||
|
||||
@ -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: <workspaceDir>
|
||||
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
|
||||
|
||||
@ -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=<path>` 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=<path>` 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 <count>` 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 <count>` 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/<theme>/*.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=<level>`. `--thinking <level>` ainda define um fallback
|
||||
global, e o formato mais antigo `--model-thinking <provider/model=level>` é
|
||||
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=<level>`. `--thinking <level>` ainda define um fallback global, e o formato mais antigo `--model-thinking <provider/model=level>` é 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)
|
||||
|
||||
@ -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
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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
|
||||
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e
|
||||
blocos truncados de chamada de ferramenta) e tokens 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.<skillKey>`, 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.<skillKey>`, 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`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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.<profile>` ao executar com um perfil nomeado.
|
||||
Substitua o rótulo por `ai.openclaw.<profile>` 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 <ws://host:port>`: substitui a configuração
|
||||
- `--mode <local|remote>`: 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 <ms>`: 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 <ms>`: janela geral de descoberta (padrão: `2000`)
|
||||
- `--json`: saída estruturada para comparação
|
||||
- `--timeout <ms>`: 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 <local>:127.0.0.1:<remote>` 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 <local>:127.0.0.1:<remote>` 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)
|
||||
|
||||
@ -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.
|
||||
|
||||
<Info>
|
||||
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.
|
||||
</Info>
|
||||
|
||||
## 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.<channel>.accounts.<id>.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.<channel>.accounts.<id>.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
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Pacote e manifesto">
|
||||
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):
|
||||
|
||||
<CodeGroup>
|
||||
```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 })`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Crie o objeto do Plugin de canal">
|
||||
A interface `ChannelPlugin` tem muitas superfícies de adaptador opcionais. Comece com
|
||||
<Step title="Crie o objeto do plugin de canal">
|
||||
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 })`.
|
||||
|
||||
<Accordion title="O que `createChatChannelPlugin` faz por você">
|
||||
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 })`.
|
||||
</Step>
|
||||
|
||||
<Step title="Trate mensagens de entrada">
|
||||
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 })`.
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Teste">
|
||||
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 -- <bundled-plugin-root>/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).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -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`:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Opções de encadeamento" icon="git-branch" href="/pt-BR/plugins/sdk-entrypoints#registration-mode">
|
||||
Modos de resposta fixos, com escopo de conta ou personalizados
|
||||
Modos de resposta fixos, com escopo por conta ou personalizados
|
||||
</Card>
|
||||
<Card title="Integração com a ferramenta de mensagem" icon="puzzle" href="/pt-BR/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool e descoberta de ações
|
||||
</Card>
|
||||
<Card title="Resolução de alvo" icon="crosshair" href="/pt-BR/plugins/architecture#channel-target-resolution">
|
||||
<Card title="Resolução de destino" icon="crosshair" href="/pt-BR/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Helpers de runtime" icon="settings" href="/pt-BR/plugins/sdk-runtime">
|
||||
@ -619,15 +594,15 @@ Escreva testes colocados lado a lado em `src/channel.test.ts`:
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subcaminhos de canal">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subcaminhos de provedor">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subcaminhos de autenticação e segurança">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subcaminhos de runtime e armazenamento">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subcaminhos de capacidade e testes">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subcaminhos de memória">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subcaminhos auxiliares empacotados reservados">
|
||||
<Accordion title="Subcaminhos reservados de helpers empacotados">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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.<id>`.
|
||||
- A configuração do usuário continua tendo prioridade. O OpenClaw mescla `agents.defaults.cliBackends.<id>` sobre o
|
||||
- A configuração do usuário continua prevalecendo. O OpenClaw mescla `agents.defaults.cliBackends.<id>` 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<string, unknown>` | Configuração específica do plugin em `plugins.entries.<id>.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)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Nunca importe seu próprio plugin por meio de `openclaw/plugin-sdk/<your-plugin>`
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
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
|
||||
|
||||
<Warning>
|
||||
O código de produção de extensões também deve evitar importações de `openclaw/plugin-sdk/<other-plugin>`.
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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/<theme>/*.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/<theme>/*.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/<theme>/*.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/<theme>/*.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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user