Tutorial di cinque minuti per configurare OpenClaw con CometAPI

All’inizio del 2026, OpenClaw — la piattaforma open-source per runtime di agenti e assistenti AI — continua a essere ampiamente adottata da sviluppatori, team di ricerca e imprese che desiderano un’orchestrazione multi-modello su canali come Slack, Telegram, WhatsApp e l’esecuzione locale da riga di comando. Nel frattempo, CometAPI è emersa come un potente gateway LLM compatibile con OpenAI, che aggrega centinaia di modelli (ad es. Kimi-K2.5, varianti GPT, Claude) sotto un unico endpoint API.

Questo articolo è una guida pratica e passo-passo per configurare OpenClaw in modo che utilizzi CometAPI come provider di modelli. Imparerai come installare, configurare i provider, definire i profili di autenticazione, verificare il funzionamento e passare tra i modelli — il tutto con esempi di configurazione reali e suggerimenti basati sulla documentazione più recente e sui feedback della community.

Che cos’è OpenClaw e perché integrarlo con CometAPI?

OpenClaw è una piattaforma open-source, device-centric, che collega l’AI conversazionale alle app di chat e ai dispositivi che le persone già usano — WhatsApp, Telegram, Slack, Discord e altro — permettendoti di eseguire i modelli dove preferisci e mantenere chiavi e dati sotto il tuo controllo. Il progetto e i suoi repository contengono esempi che mostrano come OpenClaw selezioni i provider LLM tramite una configurazione in stile gateway.

CometAPI è una piattaforma di aggregazione API che espone molti provider di modelli attraverso una singola interfaccia REST e SDK in stile OpenAI. Questo la rende comoda come unico punto di integrazione se vuoi cambiare modelli, testare i prezzi o centralizzare l’osservabilità senza modificare il core di OpenClaw.

Perché abbinare OpenClaw con CometAPI?

OpenClaw è agnostico rispetto ai modelli; esegue agenti e workflow ma si affida a provider LLM esterni. CometAPI funge da gateway compatibile con OpenAI, consentendoti di instradare le chiamate verso:

Famiglia di modelli GPT
Famiglia di modelli Claude
Kimi-K2.5 e altri modelli di terze parti aggregati da CometAPI

Questo ti offre scelta, flessibilità, controllo dei costi e ridondanza.

Come configuro OpenClaw per usare CometAPI come provider di modelli?

Risposta: aggiungi una voce di provider alla configurazione di OpenClaw che punti all’endpoint REST di CometAPI e mappa i modelli sulla struttura models.providers di OpenClaw. Il progetto OpenClaw supporta l’aggiunta di provider personalizzati tramite models.providers (lo stesso schema usato per altri gateway) e si aspetta un flavor api come "openai-completions" o "anthropic-messages" a seconda della semantica del provider.

CometAPI supporta tre formati API. Aggiungine uno o più in ~/.openclaw/openclaw.json:

Provider	Formato API	URL di base
cometapi-openai	openai-completions	`https://api.cometapi.com/v1`
cometapi-claude	anthropic-messages	`https://api.cometapi.com`
cometapi-google	google-generative-ai	https://api.cometapi.com/v1beta

Quali sono i prerequisiti per configurare OpenClaw con CometAPI?

Prima dell’integrazione, assicurati di avere l’ambiente, gli strumenti e gli account giusti.

Requisiti dell’ambiente

Ti serviranno:

Un ambiente tipo Unix: Linux, macOS o Windows Subsystem for Linux (WSL2)
Node.js e npm installati (OpenClaw usa Node sotto il cofano)
Accesso al terminale con bash/zsh o PowerShell

La documentazione ufficiale menziona anche che OpenClaw può essere eseguito via Docker, ideale per setup isolati e di produzione.

Account e chiavi API

Ti servono:

Un account CometAPI
Una chiave LLM CometAPI valida (archiviata in una variabile d’ambiente sicura)
Opzionale: account per ulteriori provider OpenClaw (OpenAI, Anthropic, modelli locali via Ollama)

💡 Suggerimento: usa un gestore sicuro di segreti o il portachiavi del sistema operativo invece di memorizzare le chiavi in chiaro. È quanto raccomanda la stessa documentazione di OpenClaw per la sicurezza in produzione.

Come configuri OpenClaw per chiamare CometAPI? (passo-passo)

Di seguito un setup pratico e conciso da cinque minuti. I nomi dei file o le chiavi esatte dipendono dalla tua versione e distribuzione di OpenClaw, ma i concetti sono direttamente trasposti dal repository e dalla documentazione ufficiali di OpenClaw.

Passo 0 — Imposta le variabili d’ambiente (il percorso rapido e sicuro)

Esempio shell (Linux/macOS):

# do NOT commit this to gitexport COMETAPI_KEY="sk-YourCometApiKeyHere"export OPENCLAW_ENV="production"   # or development

Per la produzione, usa il meccanismo di segreti della tua piattaforma (ad es., Docker secrets, systemd, Kubernetes secrets).

