Todas las guías

Cómo iniciar sesión en Claude Code en un servidor remoto por SSH

Inicia sesión en Claude Code en un servidor sin navegador por SSH con el inicio de sesión por código, un setup-token de un año o una clave de API, y mantenlo activo para las sesiones que abres desde el móvil.

Basado en
CLI
0.2.17
Ref de preview
a2c45c8

En resumen

En un servidor al que accedes por SSH, Claude Code no puede abrir un navegador, y el navegador de tu portátil no llega al callback local del servidor. Tienes tres formas de entrar:

  1. Inicio de sesión pegando un código. Ejecuta claude, abre la URL de inicio de sesión en el portátil o el móvil, entra y pega en la terminal el código que muestra el navegador. Sirve para un equipo delante del que te sientas de vez en cuando.
  2. Un token de larga duración. Ejecuta claude setup-token en un ordenador con navegador y define CLAUDE_CODE_OAUTH_TOKEN en el servidor. Sirve para un equipo delante del que no se sienta nadie.
  3. Una clave de API. Define ANTHROPIC_API_KEY. Se factura por token a través de Claude Console y es la opción adecuada para scripts y CI.

Si la pantalla de inicio de sesión no te deja copiar la URL por SSH, pasa directamente a la opción 2.

El problema

Una configuración habitual: las sesiones de Claude Code se ejecutan en un equipo Linux en otra habitación. Tiene los repositorios y nunca entra en reposo. La primera vez que ejecutas claude allí por SSH, la pantalla de inicio de sesión te pide abrir un navegador, y el equipo no tiene navegador.

El navegador de tu portátil puede abrir el enlace, pero después de iniciar sesión intenta devolverte a localhost en el portátil, donde no escucha nada. Unas semanas después caducan las credenciales y vuelves a pasar por lo mismo, quizá desde el móvil en un tren.

Así que las preguntas de verdad son: cómo iniciar sesión una vez, cómo mantener la sesión y qué hacer cuando no estás delante de un teclado.

Opción 1: inicia sesión en Claude Code por SSH pegando un código

Es el camino normal, y la documentación de autenticación de Anthropic lo describe para SSH y equipos sin interfaz gráfica.

ssh you@server
claude

En la pantalla de inicio de sesión:

  1. Pulsa c para copiar la URL de inicio de sesión, o selecciónala.
  2. Ábrela en un navegador del portátil o el móvil e inicia sesión.
  3. El navegador no llega al callback del servidor, así que muestra un código en lugar de redirigir.
  4. Pega ese código en el prompt Paste code here if prompted.

Dónde se complica:

  • El atajo de copiar copia al portapapeles del servidor, al que no llegas por SSH. Una issue de GitHub en el repositorio de Claude Code informa de que la URL se parte dentro de la interfaz de inicio de sesión a pantalla completa y tampoco se puede seleccionar. Si te pasa, usa la opción 2.
  • tmux y las terminales estrechas pueden partir la URL en varias líneas. Ensancha la ventana o amplía el panel antes de copiar.
  • Las credenciales caducan. Cuando lo hacen, la siguiente sesión en ese equipo vuelve a pararse en la pantalla de inicio de sesión y toca repetir esto por SSH.

Opción 2: inicia sesión en Claude Code con un claude setup-token de larga duración

Para un equipo delante del que no se sienta nadie, Anthropic documenta un token OAuth de un año. Lo creas una vez en un ordenador con navegador:

# on your laptop
claude setup-token

Abre el mismo inicio de sesión en el navegador que /login, imprime el token y no lo guarda en ningún sitio. Cópialo y, en el servidor:

# on the server, in the environment the agent runs in
export CLAUDE_CODE_OAUTH_TOKEN=your-token
claude

Lo que dice la documentación de Anthropic sobre este token:

  • Requiere una suscripción Pro, Max, Team o Enterprise.
  • Solo puede hacer peticiones al modelo, así que no puede iniciar sesiones de Claude Code Remote Control ni obtener conectores de claude.ai. Los servidores MCP que configures en local siguen funcionando.
  • El modo --bare no lo lee. Si un script pasa --bare, usa una clave de API.

Dos notas prácticas:

  • Guarda el token en un sitio que solo pueda leer tu usuario, como un archivo 0600 que cargues, y no en un perfil de shell de un equipo compartido. Cualquier cosa que pueda leerlo puede gastar tu suscripción.
  • Defínelo donde arranca realmente el agente. Si Claude Code lo lanza un servicio en segundo plano, una variable exportada en tu shell interactiva no estará allí. Es un motivo habitual de que un token "funcione por SSH pero no desde el servicio".

Opción 3: usa una clave de API de Anthropic en el servidor

export ANTHROPIC_API_KEY=sk-ant-...
claude

Claude Code te pide una vez que apruebes la clave y después se salta el navegador. Se factura por token a través de Claude Console, aparte de una suscripción Pro o Max. Encaja con scripts y tareas programadas.

Mantén la sesión de Claude Code para las sesiones que abres desde el móvil

Las opciones 1 a 3 resuelven el primer inicio de sesión. Lo difícil es el segundo: una sesión que abres desde el móvil un mes después, atascada en un inicio de sesión caducado en un equipo al que no estás conectado por SSH.

