OpenCode - Guia do Usuário - Documentação Integração Prefeitura do Rio de Janeiro

O OpenCode é um agente de IA no terminal que lê o contexto do seu repositório e executa tarefas de desenvolvimento de ponta a ponta — escreve, edita, testa e refatora código com base em instruções em linguagem natural. Na IplanRio, o OpenCode é configurado via Bifrost, nosso proxy centralizado de IA. Você não gerencia credenciais de cloud: basta sua Virtual Key.

Como Solicitar Acesso

Acesse o canal #peça-permissão no Discord da IplanRio
Envie sua solicitação:

🤖 Solicitação de Acesso - OpenCode

Nome: [Seu nome completo]
Email: [seu.email@prefeitura.rio]
Área/Projeto: [Ex: Escritório de Dados, SMS, etc.]
Justificativa: [Para que você pretende usar]

Aguarde aprovação da equipe de IA
Receba por email sua Virtual Key e os comandos de instalação

Limites de Uso

O acesso ao Bifrost é compartilhado e possui limites diários de tokens por Virtual Key. Ao atingir o limite, as requisições retornam erro até a renovação automática no dia seguinte. Se precisar de mais cota antes da renovação, solicite no canal #peça-permissão do Discord da IplanRio informando sua necessidade.

Use modelos mais leves para tarefas simples — isso preserva cota para quando você precisar de mais capacidade.

Instalação Automática

Linux / macOS / WSL
Windows (PowerShell)

curl -fsSL https://storage.googleapis.com/iplanrio-opencode/install.sh | bash -s -- [sua-virtual-key]

O script detecta seu sistema, instala o OpenCode e cria ~/.config/opencode/config.json com o Bifrost configurado.

& ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/install.ps1'))) -VirtualKey '[sua-virtual-key]'

Instala o binário em %LOCALAPPDATA%\Programs\opencode e cria %APPDATA%\opencode\config.json.

A Virtual Key é pessoal e intransferível. Re-executar o script atualiza providers e modelos preservando todas as outras configurações existentes.

Atualizar a configuração

Re-execute o script a qualquer momento para aplicar novos providers ou modelos. A Virtual Key existente é reutilizada automaticamente — não é obrigatório passá-la novamente. Mesmo assim, passe-a explicitamente para evitar ambiguidades:

Linux / macOS / WSL
Windows (PowerShell)

# Sem a chave — usa a chave já configurada
curl -fsSL https://storage.googleapis.com/iplanrio-opencode/install.sh | bash

# Recomendado: passe a chave explicitamente
curl -fsSL https://storage.googleapis.com/iplanrio-opencode/install.sh | bash -s -- [sua-virtual-key]

# Sem a chave — usa a chave já configurada
& ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/install.ps1')))

# Recomendado: passe a chave explicitamente
& ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/install.ps1'))) -VirtualKey '[sua-virtual-key]'

Migrando do Claude Code

Quem usou o Claude Code antes do OpenCode recebeu uma chave de service account do GCP e variáveis de ambiente apontando direto para o Google Vertex AI. A IplanRio removeu essas service accounts na migração para o Bifrost, e a chave órfã agora gera o erro:

invalid_grant: Invalid grant: account not found

O OpenCode usa apenas o config.json + Virtual Key. As variáveis antigas só atrapalham e precisam ser removidas.

O script de instalação remove essas variáveis automaticamente, criando backup antes. Para resolver, basta reexecutá-lo. As instruções abaixo são para quem configurou manualmente ou prefere limpar à mão.

Variáveis a remover

CLAUDE_CODE_USE_VERTEX
ANTHROPIC_VERTEX_PROJECT_ID
ANTHROPIC_VERTEX_REGION
GOOGLE_APPLICATION_CREDENTIALS
GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_LOCATION (quando setadas para o Claude Code)

Limpeza manual

Linux / macOS / WSL
Windows (PowerShell)

Remova ou comente as linhas export acima no seu profile (~/.zshrc, ~/.bashrc ou equivalente), depois recarregue o shell:

