Esempi di configurazione

Gli esempi seguenti sono allineati allo schema di configurazione attuale. Per il riferimento completo e le note relative a ogni campo, consultare Configurazione.

Avvio rapido

Minimo indispensabile

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Salvare in ~/.openclaw/openclaw.json; sarà quindi possibile inviare un messaggio diretto al bot da quel numero.

Configurazione iniziale consigliata

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-6" },
    },
    list: [
      {
        id: "main",
        identity: {
          name: "Clawd",
          theme: "helpful assistant",
          emoji: "🦞",
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: {
    visibleReplies: "automatic",
    groupChat: {
      visibleReplies: "message_tool", // attivazione esplicita; l'output visibile richiede message(action=send)
      unmentionedInbound: "room_event",
    },
  },
}

Esempio esteso (opzioni principali)

JSON5 consente di usare commenti e virgole finali. È supportato anche il normale JSON.

{
  // Ambiente + shell
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // Metadati dei profili di autenticazione (i segreti risiedono in auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal", "openai:default"],
    },
  },

  // L'identità è specifica per agente: impostarla in agents.list[].identity qui sotto.

  // Registrazione
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // Formattazione dei messaggi
  messages: {
    messagePrefix: "[openclaw]",
    visibleReplies: "automatic",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // attivazione esplicita per stanze condivise con modelli affidabili nell'uso degli strumenti
      unmentionedInbound: "room_event",
    },
    queue: {
      mode: "followup",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
        discord: "collect",
        slack: "collect",
        signal: "followup",
        imessage: "followup",
        webchat: "followup",
      },
    },
  },

  // Strumenti
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-transcribe" },
          // Ripiego CLI facoltativo (binario Whisper):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // Comportamento della sessione
  session: {
    scope: "per-sender",
    dmScope: "per-channel-peer", // consigliato per caselle di posta multiutente
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/main/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // durata oppure false
      maxDiskBytes: "500mb", // facoltativo
      highWaterBytes: "400mb", // facoltativo (valore predefinito: 80% di maxDiskBytes)
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Canali
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },

    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["123456789012345678"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { enabled: true },
            help: { enabled: true, requireMention: true },
          },
        },
      },
    },

    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { enabled: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
    },
  },

  // Runtime dell'agente
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-6",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "openai/gpt-5.4": { alias: "gpt" },
      },
      skills: ["github", "weather"], // ereditato dagli agenti che omettono list[].skills
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      blockStreamingDefault: "off",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",
      },
      blockStreamingCoalesce: {
        idleMs: 1000,
      },
      humanDelay: {
        mode: "natural",
      },
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      typingIntervalSeconds: 5,
      maxConcurrent: 3,
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-6",
        target: "last",
        directPolicy: "allow", // allow (predefinito) | block
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
      sandbox: {
        mode: "non-main",
        scope: "session", // preferibile al precedente perSession: true
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
        },
        browser: {
          enabled: false,
        },
      },
    },
    list: [
      {
        id: "main",
        default: true,
        identity: {
          name: "Samantha",
          theme: "bradipo disponibile",
          emoji: "🦥",
        },
        // eredita defaults.skills -> github, weather
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
        thinkingDefault: "high", // sostituzione del livello di elaborazione per agente
        reasoningDefault: "on", // visibilità del ragionamento per agente
        fastModeDefault: false, // modalità rapida per agente
      },
      {
        id: "quick",
        skills: [], // nessuna Skills per questo agente
        fastModeDefault: true, // questo agente opera sempre in modalità rapida
        thinkingDefault: "off",
      },
    ],
  },

  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["123456789012345678"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Provider di modelli personalizzati
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // Processi Cron
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 8, // valore predefinito; invio Cron + esecuzione isolata del turno dell'agente Cron
    sessionRetention: "24h",
  },

  // Webhook
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "Da: {{messages[0].from}}\nOggetto: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "gmail.js",
          export: "transformGmail",
        },
      },
    ],
    gmail: {
      account: "openclaw@gmail.com",
      label: "INBOX",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
    },
  },

  // Gateway + rete
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway-host.ts.net:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

Repository di Skills adiacente collegato simbolicamente

Utilizzare questa configurazione quando una radice di Skills integrata contiene un collegamento simbolico a un repository adiacente, ad esempio ~/.agents/skills/manager -> ~/Projects/manager/skills.

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

extraDirs analizza il repository adiacente come radice di Skills esplicita.
allowSymlinkTargets consente alle cartelle di Skills collegate simbolicamente di risolversi in tale radice di destinazione reale attendibile, senza consentire uscite arbitrarie tramite collegamenti simbolici.
Per consentire a Skill Workshop di applicare modifiche in scrittura tramite la stessa destinazione attendibile del collegamento simbolico, impostare skills.workshop.allowSymlinkTargetWrites: true.

