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

API local de LM Studio compatible con OpenAI en detalle

LM Studio puede convertir modelos cargados localmente en interfaces compatibles con OpenAI. Para proyectos existentes, generalmente no es necesario reescribir la lógica de llamada: cambie base_url del cliente OpenAI a la dirección local de LM Studio y luego cambie model al identificador del modelo en LM Studio.

Las direcciones más utilizadas son:

1

http://localhost:1234/v1

Es adecuado para conectarse a Python, JavaScript, C# u otro código de cliente OpenAI existente. Las siguientes instrucciones están en el orden “ejecutar primero y luego acceder al proyecto”.

Hablemos primero de la conclusión.

Para utilizar la interfaz compatible con OpenAI de LM Studio, solo necesita completar cuatro pasos:

1. Inicie el servidor local en la página Desarrollador de LM Studio.
2. Cargue un modelo de chat.
3. Solicite http://localhost:1234/v1/models, confirme la identificación del modelo.
4. Cambie el cliente base_url a http://localhost:1234/v1.

Escritura mínima en Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

response = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 KV cache。"}
    ],
)

print(response.choices[0].message.content)

api_key="lm-studio" es solo un valor de marcador de posición para OpenAI SDK cuando la autenticación no está habilitada; Si habilita el token API en la configuración del servicio LM Studio, debe cambiarse al token real.

Paso 1: inicie el servidor local de LM Studio

Abra LM Studio, ingrese a la página Desarrollador y active el interruptor Iniciar servidor. El servicio predeterminado escuchará:

1

http://localhost:1234

También puede utilizar la herramienta de línea de comandos de LM Studio para iniciar:

1

lms server start

Si lms no está disponible en su computadora, puede instalar la CLI de acuerdo con la documentación oficial de LM Studio:

1

npx lmstudio install-cli

El inicio del servicio solo significa que el puerto API está escuchando, pero no significa que exista un modelo sobre el cual se pueda razonar. Continúe cargando un modelo en la página de Chat o Desarrollador, o cárguelo con lms load.

Paso 2: obtenga primero la identificación del modelo

No adivine el parámetro model según el nombre del archivo. La forma más estable es solicitar una lista de modelos:

1

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

Se puede utilizar Windows PowerShell:

1

Invoke-RestMethod http://localhost:1234/v1/models

La lista data devuelta tendrá el identificador del modelo. Luego complete model con el ID real devuelto en la solicitud.

Este paso puede evitar dos problemas comunes: el modelo se descargó pero no se cargó, o el nombre escrito en el código no coincide con la ID del modelo expuesta actualmente por LM Studio.

Paso 3: Probar la finalización del chat con curl

Primera prueba con el endpoint compatible con OpenAI más intuitivo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的 LM Studio 模型 ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "解释什么是向量数据库。"}
    ],
    "temperature": 0.7
  }'

Cuando tiene éxito, la respuesta suele ser:

1

choices[0].message.content

Las finalizaciones de chat aplican automáticamente la plantilla de mensajes del modelo de chat. Siempre que el modelo en sí sea del tipo chat/instrucciones, normalmente no hay necesidad de empalmar manualmente tokens de control especiales en el lado del cliente.

Cómo reemplazar OpenAI con el proyecto Python

Si el proyecto utiliza originalmente el SDK de OpenAI Python, generalmente solo hay dos enfoques: base_url y model.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

completion = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "system", "content": "你是一名 Python 助手。"},
        {"role": "user", "content": "写一个读取 JSON 文件的最小示例。"},
    ],
    temperature=0.2,
    max_tokens=500,
)

print(completion.choices[0].message.content)

La ventaja de esto es que la capa de aplicación todavía usa los objetos y formatos de retorno del SDK de OpenAI, y el backend puede cambiar entre la API de OpenAI en la nube y el LM Studio local.

Pero “compatibilidad” no significa que todas las características del modelo de nube se puedan copiar tal cual. La disponibilidad de llamadas a herramientas, resultados estructurados, entradas visuales, contenido de inferencia y la API de Responses aún depende de la versión de LM Studio, las capacidades del modelo actual y la compatibilidad con los terminales correspondientes.

Salida de transmisión

Establezca stream=True en Finalizaciones de chat:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

