완벽한 Openclaw 설정을 위한 구조 분석

OpenClaw 워크스페이스 파일, 스킬, 채널, 권한 완벽 가이드 – 제대로 설정하는 방법

대부분의 OpenClaw 사용자는 설치하고, 채널을 연결한 후 워크스페이스 폴더는 열어보지도 않습니다.

이것은 실수입니다.

워크스페이스는 AI 어시스턴트의 행동을 제어하는 컨트롤 센터입니다. 여기에는 당신의 정체성, 커스텀 스킬, 채널 연결, 그리고 메모리가 담겨 있습니다. 각 요소가 어디에 위치하는지 이해하면, OpenClaw 를 필요에 맞게 정확히 구성할 수 있습니다.

이 가이드는 완벽한 설정의 구조를 설명합니다.

추신: Openclaw 는 시작에 불과합니다.

Build With AI 커뮤니티에서는 직접 사용하거나 고객에게 판매할 수 있는 커스텀 에이전트, 앱, 자동화 도구를 만드는 방법을 가르쳐 드립니다. 곧 시작됩니다.

여기서 대기자 명단에 등록하세요: https://return-my-time.kit.com/1bd2720397

-----------------------------------------

하나가 아닌 두 개의 설정 레이어

시작하기 전에, 한 가지 알아두면 좋은 점이 있습니다. OpenClaw 는 두 개의 설정 레이어를 사용합니다.

첫 번째는 워크스페이스 폴더(일반적으로 ~/clawd/ 또는 초기화한 위치)입니다. 여기에는 개인 설정, 스킬, 메모리, 비밀 정보가 저장됩니다.

두 번째는 전역 설치 경로인 opt/homebrew/lib/node_modules/clawdbot/(또는 시스템에 따라 동일한 위치)입니다. 여기에는 핵심 문서, 내장 스킬, 기본 동작이 포함되어 있습니다.

워크스페이스는 커스터마이징하는 곳입니다. 전역 설치는 업데이트하는 곳입니다.

AGENTS.md: 운영 지침서

이것은 전체 설정에서 가장 중요한 파일입니다. OpenClaw 가 세션을 시작할 때 가장 먼저 읽는 파일이 AGENTS.md 입니다. 이 파일을 시스템 프롬프트에 바로 로드하여 대화 전체에 걸쳐 유지합니다.

간단히 말해: AGENTS.md 에 작성하는 내용을 에이전트가 따르게 됩니다.

회의 시간을 제안하기 전에 항상 캘린더를 확인하라고 지시하면, 에이전트는 그렇게 합니다. "명시적인 승인 없이 이메일을 절대 보내지 마"라고 작성하면, 매번 그 규칙을 존중합니다.

AGENTS.md 에 실제로 포함해야 할 내용:

작성할 내용:

• 핵심 운영 지침 (에이전트의 역할은 무엇인가?)
• 주요 도구와 사용 방법 (이메일 CLI, 작업 관리 워크플로우)
• 절대 위반해서는 안 되는 확고한 규칙
• 중요한 리소스 링크 (API 문서, 스킬 위치)
• 워크플로우 트리거 (자동으로 실행되어야 할 작업)

작성하지 말아야 할 내용:

• 링크로 대체할 수 있는 전체 문서
• 이론을 설명하는 긴 문단
• 자주 변경되는 정보

AGENTS.md 는 300줄 미만으로 유지하세요. 그 이상 길어지면 컨텍스트를 너무 많이 소비하게 되어 지침 준수율이 실제로 떨어집니다.

다음은 최소한이지만 효과적인 예시입니다:

1# AGENTS.md - Clawdbot Workspace
2
3## 핵심 운영 지침
4내 어시스턴트는 내 비즈니스를 위한 능동적인 도우미로 작동합니다.
5
6**지침:**
7- 내 업무를 최대한 덜어줄 것
8- 능동적으로 행동할 것 – 요청을 기다리지 말 것
9
10## 주요 도구
11- **이메일:** 매일 받은 편지함 확인, 긴급 항목 플래그 지정
12- **캘린더:** 일정 잡기 전 충돌 여부 확인
13- **작업 관리자:** 완료된 작업을 대시보드에 동기화
14
15## 확고한 규칙
16- 명시적 허락 없이 절대 서비스를 재시작하지 말 것
17- 일정을 잡기 전에 항상 `date` 명령어로 날짜 확인
18- 모든 완료된 작업을 추적 시스템에 기록