Si quieres iniciar y guiar sesiones de Claude Code en el servidor desde el móvil, y ver cuándo una está bloqueada en el inicio de sesión sin abrir una app de SSH, Happier es una app de código abierto para ejecutar y orquestar Claude Code, Codex y otros agentes entre dispositivos, desde el móvil, el escritorio o la web.

El agente se ejecuta en tu propio ordenador o servidor, y la app del móvil, de escritorio o web se conecta a él. Cómo usar Happier desde el móvil explica la configuración. Está en GitHub, puedes descargarlo aquí y hay un Discord.

Así funciona la parte del inicio de sesión.

1) Empareja el servidor con Happier escaneando un código QR

En el servidor:

curl -fsSL https://happier.dev/install | bash
happier auth login --method mobile

La terminal muestra un código QR. Escanéalo con la app de Happier en el móvil y apruébalo. Si estás en un portátil que ya tiene la CLI de Happier, happier auth pair-remote --ssh you@server hace el emparejamiento por SSH.

2) Inicia sesión en Claude Code en el servidor desde la app de Happier

En la app, abre Configuración (Settings) → IA y agentes (AI & Agents) → Configuración del proveedor de IA (AI backends) → Claude, elige el servidor (una máquina en Happier) en la barra de contexto y mira la sección Autenticación (Authentication). Muestra si Claude Code tiene la sesión iniciada en ese ordenador y cómo.

Iniciar sesión (Log in) o Volver a autenticar (Reauthenticate) abre una Terminal de inicio de sesión del proveedor (Provider login terminal) que ejecuta Claude Code en el servidor y envía /login por ti. Abres la URL en el móvil, inicias sesión y pegas el código en esa terminal. Es la opción 1, sin la app de SSH. Comprobar ahora (Check now) actualiza el estado después de iniciar sesión de otra forma.

3) Guarda el setup-token de Claude en Happier una vez

Si prefieres usar un setup-token, Happier puede guardarlo como servicio conectado:

claude setup-token          # on a computer with a browser
happier connect claude      # paste the token when asked

happier connect claude pide un setup-token por defecto. El token se guarda cifrado en tu cuenta de Happier y solo se descifra en tus propios dispositivos. Aparece en Configuración (Settings) → Servicios conectados (Connected services), y puedes elegirlo al iniciar una sesión de Claude en cualquiera de tus ordenadores. Una clave de API de Anthropic funciona igual con happier connect claude --api-key.

El límite, dicho claramente: el servidor tiene que estar encendido y accesible. Happier no mantiene con sesión iniciada un equipo apagado, y las normas del proveedor sobre el token siguen aplicándose.

Solución de problemas

Al pulsar c en el inicio de sesión de Claude Code no se copia nada que pueda pegar

La copia va al servidor, no a tu portátil. Selecciona la URL con la selección de tu terminal, ensancha la ventana para que no se parta o usa claude setup-token en otro ordenador.

El navegador no llega a localhost después del inicio de sesión de Claude

Es el callback intentando llegar a tu portátil. Vuelve a la pestaña del navegador que muestra un código, o reinicia el inicio de sesión y busca el paso del código. Por SSH, el código es el camino previsto.

Claude Code funciona por SSH, pero las sesiones que inicia un servicio me piden iniciar sesión

El servicio no ve el entorno de tu shell interactiva. Define CLAUDE_CODE_OAUTH_TOKEN en el entorno del servicio, o guarda el token como servicio conectado para que la sesión lo reciba al arrancar.

Claude Code Remote Control no arranca con un setup-token

La documentación de Anthropic dice que el setup-token solo puede hacer peticiones al modelo, así que Remote Control necesita el inicio de sesión normal de claude.ai de la opción 1.

Preguntas frecuentes

¿Puedo iniciar sesión en Claude Code sin ningún navegador?

Necesitas un navegador en algún sitio, una vez. Puede ser el del portátil o el del móvil. claude setup-token y el inicio de sesión por código usan un navegador en otro dispositivo. Solo una clave de API se salta el navegador por completo.

¿Cuánto dura el setup-token?

Un año, según la documentación de Anthropic. Se imprime una vez y no se guarda en ningún sitio, así que guárdalo antes de cerrar la terminal.

¿Necesito Claude Pro o Max para esto?

Para el inicio de sesión por código y el setup-token necesitas una suscripción de Claude (el setup-token requiere Pro, Max, Team o Enterprise). Una clave de API no necesita suscripción y se factura a través de la Console.

¿Puedo copiar ~/.claude del portátil al servidor?

Hay quien lo hace, pero no es un método de inicio de sesión documentado, y las credenciales copiadas pueden dejar de funcionar cuando el proveedor las rota. El setup-token es la forma documentada de reutilizar un inicio de sesión en otro ordenador.

¿Funciona igual en una Raspberry Pi o un VPS?

Sí. Los pasos no dependen del hardware, solo de que el equipo no tenga navegador.

Guías relacionadas

claudesshlinuxheadlessself-host
Última actualización: 2026-10-26