> ## 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 Codex para VS Code

> Codex 集成指南 - Ace Data Cloud

O Codex é um agente de programação lançado pela OpenAI. Além do CLI de terminal, ele também oferece uma extensão para VS Code, que permite conversar, ler arquivos, citar contextos, gerar modificações, e visualizar alterações no painel lateral do editor.

Este documento explica como configurar e usar a extensão do Codex no VS Code através de um proxy compatível com o OpenAI Responses na Ace Data Cloud. A extensão do Codex para VS Code e o CLI do Codex usam o mesmo sistema de configuração local, portanto, basta apontar `~/.codex/config.toml` para a Ace Data Cloud para que o Codex no VS Code utilize `https://api.acedata.cloud/v1`.

## Processo de Solicitação

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

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

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login/registro, e após autenticar-se, retornará à página atual.

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

## Instalando a Extensão do Codex

Procure por `Codex` no marketplace de extensões do VS Code e instale a extensão **Codex - OpenAI's coding agent**, publicada pela OpenAI. O ID do Marketplace é:

```text theme={null}
openai.chatgpt
```

Também pode instalar via linha de comando:

```bash theme={null}
code --install-extension openai.chatgpt
```

Após a instalação, reinicie ou recarregue o VS Code. Se não aparecer o ícone do Codex na barra lateral, abra a paleta de comandos (`Cmd+Shift+P` no macOS, `Ctrl+Shift+P` no Windows/Linux), e execute:

```text theme={null}
Codex: Open Codex Sidebar
```

Por padrão, o Codex aparecerá na barra lateral direita do VS Code. Você também pode arrastá-lo para a barra de atividades à esquerda.

## Instalando o Codex CLI (para validação)

A documentação oficial informa que a extensão do VS Code e o CLI do Codex usam a mesma configuração. Para validar seu Token de API e modelos antes de configurar o VS Code, recomenda-se instalar o CLI do Codex.

Uma maneira recomendada é via npm, que requer Node.js 18 ou superior:

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

Usuários de macOS também podem instalar pelo Homebrew:

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

Após a instalação, verifique se o comando funciona:

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

Se desejar usar apenas a extensão do VS Code, pode pular a validação do CLI; a configuração será compartilhada por `~/.codex/config.toml`.

## Configurando a API da Ace Data Cloud

A configuração do Codex para VS Code e do CLI compartilham o mesmo arquivo de configuração. Por padrão, o Codex solicita login na conta oficial da OpenAI ou configuração de uma chave API oficial. Para usar a Ace Data Cloud, é necessário configurar o Token de API e o arquivo `~/.codex/config.toml`.

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

Recomenda-se colocar o Token de API no arquivo de configuração do 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.

Após editar, reinicie o terminal ou execute:

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

Se o VS Code já estiver aberto, reinicie ou recarregue para que a extensão leia as novas variáveis de ambiente.

### Passo 2: Editar o arquivo de configuração do Codex

O arquivo de configuração de usuário do Codex fica em `~/.codex/config.toml`. Se não existir, crie:

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

