opencode browser Markdown

Instalação e conexão

1. O que você precisa

ItemVersão mínimaObservação
Chrome ou Chromium116A extensão usa o painel lateral (side panel)
Node.js20Usado só para gerar o build e instalar o plugin
npmvem com o Node—
OpenCode Terminalv2É 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.

  1. Abra chrome://extensions e ative o modo desenvolvedor;
  2. clique em Carregar sem compactação e selecione a pasta extension/ que veio no ZIP;
  3. no terminal, dentro da pasta extraída do pacote, execute:
node scripts/install-plugin.mjs
opencode service restart
  1. abra o side panel e clique em Conectar; rode opencode pair no 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:

  1. confere se existem Node.js 20+, npm e OpenCode v2+ (para com uma mensagem clara se faltar algum);
  2. instala as dependências (npm install);
  3. gera o build da extensão (npm run build) em dist/;
  4. copia o plugin e o template do agente para a pasta de plugins do OpenCode (npm run install:plugin);
  5. reinicia o serviço do OpenCode (opencode service restart);
  6. 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.sh reinicia 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:

  1. abra chrome://extensions;
  2. ligue o modo desenvolvedor (canto superior direito);
  3. clique em Carregar sem compactação e escolha a pasta dist/ do projeto (não a raiz);
  4. 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:

  1. abra chrome://extensions;
  2. 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)

  1. Abra o painel: clique no ícone da extensão, ou use o atalho Ctrl+Shift+O (Command+Shift+O no macOS).
  2. Na primeira vez aparece a tela “Conecte o navegador ao OpenCode da sua máquina”.
  3. No terminal, rode:

bash opencode pair

  1. Copie o link exibido (é o mesmo que abre a interface web do OpenCode) e cole no campo “Link do opencode pair”.
  2. 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

MensagemO 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:

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

StatusSignificadoO que fazer
“Plugin conectado”Tudo certo—
“Plugin não encontrado — instale o plugin e reinicie o OpenCode”O plugin não foi carregadonpm run install:plugin + opencode service restart
“Plugin recusou a conexão — confira o ID da extensão”A extensão não é a esperadaRecarregue a extensão ou ajuste OPENCODE_BROWSER_EXTENSION_ID
“Plugin parou de responder — reinicie o OpenCode”O plugin travou ou o worker dormiuReinicie o OpenCode
“Plugin desconectado — reinicie o OpenCode para reconectar”O socket caiuReinicie 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.