Guía Completa de Instalación y Configuración de Claude Code con API Personalizada

Claude Code es el asistente de programación con IA oficial de Anthropic que puede utilizarse directamente en terminales, VS Code, JetBrains y otros IDEs. Sus capacidades incluyen:

Comprender toda tu base de código y editar archivos cruzados
Ejecutar comandos, crear pull requests y corregir errores automáticamente
Leer y escribir archivos, operar con Git
Conectar herramientas externas a través de MCP (Jira, Slack, etc.)

En resumen: es un programador con IA que vive en tu terminal, capaz de realizar tareas con una simple instrucción.

Requisitos del Sistema

Elemento	Requisito
Sistema operativo	macOS / Linux / Windows (WSL2 o Git Bash)
Node.js	No obligatorio (la instalación nativa no depende de Node)
Red	Acceso a claude.ai o tu endpoint de API personalizado
Cuenta	Suscripción Claude Pro/Max o API Key de Anthropic Console

Instalación de Claude Code

Instalación Nativa (Recomendada)

macOS / Linux / WSL2:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Los usuarios de Windows necesitan instalar Git for Windows previamente.

Verifica la instalación:

claude --version

Si ves el número de versión, la instalación fue exitosa ✅

La instalación nativa se actualiza automáticamente en segundo plano, sin necesidad de actualizaciones manuales.

Instalación con Homebrew (Alternativa para macOS/Linux)

brew install --cask claude-code

Nota: La instalación con Homebrew no se actualiza automáticamente, necesitas ejecutar periódicamente brew upgrade claude-code.

Instalación con WinGet (Alternativa para Windows)

winget install Anthropic.ClaudeCode

Primer Inicio de Sesión

Después de la instalación, navega a tu directorio de proyecto e inicia Claude Code:

cd tu-proyecto
claude

La primera ejecución abrirá automáticamente un navegador para iniciar sesión. Se admiten los siguientes métodos:

Método de inicio	Caso de uso
Claude Pro/Max	Usuarios individuales, inicio directo con cuenta de claude.ai
Claude for Teams/Enterprise	Usuarios de equipo, con cuenta invitada por administrador
Anthropic Console	Usuarios de pago por uso con API
Servicios en la nube (Bedrock/Vertex/Foundry)	Despliegue empresarial, configurado mediante variables de entorno

Si el navegador no se abre automáticamente, presiona la tecla c para copiar el enlace de inicio y pégalo manualmente en el navegador.

Configuración de API Personalizada y Claves (¡Importante!)

Esta es la sección que más interesa a muchos usuarios: cómo hacer que Claude Code utilice tu propia API Key o endpoints de proxy de terceros.

Uso de API Key Oficial de Anthropic

Si tienes una API Key de Anthropic Console:

export CLAVE_ANTHROPIC="sk-ant-xxxxxxxxxxxxx"

Agrégala a tu archivo de configuración de shell para que sea permanente:

# Para usuarios de Bash
echo 'export CLAVE_ANTHROPIC="sk-ant-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# Para usuarios de Zsh
echo 'export CLAVE_ANTHROPIC="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

Luego ejecuta claude y utilizará directamente tu API Key, sin necesidad de inicio de sesión en el navegador.

Uso de Endpoint Personalizado (Proxy/Terceros)

Muchos usuarios no pueden acceder directamente a la API de Anthropic y necesitan servicios proxy. Claude Code admite endpoints personalizados mediante la variable de entorno URL_BASE_ANTHROPIC:

# Configura tu dirección proxy (reemplaza con tu dirección real)
export URL_BASE_ANTHROPIC="https://tu-servicio-proxy.com"

# Configura tu API Key (proporcionada por el servicio proxy)
export CLAVE_ANTHROPIC="sk-tu-clave-proxy"

Punto clave: El servicio proxy debe ser compatible con el formato de API de Messages de Anthropic (endpoint /v1/messages) y debe reenviar correctamente los encabezados anthropic-beta y anthropic-version.

Configuración permanente:

# Agregar a .bashrc o .zshrc
cat >> ~/.bashrc << 'EOF'
# API personalizada para Claude Code
export URL_BASE_ANTHROPIC="https://tu-servicio-proxy.com"
export CLAVE_ANTHROPIC="sk-tu-clave-proxy"
EOF
source ~/.bashrc

Uso con Proxy LiteLLM (Avanzado)

Si has desplegado un servidor proxy LiteLLM para gestionar múltiples modelos de IA:

# Endpoint unificado LiteLLM (recomendado)
export URL_BASE_ANTHROPIC="https://tu-servidor-litellm:4000"
export TOKEN_AUTENTICACION="sk-litellm-tu-clave"

