Connect Codex

Usa Codex en tu terminal o en la aplicación de escritorio de ChatGPT 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 y acceso a los modelos, MCPs y habilidades que quieres usar. Instala la última versión de Codex o la aplicación de escritorio de ChatGPT.

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

Códice en el terminal

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.

ChatGPT para escritorio

En macOS y Linux, instala ug y ejecuta este comando en un terminal interactivo:

ug configure --agents codex

Selecciona tu espacio de trabajo y inicia sesión. Si te lo piden, aprueba la actualización de configuración del sistema con la contraseña de tu dispositivo. ug configura la conexión de Unity Gateway y la actualización del token OAuth.

Abre o reinicia la aplicación de escritorio y comienza una conversación del Codex. Usa el selector de modelos para cambiar de modelo. El ug codex comando abre el agente del terminal; abre la app de escritorio normalmente tras la configuración.

En Windows, utiliza la configuración manual del modelo que aparece a continuación. Aún puedes usar ug mcp add y ug skills add añadir herramientas y habilidades, y luego reiniciar la app.

Configurar los modelos manualmente

Estos ajustes se aplican tanto al agente de terminal como a la aplicación de escritorio. 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 o vuelve a abrir la app de escritorio. 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 Codex con ug codex, o vuelve a abrir la app de escritorio; 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. Estos ajustes se aplican al agente de terminal y a la aplicación de escritorio.

Configurar una app OAuth

  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>" \
  --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 y el token:

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
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 Codex o la app de escritorio. 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

  • La app de escritorio sigue pidiendo inicio de sesión con OpenAI: En macOS o Linux, reejecuta ug configure --agents codex de forma interactiva y completa la actualización de configuración del sistema. El perfil CLI por sí solo no configura la app de escritorio. Para la configuración manual, comprueba que model_provider está en el nivel superior y requires_openai_auth = false en la tabla de proveedores. No añadas esa bandera a un proveedor que usa una auth tabla para la actualización de tokens OAuth.

  • 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

  • Última actualización el