Configuración — canales

Claves de configuración por canal bajo channels.*. Cubre el acceso a MD y grupos, configuraciones multicuenta, filtrado de menciones y claves por canal para Slack, Discord, Telegram, WhatsApp, Matrix, iMessage y otros complementos de canal incluidos.

Para agentes, herramientas, tiempo de ejecución de la puerta de enlace y otras claves de nivel superior, consulte Referencia de configuración.

Canales

Cada canal se inicia automáticamente cuando existe su sección de configuración (a menos que enabled: false).

Acceso a MD y grupos

Todos los canales admiten políticas de MD y políticas de grupos:

Política de MD	Comportamiento
pairing (predeterminado)	Los remitentes desconocidos obtienen un código de emparejamiento de un solo uso; el propietario debe aprobar
allowlist	Solo remitentes en allowFrom (o almacén de permisos emparejado)
open	Permitir todos los MD entrantes (requiere allowFrom: ["*"])
disabled	Ignorar todos los MD entrantes

Política de grupos	Comportamiento
allowlist (predeterminado)	Solo grupos que coincidan con la lista de permitidos configurada
open	Omitir las listas de permitidos de grupos (aún se aplica el filtrado de menciones)
disabled	Bloquear todos los mensajes de grupos/salas

Note

channels.defaults.groupPolicy establece el valor predeterminado cuando el groupPolicy de un proveedor no está configurado. Los códigos de emparejamiento caducan después de 1 hora. Las solicitudes pendientes de emparejamiento de MD están limitadas a 3 por canal. Si falta un bloque de proveedor por completo (`channels.

ausente), la política de grupo de tiempo de ejecución vuelve aallowlist` (fail-closed) con una advertencia de inicio.

Invalidaciones del modelo de canal

Use channels.modelByChannel para fijar IDs de canal específicos a un modelo. Los valores aceptan provider/model o alias de modelo configurados. La asignación de canal se aplica cuando una sesión aún no tiene una anulación de modelo (por ejemplo, establecida a través de /model).

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-5.5",
      },
      telegram: {
        "-1001234567890": "openai/gpt-5.4-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

Valores predeterminados del canal y latido

Use channels.defaults para una política de grupo compartida y el comportamiento de latidos en todos los proveedores:

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: política de grupo de reserva cuando el groupPolicy a nivel de proveedor no está configurado.
• channels.defaults.contextVisibility: modo de visibilidad de contexto suplementario predeterminado para todos los canales. Valores: all (predeterminado, incluir todo el contexto citado/hilo/historial), allowlist (solo incluir contexto de remitentes en la lista de permitidos), allowlist_quote (igual que la lista de permitidos pero mantener el contexto de cita/respuesta explícito). Invalidación por canal: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: incluir estados de canal saludables en la salida de heartbeat.
• channels.defaults.heartbeat.showAlerts: incluir estados degradados/de error en la salida de heartbeat.
• channels.defaults.heartbeat.useIndicator: renderizar salida de heartbeat compacta estilo indicador.

WhatsApp

WhatsApp se ejecuta a través del canal web de la puerta de enlace (Baileys Web). Se inicia automáticamente cuando existe una sesión vinculada.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

WhatsApp multicuenta

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

• Los comandos salientes por defecto van a la cuenta default si está presente; de lo contrario, al primer id de cuenta configurado (ordenado).
• channels.whatsapp.defaultAccount opcional anula esa selección de cuenta predeterminada de respaldo cuando coincide con un id de cuenta configurado.
• El directorio de autenticación heredado de cuenta única de Baileys es migrado por openclaw doctor a whatsapp/default.
• Invalidaciones por cuenta: `channels.whatsapp.accounts.

.sendReadReceipts, channels.whatsapp.accounts.

.dmPolicy, channels.whatsapp.accounts.

.allowFrom`.

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      apiRoot: "https://api.telegram.org",
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token del bot: channels.telegram.botToken o channels.telegram.tokenFile (solo archivo regular; se rechazan los enlaces simbólicos), con TELEGRAM_BOT_TOKEN como respaldo para la cuenta predeterminada.
• apiRoot es solo la raíz de la API de Bot de Telegram. Use https://api.telegram.org o su propia raíz autohospedada/proxy, no https://api.telegram.org/bot<TOKEN>; openclaw doctor --fix elimina un sufijo /bot<TOKEN> final accidental.
• channels.telegram.defaultAccount opcional anula la selección de cuenta predeterminada cuando coincide con un id de cuenta configurado.
• En configuraciones multicuenta (2 o más ids de cuenta), establezca un predeterminado explícito (channels.telegram.defaultAccount o channels.telegram.accounts.default) para evitar el enrutamiento de respaldo; openclaw doctor advierte cuando esto falta o no es válido.
• configWrites: false bloquea las escrituras de configuración iniciadas por Telegram (migraciones de ID de supergrupo, /config set|unset).
• Las entradas de bindings[] de nivel superior con type: "acp" configuran enlaces ACP persistentes para temas del foro (use chatId:topic:topicId canónico en match.peer.id). La semántica de los campos se comparte en Agentes ACP.
• Las vistas previas de transmisiones de Telegram usan sendMessage + editMessageText (funciona en chats directos y grupales).
• Política de reintentos: consulte Política de reintentos.

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      suppressEmbeds: true,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, con DISCORD_BOT_TOKEN como alternativa para la cuenta predeterminada.
• Las llamadas de salida directas que proporcionan un token de Discord explícito usan ese token para la llamada; la configuración de reintento/política de la cuenta aún proviene de la cuenta seleccionada en la instantánea de tiempo de ejecución activa.
• Opcional channels.discord.defaultAccount anula la selección de cuenta predeterminada cuando coincide con una id de cuenta configurada.
• Use user:<id> (DM) o channel:<id> (canal de gremio) como objetivos de entrega; los IDs numéricos simples se rechazan.
• Los slugs de gremio están en minúsculas con los espacios reemplazados por -; las claves de canal usan el nombre en formato slug (sin #). Se prefieren los IDs de gremio.
• Los mensajes creados por bots se ignoran de forma predeterminada. allowBots: true los habilita; use allowBots: "mentions" para aceptar solo mensajes de bots que mencionan al bot (los propios mensajes aún se filtran).
• Los canales que admiten mensajes entrantes creados por el bot pueden usar una protección contra bucles de bot compartida. Establezca channels.defaults.botLoopProtection para los presupuestos de pares base, luego anule el canal o la cuenta solo cuando una superficie necesite límites diferentes.
• channels.discord.guilds.<id>.ignoreOtherMentions (y las anulaciones de canal) descarta los mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here).
• channels.discord.mentionAliases asigna el texto de @handle saliente establecido a los IDs de usuario de Discord antes de enviar, por lo que los compañeros de equipo conocidos pueden mencionarse de manera determinista incluso cuando el caché de directorio transitorio está vacío. Las anulaciones por cuenta se encuentran en channels.discord.accounts.<accountId>.mentionAliases.
• maxLinesPerMessage (por defecto 17) divide los mensajes altos incluso cuando tienen menos de 2000 caracteres.
• channels.discord.suppressEmbeds por defecto es true, por lo que las URL salientes no se expanden en vistas previas de enlaces de Discord a menos que se deshabiliten. Las cargas útiles explícitas de embeds todavía se envían normalmente; las llamadas a herramientas por mensaje pueden anular esto con suppressEmbeds.
• channels.discord.threadBindings controla el enrutamiento vinculado a hilos de Discord:
  • enabled: Anulación de Discord para las características de sesión vinculadas a hilos (/focus, /unfocus, /agents, /session idle, /session max-age y entrega/enrutamiento vinculado)
  • idleHours: Anulación de Discord para el autoenfoque por inactividad en horas (0 lo deshabilita)
  • maxAgeHours: Anulación de Discord para la antigüedad máxima estricta en horas (0 lo deshabilita)
  • spawnSessions: interruptor para la creación/enlace automático de hilos de sessions_spawn({ thread: true }) y generación de hilos de ACP (predeterminado: true)
  • defaultSpawnContext: contexto nativo del subagente para generaciones vinculadas a hilos ("fork" de manera predeterminada)
• Las entradas de bindings[] de nivel superior con type: "acp" configuran enlaces ACP persistentes para canales e hilos (use el ID del canal/hilo en match.peer.id). La semántica de los campos se comparte en Agentes ACP.
• channels.discord.ui.components.accentColor establece el color de acento para los contenedores de componentes de Discord v2.
• channels.discord.agentComponents.ttlMs controla cuánto tiempo permanecen registradas las devoluciones de llamada de componentes de Discord enviados. El valor predeterminado es 1800000 (30 minutos), el máximo es 86400000 (24 horas) y las anulaciones por cuenta se encuentran en channels.discord.accounts.<accountId>.agentComponents.ttlMs. Los valores más largos mantienen los botones/selectores/formularios antiguos utilizables por más tiempo, por lo que se prefiere el TTL más corto que se ajuste al flujo de trabajo.
• channels.discord.voice habilita las conversaciones del canal de voz de Discord y las anulaciones opcionales de unión automática + LLM + TTS. Las configuraciones de Discord solo de texto dejan la voz desactivada de forma predeterminada; establezca channels.discord.voice.enabled=true para aceptar.
• channels.discord.voice.model anula opcionalmente el modelo LLM utilizado para las respuestas del canal de voz de Discord.
• channels.discord.voice.daveEncryption y channels.discord.voice.decryptionFailureTolerance se pasan a las opciones DAVE de @discordjs/voice (true y 24 de forma predeterminada).
• channels.discord.voice.connectTimeoutMs controla la espera inicial de @discordjs/voice Ready para /vc join y los intentos de unión automática (30000 de forma predeterminada).
• channels.discord.voice.reconnectGraceMs controla cuánto tiempo puede tardar una sesión de voz desconectada en entrar en la señalización de reconexión antes de que OpenClaw la destruya (15000 por defecto).
• La reproducción de voz de Discord no se interrumpe por el evento de inicio de habla de otro usuario. Para evitar bucles de retroalimentación, OpenClaw ignora la nueva captura de voz mientras se reproduce el TTS.
• OpenClaw additionally attempts voice receive recovery by leaving/rejoining a voice session after repeated decrypt failures.
• channels.discord.streaming es la clave canónica del modo de flujo. Discord usa por defecto streaming.mode: "progress" para que el progreso de la herramienta/trabajo aparezca en un mensaje de vista previa editado; establezca streaming.mode: "off" para desactivarlo. Los valores heredados streamMode y booleanos streaming siguen siendo alias de tiempo de ejecución; ejecute openclaw doctor --fix para reescribir la configuración persistente.
• channels.discord.autoPresence asigna la disponibilidad en tiempo de ejecución a la presencia del bot (saludable => en línea, degradado => inactivo, agotado => no molestar) y permite anulaciones opcionales del texto de estado.
• channels.discord.dangerouslyAllowNameMatching reactiva la coincidencia de nombre/etiqueta mutable (modo de compatibilidad de cristal roto).
• channels.discord.execApprovals: entrega de aprobación de ejecución nativa de Discord y autorización del aprobador.
  • enabled: true, false o "auto" (predeterminado). En modo automático, las aprobaciones de ejecución se activan cuando se pueden resolver los aprobadores desde approvers o commands.ownerAllowFrom.
  • approvers: IDs de usuario de Discord permitidos para aprobar solicitudes de ejecución. Recurre a commands.ownerAllowFrom cuando se omite.
  • agentFilter: lista de permitidos de ID de agente opcional. Omita para reenviar aprobaciones para todos los agentes.
  • sessionFilter: patrones de clave de sesión opcionales (subcadena o regex).
  • target: dónde enviar los avisos de aprobación. "dm" (por defecto) envía a los MD de los aprobadores, "channel" envía al canal de origen, "both" envía a ambos. Cuando el objetivo incluye "channel", los botones solo pueden ser utilizados por aprobadores resueltos.
  • cleanupAfterResolve: cuando true, elimina los MD de aprobación después de la aprobación, denegación o tiempo de espera.

Modos de notificación de reacción: off (ninguno), own (mensajes del bot, por defecto), all (todos los mensajes), allowlist (desde guilds.<id>.users en todos los mensajes).

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• Cuenta de servicio JSON: en línea (serviceAccount) o basada en archivo (serviceAccountFile).
• También se admite SecretRef de cuenta de servicio (serviceAccountRef).
• Alternativas de entorno: GOOGLE_CHAT_SERVICE_ACCOUNT o GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Use spaces/<spaceId> o users/<userId> para los destinos de entrega.
• channels.googlechat.dangerouslyAllowNameMatching vuelve a habilitar la coincidencia de principales de correo electrónico mutable (modo de compatibilidad de cristal roto).

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      unfurlLinks: false,
      unfurlMedia: false,
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Modo Socket requiere tanto botToken como appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN para la alternativa de entorno de cuenta predeterminada).
• Modo HTTP requiere botToken además de signingSecret (en la raíz o por cuenta).
• socketMode pasa el ajuste de transporte del modo Socket del SDK de Slack a la API pública del receptor Bolt. Úselo solo al investigar el tiempo de espera de ping/pong o el comportamiento de websocket obsoleto. clientPingTimeout por defecto es 15000; serverPingTimeout y pingPongLoggingEnabled se pasan solo cuando están configurados.
• botToken, appToken, signingSecret y userToken aceptan cadenas de texto plano u objetos SecretRef.
• Las instantáneas de la cuenta de Slack exponen campos de origen/estado por credencial, como botTokenSource, botTokenStatus, appTokenStatus y, en modo HTTP, signingSecretStatus. configured_unavailable significa que la cuenta está configurada a través de SecretRef, pero la ruta del comando/ejecución actual no pudo resolver el valor del secreto.
• configWrites: false bloquea las escrituras de configuración iniciadas por Slack.
• El channels.slack.defaultAccount opcional anula la selección de cuenta predeterminada cuando coincide con un id de cuenta configurado.
• channels.slack.streaming.mode es la clave canónica del modo de transmisión de Slack. channels.slack.streaming.nativeTransport controla el transporte de transmisión nativo de Slack. Los valores heredados streamMode, el booleano streaming y nativeStreaming siguen siendo alias de tiempo de ejecución; ejecute openclaw doctor --fix para reescribir la configuración persistente.
• unfurlLinks y unfurlMedia pasan los booleanos de desenlace de enlace y medios de Slack chat.postMessage para las respuestas del bot. unfurlLinks tiene como valor predeterminado false para que los enlaces salientes del bot no se expandan en línea a menos que se habiliten; unfurlMedia se omite a menos que se configure. Establezca cualquiera de los valores en channels.slack.accounts.<accountId> para anular el valor de nivel superior para una cuenta.
• Use user:<id> (MD) o channel:<id> como objetivos de entrega.

