Configuración

Cada canal tiene su propia sección de configuración bajo `channels.<provider>`. Consulta la página dedicada del canal para los pasos de configuración:

- [WhatsApp](/docs/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/docs/channels/telegram) — `channels.telegram`
- [Discord](/docs/channels/discord) — `channels.discord`
- [Slack](/docs/channels/slack) — `channels.slack`
- [Signal](/docs/channels/signal) — `channels.signal`
- [iMessage](/docs/channels/imessage) — `channels.imessage`
- [Google Chat](/docs/channels/googlechat) — `channels.googlechat`
- [Mattermost](/docs/channels/mattermost) — `channels.mattermost`
- [MS Teams](/docs/channels/msteams) — `channels.msteams`

Todos los canales comparten el mismo patrón de política de DM:

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // solo para allowlist/open
    },
  },
}
```

Configura el modelo principal y respaldos opcionales:

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
```

- `agents.defaults.models` define el catálogo de modelos y actúa como lista de permitidos para `/model`.
- Las referencias de modelo usan el formato `provider/model` (por ejemplo `anthropic/claude-opus-4-6`).
- `agents.defaults.imageMaxDimensionPx` controla la reducción de escala de imágenes de transcripción/herramienta (por defecto `1200`); valores más bajos generalmente reducen el uso de tokens de visión en ejecuciones con muchas capturas de pantalla.
- Consulta [CLI de modelos](/docs/concepts/models) para cambiar modelos en el chat y [Failover de modelos](/docs/concepts/model-failover) para rotación de autenticación y comportamiento de respaldo.
- Para proveedores personalizados/autoalojados, consulta [Proveedores personalizados](/docs/gateway/configuration-reference#custom-providers-and-base-urls) en la referencia.

El acceso por DM se controla por canal vía `dmPolicy`:

- `"pairing"` (por defecto): los remitentes desconocidos reciben un código de emparejamiento de un solo uso para aprobar
- `"allowlist"`: solo los remitentes en `allowFrom` (o el almacén de permitidos por emparejamiento)
- `"open"`: permitir todos los DMs entrantes (requiere `allowFrom: ["*"]`)
- `"disabled"`: ignorar todos los DMs

Para grupos, usa `groupPolicy` + `groupAllowFrom` o listas de permitidos específicas del canal.

Consulta la [referencia completa](/docs/gateway/configuration-reference#dm-and-group-access) para detalles por canal.

Los mensajes de grupo requieren mención por defecto. Configura los patrones por agente:

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **Menciones por metadatos**: menciones nativas con @ (mención por toque en WhatsApp, @bot en Telegram, etc.)
- **Patrones de texto**: patrones regex en `mentionPatterns`
- Consulta la [referencia completa](/docs/gateway/configuration-reference#group-chat-mention-gating) para sustituciones por canal y modo de autochat.

Las sesiones controlan la continuidad y aislamiento de la conversación:

```json5
{
  session: {
    dmScope: "per-channel-peer",  // recomendado para multiusuario
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
```

- `dmScope`: `main` (compartida) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: valores por defecto globales para enrutamiento de sesión vinculado a hilos (Discord soporta `/focus`, `/unfocus`, `/agents`, `/session idle`, y `/session max-age`).
- Consulta [Gestión de sesiones](/docs/concepts/session) para alcance, enlaces de identidad y política de envío.
- Consulta la [referencia completa](/docs/gateway/configuration-reference#session) para todos los campos.

Ejecuta sesiones de agente en contenedores Docker aislados:

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
```

Construye la imagen primero: `scripts/sandbox-setup.sh`

Consulta [Sandboxing](/docs/gateway/sandboxing) para la guía completa y la [referencia completa](/docs/gateway/configuration-reference#sandbox) para todas las opciones.

El push respaldado por relay se configura en `openclaw.json`.

Configura esto en la configuración del gateway:

```json5
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Opcional. Por defecto: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
```

Equivalente CLI:

```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```

Qué hace esto:

- Permite que el gateway envíe `push.test`, empujones de activación y activaciones de reconexión a través del relay externo.
- Usa un grant de envío con alcance de registro reenviado por la app iOS emparejada. El gateway no necesita un token de relay de despliegue general.
- Vincula cada registro respaldado por relay a la identidad del gateway con el que la app iOS se emparejó, para que otro gateway no pueda reusar el registro almacenado.
- Mantiene los builds locales/manuales de iOS en APNs directo. Los envíos respaldados por relay se aplican solo a builds oficiales distribuidos que se registraron a través del relay.
- Debe coincidir con la URL base del relay integrada en el build oficial/TestFlight de iOS, para que el tráfico de registro y envío llegue al mismo despliegue del relay.

Flujo de extremo a extremo:

1. Instala un build oficial/TestFlight de iOS compilado con la misma URL base del relay.
2. Configura `gateway.push.apns.relay.baseUrl` en el gateway.
3. Empareja la app iOS con el gateway y permite que las sesiones de nodo y operador se conecten.
4. La app iOS obtiene la identidad del gateway, se registra con el relay usando App Attest más el recibo de la app, y luego publica el payload de `push.apns.register` respaldado por relay al gateway emparejado.
5. El gateway almacena el handle del relay y el grant de envío, luego los usa para `push.test`, empujones de activación y activaciones de reconexión.

Notas operativas:

- Si cambias la app iOS a un gateway diferente, reconecta la app para que pueda publicar un nuevo registro de relay vinculado a ese gateway.
- Si envías un nuevo build de iOS que apunta a un despliegue de relay diferente, la app actualiza su registro de relay en caché en lugar de reusar el origen del relay anterior.

Nota de compatibilidad:

- `OPENCLAW_APNS_RELAY_BASE_URL` y `OPENCLAW_APNS_RELAY_TIMEOUT_MS` siguen funcionando como sustituciones temporales de entorno.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` permanece como escape de desarrollo solo para loopback; no persistas URLs de relay HTTP en la configuración.

Consulta [App iOS](/docs/platforms/ios#relay-backed-push-for-official-builds) para el flujo de extremo a extremo y [Flujo de autenticación y confianza](/docs/platforms/ios#authentication-and-trust-flow) para el modelo de seguridad del relay.

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
```

- `every`: cadena de duración (`30m`, `2h`). Configura `0m` para deshabilitar.
- `target`: `last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`: `allow` (por defecto) o `block` para objetivos de heartbeat tipo DM
- Consulta [Heartbeat](/docs/gateway/heartbeat) para la guía completa.

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`: eliminar sesiones aisladas de ejecuciones cron completadas de `sessions.json` (por defecto `24h`; configura `false` para deshabilitar).
- `runLog`: podar `cron/runs/<jobId>.jsonl` por tamaño y líneas retenidas.
- Consulta [Tareas cron](/docs/automation/cron-jobs) para resumen de funcionalidades y ejemplos CLI.

Habilita endpoints de webhook HTTP en el Gateway:

```json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
```

Nota de seguridad:
- Trata todo el contenido de payload de hook/webhook como entrada no confiable.
- Mantén deshabilitadas las flags de bypass de contenido inseguro (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) a menos que estés depurando con alcance acotado.
- Para agentes accionados por hooks, prefiere niveles de modelo moderno fuertes y política de herramientas estricta (por ejemplo solo mensajería más sandboxing cuando sea posible).

Consulta la [referencia completa](/docs/gateway/configuration-reference#hooks) para todas las opciones de mapeo e integración con Gmail.

Ejecuta múltiples agentes aislados con workspaces y sesiones separados:

```json5
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
```

Consulta [Multi-agente](/docs/concepts/multi-agent) y la [referencia completa](/docs/gateway/configuration-reference#multi-agent-routing) para reglas de vinculación y perfiles de acceso por agente.

Usa `$include` para organizar configuraciones grandes:

```json5
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
```

- **Archivo único**: reemplaza el objeto contenedor
- **Array de archivos**: fusión profunda en orden (el último gana)
- **Claves hermanas**: se fusionan después de los includes (sobrescriben valores incluidos)
- **Includes anidados**: soportados hasta 10 niveles de profundidad
- **Rutas relativas**: resueltas relativas al archivo que incluye
- **Manejo de errores**: errores claros para archivos faltantes, errores de parseo e includes circulares

Valida + escribe la configuración completa y reinicia el Gateway en un solo paso.

> **Advertencia:** `config.apply` reemplaza **toda la configuración**. Usa `config.patch` para actualizaciones parciales, o `openclaw config set` para claves individuales.

Parámetros:

- `raw` (string) — payload JSON5 para toda la configuración
- `baseHash` (opcional) — hash de configuración de `config.get` (obligatorio cuando la configuración existe)
- `sessionKey` (opcional) — clave de sesión para el ping de activación post-reinicio
- `note` (opcional) — nota para el centinela de reinicio
- `restartDelayMs` (opcional) — retraso antes del reinicio (por defecto 2000)

Las solicitudes de reinicio se coalescen mientras una ya está pendiente/en progreso, y se aplica un enfriamiento de 30 segundos entre ciclos de reinicio.

```bash
openclaw gateway call config.get --params '{}'  # capturar payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```

Fusiona una actualización parcial en la configuración existente (semántica de JSON merge patch):

- Los objetos se fusionan recursivamente
- `null` elimina una clave
- Los arrays se reemplazan

Parámetros:

- `raw` (string) — JSON5 con solo las claves a cambiar
- `baseHash` (obligatorio) — hash de configuración de `config.get`
- `sessionKey`, `note`, `restartDelayMs` — igual que `config.apply`

El comportamiento de reinicio coincide con `config.apply`: reinicios pendientes coalescidos más un enfriamiento de 30 segundos entre ciclos de reinicio.

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

Si está habilitado y las claves esperadas no están configuradas, OpenClaw ejecuta tu shell de login e importa solo las claves faltantes:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Equivalente como variable de entorno: OPENCLAW_LOAD_SHELL_ENV=1

Referencia variables de entorno en cualquier valor string de configuración con ${VAR_NAME}:

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Reglas:

• Solo se aceptan nombres en mayúsculas: [A-Z_][A-Z0-9_]*
• Las variables faltantes/vacías generan un error al cargar
• Escapa con $${VAR} para salida literal
• Funciona dentro de archivos $include
• Sustitución en línea: "${BASE}/v1" → "https://api.example.com/v1"

Para campos que soportan objetos SecretRef, puedes usar:

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

Los detalles de SecretRef (incluyendo secrets.providers para env/file/exec) están en Gestión de secretos. Las rutas de credenciales soportadas se listan en Superficie de credenciales SecretRef.