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.

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. 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.

Para adicionar ferramentas ou habilidades MCP, execute esses comandos no seu terminal e depois reinicie o Codex:

ug mcp add
ug skills add

Cada comando permite que você escolha o que adicionar. Para configuração manual, use as seções de configuração abaixo.

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

Use o CLI do Unity Gateway

Execute este comando e selecione os serviços que deseja adicionar:

ug mcp add

Reinicie o Codex ou o aplicativo desktop, depois peça para ele usar uma ferramenta conectada. ug Registra um proxy local que autentica solicitações e atualiza as credenciais.

Configure os serviços MCP manualmente

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

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

Substitua o nome do host e o token, depois reinicie o Codex. Para outro serviço, use um nome exclusivo em mcp_servers e substitua system.ai.dbsql pelo nome de três partes do Unity Catalog.

Para a configuração do OAuth, siga as instruções de autenticação MCP do OpenAI e registre uma aplicação Azure Databricks OAuth com a URL de callback exata que o Codex usa.

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> --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.

Próximas Etapas 

  • Last updated on