Modos de notificación de reacción: off, own (predeterminado), all, allowlist (de reactionAllowlist).

Aislamiento de sesión de hilo: thread.historyScope es por hilo (predeterminado) o compartido en todo el canal. thread.inheritParent copia la transcripción del canal principal a nuevos hilos.

• La transmisión nativa de Slack junto con el estado de hilo “está escribiendo…” al estilo del asistente de Slack requieren un objetivo de hilo de respuesta. Los MD de nivel superior permanecen fuera del hilo de forma predeterminada, por lo que aún pueden transmitirse a través de las vistas previas de borrador de publicación y edición de Slack en lugar de mostrar la vista previa de transmisión/estado nativa al estilo de hilo.
• typingReaction añade una reacción temporal al mensaje entrante de Slack mientras se ejecuta una respuesta y luego la elimina al completarse. Utilice un código corto de emoji de Slack como "hourglass_flowing_sand".
• channels.slack.execApprovals: entrega de cliente de aprobación nativa de Slack y autorización de aprobador ejecutivo. Mismo esquema que Discord: enabled (true/false/"auto"), approvers (IDs de usuario de Slack), agentFilter, sessionFilter y target ("dm", "channel" o "both"). Las aprobaciones de complementos pueden usar esta ruta de cliente nativo para solicitudes de origen Slack cuando se resuelven los aprobadores del complemento de Slack; la entrega de aprobaciones de complementos nativas de Slack también se puede habilitar a través de approvals.plugin para sesiones de origen Slack o destinos de Slack. Las aprobaciones de complementos usan aprobadores de complementos de Slack de allowFrom y el enrutamiento predeterminado, no aprobadores ejecutivos.

