Usare OpenClaw con CometAPI

Usa questa guida per connettere OpenClaw a CometAPI. Scegli un formato API e un ID modello per la prima configurazione.

OpenClaw v2026.8.1 è anche denominato OpenClaw 2.0. Il pacchetto non utilizza un 2.x numero di versione. Consulta l’ annuncio di OpenClaw 2.0 e le note di rilascio di v2026.8.1.

Riferimenti ufficiali di OpenClaw:

Prerequisiti

Node.js 22.22.3+, 24.15+ o 25.9+. Node 26 è consigliato. Node 23 non è supportato.
Un account CometAPI con una chiave API attiva dal dashboard.
Un ID modello dalla pagina CometAPI Models.

Installazione e aggiornamenti

Prima installazione
Aggiornare un'installazione

Il programma di installazione ufficiale può installare la CLI senza avviare l’onboarding. In questo modo la configurazione del modello rimane un passaggio separato.

macOS / Linux / WSL2
Windows PowerShell

Il comando seguente esegue il programma di installazione ufficiale:

curl -fsSL https://openclaw.ai/install.sh \
  | bash -s -- --no-onboard

Il comando seguente esegue il programma di installazione ufficiale per PowerShell:

& ([scriptblock]::Create(
  (iwr -useb https://openclaw.ai/install.ps1)
)) -NoOnboard

Se gestisci Node.js e npm autonomamente, npm 11.16+ e npm 12 accettano l’opzione --allow-scripts opzione. Il comando seguente installa OpenClaw senza avviare l’onboarding:

npm install -g openclaw@latest --allow-scripts=openclaw

In npm 11.15 e versioni precedenti, ometti --allow-scripts=openclaw perché quella versione di npm non riconosce l’opzione.Verifica che la CLI installata soddisfi la versione minima richiesta per questa guida:

openclaw --version

Prosegui con Configurare CometAPI. Non eseguire l’onboarding standard prima, perché il flusso guidato non espone ogni adattatore API personalizzato. adattatore.

Crea e verifica un backup prima di un aggiornamento importante. L’archivio può contenere chiavi API, stato dei canali e dati di autenticazione, quindi proteggilo come proteggi la directory dello stato di OpenClaw.I comandi seguenti creano il backup e aggiornano OpenClaw:

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw update

Dopo l’aggiornamento, ripara le migrazioni supportate e verifica lo stato di Gateway:

openclaw doctor --fix
openclaw gateway restart
openclaw health

Un aggiornamento conserva il percorso del modello configurato. Non ripetere l’onboarding a meno che tu non voglia modificare il provider del modello o la sua autenticazione.

Configurare CometAPI

Usare l’onboarding classico

L’onboarding classico è il percorso preferito per la prima installazione per Chat Completions, Responses e Anthropic Messages. Il comando seguente apre l’onboarding classico e installa il servizio in background :

openclaw onboard --classic --install-daemon

In Modello/Autenticazione, scegli Provider personalizzato. Quindi inserisci i valori per una di queste opzioni di compatibilità:

Formato API	ID provider	Opzione di compatibilità	URL di base
Chat Completions	`cometapi-openai`	Compatibile con OpenAI	`https://api.cometapi.com/v1`
Responses	`cometapi-openai-responses`	Compatibile con OpenAI Responses	`https://api.cometapi.com/v1`
Anthropic Messages	`cometapi-claude`	Compatibile con Anthropic	`https://api.cometapi.com`

Inserisci l’ID provider corrispondente, your-model-id e la tua chiave API CometAPI quando richiesto. La procedura guidata del terminale maschera l’input della chiave API. Il menu classico Provider personalizzato non include l’adattatore Google Generative AI . Per usare tale adattatore, completa Configurare un provider con i comandi di configurazione, imposta il modello principale e quindi esegui l’onboarding classico. Scegli Mantieni la configurazione del modello esistente quando la procedura guidata presenta tale opzione.

Configurare un provider con i comandi di configurazione

Usa questo percorso per l’adattatore Google o per modifiche di configurazione controllate. OpenClaw supporta JSON5, quindi non analizzare e riscrivere openclaw.json con uno strumento JSON rigoroso.

Lo strumento di scrittura della configurazione nativo di OpenClaw convalida JSON5, ma normalizza il file in JSON quando scrive. I commenti esistenti, le virgole finali e la formattazione potrebbero essere rimossi. Crea un backup verificato prima di applicare una patch se questi dettagli sono importanti per te.

Per prima cosa, stampa il percorso della configurazione attiva e convalidane il contenuto:

openclaw config file
openclaw config validate

OpenClaw legge le chiavi API dei provider dall’ambiente di processo o dal file globale dello stato .env. Non considera attendibile un file .env dell’area di lavoro per le chiavi API dei provider . Il file globale è ~/.openclaw/.env, oppure $OPENCLAW_STATE_DIR/.env quando OPENCLAW_STATE_DIR è impostato. Se l’onboarding classico ha memorizzato la chiave API, salta il passaggio seguente. Altrimenti, usa la scheda relativa al tuo sistema operativo per memorizzare la chiave API senza visualizzarla .

macOS / Linux / WSL2
Windows PowerShell

I comandi seguenti aggiornano COMETAPI_KEY atomicamente e rifiutano un valore vuoto:

state_dir="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
install -d -m 700 "$state_dir"
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
if [ -z "$COMETAPI_KEY" ]; then
  echo "The CometAPI API key cannot be empty." >&2
  unset COMETAPI_KEY
  exit 1
fi
umask 077
env_file="$state_dir/.env"
temp_file="$(mktemp "${env_file}.XXXXXX")"
if [ -f "$env_file" ]; then
  awk -F= '$1 != "COMETAPI_KEY"' "$env_file" > "$temp_file"
fi
printf 'COMETAPI_KEY=%s\n' "$COMETAPI_KEY" >> "$temp_file"
chmod 600 "$temp_file"
mv "$temp_file" "$env_file"
unset COMETAPI_KEY temp_file env_file state_dir

I comandi seguenti aggiornano COMETAPI_KEY senza visualizzarlo:

$stateDir = if ($env:OPENCLAW_STATE_DIR) {
  $env:OPENCLAW_STATE_DIR
} else {
  Join-Path $HOME ".openclaw"
}
New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
$secureKey = Read-Host "CometAPI API key" -AsSecureString
$plainKey = [Net.NetworkCredential]::new("", $secureKey).Password
if ([string]::IsNullOrWhiteSpace($plainKey)) {
  throw "The CometAPI API key cannot be empty."
}
$envFile = Join-Path $stateDir ".env"
$lines = @()
if (Test-Path $envFile) {
  $lines = @(Get-Content $envFile | Where-Object {
    $_ -notmatch '^COMETAPI_KEY='
  })
}
$lines += "COMETAPI_KEY=$plainKey"
$tempFile = Join-Path $stateDir ".$([guid]::NewGuid()).tmp"
[IO.File]::WriteAllLines($tempFile, $lines)
Move-Item -Force $tempFile $envFile
$plainKey = $null
$secureKey = $null

Prima di aggiungere un provider, controlla il relativo percorso di destinazione. Sostituisci l’ID provider nel comando seguente con l’ID della scheda selezionata:

openclaw config get models.providers.cometapi-openai --json

Se il comando restituisce un provider configurato, fermati prima di applicare l’esempio. config patch unisce gli oggetti, ma sostituisce gli array. Unisci il nuovo modello nell’ array di modelli del provider prima di scrivere tale array. In questo modo vengono preservati i metadati del modello, le intestazioni personalizzate e le altre impostazioni del provider. Scegli un formato API. Ogni patch usa un SecretRef basato sull’ambiente, modifica solo i percorsi di configurazione di destinazione e mantiene intatte le altre sezioni della configurazione.

Un ID modello non è automaticamente compatibile con ogni adattatore API. Seleziona un adattatore supportato dal modello e dalla route CometAPI esatti, quindi verifica tale combinazione di provider/modello/adattatore con una richiesta attiva. Il your-model-id valore seguente è un segnaposto di configurazione, non un’affermazione universale di compatibilità.

Chat Completions
Responses
Anthropic Messages
Google Generative AI

ID provider: cometapi-openai
Adattatore OpenClaw: openai-completions
URL di base: https://api.cometapi.com/v1
Riferimento del modello principale: cometapi-openai/your-model-id

Crea cometapi.patch.json5 con questa patch del provider:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-completions",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Convalida la patch prima che OpenClaw scriva la configurazione:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Se la convalida riesce, applica la stessa patch:

openclaw config patch --file ./cometapi.patch.json5

Se non è configurato alcun modello principale, imposta questo modello come predefinito:

openclaw models set cometapi-openai/your-model-id

Verifica la configurazione del provider e invia una richiesta minima al modello:

openclaw models list --provider cometapi-openai
openclaw models status --probe \
  --probe-provider cometapi-openai
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai/your-model-id \
  --thinking off \
  --json

Per cambiare la sessione di chat OpenClaw attiva, esegui questo comando di chat:

/model cometapi-openai/your-model-id

ID provider: cometapi-openai-responses
Adattatore OpenClaw: openai-responses
URL di base: https://api.cometapi.com/v1
Riferimento del modello principale: cometapi-openai-responses/your-model-id

Crea cometapi.patch.json5 con questa patch del provider:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai-responses": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-responses",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Convalida la patch prima che OpenClaw scriva la configurazione:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Se la convalida riesce, applica la stessa patch:

openclaw config patch --file ./cometapi.patch.json5

Se non è configurato alcun modello principale, imposta questo modello come predefinito:

openclaw models set cometapi-openai-responses/your-model-id

Verifica la configurazione del provider e invia una richiesta minima al modello:

openclaw models list --provider cometapi-openai-responses
openclaw models status --probe \
  --probe-provider cometapi-openai-responses
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai-responses/your-model-id \
  --thinking off \
  --json

Per cambiare la sessione di chat OpenClaw attiva, esegui questo comando di chat:

/model cometapi-openai-responses/your-model-id

ID provider: cometapi-claude
Adattatore OpenClaw: anthropic-messages
URL di base: https://api.cometapi.com
Riferimento del modello principale: cometapi-claude/your-model-id

Crea cometapi.patch.json5 con questa patch del provider:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-claude": {
        baseUrl: "https://api.cometapi.com",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "anthropic-messages",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Convalida la patch prima che OpenClaw scriva la configurazione:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Se la convalida riesce, applica la stessa patch:

openclaw config patch --file ./cometapi.patch.json5

Se non è configurato alcun modello principale, imposta questo modello come predefinito:

openclaw models set cometapi-claude/your-model-id

Verifica la configurazione del provider e invia una richiesta minima al modello:

openclaw models list --provider cometapi-claude
openclaw models status --probe \
  --probe-provider cometapi-claude
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-claude/your-model-id \
  --thinking off \
  --json

Per cambiare la sessione di chat OpenClaw attiva, esegui questo comando di chat:

/model cometapi-claude/your-model-id

ID provider: cometapi-google
Adattatore OpenClaw: google-generative-ai
URL di base: https://api.cometapi.com/v1beta
Riferimento del modello principale: cometapi-google/your-model-id

Crea cometapi.patch.json5 con questa patch del provider:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-google": {
        baseUrl: "https://api.cometapi.com/v1beta",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "google-generative-ai",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Convalida la patch prima che OpenClaw scriva la configurazione:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Se la convalida riesce, applica la stessa patch:

openclaw config patch --file ./cometapi.patch.json5

Se non è configurato alcun modello principale, imposta questo modello come predefinito:

openclaw models set cometapi-google/your-model-id

Verifica la configurazione del provider e invia una richiesta minima al modello:

openclaw models list --provider cometapi-google
openclaw models status --probe \
  --probe-provider cometapi-google
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-google/your-model-id \
  --thinking off \
  --json

Per cambiare la sessione di chat OpenClaw attiva, esegui questo comando di chat:

/model cometapi-google/your-model-id

Se una configurazione usa già l’ID provider cometapi-gemini, mantieni tale ID e usalo nei riferimenti ai modelli e nei comandi. Non rinominarlo né creare un provider duplicato solo per conformarti a questa guida.

Elenco di modelli OpenClaw 2026.8.1 con quattro formati di provider CometAPI

Per un nuovo provider, openclaw config set fornisce lo stesso schema e gli stessi controlli SecretRef. Usa --strict-json, --merge e --dry-run prima della scrittura. La seguente alternativa mostra in anteprima il provider Chat Completions:

openclaw config set models.providers.cometapi-openai \
  '{
    "baseUrl": "https://api.cometapi.com/v1",
    "apiKey": {
      "source": "env",
      "provider": "default",
      "id": "COMETAPI_KEY"
    },
    "api": "openai-completions",
    "models": [
      {
        "id": "your-model-id",
        "name": "CometAPI model",
        "input": ["text"]
      }
    ]
  }' \
  --strict-json --merge --dry-run

