Conectar ao OpenCode

Use OpenCode com modelos, ferramentas MCP e habilidades através do Unity Gateway. A CLI do Gateway Unity (ug) gerencia o login e configuração do workspace, ou você pode configurar a conexão manualmente.

Antes de começar

Você precisa da URL do seu espaço de trabalho do Azure Databricks e acesso aos modelos, serviços MCP e habilidades que deseja usar. Para configuração manual, instale o OpenCode e tenha um token de acesso pessoal do Azure Databricks.

Para configuração manual, substitua <workspace-hostname> pelo nome de host do seu workspace Azure Databricks e <databricks-pat> pelo seu token. Use os nomes completos dos modelos disponíveis no seu espaço de trabalho e mescle as entradas de configuração aos arquivos existentes, preservando as configurações não relacionadas.

Se seu administrador já configurou seu dispositivo, siga as instruções de configuração da sua organização.

Use o CLI do Unity Gateway

Instale ug, então execute este comando a partir do diretório do seu projeto:

ug opencode

Selecione seu espaço de trabalho e faça login quando solicitado. O comando abre o OpenCode com seus modelos de gateway configurados. Comece a programar, ou insira /models para escolher outro modelo configurado.

Configure os modelos manualmente

Instale OpenCode, depois mescle esta configuração em ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "databricks-anthropic/system.ai.claude-sonnet-4-6",
  "provider": {
    "databricks-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://<workspace-hostname>/ai-gateway/anthropic/v1",
        "apiKey": "<databricks-pat>",
        "headers": {
          "Authorization": "Bearer <databricks-pat>"
        }
      },
      "models": {
        "system.ai.claude-sonnet-4-6": {
          "options": {
            "toolStreaming": false
          }
        }
      }
    }
  }
}

Substitua o nome do modelo em ambos os locais se você escolher outro modelo Claude. Mantenha toolStreaming: false para compatibilidade com o gateway. Inicie o OpenCode com opencode.

Para modelos Gemini, adicione um provedor separado usando @ai-sdk/google, URL base https://<workspace-hostname>/ai-gateway/gemini/v1beta, os mesmos campos de autenticação e os nomes dos seus modelos do Gemini. Veja a documentação do provedor do OpenCode.

Para reduzir o custo por token para tarefas rotineiras, selecione um modelo código aberto, como system.ai.glm-5-2 o seu modelo. Veja Gastos do Controle.

Adicionar ferramentas MCP

Use o CLI do Unity Gateway

Execute:

ug mcp add --agents opencode

Selecione seus serviços e reinicie com ug opencode.

Configure os serviços MCP manualmente

Misture esta entrada em ~/.config/opencode/opencode.json:

{
  "mcp": {
    "dbsql": {
      "type": "remote",
      "url": "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <databricks-pat>"
      }
    }
  }
}

Para outro serviço, mude o nome do servidor e substitua system.ai.dbsql pelo nome do Catálogo Unity em três partes. Reinicie o OpenCode e peça para ele usar uma ferramenta conectada. Veja a documentação MCP do OpenCode.

ug opencode usa ~/.ucode/opencode-xdg/opencode/opencode.json. Use esse arquivo para entradas manuais de MCP ao iniciar por meio de ug.

Adicionar habilidades

Use o CLI do Unity Gateway

Baixe habilidades publicadas:

ug skills add

Escolha suas habilidades e depois reinicie o OpenCode. Ele lê os downloads de ~/.agents/skills/ e carrega habilidades relevantes enquanto você trabalha.

Configurar habilidades manualmente

Para os arquivos que você já possui, coloque cada pasta completa da skill em ~/.agents/skills/ ou em .opencode/skills/ do seu projeto. Veja a documentação de habilidades do OpenCode.

Para acessar o registro de habilidades publicado via MCP, adicione um segundo servidor usando o exemplo MCP acima, nomeie-o databricks-skill-registry, e defina url para https://<workspace-hostname>/ai-gateway/skills/. Mantenha a barra final, o cabeçalho Bearer e oauth: false. Peça ao agente para usar uma habilidade usando seu nome completo.

As habilidades do Gateway Unity estão em Beta. Veja Habilidades de Governar para habilitação e permissões.

Solução de problemas

Uma solicitação de modelo falha: Verifique a URL do gateway, expiração do token, nome do modelo e permissões.

Um servidor MCP está faltando: Reinicie o agente. Se você o configurou com ug, inicie-o com ug opencode para que ele use as mesmas configurações. Para configuração manual, verifique ~/.config/opencode/opencode.json e coloque a ficha de portador.

Uma habilidade baixada está faltando: Verifique se a pasta completa dela contém SKILL.md em um diretório compatível. Execute novamente ug skills add com as mesmas opções para atualizar as habilidades baixadas.

Para problemas de login no workspace ou configuração de ug, execute ug doctor.

Próximas Etapas 

  • Last updated on