Codex Connect

Use o Codex no seu terminal ou o aplicativo desktop do ChatGPT com modelos, ferramentas MCP e habilidades via Unity Gateway. Use a CLI do Gateway Unity (ug) para configurar o acesso, ou configure a conexão manualmente.

Para conectar ferramentas a uma configuração de Codex existente, vá em Adicionar ferramentas MCP.

Prerequisites

Você precisa da URL do seu workspace do Azure Databricks e acesso aos modelos, MCPs e habilidades que deseja usar. Instale a versão mais recente do Codex ou o aplicativo desktop do ChatGPT.

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

Codex no terminal

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

ug codex

Siga as instruções para selecionar seu espaço de trabalho e fazer login. ug configura a conexão e abre o Codex no seu terminal. Comece a trabalhar com os mesmos prompts e comandos que você já usa. Para mudar de modelo, insira /model.

Continue adicionando ferramentas MCP ou adicionando habilidades para dar acesso ao Codex a dados e instruções compartilhadas.

ChatGPT para desktop

No macOS e Linux, instale ug e execute este comando em um terminal interativo:

ug configure --agents codex

Selecione seu espaço de trabalho e faça login. Se solicitado, aprove a atualização de configuração do sistema com a senha do seu dispositivo. ug configura a conexão do Unity Gateway e a atualização do token OAuth.

Abra ou reinicie o aplicativo desktop e inicie uma conversa do Codex. Use o seletor de modelos para mudar de modelo. O ug codex comando abre o agente do terminal; abra o aplicativo de desktop normalmente após a configuração.

No Windows, use a configuração manual do modelo abaixo. Você ainda pode usar ug mcp add e ug skills add adicionar ferramentas e habilidades, e então reiniciar o app.

Configure os modelos manualmente

Essas configurações se aplicam tanto ao agente do terminal quanto ao aplicativo desktop. Feche o Codex, depois abra ou crie ~/.codex/config.toml. No Windows, use %USERPROFILE%\.codex\config.toml.

Junte as configurações seguintes ao arquivo. Mantenha model e model_provider no nível superior, antes de qualquer cabeçalho de tabela, e preserve configurações não relacionadas.

model = "<catalog>.<schema>.<model-name>"
model_provider = "databricks"

[model_providers.databricks]
name = "Databricks"
base_url = "https://<workspace-hostname>/ai-gateway/codex/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
http_headers = { Authorization = "Bearer <databricks-pat>" }

Substitua o modelo provisório pelo nome completo do Catálogo Unity, <workspace-hostname> pelo nome do seu espaço de trabalho e <databricks-pat> pelo seu token de acesso pessoal. Este exemplo armazena o token localmente; mantenha o arquivo privado e use seu próprio token.

Execute codex pelo diretório do seu projeto ou reabra o aplicativo desktop. Se seu dispositivo tiver configurações gerenciadas de provedor, peça ao administrador para atualizá-las; essas configurações têm prioridade sobre essa configuração de usuário.

Veja a referência de configuração da OpenAI para detalhes do campo.

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 do console da conta. Veja Gerenciar prévias da conta.

  1. Abra os MCPs do Unity Gateway > no seu espaço de trabalho. Escolha um MCP embutido ou registre seu servidor MCP externo.
  2. Copie o nome completo do MCP, como system.ai.github ou <catalog>.<schema>.<service>.
  3. Confirme que você tem acesso ao MCP.

Use o CLI do Unity Gateway

Instale ug, depois adicione o MCP ao Codex:

ug mcp add --agents codex --names <catalog>.<schema>.<service>

Substitua o marcador pelo nome que você copiou. Por exemplo, use --names system.ai.github para o GitHub. Para escolher serviços de forma interativa, omita --names.

Na primeira configuração, siga as instruções para selecionar seu espaço de trabalho, fazer login e escolher um modelo. ug configura tanto o acesso ao modelo quanto ao MCP e atualiza as credenciais. Para acesso ao MCP com seu próprio app OAuth, use a configuração manual abaixo.

Reinicie o Codex com ug codex, ou reabra o aplicativo desktop, então teste uma ferramenta.

Configure MCPs manualmente

Use um aplicativo OAuth público do Azure Databricks para fazer login e atualizar as credenciais. Essas configurações se aplicam ao agente do terminal e ao aplicativo desktop.

Configure um aplicativo OAuth

  1. Feche o Codex. Em ~/.codex/config.toml, adicione essas configurações no nível superior, antes de qualquer cabeçalho de tabela. Eles dão ao callback local OAuth uma porta fixa:

    mcp_oauth_callback_port = 8080
mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"

  2. Peça para um administrador da conta abrir Configurações > Conexões do aplicativo > Adicionar conexão no console da conta. Use um nome como codex-mcp, limpe Gere um segredo do cliente, defina a URL de redirecionamento para http://127.0.0.1:8080/callback e selecione o escopo ai-gateway. Salve e copie o ID do Cliente. Consulte Criar um aplicativo OAuth.

  3. Registre o MCP no Codex, substituindo os marcadores temporários:

    codex mcp add databricks-tools \
  --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>" \
  --oauth-client-id <client-id>

  4. Verifique a URL de callback impressa pelo Codex. Pode incluir um sufixo específico do servidor. Peça para o administrador adicionar exatamente essa URL aos URLs de redirecionamento do app OAuth antes de fazer login. Repita essa verificação ao adicionar outro servidor.

  5. Faça login e reabra o Codex:

    codex mcp login databricks-tools --scopes ai-gateway,offline_access

Para as configurações de callback, veja as instruções de autenticação MCP da OpenAI. Depois teste uma ferramenta.

Use um token de acesso pessoal para testes locais

Adicione o seguinte a ~/.codex/config.toml, substituindo o nome do host e o token:

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Para outro MCP, use um nome único sob mcp_servers e substitua system.ai.dbsql por seu nome completo. Mantenha o arquivo privado, depois reinicie o Codex e teste uma ferramenta.

Teste uma ferramenta MCP

  1. No Codex, insira /mcp e verifique se o servidor está conectado.
  2. Peça ao Codex para listar as ferramentas desse servidor e então solicite uma operação de leitura. Para o GitHub, peça para ele encontrar uma issue em um repositório que você possa acessar. Para um servidor personalizado, use uma ferramenta e entradas que você testou durante o registro.
  3. Se uma chamada de ferramenta pedir que você faça login, abra o link de login devolvido pelo MCP, complete o consentimento do provedor e então tente a chamada novamente. Esse login dá ao MCP acesso à sua conta externa.
  4. Verifique se o Codex faz uma chamada de ferramenta e retorna seu resultado. Uma resposta em texto sozinha não verifica a conexão.

Para usar dados do Azure Databricks, conecte-se system.ai.genie_one_mcp para perguntas comerciais ou system.ai.dbsql para SQL. Por exemplo, peça para o MCP SQL executar SELECT 1 AS result.

Para permissões, políticas e uso, consulte Gerenciar um MCP.

Adicionar habilidades

Use o CLI do Unity Gateway

Execute o seletor interativo:

ug skills add

Ou baixe uma habilidade publicada específica:

ug skills add --names <catalog>.<schema>.<skill-name>

Reinicie o Codex ou o aplicativo desktop. Habilidades baixadas estão disponíveis localmente em ~/.agents/skills/. Execute novamente o download para obter uma versão atualizada.

Para expor as habilidades de um esquema através do MCP, execute:

ug skills add --location "<catalog>.<schema>" --via mcp

Conecte manualmente o registro de habilidades

Adicione o seguinte a ~/.codex/config.toml:

[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Substitua o nome do host e o token. Mantenha a barra no final da URL. Reinicie o Codex e peça para ele usar uma habilidade publicada, como Use <catalog>.<schema>.<skill-name> to review this query.

O registro carrega as instruções da habilidade por meio do MCP. Para instalar os arquivos de skill que você já tem, coloque a pasta completa de skills, incluindo SKILL.md e os arquivos agrupados, em ~/.agents/skills/.

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

Troubleshooting

  • O aplicativo desktop ainda pede login OpenAI: No macOS ou Linux, execute ug configure --agents codex novamente de forma interativa e complete a atualização de configuração do sistema. O perfil CLI sozinho não configura o aplicativo para desktop. Para configuração manual, verifique se model_provider está no nível superior e requires_openai_auth = false na tabela de provedores. Não adicione essa bandeira a um provedor que usa uma auth tabela para atualização de tokens OAuth.

  • Solicitações falham com erro WebSocket: Definido supports_websockets = false na tabela ativa de provedores Azure Databricks. Se seu administrador gerencia essa configuração, peça para atualizar. Reinicie o app depois.

  • Um modelo está faltando: Verifique suas permissões de modelo. Defina model para o nome completo do Catálogo Unity na configuração ativa e inicie uma nova conversa.

  • Uma conexão MCP ou de habilidade falha: Verifique o URL, as permissões e o erro do conector. Para conexões manuais, verifique também a expiração do token. Para problemas de configuração do ug, execute ug doctor. Uma habilidade baixada pode permanecer disponível mesmo que a conexão do registro falhe.

  • O login do workspace funciona, mas uma ferramenta pede para você fazer login: Abra o link de login devolvido pelo MCP, faça login com o provedor externo e então tente a chamada novamente. O login no espaço de trabalho e o login do provedor são etapas separadas.

  • O OAuth relata um desajuste de redirecionamento ou a conexão expira: Compare a URL de redirecionamento do app OAuth com a URL exata informada pelo Codex, incluindo qualquer sufixo, e verifique o acesso à rede. As alterações no app OAuth podem levar até 30 minutos para entrar em vigor.

Próximas Etapas 

  • Última atualização em