Cline AI란? VS Code 설치, API 연결, 안전한 코드 작업 방법
Cline AI를 처음 사용하는 개발자를 위한 완전한 가이드입니다. Cline agent와 모델 API의 역할, VS Code 확장 설치, BetterToken OpenAI Compatible endpoint 연결, 읽기 전용 테스트, Plan/Act, 권한, MCP, 비용, 문제 해결까지 설명합니다.
목차
Cline은 Cline AI, ClineAI, Cline agent라는 이름으로도 검색되는 오픈 소스 AI 코딩 에이전트입니다. 에디터와 터미널 안에서 작동하며, VS Code에서는 프로젝트 파일 읽기, 코드 검색, 파일 수정, 터미널 명령 실행, 브라우저 사용, MCP 도구 호출을 수행할 수 있습니다. 어떤 작업을 허용할지는 사용자가 권한으로 통제합니다. Cline 자체는 언어 모델이 아니며, 선택한 모델 제공자에 연결해 추론과 코드 생성을 수행합니다.
이 글에서는 Cline이 무엇인지, VS Code에 설치하는 방법, OpenAI Compatible 방식으로 자신의 API를 연결하는 방법, 불필요한 권한을 주지 않고 설정을 검증하는 방법을 순서대로 설명합니다. 설정 예시는 BetterToken을 사용하지만 기본 절차는 다른 호환 endpoint에도 적용할 수 있습니다.
먼저 알아둘 핵심
- Cline은 코딩 에이전트이며 모델 자체가 아닙니다.
- VS Code 확장을 설치한 뒤 Cline의 모델 접근 방식 또는 자신의 API Key를 선택할 수 있습니다.
- BetterToken을 사용할 때는
OpenAI Compatible을 선택하고 Base URL에https://www.bettertoken.ai/v1을 입력합니다.- 첫 작업은 읽기 전용으로 시작하세요. 자동 수정, 터미널 명령, 브라우저, MCP, YOLO Mode를 바로 켜지 마세요.
Cline, VS Code, 모델 API가 각각 하는 일
일반적인 Cline 작업은 세 계층으로 구성됩니다.
- VS Code는 프로젝트, 대화, diff, 터미널 출력, 승인 요청을 보여 줍니다.
- Cline agent는 컨텍스트를 수집하고 도구를 선택하며 작업 단계를 구성하고 권한을 확인합니다.
- 모델 API는 컨텍스트를 받아 분석, 코드 또는 다음 도구 호출 제안을 반환합니다.
따라서 결과는 확장 프로그램만으로 결정되지 않습니다. 모델은 추론과 코드 품질, 속도, 컨텍스트 크기, 비용에 영향을 줍니다. Cline 설정은 모델이 어떤 파일과 도구를 사용할 수 있는지, 어떤 동작에 사용자의 승인이 필요한지를 결정합니다.
이 점이 일반적인 에디터 채팅과의 가장 큰 차이입니다. 단순 채팅은 주로 텍스트를 생성하지만, Cline은 정보를 읽고, 다음 단계를 제안하고, 도구를 실행하고, 결과를 다시 분석하는 에이전트 루프를 반복합니다. 작업이 끝나거나 사용자의 판단이 필요한 지점까지 이 과정이 이어집니다.
VS Code에 Cline 설치하기
- VS Code를 엽니다.
Ctrl/Cmd + Shift + X를 눌러 Extensions를 엽니다.Cline을 검색하고 공식 Cline 확장 프로그램을 선택합니다.- Install을 클릭합니다.
- 설치가 끝나면 Activity Bar에서 Cline을 엽니다.
- 시작 화면에서 Use your own API key를 선택해 사용자 지정 제공자를 설정합니다.
설치 후 아이콘이 보이지 않으면 Developer: Reload Window를 실행하거나 VS Code를 완전히 재시작하세요. 버전에 따라 일부 문구는 달라질 수 있지만 Provider와 모델 설정은 Cline 사이드바에서 찾을 수 있습니다.
API 연결 전에 준비할 것
Cline을 BetterToken에 연결하려면 다음이 필요합니다.
- BetterToken 계정
- 별도로 만든 API Key
- 모델 및 가격 페이지에서 복사한 현재 Model ID
- endpoint에 접근할 수 있는 네트워크
- 최신 버전의 VS Code와 Cline 확장 프로그램
API Key는 비밀번호처럼 관리해야 합니다. 저장소, 스크린샷, 로그, Issue, 공개 설정 파일에 노출하지 마세요. 팀에서는 사용자나 환경마다 별도 Key를 만들면 사용 한도, 폐기, 요청 추적을 관리하기 쉽습니다.
Cline에 BetterToken API 설정하기
Cline 설정을 열고 다음 값을 입력합니다.
| 항목 | 값 |
|---|---|
| API Provider | OpenAI Compatible |
| Base URL | https://www.bettertoken.ai/v1 |
| API Key | 자신의 BetterToken API Key |
| Model | 모델 페이지의 현재 정확한 Model ID |
설정할 때 다음 사항을 지키세요.
- Base URL은
https://www.bettertoken.ai/v1입니다. 뒤에/chat/completions,/responses또는 다른 요청 경로를 붙이지 마세요. - Model ID는 오래된 글이나 이미지가 아니라 현재 모델 목록에서 정확히 복사하세요.
- 일반적으로 추가
User-Agent나 사용자 지정 Header는 필요하지 않습니다. 상위 서비스의 공식 문서에서 명시적으로 요구할 때만 추가하세요. - 모든 모델이 반드시 같은 프로토콜을 쓰는 것은 아닙니다. BetterToken의 Cline 설정 문서에서 현재 검증된 호환 범위를 확인하세요.
이전에 OpenAI 환경 변수를 설정했고 Cline이 계속 예전 endpoint를 사용한다면 macOS 또는 Linux의 현재 셸에서 다음을 실행하세요.
unset OPENAI_API_KEY
unset OPENAI_BASE_URLWindows PowerShell에서는 다음을 실행합니다.
Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinueDone으로 저장한 뒤 Cline을 다시 로드하세요. Base URL, API Key, Model을 바꾼 뒤에는 새 작업을 만드는 편이 좋습니다. 이전 세션의 오래된 설정이나 지나치게 큰 컨텍스트가 이어지는 것을 막을 수 있습니다.
첫 요청은 읽기 전용으로 테스트하기
첫 작업부터 “프로젝트 전체를 리팩터링해 줘”라고 요청하지 마세요. 일반 코드 파일 하나를 열고 다음 프롬프트를 보냅니다.
현재 열려 있는 파일만 읽어 주세요. 이 파일의 목적, 주요 입력과 출력을 설명하세요. 파일을 수정하지 말고 터미널 명령도 실행하지 마세요.첫 테스트가 성공했다고 볼 수 있는 조건은 다음과 같습니다.
- Cline이 파일 내용에 근거해 설명한다.
- 인증, 모델, 연결 오류가 나타나지 않는다.
- 파일 수정이나 명령 실행이 발생하지 않는다.
- BetterToken Dashboard에 요청과 Token 사용량이 표시된다.
Cline은 답하지만 Dashboard에 기록이 없다면 현재 Provider가 실제로 OpenAI Compatible인지 확인한 뒤 Base URL, API Key, Model ID, 네트워크 프록시를 점검하세요. 지원을 요청할 때도 전체 Key가 보이는 스크린샷을 공개하지 마세요.
Cline이 코드 작업을 수행하는 과정
일반적인 작업은 다음 순서로 진행됩니다.
- 사용자가 원하는 결과, 허용된 변경 범위, 완료 조건을 설명합니다.
- Cline이 관련 파일을 읽고 연관 코드를 찾습니다.
- 모델이 추가 읽기, 파일 수정, 테스트 실행, 질문 등의 다음 단계를 제안합니다.
- Cline이 권한 범주를 확인하고 필요하면 승인을 요청합니다.
- 도구 결과가 컨텍스트에 추가되고 모델이 다음 행동을 결정합니다.
- 사용자가 최종 diff, 명령 출력, 테스트 결과를 검토합니다.
접근 방법이 명확하지 않은 작업은 Plan Mode로 시작하세요. 이 모드에서 Cline은 코드베이스를 조사하고 해결책을 논의할 수 있지만 파일을 수정하거나 명령을 실행하지 않습니다. 계획을 확인한 뒤 Act Mode로 전환합니다.
Plan Mode 예시입니다.
로그인 endpoint가 가끔 HTTP 500을 반환하는 이유를 조사하세요. 관련 코드와 테스트만 읽고, 가능성이 높은 원인, 영향을 받는 파일, 가장 작고 안전한 수정 방안을 정리하세요. 코드는 변경하지 마세요.계획을 검토한 뒤 Act Mode에서 다음과 같이 요청합니다.
승인된 최소 수정만 적용하세요. 로그인 endpoint와 직접 관련된 테스트만 변경하세요. 가장 관련 있는 테스트를 실행하고 모두 통과하면 중단하세요. 다른 모듈은 리팩터링하지 마세요.이 방식은 “로그인을 고쳐 줘” 같은 모호한 요청보다 결과를 훨씬 쉽게 검증할 수 있습니다.
처음 사용할 때 권장하는 권한
보수적인 설정으로 시작하세요.
| 권한 | 초기 권장값 |
|---|---|
| Read project files | 켜기 |
| Read all files / workspace 외부 | 끄기 |
| Edit project files | 매번 확인하거나 처음에는 끄기 |
| Execute safe commands | 첫 몇 번은 수동 승인 |
| Execute all commands | 끄기 |
| Use the browser | 명확한 필요가 있을 때만 켜기 |
| Use MCP servers | 특정 서버를 검증한 뒤 켜기 |
| YOLO Mode | 실제 프로젝트에서는 끄기 |
명령을 승인할 때 이름만 보지 말고 인자, 작업 디렉터리, 대상 파일을 확인하세요. npm test와 npm install의 영향은 다르며, git status와 git push도 마찬가지입니다.
Checkpoints와 Git은 로컬 코드 변경을 되돌리는 데 도움이 되지만 이미 전송된 네트워크 요청, 삭제된 클라우드 데이터, 노출된 시크릿을 복원할 수는 없습니다. 중요한 저장소에서는 branch 또는 worktree를 사용하고 민감한 파일을 불필요하게 에이전트의 접근 범위에 두지 마세요.
API, MCP, Cline Rules는 서로 다릅니다
세 개념의 역할은 다음과 같습니다.
- 모델 API는 Cline이 분석, 계획, 생성을 수행할 수 있는 지능을 제공합니다.
- MCP는 데이터베이스, 외부 서비스, 사내 시스템 같은 외부 도구와 데이터 소스를 추가합니다.
- Cline Rules는 코딩 규칙, 아키텍처 제한, 테스트 요구 사항, 작업 방식을 전달합니다.
MCP는 모델 API를 대체하지 않습니다. 안정적인 순서는 먼저 API를 연결해 읽기 전용 테스트를 통과하고, 다음으로 프로젝트 Rules를 추가하고, 마지막에 명확한 용도가 있는 신뢰할 수 있는 MCP 서버만 연결하는 것입니다. MCP 인증 정보는 저장소가 아니라 환경 변수 또는 안전한 secret store에 보관하세요.
Cline 비용은 어디서 발생하나
Cline은 오픈 소스이지만 모델 실행에는 컴퓨팅 자원이 필요합니다. Cline은 내장 사용량 과금, 구독, BYOK 등 여러 모델 접근 방식을 제공합니다. BetterToken은 자신의 API를 연결하는 방식이므로 최종 비용은 선택한 모델에 실제로 전송한 요청에 따라 결정됩니다.
사용량에는 일반적으로 다음이 포함될 수 있습니다.
- input tokens: 프롬프트, 프로젝트 파일, Rules, 작업 기록
- output tokens: 응답, 생성된 코드, tool calls 내용
- cache tokens: 선택한 모델과 endpoint가 캐시를 지원할 때만 발생
Cline에 표시되는 비용은 보통 추정치입니다. 최종 기록은 제공자의 청구 내역 또는 BetterToken Dashboard를 기준으로 확인하세요. 불필요한 컨텍스트와 비용을 줄이려면 다음을 지키는 것이 좋습니다.
- 작업마다 검증 가능한 목표를 하나만 둔다.
- 이유 없이 저장소 전체를 컨텍스트에 넣지 않는다.
- 넓은 범위의 변경을 요청하기 전에 검색하고 읽는다.
- 주제가 바뀌면 새 작업을 만든다.
- 긴 실행 전 현재 모델 가격을 확인한다.
- 단순 작업에는 tool calling이 안정적인 더 빠르고 저렴한 모델을 고려한다.
- 큰 변경은 먼저 Plan해 반복 작업을 줄인다.
자주 발생하는 오류와 해결 방법
| 증상 | 먼저 확인할 것 |
|---|---|
401, Unauthorized, Invalid API Key | Key 문자열, 앞뒤 공백, 폐기 여부 |
404 | Base URL이 정확히 https://www.bettertoken.ai/v1인지, 추가 경로가 없는지 |
model not found | 현재 Model ID를 대소문자와 기호까지 정확히 복사했는지 |
| 저장 후에도 이전 설정 사용 | 저장, 확장 또는 VS Code 재로드, 새 작업 생성 |
| 연결이 계속 실패 | 로컬 네트워크, 프록시, 방화벽, DNS에서 endpoint 접근 가능 여부 |
| 응답은 있지만 Dashboard가 비어 있음 | 활성 Provider, 계정, 이전 환경 변수, Base URL |
| 출력이 이상하거나 도구 호출 실패 | 모델이 agent/tool calling에 적합한지, 모델 설정이 정확한지 |
| Token 사용량이 너무 빨리 증가 | 지나치게 큰 컨텍스트, 긴 기록, 같은 파일 반복 읽기 |
한 번에 하나의 변수만 바꾸세요. 먼저 Provider, Base URL, Key, Model을 확인한 뒤 컨텍스트 창, 출력 한도, Header, 프록시 같은 고급 설정을 조정합니다.
Cline에 잘 맞는 작업
Cline은 다음과 같은 작업에 유용합니다.
- 익숙하지 않은 모듈을 이해하고 관련 파일 찾기
- 재현 절차 또는 기존 테스트가 있는 범위가 작은 Bug 수정
- 여러 파일에 일관된 변경 적용
- lint, build, 테스트를 실행하고 실패 원인 설명
- 기존 패턴을 따르는 범위가 명확한 기능 구현
- 명시적인 접근 정책 아래 MCP 도구 호출
실무용 프롬프트 예시는 다음과 같습니다.
목표: 주문 목록에 상태 필터를 추가한다.
허용된 변경 범위: 주문 목록 페이지, 직접 사용하는 쿼리 파라미터, 관련 테스트만 변경한다.
하지 말 것: 주문 모듈 전체를 리팩터링하지 말고, 의존성을 업그레이드하지 말며, 결제 로직을 변경하지 않는다.
완료 조건: 사용자가 상태를 선택해 올바른 결과를 볼 수 있고, 페이지를 새로 고쳐도 필터가 유지된다.
검증: 주문 목록 관련 테스트를 실행하고 통과하면 중단한다.한 줄짜리 질문에는 Cline이 과할 수 있습니다. 격리와 정책 없이 매우 민감한 저장소에 무제한 접근을 주어서는 안 됩니다. 고정적이고 반복되며 무인으로 실행되는 흐름에는 VS Code를 계속 열어 두기보다 CLI나 CI 통합이 더 적합할 수 있습니다.
자주 묻는 질문
Cline AI란 무엇인가요?
Cline은 에디터와 터미널에서 사용하는 오픈 소스 AI 코딩 에이전트입니다. 코드를 읽고, 파일을 수정하고, 명령을 실행하고, 브라우저와 MCP를 사용할 수 있습니다. 외부 모델 API가 추론과 생성을 제공하고, Cline의 권한 시스템이 도구 사용을 사용자 통제 아래 둡니다.
ClineAI, Cline agent, Cline은 같은 도구인가요?
검색에서는 일반적으로 같은 코딩 에이전트를 가리킵니다. 공식 제품명은 Cline입니다.
Cline은 VS Code에서 작동하나요?
네. 공식 확장 프로그램이 VS Code 사이드바에서 실행되며 대화, diff, 작업 상태, 승인 요청을 보여 줍니다.
자신의 API를 Cline에 어떻게 연결하나요?
Cline 설정에서 알맞은 Provider를 선택합니다. BetterToken은 OpenAI Compatible을 선택하고 https://www.bettertoken.ai/v1, 자신의 API Key, 현재의 정확한 Model ID를 입력한 뒤 저장하고 확장을 다시 로드합니다.
Cline 구독이 반드시 필요한가요?
반드시 필요하지는 않습니다. Cline은 자체 과금 방식과 외부 API Key를 포함한 여러 모델 접근 방식을 지원합니다. 계정, 지역, 필요한 모델, 예산에 따라 선택하면 됩니다.
Cline과 MCP의 차이는 무엇인가요?
Cline은 작업을 수행하는 에이전트이고, 모델 API는 지능을 제공하며, MCP는 외부 도구와 데이터를 추가합니다. 서로 다른 역할을 하는 보완 관계입니다.
Cline은 안전한가요?
안전성은 권한, 프롬프트, 모델, MCP 서버, 프로젝트 환경에 따라 달라집니다. 최소 권한, 명령 검토, Git, 시크릿 분리, YOLO Mode 기본 비활성화를 적용하면 위험을 크게 줄일 수 있습니다.
마무리
Cline은 VS Code 안의 단순한 채팅창이 아닙니다. 프로젝트 컨텍스트, 파일 변경, 터미널 명령, 검토 가능한 diff를 하나의 에이전트 워크플로로 연결합니다. 올바른 시작 방법은 공식 확장을 설치하고, 하나의 모델 API를 설정하고, 읽기 전용 테스트를 통과한 뒤 편집, 명령, 브라우저, MCP 권한을 실제 필요에 따라 단계적으로 넓히는 것입니다.
BetterToken에서는 OpenAI Compatible, Base URL https://www.bettertoken.ai/v1, 자신의 API Key, 현재 유효한 Model ID를 사용합니다. 작고 구체적인 작업으로 시작하고 새로운 권한을 추가할 때마다 정말 필요한지 판단하세요.
추가 자료:
