API de modelo grande local para tutorial de uso de Codex: Ollama, LM Studio y vLLM

Si desea que Codex utilice modelos locales grandes, no conecte ninguna dirección compatible con OpenAI directamente en la configuración del proyecto. Actualmente Codex tiene una ruta de modelo local más confiable: modo OSS. Admite de forma nativa la selección de Ollama o LM Studio como proveedor local.

El comando más corto es:

1

codex --oss --local-provider ollama

o:

1

codex --oss --local-provider lmstudio

Si implementa usted mismo una vLLM, LiteLLM u otra puerta de enlace compatible con OpenAI, puede explorar la configuración avanzada de openai_base_url. Sin embargo, esta ruta requiere que el servicio sea verdaderamente compatible con el comportamiento de la API requerido por Codex, y el costo de solución de problemas es mayor. No debe confundirse con el modo OSS integrado.

Elija primero la ruta correcta

Se recomienda a los usuarios individuales comunes que ejecuten primero Ollama o LM Studio. --oss del Codex utilizará el proveedor de OSS local especificado; Si no se pasa --local-provider y no se establece ningún valor predeterminado, la CLI interactiva le pedirá que elija, pero codex exec informará directamente un error.

Solución 1: utilice Ollama para conectarse al Codex

1. Confirmar que Ollama y modelos están disponibles

Primero verifica si Ollama está disponible:

1
2

ollama -v
ollama ls

Cuando no haya ningún modelo, primero descargue un código o modelo general adecuado para la memoria de video local, por ejemplo:

1

ollama pull qwen3:8b

Pruebe por separado:

1

ollama run qwen3:8b

Si el modelo no puede ejecutarse en Ollama, primero resuelva el problema de la memoria de video, el controlador, la descarga del modelo o el servicio de Ollama; No vaya directamente al Codex para solucionar problemas.

2. Modelo local de un solo uso

Ejecutar en el directorio del proyecto:

1

codex --oss --local-provider ollama

Luego ingrese la tarea como de costumbre, por ejemplo:

1

阅读这个仓库的 README，列出本地启动步骤，不要修改文件。

Esto sólo afecta a la sesión actual. Si desea volver temporalmente al Codex normal, simplemente inícielo sin --oss.

3. Establezca Ollama como proveedor local predeterminado

Si utiliza modelos locales con frecuencia, coloque el siguiente contenido en el archivo de configuración del Codex a nivel de usuario:

1

oss_provider = "ollama"

Luego puedes ejecutar directamente:

1

codex --oss

La configuración a nivel de usuario del Codex generalmente se encuentra en CODEX_HOME y el valor predeterminado es ~/.codex/config.toml; Las rutas comunes de Windows son:

1

C:\Users\你的用户名\.codex\config.toml

Vuelva a abrir el Codex después de la modificación. Si hay una configuración compleja, primero haga una copia de seguridad de config.toml y agregue solo esta línea. No sobrescriba la zona de pruebas, MCP, habilidades y otras configuraciones originales.

Opción 2: utilizar LM Studio para conectarse al Codex

LM Studio es adecuado para personas que han descargado el modelo GGUF y desean utilizar la interfaz gráfica para ajustar el contexto y la descarga de GPU.

1. Inicie el servicio local en LM Studio y cargue el modelo.

Ingrese a la página Desarrollador de LM Studio, inicie el servidor y confirme que se haya cargado un modelo de chat/instrucciones. La API local de LM Studio escucha de forma predeterminada en:

1

http://localhost:1234

Puede verificar el servicio modelo primero:

1

curl http://localhost:1234/v1/models

Lo que se devuelve aquí es el estado del modelo lateral de LM Studio; ayuda a confirmar que tanto el servicio como el modelo están listos.

2. Inicie en modo Codex OSS

1

codex --oss --local-provider lmstudio

Configuración predeterminada a largo plazo:

1

oss_provider = "lmstudio"

Luego usa:

1

codex --oss

LM Studio aún administra la longitud del contexto del modelo, la descarga de GPU y los parámetros de inferencia de LM Studio. Si la respuesta del Codex es lenta, primero verifique si el tamaño del modelo excede la memoria de video, si el contexto es demasiado largo y si otros servicios de inferencia locales ocupan la GPU al mismo tiempo.

Opción 3: método de conexión avanzado para API compatibles con OpenAI como vLLM

vLLM, LiteLLM, puertas de enlace empresariales y algunos agentes proporcionan una interfaz /v1 compatible con OpenAI. La referencia de configuración oficial del Codex proporciona openai_base_url, que anula la dirección base del proveedor openai integrado.

Configuración esquemática:

1

openai_base_url = "http://127.0.0.1:8000/v1"

Si el servicio está en un host LAN:

1

openai_base_url = "http://192.168.1.20:8000/v1"

Hay cuatro límites a los que prestar atención en este camino:

