Claude Code se ejecuta en la terminal, pero depende de la versión correcta del entorno, los permisos del directorio, el almacenamiento de credenciales y el proxy corporativo. Esta guía explica qué preparar en local y cómo compartir la configuración dentro del equipo.
Claude Code es una herramienta de terminal y, una vez instalada, basta con un comando para usarla. Por eso muchas personas concentran toda la atención en la red. En la práctica, los bloqueos suelen venir de otros puntos: si la versión del entorno es correcta, si el directorio del proyecto tiene permisos de escritura, dónde se guardan las claves, cómo pasa el tráfico por el proxy de la empresa y cómo comparte el equipo una misma configuración.
Alinea primero el entorno de ejecución y las dependencias
Empieza revisando en la documentación oficial la versión del entorno que se exige actualmente e instala exactamente esa. Evita probar con una versión publicada hace apenas unos días. Sigue el gestor de paquetes que use el equipo: mezclar npm, pnpm y yarn puede provocar conflictos entre archivos de bloqueo. git y las herramientas básicas de línea de comandos son imprescindibles, porque este tipo de herramientas necesita leer repositorios, ejecutar comandos y lanzar pruebas. Si falta una pieza, los errores aparecen enseguida.
Después de instalar, comprueba primero tres cosas en un directorio vacío: que pueda leer archivos, modificarlos y ejecutar pruebas. Los problemas de entorno se detectan rápido en un directorio pequeño; investigarlos dentro del código de negocio cuesta mucho más.
Directorio del proyecto, permisos y límites
No la inicies desde el directorio personal del usuario ni desde la raíz de todo el disco. Asigna una raíz de repositorio bien definida y limita la lectura y escritura al proyecto. Si realmente hace falta ampliar el alcance, concede una autorización puntual en lugar de dejar el acceso abierto de forma permanente.
Revisa .gitignore antes de hacer commit. Las cachés, los registros y los scripts temporales generados en local deben quedar fuera del repositorio. En un equipo, uno de los errores más peligrosos no es escribir mal el código, sino subir por accidente archivos sensibles creados durante la depuración local.
Dónde guardar claves y credenciales
Las claves de API, los tokens de acceso y otros secretos deben pasar por variables de entorno o por el gestor de credenciales del sistema operativo. No los escribas en el código fuente, archivos de configuración ni comentarios de scripts. El propio archivo .env también debe estar en .gitignore; en el repositorio solo debería quedar un archivo de ejemplo que explique el significado de cada campo.
Separa las credenciales personales de las del equipo. Si varias personas comparten una sola clave, cuando haya un problema será difícil saber quién la estaba usando. Define de antemano el ciclo de rotación: cámbialas periódicamente, el mismo día que alguien deje el equipo y de inmediato si se sospecha una filtración. Si se detecta una exposición, revoca primero y después investiga; no borres antes los registros.
Trabajar con el proxy corporativo y la red
En redes corporativas, el problema con estas herramientas no suele ser simplemente poder conectarse, sino el proxy y los certificados. Si la puerta de enlace de la empresa realiza interceptación TLS, la herramienta puede fallar porque no confía en la cadena de certificados. En ese caso, pide a TI el certificado raíz interno e instálalo en el almacén de confianza correcto, en lugar de desactivar temporalmente la verificación.
El inicio de sesión abre un navegador, así que la línea de comandos y el navegador deberían usar, a ser posible, la misma salida. Esa salida también debe ser fija, estable y controlable. Si falta cualquiera de esas condiciones, es más fácil acabar repitiendo el inicio de sesión o viendo verificaciones CAPTCHA. Cambiar de nodo con frecuencia tiende a activar más controles que mantener uno fijo, porque este último se parece más al comportamiento de un usuario habitual.
Para comprobar si la salida se está aplicando realmente, basta con hacer una consulta de IP desde la línea de comandos usando el parámetro de proxy.
curl -x http://127.0.0.1:7897 https://ipinfo.io
La dirección mostrada debería ser la esperada. También conviene que la zona horaria y el idioma del navegador coincidan con la región de salida; evita, por ejemplo, que uno indique Norteamérica y el otro UTC+8.
Cómo compartir la configuración en el equipo
Se puede compartir la estructura, no las claves. Guarda en el repositorio, dentro de un archivo de configuración versionable, las convenciones del directorio de trabajo, las reglas de enrutamiento del proxy, el alcance de los comandos permitidos y las restricciones de estilo de código. Las claves se inyectan en cada equipo mediante variables de entorno.
Así, los nuevos miembros pueden seguir la documentación y empezar a trabajar sin tener que preguntar a cada compañero. Si el equipo utiliza varias identidades o varios entornos al mismo tiempo, PurpleMark también puede fijar el estado del navegador de cada entorno, de modo que después sea posible saber en cuál se produjo una determinada acción de inicio de sesión.
Cierre
Cuando este tipo de herramientas falla, muchas veces no se trata de un error propio de la herramienta, sino de requisitos previos que no estaban alineados. Entorno y dependencias, permisos del directorio, ubicación de las claves, salida del proxy y configuración compartida: resolver bien estos cinco puntos en un proyecto pequeño ahorra muchas investigaciones repetidas más adelante.
