Vai al contenuto principale
OpenClaw legge una configurazione opzionale da ~/.openclaw/openclaw.json. Il percorso della configurazione attiva deve essere un file regolare. I layout openclaw.json con symlink non sono supportati per le scritture gestite da OpenClaw; una scrittura atomica può sostituire il percorso invece di preservare il symlink. Se mantieni la configurazione fuori dalla directory di stato predefinita, punta OPENCLAW_CONFIG_PATH direttamente al file reale. Se il file manca, OpenClaw usa impostazioni predefinite sicure. Motivi comuni per aggiungere una configurazione:
  • Collegare canali e controllare chi può inviare messaggi al bot
  • Impostare modelli, strumenti, sandboxing o automazione (cron, hook)
  • Regolare sessioni, media, rete o UI
Vedi il riferimento completo per ogni campo disponibile. Agenti e automazione devono usare config.schema.lookup per la documentazione esatta a livello di campo prima di modificare la configurazione. Usa questa pagina per indicazioni orientate alle attività e Riferimento alla configurazione per la mappa più ampia dei campi e delle impostazioni predefinite.
Non hai mai configurato OpenClaw? Inizia con openclaw onboard per la configurazione interattiva, oppure consulta la guida Esempi di configurazione per configurazioni complete da copiare e incollare.

​
Configurazione minima

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

​
Modificare la configurazione

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

​
Validazione rigorosa

