머리말: 이 글은 다음을 이미 해냈다고 가정합니다
만약 이미:
- OpenClaw를 설치하고 정상적으로 대화할 수 있다(Discord / Telegram / WebChat 모두 가능)
SOUL.md / USER.md / IDENTITY.mdMEMORY.md,memory/의 계층 구조, 그리고memorySearch가 대략 무엇인지 안다
그렇다면 바로 읽어 내려가셔도 됩니다.
이 글에서는 7가지 주제를 다룹니다. 모두 "바로 적용할 수 있는" 설정 지점입니다:
AGENTS.md: AI에게 업무 매뉴얼을 준다(가장 중요)- 기억 시스템 실전: AI가 진짜로 기억하고 스스로 유지보수하게 만들기
- 하위 Agent: 한 사람이 작은 팀이 된다(병렬 + 컨텍스트 격리)
- Cron 작업: 분 단위로 정확한 자동화
- Skill 개발: AI에게 새 기술을 가르친다(skill을 0에서 작성)
- 다중 채널 연동: 언제 어디서나 당신의 AI를 찾기
- 설정 치트시트: 자주 쓰는 파라미터의 권장값과 함정
먼저 한눈에: "이전 글 수준"에서 "이 글의 튜닝 후"로
SOUL.md 몇 가지 원칙1. AGENTS.md: AI에게 "업무 매뉴얼"을 써 주기
1) 무엇을 해결하는가?
SOUL.md 는 "그것이 누구인지"를 정하고,USER.md 는 "누구를 돕는지"를 정합니다. 하지만 많은 사람이 놓치는 점이 있습니다:AI는 어떻게 일해야 하는지 모른다.
예를 들어:
- 새 session이 시작될 때 어떤 파일을 먼저 읽어야 하는가? 순서는?
- 기억은 어디에 써야 하는가? 어떤 형식으로 쓰는가?
- 어떤 작업은 바로 해도 되고, 어떤 것은 반드시 먼저 물어야 하는가?
- 그룹 채팅에서 당신의 개인 기억을 인용해도 되는가?
이것이 AGENTS.md 의 가치입니다. 이것은 성격 설정이 아니라 업무 매뉴얼 입니다.
이렇게 이해하면 됩니다:
SOUL.md= 성격("솔직하게 말하고 결론을 먼저 제시")AGENTS.md= SOP("무엇을 먼저 읽고, 다음에 무엇을 하고, 어떻게 기록하고, 무엇을 하면 안 되는가")
2) Session 시작 흐름: AI가 깨어나서 가장 먼저 할 일
새 session은 본질적으로 "방금 깨어난" 상태이며, 지난 대화의 컨텍스트를 자동으로 갖고 있지 않습니다. "현장 복원" 절차를 명확히 못 박아 두어야 합니다.
이제 AGENTS.md 에 단락을 추가합니다(규칙은 영어로 쓰는 편이 더 안정적입니다):
Every Session
Before doing anything else:
- Read
SOUL.md— this is who you are - Read
USER.md— this is who you're helping - Read
memory/YYYY-MM-DD.md(today + yesterday) for recent context - If in MAIN SESSION (direct chat with your human): Also read
MEMORY.md
Don't ask permission. Just do it.
"오늘 + 어제" 로그를 왜 읽어야 할까요? 새벽 시간대에는 "오늘"이 아직 비어 있을 수 있고 어제에야 내용이 있기 때문입니다.
왜 MEMORY.md 는 MAIN SESSION에서만 읽을까요? MEMORY.md 에는 더 사적이고 핵심적인 색인 정보가 담기는 경우가 많아, 그룹 채팅이나 cron·하위 agent의 session에서 불러오기에 적합하지 않기 때문입니다.
3) 기억 기록 규범: "재사용 가능한 결론"을 기록하는 법을 가르치기
많은 사람의 기억 시스템이 무너지는 것은 계층 구조 문제가 아니라 기록 규범이 정해지지 않았기 때문입니다.
결과는 보통 두 가지입니다:
- 무엇이든
MEMORY.md에 쌓아 올린다(결국 그냥 일기장이 된다) - 아니면 아예 쓰지 않는다(다음에 바로 잊는다)
"어디에 쓰고, 무엇을 쓰고, 어떻게 쓸지"를 분명히 해 두는 것을 권합니다. 예를 들어:
Memory
You wake up fresh each session. These files are your continuity.
기억 계층
MEMORY.mdmemory/projects.mdmemory/infra.mdmemory/lessons.mdmemory/YYYY-MM-DD.md기록 규칙
- 로그: 그날 일어난 일을
memory/YYYY-MM-DD.md에 기록, 형식 고정 - 프로젝트 상태: 진척이 있으면
memory/projects.md - 교훈: 문제를 겪은 뒤
memory/lessons.md - MEMORY.md: 색인이 바뀔 때만 갱신하고 간결하게 유지
철칙
- 과정이 아니라 결론을 기록한다
- memorySearch를 위해 태그를 단다
- 기억하고 싶으면 파일에 쓴다. "머릿속에 기억해 두기"를 기대하지 않는다
로그 형식은 이런 것을 쓰면 됩니다:
[PROJECT:이름] 제목
- 결론: 한 문장 요약
- 파일 변경: 관련된 파일
- 교훈: 겪은 함정(있는 경우)
- 태그: #tag1 #tag2
이 형식의 장점은 memorySearch 로 키워드를 검색할 때 적중이 더 집중되고 더 깔끔해진다는 점입니다.
4) 안전 경계: 해도 되는 일, 반드시 물어야 하는 일
"내부 vs 외부"를 분명히 그어 두는 것을 권합니다. 그러지 않으면 언젠가 사고가 납니다(특히 그룹 채팅과 자동화 작업).
Safety
- Don't exfiltrate private data. Ever.
- Don't run destructive commands without asking.
trash>rm(recoverable beats gone forever)- When in doubt, ask.
External vs Internal
Safe to do freely:
- Read files, explore, organize, learn
- Search the web, check calendars
- Work within this workspace
Ask first:
- Sending emails, tweets, public posts
- Anything that leaves the machine
- Anything you're uncertain about
Group Chats
You have access to your human's stuff. That doesn't mean you share it.
In groups, you're a participant — not their voice, not their proxy.
2. 기억 시스템 실전: AI가 진짜 "기억"하고 스스로 유지보수하게 만들기
다음 세 가지 전형적인 문제를 겪어 보셨을 것입니다:
- 오래 대화하다 갑자기 "기억을 잃는다"(대화가 압축되며 세부가 사라진다)
- 로그는 계속 늘어나는데 품질은 들쭉날쭉하고 검색 적중이 점점 운에 좌우된다
- 기억을 아무도 관리하지 않아 만료된 정보가 잡음으로 쌓인다
이 장에서 이 세 가지를 각각 해결합니다.
1) memoryFlush: 압축 전에 중요 정보를 파일로 먼저 기록
OpenClaw는 컨텍스트가 한계에 가까워지면 compaction(압축)을 발동합니다. 압축 자체는 정상이지만 압축은 세부를 잃을 수 있습니다.
해결책은 memoryFlush 를 켜서 압축 전에 먼저 디스크에 기록하게 하는 것입니다.
다음으로 openclaw.json 에 추가합니다(예시):
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 20000,
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000
}
}
}
}
}
권장값을 어떻게 이해하면 되는지 간단히 설명합니다:
reserveTokensFloor=20000: 압축 후에도 "최근 대화"를 최소한 일정 분량 유지softThresholdTokens=4000: 남은 공간이 4000 token 미만일 때 flush 발동(너무 작으면 쓸 수 없고, 너무 크면 너무 자주 발동)
2) memorySearch 정확도 높이기: 로그 하나에 주제 하나
벡터 검색은 적게 쓰는 것을 두려워하지 않습니다. 오히려 "너무 뒤섞어 쓰는 것"을 더 두려워합니다.
경험상 적중률이 가장 높은 작성법은 다음과 같습니다:
- 제목에 주제를 분명히 쓴다(nginx 리버스 프록시, IPv6, 포트 충돌 등)
- 결론은 고정된 위치에 둔다
- 태그로 동의어를 보강한다(#deploy #nginx #reverse-proxy)
비구조적인 "일기식" 기록은 유사도를 희석시켜 검색이 운에 좌우되게 만듭니다.
3) 주간 자동 유지보수: "기억 부패" 방지
예를 들어
AGENTS.md 에 "주간 유지보수" 작업을 추가합니다.HEARTBEAT.md 상태 파일로 빈도를 제어할 수 있습니다:
memory/heartbeat-state.json에 지난 유지보수 날짜를 기록- 하트비트로 "지난 유지보수로부터 7일 이상 지났는지" 확인
- 지났으면 실행: 추출, 압축, 정리, 날짜 갱신
유지보수 작업은 세 가지를 권합니다:
- 추출: 장기적으로 유용한 것을 로 옮긴다
projects.md / lessons.md - 압축: 일회성 작업을 긴 로그에서 한 줄 결론으로 압축
- 정리: 완전히 만료된 정보(예: "내일 회의")
3. 하위 Agent: 한 사람이 작은 팀이 된다(병렬 + 컨텍스트 격리)
1) 하위 Agent는 무엇을 해결하는가?
메인 두뇌가 단일 스레드일 때의 문제는, 복잡한 작업이 들어오면 오래 끌거나 중간에 끼어들 수 없다는 점입니다.
하위 Agent의 가치는 주로 두 가지입니다:
- 병렬화: 두 명의 조수에게 동시에 각각 다른 몫을 맡길 수 있다
- 컨텍스트 격리: 하위 agent의 긴 작업이 메인 대화를 터뜨리지 않는다
2) 가장 빠지기 쉬운 함정: 하위 Agent는 기본이 "컨텍스트 제로"
하위 Agent는 메인 두뇌가 준 task 설명만 보기 때문에, task를 대충 쓰면 결과도 대충 나옵니다.
좋은 task 설명에는 최소한 다음이 포함됩니다:
- 목표(무엇을 산출할지)
- 파일 경로(무엇을 읽고 쓸지)
- 제약(읽기 전용인가? 무엇을 바꾸면 안 되는가? 규범은 무엇인가?)
- 완료 기준(무엇을 완료로 볼지)
task는 "똑똑하지만 낯선 동료"에게 쓰는 설명서라고 생각하세요. 구체적일수록 안정적입니다.
3) 동시 실행 권장: 하위 Agent 2개부터
한 번에 너무 많은 agent를 투입하면 API 속도 제한(429)이 쉽게 걸립니다. 경험상:
- 일반 개인 요금제: 동시 2개가 가장 안정적
- 한도가 큰 경우·로컬 모델: 3개까지 시도 가능
- 4개 이상은 높은 확률로 429가 시작됩니다(특히 web 검색·도구 호출을 동반할 때)
4. Cron 작업: 분 단위로 정확한 자동화
1) Heartbeat vs Cron: 혼용하지 않기
- Heartbeat: "겸사겸사 확인하는" 가벼운 작업에 적합(정밀도 낮음)
- Cron: "몇 시 몇 분에 반드시 실행"하는 작업에 적합(분 단위 정확)
"매일 9:00에 조간 보고서 발송", "매주 월요일 10:00에 주간 보고서 발송"이라면 Cron이 더 적합합니다.
2) 가장 자주 쓰는 cron 표현식
0 9 * * *: 매일 9:000 9 * * 1: 매주 월요일 9:000 9,18 * * *: 매일 9:00와 18:00*/30 * * * *: 30분마다
타임존 tz 는 반드시 설정하세요. 그렇지 않으면 기본이 UTC라 시간이 8시간 어긋납니다(UTC+8에서 가장 흔한 함정).
5. Skill 개발 입문: 쓸 만한 skill을 0에서 작성하기
1) skill이란 무엇인가?
본질적으로 "운영 매뉴얼(Markdown)"입니다.
OpenClaw는 각 skill의 description 를 시스템 프롬프트에 넣습니다. 사용자가 메시지를 보내면 어떤 skill이 발동될 수 있는지 매칭하고, 매칭되면 해당 SKILL.md 를 읽어 단계대로 실행합니다.
그래서 description 는 "우아하게 쓰기"가 아니라 "빠짐없이 쓰기"가 중요합니다.
2) SKILL.md 권장 구조
- frontmatter(name/description)
- 발동 후 첫 단계로 무엇을 하는지
- 단계(실행 가능하고 재현 가능한 것이 좋음)
- 출력 형식(고정 템플릿)
- 오류 처리(반드시 작성)
3) 연습 제안: 먼저 IP 조회 skill을 작성
"IP 위치 조회" 같은 skill은 초보자 연습에 특히 적합합니다. 발동이 단순하고, 단계가 명확하고, 출력이 고정적이며, 오류 처리도 쉽습니다.
skill을 쓸 때의 원칙 하나: 먼저 손으로 흐름을 통과시킨 뒤, 그 흐름을 skill로 쓴다. 이 방식이 성공률이 가장 높습니다.
6. 다중 채널 연동: AI를 항상 온라인으로, 그러나 아무 말이나 하지 않게
다중 채널 연동의 핵심은 "많이 연결하는 것"이 아니라 두 가지입니다:
- 출처 제어:
allowFrom를 반드시 엄격히(서버/사용자/채널) - 형식 적응: 플랫폼마다 Markdown 지원이 다름(특히 표)
Discord와 Telegram을 함께 쓴다면 AGENTS.md 에 "플랫폼별 형식 규칙"을 쓰는 것을 권합니다:
- Discord: 표와 코드 블록 모두 문제없음
- Telegram: 표가 불안정하니 목록으로 대체
- WhatsApp: 사실상 순수 텍스트로 처리
7. 설정 치트시트: 자주 쓰는 파라미터를 더 안정적으로 조정하는 법
이 장에서는 제가 "효과가 뚜렷하다"고 보는 몇 가지 지점만 남깁니다. 시작부터 설정에 압도되지 않도록 하기 위해서입니다.
1) blockStreaming: 긴 답변을 마지막까지 기다리게 하지 않기
AI가 긴 답변을 나누어 보내게 하면 "실시간으로 타이핑하는" 느낌에 훨씬 가까워집니다.
권장:
blockStreamingDefault: "on"minChars: 200(너무 작으면 화면이 넘쳐 흐른다)maxChars: 1500(너무 크면 스트리밍의 의미가 없어진다)
2) ackReaction: 먼저 "받았습니다"라는 반응 주기
특히 Discord/Telegram 같은 즉시 메신저에서 중요합니다. 그러지 않으면 멈춘 줄 알게 됩니다.
3) compaction + memoryFlush: 아무리 오래 대화해도 핵심 정보를 최대한 잃지 않기
한 줄만 기억하면 됩니다: 압축 전에 파일로 먼저 쓴다. 이것이 memoryFlush 의 의미입니다.
4) Heartbeat activeHours: 한밤중에 방해하지 않기
하트비트 점검을 켰다면 activeHours 설정을 권합니다. 예를 들어 08:00–23:00입니다. 그러면 잠든 사이에 메시지를 보내지 않습니다.
마지막: 권장 설정 순서(시간 절약판)
한 번에 다 하기 어렵다면 이 우선순위대로 진행하는 것이 가장 안정적입니다:
AGENTS.md: 시작 흐름 + 기억 규범 + 안전 경계memoryFlush활성화(대화가 길어도 핵심을 잃기 어려움)ackReaction설정(체감이 즉시 좋아짐)blockStreaming켜기(긴 출력이 더 편해짐)- Heartbeat에
activeHours추가(방해하지 않음) - 그다음 Cron, 하위 Agent, Skill, 다중 채널을 검토(필요에 따라)