도구 (OpenClaw)

OpenClaw는 browser, canvas, nodes, cron을 위한 일급 에이전트 도구를 제공합니다. 이는 이전 openclaw-* 스킬을 대체합니다: 타입이 지정되어 있고, 쉘을 사용하지 않으며, 에이전트가 직접 의존할 수 있습니다.

도구 비활성화

openclaw.json의 tools.allow / tools.deny를 통해 도구를 전역적으로 허용/거부할 수 있습니다 (deny가 우선). 이는 허용되지 않은 도구가 모델 제공자에게 전송되는 것을 방지합니다.

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

참고:

  • 매칭은 대소문자를 구분하지 않습니다.
  • * 와일드카드가 지원됩니다 ("*"는 모든 도구를 의미).
  • tools.allow가 알 수 없거나 로드되지 않은 플러그인 도구 이름만 참조하면, OpenClaw는 경고를 로그하고 allowlist를 무시하여 핵심 도구를 사용 가능하게 유지합니다.

도구 프로필 (기본 allowlist)

tools.profile은 tools.allow/tools.deny 이전에 기본 도구 allowlist를 설정합니다. 에이전트별 재정의: 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" }
    }
  }
}

예제 (불안정한 엔드포인트를 위한 제공자/모델별 allowlist):

{
  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 도구 (제공자 플러그인 제외)

예제 (파일 도구 + browser만 허용):

{
  tools: {
    allow: ["group:fs", "browser"]
  }
}

플러그인 + 도구

플러그인은 핵심 세트를 넘어 추가 도구(및 CLI 명령)를 등록할 수 있습니다. 설치 + 구성은 Plugins를 참조하고, 도구 사용 가이드가 프롬프트에 주입되는 방식은 Skills를 참조하세요. 일부 플러그인은 도구와 함께 자체 스킬을 제공합니다 (예: voice-call 플러그인).

선택적 플러그인 도구:

  • Lobster: 재개 가능한 승인이 있는 타입 지정된 워크플로 런타임 (게이트웨이 호스트에 Lobster CLI 필요).
  • LLM Task: 구조화된 워크플로 출력을 위한 JSON 전용 LLM 단계 (선택적 스키마 검증).

도구 목록

apply_patch

하나 이상의 파일에 구조화된 패치를 적용합니다. 다중 hunk 편집에 사용합니다. 실험적: tools.exec.applyPatch.enabled를 통해 활성화 (OpenAI 모델만).

exec

작업 공간에서 쉘 명령을 실행합니다.

핵심 매개변수:

  • command (필수)
  • yieldMs (타임아웃 후 자동 백그라운드, 기본값 10000)
  • background (즉시 백그라운드)
  • timeout (초; 초과 시 프로세스 종료, 기본값 1800)
  • elevated (bool; 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는 에이전트가 샌드박스화된 경우에만 동작을 변경합니다(그렇지 않으면 no-op).
  • host=node는 macOS companion 앱 또는 헤드리스 노드 호스트(openclaw node run)를 대상으로 할 수 있습니다.
  • gateway/node 승인 및 allowlist: Exec approvals.

process

백그라운드 exec 세션을 관리합니다.

핵심 액션:

  • list, poll, log, write, kill, clear, remove

참고:

  • poll은 새로운 출력과 완료 시 종료 상태를 반환합니다.
  • log는 라인 기반 offset/limit을 지원합니다(offset을 생략하면 마지막 N개 라인을 가져옴).
  • process는 에이전트별로 범위가 지정됩니다; 다른 에이전트의 세션은 표시되지 않습니다.

web_search

Brave Search API를 사용하여 웹을 검색합니다.

핵심 매개변수:

  • query (필수)
  • count (1–10; tools.web.search.maxResults의 기본값)

참고:

  • Brave API 키가 필요합니다(권장: openclaw configure --section web, 또는 BRAVE_API_KEY 설정).
  • tools.web.search.enabled를 통해 활성화합니다.
  • 응답이 캐시됩니다(기본값 15분).
  • 설정은 Web tools를 참조하세요.

web_fetch

URL에서 읽을 수 있는 콘텐츠를 가져와 추출합니다(HTML → markdown/text).

핵심 매개변수:

  • url (필수)
  • extractMode (markdown | text)
  • maxChars (긴 페이지 잘라내기)

참고:

  • tools.web.fetch.enabled를 통해 활성화합니다.
  • 응답이 캐시됩니다(기본값 15분).
  • JS가 많은 사이트는 browser 도구를 선호하세요.
  • 설정은 Web tools를 참조하세요.
  • 선택적 안티봇 폴백은 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를 사용하세요.
  • snapshot은 role-snapshot 옵션(interactive, compact, depth, selector)도 지원하며 e12와 같은 ref를 반환합니다.
  • act는 snapshot의 ref가 필요합니다(AI 스냅샷의 숫자 12, role 스냅샷의 e12); 드물게 CSS 선택자가 필요한 경우 evaluate를 사용하세요.
  • 기본적으로 act → wait을 피하세요; 예외적인 경우(대기할 신뢰할 수 있는 UI 상태가 없음)에만 사용하세요.
  • upload는 선택적으로 ref를 전달하여 준비 후 자동 클릭할 수 있습니다.
  • upload는 <input type="file">을 직접 설정하기 위해 inputRef(aria ref) 또는 element(CSS 선택자)도 지원합니다.

canvas

노드 Canvas를 구동합니다(present, eval, snapshot, A2UI).

핵심 액션:

  • present, hide, navigate, eval
  • snapshot (이미지 블록 + MEDIA:<path> 반환)
  • a2ui_push, a2ui_reset

참고:

  • 내부적으로 게이트웨이 node.invoke를 사용합니다.
  • node가 제공되지 않으면 도구가 기본값(단일 연결된 노드 또는 로컬 mac 노드)을 선택합니다.
  • A2UI는 v0.8만 해당(no 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_snap, camera_clip, screen_record
  • location_get

참고:

  • 카메라/화면 명령은 노드 앱이 포그라운드에 있어야 합니다.
  • 이미지는 이미지 블록 + MEDIA:<path>를 반환합니다.
  • 비디오는 FILE:<path> (mp4)를 반환합니다.
  • 위치는 JSON 페이로드(lat/lon/accuracy/timestamp)를 반환합니다.
  • 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이 구성된 경우(기본 또는 폴백)에만 사용 가능하거나, 기본 모델 + 구성된 인증에서 암시적 이미지 모델을 추론할 수 있는 경우(최선의 노력 페어링).
  • 메인 채팅 모델과 독립적으로 이미지 모델을 직접 사용합니다.

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

게이트웨이 cron 작업 및 웨이크업을 관리합니다.

핵심 액션:

  • status, list
  • add, update, remove, run, runs
  • wake (시스템 이벤트 + 선택적 즉시 하트비트 대기열에 추가)

참고:

  • add는 전체 cron 작업 객체를 기대합니다(cron.add RPC와 동일한 스키마).
  • update는 { id, patch }를 사용합니다.

gateway

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

핵심 액션:

  • restart (권한 부여 + 제자리 재시작을 위한 SIGUSR1 전송; openclaw gateway 제자리 재시작)
  • config.get / config.schema
  • config.apply (구성 검증 + 쓰기 + 재시작 + 웨이크)
  • config.patch (부분 업데이트 병합 + 재시작 + 웨이크)
  • update.run (업데이트 실행 + 재시작 + 웨이크)

참고:

  • 진행 중인 응답을 중단하지 않도록 delayMs를 사용하세요(기본값 2000).
  • restart는 기본적으로 비활성화되어 있습니다; commands.restart: true로 활성화하세요.

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?, agentId?, model?, runTimeoutSeconds?, cleanup?
  • session_status: sessionKey? (기본값 현재; sessionId 허용), model? (default는 재정의 지우기)

참고:

  • main은 정식 직접 채팅 키입니다; global/unknown은 숨겨집니다.
  • messageLimit > 0은 세션당 마지막 N개 메시지를 가져옵니다(도구 메시지 필터링).
  • sessions_send는 timeoutSeconds > 0일 때 최종 완료를 기다립니다.
  • 전달/발표는 완료 후 발생하며 최선의 노력입니다; status: "ok"는 에이전트 실행이 완료되었음을 확인하며, 발표가 전달되었음을 확인하지 않습니다.
  • sessions_spawn은 서브 에이전트 실행을 시작하고(deliver: false, 전역 레인: subagent) 요청자 채팅 채널에 발표 응답을 게시합니다.
  • sessions_spawn은 논블로킹이며 즉시 status: "accepted"를 반환합니다.
  • sessions_send는 응답 핑퐁을 실행합니다(중지하려면 REPLY_SKIP 응답; 최대 턴은 session.agentToAgent.maxPingPongTurns, 0–5).
  • 핑퐁 후 대상 에이전트는 발표 단계를 실행합니다; 발표를 억제하려면 ANNOUNCE_SKIP으로 응답하세요.

agents_list

현재 세션이 sessions_spawn으로 대상으로 지정할 수 있는 에이전트 ID를 나열합니다.

참고:

  • 결과는 에이전트별 allowlist(agents.list[].subagents.allowAgents)로 제한됩니다.
  • ["*"]가 구성되면 도구는 모든 구성된 에이전트를 포함하고 allowAny: true로 표시합니다.

매개변수 (공통)

게이트웨이 지원 도구(canvas, nodes, cron):

  • gatewayUrl (기본값 ws://127.0.0.1:18789)
  • gatewayToken (인증이 활성화된 경우)
  • timeoutMs

브라우저 도구:

  • profile (선택사항; 기본값은 browser.defaultProfile)
  • target (sandbox | host | node)
  • node (선택사항; 특정 노드 id/이름 고정)

권장 에이전트 흐름

브라우저 자동화:

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

Canvas 렌더링:

  1. canvas → present
  2. a2ui_push (선택사항)
  3. snapshot

노드 대상 지정:

  1. nodes → status
  2. 선택한 노드에서 describe
  3. notify / run / camera_snap / screen_record

안전

  • 직접 system.run을 피하세요; 명시적 사용자 동의가 있는 경우에만 nodes → run을 사용하세요.
  • 카메라/화면 캡처에 대한 사용자 동의를 존중하세요.
  • 미디어 명령을 호출하기 전에 status/describe를 사용하여 권한을 확인하세요.

도구가 에이전트에 제시되는 방법

도구는 두 개의 병렬 채널로 노출됩니다:

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

이는 에이전트가 "어떤 도구가 존재하는지"와 "어떻게 호출하는지"를 모두 볼 수 있음을 의미합니다. 도구가 시스템 프롬프트나 스키마에 나타나지 않으면 모델은 이를 호출할 수 없습니다.

← 문서로 돌아가기