약 20줄의 핵심 지침입니다. 에이전트가 계속된 설명 없이 생산적으로 작업하는 데 필요한 모든 것을 제공합니다.

SOUL.md: 페르소나와 경계

SOUL.md 는 에이전트가 누구인지, 어떻게 의사소통해야 하는지를 정의합니다. 이것이 바로 페르소나가 살아있는 곳입니다.

1# SOUL.md - 페르소나 및 경계
2
3- 답변은 간결하고 직접적으로 유지할 것.
4- 필요할 때 명확한 질문을 할 것.
5- 외부 메시징 채널로 스트리밍/부분 답변을 보내지 말 것.

AGENTS.md 가 사용 설명서라면, SOUL.md 는 성격 프로필입니다. 어떤 사용자는 여기에 광범위한 페르소나를 작성합니다. 다른 사용자는 최소한으로 유지합니다. 둘 다 효과적이며, 원하는 페르소나 커스터마이징 정도에 따라 다릅니다.

IDENTITY.md 및 USER.md: 누가 누군지

이 두 파일은 에이전트와 사용자 사이의 관계를 설정합니다.

IDENTITY.md 는 에이전트를 정의합니다:

1# IDENTITY.md - 에이전트 정체성
2
3- 이름: [에이전트 이름]
4- 종류: [선택사항: 재미있는 설명]
5- 분위기: 똑똑하고, 도움이 되며, 신뢰할 수 있고, 끈질긴 문제 해결사
6- 이모지: [선택한 이모지]

USER.md 는 사용자를 정의합니다:

1# USER.md - 사용자 프로필
2
3- 이름: [사용자 이름]
4- 호칭: [별명]
5- 시간대: [시간대]
6- 전화번호: [전화번호]
7- 캘린더: [캘린더 플랫폼 및 이메일]

왜 별도의 파일로 나눌까요? 각각 다른 목적을 제공하기 때문입니다. IDENTITY.md 는 한 번 설정하면 거의 변경되지 않습니다. USER.md 는 선호도가 변함에 따라 업데이트됩니다. 이 둘을 분리하면 유지보수가 더 쉬워집니다.

HEARTBEAT.md: 정기 체크인

이 파일은 하트비트 폴(heartbeat poll) 중 에이전트가 수행할 작업을 제어합니다. 하트비트 폴은 시스템이 무언가 주의가 필요한지 확인하는 예정된 순간입니다.

1# HEARTBEAT.md
2
3**메시지에 "⚠️ EXECUTION CRON"이 포함된 경우:**
4- 이것은 하트비트 체크가 아닙니다 – 수행해야 할 작업입니다
5- 메시지의 전체 지침을 읽으십시오
6- 필요한 모든 단계를 실행하십시오
7- HEARTBEAT_OK 를 반환하지 마십시오
8
9**그 외의 경우:**
10- 주의가 필요한 것이 없으면 HEARTBEAT_OK 를 반환하십시오
11- 최소한으로 유지하십시오

하트비트는 능동적인 에이전트를 만드는 데 강력한 도구입니다. 에이전트가 캘린더를 확인하고, 받은 편지함을 스캔하거나, 예약된 일정에 따라 자동화된 워크플로우를 실행할 수 있게 해줍니다. 이 모든 것이 하트비트 폴에 의해 트리거됩니다.

TOOLS.md: 외부 도구 문서

이 파일은 외부 도구와 규칙에 대한 사용자의 메모를 보관합니다. 어떤 도구가 존재하는지 정의하지는 않지만(OpenClaw 가 내부적으로 처리), 사용자가 도구를 어떻게 사용하는지 문서화하는 곳입니다.

