2026년 기준으로, OpenClaw(및 유사 제품인 QClaw)는 구성과 스킬(기능) 시스템이 완성도가 매우 높아졌습니다. 텐센트 워크버디의 '투명한 박스' 방식과 달리, OpenClaw는 로컬에서 실행 가능한 Ollama 모델까지 지원하며 완전한 사용자 정의가 가능합니다.
다음은 OpenClaw에 설정을 추가하고 스킬을 활용하는 단계별 안내입니다.
1. 핵심 아키텍처 이해: 세 가지 주요 요소
구성 전에 다음 세 가지 개념을 명확히 이해해야 합니다:
- LLM 프로바이더: 인공지능의 '뇌'. 로컬의 Ollama 또는 클라우드 기반 API로 선택 가능.
- 스킬: '손발'. AI가 수행할 수 있는 작업을 정의합니다 (예: 파일 읽기, 웹 검색, 쉘 명령 실행).
- 에이전트: '지휘관'. 뇌와 손발을 결합하여 역할과 작업 흐름을 설정합니다.
2. 첫 번째 단계: 대규모 언어 모델 연결 – 로컬 Ollama 연동
기본 구성 파일은 프로젝트 루트 폴더 내 config.yaml 또는 .env에 위치합니다. 2026년 버전에서는 config.yaml를 권장합니다.
1. 로컬 Ollama 시작
먼저, 로컬에서 Ollama 서비스를 실행하고 필요한 모델을 다운로드하세요:
ollama serve
ollama pull qwen2.5-coder:7b # 코드 및 도구 호출에 최적화된 모델
2. config.yaml 수정
llm 섹션을 아래와 같이 설정합니다:
llm:
provider: ollama # 지원되는 옵션: ollama, openai, azure, deepseek 등
base_url: http://localhost:11434
model: qwen2.5-coder:7b
context_window: 16384 # GPU 메모리에 따라 조정 (7B 모델 기준)
temperature: 0.2 # 도구 사용 시 낮게 유지 (0.1~0.3), 환상 감소
stream: true # 디버깅 시 활성화, 운영 환경에서는 false 추천
설정 확인: 서비스 재시작 후 로그에서 Connected to Ollama 메시지를 확인하거나, "안녕"이라고 입력해 응답 여부를 테스트하세요.
3. 두 번째 단계: 스킬 등록 및 활용
스킬 시스템은 등록 기반이며, 내장 기능을 사용하거나 자체 개발도 가능합니다.
사례 A: 내장 스킬 사용 (즉시 사용)
OpenClaw 2026에는 다양한 기본 스킬이 포함되어 있으며, 별도 설치 없이 활성화만 하면 됩니다.
- 사용 가능한 스킬 목록 확인:
python main.py --list-skills
# 또는 웹 인터페이스의 "Skills Market"에서 확인
- 대표적인 내장 스킬:
file_reader,web_search,shell_executor,calendar_manager.
- 에이전트 설정에서 스킬 활성화:
agents/default_agent.yaml파일을 열고 다음 내용을 추가합니다:
agent:
name: "MyAssistant"
role: "효율적인 개인 보조자로서 파일 처리와 웹 검색에 능숙합니다."
enabled_skills:
- file_reader
- web_search
- shell_executor
skill_constraints:
shell_executor:
allowed_commands: ["ls", "cd", "cat", "mkdir"]
blocked_dirs: ["/", "/etc", "/sys"]
- 테스트: 서비스 시작 후 "데스크탑의 test.txt 내용을 읽어줘"라고 요청하면, 자동으로
file_reader가 작동합니다.
사례 B: 사용자 정의 스킬 추가 (Python 스크립트)
내장 기능으로 충족되지 않을 경우, 직접 함수를 작성해 스킬을 만들 수 있습니다.
단계 1: 스킬 파일 생성
skills/custom/ 폴더에 weather_skill.py 파일을 생성합니다:
# skills/custom/weather_skill.py
from openclaw.skills import register_skill
import requests
@register_skill(
name="get_weather",
description="사용자가 특정 도시의 현재 날씨를 묻는 경우 반드시 사용. 입력 형식: 도시 이름 (예: 서울).",
parameters={
"city": {
"type": "string",
"description": "도시 이름 (한글 또는 영문)",
"required": True
}
}
)
def get_weather(city: str) -> str:
print(f"🌤️ {city}의 날씨 정보를 조회 중...")
# 실제 사용 시에는 실질적인 API 키로 교체
# response = requests.get(f"http://api.weather.com?q={city}&key=YOUR_KEY")
# 예제용 가짜 데이터 반환
return f"{city} 오늘은 맑음, 기온 25도, 습도 40%입니다."
단계 2: 자동 로딩 확인
@register_skill데코레이터가 포함되어 있어야 함.- 의존성 설치:
pip install requests.
단계 3: 에이전트에서 사용 활성화
agents/default_agent.yaml 파일에 다음과 같이 추가:
agent:
enabled_skills:
- file_reader
- get_weather # 새 스킬 추가
단계 4: 테스트
서비스 재시작 후 "서울 날씨 어떻게 돼?"라고 입력하면, 해당 함수가 자동으로 호출됩니다.
사례 C: 커뮤니티 스킬 팩 가져오기
2026년 기준, OpenClaw는 커뮤니티 스킬 팩을 간편하게 설치할 수 있습니다.
- 패키지 다운로드: GitHub 또는 공식 커뮤니티에서
.zip또는.yaml형식의 팩을 가져옵니다. - 설치 명령 실행:
python main.py --install-skill ./my-custom-pack.zip
- 적용: 시스템이
skills/community/에 자동으로 압축 해제하고 설정을 업데이트합니다. 이후 재시작하면 사용 가능합니다.
4. 세 번째 단계: 디버깅 및 성능 최적화
정상 작동 후, 더 나은 동작을 위해 다음 팁을 활용하세요.
1. 스킬 설명문 개선
AI가 스킬을 호출하는 여부는 description의 명확성에 달려 있습니다.
- ❌ 나쁜 설명: "날씨 정보 제공"
- ✅ 좋은 설명: "사용자가 특정 도시의 날씨, 기온, 비 여부를 묻는 경우 반드시 이 스킬을 사용하라. 입력은 도시 한글 또는 영문 이름이어야 한다."
🔍 팁: 트리거 조건과 파라미터 형식을 구체적으로 명시하세요.
2. 온도 값 조정
- 만약 불필요한 스킬 호출이 발생한다면 (
안녕이라고만 말했지만 검색을 시도):temperature를 0.1로 낮추세요. - 반대로 필요한 순간에 호출하지 않는다면:
description을 더 명확하게 수정하거나,temperature를 0.3~0.4로 약간 올리세요.
3. 실행 로그 분석
logs/ 폴더에는 상세한 로그가 저장됩니다.
agent_thought.log: AI의 사고 과정 확인 (예: "날씨 질문 → get_weather 매칭 → 호출 준비")skill_execution.log: 스킬 호출 시 전달된 파라미터 및 결과 확인 → 오류 진단에 유용
5. 자주 발생하는 문제 해결
| 문제 | 원인 가능성 | 해결 방법 |
|---|---|---|
| 스킬이 작동하지 않음 | 1. enabled_skills 미등록 2. 모델 성능 부족 3. 설명 불분명 |
1. 설정 파일 점검 2. qwen2.5-coder:14b 이상으로 변경 3. description 재작성 |
| 스킬 실행 실패 | 1. 파이썬 패키지 누락 2. 파라미터 타입 불일치 3. 접근 권한 부족 | 1. pip install -r requirements.txt 2. 로그에서 파라미터 확인 3. 관리자 권한으로 실행 또는 폴더 권한 조정 |
| Ollama 연결 실패 | 1. Ollama 미실행 2. 주소 오류 3. 방화벽 차단 | 1. ollama serve 실행 2. base_url 확인 3. 방화벽 일시 비활성화 또는 예외 등록 |
| 무한 반복 호출 | 스킬 실패로 판단해 반복 시도 | 스킬 내 max_retries 제한 추가, 또는 에이전트 설정에서 max_iterations 제한 |
6. 전체 흐름 요약
┌───────────────────────────────────────────────────────────────┐
│ 단계 1: 환경 준비 (로컬 모델) │
├───────────────────────────────────────────────────────────────┤
│ 1. Ollama 실행: `ollama serve` │
│ 2. 모델 다운로드: `ollama pull qwen2.5-coder:7b` │
└───────────────────────────────────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ 단계 2: 핵심 설정 (모델 연결) │
├───────────────────────────────────────────────────────────────┤
│ `config.yaml` 수정: │
│ - provider: ollama │
│ - model: qwen2.5-coder:7b │
│ - temperature: 0.2 │
└───────────────────────────────────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ 단계 3: 스킬 관리 [선택] │
├───────────────────────────────────────────────────────────────┤
│ 【내장 스킬 사용】 │
│ ▶ `--list-skills`로 목록 확인 │
│ ▶ `enabled_skills`에 스킬 아이디 추가 │
│ │
│ 【사용자 스킬 개발】 │
│ ▶ `skills/custom/`에 `.py` 파일 생성 │
│ ▶ `@register_skill` 포함 필수 │
│ ▶ 설명문에 트리거 조건 명시 │
└───────────────────────────────────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ 단계 4: 에이전트 구성 (지휘관 설정) │
├───────────────────────────────────────────────────────────────┤
│ `agents/default_agent.yaml` 수정 │
│ - `enabled_skills` 리스트에 새로운 스킬 추가 │
└───────────────────────────────────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ 단계 5: 실행 및 디버깅 │
├───────────────────────────────────────────────────────────────┤
│ 1. `python main.py`로 서비스 시작 │
│ 2. "test.txt 내용 요약해줘"처럼 테스트 명령 입력 │
│ 3. `logs/agent_thought.log` 확인 → 사고 과정 분석 │
│ │
│ ❓ 실패 시? │
│ → 설명문이 명확한가? │
│ → 온도 값이 너무 높은가? │
│ → Ollama 연결 상태 확인 │
└───────────────────────────────────────────────────────────────┘
Ollama 시작
config.yaml 설정
스킬 필요?
내장 스킬
사용자 스킬
OpenClaw 재시작
테스트 명령 입력
이 과정을 거치면, 완전히 로컬 기반이며 개인정보 보호가 보장된 환경에서 확장 가능한 인공지능 보조자를 구축할 수 있습니다. 이것이 OpenClaw가 WorkBuddy보다 우월한 핵심 이유입니다: 당신의 스킬은 당신이 정의합니다.