Connect OpenCode to CometAPI with a Custom Provider

Last reviewed: September 11, 2026

Direct answer

Connect OpenCode to CometAPI by registering a custom provider ID, storing the credential through OpenCode’s /connect flow, and adding a matching provider block to opencode.json. For the Chat Completions route covered here, set the provider package to @ai-sdk/openai-compatible, use CometAPI’s documented v1 base URL, and declare a current CometAPI model ID under provider.cometapi.models.

The provider ID is the join between the stored credential and the configuration. If you enter cometapi during /connect, the configuration key must also be cometapi. OpenCode then identifies a selected model as provider_id/model_id, such as cometapi/MODEL_ID_FROM_CURRENT_CATALOG after the placeholder is replaced.

This approach follows OpenCode’s provider documentation , its model-selection contract , and the OpenAI-compatible base URL documented in the CometAPI API documentation . Test basic text generation first, then run a read-only tool-use check; a text response alone does not prove that the selected model is suitable for coding-agent tool calls.

Who this is for

This guide is for developers who already have OpenCode available locally and want to route its model requests through CometAPI. You should have access to a CometAPI credential and be able to choose a current text model from the CometAPI model catalog.

The workflow is also useful to operators reviewing a team configuration. It makes the provider ID, endpoint family, base URL, and model ID explicit, while keeping the credential out of a project file and its version-control history.

This guide deliberately targets an OpenAI-compatible Chat Completions provider. It does not assume that every CometAPI model supports tool calling, structured output, images, or the Responses endpoint. Those capabilities remain model- and endpoint-dependent, as the AI SDK OpenAI-compatible provider guide explains.

Key takeaways

Use one stable provider ID—cometapi—in both /connect and opencode.json.
Keep the credential in OpenCode’s credential store rather than writing a literal value into the project configuration.
Use @ai-sdk/openai-compatible for the Chat Completions path covered by this tutorial.
Copy an exact, current model ID; do not substitute a marketing name or an old alias.
Verify connectivity and read-only tool use as separate acceptance checks.
Log only operational metadata. Exclude credentials, authentication headers, prompts, response content, and credential-store contents.

Sources checked

The OpenCode provider guide documents /connect, provider configuration, custom base URLs, model maps, and the OpenAI-compatible provider package.
The OpenCode model guide documents /models, the provider_id/model_id format, default-model configuration, and model-loading priority.
The CometAPI documentation identifies the v1 base URL, OpenAI-compatible Chat Completions format, model-listing resources, and separate guidance for errors and rate limits.
The Vercel AI SDK provider documentation confirms that @ai-sdk/openai-compatible accepts a base URL and model ID while noting that capabilities such as tool calling and multimodal input depend on the provider and model.

Together, these sources establish the configuration contract. They do not establish that every catalog entry is appropriate for OpenCode. Check the selected model’s current capabilities before relying on it for repository tools or production work.

Contract details to verify

1. Choose and preserve one provider ID

OpenCode stores a credential against a provider ID and loads provider configuration under the same ID. Use cometapi in both places. A difference in spelling, case, or punctuation creates two unrelated identities from OpenCode’s perspective.

Run the connection flow from the OpenCode interface and select the custom-provider option labeled Other:

/connect
provider: Other
provider id: cometapi
API key: [REDACTED]

OpenCode documents that credentials added through /connect are stored in its per-user authentication file. Do not print, copy, or commit that file. For a broader repository boundary, follow the same practices described in keeping CometAPI keys out of tutorial repositories .

2. Verify the endpoint family and base URL

This configuration uses Chat Completions. The OpenCode provider package is therefore @ai-sdk/openai-compatible. Set baseURL to the v1 endpoint published in the CometAPI documentation .

Do not append a specific operation such as a chat-completions path to baseURL; the adapter constructs the operation path. Likewise, do not remove the v1 segment. If you later move to a different endpoint family, recheck the OpenCode provider-package guidance and the CometAPI endpoint documentation together instead of assuming the adapter is interchangeable.

3. Add an exact current model ID

