---
read_when:
    - 에이전트 런타임, 워크스페이스 부트스트랩 또는 세션 동작 변경
summary: 에이전트 런타임, 워크스페이스 계약, 세션 부트스트랩
title: 에이전트 런타임
x-i18n:
    generated_at: "2026-06-27T17:21:35Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 2fb4d3f0bb6e8aa2a23d00f5def5eb0ffa152bc75f82a12c40ac7ed00776011c
    source_path: concepts/agent.md
    workflow: 16
---

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

## 워크스페이스(필수)

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

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

전체 워크스페이스 레이아웃 및 백업 가이드: [에이전트 워크스페이스](/ko/concepts/agent-workspace)

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

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

`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 구성](/ko/gateway/configuration)의 `skills` 참조).

## 런타임 경계

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

## 세션

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

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

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

## 스트리밍 중 조향

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

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

블록 스트리밍은 완료된 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는 사용 가능한 경우 에이전트 이벤트를 통해 도구 출력을 스트리밍합니다.
자세한 내용: [스트리밍 + 청크화](/ko/concepts/streaming).

## 모델 참조

구성의 모델 참조(예: `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`(강력 권장)

---

_다음: [그룹 채팅](/ko/channels/group-messages)_ 🦞

## 관련 항목

- [에이전트 워크스페이스](/ko/concepts/agent-workspace)
- [멀티 에이전트 라우팅](/ko/concepts/multi-agent)
- [세션 관리](/ko/concepts/session)