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

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.

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

Prerequisites​

Você precisa da URL do workspace do Databricks e de acesso aos modelos, MCPs e habilidades que deseja usar. Instale a versão mais recente do Codex ou o aplicativo de 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:

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.

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:

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

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.

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​

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 o Codex com ug codex, ou reabra o aplicativo para desktop e, em seguida, teste uma ferramenta.

Configurar MCPs manualmente​

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

Configurar um aplicativo OAuth

  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>" \
      --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 a ~/.codex/config.toml, substituindo o hostname e o token:

Toml
[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 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 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:

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​

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

  • 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