Insira a seguinte configuração:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[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`         | Provedor de modelos padrão, corresponde a `[model_providers.acedatacloud]`    |
| `model`                  | ID do modelo padrão                                                           |
| `model_reasoning_effort` | Intensidade de raciocínio (`low`, `medium`, `high`)                           |
| `approval_policy`        | Política de confirmação antes de executar comandos (`on-request` recomendado) |
| `sandbox_mode`           | Modo sandbox ao executar comandos (`workspace-write` recomendado)             |
| `base_url`               | URL da API compatível com OpenAI na Ace Data Cloud                            |
| `env_key`                | Nome da variável de ambiente que armazena o Token de API                      |
| `wire_api`               | Tipo de protocolo, deve ser `responses` ao usar OpenAI Responses API          |

Também é possível clicar no ícone de engrenagem no canto superior direito da extensão do Codex e selecionar **Codex Settings > Open config.toml** para abrir o arquivo de configuração diretamente no VS Code.

### Configuração por projeto

Para usar configurações diferentes em projetos específicos, crie um arquivo `.codex/config.toml` na raiz do projeto. O Codex prioriza a leitura de configurações de projeto, mas somente se o projeto for marcado como trusted.

Exemplo:

```toml theme={null}
model = "gpt-4.1-mini"
model_reasoning_effort = "medium"
```

Recomenda-se guardar tokens pessoais em variáveis de ambiente e não no repositório. A configuração de projeto também deve ser avaliada quanto à necessidade de versionamento.

## Limpando cache de login na OpenAI

Se você já logou na conta oficial da OpenAI na extensão do Codex, pode ainda haver cache local. Antes de trocar para o proxy da Ace Data Cloud, execute:

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

Se o comando não estiver disponível, exclua o arquivo de cache:

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

Depois, reinicie ou recarregue o VS Code.

## Uso Básico

Após configurar, abra o painel do Codex na lateral do VS Code e digite suas solicitações. Por exemplo:

```text theme={null}
Explique a estrutura de diretórios do projeto atual e indique o arquivo principal de entrada.
```

A extensão do Codex pode usar arquivos e trechos de código selecionados como contexto. Você também pode citar arquivos usando `@`, por exemplo:

```text theme={null}
Consulte @src/App.vue e me ajude a dividir essa página em componentes mais claros.
```

Se selecionar um trecho de código, pode usar a paleta de comandos para:

```text theme={null}
Codex: Add to Codex Thread
```

Ou:

```text theme={null}
Codex: Add File to Codex Thread
```

para incluir o arquivo inteiro no contexto.

## Alternando Modelos e Intensidade de Raciocínio

A extensão do Codex permite trocar de modelos e ajustar a intensidade de raciocínio usando o seletor na parte inferior do campo de entrada. Para configurações com Ace Data Cloud, o ideal é definir o `model` padrão no `~/.codex/config.toml` e alterar conforme necessário na interface.

Recomendações de modelos por cenário:

| Cenário                                       | Modelo recomendado         | Intensidade de raciocínio |
| --------------------------------------------- | -------------------------- | ------------------------- |
| Leitura de código e pequenas modificações     | `gpt-4.1-mini`             | `medium`                  |
| Tarefas de desenvolvimento geral              | `gpt-5`                    | `high`                    |
| Reestruturação complexa e raciocínio profundo | `gpt-5.5` ou `gpt-5.5-pro` | `high`                    |
| Tarefas que requerem raciocínio reforçado     | `o3`                       | `high`                    |

Se o modelo desejado não aparecer na interface, edite o campo `model` no `~/.codex/config.toml` e reinicie o VS Code. Para uma lista completa de modelos, consulte a [documentação de serviços OpenAI na Ace Data Cloud](https://platform.acedata.cloud/documents/openai).

## Selecionando o Modo de Trabalho

A extensão suporta diferentes modos de operação:

| Modo                  | Cenário de uso                                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Chat`                | Deseja discutir, explicar código ou planejar, sem que o Codex altere arquivos automaticamente                    |
| `Agent`               | Permite que o Codex leia arquivos, modifique código e execute comandos necessários — recomendado para uso diário |
| `Agent (Full Access)` | Permite maior permissão e acesso à rede, indicado para cenários com riscos conhecidos                            |

Para uso cotidiano, recomenda-se usar o modo `Agent` com `approval_policy = "on-request"`. Assim, o Codex solicitará confirmação antes de comandos sensíveis ou acessos externos.

## Validando a Configuração

Primeiro, teste no terminal usando a mesma configuração:

```bash theme={null}
codex exec --model gpt-4.1-mini "Reply with exactly: ADC_Codex_OK"
```

Se a configuração estiver correta, deverá receber:

```text theme={null}
ADC_Codex_OK
```

Depois, no VS Code, abra o painel do Codex e envie uma pergunta simples:

```text theme={null}
Descreva em uma frase o propósito do workspace atual.
```

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

## Como Funciona

A extensão do Codex para VS Code não é uma configuração de modelo independente. Ela usa o CLI do Codex local e compartilha a configuração:

1. A extensão inicia o Codex CLI e lê `~/.codex/config.toml`.
2. Se o projeto for trusted e possuir `.codex/config.toml`, o Codex carregará essa configuração adicional.
3. Quando `model_provider` aponta para `acedatacloud`, o API Token é lido de `ACEDATACLOUD_API_KEY`.
4. As requisições são enviadas via protocolo Responses para `https://api.acedata.cloud/v1/responses`.
5. A Ace Data Cloud valida, verifica cotas, encaminha e registra o uso.

Assim, o CLI e a extensão geralmente precisam ser configurados uma única vez. Após validação no terminal, o VS Code usará a mesma configuração.

## Mais Informações

* [Documentação oficial da extensão IDE do Codex](https://developers.openai.com/codex/ide)
* [Configurações da extensão IDE do Codex](https://developers.openai.com/codex/ide/settings)
* [Configuração básica do CLI do Codex](https://developers.openai.com/codex/config-basic)
* [Documentação de serviços OpenAI na Ace Data Cloud](https://platform.acedata.cloud/documents/openai)