Choose a text model that is currently present in CometAPI’s catalog and appropriate for coding. Copy its machine-readable ID exactly into both places represented by MODEL_ID_FROM_CURRENT_CATALOG below. A display name is not a safe substitute for the model ID.

If model availability may have changed since an earlier setup, use the model-catalog validation workflow before editing the file.

Create opencode.json in the project directory:

{
  "provider": {
    "cometapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CometAPI",
      "options": {
        "baseURL": "COMETAPI_V1_BASE_URL"
      },
      "models": {
        "MODEL_ID_FROM_CURRENT_CATALOG": {
          "name": "CometAPI verified model"
        }
      }
    }
  },
  "model": "cometapi/MODEL_ID_FROM_CURRENT_CATALOG"
}

Before launching OpenCode, replace COMETAPI_V1_BASE_URL with the v1 base URL from the linked CometAPI documentation and replace both model placeholders with the same verified model ID. The top-level model field is optional, but including it makes the intended default explicit. OpenCode’s model guide defines the full value as the provider ID, a slash, and the configured model ID.

Do not add a literal credential to options. The /connect step already associates the stored credential with cometapi.

4. Run the happy-path operator workflow

Use a disposable or noncritical repository for the first check.

Start OpenCode from the directory containing the completed opencode.json.
Run the following read-only credential inventory command and confirm that cometapi appears. Do not capture credential-store contents.

opencode auth list

Open the model picker and confirm that the configured provider and model are visible.

/models

Select the model if it is not already the default. Confirm that the displayed identity combines cometapi with the exact configured model ID.
Send a minimal text prompt so failures are easy to interpret.

Reply with the single word READY.

If the text response succeeds, run a separate, read-only tool test in a disposable repository containing at least one known file.

Inspect the current directory, name one file, and do not modify anything.

Check the repository state with your normal version-control tooling. The test passes only if OpenCode identifies an existing file, returns without an unexpected error, and leaves the working tree unchanged.

This sequence distinguishes three different outcomes: provider configuration loaded, text generation worked, and the selected model handled a simple tool-oriented task. Record each outcome separately rather than collapsing them into one “connected” result.

5. Record sanitized operational evidence

A useful success record contains enough context to reproduce the configuration decision without retaining user content or authentication material. For example:

{
  "timestamp": "2026-09-11T00:00:00Z",
  "operation": "opencode_connectivity_smoke_test",
  "provider_id": "cometapi",
  "model_id": "MODEL_ID_FROM_CURRENT_CATALOG",
  "base_url_label": "cometapi_v1",
  "endpoint_family": "chat_completions",
  "outcome": "success",
  "duration_ms": 0,
  "error_type": null,
  "service_request_id": "[REDACTED]",
  "retry_count": 0
}

Populate only fields actually observed. If OpenCode does not expose a service request ID or duration, use null instead of inventing a value. Safe fields include the timestamp, OpenCode version, operation name, provider ID, model ID, nonsecret base-URL label, endpoint family, outcome, duration, error category, retry count, and a redacted service request ID when one exists.

Do not log the credential, authentication headers, credential file, prompt, response body, source-code excerpts, environment dumps, or full error payloads that might echo request content.

6. Follow a bounded error path

When the first request fails, stop before repeatedly retrying it.

Record the time, provider ID, model ID, endpoint family, and high-level error category.
Run opencode auth list and verify that the stored provider ID is exactly cometapi.
Validate that opencode.json is valid JSON and that its provider key is also cometapi.
Compare baseURL with the documented CometAPI v1 base URL, including its version segment.
Recheck the model ID against the current catalog and confirm that it is intended for text generation.
Confirm that the configured package matches the Chat Completions endpoint family.
Retry once only when the failure appears temporary. Do not use repeated retries to mask a deterministic configuration error.
If the retry fails, preserve a sanitized error category and any redacted service request identifier, then consult the relevant official documentation or support channel.

This order tests local identity and configuration before attributing the problem to a model or remote service.

Failure modes

The provider does not appear in `/models`

