Guía de configuración de OpenCode
Configuración de proveedor en opencode.jsonc, IDs de modelo por plan y cómo revisar errores comunes.
Al abrir opencode serve en el navegador es fácil quedarse atrapado en un diálogo infinito de Basic Auth o en una carga eterna con 401. Revisando entorno, curl, Network y proxy en orden se localiza el fallo en minutos.
Al arrancar opencode serve u opencode web en OpenCode 2.x y abrirlo en el navegador, es habitual tropezar con uno de estos dos bloqueos: o no configuraste contraseña y aun así la web gira sin fin devolviendo 401 Unauthorized, o pusiste contraseña, la escribiste bien y el diálogo de HTTP Basic Auth reaparece cada pocos segundos.
Reintentar en el navegador rara vez aclara qué pasa. Salir a la terminal y comprobar en orden variables de entorno, curl, la pestaña Network y el proxy inverso despeja la causa enseguida.
Dos detalles despistan casi siempre: dejar OPENCODE_SERVER_PASSWORD="" vacío no equivale a hacer unset, y cuando hay contraseña activa, OpenCode espera el usuario por defecto opencode.
Sin OPENCODE_SERVER_PASSWORD, el servidor debe funcionar sin contraseña. Pero si en .env o en tu perfil de shell quedó OPENCODE_SERVER_PASSWORD="" —o te topas con la regresión de anomalyco/opencode#50370—, los endpoints devuelven 401 Unauthorized sin abrir un inicio de sesión válido.
Si trabajas en local o en una red de confianza sin contraseña, elimina ambas variables antes de arrancar:
unset OPENCODE_SERVER_PASSWORDunset OPENCODE_SERVER_USERNAMEopencode servecurl antes de culpar al navegadorCuando sí quieres contraseña, lo que más suele fallar en el cuadro del navegador es el usuario: OpenCode fija por defecto opencode (OPENCODE_SERVER_USERNAME), no tu usuario del sistema ni un campo vacío.
Exporta ambos valores de forma explícita:
export OPENCODE_SERVER_USERNAME="opencode"export OPENCODE_SERVER_PASSWORD="your-password"opencode serveY prueba /global/health desde otra terminal:
curl -i -u opencode:your-password http://127.0.0.1:4096/global/healthcurl devuelve 200, servidor y credenciales están bien; el bucle viene de la caché del navegador o del proxy.v2 serve también responde 401 en curl, puede ser la regresión de #45856; actualiza OpenCode a la última versión.Si el primer acceso funciona pero al refrescar vuelve el aviso, revisa Network: peticiones como /site.webmanifest o /global/health pueden devolver 401 al recargar (#18325), y los gestores de contraseñas suelen fallar al rellenar diálogos nativos de Basic Auth.
opencode attachSi opencode serve está detrás de Nginx, Caddy o Cloudflare Access con su propio login y mantienes OPENCODE_SERVER_PASSWORD activo, ambos envían cabeceras WWW-Authenticate enfrentadas. Vincula opencode serve a 127.0.0.1 sin su propia contraseña para que autentique solo el proxy.
Y si el 401 aparece en otra terminal o en un SDK (#31254), pasa -p al conectar:
opencode attach http://localhost:4096 -p your-password| Síntoma | Qué comprobar primero |
|---|---|
| Carga infinita / 401 sin contraseña | Asegúrate de no tener OPENCODE_SERVER_PASSWORD="" y ejecuta unset |
| El navegador rechaza la contraseña correcta | Usa el usuario opencode y verifica con curl -u opencode:... |
| Bucle detrás de Nginx / Caddy / Cloudflare Access | Quita la contraseña propia de OpenCode y deja la auth en el proxy |
opencode attach o SDK reciben 401 | Añade -p <contraseña> o la cabecera Basic Auth |
Por último, recuerda que OPENCODE_SERVER_PASSWORD solo protege el servidor HTTP local de OpenCode, no tu clave de modelos. Para CodingPass, guarda tu clave aparte con opencode service set env CODINGPASS_API_KEY cp-live-... como indica la guía de OpenCode.
Deja opencode serve en local sin bucles 401 y apunta tu proveedor a CodingPass para usar Claude, GPT y modelos abiertos con pago por uso.