Conectar o Codex
Use o Codex no seu terminal ou no aplicativo para desktop do ChatGPT com modelos, ferramentas MCP e habilidades por meio do Unity Gateway. Use a CLI do Unity Gateway (ug) para configurar o acesso ou configure a conexão manualmente.
Antes de começar
Você precisa da URL do seu workspace do Databricks e de acesso aos modelos, aos serviços MCP e às habilidades que deseja usar. Instale a versão mais recente do Codex ou do aplicativo para desktop do ChatGPT.
Se o seu administrador já configurou o seu dispositivo, siga as instruções de inicialização da sua organização.
Codex no terminal
Use a CLI do Unity Gateway (recomendado)
Instale ug e, em seguida, execute este comando no diretório do seu projeto:
ug codex
Siga as instruções para selecionar seu Workspace 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 alterar os modelos, insira /model.
Para adicionar ferramentas ou habilidades do MCP, execute estes comandos em seu terminal e, em seguida, reinicie o Codex:
ug mcp add
ug skills add
Each comando lets you select what to add. For manual setup, use the configuration sections abaixo.
ChatGPT para desktop
Use a CLI do Unity Gateway (recomendado)
No macOS e no Linux, instale o ug e execute este comando em um terminal interativo:
ug configure --agents codex
Selecione seu workspace e faça login. Se solicitado, aprove a atualização da configuração do sistema com a senha do seu dispositivo. ug configura a conexão do Unity Gateway e o refresh do token OAuth.
Abra ou reinicie o aplicativo de desktop e comece uma conversa no Codex. Use o seletor de modelos para alterar os modelos. O comando ug codex 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 para adicionar ferramentas e habilidades, e reiniciar o aplicativo.
Configure modelos manualmente
Estas configurações se aplicam tanto ao agente de terminal quanto ao aplicativo para desktop. Feche o Codex e, em seguida, abra ou crie ~/.codex/config.toml. No Windows, use %USERPROFILE%\.codex\config.toml.
Merge the following settings into the file. Keep model and model_provider at the top level, before any table headers, and preserve unrelated settings.
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 espaço reservado do modelo pelo nome completo no Unity Catalog, <workspace-hostname> pelo hostname do seu workspace e <databricks-pat> pelo seu access token pessoal. Este exemplo armazena o token localmente; mantenha o arquivo privado e use seu próprio token.
Run codex from your project directory or reopen the desktop app. If your device has configurações de provedor gerenciadas, ask your admin to update them; those settings take precedence over this user configuration.
Consulte a referência de configuração da OpenAI para obter detalhes dos campos.
Add MCP tools
Use a CLI do Unity Gateway
Execute este comando e selecione os serviços que deseja adicionar:
ug mcp add
Reinicie o Codex ou o aplicativo para desktop e peça para ele usar uma ferramenta conectada. ug registra um proxy local que autentica requisições e faz refresh de credenciais.
Configurar 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 hostname e o token e 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 da OpenAI e faça o registro de um aplicativo OAuth do Databricks com a URL de retorno de chamada exata que o Codex usa.
Adicionar habilidades
Use a CLI do Unity Gateway
Executar o seletor interativo:
ug skills add
Ou faça download de uma habilidade publicada específica:
ug skills add --names <catalog>.<schema>.<skill-name>
Reinicie o Codex ou o aplicativo de desktop. As habilidades de download 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 por meio do MCP, execute:
ug skills add --location <catalog>.<schema> --mcp
Connect the skill registry manually
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 hostname e o token. Mantenha a barra à direita no 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 de habilidade por meio do MCP. Para instalar os arquivos de habilidade que você já tem, coloque a pasta de habilidade completa, incluindo SKILL.md e os arquivos agrupados, em ~/.agents/skills/.
Unity Gateway skills are in Beta. See Govern skills for enablement and permissions.
Solução de problemas
The desktop app still asks for OpenAI sign-in: On macOS or Linux, rerun ug configure --agents codex interactively and complete the system configuration update. The CLI profile alone does not configure the desktop app. For manual setup, check that model_provider is at the top level and requires_openai_auth = false is in the provider table. Do not add that flag to a provider that uses an auth table for OAuth token refresh.
As solicitações falham com um erro de WebSocket: Defina supports_websockets = false na tabela de provedores ativa do Databricks. Se o seu administrador gerenciar essa configuração, peça a ele que a atualize. Reinicie o aplicativo em seguida.
Falta um modelo: verifique as permissões do seu modelo. Defina model como o nome completo no Unity Catalog na configuração ativa e começar uma nova conversa.
Uma conexão de MCP ou habilidade falha: Verifique a 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 de ug, execute ug doctor. Uma habilidade baixada pode permanecer disponível mesmo se a conexão do registro falhar.