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

Configuration

Enrutamiento de canales

Canales y enrutamiento

OpenClaw dirige las respuestas de vuelta al canal del que provino el mensaje. El modelo no elige un canal; el enrutamiento es determinista y está controlado por la configuración del host.

Términos clave

  • Canal: un plugin de canal incluido, como discord, googlechat, imessage, irc, line, signal, slack, telegram o whatsapp, además de los canales de plugins instalados. webchat es el canal interno de la interfaz de WebChat y no es un canal saliente configurable.
  • AccountId: instancia de cuenta por canal (cuando se admite).
  • Cuenta predeterminada opcional del canal: channels.<channel>.defaultAccount elige qué cuenta se utiliza cuando una ruta saliente no especifica accountId.
    • En configuraciones con varias cuentas, establezca un valor predeterminado explícito (defaultAccount o una cuenta denominada default) cuando haya dos o más cuentas configuradas. Sin él, el enrutamiento alternativo puede elegir el primer ID de cuenta normalizado.
  • AgentId: un espacio de trabajo y almacén de sesiones aislados («cerebro»).
  • SessionKey: la clave de agrupación utilizada para almacenar el contexto y controlar la concurrencia.

Prefijos de destinos salientes

Los destinos salientes explícitos pueden incluir un prefijo de proveedor, como telegram:123 o tg:123. El núcleo trata ese prefijo como una indicación para seleccionar el canal únicamente cuando el canal seleccionado es last o no está resuelto de algún otro modo, y solo cuando el plugin cargado anuncia dicho prefijo. Si el autor de la llamada ya seleccionó un canal explícito, el prefijo del proveedor debe coincidir con ese canal; las combinaciones entre canales, como la entrega mediante WhatsApp a telegram:123, fallan antes de la normalización del destino específica del plugin.

Los prefijos de tipo de destino y servicio, como channel:<id>, user:<id>, room:<id>, thread:<id>, imessage:<handle> y sms:<number>, permanecen dentro de la gramática del canal seleccionado. No seleccionan por sí mismos el proveedor.

Formatos de las claves de sesión (ejemplos)

Los mensajes directos se agrupan de forma predeterminada en la sesión principal del agente:

  • agent:<agentId>:<mainKey> (valor predeterminado: agent:main:main)

session.dmScope controla la agrupación de los mensajes directos: main (valor predeterminado) comparte una única sesión principal, mientras que per-peer, per-channel-peer y per-account-channel-peer mantienen los mensajes directos en sesiones separadas. Un enlace de ruta puede anular el ámbito para los interlocutores que coincidan mediante bindings[].session.dmScope.

Aunque el historial de conversaciones de mensajes directos se comparta con la sesión principal, las políticas del entorno aislado y de las herramientas utilizan una clave de entorno de ejecución de chat directo derivada por cuenta para los mensajes directos externos, de modo que los mensajes originados en canales no se traten como ejecuciones locales de la sesión principal.

Los grupos y canales permanecen aislados por canal:

  • Grupos: agent:<agentId>:<channel>:group:<id>
  • Canales/salas: agent:<agentId>:<channel>:channel:<id>

Hilos:

  • Los hilos de Slack/Discord añaden :thread:<threadId> a la clave base.
  • Los temas de foros de Telegram incorporan :topic:<topicId> en la clave del grupo.

Ejemplos:

  • agent:main:telegram:group:-1001234567890:topic:42
  • agent:main:discord:channel:123456:thread:987654

Fijación de la ruta principal de mensajes directos

Cuando session.dmScope es main, los mensajes directos pueden compartir una única sesión principal. Para evitar que mensajes directos ajenos al propietario sobrescriban el valor lastRoute de la sesión, OpenClaw deduce un propietario fijado a partir de allowFrom cuando se cumplen todas estas condiciones:

  • allowFrom contiene exactamente una entrada sin comodín.
  • La entrada puede normalizarse como un ID de remitente concreto para ese canal.
  • El remitente del mensaje directo entrante no coincide con ese propietario fijado.

En ese caso de discrepancia, OpenClaw sigue registrando los metadatos de la sesión entrante, pero omite la actualización de lastRoute en la sesión principal.

