Codex SDK

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.

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.

Pré-requisitos

Você concluiu Criar uma conta.
Você concluiu Obter uma API Key.
Node.js 18 ou superior está instalado.
Codex CLI está instalado e codex --version funciona.
Você tem um projeto TypeScript ou JavaScript.

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.

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. Use o SDK quando precisar controlar o Codex por código.

Instale o SDK

Instale o Codex SDK no seu projeto.

npm install @openai/codex-sdk

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

npm install -g @openai/codex

Depois da instalação, verifique o comando:

codex --version

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

pnpm add @openai/codex-sdk

yarn add @openai/codex-sdk

Copie os valores de conexão

Abra API Keys

Abra o painel e acesse API Keys.

Escolha uma API Key

Encontre a API Key que será usada pelo SDK e clique em Usar chave.

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.

Configure variáveis de ambiente

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

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:

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.

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.

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. Para mais usos do SDK, consulte a documentação oficial da OpenAI: Codex SDK.

Problemas comuns

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.

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.

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.

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.

Início rápido

Clientes

SDKs

Pré-requisitos

Casos de uso

Instale o SDK

Copie os valores de conexão

Configure variáveis de ambiente

Inicialize o Codex

Verifique a conexão

Exemplo de revisão de código

Problemas comuns

​Pré-requisitos

​Casos de uso

​Instale o SDK

​Copie os valores de conexão

​Configure variáveis de ambiente

​Inicialize o Codex

​Verifique a conexão

​Exemplo de revisão de código

​Problemas comuns

Pré-requisitos

Casos de uso

Instale o SDK

Copie os valores de conexão

Configure variáveis de ambiente

Inicialize o Codex

Verifique a conexão

Exemplo de revisão de código

Problemas comuns