Agent Runtime 이해하기

에이전트를 개발하다 보면 컨텍스트를 관리하고 작업 디렉토리를 설정하는 일이 생각보다 번거로울 때가 많아요. 파일이 여기저기 흩어져 있거나 세션이 꼬여서 에이전트가 이전에 무슨 대화를 했는지 잊어버리면 정말 난감하죠.

OpenClaw는 pi-mono에서 파생된 단일 임베디드 Agent Runtime을 사용하여 이런 복잡한 관리 과정을 하나로 합쳤어요. 에이전트가 어떻게 작동하고 어떻게 설정하면 되는지 바로 살펴볼게요.

필요한 것

시작하기 전에 다음 설정이 준비되어 있어야 해요.

• agents.defaults.workspace 경로 설정 (필수)
• channels.whatsapp.allowFrom 설정 (권장)

빠른 시작

5분 안에 에이전트 실행 환경을 구성하는 방법이에요.

1. 설정 초기화: openclaw setup 명령어를 실행하세요. ~/.openclaw/openclaw.json 파일이 생성되고 workspace 파일들이 초기화됩니다.
2. Workspace 확인: 에이전트는 agents.defaults.workspace에 지정된 디렉토리만 작업 디렉토리(cwd)로 사용해요.
3. Bootstrap 파일 작성: AGENTS.md에 지침을, SOUL.md에 페르소나를 적어주세요.
4. 모델 연결: provider/model 형식으로 모델을 지정하면 에이전트가 대화를 시작할 준비가 끝나요.

Bootstrap 파일로 컨텍스트 주입하기

OpenClaw는 세션이 시작될 때 workspace 안에 있는 특정 파일들을 읽어서 에이전트의 컨텍스트에 직접 주입해요. 이 파일들은 사용자가 직접 수정할 수 있어요.

• AGENTS.md: 운영 지침 및 “메모리”
• SOUL.md: 페르소나, 경계 설정, 톤앤매너
• TOOLS.md: 도구 사용에 관한 사용자 노트
• IDENTITY.md: 에이전트 이름, 분위기, 이모지
• USER.md: 사용자 프로필 및 선호하는 호칭
• BOOTSTRAP.md: 첫 실행 시 단 한 번 수행할 리추얼 (완료 후 삭제됨)

파일이 비어 있으면 무시되고, 너무 크면 프롬프트 용량을 아끼기 위해 중간이 잘릴 수 있어요. 만약 미리 구성된 workspace를 사용해서 이 과정을 건너뛰고 싶다면 설정을 추가하면 돼요.

{ agent: { skipBootstrap: true } }

스킬 및 도구 관리

에이전트가 사용하는 도구와 스킬은 체계적으로 관리됩니다.

Built-in 도구

읽기, 실행, 편집, 쓰기와 같은 핵심 도구는 항상 사용할 수 있어요. apply_patch 도구는 선택 사항이며 tools.exec.applyPatch 설정으로 제어합니다. TOOLS.md 파일은 도구를 새로 만드는 게 아니라, 에이전트에게 도구를 어떻게 써야 하는지 가이드를 주는 용도예요.

Skills 로드 위치

스킬은 다음 세 곳에서 로드되며, 이름이 충돌하면 workspace에 있는 스킬이 우선권을 가져요.

1. Bundled: 설치 시 기본 포함된 스킬
2. Managed/Local: ~/.openclaw/skills 경로의 스킬
3. Workspace: <workspace>/skills 경로의 스킬

세션 및 스트리밍 제어

세션 저장

모든 세션 기록은 JSONL 형식으로 다음 경로에 저장됩니다. ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

실시간 스티어링 (Steer)

대화 중에 새로운 메시지가 들어오면 어떻게 처리할지 정할 수 있어요. steer 모드에서는 도구 실행이 끝날 때마다 큐를 확인해요. 대기 중인 메시지가 있으면 남은 도구 실행을 건너뛰고 바로 사용자의 새로운 메시지를 처리합니다.

블록 스트리밍

에이전트의 응답을 블록 단위로 보낼 수 있는데, 기본값은 꺼져 있어요 ("off").

• agents.defaults.blockStreamingDefault: "off"
• agents.defaults.blockStreamingBreak: 블록을 나누는 기준 설정 (text_end 또는 message_end)

문제 해결

문제가 발생했을 때 확인해야 할 내용이에요.

• Bootstrap 파일이 주입되지 않나요?: 파일이 아예 없으면 OpenClaw는 “missing file” 마커를 대신 주입해요. openclaw setup을 통해 기본 템플릿을 생성했는지 확인하세요.
• 모델 연결 오류가 나나요?: 모델 참조 시 반드시 첫 번째 /를 기준으로 provider를 구분해야 해요. 예를 들어 OpenRouter 모델이라면 openrouter/moonshotai/kimi-k2처럼 작성해야 합니다. provider를 생략하면 기본 provider의 모델로 간주해요.

---

더 자세한 설정 방법이 궁금하다면 AI Setup Assistant에게 물어보세요.

What’s Next

• Group Chats 🦞