Pular para o conteúdo principal
Última atualização em

Conectar o Codex

Use o Codex no seu terminal 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.

Para conectar ferramentas a uma configuração existente do Codex, acesse Adicionar ferramentas MCP.

Prerequisites​

Você precisa da URL do seu workspace do Databricks, acesso aos modelos, MCPs e habilidades que deseja usar, além da versão mais recente da Codex CLI.

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

Use a CLI do Unity Gateway (recomendado)​

Instale ug e, em seguida, execute este comando no diretório do seu projeto:

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

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

execução no compute do Databricks​

Para execução o Codex em um compute Serverless ou em um cluster dedicado sem instalar o ug, conecte-se com o túnel SSH e execução o codex. O agente está pré-configurado para o Unity Gateway. Consulte Execução agentes de codificação em uma sessão SSH.

Configure modelos manualmente​

Feche o Codex e 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.

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

Execução codex a partir do diretório do projeto. Se o seu dispositivo tem configurações de provedor gerenciadas, peça ao seu administrador para atualizá-las; essas configurações têm precedência sobre esta configuração de usuário.

Consulte a referência de configuração da OpenAI para obter detalhes dos campos.

Add MCP tools​

Para usar system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, um administrador de account deve habilitar o beta do Unity Gateway na página Previews do console da account. Consulte Gerenciar prévias da account.

  1. Abra o Unity Gateway > MCPs em seu workspace. Escolha um MCP integrada ou registro seu servidor MCP externo.
  2. Copy the MCP's full name, such as system.ai.github or <catalog>.<schema>.<service>.
  3. Confirme que você tem acesso ao MCP.

Use a CLI do Unity Gateway​

Instale o ug e, em seguida, adicione o MCP ao Codex:

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

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

Na primeira configuração, siga os prompts para selecionar seu workspace, fazer login e escolher um modelo. ug configura o acesso ao modelo e ao MCP e refresh as credenciais. Para acesso ao MCP com seu próprio aplicativo OAuth, use a configuração manual abaixo.

Reinicie a CLI do Codex com ug codex, depois teste uma ferramenta.

Configurar MCPs manualmente​

Use um aplicativo OAuth público do Databricks para fazer login e refresh credenciais.

Para usar o ID de cliente Codex default, que não precisa de um administrador account para criar um aplicativo OAuth:

  1. Registre o MCP no Codex, substituindo os espaços reservados:

    Bash
    codex mcp add databricks-tools \
      --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \
      --oauth-client-id https://chatgpt.com/oauth/codex/client.json

  2. Faça login e, em seguida, reabra o Codex:

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

Em seguida, teste uma ferramenta.

Configurar um aplicativo OAuth personalizado

  1. Fechar o Codex. Em ~/.codex/config.toml, adicione estas configurações no nível superior, antes de qualquer cabeçalho de tabela. Elas fornecem ao retorno de chamada OAuth local uma porta fixa:

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

  2. Peça a um administrador da account que abra Settings > App connections > Add connection no console da account. Use um nome como codex-mcp, desmarque Generate a client secret , defina a URL de redirecionamento como http://127.0.0.1:8080/callback e selecione o escopo ai-gateway. Salve e copie o Client ID . Consulte Criar um aplicativo OAuth.

  3. Registre o MCP no Codex, substituindo os espaços reservados:

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

  4. Verifique a URL de retorno de chamada impressa pelo Codex. Ele pode incluir um sufixo específico do servidor. Peça ao administrador para adicionar essa URL exata às URLs de redirecionamento do aplicativo OAuth antes de fazer login. Repita essa verificação ao adicionar outro servidor.

  5. Faça login e, em seguida, reabra o Codex:

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

Para configurações de retorno de chamada, consulte Instruções de autenticação MCP da OpenAI. Em seguida, teste uma ferramenta.

Use um personal access token para testes locais

Adicione o seguinte ao ~/.codex/config.toml, substituindo o hostname, o ID do workspace e o token:

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

Para outro MCP, use um nome exclusivo sob mcp_servers e substitua system.ai.dbsql pelo nome completo dele. Mantenha o arquivo privado, reinicie o Codex e teste uma ferramenta.

Testar 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, em seguida, solicite uma operação de leitura. Para o GitHub, peça para ele encontrar um problema (issue) em um repository 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 solicitar que você faça login, abra o link de login retornado pelo MCP, conclua o consentimento do provedor e tente novamente a chamada. Este login concede ao MCP acesso à sua account externa.
  4. Verifique se o Codex faz uma chamada de ferramenta e retorna o resultado. Uma resposta em texto sozinha não verifica a conexão.

Para usar dados do Databricks, conecte system.ai.genie_one_mcp para perguntas de negócios ou system.ai.dbsql para SQL. Por exemplo, peça ao SQL MCP para realizar a execução SELECT 1 AS result.

Para obter informações sobre permissões, políticas e uso, consulte Governar um MCP.

Adicionar habilidades​

Use a CLI do Unity Gateway​

Executar o seletor interativo:

Bash
ug skills add

Ou faça download de uma habilidade publicada específica:

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

Reinicie a Codex CLI. As habilidades download ficam 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:

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

Connect the skill registry manually​

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

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​

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

  • Workspace sign-in works, but a tool asks you to log in: Open the login link returned by the MCP, sign in to the external provider, then retry the call. Workspace e o início de sessão do provedor são os passos separados.

  • O OAuth relata uma divergência de redirecionamento ou a conexão esgota o tempo limite: verifique se a URL de redirecionamento do aplicativo OAuth corresponde exatamente à URL relatada pelo Codex, incluindo qualquer sufixo, e verifique o acesso à rede. As alterações no aplicativo OAuth podem levar até 30 minutos para entrar em vigor.

Passos seguintes​

Nesta página