Gateway

Esempi di configurazione

Gli esempi seguenti sono allineati con lo schema di configurazione attuale. Per il riferimento completo e le note per campo, consulta Configurazione.

Avvio rapido

Minimo assoluto

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

Salva in ~/.openclaw/openclaw.json e puoi 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", // default; use "automatic" for legacy room replies    },  },}

Esempio esteso (opzioni principali)

JSON5 ti consente di usare commenti e virgole finali. Anche il JSON normale funziona.

json5
{  // Environment + shell  env: {    OPENROUTER_API_KEY: "sk-or-...",    vars: {      GROQ_API_KEY: "gsk-...",    },    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },   // Auth profile metadata (secrets live 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-codex:personal": { provider: "openai-codex", mode: "oauth" },    },    order: {      anthropic: ["anthropic:default", "anthropic:work"],      openai: ["openai:default"],      "openai-codex": ["openai-codex:personal"],    },  },   // Identity is per agent — set it on agents.list[].identity below.   // Logging  logging: {    level: "info",    file: "/tmp/openclaw/openclaw.log",    consoleLevel: "info",    consoleStyle: "pretty",    redactSensitive: "tools",  },   // Message formatting  messages: {    messagePrefix: "[openclaw]",    visibleReplies: "automatic",    responsePrefix: ">",    ackReaction: "👀",    ackReactionScope: "group-mentions",    groupChat: {      historyLimit: 50,      visibleReplies: "message_tool", // normal final replies stay private in groups/channels    },    queue: {      mode: "steer",      debounceMs: 500,      cap: 20,      drop: "summarize",      byChannel: {        whatsapp: "steer",        telegram: "steer",        discord: "steer",        slack: "steer",        signal: "steer",        imessage: "steer",        webchat: "steer",      },    },  },   // Tooling  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-mini-transcribe" },          // Optional CLI fallback (Whisper binary):          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }        ],        timeoutSeconds: 120,      },      video: {        enabled: true,        maxBytes: 52428800,        models: [{ provider: "google", model: "gemini-3-flash-preview" }],      },    },  },   // Session behavior  session: {    scope: "per-sender",    dmScope: "per-channel-peer", // recommended for multi-user inboxes    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 60,    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },    resetTriggers: ["/new", "/reset"],    store: "~/.openclaw/agents/default/sessions/sessions.json",    maintenance: {      mode: "warn",      pruneAfter: "30d",      maxEntries: 500,      resetArchiveRetention: "30d", // duration or false      maxDiskBytes: "500mb", // optional      highWaterBytes: "400mb", // optional (defaults to 80% of maxDiskBytes)    },    typingIntervalSeconds: 5,    sendPolicy: {      default: "allow",      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],    },  },   // Channels  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: { allow: true },            help: { allow: true, requireMention: true },          },        },      },    },     slack: {      enabled: true,      botToken: "xoxb-REPLACE_ME",      appToken: "xapp-REPLACE_ME",      channels: {        "#general": { allow: true, requireMention: true },      },      dm: { enabled: true, allowFrom: ["U123"] },      slashCommand: {        enabled: true,        name: "openclaw",        sessionPrefix: "slack:slash",        ephemeral: true,      },    },  },   // Agent runtime  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"], // inherited by agents that omit 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 (default) | 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", // preferred over legacy 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: "helpful sloth",          emoji: "🦥",        },        // inherits defaults.skills -> github, weather        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },        thinkingDefault: "high", // per-agent thinking override        reasoningDefault: "on", // per-agent reasoning visibility        fastModeDefault: false, // per-agent fast mode      },      {        id: "quick",        skills: [], // no skills for this agent        fastModeDefault: true, // this agent always runs fast        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: ["[email protected]"],        webchat: ["session:demo"],      },    },  },   // Custom model providers  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,          },        ],      },    },  },   // Cron jobs  cron: {    enabled: true,    store: "~/.openclaw/cron/cron.json",    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },   // Webhooks  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: "From: {{messages[0].from}}\nSubject: {{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: "[email protected]",      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 + networking  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.tailnet: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 },    },  },}

Usalo quando una radice skill integrata contiene un symlink verso un repository adiacente, per esempio ~/.agents/skills/manager -> ~/Projects/manager/skills.

json5
{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}
  • extraDirs esegue la scansione del repository adiacente come radice skill esplicita.
  • allowSymlinkTargets consente alle cartelle skill collegate tramite symlink di risolversi in quella radice di destinazione reale attendibile, senza consentire escape di symlink arbitrari.

Pattern comuni

Baseline skill condivisa con un override

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 baseline condivisa.
  • agents.list[].skills sostituisce quella baseline per un agente.
  • Usa 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 dei nodi in una rete attendibile

Mantieni manuale l'abbinamento dei dispositivi, a meno che tu non controlli il percorso di rete. Per un laboratorio dedicato o una sottorete tailnet, puoi abilitare l'approvazione automatica dei dispositivi nodo al primo utilizzo con CIDR o IP esatti:

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

Questa opzione resta disattivata se non viene impostata. Si applica solo all'abbinamento nuovo con role: node e senza ambiti richiesti. Client operatore/browser e aggiornamenti di ruolo, ambito, metadati o chiave pubblica richiedono comunque l'approvazione manuale.

Modalità DM sicura (inbox condivisa / DM multiutente)

Se più di una persona può inviare DM al tuo bot (più voci in allowFrom, approvazioni di abbinamento per più persone o dmPolicy: "open"), abilita la modalità DM sicura in modo che i DM provenienti da mittenti diversi non condividano un unico contesto per impostazione predefinita:

json5
{  // Secure DM mode (recommended for multi-user or sensitive DM agents)  session: { dmScope: "per-channel-peer" },   channels: {    // Example: WhatsApp multi-user inbox    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+15555550123", "+15555550124"],    },     // Example: Discord multi-user inbox    discord: {      enabled: true,      token: "YOUR_DISCORD_BOT_TOKEN",      dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] },    },  },}

Per Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC, l'autorizzazione del mittente è basata sugli ID per impostazione predefinita. Abilita la corrispondenza diretta e mutabile per nome/email/nick con dangerouslyAllowNameMatching: true di ciascun canale solo se accetti esplicitamente quel 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": { allow: true, requireMention: true },        "#general": { allow: 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 imposti dmPolicy: "open", l'elenco allowFrom corrispondente deve includere "*".
  • Gli ID dei provider differiscono (numeri di telefono, ID utente, ID canale). Usa la documentazione del provider per confermare il formato.
  • Sezioni facoltative da aggiungere in seguito: web, browser, ui, discovery, plugins, talk, signal, imessage.
  • Consulta Provider e Risoluzione dei problemi per note di configurazione più approfondite.

Correlati

Was this useful?