Instalação e importação com um clique do CC Switch

O Claude Code, o Codex CLI, o Codex Desktop e o OpenCode podem todos importar a HiAPI através do CC Switch. Os passos abaixo usam o Codex CLI e o gpt-6-astra como exemplo e seguem a interface do CC Switch 4.0.10; nas versões mais recentes os nomes dos botões podem variar ligeiramente. Para os valores a confirmar ao importar outras ferramentas, consulte Valores a importar por ferramenta no final. A entrada de importação do Claude Code não está na página de ligação, mas na página API Keys; consulte Claude Code.

1. Transferir e instalar o CC Switch

1. Abra a página de transferência do CC Switch e desça até Assets. Num Mac, transfira CC-Switch-v<version>-macOS.dmg. Não transfira Source code nem .sig.

① Mac: escolha macOS.dmg; ② Windows x64: escolha Windows.msi; ③ Windows ARM64: escolha Windows-arm64.msi.

2. Faça duplo clique no .dmg transferido e arraste o CC Switch.app para Applications, depois abra-o a partir de Applications. Se o sistema perguntar se quer abrir, verifique a origem da aplicação e clique em Open. Se já tiver o CC Switch, basta abri-lo.
3. No Windows x64, transfira Windows.msi; no ARM64, transfira Windows-arm64.msi. Conclua o instalador e abra o CC Switch a partir do menu Iniciar.

2. Fazer uma cópia de segurança da configuração atual (opcional)

Se já tiver fornecedores, anote primeiro o nome do cartão marcado como In use na página da ferramenta correspondente (por exemplo Codex), para poder voltar atrás mais tarde. Para fazer a cópia de segurança, clique em Settings → Data → SQL import/export → Export SQL backup e guarde-a numa pasta privada neste computador. Uma cópia de segurança pode conter chaves, por isso não a partilhe.

① Clique em Export SQL backup e guarde-a localmente.

3. Escolher uma chave da HiAPI

Crie ou escolha uma chave como descrito em Obter uma chave de API e anote o nome. A caixa de importação escolhe a chave pelo nome, por isso não precisa de copiar a chave agora.

① Introduza um nome para a chave; ② escolha ilimitado ou um limite de gastos conforme necessário; ③ clique em Create key.

4. Preparar a importação na página de ligação

1. Abra a página de ligação da HiAPI. Selecione primeiro API Key setup e depois escolha, pela ordem, tool → command line or desktop → model → system. Para o Codex, é Codex → Command line → gpt-6-astra → macOS.
2. Clique em Import to CC Switch. Na caixa de diálogo, confirme a ferramenta e o modelo, escolha o nome da chave que anotou na lista pendente API Key e confirme o protocolo e o endereço na parte inferior (para o Codex: Responses API · https://api.hiapi.ai/v1).

① Escolha Codex como ferramenta; ② escolha gpt-6-astra como modelo; ③ escolha uma chave existente pelo nome; ④ confirme o endpoint Responses abaixo e clique em Prepare import.

3. Clique em Prepare import. Quando a página indicar que está pronto e pedir para confirmar no cliente, clique em Open CC Switch. Neste momento a importação está apenas preparada; o fornecedor ainda não está ativado.

① Confirme o endpoint e a mensagem de pronto; ② clique em Open CC Switch.

4. Quando o navegador perguntar se quer abrir uma aplicação externa, confirme que é o CC Switch e permita desta vez; não precisa de assinalar «Always allow». Se o cliente não abrir, abra o CC Switch manualmente e clique novamente em Open CC Switch na página.

① Clique em Open CC Switch e permita desta vez.

5. Confirmar a importação no CC Switch

1. Na janela «Confirm provider import», verifique o tipo de aplicação, o nome do fornecedor, o endpoint da API e o modelo; a API key deve estar preenchida e oculta. Para o Codex:

Campo	Valor esperado
App type	Codex
Provider name	HiAPI - gpt-6-astra
API endpoint	https://api.hiapi.ai/v1
Model	gpt-6-astra
API key	Preenchida e oculta

2. Deixe Switch to this provider immediately after import desligado e clique em Import no canto inferior direito. Isto guarda primeiro a configuração e ativa-a no passo seguinte.

① Verifique Codex, o nome do fornecedor, o endpoint da API e o modelo; ② deixe a mudança imediata desligada; ③ clique em Import.

3. De volta à página da ferramenta correspondente no CC Switch, um cartão HiAPI - gpt-6-astra significa que a importação funcionou, mas ainda não está ativado. Se o cartão já existir, não precisa de importar novamente.

6. Ativar a HiAPI

1. Espere primeiro que a tarefa em execução da ferramenta termine. Na página da ferramenta no CC Switch (por exemplo Codex → Direct), localize o cartão HiAPI.
2. Clique no botão Switch / Enable do cartão (um triângulo na 4.0.10; passe o cursor para ver a etiqueta). A HiAPI só está ativada quando o cartão HiAPI está marcado como In use. Se a página da ferramenta não estiver definida como Direct no topo (por exemplo, se tiver vários fornecedores em rotação), clique primeiro em Back to direct e depois mude o cartão.

Captura de ecrã tirada antes do clique: a HiAPI está importada mas não ativada, e o fornecedor original continua em uso. O rodapé do cartão mostra o endereço do site; o endpoint da API é o que a janela de confirmação mostrou.

3. Saia e volte a abrir o cliente que está a configurar para que a nova configuração tenha efeito. Para voltar ao fornecedor original mais tarde, mude para o cartão dele aqui e volte a abrir o cliente.

Valores a importar por ferramenta

Ferramenta	O que escolher na página de ligação	App type	API endpoint	Tutorial
Claude Code	Clique em «Import CCS» à direita da chave na página API Keys	Claude Code	https://api.hiapi.ai	Claude Code
Codex CLI	Codex → Command line → gpt-6-astra	Codex	https://api.hiapi.ai/v1	Codex CLI
Codex Desktop	Codex → Desktop → gpt-6-astra	Codex	https://api.hiapi.ai/v1	Codex Desktop
OpenCode	OpenCode → Command line → o seu modelo	OpenCode	https://api.hiapi.ai/v1	OpenCode

O Codex CLI e o Codex Desktop podem partilhar a configuração local do Codex, por isso mudar no CC Switch altera ambos.