도구 (OpenClaw)
OpenClaw는 브라우저, 캔버스, 노드, 크론을 위한 퍼스트 클래스 에이전트 도구를 제공합니다.
기존 openclaw-* 스킬을 대체하며, 타입이 지정되고 셸 호출이 필요 없으므로
에이전트가 직접 사용할 수 있습니다.
도구 비활성화
openclaw.json의 tools.allow / tools.deny를 통해 도구를 전역적으로 허용하거나 차단할 수 있습니다(deny가 우선 적용). 차단된 도구는 모델 프로바이더에 전송되지 않습니다.
{
tools: { deny: ["browser"] },
}
참고:
- 매칭은 대소문자를 구분하지 않습니다.
*와일드카드를 지원합니다("*"는 모든 도구를 의미).tools.allow에 알 수 없거나 로드되지 않은 플러그인 도구 이름만 있을 경우, OpenClaw는 경고를 기록하고 허용 목록을 무시하여 핵심 도구를 계속 사용할 수 있도록 합니다.
도구 프로파일 (기본 허용 목록)
tools.profile은 tools.allow/tools.deny 이전에 적용되는 기본 도구 허용 목록을 설정합니다.
에이전트별 재정의: agents.list[].tools.profile.
프로파일:
minimal:session_status만 허용coding:group:fs,group:runtime,group:sessions,group:memory,imagemessaging:group:messaging,sessions_list,sessions_history,sessions_send,session_statusfull: 제한 없음 (설정하지 않은 것과 동일)
예시 (기본은 메시징 전용, Slack + Discord 도구도 허용):
{
tools: {
profile: "messaging",
allow: ["slack", "discord"],
},
}
예시 (코딩 프로파일, exec/process는 전체 차단):
{
tools: {
profile: "coding",
deny: ["group:runtime"],
},
}
예시 (전역 코딩 프로파일, 메시징 전용 지원 에이전트):
{
tools: { profile: "coding" },
agents: {
list: [
{
id: "support",
tools: { profile: "messaging", allow: ["slack"] },
},
],
},
}
프로바이더별 도구 정책
tools.byProvider를 사용하면 전역 기본값을 변경하지 않고 특정 프로바이더(또는 단일 provider/model)에 대해 도구를 추가 제한할 수 있습니다.
에이전트별 재정의: agents.list[].tools.byProvider.
기본 도구 프로파일 이후, allow/deny 목록 이전에 적용되므로
도구 집합을 축소만 할 수 있습니다.
프로바이더 키는 provider(예: google-antigravity) 또는
provider/model(예: openai/gpt-5.2) 형식을 지원합니다.
예시 (전역 코딩 프로파일 유지, Google Antigravity는 최소 도구만):
{
tools: {
profile: "coding",
byProvider: {
"google-antigravity": { profile: "minimal" },
},
},
}
예시 (불안정한 엔드포인트를 위한 프로바이더/모델별 허용 목록):
{
tools: {
allow: ["group:fs", "group:runtime", "sessions_list"],
byProvider: {
"openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
},
},
}
예시 (단일 프로바이더에 대한 에이전트별 재정의):
{
agents: {
list: [
{
id: "support",
tools: {
byProvider: {
"google-antigravity": { allow: ["message", "sessions_list"] },
},
},
},
],
},
}
도구 그룹 (단축 표현)
도구 정책(전역, 에이전트, 샌드박스)은 여러 도구로 확장되는 group:* 항목을 지원합니다.
tools.allow / tools.deny에서 사용하세요.
사용 가능한 그룹:
group:runtime:exec,bash,processgroup:fs:read,write,edit,apply_patchgroup:sessions:sessions_list,sessions_history,sessions_send,sessions_spawn,session_statusgroup:memory:memory_search,memory_getgroup:web:web_search,web_fetchgroup:ui:browser,canvasgroup:automation:cron,gatewaygroup:messaging:messagegroup:nodes:nodesgroup:openclaw: 모든 OpenClaw 내장 도구 (프로바이더 플러그인 제외)
예시 (파일 도구 + 브라우저만 허용):
{
tools: {
allow: ["group:fs", "browser"],
},
}
플러그인 + 도구
플러그인은 핵심 도구 세트 외에 추가 도구(및 CLI 명령)를 등록할 수 있습니다. 설치 및 설정은 플러그인을 참고하고, 도구 사용 안내가 프롬프트에 삽입되는 방식은 스킬을 참고하세요. 일부 플러그인은 도구와 함께 자체 스킬을 제공합니다(예: 음성 통화 플러그인).
선택적 플러그인 도구:
- Lobster: 재개 가능한 승인 기능을 갖춘 타입 지정 워크플로 런타임 (게이트웨이 호스트에 Lobster CLI 필요).
- LLM Task: 구조화된 워크플로 출력을 위한 JSON 전용 LLM 단계 (선택적 스키마 검증).
- Diffs: 텍스트 또는 통합 패치의 전후 비교 및 PNG/PDF 파일 렌더링을 위한 읽기 전용 diff 뷰어.
도구 목록
apply_patch
하나 이상의 파일에 구조화된 패치를 적용합니다. 다중 헝크 편집에 사용하세요.
실험적 기능: tools.exec.applyPatch.enabled로 활성화 (OpenAI 모델 전용).
tools.exec.applyPatch.workspaceOnly는 기본값이 true입니다(워크스페이스 내부로 제한). 워크스페이스 디렉터리 외부에 쓰기/삭제를 허용하려면 false로 설정하세요.
exec
워크스페이스에서 셸 명령을 실행합니다.
주요 매개변수:
command(필수)yieldMs(타임아웃 후 자동 백그라운드 전환, 기본값 10000)background(즉시 백그라운드 실행)timeout(초 단위; 초과 시 프로세스 종료, 기본값 1800)elevated(불리언; 관리자 모드가 활성화/허용된 경우 호스트에서 실행; 에이전트가 샌드박스된 경우에만 동작 변경)host(sandbox | gateway | node)security(deny | allowlist | full)ask(off | on-miss | always)node(host=node시 노드 id/이름)- 실제 TTY가 필요한 경우
pty: true를 설정하세요.
참고:
- 백그라운드 실행 시
sessionId와 함께status: "running"을 반환합니다. - 백그라운드 세션의 폴링/로그/쓰기/종료/정리에는
process를 사용하세요. process가 비허용된 경우,exec는 동기적으로 실행되며yieldMs/background를 무시합니다.elevated는tools.elevated와agents.list[].tools.elevated재정의에 의해 제어됩니다(둘 다 허용해야 함).host=gateway+security=full의 별칭입니다.elevated는 에이전트가 샌드박스된 경우에만 동작이 변경됩니다(그 외에는 무동작).host=node로 macOS 컴패니언 앱 또는 헤드리스 노드 호스트(openclaw node run)를 대상으로 지정할 수 있습니다.- 게이트웨이/노드 승인 및 허용 목록: 실행 승인.
process
백그라운드 exec 세션을 관리합니다.
주요 동작:
list,poll,log,write,kill,clear,remove
참고:
poll은 완료 시 새 출력과 종료 상태를 반환합니다.log는 줄 기반offset/limit를 지원합니다(offset생략 시 마지막 N줄 가져오기).process는 에이전트별로 범위가 제한되며, 다른 에이전트의 세션은 보이지 않습니다.
loop-detection (도구 호출 루프 가드레일)
OpenClaw는 최근 도구 호출 이력을 추적하고 반복적인 무진행 루프를 감지하면 차단하거나 경고합니다.
tools.loopDetection.enabled: true로 활성화합니다(기본값은 false).
{
tools: {
loopDetection: {
enabled: true,
warningThreshold: 10,
criticalThreshold: 20,
globalCircuitBreakerThreshold: 30,
historySize: 30,
detectors: {
genericRepeat: true,
knownPollNoProgress: true,
pingPong: true,
},
},
},
}
genericRepeat: 동일한 도구 + 동일한 매개변수의 반복 호출 패턴.knownPollNoProgress: 동일한 출력을 반복하는 폴링 유형 도구.pingPong: 교대로 반복되는A/B/A/B무진행 패턴.- 에이전트별 재정의:
agents.list[].tools.loopDetection.
web_search
Perplexity, Brave, Gemini, Grok 또는 Kimi를 사용한 웹 검색.
주요 매개변수:
query(필수)count(1–10; 기본값은tools.web.search.maxResults)
참고:
- 선택한 프로바이더의 API 키가 필요합니다(권장:
openclaw configure --section web). tools.web.search.enabled로 활성화합니다.- 응답은 캐시됩니다(기본 15분).
- 설정 방법은 웹 도구를 참고하세요.
web_fetch
URL에서 가독성 있는 콘텐츠를 가져와 추출합니다(HTML → 마크다운/텍스트).
주요 매개변수:
url(필수)extractMode(markdown|text)maxChars(긴 페이지 잘라내기)
참고:
tools.web.fetch.enabled로 활성화합니다.maxChars는tools.web.fetch.maxCharsCap(기본값 50000)으로 제한됩니다.- 응답은 캐시됩니다(기본 15분).
- JS 기반 사이트의 경우 브라우저 도구를 사용하는 것이 좋습니다.
- 설정 방법은 웹 도구를 참고하세요.
- 선택적 안티봇 폴백은 Firecrawl을 참고하세요.
browser
OpenClaw 전용 관리형 브라우저를 제어합니다.
주요 동작:
status,start,stop,tabs,open,focus,closesnapshot(aria/ai)screenshot(이미지 블록 +MEDIA:<path>반환)act(UI 동작: click/type/press/hover/drag/select/fill/resize/wait/evaluate)navigate,console,pdf,upload,dialog
프로파일 관리:
profiles— 모든 브라우저 프로파일과 상태 목록create-profile— 자동 할당 포트(또는cdpUrl)로 새 프로파일 생성delete-profile— 브라우저 중지, 사용자 데이터 삭제, 설정에서 제거 (로컬 전용)reset-profile— 프로파일 포트의 고아 프로세스 종료 (로컬 전용)
공통 매개변수:
profile(선택 사항; 기본값은browser.defaultProfile)target(sandbox|host|node)node(선택 사항; 특정 노드 id/이름 지정) 참고:browser.enabled=true가 필요합니다(기본값은true;false로 비활성화).- 모든 동작은 다중 인스턴스 지원을 위해 선택적
profile매개변수를 지원합니다. profile이 생략되면browser.defaultProfile을 사용합니다(기본값 “chrome”).- 프로파일 이름: 소문자 영숫자 + 하이픈만 허용 (최대 64자).
- 포트 범위: 18800-18899 (최대 약 100개 프로파일).
- 원격 프로파일은 연결 전용(start/stop/reset 불가).
- 브라우저 지원 노드가 연결된 경우,
target을 지정하지 않으면 자동으로 해당 노드로 라우팅될 수 있습니다. snapshot은 Playwright가 설치된 경우 기본적으로ai를 사용합니다. 접근성 트리를 보려면aria를 사용하세요.snapshot은e12와 같은 참조를 반환하는 role-snapshot 옵션(interactive,compact,depth,selector)도 지원합니다.act는snapshot에서 얻은ref가 필요합니다(AI 스냅샷의 숫자12또는 role 스냅샷의e12). 드문 CSS 선택자가 필요한 경우evaluate를 사용하세요.act→wait패턴은 기본적으로 피하세요. 신뢰할 수 있는 UI 상태가 없는 예외적인 경우에만 사용합니다.upload는 선택적으로ref를 전달하여 설정 후 자동 클릭할 수 있습니다.upload는inputRef(aria ref) 또는element(CSS 선택자)를 사용하여<input type="file">을 직접 설정하는 것도 지원합니다.
canvas
노드 Canvas를 제어합니다(표시, 평가, 스냅샷, A2UI).
주요 동작:
present,hide,navigate,evalsnapshot(이미지 블록 +MEDIA:<path>반환)a2ui_push,a2ui_reset
참고:
- 내부적으로 게이트웨이
node.invoke를 사용합니다. node가 제공되지 않으면 기본값을 자동 선택합니다(단일 연결 노드 또는 로컬 mac 노드).- A2UI는 v0.8 전용(
createSurface없음); CLI는 v0.9 JSONL을 줄 오류로 거부합니다. - 빠른 테스트:
openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".
nodes
페어링된 노드를 검색하고 타겟팅합니다. 알림을 보내고, 카메라/화면을 캡처합니다.
주요 동작:
status,describepending,approve,reject(페어링)notify(macOSsystem.notify)run(macOSsystem.run)camera_list,camera_snap,camera_clip,screen_recordlocation_get,notifications_list,notifications_actiondevice_status,device_info,device_permissions,device_health
참고:
- 카메라/화면 명령은 노드 앱이 포그라운드 상태여야 합니다.
- 이미지는 이미지 블록 +
MEDIA:<path>를 반환합니다. - 비디오는
FILE:<path>(mp4)를 반환합니다. - 위치는 JSON 페이로드(위도/경도/정확도/타임스탬프)를 반환합니다.
run매개변수:commandargv 배열; 선택적cwd,env(KEY=VAL),commandTimeoutMs,invokeTimeoutMs,needsScreenRecording.
예시 (run):
{
"action": "run",
"node": "office-mac",
"command": ["echo", "Hello"],
"env": ["FOO=bar"],
"commandTimeoutMs": 12000,
"invokeTimeoutMs": 45000,
"needsScreenRecording": false
}
image
설정된 이미지 모델로 이미지를 분석합니다.
주요 매개변수:
image(필수, 경로 또는 URL)prompt(선택 사항; 기본값 “Describe the image.”)model(선택적 재정의)maxBytesMb(선택적 크기 제한)
참고:
agents.defaults.imageModel이 설정된 경우(기본 또는 폴백)에만 사용 가능하며, 기본 모델 + 설정된 인증에서 추론 가능한 암시적 이미지 모델이 있을 때도 사용할 수 있습니다(최선 노력 매칭).- 이미지 모델을 직접 사용합니다(메인 채팅 모델과 독립적).
pdf
하나 이상의 PDF 문서를 분석합니다.
전체 동작, 제한, 설정 및 예시는 PDF 도구를 참고하세요.
message
Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams에서 메시지 및 채널 동작을 수행합니다.
주요 동작:
send(텍스트 + 선택적 미디어; MS Teams는 Adaptive Cards를 위한card도 지원)poll(WhatsApp/Discord/MS Teams 투표)react/reactions/read/edit/deletepin/unpin/list-pinspermissionsthread-create/thread-list/thread-replysearchstickermember-info/role-infoemoji-list/emoji-upload/sticker-uploadrole-add/role-removechannel-info/channel-listvoice-statusevent-list/event-createtimeout/kick/ban
참고:
send는 WhatsApp의 경우 게이트웨이를 통해 라우팅하며, 다른 채널은 직접 전달합니다.poll은 WhatsApp과 MS Teams의 경우 게이트웨이를 사용하며, Discord 투표는 직접 처리합니다.- 메시지 도구 호출이 활성 채팅 세션에 바인딩된 경우, 전송은 해당 세션의 대상으로 제한되어 컨텍스트 간 유출을 방지합니다.
cron
게이트웨이 크론 작업 및 깨우기를 관리합니다.
주요 동작:
status,listadd,update,remove,run,runswake(시스템 이벤트 큐 등록 + 선택적 즉시 하트비트)
참고:
add는 전체 크론 작업 객체를 필요로 합니다(cron.addRPC와 동일한 스키마).update는{ jobId, patch }를 사용합니다(호환을 위해id도 허용).
gateway
실행 중인 게이트웨이 프로세스를 재시작하거나 업데이트를 적용합니다(인플레이스).
주요 동작:
restart(인증 + 인프로세스 재시작을 위한SIGUSR1전송;openclaw gateway인플레이스 재시작)config.schema.lookup(전체 스키마를 프롬프트에 로드하지 않고 개별 설정 경로 검사)config.getconfig.apply(검증 + 설정 파일 쓰기 + 재시작 + 깨우기)config.patch(부분 업데이트 병합 + 재시작 + 깨우기)update.run(업데이트 실행 + 재시작 + 깨우기)
참고:
config.schema.lookup은gateway.auth또는agents.list.*.heartbeat같은 특정 설정 경로를 필요로 합니다.- 경로에
plugins.entries.<id>를 처리할 때 슬래시로 구분된 플러그인 ID를 포함할 수 있습니다. 예:plugins.entries.pack/one.config. - 진행 중인 응답 중단을 피하려면
delayMs(기본값 2000)를 사용하세요. config.schema는 내부 Control UI 흐름에서 사용 가능하며 에이전트gateway도구를 통해서는 노출되지 않습니다.restart는 기본적으로 활성화되어 있습니다.commands.restart: false로 비활성화할 수 있습니다.
sessions_list / sessions_history / sessions_send / sessions_spawn / session_status
세션 목록 조회, 대화 이력 검사, 다른 세션으로 전송.
주요 매개변수:
sessions_list:kinds?,limit?,activeMinutes?,messageLimit?(0 = 없음)sessions_history:sessionKey(또는sessionId),limit?,includeTools?sessions_send:sessionKey(또는sessionId),message,timeoutSeconds?(0 = fire-and-forget)sessions_spawn:task,label?,runtime?,agentId?,model?,thinking?,cwd?,runTimeoutSeconds?,thread?,mode?,cleanup?,sandbox?,streamTo?,attachments?,attachAs?session_status:sessionKey?(기본값 현재;sessionId허용),model?(default로 재정의 해제)
참고:
main은 정식 다이렉트 채팅 키이며, global/unknown은 숨겨집니다.messageLimit > 0은 세션당 마지막 N개 메시지를 가져옵니다(도구 메시지 필터링).- 세션 타겟팅은
tools.sessions.visibility로 제어됩니다(기본값tree: 현재 세션 + 생성된 서브에이전트 세션). 여러 사용자를 위한 공유 에이전트를 운영하는 경우 세션 간 탐색을 방지하기 위해tools.sessions.visibility: "self"를 고려하세요. sessions_send는timeoutSeconds > 0일 때 최종 완료까지 대기합니다.- 전달/공지는 완료 후 수행되며 최선 노력 방식입니다.
status: "ok"는 에이전트 실행이 완료되었음을 확인하지만 공지가 전달되었음을 보장하지는 않습니다. sessions_spawn은runtime: "subagent" | "acp"를 지원합니다(기본값subagent). ACP 런타임 동작은 ACP 에이전트를 참고하세요.- ACP 런타임의 경우,
streamTo: "parent"는 초기 실행 진행 요약을 직접 자식 전달 대신 시스템 이벤트로 요청자 세션에 라우팅합니다. sessions_spawn은 서브에이전트 실행을 시작하고 요청자 채팅에 공지 응답을 게시합니다.- 원샷 모드(
mode: "run")와 영구 스레드 바인딩 모드(mode: "session"+thread: true)를 지원합니다. thread: true이고mode가 생략된 경우, mode의 기본값은session입니다.mode: "session"은thread: true를 필요로 합니다.runTimeoutSeconds가 생략된 경우, OpenClaw는 설정된agents.defaults.subagents.runTimeoutSeconds를 사용하며, 그렇지 않으면 기본값0(타임아웃 없음)을 사용합니다.- Discord 스레드 바인딩 흐름은
session.threadBindings.*와channels.discord.threadBindings.*에 의존합니다. - 응답 형식에는
Status,Result, 간략한 통계가 포함됩니다. Result는 어시스턴트 완료 텍스트이며, 없는 경우 최신toolResult가 폴백으로 사용됩니다.
- 원샷 모드(
- 수동 완료 모드 생성은 직접 전송을 먼저 시도하며, 큐 폴백과 일시적 오류에 대한 재시도를 수행합니다(
status: "ok"는 실행 완료를 의미하며 공지 전달을 보장하지 않습니다). sessions_spawn은 서브에이전트 런타임에서만 인라인 파일 첨부를 지원합니다(ACP는 거부). 각 첨부 파일에는name,content, 선택적encoding(utf8또는base64) 및mimeType이 있습니다. 파일은 자식 워크스페이스의.openclaw/attachments/<uuid>/에.manifest.json메타데이터 파일과 함께 생성됩니다. 도구는count,totalBytes, 파일별sha256,relDir이 포함된 영수증을 반환합니다. 첨부 콘텐츠는 대화 이력 저장에서 자동으로 편집됩니다.tools.sessions_spawn.attachments로 제한을 설정합니다(enabled,maxTotalBytes,maxFiles,maxFileBytes,retainOnSessionKeep).attachAs.mountPath는 향후 마운트 구현을 위한 예약 힌트입니다.
sessions_spawn은 비차단이며 즉시status: "accepted"를 반환합니다.- ACP
streamTo: "parent"응답에는 진행 이력 추적을 위한streamLogPath(세션 범위*.acp-stream.jsonl)가 포함될 수 있습니다. sessions_send는 응답 핑퐁을 실행합니다(중지하려면REPLY_SKIP응답; 최대 턴은session.agentToAgent.maxPingPongTurns, 0–5).- 핑퐁 이후, 대상 에이전트는 공지 단계를 실행합니다. 공지를 억제하려면
ANNOUNCE_SKIP으로 응답하세요. - 샌드박스 제한: 현재 세션이 샌드박스이고
agents.defaults.sandbox.sessionToolsVisibility: "spawned"인 경우, OpenClaw는tools.sessions.visibility를tree로 제한합니다.
agents_list
현재 세션이 sessions_spawn으로 타겟팅할 수 있는 에이전트 ID를 나열합니다.
참고:
- 결과는 에이전트별 허용 목록(
agents.list[].subagents.allowAgents)으로 제한됩니다. ["*"]이 설정된 경우, 모든 설정된 에이전트를 포함하고allowAny: true를 표시합니다.
매개변수 (공통)
게이트웨이 기반 도구(canvas, nodes, cron):
gatewayUrl(기본값ws://127.0.0.1:18789)gatewayToken(인증이 활성화된 경우)timeoutMs
참고: gatewayUrl이 설정된 경우 gatewayToken을 명시적으로 포함하세요. 도구는 재정의를 위해 설정이나 환경 인증 정보를 상속하지 않으며, 명시적 인증 정보가 누락되면 오류가 발생합니다.
브라우저 도구:
profile(선택 사항; 기본값은browser.defaultProfile)target(sandbox|host|node)node(선택 사항; 특정 노드 id/이름 지정)- 문제 해결 가이드:
- Linux 시작/CDP 문제: 브라우저 문제 해결 (Linux)
- WSL2 게이트웨이 + Windows 원격 Chrome CDP: WSL2 + Windows + 원격 Chrome CDP 문제 해결
권장 에이전트 흐름
브라우저 자동화:
browser→status/startsnapshot(ai 또는 aria)act(click/type/press)screenshot— 시각적 확인이 필요한 경우
캔버스 렌더링:
canvas→presenta2ui_push(선택 사항)snapshot
노드 타겟팅:
nodes→status- 선택한 노드에
describe notify/run/camera_snap/screen_record
안전
- 직접적인
system.run은 피하세요.nodes→run은 사용자의 명시적 동의 하에만 사용하세요. - 카메라/화면 캡처 시 사용자 동의를 존중하세요.
- 미디어 명령 실행 전
status/describe로 권한을 확인하세요.
에이전트에게 도구가 제공되는 방식
도구는 두 가지 채널로 노출됩니다:
- 시스템 프롬프트 텍스트: 사람이 읽을 수 있는 목록 + 안내.
- 도구 스키마: 모델 API에 전송되는 구조화된 함수 정의.
에이전트는 “어떤 도구가 있는지”와 “어떻게 호출하는지”를 모두 볼 수 있습니다. 도구가 시스템 프롬프트나 스키마에 나타나지 않으면 모델은 해당 도구를 호출할 수 없습니다.