Guía de instalación para Agentes

Por favor, lee https://linkly.ai/docs/es/agent-setup.md y guíame en la instalación e integración de Linkly AI

​

Para el agente de IA

​

Tu tarea

1. La aplicación de escritorio Linkly AI esté instalada, inicializada e indexando: con los ejemplos incluidos basta; los documentos propios del usuario son un extra; y
2. Tú —u otra herramienta de IA que el usuario posea— puedas invocar realmente las herramientas de recuperación de Linkly AI y encontrar un documento real.

​

Tus límites y reglas

• Puedes hacer tú mismo: ejecutar comandos de sondeo, instalar la CLI, configurar MCP, instalar Skills, ejecutar comandos de verificación, interpretar errores e informar de los resultados. Para cualquier cosa que instale software, muestra el comando y obtén consentimiento primero.
• El usuario debe hacer: descargar y ejecutar el instalador, completar el asistente de configuración, añadir carpetas de documentos en la aplicación y conceder permisos del sistema. Son acciones de interfaz gráfica: tú no puedes hacerlas.

• Sondea antes de actuar. Puede que el usuario ya tenga parte de la configuración hecha, o que esté reinstalando: no recorras a ciegas todos los pasos desde el principio.
• Verifica cada paso. Cada paso indica su criterio de aceptación. Si la comprobación no pasa, no avances.
• Cuando el usuario deba actuar, dilo todo de una vez, luego detente y espera una única respuesta. No dividas una misma tarea en varias rondas de confirmación de ida y vuelta.
• Muestra los comandos de instalación y obtén consentimiento antes de ejecutarlos, especialmente cualquier cosa que descargue y ejecute un script desde la red.
• Nunca exageres el progreso. Si no está verificado, no está hecho. Di exactamente dónde te has atascado y qué has intentado.
• No eludas los requisitos de permisos, seguridad o verificación. Cuando la sección Resolución de problemas no cubra un problema, ejecuta primero linkly doctor y consulta la guía oficial correspondiente; si usas un enfoque no listado aquí, explica tu motivo y vuelve a verificar.

​

Primero, comprueba si puedes ejecutar comandos

​

Paso 0: Sondear el estado actual

echo "--- 1. port file ---"
cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE"
echo ""
echo "--- 2. health ---"
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null)
curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE"
echo ""
echo "--- 3. cli ---"
linkly --version 2>/dev/null || echo "NO_CLI"
echo "--- 4. status ---"
linkly status --json 2>/dev/null || echo "NO_STATUS"
echo "--- 5. skills ---"
ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS"

Write-Output "--- 1. port file ---"
$port = 60606
if (Test-Path "$HOME\.linkly\port") {
  Get-Content "$HOME\.linkly\port"
  $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port
} else { Write-Output "NO_PORT_FILE" }
Write-Output "--- 2. health ---"
try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" }
Write-Output "--- 3. cli ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" }
Write-Output "--- 4. status ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" }
Write-Output "--- 5. skills ---"
if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" }

​

Cómo interpretar los resultados

{
  "version": "0.8.1",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1"]
}

• Nunca codifiques de forma fija el puerto 60606. Es solo el valor por defecto; si el puerto está ocupado, la aplicación va incrementándolo. Lee siempre el puerto real de ~/.linkly/port, cuyo contenido es JSON compacto: {"port":60606}.
• Que exista el archivo de puerto no significa que el servicio esté en ejecución. El archivo queda atrás cuando la aplicación se cierra a la fuerza o se bloquea. Juzga el estado únicamente por si /health devuelve 200.
• Que mcp_endpoint sea null significa que el interruptor de MCP está desactivado (/health sigue devolviendo 200). No te pongas a depurar el puerto: pide al usuario que lo active en Ajustes → MCP.
• Valores de index_status: watching (terminado — la CLI muestra Up to date), scanning, indexing, idle, error.
• doc_count es el número de documentos indexados: úsalo para calibrar el progreso de la indexación, no como prueba concluyente de que los archivos del usuario se han recogido: es solo un total, y 151 frente a 150 apenas se distingue cuando solo se añadió uno o dos archivos.

​

Tabla de estados

​

Paso 1: Instalar e inicializar

​

1. Descargar e instalar

• macOS: haz doble clic en el .dmg para montarlo, arrastra el icono de LinklyAI a Applications y luego inícialo desde Launchpad.
• Windows: haz doble clic en el .exe y sigue el asistente (se instala en el directorio del usuario por defecto), luego inícialo desde el menú Inicio.
• Linux: AppImage — chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage; o deb — sudo dpkg -i linkly-ai-*.deb.

​

2. Completar el asistente del primer inicio