# Desativar na sessão atual
unset CLAUDE_CODE_USE_VERTEX ANTHROPIC_VERTEX_PROJECT_ID ANTHROPIC_VERTEX_REGION \
      GOOGLE_APPLICATION_CREDENTIALS GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION \
      GCP_PROJECT GCLOUD_PROJECT

# Recarregar o profile
source ~/.zshrc   # ou ~/.bashrc

foreach ($v in 'CLAUDE_CODE_USE_VERTEX','ANTHROPIC_VERTEX_PROJECT_ID','ANTHROPIC_VERTEX_REGION','GOOGLE_APPLICATION_CREDENTIALS','GOOGLE_CLOUD_PROJECT','GOOGLE_CLOUD_LOCATION','GCP_PROJECT','GCLOUD_PROJECT') {
    [Environment]::SetEnvironmentVariable($v, $null, 'User')
    Remove-Item "Env:$v" -ErrorAction SilentlyContinue
}

Reabra o terminal em seguida.

O Claude Code não faz mais parte do fluxo da IplanRio — use o OpenCode. Se você rodava claude por hábito, passe a rodar opencode.

Configuração Manual

Para quem prefere configurar manualmente, usa o OpenCode Desktop, ou quer adicionar o Bifrost a uma instalação existente.

Instalar o OpenCode

macOS (Homebrew)
Linux
Windows
Desktop

brew install anomalyco/tap/opencode

curl -fsSL https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-x64.tar.gz \
  | tar -xz -C /usr/local/bin opencode
chmod +x /usr/local/bin/opencode

Para ARM64 substitua x64 por arm64.

Baixe o .zip em releases e adicione a pasta ao PATH.

Sistema	Arquivo
macOS Apple Silicon	`opencode-desktop-mac-arm64.dmg`
macOS Intel	`opencode-desktop-mac-x64.dmg`
Windows	`opencode-desktop-win-x64.exe`
Linux (deb)	`opencode-desktop-linux-amd64.deb`

Baixe em releases.

Arquivo de configuração

Crie ou edite o arquivo abaixo com sua Virtual Key:

Linux / macOS — ~/.config/opencode/config.json
Windows — %APPDATA%\opencode\config.json
Desktop

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "name": "Bifrost IplanRio (Anthropic)",
      "options": {
        "apiKey": "[sua-virtual-key]",
        "baseURL": "https://bifrost.iplan.dados.rio/anthropic/v1"
      },
      "models": {
        "claude-haiku-4-5": {
          "limit": {
            "context": 200000,
            "output": 64000
          }
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "name": "Bifrost IplanRio (Anthropic)",
      "options": {
        "apiKey": "[sua-virtual-key]",
        "baseURL": "https://bifrost.iplan.dados.rio/anthropic/v1"
      },
      "models": {
        "claude-haiku-4-5": {
          "limit": {
            "context": 200000,
            "output": 64000
          }
        }
      }
    }
  }
}

Vá em Settings → Providers → Add Provider:

Campo	Valor
Provider	Anthropic
Name	Bifrost IplanRio (Anthropic)
API Key	`[sua-virtual-key]`
Base URL	`https://bifrost.iplan.dados.rio/anthropic/v1`

Defina o modelo padrão como claude-haiku-4-5.

O exemplo acima habilita apenas o Claude. Para os demais modelos (Gemini, Kimi, GLM), adicione o provider bifrost-google ao mesmo config.json. O script de instalação escreve este bloco automaticamente.

Adicionar Gemini, Kimi e GLM (provider bifrost-google)

{
  "provider": {
    "bifrost-google": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Bifrost (Google)",
      "options": {
        "apiKey": "[sua-virtual-key]",
        "baseURL": "https://bifrost.iplan.dados.rio/openai/v1"
      },
      "models": {
        "gemini-3.5-flash": {
          "id": "vertex/gemini-3.5-flash",
          "limit": { "context": 200000, "output": 64000 }
        },
        "gemini-3.1-pro-preview": {
          "id": "vertex/gemini-3.1-pro-preview",
          "limit": { "context": 200000, "output": 64000 }
        },
        "kimi-k2-thinking": {
          "id": "vertex/moonshotai/kimi-k2-thinking-maas",
          "limit": { "context": 256000, "output": 64000 }
        },
        "glm-5": {
          "id": "vertex/zai-org/glm-5-maas",
          "limit": { "context": 200000, "output": 64000 }
        }
      }
    }
  }
}

