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

# Tutorial de Uso do Terminal Codex CLI

> Codex 集成指南 - Ace Data Cloud

Codex CLI é um agente de programação local de código aberto lançado pela OpenAI, que roda no seu terminal. Ele pode ler código, modificar arquivos, executar comandos, interpretar erros e auxiliar em tarefas diárias de desenvolvimento.

Codex CLI suporta fornecedores de modelos personalizados. Você pode usá-lo através do proxy compatível com OpenAI Responses fornecido pela Ace Data Cloud, sem precisar assinar uma conta oficial da OpenAI. Após a configuração, o Codex CLI enviará as requisições para `https://api.acedata.cloud/v1`.

## Processo de Solicitação

Para usar o Codex CLI, primeiro acesse o [Console da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde poderá se registrar e entrar. Após o login, você será redirecionado de volta para a página atual.

Na primeira solicitação, há uma cota gratuita para experimentar o serviço Codex CLI sem custos.

## Instalação do Codex CLI

Codex CLI suporta macOS, Linux, Windows e WSL. Você pode instalar via npm ou usar Homebrew (somente macOS).

### Instalação via npm (Recomendado)

Se você já tem Node.js instalado, pode instalar diretamente via npm. Requer Node.js 18 ou superior.

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

### Instalação via Homebrew (macOS)

Usuários macOS também podem instalar via Homebrew:

```bash theme={null}
brew install --cask codex
```

### Verificar Instalação

Após a instalação, reabra o terminal e verifique se o comando está disponível:

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

Se aparecer `command not found`, geralmente significa que o terminal atual ainda não carregou o novo PATH. Feche e reabra o terminal ou verifique as configurações de PATH indicadas na saída do script de instalação.

## Configuração do Codex CLI

Após a instalação, o Codex CLI tentará se conectar ao serviço oficial da OpenAI por padrão. Para usar a Ace Data Cloud, é necessário declarar um `model_provider` personalizado no arquivo de configuração do Codex e colocar o Token da API na variável de ambiente correspondente.

### Passo 1: Definir Variável de Ambiente

Recomenda-se adicionar o Token da API no arquivo de configuração do seu shell, como `~/.zshrc`, `~/.bashrc` ou `~/.bash_profile`:

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

Substitua `{token}` pelo Token de API copiado do console da Ace Data Cloud.

Depois, reabra o terminal ou execute o comando `source` para aplicar a configuração imediatamente:

```bash theme={null}
source ~/.zshrc
```

### Passo 2: Editar o Arquivo de Configuração do Codex

O Codex CLI usa `~/.codex/config.toml` como arquivo de configuração global. Se não existir, crie-o:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

Adicione o seguinte conteúdo em `~/.codex/config.toml`:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

Descrição dos campos:

| Campo                                     | Descrição                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------- |
| `model_provider`                          | Nome do fornecedor padrão, correspondente à chave em `[model_providers.<nome>]` |
| `model`                                   | ID do modelo padrão usado                                                       |
| `model_reasoning_effort`                  | Intensidade do raciocínio, valores comuns: `low`, `medium`, `high`              |
| `[model_providers.acedatacloud].base_url` | Endereço do proxy OpenAI Responses da Ace Data Cloud                            |
| `[model_providers.acedatacloud].env_key`  | Nome da variável de ambiente para o Token da API                                |
| `[model_providers.acedatacloud].wire_api` | Tipo de protocolo, deve ser `responses` para usar OpenAI Responses API          |

### Limpar Cache de Login da OpenAI

Se você já fez login com uma conta oficial da OpenAI no Codex CLI, pode haver um cache local do estado de login (normalmente em `~/.codex/auth.json`). Antes de mudar para o proxy da Ace Data Cloud, recomenda-se limpar esse login antigo:

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

Se o comando `codex logout` não estiver disponível, você pode remover manualmente o arquivo de cache:

```bash theme={null}
rm -f ~/.codex/auth.json
```

Se você nunca fez login com uma conta oficial da OpenAI, pode pular esta etapa.

### Iniciar uma Sessão

Entre no diretório do seu projeto e inicie o Codex CLI:

```bash theme={null}
cd /path/to/your/project
codex
```

Quando a interface interativa do Codex aparecer, você pode digitar suas solicitações, por exemplo:

```text theme={null}
Explique a estrutura de diretórios deste projeto
```

### Verificar Configuração

Dentro do Codex CLI, você pode verificar o modelo e fornecedor atuais com:

```text theme={null}
/model
```

Você deverá ver que o modelo está vindo do fornecedor `acedatacloud`, por exemplo:

```text theme={null}
Model: gpt-5
Provider: acedatacloud
```

Se o fornecedor mostrado não for `acedatacloud`, significa que a configuração não foi aplicada corretamente. Verifique se `~/.codex/config.toml` foi salvo corretamente e se a variável `ACEDATACLOUD_API_KEY` está acessível no terminal atual:

```bash theme={null}
echo $ACEDATACLOUD_API_KEY
```

Você também pode consultar o histórico de uso e detalhes de cobrança no [Console da Ace Data Cloud - Histórico de Uso](https://platform.acedata.cloud/console/usages) e verificar o saldo restante em [Console da Ace Data Cloud - Lista de Aplicações](https://platform.acedata.cloud/console/applications).

## Como Funciona

Codex CLI usa nativamente o protocolo OpenAI Responses API. A Ace Data Cloud oferece um serviço proxy compatível em `https://api.acedata.cloud/v1/responses`, portanto o Codex CLI não precisa de um proxy local nem plugins adicionais.

O fluxo de trabalho é:

1. Codex CLI lê `model_provider` em `~/.codex/config.toml` e carrega o bloco de configuração correspondente `[model_providers.acedatacloud]`.
2. Codex CLI lê o Token da API da variável de ambiente indicada por `env_key` (`ACEDATACLOUD_API_KEY`).
3. A requisição é enviada via protocolo `wire_api = "responses"` para `base_url + /responses`, ou seja, `https://api.acedata.cloud/v1/responses`.
4. A Ace Data Cloud autentica o Token, verifica a cota e encaminha a requisição para o canal de modelo upstream disponível.
5. Após a conclusão, a plataforma registra o uso e deduz a cota correspondente.

Isso significa que você continua usando o comando original `codex` e a experiência nativa do Codex CLI, apenas alterando o serviço de modelo para a Ace Data Cloud.

## Configurar o Modelo

O campo `model` em `~/.codex/config.toml` determina o modelo padrão usado pelo Codex. O serviço OpenAI Responses da Ace Data Cloud suporta vários modelos comuns, incluindo:

| Modelo             | Descrição                                                                     |
| ------------------ | ----------------------------------------------------------------------------- |
| `gpt-5`            | Modelo padrão recomendado, adequado para a maioria das tarefas de codificação |
| `gpt-5-mini`       | Mais leve e rápido, ideal para tarefas simples                                |
| `gpt-5.5`          | Versão atualizada, com maior capacidade                                       |
| `gpt-5.5-pro`      | Versão aprimorada, adequada para tarefas complexas de raciocínio              |
| `gpt-4.1`          | Modelo principal da geração anterior                                          |
| `o3`               | Modelo com raciocínio avançado, para tarefas que exigem raciocínio profundo   |
| `o4-mini-high-all` | Modelo leve para raciocínio                                                   |

Para trocar temporariamente o modelo, use o parâmetro na linha de comando ao iniciar o Codex:

```bash theme={null}
codex --model gpt-5-mini
```

Ou modifique diretamente o campo `model` em `~/.codex/config.toml` e reinicie o Codex. A lista completa de modelos está disponível na [Documentação do Serviço OpenAI da Ace Data Cloud](https://platform.acedata.cloud/documents/openai).

## Nível de Confiança do Projeto

Codex CLI permite definir níveis de confiança diferentes para projetos distintos, controlando quais operações o agente pode executar. Você pode adicionar ao final do `~/.codex/config.toml`:

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

Onde:

* `trusted`: O agente tem permissões completas, podendo executar comandos e modificar arquivos.
* `untrusted`: O agente tem permissões restritas, mais adequado para projetos desconhecidos.

## Saiba Mais

* [Repositório Oficial do Codex CLI](https://github.com/openai/codex)
* [Documentação do Serviço OpenAI da Ace Data Cloud](https://platform.acedata.cloud/documents/openai)
* [Console da Ace Data Cloud](https://platform.acedata.cloud/console/applications)