Passo 1 — Installa OpenClaw

Opzione A: One-liner tramite script di installazione

È il modo più rapido:

curl -fsSL https://openclaw.ai/install.sh | bash# Verify installationopenclaw --version

Questo script rileva il tuo sistema operativo e installa OpenClaw insieme alle dipendenze.

Opzione B: Installazione globale via npm

Se già gestisci i pacchetti Node:

npm install -g openclaw@latestopenclaw --version

Questo installa globalmente la CLI di OpenClaw.

Opzionale: Installazione Docker

Se distribuisci in produzione o desideri isolamento:

docker pull openclaw/openclaw:latestdocker run -d --name openclaw -v ~/.openclaw:/root/.openclaw openclaw/openclaw

Le distribuzioni containerizzate semplificano la gestione di dipendenze e carichi di lavoro.nClaw version; gli esempi di OpenClaw seguono questo schema.)

Passo 2 — Configura i provider

Configurare i provider indica a OpenClaw dove trovare il backend LLM.

Modifica del file di configurazione di OpenClaw

OpenClaw memorizza la configurazione in un file JSON in:

~/.openclaw/openclaw.json

Definirai un provider personalizzato per CometAPI.

Ecco una configurazione minima del provider:

base_url indica a OpenClaw di inviare le richieste LLM all’endpoint compatibile con OpenAI di CometAPI.
auth_env punta alla variabile d’ambiente che contiene la tua chiave API.
Il flag type specifica il tipo di protocollo API (stile OpenAI).