• Portada: elige el idioma de la interfaz y el tema. Debes marcar «He leído y acepto la Política de Privacidad» para continuar. En la misma pantalla hay un interruptor de telemetría, «Ayuda a mejorar Linkly AI», activado por defecto, que puedes desactivar.
• Inicio de sesión (1/2): al pulsar «Iniciar sesión / Registrarse» se abre el navegador para el flujo OAuth. Este paso se puede omitir: el acceso para omitirlo es un enlace «omitir el inicio de sesión» en una línea de texto pequeño al final. Dile al usuario: iniciar sesión solo sirve para obtener rápidamente la cuota de prueba de los modelos de IA oficiales y las funciones de biblioteca de conocimiento en la nube, lo que facilita probarlo; la indexación local, la búsqueda local y el servicio MCP no necesitan conexión a internet en absoluto.
• Preparación (2/2): la aplicación descomprime un conjunto de documentos de ejemplo incluidos y los indexa, normalmente en unos minutos. Espera a que se active el botón «Empezar».
• Panel de inicio: seis tarjetas de funciones. Haz clic en cualquier tarjeta para probar la función principal; haz clic en la × de la esquina superior derecha para finalizar el asistente.

​

3. Añade tus propias carpetas de documentos (opcional)

• Abre Ajustes → Carpetas y añade los directorios a indexar (Documentos, Descargas, un directorio de proyecto, etc.);
• O deja archivos en la carpeta ~/LinklyAI: está vigilada por defecto, así que todo lo que se coloque ahí se indexa automáticamente.

​

4. Ten en cuenta que los modelos se descargan en segundo plano (no requiere acción, pero avisa al usuario)

• La búsqueda por palabras clave funciona de inmediato y no se ve afectada en absoluto;
• La búsqueda semántica espera a que terminen la descarga y la indexación. Hasta entonces, search recurre automáticamente a la recuperación solo por palabras clave (texto completo): la relevancia baja ligeramente. Es el comportamiento esperado, no un fallo.

​

5. Responde una sola vez cuando todo esté hecho

​

Paso 2: Conectar la vía de acceso a las herramientas

PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port)
MCP_URL="http://127.0.0.1:$PORT/mcp"

​

Opción A: Instalar la CLI (recomendado)

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

brew tap LinklyAI/tap
brew install linkly

irm https://updater.linkly.ai/cli/install.ps1 | iex

cargo install linkly-ai-cli

• macOS / Linux: se instala en ~/.linkly/bin/linkly, con el PATH añadido a .zshrc / .bashrc / .profile;
• Windows: se instala en %LOCALAPPDATA%\linkly\bin\linkly.exe, modificando el PATH a nivel de usuario.

​

Opción B: Configurar MCP

• Claude Code: claude mcp add --transport http linkly-ai "$MCP_URL"
• Codex: codex mcp add linkly-ai --url "$MCP_URL"
• Cursor: Settings → MCP Servers → Add Server; Name linkly-ai, Type StreamableHTTP, la URL es el valor resuelto de $MCP_URL.

curl -sf --max-time 5 -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

​

Paso 3: Instalar Skills

npx skills add LinklyAI/linkly-ai-skills

# Claude Code (user level)
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai

# Codex CLI
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai

https://updater.linkly.ai/skills/linkly-skills-latest.zip

​

Paso 4: Verificación de extremo a extremo

linkly search "Holmes" --json

Tras recargar/iniciar una nueva sesión, pídeme «busca Holmes con linkly-ai»: si devuelve entradas de documentos, toda la cadena funciona.

​

Resolución de problemas

​

Informa cuando hayas terminado

• qué pasos completaste y por qué vía (CLI o MCP);
• si es necesario reiniciar la sesión para que algo surta efecto;
• el estado actual de la indexación y el número de documentos;
• cómo usarlo realmente — por ejemplo, añadiendo use linkly-ai a cualquier prompt, o pulsando CMD/Ctrl + Shift + L para abrir el lanzador de búsqueda.

​

Termina con cuatro preguntas de ejemplo

1. Lee A Life in 10 Years y analiza los patrones de vida recurrentes en los diez años de diarios de Samuel Pepys, y los puntos ciegos que quizá él mismo nunca llegó a ver.
2. ¿En qué gana realmente Sherlock Holmes? Lee los 12 casos de Detectives Library, extrae su fórmula para resolver casos y convierte el método de Holmes en una checklist para diagnosticar problemas de negocio complejos.
3. ¿Qué temían realmente los fundadores de Estados Unidos? Lee los Federalist Papers completos y dame una respuesta. Explica cómo diseñaron un sistema donde la ambición frena a la ambición y las facciones se equilibran, y luego traduce esa lógica en principios de gobernanza para las empresas de IA o las plataformas de internet de hoy.
4. Tras leer los recuerdos contados en primera persona por cientos de personas antes esclavizadas, ¿qué es lo que los libros de historia de Estados Unidos menos se atreven a contar en detalle? Responde basándote en las WPA Slave Narratives.

​

Lecturas adicionales

• Inicio rápido — la guía completa de instalación e incorporación, escrita para personas
• Usar CLI — todos los subcomandos y parámetros de la CLI
• Usar MCP — los tres modos de acceso y la configuración por cliente
• Usar Skills — cómo se instalan Skills y cómo funcionan