Documentación › Agentes de IA
Agentes de IA
Los agentes corren en las tarjetas con tu propia cuenta, en tu computadora o en tus servidores. Conectados por cables, se hacen pedidos entre ellos y ejecutan comandos en los shells que permitas, siempre a la vista.
Octopus usa el Claude Code y el Codex que ya tienes, con tu cuenta (Claude Pro o Max, ChatGPT Plus o Pro) o con una clave de API. Los límites son los de tu plan, y las conversaciones quedan en tus máquinas.
Paso a paso
- Abre una Nueva terminal (⌘TCtrl+Shift+T) y elige el bloque Claude Code o Codex.
- La primera vez en una máquina, inicia sesión en tu cuenta: en tu computadora, desde el navegador; en un servidor, con un enlace y un código.
- El agente ya empieza sabiendo que está en una tarjeta de Octopus. Cuando hablas de una nota, de un archivo adjunto o de otro agente, busca lo que está conectado a él.
- La pestaña de la tarjeta muestra el estado: “· trabajando” o “· esperándote”. El borde se pone ámbar cuando te llama y verde cuando termina.
| Nueva terminal | ⌘TCtrl+Shift+T |
Cada agente se puede ver como terminal o como chat, con la misma conversación.
Ver tambiénChat | TerminalSkills instaladasTe llama y Terminó
¿Abriste un Claude Code o un Codex en una máquina donde no está instalado? Octopus ofrece instalarlo ahí mismo, incluso en un servidor, y abre el agente cuando termina.
Paso a paso
- Crea la terminal del agente como siempre. Si no existe en la máquina, aparece, por ejemplo, “Codex no está instalado en staging”.
- Haz clic en “Instalar Codex”. Una tarjeta “Instalando Codex” ejecuta el instalador oficial, sin contraseña, a la vista.
- Después de la instalación, inicia sesión en tu cuenta: en tu computadora, desde el navegador; en un servidor, con un enlace y un código.
- Cuando todo termina, la tarjeta de la instalación se cierra y se abre el agente.
- ¿Prefieres instalarlo a tu manera? “Abrir un Shell” abre un shell en la misma carpeta.
La primera vez que abres Octopus, la configuración rápida también instala tmux, Claude Code y Codex en tu computadora.
Ver tambiénClaude Code y Codex con tu cuenta
Un Claude Code o Codex abierto fuera de Octopus (en un tmux antiguo, o escrito a mano en una tarjeta Shell) corre sin alertas, sin chat y sin Maestro. Convertir reabre la misma conversación, en el mismo tmux, ya con todo eso.
Paso a paso
- Un agente externo aparece con la insignia “externo” en la pestaña. La barra de la tarjeta muestra el botón Convertir (también en el clic derecho › “Convertir…”).
- Haz clic en Convertir. El aviso lista lo que gana: alertas cuando te necesite, el chat de Octopus, retomar la conversación después de reiniciar, Maestro y mensajes entre agentes.
- Si está trabajando, elige “Convertir cuando pare” (la insignia pasa a decir “se convierte al parar”) o “Convertir ahora”. Si está detenido, haz clic en “Convertir”. “Ahora no” lo deja como está.
- La insignia muestra “convirtiendo…” y, al final, un aviso lo confirma. La conversación, los archivos y el tmux siguen igual; solo se reinicia el proceso del agente.
- Al traer sesiones de un servidor, “Traer y convertir” lo hace todo de una vez.
Si el agente no se cierra para la conversión, Octopus te pide que lo cierres (Ctrl-C) y lo intentes de nuevo.
Ver tambiénHacer clic en un servidor: las sesiones que ya corren
Cuando Claude Code manda una sesión a segundo plano, sigue hablando con Octopus: usa las notas y las tarjetas conectadas y avisa cuando te necesita.
Paso a paso
- En Claude Code, manda la sesión a segundo plano como siempre (por ejemplo, con /background).
- Sigue con octo: lee las notas conectadas, habla con los otros agentes y le manda los avisos a Octopus.
- En el chat, lo que corre en segundo plano aparece en la caja encima del mensaje.
Mientras un trabajo suyo corre por detrás (pruebas, una ronda larga), la tarjeta sigue con el indicador de trabajo; el aviso “Terminó” solo sale cuando todo acaba.
Ver tambiénWorkflow y agentes en segundo planoTrabajo de fondo y Quién decide
Conecta dos tarjetas con un cable y los agentes empiezan a intercambiar pedidos y respuestas, incluso en máquinas distintas. Un Claude Code en tu computadora puede pedirle un entrenamiento a Codex en gpu-01 y esperar el resultado.
Paso a paso
- Selecciona una tarjeta, presiona ⌘LCtrl+Shift+L (o el botón Conectar de la barra) y haz clic en la otra tarjeta. Aparece el cable.
- Pídeselo a tu agente con palabras comunes: “pregúntale a Codex si pasan las pruebas”. Usa octo ask y espera la respuesta.
- A la otra tarjeta llega un mensaje que empieza con “[Octopus] Pedido de” y trae el número del pedido. El agente hace el trabajo y responde con octo reply; la respuesta vuelve a quien preguntó.
- Para seguir el trabajo sin interrumpir, el agente usa octo check y ve la pantalla actual del otro.
- En un chat, esos mensajes aparecen como “Mensaje de otro agente a través de Octopus”.
| Iniciar conexión | ⌘LCtrl+Shift+L |
Los mensajes largos llegan completos, y cada pedido tiene un número: la respuesta siempre encuentra a quien preguntó. Si la respuesta tarda más que la espera, llega después, como “[Octopus] Resposta de”.
Ver tambiénocto ask, check y replyComandos en un shell conectadoTentáculos (cables)
Un agente conectado a un shell ejecuta comandos en él con octo run. El comando aparece escrito en la tarjeta, en la carpeta y con las variables de ese shell, y la salida completa y el código de salida vuelven al agente.
Paso a paso
- Conecta el agente a una tarjeta Shell, o usa “Shell al lado”.
- Pide la tarea: “mira los logs de la API en staging”. El agente ejecuta octo run en el shell y ves cómo se escribe el comando ahí.
- octo run espera a que el comando termine y devuelve la salida y el código de salida. Si se pasa del tiempo, sigue corriendo y el agente lo sigue con octo run --wait.
- Para responder a una pregunta del programa (un [y/N]) o interrumpirlo, el agente manda teclas con octo keys, como y, Enter o C-c.
- Con octo run --fora, el comando corre por fuera de la tarjeta, sin aparecer ni estorbar lo que hay en el shell. Sirve para lecturas rápidas: estado, logs, espacio en disco.
- Con octo copy, el agente copia archivos y carpetas entre las máquinas de los shells conectados a él, directo de servidor a servidor cuando uno alcanza al otro.
El agente nunca escribe contraseñas por ti: si un comando pide contraseña, te pide que la escribas en la tarjeta.
Ver tambiénEl bloqueo “Comandos de agentes”octo run, keys y copyShell al lado
Cada tarjeta Shell tiene su bloqueo: Libre, Preguntar o Bloqueado. Decide si los agentes conectados ejecutan comandos, teclas y copias ahí sin preguntar, solo con tu aprobación, o nunca.
Paso a paso
- Haz clic derecho en una tarjeta Shell y abre “Comandos de agentes”.
- “Libre”: los agentes conectados ejecutan comandos ahí sin preguntar. “Preguntar”: cada comando espera a que lo permitas. “Bloqueado”: ningún comando de agente se ejecuta ahí.
- En los servidores marcados como “Servidor de producción” (hoja del servidor, en Avanzado), los shells empiezan en “Preguntar”.
- El agente ve el bloqueo de cada shell en octo list. Un rechazo vale para ese comando: no insiste y te pregunta en la conversación.
El bloqueo vale para octo run, octo keys y octo copy. Cambiar el bloqueo deshace los permisos “en esta sesión” de ese shell.
Ver tambiénAprobar un comandoRegistrar un servidor
Con el bloqueo en “Preguntar”, el pedido del agente aparece en una hoja: quién pide, en qué shell y máquina, y el comando completo. Lo permites una vez, lo permites en esta sesión o lo rechazas.
Paso a paso
- Cuando un agente pide, se abre la hoja y su tarjeta se pone ámbar, con el motivo “Pidió ejecutar en” y el nombre del shell.
- Lee el comando. La línea de arriba dice la máquina y el tipo de pedido: en la tarjeta, por fuera de la tarjeta, teclas o copia de archivos.
- “Permitir” (↩Enter) ejecuta solo este comando. “Permitir en esta sesión” libera a este agente en este shell hasta que Octopus se cierre. “Rechazar” (Esc) no ejecuta nada.
- Si no respondes en 90 segundos, el pedido cuenta como rechazado y el agente se entera.
| Permitir | ↩Enter |
| Rechazar | Esc |
Los pedidos aparecen de uno en uno: mientras uno espera tu respuesta, los demás esperan en la cola.
Ver tambiénEl bloqueo “Comandos de agentes”Te llama y Terminó
En el menú de una tarjeta de agente, “Copiar ID de la sesión” copia el identificador de la conversación, para retomarla en otro lugar. “Copiar diagnóstico de alertas” copia lo que la tarjeta recibió y decidió sobre las alertas y el estado “en ejecución”.
Paso a paso
- Haz clic derecho en la tarjeta de Claude Code o de Codex.
- “Copiar ID de la sesión”: un aviso muestra el ID copiado (pasa el ratón por el elemento para verlo antes). Si el agente todavía no guardó la conversación, Octopus avisa.
- “Copiar diagnóstico de alertas” (desde la 1.0.16): pégalo en una conversación para explicar una alerta que no llegó o llegó a destiempo.
En el chat, el ID también aparece en el panel del anillo de contexto, en “Sesión”, con “Copiar”.
Ver tambiénContexto y límites del planCopiar diagnóstico de alertas
En cada máquina donde abre terminales, Octopus instala dos skills para Claude Code y Codex: “octopus”, que le enseña al agente a usar el lienzo, y “octopus-maestro”, para cuando es el Maestro.
Paso a paso
- Quedan en ~/.claude/skills y ~/.codex/skills, en tu computadora y en cada servidor, junto con el comando octo. Octopus lo mantiene todo actualizado.
- La skill octopus entra en acción cuando hablas de algo conectado a la tarjeta: una nota, una imagen adjunta, otro agente, un shell, un portal, una cuenta en la nube o un dibujo.
- La skill octopus-maestro solo vale para un agente en modo Maestro: decidir si reparte el trabajo, reclutar, seguir y cerrar el equipo.
- Al abrir un agente, Octopus también le avisa, desde el principio, que está en una tarjeta del lienzo.
En un servidor con más de un perfil de Claude Code (CLAUDE_CONFIG_DIR en las variables del servidor), la skill va a cada perfil.
Ver tambiénLas skills octopus y octopus-maestroQué es el Maestro