Connect Codex

Usa Codex en tu terminal con modelos, herramientas MCP y habilidades a través de Unity Gateway. Utiliza la CLI de Unity Gateway (ug) para configurar el acceso, o configura la conexión manualmente.

Para conectar herramientas a una configuración de Codex existente, ve a Añadir herramientas MCP.

Prerequisites

Necesitas la URL de tu espacio de trabajo de Azure Databricks, acceso a los modelos, MCPs y habilidades que quieres usar, y la última CLI de Codex.

Si tu administrador ya ha configurado tu dispositivo, sigue las instrucciones de lanzamiento de tu organización.

Instala ug, y luego ejecuta este comando desde el directorio de tu proyecto:

ug codex

Sigue las indicaciones para seleccionar tu espacio de trabajo e iniciar sesión. ug configura la conexión y abre Codex en tu terminal. Empieza a usar las mismas indicaciones y comandos que ya usas. Para cambiar de modelo, introduce /model.

Continúe en Agregar herramientas MCP o Agregar aptitudes para dar a Codex acceso a los datos y las instrucciones compartidas.

Ejecución en el proceso de Azure Databricks

Para ejecutar Codex en computación serverless o en un clúster dedicado sin instalar ug, conéctate con el túnel SSH y ejecuta codex. El agente está preconfigurado para Unity Gateway. Ver Ejecutar agentes de codificación en una sesión SSH.

Configurar los modelos manualmente

Cierra el Codex, luego abre o crea ~/.codex/config.toml. Para Windows, use %USERPROFILE%\.codex\config.toml.

Fusiona los siguientes ajustes en el archivo. Guarda model y model_provider en el nivel superior, antes de cualquier cabecera de tablas, y conserva configuraciones no 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>" }

Sustituye el marcador de posición del modelo por su nombre completo del Catálogo de Unity, <workspace-hostname> por el nombre de host de tu espacio de trabajo y <databricks-pat> por tu token de acceso personal. Este ejemplo almacena el token localmente; mantén el archivo privado y usa tu propio token.

Ejecuta codex desde el directorio de tu proyecto. Si tu dispositivo tiene configuraciones gestionadas del proveedor, pide a tu administrador que las actualice; esas configuraciones tienen prioridad sobre esta configuración de usuario.

Consulta la referencia de configuración de OpenAI para detalles del campo.

Añadir herramientas MCP

Para usar system.ai.dbsql, system.ai.sandbox, o system.ai.web_search, un administrador de cuenta debe habilitar la beta Unity Gateway desde la página de vistas previas de la consola de cuentas. Consulte Administrar vistas previas de la cuenta.

  1. Abre los MCPs de Unity Gateway > en tu espacio de trabajo. Elige un MCP integrado o registra tu servidor MCP externo.
  2. Copia el nombre completo del MCP, como system.ai.github o <catalog>.<schema>.<service>.
  3. Confirma que tienes acceso al MCP.

Utiliza la CLI de Unity Gateway

Instala ug, luego añade el MCP al Codex:

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

Sustituye el marcador por el nombre que copiaste. Por ejemplo, usa --names system.ai.github para GitHub. Para elegir servicios de forma interactiva, omite --names.

En la primera configuración, sigue las indicaciones para seleccionar tu espacio de trabajo, iniciar sesión y elegir un modelo. ug configura tanto el acceso al modelo como al MCP y actualiza las credenciales. Para acceder a MCP con tu propia app OAuth, utiliza la configuración manual que aparece a continuación.

Reinicia la CLI del Codex con ug codex, y luego prueba una herramienta.

Configurar MCP manualmente

Utiliza una aplicación pública de Azure Databricks OAuth para iniciar sesión y actualizar las credenciales.

Para usar el ID de cliente Codex por defecto, que no necesita un administrador de cuenta para crear una app OAuth:

  1. Registrar el MCP en Codex, reemplazando los marcadores de posición:

    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. Inicia sesión y luego vuelve a abrir Codex:

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

Luego prueba una herramienta.

Configura una app OAuth personalizada
  1. Cerrar Codex. En ~/.codex/config.toml, añade estos ajustes en el nivel superior, antes de cualquier cabecera de tabla. Proporcionan al callback local OAuth un puerto fijo:

    mcp_oauth_callback_port = 8080
    mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"
    
  2. Haz que un administrador de cuenta abra Configuración > Conexiones de aplicaciones > Añadir conexión en la consola de cuentas. Utilice un nombre como codex-mcp, desactive Generar un secreto de cliente, establezca la URL de redirección en http://127.0.0.1:8080/callback y seleccione el ámbito ai-gateway. Guarda y copia el ID del cliente. Consulta cómo crear una aplicación OAuth.

  3. Registrar el MCP en Codex, reemplazando los marcadores de posición:

    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. Consulta la URL de callback impresa por Codex. Puede incluir un sufijo específico para cada servidor. Haz que el administrador añada esa URL exacta a las URLs de redirección de la app de OAuth antes de iniciar sesión. Repite esta comprobación al añadir otro servidor.

  5. Inicia sesión y luego vuelve a abrir Codex:

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