O mediante el archivo settings.json de Claude Code:

{
  "env": {
    "URL_BASE_ANTHROPIC": "https://tu-servidor-litellm:4000",
    "TOKEN_AUTENTICACION": "sk-litellm-tu-clave"
  }
}

La ubicación de settings.json es: ~/.claude/settings.json (efecto global).

Uso con Amazon Bedrock

export USAR_BEDROCK_CLAUDE=1
export REGION_AWS=us-east-1
export ID_CLAVE_ACCESO_AWS="tu-clave-acceso"
export CLAVE_SECRETA_AWS="tu-clave-secreta"

Uso con Google Vertex AI

export USAR_VERTEX_CLAUDE=1
export REGION_CLOUD_ML=us-east5
export ID_PROYECTO_VERTEX_ANTHROPIC=tu-id-proyecto

Uso con Microsoft Azure Foundry

export USAR_FOUNDRY_CLAUDE=1
export RECURSO_FOUNDRY_ANTHROPIC=tu-recurso
export CLAVE_API_FOUNDRY_ANTHROPIC=tu-clave-api

Nombres de Modelos Personalizados

Claude Code utiliza por defecto el modelo Claude más reciente. Puedes especificar un modelo específico mediante variables de entorno:

# Especificar el modelo a usar por defecto
export MODELO_ANTHROPIC=claude-sonnet-4-6

# O especificar diferentes modelos para cada nivel
export MODELO_OPUS_DEFECTO=claude-opus-4-6
export MODELO_SONNET_DEFECTO=claude-sonnet-4-6
export MODELO_HAIKU_DEFECTO=claude-haiku-3-5-20241022

También puedes cambiar durante la ejecución:

# Especificar al iniciar
claude --model opus

# Cambiar durante ejecución (dentro de Claude Code)
/model sonnet

Alias de modelos disponibles:

Alias	Descripción
`default`	Selección automática según tipo de cuenta
`sonnet`	Modelo Sonnet más reciente, para codificación diaria
`opus`	Modelo Opus más reciente, para razonamiento complejo
`haiku`	Rápido y eficiente, para tareas simples
`opusplan`	Planificación con Opus, ejecución con Sonnet

Gestión Unificada de Configuración con settings.json

Además de las variables de entorno, puedes gestionar toda la configuración a través de ~/.claude/settings.json:

{
  "env": {
    "URL_BASE_ANTHROPIC": "https://tu-servicio-proxy.com",
    "CLAVE_ANTHROPIC": "sk-tu-clave",
    "MODELO_ANTHROPIC": "claude-sonnet-4-6"
  },
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)"
    ]
  }
}

Prioridad de configuración (de mayor a menor):

Managed (configuración gestionada por organización, no sobreescribible)
Argumentos de línea de comandos (sobrescribe sesión temporal)
Local (.claude/settings.local.json, solo para este proyecto y usuario)
Project (.claude/settings.json, compartido por equipo)
User (~/.claude/settings.json, global personal)

Verificación de Configuración

Después de iniciar Claude Code, ingresa el comando /status para ver la configuración actual:

claude
# Después de iniciar, ingresa:
/status

Mostrará el modelo en uso, información de cuenta, endpoint de API, etc. Confirma que todo es correcto ✅

Problemas Comunes y Soluciones

Error 1: Error `ERR\_BAD\_REQUEST` al iniciar

Síntoma: Las variables de entorno están configuradas, la API funciona con curl, pero ejecutar claude muestra directamente Failed to connect to api.anthropic.com: ERR_BAD_REQUEST y sale.

Causa raíz: Claude Code al iniciar verifica la conectividad solicitando https://api.anthropic.com/api/hello, completamente independiente de tu URL_BASE_ANTHROPIC. En China continental, esta dirección devuelve error y Claude Code sale con process.exit(1).

Solución: Se necesitan dos pasos:

① Deshabilitar verificación de tráfico no esencial:

export DESACTIVAR_TRAFICO_NOESENCIAL_CLAUDE=1

② Agregar la huella de tu API Key a la lista aprobada:

Este es el paso más crítico. Claude Code en modo interactivo verifica si las API Keys de terceros están "aprobadas", si no, intentará conectar con api.anthropic.com.

1. Obtén la huella de tu key (últimos 20 caracteres)

echo -n "TU_API_KEY" | tail -c 20

2. Crea manualmente ~/.claude/.config.json

cat > ~/.claude/.config.json << 'EOF' { "customApiKeyResponses": { "approved": ["últimos20caracteresdetukey"] } } EOF


