OpenCode API Key: Astra, Grok y configuración de proxy

Muchas consultas sobre autenticación en OpenCode parecen referirse a lo mismo, pero en realidad hablan de capas distintas. La API Key de un proveedor de modelos no es igual que el inicio de sesión de OpenCode Go, el OAuth de xAI ni la contraseña que protege opencode web.

Esta guía separa cada mecanismo y ofrece una configuración funcional de proveedor personalizado para BetterToken, un ejemplo listo para copiar con gpt-6-astra, ajustes de red para Linux y Astra Linux, autenticación directa de Grok, conexión con OpenCode Go y la forma correcta de proteger la interfaz Web de OpenCode.

OpenCode cambia con rapidez. Antes de usar esta configuración en producción, compara los comandos con la documentación actual de OpenCode y confirma el Model ID exacto en el catálogo de BetterToken.

Respuesta rápida

Lo que quieres hacer	Lugar o comando correcto
Guardar de forma interactiva una API Key	Ejecuta `/connect` dentro de OpenCode
Ver los proveedores guardados	Ejecuta `opencode auth list`
Definir proveedor, Base URL y modelos	`opencode.json` u `opencode.jsonc`
Usar BetterToken	Base URL: `https://www.bettertoken.ai/v1`
Usar GPT-6 Astra	Model ID: `gpt-6-astra`, si está disponible para tu cuenta
Iniciar sesión en OpenCode Go	`/connect` → OpenCode Go → `https://opencode.ai/auth`
Autenticar xAI/Grok directamente	`/connect` → xAI → OAuth de suscripción o API Key
Proteger OpenCode Web	Define `OPENCODE_SERVER_PASSWORD` antes de `opencode web`
Usar un proxy regional o corporativo	Define `HTTP_PROXY`, `HTTPS_PROXY` y `NO_PROXY`

Antes de empezar

Prepara lo siguiente:

una versión reciente de OpenCode;
una API Key separada para pruebas, en lugar de reutilizar una clave de producción;
el Model ID exacto que aparece en el catálogo del proveedor;
un repositorio pequeño de prueba donde el agente no pueda dañar archivos importantes;
acceso desde el terminal tanto al instalador de OpenCode como al endpoint de la API.

Trata la API Key como una contraseña. No pegues una clave real en un prompt, una captura, un Issue, un artículo ni un repositorio Git.

Instalar OpenCode

En macOS y Linux puedes usar el instalador oficial:

curl -fsSL https://opencode.ai/install | bash

También puedes instalarlo con npm:

npm install -g opencode-ai

En Windows, OpenCode recomienda WSL para obtener la mejor compatibilidad. La documentación también incluye Chocolatey y Scoop:

choco install opencode

scoop install opencode

Comprueba la instalación:

opencode --version

Debe mostrarse un número de versión. Si aparece command not found, vuelve a abrir el terminal y comprueba que el directorio de instalación esté incluido en PATH.

Las cuatro capas de autenticación

1. API Key del proveedor de modelos

Esta clave autoriza las solicitudes a BetterToken, xAI, OpenAI u otro proveedor. OpenCode puede guardarla mediante /connect o leerla desde una variable de entorno referenciada por el archivo de configuración.

2. Autenticación de OpenCode Go u OpenCode Zen

OpenCode Go y Zen son servicios de modelos operados por OpenCode. Su flujo abre https://opencode.ai/auth, donde inicias sesión, completas la configuración de facturación, copias una API Key y la pegas de nuevo en /connect.

Esa clave no está relacionada con tu clave de BetterToken.

3. Autenticación de xAI/Grok

El flujo actual de OpenCode para xAI admite una suscripción compatible mediante OAuth con código de dispositivo o una API Key de pago por uso de xAI. Es una conexión directa con xAI, no con BetterToken.

4. Contraseña de OpenCode Web

OPENCODE_SERVER_PASSWORD protege el servidor HTTP local y la interfaz del navegador mediante Basic Auth. No autoriza solicitudes a modelos y no sustituye una API Key de proveedor.

Cómo configurar una API Key en OpenCode

OpenCode admite JSON y JSONC. Los ejemplos oficiales suelen usar opencode.json; JSONC resulta útil cuando necesitas comentarios. Lo importante es que las credenciales y la definición del proveedor se gestionan por separado.

Método 1: guardar la clave con `/connect`

Inicia OpenCode dentro de una carpeta segura de prueba:

mkdir opencode-first-test
cd opencode-first-test
opencode

Dentro de la TUI, ejecuta:

/connect

Para BetterToken:

Selecciona Other.
Escribe bettertoken como provider ID.
Pega tu API Key de BetterToken en el campo de credenciales.
Después de añadir la configuración del proveedor, reinicia por completo OpenCode.

Las credenciales añadidas con /connect se almacenan en:

~/.local/share/opencode/auth.json

Comprueba que el proveedor esté registrado sin mostrar la clave:

opencode auth list

El provider ID usado en /connect debe coincidir exactamente con el ID del archivo de configuración. Si usaste bettertoken, la clave de configuración también debe ser bettertoken.

