OpenCode Claude Agent: configuração, limites da assinatura e regras

Use o provedor Claude Agent do OpenCode por meio da sua instalação local do Claude Code. Instale as duas ferramentas, execute claude auth login e escolha Claude Agent em /connect. Escolha uma chave de API se sua equipe precisa de autenticação documentada para aplicativos de terceiros.

Em 2026-11-05, o OpenCode oferece um guia específico de configuração do Claude Agent. O provedor usa a autenticação ativa do Claude Code. Portanto, escolhê-lo não seleciona automaticamente a cobrança pela assinatura.

O que muda com o Claude Agent?

Com o Claude Agent, o OpenCode fornece a interface e executa as ferramentas. O Claude Code cuida da comunicação com o modelo. O OpenCode chama o executável claude instalado na sua máquina por meio do Claude Agent SDK da Anthropic.

O provedor integrado chegou no OpenCode v2.2.3. A versão v2.2.4 incluiu a configuração guiada no seletor de provedores da interface do aplicativo. Você não precisa de um plugin separado para usar a assinatura.

Pela arquitetura do provedor, o OpenCode executa operações com arquivos e comandos do shell, além de controlar as permissões. As ferramentas integradas do Claude Code ficam desativadas.

O OpenCode também compacta o contexto e executa subagentes, conforme seu guia atual do Claude Agent. A integração não carrega as configurações nativas, os hooks, os servidores MCP, as skills nem a memória do Claude Code.

Por isso, as instruções e ferramentas do OpenCode determinam como o projeto será tratado. Revise-as antes de autorizar edições ou a execução de comandos. Se seu fluxo depende dos hooks nativos ou das equipes de agentes do Claude Code, continue nele até ter uma alternativa equivalente.

A principal razão para testar esse provedor é manter a interface do OpenCode e seu fluxo de troca de modelos. Instalá-lo não reproduz toda a experiência do Claude Code.

Instale e conecte o Claude Agent

Use o OpenCode V2 e o Claude Code na mesma máquina em que roda o servidor do OpenCode. Esse provedor não está disponível nos espaços de trabalho remotos do OpenCode.

Para usar a assinatura, este procedimento pressupõe um plano individual Pro, Max ou Ultra ativo.

Instale as versões corretas

Instale o OpenCode V2, com v2.2.3 como versão mínima para esse recurso. Para a configuração guiada no aplicativo, use v2.2.4 ou posterior.

Os comandos abaixo são para Bash no macOS, Linux ou WSL. Eles seguem as instruções de instalação do OpenCode V2 e as instruções de instalação do Claude Code:

curl -fsSL https://opencode.ai/v2/install | bash
curl -fsSL https://claude.ai/install.sh | bash

Abra um novo terminal e confira as duas versões:

opencode --version
claude --version

O Claude Code precisa ser 2.1.248 ou posterior, conforme a verificação de versão do provedor. Atualize instalações nativas antigas com claude update. Se usou um gerenciador de pacotes, atualize por ele.

Se você já usa o V1, leia primeiro o guia de migração para o V2. As duas versões usam o comando opencode e os mesmos locais para arquivos de configuração.

A instalação não inclui uso dos modelos. Se ainda não escolheu uma forma de acesso, veja instalação, assinatura e acesso por API no Claude Code.

Faça login pelo próprio Claude Code. Se pretende usar a cota da assinatura, selecione sua conta com essa assinatura:

claude auth login
claude auth status --text

Confirme se o status mostra a conta e o método de autenticação desejados. A referência da CLI diferencia esse fluxo de claude auth login --console, que seleciona a cobrança pela API do Console.

Verifique as credenciais herdadas antes de testar a assinatura. A Anthropic documenta que chaves de API no ambiente podem ter prioridade sobre a autenticação por assinatura. Se uma chave antiga estiver definida por engano no seu shell, remova essa variável:

unset ANTHROPIC_API_KEY
claude auth status --text

Verifique também se ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL ou configurações de provedores de nuvem foram definidas por engano. Consulte a ordem de prioridade da autenticação. O login por assinatura não tem prioridade sobre todas as outras credenciais.

Na configuração do OpenCode, procure apiKey, authToken ou baseURL em providers.claude-agent.settings. Confira também os valores definidos no nível do modelo. A implementação da conexão aplica essas configurações depois das variáveis de ambiente do servidor.