stream = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[{"role": "user", "content": "写一首四行小诗。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

La salida de streaming es adecuada para interfaces de chat, herramientas de terminal y respuestas largas. Mejora la experiencia de espera del usuario y no hace que el modelo local se genere más rápido.

Cómo elegir entre incrustaciones, respuestas y API REST nativa

La capa de compatibilidad OpenAI de LM Studio incluye puntos finales comunes:

LM Studio también tiene su propia interfaz nativa. La ruta recomendada actualmente es /api/v1/*, como /api/v1/chat y /api/v1/models. La API nativa es más adecuada para proyectos que requieren carga/descarga de modelos, chat con estado, MCP o capacidades específicas de LM Studio.

Juicio simple: si ya tiene un proyecto OpenAI SDK, use /v1 primero; Si un nuevo proyecto requiere una gestión en profundidad de los modelos locales o utiliza las capacidades exclusivas de LM Studio, considere /api/v1.

Salida estructurada y llamadas a herramientas

La capa de compatibilidad OpenAI de LM Studio admite llamadas a herramientas y salida estructurada en los puntos finales correspondientes, pero primero confirme dos cosas:

1. El modelo que cargue debe tener capacidades confiables de llamada de herramientas o salida JSON.
2. Las versiones de LM Studio y el SDK del cliente deben ser lo suficientemente nuevas.

No asuma que el modelo puede generar de manera estable resultados que se ajusten al esquema solo porque no hay errores en la solicitud. Las pruebas deben realizarse utilizando parámetros reales, ramas anormales y múltiples rondas de solicitudes antes de conectarse.

Solución de problemas de errores comunes

1. Conexión rechazada o Connection refused

Primero confirme que el servidor en la página del desarrollador se haya iniciado y luego pruebe:

1

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

Si no puede conectarse aquí, primero verifique el puerto, si LM Studio aún se está ejecutando o si el software de seguridad local bloquea el puerto local.

2. 404 Not Found

La razón más común es que la ruta está escrita incorrectamente. Los puntos finales de chat compatibles con OpenAI son:

1

/v1/chat/completions

No /api/v1/chat/completions. Este último pertenece a otro conjunto de rutas API nativas.

3. El modelo no existe o se devuelve una lista vacía.

Primero cargue el modelo en LM Studio y luego verifique el retorno de /v1/models. model en el código debe utilizar el identificador devuelto real y no copiar los nombres de modelo de otras personas.

4. Puedo responder pero el formato es extraño.

Compruebe que esté cargado el modelo base en lugar del modelo de instrucción/chat; También verifique que LM Studio aplique automáticamente la plantilla de chat. Para llamadas a herramientas y resultados JSON, confirme también que el modelo realmente admita la capacidad.

5. No se puede acceder al dispositivo LAN

LM Studio puede configurar servicios para la red local en la página del desarrollador. Después de habilitar el acceso a la red, también debe confirmar la configuración del firewall, la dirección de escucha y el token API. No exponga servicios de modelos locales no autenticados directamente a la red pública.

Una lista de verificación de acceso mínimo

1
2
3
4
5
6
7

1. LM Studio Developer -> Start server
2. 加载一个 instruct/chat 模型
3. curl http://localhost:1234/v1/models
4. 客户端 base_url 改为 http://localhost:1234/v1
5. model 填实际返回的 ID
6. 用 chat/completions 跑通单轮请求
7. 再测试流式、工具调用、Embeddings 或结构化输出

Primero ejecute la solicitud mínima y luego conecte RAG, Agent o el complemento del editor; la solución de problemas será mucho más fácil.

Resumir

La interfaz compatible con OpenAI de LM Studio es adecuada para conectar modelos locales a proyectos OpenAI SDK existentes. Lo más importante no es copiar un fragmento de código, sino confirmar que se inicia el servicio, se carga el modelo, base_url apunta a /v1 y model usa la ID del modelo real.

Si lo que necesita es una gestión de modelos local más profunda, chat con estado o MCP, la interfaz nativa /api/v1/* de LM Studio será más adecuada; Si el objetivo es una rápida compatibilidad con proyectos antiguos, continuar usando /v1/chat/completions suele ser lo más fácil de hacer.

referirse a:

• Puntos finales de compatibilidad de LM Studio OpenAI
• Finalizaciones del chat de LM Studio
• Servidor API local de LM Studio
• API REST de LM Studio