Fundamentals

에이전트 런타임

OpenClaw는 단일 내장 에이전트 런타임을 실행합니다. Gateway당 하나의 에이전트 프로세스가 있으며, 자체 워크스페이스, 부트스트랩 파일, 세션 저장소를 가집니다. 이 페이지는 해당 런타임 계약을 다룹니다. 워크스페이스에 무엇이 포함되어야 하는지, 어떤 파일이 주입되는지, 세션이 이를 기준으로 어떻게 부트스트랩되는지 설명합니다.

워크스페이스(필수)

OpenClaw는 단일 에이전트 워크스페이스 디렉터리(agents.defaults.workspace)를 도구와 컨텍스트를 위한 에이전트의 유일한 작업 디렉터리(cwd)로 사용합니다.

권장: ~/.openclaw/openclaw.json이 없으면 openclaw setup을 사용해 생성하고 워크스페이스 파일을 초기화하세요.

전체 워크스페이스 레이아웃 및 백업 가이드: 에이전트 워크스페이스

agents.defaults.sandbox가 활성화되어 있으면, 메인이 아닌 세션은 agents.defaults.sandbox.workspaceRoot 아래의 세션별 워크스페이스로 이를 재정의할 수 있습니다(Gateway 구성 참조).

부트스트랩 파일(주입됨)

agents.defaults.workspace 안에서 OpenClaw는 사용자가 편집할 수 있는 다음 파일을 기대합니다.

AGENTS.md - 운영 지침 + "메모리"
SOUL.md - 페르소나, 경계, 어조
TOOLS.md - 사용자가 관리하는 도구 메모(예: imsg, sag, 규칙)
BOOTSTRAP.md - 최초 실행 시 한 번만 수행하는 의식(완료 후 삭제됨)
IDENTITY.md - 에이전트 이름/분위기/이모지
USER.md - 사용자 프로필 + 선호 호칭

새 세션의 첫 번째 턴에서 OpenClaw는 이러한 파일의 내용을 시스템 프롬프트의 프로젝트 컨텍스트에 주입합니다.

빈 파일은 건너뜁니다. 큰 파일은 프롬프트를 간결하게 유지하기 위해 마커와 함께 잘라내고 축약됩니다(전체 내용은 파일을 읽으세요).

파일이 없으면 OpenClaw는 단일 "파일 없음" 마커 줄을 주입합니다(그리고 openclaw setup은 안전한 기본 템플릿을 생성합니다).

BOOTSTRAP.md는 완전히 새로운 워크스페이스(다른 부트스트랩 파일이 없음)에만 생성됩니다. 대기 중인 동안 OpenClaw는 이를 프로젝트 컨텍스트에 유지하고, 사용자 메시지에 복사하는 대신 초기 의식을 위한 시스템 프롬프트 부트스트랩 안내를 추가합니다. 의식을 완료한 뒤 삭제하면 이후 재시작 시 다시 생성되지 않아야 합니다.

워크스페이스가 관찰된 뒤에는 OpenClaw가 워크스페이스 경로에 대한 상태 디렉터리 증명 마커도 유지합니다. 최근 증명된 워크스페이스가 사라지거나 지워진 경우, 시작 시 BOOTSTRAP.md를 조용히 다시 시드하지 않습니다. 워크스페이스를 복원하거나 전체 온보딩 재설정을 사용해 워크스페이스와 마커를 함께 지우세요.

부트스트랩 파일 생성을 완전히 비활성화하려면(미리 시드된 워크스페이스용) 다음을 설정하세요.

json5

{ agents: { defaults: { skipBootstrap: true } } }

내장 도구

핵심 도구(read/exec/edit/write 및 관련 시스템 도구)는 도구 정책에 따라 항상 사용할 수 있습니다. apply_patch는 선택 사항이며 tools.exec.applyPatch로 제한됩니다. TOOLS.md는 어떤 도구가 존재하는지를 제어하지 않습니다. 이는 사용자가 도구를 어떻게 사용하기 원하는지에 대한 안내입니다.

Skills

