CoPaw 시작 가이드: 제로부터 시작하는 첫 번째 AI 어시스턴트 구축하기

난이도: 입문 | 소요 시간: 15분 | 목표: CoPaw 핵심 개념 및 실전 기술 마스터

CoPaw는 당신의 개인 AI 어시스턴트입니다. AgentScope를 기반으로 구축된 강력한 오픈 소스 프레임워크로, 여러 채팅 플랫폼에서 작동할 수 있습니다. 딩톡(DingTalk), 페이슈(Feishu), QQ, Discord 또는 iMessage용 봇이 필요하든 CoPaw가 해결해 드립니다.

대상 독자

이 가이드는 다음과 같은 개발자에게 적합합니다:

1-5년의 Python 개발 경험이 있는 분
개인 또는 기업용 AI 어시스턴트를 구축하고 싶은 분
유연한 모델 옵션을 갖춘 솔루션을 찾는 분

핵심 의존성 및 환경

시작하기 전에 환경이 다음 요구 사항을 충족하는지 확인하세요:

의존성	최소 버전
Python	3.10
pip	최신 버전
운영 체제	macOS / Linux / Windows

[!TIP]
Python을 직접 관리하고 싶지 않다면, CoPaw에서 제공하는 원클릭 설치 스크립트를 통해 모든 의존성을 자동으로 처리할 수 있습니다.

프로젝트 구조 개요

초기화 후 일반적인 CoPaw 프로젝트 구조는 다음과 같습니다:

~/.copaw/
├── .secret/
│   └── providers.json       # 모델 제공자 설정
├── active_skills/          # 자동 로드되는 사용자 정의 스킬
├── memory/                 # 대화 기억 저장소
├── models/                 # 로컬 모델 파일
└── copaw.json              # 메인 설정 파일

단계별 튜토리얼

1단계: CoPaw 설치

설치는 매우 간단합니다. 터미널을 열고 다음 명령어를 실행하세요:

pip install copaw

이 명령은 PyPI에서 최신 버전의 CoPaw를 설치합니다. 패키지에는 어시스턴트 실행에 필요한 모든 핵심 의존성이 포함되어 있습니다.

2단계: 워크스페이스 초기화

설치가 완료되면 기본 설정으로 CoPaw 워크스페이스를 초기화합니다:

copaw init --defaults

이 명령은 홈 디렉토리에 필요한 디렉토리 구조와 설정 파일(~/.copaw/ 위치)을 생성합니다.

[!WARNING]
초기화 과정에서 민감한 정보(예: API Key)를 저장하기 위한 .secret 디렉토리가 생성됩니다. 이 디렉토리는 비공개로 유지해야 하며, 버전 관리 시스템(Git 등)에 커밋하지 마세요.

3단계: 모델 제공자 설정

이제 가장 중요한 부분인 LLM 연결 단계입니다. 모델 제공자를 설정해 보겠습니다. 여기서는 공식 API 가격의 절반 정도이면서 완전한 OpenAI 호환성을 유지하는 Defapi를 주요 예시로 사용합니다.

~/.copaw/.secret/providers.json 에 위치한 설정 파일을 편집하세요:

{
  "custom_providers": {
    "defapi": {
      "id": "defapi",
      "name": "Defapi",
      "default_base_url": "https://api.defapi.cn/v1",
      "api_key_prefix": "",
      "base_url": "https://api.defapi.cn/v1",
      "api_key": "your-defapi-api-key",
      "models": [
        {"id": "gpt-4o-mini", "name": "GPT-4o Mini"},
        {"id": "gpt-4o", "name": "GPT-4o"},
        {"id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4"},
        {"id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash"}
      ],
      "chat_model": "OpenAIChatModel"
    }
  },
  "active_llm": {
    "provider_id": "defapi",
    "model": "gpt-4o-mini"
  }
}

