OpenCode

O OpenCode é uma ferramenta de programação com IA de código aberto que funciona no terminal. Pode ligá-lo à HiAPI com uma importação do CC Switch ou editando o ficheiro de configuração manualmente; escolha uma das duas. Os passos abaixo usam deepseek-v4.1-flash como exemplo; a HiAPI usa o protocolo OpenAI Chat Completions. Este tutorial foi verificado no Windows 11 com o OpenCode 1.19.4. Prepare uma HiAPI API key antes de começar; se importar com o CC Switch, instale primeiro uma versão que suporte o OpenCode como descrito em Instalação e importação com um clique do CC Switch.

1. Instalar o OpenCode

No Mac / Linux, execute isto num terminal:

curl -fsSL https://opencode.ai/install | bash

Se já tiver o Node.js (veja Configuração do Node.js), também pode instalar com o npm. No Windows, use o script de instalação acima dentro do WSL ou execute isto num terminal local:

npm install -g opencode-ai

Depois de instalar, volte a abrir o terminal e verifique a versão:

opencode --version

Ver o número de versão é suficiente.

2. Configurar a HiAPI

Opção 1: importação com um clique pelo CC Switch

1. Abra a página de ligação do OpenCode da HiAPI, escolha o modelo e a HiAPI API key e clique em Prepare import.

2. Na janela «Confirm provider import» do CC Switch, verifique os itens abaixo e clique em Import:

Opção 2: editar o ficheiro de configuração manualmente

Abra o ficheiro de configuração global ~/.config/opencode/opencode.json e adicione um fornecedor HiAPI (protocolo OpenAI Chat Completions). Crie o ficheiro se não existir; se já tiver outra configuração, apenas funda os campos provider.hiapi e model abaixo. Defina o Base URL como https://api.hiapi.ai/v1, sem acrescentar /chat/completions.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hiapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HiAPI",
      "options": {
        "baseURL": "https://api.hiapi.ai/v1",
        "apiKey": "{env:HIAPI_API_KEY}"
      },
      "models": {
        "deepseek-v4.1-flash": {
          "name": "DeepSeek V4.1 Flash"
        },
        "claude-opus-5-5": {
          "name": "Claude Opus 5.5"
        }
      }
    }
  },
  "model": "hiapi/deepseek-v4.1-flash"
}

{env:HIAPI_API_KEY} é a forma como o OpenCode lê uma variável de ambiente; deixe como está. Depois defina essa variável no terminal, substituindo YOUR_HIAPI_API_KEY pela sua HiAPI API key e mantendo as aspas:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

$env:HIAPI_API_KEY = "YOUR_HIAPI_API_KEY"

A variável de ambiente só se aplica ao terminal atual, por isso inicie o OpenCode no mesmo terminal depois de a definir; se voltar a abrir o terminal, defina-a novamente, ou acrescente-a ao ficheiro de arranque da shell (como ~/.zshrc) para a tornar permanente.

O exemplo define hiapi/deepseek-v4.1-flash como modelo predefinido. Para mudar de modelo, altere tanto a definição do modelo em provider.hiapi.models como o campo model.

3. Verificar

Vá para o diretório do seu projeto e inicie o OpenCode no terminal onde definiu a variável de ambiente:

opencode

Escreva /models e escolha um modelo no fornecedor HiAPI, por exemplo deepseek-v4.1-flash. Envie «Olá, apresente-se numa frase.». Uma resposta normal significa que a ligação funciona.

O nome do fornecedor pode variar entre os dois métodos de importação; basta verificar o fornecedor selecionado, o nome do modelo e o Base URL. Também pode confirmar nos Registos de pedidos da consola da HiAPI que os pedidos passam pela HiAPI.

4. Resolução de problemas

Aqui só estão listados problemas específicos do OpenCode. Para erros comuns como 401, 404 e 429, consulte Erros comuns.