AiHubMix Documentation Hub

Codex CLI é a ferramenta oficial de programação em terminal da OpenAI. Depois de conectar o AIHubMix, uma única chave de API permite chamar e alternar livremente entre modelos da GLM, Claude, Gemini, DeepSeek e outros provedores no terminal, sem ficar preso a um só. Este guia cobre duas abordagens: a abordagem básica (profile + um modelo fixo, a mais rápida) e a abordagem de modelos personalizados (um arquivo de catálogo model_catalog_json para alternar a qualquer momento pela lista /model).

Instalação

Download Oficial (Versão macOS)

https://openai.com/en/codex/

Instalar via Linha de Comando

npm install -g @openai/codex

Configuração de Variáveis de Ambiente

Configurar Usando Arquivos de Configuração

Modifique o arquivo de configuração ~/.codex/config.toml para adicionar as seguintes configurações:

profile = "aihubmix"

[model_providers.aihubmix]
name = "aihubmix"
base_url = "https://aihubmix.com/v1"
personality = "pragmatic"
wire_api = "responses"

[profiles.aihubmix]
model = "gpt-5.2"
model_provider = "aihubmix"
model_reasoning_effort = "high"

Modifique o arquivo de configuração ~/.codex/auth.json para alterar as seguintes configurações:

{
  "OPENAI_API_KEY": "AIHUBMIX_API_KEY"
}

Configurar via cc-switch

Execute o CC-Switch e adicione o provider.

Selecione “AiHubMix” da lista predefinida.

Selecionar AiHubMix na lista de predefinições do CC-Switch

Insira sua chave no campo “chave de API” e clique em “Adicionar” para salvar as configurações.

Inserir a chave de API e salvar no CC-Switch

Retorne à página inicial, selecione “AiHubMix” da lista de providers e clique em “Habilitar” para começar a usá-lo.

Usando o Codex

Usando no Terminal

Abra o terminal, navegue até o diretório do seu projeto e execute o comando codex.

cd /your/project/path
codex

Configure as permissões conforme necessário.

Definir permissões de aprovação ao iniciar o Codex

Selecione o modelo de que precisa com base nos seus requisitos.

Insira linguagem natural; se receber uma resposta normal, a configuração foi bem-sucedida.

Digitar linguagem natural no terminal do Codex com resposta normal

Usando no Aplicativo Desktop do Codex

Abra o aplicativo desktop do Codex e selecione o diretório de trabalho.
Insira a tarefa na caixa de entrada; se receber uma resposta normal, a configuração foi bem-sucedida.

Digitar uma tarefa no Codex desktop com resposta normal

Referências de Comandos Úteis

Comando de Ajuda

codex -h

Opções de Comando Completas

Usage
  $ codex [options] <prompt>

Options
  -h, --help                 Show help information and exit
  -m, --model <model>        Specify the model to use (default: codex-mini-latest)
  -i, --image <path>         Path to the file containing image input
  -v, --view <rollout>       View previously saved session records
  -q, --quiet                Non-interactive mode, only prints the final output of the assistant
  -a, --approval-mode <mode> Override approval policy: 'suggest', 'auto-edit', or 'full-auto'

  --auto-edit                Automatically approve file edits; will still prompt for command confirmation
  --full-auto                Automatically approve edits and commands in sandbox environment

  --no-project-doc           Do not automatically include 'codex.md' file from the repository
  --project-doc <file>       Include specified Markdown file as context
  --full-stdout              Do not truncate stdout/stderr of command output

Dangerous Options
  --dangerously-auto-approve-everything
                             Skip all confirmation prompts and execute commands directly (no sandbox protection)
                             For use only in temporary local testing environments

Experimental Options
  -f, --full-context         Start in "full context" mode, loading the entire repository into context
                             and applying bulk edits in a single operation
                             Only compatible with --model parameter

Examples
  $ codex "Write and run a Python program that prints ASCII art"
  $ codex -q "Fix build issues"

Usar modelos personalizados no Codex

Por padrão, o Codex exibe na lista /model apenas os modelos oficiais da OpenAI. Se você quiser selecionar diretamente na lista qualquer modelo disponível na AIHubMix (GLM, Claude, Gemini, DeepSeek, Kimi, Qwen…), pode usar o mecanismo de “modelos personalizados” oficialmente suportado: declare os modelos disponíveis por meio de um arquivo JSON local (model_catalog_json) e direcione as requisições para a AIHubMix usando [model_providers.aihubmix].

