Budowanie z Codex SDK

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

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 result = await thread.run(
  "Analyze the test failures in the CI logs and propose fixes"
);

console.log(result);

Metoda run() wysyła prompt do Codex, czeka na zakończenie pracy agenta (w tym odczyt plików, edycje i wykonywanie poleceń) i zwraca końcowy wynik.

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, fix, validation };
}

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 result = await thread.run(prompt);
    res.json({
      threadId: thread.id,
      result,
      status: "completed"
    });
  } catch (error) {
    res.status(500).json({ error: 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 result = 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", result);
});

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 coś nie działa

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.

Co dalej

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