Connect OpenClaw to CometAPI with Custom Model Providers

Last reviewed: August 4, 2026.

Direct answer

A CometAPI OpenClaw integration is not a single generic endpoint toggle. OpenClaw routes custom providers according to API shape, so each CometAPI route needs a provider ID, the matching API adapter, the correct base path, and at least one current model ID. The refetched CometAPI OpenClaw integration guide documents three mappings:

cometapi-openai uses openai-completions.
cometapi-claude uses anthropic-messages.
cometapi-google uses google-generative-ai.

Keep the credential outside the provider definitions. OpenClaw can substitute ${COMETAPI_KEY} when it loads ~/.openclaw/openclaw.json. Its environment variable reference recommends the Gateway process environment or the global ~/.openclaw/.env file for provider credentials. A workspace-level .env is not the right location because OpenClaw ignores provider credentials from that lower-trust source.

Start with this provider-only shape, then replace each BASE_URL_FROM_DOCS_* marker with the current HTTPS value represented by the host/path table later in this guide. It intentionally leaves the current primary model unchanged:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai": {
        baseUrl: "BASE_URL_FROM_DOCS_OPENAI",
        apiKey: "${COMETAPI_KEY}",
        api: "openai-completions",
        models: [{ id: "gpt-5.4", name: "GPT-5.4" }]
      },
      "cometapi-claude": {
        baseUrl: "BASE_URL_FROM_DOCS_CLAUDE",
        apiKey: "${COMETAPI_KEY}",
        api: "anthropic-messages",
        models: [{ id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" }]
      },
      "cometapi-google": {
        baseUrl: "BASE_URL_FROM_DOCS_GOOGLE",
        apiKey: "${COMETAPI_KEY}",
        api: "google-generative-ai",
        models: [{ id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro" }]
      }
    }
  }
}

This snippet deliberately omits agents.defaults.model.primary. Merge and validate the provider definitions first; step 8 changes the default only after a live probe succeeds.

Those model IDs are documented examples, not permanent availability promises. Verify them against the live provider documentation before deployment. Edit ~/.openclaw/openclaw.json, not a per-agent models.json file: the CometAPI guide says OpenClaw materializes custom providers into those per-agent files after loading the source configuration.

Who this is for

This guide is for developers or operators who run an OpenClaw Gateway and want to expose one or more CometAPI model families through OpenClaw’s normal provider/model selection flow. It assumes you can edit the Gateway’s configuration and trusted runtime environment, restart the service, and run OpenClaw diagnostics.

It is also useful when a setup appears partially healthy: the provider is listed, but authentication, model resolution, or a real probe still fails. If you are writing an agent directly instead of configuring OpenClaw, the LangGraph integration tutorial is a closer starting point. For repository hygiene around local examples, review how to keep CometAPI keys out of tutorial repositories .

Key takeaways

Provider IDs and model references are explicit. Use the full provider/model form, such as cometapi-claude/claude-sonnet-4-6.
Pair each API adapter with its documented base path. A correct hostname with the wrong adapter is still a broken contract.
Put COMETAPI_KEY in a trusted source visible to the Gateway process. Do not rely on a workspace .env file.
Adding or repairing provider authentication does not automatically replace the primary model. The OpenClaw provider reference says to use openclaw models set <provider/model> for an intentional default change.
openclaw models list is read-only and does not prove that inference works. A live probe or small real request is the execution check.
Model IDs, base paths, OpenClaw configuration keys, and command behavior can change. Recheck live documentation during upgrades and before a production rollout.

Sources checked

The CometAPI OpenClaw integration guide supplies the three API-shape mappings, example model IDs, source configuration path, restart sequence, and verification commands.
The CometAPI quick start confirms the OpenAI-compatible base path and recommends storing the credential in a server-side environment variable or local environment file.
The OpenClaw model-provider reference defines custom providers, provider/model references, model selection, and the difference between adding authentication and changing the primary model.
The OpenClaw environment variable reference documents source precedence, global environment loading, workspace restrictions, and ${VAR} substitution.
The OpenClaw models CLI reference documents status, list, set, JSON output, live probes, exit checks, and failure categories.

Contract details to verify

The provider map below reflects the refetched CometAPI integration guide. Use the HTTPS scheme with each documented host/path combination, and verify the values again before editing a live Gateway.

Provider ID	OpenClaw API adapter	CometAPI host/path	Example full model reference
`cometapi-openai`	`openai-completions`	`api.cometapi.com/v1`	`cometapi-openai/gpt-5.4`
`cometapi-claude`	`anthropic-messages`	`api.cometapi.com`	`cometapi-claude/claude-sonnet-4-6`
`cometapi-google`	`google-generative-ai`	`api.cometapi.com/v1beta`	`cometapi-google/gemini-3.1-pro-preview`

Before rollout, also validate the current CometAPI model catalog rather than assuming that an example ID is enabled for every account or remains unchanged.

Happy-path operator workflow

Run OpenClaw onboarding once and confirm that the Gateway starts before adding a custom provider.
Back up the source configuration. Do not edit a generated per-agent model file.
Store the real credential through a trusted secret workflow. If the global environment file is used, its relevant line should have this redacted shape, and the file should be readable only by the service owner:

COMETAPI_KEY=[REDACTED]

Merge the provider configuration into ~/.openclaw/openclaw.json without changing the current primary model. Add only the API families you intend to use, or add all three when you need all three formats.
Restart the Gateway after changing either the global environment file or provider configuration.
Check configuration, model resolution, and diagnostics before sending a real request.

openclaw onboard --install-daemon
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-cometapi
chmod 600 ~/.openclaw/.env
openclaw gateway restart
openclaw gateway status
openclaw models status --check
openclaw models list --provider cometapi-claude
openclaw doctor

Run one provider-scoped live probe. The CLI documentation warns that a probe makes a real request, may consume tokens, and can encounter rate limits.

openclaw models status --probe --probe-provider cometapi-claude

Set the intended default explicitly only after the probe succeeds.

openclaw models set cometapi-claude/claude-sonnet-4-6
openclaw models status --check

A healthy path has four separate signals: the Gateway is running, the provider-scoped list contains the configured model, the live probe reports ok, and openclaw doctor reports no configuration-schema or provider-authentication error. A successful list alone is insufficient because the CLI reference states that listing does not call provider APIs or prove execution readiness.

Sanitized logging record

Capture enough context to reproduce an incident without copying credentials, request headers, prompts, or model output. A small structured record can look like this:

{
  "timestamp": "2026-08-04T00:00:00Z",
  "operation": "model_probe",
  "provider_id": "cometapi-claude",
  "model_ref": "cometapi-claude/claude-sonnet-4-6",
  "gateway_state": "running",
  "outcome_category": "ok",
  "http_status": 200,
  "duration_ms": 420,
  "retry_count": 0,
  "credential_source": "global_env",
  "credential_present": true,
  "config_revision": "rev-3"
}

Record http_status only when the diagnostic surface exposes it. credential_present is a boolean check, never the credential value. Keep full headers, environment-file contents, raw prompts, response bodies, and copied configuration fragments out of routine logs.

Failure modes

OpenClaw’s models CLI groups live-probe failures into categories including auth, rate_limit, billing, timeout, format, unknown, and no_model. Treat the category as a routing clue, not a reason to change several settings at once.

Symptom	Likely boundary	Operator action
Gateway restart reports a schema error	Malformed configuration or unsupported fields	Restore the backup, validate the edited provider block, and reapply one provider at a time.
`missing_credential` or `unresolved_ref`	The Gateway cannot resolve the configured environment reference	Confirm the secret is in the process environment or global OpenClaw environment file, check file ownership, restart, and probe again.
Provider list is empty or probe reports `no_model`	Provider ID, model ID, or materialized catalog does not match	Compare the configured ID with the live CometAPI guide, restart after corrections, then rerun the provider-scoped list.
Probe reports `auth`	The credential is absent, invalid, or not visible to the daemon	Reinstall the value through the approved secret channel, restart the Gateway, and retry once without printing the value.
Probe reports `rate_limit`	The provider accepted authentication but rejected current request volume or quota	Stop rapid retries, reduce concurrency, wait according to the applicable service policy, and retry a bounded probe.
Probe reports `billing`	The provider route cannot serve the request under the current account state	Check the account state through the normal administrative path before retrying. Do not treat it as a model-format problem.
Probe reports `timeout`	Network reachability, endpoint selection, or upstream latency	Verify the documented base path, local DNS and egress, then run one timed probe rather than an open retry loop.
Probe reports `format`	API adapter and endpoint family do not agree, or the model rejects the request shape	Recheck the provider’s `api` value, base path, and model family as one contract.
Authentication was added but the old default remains	Expected model-selection behavior	Run `openclaw models set` with the complete provider/model reference after its live probe succeeds.

Error-path operator workflow

Stop automated retries when the same auth, format, or no_model result repeats.
Capture the sanitized fields above plus openclaw models status --json. Keep diagnostic standard error separate if another tool parses standard output.
Compare provider ID, API adapter, base host/path, and model ID with the current documentation.
Check environment precedence. A variable already present in the Gateway process takes priority, while the global environment file only fills a missing value.
Restart once after a configuration or environment correction.
Run the provider-scoped list, followed by one bounded live probe.
If the failure persists, share only the sanitized category, timestamps, provider/model reference, Gateway version, and non-sensitive diagnostic output. The guide to triaging CometAPI error bodies provides a safer boundary for escalation notes.

This sequence separates discovery, authentication, request format, and live execution. It also prevents a common mistake: changing the model, endpoint, credential source, and default selection simultaneously, then losing track of which change affected the result.

FAQ

Do I need all three custom providers?

No. Configure only the API formats your OpenClaw deployment will use. Keep separate provider blocks when you need OpenAI-compatible, Anthropic Messages, and Gemini-native formats because OpenClaw routes them by API compatibility rather than vendor name alone.

Where should `COMETAPI_KEY` live?

Use the Gateway process environment, a service or container secret, or the global ~/.openclaw/.env file. The OpenClaw environment reference marks the global file as a recommended provider-credential source and says workspace .env files do not supply provider credentials.

Does `openclaw models list` prove the integration works?

No. It is a read-only catalog and configuration view. It does not load the provider runtime, call the provider API, or prove exact execution readiness. Use a bounded live probe and then a small real request.

Why did adding authentication not change my primary model?

That is expected. OpenClaw preserves an existing primary when authentication is added or refreshed. Use openclaw models set <provider/model> after a successful probe when you intentionally want a new default.

Should I edit the per-agent `models.json` file?

Use ~/.openclaw/openclaw.json as the source configuration. The CometAPI integration guide says OpenClaw materializes custom providers into per-agent model files after loading or synchronization, so direct edits to generated files are not the durable configuration path.

Can I keep using the model IDs in this example indefinitely?

Treat them as documented examples. Model availability and identifiers can change. Verify the current catalog and provider guide during upgrades and immediately before deployment.

Reader next step

Use the CometAPI provider contract cited in Sources checked beside the OpenClaw models CLI reference . Back up openclaw.json, configure one provider family without changing the current default, restart once, and require all four healthy signals before switching models or adding another family.

Before promoting the configuration, use the tracked checklist to verify the CometAPI base URL before deployment . Preserve the sanitized success record with the deployment notes so the next operator can distinguish a known-good contract from later model, environment, or configuration drift.