OpenCode Claude Agent: configuración, límites y condiciones
Conecta OpenCode V2 a tu instalación local de Claude Code, comprueba la cuenta activa y prueba una tarea pequeña. Aprende quién ejecuta las herramientas, cómo se distinguen los límites de la suscripción y la facturación de la API, qué dicen OpenCode y Anthropic sobre el permiso y cuándo conviene conectarse con una clave API, directamente o mediante un proveedor compatible.
Índice
Usa el proveedor OpenCode Claude Agent a través de tu propia instalación local de Claude Code. Instala ambas herramientas, ejecuta claude auth login y elige Claude Agent en /connect. Elige una clave API si tu equipo necesita una vía de autenticación para terceros claramente documentada.
A fecha de 2026-11-05, OpenCode ofrece una guía específica de configuración de Claude Agent. El proveedor usa la autenticación activa de Claude Code, por lo que seleccionarlo no activa automáticamente la facturación mediante la suscripción.
¿Qué cambia con Claude Agent?
Claude Agent proporciona la interfaz y la ejecución de herramientas de OpenCode, mientras Claude Code se comunica con el modelo. OpenCode llama al claude instalado mediante el Claude Agent SDK de Anthropic.
El proveedor integrado llegó en OpenCode v2.2.3. La versión v2.2.4 añadió la configuración guiada al selector de proveedores de la aplicación. No necesitas un plugin de suscripción aparte.
El diseño del proveedor asigna a OpenCode las operaciones con archivos, los comandos de shell y los permisos. Las herramientas integradas de Claude Code están desactivadas.
OpenCode también ejecuta la compactación del contexto y los subagentes, según la guía actual de Claude Agent. La integración no carga la configuración nativa, los hooks, los servidores MCP, las habilidades (skills) ni la memoria de Claude Code. Los hooks son acciones asociadas a eventos.
Por tanto, las instrucciones y herramientas de OpenCode determinan cómo se trabaja en el proyecto. Revísalas antes de permitir cambios o comandos. Si dependes de los hooks nativos o los equipos de agentes de Claude Code, sigue usándolo hasta tener un flujo equivalente.
Este proveedor resulta útil si quieres conservar la interfaz de OpenCode y su forma de cambiar de modelo. Instalarlo no reproduce toda la experiencia de Claude Code.
Instala y conecta Claude Agent
Usa OpenCode V2 y Claude Code en la misma máquina que ejecuta el servidor de OpenCode. Este proveedor no está disponible en los espacios de trabajo remotos de OpenCode.
La vía de suscripción requiere un plan individual Pro, Max o Ultra activo.
Instala las versiones correctas
Instala OpenCode V2; la función requiere como mínimo v2.2.3. Usa v2.2.4 o posterior para la configuración guiada en la aplicación.
Estos comandos son para Bash en macOS, Linux o WSL. Siguen las instrucciones de instalación de OpenCode V2 y las instrucciones de instalación de Claude Code:
curl -fsSL https://opencode.ai/v2/install | bash
curl -fsSL https://claude.ai/install.sh | bashAbre un terminal nuevo y comprueba ambas versiones:
opencode --version
claude --versionClaude Code debe ser 2.1.248 o posterior, según la comprobación de versión del proveedor. Actualiza las instalaciones nativas antiguas con claude update. Si lo instalaste con un gestor de paquetes, usa ese gestor para actualizarlo.
Si ya usas V1, consulta primero la guía de migración a V2. Ambas versiones usan el comando opencode y comparten las ubicaciones de configuración.
La instalación no incluye uso de los modelos. Consulta las opciones de instalación, suscripción y acceso API de Claude Code si todavía no has elegido una modalidad de acceso.
Inicia sesión y comprueba la cuenta
Autentícate mediante el inicio de sesión propio de Claude Code. Selecciona la cuenta de tu suscripción si quieres consumir su uso incluido:
claude auth login
claude auth status --textConfirma que el estado identifica la cuenta y el método de autenticación previstos. La referencia de CLI distingue esta opción de claude auth login --console, que selecciona la facturación API de Console.
Antes de probar la suscripción, comprueba si hay credenciales heredadas en el entorno. Anthropic documenta que las claves API del entorno pueden tener prioridad sobre la autenticación por suscripción. Si hay una clave antigua configurada por error en tu shell personal, elimina esa variable:
unset ANTHROPIC_API_KEY
claude auth status --textComprueba también si ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL o los ajustes de un proveedor en la nube están configurados por error. Consulta el orden de prioridad de autenticación de Anthropic. Iniciar sesión con una suscripción no anula todas las demás credenciales.
Revisa providers.claude-agent.settings en la configuración de OpenCode por si contiene apiKey, authToken o baseURL. Los ajustes específicos del modelo también importan. La implementación de la conexión aplica estos ajustes después del entorno del servidor.
Conecta el proveedor y comprueba una solicitud real
Inicia un servidor privado de OpenCode para la primera comprobación:
opencode --standaloneEl modo standalone usa un servidor privado. Así se aplica el entorno del shell actual, sin depender de un servicio compartido que ya esté en ejecución. Este modo no elimina los ajustes definidos en la configuración.
Dentro de OpenCode, ejecuta /connect y selecciona Claude Agent. Después, ejecuta /models y elige uno de los modelos que devuelve Claude Code. Las referencias del proveedor pueden usar alias como claude-agent/opus; no supongas que coinciden con los identificadores de modelos de la API directa.
En la aplicación, la configuración guiada ofrece instalación, inicio de sesión, comprobación de conexión y recuperación ante errores. Si la comprobación funciona, continúa con la selección del modelo. Estos controles de la aplicación son distintos de las instrucciones de terminal anteriores.
Usa un repositorio que contenga README.md y envía:
Read README.md and summarize the project in three sentences. Do not modify files or run shell commands.La solicitud pide resumir el proyecto en tres frases sin editar archivos ni ejecutar comandos. Comprueba que OpenCode muestre una llamada de lectura de archivos y una respuesta pertinente. Así verificas el acceso al modelo y la devolución del resultado de la herramienta.
Un selector con modelos no basta: la comprobación de conexión no envía una solicitud al modelo.
Define OPENCODE_CLAUDE_PATH si falla la detección
Indica al servidor el ejecutable real de Claude Code si su PATH no encuentra la instalación deseada. Primero, confirma que command -v claude devuelve el ejecutable correcto en tu terminal.
Para otra comprobación con un servidor privado:
export OPENCODE_CLAUDE_PATH="$(command -v claude)"
opencode --standalonePara el servicio compartido en segundo plano, usa su entorno administrado:
opencode service set env OPENCODE_CLAUDE_PATH "$(command -v claude)"Cambiar el entorno del servicio detiene el servicio en ejecución. El siguiente comando que necesite el servidor local lo inicia con el nuevo valor. Vuelve a conectar Claude Agent y repite la solicitud pequeña.
Las instrucciones sobre el entorno del servidor explican por qué cambiar solo el terminal del cliente puede ser insuficiente.
¿Qué cuota consume Claude Agent?
Planifica el gasto según la credencial activa de Claude Code. Con autenticación por suscripción, considera las solicitudes de Claude Agent parte de tu cuota existente de Claude.
OpenCode documenta que esta vía está cubierta por la suscripción. Anthropic confirma que Claude y Claude Code comparten los límites del plan. De ambas reglas se deduce que cambiar de interfaz no crea una segunda cuota.
Distingue estos tres casos:
| Autenticación de Claude Code | Cómo se paga el uso |
|---|---|
| Suscripción de Claude | Cuota incluida en el plan, con sus límites; créditos de uso de pago si están activados |
| Cuenta de Anthropic API o de un proveedor en la nube compatible | Facturación y límites API de esa cuenta |
| Pasarela personalizada | Reglas de facturación de la cuenta de esa pasarela |
No interpretes una estimación de costo vacía como prueba de uso gratuito. La lógica de costos del proveedor también omite las estimaciones para URL base personalizadas.
Consulta el consumo y cuándo se restablecen los límites en Claude Settings > Usage. La vista nativa /usage de Claude Code no está disponible dentro de OpenCode. Revisa también los créditos de uso de pago: activarlos puede generar cargos adicionales tras agotar el uso incluido.
Para elegir la modalidad de acceso, compara las suscripciones de Claude y la facturación API.
¿Qué establecen las condiciones de uso?
Evalúa el permiso para la implementación y el uso concretos. Utilizar el SDK oficial no concede automáticamente a cualquier aplicación externa acceso a las credenciales de una suscripción.
Los tres documentos abordan situaciones distintas:
| Fuente oficial | Qué dice | Qué implica para esta configuración |
|---|---|---|
| Página de proveedores de OpenCode para versiones anteriores | Advierte que Anthropic prohíbe los plugins de suscripciones Pro/Max y que OpenCode dejó de incluirlos en 1.3.0. | Esta advertencia histórica sobre plugins no describe la implementación del nuevo proveedor V2. |
| Descripción general de Anthropic Agent SDK | Los desarrolladores externos necesitan aprobación previa para ofrecer el inicio de sesión o los límites de uso de Claude en sus productos. | Usar el SDK no demuestra por sí solo que exista permiso. |
| Condiciones legales y de cumplimiento de Claude Code | Restringe la intermediación de credenciales por terceros, pero permite iniciar sesión con la suscripción propia en un binario de Claude Code sin modificar. | Conserva el inicio de sesión nativo; no extiendas esta excepción al uso conjunto de credenciales ni a un nuevo servicio comercial. |
También hay una declaración sobre esta implementación. El 2026-10-30, Tarquinen, autor del PR, afirmó que Anthropic había dado permiso y describió la integración como conforme con las condiciones. Esa afirmación corresponde al colaborador de OpenCode. No es un documento emitido por Anthropic que defina el alcance de la aprobación.
Para uso personal, utiliza tu propia cuenta en la instalación de Claude Code sin modificar. No exportes tokens de sesión a otro plugin. Para una implantación empresarial o una integración en un producto, solicita confirmación para ese caso o usa la vía documentada con clave API.
Que la autenticación funcione demuestra que una solicitud puede completarse. No establece que las condiciones permitan cualquier despliegue.
Resuelve el fallo que realmente aparece
Relaciona el síntoma con su causa y repite la solicitud pequeña que lee un archivo.
| Síntoma | Comprobación y siguiente paso |
|---|---|
Claude Code is not installed | Instálalo en la máquina del servidor de OpenCode o define allí OPENCODE_CLAUDE_PATH. Vuelve a conectar. |
Claude Code is not logged in | Ejecuta claude auth login en esa máquina con el mismo usuario. Comprueba el estado y vuelve a conectar. |
El error indica 2.1.248 or later is required | Actualiza Claude Code y confirma la versión del ejecutable antes de reintentar. |
| Está conectado, pero no hay modelos o ninguna respuesta funciona | Comprueba el ejecutable y el inicio de sesión del servidor. Vuelve a conectar; detectar modelos no demuestra que las solicitudes funcionen. |
Los errores de conexión documentados cubren la falta de instalación y de inicio de sesión. Si una solicitud alcanza el límite del plan, consulta la página de uso de la cuenta. Volver a conectar no repone la cuota.
¿Cuándo conviene usar una clave API?
Elige una clave API si necesitas facturación separada, un servidor sin Claude Code local o la autenticación documentada para un producto de terceros. Mantén su presupuesto y sus límites separados de la suscripción de Claude.
Acceso directo a la API de Anthropic
Crea tu propia clave en Claude Console. En OpenCode, selecciona Anthropic mediante /connect y usa la autenticación con clave API.
El comando de autenticación de V2 equivalente solicita el secreto de forma interactiva:
opencode auth login anthropic --method key
opencode run --standalone --model anthropic/claude-sonnet-5-5 "Reply with only: OK"Comprueba que recibes una respuesta OK y que el uso corresponde a la cuenta API prevista. Si seleccionaste otra cuenta o modelo, corrígelo mediante /connect o /models antes de reintentar.
Una vía API compatible con OpenAI
A fecha de 2026-11-05, BetterToken también incluye claude-sonnet-5-5 y claude-opus-5-5 en su catálogo. Su integración documentada con OpenCode usa una API compatible con OpenAI y tu propia clave de BetterToken. Este acceso API se factura por separado.
Crea una clave en tu espacio de trabajo. Para una configuración nueva de V2, añade este proveedor al archivo opencode.jsonc del proyecto, conservando los demás ajustes:
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"bettertoken": {
"name": "BetterToken",
"env": ["BETTERTOKEN_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "https://www.bettertoken.ai/v1"
},
"models": {
"claude-sonnet-5-5": {
"name": "Claude Sonnet 5.5"
}
}
}
}
}El ejemplo sigue el formato nativo de proveedores personalizados de V2. Usa providers, package y settings; no mezcles los nombres de campos de V1 dentro de esta entrada.
Introduce la clave sin mostrarla en pantalla y ejecuta la comprobación en el mismo terminal Bash:
read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
opencode run --standalone --model bettertoken/claude-sonnet-5-5 "Reply with only: OK"El resultado esperado es una respuesta normal que contenga OK. Después, revisa la solicitud y el cargo en el espacio de trabajo. Si ya guardaste una cuenta de BetterToken en OpenCode, comprueba cuál está activa: las cuentas guardadas tienen prioridad sobre las conexiones del entorno.
Revisa los precios actuales antes de iniciar una tarea mayor. Esta vía API no incluye una suscripción de Claude ni autoriza otras integraciones que usen el inicio de sesión de la suscripción.
