Ligar ao Codex

Use o Codex no seu terminal ou a aplicação de desktop ChatGPT com modelos, ferramentas MCP e competências através do Unity Gateway. Use a CLI do Gateway Unity (ug) para configurar o acesso, ou configure a ligação manualmente.

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

Prerequisites

Precisas do URL do teu espaço de trabalho do Azure Databricks e de ter acesso aos modelos, MCPs e competências que queres usar. Instale a versão mais recente do Codex ou a aplicação desktop do ChatGPT.

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

Codex no terminal

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

ug codex

Siga as instruções para selecionar o seu espaço de trabalho e iniciar sessão. ug configura a ligação e abre o Codex no teu terminal. Começa a trabalhar com os mesmos prompts e comandos que já usas. Para mudar de modelo, introduza /model.

Continue a adicionar ferramentas MCP ou adicionar competências para dar ao Codex acesso a dados e instruções partilhadas.

ChatGPT para computador

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

ug configure --agents codex

Selecione o seu espaço de trabalho e inicie sessão. Se for solicitado, aprove a atualização de configuração do sistema com a palavra-passe do seu dispositivo. ug configura a ligação do Unity Gateway e a atualização do token OAuth.

Abre ou reinicia a aplicação de ambiente de trabalho e inicia uma conversa do Codex. Usa o seletor de modelos para mudar de modelo. O ug codex comando abre o agente do terminal; abre a aplicação de ambiente de trabalho normalmente após a configuração.

No Windows, use a configuração manual do modelo abaixo. Ainda podes usar ug mcp add e ug skills add adicionar ferramentas e competências, e depois reiniciar a aplicação.

Configurar os modelos manualmente

Estas definições aplicam-se tanto ao agente do terminal como à aplicação de ambiente de trabalho. Fecha o Codex, depois abre ou cria ~/.codex/config.toml. No Windows, use %USERPROFILE%\.codex\config.toml.

Intercale as seguintes configurações no ficheiro. Mantém model e model_provider no nível superior, antes de quaisquer cabeçalhos de tabela, e preserva definiçõ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 de host do seu espaço de trabalho e <databricks-pat> pelo seu token de acesso pessoal. Este exemplo armazena o token localmente; mantenha o ficheiro privado e use o seu próprio token.

Executa codex a partir do diretório do teu projeto ou reabre a aplicação de ambiente de trabalho. Se o seu dispositivo tiver definições geridas do fornecedor, peça ao seu administrador para as atualizar; essas definições têm prioridade sobre esta configuração do utilizador.

Consulte 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 da consola da conta. Consulte Gerir pré-visualizações da conta.

  1. Abra os MCPs do Unity Gateway > no seu espaço de trabalho. Escolha um MCP incorporado ou registe o seu servidor MCP externo.
  2. Copie o nome completo do MCP, como system.ai.github ou <catalog>.<schema>.<service>.
  3. Confirma que tens acesso ao MCP.

Utilize a CLI do Unity Gateway

Instale ug, depois adicione o MCP ao Codex:

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

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

Na primeira configuração, siga as instruções para selecionar o seu espaço de trabalho, iniciar sessão e escolher um modelo. ug configura tanto o acesso ao modelo como ao MCP e atualiza as credenciais. Para aceder ao MCP com a sua própria aplicação OAuth, use a configuração manual abaixo.

Reinicie o Codex com ug codex, ou abra novamente a aplicação de ambiente de trabalho, depois teste uma ferramenta.

Configurar os MCPs manualmente

Use uma aplicação pública Azure Databricks OAuth para iniciar sessão e atualizar as credenciais. Estas definições aplicam-se ao agente do terminal e à aplicação de ambiente de trabalho.

Configurar uma aplicação OAuth

  1. Fecha o Codex. Em ~/.codex/config.toml, adicione estas definições ao nível superior, antes de quaisquer cabeçalhos de tabela. Eles dão ao callback OAuth local uma porta fixa:

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

  2. Faça com que um administrador de conta abra Definições > Ligações da aplicação > Adicionar ligação na consola da conta. Utilize um nome como codex-mcp, desmarque Gerar um segredo do cliente, defina o URL de redirecionamento para http://127.0.0.1:8080/callback, e selecione o âmbito ai-gateway. Guarda e copia o ID do Cliente. Veja Crie uma app OAuth.

  3. Registe o MCP no Codex, substituindo os marcadores de lugar:

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

  4. Verifique o URL de callback impresso por Codex. Pode incluir um sufixo específico do servidor. Peça ao administrador para adicionar exatamente esse URL aos URLs de redirecionamento da aplicação OAuth antes de iniciar sessão. Repita esta verificação ao adicionar outro servidor.

  5. Iniciar sessão e depois reabrir o Codex:

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

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