Registro protegido de mensajes entrantes

Los plugins de canal pueden marcar un registro de sesión entrante como createIfMissing: false cuando una ruta protegida no debe crear una nueva sesión de OpenClaw. En ese modo, OpenClaw puede actualizar los metadatos y lastRoute de una sesión existente, pero no crea una entrada de sesión solo para la ruta por el mero hecho de que se haya observado un mensaje.

Reglas de enrutamiento (cómo se elige un agente)

El enrutamiento selecciona un agente para cada mensaje entrante:

  1. Coincidencia exacta de interlocutor (bindings con peer.kind + peer.id).
  2. Coincidencia con el interlocutor principal (herencia de hilos).
  3. Coincidencia mediante comodín de interlocutor (peer.id: "*" para un tipo de interlocutor).
  4. Coincidencia de servidor + roles (Discord) mediante guildId + roles.
  5. Coincidencia de servidor (Discord) mediante guildId.
  6. Coincidencia de equipo (Slack) mediante teamId.
  7. Coincidencia de cuenta (accountId en el canal).
  8. Coincidencia de canal (cualquier cuenta de ese canal, accountId: "*").
  9. Agente predeterminado (agents.list[].default; de lo contrario, la primera entrada de la lista, con main como alternativa).

Cuando una vinculación incluye varios campos de coincidencia (peer, guildId, teamId, roles), todos los campos proporcionados deben coincidir para que se aplique esa vinculación.

El agente coincidente determina qué espacio de trabajo y almacén de sesiones se utilizan.

Grupos de difusión (ejecutar varios agentes)

Los grupos de difusión permiten ejecutar varios agentes para el mismo interlocutor cuando OpenClaw respondería normalmente (por ejemplo, en grupos de WhatsApp, después del control de menciones/activación).

Configuración:

json5
{  broadcast: {    strategy: "parallel",    "120363403215116621@g.us": ["alfred", "baerbel"],    "+15555550123": ["support", "logger"],  },}

Consulte: Grupos de difusión.

Descripción general de la configuración

  • agents.list: definiciones de agentes con nombre (espacio de trabajo, modelo, etc.).
  • bindings: asigna canales, cuentas e interlocutores entrantes a agentes.

Ejemplo:

json5
{  agents: {    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],  },  bindings: [    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },  ],}

Almacenamiento de sesiones

Las filas de sesiones en tiempo de ejecución se encuentran en la base de datos SQLite de cada agente, dentro del directorio de estado (de forma predeterminada, ~/.openclaw):

  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

Las instalaciones anteriores pueden tener archivos JSONL heredados de transcripciones y un almacén de filas sessions.json en ~/.openclaw/agents/<agentId>/sessions/. El inicio del Gateway y openclaw doctor --fix importan automáticamente en SQLite las filas y el historial heredados activos. Use openclaw doctor --session-sqlite inspect --session-sqlite-all-agents y la secuencia de validación de Doctor cuando necesite pruebas explícitas de la migración. Aún puede seleccionar una ruta de almacén heredado mediante session.store y las plantillas de {agentId} para flujos de trabajo de migración y mantenimiento sin conexión.

La detección de sesiones del Gateway y ACP también examina los almacenes de agentes respaldados en disco en la raíz predeterminada agents/ y en las raíces de session.store basadas en plantillas. Los almacenes detectados deben permanecer dentro de esa raíz de agente resuelta y usar un archivo heredado normal sessions.json. Se ignoran los enlaces simbólicos y las rutas fuera de la raíz.

Comportamiento de WebChat

WebChat se conecta al agente seleccionado y usa de forma predeterminada la sesión principal del agente. Por ello, WebChat permite ver en un solo lugar el contexto de ese agente en distintos canales.

Contexto de la respuesta

Las respuestas entrantes incluyen:

  • ReplyToId, ReplyToBody y ReplyToSender cuando están disponibles.
  • El contexto citado se añade a Body como un bloque [Replying to ...].

Este comportamiento es uniforme en todos los canales.

Contenido relacionado

Was this useful?
On this page

On this page