> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usando o APIMart no Codex CLI

> Um guia detalhado sobre como configurar e usar os serviços de API do APIMart no Codex CLI, permitindo que você acesse vários modelos de IA para programação assistida com uma configuração simples.

## Introdução

O Codex CLI é o agente de codificação de terminal de código aberto da OpenAI que pode ler e escrever arquivos, executar comandos, corrigir bugs e concluir tarefas completas de codificação diretamente na linha de comando.
Ao se conectar através do APIMart, você pode usar livremente vários modelos — incluindo GPT e Claude — no Codex CLI, com preços mais flexíveis e competitivos.

## Pré-requisitos

Antes de começar, certifique-se de ter:

1. **Node.js instalado**
   Baixe e instale do [site do Node.js](https://nodejs.org/) (LTS mais recente, v20 ou mais recente recomendado) para instalar o Codex CLI via npm

2. **Obtido uma chave de API do APIMart**
   Acesse o [Console do APIMart](https://apimart.ai/keys) para obter sua chave de API (começa com `sk-`)

<Note>**Dica:** Se você ainda não tem uma conta no APIMart, registre-se primeiro em [APIMart](https://apimart.ai) e obtenha sua chave de API.</Note>

## Etapa 1: Instalar o Codex CLI

Escolha um dos seguintes métodos para instalar:

<Tabs>
  <Tab title="npm (Recomendado)">
    Instale globalmente com o npm — funciona em todos os sistemas operacionais:

    ```bash theme={null}
    npm install -g @openai/codex
    ```

    <Note>Se você encontrar problemas de permissão, prefixe com `sudo` (macOS / Linux).</Note>
  </Tab>

  <Tab title="Homebrew (macOS)">
    Usuários de macOS também podem instalar com o Homebrew:

    ```bash theme={null}
    brew install codex
    ```
  </Tab>
</Tabs>

### Verificar a instalação

Após a instalação, execute o seguinte comando para confirmar:

```bash theme={null}
codex --version
```

Se um número de versão for impresso, a instalação foi bem-sucedida.

## Etapa 2: Configurar a API do APIMart

O Codex CLI gerencia provedores de modelos por meio de arquivos de configuração no diretório `~/.codex/`. Tudo o que precisamos fazer é adicionar um provedor personalizado apontando para o APIMart.

### 2.1 Localize o diretório de configuração

* **macOS / Linux:** `~/.codex/`
* **Windows:** `C:\Users\<username>\.codex\`

<Note>Se o diretório não existir, execute `codex` uma vez no seu terminal e pressione `Ctrl + C` para sair — ele será criado automaticamente.</Note>

### 2.2 Configurar a chave de API

No diretório de configuração, crie ou edite o arquivo `auth.json` e preencha com sua chave do APIMart:

```json theme={null}
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxx"
}
```

| Campo            | Descrição                                      |
| ---------------- | ---------------------------------------------- |
| `OPENAI_API_KEY` | Sua chave de API do APIMart (começa com `sk-`) |

### 2.3 Configurar o provedor de modelos

No diretório de configuração, crie ou edite o arquivo `config.toml` e adicione o provedor APIMart:

```toml theme={null}
# Default model
model = "gpt-5.5"
# Default provider — matches [model_providers.apimart] below
model_provider = "apimart"

# APIMart provider configuration
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

| Campo                  | Descrição                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `model`                | ID do modelo padrão — escolha um da lista de modelos abaixo                               |
| `model_provider`       | Provedor padrão — deve corresponder ao ID dentro de `[model_providers.xxx]`               |
| `name`                 | Nome de exibição do provedor — pode ser personalizado                                     |
| `base_url`             | URL compatível com OpenAI do APIMart — fixada em `https://api.apimart.ai/v1`              |
| `wire_api`             | Protocolo de comunicação — versões recentes do Codex requerem `responses` (Responses API) |
| `requires_openai_auth` | Defina como `true` para autenticar usando a chave de `auth.json`                          |

Após salvar ambos os arquivos, reinicie o Codex CLI para que as alterações tenham efeito.

<Warning>Certifique-se de que `auth.json` é JSON válido e `config.toml` é TOML válido. Não use aspas inteligentes ou de largura total, caso contrário a configuração não será aplicada.</Warning>

## Etapa 3: Começar

### Verificar a configuração

Em qualquer diretório de projeto, execute o seguinte comando para confirmar que tudo está conectado:

```bash theme={null}
codex "Introduce yourself in one sentence"
```

Se você receber uma resposta da IA, a configuração está funcionando. Se você vir uma tela de login ou erros `401` / `403`, consulte a seção FAQ abaixo.

### Modo interativo

Execute `codex` diretamente para entrar na UI interativa — ideal para tarefas completas de codificação:

```bash theme={null}
codex
```

Uma vez dentro, descreva o que você precisa em linguagem natural, por exemplo:

```
Create an Express.js server with a JSON-returning health check endpoint
```

O Codex analisará seu projeto, gerará código, executará comandos e pedirá confirmação antes de realizar operações sensíveis.

### Modos de aprovação

Na primeira execução, o Codex pedirá que você escolha um nível de aprovação:

| Modo            | Descrição                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------- |
| **Read Only**   | Apenas leituras de arquivos são permitidas — qualquer modificação ou comando requer confirmação |
| **Auto**        | Pode ler/escrever arquivos e executar comandos dentro do diretório de trabalho (recomendado)    |
| **Full Access** | Realiza qualquer operação sem confirmação — use com cuidado                                     |

Recomendamos começar com o modo **Auto**. Digite `/approvals` na UI interativa para alterá-lo a qualquer momento.

### Trocar de modelos

Na UI interativa, digite `/model` para trocar rapidamente, ou altere o campo `model` em `config.toml` e reinicie.

## Modelos suportados

Para o Codex CLI, os seguintes modelos da série GPT-5 são recomendados:

| ID do modelo    | Pontos fortes                                                | Casos de uso recomendados                          |
| --------------- | ------------------------------------------------------------ | -------------------------------------------------- |
| `gpt-5.5`       | Carro-chefe mais recente, capacidade de codificação superior | Primeira escolha para o Codex, engenharia complexa |
| `gpt-5.4`       | Carro-chefe da geração anterior, muito capaz                 | Codificação complexa, design de arquitetura        |
| `gpt-5.4-mini`  | Leve, rápido, econômico                                      | Codificação diária, iteração rápida                |
| `gpt-5.3-codex` | Modelo de codificação otimizado para o Codex                 | Tarefas de codificação agentivas                   |
| `gpt-5.2`       | Estável e equilibrado                                        | Tarefas de codificação rotineiras                  |

<Tip>
  **Dicas de seleção de modelos:** A série GPT-5 acima combina melhor com o Codex CLI. Para a melhor experiência, prefira `gpt-5.5`; `gpt-5.3-codex` é especificamente otimizado para os cenários de codificação agentiva do Codex.
</Tip>

## Comandos comuns

Comandos e atalhos frequentemente usados no Codex CLI:

| Comando                 | Descrição                                |
| ----------------------- | ---------------------------------------- |
| `codex`                 | Entrar na UI interativa                  |
| `codex "task"`          | Iniciar com uma instrução inicial        |
| `codex exec "task"`     | Modo não interativo — executar e sair    |
| `codex --model gpt-5.4` | Iniciar com um modelo especificado       |
| `codex --version`       | Mostrar o número da versão               |
| `/model`                | Trocar de modelo dentro da UI interativa |
| `/approvals`            | Ajustar o modo de aprovação dentro da UI |
| `Ctrl + C`              | Sair da UI interativa                    |

## FAQ

### Q1: Uma tela de login do ChatGPT aparece após a inicialização?

Se você vir "Sign in with ChatGPT" ou similar após a inicialização, a configuração não teve efeito.

**Solução de problemas:**

1. Certifique-se de que tanto `config.toml` quanto `auth.json` estão dentro de `~/.codex/`
2. Verifique se `model_provider` em `config.toml` está definido como `apimart`
3. Verifique se `auth.json` é JSON válido e a chave está preenchida completamente

### Q2: Recebendo erros 401 / 403?

| Código de status   | Significado                              | Solução                                                            |
| ------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
| `401 Unauthorized` | Chave de API ausente ou inválida         | Verifique a chave em `auth.json` — deve começar com `sk-`          |
| `403 Forbidden`    | Permissão insuficiente ou chave expirada | Acesse o [Console](https://apimart.ai/keys) para verificar a chave |

Certifique-se também de que `base_url` está definido como `https://api.apimart.ai/v1`, e não a URL oficial da OpenAI.

### Q3: Falha na conexão?

1. Verifique sua conexão de rede
2. Certifique-se de que `base_url` em `config.toml` está correto
3. Se você está atrás de um proxy, certifique-se de que ele permite acesso a `api.apimart.ai`

### Q4: `wire_api = "chat"` não é mais suportado?

Versões recentes do Codex CLI (0.84.0 e posteriores) removeram o protocolo `chat`. Atualize `wire_api` em `config.toml` para `responses`:

```toml theme={null}
wire_api = "responses"
```

O APIMart suporta a Responses API — basta reiniciar o Codex após a alteração.

### Q5: Chamadas de ferramenta ou execuções estão falhando?

Certifique-se de que `wire_api` em `config.toml` está definido como `responses`. Se ainda encontrar problemas de compatibilidade, mude para um modelo da série GPT-5 recomendado (por exemplo, `gpt-5.5`, `gpt-5.3-codex`) — eles se combinam de forma mais confiável com o Codex CLI.

### Q6: Usar variáveis de ambiente em vez de auth.json?

Você também pode configurar a chave por meio de uma variável de ambiente. Altere o bloco do provedor em `config.toml` para:

```toml theme={null}
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
env_key = "APIMART_API_KEY"
```

Em seguida, defina a variável de ambiente `APIMART_API_KEY` para sua chave do APIMart. `auth.json` não é mais necessário nesta configuração.

### Q7: Como trocar de modelos?

Duas maneiras:

1. **Na UI interativa**: Digite `/model` para trocar
2. **Edite a configuração**: Altere o campo `model` em `config.toml` e reinicie o Codex CLI

### Q8: Como verificar o uso e o faturamento?

Acesse o [Console do APIMart](https://apimart.ai/overview) para visualizar estatísticas de chamadas de API, detalhes de consumo de tokens e tendências de custos.

## Suporte e ajuda

Se você encontrar algum problema ao usar o Codex CLI:

* 📚 [Centro de documentação do APIMart](https://docs.apimart.ai)
* 💬 [Comunidade do Discord](https://discord.gg/V8zqssyZ5c)
* 🐦 [Twitter @APIMart\_](https://x.com/APIMart_)
* 📧 Suporte técnico: [zhihong@apimart.ai](mailto:zhihong@apimart.ai)

***

<Card title="Comece a usar o APIMart" icon="rocket" href="https://apimart.ai">
  Cadastre-se no APIMart agora, obtenha sua chave de API e experimente um assistente de programação multimodelo no Codex CLI!
</Card>