> ## 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 o OpenCode com a CometAPI

> Use este guia para configurar quatro formatos de API da CometAPI como provedores personalizados no OpenCode.

Use este guia para executar [o OpenCode](https://opencode.ai/docs/) com a CometAPI.
A configuração expõe quatro formatos de API por meio de provedores personalizados separados.

Esta configuração foi testada com o OpenCode 1.18.16.

Referências oficiais:

* [Instalação do OpenCode](https://opencode.ai/docs/#install)
* [Configuração do OpenCode](https://opencode.ai/docs/config/)
* [Provedores personalizados do OpenCode](https://opencode.ai/docs/providers/#custom-provider)
* [Seleção de modelos no OpenCode](https://opencode.ai/docs/models/)
* [Permissões do OpenCode](https://opencode.ai/docs/permissions/)

<Note>
  Substitua cada valor `your-model-id` por um ID de modelo da
  [página de modelos da CometAPI](/pt/overview/models). Escolha um modelo que aceite o formato de API
  da entrada de provedor ao redor.
</Note>

## Pré-requisitos

* Node.js e npm, ou outro método de instalação do guia do OpenCode
* Uma conta da CometAPI com uma chave de API ativa do
  [painel](https://www.cometapi.com/console/token)
* Um ou mais IDs de modelo da [página de modelos da CometAPI](/pt/overview/models)

## Entenda os formatos de API

Cada ID de provedor seleciona um adaptador de SDK e um formato de API.

| ID do provedor       | Adaptador do OpenCode       | URL base                          | Formato de API         |
| -------------------- | --------------------------- | --------------------------------- | ---------------------- |
| `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 |

Este guia verifica a operação de Streaming do Gemini usada durante um turno normal do
agente do OpenCode. O adaptador do Google acrescenta
`:streamGenerateContent?alt=sse` ao caminho do modelo.

Não adicione `/chat/completions`, `/responses`, `/messages`, nem um caminho de modelo do Gemini
a `baseURL`. Cada adaptador acrescenta o caminho de operação necessário.

## Entenda as permissões em tempo de execução

O OpenCode é executado com as permissões do processo que o inicia. Inicie
o OpenCode no diretório de projeto pretendido e mantenha um caminho de reversão, como
git. Use um contêiner ou sandbox quando precisar de limites mais rigorosos para sistema de arquivos, processos,
rede ou chaves de API.

## Configurar o OpenCode

<Steps>
  <Step title="Instalar o OpenCode">
    Instale o OpenCode usando o pacote oficial do npm:

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

    Confirme que a CLI está disponível:

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

    Consulte o [guia de instalação do OpenCode](https://opencode.ai/docs/#install)
    para Homebrew, Windows, Docker e outros métodos de instalação.
  </Step>

  <Step title="Definir sua chave de API da CometAPI">
    Armazene sua chave de API da CometAPI na variável de ambiente `COMETAPI_KEY`.

    <Tabs>
      <Tab title="macOS / Linux / WSL">
        Leia a chave de API sem exibi-la no terminal:

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

      <Tab title="Windows PowerShell">
        Leia a chave de API na sessão atual do PowerShell:

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

    Defina a variável em todas as sessões do shell que iniciam o OpenCode. Não
    faça commit de chaves de API no controle de versão.
  </Step>

  <Step title="Escolher um local de configuração">
    Use um destes locais compatíveis:

    * Configuração global: `~/.config/opencode/opencode.json`
    * Configuração do projeto: `opencode.json` na raiz do projeto

    O OpenCode mescla os arquivos de configuração. Uma configuração do projeto substitui
    valores conflitantes da configuração global.

    Use o arquivo global quando quiser os provedores em todos os projetos. Use o
    arquivo do projeto quando um repositório precisar de suas próprias entradas de modelo.
  </Step>

  <Step title="Adicionar os provedores da CometAPI">
    Crie o arquivo de configuração selecionado. Se o arquivo já contiver um
    `provider` objeto, mescle estas quatro entradas nesse objeto:

    ```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"
            }
          }
        }
      }
    }
    ```

    Substitua cada chave `your-model-id` individualmente. As quatro entradas podem usar
    IDs de modelo diferentes.

    A configuração não define um `model` de nível superior. Isso permite escolher
    o formato de API necessário e o modelo por meio de `/models`.

    <Warning>
      Não use `/connect` para esta configuração. Os campos `apiKey` leem
      `COMETAPI_KEY` do ambiente. Uma variável não definida é resolvida como um
      valor vazio em vez de uma chave de API `/connect` armazenada.
    </Warning>
  </Step>

  <Step title="Selecionar e verificar cada provedor">
    Inicie o OpenCode no projeto ao qual você quer que ele tenha acesso:

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

    Execute `/models` e selecione uma entrada `provider/model`. Nas quatro verificações
    realizadas para este guia, cada rodada do modelo usou o formato de API correspondente à entrada
    selecionada. Não foi observada nenhuma distribuição de solicitações entre formatos nem negociação automática do formato de API
    .

    Para verificar Chat Completions na linha de comando, execute:

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

    Para verificar Responses na linha de comando, execute:

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

    Para verificar Anthropic Messages na linha de comando, execute:

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

    Para verificar Gemini generateContent na linha de comando, execute:

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

## Solução de problemas

<AccordionGroup>
  <Accordion title="O OpenCode não exibe um modelo da CometAPI">
    Confirme se a configuração é um JSON válido. Cada entrada personalizada deve estar
    dentro do objeto `provider` de nível superior, e cada ID de modelo deve estar dentro
    do objeto `models` correspondente. Reinicie o OpenCode e abra `/models` novamente.
  </Accordion>

  <Accordion title="O OpenCode informa um erro de chave de API ou autenticação">
    Confirme se `COMETAPI_KEY` está definido no shell que inicia o OpenCode.
    Uma referência `{env:COMETAPI_KEY}` não definida se torna um valor vazio. Abra um novo
    shell depois de alterar um perfil de shell.
  </Accordion>

  <Accordion title="Um ID de modelo está indisponível">
    Confira a [página CometAPI Models](/pt/overview/models), depois substitua o modelo
    ID dentro da entrada do provedor selecionado. Confirme se o modelo aceita esse formato de API do
    provedor.
  </Accordion>

  <Accordion title="As solicitações usam um caminho incorreto">
    Mantenha `baseURL` em `/v1` para Chat Completions, Responses e Messages. Use
    `/v1beta` para Gemini. Não inclua um caminho de operação em `baseURL`.
  </Accordion>

  <Accordion title="Um provedor funciona, mas outro falha">
    Use um ID de modelo que aceite o formato de API do provedor selecionado. Não
    presuma que um ID de modelo aceite os quatro formatos.
  </Accordion>

  <Accordion title="A configuração do projeto altera um provedor global">
    O OpenCode mescla a configuração global e a do projeto. Renomeie o ID do provedor do projeto
    ou remova os valores conflitantes quando quiser que a entrada do provedor global
    permaneça inalterada.
  </Accordion>

  <Accordion title="O OpenCode tem mais acesso do que o esperado">
    O OpenCode usa as permissões do processo que o iniciou. Execute o OpenCode
    em um contêiner ou sandbox quando precisar de limites de acesso mais rigorosos.
  </Accordion>
</AccordionGroup>

## Recursos relacionados

* [Início rápido do CometAPI](/pt/overview/quick-start)
* [Página de modelos do CometAPI](/pt/overview/models)
* [Provedores personalizados do OpenCode](https://opencode.ai/docs/providers/#custom-provider)
* [Configuração do OpenCode](https://opencode.ai/docs/config/)
* [Seleção de modelos do OpenCode](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": "Usar o OpenCode com o CometAPI",
        "description": "Use este guia para configurar quatro formatos de API do CometAPI como provedores personalizados no OpenCode.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-1",
            "position": 1,
            "name": "Instalar o OpenCode",
            "text": "Instale o OpenCode e confirme que a CLI está disponível."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-2",
            "position": 2,
            "name": "Definir sua chave de API do CometAPI",
            "text": "Armazene sua chave de API do CometAPI na variável de ambiente COMETAPI_KEY."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-3",
            "position": 3,
            "name": "Escolher um local de configuração",
            "text": "Escolha a configuração global do OpenCode ou uma configuração do projeto."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-4",
            "position": 4,
            "name": "Adicionar os provedores do CometAPI",
            "text": "Adicione quatro entradas de provedores personalizados do CometAPI a opencode.json."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-5",
            "position": 5,
            "name": "Selecionar e verificar cada provedor",
            "text": "Selecione e verifique o provedor e o modelo do CometAPI necessários."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Documentação do CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrações",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Usar o OpenCode com o CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/opencode"
          }
        ]
      }
    ]
    }
    `}
</script>