Skip to content

Latest commit

 

History

History
388 lines (306 loc) · 11.4 KB

README_COMPLETO.md

File metadata and controls

388 lines (306 loc) · 11.4 KB

📚 CLAUDE CODE VANILLA - GUÍA COMPLETA

🎯 OBJETIVO Y CONTEXTO

Problema Inicial

El usuario tenía un sistema Claude Code con configuración custom (Synthetic API + GLM-4.6) y quería crear una instalación vanilla limpia que:

  1. Use solo API oficial de Anthropic
  2. Esté completamente aislada de configuraciones existentes
  3. No contamine ni sea contaminada por el entorno actual
  4. Sea lo más minimal posible en recursos

Contexto Técnico Preexistente

# Sistema original del usuario:
- cs      → Synthetic API (GLM-4.6) - Config custom
- co      → Claude API (Sonnet)    - Config mixed
- Variables ANTHROPIC_* configuradas para Synthetic
- ~/.claude/ con configuración personalizada
- switchClaude/ con sistema dual

🏗️ ARQUITECTURA DE SOLUCIÓN

Diseño del Entorno Aislado

~/claude-clean/                 ← Directorio base 100% aislado
├── test-claude.sh             ← Wrapper ejecutor (aislador)
├── .claude/
│   └── settings.json          ← Config Anthropic pura
├── README_COMPLETO.md         ← Este documento
├── README.md                  ← Documentación básica
└── SOLUCION_MODELO.md         ← Historial del problema 404

Flujo de Aislamiento

  1. test-claude.sh se ejecuta
  2. Limpia todas las variables ANTHROPIC_* del entorno actual
  3. Define CLAUDE_CONFIG_DIR apuntando solo a ~/claude-clean/.claude/
  4. Ejecuta Claude con configuración 100% vanilla
  5. Resultado: Claude no ve nada fuera de su directorio

🛠️ PROCESO DE INSTALACIÓN DETALLADO

Paso 1: Backup de Configuración Existente

# Se preservó completamente la configuración original
mkdir -p ~/backups/CustomClaude/
cp -r ~/.claude ~/backups/CustomClaude/claude-config
cp ~/.bashrc ~/backups/CustomClaude/bashrc-backup
cp -r ~/switchClaude ~/backups/CustomClaude/switchClaude-backup

Paso 2: Creación del Entorno Limpio

# Estructura minimal sin nada del entorno original
mkdir -p ~/claude-clean/.claude/
cd ~/claude-clean/

Paso 3: Instalación Claude Code

# Descarga oficial Anthropic (misma versión para todos)
curl -fsSL https://claude.ai/install.sh | bash -s -- stable
# Resultado: Versión 2.0.30

Paso 4: Configuración Anthropic Pura

{
  "model": "claude-sonnet-4-5-20250929",
  "api_url": "https://api.anthropic.com",
  "authorization_token": "YOUR_ANTHROPIC_API_KEY_HERE",
  "alwaysThinkingEnabled": false
}

🐛 PROBLEMAS CRÍTICOS RESUELTOS

Problema 1: Error 404 Modelo Obsoleto

Symptoms:

API Error: 404 {"type":"error","error":{"type":"not_found_error","message":"model: claude-3-5-sonnet-20241022"}}

Root Cause:

  • El modelo claude-3-5-sonnet-20241022 expiró el 22 de octubre de 2025
  • Afectaba a instalaciones nuevas de Claude Code

Solution:

  • Actualizar a claude-sonnet-4-5-20250929
  • Funcionamiento verificado: ✅ OK response

Problema 2: Variables de Entorno Contaminantes

Symptoms:

  • Claude vanilla detectaba configuración Synthetic del entorno
  • No había aislamiento real entre configuraciones

Solution:

  • Wrapper test-claude.sh con export explícito:
unset CLAUDE_CONFIG_DIR
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_MODEL
unset ANTHROPIC_*
export CLAUDE_CONFIG_DIR="$(pwd)/.claude"

📊 COMPARACIÓN DE ENTORNOS