<h4>Error 2: Campo `apiBaseUrl` en `settings.json` no funciona</h4>
<p><strong>Síntoma</strong>: Configuraste <code>apiBaseUrl</code> y <code>apiKey</code> en <code>~/.claude/settings.json</code>, pero Claude Code ignora completamente esta configuración.</p>
<p><strong>Causa raíz</strong>: <strong>Claude Code no reconoce el campo <code>apiBaseUrl</code>!</strong> La dirección API solo se puede establecer mediante la variable de entorno <code>URL_BASE_ANTHROPIC</code>.</p>
<p><strong>Configuración incorrecta (no funciona):</strong></p>
<code>{
  "apiBaseUrl": "https://tu-proxy.com",
  "apiKey": "sk-xxx"
}</code>
<p><strong>Enfoque correcto: usar variables de entorno</strong></p>
<code>export URL_BASE_ANTHROPIC="https://tu-proxy.com"
export CLAVE_ANTHROPIC="sk-xxx"</code>
<p><strong>O configurar en el campo env de settings.json:</strong></p>
<code>{
  "env": {
    "URL_BASE_ANTHROPIC": "https://tu-proxy.com",
    "CLAVE_ANTHROPIC": "sk-xxx"
  }
}</code>

<h4>Error 3: Variables de entorno perdidas por retorno temparno no interactivo</h4>
<p><strong>Síntoma</strong>: Escribiste <code>export URL_BASE_ANTHROPIC=...</code> al final de <code>.bashrc</code>, funciona en terminal interactiva, pero en terminal de VS Code, login shell o algunos subprocesos las variables desaparecen.</p>
<p><strong>Causa raíz</strong>: El archivo <code>.bashrc</code> predeterminado de Ubuntu tiene esta sección al inicio:</p>
<code># If not running interactively, don't do anything
case $- in
    *i*) ;;
      *) return;;
esac</code>
<p><strong>¡Los shells no interactivos retornan directamente y no ejecutan ningún <code>export</code> posterior!</strong> VS Code inicia WSL usando shells no interactivos.</p>
<p><strong>Solución</strong>: Coloca las variables de entorno antes del retorno temprano</p>
<code># Al inicio de ~/.bashrc (antes de case $-)
export URL_BASE_ANTHROPIC="https://tu-proxy.com"
export CLAVE_ANTHROPIC="sk-xxx"
export DESACTIVAR_TRAFICO_NOESENCIAL_CLAUDE=1

# If not running interactively, don't do anything
case $- in
    *i*) ;;
      *) return;;
esac
# ... contenido original continúa aquí</code>
<p><strong>También escribe en <code>~/.profile</code> (para login shell):</strong></p>
<code># Agregar al final de ~/.profile
export URL_BASE_ANTHROPIC="https://tu-proxy.com"
export CLAVE_ANTHROPIC="sk-xxx"
export DESACTIVAR_TRAFICO_NOESENCIAL_CLAUDE=1</code>

<h4>Error 4: Terminal WSL2 no carga nuevas variables de entorno</h4>
<p><strong>Síntoma</strong>: Modificaste <code>.bashrc</code> y <code>.profile</code>, pero al abrir nueva terminal las variables de entorno siguen sin cambiar.</p>
<p><strong>Causa</strong>: Las instancias WSL2 se ejecutan continuamente en segundo plano y las nuevas ventanas de terminal heredan el entorno del proceso antiguo.</p>
<p><strong>Solución</strong>: Cierra completamente WSL desde Windows y vuelve a abrir:</p>
<code># Ejecutar en Windows PowerShell o CMD
wsl --shutdown</code>
<p>Luego abre la terminal nuevamente. VS Code también necesita cerrarse completamente y volver a abrirse.</p>

<h4>Error 5: `command not found: claude` después de la instalación</h4>
<p><strong>Síntoma</strong>: El script de instalación terminó, pero al escribir <code>claude</code> indica comando no encontrado.</p>
<p><strong>Causa</strong>: El directorio de instalación <code>~/.local/bin</code> no está en PATH.</p>
<p><strong>Solución</strong>:</p>
<code># Verificar PATH
echo $PATH | tr ':' '\n' | grep local/bin

# Si no hay salida, agregar manualmente:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verificar
claude --version</code>

<h3>Comandos Útiles</h3>
<h4>Comandos de Terminal</h4>

Comando	Uso
`claude`	Iniciar modo interactivo
`claude --model opus`	Iniciar con modelo específico
`claude -p "tu tarea"`	Modo no interactivo (tarea única)
`claude --version`	Ver versión