Para la configuración de callback, consulta las instrucciones de autenticación MCP de OpenAI. Luego prueba una herramienta.

Utiliza un token de acceso personal para pruebas locales

Añade lo siguiente a ~/.codex/config.toml, reemplazando el nombre de host, el ID del espacio de trabajo y el token:

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

Para otro MCP, usa un nombre único debajo mcp_servers y sustituye system.ai.dbsql por su nombre completo. Mantén el archivo privado, luego reinicia Codex y prueba una herramienta.

Prueba una herramienta MCP

  1. En Codex, introduce /mcp y comprueba que el servidor está conectado.
  2. Pide a Codex que liste las herramientas de ese servidor y luego solicita una operación de lectura. Para GitHub, pídele que encuentre un issue en un repositorio al que puedas acceder. Para un servidor personalizado, usa una herramienta y entradas que probaste durante el registro.
  3. Si una llamada de herramienta te pide iniciar sesión, abre el enlace de inicio de sesión que te devuelve el MCP, completa el consentimiento del proveedor y luego vuelve a intentar la llamada. Este inicio de sesión da al MCP acceso a tu cuenta externa.
  4. Comprueba que Codex realiza una llamada a la herramienta y devuelve su resultado. Una respuesta por texto por sí sola no verifica la conexión.

Para usar datos de Azure Databricks, conecta system.ai.genie_one_mcp para preguntas de negocio o system.ai.dbsql para SQL. Por ejemplo, pide al MCP SQL que ejecute SELECT 1 AS result.

Para permisos, políticas y uso, véase Administrar un MCP.

Adición de aptitudes

Utiliza la CLI de Unity Gateway

Ejecuta el selector interactivo:

ug skills add

O descarga una habilidad publicada específica:

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

Reinicia la CLI de Codex. Las habilidades descargadas están disponibles localmente en ~/.agents/skills/. Vuelve a descargar la descarga para obtener una versión actualizada.

Para exponer las habilidades de un esquema mediante MCP en su lugar, ejecuta:

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

Conecta el registro de habilidades manualmente

Agregue lo siguiente a ~/.codex/config.toml:

[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Cambia el nombre de host y el token. Mantén la barra diagonal final en la URL. Reinicia Codex y pídele que use una habilidad publicada, como Use <catalog>.<schema>.<skill-name> to review this query.

El registro carga las instrucciones de habilidades mediante MCP. Para instalar los archivos de habilidades que ya tienes, coloca la carpeta completa de habilidades, incluyendo SKILL.md y los archivos agrupados, en ~/.agents/skills/.

Las habilidades de Unity Gateway están en Beta. Consulta Habilidades de Gobierno para habilitación y permisos.

Troubleshooting

  • Las solicitudes fallan con un error WebSocket: Establecido supports_websockets = false en la tabla activa de proveedores de Azure Databricks. Si tu administrador gestiona esa configuración, pídele que la actualice. Reinicia la app después.

  • Falta un modelo: Comprueba los permisos de tu modelo. Configura model con su nombre completo en Unity Catalog en la configuración activa y comienza una nueva conversación.

  • Falla una conexión MCP o de skill: Comprueba la URL, los permisos y el error del conector. Para conexiones manuales, también comprueba la expiración del token. Para problemas ug de configuración, ejecuta ug doctor. Una habilidad descargada puede permanecer disponible incluso si falla la conexión al registro.

  • El inicio de sesión en el espacio de trabajo funciona, pero una herramienta te pide iniciar sesión: Abre el enlace de inicio de sesión que devuelve el MCP, inicia sesión con el proveedor externo y luego vuelve a intentar la llamada. El espacio de trabajo y el inicio de sesión con el proveedor son pasos separados.

  • OAuth informa de que la URL de redirección no coincide o de que la conexión se agota: Compara la URL de redirección de la app OAuth con la URL exacta que informa Codex, incluyendo cualquier sufijo, y comprueba el acceso a la red. Los cambios en la app de OAuth pueden tardar hasta 30 minutos en hacer efecto.

Pasos siguientes