> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Tutorial: conectar AIHubMix no Codex CLI > Conecte o AIHubMix no Codex CLI: com uma única chave de API, alterne livremente entre GLM, Claude, Gemini, DeepSeek e outros modelos pela lista /model. Inclui configuração do config.toml, um script para gerar o catálogo model_catalog_json e perguntas frequentes de solução de problemas. [Codex CLI](https://openai.com/codex/) é 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/](https://openai.com/en/codex/) ### Instalar via Linha de Comando ```bash theme={null} npm install -g @openai/codex ``` ## Configuração de Variáveis de Ambiente ### Configurar Usando Arquivos de Configuração 1. Modifique o arquivo de configuração `~/.codex/config.toml` para adicionar as seguintes configurações: ```toml theme={null} 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" ``` 2. Modifique o arquivo de configuração `~/.codex/auth.json` para alterar as seguintes configurações: ```json theme={null} { "OPENAI_API_KEY": "AIHUBMIX_API_KEY" } ``` ### Configurar via cc-switch 1. Execute o CC-Switch e adicione o provider. Tela de adicionar provedor no CC-Switch 2. Selecione "AiHubMix" da lista predefinida. Selecionar AiHubMix na lista de predefinições do CC-Switch 3. 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 4. Retorne à página inicial, selecione "AiHubMix" da lista de providers e clique em "Habilitar" para começar a usá-lo. Ativar o provedor AiHubMix no CC-Switch ## Usando o Codex ### Usando no Terminal 1. Abra o terminal, navegue até o diretório do seu projeto e execute o comando `codex`. ```bash theme={null} cd /your/project/path codex ``` 2. Configure as permissões conforme necessário. Definir permissões de aprovação ao iniciar o Codex 3. Selecione o modelo de que precisa com base nos seus requisitos. Escolher o modelo a usar no Codex 4. 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 1. Abra o aplicativo desktop do Codex e selecione o diretório de trabalho. 2. 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 ```bash theme={null} codex -h ``` ### Opções de Comando Completas ```bash theme={null} Usage $ codex [options] Options -h, --help Show help information and exit -m, --model Specify the model to use (default: codex-mini-latest) -i, --image Path to the file containing image input -v, --view View previously saved session records -q, --quiet Non-interactive mode, only prints the final output of the assistant -a, --approval-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 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](https://developers.openai.com/codex/config-advanced) ### 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`. ```json theme={null} { "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](https://aihubmix.com/api/v1/models?type=llm), 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: ```bash theme={null} 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`: ```toml theme={null} # ⚠️ 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: ```toml theme={null} 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 `=`): ```bash theme={null} export AIHUBMIX_API_KEY=sk-xxx ``` Recomenda-se gravá-la em `~/.zshrc` / `~/.bashrc` para persistência. Obtenha sua chave no [console da AIHubMix](https://aihubmix.com/token). ### 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: ```bash theme={null} 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 1. 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`). 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](https://aihubmix.com/token), 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](https://github.com/openai/codex/issues/19694), [#15138](https://github.com/openai/codex/issues/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](https://developers.openai.com/codex/config-advanced) ｜ [Configuration Reference](https://developers.openai.com/codex/config-reference) * Referência do formato do catálogo interno oficial: [codex-rs/models-manager/models.json](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json) * Guia da comunidade: [config.toml do Codex: integre qualquer provider personalizado em 6 linhas](https://www.morphllm.com/codex-provider-configuration) *** Última atualização: 2026-06-25