The configuration may not have loaded, the JSON may be invalid, or the provider block may use a different ID from the one entered during /connect. Confirm that OpenCode is running in the intended project directory and that provider.cometapi exists. Then verify the credential inventory and reopen /models.

The provider appears, but the model does not

The model must be declared beneath provider.cometapi.models. Check that the placeholder was replaced and that the map key exactly matches a current CometAPI model ID. Also confirm that a display label was not pasted in place of the ID.

Authentication is rejected

The stored credential may be missing, stale, or associated with another provider ID. Re-run /connect, choose Other, and enter the same cometapi ID. Enter the credential interactively as [REDACTED]; do not paste it into logs, screenshots, shell history, or opencode.json.

The request reaches the wrong route

A base URL missing the v1 segment, a base URL containing an operation path, or an adapter chosen for another endpoint family can produce route or compatibility failures. Restore the documented base URL and confirm that this tutorial’s @ai-sdk/openai-compatible package is being used for Chat Completions.

Text works, but repository tools fail

Basic generation and tool calling are different capabilities. The OpenCode model guide specifically warns that relatively few models are strong at both coding and tool use, while the AI SDK documentation marks several capabilities as provider-dependent. Keep the successful text result, mark the tool test as failed, and evaluate a currently available coding model with documented tool support.

Requests become temporarily unavailable or limited

CometAPI publishes separate error and rate-limit guidance. Preserve the high-level error category and any safely redacted service request identifier. Apply only a bounded retry consistent with the returned guidance. Switching model IDs or endlessly retrying without first checking the contract makes the incident harder to diagnose.

A response succeeds but is not trustworthy evidence

A nonempty answer does not prove that OpenCode used the intended provider, selected the intended model, or left the repository unchanged. Pair the response with the visible provider/model identity, a sanitized operation record, and a version-control state check.

FAQ

Why use `cometapi` as the provider ID?

It is short, memorable, and clearly identifies the service. The exact text is not mandatory, but consistency is: the ID entered during /connect must match the provider key in opencode.json. If you choose another ID, replace it everywhere, including the default model’s provider_id/model_id value.

Can I put the CometAPI credential directly in `opencode.json`?

Do not put a literal credential in a project file. This workflow uses /connect so OpenCode stores it in its per-user authentication location. That keeps the secret outside the repository, although the local credential store still needs normal workstation protections.

Which CometAPI model should I configure?

Choose a current text model from CometAPI’s catalog and verify that its intended capabilities fit OpenCode. Avoid hard-coding a model from an old tutorial because IDs and availability can change. If tool use matters, test it separately after the text smoke test.

Why does the default model contain a slash?

OpenCode defines a complete model identity as provider_id/model_id. For a custom provider named cometapi, the prefix is therefore cometapi/, followed by the exact key declared under provider.cometapi.models.

Does a successful READY response prove the integration is complete?

It proves only that a minimal text request returned through the selected setup. It does not prove reliable tool calling, correct handling of large contexts, structured output, multimodal input, cost behavior, or production resilience. Add focused tests only for the capabilities your workflow will use.

Should I use the same configuration for the Responses endpoint?

Not without revalidation. This article intentionally pairs the OpenAI-compatible package with CometAPI’s Chat Completions path. OpenCode distinguishes endpoint families in its provider guidance. Check both products’ current documentation before changing the adapter or endpoint.

What should I include in a support report?

Include the timestamp, OpenCode version, provider ID, model ID, endpoint family, sanitized error category, retry count, and a redacted service request ID if available. Exclude credentials, authentication headers, prompts, response bodies, source code, and environment dumps.

Reader next step

Choose one current CometAPI text model, validate its exact ID, and complete the /connect plus opencode.json workflow in a disposable repository. Require four pieces of evidence before adopting it more broadly: the credential inventory lists cometapi, /models shows the expected full model identity, the minimal text prompt succeeds, and the read-only tool test leaves the repository unchanged.

Keep the resulting record small and sanitized. If you need a reusable evidence format, continue with local smoke-test evidence for CometAPI tutorial authors . If any check fails, follow the bounded error path above before changing models or adding retries.