Característica Synthetic (cs) Claude Official (co) Vanilla (cvanilla)
API Synthetic API Anthropic API Anthropic API
Modelo GLM-4.6 Sonnet 3.5 Sonnet 4.5
Config Dir ~/.claude/ ~/.claude-official/ ~/claude-clean/.claude/
Variables ANTHROPIC_* personalizadas Mixed None explícitas
Aislamiento ❌ Compartido ❌ Parcial ✅ 100% aislado
MCPs ✅ Disponibles ✅ Disponibles ⚠️ Requiere config
Recursos Base Base +50MB config

⚙️ FUNCIONAMIENTO DETALLADO

Script de Aislamiento: test-claude.sh

#!/bin/bash
cd "$(dirname "$0")"

# 1. Limpieza total de entorno
unset CLAUDE_CONFIG_DIR
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_MODEL
unset ANTHROPIC_*

# 2. Configuración local exclusiva
export CLAUDE_CONFIG_DIR="$(pwd)/.claude"

# 3. Ejecución Claude vanilla
~/.local/bin/claude "$@"

Flujo de Ejecución

Usuario ejecuta: ~/claude-clean/test-claude.sh
       ↓
test-claude.sh limpia todas las variables ANTHROPIC_*
       ↓
Define CLAUDE_CONFIG_DIR = ~/claude-clean/.claude/
       ↓
Claude usa solo settings.json local
       ↓
Resultado: 100% Anthropic API vanilla

🚀 MÉTODOS DE EJECUCIÓN

Método 1: Directo

~/claude-clean/test-claude.sh --dangerously-skip-permissions

Método 2: Non-Interactive

~/claude-clean/test-claude.sh -p "question here" --dangerously-skip-permissions

Método 3: Alias Permanente

echo 'alias cvanilla="~/claude-clean/test-claude.sh --dangerously-skip-permissions"' >> ~/.bashrc
source ~/.bashrc
cvanilla  # Ahora disponible globalmente

⚠️ LIMITACIONES Y CONSIDERACIONES

Limitación 1: MCPs (Model Context Protocol)

Problema:

  • MCPs se configuran en ~/.claude/claude_desktop_config.json
  • Entorno vanilla usa ~/claude-clean/.claude/ como config dir

Impacto:

  • Claude vanilla NO ve MCPs del sistema principal
  • Cada entorno tiene sus propios MCPs

Soluciones:

# Opción A: Copiar MCPs existentes
cp ~/.claude/claude_desktop_config.json ~/claude-clean/.claude/

# Opción B: Symlink automático
ln -s ~/.claude/claude_desktop_config.json ~/claude-clean/.claude/

# Opción C: MCPs específicos por entorno
# Mantener configs diferentes para cada caso

Limitación 2: Actualizaciones Automáticas

Problema:

  • Claude Code se actualiza globalmente vía ~/.local/bin/claude
  • Todas las instancias comparten el mismo binary

Impacto:

  • No puedes tener diferentes versiones por entorno
  • Actualización afecta a todos los entornos

Mitigación:

  • Usar versiones fijas si se necesita estabilidad
  • Documentar versiones probadas (2.0.30 funcional)

Limitación 3: Recursos de Sistema

Consumo real:

  • Disco: 50.1MB total (binary + config)
  • RAM: 0MB en reposo, igual que Claude normal al ejecutar
  • CPU: 0% cuando no está en uso

No es:

  • Machine virtual (no overhead de virtualización)
  • Contenedor Docker (no aislamiento de kernel)
  • Instalación duplicada (comparte binary)

Limitación 4: Administración de Secrets

Consideración:

  • API key está en texto plano en settings.json
  • Mismo archivo puede ser accedido por múltiples entornos si symlinks

Recomendación:

  • Permisos restrictivos: chmod 600 settings.json
  • Considerar variables de entorno para producción

🔧 MANTENIMIENTO Y TROUBLESHOOTING

Verificación de Funcionamiento

# Basic test
~/claude-clean/test-claude.sh -p "test connection" --dangerously-skip-permissions
# Expected: OK

# Version check
~/claude-clean/test-claude.sh --version
# Expected: 2.0.30

# Config verification
cat ~/claude-clean/.claude/settings.json

Problemas Comunes y Soluciones

Error 404 Modelo No Encontrado

# Symptom: API Error 404 model not found
# Cause: Modelo deprecated
# Solution: Verificar settings.json tenga modelo actual
"model": "claude-sonnet-4-5-20250929"

