Tutorial de Claude Code — uso diario con una clave de pago por uso: cambiar de modelo, calcular costes y gestionar el contexto

El uso de Claude Code puede resumirse en cuatro pasos: ejecuta claude en la carpeta del proyecto, ejecuta una vez /init para que genere CLAUDE.md, describe la tarea en chino e incluye la ruta del archivo y revisa los cambios propuestos antes de decidir si los aceptas. Es un asistente de programación que vive en el terminal: lee y modifica archivos y ejecuta pruebas, pero pide tu aprobación antes de actuar. Puedes usarlo iniciando sesión con una suscripción Pro/Max o configurando una clave de API de pago por uso; con una clave, cada paso se factura por token, así que lo importante en el uso diario son tres cosas: cambiar de modelo según la tarea, saber cuánto cuesta una sesión y mantener el contexto conciso.

Casi todas las guías de Claude Code en Internet presuponen el inicio de sesión con una suscripción. Esta página está dirigida a quienes no tienen suscripción o no quieren estar limitados por la ventana de uso de 5 horas y prefieren una clave de pago por uso. Si aún no lo has instalado, consulta primero Guía de instalación de Claude Code; vuelve aquí después de instalarlo y conectarlo.

Primeros pasos: cuatro acciones

# 1. 一定要在專案資料夾裡啟動——它能看、能改的範圍就是這個資料夾
cd ~/work/my-app
claude

# 2. 第一個指令：讀過整個 repo，產生 CLAUDE.md
> /init

# 3. 之後直接用中文交代任務，附上檔案路徑最準
> 把 src/api/user.ts 的輸入驗證改用 zod，測試也一起修好

# 4. 牽涉很多檔案的任務，先按 Shift+Tab 切到計畫模式，確認做法再動手

Te preguntará antes de modificar un archivo o ejecutar un comando. Si la dirección es incorrecta, pulsa Esc para detenerlo y usa /rewind para volver al punto de control anterior; el código y la conversación retrocederán juntos. El CLAUDE.md generado por /init es solo un borrador; más adelante hay una sección dedicada a acortarlo.

Cómo se factura una sesión al usar una clave de API

Cada vez que Claude Code envía una solicitud, vuelve a enviar el prompt del sistema, CLAUDE.md, toda la conversación y el contenido de los archivos leídos, añadiendo el contenido nuevo al final. La parte inicial que no ha cambiado pasa por la caché: las lecturas de caché se cobran al 10 % del precio de entrada y las escrituras a 1,25 veces ese precio. Por eso, en una sesión, la mayor parte de la factura suele corresponder a «volver a leer la conversación antigua».

La tabla siguiente toma como ejemplo una sesión de la documentación oficial de costes de Anthropic (1.200 tokens de entrada, 5.300 de salida, 940.000 leídos desde la caché y 50.000 escritos en la caché) y la calcula con las tarifas de Kunavo para los cuatro modelos:

En Claude Sonnet 5, aproximadamente el 85% de la factura de esta sesión corresponde a lecturas y escrituras de caché. En otras palabras, el coste depende de cuánto se alarga la conversación, no de cuántas palabras escribes; esa es también la razón de la sección posterior sobre «higiene del contexto».

Para consultar tus cifras, ejecuta /usage en Claude Code (/cost es su alias); mostrará los cuatro tipos de tokens. Sin embargo, el importe que aparece al lado es una estimación local de Claude Code basada en los precios de Anthropic. Al usar Kunavo, el cargo real aparece en la página de uso del panel, con los tokens de cada modelo (incluidas las lecturas y escrituras de caché) y el importe cobrado.

Cambiar de modelo según la tarea