Verificar

opencode --version

Abra o OpenCode e confirme com /status:

> /status
API Provider: Anthropic (Bifrost IplanRio)
Model: claude-haiku-4-5

Como Usar

Início rápido

Execute opencode dentro do diretório do projeto. O agente lê o repositório e fica pronto para instruções:

cd meu-projeto
opencode

Digite qualquer instrução em linguagem natural. O agente lê os arquivos relevantes, propõe e executa edições, roda comandos de build e lint para verificar e itera até concluir.

Comandos internos

Dentro do OpenCode, use / para acessar funções do sistema:

Comando	O que faz
`/status`	Exibe provider, modelo e uso da sessão
`/clear`	Limpa o histórico da conversa atual
`/compact`	Comprime o histórico para economizar contexto
`/help`	Lista todos os comandos disponíveis
`/exit`	Encerra o OpenCode

Modo não-interativo

Ideal para automações e integração com outros comandos:

# Instrução pontual
opencode -p "Explique o que a função calculate_tax faz e seus edge cases"

# Passando arquivo via stdin
opencode -p "Revise este código e aponte problemas" < src/handler.go

# Encadeando com git
git diff HEAD~1 | opencode -p "Resuma as mudanças deste diff em português"

Permissões

Para projetos onde você quer que o agente trabalhe com mais autonomia, sem confirmar cada passo, adicione ao config.json:

{
  "permission": {
    "bash": "allow",
    "edit": "allow",
    "write": "allow",
    "read": "allow"
  }
}

Use permissões abertas apenas em repositórios onde você tem controle total. Em repositórios compartilhados, prefira o modo padrão com confirmação a cada ação.

Modelos Disponíveis e Otimização de Custo

O Bifrost IplanRio dá acesso a múltiplos modelos. Escolha o modelo adequado à tarefa para preservar sua cota diária.

Modelo	Quando usar
`anthropic/claude-haiku-4-5`	Padrão — tarefas do dia a dia, explicar código, commits, perguntas rápidas
`anthropic/claude-sonnet-4-6`	Features complexas, revisões profundas, refatorações grandes
`bifrost-google/gemini-3.5-flash`	Alternativa rápida e econômica para tarefas de baixa complexidade
`bifrost-google/gemini-3.1-pro-preview`	Raciocínio avançado, análise de arquiteturas complexas
`bifrost-google/kimi-k2-thinking`	Problemas que exigem raciocínio profundo passo a passo
`bifrost-google/glm-5`	Alternativa de baixo custo para tarefas gerais

Trocar o modelo na sessão

Dentro do OpenCode, use o seletor de modelo para escolher sem editar o arquivo de configuração.

Definir um modelo padrão diferente

Edite o campo model em ~/.config/opencode/config.json (Linux/macOS) ou %APPDATA%\opencode\config.json (Windows):

{
  "model": "anthropic/claude-sonnet-4-6"
}

O padrão claude-haiku-4-5 cobre bem a maioria das tarefas. Mude para claude-sonnet-4-6 quando precisar de raciocínio mais profundo — desenvolvimento de features complexas, revisões de arquitetura ou refatorações grandes.

Contexto de projeto com AGENTS.md

Crie um AGENTS.md na raiz do repositório para dar contexto permanente ao agente — o OpenCode lê este arquivo automaticamente em toda sessão.

Estrutura recomendada

# [Nome do Projeto]

## Stack
- [Linguagem e versão]
- [Framework principal]
- [Banco de dados / infra]

## Comandos importantes
- `just build` — compila
- `just test` — roda testes
- `just lint` — verifica qualidade

