프로덕션 환경의 Cline: 세션 구성과 안전한 복구
ClineCore 세션 구성, 런타임 설정과 공급자 구성의 분리, 안전한 재시도 및 복구 규칙 설계를 안내하는 실용 가이드입니다.
요약 · TL;DR
ClineCore에서는 백엔드 모드, 기능, 도구 정책, 자동화 같은 런타임 선택 사항과 각 세션에 설정하는 공급자 및 모델을 분리합니다. 이 가이드에서는 이러한 구분을 명확히 하고, 무작정 작업을 반복하는 대신 세션 ID와 영속 상태를 바탕으로 복구 동작을 설계하는 방법을 설명합니다.
핵심 요점
- 런타임, 도구 권한, 공급자·모델 구성은 각각 별개의 결정으로 관리하세요.
- 재시도하기 전에 세션 ID와 영속 메시지를 활용해 실패 원인을 살펴보세요.
- 재시도하면 부수 효과가 중복될 수 있습니다. 워크플로에 맞는 체크포인트와 복구 규칙을 정하세요.
- API 참조에는 세션 작업이 설명되어 있지만 재시도 의미, 체크포인트 형식, 공급자 호환성 보장은 명시되어 있지 않습니다.
목차 (9)
ClineCore를 사용하면 애플리케이션에서 세션 생성, 런타임 선택, 도구 권한, 세션 기록을 제어할 수 있습니다. 프로덕션 워크플로를 운영할 때 핵심 설계 과제는 실패한 호출을 재시도할지 여부만이 아닙니다. 작업을 다시 실행하기 전에 이미 어떤 일이 일어났는지 파악하는 방법이 중요합니다.
아래 구성은 설명을 위한 예시이며, 테스트를 거친 배포 절차가 아닙니다. ClineCore API 참조에서 여기서 다루는 옵션과 메서드를 확인할 수 있습니다. 정확한 타입과 동작은 설치한 SDK 버전의 문서를 참고하세요.
런타임 설정과 모델 설정 분리하기
유용한 구성 경계는 세 부분으로 나뉩니다.
- 런타임: 백엔드 선택, 클라이언트 식별 정보, 선택적 원격 또는 허브 연결 설정
- 실행 정책: 도구 정책, 기능, 자동화 API 활성화 여부
- 세션 모델 구성: 특정 세션에 사용할 공급자 ID, 모델 ID, 인증 정보, 작업공간 경로, 도구 사용 가능 여부
이렇게 구분하면 모델을 변경하더라도 런타임 정책을 독립적으로 관리하기 쉽습니다. 그렇다고 공급자별 필드를 서로 바꿔 쓸 수 있는 것은 아닙니다. providerId, modelId, apiKey는 선택한 공급자에 맞는 값이어야 합니다. API 참조는 모든 공급자나 엔드포인트와의 호환성을 보장하지 않습니다.
런타임을 만들고 세션 시작하기
사전 준비: 배포하려는 Cline SDK 버전을 설치하고, 애플리케이션의 비밀 정보 관리 방식으로 인증 정보를 제공하며, 에이전트가 사용할 수 있는 도구를 정합니다. 인증 정보를 로그나 세션 메타데이터에 넣지 마세요.
import { ClineCore } from "@cline/sdk"
const cline = await ClineCore.create({
clientName: "repo-maintenance-worker",
backendMode: "auto",
toolPolicies: {},
automation: false,
})
const session = await cline.start({
prompt: "Inspect the repository and report failing tests. Do not modify files.",
source: "scheduled-check",
interactive: false,
sessionMetadata: { jobId: "job-123" },
config: {
providerId: "anthropic",
modelId: "claude-sonnet-4-6",
apiKey: process.env.ANTHROPIC_API_KEY,
systemPrompt: "Follow the task scope and report actions taken.",
cwd: process.cwd(),
workspaceRoot: process.cwd(),
enableTools: true,
enableSpawnAgent: false,
enableAgentTeams: false,
},
})
console.log(session.sessionId)
위의 공급자 및 모델 값은 API 참조의 예시를 따른 것이며, 권장 설정이나 해당 예시를 넘어서는 공급자 호환성 보장이 아닙니다. 참조 문서에는 backendMode 값으로 auto, local, hub, remote가 나와 있으며 선택적 hub 및 remote 설정도 설명되어 있습니다. 특정 배포에 가장 적합한 모드는 정의되어 있지 않습니다. 적절한 모드를 선택한 다음 실제 환경에서 연결 및 권한을 검증하세요.
빈 toolPolicies 객체는 보안 정책이 아닙니다. 설치한 SDK에서 지원하는 정책 타입에 따라 기본 정책과 세션별 정책을 명시적으로 설정하세요. 클라이언트가 도구 실행기나 승인 콜백을 제공하는 경우 capabilities를 사용하고, 제한된 작업이 실제로 거부되는지 테스트하세요.
세션 상태를 기준으로 재시도 규칙 만들기
네트워크 오류나 작업자 시간 초과만으로 에이전트가 작업을 완료하기 전에 멈췄다고 단정할 수는 없습니다. 원래 프롬프트를 반복하면 편집, 외부 호출 또는 기타 부수 효과가 중복될 수 있습니다. API 참조에는 get, readMessages, getAccumulatedUsage, abort, stop, restore가 나와 있지만 자동 재시도, 정확히 한 번 실행, 체크포인트 내용은 명시되어 있지 않습니다.
보다 안전한 운영 절차는 다음과 같습니다.
- 세션 ID를 즉시 기록합니다. 작업 ID와 함께 영속 저장해 작업자가 재시작되더라도 같은 세션을 찾을 수 있게 합니다.
- 실패 유형을 분류합니다. 실패가 확정된 경우와 완료 여부가 불확실한 시간 초과 또는 연결 끊김을 구분합니다.
- 다시 제출하기 전에 확인합니다.
get과readMessages로 세션 메타데이터와 영속 메시지를 확인합니다. 필요한 경우 누적 사용량을 운영상 참고 정보로 살펴볼 수 있지만, 특정 작업의 완료를 증명하는 자료로 보아서는 안 됩니다. - 복구 방식을 신중히 선택합니다. 세션이 아직 활성 상태라면 기다릴지, 중단할지, 정지할지 결정합니다. 작업을 이어가려면
send에 세션 ID와 후속 프롬프트를 전달할 수 있습니다. 체크포인트를 사용할 수 있고 적절하다면 API에서restore를 제공합니다. 필요한 입력과 동작 의미는 SDK 문서를 확인하세요. - 부수 효과를 반복해도 안전하게 처리합니다. 에이전트 세션 상태 바깥에서 발생하는 작업에는 적절한 경우 애플리케이션 수준의 멱등성 키, 중복 제거 또는 사람의 승인 절차를 적용하세요.
start를 무조건 재시도하는 루프로 감싸지 마세요. 호출자가 응답을 받지 못했더라도 최초 요청으로 세션이 생성되었을 수 있습니다. 이런 상황에서 start를 다시 호출하면 별도의 작업이 만들어질 수 있습니다. API 참조에는 start의 멱등성 키가 문서화되어 있지 않으므로 그런 키가 있다고 가정하지 마세요.
프로덕션에서 흔히 발생하는 문제 해결
세션이 잘못된 런타임으로 시작됨
선택한 백엔드 모드와 민감하지 않은 세션 식별 정보를 로그에 남기세요. 작업자가 실행되는 환경에 맞춰 backendMode, hub, remote 옵션을 확인합니다. 참조 문서는 이를 런타임 선택 옵션으로 설명하지만 자동 장애 조치 동작은 문서화하지 않습니다. 추정한 대체 동작에 의존하지 말고 사용 중인 SDK 버전에서 auto가 어떻게 작동하는지 확인하세요.
도구를 사용할 수 없거나 예상과 달리 허용됨
세션의 config와 해당되는 기본 및 세션별 toolPolicies 또는 capabilities를 모두 확인하세요. 참조 문서는 이를 도구 정책과 클라이언트가 관리하는 실행기·승인 제어로 설명합니다. 제공된 API 요약에는 정책 우선순위가 나와 있지 않으므로 설치한 SDK 문서에서 우선순위를 확인하고 허용 및 거부 사례를 모두 테스트하세요.
실행 중 작업자의 연결이 끊김
세션 ID와 작업 ID를 내구성 있는 애플리케이션 상태로 보관하세요. 재시작한 뒤에는 기존 세션을 확인하고 send로 이어갈지, 정지할지, 체크포인트에서 복구할지 결정합니다. 응답이 없다는 이유만으로 작업이 완료되었다고 판단하지 마세요.
공급자 또는 모델 구성에 실패함
선택한 설정에 대해 공급자 및 Cline 문서에서 공급자 ID, 모델 ID, 인증 정보, 엔드포인트 요구 사항을 확인하세요. ClineCore 참조에는 공급자·모델 구성 형식이 나와 있지만, 임의의 OpenAI 호환 엔드포인트나 공급자별 매개변수가 수정 없이 작동한다고 보장하지는 않습니다.
프로덕션 체크리스트
- 세션 ID를 내구성 있게 저장하고 로그 및 메타데이터에서 비밀 정보를 제외하세요.
- 도구 권한을 명시적으로 설정하고 승인 및 거부 경로를 테스트하세요.
- 작업 실패와 결과를 알 수 없는 작업을 구분하세요.
- 작업을 다시 제출하기 전에 세션 기록을 확인하세요.
- 외부 부수 효과는 멱등하게 처리하거나 재실행 전에 승인을 요구하세요.
- 실제 배포 환경에서 백엔드와 공급자 동작을 검증하세요.
- SDK에 문서화된 수명 주기 절차에 따라 정상 종료 시 런타임 리소스를 정리하세요.
실무 원칙은 간단합니다. 무엇을 재시도하는지 파악한 뒤에만 재시도하세요. ClineCore는 세션 및 복구 관련 API를 제공하지만, 프로덕션에서 안전하게 동작하려면 애플리케이션 차원의 내구성 있는 작업 추적, 권한 설계, 중복 부수 효과 처리 방식이 여전히 중요합니다.
FAQ
어떤 ClineCore 설정이 모델 공급자와 독립적인가요?
`clientName`, `backendMode`, 선택적 허브 또는 원격 설정, 기능, 도구 정책, 자동화 같은 런타임 옵션은 세션의 공급자 및 모델 필드와 별개입니다. 정확한 옵션 동작은 사용 중인 SDK 버전의 문서에서 확인하세요.
시간 초과 후 ClineCore.start를 재시도해야 하나요?
무작정 재시도하지 마세요. 시간 초과만으로 세션이 생성되었는지 알 수는 없습니다. 확인 가능한 경우 세션 ID를 영속 저장하고 새 작업을 시작하기 전에 기존 세션을 살펴보세요. 제공된 API 참조에는 `start`의 멱등성 키가 문서화되어 있지 않습니다.
ClineCore로 실패한 세션을 복구할 수 있나요?
API 참조에는 `restore` 메서드가 나와 있지만, 제공된 요약에는 필요한 입력이나 체크포인트의 동작 의미가 명시되어 있지 않습니다. 이를 기반으로 복구 방식을 설계하기 전에 설치된 SDK 문서를 확인하세요.
이 구성은 모든 OpenAI 호환 공급자에서 작동하나요?
인용된 ClineCore 참조만으로는 이를 확인할 수 없습니다. 공급자 호환성과 허용되는 매개변수는 해당 엔드포인트 및 선택한 공급자 구성에 대해 문서화된 지원 여부에 따라 달라집니다. 서로 바꿔 쓸 수 있다고 가정하지 말고 확인하세요.
관련 글
Guides
API 인시던트 진단을 위한 Cline 구성
API 인시던트 진단을 위해 Cline SDK 세션을 구성하고, 프로바이더에 종속되지 않는 런타임 설정을 선택하며, 관찰 가능한 장애 신호를 바탕으로 문제를 해결합니다.
Guides
안정적인 재시도·복구 결정을 위한 Hugging Face 모델 평가
운영 환경의 재시도 및 복구 결정을 비교할 수 있도록 작업별로 재현 가능한 Hugging Face 모델 평가를 설계합니다.
Guides
개인정보 보호를 고려한 코딩 세션을 위한 ClineCore 설정
ClineCore 세션 설정, 민감한 데이터 노출 제한, 일반적인 설정 문제 해결을 위한 실용 가이드입니다.
Guides
출처를 제시하는 문서 Q&A를 위해 Cline에서 OpenAI 호환 제공자 구성하기
Cline SDK에서 OpenAI 호환 제공자를 구성하고, 검증 가능한 출처를 반환하는 문서 질의응답 워크플로를 만들어 보세요.