Documentação oficial: Advanced Configuration · OSS mode / local providers

Duas formas de integração

A seção “Configuração de Variáveis de Ambiente” anterior nesta página descreve a forma básica; esta seção descreve a forma com modelos personalizados. As diferenças estão abaixo; escolha conforme a sua necessidade:

	Forma básica (profile + modelo único)	Forma com modelos personalizados (esta seção)
Conteúdo da configuração	Define um `model = "xxx"` fixo no `config.toml`	Mantém adicionalmente um arquivo de catálogo `model_catalog_json`
Trocar de modelo	Edita o arquivo de configuração e reinicia	Seleciona diretamente na lista `/model`, a qualquer momento
Cenário adequado	Usar fixamente um único modelo por longos períodos	Comparar / alternar com frequência entre vários modelos
Complexidade	Baixa	Média

O fluxo completo tem apenas 4 etapas: gerar o arquivo de catálogo → editar o config.toml → definir a variável de ambiente → reiniciar e escolher o modelo.

Etapa 1: Gerar o arquivo de catálogo de modelos

O arquivo de catálogo é uma estrutura { "models": [ ... ] }, em que cada elemento do array descreve um modelo que pode ser selecionado em /model. A seguir, explicamos os campos usando um modelo fixo e, depois, fornecemos um script para gerar em lote os 30 primeiros.

1.1 Entenda primeiro o formato: fixar um modelo

Abaixo está um catálogo mínimo completo comprovadamente analisável pelo Codex (contendo apenas o modelo glm-5.2). Basta salvá-lo como ~/.codex/model-catalogs/custom-models.json para usá-lo; para ter mais modelos, continue adicionando entradas com a mesma estrutura ao array models.

{
  "models": [
    {
      "slug": "glm-5.2",
      "display_name": "GLM 5.2",
      "description": "GLM 5.2 (via AIHubMix)",
      "context_window": 1000000,
      "max_context_window": 1000000,
      "supported_reasoning_levels": [
        { "effort": "low",    "description": "Fast responses" },
        { "effort": "medium", "description": "Balanced" },
        { "effort": "high",   "description": "Deeper reasoning" }
      ],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 0,
      "availability_nux": null,
      "upgrade": null,
      "base_instructions": "You are Codex, a coding agent.",
      "supports_reasoning_summaries": true,
      "support_verbosity": false,
      "default_verbosity": null,
      "apply_patch_tool_type": null,
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "supports_parallel_tool_calls": true,
      "experimental_supported_tools": []
    }
  ]
}

Descrição dos campos (os poucos que você normalmente vai alterar):

Campo	Função	Da API
`slug`	ID do modelo; o Codex o usa para iniciar a requisição e deve ser idêntico ao `model_id` retornado pela API	`model_id`
`display_name`	Nome exibido na lista `/model`	`model_name`
`context_window` / `max_context_window`	Janela de contexto. Se omitida, retorna a um valor padrão conservador muito pequeno; recomenda-se preencher com o valor real da API	`context_length`
`supported_reasoning_levels`	Níveis de raciocínio; após trocar de modelo, ainda é possível escolher o effort em `/model`	—
`visibility`	Defina como `list` para que apareça no seletor	—
`priority`	Ordenação da lista; quanto menor o número, mais à frente	—

Os demais campos são obrigatórios e têm valores fixos: base_instructions, availability_nux, upgrade, supports_reasoning_summaries, support_verbosity, default_verbosity, apply_patch_tool_type, truncation_policy, supports_parallel_tool_calls, experimental_supported_tools. As versões recentes do Codex (já verificado no codex-cli 0.130.0) fazem uma análise rigorosa: se faltar qualquer um deles, todo o catálogo é descartado e há um retorno ao catálogo interno, com um erro do tipo missing field base_instructions, que se manifesta como “não aparecer nenhum modelo personalizado em /model”. Por isso, não é possível remover mais campos deste exemplo.

Sobre base_instructions: é o prompt de sistema desse modelo. No exemplo, usamos uma frase como placeholder, e o modelo funciona normalmente; para obter o desempenho de codificação mais próximo do Codex nativo, substitua-o pelo base_instructions completo de qualquer modelo interno listado em codex debug models --bundled (é exatamente o que faz o script de geração em lote da próxima seção).