Grupo de acción	Predeterminado	Notas
reacciones	habilitado	Reaccionar + listar reacciones
mensajes	habilitado	Leer/enviar/editar/eliminar
fijaciones	habilitado	Fijar/Desfijar/Listar
memberInfo	habilitado	Información de miembro
emojiList	habilitado	Lista de emojis personalizados

Mattermost

Mattermost se distribuye como un complemento incluido en las versiones actuales de OpenClaw. Las versiones anteriores o las compilaciones personalizadas pueden instalar un paquete npm actual con openclaw plugins install @openclaw/mattermost. Consulte npmjs.com/package/@openclaw/mattermost para las etiquetas de distribución actuales antes de fijar una versión.

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

Modos de chat: oncall (responder al @-mención, predeterminado), onmessage (todos los mensajes), onchar (mensajes que comienzan con el prefijo de activación).

Cuando los comandos nativos de Mattermost están habilitados:

• commands.callbackPath debe ser una ruta (por ejemplo /api/channels/mattermost/command), no una URL completa.
• commands.callbackUrl debe resolverse al punto de conexión de la puerta de enlace de OpenClaw y ser accesible desde el servidor Mattermost.
• Las devoluciones de llamada de slash nativas se autentican con los tokens por comando devueltos por Mattermost durante el registro del comando slash. Si el registro falla o no hay comandos activados, OpenClaw rechaza las devoluciones de llamada con Unauthorized: invalid command token.
• Para hosts de devolución de llamada privados/tailnet/internos, Mattermost puede requerir que ServiceSettings.AllowedUntrustedInternalConnections incluya el host/dominio de la devolución de llamada. Use valores de host/dominio, no URL completas.
• channels.mattermost.configWrites: permitir o denegar escrituras de configuración iniciadas por Mattermost.
• channels.mattermost.requireMention: requerir @mention antes de responder en los canales.
• channels.mattermost.groups.<channelId>.requireMention: anulación de filtrado de menciones por canal ("*" para el valor predeterminado).
• Opcional channels.mattermost.defaultAccount anula la selección de cuenta predeterminada cuando coincide con una id de cuenta configurada.

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