## Estrutura do projeto
[Breve descrição das pastas principais]

## Convenções
[Padrões de código, nomenclatura, commits]

## O que NÃO fazer
[Antipadrões, arquivos que não devem ser alterados]

Exemplos por tipo de repositório IplanRio

API Go (Gin)
Pipeline dbt
Script Python / Prefect

# API [Nome]

## Stack
- Go 1.24 + Gin
- PostgreSQL via Cloud SQL (driver pgx)
- Autenticação via JWT (Keycloak)
- Deploy em GKE

## Comandos
- `just build` — compila o binário
- `just test` — roda testes com cobertura
- `just lint` — golangci-lint
- `just run` — inicia localmente com .env

## Estrutura
- `cmd/` — entrypoints (main.go)
- `internal/handlers/` — handlers HTTP
- `internal/service/` — lógica de negócio
- `internal/repository/` — acesso ao banco

## Convenções
- Handlers retornam apenas HTTP; lógica fica em service/
- Erros sempre propagados com contexto: `fmt.Errorf("...: %w", err)`
- Testes ao lado dos arquivos (`_test.go`)
- Commits em Conventional Commits (feat/fix/chore)

# Pipeline dbt — [Nome]

## Stack
- dbt + BigQuery
- Prefect para orquestração

## Comandos
- `dbt run` — executa os modelos
- `dbt test` — roda os testes
- `dbt docs generate && dbt docs serve` — documentação local

## Estrutura de camadas
- `models/raw_` — dados brutos sem transformação
- `models/int_` — transformações intermediárias
- `models/dim_` / `models/fct_` — marts de consumo

## Convenções de nomenclatura
- Tabelas: `<camada>_<fonte>__<entidade>` (ex: `raw_ergon__servidores`)
- Colunas de data: sufixo `_data` (ex: `data_admissao`)
- IDs externos: sufixo `_id` (ex: `matricula_id`)
- Toda tabela deve ter testes de `not_null` e `unique` na PK

## O que NÃO fazer
- Nunca colocar lógica de negócio em raw_
- Não usar SELECT * em marts

# [Nome do flow] — Prefect

## Stack
- Python 3.12 + uv
- Prefect 3
- BigQuery como destino

## Comandos
- `uv run python flow.py` — executa localmente
- `uv run pytest` — roda testes
- `uv run ruff check .` — lint

## Estrutura
- `flow.py` — definição principal do flow
- `tasks/` — tasks Prefect reutilizáveis
- `utils/` — helpers sem dependência de Prefect

## Convenções
- Tasks são funções puras sempre que possível
- Segredos via `Secret.load("nome-do-secret")`
- Logs com `get_run_logger()`, nunca `print()`
- Type hints obrigatórios em todas as funções

Fluxo de trabalho típico

Desenvolvimento de feature

git checkout -b feat/nova-feature
opencode
# Descreva o que quer construir:
> Implemente o endpoint POST /api/vagas com campos [título, descrição, secretaria],
  validação no padrão dos handlers existentes e persistência no banco.
  Escreva os testes de integração junto.

# O agente lê os handlers existentes, cria o novo, escreve os testes e roda just test

Code review antes do PR

git diff main | opencode -p "
Revise este diff como code reviewer experiente em Go.
Aponte bugs, problemas de segurança, desvios das convenções e melhorias de performance.
Seja direto e específico com número de linha.
"

Depuração de erro

opencode -p "
Estou recebendo este erro em produção:
[cole o stack trace aqui]

Analise o código em internal/service/payment.go e identifique a causa raiz.
"

Escrita de commits

git diff --staged | opencode -p "
Escreva uma mensagem de commit em Conventional Commits para este diff.
Seja específico sobre o que mudou e por quê.
"

Exemplos no contexto IplanRio

# Revisar modelo dbt antes do PR
opencode -p "Revise models/fct_servidores.sql: nomenclatura, testes ausentes e otimizações"

# Criar handler Go seguindo padrão do projeto
opencode -p "Crie GET /api/cidadao/:cpf seguindo o padrão de internal/handlers/servidor.go"

