OpenCode también aparece en consultas cada vez más frecuentes sobre “codificación de IA”, “codificación de vibración”, “IA de código abierto” y “agente de codificación”.
El error de acceso más común no es la clave API, sino la desalineación del protocolo, el ID del proveedor y el nombre del modelo.
Primero confirme qué protocolo utiliza el upstream
/v1/chat/completions Generalmente usa @ai-sdk/openai-compatible.
/v1/responses Utilice @ai-sdk/openai.
“Compatible con OpenAI” no significa que ambos puntos finales estén implementados.
Primero confirme con la documentación anterior y una solicitud de rizo mínima.
|
|
No escriba la clave directamente en el historial del shell.
Credenciales separadas de la configuración
Ejecute /connect en OpenCode, seleccione Other.
Ingrese una ID de proveedor única, por ejemplo corp-gateway.
Este ID debe ser exactamente igual que opencode.json.
Solo ejecutar /connect solo guardará las credenciales y no generará automáticamente la configuración completa del proveedor.
Una configuración mínima
|
|
La clave del modelo debe ser un ID de modelo que la puerta de enlace realmente acepte.
El nombre para mostrar se puede personalizar pero no reemplaza la identificación real.
Agregar restricciones de contexto a modelos desconocidos
|
|
OpenCode utiliza estos valores para estimar el contexto restante.
No complete directamente el token total anunciado por el proveedor tanto en la entrada como en la salida.
Un límite superior de salida excesivo puede hacer que la solicitud sea rechazada por el flujo ascendente.
Personaliza el límite del encabezado
El enrutamiento de inquilino o puerta de enlace puede requerir encabezados adicionales.
Se pueden colocar valores estáticos no sensibles en la configuración.
La clave debe hacer referencia a una variable de entorno.
No deje el encabezado de identidad del usuario al Agente para que lo modifique gratuitamente.
La puerta de enlace debe derivar inquilinos a partir de información de autenticación confiable en lugar de confiar en los autoinformes del cliente.
Enrutamiento de puerta de enlace Vercel AI
Los ejemplos oficiales admiten opciones como order, only y zeroDataRetention.
order representa la secuencia de intentos del proveedor.
only Limitar proveedores disponibles.
zeroDataRetention se utiliza para filtrar rutas que cumplen con los requisitos de retención de datos.
La reversión no puede limitarse a mirar el código de estado HTTP.
Los errores de autenticación, el saldo insuficiente y los rechazos de políticas de contenido generalmente no deben cambiarse de proveedor a ciegas ni volver a intentarse.
Utilice tres solicitudes de aceptación
Envíe primero las preguntas y respuestas en texto sin formato.
Luego envíe tareas que requieran llamadas a herramientas.
Finalmente envíe una entrada larga cerca del límite del contexto.
Registre el nombre del modelo, el ID de la solicitud, el retraso del primer token y el total de tokens.
Si la puerta de enlace reescribe el nombre del modelo, tanto el valor de la solicitud como el valor de la ruta real deben conservarse en el registro.
Errores comunes
401: Las credenciales no se guardan, las variables de entorno no se ingresan en el proceso actual o el nombre del encabezado es incorrecto.
404: Escribe más o menos /v1 en baseURL, o puedes elegir el protocolo incorrecto.
400 unknown model: La clave de configuración no coincide con el ID del modelo ascendente.
La herramienta no funciona: upstream solo es compatible con formatos de texto y no implementa completamente las llamadas a herramientas.
Desbordamiento prematuro del contexto: limit.context no coincide con el modelo real.
Comando de solución de problemas
|
|
Confirme que la entrada de credencial existe, pero no imprima la clave real.
Luego use /models para verificar si aparece el modelo.
La misma solicitud se ejecuta una vez llamando a la puerta de enlace directamente y una vez a través de OpenCode.
Si la solicitud directa tiene éxito pero OpenCode falla, concéntrese en verificar la configuración y el protocolo SDK.
Si ambas partes fallan, verifique primero la puerta de enlace y la cuenta.
Configuración de múltiples entornos
Las puertas de enlace de desarrollo, prueba y producción utilizan diferentes ID de proveedor.
Por ejemplo corp-dev y corp-prod.
Los ID de producción no aparecen en las configuraciones de desarrollo personal de forma predeterminada.
CI utiliza credenciales a corto plazo y no reutiliza el token local del desarrollador.
Después de cambiar el entorno, ejecute primero la tarea de solo lectura para confirmar que no hay ninguna conexión errónea con la producción.
Seguridad y control de costes
Establezca el presupuesto y la tarifa para cada clave en el lado de la puerta de enlace.
Registrar cargos por proveedor, modelo, almacén y usuario.
Enmascaramiento de registros Autorización y credenciales cuando se le solicite.
Limite los archivos y comandos a los que puede acceder el Agente.
El enrutamiento API exitoso no significa que la ejecución de la herramienta local sea segura.
Lista de verificación de aceptación
-
Confirmar el protocolo de respuestas o finalización del chat.
-
/connectEl ID es exactamente el mismo que el de la configuración. -
baseURL contiene
/v1solo una vez. -
El ID del modelo es consistente con la puerta de enlace.
-
las restricciones de contexto/salida provienen de documentos reales.
-
La política alternativa distingue entre errores reintentables y no reintentables.
-
Las credenciales no están en JSON y Git.
-
Los tres tipos de solicitudes guardan el ID de la solicitud y la ruta real.
Documento de configuración del proveedor
Primero use un script separado para verificar el protocolo de puerta de enlace
Antes de conectarse a OpenCode, confirme la autenticación de la puerta de enlace, el nombre del modelo y el formato de respuesta con solicitudes mínimas. A continuación se muestra un ejemplo del punto final de finalización de chat:
|
|
Si esta solicitud falla, resuelva primero el problema de la puerta de enlace. Tiene éxito y OpenCode falla antes de verificar la configuración del proveedor y el paquete AI SDK.
La API de respuestas no puede simplemente reemplazar la URL
Las entradas, las definiciones de herramientas y los eventos de transmisión de la API de Respuestas no son idénticos a las Finalizaciones de Chat. Cuando el flujo ascendente solo proporciona /v1/responses, reemplace el paquete npm del proveedor con @ai-sdk/openai y verifique si la puerta de enlace transmite el protocolo de manera transparente.
No reenvíe dos cuerpos de solicitud directamente al mismo controlador en un proxy inverso. Si bien las solicitudes de texto aparentemente simples pueden tener éxito, las llamadas a herramientas y las solicitudes multimodales se corrompen sobre la marcha.
Usar variables de entorno para hacer referencia a la clave API
Antes de enviar la configuración del proyecto a Git, busque si contiene credenciales reales:
|
|
El nombre de la variable de entorno local debe reflejar su propósito, como CORP_GATEWAY_KEY, y no reutilizar el ambiguo API_KEY. CI, PC y VPS utilizan claves diferentes respectivamente.
Verificar salida de streaming
Una vez que la respuesta normal sea exitosa, pruebe respuestas más largas y llamadas a herramientas. Compruebe si el primer evento, el texto incremental, el motivo final y el uso final están completos.
El servidor proxy debe desactivar el almacenamiento en búfer de respuestas innecesario y establecer el tiempo de espera de lectura para que sea mayor que el tiempo de espera de la tarea del modelo. De lo contrario, OpenCode mostrará una desconexión mientras el modelo aún se esté ejecutando.
¿Qué pasará si el límite superior del contexto se escribe incorrectamente?
Cuando el valor de configuración es mayor que el límite superior real, OpenCode piensa que todavía hay espacio, pero el flujo ascendente devuelve que el contexto es demasiado largo. Cuando el valor de configuración es demasiado bajo, el cliente comprime o descarta contenido útil prematuramente.
Utilice muestras de tokens fijos para aumentar la entrada paso a paso y registrar los puntos de rechazo reales de la puerta de enlace. También se deducen las indicaciones del sistema, las definiciones de herramientas y las salidas reservadas, en lugar de solo los archivos del usuario.
Los alias de modelos requieren gestión de versiones
Las puertas de enlace a menudo apuntan coding-model a servidores que se actualizan continuamente. Esto facilita el cambio, pero producirá resultados diferentes para la misma configuración.
Los flujos de trabajo de producción utilizan alias versionados, como coding-model-2026-07. Cree un nuevo alias al actualizar y cambie a la ruta predeterminada después de ejecutar el almacén de prueba y devolverlo.
Mantener la compatibilidad de capacidades durante la reversión
El modelo principal admite llamadas a herramientas y contextos largos, y el modelo alternativo también debe cumplir con las capacidades mínimas de la tarea. Si el modelo alternativo solo admite texto, debería fallar explícitamente y no devolver el JSON de la herramienta al Agente como texto normal.
Registre supports_tools, supports_vision, contexto, salida y política de retención de datos para cada ruta. Cuando elijas regresar, filtra por habilidad y prueba en orden.
Reglas de desensibilización para registros de agentes
Conserve el ID de la solicitud, el inquilino, el modelo, el código de estado, el token y el tiempo transcurrido. Elimine la autorización y el texto del mensaje no se incluirá en el registro centralizado de forma predeterminada.
Si debe probar el texto durante la depuración, utilice una cuenta de prueba dedicada, un período de retención corto y almacenamiento limitado. Después de la depuración, cierre el muestreo y elimine los datos temporales.
Cerrar conexión y reintentar estrategia
Los tiempos de espera de conexión se pueden reintentar de forma limitada; Los errores de autenticación, los errores de parámetros y los rechazos de políticas de contenido no se vuelven a intentar. 429 Decida si desea esperar según Retry-After y el presupuesto.
Cuando la herramienta de escritura ya se está ejecutando y la respuesta del modelo se interrumpe, no se vuelve a ejecutar toda la tarea. Restaure la interacción o verifique primero el árbol de trabajo para evitar modificaciones repetidas.
Prueba de humo de cinco minutos después de cambios de configuración
Ejecute /models, preguntas y respuestas de texto breve, tarea de archivo de solo lectura y una pequeña tarea que requiere la llamada de herramientas en secuencia. Confirme que el modelo que se muestra en la interfaz sea coherente con el modelo real en el registro de la puerta de enlace.
Luego ingrese deliberadamente un nombre de modelo que no existe. El sistema debería devolver errores de configuración explícitos en lugar de redirigir silenciosamente a costosos modelos predeterminados.
Finalmente, abra una nueva terminal y vuelva a realizar la prueba para eliminar el éxito falso causado por variables de entorno temporales de la sesión actual. Los resultados de las pruebas se guardan con la diferencia de configuración para una fácil reversión.
Si la prueba de humo falla, restaure el opencode.json anterior y los alias del modelo bloqueado, y no continúe superponiendo modificaciones de configuración en el estado de falla.