OpenClaw는 다음 위치에서 Skills를 불러옵니다(가장 높은 우선순위부터).

워크스페이스: <workspace>/skills
프로젝트 에이전트 Skills: <workspace>/.agents/skills
개인 에이전트 Skills: ~/.agents/skills
관리형/로컬: ~/.openclaw/skills
번들(설치와 함께 제공됨)
추가 Skill 폴더: skills.load.extraDirs

Skill 루트는 <workspace>/skills/personal/foo/SKILL.md 같은 그룹화된 폴더를 포함할 수 있습니다. 그래도 Skill은 예를 들어 foo처럼 평면 frontmatter 이름으로 노출됩니다.

Skills는 구성/env로 제한될 수 있습니다(Gateway 구성의 skills 참조).

런타임 경계

내장 에이전트 런타임은 OpenClaw가 소유합니다. 모델 탐색, 도구 연결, 프롬프트 조립, 세션 관리, 채널 전달은 하나의 통합 런타임 표면을 공유합니다.

세션

세션 transcript는 JSONL로 다음 위치에 저장됩니다.

~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

세션 ID는 안정적이며 OpenClaw가 선택합니다. 다른 도구의 레거시 세션 폴더는 읽지 않습니다.

스트리밍 중 조향

실행 중간에 도착한 인바운드 프롬프트는 기본적으로 현재 실행으로 조향됩니다. 조향은 현재 assistant 턴이 도구 호출 실행을 마친 뒤, 다음 LLM 호출 전에 전달되며, 더 이상 현재 assistant 메시지의 남은 도구 호출을 건너뛰지 않습니다.

/queue steer는 기본 활성 실행 동작입니다. /queue followup 및 /queue collect는 메시지를 조향하는 대신 이후 턴까지 기다리게 합니다. /queue interrupt는 대신 활성 실행을 중단합니다. 큐와 경계 동작은 큐 및 조향 큐를 참조하세요.

블록 스트리밍은 완료된 assistant 블록을 완료되는 즉시 전송합니다. 이는 기본적으로 꺼져 있습니다(agents.defaults.blockStreamingDefault: "off"). 경계는 agents.defaults.blockStreamingBreak로 조정하세요(text_end 대 message_end; 기본값은 text_end). 소프트 블록 청크화는 agents.defaults.blockStreamingChunk로 제어합니다(기본값은 800-1200자이며, 문단 구분을 우선하고 그다음 줄바꿈, 마지막으로 문장을 사용). agents.defaults.blockStreamingCoalesce로 스트리밍 청크를 병합해 한 줄 스팸을 줄일 수 있습니다(전송 전 idle 기반 병합). Telegram이 아닌 채널은 블록 응답을 활성화하려면 명시적인 *.blockStreaming: true가 필요합니다. 상세 도구 요약은 도구 시작 시 내보냅니다(debounce 없음). Control UI는 사용 가능한 경우 에이전트 이벤트를 통해 도구 출력을 스트리밍합니다. 자세한 내용: 스트리밍 + 청크화.

모델 참조

구성의 모델 참조(예: agents.defaults.model 및 agents.defaults.models)는 첫 번째 /를 기준으로 분할해 파싱됩니다.

모델을 구성할 때는 provider/model을 사용하세요.
모델 ID 자체에 /가 포함되어 있으면(OpenRouter 스타일) provider 접두사를 포함하세요(예: openrouter/moonshotai/kimi-k2).
provider를 생략하면 OpenClaw는 먼저 alias를 시도하고, 그다음 해당 정확한 모델 ID와 일치하는 고유한 구성된 provider를 찾으며, 그 후에야 구성된 기본 provider로 fallback합니다. 해당 provider가 구성된 기본 모델을 더 이상 노출하지 않으면, OpenClaw는 오래되어 제거된 provider 기본값을 표시하는 대신 첫 번째로 구성된 provider/model로 fallback합니다.

구성(최소)

최소한 다음을 설정하세요.

agents.defaults.workspace
channels.whatsapp.allowFrom(강력 권장)

다음: 그룹 채팅 🦞