Ajuda e referência
13. Avisos e sinais
| Sinal | O que significa |
|---|---|
| Badge “!” no ícone | Falta configurar o pareamento |
| Badge com número | Quantas conversas têm novidade (no máximo 9) |
| Ponto verde/vermelho/âmbar no cabeçalho | API online, offline ou conectando |
| Banner de conexão | Explica a falha e oferece Tentar novamente, Reconectar ou Abrir configurações |
| Faixa de status abaixo do chat | Tentativas de reconexão e mensagens do backend |
| Borda azul na página | O agente está agindo naquela aba; tem botão Parar |
| “ferramentas conectadas” / “ferramentas offline” | Estado do plugin no rodapé do composer |
| Som + notificação | Algo aconteceu com o painel fechado (fim de execução, permissão, pergunta) |
| Aviso temporário no rodapé | Confirmação ou erro de uma ação sua |
14. Problemas comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Painel diz que o OpenCode não está respondendo | Servidor parado | Rode opencode serve e clique em Tentar novamente |
| “Token do OpenCode inválido ou expirado” | Token revogado ou trocado | opencode pair e cole o link novo nas configurações |
| “O OpenCode demorou demais para responder” | Servidor travado | Reinicie o OpenCode |
| Ferramentas offline | Plugin não instalado ou serviço antigo em memória | npm run install:plugin + opencode service restart |
| “Plugin recusou a conexão” | ID da extensão diferente do esperado | Recarregue a extensão; se persistir, ajuste OPENCODE_BROWSER_EXTENSION_ID |
O agente não acha browser_tabs_close | Nome reservado por outro plugin | Use browser_tabs_close_tab e reagende as ferramentas |
| Mudança no código não aparece | Service worker em cache | Recarregar em chrome://extensions |
| “Não foi possível preparar a página…” | Página chrome://, Chrome Web Store ou aba em branco | Abra uma página normal e tente de novo |
| “O DevTools está aberto nesta aba…” | DevTools interfere na automação | Feche o DevTools daquela aba |
| “A ref … está dentro de um iframe…” | Ação por coordenadas em elemento de iframe | Peça a ação por referência (clicar/preencher) |
| “Ref … não encontrada” | A página mudou depois da leitura | Peça ao agente para ler a página de novo |
| “Só é possível anexar abas http(s).” | Aba interna do navegador | Use uma página comum |
| “A aba está em outra janela…” | Grupo pertence a outra janela | Abra uma aba pela conversa ou mova a aba de janela |
| “O arquivo … excede o limite de ~5 MB.” | Upload grande demais | Reduza o arquivo |
| “Nenhum quadro gravado…” | GIF sem start | Peça para iniciar a gravação antes |
| “Falha ao gerar o GIF (offscreen indisponível).” | Documento offscreen não subiu | Recarregue a extensão |
Erro 403 nas ferramentas | Token do relay desatualizado | Apague ~/.cache/opencode-browser/relay.json (ou em $XDG_RUNTIME_DIR/opencode-browser/) e reinicie o OpenCode |
15. Limites e privacidade
- Tudo local: a extensão fala com
127.0.0.1; o plugin escuta apenas em loopback (portas 8799–8802) e exige um “hello” da extensão antes de atender. - O painel é uma visão só: duas janelas abertas mostram a mesma conversa.
- Vínculo conversa↔grupo não sobrevive a fechar o Chrome por completo.
- Até 4 conversas com estado detalhado em memória ao mesmo tempo.
- Uma resposta em streaming por vez, mas várias conversas podem executar em paralelo.
- Grupo automático cria uma aba em branco por conversa; grupos de conversas apagadas fora da extensão só são liberados no próximo início do navegador.
- O card de permissão é modal: enquanto houver um pedido aberto, o painel fica coberto — responda (ou use Esc) para continuar.
16. Referência rápida
Caminhos
| O quê | Onde |
|---|---|
| Build da extensão | dist/ (é a pasta a carregar no Chrome) |
| Plugin e agente | ~/.config/opencode/plugins/ |
| Conversas do navegador | ~/.opencode-browser-extensions |
| Capturas do agente | ~/.cache/opencode-browser/capturas/ |
| Token e porta do relay | $XDG_RUNTIME_DIR/opencode-browser/relay.json ou ~/.cache/opencode-browser/relay.json |
Comandos úteis
npm run build # gera dist/
npm run install:plugin # copia plugin e agente
opencode service restart # recarrega plugin e agente
opencode pair # gera o link de pareamento
curl http://127.0.0.1:8799/health
Pedidos que funcionam bem
- “Abra example.com e me diga o título da página.”
- “Leia a página atual e liste os links do menu.”
- “Preencha o formulário de contato com dados de teste e me mostre um print antes de enviar.”
- “Investigue por que o botão Salvar não responde: veja o console e a rede.”
- “Pesquise o preço deste produto em três lojas e monte uma tabela.”
- “Grave um GIF mostrando o passo a passo do login.”