Método 2: configurar `opencode.json` u `opencode.jsonc`

Usa el archivo global cuando quieras disponer del proveedor en todos los proyectos:

~/.config/opencode/opencode.json

Si un repositorio necesita un modelo o endpoint propio, coloca opencode.json u opencode.jsonc en su raíz.

Este ejemplo completo usa BetterToken y el Model ID actual gpt-6-astra:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

Antes de usarlo, confirma que gpt-6-astra figure en el catálogo actual de BetterToken y esté habilitado para tu grupo de acceso. Si el catálogo muestra otro ID, sustituye tanto bettertoken/gpt-6-astra como la clave gpt-6-astra dentro de models.

No añadas /chat/completions manualmente a la Base URL. El adaptador construye la ruta de la solicitud.

Usar una variable de entorno en lugar de `/connect`

En macOS o Linux:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

En PowerShell:

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

Después referencia la variable en las opciones del proveedor:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

Es más seguro que escribir el secreto directamente en JSON. Si la variable no existe, OpenCode la sustituye por una cadena vacía y normalmente recibirás un error 401.

Por qué OpenCode puede ignorar tu configuración

OpenCode combina varias fuentes de configuración. Cuando un mismo campo entra en conflicto, la fuente cargada más tarde sustituye a la anterior. Para una instalación normal, el orden más relevante es:

valores remotos de la organización;
configuración global ~/.config/opencode/opencode.json;
archivo personalizado indicado por OPENCODE_CONFIG;
opencode.json u opencode.jsonc del proyecto;
contenido inline de OPENCODE_CONFIG_CONTENT;
ajustes administrados, que pueden prevalecer sobre los archivos del usuario.

Si OpenCode elige un modelo o endpoint inesperado, no borres archivos al azar. Localiza todas las configuraciones activas y compara:

el valor superior model;
provider.bettertoken.options.baseURL;
las claves de provider.bettertoken.models;
OPENCODE_CONFIG y OPENCODE_CONFIG_CONTENT en la sesión actual.

Reinicia OpenCode después de modificar el proveedor.

OpenCode Astra: ¿modelo o Astra Linux?

La consulta “OpenCode Astra” puede referirse a dos cosas distintas.

Usar GPT-6 Astra en OpenCode

Si te refieres al modelo de OpenAI, usa el API ID exacto gpt-6-astra. Con el proveedor BetterToken anterior, selecciona:

bettertoken/gpt-6-astra

Abre el selector de modelos:

/models

Si no aparece, revisa el provider ID, el mapa models, el grupo de acceso de BetterToken y el catálogo actual. No deduzcas el Model ID a partir del nombre visible.

Ejecutar OpenCode en Astra Linux

La documentación de OpenCode incluye métodos de instalación para Linux, pero no ofrece una garantía específica para Astra Linux. Trátalo como un entorno Linux y valida la máquina y la versión concreta de la distribución.

Comprueba la arquitectura y las herramientas necesarias:

uname -m
command -v curl
command -v bash

Prueba por separado el instalador y las rutas de la API. Que la API del modelo responda no significa que también estén disponibles el instalador, npm Registry, GitHub o el servidor de actualizaciones.

Para un proxy estándar:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXY es importante porque la TUI se comunica con un servidor HTTP local de OpenCode. Enviar el tráfico loopback al proxy puede provocar bucles de red, errores de conexión o una interfaz aparentemente bloqueada.

Si tu organización utiliza una autoridad certificadora privada:

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

No escribas credenciales reales del proxy en scripts compartidos. Usa variables protegidas o el gestor de secretos de la organización.

OpenCode Grok auth: ¿xAI directo o gateway?

Conexión directa con xAI

Ejecuta:

/connect

Selecciona xAI. La documentación actual de OpenCode ofrece dos métodos:

una suscripción xAI compatible mediante OAuth con código de dispositivo;
introducir manualmente una API Key creada en xAI Console.

Después de autorizar, ejecuta:

/models

y elige un modelo Grok disponible.

Grok mediante BetterToken u otro gateway

Un gateway personalizado solo funciona si realmente ofrece en ese momento un modelo Grok válido y el protocolo necesario. No inventes un Model ID de Grok ni des por hecho que todos los gateways compatibles con OpenAI incluyen modelos de xAI.

Consulta primero el catálogo en vivo. Si Grok no aparece, usa el proveedor xAI directo de OpenCode. Los plugins comunitarios de Grok auth son una vía distinta; antes de instalarlos revisa su mantenimiento, permisos y tratamiento de credenciales.

Qué significa OpenCode Go auth

OpenCode Go no es un comando general para autenticar cualquier proveedor. Es un servicio de suscripción de OpenCode.

Para conectarlo:

Ejecuta /connect.
Selecciona OpenCode Go.
Abre https://opencode.ai/auth.
Inicia sesión, completa la facturación si es necesario y copia la clave generada.
Pégala de nuevo en OpenCode.
Ejecuta /models y elige un modelo incluido en el plan.

Utiliza este flujo solo para OpenCode Go. Para BetterToken, conserva el provider ID y la clave bajo bettertoken.