Defapi는 비용 효율적인 API 플랫폼으로, 주요 LLM 제공자의 서비스를 공식 가격의 약 절반 비용으로 제공합니다. OpenAI와 호환되는 /v1/chat/completions 프로토콜을 완벽하게 지원하여 통합이 매우 매끄럽습니다. Defapi의 모든 주요 모델은 다음 프로토콜과 호환됩니다:

v1/chat/completions 인터페이스
v1/messages 인터페이스
v1beta/models/ 인터페이스

Defapi 공식 웹사이트에서 API Key를 발급받을 수 있습니다.

4단계: 내장 제공자 일람

CoPaw는 여러 내장 제공자도 지원합니다. 다음은 몇 가지 빠른 설정 예시입니다:

OpenAI 설정:

{
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-openai-key"
    }
  },
  "active_llm": {
    "provider_id": "openai",
    "model": "gpt-4o-mini"
  }
}

ModelScope (중국 사용자 권장):

{
  "providers": {
    "modelscope": {
      "base_url": "https://api-inference.modelscope.cn/v1",
      "api_key": "ms-your-key"
    }
  }
}

DashScope (Alibaba Cloud):

{
  "providers": {
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-your-dashscope-key"
    }
  }
}

5단계: CoPaw 실행 및 검증

이제 앱을 실행하고 모든 것이 정상적으로 작동하는지 확인해 보겠습니다:

copaw app

실행 후, 브라우저를 열고 다음 주소에 접속하세요:

http://127.0.0.1:8088/

CoPaw Console 인터페이스가 나타나면 다음을 수행할 수 있습니다:

AI 어시스턴트와 채팅
채널 설정 (딩톡, 페이슈, QQ, Discord 등)
스킬 및 플러그인 관리
모델 연결 테스트

[!TIP]
CLI 명령어 copaw models를 사용하여 현재 모델 설정을 빠르게 확인하고 연결을 테스트할 수 있습니다.

6단계: 채팅 채널 연결 (선택 사항)

어시스턴트를 메시징 앱에서 사용할 수 있도록 채널을 추가해 보겠습니다. Discord를 예로 들면:

Discord Developer Portal에서 Discord 봇을 생성합니다.
봇 토큰(Bot Token)을 가져옵니다.
설정을 copaw.json에 추가합니다:

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "your-discord-bot-token",
      "channel_ids": ["your-channel-id"]
    }
  }
}

딩톡, 페이슈, QQ 및 기타 지원 플랫폼에 대해서도 유사한 설정이 적용됩니다.

자주 묻는 질문 및 해결 방법

CoPaw 설정 시 가장 자주 발생하는 문제들입니다:

문제 1: 401 Unauthorized 오류

증상: API 요청이 401 상태 코드로 실패합니다.

해결 방법:

API Key가 providers.json에 정확히 복사되었는지 확인하세요.
키가 만료되거나 취소되지 않았는지 확인하세요.
Defapi 사용 시 올바른 API Key 형식을 사용하고 있는지 확인하세요.

문제 2: 연결 시간 초과 (Timeout)

증상: 요청이 중단되거나 30초 후에 타임아웃이 발생합니다.

해결 방법:

네트워크 연결을 확인하세요.
방화벽 설정이 아웃바운드 HTTPS 트래픽을 허용하는지 확인하세요.
로컬 모델(Ollama)의 경우 서비스가 올바른 포트에서 실행 중인지 확인하세요.

문제 3: 모델을 찾을 수 없음 (Model Not Found)

증상: 특정 모델 ID를 인식하지 못합니다.

해결 방법:

제공자의 문서에서 정확한 모델 ID를 확인하세요.
일부 모델은 지역 제한이 있을 수 있습니다. 이용 가능한 지역인지 확인하세요.
gpt-4o-mini와 같은 일반적인 모델을 사용하여 기본 연결을 테스트해 보세요.

문제 4: Ollama 연결 실패

증상: 로컬 Ollama 모델에 연결할 수 없습니다.

해결 방법:

