Budowanie z Codex SDK

Codex SDK to biblioteka TypeScript pozwalająca aplikacjom programistycznie uruchamiać wątki, wysyłać prompty i przetwarzać wyniki zamiast polegać na interaktywnym CLI. Wspiera wieloturowe konwersacje w tym samym wątku, wznawianie poprzedniego wątku po ID dla pipeline’ów wieloetapowych oraz wzorce architektoniczne, takie jak wewnętrzne dashboardy udostępniające Codex przez web API lub zaplanowane pipeline’y publikujące nocne podsumowania pull requestów na Slacku.

Twój zespół chce wewnętrzny dashboard, w którym product managerowie mogą kliknąć “Fix this bug” na tickecie Jira i Codex automatycznie przeanalizuje problem, zaproponuje poprawkę i otworzy PR. Albo potrzebujesz nocnego crona, który przegląda wszystkie otwarte PR-y i publikuje podsumowania. Codex CLI obsługuje jednorazowe zadania; SDK pozwala wbudować Codex w twoje własne aplikacje.

Czego się nauczysz o Codex SDK

Działającą integrację TypeScript, która uruchamia wątki Codex, wysyła prompty i przetwarza wyniki
Wzorce dla wieloturowych konwersacji, wznawiania sesji i obsługi błędów
Wskazówki architektoniczne do budowania wewnętrznych narzędzi, dashboardów i zautomatyzowanych pipeline’ów z SDK
Najlepsze praktyki bezpieczeństwa dla zarządzania kluczami API w aplikacjach serwerowych

Rozpoczęcie pracy

SDK wymaga Node.js 18+ i działa tylko po stronie serwera.

npm install @openai/codex-sdk

Podstawowe użycie

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const turn = await thread.run(
  "Analyze the test failures in the CI logs and propose fixes"
);

console.log(turn.finalResponse);

Metoda run() wysyła prompt do Codex, czeka na zakończenie pracy agenta (w tym odczyt plików, edycje i wykonywanie poleceń) i zwraca obiekt tury. Końcowy tekst agenta znajduje się w turn.finalResponse; pełna lista wykonanych akcji w turn.items, a przebiegi strumieniowe udostępniają liczbę tokenów w turn.usage.

Wieloturowe konwersacje

Wywołaj run() ponownie na tym samym wątku, aby kontynuować konwersację:

// First turn: analyze
const analysis = await thread.run(
  "Review the authentication module for security issues"
);

// Second turn: fix what was found
const fixes = await thread.run(
  "Implement the fixes you identified. Run the test suite after each change."
);

Wznawianie wcześniejszych wątków

Jeśli musisz kontynuować poprzednią sesję (np. dwuetapowy pipeline), podaj ID wątku:

const threadId = "01912345-abcd-7890-ef01-234567890abc";
const thread = codex.resumeThread(threadId);
const result = await thread.run("Pick up where you left off and finish the migration");

import { Codex } from "@openai/codex-sdk";

async function fixBug(issueDescription: string, repo: string) {
  const codex = new Codex();
  const thread = codex.startThread();

  // Step 1: Diagnose
  const diagnosis = await thread.run(
    `Given this bug report, identify the root cause in the codebase:\n\n${issueDescription}`
  );

  // Step 2: Fix
  const fix = await thread.run(
    "Implement the minimal fix. Run tests to verify. Do not refactor unrelated code."
  );

  // Step 3: Validate
  const validation = await thread.run(
    "Run the full test suite and lint checks. Report the results."
  );

  return {
    diagnosis: diagnosis.finalResponse,
    fix: fix.finalResponse,
    validation: validation.finalResponse,
  };
}

Wzorce architektoniczne

Wewnętrzny dashboard

Zbuduj web API udostępniające operacje Codex dla wewnętrznych narzędzi:

// POST /api/codex/task
app.post("/api/codex/task", async (req, res) => {
  const { prompt, projectPath } = req.body;

  const codex = new Codex();
  const thread = codex.startThread();

  try {
    const turn = await thread.run(prompt);
    res.json({
      result: turn.finalResponse,
      status: "completed"
    });
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    res.status(500).json({ error: message });
  }
});

Zaplanowany pipeline

Połącz SDK ze schedulerem zadań dla cyklicznych operacji:

import { CronJob } from "cron";

const nightlyReview = new CronJob("0 2 * * *", async () => {
  const codex = new Codex();
  const thread = codex.startThread();

  const turn = await thread.run(
    "Review all PRs opened in the last 24 hours. " +
    "For each PR, summarize the changes and flag any security concerns. " +
    "Output a JSON array with pr_number, summary, and risk_level fields."
  );

  await postToSlack("#engineering", turn.finalResponse);
});

nightlyReview.start();

SDK vs codex exec vs Cloud Tasks

Funkcja	SDK	`codex exec`	Cloud Tasks
Kontrola programistyczna	Pełna	Flagi CLI + stdin/stdout	Web UI + integracje
Wieloturowe konwersacje	Natywne	Wznów z `--last`	Follow-up w wątku
Środowisko	Twój serwer	Twoja maszyna / CI runner	Kontenery OpenAI
Najlepsze do	Niestandardowe aplikacje, dashboardy	Skrypty CI/CD, jednorazowa automatyzacja	Delegowana praca, mobilna segregacja

Gdy integracje z Codex SDK nie działają

Błędy uwierzytelniania: SDK używa tych samych poświadczeń co CLI. Upewnij się, że CODEX_API_KEY jest ustawiony lub uruchom codex login na maszynie uruchamiającej SDK.
Timeout wątku: Długotrwałe zadania mogą trafić na timeout API. Dziel złożoną pracę na mniejsze wywołania run() zamiast jednego masywnego promptu.
Limity rate: SDK podlega tym samym limitom co twój plan. Monitoruj użycie za pomocą /status w CLI lub dashboardu użycia.
Nieaktualny stan wątku: Jeśli wznawiasz wątek sprzed kilku dni, codebase mógł się zmienić. Dołącz kontekst o ostatnich zmianach w swoim follow-up prompt.

Dokąd dalej z Codex SDK

Tryb nieinteraktywny — Dla prostszych potrzeb skryptowych codex exec może wystarczyć
GitHub Action — Gotowa integracja CI/CD bez pisania kodu SDK
Zarządzanie kosztami — Użycie SDK liczy się w ramach limitów twojego planu