Use OpenClaw with CometAPI

Use this guide to connect OpenClaw to CometAPI. Choose one API format and model ID for the first configuration.

OpenClaw v2026.8.1 is also branded OpenClaw 2.0. The package does not use a 2.x version number. See the OpenClaw 2.0 announcement and the v2026.8.1 release notes.

Official OpenClaw references:

Prerequisites

Node.js 22.22.3+, 24.15+, or 25.9+. Node 26 is recommended. Node 23 is not supported.
A CometAPI account with an active API key from the dashboard.
A model ID from the CometAPI Models page.

Installation and upgrades

First installation
Upgrade an installation

The official installer can install the CLI without starting onboarding. This keeps model configuration as a separate step.

macOS / Linux / WSL2
Windows PowerShell

The following command runs the official installer:

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

The following command runs the official PowerShell installer:

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

If you manage Node.js and npm yourself, npm 11.16+ and npm 12 accept the --allow-scripts option. The following command installs OpenClaw without starting onboarding:

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

On npm 11.15 and earlier, omit --allow-scripts=openclaw because that npm version does not recognize the option.Confirm that the installed CLI meets the minimum version for this guide:

openclaw --version

Continue to Configure CometAPI. Do not run plain onboarding first, because the guided flow does not expose every custom API adapter.

Create and verify a backup before a significant update. The archive can contain API keys, channel state, and authentication data, so protect it as you protect the OpenClaw state directory.The following commands create the backup and update OpenClaw:

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

After the update, repair supported migrations and check Gateway health:

openclaw doctor --fix
openclaw gateway restart
openclaw health

An update preserves the configured model route. Do not repeat onboarding unless you want to change the model provider or its authentication.

Configure CometAPI

Use classic onboarding

Classic onboarding is the preferred first-installation path for Chat Completions, Responses, and Anthropic Messages. The following command opens classic onboarding and installs the background service:

openclaw onboard --classic --install-daemon

In Model/Auth, choose Custom Provider. Then enter the values for one of these compatibility options:

API format	Provider ID	Compatibility option	Base URL
Chat Completions	`cometapi-openai`	OpenAI-compatible	`https://api.cometapi.com/v1`
Responses	`cometapi-openai-responses`	OpenAI Responses-compatible	`https://api.cometapi.com/v1`
Anthropic Messages	`cometapi-claude`	Anthropic-compatible	`https://api.cometapi.com`

Enter the matching provider ID, your-model-id, and your CometAPI API key when prompted. The terminal wizard masks the API key input. The classic Custom Provider menu does not include the Google Generative AI adapter. To use that adapter, complete Configure a provider with config commands, set the primary model, and then run classic onboarding. Choose Keep existing model config when the wizard presents that option.

Configure a provider with config commands

Use this path for the Google adapter or for controlled configuration changes. OpenClaw supports JSON5, so do not parse and rewrite openclaw.json with a strict JSON tool.

OpenClaw’s native config writer validates JSON5 but normalizes the file to JSON when it writes. Existing comments, trailing commas, and formatting may be removed. Create a verified backup before applying a patch if those details are important to you.

First, print the active config path and validate its content:

openclaw config file
openclaw config validate

OpenClaw reads provider API keys from the process environment or the global state .env file. It does not trust a workspace .env file for provider API keys. The global file is ~/.openclaw/.env, or $OPENCLAW_STATE_DIR/.env when OPENCLAW_STATE_DIR is set. If classic onboarding stored the API key, skip the following step. Otherwise, use the tab for your operating system to store the API key without displaying it.

macOS / Linux / WSL2
Windows PowerShell

The following commands update COMETAPI_KEY atomically and reject an empty value:

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

The following commands update COMETAPI_KEY without displaying it:

$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

Before you add a provider, inspect its target path. Replace the provider ID in the following command with the ID from your selected tab:

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

If the command returns a configured provider, stop before applying the example. config patch merges objects, but it replaces arrays. Merge the new model into the provider’s model array before you write that array. This preserves model metadata, custom headers, and other provider settings. Choose one API format. Each patch uses an environment-backed SecretRef, changes only the target config paths, and keeps other config sections intact.

A model ID is not automatically compatible with every API adapter. Select an adapter that the exact CometAPI model and route support, then verify that provider/model/adapter combination with a live request. The your-model-id value below is a configuration placeholder, not a universal compatibility claim.

Chat Completions
Responses
Anthropic Messages
Google Generative AI

Provider ID: cometapi-openai
OpenClaw adapter: openai-completions
Base URL: https://api.cometapi.com/v1
Primary model reference: cometapi-openai/your-model-id

Create cometapi.patch.json5 with this provider patch:

{
  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"],
          },
        ],
      },
    },
  },
}

Validate the patch before OpenClaw writes the config:

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

If validation succeeds, apply the same patch:

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

If no primary model is configured, set this model as the default:

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

Verify the provider configuration and send a minimal model request:

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

To switch the active OpenClaw chat session, run this chat command:

/model cometapi-openai/your-model-id

Provider ID: cometapi-openai-responses
OpenClaw adapter: openai-responses
Base URL: https://api.cometapi.com/v1
Primary model reference: cometapi-openai-responses/your-model-id

Create cometapi.patch.json5 with this provider patch:

{
  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"],
          },
        ],
      },
    },
  },
}

Validate the patch before OpenClaw writes the config:

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

If validation succeeds, apply the same patch:

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

If no primary model is configured, set this model as the default:

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

Verify the provider configuration and send a minimal model request:

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

To switch the active OpenClaw chat session, run this chat command:

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

Provider ID: cometapi-claude
OpenClaw adapter: anthropic-messages
Base URL: https://api.cometapi.com
Primary model reference: cometapi-claude/your-model-id

Create cometapi.patch.json5 with this provider patch:

{
  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"],
          },
        ],
      },
    },
  },
}

Validate the patch before OpenClaw writes the config:

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

If validation succeeds, apply the same patch:

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

If no primary model is configured, set this model as the default:

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

Verify the provider configuration and send a minimal model request:

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

To switch the active OpenClaw chat session, run this chat command:

/model cometapi-claude/your-model-id

Provider ID: cometapi-google
OpenClaw adapter: google-generative-ai
Base URL: https://api.cometapi.com/v1beta
Primary model reference: cometapi-google/your-model-id

Create cometapi.patch.json5 with this provider patch:

{
  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"],
          },
        ],
      },
    },
  },
}

Validate the patch before OpenClaw writes the config:

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

If validation succeeds, apply the same patch:

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

If no primary model is configured, set this model as the default:

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

Verify the provider configuration and send a minimal model request:

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

To switch the active OpenClaw chat session, run this chat command:

/model cometapi-google/your-model-id

If a configuration already uses the cometapi-gemini provider ID, keep that ID and use it in model references and commands. Do not rename it or create a duplicate provider only to match this guide.

OpenClaw 2026.8.1 model list with four CometAPI provider formats

For a new provider, openclaw config set provides the same schema and SecretRef checks. Use --strict-json, --merge, and --dry-run before the write. The following alternative previews the Chat Completions provider:

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

If the dry run succeeds, repeat the command without --dry-run to save it. Do not apply this example to a configured provider. The models array must include the provider’s complete merged model list before a write.

Understand model metadata

The minimal patches declare a text-only model. Add optional metadata only when you have verified the model’s specifications:

Field	Effect
`input`	Declares accepted input modalities. Use `["text", "image"]` only when the model accepts native image input.
`contextWindow`	Records the model’s native context-window capacity.
`contextTokens`	Limits the active input budget without changing `contextWindow`.
`maxTokens`	Limits the output tokens that OpenClaw requests from the model.

Incorrect values can hide supported inputs, overstate the usable context, or request an unsupported output size. Keep your-model-id in reusable examples, and use the CometAPI Models page to select a model ID.

Verify the complete setup

After the config or global .env file changes, restart the Gateway:

openclaw gateway restart

Then validate the config and Gateway state:

openclaw config validate
openclaw doctor
openclaw health

Run the provider-specific commands from the selected API-format tab. A model list or status check confirms configuration only. The openclaw agent exec command sends a real model request. Confirm that it returns OPENCLAW_OK without an unresolved authentication, adapter, or model error. If OpenClaw retries a request, record and inspect every attempt instead of treating the final marker as single-attempt success.

Troubleshooting

The API key is missing

Confirm that COMETAPI_KEY is present in the process environment or the global state .env file. Do not print the value into terminal output.After you correct the trusted key source, restart and check the Gateway:

openclaw gateway restart
openclaw health

A provider ID has different settings

Do not overwrite a provider that has a different baseUrl, api, custom headers, or model metadata. Inspect the target provider first:

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

Use a different provider ID when both configurations are intentional. If the difference is accidental, create a verified backup before you change the target provider.

An update did not finish

Inspect update state before you repair the installation:

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

These commands preserve the state directory.

A code rollback is required

Reinstall a known package version while you keep the state directory. First, preview the operation:

openclaw update --tag 2026.8.1 --dry-run

If the preview is correct, run the same operation without --dry-run:

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

Restore a state backup only when the installed code cannot read the state. A state restore can discard sessions and configuration changes that were created after the backup.

Overview

AI coding agents

AI agents

AI chat clients

Translation and language

Automation platforms

Observability and evaluation

AI frameworks

Prerequisites

Installation and upgrades

Configure CometAPI

Use classic onboarding

Configure a provider with config commands

Understand model metadata

Verify the complete setup

Troubleshooting

​Prerequisites

​Installation and upgrades

​Configure CometAPI

​Use classic onboarding

​Configure a provider with config commands

​Understand model metadata

​Verify the complete setup

​Troubleshooting

Prerequisites

Installation and upgrades

Configure CometAPI

Use classic onboarding

Configure a provider with config commands

Understand model metadata

Verify the complete setup

Troubleshooting