Schemi comuni

Base di Skills condivisa con una sostituzione

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      skills: ["github", "weather"],
    },
    list: [
      { id: "main", default: true },
      { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] },
    ],
  },
}

agents.defaults.skills è la base condivisa.
agents.list[].skills sostituisce tale base per un singolo agente.
Usare skills: [] quando un agente non deve vedere alcuna skill.

Configurazione multipiattaforma

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["123456789012345678"] },
    },
  },
}

Approvazione automatica nella rete di nodi attendibile

Mantenere manuale l’associazione dei dispositivi, a meno che non si controlli il percorso di rete. Per una rete di laboratorio dedicata o una sottorete tailnet, è possibile abilitare l’approvazione automatica dei dispositivi Node alla prima connessione mediante CIDR o indirizzi IP esatti:

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
    },
  },
}

Se non configurata, questa opzione rimane disattivata. Si applica solo alle nuove associazioni role: node senza ambiti richiesti. I client operatore/browser e gli aggiornamenti di ruolo, ambito, metadati o chiave pubblica richiedono comunque l’approvazione manuale.

Modalità DM sicura (casella condivisa / DM multiutente)

Se più persone possono inviare DM al bot (più voci in allowFrom, approvazioni di associazione per più persone oppure dmPolicy: "open"), abilitare la modalità DM sicura affinché, per impostazione predefinita, i DM di mittenti diversi non condividano lo stesso contesto:

{
  // Modalità DM sicura (consigliata per agenti DM multiutente o sensibili)
  session: { dmScope: "per-channel-peer" },

  channels: {
    // Esempio: casella WhatsApp multiutente
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // Esempio: casella Discord multiutente
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] },
    },
  },
}

Per Discord/Google Chat/IRC/Mattermost/Microsoft Teams/Slack, per impostazione predefinita l’autorizzazione del mittente si basa innanzitutto sull’ID. Abilitare la corrispondenza diretta con nomi/email/nickname modificabili tramite dangerouslyAllowNameMatching: true di ciascun canale solo se si accetta esplicitamente tale rischio.

Chiave API Anthropic + fallback MiniMax

{
  auth: {
    profiles: {
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
    },
  },
}

Bot di lavoro (accesso limitato)

{
  agents: {
    defaults: {
      workspace: "~/work-openclaw",
      elevatedDefault: "off",
    },
    list: [
      {
        id: "main",
        identity: {
          name: "WorkBot",
          theme: "professional assistant",
        },
      },
    ],
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { enabled: true, requireMention: true },
        "#general": { enabled: true, requireMention: true },
      },
    },
  },
}

Solo modelli locali

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "lmstudio/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Suggerimenti

Se si imposta dmPolicy: "open", l’elenco allowFrom corrispondente deve includere "*".
Gli ID dei provider sono diversi (numeri di telefono, ID utente, ID canale). Consultare la documentazione del provider per confermare il formato.
Sezioni facoltative da aggiungere in seguito: web, browser, ui, discovery, plugins, talk, signal, imessage.
Consultare Provider e Risoluzione dei problemi per note di configurazione più approfondite.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Esempi di configurazione

Avvio rapido

Minimo indispensabile

Configurazione iniziale consigliata

Esempio esteso (opzioni principali)

Repository di Skills adiacente collegato simbolicamente

Schemi comuni

Base di Skills condivisa con una sostituzione

Configurazione multipiattaforma

Approvazione automatica nella rete di nodi attendibile

Modalità DM sicura (casella condivisa / DM multiutente)

Chiave API Anthropic + fallback MiniMax

Bot di lavoro (accesso limitato)

Solo modelli locali

Suggerimenti

Contenuti correlati

​Avvio rapido

​Minimo indispensabile

​Configurazione iniziale consigliata

​Esempio esteso (opzioni principali)

​Repository di Skills adiacente collegato simbolicamente

​Schemi comuni

​Base di Skills condivisa con una sostituzione

​Configurazione multipiattaforma

​Approvazione automatica nella rete di nodi attendibile

​Modalità DM sicura (casella condivisa / DM multiutente)

​Chiave API Anthropic + fallback MiniMax

​Bot di lavoro (accesso limitato)

​Solo modelli locali

​Suggerimenti

​Contenuti correlati

Avvio rapido

Minimo indispensabile

Configurazione iniziale consigliata

Esempio esteso (opzioni principali)

Repository di Skills adiacente collegato simbolicamente

Schemi comuni

Base di Skills condivisa con una sostituzione

Configurazione multipiattaforma

Approvazione automatica nella rete di nodi attendibile

Modalità DM sicura (casella condivisa / DM multiutente)

Chiave API Anthropic + fallback MiniMax

Bot di lavoro (accesso limitato)

Solo modelli locali

Suggerimenti

Contenuti correlati