OpenClawDocs
In questa pagina

In questa pagina

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

Gateway

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

json5
{  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

json5
{  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.

json5
{  // 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.

json5
{  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

json5
{  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

json5
{  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:

json5
{  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:

json5
{  // 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

json5
{  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)

json5
{  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

json5
{  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.

Contenuti correlati

Was this useful?