도구 (OpenClaw)

OpenClaw는 브라우저, 캔버스, 노드, 크론을 위한 퍼스트 클래스 에이전트 도구를 제공합니다. 기존 openclaw-* 스킬을 대체하며, 타입이 지정되고 셸 호출이 필요 없으므로 에이전트가 직접 사용할 수 있습니다.

도구 비활성화

openclaw.jsontools.allow / tools.deny를 통해 도구를 전역적으로 허용하거나 차단할 수 있습니다(deny가 우선 적용). 차단된 도구는 모델 프로바이더에 전송되지 않습니다.

{
  tools: { deny: ["browser"] },
}

참고:

  • 매칭은 대소문자를 구분하지 않습니다.
  • * 와일드카드를 지원합니다("*"는 모든 도구를 의미).
  • tools.allow에 알 수 없거나 로드되지 않은 플러그인 도구 이름만 있을 경우, OpenClaw는 경고를 기록하고 허용 목록을 무시하여 핵심 도구를 계속 사용할 수 있도록 합니다.

도구 프로파일 (기본 허용 목록)

tools.profiletools.allow/tools.deny 이전에 적용되는 기본 도구 허용 목록을 설정합니다. 에이전트별 재정의: agents.list[].tools.profile.

프로파일:

  • minimal: session_status만 허용
  • coding: group:fs, group:runtime, group:sessions, group:memory, image
  • messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
  • full: 제한 없음 (설정하지 않은 것과 동일)

예시 (기본은 메시징 전용, 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, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:web: web_search, web_fetch
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group: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를 무시합니다.
  • elevatedtools.elevatedagents.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.

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로 활성화합니다.
  • maxCharstools.web.fetch.maxCharsCap(기본값 50000)으로 제한됩니다.
  • 응답은 캐시됩니다(기본 15분).
  • JS 기반 사이트의 경우 브라우저 도구를 사용하는 것이 좋습니다.
  • 설정 방법은 웹 도구를 참고하세요.
  • 선택적 안티봇 폴백은 Firecrawl을 참고하세요.

browser

OpenClaw 전용 관리형 브라우저를 제어합니다.

주요 동작:

  • status, start, stop, tabs, open, focus, close
  • snapshot (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를 사용하세요.
  • snapshote12와 같은 참조를 반환하는 role-snapshot 옵션(interactive, compact, depth, selector)도 지원합니다.
  • actsnapshot에서 얻은 ref가 필요합니다(AI 스냅샷의 숫자 12 또는 role 스냅샷의 e12). 드문 CSS 선택자가 필요한 경우 evaluate를 사용하세요.
  • actwait 패턴은 기본적으로 피하세요. 신뢰할 수 있는 UI 상태가 없는 예외적인 경우에만 사용합니다.
  • upload는 선택적으로 ref를 전달하여 설정 후 자동 클릭할 수 있습니다.
  • uploadinputRef(aria ref) 또는 element(CSS 선택자)를 사용하여 <input type="file">을 직접 설정하는 것도 지원합니다.

canvas

노드 Canvas를 제어합니다(표시, 평가, 스냅샷, A2UI).

주요 동작:

  • present, hide, navigate, eval
  • snapshot (이미지 블록 + 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, describe
  • pending, approve, reject (페어링)
  • notify (macOS system.notify)
  • run (macOS system.run)
  • camera_list, camera_snap, camera_clip, screen_record
  • location_get, notifications_list, notifications_action
  • device_status, device_info, device_permissions, device_health

참고:

  • 카메라/화면 명령은 노드 앱이 포그라운드 상태여야 합니다.
  • 이미지는 이미지 블록 + MEDIA:<path>를 반환합니다.
  • 비디오는 FILE:<path> (mp4)를 반환합니다.
  • 위치는 JSON 페이로드(위도/경도/정확도/타임스탬프)를 반환합니다.
  • run 매개변수: command argv 배열; 선택적 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 / delete
  • pin / unpin / list-pins
  • permissions
  • thread-create / thread-list / thread-reply
  • search
  • sticker
  • member-info / role-info
  • emoji-list / emoji-upload / sticker-upload
  • role-add / role-remove
  • channel-info / channel-list
  • voice-status
  • event-list / event-create
  • timeout / kick / ban

참고:

  • send는 WhatsApp의 경우 게이트웨이를 통해 라우팅하며, 다른 채널은 직접 전달합니다.
  • poll은 WhatsApp과 MS Teams의 경우 게이트웨이를 사용하며, Discord 투표는 직접 처리합니다.
  • 메시지 도구 호출이 활성 채팅 세션에 바인딩된 경우, 전송은 해당 세션의 대상으로 제한되어 컨텍스트 간 유출을 방지합니다.

cron

게이트웨이 크론 작업 및 깨우기를 관리합니다.

주요 동작:

  • status, list
  • add, update, remove, run, runs
  • wake (시스템 이벤트 큐 등록 + 선택적 즉시 하트비트)

참고:

  • add는 전체 크론 작업 객체를 필요로 합니다(cron.add RPC와 동일한 스키마).
  • update{ jobId, patch }를 사용합니다(호환을 위해 id도 허용).

gateway

실행 중인 게이트웨이 프로세스를 재시작하거나 업데이트를 적용합니다(인플레이스).

주요 동작:

  • restart (인증 + 인프로세스 재시작을 위한 SIGUSR1 전송; openclaw gateway 인플레이스 재시작)
  • config.schema.lookup (전체 스키마를 프롬프트에 로드하지 않고 개별 설정 경로 검사)
  • config.get
  • config.apply (검증 + 설정 파일 쓰기 + 재시작 + 깨우기)
  • config.patch (부분 업데이트 병합 + 재시작 + 깨우기)
  • update.run (업데이트 실행 + 재시작 + 깨우기)

참고:

  • config.schema.lookupgateway.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_sendtimeoutSeconds > 0일 때 최종 완료까지 대기합니다.
  • 전달/공지는 완료 후 수행되며 최선 노력 방식입니다. status: "ok"는 에이전트 실행이 완료되었음을 확인하지만 공지가 전달되었음을 보장하지는 않습니다.
  • sessions_spawnruntime: "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.visibilitytree로 제한합니다.

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을 명시적으로 포함하세요. 도구는 재정의를 위해 설정이나 환경 인증 정보를 상속하지 않으며, 명시적 인증 정보가 누락되면 오류가 발생합니다.

브라우저 도구:

권장 에이전트 흐름

브라우저 자동화:

  1. browserstatus / start
  2. snapshot (ai 또는 aria)
  3. act (click/type/press)
  4. screenshot — 시각적 확인이 필요한 경우

캔버스 렌더링:

  1. canvaspresent
  2. a2ui_push (선택 사항)
  3. snapshot

노드 타겟팅:

  1. nodesstatus
  2. 선택한 노드에 describe
  3. notify / run / camera_snap / screen_record

안전

  • 직접적인 system.run은 피하세요. nodesrun은 사용자의 명시적 동의 하에만 사용하세요.
  • 카메라/화면 캡처 시 사용자 동의를 존중하세요.
  • 미디어 명령 실행 전 status/describe로 권한을 확인하세요.

에이전트에게 도구가 제공되는 방식

도구는 두 가지 채널로 노출됩니다:

  1. 시스템 프롬프트 텍스트: 사람이 읽을 수 있는 목록 + 안내.
  2. 도구 스키마: 모델 API에 전송되는 구조화된 함수 정의.

에이전트는 “어떤 도구가 있는지”와 “어떻게 호출하는지”를 모두 볼 수 있습니다. 도구가 시스템 프롬프트나 스키마에 나타나지 않으면 모델은 해당 도구를 호출할 수 없습니다.