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

# Codex SDK

> Conecte o 4096bytes pelo Codex SDK no código da aplicação

O Codex SDK serve para integrar o Codex à sua aplicação, ferramenta interna ou fluxo de automação. Copie o Base URL, a API Key e o nome do modelo no painel, depois passe os valores de conexão ao instanciar `Codex`.

<Tip>
  Use o Base URL, a API Key e o nome do modelo exibidos no painel. Não copie esses valores de capturas de tela, documentos antigos ou configurações de outros usuários.
</Tip>

## Pré-requisitos

* Você concluiu [Criar uma conta](/pt-BR/quickstart/create-account).
* Você concluiu [Obter uma API Key](/pt-BR/quickstart/get-api-key).
* Node.js 18 ou superior está instalado.
* Codex CLI está instalado e `codex --version` funciona.
* Você tem um projeto TypeScript ou JavaScript.

<Warning>
  A API Key é uma credencial sensível. Não coloque a API Key no código de frontend, não envie para o repositório e não imprima em logs.
</Warning>

## Casos de uso

O Codex SDK é útil quando você precisa colocar o Codex dentro de um fluxo de engenharia existente.

| Cenário                                 | Para que serve                                                                                                                           |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Automação de CI/CD                      | Acionar verificações de código, análise de causa raiz, sugestões de correção ou relatórios estruturados em um pipeline.                  |
| Revisão automática de código            | Executar revisão no GitHub Actions, GitLab CI/CD, Azure DevOps Pipelines ou Jenkins, depois publicar achados como comentários no código. |
| Ferramentas internas de desenvolvimento | Adicionar Codex a plataformas internas para planos de migração, análise de repositório ou diagnóstico de falhas de build.                |
| Assistente de engenharia no app         | Iniciar threads do Codex pela sua aplicação e permitir tarefas de engenharia em várias etapas.                                           |
| Fluxos com saída estruturada            | Pedir saída em JSON schema e chamar SCM, Slack, sistema de tickets ou APIs internas.                                                     |

Se você só quer usar o 4096bytes em um terminal local, comece por [Codex CLI](/pt-BR/clients/codex). Use o SDK quando precisar controlar o Codex por código.

## Instale o SDK

Instale o Codex SDK no seu projeto.

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

O Codex SDK chama o Codex CLI local. Se o Codex CLI ainda não estiver instalado, instale primeiro:

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

Depois da instalação, verifique o comando:

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

Se você usa pnpm ou yarn, use o comando correspondente.

```bash theme={null}
pnpm add @openai/codex-sdk
```

```bash theme={null}
yarn add @openai/codex-sdk
```

## Copie os valores de conexão

<Steps>
  <Step title="Abra API Keys">
    Abra o painel e acesse **API Keys**.
  </Step>

  <Step title="Escolha uma API Key">
    Encontre a API Key que será usada pelo SDK e clique em **Usar chave**.
  </Step>

  <Step title="Copie os valores do SDK">
    Copie o Base URL, a API Key e o nome do modelo exibidos no painel. Substitua todos os placeholders do exemplo pelos valores atuais do painel.
  </Step>
</Steps>

## Configure variáveis de ambiente

Armazene a API Key, o Base URL e o nome do modelo em variáveis de ambiente no servidor.

```bash theme={null}
export CODEX_API_KEY="YOUR_4096BYTES_API_KEY"
export CODEX_BASE_URL="YOUR_BASE_URL"
export CODEX_MODEL="YOUR_MODEL_NAME"
```

Se o seu ambiente usa um arquivo `.env`, escreva:

```bash theme={null}
CODEX_API_KEY=YOUR_4096BYTES_API_KEY
CODEX_BASE_URL=YOUR_BASE_URL
CODEX_MODEL=YOUR_MODEL_NAME
```

## Inicialize o Codex

Crie uma instância de `Codex` no código do servidor. Passe `apiKey` e `baseUrl` ao construtor.

```ts theme={null}
import { Codex } from "@openai/codex-sdk";

const apiKey = process.env.CODEX_API_KEY;
const baseUrl = process.env.CODEX_BASE_URL;
const model = process.env.CODEX_MODEL;

if (!apiKey || !baseUrl || !model) {
  throw new Error("Missing CODEX_API_KEY, CODEX_BASE_URL, or CODEX_MODEL");
}

const codex = new Codex({
  apiKey,
  baseUrl,
});

const thread = codex.startThread({
  model,
});

const result = await thread.run("Descreva o objetivo deste projeto em uma frase.");

console.log(result.finalResponse);
```

Defina `CODEX_API_KEY` com a API Key criada no painel. Copie `CODEX_BASE_URL` e `CODEX_MODEL` do painel.

## Verifique a conexão

Comece com um prompt somente leitura.

```ts theme={null}
const result = await thread.run("Responda apenas ok. Não modifique nenhum arquivo.");
```

Depois que a resposta funcionar, conecte o SDK ao seu fluxo real.

## Exemplo de revisão de código

O cookbook oficial da OpenAI mostra um fluxo de revisão automática de código. O fluxo aciona o Codex em um runner de CI/CD, faz o Codex ler o diff do PR, pede saída estruturada em JSON schema e depois chama a API do SCM para publicar comentários inline.

Você pode usar esse padrão para:

* Revisão automática de PR.
* Fluxos de revisão para repositórios on-premise ou SCMs que não sejam GitHub.
* Criar tickets, enviar notificações no Slack ou atualizar painéis internos de qualidade a partir de resultados estruturados.

Comece com tarefas de revisão somente leitura. Depois que a saída estiver estável, conecte publicação de comentários, criação de tickets ou outras ações que alterem estado externo.

Exemplo oficial: [Build Code Review with the Codex SDK](https://developers.openai.com/cookbook/examples/codex/build_code_review_with_codex_sdk).

Para mais usos do SDK, consulte a documentação oficial da OpenAI: [Codex SDK](https://developers.openai.com/codex/sdk).

## Problemas comuns

<AccordionGroup>
  <Accordion title="Qual Base URL devo usar">
    Use o Base URL atual exibido no painel. Não copie um endereço fixo de documentos, capturas de tela ou configurações antigas.
  </Accordion>

  <Accordion title="Qual nome de modelo devo usar">
    Use o nome do modelo exibido no painel. Copie o valor completo, incluindo maiúsculas, minúsculas, hifens e sufixos de versão.
  </Accordion>

  <Accordion title="Posso chamar pelo frontend do navegador">
    Não é recomendado. Código de frontend expõe a API Key. Chame o SDK pelo servidor, por jobs de backend ou por automações controladas.
  </Accordion>

  <Accordion title="Falha de autenticação">
    Verifique se a API Key foi copiada por completo, se o processo consegue ler as variáveis de ambiente e se o Base URL pertence à mesma conta ou ambiente do painel.
  </Accordion>
</AccordionGroup>