Modos de notificación de reacción: off, own (predeterminado), all, allowlist (de reactionAllowlist).

• channels.signal.account: fijar el inicio del canal a una identidad de cuenta de Signal específica.
• channels.signal.configWrites: permitir o denegar escrituras de configuración iniciadas por Signal.
• Opcional channels.signal.defaultAccount anula la selección de cuenta predeterminada cuando coincide con una id de cuenta configurada.

iMessage

OpenClaw genera imsg rpc (JSON-RPC sobre stdio). No se requiere demonio ni puerto. Esta es la ruta preferida para nuevas configuraciones de iMessage de OpenClaw cuando el host puede otorgar permisos de base de datos de Messages y Automatización.

Se eliminó la compatibilidad con BlueBubbles. channels.bluebubbles no es una superficie de configuración de tiempo de ejecución compatible en OpenClaw actual. Migre las configuraciones antiguas a channels.imessage; use Eliminación de BlueBubbles y la ruta iMessage imsg para la versión breve y Viniendo de BlueBubbles para la tabla de traducción completa.

Si la Puerta de enlace no se está ejecutando en la Mac de Messages con la sesión iniciada, mantenga channels.imessage.enabled=true y configure channels.imessage.cliPath en un contenedor SSH que ejecute imsg "$@" en esa Mac. La ruta local imsg predeterminada es solo para macOS.