Conecte o provedor e teste uma requisição real

Para a primeira verificação, inicie um servidor privado do OpenCode:

opencode --standalone

O modo standalone usa um servidor privado. Esse servidor usa o ambiente do shell atual, sem depender do serviço compartilhado já em execução. As configurações explícitas continuam tendo prioridade.

Dentro do OpenCode, execute /connect e selecione Claude Agent. Depois, execute /models e escolha um dos modelos informados pelo Claude Code. As referências de modelos do provedor podem usar aliases como claude-agent/opus; não presuma que correspondam aos IDs da API direta.

Na interface do aplicativo, a configuração guiada oferece instalação, login, verificação da conexão e recuperação após falhas. Uma verificação bem-sucedida leva à seleção do modelo. Esses controles do aplicativo são separados das instruções de terminal acima.

Em um repositório que contenha README.md, envie:

Read README.md and summarize the project in three sentences. Do not modify files or run shell commands.

O pedido solicita um resumo do projeto em três frases, sem editar arquivos nem executar comandos do shell. Confira se o OpenCode mostra uma chamada da ferramenta de leitura de arquivo e uma resposta pertinente. Isso verifica o acesso ao modelo e a devolução do resultado da ferramenta.

Uma lista de modelos preenchida não basta: a verificação de conexão não envia um prompt ao modelo.

Defina OPENCODE_CLAUDE_PATH se o executável não for encontrado

Se o PATH do servidor não localizar a instalação desejada, indique o caminho do executável do Claude Code. Primeiro, confirme se command -v claude localiza o executável correto no terminal.

Para outra verificação com um servidor privado:

export OPENCODE_CLAUDE_PATH="$(command -v claude)"
opencode --standalone

Para o serviço compartilhado em segundo plano, use o ambiente gerenciado pelo serviço:

opencode service set env OPENCODE_CLAUDE_PATH "$(command -v claude)"

Alterar o ambiente do serviço interrompe o serviço em execução. O próximo comando que precisar do servidor local iniciará o serviço com o novo valor. Conecte o Claude Agent novamente e repita a pequena requisição.

As instruções sobre o ambiente do servidor explicam por que alterar apenas o terminal do cliente pode não bastar.

Qual cota de uso o Claude Agent utiliza?

Planeje o uso conforme a credencial ativa do Claude Code. Com autenticação por assinatura, considere as requisições do Claude Agent parte da sua cota atual do Claude.

O OpenCode documenta que a assinatura cobre esse acesso. A Anthropic confirma que Claude e Claude Code compartilham os limites de uso do plano. Essas duas regras indicam que trocar de interface não cria uma segunda cota.

Separe os três casos:

Autenticação do Claude Code	Origem da cobrança
Assinatura Claude	Cota incluída no plano, sujeita aos limites e a eventuais créditos de uso pagos que você tenha ativado
Conta da API da Anthropic ou conta de nuvem compatível	Cobrança e limites da API dessa conta
Gateway personalizado	Regras de cobrança da conta no gateway

Uma estimativa de custo vazia não comprova uso gratuito. A lógica de custos do provedor também omite estimativas para URLs base personalizadas.

Confira o consumo e os horários de renovação dos limites em Claude Settings > Usage. A visualização nativa de /usage do Claude Code não está disponível dentro do OpenCode. Confira também os créditos de uso pagos: ativá-los pode gerar cobranças adicionais depois do limite incluído.

Para escolher a forma de acesso, compare assinaturas Claude e cobrança por API.

O que dizem as regras de uso?

Considere a permissão específica para cada implementação e forma de uso. Usar o SDK oficial não concede automaticamente acesso a credenciais de assinatura a qualquer aplicativo de terceiros.

Os três documentos tratam de situações diferentes:

Fonte oficial	O que diz	O que isso significa para esta configuração
Página legada de provedores do OpenCode	Alerta que a Anthropic proíbe plugins de assinatura Pro/Max e informa que o OpenCode deixou de incluí-los em 1.3.0.	O aviso sobre os plugins antigos não descreve a implementação do novo provedor V2.
Visão geral do Anthropic Agent SDK	Desenvolvedores de terceiros precisam de aprovação prévia para oferecer login de contas Claude ou seus limites de uso em seus produtos.	Chamar o SDK não basta para comprovar permissão.
Regras legais e de conformidade do Claude Code	Restringe a intermediação de credenciais por terceiros, mas permite ao usuário entrar no binário não modificado do Claude Code com sua assinatura.	Mantenha o fluxo nativo de login; não estenda essa exceção ao compartilhamento de credenciais ou a um novo serviço comercial.

