# openclaw agents

Gestiona agentes aislados (espacios de trabajo + autenticación + enrutamiento).

Relacionado:

• Enrutamiento multiagente
• Espacio de trabajo del agente
• Configuración de Skills: configuración de visibilidad de Skills.

# Ejemplos

openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work

# Enlaces de enrutamiento

Usa enlaces de enrutamiento para fijar el tráfico entrante del canal a un agente específico.

Si también quieres Skills visibles diferentes por agente, configura agents.defaults.skills y agents.list[].skills en openclaw.json. Consulta Configuración de Skills y Referencia de configuración.

Listar enlaces:

openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json

Añadir enlaces:

openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a

Si omites accountId (--bind <channel>), OpenClaw lo resuelve a partir de los valores predeterminados del canal y los hooks de configuración del plugin cuando estén disponibles.

Si omites --agent para bind o unbind, OpenClaw apunta al agente predeterminado actual.

# Comportamiento del alcance de los enlaces

• Un enlace sin accountId coincide solo con la cuenta predeterminada del canal.
• accountId: "*" es la alternativa de respaldo para todo el canal (todas las cuentas) y es menos específica que un enlace de cuenta explícito.
• Si el mismo agente ya tiene un enlace de canal coincidente sin accountId, y más tarde enlazas con un accountId explícito o resuelto, OpenClaw actualiza ese enlace existente en su lugar en vez de añadir un duplicado.

Ejemplo:

# initial channel-only binding
openclaw agents bind --agent work --bind telegram

# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:ops

Después de la actualización, el enrutamiento para ese enlace queda limitado a telegram:ops. Si también quieres enrutamiento de la cuenta predeterminada, añádelo explícitamente (por ejemplo, --bind telegram:default).

Eliminar enlaces:

openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all

unbind acepta --all o uno o más valores --bind, pero no ambos.

# Superficie de comandos

# agents

Ejecutar openclaw agents sin subcomando equivale a openclaw agents list.

# agents list

Opciones:

• --json
• --bindings: incluye reglas de enrutamiento completas, no solo conteos/resúmenes por agente

# agents add [name]

Opciones:

• --workspace <dir>
• --model <id>
• --agent-dir <dir>
• --bind <channel[:accountId]> (repetible)
• --non-interactive
• --json

Notas:

• Pasar cualquier flag explícito de añadir cambia el comando a la ruta no interactiva.
• El modo no interactivo requiere tanto un nombre de agente como --workspace.
• main está reservado y no puede usarse como id del nuevo agente.
• En modo interactivo, la siembra de autenticación copia solo perfiles estáticos portables (api_key y token estático de forma predeterminada). Los perfiles de token de actualización OAuth siguen disponibles solo mediante herencia de lectura desde el almacén real del agente main. Si el agente predeterminado configurado no es main, inicia sesión por separado para los perfiles OAuth en el nuevo agente.

# agents bindings

Opciones:

• --agent <id>
• --json

# agents bind

Opciones:

• --agent <id> (usa el agente predeterminado actual de forma predeterminada)
• --bind <channel[:accountId]> (repetible)
• --json

# agents unbind

Opciones:

• --agent <id> (usa el agente predeterminado actual de forma predeterminada)
• --bind <channel[:accountId]> (repetible)
• --all
• --json

# agents delete <id>

Opciones:

• --force
• --json

Notas:

• main no se puede eliminar.
• Sin --force, se requiere confirmación interactiva.
• Los directorios del espacio de trabajo, el estado del agente y las transcripciones de sesión se mueven a la papelera, no se eliminan de forma permanente.
• Cuando el Gateway está accesible, la eliminación se envía a través del Gateway para que la limpieza de la configuración y del almacén de sesiones compartan el mismo escritor que el tráfico en tiempo de ejecución. Si no se puede acceder al Gateway, la CLI recurre a la ruta local sin conexión.
• Si el espacio de trabajo de otro agente es la misma ruta, está dentro de este espacio de trabajo o contiene este espacio de trabajo, el espacio de trabajo se conserva y --json informa workspaceRetained, workspaceRetainedReason y workspaceSharedWith.

# Archivos de identidad

Cada espacio de trabajo de agente puede incluir un IDENTITY.md en la raíz del espacio de trabajo:

• Ruta de ejemplo: ~/.openclaw/workspace/IDENTITY.md
• set-identity --from-identity lee desde la raíz del espacio de trabajo (o desde un --identity-file explícito)

Las rutas de avatar se resuelven relativas a la raíz del espacio de trabajo.

# Establecer identidad

set-identity escribe campos en agents.list[].identity:

• name
• theme
• emoji
• avatar (ruta relativa al espacio de trabajo, URL http(s) o URI de datos)

Opciones:

• --agent <id>
• --workspace <dir>
• --identity-file <path>
• --from-identity
• --name <name>
• --theme <theme>
• --emoji <emoji>
• --avatar <value>
• --json

Notas:

• --agent o --workspace se pueden usar para seleccionar el agente de destino.
• Si dependes de --workspace y varios agentes comparten ese espacio de trabajo, el comando falla y te pide pasar --agent.
• Cuando no se proporcionan campos de identidad explícitos, el comando lee los datos de identidad desde IDENTITY.md.

Cargar desde IDENTITY.md:

openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity

Sobrescribir campos explícitamente:

openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png

Ejemplo de configuración:

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "OpenClaw",
          theme: "space lobster",
          emoji: "🦞",
          avatar: "avatars/openclaw.png",
        },
      },
    ],
  },
}

# Relacionado

• Referencia de CLI
• Enrutamiento multiagente
• Espacio de trabajo del agente