세션 도구
OpenClaw는 에이전트에게 세션 간 작업, 상태 검사, 서브 에이전트 오케스트레이션을 위한 도구를 제공합니다.
사용 가능한 도구
| 도구 | 기능 |
|---|---|
sessions_list | 선택적 필터 (kind, recency)로 세션 목록 조회 |
sessions_history | 특정 세션의 트랜스크립트 읽기 |
sessions_send | 다른 세션에 메시지 전송하고 선택적으로 대기 |
sessions_spawn | 백그라운드 작업을 위한 격리된 서브 에이전트 세션 생성 |
sessions_yield | 현재 턴을 종료하고 후속 서브 에이전트 결과를 기다림 |
subagents | 이 세션에 대해 생성된 서브 에이전트 목록, 조종 또는 종료 |
session_status | /status 스타일 카드를 표시하고 선택적으로 세션별 모델 오버라이드를 설정 |
세션 목록 및 읽기
sessions_list는 키, 종류, 채널, 모델, 토큰 수, 타임스탬프와 함께 세션을 반환합니다. 종류 (main, group, cron, hook, node) 또는 최근성 (activeMinutes)으로 필터링하십시오.
sessions_history는 특정 세션의 대화 트랜스크립트를 가져옵니다. 기본적으로 도구 결과는 제외됩니다 -- includeTools: true를 전달하면 볼 수 있습니다. 반환된 뷰는 의도적으로 제한되고 안전하게 필터링됩니다:
- 어시스턴트 텍스트는 회상 전에 정규화됩니다:
- thinking 태그 제거됨
<relevant-memories>/<relevant_memories>스캐폴딩 블록 제거됨<tool_call>...</tool_call>,<function_call>...</function_call>,<tool_calls>...</tool_calls>,<function_calls>...</function_calls>와 같은 일반 텍스트 도구 호출 XML 페이로드 블록 제거됨 (깔끔하게 닫히지 않은 잘린 페이로드 포함)[Tool Call: ...],[Tool Result ...],[Historical context ...]와 같은 다운그레이드된 도구 호출/결과 스캐폴딩 제거됨<|assistant|>, 기타 ASCII<|...|>토큰, 전각<｜...｜>변형과 같은 유출된 모델 제어 토큰 제거됨<invoke ...>/</minimax:tool_call>와 같은 잘못된 형식의 MiniMax 도구 호출 XML 제거됨
- 자격 증명/토큰 형태의 텍스트는 반환 전에 교정됩니다
- 긴 텍스트 블록은 잘립니다
- 매우 큰 히스토리는 오래된 행을 삭제하거나 과도한 크기의 행을
[sessions_history omitted: message too large]로 대체할 수 있습니다 - 도구는
truncated,droppedMessages,contentTruncated,contentRedacted,bytes와 같은 요약 플래그를 보고합니다
두 도구 모두 세션 키 (예: "main") 또는 이전 목록 호출의 세션 ID를 허용합니다.
정확한 바이트 단위 트랜스크립트가 필요한 경우, sessions_history를 원시 덤프로 처리하는 대신 디스크의 트랜스크립트 파일을 직접 검사하십시오.
크로스 세션 메시지 전송
sessions_send는 다른 세션에 메시지를 전달하고 선택적으로 응답을 기다립니다:
- Fire-and-forget:
timeoutSeconds: 0을 설정하면 즉시 큐에 넣고 반환합니다. - 응답 대기: 타임아웃을 설정하고 응답을 인라인으로 받습니다.
대상이 응답한 후, OpenClaw는 에이전트가 번갈아 메시지를 교환하는 응답 루프를 실행할 수 있습니다 (최대 5턴). 대상 에이전트는 REPLY_SKIP을 응답하여 일찍 중단할 수 있습니다.
상태 및 오케스트레이션 도우미
session_status는 현재 또는 다른 가시적 세션을 위한 가벼운 /status 상당 도구입니다. 사용량, 시간, 모델/런타임 상태, 존재 시 연결된 백그라운드 태스크 컨텍스트를 보고합니다. /status와 마찬가지로, 최신 트랜스크립트 사용량 항목에서 희박한 토큰/캐시 카운터를 백필할 수 있으며, model=default는 세션별 오버라이드를 지웁니다.
sessions_yield는 현재 턴을 의도적으로 종료하여 다음 메시지가 대기 중인 후속 이벤트가 될 수 있도록 합니다. 폴링 루프를 구축하는 대신 완료 결과가 다음 메시지로 도착하기를 원할 때 서브 에이전트를 생성한 후 사용하십시오.
subagents는 이미 생성된 OpenClaw 서브 에이전트를 위한 컨트롤 플레인 도우미입니다. 다음을 지원합니다:
action: "list"활성/최근 실행 검사action: "steer"실행 중인 자식에게 후속 안내 전송action: "kill"하나의 자식 또는all중단
서브 에이전트 생성
sessions_spawn은 백그라운드 태스크를 위한 격리된 세션을 생성합니다. 항상 비차단적입니다 -- 즉시 runId와 childSessionKey를 반환합니다.
주요 옵션:
runtime: "subagent"(기본값) 또는 외부 하네스 에이전트에는"acp".- 자식 세션에 대한
model및thinking오버라이드. thread: true생성을 채팅 스레드 (Discord, Slack 등)에 바인딩.sandbox: "require"자식에게 샌드박싱 강제.
기본 리프 서브 에이전트는 세션 도구를 받지 않습니다. maxSpawnDepth >= 2인 경우, 깊이-1 오케스트레이터 서브 에이전트는 자체 자식을 관리할 수 있도록 sessions_spawn, subagents, sessions_list, sessions_history를 추가로 받습니다. 리프 실행은 여전히 재귀 오케스트레이션 도구를 받지 않습니다.
완료 후, 공지 단계가 요청자의 채널에 결과를 게시합니다. 완료 전달은 가능한 경우 바인딩된 스레드/토픽 라우팅을 보존하며, 완료 출처가 채널만 식별하는 경우 OpenClaw는 직접 전달을 위해 요청자 세션의 저장된 경로 (lastChannel / lastTo)를 재사용할 수 있습니다.
ACP별 동작은 ACP 에이전트를 참조하십시오.
가시성
세션 도구는 에이전트가 볼 수 있는 것을 제한하는 범위로 설정됩니다:
| 수준 | 범위 |
|---|---|
self | 현재 세션만 |
tree | 현재 세션 + 생성된 서브 에이전트 |
agent | 이 에이전트의 모든 세션 |
all | 모든 세션 (구성된 경우 크로스 에이전트) |
기본값은 tree입니다. 샌드박싱된 세션은 구성에 관계없이 tree로 제한됩니다.