Error API Key Invalid

# Symptom: Invalid API key
# Cause: Token incorrecto o expirado
# Solution: Verificar authorization_token en settings.json

Variables de Entorno Contaminantes

# Symptom: Claude detecta config del sistema principal
# Cause: Variables ANTHROPIC_* no limpiadas
# Solution: Verificar test-claude.sh haga unset completo

📁 ESTRUCTURA DE ARCHIVOS COMPLETA

~/claude-clean/                    [DIR - Entorno vanilla]
├── test-claude.sh                [FILE - Wrapper ejecutor]
├── .claude/                      [DIR - Config aislada]
│   └── settings.json             [FILE - Config Anthropic]
├── README_COMPLETO.md            [FILE - Este documento]
├── README.md                     [FILE - Documentación básica]
└── SOLUCION_MODELO.md            [FILE - Historial 404]

~/backups/CustomClaude/           [DIR - Backup configuración original]
├── claude-config/                [DIR - Backup ~/.claude/]
├── bashrc-backup                 [FILE - Backup .bashrc]
└── switchClaude-backup/          [DIR - Backup sistema dual]

~/.claude-vanilla/               [DIR - Primer intento (no usado)]

🎯 CASOS DE USO RECOMENDADOS

✅ Casos Ideales para Entorno Vanilla

  1. Testing y desarrollo aislado
  2. Producción con configuración bloqueada
  3. Experimentos sin afectar entorno principal
  4. Ambientes de prueba para nuevos modelos
  5. Documentación y demos limpias

❌ Casos NO Recomendados

  1. Uso diario principal (mejor el sistema existente)
  2. Cuando se necesitan MCPs extensos (requiere config extra)
  3. Multiusuaría simultánea (comparte binary)
  4. Cuando se necesitan versiones diferentes (binary compartido)

🔐 CONSIDERACIONES DE SEGURIDAD

Aspectos de Seguridad

  • API key en texto plano: Considerar encryptación para producción
  • Permisos de archivos: chmod 600 para settings.json
  • Aislamiento de red: Misma conexión que el sistema principal
  • Logging: Claude puede escribir logs en su directorio config

Recomendaciones

# Security hardening
chmod 700 ~/claude-clean/
chmod 700 ~/claude-clean/.claude/
chmod 600 ~/claude-clean/.claude/settings.json
chmod 700 ~/claude-clean/test-claude.sh

📈 FUTURO Y EVOLUCIÓN

Posibles Mejoras

  1. Automatización de MCPs: Script para sincronizar configs
  2. Gestión de secrets: Integración con vault systems
  3. Monitorización: Logging y métricas de uso
  4. Versionamiento: Control de versiones de configuraciones
  5. Testing automático: CI/CD para validación del entorno

Roadmap Sugerido

  • Script de sincronización MCPs
  • Integración con secret managers
  • Dashboard de monitoreo multi-entorno
  • Testing suite automatizado
  • Documentación interactiva

🎖️ CONCLUSIONES

Logros Alcanzados

✅ Aislamiento 100% funcional - Entorno completamente separado ✅ Consumo minimal - Solo 50MB overhead ✅ Configuración vanilla pura - Solo Anthropic API ✅ Problemas críticos resueltos - Modelo obsoleto, variables contaminantes ✅ Documentación completa - Para cualquier IA/usuario entienda el sistema

Estado Final

El entorno ~/claude-clean/ es una instalación Claude Code 100% vanilla que:

  • Usa exclusivamente API de Anthropic con Sonnet 4.5
  • Está completamente aislada de configuraciones del sistema
  • Consume recursos mínimos (~50MB disco)
  • Funciona perfectamente verificada con conexión OK
  • Está documentada para mantenimiento futuro

Valor del Proyecto

Este sistema permite tener un entorno controlado y predecible para Claude Code, ideal para testing, producción, o cualquier caso donde se necesite certeza absoluta del comportamiento sin interferencias de configuraciones existentes.

📅 Última actualización: 31 de octubre de 2025 🔧 Versión Claude Code: 2.0.30 🤖 Modelo: claude-sonnet-4-5-20250929 ✅ Estado: Fully Functional and Tested