Codex Harness

어댑터는 첫 번째 세션이 시작될 때 sandbox 안에서 Codex 브리지 의존성을 부트스트랩해요.

Import

import { codex, createCodex } from '@ai-sdk/harness-codex';

codex 는 기본 설정을 가진 createCodex() 와 동일해요.

기본 사용법

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { codex } from '@ai-sdk/harness-codex';
import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';

const agent = new HarnessAgent({
  harness: codex,
  model: 'gpt-5.6-luna',
});

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});
const session = await agent.createSession({ sandboxSession });

let exitCode = 0;
try {
  const result = await agent.stream({
    session,
    prompt: 'Check the test failures and fix the production code.',
  });

  for await (const part of result.stream) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
} catch (err) {
  exitCode = 1;
  console.error(err);
} finally {
  await session.destroy();
  await sandboxSession.destroy();
  process.exit(exitCode);
}

이 에이전트를 사용하려면 환경 변수에 Vercel Sandbox용 VERCEL_OIDC_TOKEN 과, Codex용으로 인증 섹션에 나열된 변수 중 하나가 포함되어야 해요.

어댑터 설정

createCodex() 를 사용해 런타임을 설정하세요:

const harness = createCodex({
  reasoningEffort: 'high',
  webSearch: true,
  codexConfig: {
    model_verbosity: 'low',
  },
});

설정:

• auth: 인증 모드(auto, direct, ai-gateway) 또는 격리된 인증 환경.
• credentialForwarding: harness 어댑터가 자격 증명을 sandbox 프로세스로 전달하기 직전에 각 자격 증명을 사용자 정의하는 선택적 동기/비동기 콜백. 전달될 자격 증명 값(실제 자격 증명 또는 마스킹된 값)과 이를 노출하는 데 사용되는 환경 변수 이름을 받아요. 이 콜백은 sandbox 프로세스로 전달되는 값만 제어해요. harness 어댑터가 호스트 프로세스에서 발견/읽기/접근할 수 있는 자격 증명을 제한하지는 않아요.
• codexConfig: 추가 네이티브 Codex 설정. 값은 제공된 대로 통과되므로 Codex config.toml 참조의 snake_case 키를 사용하세요. 어댑터의 관리 값은 충돌하는 항목보다 우선해요.
• mcpServers: 서버 이름 키로 된 MCP 서버 정의.
• reasoningEffort: low, medium, high, xhigh, 또는 max.
• webSearch: 라이브 웹 검색 허용.
• port: 브리지 포트 오버라이드.
• startupTimeoutMs: 브리지가 시작될 때까지 기다리는 최대 시간.
• reconnect: 설정된 브리지 WebSocket 연결이 끊긴 후 재연결 타이밍. maxElapsedMs 는 연결 설정과 백오프 지연을 포함한 총 재시도 창을 제어하며 기본값은 30초. initialDelayMs 는 기본 50밀리초, maxDelayMs 는 기본 2초. 이 재시도는 지수 백오프를 사용하며 startupTimeoutMs 와는 별개예요. sandbox, 브리지 프로세스, 또는 브리지 엔드포인트가 영구적으로 사용 불가하면 복구할 수 없어요.
• mintBridgeToken: sandbox ID를 받아 브리지 인증 토큰을 반환하는 동기 함수. 기본적으로 어댑터는 무작위 32바이트 토큰을 생성해요. 커스텀 구현은 적절히 비밀인 토큰을 반환해야 해요.

내장 Tool 필터링 (Built-in Tool Filtering)

Codex는 bash, webSearch, apply_patch, view_image 에 대해 activeTools 와 inactiveTools 를 지원해요. 호스트 tools는 Codex로 보내지기 전에 필터링돼요. 네이티브 Codex 설정은 bash, view_image, webSearch 를 개별적으로 비활성화해요. bash, apply_patch, view_image 가 모두 비활성이면 어댑터는 Codex 환경을 비활성화하고 bash 와 view_image 를 명시적으로 비활성화해요. apply_patch 가 비활성이지만 bash 또는 view_image 가 활성으로 남아 있으면, 어댑터는 패치 실행을 거부하는 Codex PreToolUse 후크를 설치해요. 각 턴을 시작하기 전에 어댑터는 Codex가 후크를 로드하고 신뢰했는지 확인하며, 그렇지 않으면 턴을 실패시킨다... activeTools 에 webSearch 를 포함한다고 해서 스스로 활성화되지는 않아요. 라이브 검색을 허용하려면 createCodex() 에 webSearch: true 를 설정하세요.