1# TOOLS.md - 사용자 도구 노트
2
3## 이메일 CLI
4- 계정: [email protected]
5- 일반 명령어: `cli email search`, `cli calendar create`
6
7## 작업 관리 API
8- 토큰 위치: ~/.secrets/task-api-token.txt
9- 페이지네이션 문제를 피하려면 항상 `limit=100` 사용
10- 상태 변환: [특정 워크플로우 문서화]
11
12## 웹 스크래핑 도구 (일반 요청이 차단된 사이트용)
13- 위치: ~/clawd/.venv/scraper
14- 보호된 사이트에는 스텔스 모드 사용

이것은 개인 참조 가이드가 됩니다. 에이전트가 도구를 사용해야 할 때 TOOLS.md 에서 사용자의 특정 규칙을 확인합니다.

skills/ 폴더: 재사용 가능한 워크플로우

스킬은 OpenClaw 가 강력해지는 지점입니다. 각 스킬은 독립적인 워크플로우로, 작업이 스킬의 설명과 일치할 때 에이전트가 호출할 수 있습니다.

모든 스킬은 자체 하위 디렉토리에 SKILL.md 파일과 함께 위치합니다:

1skills/
2├── meeting-prep/
3│   └── SKILL.md
4├── social-post-writer/
5│   ├── SKILL.md
6│   └── references/
7│       └── templates.md
8└── podcast-show-notes/
9    └── SKILL.md

SKILL.md 는 YAML 프론트매터를 사용하여 언제 사용해야 하는지 설명합니다:

1---
2name: meeting-prep
3description: 자동화된 사전 통화 조사 및 브리핑. 사용자가 예정된 회의를 확인하거나 회의 준비를 요청할 때 사용합니다.
4---
5
6# 회의 준비 스킬
7
8## 트리거 시점:
9- 사용자가 예정된 회의 확인을 요청할 때
10- cron을 통해 10분마다 실행되도록 예약됨
11- **첫 통화에 대해서만** 브리핑 수행
12
13## 프로세스:
141. 캘린더에서 향후 15-45분 내 회의 확인
152. 참석자 조사 (LinkedIn, 회사 웹사이트)
163. 브리핑 문서 생성
174. 캘린더 이벤트에 링크 첨부

정적 지침과의 주요 차이점: 스킬은 함께 지원 파일을 번들로 묶을 수 있습니다. references/templates.md 파일은 예시 출력물, 입증된 형식, 또는 스킬이 활성화될 때만 로드되는 추가 컨텍스트를 보관할 수 있습니다.

memory/ 폴더: 영구 컨텍스트

이것은 에이전트의 장기 기억입니다. 세션 기록, 학습된 선호도, 일일 로그가 모두 여기에 저장됩니다.

1memory/
2├── 2026-03-22.md
3├── 2026-03-21.md
4├── email-style.md
5├── business-context-2026-02.md
6└── workflow-playbook.md

좋은 관행:

• 일일 로그는 memory/YYYY-MM-DD.md 에 저장
• 세션 시작 시, 에이전트는 오늘과 어제 파일이 있으면 읽음
• 지속적인 사실, 선호도, 결정 사항을 캡처
• 비밀 정보는 저장하지 않음

메모리 파일은 에이전트가 세션 간 컨텍스트를 유지하도록 해줍니다. 이것이 없으면 모든 대화가 초기화 상태에서 시작됩니다.

.secrets/ 폴더: 자격 증명

API 토큰, 비밀번호, 민감한 설정이 여기에 저장됩니다. 이 폴더는 gitignore 에 추가되어 절대 커밋되지 않아야 합니다.

1.secrets/
2├── task-api-token.txt
3├── openai-api-key.txt
4├── anthropic-api-key.txt
5└── service-credentials.txt

AGENTS.md 또는 TOOLS.md 에서 실제 값을 노출하지 않고 이러한 경로를 참조할 수 있습니다.

채널 구성: 에이전트와 대화하는 곳