O catálogo oficial usa campos em snake_case (display_name, supported_in_api, visibility). Dois tipos de erro fazem com que todo o catálogo seja descartado e os modelos não apareçam em /model: a falta de um campo obrigatório gera missing field ...; o uso de formatos antigos em camelCase como displayName, hidden ou de valores não reconhecidos gera unknown variant .... Basta seguir o conjunto de campos deste artigo para evitar esses problemas.

1.2 Gerar em lote os 30 primeiros

Escrever manualmente várias entradas é propenso à omissão de campos. Para gravar de uma só vez no catálogo os 30 primeiros LLMs da API de lista de modelos da AIHubMix, use o script abaixo — ele clona a partir de um modelo interno usado como template, de modo que os campos obrigatórios (incluindo o base_instructions correto) já vêm completos por natureza e não faltam em nenhuma versão do Codex. Requer curl, python3 e a CLI codex já instalada:

mkdir -p ~/.codex/model-catalogs

# 1) Pega um modelo interno como template: ele já traz base_instructions e todos os demais campos obrigatórios
codex debug models --bundled > /tmp/_tpl.json

# 2) Baixa a lista de modelos da AIHubMix
curl -s "https://aihubmix.com/api/v1/models?type=llm" > /tmp/_aihubmix.json

# 3) Clona o template e gera as entradas uma a uma, sobrescrevendo apenas os campos exclusivos de cada modelo
python3 - <<'PY' > ~/.codex/model-catalogs/custom-models.json
import json, sys
tpl = json.load(open("/tmp/_tpl.json"))["models"][0]   # qualquer modelo interno como template
api = json.load(open("/tmp/_aihubmix.json"))["data"]
# pula modelos de geração de imagem (types contém image_generation) e pega os 30 primeiros
api = [m for m in api if "image_generation" not in (m.get("types") or "")][:30]
out = []
for i, m in enumerate(api):
    e = dict(tpl)                                       # clona todos os campos do template
    ctx = m.get("context_length") or 200000
    e["slug"] = m["model_id"]                           # deve ser idêntico ao model_id da API
    e["display_name"] = m.get("model_name") or m["model_id"]
    e["description"] = (m.get("model_name") or m["model_id"]) + " (via AIHubMix)"
    e["context_window"] = ctx
    e["max_context_window"] = ctx
    e["visibility"] = "list"
    e["supported_in_api"] = True
    e["priority"] = i
    e["availability_nux"] = None
    e["upgrade"] = None
    out.append(e)
json.dump({"models": out}, sys.stdout, ensure_ascii=False, indent=2)
PY

O script sobrescreve apenas os campos exclusivos de cada modelo (slug, display_name, description, context_window etc.); todos os demais campos obrigatórios são clonados do template interno — exatamente o conjunto de campos da seção 1.1, apenas com base_instructions usando o prompt oficial completo.

O arquivo gerado é relativamente grande (cada entrada contém o base_instructions completo, cerca de 1 a 2 MB), o que é normal. Depois de executá-lo, use codex debug models para verificar se ele é analisado corretamente (veja a Etapa 5).

A linha de filtro image_generation no script foi mantida de propósito: dentre os retornos de type=llm, há pouquíssimos modelos que também trazem a tag image_generation (como gpt-image-2), inadequados para conversação; o script os ignora automaticamente antes de pegar os 30 primeiros.

Etapa 2: Modificar o `config.toml`

Edite ~/.codex/config.toml, adicione model_catalog_json no nível raiz e defina o provider aihubmix:

# ⚠️ model_catalog_json deve ficar no nível raiz, não dentro de uma seção [model_providers.*]
model_provider = "aihubmix"
model_catalog_json = "~/.codex/model-catalogs/custom-models.json"

[model_providers.aihubmix]
name = "Aihubmix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

wire_api = "responses" é fundamental: omiti-lo ou defini-lo como chat impede a conexão. As versões recentes do Codex usam apenas a Responses API da OpenAI (/v1/responses); a AIHubMix já é nativamente compatível com a Responses API, então basta apontar para https://aihubmix.com/v1, sem necessidade de criar um proxy de conversão próprio.

Se você também quiser especificar o modelo padrão e o nível de raciocínio padrão (para usar diretamente ao iniciar, sem precisar selecionar manualmente toda vez), use esta configuração mais completa:

model = "glm-5.2"                   # modelo padrão ao iniciar; deve existir no arquivo de catálogo
model_provider = "aihubmix"
model_catalog_json = "~/.codex/model-catalogs/custom-models.json"
model_reasoning_effort = "high"     # nível de raciocínio padrão: minimal / low / medium / high

[model_providers.aihubmix]
name = "Aihubmix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

Após a configuração, o config.toml deve ficar parecido com o abaixo (os retângulos vermelhos são os itens-chave desta etapa: model / model_provider / model_catalog_json no nível raiz, além da seção [model_providers.aihubmix]):

Configuração de model_catalog_json e do provedor aihubmix no config.toml

Etapa 3: Definir a variável de ambiente

Configure a variável de ambiente indicada acima em env_key (atenção para não deixar espaços ao redor do =):

export AIHUBMIX_API_KEY=sk-xxx

Recomenda-se gravá-la em ~/.zshrc / ~/.bashrc para persistência. Obtenha sua chave no console da AIHubMix.

Etapa 4: Reiniciar e escolher o modelo

Reinicie o app / TUI do Codex para que o arquivo de catálogo tenha efeito e, em seguida:

codex
# Na interface interativa, digite /model para ver os 30 modelos declarados na etapa anterior e alternar entre eles

Após digitar /model, são listados todos os modelos declarados no catálogo; use as setas para selecionar e Enter para confirmar:

Seletor /model do Codex mostrando a lista de modelos personalizados da AIHubMix

Depois de selecionar um modelo, o /model também permite escolher o nível de raciocínio (effort); escolha low / medium / high conforme a necessidade.

Etapa 5: Verificar se está funcionando

No Codex, digite /model, confirme que você consegue ver os modelos declarados no catálogo e troque para um deles (por exemplo, glm-5.2).
Faça uma pergunta qualquer para verificar se o caminho está funcionando. Atenção: não confie em “qual modelo você é?” para julgar — em base_instructions está escrito “You are Codex… based on GPT-5”, de modo que todos os modelos se identificarão como GPT-5, e perguntar não revela o modelo real. Para confirmar o modelo efetivamente chamado, faça login no console da AIHubMix, acesse a página “Logs” e veja o model_id daquele registro de requisição — essa é a verdade.

Após a troca bem-sucedida, o topo exibirá Model changed to ..., e a barra de status na parte inferior também mostrará o modelo atual e a janela de contexto (na imagem abaixo, trocou-se para glm-5.2, janela de 258K):

Sessão do Codex e barra de status após trocar para glm-5.2

Perguntas frequentes sobre modelos personalizados

