# Instrucciones de instalación para Claude Code — ChatCut Source: [Instrucciones de instalación para Claude Code — ChatCut]() Content index: [llms.txt]() ## Instrucciones de instalación de Claude Code Instala el plugin de Claude Code mantenido por ChatCut desde el marketplace público de ChatCut, fijado en `main`. ## Instalar e iniciar sesión Primero ejecuta estos dos comandos de instalación, en este orden: ```text claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main claude plugin install chatcut@chatcut-inc ``` El comando del marketplace clona un repositorio grande y puede tardar varios minutos. Ejecútalo como un proceso de larga duración, dale un tiempo de espera generoso y consulta su estado hasta que termine. Que no muestre nada durante un rato no significa que haya fallado; no lo canceles solo porque venza el tiempo de espera corto de un comando normal. Si es posible que ya se haya usado ChatCut en este equipo, puedes comprobar si existe una configuración anterior de servidor MCP independiente: ```text claude mcp get chatcut ``` Si ese comando encuentra un servidor llamado exactamente `chatcut`, elimina la entrada independiente antigua antes de iniciar sesión: ```text claude mcp remove chatcut ``` No elimines `plugin:chatcut:chatcut`; es el servidor que gestiona el plugin recién instalado. Si `claude mcp get chatcut` indica que no existe tal servidor, continúa con normalidad. Después, inicia sesión en el servidor MCP de ChatCut con el script de inicio de sesión del plugin. ```text sh "${CLAUDE_PLUGIN_ROOT}/skills/chatcut-plugin-basics-claude/login-chatcut.sh" > /tmp/chatcut-login.log 2>&1 & ``` Lee de inmediato `/tmp/chatcut-login.log` y sigue consultándolo. Claude Code abrirá la página de autorización de ChatCut. Confirma la instalación después de autenticarte: ```text claude plugin list claude mcp get plugin:chatcut:chatcut ``` La lista de plugins debe mostrar `chatcut@chatcut-inc` como habilitado. La señal definitiva de que OAuth se ha completado correctamente es la salida de inicio de sesión `Authenticated with "plugin:chatcut:chatcut"`, no solo `Connected`. Por último, explica que ChatCut permite editar video, crear motion graphics y generar video, voz en off, música, efectos de sonido y otros recursos del proyecto. Las herramientas del plugin solo se cargan al iniciar una sesión, así que indica al usuario que haga clic en **New session** y formule una petición en lenguaje natural que mencione ChatCut, como «Usa ChatCut para ayudarme a…». No intentes usar una herramienta de ChatCut durante la sesión de instalación ni impongas un prompt fijo. Claude Code comparte `~/.claude` entre la CLI y la aplicación de escritorio, por lo que el plugin y la sesión de OAuth están disponibles en ambas, y la sesión se renueva automáticamente. ## Solución de problemas Trata toda la configuración como una sola operación continua. Un plugin instalado a medias o instalado pero sin autenticar es un estado de error: identifica el síntoma correspondiente de los que aparecen abajo, corrígelo y retoma el paso interrumpido. Cualquier confirmación inevitable del navegador, de la contraseña del sistema operativo o del instalador es un estado de espera activo, no el final de la tarea. ### Falta `claude` o la versión es demasiado antigua El comando de inicio de sesión requiere Claude Code `2.1.210` o una versión posterior. Comprueba ambas capacidades: ```text claude --version claude mcp login --help ``` Si el shell actual no puede resolver `claude`, comprueba primero `command -v claude` y `~/.local/bin/claude`. En Windows, localízalo también desde distintos shells con: ```text powershell.exe -NoProfile -Command "(Get-Command claude -ErrorAction SilentlyContinue).Source" cmd.exe /d /c where claude ``` Ejecuta directamente el archivo resuelto en vez de reinstalar, ya que un shell puede tener un `PATH` obsoleto o diferente. Tener Claude Code Desktop no garantiza por sí solo que exista la CLI para terminal. Solo si no existe ningún ejecutable de terminal, usa el instalador oficial de Anthropic: ```text # macOS / Linux / WSL curl -fsSL https://claude.ai/install.sh | bash # Windows PowerShell irm https://claude.ai/install.ps1 | iex ``` Si la CLI existe pero es demasiado antigua, no preguntes al usuario qué método de actualización prefiere. Ejecuta `claude update` con un tiempo de espera generoso y vuelve a comprobar ambos comandos. Si se bloquea, falla o sigue sin estar disponible `claude mcp login --help`, ejecuta `npm install -g @anthropic-ai/claude-code@latest` y vuelve a comprobarlo. Una actualización nativa puede necesitar una TTY: ```text python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude update ``` Si un instalador solicita la contraseña del sistema operativo o de administrador, indica una vez la acción exacta, sigue esperando y retoma el proceso automáticamente después. Si hay un proxy, configura el valor real de `HTTPS_PROXY` del usuario antes de reintentarlo. ### Añadir el marketplace tarda demasiado `claude plugin marketplace add` realiza una clonación de larga duración. Iníciala con un tiempo de espera adecuado para un repositorio grande y consulta el proceso en vez de ejecutarla una y otra vez. Deja que el proceso actual termine salvo que finalice con un error o esté claramente bloqueado más allá del tiempo de espera generoso. No ejecutes varios intentos de adición al marketplace a la vez. Si el proceso sigue activo pero sin mostrar nada, espera. Si el entorno de ejecución impone un tiempo de espera corto, ejecútalo en segundo plano o en un shell de larga duración, captura la salida en un registro, consulta tanto el estado del proceso como el registro y no vuelvas a intentarlo hasta que el proceso anterior haya terminado. ### La red impide añadir el marketplace Los tiempos de espera agotados, los errores de TLS/DNS, `fatal: early EOF` y el engañoso `fatal: Invalid path ...` suelen indicar una transferencia de GitHub interrumpida, no un nombre de archivo incorrecto en el repositorio. Reinténtalo con pausas progresivas sin detener la instalación. Usa el proxy que ya tenga configurado el usuario, si existe. Lee `HTTPS_PROXY` y `HTTP_PROXY`, o identifica la herramienta de proxy en ejecución y su puerto real; entre los puertos locales habituales están `7890`, `7897`, `1080`, `8080` y `8888`, pero no elijas uno a ciegas ni dejes configurado un proxy incorrecto. ```text # macOS / Linux example; substitute the user's actual proxy HTTPS_PROXY=http://127.0.0.1:7890 ALL_PROXY=http://127.0.0.1:7890 claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main # Windows PowerShell example $env:HTTPS_PROXY='http://127.0.0.1:7890'; $env:ALL_PROXY=$env:HTTPS_PROXY; claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main ``` Si la clonación completa del marketplace se interrumpe repetidamente, haz una clonación superficial como otro proceso de larga duración, consulta su estado hasta que termine y después añade la ruta local e instala: ```text git clone --depth 1 --branch main https://github.com/ChatCut-Inc/agent-plugin.git claude plugin marketplace add /path/to/agent-plugin claude plugin install chatcut@chatcut-inc ``` Si al añadir el marketplace aparece `program not found`, confirma `git --version`. Instala Git de forma no interactiva cuando sea posible con `brew install git`, `winget install Git.Git`, `apt-get install -y git` o `dnf install -y git`, asegúrate de que esté en `PATH` y vuelve a intentarlo. Espera durante cualquier confirmación inevitable del instalador del sistema operativo. ### El inicio de sesión indica que stdin no es un terminal El script de inicio de sesión del plugin inicia su propia PTY. Ejecútalo por la ruta normal en vez de invocar directamente `claude mcp login`. Si necesitas iniciar sesión directamente y `python3` no está disponible, usa la sintaxis de `script` específica de cada plataforma: ```text # macOS (BSD script) script -q /tmp/chatcut-login.log claude mcp login plugin:chatcut:chatcut & # Linux (util-linux script) script -qc "claude mcp login plugin:chatcut:chatcut" /tmp/chatcut-login.log & ``` No copies la forma de `script` de un sistema operativo en el otro. En Windows, intenta primero ejecutar el comando de inicio de sesión envuelto en una PTY desde un shell que tenga `python3` disponible: ```text python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude mcp login plugin:chatcut:chatcut > /tmp/chatcut-login.log 2>&1 & ``` Si ese shell no puede ejecutar `python3` ni el comando, confirma `cmd.exe /d /c where claude` y después usa una consola real desechable mientras capturas la salida: ```text Start-Process cmd -ArgumentList '/c','claude mcp login plugin:chatcut:chatcut > %TEMP%\chatcut-login.log 2>&1' ``` La consola puede aparecer en blanco porque la salida está redirigida. Consulta `$env:TEMP\chatcut-login.log`; abre la URL de autorización limpia en cuanto aparezca y sigue consultando el registro. ### Un servidor MCP antiguo de ChatCut entra en conflicto con el plugin Usa `claude mcp list` para distinguir entre un servidor independiente llamado `chatcut` y el servidor gestionado por el plugin llamado `plugin:chatcut:chatcut`. Elimina solo la entrada independiente con `claude mcp remove chatcut` y después verifica que `claude mcp get plugin:chatcut:chatcut` siga resolviéndose. Nunca elimines el servidor de plugin con espacio de nombres como parte de la limpieza. ### El inicio de sesión agota el tiempo de espera o devuelve un error 5xx Si el inicio de sesión muestra `Authentication timeout`, ejecuta inmediatamente el cierre de sesión, inicia un único proceso de inicio de sesión nuevo, muestra la nueva URL de autorización y vuelve a consultar el estado. Nunca ejecutes varios intentos de inicio de sesión a la vez. Antes de completar la autenticación, los errores HTTP 502 y otros 5xx durante el descubrimiento de OAuth, el registro, la gestión de la devolución de llamada o el intercambio de tokens son fallos reintentables del servicio, no credenciales incorrectas ni motivo para reinstalar. Espera a que termine el proceso de inicio de sesión actual, reinténtalo con pausas progresivas y, si quieres, comprueba la disponibilidad: ```text curl -fsS https://api.chatcut.io/.well-known/oauth-authorization-server ``` En Windows, usa `curl.exe`. Una respuesta correcta del endpoint de descubrimiento solo demuestra que ese endpoint está accesible; continúa hasta que el proceso de inicio de sesión muestre la línea de autenticación. ### `claude mcp login` no existe Actualiza Claude Code con los pasos de recuperación anteriores. Los envoltorios de seudoterminal solucionan los errores de shell no interactivo, así que una CLI antigua es el único motivo para recurrir a la interfaz de la aplicación. Solo después de obtener pruebas exactas de que han fallado las dos vías de actualización, indica al usuario que escriba `/mcp`, seleccione `chatcut` (`plugin:chatcut:chatcut`) y elija **Authenticate**. Sigue consultando `claude mcp get plugin:chatcut:chatcut` y retoma el proceso automáticamente cuando la autenticación esté disponible. ### Una solicitud de API o MCP devuelve 403 Pausa los reintentos automáticos mientras siga apareciendo el error 403. Conserva el proyecto actual y los archivos multimedia locales. Escribe a [team@chatcut.io](mailto:team@chatcut.io) con el error, la hora aproximada y la zona horaria, y la IP pública que usabas en ese momento. Incluye un ID de solicitud ya registrado, si lo tienes; no hace falta volver a importar ni generar contenido para enviar el informe. Un error 403 requiere revisar las reglas de acceso o de limitación de solicitudes. No demuestra que tus credenciales sean incorrectas. Cuando se restablezca el acceso, comprueba el estado de la tarea original antes de reanudarla. ### La verificación resulta confusa o las herramientas tardan `claude mcp get` puede mostrar `Connected` antes de que OAuth se complete. Si aparece `Needs authentication` antes de un inicio de sesión correcto, vuelve al bucle de inicio de sesión. `Connected · tools fetch failed` o `Request timed out` suele indicar que el backend está lento temporalmente; no reinstales ni detengas el proceso por ello. Después de que la salida de inicio de sesión ya haya confirmado la autenticación, una carga lenta de la lista de herramientas puede cambiar brevemente el estado a `Needs authentication`, y las primeras llamadas de la sesión nueva pueden agotar el tiempo de espera mientras el backend entra en funcionamiento. Reintenta el descubrimiento u otras cargas de solo lectura con esperas cada vez mayores; no repitas el inicio de sesión. Si una llamada a una herramienta agotó el tiempo de espera y pudo haber modificado el proyecto o iniciado una generación, comprueba el estado de la tarea original antes de repetirla. Trátalo como un problema real de autenticación solo si una herramienta de ChatCut devuelve repetidamente un error explícito `connector authentication is missing` en lugar de agotar el tiempo de espera. ## Recuperar una actualización fallida Los comandos normales de actualización son: ```text claude plugin marketplace update chatcut-inc claude plugin update chatcut@chatcut-inc ``` Si una actualización falla, aplica la solución correspondiente indicada arriba para la CLI, el marketplace de larga duración, la red o el proxy y después repite la verificación. Las herramientas actualizadas también se cargan solo en una **sesión nueva**; no ejecutes ni pidas al usuario que ejecute `/reload-plugins`.