Contraseña de OpenCode Web: usa la variable de entorno

Al buscar opencode web password aparecen ejemplos no oficiales que sugieren un parámetro -p. El método documentado es la variable OPENCODE_SERVER_PASSWORD.

En macOS o Linux:

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

Para cambiar también el usuario:

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

En PowerShell:

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

El usuario predeterminado es opencode. Para uso exclusivamente local en 127.0.0.1, la necesidad de contraseña depende del entorno, pero el acceso de red debe estar protegido. No enlaces el servicio a 0.0.0.0 ni lo publiques mediante un túnel antes de configurar autenticación y controles de red.

La contraseña Web protege el servidor de OpenCode. No protege la cuenta del proveedor si la API Key se filtra por otro medio.

Verificar la primera solicitud

Reinicia OpenCode después de editar JSON:

opencode

Abre el selector:

/models

Elige bettertoken/gpt-6-astra y envía un prompt breve y fácil de comprobar:

Devuelve únicamente este JSON y no modifiques ningún archivo: {"tool":"opencode","sum":4}

La configuración se considera correcta cuando:

OpenCode devuelve JSON válido;
no cambia ningún archivo del proyecto;
el modelo seleccionado es bettertoken/gpt-6-astra;
aparece una solicitud correspondiente en el Dashboard de BetterToken;
modelo, estado, tokens de entrada, tokens de salida y cargo son razonables.

Si OpenCode responde pero no aparece ninguna solicitud en BetterToken, una configuración de mayor prioridad puede estar enviando el tráfico a otro proveedor.

Solución de problemas

Error `401` o de credenciales

Repite /connect con provider ID bettertoken.
Ejecuta opencode auth list.
Si usas {env:BETTERTOKEN_API_KEY}, comprueba solo que la variable exista; no imprimas el secreto.
Confirma que la clave siga activa y tenga saldo o permisos suficientes.

Error `404` o de ruta API

La Base URL de BetterToken debe ser:

https://www.bettertoken.ai/v1

No añadas /chat/completions manualmente.

`model not found`

Comprueba el ID actual exacto en el catálogo. El campo superior model y la clave dentro de models deben señalar al proveedor y modelo correctos.

Se usa otro endpoint o modelo

Revisa las configuraciones global, personalizada, de proyecto, inline y administrada. Después reinicia OpenCode y vuelve a seleccionar el modelo con /models.

OpenCode se bloquea al activar el proxy

Asegúrate de excluir las direcciones loopback:

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Web devuelve `Unauthorized`

Comprueba que el navegador use el usuario y la contraseña configurados. Revisa también si queda un valor antiguo de OPENCODE_SERVER_PASSWORD en el shell o si un proceso cliente heredó un valor distinto.

`opencode: command not found`

Vuelve a abrir el terminal, comprueba PATH y consulta la ubicación de binarios globales del gestor de paquetes. No instales OpenCode con varios gestores hasta saber qué ejecutable está activo.

FAQ

¿Cómo configuro una API Key en OpenCode?

El método interactivo recomendado es /connect. Para un proveedor personalizado, elige Other, introduce el provider ID y pega la clave. Aun así debes definir el proveedor y sus modelos en opencode.json u opencode.jsonc.

¿El archivo se llama `opencode.json` u `opencode.jsonc`?

OpenCode admite ambos formatos. Usa JSONC si necesitas comentarios. Evita varias configuraciones de proyecto en competencia salvo que entiendas cómo se combinan.

¿Dónde guarda OpenCode las API Keys?

Las credenciales añadidas mediante /connect se guardan en ~/.local/share/opencode/auth.json. No publiques, sincronices ni confirmes ese archivo en Git.

¿Puedo escribir la API Key directamente en la configuración?

OpenCode admite options.apiKey, pero un secreto literal dentro de un JSON seguido por Git es arriesgado. Prefiere /connect, {env:VARIABLE_NAME} o {file:path/to/secret}.

¿OpenCode Go auth es lo mismo que la autenticación del proveedor?

No. OpenCode Go es un servicio independiente. Las claves de BetterToken, xAI y otros proveedores permanecen separadas.

¿Cómo configuro la contraseña de OpenCode Web?

Define OPENCODE_SERVER_PASSWORD antes de ejecutar opencode web. El método oficial usa una variable de entorno, no un parámetro genérico -p.

¿Cómo autentico Grok en OpenCode?

Ejecuta /connect, selecciona xAI y usa el OAuth de suscripción compatible o introduce manualmente una API Key de xAI. Un gateway solo es válido si realmente incluye un modelo Grok.

¿“OpenCode Astra” significa GPT-6 Astra o Astra Linux?

Puede significar cualquiera de los dos. Para el modelo usa gpt-6-astra; para Astra Linux sigue la instalación de Linux y valida la red en esa distribución concreta.

¿Necesito VPN para usar OpenCode desde Rusia?

No existe una respuesta única: el instalador, GitHub, npm, la web de OpenCode y la API del modelo siguen rutas de red diferentes. Prueba cada una por separado y usa una configuración corporativa o regional permitida cuando sea necesario.