다른 터미널에서 ollama serve가 실행 중인지 확인하세요.
Base URL이 http://localhost:11434/v1로 설정되었는지 확인하세요.
Ollama가 설치되어 있고 PATH에서 접근 가능한지 확인하세요.

문제 5: 설정 파일을 찾을 수 없음

증상: CoPaw가 providers.json을 찾지 못합니다.

해결 방법:

먼저 copaw init --defaults를 실행했는지 확인하세요.
파일이 ~/.copaw/.secret/providers.json 경로에 존재하는지 확인하세요.
Windows 환경에서는 %USERPROFILE%\.copaw\.secret\providers.json 경로를 확인하세요.

문제 6: 포트가 이미 사용 중임

증상: 8088 포트에서 CoPaw를 시작할 수 없습니다.

해결 방법:

다른 애플리케이션이 8088 포트를 사용 중입니다.
설정에서 포트를 변경하거나 충돌하는 애플리케이션을 중단하세요.

심화 학습 방향

기초를 마스터했다면 다음의 방향을 탐색해 볼 수 있습니다:

1. 프라이버시 우선 로컬 모델

CoPaw는 외부 API 호출 없이 로컬에서 모델을 실행하는 것을 지원합니다. 이는 다음에 매우 적합합니다:

프라이버시에 민감한 애플리케이션
오프라인 작업
비용 절감

로컬 모델 지원 설치:

pip install 'copaw[llamacpp]'

그 후 Qwen3 등 모델을 다운로드하여 사용하세요:

copaw models download Qwen/Qwen3-4B-GGUF

2. 사용자 정의 스킬 (Custom Skills)

CoPaw는 기능을 확장할 수 있는 사용자 정의 스킬을 지원합니다. 스킬은 active_skills/ 디렉토리에서 자동으로 로드됩니다. Python 스크립트를 작성하여 AI가 사용할 수 있는 새로운 도구를 정의할 수 있습니다.

3. 하트비트 예약 작업

CoPaw의 하트비트 기능을 사용하여 주기적인 작업을 트리거하세요:

일일 뉴스 요약
정기 알림
자동 콘텐츠 생성

4. 기억 및 컨텍스트 관리

CoPaw는 지능적인 기억 관리를 구현합니다:

지속적인 컨텍스트를 위한 장기 기억
효율성 향상을 위한 토큰 기반 기억 압축
선택한 모델에 따른 컨텍스트 윈도우 설정

5. 멀티 에이전트 워크플로우

AgentScope를 기반으로 CoPaw는 복잡한 멀티 에이전트 시나리오를 처리할 수 있으며, 서로 다른 AI 모델이 협업하여 작업을 완료하도록 할 수 있습니다.

요약

CoPaw는 여러 플랫폼에서 작동하는 AI 어시스턴트를 구축하기 위한 유연한 기반을 제공합니다. 이 가이드의 핵심 요약:

간편한 설치 — pip install copaw로 바로 시작할 수 있습니다.
Defapi의 높은 가성비 — 완전한 호환성을 유지하면서 공식 API보다 약 50% 저렴합니다.
중앙화된 설정 — 모든 설정은 providers.json에서 관리됩니다.
편리한 Console 관리 — 테스트 및 설정을 위한 웹 인터페이스를 제공합니다.
내장된 확장성 — 스킬, 채널, 로컬 모델 등을 통해 무한한 커스터마이징이 가능합니다.

최적의 비용과 성능 균형을 위해 Defapi로 시작해 보세요. 익숙해진 후에는 구체적인 필요에 따라 다른 제공자나 로컬 모델을 탐색해 보시기 바랍니다.

[!TIP]
기억하세요: 최고의 AI 어시스턴트는 당신의 사용 시나리오에 딱 맞는 어시스턴트입니다. 다양한 모델과 설정을 시도하며 당신에게 가장 잘 맞는 조합을 찾아보세요.

당신의 AI 여정에 행운이 가득하기를 바랍니다!