Se l’esecuzione di prova riesce, ripeti il comando senza --dry-run per salvarlo. Non applicare questo esempio a un provider configurato. L’array models deve includere l’elenco completo e unito dei modelli del provider prima di una scrittura.

Comprendere i metadati del modello

Le patch minime dichiarano un modello solo testuale. Aggiungi metadati facoltativi solo quando hai verificato le specifiche del modello:

Campo	Effetto
`input`	Dichiara le modalità di input accettate. Usa `["text", "image"]` solo quando il modello accetta input di immagini nativo.
`contextWindow`	Registra la capacità nativa della finestra di contesto del modello.
`contextTokens`	Limita il budget di input attivo senza modificare `contextWindow`.
`maxTokens`	Limita i token di output richiesti da OpenClaw al modello.

Valori errati possono nascondere input supportati, sovrastimare il contesto utilizzabile o richiedere una dimensione di output non supportata. Mantieni your-model-id negli esempi riutilizzabili, e usa la pagina Modelli CometAPI per selezionare un ID modello.

Verifica della configurazione completa

Dopo le modifiche al file di configurazione o al file globale .env, riavvia il Gateway:

openclaw gateway restart

Quindi convalida la configurazione e lo stato del Gateway:

openclaw config validate
openclaw doctor
openclaw health

Esegui i comandi specifici del provider dalla scheda del formato API selezionata. Un elenco di modelli o un controllo dello stato confermano solo la configurazione. Il comando openclaw agent exec invia una richiesta reale al modello. Verifica che restituisca OPENCLAW_OK senza errori di autenticazione, adattatore o modello non risolti. Se OpenClaw ritenta una richiesta, registra e ispeziona ogni tentativo anziché considerare il marcatore finale come successo al primo tentativo.

Risoluzione dei problemi

La chiave API è mancante

Verifica che COMETAPI_KEY sia presente nell’ambiente del processo o nel file .env dello stato globale. Non stampare il valore nell’output del terminale.Dopo aver corretto l’origine attendibile della chiave, riavvia e controlla il Gateway:

openclaw gateway restart
openclaw health

Un ID provider ha impostazioni diverse

Non sovrascrivere un provider che dispone di baseUrl, api, intestazioni personalizzate o metadati del modello diversi. Ispeziona prima il provider di destinazione:

openclaw config get models.providers.cometapi-openai --json
openclaw config validate

Usa un ID provider diverso quando entrambe le configurazioni sono intenzionali. Se la differenza è accidentale, crea un backup verificato prima di modificare il provider di destinazione.

Un aggiornamento non è stato completato

Ispeziona lo stato dell’aggiornamento prima di riparare l’installazione:

openclaw update status --json
openclaw update repair
openclaw doctor --fix
openclaw health

Questi comandi mantengono la directory dello stato.

È necessario un rollback del codice

Reinstalla una versione nota del pacchetto mantenendo la directory dello stato. Prima, visualizza l’anteprima dell’operazione:

openclaw update --tag 2026.8.1 --dry-run

Se l’anteprima è corretta, esegui la stessa operazione senza --dry-run:

openclaw update --tag 2026.8.1
openclaw doctor --fix
openclaw health

Ripristina un backup dello stato solo quando il codice installato non riesce a leggere lo stato. Un ripristino dello stato può eliminare le sessioni e le modifiche alla configurazione che sono state create dopo il backup.

Panoramica

Agenti AI per la programmazione

Agenti AI

Client di chat AI

Traduzione e linguaggio

Piattaforme di automazione

Osservabilità e valutazione

Framework AI

Prerequisiti

Installazione e aggiornamenti

Configurare CometAPI

Usare l’onboarding classico

Configurare un provider con i comandi di configurazione

Comprendere i metadati del modello

Verifica della configurazione completa

Risoluzione dei problemi

​Prerequisiti

​Installazione e aggiornamenti

​Configurare CometAPI

​Usare l’onboarding classico

​Configurare un provider con i comandi di configurazione

​Comprendere i metadati del modello

​Verifica della configurazione completa

​Risoluzione dei problemi

Prerequisiti

Installazione e aggiornamenti

Configurare CometAPI

Usare l’onboarding classico

Configurare un provider con i comandi di configurazione

Comprendere i metadati del modello

Verifica della configurazione completa

Risoluzione dei problemi