const agent = new HarnessAgent({
  harness: createCodex(),
  sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000] }),
  inactiveTools: ['apply_patch'],
});

구조화된 출력 (Structured Output)

Codex는 스키마 기반 HarnessAgent 구조화된 출력 을 지원해요. 어댑터는 Codex app-server의 turn/start outputSchema 매개변수를 통해 JSON Schema를 전달해요.

인증 (Authentication)

auth 설정은 호스트 환경에서 자격 증명을 어떻게 해석하는지 선택해요:

• auto (기본값): 사용 가능하면 AI Gateway 자격 증명을 사용하고, 그다음 직접 OpenAI 자격 증명으로 폴백.
• direct: OpenAI 자격 증명 사용.
• ai-gateway: AI Gateway 자격 증명 사용.

sandbox가 덧셈 요청 변환(additive request transformations)을 지원하면 브리지는 자리표시자를 받고 어댑터는 일치하는 아웃바운드 요청에 자격 증명을 주입해요. 그 기능이 없는 sandbox는 직접 자격 증명 전달을 유지해요.

지원되는 환경 변수:

• VERCEL_OIDC_TOKEN
• AI_GATEWAY_API_KEY
• AI_GATEWAY_BASE_URL
• OPENAI_API_KEY
• CODEX_API_KEY
• OPENAI_BASE_URL
• OPENAI_ORGANIZATION
• OPENAI_PROJECT

적용 가능한 자격 증명 환경 변수가 설정되지 않았고 AI Gateway 인증이 선택되지 않았다면, 어댑터는 호스트 시스템에서 네이티브 구독을 해석하려 시도해요.

자동 감지가 싫을 때 특정 인증 모드를 선택하세요:

const directHarness = createCodex({ auth: 'direct' });
const gatewayHarness = createCodex({ auth: 'ai-gateway' });

process.env 를 읽지 않고 프로그래밍 방식으로 해석된 자격 증명을 사용하려면 인증 환경을 전달하세요:

const harness = createCodex({
  auth: { OPENAI_API_KEY: await resolveOpenAIToken() },
});

제공된 레코드는 인증 발견을 위해 호스트 환경을 대체해요. 인식된 인증 변수만 전달돼요.

OpenAI 호환 엔드포인트의 경우 direct 를 선택하고 OPENAI_BASE_URL 을 설정하세요.

Sandbox

Codex는 노출된 포트가 하나 이상 있는 네트워크 sandbox를 필요로 해요. 예: @ai-sdk/sandbox-vercel:

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});

내장 Tool (Built-in Tools)

어댑터는 agent.tools 를 통해 다음 Codex 내장 기능을 노출해요:

• bash 와 webSearch 는 공통 크로스-harness tool 이름을 사용해요.
• apply_patch 는 Codex의 자유형 패치 문자열을 받아요.
• view_image 는 선택적 detail 및 environment_id 필드와 함께 로컬 이미지 path 를 받아요.

일부 Codex 파일 변형이 보이는 모델 호출 가능 tool에서 비롯되지 않기 때문에 Codex 파일 변경이 동적 fileChange tool 파트로 나타날 수도 있어요.

알려진 제한 사항

Codex는 현재 내장 tool 승인 요청을 지원하지 않아요. 이 어댑터에서는 permissionMode: 'allow-all' 을 사용하세요. 호스트에서 실행되는 AI SDK tool 승인은 여전히 동작해요.

app-server가 스레드를 콜드 재개(cold-resume)해야 할 때 Codex는 apply_patch 와 view_image 의 원시 이벤트를 제공하지 않으므로, 재개된 스레드에서는 그 tool 호출과 결과를 표시할 수 없어요.

관련

• HarnessAgent
• Harness tools
• Harness 어댑터

더 알아보기 (Learn more)

• Claude Code
• Codex
• Pi
• OpenCode
• Deep Agents
• Agent Client Protocol
• Grok Build
• Cline
• Cursor
• fx
• GitHub Copilot

전체 사이트맵