Cline 하네스

Cline 하네스 (Cline Harness)

Cline 하네스 어댑터는 HarnessAgent를 Cline SDK 에이전트 런타임(@cline/agents)에 연결해요. 이 런타임은 호스트에서 인프로세스 Node 라이브러리로 실행돼요 — 브리지가 없고, 내장 도구는 세션 샌드박스에 대해 실행되므로 모델이 추론하는 워크스페이스가 완전히 샌드박스 안에 있어요.

참고: 하네스 패키지는 실험적이에요. 이 초기 API가 더 다듬어지면서 릴리스 사이에 파괴적인 변경이 예상돼요.

출처: 문서

본문

셋업 (Setup)

npm install @ai-sdk/harness @ai-sdk/harness-cline @ai-sdk/sandbox-vercel

Cline 런타임에는 부트스트랩 단계가 없어요: 세션이 시작될 때 샌드박스 안에 아무것도 설치되지 않아요.

Import

import { cline, createCline } from '@ai-sdk/harness-cline';

cline은 기본 구성으로 createCline()을 호출한 것과 같아요.

기본 사용법 (Basic Usage)

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

const agent = new HarnessAgent({
  harness: cline,
  model: 'anthropic/claude-opus-5',
});

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  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이 포함돼 있는지 확인하세요. 기본 auto 인증 모드를 사용할 때 같은 토큰이 AI Gateway를 통한 모델 호출을 인증해요.

어댑터 설정 (Adapter Settings)

createCline()으로 런타임을 구성하세요:

const harness = createCline({
  auth: 'direct',
});

설정:

• auth: 인증 모드(auto, direct, ai-gateway) 또는 격리된 인증 환경.
• mcpServers: 서버 이름별 MCP 서버 정의.
• providerId: Cline LLM provider id(예: anthropic, openai, gemini). 생략하면 직접 인증이 Cline 백엔드를 사용해요. 명시적 커스텀 provider는 직접 인증에만 적용돼요.
• apiKey: provider API 키. 생략하면 Cline 게이트웨이가 구성된 provider의 환경 변수로 폴백해요.
• baseUrl: 커스텀 provider 엔드포인트.
• headers: provider로 보내는 추가 헤더.
• reasoningEffort: 추론 가능한 모델의 추론 노력. none, minimal, low, medium, high, xhigh, max를 지원해요. none은 추론을 비활성화하고, 그 외 모든 값은 그 수준으로 추론을 활성화해요. 생략하면 Cline SDK가 추론 동작을 선택해요.
• maxIterations: 턴당 에이전트 루프 반복에 대한 안전 상한.

추가 운영 지침을 제공하려면 HarnessAgent에서 instructions 설정을 사용하세요. 어댑터가 이를 Cline의 시스템 프롬프트에 덧붙여요.

구조화 출력 (Structured Output)

Cline은 요청된 JSON Schema를 인자로 쓰는 터미널 도구를 요구하는 방식으로 스키마 기반 HarnessAgent 구조화 출력을 지원해요. 이는 외부 도구 지원이 있는 provider/모델 라우트가 필요해요. providerId: 'openai-codex-cli'는 HarnessCapabilityUnsupportedError를 throw해요.

인증 (Authentication)

auth 설정은 Cline이 호스트 환경에서 읽을 자격 증명을 선택해요:

• auto(기본값): 사용 가능하면 AI Gateway 자격 증명을, 그렇지 않으면 직접 Cline 자격 증명을 사용.
• direct: CLINE_API_KEY와 선택 CLINE_API_BASE_URL을 사용.
• ai-gateway: AI_GATEWAY_API_KEY 또는 VERCEL_OIDC_TOKEN과 선택 AI_GATEWAY_BASE_URL을 사용.

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

const harness = createCline({ auth: 'ai-gateway' });

호스트가 런타임에 자격 증명을 해결할 때 인증 환경을 전달하세요:

const harness = createCline({
  auth: {
    AI_GATEWAY_API_KEY: await resolveGatewayToken(),
    AI_GATEWAY_BASE_URL: 'https://ai-gateway.vercel.sh',
  },
});

제공된 record는 인증 발견을 위해 호스트 환경을 대체하므로 CLINE_API_KEY로 직접 인증을 선택할 수도 있어요.

CLINE_API_BASE_URL은 Cline의 백엔드 루트 URL이고, SDK의 /api/v1 provider 경로가 그 뒤에 붙어요. AI Gateway의 경우 어댑터는 대신 Gateway 자격 증명과 그 /v1 엔드포인트로 Cline의 인프로세스 provider 구성을 재정의해요. 명시적 Gateway 모드나 제공된 인증 환경이 Gateway를 선택할 때 직접 Cline 자격 증명은 폴백으로 절대 사용되지 않아요.

샌드박스 (Sandbox)

Cline 런타임은 호스트에서 실행되고 샌드박스 포트가 필요 없으므로, 포트 없는 구성을 포함해 어떤 네트워크 샌드박스든 작동해요:

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

모든 내장 도구는 샌드박스 세션의 파일/exec 표면을 통해 샌드박스 파일시스템에서 동작해요.

내장 도구 (Built-in Tools)

어댑터는 agent.tools를 통해 다음 내장 도구를 노출해요:

• read
• write
• edit
• bash
• grep
• glob
• ls

모든 내장 도구는 샌드박스 지원이에요: bash는 세션 작업 디렉터리에서 실행되고 상대 파일 경로는 그 기준으로 해결돼요.

Cline은 permissionMode가 allow-reads 또는 allow-edits일 때 내장 도구 승인 요청, activeTools/inactiveTools를 통한 네이티브 내장 도구 필터링, 호스트 실행 AI SDK 도구 승인을 지원해요.

스킬 (Skills)

하네스가 제공한 스킬은 샌드박스 HOME(~/.agents/skills/<name>/SKILL.md)에 기록되고 시스템 프롬프트 섹션으로 모델에 알려져요. 모델은 작업이 요구할 때 read 도구로 스킬의 전체 내용을 로드해요.

세션 수명주기 (Session Lifecycle)

대화 상태는 호스트 프로세스 런타임에 있어요. detach/stop 시 어댑터는 대화 기록을 샌드박스 워크스페이스(세션 작업 디렉터리의 .cline-harness/history.json)에 보존해서, 이후 프로세스가 호출자가 샌드박스를 다시 붙인 후 세션을 재개할 수 있게 해요. 런타임이 호스트 상주이므로, 일시 중단된 턴은 (손실 없이 붙는 대신) 보존된 기록에서 다시 실행-계속돼요(Pi 어댑터와 같은 트레이드오프).

수동 압축(doCompact)은 독립 실행형 Cline 런타임에서 지원되지 않고 HarnessCapabilityUnsupportedError를 throw해요.

더 알아보기 (Learn more)

• HarnessAgent
• Harness 도구
• Harness 어댑터
• Cursor
• fx
• GitHub Copilot