Ligar OpenCode

Use OpenCode com modelos, ferramentas MCP e competências através do Unity Gateway. A CLI do Unity Gateway (ug) trata do início de sessão e da configuração do espaço de trabalho, ou pode configurar a ligação manualmente.

Prerequisites

Precisa do URL do seu espaço de trabalho do Azure Databricks e de acesso aos modelos, serviços MCP e competências que pretende utilizar. Para configuração manual, instala o OpenCode e tem 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 funde as entradas de configuração em ficheiros existentes, mantendo definições não relacionadas.

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

Utilize a CLI do Unity Gateway

Instale ug, depois execute este comando a partir do diretório do seu projeto:

ug opencode

Selecione o seu espaço de trabalho e inicie sessão quando solicitado. O comando abre o OpenCode com os modelos do teu gateway configurados. Comece a programar, ou entre /models para escolher outro modelo configurado.

Configurar os modelos manualmente

Instale o OpenCode, depois funde 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 nos dois locais, caso escolha outro modelo Claude. Mantenha toolStreaming: false para compatibilidade com o gateway. Inicie OpenCode com opencode.

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

Para reduzir o custo por token para tarefas rotineiras, selecione um modelo open source como system.ai.glm-5-2 o seu modelo. Ver Controlar despesas.

Adicionar ferramentas MCP

Para usar system.ai.dbsql, system.ai.sandbox, ou system.ai.web_search, um administrador de conta deve ativar a versão beta do Unity Gateway a partir da página de Pré-visualizações da consola da conta. Consulte Gerir pré-visualizações da conta.

Utilize a CLI do Unity Gateway

Corrida:

ug mcp add --agents opencode

Selecione os seus serviços, depois reinicie com ug opencode.

Configurar manualmente os serviços MCP

Funde 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, altere o nome do servidor e substitua system.ai.dbsql pelo nome do Catálogo Unity em três partes. Reinicia o OpenCode e pede-lhe que use uma ferramenta conectada. Consulte a documentação MCP da OpenCode.

ug opencode utiliza ~/.ucode/opencode-xdg/opencode/opencode.json. Utilize esse ficheiro para entradas manuais de MCP ao iniciar através de ug.

Adicionar competências

Utilize a CLI do Unity Gateway

Descarregue competências publicadas:

ug skills add

Escolhe as tuas competências e depois reinicia o OpenCode. Lê os downloads ~/.agents/skills/ e carrega as competências relevantes enquanto trabalhas.

Configure as competências manualmente

Para os ficheiros que já tem, coloque cada pasta completa de skill em ~/.agents/skills/ ou na .opencode/skills/ do seu projeto. Consulte a documentação de competências do OpenCode.

Para aceder ao registo de habilidades publicado através do 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 à direita, o cabeçalho Bearer e oauth: false. Peça ao agente para usar uma capacidade pelo seu nome completo.

As funcionalidades do Unity Gateway estão em versão beta. Consulte Competências de Governar para habilitação e permissões.

Troubleshooting

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

Falta um servidor MCP: Reiniciar o agente. Se o configuraste com ug, inicia-o com ug opencode para que utilize as mesmas definições. Para a configuração manual, verifique ~/.config/opencode/opencode.json e coloque a ficha do portador.

Falta uma habilidade descarregada: Verifique se a pasta completa se encontra num diretório suportado e contém SKILL.md. Execute novamente ug skills add com as mesmas opções para atualizar as skills descarregadas.

Para problemas de início de sessão ou ug configuração do espaço de trabalho, execute ug doctor.

Passos seguintes

  • Última atualização a