{
  "models": {
    "mode": "merge",
    "providers": {
      "cometapi-openai": {
        "baseUrl": "https://api.cometapi.com/v1",
        "apiKey": "<YOUR_COMETAPI_KEY>",
        "api": "openai-completions",
        "models": [{ "id": "gpt-5.2", "name": "GPT-5.2" }]
      },
      "cometapi-claude": {
        "baseUrl": "https://api.cometapi.com",
        "apiKey": "<YOUR_COMETAPI_KEY>",
        "api": "anthropic-messages",
        "models": [{ "id": "claude-opus-4-6", "name": "Claude Opus 4.6" }]
      },
      "cometapi-google": {
        "baseUrl": "https://api.cometapi.com/v1beta",
        "apiKey": "<YOUR_COMETAPI_KEY>",
        "api": "google-generative-ai",
        "models": [{ "id": "gemini-3-pro-preview", "name": "Gemini 3 Pro" }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "cometapi-claude/claude-opus-4-6" }
    }
  },
  "auth": {
    "profiles": {
      "cometapi-openai:default": { "provider": "cometapi-openai", "mode": "api_key" },
      "cometapi-claude:default": { "provider": "cometapi-claude", "mode": "api_key" },
      "cometapi-google:default": { "provider": "cometapi-google", "mode": "api_key" }
    }
  }
}

Sostituisci <YOUR_COMETAPI_KEY> con la tua chiave API. Tutti e tre i provider usano la stessa chiave.

Puoi aggiungere qualsiasi modello dalla Pagina dei modelli CometAPI al provider corrispondente.

Passo 3 — Configura i profili di autenticazione

⚠️ Obbligatorio! OpenClaw legge le chiavi API da questo file, non da openclaw.json. Saltare questo passaggio causa errori HTTP 401.

Crea ~/.openclaw/agents/main/agent/auth-profiles.json:

{
  "version": 1,
  "profiles": {
    "cometapi-openai:default": {
      "type": "api_key",
      "provider": "cometapi-openai",
      "key": "<YOUR_COMETAPI_KEY>"
    },
    "cometapi-claude:default": {
      "type": "api_key",
      "provider": "cometapi-claude",
      "key": "<YOUR_COMETAPI_KEY>"
    },
    "cometapi-google:default": {
      "type": "api_key",
      "provider": "cometapi-google",
      "key": "<YOUR_COMETAPI_KEY>"
    }
  },
  "lastGood": {
    "cometapi-openai": "cometapi-openai:default",
    "cometapi-claude": "cometapi-claude:default",
    "cometapi-google": "cometapi-google:default"
  }
}

Riavvia il gateway:

openclaw gateway restart

Verifica gli stati con:

openclaw auth status

E per elencare tutti i modelli configurati:

openclaw models list

Questi comandi confermano se i tuoi provider e profili di autenticazione sono impostati correttamente. Tutti i modelli dovrebbero mostrare Auth = yes:

Model                                        Auth
cometapi-openai/gpt-5.2                      yes
cometapi-claude/claude-opus-4-6              yes
cometapi-google/gemini-3-pro-preview         yes

Passo 4 — Esegui OpenClaw e osserva i log

Avvia/riavvia OpenClaw e segui i log. Controlla in particolare:

Log delle richieste in uscita che mostrano base_url o il nome del provider.
HTTP 401/403 → problema di chiave o scope.
429 → rate limit (valuta cambi di modello/prestazioni).
Latenze insolitamente lunghe → rete o throttling del modello.

Un comando diagnostico rapido (esempio):

# If OpenClaw runs as a system service:journalctl -u openclaw -f# If running in Docker:docker logs -f openclaw

Passa da un modello all’altro

# Set default model
openclaw models set cometapi-claude/claude-opus-4-6

# Or switch in TUI
/model cometapi-openai/gpt-5.2

Come usi OpenClaw con CometAPI nei workflow reali?

Dopo l’integrazione, puoi creare workflow che includono generazione di codice, attività multimodali, automazione di agenti e pubblicazione su canali.

Esempio di workflow: interpretazione di screenshot

Se il tuo agente supporta gli allegati:

User: Analyze this screenshot and generate a minimal React component.

OpenClaw invia il prompt (più i dati immagine) tramite il modello di CometAPI (come Kimi K-2.5), che restituisce output di codice — ideale per prototipare workflow UI.

Integrazione Slack / Discord

Una volta che CometAPI è il backend, puoi instradare le risposte degli agenti su qualsiasi piattaforma configurata:

Canali Slack
Gruppi WhatsApp
Bot Telegram

OpenClaw gestisce l’instradamento e il parsing delle richieste; CometAPI fornisce le risposte del modello.

Quale monitoraggio e quali controlli sui costi dovresti aggiungere?

Quando centralizzi su un aggregatore, guadagni controllo — ma devi configurarlo:

Strumentazione

Registra nome del modello, token usati, latenza e codici di errore per ogni richiesta.
Etichetta le richieste con agente e canale (ad es., agent=personal_assistant, channel=telegram) così da attribuire i costi.

Leve di controllo dei costi

Imposta max_tokens e timeout_seconds nella configurazione del provider.
Usa modelli più economici per attività di routine e riserva i modelli grandi per flussi ad alto valore.
Configura rate limit per agente e quote per utente (OpenClaw spesso può essere esteso per applicarli).

CometAPI pubblicizza strumenti per l’ottimizzazione di prestazioni e costi; utilizza la telemetria di entrambe le parti (log di OpenClaw + metriche d’uso di CometAPI) per creare dei guardrail.

Come risolvo i comuni errori nell’integrazione?

Risposta: ecco le modalità di errore più comuni e come risolverle rapidamente:

Fix: Il pannello di controllo di OpenClaw mostrerà un token monouso; incollalo nelle impostazioni della Control UI come da documentazione. Le note della community fanno spesso riferimento a questo passaggio.

401 Unauthorized

Causa: COMETAPI_KEY mancante, errata o non iniettata nel processo OpenClaw.

Fix: Esporta la chiave nella shell che avvia OpenClaw o scrivila nel tuo .env di OpenClaw e riavvia il gateway. Conferma con un test curl.

Provider che ricade silenziosamente su/default

Causa: JSON models.providers malformato o api mancante, che porta OpenClaw a ignorare il provider.

Fix: Valida openclaw.json (lint JSON) e assicurati che api corrisponda ai flavor supportati. I thread della community mostrano che questa configurazione errata è comune.

Timeout o latenza elevata

Causa: percorso di rete o lentezza del modello remoto.

Fix: Scegli un modello Comet a latenza più bassa o esegui OpenClaw vicino alla stessa regione cloud; valuta l’esecuzione di un modello locale per attività sensibili alla latenza. Documentazione e blog discutono il trade-off tra modelli locali e API (latenza vs costi).

Uso eccessivo / 429

Causa: raggiunti i limiti di quota o di piano di CometAPI.

Fix: Controlla la dashboard Comet per le quote; aggiungi logica di retry/backoff nelle azioni dell’agente OpenClaw o limita le richieste al gateway. Comet e la documentazione dei partner evidenziano le quote dei piani e i pattern consigliati di backoff.

Gateway token mancante / disconnessioni websocket

Causa: token di controllo di OpenClaw mancanti nella configurazione della dashboard quando si esegue il Gateway.

Nota finale

Collegare OpenClaw a CometAPI è rapido e sblocca un potente backend multi-modello per il tuo assistente personale. Ma la velocità non giustifica ignorare la sicurezza: vincola il gateway a localhost durante i test, usa allowlist, registra tutto e richiedi conferme per azioni distruttive. Con questi controlli in atto, puoi passare da zero a un agente OpenClaw → CometAPI funzionante in circa cinque minuti — mantenendo dati e sistemi protetti mentre sperimenti.

Gli sviluppatori possono accedere a kimi k-2.5 tramite CometAPI già da ora. Per iniziare, esplora le capacità del modello nel Playground e consulta la guida API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l’accesso a CometAPI e di aver ottenuto la chiave API. CometAPI offre un prezzo molto inferiore rispetto al prezzo ufficiale per aiutarti a integrare.

Pronto a iniziare? → Iscriviti a OpenClaw oggi stesso!

Se vuoi conoscere altri consigli, guide e novità sull’AI seguici su VK, X e Discord!