1. **Escrito únicamente en el nivel de usuario ~/.codex/config.toml. ** Codex ignorará openai_base_url, model_provider y model_providers en el proyecto .codex/config.toml para evitar que el repositorio cambie en secreto el proveedor del modelo de la máquina.
2. Un servicio no es solo “/v1/chat/completions”, eso es suficiente. Los flujos de trabajo específicos del Codex pueden requerir modelos, respuestas de transmisión, llamadas de herramientas u otros comportamientos compatibles.
3. La autenticación está determinada por su puerta de enlace. Si la puerta de enlace requiere un token de portador, se debe configurar correctamente de acuerdo con la configuración de autenticación actual de la puerta de enlace y del Codex; no escriba el token en el archivo del almacén.
4. Este no es un proveedor local oficial de OSS incluido en el Codex. Cuando encuentre una excepción, primero use Ollama o LM Studio para verificar el modo Codex OSS y luego verifique la compatibilidad de la puerta de enlace.

El servicio vLLM se puede verificar primero de forma independiente:

1

curl http://127.0.0.1:8000/v1/models

Solo después de que el comando devuelva una lista estable de modelos se continúa verificando el códice para el nivel de usuario openai_base_url.

Cómo elegir un modelo

Que un modelo local pueda “utilizarse” y que pueda ser “tan fiable como el modelo oficial del Codex” son dos cosas diferentes. Los agentes de código generalmente requieren un contexto extenso, llamadas a herramientas estables, una sólida comprensión del código y velocidades de generación suficientemente rápidas.

Al seleccionar, fíjate al menos en:

• Si la memoria de video puede acomodar pesos de modelo y contexto común;
• Si el modelo es un modelo de instrucción/chat o de código especializado;
• Si puede cumplir de manera estable con los requisitos de modificación de archivos, pruebas y ejecución de comandos;
• Si admite las llamadas a herramientas o la salida JSON que necesita;
• ¿Es fácil desviarse, olvidar restricciones o producir modificaciones incompletas en tareas largas?

El modelo local 7B/8B es adecuado para exploración de almacenes, scripts simples, organización de documentos y modificaciones locales. La refactorización de múltiples archivos, las reparaciones de prueba complejas y las tareas del Agente a largo plazo requieren mayores requisitos de modelo y hardware; No asuma que solo porque la API local se puede conectar, es adecuada para cambios automáticos de alto riesgo.

Una forma segura de empezar

Cuando utilice un modelo local para ejecutar Codex por primera vez, se recomienda restringir los permisos primero:

1

codex --oss --local-provider ollama --sandbox read-only

Deje que el modelo complete primero la tarea de solo lectura:

1

分析当前仓库的目录结构，指出启动命令和测试命令。不要修改文件。

Después de confirmar que el modelo comprende el almacén y que la salida es estable, permita gradualmente la escritura en el espacio de trabajo y la ejecución de pruebas. No habilite el modo sin zona de pruebas ni el modo de omisión de aprobación directamente para guardar el paso de confirmación.

Preguntas frecuentes

1. codex exec --oss informa un error directamente

Normalmente no se especifica ningún proveedor local. usar:

1

codex exec --oss --local-provider ollama "只分析当前仓库，不修改文件"

O establezca oss_provider en la configuración a nivel de usuario.

2. Codex no puede conectarse a Ollama o LM Studio

Primero verifique los servicios por separado:

1
2

ollama ls
curl http://localhost:1234/v1/models

Luego verifique si el servicio se inició, si el modelo está cargado y si el puerto local se ve afectado por un firewall u otros procesos.

3. Los modelos locales siempre rompen el código

Primero reduzca la tarea: hágala de solo lectura para el análisis, cambie solo un archivo y proporcione el plan primero antes de ejecutarlo. Y use ramas de Git o confirme puntos para guardar el estado revertible. Cuando la capacidad del modelo es insuficiente, aumentar la complejidad de las palabras clave generalmente no puede resolver el problema fundamental.

4. La configuración se escribe pero no surte efecto.

Compruebe si el proyecto .codex/config.toml se escribió por error. La clave relacionada con el proveedor debe escribirse en el nivel de usuario ~/.codex/config.toml; reinicie el Codex después de la modificación.

Resumir

Para permitir que el Codex utilice grandes modelos locales, el orden de prioridad debería ser:

1
2
3
4
5

Ollama / LM Studio 跑通模型
-> codex --oss --local-provider ollama|lmstudio
-> 只读任务验证
-> 设置 oss_provider 作为默认
-> 再考虑 vLLM 等 OpenAI 兼容网关

Para la mayoría de los usuarios, --oss es la entrada más corta y controlable. openai_base_url es adecuado para escenarios avanzados que ya tienen puertas de enlace compatibles y requisitos de operación y mantenimiento, pero primero se debe configurar a nivel de usuario y verificar la compatibilidad de la interfaz.

referirse a:

• Proveedores locales en modo Codex OSS
• Referencia de configuración del Codex
• Comandos de desarrollador de Codex
• Tutorial de interfaz compatible con LM Studio OpenAI
• solución de problemas de memoria insuficiente de vLLM KV Cache