# Otimizar query BigQuery lenta
opencode -p "Esta query demora 45s. Reescreva usando particionamento e clustering adequados"

# Documentar endpoints
opencode -p "Gere a spec OpenAPI 3.0 para todos os endpoints em internal/handlers/"

# Migração de dados
opencode -p "Escreva script Python que migra ergon.servidores para o formato RMI com validação e relatório de erros"

Recursos

Documentação oficial do OpenCode
Repositório OpenCode
Releases e changelogs
Boas práticas de agentes de código — material conceitual, válido para qualquer agente de código

Diagnóstico Automático

Se algo não estiver funcionando, rode o script de diagnóstico. Ele usa um modelo gratuito do OpenCode — não precisa de Virtual Key configurada — e verifica, identifica e corrige os problemas sozinho.

Linux / macOS / WSL
Windows (PowerShell)

curl -fsSL https://storage.googleapis.com/iplanrio-opencode/doctor.sh | bash

& ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/doctor.ps1')))

O agente verifica e corrige automaticamente:

Binário opencode no PATH
config.json — model, providers Anthropic e Google, estrutura de modelos
opencode.json — small_model
Conectividade com o Bifrost
Presença e validade da Virtual Key

Se a Virtual Key estiver ausente ou inválida, o agente instrui a solicitá-la no canal #peça-permissão do Discord da IplanRio.

Troubleshooting

invalid_grant: Invalid grant: account not found Variáveis de ambiente do antigo setup Claude Code + Vertex AI continuam ativas no seu shell. Reexecute o script de instalação — ele remove essas variáveis automaticamente, com backup — ou siga a limpeza manual. opencode: command not found após instalação no Linux O binário foi instalado em ~/.local/bin. Adicione ao PATH:

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # ou ~/.zshrc

401 Unauthorized ao usar o OpenCode A Virtual Key expirou ou foi revogada. Solicite uma nova no #peça-permissão. Erro de conexão com o Bifrost O Bifrost (bifrost.iplan.dados.rio) requer HTTPS na porta 443. Verifique sua conexão ou VPN. Modelo errado aparecendo Confirme que "model": "anthropic/claude-haiku-4-5" está no nível raiz do config.json. Reexecute o script de instalação se necessário. Agente editando arquivos que não deveria Remova o bloco "permission" do config.json para voltar ao modo com confirmação a cada ação.

​Como Solicitar Acesso

​Limites de Uso

​Instalação Automática

​Atualizar a configuração

​Migrando do Claude Code

​Variáveis a remover

​Limpeza manual

​Configuração Manual

​Instalar o OpenCode

​Arquivo de configuração

​Verificar

​Como Usar

​Início rápido

​Comandos internos

​Modo não-interativo

​Permissões

​Modelos Disponíveis e Otimização de Custo

​Trocar o modelo na sessão

​Definir um modelo padrão diferente

​Contexto de projeto com AGENTS.md

​Estrutura recomendada

​Exemplos por tipo de repositório IplanRio

​Fluxo de trabalho típico

​Desenvolvimento de feature

​Code review antes do PR

​Depuração de erro

​Escrita de commits

​Exemplos no contexto IplanRio

​Recursos

​Diagnóstico Automático

​Troubleshooting

Como Solicitar Acesso

Limites de Uso

Instalação Automática

Atualizar a configuração

Migrando do Claude Code

Variáveis a remover

Limpeza manual

Configuração Manual

Instalar o OpenCode

Arquivo de configuração

Verificar

Como Usar

Início rápido

Comandos internos

Modo não-interativo

Permissões

Modelos Disponíveis e Otimização de Custo

Trocar o modelo na sessão

Definir um modelo padrão diferente

Contexto de projeto com AGENTS.md

Estrutura recomendada

Exemplos por tipo de repositório IplanRio

Fluxo de trabalho típico

Desenvolvimento de feature

Code review antes do PR

Depuração de erro

Escrita de commits

Exemplos no contexto IplanRio

Recursos

Diagnóstico Automático

Troubleshooting