Primero, en el bloque env de ~/.claude/settings.json, asigna cada alias al modelo real. Al escribirlo en este archivo, también pueden leerlo la extensión del editor y los procesos en segundo plano; no lo escribas en .claude/settings.json, que se confirmará en el proyecto mediante commit. Los alias deben corresponder: el modelo predeterminado de Claude Code y el alias opus apuntan al Opus más reciente; si Kunavo aún no lo ofrece, una configuración sin correspondencia recibirá un 404 en la primera solicitud. El alias sonnet apunta a Sonnet 5.5, modelo que Kunavo no ofrece; sin ANTHROPIC_DEFAULT_SONNET_MODEL, la ejecución de /model sonnet y opusplan, así como los subagentes configurados como model: sonnet, recibirán un 404. La configuración siguiente asigna el alias opus a Claude Opus 5.5 (claude-opus-5-5); requiere Claude Code v2.1.280 o posterior. Si utilizas una versión anterior, ejecuta primero claude update.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5"
  }
}

Una vez configurado, cambiarlo requiere una sola línea:

# 工作階段裡切換（別名會對應到上面設定的模型）
> /model haiku
> /model sonnet
> /model opus

# 也可以直接打完整名稱
> /model claude-fable-5

# 或在啟動時指定
claude --model claude-opus-5-5

/model guarda la elección como predeterminada para las sesiones nuevas; si solo quieres cambiarla esta vez, ejecuta /model sin argumentos y pulsa s en el menú. ANTHROPIC_DEFAULT_HAIKU_MODEL también controla los resúmenes y títulos que Claude Code genera en segundo plano; apuntarlo al modelo más barato es la configuración más rentable.

En Kunavo, Claude Opus 5.5 cuesta $2.80 / $14.00, y Claude Sonnet 5 cuesta $1.40 / $7.00; el precio unitario de Claude Haiku 4.5 es aproximadamente 1/2 del de Claude Sonnet 5, mientras que el de Claude Fable 5 equivale a 5 veces ese precio de referencia. Frente al precio oficial: Claude Sonnet 5 Aproximadamente un 30% más barato que Anthropic oficialmente, Claude Opus 5.5 Aproximadamente un 30% más barato que Anthropic oficialmente, Claude Haiku 4.5 Aproximadamente un 30% más barato que Anthropic oficialmente, Claude Fable 5 Aproximadamente un 30% más barato que Anthropic oficialmente.

El momento de cambiar de modelo es entre tareas, no a mitad de una tarea. La caché de cada modelo es independiente: si /model a mitad de una tarea, la siguiente solicitud debe volver a leer toda la conversación al precio sin caché (mientras la caché siga vigente, Claude Code te pedirá confirmación). Ejecuta primero /clear y luego cambia de modelo; así solo se relee la conversación nueva y breve. Los tokens de razonamiento se cobran al precio de salida; para tareas sencillas puedes usar /effort para reducir el nivel de razonamiento. También debe configurarse al principio de la tarea; en la mayoría de los modelos, cambiar el esfuerzo a mitad de la tarea invalida la caché.

CLAUDE.md: escribe solo lo que tengas que repetir con frecuencia

# CLAUDE.md — 放在專案根目錄，commit 進 git

## 指令
- 測試：npm test（只跑一個檔：npm test -- path/to/file）
- 型別檢查：npx tsc --noEmit
- Lint：npm run lint

## 規則
- 日期一律用 date-fns，不用 moment。
- API handler 只放在 app/api/**/route.ts。
- commit 訊息用繁體中文，前綴 feat / fix / docs。

## 不要動的地方
- db/migrations/ —— 產生出來的檔案，不要手改。

CLAUDE.md se carga al comienzo de cada sesión y se incluye en todas las solicitudes posteriores (normalmente con precio de lectura de caché). Anthropic recomienda limitar el archivo a 200 líneas; cuanto más largo sea, más contexto consume y peor se cumple. No incluyas información deducible del código, como la estructura de directorios o la explicación de funciones; las notas destinadas solo a personas pueden encerrarse en <!-- -->, y se eliminarán antes de incorporarse al contexto.

Otro malentendido frecuente: modificar CLAUDE.md durante una sesión no surte efecto de inmediato; hay que esperar a /clear, /compact o reiniciar para que se lea la nueva versión.