Comandos Internos de Claude Code

Comando	Uso
`/status`	Ver estado actual (modelo, cuenta, configuración)
`/model`	Cambiar modelo
`/logout`	Cerrar sesión actual
`/config`	Abrir interfaz de configuración
`/help`	Ver ayuda

Variables de Entorno Clave

Variable	Descripción
`CLAVE_ANTHROPIC`	API Key oficial
`URL_BASE_ANTHROPIC`	Endpoint de API personalizado
`TOKEN_AUTENTICACION`	Token de autenticación (sobrescribe API Key)
`MODELO_ANTHROPIC`	Modelo por defecto
`USAR_BEDROCK_CLAUDE`	Habilitar Bedrock
`USAR_VERTEX_CLAUDE`	Habilitar Vertex AI
`USAR_FOUNDRY_CLAUDE`	Habilitar Azure Foundry

Ejemplos de Configuración Completa #### Escenario 1: Usuario con proxy

# Agregar a ~/.bashrc
export URL_BASE_ANTHROPIC="https://tu-proxy-cn.com"
export CLAVE_ANTHROPIC="sk-tu-clave-proxy"
export MODELO_ANTHROPIC="claude-sonnet-4-6"

Escenario 2: Usuario empresarial con Bedrock

# Agregar a ~/.bashrc
export USAR_BEDROCK_CLAUDE=1
export REGION_AWS=us-east-1
export PERFIL_AWS=tu-perfil-aws
export MODELO_SONNET_DEFECTO="us.anthropic.claude-sonnet-4-6-v1:0"

Escenario 3: Mediante gateway LiteLLM unificado

# Agregar a ~/.bashrc
export URL_BASE_ANTHROPIC="https://litellm.interno.empresa.com:4000"
export TOKEN_AUTENTICACION="sk-litellm-clave-equipo"

Etiquetas: ClaudeCode API configuracion terminal desarrollo

Publicado el 8-11 13:06

Friki Work

Guía Completa de Instalación y Configuración de Claude Code con API Personalizada

Requisitos del Sistema

Instalación de Claude Code

Instalación Nativa (Recomendada)

Instalación con Homebrew (Alternativa para macOS/Linux)

Instalación con WinGet (Alternativa para Windows)

Primer Inicio de Sesión

Configuración de API Personalizada y Claves (¡Importante!)

Uso de API Key Oficial de Anthropic

Uso de Endpoint Personalizado (Proxy/Terceros)

Uso con Proxy LiteLLM (Avanzado)

Uso con Amazon Bedrock

Uso con Google Vertex AI

Uso con Microsoft Azure Foundry

Nombres de Modelos Personalizados

Gestión Unificada de Configuración con settings.json

Verificación de Configuración

Problemas Comunes y Soluciones

Error 1: Error `ERR\_BAD\_REQUEST` al iniciar

1. Obtén la huella de tu key (últimos 20 caracteres)

2. Crea manualmente ~/.claude/.config.json

Comandos Internos de Claude Code

Variables de Entorno Clave

Ejemplos de Configuración Completa #### Escenario 1: Usuario con proxy

Escenario 2: Usuario empresarial con Bedrock

Escenario 3: Mediante gateway LiteLLM unificado

Etiquetas populares

Friki Work

Guía Completa de Instalación y Configuración de Claude Code con API Personalizada

Requisitos del Sistema

Instalación de Claude Code

Instalación Nativa (Recomendada)

Instalación con Homebrew (Alternativa para macOS/Linux)

Instalación con WinGet (Alternativa para Windows)

Primer Inicio de Sesión

Configuración de API Personalizada y Claves (¡Importante!)

Uso de API Key Oficial de Anthropic

Uso de Endpoint Personalizado (Proxy/Terceros)

Uso con Proxy LiteLLM (Avanzado)

Uso con Amazon Bedrock

Uso con Google Vertex AI

Uso con Microsoft Azure Foundry

Nombres de Modelos Personalizados

Gestión Unificada de Configuración con settings.json

Verificación de Configuración

Problemas Comunes y Soluciones

Error 1: Error ERR\_BAD\_REQUEST al iniciar

1. Obtén la huella de tu key (últimos 20 caracteres)

2. Crea manualmente ~/.claude/.config.json

Comandos Internos de Claude Code

Variables de Entorno Clave

Ejemplos de Configuración Completa #### Escenario 1: Usuario con proxy

Escenario 2: Usuario empresarial con Bedrock

Escenario 3: Mediante gateway LiteLLM unificado

Etiquetas populares

Error 1: Error `ERR\_BAD\_REQUEST` al iniciar