Há também uma declaração sobre essa implementação. Em 2026-10-30, Tarquinen, autor do PR, afirmou que a Anthropic havia dado permissão e declarou que a integração respeitava os termos. A afirmação é de um colaborador do projeto OpenCode. Não é um documento da Anthropic que delimite o alcance da aprovação.

Para uso pessoal, mantenha seu próprio login na instalação não modificada do Claude Code. Não exporte tokens de sessão para outro plugin. Para adoção em uma empresa ou integração em um produto, obtenha confirmação para esse cenário ou use o acesso documentado por chave de API.

A autenticação bem-sucedida confirma que uma requisição funciona. Ela não resolve a aplicação dos termos contratuais a todas as formas de implantação.

Corrija a falha que está ocorrendo

Escolha a verificação conforme o sintoma e repita a requisição curta de leitura do arquivo.

Sintoma	Verificação e próximo passo
`Claude Code is not installed`	Instale o Claude Code na máquina do servidor do OpenCode ou defina `OPENCODE_CLAUDE_PATH` nesse servidor. Conecte novamente.
`Claude Code is not logged in`	Execute `claude auth login` nessa máquina com o mesmo usuário. Confira o status e conecte novamente.
O erro informa `2.1.248 or later is required`	Atualize o Claude Code e confirme a versão do executável antes de tentar novamente.
Conectado, mas sem modelos ou sem uma resposta válida	Confira o executável e o login no servidor. Conecte novamente; descobrir modelos não comprova que as requisições funcionam.

Os erros de conexão documentados cobrem os casos de instalação ausente e falta de login. Se a requisição atingir um limite do plano, confira a página de uso da conta. Reconectar não renova a cota.

Quando usar uma chave de API?

Use uma chave de API quando precisar de cobrança separada ou de um servidor sem Claude Code local. Também prefira esse caminho quando precisar da autenticação documentada para produtos de terceiros. Mantenha custos e limites separados da assinatura Claude.

Acesso direto à API da Anthropic

Crie sua própria chave no Claude Console. No OpenCode, selecione Anthropic em /connect e use a autenticação com chave de API.

Este comando equivalente de autenticação no V2 solicita a chave de forma interativa:

opencode auth login anthropic --method key
opencode run --standalone --model anthropic/claude-sonnet-5-5 "Reply with only: OK"

Espere uma resposta OK e confirme o uso na conta de API desejada. Se a conta ou o modelo estiver incorreto, ajuste a seleção em /connect ou /models antes de tentar novamente.

Acesso por uma API compatível com OpenAI

Em 2026-11-05, o BetterToken também lista claude-sonnet-5-5 e claude-opus-5-5. A integração documentada com o OpenCode usa uma API compatível com OpenAI e sua própria chave BetterToken. Esse acesso à API é cobrado separadamente.

Crie uma chave no seu painel. Para uma nova configuração nativa do V2, incorpore este provedor ao opencode.jsonc do projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "bettertoken": {
      "name": "BetterToken",
      "env": ["BETTERTOKEN_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Claude Sonnet 5.5"
        }
      }
    }
  }
}

O exemplo segue o formato nativo de provedores personalizados do V2. Ele usa providers, package e settings; não misture campos do V1 dentro dessa entrada de provedor.

Digite a chave sem exibi-la e execute a verificação no mesmo terminal Bash:

read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
opencode run --standalone --model bettertoken/claude-sonnet-5-5 "Reply with only: OK"

Espere uma resposta normal contendo OK. Depois, confira a requisição e a cobrança no painel. Se já salvou uma conta BetterToken no OpenCode, confira qual está ativa: contas salvas têm prioridade sobre conexões definidas por variáveis de ambiente.

Consulte os preços atuais antes de uma tarefa maior. Esse acesso por API não inclui uma assinatura Claude nem autoriza outras integrações baseadas no login da assinatura.