Codex CLI

O Codex CLI pode ligar-se à HiAPI através da importação com um clique do CC Switch, ou pode configurá-lo manualmente (passo 9). Os passos abaixo usam gpt-6-astra como exemplo; a HiAPI usa o protocolo OpenAI Responses. Este tutorial foi verificado no Mac com o Codex CLI 0.162.1; os passos do Mac são o caminho principal e os do Windows são apresentados em separado. Pode ignorar a instalação do software que já tem.

1. Instalar o Node.js

Instale a LTS 22.19 ou posterior como descrito em Configuração do Node.js e ignore se já a tiver. Depois execute os dois comandos abaixo num terminal; ver números de versão é suficiente:

node --version
npm --version

2. Instalar o Codex CLI

No terminal que acabou de abrir, execute cada linha:

npm install -g @openai/codex
codex --version

Ver um número de versão do codex-cli é suficiente; a configuração manual (passo 9) requer a versão 0.134 ou posterior. No Windows PowerShell, use npm.cmd install -g @openai/codex e codex.cmd --version.

3. Instalar e abrir o CC Switch

Transfira, instale e abra o CC Switch como descrito em Instalação e importação com um clique do CC Switch; se já o tiver, basta abri-lo.

Se já tiver fornecedores, anote primeiro o nome do cartão marcado como «In use» na página Codex e, quando necessário, exporte uma cópia de segurança SQL como descrito em Fazer uma cópia de segurança da configuração atual.

4. Escolher uma HiAPI API key

Escolha ou crie uma chave como descrito em Obter uma chave de API e anote o nome. Não precisa de copiar a chave aqui; a importação leva-a consigo.

5. Preparar a importação com um clique na web

1. Abra a página de ligação do Codex da HiAPI e escolha API Key setup → Codex → Command line → gpt-6-astra → macOS. No Windows, escolha Windows como sistema.

2. Clique em Import to CC Switch, escolha o nome da chave que anotou na lista pendente API Key e confirme que a parte inferior mostra Responses API · https://api.hiapi.ai/v1.

3. Clique em Prepare import e depois em Open CC Switch; permita quando o navegador perguntar.

Capturas de ecrã de cada passo em Preparar a importação na página de ligação.

6. Confirmar a importação no CC Switch

Na janela «Confirm provider import», verifique os itens abaixo, deixe Switch to this provider immediately after import desligado e clique em Import:

De volta à página Codex no CC Switch, o cartão HiAPI - gpt-6-astra significa que a importação funcionou (ainda não está ativado). Veja as capturas de ecrã em Confirmar a importação no CC Switch.

7. Ativar a HiAPI

1. Espere primeiro que a tarefa em execução do Codex termine. Na página Codex → Direct do CC Switch, clique no botão Switch / Enable do cartão HiAPI - gpt-6-astra; a HiAPI só está ativada quando o cartão está marcado como «In use». Veja as capturas de ecrã em Ativar a HiAPI.
2. Feche completamente o Codex e volte a abri-lo para que a nova configuração tenha efeito. O CLI e o Desktop podem partilhar a configuração local do Codex; para voltar ao fornecedor original mais tarde, mude para o cartão dele aqui e volte a abrir o cliente.

8. Abrir o Codex, escolher um modelo e começar

1. Abra um novo terminal e vá para a pasta do projeto que quer usar, ou crie primeiro uma pasta vazia:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. Da primeira vez, pergunta se quer confiar no diretório: confirme que o caminho é a pasta que acabou de escolher, depois confirme conforme indicado e mantenha as permissões predefinidas. Com a importação com um clique, execute codex diretamente; não acrescente o --profile hiapi usado na configuração manual.

3. Na caixa de entrada do Codex, escreva /model e prima Enter. Use as teclas de seta para escolher GPT-6 Astra / gpt-6-astra e prima Enter; se houver um nível de raciocínio, escolha um e confirme, depois prima Esc para voltar.

① Use as teclas de seta para escolher GPT-6-Astra; ② prima Enter para confirmar.

4. Envie «Olá, apresente-se numa frase.». Uma resposta normal significa que a ligação funciona. Se Registos de pedidos na consola da HiAPI mostrar este pedido, está a passar pela HiAPI. Depois disso, basta escrever na caixa de entrada o que quer fazer.

9. Configuração manual (sem CC Switch)

Ignore este passo se usou a importação com um clique. A configuração manual só se aplica ao Codex CLI, não ao Codex Desktop.

1. Num Mac, execute as três linhas abaixo num terminal; um ficheiro existente com o mesmo nome é primeiro copiado automaticamente para uma cópia de segurança:

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. Para um ficheiro novo, cole todo o conteúdo abaixo; se o ficheiro existir, atualize apenas os campos e tabelas com o mesmo nome, mantenha o resto e não acrescente duplicados. Os campos de nível superior têm de vir antes de [model_providers.hiapi]. env_key = "HIAPI_API_KEY" é a forma como o Codex lê uma variável de ambiente; deixe como está.

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. Prima Ctrl+O → Enter → Ctrl+X para guardar e sair. O nome do ficheiro tem de ser hiapi.config.toml, não .toml.txt. Se tiver definido CODEX_HOME, guarde o ficheiro nesse diretório.

4. Volte a Consola da HiAPI → API Keys, clique no ícone de copiar junto à chave e copie a HiAPI API key completa. No mesmo terminal onde vai iniciar o Codex, execute o comando abaixo (substitua YOUR_HIAPI_API_KEY pela sua HiAPI API key e mantenha as aspas) e depois vá para o diretório do projeto e inicie:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. No Windows, use o PowerShell para criar o diretório $env:USERPROFILE\.codex, abra hiapi.config.toml no Notepad e cole o mesmo TOML; primeiro faça uma cópia de segurança de um ficheiro existente. Em Save as, escolha «All files» e UTF-8, e confirme que não há sufixo .txt. Na mesma janela do PowerShell e no mesmo diretório do projeto, execute:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

A variável de ambiente só se aplica ao terminal atual; defina-a novamente depois de fechar o terminal. Depois de iniciar, escolha um modelo como no passo 8.

Resolução de problemas

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