OpenCode en Rusia: configuración de API y primera solicitud

Qué necesitas para iniciar OpenCode en Rusia

OpenCode es un agente de programación para terminal. Lee archivos del proyecto, trabaja con el modelo elegido y puede actuar en el repositorio. Para el primer inicio necesitas:

• macOS, Linux o Windows con acceso a una instalación oficial;
• tu propia API Key de BetterToken;
• el Model ID actual del catálogo BetterToken;
• un directorio de prueba para revisar la respuesta con seguridad.

BetterToken gestiona aquí la solicitud API externa. No garantiza la disponibilidad del sitio de OpenCode, el instalador, GitHub o las actualizaciones. Desde Rusia puedes conectarte al BetterToken API Endpoint sin VPN; esto no cubre sitios ni descargas de terceros.

Instalar OpenCode desde la fuente oficial

Elige un método. Node.js solo hace falta para instalar con npm.

macOS y Linux: instalador oficial

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

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

OpenCode recomienda su propio tap, porque la fórmula brew install opencode mantenida por Homebrew puede cambiar después.

Windows

La documentación oficial propone Chocolatey o Scoop:

choco install opencode

scoop install opencode

Después comprueba que el comando esté disponible:

opencode --version

La versión debe imprimirse sin command not found. No se fija un número porque cambia con los lanzamientos.

Cómo funcionan /connect y opencode.json

OpenCode almacena por separado las credenciales y los ajustes de provider.

• /connect guarda la API Key en ~/.local/share/opencode/auth.json.
• El archivo global ~/.config/opencode/opencode.json define providers y modelos del usuario.
• opencode.json en la raíz del proyecto modifica solo ese proyecto.

Los archivos de configuración se combinan. Si hay conflicto, la fuente posterior sustituye a la anterior. Para una configuración local normal, importa este orden: configuración global → archivo de OPENCODE_CONFIG → opencode.json del proyecto. Los ajustes administrados por una organización tienen una prioridad superior independiente.

1. Guardar la API Key con /connect

Inicia OpenCode en el directorio de prueba:

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

En la TUI ejecuta:

/connect

Elige Other, escribe el id de provider bettertoken y pega tu API Key en el campo credential. No pongas la clave real en el prompt, opencode.json, una captura ni Git.

Tras guardarla, sal de OpenCode y confirma que el provider está registrado:

opencode auth list

El comando debe mostrar el provider sin revelar la clave.

2. Añadir el provider BetterToken

Para configurarlo en todos los proyectos, crea o actualiza:

~/.config/opencode/opencode.json

Si solo lo necesitas en un repositorio, coloca opencode.json en su raíz. Configuración mínima:

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

Sustituye YOUR_MODEL_ID por el ID exacto del catálogo actual. El mismo valor debe estar en model, en la clave de models y en su name. No añadas /chat/completions a la Base URL: OpenCode y @ai-sdk/openai-compatible generan la solicitud.

Los comandos detallados de configuración automática y las restricciones actuales de grupos de modelos están en la documentación BetterToken para OpenCode. El Model ID queda como marcador porque la lista cambia.

3. Comprobar qué archivo tiene prioridad

El opencode.json del proyecto puede sustituir el modelo o provider global. Si OpenCode elige un endpoint inesperado, revisa:

1. ~/.config/opencode/opencode.json;
2. el valor de OPENCODE_CONFIG, si existe;
3. opencode.json del proyecto actual o del directorio padre más cercano hasta la raíz Git.

No borres archivos al azar. Compara model, provider.bettertoken.options.baseURL y provider.bettertoken.models en cada configuración encontrada.

Ejecutar y probar la primera solicitud

Reinicia OpenCode después de cambiar el JSON:

opencode

Abre el selector de modelos con:

/models

Selecciona bettertoken/YOUR_MODEL_ID y envía una consulta corta y verificable:

Devuelve solo JSON: {"tool":"opencode","sum":4}. No modifiques archivos.

La primera solicitud queda confirmada cuando coinciden cuatro comprobaciones:

• OpenCode devuelve JSON válido y no modifica archivos;
• en la TUI está seleccionado bettertoken/YOUR_MODEL_ID;
• aparece en BetterToken Dashboard una solicitud con el modelo y estado esperados;
• el Dashboard muestra tokens de entrada, salida, caché aplicable y el cargo correspondiente.

El Dashboard no debe guardar el prompt o la respuesta completa: aquí se refiere a metadatos de uso y consumo de tokens. Si no aparece la entrada, la respuesta puede haber llegado de otro provider por una sustitución de configuración.

Corregir errores frecuentes

opencode: command not found

Cierra y vuelve a abrir la terminal. Si instalaste con npm, comprueba que el directorio global de npm esté en PATH. No ejecutes un segundo instalador antes de saber dónde se instaló el primer binario.

401 o error de credential

Ejecuta /connect de nuevo y selecciona bettertoken. Compruébalo mediante opencode auth list. No pegues la clave en la línea de comandos ni en JSON para probar rápido.

404 o error de API

provider.bettertoken.options.baseURL debe contener:

https://www.bettertoken.ai/v1

No añadas /chat/completions. Si la URL es correcta, reinicia OpenCode y repite la solicitud corta.

model not found

Comprueba el Model ID exacto en la documentación y el catálogo actuales. El campo superior model debe ser bettertoken/YOUR_MODEL_ID, y provider.bettertoken.models debe tener una clave con el mismo YOUR_MODEL_ID.

OpenCode usa otro modelo o endpoint

Normalmente significa que existe una sustitución de configuración. Compara el archivo global, OPENCODE_CONFIG y el archivo del proyecto. El proyecto tiene la mayor prioridad entre archivos estándar. Tras corregirlo, reinicia por completo OpenCode y comprueba otra vez /models y el Dashboard.

Preguntas frecuentes

¿Debo guardar la API Key en opencode.json?

No. Para una configuración normal usa /connect: OpenCode guarda la credencial en ~/.local/share/opencode/auth.json. El archivo de configuración puede quedar sin la clave real.

¿Qué Base URL necesita OpenCode?

Para el provider OpenAI-compatible BetterToken se usa https://www.bettertoken.ai/v1. Es una Base URL, por lo que no se añade /chat/completions manualmente.

¿Elegir opencode.json global o de proyecto?

El global sirve para un provider y modelo comunes. Un archivo de proyecto es apropiado si el repositorio necesita otro Model ID o permisos. Si hay conflicto, el archivo de proyecto sustituye al global.

¿Necesito una cuenta de OpenCode para el provider BetterToken?

Un Custom Provider usa la credencial del servicio API elegido. BetterToken proporciona tu propia API Key, pero no sustituye el sitio, la cuenta ni otros servicios de OpenCode. Consulta los requisitos actuales de la herramienta en la documentación oficial de OpenCode.