> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Use OpenClaw with CometAPI > Use this guide to configure OpenClaw with CometAPI through Chat Completions, Responses, Anthropic Messages, or Google Generative AI. Use this guide to connect [OpenClaw](https://openclaw.ai) 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](https://openclaw.ai/blog/openclaw-2-accidentally) and the [v2026.8.1 release notes](https://docs.openclaw.ai/releases/2026.8.1). Official OpenClaw references: * [Installation](https://docs.openclaw.ai/install) * [Updating](https://docs.openclaw.ai/install/updating) * [Onboarding](https://docs.openclaw.ai/start/onboarding-overview) * [Custom provider configuration](https://docs.openclaw.ai/gateway/config-tools) * [Environment variables and SecretRef](https://docs.openclaw.ai/help/environment) ## 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](https://www.cometapi.com/console/token). * A model ID from the [CometAPI Models page](/overview/models). ## Installation and upgrades The official installer can install the CLI without starting onboarding. This keeps model configuration as a separate step. The following command runs the official installer: ```bash theme={null} curl -fsSL https://openclaw.ai/install.sh \ | bash -s -- --no-onboard ``` The following command runs the official PowerShell installer: ```powershell theme={null} & ([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: ```bash theme={null} 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: ```bash theme={null} openclaw --version ``` Continue to [Configure CometAPI](#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: ```bash theme={null} mkdir -p ~/Backups/openclaw openclaw backup create --output ~/Backups/openclaw --verify openclaw update ``` After the update, repair supported migrations and check Gateway health: ```bash theme={null} 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: ```bash theme={null} 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](#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: ```bash theme={null} 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. The following commands update `COMETAPI_KEY` atomically and reject an empty value: ```bash theme={null} 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: ```powershell theme={null} $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: ```bash theme={null} 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. * 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: ```json5 theme={null} { 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: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 --dry-run ``` If validation succeeds, apply the same patch: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 ``` If no primary model is configured, set this model as the default: ```bash theme={null} openclaw models set cometapi-openai/your-model-id ``` Verify the provider configuration and send a minimal model request: ```bash theme={null} 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: ```text theme={null} /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: ```json5 theme={null} { 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: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 --dry-run ``` If validation succeeds, apply the same patch: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 ``` If no primary model is configured, set this model as the default: ```bash theme={null} openclaw models set cometapi-openai-responses/your-model-id ``` Verify the provider configuration and send a minimal model request: ```bash theme={null} 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: ```text theme={null} /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: ```json5 theme={null} { 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: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 --dry-run ``` If validation succeeds, apply the same patch: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 ``` If no primary model is configured, set this model as the default: ```bash theme={null} openclaw models set cometapi-claude/your-model-id ``` Verify the provider configuration and send a minimal model request: ```bash theme={null} 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: ```text theme={null} /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: ```json5 theme={null} { 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: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 --dry-run ``` If validation succeeds, apply the same patch: ```bash theme={null} openclaw config patch --file ./cometapi.patch.json5 ``` If no primary model is configured, set this model as the default: ```bash theme={null} openclaw models set cometapi-google/your-model-id ``` Verify the provider configuration and send a minimal model request: ```bash theme={null} 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: ```text theme={null} /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: ```bash theme={null} 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](/overview/models) to select a model ID. ## Verify the complete setup After the config or global `.env` file changes, restart the Gateway: ```bash theme={null} openclaw gateway restart ``` Then validate the config and Gateway state: ```bash theme={null} 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 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: ```bash theme={null} openclaw gateway restart openclaw health ``` Do not overwrite a provider that has a different `baseUrl`, `api`, custom headers, or model metadata. Inspect the target provider first: ```bash theme={null} 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. Inspect update state before you repair the installation: ```bash theme={null} openclaw update status --json openclaw update repair openclaw doctor --fix openclaw health ``` These commands preserve the state directory. Reinstall a known package version while you keep the state directory. First, preview the operation: ```bash theme={null} openclaw update --tag 2026.8.1 --dry-run ``` If the preview is correct, run the same operation without `--dry-run`: ```bash theme={null} 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.