Higiene del contexto: abaratar cada paso

• Usa /clear entre tareas no relacionadas. Abre una conversación completamente nueva y no cuesta nada; después puedes recuperar la anterior con /resume.
• Si una misma tarea se alarga demasiado, usa /compact. Puedes indicar los puntos que deben conservarse, por ejemplo /compact 保留測試輸出和改過的檔案. Envía una solicitud de resumen, así que es más barato hacerlo mientras la caché siga vigente; si haces compact después de mucho tiempo, la solicitud de resumen tendrá que volver a leer todo el historial al precio sin caché.
• Si vas en la dirección equivocada, usa /rewind. Retrocede a una parte inicial que ya esté en caché, por lo que es más barato que compact.
• En el modo de clave, la caché vive 5 minutos por defecto. Si vuelves después de más de 5 minutos, el primer paso volverá a escribir todo el contexto anterior en la caché (1,25 veces el precio de entrada). Antes de ir a una reunión o a comer, termina con /compact o /clear.
• Usa /context para ver qué ocupa el contexto. Al usar Kunavo, esta cifra es una estimación local; Kunavo actualmente no proporciona /v1/messages/count_tokens, y la compresión automática y la propia sesión no se ven afectadas.
• Desactiva los servidores MCP que no uses en /mcp. La documentación de Anthropic indica que, si configuras un ANTHROPIC_BASE_URL personalizado, no hay búsqueda de herramientas (tool search): las definiciones de herramientas MCP no se cargan de forma diferida, sino que ocupan espacio en cada solicitud.
• Incluye las rutas de los archivos al describir la tarea. «Cambia la validación» hará que busque por todas partes y lea muchos archivos; «cambia la validación de src/api/user.ts para usar zod» limita la lectura a lo necesario.

Para que pregunte menos veces «¿puedo ejecutarlo?», se recomienda permitir únicamente comandos de lectura y validación. La opción que omite todas las confirmaciones solo debe usarse en entornos que puedan desecharse por completo; el motivo se explica en Descripción de --dangerously-skip-permissions (inglés). Para saber cómo se factura la caché, consulta Documentación de la caché.

Límites de gasto y pagos

En la página de gestión de claves, crea una clave exclusiva para Claude Code y establece un límite de gasto mensual. Al alcanzar el límite, las solicitudes de esa clave devolverán 402, no se seguirá cobrando y cualquier bucle descontrolado solo consumirá hasta el límite. En la misma página también puedes establecer una lista blanca de IP.

La cuenta es prepaga: la recarga mínima es de $10, el saldo no caduca y las solicitudes fallidas no generan cargos. En Taiwán puedes recargar con una tarjeta internacional (Visa, Mastercard, Amex, JCB, UnionPay), Apple Pay o Google Pay. Actualmente no hay canales locales como JKO Pay o LINE Pay; consulta los detalles en Coste de Claude Code.

Cuándo resulta más rentable una suscripción

Para quienes interactúan durante mucho tiempo cada día y ejecutan muchos pasos al mes, la cuota mensual fija de una suscripción suele ser más barata que el pago por uso. El cálculo requiere una sola división: cuota mensual ÷ coste por paso = pasos del punto de equilibrio. Con Claude Sonnet 5 a aproximadamente $0.043 por paso (sin contar la caché), si ejecutas menos pasos que esa cantidad al mes, el pago por uso es más barato y los meses sin actividad también cuestan $0. La cuota mensual actual de cada plan y el cálculo completo están en Coste de Claude Code; no los repetimos aquí.

También conviene aclarar el compromiso de esta ruta: al usar Kunavo empleas capacidad compartida, sin cuota dedicada ni SLA contractual. Los equipos que necesiten cuota o SLA garantizados deben contratar directamente con Anthropic. La configuración completa de la conexión está en Documentación de integración de Claude Code (inglés).

Preguntas frecuentes