Utilize um token de acesso pessoal para testes locais

Adicione o seguinte a ~/.codex/config.toml, substituindo o nome do anfitrião 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 em mcp_servers e substitua system.ai.dbsql pelo seu nome completo. Mantém o ficheiro privado, depois reinicia o Codex e testa uma ferramenta.

Teste uma ferramenta MCP

  1. No Codex, introduza /mcp e verifique se o servidor está ligado.
  2. Pede à Codex para listar as ferramentas desse servidor e depois solicita uma operação de leitura. No GitHub, pede-lhe que encontre uma issue num repositório ao qual possa aceder. Para um servidor personalizado, usa uma ferramenta e entradas que testaste durante o registo.
  3. Se uma chamada de ferramenta lhe pedir para iniciar sessão, abra o link de login devolvido pelo MCP, complete o consentimento do fornecedor e depois tente novamente a chamada. Este login dá ao MCP acesso à sua conta externa.
  4. Verifica se o Codex faz uma chamada de ferramenta e devolve o resultado. Uma resposta de texto por si só não verifica a ligação.

Para usar Azure Databricks data, ligue-se a system.ai.genie_one_mcp para perguntas empresariais ou system.ai.dbsql para SQL. Por exemplo, peça ao SQL MCP para executar SELECT 1 AS result.

Para permissões, políticas e utilização, consulte Governação de um MCP.

Adicionar competências

Utilize a CLI do Unity Gateway

Execute o seletor interativo:

ug skills add

Ou descarregue uma competência publicada específica:

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

Reinicie o Codex ou a aplicação de desktop. As competências descarregadas estão disponíveis localmente em ~/.agents/skills/. Repete o download para obter uma versão atualizada.

Para expor as capacidades de um schema através do MCP, em vez disso, execute:

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

Ligue manualmente o registo de competências

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>" }

Substitui o nome do host e o token. Mantém a barra final no URL. Reinicie o Codex e peça-lhe que utilize uma capacidade publicada, como Use <catalog>.<schema>.<skill-name> to review this query.

O registo carrega instruções de competências através do MCP. Para instalar ficheiros de skill que já tem, coloque a pasta completa de skills, incluindo SKILL.md e os ficheiros agrupados, em ~/.agents/skills/.

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

Troubleshooting

  • A aplicação para computador continua a pedir que inicie sessão na OpenAI: No macOS ou Linux, execute novamente ug configure --agents codex de forma interativa e conclua a atualização da configuração do sistema. O perfil CLI por si só não configura a aplicação de ambiente de trabalho. Para configuração manual, verifique se está model_provider no nível superior e requires_openai_auth = false na tabela de fornecedores. Não adicione essa bandeira a um fornecedor que use uma auth tabela para atualização de tokens OAuth.

  • Os pedidos falham com um erro WebSocket: Definir supports_websockets = false na tabela ativa de fornecedores do Azure Databricks. Se o teu administrador gerir essa configuração, pede-lhe para a atualizar. Reinicia a aplicação depois.

  • Falta um modelo: Verifique as permissões dos seus modelos. Define model o nome completo do Catálogo Unity na configuração ativa e inicia uma nova conversa.

  • Uma ligação MCP ou skill falha: Verifique a URL, permissões e erro do conector. Para ligações manuais, verifique também a expiração do token. Para problemas de configuração de ug, execute ug doctor. Uma funcionalidade transferida pode continuar disponível mesmo que a ligação ao registo falhe.

  • O login no espaço de trabalho funciona, mas uma ferramenta pede-lhe para iniciar sessão: Abra o link de login devolvido pelo MCP, inicie sessão no fornecedor externo e depois tente novamente a chamada. O espaço de trabalho e o início de sessão do fornecedor são etapas separadas.

  • O OAuth reporta um desajuste de redirecionamento ou a ligação expira: Compare o URL de redirecionamento da aplicação OAuth com o URL exato que o Codex indica, incluindo qualquer sufixo, e verifique o acesso à rede. As alterações da aplicação OAuth podem demorar até 30 minutos a entrar em vigor.

Passos seguintes

  • Última atualização a