Instalação e conexão
1. O que você precisa
| Item | Versão mínima | Observação |
|---|---|---|
| Chrome ou Chromium | 116 | A extensão usa o painel lateral (side panel) |
| Node.js | 20 | Usado só para gerar o build e instalar o plugin |
| npm | vem com o Node | — |
| OpenCode Terminal | v2 | É quem roda os modelos e as conversas |
Os modelos são os mesmos que você já usa no OpenCode: se o seu OpenCode funciona no terminal, a extensão funciona.
2. Instalar a extensão
2.1 Pelo pacote pronto (recomendado)
Baixe o ZIP da última release e extraia os arquivos. O pacote inclui a extensão compilada, o plugin e o instalador do plugin; não é necessário rodar npm install ou compilar o projeto.
- Abra
chrome://extensionse ative o modo desenvolvedor; - clique em Carregar sem compactação e selecione a pasta
extension/que veio no ZIP; - no terminal, dentro da pasta extraída do pacote, execute:
node scripts/install-plugin.mjs
opencode service restart
- abra o side panel e clique em Conectar; rode
opencode pairno terminal e cole o link exibido no painel.
2.2 Pelo script do projeto
Na pasta do projeto:
./scripts/install.sh # Linux e macOS
.\scripts\install.ps1 # Windows (PowerShell 5.1+)
O script, nesta ordem:
- confere se existem Node.js 20+, npm e OpenCode v2+ (para com uma mensagem clara se faltar algum);
- instala as dependências (
npm install); - gera o build da extensão (
npm run build) emdist/; - copia o plugin e o template do agente para a pasta de plugins do OpenCode (
npm run install:plugin); - reinicia o serviço do OpenCode (
opencode service restart); - espera o plugin responder em
http://127.0.0.1:8799/health.
Se o passo 6 falhar, o próprio script avisa: abra o painel da extensão e verifique.
O
install.shreinicia o serviço do OpenCode. Se você estiver usando o OpenCode em um terminal, a sessão atual cai por alguns segundos e reconecta — não é erro.
2.3 Manual
npm install
npm run build
npm run install:plugin
opencode service restart
Depois, no Chrome:
- abra
chrome://extensions; - ligue o modo desenvolvedor (canto superior direito);
- clique em Carregar sem compactação e escolha a pasta
dist/do projeto (não a raiz); - o ícone do OpenCode Browser aparece na barra.
2.4 Depois de atualizar o código
O Chrome mantém o service worker em cache. Sempre que você rodar npm run build de novo:
- abra
chrome://extensions; - clique em Recarregar no cartão da extensão.
Sem esse passo, o comportamento antigo continua no ar mesmo com o código novo.
3. Conectar a extensão ao OpenCode (pareamento)
- Abra o painel: clique no ícone da extensão, ou use o atalho Ctrl+Shift+O (Command+Shift+O no macOS).
- Na primeira vez aparece a tela “Conecte o navegador ao OpenCode da sua máquina”.
- No terminal, rode:
bash opencode pair
- Copie o link exibido (é o mesmo que abre a interface web do OpenCode) e cole no campo “Link do
opencode pair”. - Clique em “Conectar ao OpenCode”. Ao terminar aparece o aviso “Conectado ao OpenCode.”
O link é de uso único e expira em 5 minutos. Se expirar, rode opencode pair de novo. O token anterior continua válido até você desconectar.
Se o pareamento falhar
| Mensagem | O que fazer |
|---|---|
“Link inválido. Cole o link completo exibido por opencode pair.” | Copie o link inteiro, sem cortar o código final |
| “O link precisa começar com http:// ou https://.” | Você colou só o código; cole a URL completa |
| “O link não contém /auth/connect/<código>.” | Não é um link de pareamento |
| “Não foi possível falar com o OpenCode em … Ele está rodando?” | O servidor não está no ar: rode opencode serve |
“Link expirado ou já usado. Rode opencode pair novamente.” | Gere um link novo |
| “O servidor não devolveu um token de sessão.” | Versão do OpenCode incompatível: atualize para a v2 |
4. Instalar o plugin de ferramentas
O chat funciona só com a API — para o agente controlar o Chrome, ele precisa do plugin:
npm run install:plugin
opencode service restart
O comando copia, para a pasta de plugins do OpenCode:
browser-relay.ts— o servidor que expõe as ferramentas do navegador;opencode-browser.agent.md— o template do agenteopencode-browser.
e cria a pasta padrão das conversas do navegador (~/.opencode-browser-extensions).
Confira se está tudo certo:
curl http://127.0.0.1:8799/health
No painel, o rodapé do composer mostra “ferramentas conectadas” quando o plugin está ativo.
Se o plugin não conectar
| Status | Significado | O que fazer |
|---|---|---|
| “Plugin conectado” | Tudo certo | — |
| “Plugin não encontrado — instale o plugin e reinicie o OpenCode” | O plugin não foi carregado | npm run install:plugin + opencode service restart |
| “Plugin recusou a conexão — confira o ID da extensão” | A extensão não é a esperada | Recarregue a extensão ou ajuste OPENCODE_BROWSER_EXTENSION_ID |
| “Plugin parou de responder — reinicie o OpenCode” | O plugin travou ou o worker dormiu | Reinicie o OpenCode |
| “Plugin desconectado — reinicie o OpenCode para reconectar” | O socket caiu | Reinicie o OpenCode ou use Reconectar plugin nas configurações |
Mantenha uma única cópia do plugin na pasta de plugins. Duas cópias registram o mesmo plugin e uma delas falha.