OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Remote access

Tailscale

OpenClaw puede configurar automáticamente Tailscale Serve (tailnet) o Funnel (público) para el panel del Gateway y el puerto WebSocket. Esto mantiene el Gateway enlazado a local loopback mientras Tailscale proporciona HTTPS, enrutamiento y, en el caso de Serve, encabezados de identidad.

Modos

gateway.tailscale.mode:

Modo Comportamiento
serve Serve solo para la tailnet mediante tailscale serve. El Gateway permanece en 127.0.0.1.
funnel HTTPS público mediante tailscale funnel. Requiere una contraseña compartida.
off (predeterminado) Sin automatización de Tailscale.

La salida de estado y auditoría usa exposición de Tailscale para este modo Serve/Funnel de OpenClaw. off significa que OpenClaw no administra Serve ni Funnel; no significa que el daemon local de Tailscale esté detenido o que se haya cerrado la sesión.

Ejemplos de configuración

Solo tailnet (Serve)

json5
{  gateway: {    bind: "loopback",    tailscale: { mode: "serve" },  },}

Abra: https://<magicdns>/ (o el valor configurado de gateway.controlUi.basePath)

Para exponer la interfaz de control mediante un servicio de Tailscale con nombre en lugar del nombre de host del dispositivo, establezca gateway.tailscale.serviceName en el nombre del servicio:

json5
{  gateway: {    bind: "loopback",    tailscale: { mode: "serve", serviceName: "svc:openclaw" },  },}

Al iniciarse, se muestra la URL del servicio como https://openclaw.<tailnet-name>.ts.net/ en lugar del nombre de host del dispositivo. Los servicios de Tailscale requieren que el host sea un nodo etiquetado aprobado en su tailnet; configure la etiqueta y apruebe el servicio en Tailscale antes de habilitar esta opción. De lo contrario, tailscale serve --service=... falla durante el inicio del Gateway.

Solo tailnet (enlace a la IP de la tailnet)

Use esta opción para que el Gateway escuche directamente en la IP de la tailnet, sin Serve ni Funnel:

json5
{  gateway: {    bind: "tailnet",    auth: { mode: "token", token: "your-token" },  },}

Conéctese desde otro dispositivo de la tailnet:

  • Interfaz de control: http://<tailscale-ip>:18789/
  • WebSocket: ws://<tailscale-ip>:18789

Internet público (Funnel + contraseña compartida)

json5
{  gateway: {    bind: "loopback",    tailscale: { mode: "funnel" },    auth: { mode: "password", password: "replace-me" },  },}

Es preferible usar OPENCLAW_GATEWAY_PASSWORD en lugar de guardar una contraseña en el disco.

Ejemplos de CLI

bash
openclaw gateway --tailscale serveopenclaw gateway --tailscale funnel --auth password

Autenticación

gateway.auth.mode controla el protocolo de enlace:

Modo Caso de uso
none Solo entrada privada
token (predeterminado cuando se establece OPENCLAW_GATEWAY_TOKEN) Token compartido
password Secreto compartido mediante OPENCLAW_GATEWAY_PASSWORD o la configuración
trusted-proxy Proxy inverso con reconocimiento de identidad; consulte Autenticación mediante proxy de confianza

Encabezados de identidad de Tailscale (solo Serve)

Cuando tailscale.mode: "serve" y gateway.auth.allowTailscale es true, la autenticación de la interfaz de control/WebSocket puede usar los encabezados de identidad de Tailscale (tailscale-user-login) en lugar de un token o una contraseña. OpenClaw verifica el encabezado resolviendo la dirección x-forwarded-for de la solicitud mediante el daemon local de Tailscale (tailscale whois) y comparándola con el nombre de inicio de sesión del encabezado antes de aceptarla. Una solicitud solo cumple los requisitos para esta ruta cuando llega desde local loopback e incluye los encabezados x-forwarded-for, x-forwarded-proto y x-forwarded-host de Tailscale.