Antes de confiar en un contenedor SSH para envíos de producción, verifique un imsg send saliente a través de ese contenedor exacto. Algunos estados de macOS TCC asignan la automatización de mensajes a /usr/libexec/sshd-keygen-wrapper, lo que puede hacer que las lecturas y sondas funcionen mientras que los envíos fallan con AppleEvents -1743; consulte Los envíos del contenedor SSH fallan con AppleEvents -1743.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
      },
      catchup: {
        enabled: false,
      },
    },
  },
}

• Opcional channels.imessage.defaultAccount anula la selección de cuenta predeterminada cuando coincide con un id de cuenta configurado.

• Requiere acceso completo al disco (Full Disk Access) para la base de datos de Messages.

• Prefiera objetivos chat_id:<id>. Use imsg chats --limit 20 para listar chats.

• cliPath puede apuntar a un contenedor de SSH; establezca remoteHost (host o user@host) para la obtención de adjuntos por SCP.

• attachmentRoots y remoteAttachmentRoots restringen las rutas de archivos adjuntos entrantes (predeterminado: /Users/*/Library/Messages/Attachments).

• SCP usa verificación estricta de clave de host, así que asegúrese de que la clave de host del relay ya exista en ~/.ssh/known_hosts.

• channels.imessage.configWrites: permitir o denegar escrituras de configuración iniciadas por iMessage.

• channels.imessage.actions.*: habilitar acciones de API privada que también están controladas por imsg status / openclaw channels status --probe.

• channels.imessage.includeAttachments está desactivado de forma predeterminada; establézcalo en true antes de esperar medios entrantes en turnos del agente.

• channels.imessage.catchup.enabled: optar por reproducir mensajes entrantes que llegaron mientras el Gateway estaba apagado.

• channels.imessage.groups: registro de grupos y configuraciones por grupo. Con groupPolicy: "allowlist", configure claves chat_id explícitas o una entrada comodín "*" para que los mensajes de grupo puedan pasar el filtro del registro.

• Las entradas bindings[] de nivel superior con type: "acp" pueden vincular conversaciones de iMessage a sesiones ACP persistentes. Use un identificador normalizado o un objetivo de chat explícito (chat_id:*, chat_guid:*, chat_identifier:*) en match.peer.id. Semántica de campo compartida: ACP Agents.

Ejemplo de contenedor SSH de iMessage

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Matrix

Matrix está respaldado por un complemento y se configura bajo channels.matrix.

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• La autenticación con token usa accessToken; la autenticación con contraseña usa userId + password.
• channels.matrix.proxy enruta el tráfico HTTP de Matrix a través de un proxy HTTP(S) explícito. Las cuentas con nombre pueden anularlo con channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork permite homeservers privados/internos. proxy y esta opt-in de red son controles independientes.
• channels.matrix.defaultAccount selecciona la cuenta preferida en configuraciones de múltiples cuentas.
• channels.matrix.autoJoin tiene como valor predeterminado off, por lo que las salas invitadas y las invitaciones nuevas de estilo DM se ignoran hasta que establezcas autoJoin: "allowlist" con autoJoinAllowlist o autoJoin: "always".
• channels.matrix.execApprovals: entrega de aprobación de ejecución nativa de Matrix y autorización de aprobadores.
  • enabled: true, false o "auto" (predeterminado). En modo automático, las aprobaciones de ejecución se activan cuando se pueden resolver los aprobadores desde approvers o commands.ownerAllowFrom.
  • approvers: ID de usuario de Matrix (p. ej. @owner:example.org) autorizados para aprobar solicitudes de ejecución.
  • agentFilter: lista de permitidos (allowlist) de ID de agente opcional. Omite para reenviar aprobaciones para todos los agentes.
  • sessionFilter: patrones de clave de sesión opcionales (subcadena o regex).
  • target: dónde enviar los avisos de aprobación. "dm" (predeterminado), "channel" (sala de origen) o "both".
  • Anulaciones por cuenta: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope controla cómo se agrupan los MD de Matrix en sesiones: per-user (predeterminado) comparte por peer enrutado, mientras que per-room aísla cada sala de MD.
• Las sondas de estado de Matrix y las búsquedas de directorio en vivo utilizan la misma política de proxy que el tráfico de tiempo de ejecución.
• La configuración completa de Matrix, las reglas de orientación y los ejemplos de configuración están documentados en Matrix.

Microsoft Teams

Microsoft Teams está respaldado por un complemento y se configura bajo channels.msteams.

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• Rutas de clave principal cubiertas aquí: channels.msteams, channels.msteams.configWrites.
• La configuración completa de Teams (credenciales, webhook, políticas de DM/grupo, anulaciones por equipo/canal) está documentada en Microsoft Teams.

IRC

IRC está respaldado por un complemento y se configura bajo channels.irc.

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "[email protected]",
      },
    },
  },
}

• Rutas de clave principal cubiertas aquí: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permisos/filtrado de menciones) está documentada en IRC.

Multicuenta (todos los canales)

Ejecute múltiples cuentas por canal (cada una con su propio accountId):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default se usa cuando se omite accountId (CLI + enrutamiento).
• Los tokens de entorno solo se aplican a la cuenta predeterminada.
• La configuración base del canal se aplica a todas las cuentas a menos que se anule por cuenta.
• Use bindings[].match.accountId para enrutar cada cuenta a un agente diferente.
• Si agrega una cuenta no predeterminada a través de openclaw channels add (o incorporación del canal) mientras aún está en una configuración de canal de nivel superior de cuenta única, OpenClaw promueve primero los valores de nivel superior de cuenta única con ámbito de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueven a channels.<channel>.accounts.default; Matrix puede preservar en su lugar un objetivo con nombre/predeterminado existente que coincida.
• Los enlaces existentes solo de canal (sin accountId) siguen coincidiendo con la cuenta predeterminada; los enlaces con ámbito de cuenta permanecen opcionales.
• openclaw doctor --fix también repara formas mixtas moviendo los valores de nivel superior de cuenta única con ámbito de cuenta a la cuenta promovida elegida para ese canal. La mayoría de los canales usan accounts.default; Matrix puede preservar en su lugar un objetivo con nombre/predeterminado existente que coincida.

Otros canales de complementos

Muchos canales de complementos se configuran como channels.<id> y se documentan en sus páginas de canal dedicadas (por ejemplo, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). Vea el índice completo de canales: Channels.

Filtrado de menciones en chats grupales

Los mensajes grupales tienen como valor predeterminado requerir mención (mención de metadatos o patrones de regex seguros). Se aplica a grupos de WhatsApp, Telegram, Discord, Google Chat e iMessage.

Las respuestas visibles se controlan por separado. Las solicitudes directas normales de grupo, canal y WebChat interno tienen como valor predeterminado la entrega final automática: las publicaciones de texto final del asistente se realizan a través de la ruta de respuesta visible heredada. Opte por messages.visibleReplies: "message_tool" o messages.groupChat.visibleReplies: "message_tool" cuando la salida visible solo debe publicarse después de que el agente llame a message(action=send). Si el modelo devuelve texto final sin llamar a la herramienta de mensaje en un modo de solo herramienta optado, ese texto final permanece privado y el registro detallado (verbose) de la gateway registra los metadatos de la carga útil suprimida.

Las respuestas visibles de solo herramienta requieren un modelo/tiempo de ejecución que llame a las herramientas de manera confiable y se recomiendan para salas ambientales compartidas en modelos de última generación como GPT 5.5. Algunos modelos más débiles pueden responder con texto final, pero no logran entender que la salida visible para la fuente debe enviarse con message(action=send). Para esos modelos, use "automatic" para que el turno final del asistente sea la ruta de respuesta visible. Si el registro de la sesión muestra texto del asistente con didSendViaMessagingTool: false, el modelo produjo texto final privado en lugar de llamar a la herramienta de mensaje. Cambie a un modelo más sólido de llamada a herramientas para ese canal, inspeccione el registro detallado (verbose) de la gateway para ver el resumen de la carga útil suprimida, o configure messages.groupChat.visibleReplies: "automatic" para usar respuestas finales visibles para cada solicitud de grupo/canal.

Si la herramienta de mensaje no está disponible bajo la política de herramienta activa, OpenClaw recurre a respuestas visibles automáticas en lugar de suprimir silenciosamente la respuesta. openclaw doctor advierte sobre esta discrepancia.

Esta regla se aplica al texto final normal del agente. Los enlaces de conversación propiedad del complemento utilizan la respuesta devuelta por el complemento propietario como la respuesta visible para los turnos de hilo enlazados reclamados; el complemento no necesita llamar a message(action=send) para esas respuestas de enlace.

Solución de problemas: la mención @ de grupo activa el indicador de escritura y luego silencio (sin error)

Síntoma: una mención @ de grupo/canal muestra el indicador de escritura y el registro de la puerta de enlace informa dispatch complete (queuedFinal=false, replies=0), pero ningún mensaje llega a la sala. Los mensajes directos al mismo agente responden con normalidad.

Causa: el modo de respuesta visible del grupo/canal se resuelve como "message_tool", por lo que OpenClaw ejecuta el turno pero suprime el texto final del asistente a menos que el agente llame a message(action=send). No hay un contrato NO_REPLY en este modo; ninguna llamada a la herramienta de mensaje significa ninguna respuesta de origen. No hay ningún error porque la supresión es el comportamiento configurado. Los turnos normales de grupo y canal tienen como valor predeterminado "automatic", por lo que este síntoma solo aparece cuando messages.groupChat.visibleReplies (o el global messages.visibleReplies) se establece explícitamente en "message_tool". El arnés defaultVisibleReplies no se aplica aquí: el solucionador de grupo/canal lo ignora; solo afecta los chats directos/de origen (el arnés Codex suprime los finales de chat directo de esa manera).

Solución: elija un modelo de llamada a herramientas más sólido, elimine la anulación explícita "message_tool" para volver al valor predeterminado "automatic", o establezca messages.groupChat.visibleReplies: "automatic" para forzar respuestas visibles para cada solicitud de grupo/canal. La puerta de enlace recarga en caliente la configuración messages después de guardar el archivo; solo reinicie la puerta de enlace cuando la observación de archivos o la recarga de la configuración estén deshabilitadas en el despliegue.

Tipos de mención:

• Menciones de metadatos: Menciones @ de la plataforma nativa. Se ignoran en el modo de chat propio de WhatsApp.
• Patrones de texto: Patrones de regex seguros en agents.list[].groupChat.mentionPatterns. Se ignoran los patrones no válidos y la repetición anidada insegura.
• El control de menciones solo se aplica cuando es posible la detección (menciones nativas o al menos un patrón).

{
  messages: {
    visibleReplies: "automatic", // force old automatic final replies for direct/source chats
    groupChat: {
      historyLimit: 50,
      unmentionedInbound: "room_event", // always-on unmentioned room chatter becomes quiet context
      visibleReplies: "message_tool", // opt-in; require message(action=send) for visible room replies
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit establece el valor predeterminado global. Los canales pueden anularlo con channels.<channel>.historyLimit (o por cuenta). Establezca 0 para desactivar.

messages.groupChat.unmentionedInbound: "room_event" envía mensajes de grupo/canal siempre activos sin mención como contexto de sala silencioso en los canales compatibles. Los mensajes mencionados, comandos y mensajes directos siguen siendo solicitudes de usuario. Consulte Ambient room events para ver ejemplos completos de Discord, Slack y Telegram.

messages.visibleReplies es el valor predeterminado global de eventos de origen; messages.groupChat.visibleReplies lo anula para eventos de origen de grupo/canal. Cuando messages.visibleReplies no está establecido, los chats directos/de origen utilizan el tiempo de ejecución seleccionado o el valor predeterminado del arnés, pero los turnos directos internos de WebChat utilizan la entrega final automática para la paridad de mensajes de Pi/Codex. Establezca messages.visibleReplies: "message_tool" para requerir intencionalmente message(action=send) para una salida visible. Las listas de permitidos de canales y el filtrado de menciones todavía deciden si se procesa un evento.

Límites del historial de MD

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

Resolución: anulación por MD → valor predeterminado del proveedor → sin límite (se conservan todos).

Compatible con: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Modo de autocomunicación

Incluya su propio número en allowFrom para habilitar el modo de autocomunicación (ignora las menciones nativas de @, solo responde a patrones de texto):

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

Comandos (manejo de comandos de chat)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

Detalles del comando

• Este bloque configura las superficies de comandos. Para el catálogo de comandos integrados + incluidos actual, consulte Comandos de barra.
• Esta página es una referencia de claves de configuración, no el catálogo completo de comandos. Los comandos propiedad del canal/complemento, como QQ Bot /bot-ping /bot-help /bot-logs, LINE /card, device-pair /pair, memory /dreaming, phone-control /phone y Talk /voice están documentados en sus páginas de canal/complemento además de en Comandos de barra.
• Los comandos de texto deben ser mensajes independientes con / al inicio.
• native: "auto" activa los comandos nativos para Discord/Telegram, deja Slack desactivado.
• nativeSkills: "auto" activa los comandos de habilidades nativas para Discord/Telegram, deja Slack desactivado.
• Anular por canal: channels.discord.commands.native (bool o "auto"). Para Discord, false omite el registro y la limpieza de comandos nativos durante el inicio.
• Anule el registro de habilidades nativas por canal con `channels.

.commands.nativeSkills`.

• channels.telegram.customCommands añade entradas de menú adicionales al bot de Telegram.
• bash: true habilita `!

para el shell del host. Requieretools.elevated.enabledy remitente entools.elevated.allowFrom.

`.

• config: true habilita /config (lee/escribe openclaw.json). Para clientes de gateway chat.send, las escrituras persistentes /config set|unset también requieren operator.admin; solo lectura /config show permanece disponible para clientes operadores normales con ámbito de escritura.
• mcp: true habilita /mcp para la configuración del servidor MCP administrada por OpenClaw bajo mcp.servers.
• plugins: true habilita /plugins para el descubrimiento, instalación y controles de habilitación/deshabilitación de complementos.
• `channels.

.configWrites` limita las mutaciones de configuración por canal (predeterminado: true).

• Para canales multicuenta, `channels.

.accounts.

.configWritestambién limita las escrituras dirigidas a esa cuenta (por ejemplo/allowlist —config —account

o/config set channels.

.accounts.

…`).

• restart: false deshabilita /restart y las acciones de herramientas de reinicio del gateway. Predeterminado: true.
• ownerAllowFrom es la lista de permitidos explícita del propietario para comandos solo para propietarios y acciones de canal restringidas al propietario. Está separada de allowFrom.
• ownerDisplay: "hash" aplica un hash a los identificadores de propietario en el mensaje del sistema. Configure ownerDisplaySecret para controlar el hash.
• allowFrom es por proveedor. Cuando se establece, es la única fuente de autorización (se ignoran las listas de permitidas/emparejamiento de canales y useAccessGroups).
• useAccessGroups: false permite que los comandos omitan las políticas de grupos de acceso cuando allowFrom no está establecido.
• Mapa de documentación de comandos:
  • catálogo integrado + incluido: Comandos de barra
  • superficies de comandos específicas del canal: Canales
  • comandos de QQ Bot: QQ Bot
  • comandos de emparejamiento: Emparejamiento
  • comando de tarjeta LINE: LINE
  • ensoñación de memoria: Ensoñación

---

Relacionado

• Referencia de configuración — claves de nivel superior
• Configuración — agentes
• Descripción general de canales