OpenClaw accetta solo configurazioni che corrispondono completamente allo schema. Chiavi sconosciute, tipi malformati o valori non validi fanno sì che il Gateway rifiuti di avviarsi. L’unica eccezione a livello radice è $schema (stringa), così gli editor possono allegare metadati JSON Schema.
openclaw config schema stampa il JSON Schema canonico usato dalla Control UI e dalla validazione. config.schema.lookup recupera un singolo nodo limitato a un percorso più i riepiloghi dei figli per strumenti di approfondimento. I metadati di documentazione dei campi title/description vengono propagati attraverso oggetti annidati, wildcard (*), elementi di array ([]) e rami anyOf/ oneOf/allOf. Gli schemi runtime di Plugin e canali vengono uniti quando il registro dei manifest è caricato. Quando la validazione fallisce:
  • Il Gateway non si avvia
  • Funzionano solo i comandi diagnostici (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Esegui openclaw doctor per vedere i problemi esatti
  • Esegui openclaw doctor --fix (o --yes) per applicare le riparazioni
Il Gateway conserva una copia attendibile dell’ultima configurazione valida dopo ogni avvio riuscito, ma l’avvio e l’hot reload non la ripristinano automaticamente. Se openclaw.json fallisce la validazione (inclusa la validazione locale del Plugin), l’avvio del Gateway fallisce oppure il ricaricamento viene saltato e il runtime corrente mantiene l’ultima configurazione accettata. Esegui openclaw doctor --fix (o --yes) per riparare configurazioni prefissate/sovrascritte oppure ripristinare la copia dell’ultima configurazione valida. La promozione all’ultima configurazione valida viene saltata quando un candidato contiene segnaposto di segreti redatti come ***.

​
Attività comuni

Ogni canale ha la propria sezione di configurazione sotto channels.<provider>. Vedi la pagina dedicata del canale per i passaggi di configurazione:Tutti i canali condividono lo stesso pattern di policy DM:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
Imposta il modello principale e i fallback opzionali:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models definisce il catalogo dei modelli e funge da allowlist per /model; le voci provider/* filtrano /model, /models e i selettori di modelli sui provider selezionati, continuando a usare la scoperta dinamica dei modelli.
  • Usa openclaw config set agents.defaults.models '<json>' --strict-json --merge per aggiungere voci all’allowlist senza rimuovere i modelli esistenti. Le sostituzioni semplici che rimuoverebbero voci vengono rifiutate a meno che tu non passi --replace.
  • I riferimenti ai modelli usano il formato provider/model (es. anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx controlla il ridimensionamento di immagini di transcript/strumenti (predefinito 1200); valori più bassi di solito riducono l’uso di token visivi nelle esecuzioni ricche di screenshot.
  • Vedi CLI dei modelli per cambiare modello in chat e Failover dei modelli per la rotazione dell’autenticazione e il comportamento di fallback.
  • Per provider personalizzati/self-hosted, vedi Provider personalizzati nel riferimento.
L’accesso DM è controllato per canale tramite dmPolicy:
  • "pairing" (predefinito): i mittenti sconosciuti ricevono un codice di pairing monouso da approvare
  • "allowlist": solo mittenti in allowFrom (o nell’archivio allow abbinato)
  • "open": consenti tutti i DM in ingresso (richiede allowFrom: ["*"])
  • "disabled": ignora tutti i DM
Per i gruppi, usa groupPolicy + groupAllowFrom oppure allowlist specifiche del canale.Vedi il riferimento completo per i dettagli per canale.
I messaggi di gruppo richiedono per impostazione predefinita una menzione obbligatoria. Configura i pattern di trigger per agente. Le risposte normali di gruppo/canale vengono pubblicate automaticamente; abilita esplicitamente il percorso dello strumento messaggi per le stanze condivise in cui l’agente deve decidere quando parlare:
{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)
      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Menzioni da metadati: @-menzioni native (tap-to-mention di WhatsApp, @bot di Telegram, ecc.)
  • Pattern di testo: pattern regex sicuri in mentionPatterns
  • Risposte visibili: messages.visibleReplies può richiedere globalmente invii tramite strumento messaggi; messages.groupChat.visibleReplies lo sovrascrive per gruppi/canali.
  • Vedi il riferimento completo per le modalità di risposta visibile, gli override per canale e la modalità self-chat.
Usa agents.defaults.skills per una baseline condivisa, poi sovrascrivi agenti specifici con agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}
Controlla con quale aggressività il gateway riavvia i canali che sembrano inattivi:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • Imposta gateway.channelHealthCheckMinutes: 0 per disabilitare globalmente i riavvii del monitoraggio della salute.
  • channelStaleEventThresholdMinutes deve essere maggiore o uguale all’intervallo di controllo.
  • Usa channels.<provider>.healthMonitor.enabled o channels.<provider>.accounts.<id>.healthMonitor.enabled per disabilitare i riavvii automatici per un canale o un account senza disabilitare il monitoraggio globale.
  • Vedi Controlli di salute per il debug operativo e il riferimento completo per tutti i campi.
Dai ai client locali più tempo per completare l’handshake WebSocket pre-autenticazione su host carichi o a bassa potenza:
{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
  • Il valore predefinito è 15000 millisecondi.
  • OPENCLAW_HANDSHAKE_TIMEOUT_MS continua ad avere precedenza per override una tantum del servizio o della shell.
  • Preferisci prima correggere stalli di avvio/event loop; questa manopola è per host sani ma lenti durante il warmup.
Le sessioni controllano la continuità e l’isolamento della conversazione:
{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (condiviso) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: impostazioni predefinite globali per l’instradamento delle sessioni vincolate ai thread (Discord supporta /focus, /unfocus, /agents, /session idle e /session max-age).
  • Consulta Gestione delle sessioni per ambito, collegamenti di identità e criteri di invio.
  • Consulta il riferimento completo per tutti i campi.
Esegui le sessioni degli agenti in runtime sandbox isolati:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Crea prima l’immagine: da un checkout del sorgente esegui scripts/sandbox-setup.sh, oppure da un’installazione npm consulta il comando inline docker build in Sandboxing § Immagini e configurazione.Consulta Sandboxing per la guida completa e il riferimento completo per tutte le opzioni.
Le notifiche push basate su relay per le build pubbliche dell’App Store usano il relay OpenClaw ospitato: https://ios-push-relay.openclaw.ai.Le distribuzioni relay personalizzate richiedono un percorso di build/distribuzione iOS deliberatamente separato il cui URL relay corrisponda all’URL relay del gateway. Se usi una build relay personalizzata, imposta questo nella configurazione del gateway:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
Equivalente CLI:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
Cosa fa:
  • Consente al gateway di inviare push.test, solleciti di risveglio e risvegli di riconnessione tramite il relay esterno.
  • Usa una concessione di invio con ambito di registrazione inoltrata dall’app iOS abbinata. Il gateway non necessita di un token relay valido per l’intera distribuzione.
  • Vincola ogni registrazione basata su relay all’identità del gateway con cui l’app iOS è stata abbinata, così un altro gateway non può riutilizzare la registrazione archiviata.
  • Mantiene le build iOS locali/manuali su APNs diretto. Gli invii basati su relay si applicano solo alle build distribuite ufficiali registrate tramite il relay.
  • Deve corrispondere all’URL di base del relay integrato nella build iOS, così il traffico di registrazione e invio raggiunge la stessa distribuzione relay.
Flusso end-to-end:
  1. Installa l’app iOS ufficiale.
  2. Facoltativo: configura gateway.push.apns.relay.baseUrl sul gateway solo quando usi una build relay personalizzata deliberatamente separata.
  3. Abbina l’app iOS al gateway e lascia che sia le sessioni del nodo sia quelle dell’operatore si connettano.
  4. L’app iOS recupera l’identità del gateway, si registra con il relay usando App Attest più la ricevuta dell’app, quindi pubblica il payload push.apns.register basato su relay verso il gateway abbinato.
  5. Il gateway archivia l’handle relay e la concessione di invio, poi li usa per push.test, solleciti di risveglio e risvegli di riconnessione.
Note operative:
  • Se passi l’app iOS a un gateway diverso, riconnetti l’app così può pubblicare una nuova registrazione relay vincolata a quel gateway.
  • Se distribuisci una nuova build iOS che punta a una distribuzione relay diversa, l’app aggiorna la registrazione relay nella cache invece di riutilizzare la vecchia origine relay.
Nota di compatibilità:
  • OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS continuano a funzionare come override env temporanei.
  • Gli URL relay gateway personalizzati devono corrispondere all’URL di base del relay integrato nella build iOS. Il canale di rilascio pubblico App Store rifiuta gli override URL relay iOS personalizzati.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true resta una via di uscita di sviluppo solo local loopback; non rendere persistenti nella configurazione URL relay HTTP.
Consulta App iOS per il flusso end-to-end e Autenticazione e flusso di fiducia per il modello di sicurezza del relay.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: stringa di durata (30m, 2h). Imposta 0m per disabilitare.
  • target: last | none | <channel-id> (per esempio discord, matrix, telegram o whatsapp)
  • directPolicy: allow (predefinito) o block per destinazioni Heartbeat in stile DM
  • Consulta Heartbeat per la guida completa.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: elimina da sessions.json le sessioni di esecuzione isolate completate (predefinito 24h; imposta false per disabilitare).
  • runLog: elimina le righe conservate della cronologia esecuzioni Cron per processo. maxBytes resta accettato per i log di esecuzione più vecchi basati su file.
  • Consulta processi Cron per una panoramica della funzionalità ed esempi CLI.
Abilita gli endpoint Webhook HTTP sul Gateway:
{
  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 di sicurezza:
  • Tratta tutto il contenuto dei payload hook/Webhook come input non attendibile.
  • Usa un hooks.token dedicato; non riutilizzare segreti di autenticazione Gateway attivi (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
  • L’autenticazione hook è solo tramite header (Authorization: Bearer ... o x-openclaw-token); i token nella query string vengono rifiutati.
  • hooks.path non può essere /; mantieni l’ingresso Webhook su un sottopercorso dedicato, ad esempio /hooks.
  • Mantieni disabilitati i flag di bypass dei contenuti non sicuri (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) salvo per debug con ambito strettamente limitato.
  • Se abiliti hooks.allowRequestSessionKey, imposta anche hooks.allowedSessionKeyPrefixes per limitare le chiavi di sessione selezionate dal chiamante.
  • Per agenti guidati da hook, preferisci livelli di modello moderni robusti e criteri rigorosi per gli strumenti (per esempio solo messaggistica più sandboxing dove possibile).
Consulta il riferimento completo per tutte le opzioni di mapping e l’integrazione Gmail.
Esegui più agenti isolati con workspace e sessioni separati:
{
  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-Agent e il riferimento completo per regole di associazione e profili di accesso per agente.
Usa $include per organizzare configurazioni grandi:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • File singolo: sostituisce l’oggetto contenitore
  • Array di file: uniti in profondità in ordine (l’ultimo prevale)
  • Chiavi sorelle: unite dopo gli include (sovrascrivono i valori inclusi)
  • Include annidati: supportati fino a 10 livelli di profondità
  • Percorsi relativi: risolti relativamente al file includente
  • Formato percorso: i percorsi di include non devono contenere byte nulli e devono essere strettamente più brevi di 4096 caratteri prima e dopo la risoluzione
  • Scritture di proprietà di OpenClaw: quando una scrittura modifica solo una sezione di primo livello supportata da un include a file singolo come plugins: { $include: "./plugins.json5" }, OpenClaw aggiorna quel file incluso e lascia intatto openclaw.json
  • Write-through non supportato: include root, array di include e include con override di chiavi sorelle falliscono in modo chiuso per le scritture di proprietà di OpenClaw invece di appiattire la configurazione
  • Confinamento: i percorsi $include devono risolversi sotto la directory che contiene openclaw.json. Per condividere un albero tra macchine o utenti, imposta OPENCLAW_INCLUDE_ROOTS su un elenco di percorsi (: su POSIX, ; su Windows) di directory aggiuntive a cui gli include possono fare riferimento. I symlink vengono risolti e ricontrollati, quindi un percorso che lessicalmente si trova in una directory di configurazione ma il cui target reale esce da ogni root consentita viene comunque rifiutato.
  • Gestione errori: errori chiari per file mancanti, errori di parsing, include circolari, formato percorso non valido e lunghezza eccessiva

​
Ricaricamento a caldo della configurazione

Il Gateway monitora ~/.openclaw/openclaw.json e applica le modifiche automaticamente: non è necessario alcun riavvio manuale per la maggior parte delle impostazioni. Le modifiche dirette ai file sono trattate come non attendibili finché non vengono validate. Il watcher attende che il ciclo di scrittura temporanea/rinomina dell’editor si stabilizzi, legge il file finale e rifiuta le modifiche esterne non valide senza riscrivere openclaw.json. Le scritture di configurazione di proprietà di OpenClaw usano lo stesso controllo di schema prima della scrittura; sovrascritture distruttive come l’eliminazione di gateway.mode o la riduzione del file di oltre metà vengono rifiutate e salvate come .rejected.* per l’ispezione. Se vedi config reload skipped (invalid config) o l’avvio segnala Invalid config, ispeziona la configurazione, esegui openclaw config validate, quindi esegui openclaw doctor --fix per la riparazione. Consulta Risoluzione dei problemi del Gateway per la checklist.

​
Modalità di ricaricamento

ModalitàComportamento
hybrid (predefinito)Applica a caldo istantaneamente le modifiche sicure. Riavvia automaticamente per quelle critiche.
hotApplica a caldo solo le modifiche sicure. Registra un avviso quando è necessario un riavvio: lo gestisci tu.
restartRiavvia il Gateway a ogni modifica della configurazione, sicura o meno.
offDisabilita il monitoraggio dei file. Le modifiche hanno effetto al successivo riavvio manuale.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Cosa si applica a caldo e cosa richiede un riavvio

La maggior parte dei campi si applica a caldo senza interruzioni. In modalità hybrid, le modifiche che richiedono il riavvio vengono gestite automaticamente.
CategoriaCampiRiavvio necessario?
Canalichannels.*, web (WhatsApp) - tutti i canali integrati e pluginNo
Agente e modelliagent, agents, models, routingNo
Automazionehooks, cron, agent.heartbeatNo
Sessioni e messaggisession, messagesNo
Strumenti e mediatools, browser, skills, mcp, audio, talkNo
UI e varieui, logging, identity, bindingsNo
Server Gatewaygateway.* (port, bind, auth, tailscale, TLS, HTTP)Sì
Infrastrutturadiscovery, pluginsSì
gateway.reload e gateway.remote sono eccezioni - modificarli non attiva un riavvio.

​
Pianificazione del ricaricamento

Quando modifichi un file sorgente a cui si fa riferimento tramite $include, OpenClaw pianifica il ricaricamento dal layout creato nel sorgente, non dalla vista appiattita in memoria. Questo mantiene prevedibili le decisioni di hot reload (applicazione a caldo vs riavvio) anche quando una singola sezione di primo livello risiede nel proprio file incluso, ad esempio plugins: { $include: "./plugins.json5" }. La pianificazione del ricaricamento fallisce in modo chiuso se il layout sorgente è ambiguo.

​
RPC di configurazione (aggiornamenti programmatici)

Per gli strumenti che scrivono la configurazione tramite l’API Gateway, preferisci questo flusso:
  • config.schema.lookup per ispezionare un sottoalbero (nodo schema superficiale + riepiloghi dei figli)
  • config.get per recuperare lo snapshot corrente più hash
  • config.patch per aggiornamenti parziali (patch di merge JSON: gli oggetti vengono uniti, null elimina, gli array vengono sostituiti quando confermato esplicitamente con replacePaths se le voci verrebbero rimosse)
  • config.apply solo quando intendi sostituire l’intera configurazione
  • update.run per autoaggiornamento esplicito più riavvio; includi continuationMessage quando la sessione post-riavvio deve eseguire un turno di follow-up
  • update.status per ispezionare l’ultimo sentinel di riavvio dell’aggiornamento e verificare la versione in esecuzione dopo un riavvio
Gli agenti devono considerare config.schema.lookup come il primo punto di accesso per la documentazione e i vincoli esatti a livello di campo. Usa Riferimento di configurazione quando hanno bisogno della mappa di configurazione più ampia, dei valori predefiniti o dei link ai riferimenti dedicati dei sottosistemi.
Le scritture del piano di controllo (config.apply, config.patch, update.run) sono limitate a 3 richieste ogni 60 secondi per deviceId+clientIp. Le richieste di riavvio vengono accorpate e poi applicano un cooldown di 30 secondi tra i cicli di riavvio. update.status è di sola lettura ma con ambito admin perché il sentinel di riavvio può includere riepiloghi dei passaggi di aggiornamento e code dell’output dei comandi.
Esempio di patch parziale: 
openclaw gateway call config.get --params '{}'  # acquisisci payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
Sia config.apply sia config.patch accettano raw, baseHash, sessionKey, note e restartDelayMs. baseHash è obbligatorio per entrambi i metodi quando una configurazione esiste già. config.patch accetta anche replacePaths, un array di percorsi di configurazione la cui sostituzione di array è intenzionale. Se una patch sostituisse o eliminasse un array esistente con meno voci, il Gateway rifiuta la scrittura a meno che quel percorso esatto non compaia in replacePaths; gli array annidati sotto voci di array usano [], ad esempio agents.list[].skills. Questo impedisce che snapshot config.get troncati sovrascrivano silenziosamente array di instradamento o allowlist. Usa config.apply quando intendi sostituire la configurazione completa.

​
Variabili d’ambiente

OpenClaw legge le variabili d’ambiente dal processo padre più:
  • .env dalla directory di lavoro corrente (se presente)
  • ~/.openclaw/.env (fallback globale)
Nessuno dei due file sovrascrive variabili d’ambiente esistenti. Puoi anche impostare variabili d’ambiente inline nella configurazione: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Se abilitata e le chiavi previste non sono impostate, OpenClaw esegue la tua shell di login e importa solo le chiavi mancanti:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Equivalente variabile d’ambiente: OPENCLAW_LOAD_SHELL_ENV=1
Fai riferimento alle variabili d’ambiente in qualsiasi valore stringa della configurazione con ${VAR_NAME}:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Regole:
  • Solo nomi maiuscoli corrispondenti a: [A-Z_][A-Z0-9_]*
  • Le variabili mancanti/vuote generano un errore al momento del caricamento
  • Esegui l’escape con $${VAR} per output letterale
  • Funziona dentro i file $include
  • Sostituzione inline: "${BASE}/v1" → "https://api.example.com/v1"
Per i campi che supportano oggetti SecretRef, puoi usare:
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
I dettagli di SecretRef (inclusi secrets.providers per env/file/exec) sono in Gestione dei segreti. I percorsi delle credenziali supportati sono elencati in Superficie delle credenziali SecretRef.
Vedi Ambiente per precedenza e sorgenti complete.

​
Riferimento completo

Per il riferimento completo campo per campo, vedi Riferimento di configurazione.
Correlati: Esempi di configurazione · Riferimento di configurazione · Doctor

​
Correlati