Os modelos personalizados não aparecem em /model? Verifique nesta ordem:
1. Primeiro, execute codex debug models. Se aparecer missing field ... (o mais comum, falta um campo obrigatório) ou unknown variant ... (nome/valor de campo incorreto), significa que todo o catálogo falhou na análise e foi descartado — basta regerá-lo com o script “clonar template interno” da Etapa 1.
2. Confirme que model_catalog_json está no nível raiz do config.toml, e não dentro de uma seção [model_providers.*];
3. Confirme que o JSON usa os campos oficiais em snake_case e que visibility está como list;
4. Se codex debug models já mostra todos os modelos, mas no aplicativo desktop (Desktop App) restam apenas um ou dois e o modelo atual aparece como “personalizado” — esse é um bug conhecido do aplicativo desktop: ele aplica, sobre o catálogo local, mais uma camada de filtro por uma lista de permissões de slugs oficiais, removendo do seletor os modelos não oficiais (veja as GitHub Issues #19694, #15138). Nesse caso, o modelo ainda é chamado normalmente conforme o model = "..." no config.toml (é possível confirmar nos logs da AIHubMix), apenas o nome não é exibido. Para exibi-lo corretamente, use a CLI / TUI codex no terminal; no aplicativo desktop, só resta definir explicitamente model = "o modelo que você quer" no config.toml e aguardar a correção oficial.
O catálogo “substitui”, não “mescla”. O model_catalog_json substitui toda a lista de modelos, em vez de acrescentar (comprovado na prática: com apenas 2 modelos no catálogo, codex debug models mostra somente esses 2, e todos os gpt-5.x internos desaparecem). Se você quiser os dois tipos, inclua-os juntos no catálogo personalizado.
A requisição retorna erro de protocolo / não conecta. Na maioria das vezes, o base_url ou o wire_api do provider não foi configurado corretamente. Para a AIHubMix, é obrigatório wire_api = "responses" + base_url = "https://aihubmix.com/v1". Se você estiver integrando um terceiro que só suporta Chat Completions, será necessário um proxy de conversão local; usuários da AIHubMix não precisam dessa etapa.
Reconexões frequentes (“Reconnecting”). Em alguns ambientes de rede/proxy, o WebSocket (WSS) não funciona; é possível adicionar supports_websockets = false na seção do provider para forçar o uso de HTTP.
A análise retorna missing field ... (por exemplo, missing field base_instructions). A entrada está sem um campo obrigatório. As versões recentes do Codex fazem uma análise rigorosa: base_instructions, availability_nux, upgrade, supports_reasoning_summaries, support_verbosity, default_verbosity, apply_patch_tool_type, truncation_policy, supports_parallel_tool_calls, experimental_supported_tools etc. devem todos existir. O script “clonar template interno” da Etapa 1 preenche tudo de uma só vez.
A análise retorna unknown variant. O JSON do catálogo contém um nome de campo ou valor que o Codex não reconhece (comum em formatos antigos em camelCase como displayName/hidden). Basta usar o conjunto de campos em snake_case deste artigo.

Artigos de referência

Documentação oficial: Advanced Configuration ｜ Configuration Reference
Referência do formato do catálogo interno oficial: codex-rs/models-manager/models.json
Guia da comunidade: config.toml do Codex: integre qualquer provider personalizado em 6 linhas

Última atualização: 2026-06-25

Assistentes de codificação

Integrações IDE

Agente / Workflow

SDKs e frameworks

Tutorial: conectar AIHubMix no Codex CLI

Instalação

Download Oficial (Versão macOS)

Instalar via Linha de Comando

Configuração de Variáveis de Ambiente

Configurar Usando Arquivos de Configuração

Configurar via cc-switch

Usando o Codex

Usando no Terminal

Usando no Aplicativo Desktop do Codex

Referências de Comandos Úteis

Comando de Ajuda

Opções de Comando Completas

Usar modelos personalizados no Codex

Duas formas de integração

Etapa 1: Gerar o arquivo de catálogo de modelos

1.1 Entenda primeiro o formato: fixar um modelo

1.2 Gerar em lote os 30 primeiros

Etapa 2: Modificar o `config.toml`

Etapa 3: Definir a variável de ambiente

Etapa 4: Reiniciar e escolher o modelo

Etapa 5: Verificar se está funcionando

Perguntas frequentes sobre modelos personalizados

Artigos de referência

​Instalação

​Download Oficial (Versão macOS)

​Instalar via Linha de Comando

​Configuração de Variáveis de Ambiente

​Configurar Usando Arquivos de Configuração

​Configurar via cc-switch

​Usando o Codex

​Usando no Terminal

​Usando no Aplicativo Desktop do Codex

​Referências de Comandos Úteis

​Comando de Ajuda

​Opções de Comando Completas

​Usar modelos personalizados no Codex

​Duas formas de integração

​Etapa 1: Gerar o arquivo de catálogo de modelos

​1.1 Entenda primeiro o formato: fixar um modelo

​1.2 Gerar em lote os 30 primeiros

​Etapa 2: Modificar o config.toml

​Etapa 3: Definir a variável de ambiente

​Etapa 4: Reiniciar e escolher o modelo

​Etapa 5: Verificar se está funcionando

​Perguntas frequentes sobre modelos personalizados

​Artigos de referência

Instalação

Download Oficial (Versão macOS)

Instalar via Linha de Comando

Configuração de Variáveis de Ambiente

Configurar Usando Arquivos de Configuração

Configurar via cc-switch

Usando o Codex

Usando no Terminal

Usando no Aplicativo Desktop do Codex

Referências de Comandos Úteis

Comando de Ajuda

Opções de Comando Completas

Usar modelos personalizados no Codex

Duas formas de integração

Etapa 1: Gerar o arquivo de catálogo de modelos

1.1 Entenda primeiro o formato: fixar um modelo

1.2 Gerar em lote os 30 primeiros

Etapa 2: Modificar o `config.toml`

Etapa 3: Definir a variável de ambiente

Etapa 4: Reiniciar e escolher o modelo

Etapa 5: Verificar se está funcionando

Perguntas frequentes sobre modelos personalizados

Artigos de referência