Este flujo sin token presupone que el host del Gateway es de confianza. Si puede ejecutarse código local que no sea de confianza en el mismo host, establezca gateway.auth.allowTailscale: false y exija en su lugar autenticación mediante token o contraseña.

Alcance de la omisión:

  • Se aplica únicamente a la superficie de autenticación WebSocket de la interfaz de control. Los endpoints de la API HTTP (/v1/*, /tools/invoke, /api/channels/*, etc.) nunca usan autenticación mediante encabezados de identidad de Tailscale; siempre siguen el modo normal de autenticación HTTP del Gateway.
  • En las sesiones de operador de la interfaz de control que ya incluyen la identidad del dispositivo del navegador, una identidad de Tailscale verificada omite el recorrido de ida y vuelta del emparejamiento mediante token de arranque o código QR.
  • No omite la identidad del propio dispositivo: los clientes sin dispositivo siguen siendo rechazados y las conexiones con rol de nodo siguen pasando por las comprobaciones normales de emparejamiento y autenticación.

Notas

  • Tailscale Serve/Funnel requiere que la CLI tailscale esté instalada y tenga una sesión iniciada.
  • tailscale.mode: "funnel" se niega a iniciarse a menos que el modo de autenticación sea password, para evitar la exposición pública.
  • gateway.tailscale.serviceName solo se aplica al modo Serve y se pasa a tailscale serve --service=<name>. El valor debe usar el formato svc:<dns-label> de Tailscale, por ejemplo, svc:openclaw. Tailscale exige que los hosts del servicio sean nodos etiquetados y es posible que el servicio necesite aprobación en la consola de administración antes de que Serve pueda publicarlo.
  • gateway.tailscale.resetOnExit deshace la configuración de tailscale serve/tailscale funnel al cerrar.
  • gateway.tailscale.preserveFunnel: true mantiene activa una ruta tailscale funnel configurada externamente durante los reinicios del Gateway. Con mode: "serve", OpenClaw comprueba tailscale funnel status antes de volver a aplicar Serve y lo omite cuando una ruta de Funnel ya cubre el puerto del Gateway. La política de OpenClaw que exige únicamente contraseña para el Funnel administrado no cambia.
  • gateway.bind: "tailnet" usa un enlace directo a la tailnet (sin HTTPS ni Serve/Funnel), además del acceso local obligatorio mediante 127.0.0.1 cuando hay disponible una dirección IPv4 de la tailnet; de lo contrario, recurre únicamente a local loopback.
  • gateway.bind: "auto" prefiere local loopback; use tailnet para limitar la exposición de red a la tailnet y conservar a la vez el acceso mediante local loopback desde el mismo host.
  • Serve/Funnel solo expone la interfaz de control del Gateway + WS. Los nodos se conectan mediante el mismo endpoint WS del Gateway, por lo que Serve también funciona para el acceso de los nodos.

Requisitos previos y limitaciones de Tailscale

  • Serve requiere que HTTPS esté habilitado para su tailnet; la CLI muestra una solicitud si falta.
  • Serve inserta encabezados de identidad de Tailscale; Funnel no.
  • Funnel requiere Tailscale v1.38.3 o posterior, MagicDNS, HTTPS habilitado y un atributo de nodo de Funnel.
  • Funnel solo admite los puertos 443, 8443 y 10000 mediante TLS.
  • Funnel en macOS requiere la variante de código abierto de la aplicación Tailscale.

Control del navegador (Gateway remoto + navegador local)

Para ejecutar el Gateway en una máquina, pero controlar un navegador en otra, ejecute un host de nodo en la máquina del navegador y mantenga ambas en la misma tailnet. El Gateway actúa como proxy de las acciones del navegador hacia el nodo; no se necesita ningún servidor de control ni URL de Serve independientes.

Evite Funnel para controlar el navegador; trate el emparejamiento del nodo como acceso de operador.

Más información

Temas relacionados

Was this useful?
On this page

On this page