OpenClaw 는 Discord, Telegram, Signal, WhatsApp 등 여러 메시징 채널을 지원합니다. 채널 구성은 게이트웨이 설정( clawdbot gateway 명령어로 관리)에 있습니다.

핵심 개념:

• 각 채널은 고유한 세션 동작을 가짐
• 여러 채널을 동시에 활성화할 수 있음
• 채널별 규칙(예: "Discord에서 @멘션되지 않으면 응답하지 마")은 AGENTS.md 에 저장

전체 그림

모든 것이 어떻게 결합되는지 살펴보겠습니다:

1~/clawd/
2├── AGENTS.md           # 운영 지침 (일상 사용)
3├── SOUL.md             # 페르소나 및 경계
4├── IDENTITY.md         # 에이전트 정체성
5├── USER.md             # 사용자 프로필
6├── HEARTBEAT.md        # 정기 체크인 동작
7├── TOOLS.md            # 외부 도구 문서
8├── BOOTSTRAP.md        # 첫 실행 의식 (사용 후 삭제)
9│
10├── skills/             # 커스텀 워크플로우
11│   ├── meeting-prep/
12│   ├── podcast-show-notes/
13│   └── social-post-writer/
14│
15├── memory/             # 영구 컨텍스트
16│   ├── 2026-03-22.md
17│   └── key-context.md
18│
19├── .secrets/           # API 키 및 자격 증명 (gitignore 처리)
20│   ├── task-api-token.txt
21│   └── anthropic-api-key.txt
22│
23└── output/             # 생성된 파일 및 내보내기

시작을 위한 실용적인 설정

처음부터 시작한다면, 다음 순서대로 진행하면 좋습니다.

1단계. openclaw onboard 를 실행하고 초기 설정을 완료하세요. 모델 제공업체를 선택하고 하나 이상의 채널을 연결하세요.

2단계. 워크스페이스 폴더를 만들고 핵심 지침을 담은 AGENTS.md 를 추가하세요. 주요 사용 사례를 다루는 10-20줄로 시작하세요.

3단계. IDENTITY.md, USER.md, SOUL.md 를 추가하세요. 이 파일들은 관계와 페르소나를 설정합니다.

4단계. 반복적으로 수행하는 워크플로우를 위한 첫 번째 스킬을 만드세요. 회의 준비, 이메일 초안 작성, 콘텐츠 제작이 좋은 시작점입니다.

5단계. 일일 로그 템플릿으로 memory/ 를 설정하세요. 에이전트가 시간이 지남에 따라 컨텍스트를 쌓기 시작할 것입니다.

6단계. 도구별 패턴을 발견하면 TOOLS.md 를 추가하세요.

이 정도면 95% 의 사용 사례에 충분합니다. 크론 작업, 멀티 에이전트 설정, 커스텀 채널 플러그인과 같은 고급 기능은 자동화할 가치가 있는 특정 워크플로우가 있을 때 사용됩니다.

핵심 통찰

OpenClaw 워크스페이스는 본질적으로 AI 어시스턴트에게 당신이 누구인지, 무엇을 해야 하는지, 어떤 규칙을 따라야 하는지 알려주는 프로토콜입니다. 이를 더 명확하게 정의할수록 에이전트를 수정하는 데 소요되는 시간은 줄어들고, 유용한 작업을 수행하는 데 더 많은 시간을 할애하게 됩니다.

AGENTS.md 는 가장 영향력이 큰 파일입니다. 이것을 먼저 제대로 설정하세요. 나머지는 모두 최적화에 불과합니다.

작게 시작하고, 진행하면서 개선하며, 워크플로우의 다른 인프라처럼 대하세요. 제대로 설정되면 매일 이익을 창출하는 자산입니다.

추신: Openclaw 는 시작에 불과합니다.

Build With AI 커뮤니티에서는 직접 사용하거나 고객에게 판매할 수 있는 커스텀 에이전트, 앱, 자동화 도구를 만드는 방법을 가르쳐 드립니다. 곧 시작됩니다.

여기서 대기자 명단에 등록하세요:

https://return-my-time.kit.com/1bd2720397