> ## 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 OpenCode with CometAPI

> Use this guide to configure four CometAPI API formats as custom providers in OpenCode.

Use this guide to run [OpenCode](https://opencode.ai/docs/) with CometAPI.
The configuration exposes four API formats through separate custom providers.

This configuration was tested with OpenCode 1.18.16.

Official references:

* [OpenCode installation](https://opencode.ai/docs/#install)
* [OpenCode configuration](https://opencode.ai/docs/config/)
* [OpenCode custom providers](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode model selection](https://opencode.ai/docs/models/)
* [OpenCode permissions](https://opencode.ai/docs/permissions/)

<Note>
  Replace each `your-model-id` value with a model ID from the
  [CometAPI Models page](/overview/models). Choose a model that accepts the API
  format of the surrounding provider entry.
</Note>

## Prerequisites

* Node.js and npm, or another installation method from the OpenCode guide
* A CometAPI account with an active API key from the
  [dashboard](https://www.cometapi.com/console/token)
* One or more model IDs from the [CometAPI Models page](/overview/models)

## Understand the API formats

Each provider ID selects one SDK adapter and one API format.

| Provider ID          | OpenCode adapter            | Base URL                          | API format             |
| -------------------- | --------------------------- | --------------------------------- | ---------------------- |
| `cometapi-chat`      | `@ai-sdk/openai-compatible` | `https://api.cometapi.com/v1`     | Chat Completions       |
| `cometapi-responses` | `@ai-sdk/openai`            | `https://api.cometapi.com/v1`     | Responses              |
| `cometapi-messages`  | `@ai-sdk/anthropic`         | `https://api.cometapi.com/v1`     | Anthropic Messages     |
| `cometapi-gemini`    | `@ai-sdk/google`            | `https://api.cometapi.com/v1beta` | Gemini generateContent |

This guide verifies the Gemini streaming operation used during a normal
OpenCode agent turn. The Google adapter appends
`:streamGenerateContent?alt=sse` to the model path.

Do not add `/chat/completions`, `/responses`, `/messages`, or a Gemini model
path to `baseURL`. Each adapter appends its required operation path.

## Understand runtime permissions

OpenCode runs with the permissions of the process that launches it. Start
OpenCode in the intended project directory and keep a rollback path such as
git. Use a container or sandbox when you need stronger filesystem, process,
network, or API key boundaries.

## Configure OpenCode

<Steps>
  <Step title="Install OpenCode">
    Install OpenCode with the official npm package:

    ```bash theme={null}
    npm install -g opencode-ai
    ```

    Confirm that the CLI is available:

    ```bash theme={null}
    opencode --version
    ```

    See the [OpenCode installation guide](https://opencode.ai/docs/#install)
    for Homebrew, Windows, Docker, and other installation methods.
  </Step>

  <Step title="Set your CometAPI API key">
    Store your CometAPI API key in the `COMETAPI_KEY` environment variable.

    <Tabs>
      <Tab title="macOS / Linux / WSL">
        Read the API key without displaying it in the terminal:

        ```bash theme={null}
        read -rsp "CometAPI API key: " COMETAPI_KEY
        printf '\n'
        export COMETAPI_KEY
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        Read the API key into the current PowerShell session:

        ```powershell theme={null}
        $secureKey = Read-Host "CometAPI API key" -AsSecureString
        $env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
          "",
          $secureKey
        ).Password
        ```
      </Tab>
    </Tabs>

    Set the variable in every shell session that launches OpenCode. Do not
    commit API keys to version control.
  </Step>

  <Step title="Choose a configuration location">
    Use one of these supported locations:

    * Global configuration: `~/.config/opencode/opencode.json`
    * Project configuration: `opencode.json` in the project root

    OpenCode merges configuration files. A project configuration overrides
    conflicting values from the global configuration.

    Use the global file when you want the providers in every project. Use the
    project file when a repository needs its own model entries.
  </Step>

  <Step title="Add the CometAPI providers">
    Create the selected configuration file. If the file already contains a
    `provider` object, merge these four entries into that object:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "cometapi-chat": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "CometAPI Chat Completions",
          "options": {
            "baseURL": "https://api.cometapi.com/v1",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Chat model"
            }
          }
        },
        "cometapi-responses": {
          "npm": "@ai-sdk/openai",
          "name": "CometAPI Responses",
          "options": {
            "baseURL": "https://api.cometapi.com/v1",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Responses model"
            }
          }
        },
        "cometapi-messages": {
          "npm": "@ai-sdk/anthropic",
          "name": "CometAPI Anthropic Messages",
          "options": {
            "baseURL": "https://api.cometapi.com/v1",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Messages model"
            }
          }
        },
        "cometapi-gemini": {
          "npm": "@ai-sdk/google",
          "name": "CometAPI Gemini",
          "options": {
            "baseURL": "https://api.cometapi.com/v1beta",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Gemini model"
            }
          }
        }
      }
    }
    ```

    Replace each `your-model-id` key independently. The four entries can use
    different model IDs.

    The configuration does not set a top-level `model`. This lets you choose
    the required API format and model through `/models`.

    <Warning>
      Do not use `/connect` for this configuration. The `apiKey` fields read
      `COMETAPI_KEY` from the environment. An unset variable resolves to an
      empty value instead of a stored `/connect` API key.
    </Warning>
  </Step>

  <Step title="Select and verify each provider">
    Start OpenCode in the project that you want it to access:

    ```bash theme={null}
    opencode
    ```

    Run `/models`, then select a `provider/model` entry. In the four verification
    runs for this guide, each model turn used the selected entry's matching API
    format. No cross-format request fan-out or automatic API format negotiation
    was observed.

    To verify Chat Completions from the command line, run:

    ```bash theme={null}
    opencode run \
      --model cometapi-chat/your-model-id \
      "Reply exactly with: COMETAPI_CHAT_OK"
    ```

    To verify Responses from the command line, run:

    ```bash theme={null}
    opencode run \
      --model cometapi-responses/your-model-id \
      "Reply exactly with: COMETAPI_RESPONSES_OK"
    ```

    To verify Anthropic Messages from the command line, run:

    ```bash theme={null}
    opencode run \
      --model cometapi-messages/your-model-id \
      "Reply exactly with: COMETAPI_MESSAGES_OK"
    ```

    To verify Gemini generateContent from the command line, run:

    ```bash theme={null}
    opencode run \
      --model cometapi-gemini/your-model-id \
      "Reply exactly with: COMETAPI_GEMINI_OK"
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="OpenCode does not show a CometAPI model">
    Confirm that the configuration is valid JSON. Each custom entry must be
    inside the top-level `provider` object, and each model ID must be inside
    the matching `models` object. Restart OpenCode, then open `/models` again.
  </Accordion>

  <Accordion title="OpenCode reports an API key or authentication error">
    Confirm that `COMETAPI_KEY` is set in the shell that launches OpenCode.
    An unset `{env:COMETAPI_KEY}` reference becomes an empty value. Open a new
    shell after changing a shell profile.
  </Accordion>

  <Accordion title="A model ID is unavailable">
    Check the [CometAPI Models page](/overview/models), then replace the model
    ID inside the selected provider entry. Confirm that the model accepts that
    provider's API format.
  </Accordion>

  <Accordion title="Requests use an incorrect path">
    Keep `baseURL` at `/v1` for Chat Completions, Responses, and Messages. Use
    `/v1beta` for Gemini. Do not include an operation path in `baseURL`.
  </Accordion>

  <Accordion title="One provider works but another provider fails">
    Use a model ID that accepts the selected provider's API format. Do not
    assume that one model ID accepts all four formats.
  </Accordion>

  <Accordion title="The project configuration changes a global provider">
    OpenCode merges global and project configuration. Rename the project
    provider ID or remove its conflicting values when you want the global
    provider entry to remain unchanged.
  </Accordion>

  <Accordion title="OpenCode has more access than expected">
    OpenCode uses the permissions of the process that launched it. Run OpenCode
    in a container or sandbox when you need stronger access boundaries.
  </Accordion>
</AccordionGroup>

## Related resources

* [CometAPI quick start](/overview/quick-start)
* [CometAPI Models page](/overview/models)
* [OpenCode custom providers](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode configuration](https://opencode.ai/docs/config/)
* [OpenCode model selection](https://opencode.ai/docs/models/)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/opencode#howto",
        "name": "Use OpenCode with CometAPI",
        "description": "Use this guide to configure four CometAPI API formats as custom providers in OpenCode.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-1",
            "position": 1,
            "name": "Install OpenCode",
            "text": "Install OpenCode and confirm that the CLI is available."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-2",
            "position": 2,
            "name": "Set your CometAPI API key",
            "text": "Store your CometAPI API key in the COMETAPI_KEY environment variable."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-3",
            "position": 3,
            "name": "Choose a configuration location",
            "text": "Choose the global OpenCode configuration or a project configuration."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-4",
            "position": 4,
            "name": "Add the CometAPI providers",
            "text": "Add four CometAPI custom provider entries to opencode.json."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-5",
            "position": 5,
            "name": "Select and verify each provider",
            "text": "Select and verify the required CometAPI provider and model."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "CometAPI Docs",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrations",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Use OpenCode with CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/opencode"
          }
        ]
      }
    ]
    }
    `}
</script>